Software Design | Francis Du

wcode：我为什么开始把 edit file 往后放

Wed, 26 Aug 2026 03:15:00 +0800

写 Coding Agent 很容易最后都收敛到几个工具：

read_file
search
edit_file
run_test

第一版 wcode 也差不多。

当时我花很多时间把这些工具做得安全一点：路径不能逃出 Workspace，写入有 SHA，命令不经过 Shell，验证有固定 Harness。

这些当然还重要。

但用久以后我发现，edit_file 其实不是最难的部分。

真正让我头疼的是一个稍微大一点的修改：为什么要改？这次到底影响什么？哪件事必须先做？什么时候算完成？如果一个模型做到一半退出了，第二个模型从哪里接？

所以我后来开始把 edit file 往后放，前面先补 Reconciliation。

我先想要的是一个能恢复的 Plan#

现在一条链大概是：

Design State
    ↓
Actual State / Git Change
    ↓
Drift
    ↓
Impact
    ↓
Risk
    ↓
Reconciliation Plan
    ↓
Verification / Human Approval
    ↓
Evidence

Plan 不是一句“修好这个问题”。

它会带上这次 Design Change、发现的 Drift、Impact、Risk、Change Intent 和 Verification Requirement，然后再拆成有依赖的 Task。

这听起来有点重，但原因其实很现实：聊天记录不适合拿来当长期工作状态。

Session 断掉比想象中常见#

模型会换，工具会重连，Web Session 会过期，有时我自己也会中途停下来改别的东西。

如果任务做到一半，所有进度都只存在上一段 Conversation 里，下一次基本又得从头解释。

所以 Reconciliation Plan 和 Execution 都会持久化。

执行者面对的是：

claim
submit
retry
status

Claim 只能拿当前依赖已经满足的 Task。

Submit 会留下执行结果和 Evidence。

失败就是失败，不会因为任务“差不多做完了”自动翻成成功。要继续就 Retry。

这套状态机没有多复杂，但它给不同模型之间提供了一个比聊天记录稳定得多的交接面。

“代码写完”不等于“修改完成”#

我后来很想把这两个状态拆开。

以前 Agent 写完最后一个 Patch，往往心理上任务就已经结束了，测试变成一个尾巴：

TODO: run tests

Reconciliation 里 Verification 和 Human Approval 可以是实际的系统 Gate。

只有对应 Evidence 到了，Task 才继续往后走。

所以：

Implementation complete

和：

Change converged

不是同一个状态。

这个区别在安全相关修改里尤其明显。代码可能十分钟前已经写完，但 Security Review、Maintainability Review、Full Verification 还没结束，那我就不希望系统把它显示成“完成”。

Plan 没有超级写权限#

Reconciliation 做到这里，很容易给它加一条捷径：既然 Plan 已经知道要改什么，那直接让执行器 Patch 不就行了。

我没有这么做。

真正的文件修改仍然走 Workspace 原来的边界：

Workspace root isolation
SHA-256 precondition
atomic write
symlink / hardlink safety
protected path policy
authorization

假设 Plan 是十分钟前生成的，这十分钟里我手动改了目标文件。

执行者拿旧 SHA 去写，照样失败。

Plan 不能因为“自己是计划”就压过现在的文件状态。

这条限制看起来会让自动化麻烦一点，但我觉得值得。

并行也没有直接全开#

现在 parallel_tools 已经能处理不只是 Read/Discovery，也包括一部分独立的 Workspace Write。

但不是把一堆写操作扔进 Tokio 就结束了。

Scheduler 会先按路径做 Resource Model：哪些操作读同一个文件、哪些写同一个文件、Move / Delete / Create 有没有父子目录依赖。

独立的可以 fan out；冲突的先排序。

同一个文件上的 apply_edits 只有在 SHA 一样、Edit 本身不冲突时才会合并成一次原子提交。

