03 · 做成 Agent 产品：从目标到可验收

开篇 · 真实案例：把认证 Agent 做成可上线产品

00 / 案例背景

机制齐了不等于产品成了。产品成了的标志：用户目标可验收，失败可见，能上线——而不是又一个「什么都会聊」的对话框。

1. 产品背景：认证机制跑通后，为什么还要把它做成产品

01 里阿明用契约、证据和工序把认证修到可合并；02 里小周补齐了 Agent 的运行时，能够读取现行代码、在受控范围内修改 session、运行测试与探针，并在失败时从 Checkpoint 继续。机制已经能跑，但业务后端同学仍无法直接拿它完成一次可交付的认证任务。

产品同学小林接下下一步：做一个“认证交付助手”。它服务于业务后端，而不是泛化成什么都能聊的窗口。用户应能提交明确的认证目标，看到当前步骤、证据与失败原因，在授权边界内让系统修改 auth 并验证“登出后 GET /me 返回 401”。

产品完成的定义：不是界面里出现了聊天、规划和工具按钮，而是目标可验收、能力边界可解释、失败状态可见、高危动作可控，并能在真实仓库与上线流程中承担责任。

2. 核心问题：为什么“Agent 能力清单”还不是可上线产品

小林的第一版几乎把 02 的每个机制都搬进页面：会规划、会工具、会记忆、会反思。演示时，系统能展示一条漂亮的认证链路；接入真实仓库后，团队才发现它没有回答最重要的产品问题：谁是目标用户、这轮任务承诺什么、哪些操作明确不做、什么证据能让用户确认完成、失败后用户应如何继续。

没有这些答案，能力越多，责任反而越模糊。OAuth 会因为“顺便支持”进入范围，哈希路径可能因“自动修复”被触碰，测试失败只能显示“我再试试”，而负责人无法判断是等待、补充信息还是接管任务。此时它仍是机制演示壳，不是能上线的产品。

产品化的关键转译：把内部机制转换为用户可感知的目标、边界、进度、证据和闸门。用户不必了解 ReAct 或 Harness，但必须知道系统承诺做什么、做到哪里、凭什么说完成。

3. 事实证据：第一版为何在真实仓库中失控

下表记录的不是功能缺失，而是产品契约缺失。每一个现场问题都说明：机制没有被封装成用户、权限和验收都能共同理解的行为边界。

时间线	发生了什么	产品缺口
需求会	抄一堆能力：会规划、会工具、会记忆、会反思	没有用户与可否决成功标准
演示日	对话框里「全链路演示」很漂亮	范围未钉死，OAuth 顺手就进了
接真仓库	失败只回「我再试试」；哈希差点被改	失败不可见、无权限闸、无上线标准
复盘	结论：这是机制演示壳，不是可上线产品	缺问题表 → 规格 → 设计卡 → 四柱

flowchart TB Need["业务后端提出认证目标\n登出后 /me = 401"] --> Contract["产品契约\n用户、范围、验收、非目标"] Contract --> Scope{"范围与权限\n是否允许本轮行动？"} Scope -->|不清楚| Clarify["产品显示阻塞\n要求补充目标或授权"] Scope -->|允许| Plan["可见计划\n步骤、进度、Checkpoint"] Plan --> Execute["受控执行\n限域改 auth、跑测试与探针"] Execute --> Evidence{"产品证据面板\n验收是否通过？"} Evidence -->|通过| Deliver["可复查交付\n结果、Diff、run-id、probe-id"] Evidence -->|失败| Recovery["可见失败状态\n补信息、重试、重规划或人工接管"] Recovery --> Plan Scope -->|高危| Gate["人工闸\n批准范围与时效"] Gate -->|批准| Plan Gate -->|拒绝| Stop["产品明确终止原因"]

图中新增的不是一个更复杂的后端流程，而是产品必须露出的责任点：用户先确认目标和范围，系统才开始行动；执行结束后由证据面板而非模型自述裁定结果；失败、阻塞和高危审批都成为可理解、可接手的产品状态。

4. 执行结论：按产品路径重做，先承诺再设计

小林与阿明、小周重新对齐：02 解决“系统缺什么”，本篇解决如何封成可验收的单个产品。接下来的工作不再从“我们有哪些模型能力”开始，而是从用户、目标、验收和非目标开始，再选择本轮需要暴露的能力、状态与控制面。

案例主线：钉用户与目标 → 机制映射成能力 → 勾选本轮能力 → 六项规格填实 → 一页设计卡 → 四柱验收放行。
不重讲 Agent 原理；不扩到平台编制（那是 04）。

进入产品设计前，先确认四件事：

1. 目标用户是谁；一次认证交付替他减少了哪些不可跳过的人工作业？
2. 本轮承诺的成功标准是否能由测试、探针与审计记录共同否决？
3. OAuth、多租户、改哈希、合主干等能力是否已被明确排除或进入人工闸？
4. 失败、暂停、审批拒绝与人工接管是否都有用户能理解的状态和下一步？

思考：产品不是把 Agent 能力摆出来，而是替用户承担一次可追溯的结果

用户真正需要的不是“一个会规划的模型”，而是一次能看懂、能验收、出问题能接住的认证交付。机制越复杂，产品越应把复杂性收在系统内部，把目标、证据、风险和责任清楚地呈现出来。

从这一刻起，任何能力是否进入产品，都要先回答它如何帮助用户达成验收结果，以及失败时由谁、依据什么、以什么状态继续。

---

Part 01 · 产品问题：为谁、完成什么、怎样算成

01 / 用户与目标

不问「Agent 是什么」，先问：为谁、完成什么、怎样算成、明确不做什么。问题表写不满，不要进入能力设计。

1. 问题背景：为什么产品设计要先钉用户与完成态

小林 v0 从“会规划、会工具、会记忆”开工，演示很炫，交付却很虚。能力本身无法说明它为谁服务、要承担什么结果，团队只能不断往清单里加入看似有用的功能。阿明作为首批用户，要的不是又一个聊天窗，而是一份能被合并与联调的认证增量。

因此，认证交付助手的起点不是模型或界面，而是产品问题表：具体用户处于什么场景，本轮目标的完成态是什么，哪几条外部证据可以否决完成，哪些看似合理的需求必须明确排除。问题表未定，后续的能力、规格和设计都没有稳定边界。

成败标准：成功标准必须可外部观察。「更安全」「更好用」不能验收，等于没写目标。

2. 核心问题：为什么“所有人都能用、什么认证都能做”必然失控

当用户被写成“所有人”，场景被写成“做认证”，目标被写成“更安全”，系统就无法判断该选择哪种权限、跑哪些验证、向谁解释失败。范围会自然膨胀到 OAuth、多租户 SSO、自动合主干和生产密钥，任何一项都足以改变产品的风险模型和上线要求。

产品问题表的作用不是写一份漂亮的需求文档，而是拒绝不满足交付条件的任务。用户角色决定授权边界，场景决定所需证据，完成态决定计划终点，成功标准决定能否放行，非目标决定系统必须在何处停止。五项缺一，能力设计就会成为无上限的愿望清单。

产品准入原则：只有当“为谁、在什么场景、交出什么结果、如何否决、明确不做什么”都被写清，任务才允许进入下一章的能力映射。

3. 事实证据：认证交付助手的问题表如何锁住边界

