# 设计文档集补齐(P1 全卷 + P2-P5 阶段文档)

- **日期**:2026-06-11
- **任务类型**:大型多文档设计撰写(并行子代理起草 + 主助理收口)

## 任务

把设计文档集从「5 篇 P1 文档 + roadmap + architecture」补齐到全卷可按图施工:新增 P1 文档 8 篇(00/03/07/08/09/10/11/12)、阶段文档 4 篇(p2-p5),并完成 7 组跨文档回填。最终 19 篇约 13700 行,交叉引用无断链。

## 预期 vs 实际

- 预期:每篇由独立子代理起草后直接可用。
- 实际:整体达成,但 3 个子代理因 socket 中断丢失;其中 2 次文件已落盘可续用,1 篇(p3-wasm-tier)三次失败后改由主助理亲自撰写。回填工作量比预期大(7 组),必须由主助理单点收口。

## 做对了什么(可复用模式)

1. **并行子代理起草 + 主助理收口回填**。每篇 prompt 指定必读上游文档与风格基线;主助理逐篇核验、统一执行跨文档回填。关键:回填必须由单一执行者收口,否则「A 请求 B 增字段」会悬空。
2. **「回填请求」节作为多文档协同协议**。下游文档对上游布局提字段增补时,在自己文档里写「对 XX 的回填请求」节;主助理统一兑现后改标「已兑现」。请求与兑现状态都留在文档内,可审计、不丢失。本次兑现 7 组(05→01/02、07→06、08→05、09→01、P2→02/05、P3→05/06、03→04)。
3. **指定单一「验收口径收口点」**。所有文档把「待定口径」指向 12-testing-difftest,由它用验收口径总表(25 条)逐条收口。「分散提出、集中收口」避免口径在多篇文档间打架。
4. **第三方语言规范内容的纪律**:基于模型已有的 Lua 5.1 公开规范知识直接撰写,不抓取 C 源码;不确定的错误信息精确措辞一律标「待 12 差分核对」,不编造。

## 什么出了问题 / 根因

- **子代理因 socket 中断丢失 ×3**。根因:长会话 + 大文件输出的子代理对网络中断脆弱。教训:
  - 续接(SendMessage)前**必须先核验文件是否已落盘**(`wc -l` + 看头尾),已落盘则续写而非重写;
  - 同一篇连续失败 2-3 次后,切换为主助理亲自撰写——单次大块 Write 比长会话子代理更抗中断。
- **回填依赖图后置发现**。起草阶段未预判哪些下游文档会反向修改上游布局,回填集中在收口期爆发。下次可在分派 prompt 中要求子代理「凡需上游增补,只写回填请求节、不要假设已存在」,本次已这样做且有效,应固化。

## 缺失的文档或信号

- 当时没有「多文档并行起草工作流」的 guide,模式靠任务内即兴约定。
- 子代理 prompt 模板(必读上游清单 + 风格基线 + 回填请求约定)未沉淀,下次同类任务要重新拼。

## Promotion 候选

- **`guides/`(优先)**:「多文档并行起草工作流」——回填请求节协议、单点收口、验收口径收口点指定、子代理失败恢复纪律(先核验落盘、N 次失败转主助理)。这是首个可成文的可操作工作流,可填补 guides/ 空缺。
- **`reference/` 或 guide 附录**:子代理起草 prompt 模板(必读上游文档清单、风格基线、回填请求约定、规范类内容「不编造、标待核对」纪律)。
- **暂留 memory**:本次具体的 7 组回填清单、p3 三次失败的细节——任务特定,无促进价值。

## 后续行动

- 下一次多文档任务前,把「回填请求节协议 + 失败恢复纪律」固化为 `guides/` 一篇(可请 recorder 执行)。
- 实现阶段开始后,12 中标「待差分核对」的措辞需逐条兑现,勿当作已定稿。