这和 Reconciliation 的想法很接近：不是追求“看起来同时跑了很多东西”，而是先搞清楚哪些事情真的互相独立。

Continuous Reconciliation 我现在还是很谨慎#

“Reconciliation” 这个词很容易让人联想到 Kubernetes Controller：不停观察 Desired / Actual，然后自动把实际状态修回去。

wcode 确实有往这个方向走的设计，但我暂时不想让代码库也变成那种全自动 Controller。

软件修改和副本数不一样。

有些 Drift 很机械，可以自动发现；但“这里应该不应该改”“设计到底是不是变了”“这个抽象还值不值得留”，很多时候不适合无条件自动推进。

所以我目前更关心的是把：

观察
计划
执行
验证
证据

这几段先做成可靠的状态。

自动化程度以后再加。

不同模型终于不用共享一段脑内上下文#

这是我现在最喜欢 Reconciliation 的地方。

一个模型可以做 Implementation，另一个做 Security Review，再换一个看 Maintainability 或补 Test。

它们不需要彼此复述上一段 Chat。

只要都通过 wcode，看到的是同一个 Requirement、同一个 Plan、同一个 revision 和同一组 Evidence。

模型当然还是会有各自的判断差异，但至少“项目现在做到哪了”不必由模型自己记。

再往外一层，就是怎么把这些能力交给不同 Agent，而又不把权限和工作流混在一起。我把这部分写在 MCP 负责能力，Skill 只负责工作习惯里。

wcode：Git Diff 之外，我还想知道什么

Wed, 26 Aug 2026 03:13:00 +0800

我做 Code Review 时很少只看 Diff。

Diff 只是入口。

看到一个函数被改，我脑子里会自动继续问：谁在调用它？这个模块原来为什么这么写？有没有对应测试？它是不是安全边界？这次只是重构，还是已经改变了设计？

这些问题以前都靠人自己补。

Agent 也一样，只不过它能补多少，很看这一次上下文有没有给够。

所以做完 Design State 和 Software Graph 以后，我开始把其中一部分变成 wcode 可以直接算的东西。

Traceability 先回答最笨的问题#

traceability_status 主要看几条链有没有断：

Requirement → Component
Component → Implementation
Acceptance Criterion → Verification

我一开始考虑过做一个总 Coverage。

比如：

87%

后来觉得没什么用。

如果丢的是一个低优先级页面的 Acceptance，和丢的是 Workspace Root Isolation 的测试，显然不是同一件事。把它们平均成一个百分比，信息反而少了。

所以现在直接分开报。

我更想看到这种东西：

Requirement 还在
Component 还在
但原来映射的 Symbol 已经搬走了

或者：

Acceptance 还指着一个已经改名的 test

这种错误没有多高级，但特别常见。

Product Scope 解决“别把整个仓库都拖进来”#

wcode 后来又加了 Product Scope，因为只靠 Requirement 还不够。

项目一大，Context 很容易横跨一堆不相关目录。

现在我通常先跑 scope_status，看看源码是怎么落在各个 Scope 里的，还有没有没归类的文件。真正做任务时，software_context(scopes=...) 会把源码导航收窄到指定范围。

例如我只在 workspace / risk 一类 Scope 里查，就不会顺手把 UI、Connector、Release 相关东西一起塞进来。

这个功能对模型没有那么“惊艳”，但对长期项目很实用。Context 少一点，误判也少一点。

Drift 不是报错，更像提醒#

Traceability 看的是“关系还通不通”，Drift 看的是“变化之后，两边是不是开始不一致”。

现在大致有两类。

一种是 Implementation Drift。

Design 变了，代码没跟；或者原来声明的实现、验证链现在断了。

另一种是 Design Drift。

某个已经有 Design 身份的实现被改了，但这次 Design State 完全没动。

第二种不能理解成“改代码必须改 YAML”。

很多重构当然不需要改设计。

所以它更像一句提醒：

这个地方在 Design State 里是有名字的，现在代码变了，确认一下原来的描述还成立。

