AI 协作工程化 02：谁能改状态，Controller、Handoff 与结构化 Return
多人协作最危险的错误，不是某个人写错了一段文字，而是多人同时相信自己有权修改“当前事实”。在 AI 工作流里，这个问题被放大了：Designer 可以写需求和计划，Developer 可以写代码和执行记录，Reviewer 可以写结论。如果所有角色都能直接改共享状态，流程很快就会变成一份互相覆盖的 Markdown。
一个可靠的解法是把系统拆成控制面与事实面：Controller 只负责状态变更和路由；专业角色只负责自己的权威产物；二者用结构化 Return 连接。
先分清两类数据
控制面只保存当前流程需要快速判断的动态信息，例如当前工作单、流转版本、事件日志和各类事实的速查索引。它适合放在一个 Handoff 中，但不应该承载完整设计、代码说明或审查正文。
事实面则由专业产物构成：
| 角色 | 权威产物 | 负责回答的问题 |
|---|---|---|
| Designer | 需求、计划、设计确认 | 要做什么，为什么做，如何拆分 |
| Developer | 开发记录与代码提交 | 实际做了什么，如何验证 |
| Design Reviewer | 设计审查报告 | 计划是否可执行、范围是否等价 |
| Develop Reviewer | 实现审查报告 | 代码与提交是否符合计划 |
| Accept Reviewer | 验收报告 | 用户目标是否已经实现 |
Handoff 不替代这些正文，它只保留到正文的稳定引用。这样既让 Controller 能快速路由，也避免把详细事实压缩成难以维护的一行摘要。
Return 是变更申请，不是聊天结论
角色完成一个工作单后，不直接改 Handoff，而是提交一份可解析的 Return。它至少包含结果、工作单 ID、正文锚点和台账 delta。
status: completed
ledger_delta:
work_order_id: WO-017
return_ref: development.md#return-WO-017
rows:
- table: execution
id: TASK-007
op: upsert
source_ref: development.md#execution-TASK-007
fields:
state: completed
verification_refs:
- development.md#verification-TASK-007-1这份数据结构有意保持克制。它不携带下一角色，也不允许角色提交事件日志；下一阶段由 Controller 根据协议派生。角色表达的是“我完成了什么，证据在哪里”，而不是“系统接下来应该怎么运行”。
为什么要让 Controller 单写
单写带来三个工程性质。
原子性
Controller 先在内存中构造候选 Handoff：应用 delta、计算审查结果、生成下一个工作单、追加流转日志，再做结构校验。只有全部成功才一次写入。文件写入失败时，当前状态和日志都保持不变。
幂等性
Return 用当前工作单 ID 匹配。一个 Return 被接受后，活跃工作单已经变化；同一个 Return 再次到达时只会被忽略。这比依靠“请不要重复执行”的提示词可靠得多。
最小权限
Designer 不能伪造审查通过，Reviewer 不能修改代码记录，Developer 不能关闭自己的设计回交。权限被限制在“谁拥有哪张表、哪些字段、哪些操作”这一层，而不是只写在自然语言约定里。
Markdown 也可以有模式演进
把 Handoff 写成 Markdown 并不等于放弃数据治理。关键是为表格定义当前规范，并在每次写入前做机械校验：列数一致、必需列存在、已知旧列能按列名迁移、新派生列有默认值。
这样的兼容策略非常适合长生命周期文档。它允许协议增加一个受控字段，而不会让旧需求永久停留在旧格式；同时也拒绝未知列、重复列和无法映射的数据行，避免“看起来像表格”的文本悄悄污染控制面。
WARNING
不要让 Controller 阅读和解释每一篇专业正文。它只需验证引用、表结构、ID 格式和字段权限；判断设计是否正确、代码是否可用，仍属于对应专业角色。
控制面过度膨胀的信号
如果 Handoff 开始出现以下内容，通常说明边界被打破：
- 长篇业务规则和方案解释；这些应回到需求或计划正文。
- 代码 diff、命令日志和截图描述；这些应回到开发记录或测试证据。
- “建议下一步由谁做什么”的自由文本；这会与固定路由竞争。
- 为了方便搜索而复制多个版本的结论；应保存引用而不是副本。
控制面越小，恢复和审计越可靠。事实面越完整，专业判断越容易复核。两者相互引用，而不是互相吞并。
小结
Controller 的价值不在于比专业角色更懂业务，而在于它不参与专业判断。它把控制权集中为一个小而可验证的边界，让每个角色只对自己的事实负责。
下一篇讨论另一个经常被忽略的问题：如何把需求、设计、任务、代码提交和验证证据串成一条可追溯链。
系列导航：