以下定稿把阿明的真实工作对象、验收路径与禁区写成同一份产品输入。它不仅告诉团队要做什么，也告诉产品在哪些请求上必须阻塞、转人工或另开任务。

字段	本轮定稿	写糊会长什么样
用户	业务后端工程师（有仓库写权限；阿明是首批用户）	「所有人」→ 需求互相打架
场景	迭代里要交认证相关增量，怕一次生成踩哈希 / 泄密	场景虚 → 功能清单膨胀
目标（完成态）	在边界内完成注册 / 登录 / 登出相关改动，并通过约定验收	「做好认证」→ 无法判定完成
成功标准	① auth 单测绿 ② 手动：登录→/me 200→登出→/me 401 ③ 错误体不泄堆栈/路径 ④ 关键写操作可审计	形容词验收 → 假完成
非目标	不做 OAuth、不做多租户 SSO、不替人合主干、不碰生产密钥	缺非目标 → 范围漂（v0 翻车）

用户

具体到角色与权限

有写权限的业务后端；不是「全公司」或「AI 爱好者」。

成功标准

可一票否决

每条对应命令或手动路径；第三方能按同一路径说「没过」。

非目标

挡住最易漂的三项

OAuth / 合主干 / 密钥——v0 演示里全踩过边。

目标

完成态语言

写「边界内改完并证明」，不写「提供智能认证体验」。

flowchart TB Start["提出认证产品需求"] --> User{"用户是否具体到\n角色与权限？"} User -->|否| Narrow["收窄用户\n不能写成所有人"] User -->|是| Scenario{"场景与任务范围\n是否明确？"} Narrow --> User Scenario -->|否| Clarify["补充场景\n例如认证增量交付"] Scenario -->|是| Goal{"完成态是否可描述\n边界内改完并证明？"} Clarify --> Scenario Goal -->|否| Rewrite["重写目标\n拒绝形容词承诺"] Goal -->|是| Acceptance{"成功标准是否\n可被测试或探针否决？"} Rewrite --> Goal Acceptance -->|否| Evidence["补充验收路径\n测试、探针、审计"] Acceptance -->|是| NonGoal{"OAuth、合主干、密钥等\n非目标是否明确？"} Evidence --> Acceptance NonGoal -->|否| Fence["写入非目标与人工闸"] NonGoal -->|是| Ready["问题表定稿\n允许进入能力设计"] Fence --> NonGoal

图中的每个判断都可以把需求挡在能力设计之前。缺用户就不能选择权限，缺验收就不能显示完成，缺非目标就不能阻止范围漂移。问题表不是一次性填写的表单，而是产品承诺的第一道闸门。

4. 执行结论：问题表定稿后，才允许讨论能力与规格

产品团队应将问题表视为能力设计的准入条件。它通过，不代表产品已经设计完成；它只意味着团队终于拥有了一个可以被检验的目标，可以据此选择目标理解、任务规划、工具调用等能力，并为每项能力继续写输入、输出、失败态和验收点。

1. 能否指出「哪一条命令/手动路径」证明没过？不能 → 重写成功标准。
2. 非目标是否挡住最容易漂的三项？没有 → 补 OAuth / 合主干 / 密钥。
3. 用户是否具体到角色，而不是「所有人」？否 → 先收窄。
4. 阿明能否用这张表向 reviewer 解释「助手何时算帮完」？不能 → 表未定稿。

补充判断：当新的需求试图加入 OAuth、自动合主干或生产密钥时，不应悄悄塞回本轮范围；应回到问题表重新评估用户、风险、验收与非目标，或建立新的产品任务。

思考：产品问题表真正保护的不是文档完整度，而是用户对结果的预期

用户愿意把认证改动交给助手，前提是知道它会做什么、不会做什么、何时能说完成。把这几件事写成可否决的问题，才能让能力设计服务于结果，而不是让结果迁就一张越来越长的功能清单。

问题表越具体，后面的产品选择越容易：哪些能力必须做、哪些必须延后、哪些风险必须在界面上提前说明，都会有可追溯的依据。

这一幕带走：产品从问题表开始。成功标准可一票否决，非目标挡住范围漂；写不满四行，不开能力设计。

---

Part 02 · 机制对照：把 02 翻成产品能力

02 / 映射

02 的机制名翻成产品能力名。本篇写规格与选型，不写原理课——机制名进抽屉，产品能力进规格。

1. 映射背景：为什么不能把 02 的机制名直接搬进产品

02 解决的是认证 Agent 在运行时缺什么：Context、Plan、Tool、Harness、Reflection、Routing 和 Governance 各自承担什么职责。产品设计面对的却是另一组问题：阿明在什么时候需要确认目标，为什么任务被阻塞，哪里可以看到依据和进度，工具被拒绝时如何理解，完成时凭什么相信结果。

因此，小周讲机制，小林问产品要什么。对照表不是把 02 再讲一遍，而是把内部运行能力翻译成可承诺的产品行为。每一格都必须回答：本产品要不要、要成什么样、用户如何感知、失败时显示什么。

避免术语直出：用户不需要一个名叫“Reflection”的按钮；他需要看到“验证未通过”的原因、对应证据和下一步。机制名没有被翻译为可见行为，就还没有进入产品规格。

2. 核心问题：为什么“有能力”不等于“用户能使用并验收”

一个运行时能力只有被放进明确的产品边界后才有意义。Tool 若没有白名单、拒绝提示和审计入口，用户只会看到一次不可解释的失败；Harness 若没有暂停、恢复和交接状态，用户仍会在中断后重新提问；Reflection 若不展示测试与探针证据，完成标记依然只是模型自述。

产品能力应同时满足四个条件：它服务于 Part 01 的目标；能写出输入、输出、失败态和验收点；不与非目标冲突；用户能在界面或交付物中感知其成功与失败。缺少任何一项，能力都只是架构图上的名词，不应进入本轮承诺。

转译原则：把“系统怎么做”改写为“产品为用户提供什么状态、控制与证据”。内部实现可以迭代，用户可验收的行为必须稳定。

3. 事实证据：认证助手如何把运行机制转成可感知能力

下面的映射表为认证交付助手定义了最小的能力外观。它将运行时责任、产品承诺和用户可见的反馈放到同一行，避免出现“后台有能力，前台没有结果”的断层。

运行时机制（02）	产品能力	认证助手要什么	用户如何感知
目标 / Context	目标理解	澄清验收与非目标，歧义阻塞	可编辑契约卡；阻塞态可见
Plan	任务规划	可验证步骤，进度可见	步骤列表；卡在 Sx 可看见
Tool	工具调用	限域读改测；越权拒绝	拒绝原因弹层；审计可查
Context / Memory	上下文与记忆	本轮依据 + 短程进度	可展开「依据来源」
Harness 状态	状态与恢复	中断可续、可交接	暂停/恢复按钮；Brief 导出
Reflection	验证与反馈	回证据，禁假完成	通过/未通过 + 证据链接

flowchart TB Runtime["运行时机制\nContext · Plan · Tool · Harness · Reflection"] --> Translate["产品能力转译\n选择本轮要承诺的行为"] Translate --> Goal["目标理解\n可编辑契约与阻塞态"] Translate --> Planning["任务规划\n步骤、依赖与进度可见"] Translate --> Tools["工具调用\n限域执行、拒绝原因、审计"] Translate --> Memory["上下文与记忆\n依据来源可展开"] Translate --> State["状态与恢复\n暂停、恢复与交接"] Translate --> Verify["验证与反馈\n通过或未通过 + 证据"] Goal --> Spec{"四段规格齐全？\n输入、输出、失败态、验收点"} Planning --> Spec Tools --> Spec Memory --> Spec State --> Spec Verify --> Spec Spec -->|是| Promise["写入产品能力组合\n进入 Part 03"] Spec -->|否| Backlog["不承诺或补规格\n不能只列功能名"]

