最小改造路径

五阶段总览

P0 · Bootstrap（~2.5 周 / 11.5 天）

P0 子任务速览

验收

node scripts/phase0-verify.js
# ✓ All 79 tools registered (34 unique impl)
# ✓ 6 system prompts extracted to system/templates/devloop-*.md
# ✓ _registry.json contains all 6 devloop-* entries

node scripts/phase0-test-call.js
# ✓ Mock PM call → write_todolist tool invoked
# ✓ data/companies/c-test/projects/p-mock/agent-state/pm-todo.json written
# ✓ SSE agent.todolist event emitted
# ✓ No sandbox violations

P1 · Docs MVP（~1 周 / 5 天）

新增文件

server/
├── services/
│   └── doc-store.js             # ~140 行
├── routes/
│   └── devloop.js                # 只挂 POST /projects · GET /state，~80 行
└── src/core/
    └── (LoopController 阶段性 stub)

system/templates/
├── devloop-pm.md                 # PM system prompt
├── devloop-architect.md          # Architect system prompt
└── _registry.json                # 追加 6 条（先用 PM + Architect 两条）
        

验收

curl -X POST http://localhost:3010/api/devloop/projects -d @/tmp/req.json
# /tmp/req.json: {"company_id":"c-001","name":"todo-demo","requirement":"做一个 TODO 列表：能新增、列表、Vue 前端"}

# 期望产物（与 data-layout.html 对齐）
data/companies/c-001/projects/p-XXXXXX/
├── project.json                              ✓  # M-1 项目元数据
├── prd/                                      ✓  # M-3 多页 PRD 站点
│   ├── index.html
│   ├── reading-guide.html
│   ├── product/{background,personas,...}.html
│   ├── feature/feature-tree.html
│   ├── flow/user-flows.html
│   └── prototype/proto-*.html
├── sdd/                                      ✓  # M-4 多页 SDD 站点
│   ├── index.html
│   └── mvcp/{model,view,control,process}.html
├── units.json                                ✓  # M-2 含 l2_rounds / l2_budget 初值
├── integration/spec.json                     ✓  # Architect 写
├── agent-state/                              ✓  # M-10 / M-12 Agent 持久化运行态
│   ├── pm.json · pm-todo.json
│   └── architect.json · architect-todo.json
└── history/                                  ✓  # 全部 rev 归档
    ├── prd-rev-001.html
    └── sdd-rev-001.html

P2 · L1 单 Unit（~1.5 周 / 8 天）

新增文件

server/
├── services/
│   └── unit-registry.js          # ~120 行
└── src/core/
    └── loop-controller.js        # runUnit() 单 unit 循环 + retryWithReflection() 内置，~140 行

system/templates/
├── devloop-coder.md
└── devloop-tester.md

修改文件

• server/routes/devloop.js · 加 POST /api/devloop/projects/:pid/run（即 sdd-control · C-3）；P2 阶段 handler 临时支持 query ?only=<unitId> 调用 loopController.runUnit(pid, unitId) 让单 unit 可测，P3 改造 runProject() 后即移除 only 参数，与 C-3 完全等价
• server/services/evolution-loop.js · 不动

验收

跑命令后看到：

• Unit 状态从 pending → coding → testing → failed → coding → testing → passed
• coder.log 第二条决策明显引用了第一条的失败原因（说明反思生效）
• 沙箱越权（试图改其他 unit code）被工具层拒绝

P3 · L1 + L2 联动（~3 周 / 15 天）

新增 / 完善

server/src/core/loop-controller.js   # 完整 runProject() 主循环（去掉 P2 的 ?only= 临时入口）

system/templates/
├── devloop-integrator.md
└── devloop-triager.md

server/services/
├── sse-broker.js                # SSE 订阅管理 + stream.log replay，~80 行
└── bug-tracker.js               # 写 bugs.ndjson + GET /bugs 端点支持，~80 行

server/routes/devloop.js             # 加 C-5 GET /api/devloop/projects/:pid/stream + GET /:pid/bugs

# 同步生成的 append-only 产物（与 data-layout.html 对齐）
projects/{pid}/
├── timeline.ndjson                  # M-13 全流程统一日志（loop-controller / agent-bridge 写）
├── bugs.ndjson                      # M-14 跨 run bug 台账（bug-tracker 写）
├── changelog.ndjson                 # M-15 PRD/SDD/units rev 变更流（DocStore 写）
└── stream.log                       # SSE 客户端视角日志（sse-broker 写，7 天滚动）

验收

P3 必须在 4 类 L2 分支（参见 sdd-process · P-2）下都跑通：

① contract_mismatch · 自动 patch SDD

1. 需求 = 「一个登录系统：邮箱密码 + token，前端展示」
2. 在 Architect 生成的 SDD 中故意插入矛盾（auth-be 写 401，auth-fe 假设 403）
3. L1 全部 passed → L2 集成失败
4. BugTriager 给出 contract_mismatch，confidence ≥ 0.5
5. Architect 自动 patch SDD（mode=patch）→ sdd.updated 事件
6. auth-be + auth-fe reset → 重跑 L1（计 1 个 l2_round）
7. 第二次 L2 通过 → project.shipped

② impl_bug · 不改 SDD，仅 reset