我不想把这种 heuristic 叫 formal verification。它没那么聪明。

Impact 是我真正天天想看的东西#

Git 能给 Changed Paths，但 Review 时我通常还想看：

碰到了哪些 Component
关联哪些 Requirement
哪些 Acceptance 需要重新验证
调用方有哪些
有没有 Public API 信号
有没有 Security Boundary

impact_analysis 会从 Working Tree 开始，再沿 Composite Software Graph 往调用方扩。

现在主要看 Calls / RuntimeCalls 这类关系。

有 fresh LSP / Runtime Provider 就用更高精度的关系；没有就退到 Tree-sitter Syntax Edge。结果里会保留 Provider 和 Precision，不把不同来源混成一句“确定会影响”。

这也是为什么前面 Software Graph 那篇我一直强调 provenance。

没有 provenance，Impact 最后只剩一个很自信的列表，但没人知道它为什么这么判断。

Transitive Analysis 一定得有刹车#

调用图特别容易爆。

一个底层 helper 可能被几百个地方用。如果“所有调用方的调用方再递归展开”没有上限，最后返回的 Context 比直接把仓库读一遍还离谱。

所以 wcode 这类 Query 都是 bounded 的。

到上限就明确返回：

truncated = true

我宁愿看到一个“这里没展开完”，也不要看到一份看起来完整、其实只是因为上下文被截断而少东西的结果。

Review 里现在还会看代码是不是开始长歪#

最近 review_changes 又加了一些结构信号。

例如：

一个源码文件从 1,000 行以下跨到 1,000 行以上
大量净新增集中在一个文件
一次大改横跨多个 Product Scope

这些不会直接判“代码质量差”。

它们只是进入 Risk，让后面的 Verification 决定是不是要增加 Maintainability Review。

这个区别我觉得挺重要。

工具可以很容易数行数，但“抽象是不是多余”“是不是出现了重复的 canonical helper”“是不是为了兼容又堆了一层 wrapper”，这些还是要 Review。

所以确定性信号负责发现值得看一眼的地方，Reviewer 再判断是不是问题。

现在 Project Observatory 也会把 Requirement、实现、Verification、Git Change 和依赖关系放在一起。我平时打开它，基本就是为了回答这篇文章标题那个问题：

Diff 之外，这次到底动了什么。

Impact 算出来只是知道该看哪里，最后还是要落到“怎么证明这次改动真的可以”。Verification 和 Evidence 我放在测试通过以后，我还想留下什么里。

我为什么把 wcode 的需求写进仓库

Wed, 26 Aug 2026 03:11:00 +0800

做 wcode 一段时间以后，我越来越不喜欢一种状态：代码里明明有很多约束，但这些约束只活在人脑里。

比如 Workspace Root 为什么不能随便放宽，为什么 Symlink 要单独挡，为什么一个旧 SHA 不能继续写文件。代码看得出来“怎么做”，但不一定看得出来“为什么不能改成别的样子”。

人长期待在项目里还好，换一个 Agent 进来，它看到的通常只有当前源码。

于是我开始把一部分“为什么”写进仓库。

不是 README，也不是另起一个 Wiki，而是一份机器也能读的 Design State。

其实就是几份 YAML#

现在结构很普通：

.wcode/
├── project.yaml
└── design/
    ├── product.yaml
    ├── requirements.yaml
    ├── components.yaml
    ├── constraints.yaml
    ├── acceptance.yaml
    └── decisions.yaml

关键不在 YAML，而在稳定 ID。

例如 Workspace Root Isolation 可以有一个 Requirement：

- schema_version: 1
  id: REQ-SEC-001
  title: Workspace root isolation
  intent: Remote models must never escape the configured workspace root.
  priority: critical
  implemented_by:
    - component:workspace-security
  acceptance:
    - AC-SEC-001
  constraints:
    - CONSTRAINT-ROOT-ISOLATION