图中的汇聚点说明：能力只有通过四段规格检查后才能进入产品承诺。产品可以在内部用不同模型或工具实现“目标理解”，但用户始终应看到可编辑契约与明确阻塞态；同理，验证能力的价值不在内部反思次数，而在界面能否给出通过、未通过与证据链接。

4. 执行结论：先选用户可验收的能力，再决定内部实现

Part 02 的输出不是一份技术架构，而是一张进入 Part 03 的能力候选表。每项能力都要基于 Part 01 的用户目标做取舍：目标不依赖的能力不承诺，无法写清四段规格的能力先补设计，与非目标冲突的能力要砍掉或降级为说明产出。

1. 用户目标是否依赖该能力？否 → 本轮不承诺。
2. 能否写出输入 / 输出 / 失败态 / 验收点？否 → 还是名词，不是产品能力。
3. 是否与非目标冲突（如自动合主干）？是 → 砍掉或降级为说明产出。
4. 用户能否在界面上感知该能力的成功与失败？不能 → 规格未落地。

干货：Governance / Routing 在单产品里体现为权限表与上线闸门，不必再开两个「能力模块」名词吓唬人。

思考：产品能力的稳定性，来自用户可见的契约，而不是内部实现的固定

模型、检索方案和工具链都可能替换，但“任务被阻塞时显示什么”“写操作被拒绝时如何解释”“完成时凭什么给出证据”不能随着实现变化而漂移。用户依赖的是这些稳定的行为边界，而不是某个机制名称。

完成映射后，团队才有资格讨论本轮到底勾选哪些能力。下一章的选择不再是“功能越多越好”，而是对每一项可验收承诺负责。

这一幕带走：对照表用来选型；每格要有「要什么 + 用户如何感知」。

---

Part 03 · 能力地图：本轮勾选，不贪多

03 / 组合

六项都是模块。勾选 = 承诺可验收的最小规格，不是愿望清单。v0 错在「全开 + 无规格」；本轮是「全开 + 每格可验收」。

1. 组合背景：为什么 v1 不能从“把能力全开”开始

Part 02 已把运行机制翻译为产品能力，但映射不是承诺。小林的 v0 正是因为把“会规划、会工具、会记忆、会反思”一股脑放进演示，才让范围、权限和验收一起失去边界。每增加一项能力，产品就多了一份用户预期、失败状态和验收责任。

本轮的能力地图因此不是功能菜单，而是一份交付承诺：认证交付助手只勾选阿明完成本轮认证增量不可缺少的能力，并为每一项写下最小规格；任何无法证明价值、无法定义失败态或与非目标冲突的能力，都必须延后或拒绝。

勾选的含义：勾选不是“以后可能做”，而是“本轮用户可以依赖，并能验收成功或失败”。没有规格与验收点的能力，不能以“先放个入口”进入 v1。

2. 核心问题：为什么能力越多，不一定越接近可上线

能力越多会扩大产品承诺面。自动合主干需要更严格的治理与人工闸，多租户和跨仓库编排需要新的身份、状态和隔离模型，长期跨项目记忆会带来脏数据与合规成本，OAuth/SSO 则已经超出当前认证增量的任务边界。把这些能力与“修复登出会话”一起交付，只会让测试、权限和支持成本同时失控。

正确的取舍不是追求能力数量，而是检查每项能力是否直接支撑 Part 01 的完成态：能否让目标变清楚、步骤可执行、写入受控、依据可靠、中断可恢复、完成可证明。若答案为否，或产品暂时无法承担其风险与验收，就不应进入本轮范围。

最小组合原则：为完成“边界内修改认证并证明登出后 /me 为 401”而选能力；不为展示 Agent 看起来更全能而扩张范围。

3. 事实证据：认证交付助手本轮承诺什么，也明确不承诺什么

六项必选能力共同构成一条可交付链路：先把目标写成契约，再把工作拆成可验证步骤，在限域工具和可信依据下执行，允许中断恢复，并以证据而非自述结束任务。它们都不是“高级功能”，而是本轮验收不可缺失的底座。

目标理解必选 · Part 04

任务规划必选 · Part 05

工具调用必选 · Part 06

上下文与记忆必选 · Part 07

状态与恢复必选 · Part 08

验证与反馈必选 · Part 09

能力	为何必选（对阿明）	最小规格一句话
目标理解	防止「安全一点」开干	输出可编辑契约；歧义阻塞
任务规划	大 Diff 不可验收	步骤可勾选；未确认不往下
工具调用	要真改仓库	白名单写；拒绝可见
上下文与记忆	要吃对现行实现	依据可展开；密钥进不来
状态与恢复	联调会中断换人	可暂停；Brief 可交接
验证与反馈	防假完成	无证据不得标完成

明确砍掉同样是产品决策。下列能力不是“不重要”，而是在当前用户、范围与验收条件下不应由认证交付助手承担。它们必须写入非目标或路线图，防止在实现过程中以“顺手支持”的方式回潮。

砍掉项	原因	以后谁做
自动合主干	高危；本产品只产出可审查变更说明	治理更严的平台能力
多租户 / 跨仓库编排	超出单产品边界	04 数字员工平台
长期跨项目偏好记忆	易脏、难合规	可选增强，非 v1
OAuth / SSO 交付	非目标	另开产品问题表

flowchart TB Candidate["候选产品能力"] --> Goal{"是否直接服务\n认证完成态？"} Goal -->|否| Defer["延后或另开产品问题表"] Goal -->|是| Spec{"能否写清\n输入、输出、失败态、验收点？"} Spec -->|否| Design["补规格\n暂不承诺"] Spec -->|是| Boundary{"是否与非目标或\n风险边界冲突？"} Boundary -->|是| Reject["砍掉或降级\n例如自动合主干、OAuth"] Boundary -->|否| Visible{"用户是否能感知\n成功、失败与证据？"} Visible -->|否| Surface["补状态与反馈设计"] Visible -->|是| Commit["写入能力组合\n进入对应规格章节"] Design --> Spec Surface --> Visible

图中的出口避免了“功能不是现在做、但页面先留着”的灰色地带。候选能力要么进入带验收点的本轮组合，要么补规格后再评估，要么明确进入路线图或非目标；没有第四种“默认会做”。

4. 执行结论：能力组合通过门禁后，再逐项填实规格

Part 03 的输出是一张受约束的能力组合，而不是产品设计终稿。每项勾选能力接下来都要在 Part 04 至 Part 09 中完成输入、输出、失败态和验收点；每项砍掉能力都要留在非目标或路线图中，确保范围变化时可以重新审查，而不是在实现中被悄悄恢复。

1. 该项是否写入设计卡「能力组合」？
2. 是否已有（或本篇将写）输入/输出/失败态/验收点？
3. 砍掉项是否出现在非目标或路线图？未写 = 仍可能被悄悄做回来。

补充判断：当某项新能力进入候选列表，重新从“是否服务当前完成态”开始走门禁；不要因为它在技术上可实现，就跳过用户价值、风险边界与验收责任。