• SDD 正确，故意把 auth-be 实现写成 password 字段名打错
• BugTriager 归因 impl_bug → SDD 不动 → 仅 auth-be reset → 重跑 L1（不烧 l2_round 预算）

③ spec_ambiguous / confidence < 0.5 · 升 L3 等待人类

• 需求中故意留模糊点（如「token 续期策略」未定）
• Triager 给出 spec_ambiguous 或 confidence < 0.5
• SSE 收到 human_intervention_needed（reason=low_confidence_triage）→ LoopController 进入 l2_blocked，不自动 patch

④ infra_flake · 直接重跑

• 模拟 Integrator 进程超时（kill -9）→ 归因 infra_flake → 直接 runL2() 重跑，不烧预算、不动 Unit

⑤ 可观测性产物校验（4 类分支跑完后统一检查）

• bugs.ndjson 含上述每次 triage 结果（open → fixing → fixed → verified 状态机轨迹）
• changelog.ndjson 至少 1 条 sdd-rev 变更（来自分支 ①）
• timeline.ndjson 含完整事件链路（unit.state / integration.result / triage.result / sdd.updated）
• SSE GET /api/devloop/projects/:pid/stream 用 Last-Event-ID 重连后能 replay 缺失事件

桥梁：极简 Status Page

P3 末尾顺手做一个 ~100 行的纯静态 HTML status page（不上 Vue 路由，单文件放 server/public/devloop-status.html），轮询 GET /api/devloop/projects/:pid/state 渲染 DAG 与 loop 状态条。作用：

• 给 P3 后期调试时一个可视化窗口（眼看 unit 状态翻飞比 tail 文件直观）
• 作为 P4 完整 Dashboard 的功能预演 — 提前发现交互问题
• ~100 行，不算进 P4 工作量

P4 · L3 + UI（~2 周 / 10 天）

新增

web/src/views/
├── DevLoopDashboard.vue         # ~400 行
└── DevLoopOps.vue                # Ops 容器（4 个 tab：Bugs / Loops / Changelog / Progress）

web/src/components/devloop/         # Dashboard 子组件
├── DashboardHeader.vue
├── LoopStatusBar.vue
├── UnitsDAG.vue                 # 复用 PipelineEditor 渲染层
├── LiveAgentStream.vue
├── PrdDiffPanel.vue
└── FeedbackModal.vue

web/src/components/devloop/ops/     # Ops 子页（与 ops-*.html wireframe 对齐）
├── BuglistView.vue              # 渲染 bugs.ndjson（M-14）
├── LoopLogView.vue              # 按 L1/L2/L3 分组 timeline.ndjson
├── ChangelogView.vue            # 渲染 changelog.ndjson（M-15）
└── ProgressView.vue             # 项目实时进度聚合

web/src/router/index.js              # 加 /devloop/:pid 主路由 + /devloop/:pid/ops/{bugs,loops,changelog,progress} 4 个子路由

server/routes/devloop.js             # 加 C-6 POST /:pid/sign-off + C-7 POST /:pid/abandon（参见 sdd-control）

验收

• 打开 http://localhost:5173/devloop/p-XXXXXX 看到 wireframe 描述的全部 4 个区域
• 点 「+ NEW REQUIREMENT」发新需求 → PRD diff 区出现新 section（触发 PM incremental 模式）
• Live 流实时滚动 Agent 输出（断网 5s 后自动重连，用 Last-Event-ID replay）
• DAG 节点点击展开抽屉，看 unit 的最近 3 次 run
• 4 个 Ops 子页都能打开：/ops/bugs · /ops/loops · /ops/changelog · /ops/progress
• 项目交付后点 「Sign Off」按钮 → POST /api/devloop/projects/:pid/sign-off → 状态变 shipped-final，前端拒绝再发新反馈
• 异常项目点 「Abandon」按钮 → POST /api/devloop/projects/:pid/abandon → 状态变 abandoned，SSE 发 close 帧

成本估算

较早前版本（20 文件 / ~1580 行）低估了：① Agent 模板单文件实际 prompt 长度（PM/Architect 当前 PRD 已揭示需 200-300 行 prompt + 数个 few-shot）；② Dashboard 子组件粒度（DAG / 抽屉 / diff 渲染单组件就 100+ 行）；③ Ops 4 个子页此前未计入。

时间预算

单人 Claude Code 协同开发：P0（11 天） → P1（5 天）→ P2（8 天）→ P3（18 天）→ P4（15 天）= 约 9.5 周。每阶段末 1 天用于演示 + 写迭代 PR 描述。

• P0（11 天）：79 工具实现 + ACP 桥接 + 提示提取 + 验证脚本，是 P1 的前置（详见上方 P0 表格 + tool-registry §⑪）
• P3 +3 天：增加 4 类 L2 分支演示（contract_mismatch / impl_bug / spec_ambiguous / infra_flake）+ 可观测性产物（bugs/changelog/timeline.ndjson）+ bug-tracker 服务
• P4 +5 天：Ops 4 个子页（Bugs / Loops / Changelog / Progress）+ sign-off / abandon 端点联调

早期版本估算 4 周过紧，6 周漏了 P0，7 周漏了 P0 — 现在 9.5 周是含 P0 + 含 Ops + 含多分支演示的诚实估算。参考 成本预算 看实际 token / 美元数字。

「自举」乐趣