Component 再指到真实实现。现在 wcode 的目录已经拆过几轮，Workspace Root 相关实现就在：

- schema_version: 1
  id: component:workspace-security
  name: Workspace Security
  implementation:
    - kind: symbol
      path: src/workspace/roots.rs
      symbol: Workspace::existing_path

Acceptance 最后落到测试：

- schema_version: 1
  id: AC-SEC-001
  title: Workspace traversal is blocked
  verification:
    - kind: test
      path: src/workspace/mod.rs
      symbol: tests::blocks_path_traversal_and_stale_writes

最后能顺着一条真实链走下去：

REQ-SEC-001
    ↓
component:workspace-security
    ↓
src/workspace/roots.rs::Workspace::existing_path
    ↓
AC-SEC-001
    ↓
src/workspace/mod.rs::tests::blocks_path_traversal_and_stale_writes

这件事看起来很朴素，但它改变了我给 Agent 下任务的方式。

以前会说：

去看一下 workspace 相关代码，路径安全这里改一下。

现在可以先从 Requirement 开始：

看一下 workspace root isolation 现在的实现、约束和验证。

文件名反而是后面的事情。

我不想维护第二份源码#

Design State 最容易做过头。

如果每个函数、每个类型、每条调用关系都要手工抄进 YAML，那这东西一定会烂掉。代码一重构，Design State 马上过期，最后大家只能一起假装它还可信。

所以我现在只放那些值得稳定命名的东西：

Requirement
Component responsibility
Constraint
Acceptance Criterion
重要 Decision

至于“这个函数现在调用谁”“某个模块里有哪些 Symbol”，让代码索引和 Software Graph 自己算。

Design State 负责的是“应该是什么”，不是给源码做一份手写镜像。

Product Scope 是后来补的一层#

项目拆大以后，我还遇到过另一个问题。

Design State 能告诉我 Requirement 属于什么能力，但 Agent 做源码导航时仍然可能在整个仓库里乱跑。

所以后来 wcode 又有了 Product Scope。

它和 Design State 不是一回事。

Design State 管稳定的产品意图，Product Scope 更像源码架构上的边界。现在 scope_status 会检查源码落在哪些 Scope，还有没有没归类的文件；software_context(scopes=...) 可以真的只在选定 Scope 里找相关源码。

我自己用下来，两个东西刚好互补：

Design State：为什么有这个能力
Product Scope：这类能力大致落在哪块源码
Software Graph：代码现在实际怎么连

比起把所有东西都塞进一张图里，这样更容易维护。

Tree-sitter 解析到了，也只能说明解析到了#

Component 和 Acceptance 可以引用 Symbol，但基础解析还是 Tree-sitter。

所以结果会明确带：

provider = tree-sitter
precision = syntax

这表示“这里有这个语法定义”，不是“编译器已经证明这就是最终绑定到的实现”。

这种区别有时候很烦，尤其写展示页面时，直接写成“已解析”会好看很多。

但我宁愿页面上多一个 syntax，也不想让 Design State 借着结构化格式显得比底层事实更可靠。

我最后还是让 wcode 管自己#

Design State 真正变得有用，是我开始拿它 Dogfood wcode 自己以后。

源码一移动，Traceability 会暴露旧路径；Requirement 加了 Acceptance 但测试没接上，也会直接出现 Gap。现在 Project Observatory 里还能从 Requirement 一路看到 Component、当前实现、Verification 和这次 Git Change。

这时候 .wcode/design 才不是“又多了几份文档”。

它真的进入了开发流程。

当然它也会带来维护成本。改架构时，有时候代码改完还得回来修 Design mapping。这个成本我现在愿意付，因为不付的代价通常是几个月以后重新猜一遍为什么当初这么设计。

下一篇是 Software Graph。Design State 解决“应该是什么”，Graph 解决的是另一个更麻烦的问题：代码现在到底是什么，而且我们对这个答案有多大把握。