思考：产品克制不是少做功能，而是让每项承诺都值得被用户相信

认证交付助手不替人合主干、不碰生产密钥，并不是能力不足，而是把自动化停在当前产品能证明、能支持、能治理的边界内。对用户而言，一个可靠地完成六项承诺的助手，比一个承诺十项却无法解释失败的系统更有价值。

能力地图的真正作用，是让团队在开发之前就公开地做取舍，并在每次范围变化时重新承担这份取舍的后果。

这一幕带走：勾选即承诺最小可验收规格；砍掉项必须写明，防止能力回潮。

---

Part 04 · 规格：目标理解

04 / 目标理解

用户一句话进来，产品要输出可执行的目标契约字段；歧义未消就阻塞，不准开改。

1. 规格背景：为什么一句“把登录做安全一点”不能直接开改

业务后端工程师通常从一句自然语言开始描述认证问题，例如“把登录做得安全一点”或“登出后用户好像还能访问”。这句话可以启动对话，却不能启动写操作：它没有说明要改哪个边界、成功如何验证、是否允许触碰 session 以外的路径，以及 OAuth、密钥等高风险范围是否被排除。

目标理解是认证交付助手的第一道产品能力。它将用户意图转成可编辑、可否决的目标契约，在歧义未消或范围冲突时向用户展示阻塞原因；只有用户确认契约后，任务规划和工具调用才有合法输入。

写入前提：自然语言不是授权。契约未确认时，全局写锁保持关闭；产品应显示缺什么、为什么阻塞、用户可如何补充，而不是让模型猜测后继续执行。

2. 核心问题：为什么目标理解必须产出结构化契约

如果目标只停留在聊天记录中，用户、执行器和 reviewer 会分别理解成不同任务：有人认为只要改登录页，有人认为应重做密码策略，有人会顺手加入 OAuth。产品既无法确定可调用的工具，也无法为“完成”提供一致证据，失败时更无法说明究竟是目标缺失、权限不足还是实现未通过。

结构化契约把这一层不确定性拆成四个可检查字段：Goal 描述完成态，Boundary 限定可行动范围，Acceptance 给出外部可否决证据，Non-goals 明确系统必须停止的地方。它既是用户确认的产品对象，也是后续 Plan、Tool、验证与审计共同消费的输入。

契约的产品价值：不是替用户写得更正式，而是让用户能编辑和确认承诺，让系统能据此阻塞越界请求，让第三方能凭同一条 Acceptance 否决“已完成”。

3. 事实证据：认证输入如何被转成可放行或可阻塞的契约

认证交付助手的目标理解不以“模型给出一个合理建议”为终点，而以一张可展示的契约卡为终点。它必须能说明输入是什么、输出如何被用户编辑、哪些情况阻塞，以及什么证据证明契约已经足够进入规划。

段	认证交付助手
输入	工程师自然语言 + 可选仓库路径提示
输出	Goal / Boundary / Acceptance / Non-goals（结构化，可展示可编辑）
失败态	缺验收句、范围含 OAuth/密钥 → 阻塞，要求人补全
验收点	输出契约可被第三方按 Acceptance 一票否决；禁止用形容词充数

用户输入	产品应有状态	下一步
「把登录做得安全一点」	blocked_need_acceptance	UI 要求补可否决句
「顺便把 OAuth 也做了」	blocked_non_goal	标红非目标冲突，请删或另开任务
完整四字段 + 登出后 401	contract_ready	进入任务规划

示例输出（产品界面可见）： Goal: 修复登出后会话仍有效 Boundary: 只改 auth/session 与对应测试；禁止改哈希 Acceptance: auth.session.spec 绿；手动登出后 GET /me → 401 Non-goals: 不引入 OAuth

flowchart TB Input["用户输入\n自然语言 + 可选仓库提示"] --> Parse["提取候选契约\nGoal · Boundary · Acceptance · Non-goals"] Parse --> Acceptance{"Acceptance 是否\n可被测试或探针否决？"} Acceptance -->|否| NeedAcceptance["blocked_need_acceptance\n显示需补充的验收句"] Acceptance -->|是| Boundary{"Boundary 与 Non-goals\n是否冲突或越权？"} NeedAcceptance --> Edit["用户编辑契约卡"] Boundary -->|是| NeedScope["blocked_non_goal\n标红 OAuth、密钥或越权范围"] Boundary -->|否| Confirm{"用户确认\n本轮契约？"} NeedScope --> Edit Edit --> Parse Confirm -->|否| Edit Confirm -->|是| Ready["contract_ready\n打开规划，保持审计关联"] Ready --> Plan["进入 Part 05 任务规划\n工具写权限仍按 Boundary 限制"]

图中的阻塞状态不是产品失败，而是可靠产品行为。缺验收句时，用户看到 blocked_need_acceptance 并补充可否决证据；范围碰到 OAuth 或密钥时，用户看到 blocked_non_goal 并收窄任务或另开需求。只有契约被确认，系统才产生 contract_ready。

4. 执行结论：契约未确认不规划，规划未完成不开写

Goal、Boundary、Acceptance、Non-goals 与 01 的人侧任务契约同构，但在产品里它们必须是用户可见、可编辑、可审计的结构化对象。阿明确认前，系统可以解释、澄清和展示候选契约，却不得开始修改仓库；确认后，Plan 只能在 Boundary 内拆步，Tool 只能在相应白名单内行动。

目标理解的规格自检：

1. 每个用户输入是否都能归入“可澄清、可阻塞或可确认”三种产品状态，而不是被静默猜测？
2. Acceptance 是否对应具体测试、探针或人工路径，使第三方能够明确指出“没有通过”？
3. Non-goals 是否覆盖 OAuth、合主干、密钥等最常见的范围漂移入口？
4. contract_ready 是否是唯一允许进入任务规划的状态？

干货：目标理解的产品验收不是“模型会不会总结需求”，而是“契约能不能否决完成，阻塞态能不能阻止越界开写”。

思考：澄清不是多问几轮，而是让系统只在承诺成立后行动

用户有时会觉得阻塞多了一步，但缺少这一步的代价是让写操作在错误的目标、范围或验收下发生。好的目标理解不是让对话变长，而是让每一次追问都对应一个缺失字段，并在字段补齐后明确推进状态。

当用户能看见并确认这张契约卡，后续规划、工具调用和验证就不再是模型的私人推理，而是一份可以共同执行与复查的产品承诺。

这一幕带走：契约未确认 = 全局写锁关闭。阻塞态必须对用户可见。

---

Part 05 · 规格：任务规划

05 / 任务规划

输出可验证步骤与依赖；依赖不清则重规划并告知用户，不准闷头开改。

1. 规划背景：为什么契约确认后仍不能直接执行

contract_ready 说明用户、范围和验收已经对齐，但它还没有告诉系统应以什么顺序改动、每一步如何判断通过、哪一步可以并行、失败后从哪里恢复。若系统把整份认证需求一次性交给模型执行，用户最终只会得到一个大 Diff 和一句“应该修好了”，既无法审查，也无法定位失败。

任务规划的产品职责，是把已确认契约翻译为用户可见的步骤对象：每步有依赖、完成条件、风险与当前状态。阿明不需要阅读内部推理过程，但应能看见系统当前卡在 S3、为什么卡住、下一步被允许做什么，以及重规划后哪些已确认结果仍然保留。

