项目助手工作流

学习目标

读完本课你能把 A25-A29 的机制拼成一个完整可用的项目助手：一个「读需求 → 查代码 → 提修改 → 复盘」的受控工作流——每一步有证据、有边界、有明确的停止条件，出问题能回放全过程。

问题场景

「帮我看看导入功能为什么慢，改一下。」这类需求交给裸智能体，常见结局：它读了个大概就开始改代码，改了三个文件，其中一处引入新 bug，最后说不清它到底改了什么、依据是什么。需求本身不复杂，复杂的是过程要可信：每步做了什么、凭什么这么做、谁批准的——A25（形态）、A26（轨迹）、A22（引用）、A29（确认）各自回答过一角，现在拼起来。

核心解释

整体形态按 A25 的标准选：骨架是工作流（四阶段写死），阶段内部是受限智能体（模型自主用只读工具）。路径可预列（四个阶段），所以骨架受控；每个阶段内部要处理什么材料不可预列，所以给模型只读工具让它自己看。

阶段 1  读需求     输入用户的原始描述 → 模型产出结构化需求（改哪里、目标、验收标准）
        ↓ 退出条件：需求四要素齐全，缺了就停下来问用户（不猜）
阶段 2  查代码     受限智能体：只读工具（检索资料库、读课程/文档）→ 定位相关代码与约束
        ↓ 退出条件：命中的片段都有引用（A22），轮次达上限则基于已有信息进入下一阶段
阶段 3  提修改     模型基于证据产出 Proposal（A29）→ 用户预览 diff + reason → 确认/拒绝
        ↓ 退出条件：applied（真实应用结果回传）或 rejected（原因回传，回到阶段 2）
阶段 4  复盘       汇总全程证据：需求原文、检索命中与引用、建议与确认记录、应用结果

四个停止条件（缺一不可，全部写进代码而非约定）：

1. 需求不明即停：阶段 1 的产出缺「改哪里/目标/验收」任一项，直接反问用户，不带着模糊需求往下走。
2. 轮次上限即停：阶段 2 的工具循环沿用 A17 的上限，超限不重启，带着已有信息继续——宁可基于部分证据，不可无限检索。
3. 写操作前必停：阶段 3 的任何落盘动作都要等人工确认（A29），模型没有直接写能力。
4. 资料不足即停：检索明确零命中（A21 的第三层提示）时，如实告知「依据不足」，让用户补充资料或降低要求。

证据保留直接复用 A26 的两张表——task + task_step，加上 A29 的 proposal：

// 每个阶段结束时落一条步骤记录（证据链的核心）
await recordStep(taskId, {
  stepKey: "phase2_search",
  status: "done",
  toolName: "search_documents",
  inputDigest: "查询：导入 幂等",
  outputDigest: "命中 3 片段：团队接口规范.md/删除接口、…（含引用）",
});
// 复盘 = 按 task_id 读全部 step + proposal，按时间线回放

如何验证整个工作流：拿一个真实小需求（如「把切分窗口从 800 改成 600 并说明影响」）完整走一遍，检查证据链闭环——从复盘记录里能独立回答：需求是什么？改动的依据来自哪几个片段？谁确认的？应用结果如何？四个问题都有据可查，工作流才算合格。

示例拆解

一次完整运行的证据链（复盘视图）：

{
  "task": { "id": "task_02", "kind": "assist_review", "status": "done" },
  "timeline": [
    { "phase": "read_requirement", "evidence": "需求：调整 chunkText 窗口为 600；验收：实验对比命中质量" },
    { "phase": "search", "evidence": "引用：A19《文档解析与切分》片段、lib/documents/parse.ts:120" },
    { "phase": "propose", "evidence": "Proposal prop_03：WINDOW 800→600，reason 带实验数据；confirmedBy: user" },
    { "phase": "retrospect", "evidence": "应用成功；实测 5 题命中 top-1 由 2 提升到 4；已知代价：块数 +30%" }
  ]
}

关键点：

• 退出条件就是停止条件的另一面：不满足就停在那里等人或等资料，不带病闯关。写代码时它们是显式的 if 判断，不是注释里的愿望。
• 复盘阶段不是可选项：它是证据链的收口——A31 的评估样例、A33 的回归记录，很多素材就来自复盘视图。没有复盘的工作流跑一百次也沉淀不下经验。
• 失败也要复盘：rejected 的建议、stale 的应用、资料不足的中断都是合法终点——「为什么被拒」本身就是最有价值的证据。
• 成本跟着阶段走：阶段 2 的多次工具调用、阶段 3 的生成，各自记账（A23 的思路），复盘时能看到「这个需求花了多少调用」。

动手任务

1. 把四阶段流程写成 task 表里的真实数据：为「调整切分窗口」需求填出一行 task + 四行 task_step（含每步 input/output 摘要）。
2. 推演中断恢复：任务在阶段 2 第三轮工具调用时进程挂了，写出恢复逻辑——查 task.current_step、读已 done 步骤的输出、幂等键防重复（A27）。
3. 审计任务：对照站内学习助手的现有能力（只读工具、refs 事件、轮次上限），列出「升级成项目助手」还缺的机制清单（至少三条：需求结构化、proposal 表、确认接口、复盘视图）。

常见错误

• 四阶段做成一个巨型 prompt：「你先理解需求再查资料再给方案」，全靠模型自觉——阶段边界不存在，停止条件无从谈起。阶段是代码里的状态机，不是提示词里的排比句。
• 证据只在对话里：聊天记录翻了半天找不到当时引用了哪个片段。证据必须落库（task/proposal），对话只是展示层。
• 停止条件写成建议：「建议在信息不足时询问用户」——模型忙起来就忘了。停止条件是流程代码里的硬分支。
• 复盘变成夸夸文：只记成功不记拒绝与中断，证据链选择性失明。复盘的价值一半在失败案例。

检查与复盘

自查清单：

• 能画出四阶段状态机，标出每个阶段的进入/退出条件
• 能从复盘视图独立回答「需求、依据、确认、结果」四问
• 能说出四个停止条件分别拦在哪个阶段、由哪段代码保证

参考资料

• Anthropic：Building effective agents —— 编排与人工确认环节的官方模式
• OpenAI 文档：Function calling —— 阶段内受限智能体的机制
• SQLite 官方文档：ON CONFLICT —— 证据表与幂等的落库基础
• 下一课 A31 起进入评估篇：先给系统建一个小的考题本。