执行前提：没有完成条件和依赖关系的“计划”只是散文。步骤对象未生成或依赖不清时，产品应显示规划阻塞或重规划，而不是闷头开始 patch。

2. 核心问题：为什么散文计划与静默重规划会破坏产品信任

散文计划无法回答“现在完成了哪一步”“为什么 S3 可以开始”“测试失败后要回哪里”。更危险的是，系统在发现假设错误后若静默重写计划，用户会看到任务突然跳步或重复执行，却不知道范围、风险或验收条件是否已经变化。

产品级规划必须将计划变化视为可感知事件。步骤依赖约束执行顺序，Checkpoint 约束下游消费已确认输出，重规划记录原因和新版本，用户据此决定继续、补充信息或接管。这样，规划不再是模型的思考草稿，而是认证交付过程的共同工作面。

产品规划原则：用户看到步骤、状态、完成条件与变更原因；系统保留内部推理细节，但不能隐藏会改变范围、依赖或恢复点的计划变更。

3. 事实证据：认证契约如何变成可勾选的 S1-S4 计划

认证交付助手接收已确认契约后，输出的不是一篇执行方案，而是一组可被验证层勾选的步骤。下表定义产品在规划阶段必须展示和保存的字段，确保每一次前进都能解释“依据什么、如何通过、失败后到哪里”。

段	认证交付助手
输入	已确认契约（contract_ready）
输出	步骤列表：每步完成条件、依赖、风险；S1 登录 → S2 鉴权 → S3 登出 → S4 错误体
失败态	步骤无完成条件 / 依赖成环 → 重规划并告知用户
验收点	任一步可单独勾选「过/不过」；下一步不得消费未确认输出

补充证据：步骤对象、依赖与重规划如何对用户可见

可见

步骤对象，非散文

用户应能看到「当前卡在 S3」；只暴露产品字段，不暴露内部推理轨迹全文。

重规划

显式、可感知

依赖变化或假设错误时，UI 显示原因与新步骤图，不静默改计划。

依赖

S3 不得抢跑

S2 未确认前，禁止启动登出失效步骤——与 01 工序、02 Plan 同构。

验收

进度可见 + 步步可验

每步完成条件映射到测试或探针；勾选由验证层驱动，不由模型自述。

产品计划卡（用户可见）： S1 登录可用 完成条件：登录用例绿 状态：待执行 S2 无会话 /me=401 完成条件：未登录探针返回 401 依赖：S1 S3 登出后 /me=401 完成条件：登出探针返回 401 依赖：S2 S4 错误体合规 完成条件：快照绿且无绝对路径 依赖：S2、S3 当前：S3 · checkpoint：guard-401 · 可选出口：修复 / 补依据 / 重规划

flowchart TB Contract["contract_ready\n认证目标与验收已确认"] --> Plan["生成计划 v1\n步骤、依赖、完成条件、风险"] Plan --> S1["S1 登录可用\n登录用例绿"] S1 --> C1["Checkpoint: login-ok"] C1 --> S2["S2 无会话 /me = 401\n未登录探针通过"] S2 --> C2["Checkpoint: guard-401"] C2 --> S3["S3 登出后 /me = 401\n登出探针通过"] C2 --> S4["S4 错误体合规\n快照无路径泄露"] S3 --> C3["Checkpoint: logout-401"] C3 --> S4 S4 --> C4["Checkpoint: error-body"] C3 --> Review["交付审查"] C4 --> Review S3 -. "依赖变化或假设失效" .-> Replan["显式重规划 v2\n显示原因与保留的 Checkpoint"] Replan --> Plan

图中 S3 不得在 S2 确认前启动，S4 同时依赖鉴权与登出结果。若登出问题暴露出新的依赖或原假设错误，系统不会把 S1、S2 的绿点抹掉，而是生成可见的计划新版本；用户能看到为什么变化、哪些结果继续有效、下一步将从哪里恢复。

4. 执行结论：下一步只消费已确认输出，重规划必须可见

任务规划的验收不在于模型能否列出更多步骤，而在于用户能否据此审查推进过程。每个步骤必须有完成条件，下一步必须消费已经确认的 Checkpoint，验证失败必须停在当前或回到最近恢复点；范围、依赖或风险一旦变化，系统就必须以新版本计划说明原因，而非在后台静默改写。

规划规格自检：

1. 每一步是否都有用户可理解的名称、依赖、完成条件和当前状态？
2. 用户是否能看到当前卡在哪一步，而不是只看见一段模型总结？
3. 后续步骤是否只消费已确认的 Checkpoint，禁止未验证抢跑？
4. 重规划是否展示触发原因、新旧计划差异和仍然有效的 Checkpoint？

思考：好的计划不是替用户预测一切，而是让变化发生时仍然可解释

认证任务一定会遇到未知：测试可能暴露新约束，仓库状态可能变化，某一步也可能失败。计划的价值不在于一开始排得绝对正确，而在于把已确认的结果保留下来，让后续变化以可见、可审计、可恢复的方式发生。

当用户可以看见步骤、证据和重规划原因，系统就不再是在“替他思考”，而是在与他共享一条可以共同交付的工作路径。

这一幕带走：规划输出是可勾选的步骤对象；下一步只消费已确认输出；重规划必须可见。

---

Part 06 · 规格：工具调用

06 / 工具调用

工具是产品能力的手。越权与失败必须对用户可见，关键写操作可审计——「拒绝长什么样」比「能调什么」更重要。

1. 调用背景：工具为什么不能只是模型的一只手

计划进入 S1-S4 后，认证交付助手才需要读取仓库、编辑受限文件、运行测试和发起本地探针。工具调用把“建议”变成了对工作区的真实动作：一次错误的路径匹配可能改到密码哈希，一次未经约束的命令可能扩大变更范围，一次没有关联任务的 patch 则让用户无法判断它为何发生。

因此，工具层的产品职责不是尽可能多地开放能力，而是把当前步骤翻译为一次受限、可解释、可回溯的授权。模型可以提出调用意图，策略与运行时负责判断它是否符合已确认的契约、步骤和权限边界；用户看到的则是这次动作做了什么、依据什么被允许或拒绝。

调用前提：没有步骤 ID、目标路径、操作类型和策略版本的调用，不应获得写权限。工具并不替代任务规划，它只执行已经被规划和授权的下一步。

2. 核心问题：为什么“能跑通”仍可能是一次失控

裸工具调用通常只关心命令是否成功，却回答不了“它是否应该执行”。例如，Agent 为让登录测试变绿而修改共享哈希工具，或为了调试直接读取 .env，即使短期测试通过，也已经越过本轮认证交付的边界。把成功退出码当成完成，会让风险以更快的速度积累。

另一种常见失控是拒绝不可见：系统只在内部跳过危险操作，用户最终看到一个缺失的 Diff，既不知道任务为何停住，也无法决定是收窄范围、补充授权还是人工接管。产品必须把“拒绝”设计成正常结果，而不是静默异常。

受控调用原则：每次调用都回答四个问题：谁在什么步骤提出了什么动作、将影响哪里、依据哪条策略被允许或拒绝、结果如何影响下一步。缺少其中任一项，系统就只能停在待确认状态。

3. 事实证据：认证步骤如何变成可审计的工具调用

当计划推进到 S3“登出后 GET /me = 401”时，系统不会把终端交给模型自由探索，而是为这个步骤生成最小调用许可：可读取现有 session 路由与相关测试，可修改认证实现和认证测试，可运行指定测试与本地探针；密码哈希、环境文件、密钥和合主干则始终不在许可内。

权限矩阵（产品配置）： allow_write: src/auth/** , tests/auth/** deny: **/*hash* , **/.env* , **/secrets/** high_risk: 合主干 → 本产品不做，只产出 PR 草稿说明 拒绝 UI 必含： reason_code · 触碰路径 · 对应策略版本 · 「请改范围或联系管理员」

步骤事件	允许的调用与用户可见结果	必须保留的证据
S3 读取现有会话逻辑	read session 路由与登出测试；展示读取范围	step-id、文件清单、策略版本
S3 修复会话失效	patch 仅限 src/auth/**；展示 Diff 摘要	调用参数、变更指纹、可回滚工作树状态
验证登出行为	test + probe；展示 GET /me 的 401 结果	run-id、退出状态、日志与响应快照
试图改哈希或读取密钥	拒绝卡片：路径、原因码、下一步选择	DENY、FORBIDDEN_PATH、策略版本

flowchart TB Step["当前步骤 S3\n登出后 /me = 401"] --> Intent["模型提出工具意图\nread / patch / test / probe"] Intent --> Gate{"策略闸：步骤、路径、操作、权限\n是否同时匹配？"} Gate -->|允许| Execute["受限执行\n记录 step-id 与策略版本"] Execute --> Result{"结果是否满足完成条件？"} Result -->|是| Evidence["保存 Diff、run-id、401 快照\n写入 checkpoint: logout-401"] Evidence --> Next["解锁下一步或进入交付审查"] Result -->|否| Failed["步骤标红\n附日志与失败证据"] Failed --> Recover["回到当前步骤\n修复、补依据或重规划"] Gate -->|拒绝| Deny["拒绝卡片\n原因码、路径、策略版本"] Deny --> Choice["用户：收窄范围 / 申请授权 / 人工接管"]

这个流程的关键不在于拦住所有调用，而在于把每个调用绑定到可验证的交付路径。允许的 patch 必须能追溯到 S3，测试失败必须让 S3 保持未完成，越权请求必须留下拒绝证据并给出用户可以采取的下一步。

4. 执行结论：授权、执行、验收必须是同一条链

工具调用的验收标准不是“工具能用”，而是任何写操作都不能脱离已确认的计划与边界。产品应在执行前完成策略判定，在执行中保存可审计事件，在执行后用测试或探针裁定步骤是否完成；策略拒绝、命令失败和验证失败都必须把任务送往可见的恢复入口。

准备：step-id + 调用意图 + 策略版本 判定：允许 → 受限执行；拒绝 → 原因码与用户选项 执行：读/改/测均写入审计；写操作保存 Diff 与工作树指纹 验收：测试或探针通过 → checkpoint；失败 → 当前步骤回流 边界：不读密钥、不改哈希、不合主干；超出边界交给用户决策

工具调用规格自检

1. 每次 patch 是否都带有计划步骤 ID、允许路径和策略版本？
2. 拒绝事件是否向用户展示原因、触碰范围与可执行的下一步，而不泄露敏感内容？
3. 测试与探针结果是否回写到该步骤，而不是只显示一段孤立日志？
4. 高风险动作是否明确停在产品边界外，并提供人工接管或 PR 草稿等替代产出？

思考：真正的自主，不是少问人，而是知道何时必须停下

用户把认证任务交给 Agent，并不等于把所有权限一并交出去。越是在看似简单的修复中，越需要让系统明确它能做什么、拒绝什么、失败后如何把控制权交还给人。

受控工具调用并没有削弱执行速度：它把无效探索和不可解释的返工挡在边界外，让每一次实际改动都更接近可合并、可复查的交付结果。

这一幕带走：手必须受控：白名单、拒绝可见、写操作可审计；合主干不做，只给说明产出。

---

Part 07 · 规格：上下文与记忆

07 / 上下文与记忆

产品要规定：存什么、召回什么、过期与越权数据进不来。价值是「正确时间给正确依据」，不是存得越多越好。

1. 上下文背景：为什么认证 Agent 不能靠“记得很多”工作

当认证任务走到 S3，系统需要同时理解已确认的契约、当前 Checkpoint、现有 session 实现、相关测试和最近一次失败的探针结果。它需要的不是整仓代码或所有历史聊天，而是一份足以裁定当前动作的依据包。少了关键约束，模型会猜；塞入无关或过期内容，模型又会在错误的事实之上推理。

上下文与记忆在产品中的职责，是为每一个步骤提供“此刻可用、来源可查、权限匹配”的最小事实集，并保存短程任务状态。用户不必阅读模型内部如何压缩文本，但应能展开查看：这一步依据哪些文件与验证结果，它们何时生成、是否仍有效、为什么某条信息没有被带入。

装载前提：只有能对应当前步骤、来源明确且未过期的内容，才能成为依据。上下文不是素材堆，更不是绕开工具权限读取敏感信息的通道。

2. 核心问题：为什么旧日志、整仓输入和长期偏好都会污染判断

若系统为“避免遗忘”把整仓代码、旧 run 日志和历史偏好一并塞入上下文，当前步骤就失去优先级。一个早已修复的失败记录，可能让 Agent 重复无效补丁；一份与本轮无关的 OAuth 设计，可能把范围重新拉大；一段来自密钥或环境文件的内容，则直接突破了工具层设定的边界。

记忆失控的后果通常不像越权写入那样显眼。它会表现为模型引用过时实现、反复解释已被否决的方案，或声称“按照项目惯例”却没有可展开的来源。产品因此必须把存入、召回、驱逐和清理做成显式策略，而不是把它们留给一次不可见的上下文拼接。

治理原则：当前事实优先于历史摘要，任务内证据优先于跨任务偏好，授权范围优先于“可能有用”的信息。无法说明来源、有效期与授权关系的内容，默认不进入依据包。

3. 事实证据：S3 的最小依据包如何生成、使用与淘汰

针对“登出后 GET /me 仍返回 200”的 S3，认证交付助手只装载五类信息：已确认的登出验收句、guard-401 Checkpoint、session 与登出路由、对应测试、最近一次 200 响应快照。系统把每项内容附上来源、获取时间和适用步骤；哈希、.env、密钥、旧 run 与 OAuth 文件即使被检索到，也必须在策略闸处被排除。

存

本任务级

契约确认版、Checkpoint、本轮失败约束，以及每条依据的来源、时间和适用步骤。

召回

按步装载

S3 只装 session、登出测试与 200 快照；不整仓灌入。

驱逐

过期与越权出局

旧 run、密钥、非目标范围文件和失效快照，均由策略拒绝进入。

裁剪

不做长期偏好

跨项目「个人偏好记忆」非 v1；任务结束可清理。

依据条目	何时可进入 S3	用户可见信息与失效条件
确认版契约	状态为 contract_ready，且 Acceptance 包含登出后 401	契约版本；用户撤回或修改范围即失效
session / 登出实现	路径落在当前工具读取白名单	文件来源与版本；工作树变化后重新获取
测试与 200 快照	绑定当前 S3 run 与同一环境	run-id、时间、响应摘要；新一轮执行后替换
密钥、哈希、OAuth 文件	永不进入本轮依据包	显示排除原因，不展示敏感正文

flowchart TB Step["当前步骤 S3\n登出后 /me 必须为 401"] --> Collect["候选依据\n契约、Checkpoint、session、测试、最近快照"] Collect --> Filter{"来源、时效、步骤相关性、权限\n是否全部通过？"} Filter -->|通过| Pack["生成最小依据包\n每项带 source / time / scope"] Pack --> Execute["供受控 read / patch / test 使用"] Execute --> Verify{"新的测试与探针结果"} Verify -->|通过| Store["更新短程记忆\ncheckpoint: logout-401"] Verify -->|失败| Refresh["保存失败证据\n替换过期快照后重新装载"] Refresh --> Collect Filter -->|拒绝| Exclude["排除：旧 run、越权文件、密钥、非目标内容"] Exclude --> Notice["用户可展开排除原因\n不暴露敏感正文"] Store --> Cleanup["任务结束：保留审计摘要\n清理任务级运行上下文"]

与 Part 02 的分工：Context 治理在系统侧；产品侧必须呈现“本步依据来源”、排除原因和任务结束后的清理策略，让用户能判断系统是否在正确事实之上执行。

4. 执行结论：记忆必须服务于当前步骤，并且允许被遗忘

上下文与记忆的验收不在于保存了多少内容，而在于当前步骤是否能凭借一组可信事实做出正确动作。每一条进入依据包的内容都应有来源、有效期、适用范围与可见摘要；每一次新验证都应更新或淘汰旧证据；任务结束后则按策略清理运行上下文，仅保留交付所需的审计与结果摘要。

收集：仅取契约、当前 Checkpoint、授权文件、当前 run 证据；过滤：校验来源、时效、步骤相关性与权限，不通过即排除；装载：最小依据包随步骤进入受控执行，并可向用户展开来源；更新：新测试覆盖旧快照，失败证据回流到当前步骤；清理：任务结束移除短程上下文，不做跨项目长期偏好记忆。

上下文与记忆规格自检

1. 用户能否看见当前步骤引用了哪些来源，以及这些来源为何仍然有效？
2. 旧 run、过期快照、越权路径和敏感内容是否在进入模型前即被排除？
3. 新的测试与探针结果是否会替换旧证据，而不是与旧结论并列造成冲突？
4. 任务完成、取消或移交后，短程上下文是否按策略可清理、可审计？

思考：可靠的记忆，不是把过去带得更远，而是把当前事实留得更清楚

对认证 Agent 而言，真正有价值的“记住”是已确认的契约、仍然有效的证据和刚刚发生的失败，而不是把每一次聊天、每个文件和每个人的偏好永久保留。

当系统敢于排除无关信息、淘汰过期结论并在任务结束后清理上下文，用户才可以相信它是在当前边界内行动，而不是被过去的噪声推着继续改代码。

这一幕带走：记忆的产品验收 = 来源可展开 + 越权/密钥进不来 + 任务级可清理。

---

Part 08 · 规格：状态与恢复

08 / 状态与恢复

演示可以一路顺风；产品必须回答：中断、换人、失败后怎么续——可暂停、可恢复、可交接。

1. 状态背景：为什么“任务还在跑”不是一个可恢复的状态

认证交付并不会总在一个连续会话中完成：浏览器可能关闭，工具调用可能超时，测试可能把任务停在 S3，也可能在联调时由另一位同事接手。若系统只把进度留在聊天记录或模型上下文中，恢复时它既无法确认上次做到哪里，也无法判断工作区是否已被外部改动。

状态与恢复的产品职责，是把任务从一次对话变成可持久化的工作对象。每次到达 Checkpoint、提交 patch、运行验证或等待人工时，系统都要保存可恢复快照：当前步骤、已确认输出、未完成动作、依据版本、工作树指纹和风险状态。恢复不是继续生成，而是先验证这些事实仍然成立。

恢复前提：系统只能从已确认 Checkpoint 恢复，不能凭“上次大概做到这里”自动猜测。工作树、契约或权限边界发生关键变化时，必须先重新裁定是否仍可续跑。

2. 核心问题：为什么静默续跑比明确中断更危险

中断之后最危险的动作不是停止，而是系统在没有校验环境的情况下接着修改。阿明在暂停期间可能已经手动修过 session；同事也可能更新了测试基线。如果 Agent 仍按照旧上下文继续 patch，就会覆盖新改动、重复执行过时计划，甚至把一个已通过的 Checkpoint 重新变红。

另一个问题是交接信息不足。把“请继续修登出问题”留给接手人，需要他重新翻聊天、猜当前风险、定位上次日志。产品应该生成面向人的恢复 Brief，而不是假设下一位操作者能继承模型的短期记忆。无法证明一致性的任务也不能伪装成可恢复状态。

恢复原则：暂停是保存事实，不是冻结屏幕；恢复是重新核验，不是重新猜测；交接是导出状态对象，不是转发聊天记录；不可恢复是明确结果，不是让自动化继续试错。

3. 事实证据：S3 中断后，系统凭什么允许另一人继续

在 S3“登出后 GET /me = 401”中，系统已经确认 guard-401，并保存了最近的失败证据：登出后探针仍为 200、当前 patch 的 Diff 摘要、相关测试 run-id，以及工作树指纹。用户点击暂停时，任务状态转换为 paused，不再发起新的写操作；恢复或交接时，系统先检查契约版本、权限策略和工作树是否仍与快照兼容。

场景	产品行为	恢复依据与验收演练
中断	暂停 → 状态外置 → 禁止新写操作	关页 10 分钟再开，仍显示 S3、guard-401 与未通过的 200 快照
同人恢复	核验工作树与策略 → 从原 Checkpoint 续跑	无关键差异时仅重做 S3 的下一步，不重复已确认的 S1/S2
换人交接	导出 Brief；接手人确认后续跑	阿明停止，同事凭 Brief 在 S3 继续，不翻聊天记录
不可恢复	停止自动；提示重置、重规划或人工处理	外部大改工作树、契约撤回或权限变化后不得假续跑

交接 Brief 必含：task_id · 契约版本 · 当前步骤 · 已确认 Checkpoint · 最近 Diff 摘要 · 阻塞原因 · run-id / 日志入口 · 工作树指纹 · 禁区提醒 · 下一步可选操作

stateDiagram-v2 [*] --> Running: 计划批准后执行 Running --> Checkpointed: 验证通过并保存 checkpoint Checkpointed --> Running: 解锁下一步骤 Running --> Paused: 用户暂停 / 会话中断 Paused --> VerifyResume: 用户恢复或交接 VerifyResume --> Running: 契约、策略、工作树均兼容 VerifyResume --> Replan: 假设或范围变化 VerifyResume --> WaitingHuman: 工作树冲突或高风险 Running --> WaitingHuman: 需要人工裁定 Replan --> Running: 新计划确认 WaitingHuman --> Running: 人工处理并确认恢复点 WaitingHuman --> [*]: 取消或重置任务

流程图中的 VerifyResume 是恢复的关键闸门。它不检查模型“是否还记得”，而是检查当前工作区、契约和策略能否支持继续执行。只有三者一致，系统才回到 Running；否则进入重规划或等待人工，保留现场证据而不继续写入。

4. 执行结论：恢复需要证据，不能只靠连续性

状态能力的验收不是页面上有“继续”按钮，而是中断后仍能安全地解释和推进任务。产品必须在关键动作后保存状态快照，以 Checkpoint 为恢复边界，以工作树、契约和策略的一致性为恢复条件，以 Brief 为交接载体；一旦这些条件不满足，就停止自动执行并把选择权明确交还给用户。

保存：步骤、Checkpoint、Diff 摘要、run-id、依据/策略版本、工作树指纹；暂停：停止新的工具写入；恢复：核验工作树 + 契约 + 策略；一致则从 Checkpoint 续跑，不一致则重规划或人工；交接：导出 Brief，不依赖聊天；取消：清理运行态但保留审计摘要。

状态与恢复规格自检

1. 关闭页面或工具超时后，任务是否仍能定位到最后一个已确认 Checkpoint？
2. 恢复前是否核验工作树、契约版本和权限策略，而非直接继续执行旧计划？
3. 另一位同事是否能仅凭 Brief 理解当前步骤、阻塞证据、禁区与下一步？
4. 任务不可恢复时，产品是否停止自动写入并清楚提供重置、重规划或人工处理出口？

思考：可恢复不是让系统永远不停，而是让每一次停下都不丢失判断

长任务真正稀缺的不是连续运行时间，而是中断之后仍然能够辨认现场：哪些已经确认、哪些尚未完成、哪些假设已经失效，以及谁可以在什么条件下继续。

当暂停、恢复和交接都依赖同一份可审计状态，Agent 才不再是一次性的对话工具，而成为可以进入真实协作流程的执行对象。

这一幕带走：状态能力的验收 = 可暂停、可恢复、可交接；不可恢复必须诚实告知。

---

Part 09 · 规格：验证与反馈

09 / 验证与反馈

产品不得在证据不足时显示「已完成」。未通过原因必须对用户可见——假完成进不了 UI。

1. 验证背景：为什么“代码写完了”还不能点亮完成

认证 Agent 可以生成 patch、运行命令，甚至给出一段看起来很自信的总结，但这些都不是交付完成的证据。阿明真正需要确认的是：登录是否可用、未登录是否被拒绝、登出后会话是否失效、错误体是否没有泄露路径。只有这些契约中的 Acceptance 被独立证据逐条满足，任务才有资格结束。

验证与反馈的产品职责，是把模型产出与可裁定事实分开。系统接收当前步骤的产物、测试和探针结果，再按确认版契约逐条判定；它展示“哪条已通过、哪条未通过、证据在哪里、下一步可以做什么”，而不让模型的一句“应该修好了”替代裁定。

完成前提：完成状态只能由全部 Acceptance 与对应证据共同产生。没有 run-id、响应快照、测试日志或人工验收记录的结论，最多是待验证，不能成为“已完成”。

2. 核心问题：为什么绿灯、日志和模型自述都可能误导用户

一组单测全绿并不必然覆盖真实会话链路；一次 curl 返回 401 也不一定来自正确的登出流程；模型摘要更可能遗漏未执行的验收项。如果产品把这些碎片化信号直接折叠为“成功”，用户会在联调或上线时才发现登出后 /me 仍然可访问，或者错误响应把内部路径带给了前端。

验证失败也不能一律重试。网络超时属于瞬时问题，session 假设错误需要重规划，缺少现行规范应补上下文，权限冲突或安全风险必须交给人裁定。没有证据分类的“再试一次”，只会让 Agent 在同一错误路径上循环。

裁定原则：每一条结论必须指向一个 Acceptance 和一份可复查证据；每一次失败必须说明它是瞬时、假设、依据还是风险问题。产品提供出口，但不替用户掩盖不确定性。

3. 事实证据：认证任务如何从 S1-S4 汇总为可否决的完成态

认证交付助手在交付审查时，将计划中的步骤证据回连到契约：S1 的登录用例证明凭证路径可用；S2 的未登录探针证明受保护接口返回 401；S3 的登出后探针证明会话已被清理；S4 的错误体快照证明没有服务器路径泄露。任何一项缺失、过期或失败，完成徽章都必须保持关闭。

Acceptance	最小证据	未满足时的用户可见状态
登录可用	S1 测试 run-id + 成功响应摘要	“登录链路未验证”，可查看日志或重试
未登录 /me = 401	S2 无会话探针快照	“鉴权边界未满足”，回到 S2
登出后 /me = 401	S3 登出序列与 401 响应快照	“会话未失效”，回到 S3 并保留 200 证据
错误体不泄露路径	S4 错误响应快照 / 安全断言	“错误体合规未通过”，回到 S4 或人工复核

flowchart TB Contract["确认版契约\nAcceptance A1-A4"] --> Gather["收集步骤证据\nS1-S4 run-id、快照、Diff、人工记录"] Gather --> Match{"每份证据是否\n来源可信、未过期、对应 Acceptance？"} Match -->|否| Missing["未通过：证据不足或无效\n完成徽章保持关闭"] Match -->|是| Judge{"A1-A4 是否全部满足？"} Judge -->|是| Complete["已通过\n展示验收清单与证据链接"] Judge -->|否| Diagnose{"失败类型"} Diagnose --> Retry["瞬时失败\n限次重试"] Diagnose --> Replan["假设错误\n重规划并保留 checkpoint"] Diagnose --> Context["依据不足\n补上下文后再验证"] Diagnose --> Human["高风险或僵局\n生成 Brief，等待人工"] Retry --> Gather Replan --> Gather Context --> Gather Human --> Gather

图中没有从“模型说完成”直接通往交付的箭头。模型可以解释证据、建议回流出口，但完成态只能由验证层写入；回流后重新收集的是新证据，已确认的 Checkpoint 仍被保留，避免每次失败都把整条认证链路重做一遍。

4. 执行结论：把失败分类，把完成锁给证据

验证能力的验收不在于页面展示了更多日志，而在于用户能据此做出正确决策。产品需要将每一条 Acceptance 绑定到最小证据和明确的未通过状态，禁止证据缺失时点亮完成；当失败发生时，根据其性质路由到重试、重规划、补上下文或人工处理，并把结果回写到原步骤和任务状态。

重试

瞬时失败

UI 显示限次重试与剩余次数，不改步骤假设。

重规划

假设错误

展示新步骤图与原因；保留已确认 Checkpoint。

补上下文

证据不足

引导补依据来源；补齐前不开写。

人工

僵局/高危

生成 Brief，停自动执行，状态=waiting_human。

输入：契约 Acceptance + 当前步骤产物 + run-id / 快照；裁定：逐条匹配证据，证据不足即未通过；汇总：A1-A4 全部满足才点亮完成；回流：瞬时失败→重试，假设错误→重规划，依据不足→补上下文，高危/僵局→人工；输出：通过或未通过，均附可展开证据。

验证与反馈规格自检

1. 每一条 Acceptance 是否都有独立、可复查且仍有效的最小证据？
2. 证据缺失、测试未跑或探针环境不匹配时，完成状态是否被产品层禁止？
3. 失败原因是否被分类并路由到恰当出口，而不是默认无限重试？
4. 用户能否直接看到未通过的具体条目、证据入口与下一步，而非只收到模型摘要？

思考：验证的价值，不是替系统宣布正确，而是让错误无法被悄悄带过去

真正可靠的完成感并不来自一个醒目的绿色徽章，而来自任何人都能沿着验收条目回到测试、探针和变更记录，确认这次认证交付确实发生过、也确实符合边界。

当产品让证据决定完成、让失败带着原因回流，Agent 的速度才不会把不确定性更快地推向联调与生产环境。