02 · 吃透 AI Agent：从会说话到能闭环

开篇 · 真实案例：想让 Agent 自己跑完认证？先别急着堆 Prompt

00 / 案例背景

从「人侧交付」走向「Agent 闭环」，缺的不是更长 Prompt，而是让事实、行动、状态与验证真正接入任务系统。

00 / 案例背景：从“人侧交付”到“Agent 闭环”的惊险一跃

在上一篇中，阿明通过契约、证据包、工序、回流四大支柱，成功将 B 端控制台认证修复至可合并状态。但这依然依赖于人的高强度介入。团队很快提出了下一个挑战：能不能搭一个 Agent，让它自己把认证目标跑完？

这个试点的目标不是写一篇新教程，而是构建一个认证交付 Agent：输入是 Spec v1.0，输出必须是可复查的交付证据。正如「LLM Agent 框架原理」图示所强调的：LLM 是智能内核；Agent 是让智能参与真实任务的运行系统。

这个试点的完成定义：

能读取当前分支的认证实现与相关规范，而不是根据记忆猜测。
能在授权范围内修改 session 清理路径，并把变更落进真实工作区。
能运行测试和接口探针，以外部结果判断登出后的 GET /me 是否为 401。
失败时能保留检查点、记录证据并从当前步骤续跑，而不是重新聊天。

01 / 核心问题：把 Spec 丢进对话框，为什么仍不是 Agent？

小周的第一版很诱人——本质是加强版聊天：把 Spec、几段代码说明贴进去，模型洋洋洒洒写出改造方案，甚至贴出「伪测试通过」和「登出后应为 401」的结论段落。演示会上大家觉得「差不多能自己干了」。

一接真实仓库与 CI，原形毕露：模型能解释“应该怎样修”，却没有能力证明“仓库已经修好”。这正是图左侧的断点：Spec 进入模型后，只产出方案与自述，既没有落到真实仓库，也没有进入测试与探针的验证路径。

问题不在于这份方案是否听起来合理，而在于它没有接触交付所依赖的外部世界：它不知道当前分支是否已有未提交改动，不能真正调用测试 runner，也无法在窗口被压缩或任务中断后确认自己推进到了哪一步。对话给出了建议，系统却没有获得可执行的任务状态。

02 / 事实证据：真实仓库与 CI 如何否定“自述”

时间线记录的不是模型文笔，而是图中右侧闭环路径缺了哪些节点。

时间线	发生了什么	暴露的机制缺口
周一上午	Spec v1.0 贴进对话框，十分钟出「完整方案」	只有语言，没有任务状态
周一中午	模型声称「已按 session 清理修好」	不能真改仓库，只会建议
周一下午	本地跑 `auth.session.spec` 仍红；登出后 `/me` 仍 200	不知现网/现行行为，验证靠自述
周一傍晚	多轮聊天后忘了 T02 是否已过、该从哪续	进度只活在上下文窗口里
周二复盘	结论：这不是 Agent，是会写方案的 LLM	缺事实、行动、状态、验证四层

认证交付的两条路径：对话自述 vs Agent 闭环

flowchart LR Spec["认证 Spec v1.0"] subgraph Chat["裸对话：止于语言"] LLM["LLM 生成方案"] --> Claim["自述：已修好"] Claim --> Gap["没有仓库变更、测试证据与任务状态"] end subgraph Agent["Agent 系统：进入真实任务"] State["计划与 Checkpoint"] --> Facts["事实：读代码与探针"] Facts --> Act["行动：受控读改测"] Act --> Verify{"验证：测试 / 探针通过？"} Verify -->|通过| Evidence["保存证据，交付结果"] Verify -->|失败| Recover["记录失败，回流当前步骤"] Recover --> State end Spec --> LLM Spec --> State classDef chat fill:#fef2f2,stroke:#ef4444,color:#7f1d1d classDef system fill:#eff6ff,stroke:#2563eb,color:#1e3a8a classDef success fill:#dcfce7,stroke:#16a34a,color:#14532d classDef failure fill:#fff7ed,stroke:#ea580c,color:#7c2d12 class LLM,Claim,Gap chat class State,Facts,Act,Verify system class Evidence success class Recover failure

图中的分界很明确：裸对话在“自述”处结束；Agent 必须继续进入读事实、做行动、跑验证和保存状态的循环。表中的“不能真改仓库”对应图里的受控修改与测试调用缺失；“不知真实行为”对应读取现行代码与接口状态缺失；“忘了 T02 是否已过”对应计划与 Checkpoint缺失；测试仍红却自称完成，则是绕过了测试 / 探针通过？这个裁定节点。

03 / 执行结论：从“换模型”转向“补机制”

小周没有继续堆 Prompt。他和阿明对齐：上一篇解决的是人怎么用 AI 交付；本篇要解决的是系统缺什么才能闭环——Context 如何治理、Tool 如何契约、计划与状态如何外置、失败如何回证据、Harness / 路由 / 治理如何托底。

这意味着模型不再被要求独自承担“知道事实、执行写入、记住进度、宣布完成”四种职责。它只负责在当前状态和策略约束下判断下一步；其余职责交由受控工具、状态机、验证器和治理规则共同完成。按图实施时，成功路径由验证通过后保存证据并交付结果收束；失败路径则记录失败、回流当前步骤，再从计划对象继续，而不是重新开始一次聊天。

系统改造原则：先让每一次读取、修改、测试和失败都有可追溯记录，再讨论模型是否需要更强的规划、推理或多角色协作。没有这些底座，模型再强也只能把方案写得更像交付。

思考笔记：语言能力不是任务闭环

模型可以给出看似完整的改造方案，却无法仅凭语言知道仓库当前是什么状态、一次写操作是否成功，或测试是否真的通过。把“会解释”误当成“会交付”，正是这类 Agent 试点最容易出现的错位。

要让系统自己跑完认证，必须把事实、行动、状态和验证从聊天窗口外置为可管理的机制。模型负责判断下一步，系统负责让每一步可执行、可恢复、可证明。

带着这个问题进入下一章：裸对话要变成可交付 Agent，首先缺少的四块系统能力分别是什么？

这一幕带走：语言能力不是任务闭环。先把事实、行动、状态和验证外置成可管理机制，再讨论模型是否需要更强的规划与推理。

Part 01 · 四个缺口：裸对话交不出认证

01 / 缺口诊断

小周第一版把 Spec 丢给裸 LLM——缺的不是文笔，是任务闭环的四块砖：事实、行动、状态、验证。缺一块，认证就停在「像那么回事」。

01 / 缺口诊断：为什么“会说话”不等于“能闭环”？

小周的第一版尝试把 Spec 丢给裸 LLM，结果惨败。这缺的不是文笔，而是任务闭环的四块砖：事实、行动、状态、验证。缺一块，认证交付就永远停在「像那么回事」的阶段。

正如「PART 01 · 起点」图示所强调的：Agent 的核心价值，是把语言智能组织成可执行、可验证的任务闭环。LLM ≠ Agent：语言能解决“会理解和表达”，但真实任务还需要感知、行动、状态与反馈。

演示会上，模型把 Spec v1.0 讲得很完整：登出清理思路、测试用例草案、甚至「预期 401」的段落。阿明问一句：仓库里改了吗？CI 绿了吗？——没有。

关键误判：把「生成一段正确说明」当成「完成一次交付」。语言智能能规划与解释；闭环还要读真实系统、改外部世界、记住进度、用外部证据证明完成。

认证任务尤其容易暴露这个差异：它既依赖当前仓库里的 session 实现，也要求真实写入、跨步骤推进和对外接口验证。只要其中一项仍停留在模型自述里，系统就没有资格宣布“认证已交付”。四个缺口不是文风问题，而是系统能力边界。

02 / 事实证据：裸对话缺少哪四块系统能力？

每一层看三样：现场长什么样 · 裸对话只会怎样 · 系统要补什么

这四类能力不是可以互相替代的插件。能读代码却不能执行，仍然无法改变仓库；能运行工具却不保存状态，任务中断后仍会失忆；能执行却不做外部验证，则只是把“自述完成”换成了“自动自述完成”。

缺口 1 · 事实

读不到现行真实状态

现场：不知登出后 GET /me 真实是 200 还是 401；不知 session.ts HEAD 长什么样。

裸对话：用训练记忆与「应该如此」填空。

系统要补：可追溯的实时依据（Context + 探针/读文件）。→ Part 04

缺口 2 · 行动

动不了仓库与 runner

现场：只能「建议改 session 清理」；Diff 不进分支，测试跑不起来。

裸对话：输出伪代码与「请你手动执行」。

系统要补：受控外部操作（Tool 契约：读改测、权限、返回四态）。→ Part 05

缺口 3 · 状态

进度只活在窗口里

现场：多轮后忘了 T02 是否已过、该从 T04 哪点续；刷新对话等于失忆。

裸对话：靠上下文窗口「大概记得」。

系统要补：进度外置、可恢复（计划对象 + Checkpoint + Harness）。→ Part 07 / 10

缺口 4 · 验证

完成靠自述，不是证据

现场：自称「应该 401 了」「伪测试通过」；本地 auth.session.spec 仍红。

裸对话：用更长、更自信的段落代替 runner 结果。

系统要补：外部证据裁定（测试/探针 + Reflection 出口）。→ Part 08

从四个缺口到认证交付闭环

flowchart LR Spec["认证 Spec v1.0"] subgraph Chat["裸 LLM：缺口只会累积"] LLM["生成方案"] --> F["事实缺口"] LLM --> A["行动缺口"] LLM --> S["状态缺口"] LLM --> V["验证缺口"] end subgraph Runtime["Agent 运行时：每项能力都有责任者"] Context["事实：Context + 探针"] --> Plan["状态：Plan + Checkpoint"] Plan --> Tool["行动：受控 Tool 读改测"] Tool --> Verify{"验证：测试 / 探针通过？"} Verify -->|通过| Done["保存证据\n认证可交付"] Verify -->|失败| Recover["记录失败\n回流当前步骤"] Recover --> Plan end Spec --> LLM Spec --> Context F -. "补事实" .-> Context A -. "补行动" .-> Tool S -. "补状态" .-> Plan V -. "补验证" .-> Verify classDef gap fill:#fef2f2,stroke:#ef4444,color:#7f1d1d classDef runtime fill:#eff6ff,stroke:#2563eb,color:#1e3a8a classDef success fill:#dcfce7,stroke:#16a34a,color:#14532d classDef recover fill:#fff7ed,stroke:#ea580c,color:#7c2d12 class LLM,F,A,S,V gap class Context,Plan,Tool,Verify runtime class Done success class Recover recover

图中的四条虚线说明了“补什么”：不是向模型追加更多形容词，而是把缺失能力接入运行时。实线是能够运行的认证交付路径；验证失败回到计划状态，而不是回到一段新的聊天请求。

四缺口对照表：现场、裸对话与系统能力

缺口	现场痛点	裸对话表现	Agent 补什么（系统能力）	对应后文
1. 事实	不知 `/me` 登出后真实是 200 还是 401；不知 `session.ts` HEAD 长什么样。	用训练记忆与「应该如此」填空。	工具调用（Context + 探针 / 读文件）	Part 04
2. 行动	只能建议改 session 清理；Diff 不进分支，测试跑不起来。	输出伪代码与「请你手动执行」。	流程控制（Tool 契约：读改测、权限）	Part 05
3. 状态	多轮后忘了 T02 是否已过、该从 T04 哪点续；刷新对话等于失忆。	靠上下文窗口「大概记得」。	记忆与状态（Plan + Checkpoint + Harness）	Part 07 / 10
4. 验证	自称「应该 401 了」「伪测试通过」；本地 `auth.session.spec` 仍红。	用更长、更自信的段落代替 runner 结果。	验证与治理（测试 / 探针 + Reflection）	Part 08

补充自检：何时不能只用裸 LLM

有一问为「是」，就不能只用裸对话当 Agent：

要读真实系统的现行状态吗？（仓库 HEAD、接口实测、CI 日志）
要跨多步记住进度、失败后从检查点续跑吗？
要拿出可复查证明（测试绿、探针码、审计日志）才能算完成吗？

干货：认证交付三问全是「是」。所以小周第一版失败，不是模型不够强，是把 LLM 误当成了完整 Agent。

03 / 执行结论：先补缺口，再谈模型能力

四缺口诊断的输出，不是“换一个模型试试”，而是明确本轮需要接入哪种系统能力。事实、行动、状态、验证可以同时缺失，但每一项都必须有对应的运行时责任者和可检查产物。

误判	你实际在做的事	典型结果
缺事实，却猛换更强模型	同一片空白换引擎	方案更流畅，`/me` 仍不知真值
缺行动，却加长 Prompt	更细的「请手动改这里」	仍改不了仓库，交付悬空
缺状态，却开更多聊天窗口	多窗口并行「帮忙记」	进度分裂，更难续跑
缺验证，却让模型「再确认一遍」	又一次自述完成	CI 仍红，置信度虚高

与上一篇的分工：01 讲人侧用法（契约/证据/工序/回流）；本篇讲系统侧机制——四缺口是机制地图的入口，下一章先画「认证必须走完的五步环」。

思考笔记：Agent 的能力来自协作分工，而非单次回答

把更多要求塞进 Prompt，只能让模型更努力地描述它想做什么，不能让它获得当前事实、写入权限、持久状态或独立验证。真正的 Agent 不是“更会聊天的模型”，而是模型与上下文、工具、状态机、验证器共同组成的执行系统。

因此，判断一个系统是否接近 Agent，不应先问它能生成多长的计划，而应追问：它能否读取真值、留下受控行动、从检查点恢复，并让外部证据裁定完成？

带着这个判断进入下一章：四个缺口确认之后，认证交付 Agent 的最小闭环应该由哪些步骤组成？

这一幕带走：Agent 的价值，是把语言智能组织成可执行、可验证的任务闭环。四缺口先对上号，再往下补层。

Part 02 · 闭环地图：认证必须走完的五步

02 / 运行地图

Agent 不是一次生成。验证失败必须回流，禁止「感觉做完」收工——闭环的默认失败动作必须画在图上。

01 / 运行地图：为什么先画运行地图，再谈各层机制

四个缺口告诉你「缺什么」。闭环地图告诉你「认证跑起来长什么样」——目标进来，必须能走到可复查的完成，或明确的回流，而不能停在一段漂亮说明上。

小周第一版的形状：目标进 → 模型一次生成方案 → 自称完成。图上没有「观察 / 验证失败 / 回流」。系统没有画失败边，运行时就会用「再生成一次完整答案」冒充闭环。

下面五步是认证交付 Agent 的最小运行地图；后文 Context、Tool、ReAct、Plan、Reflection、Harness 都挂在这条环上。它们不是五个相邻的功能菜单，而是同一任务在同一个 run-id 下持续累积事实、状态与证据的过程。

02 / 核心问题：认证闭环必须走完哪五步？

每一步：要产出什么 · 缺了会断在哪 · 主要靠哪类机制托底

步骤	核心动作	要产出什么	缺了会断在哪	对应机制
1. 目标与上下文	装载 Spec 验收句 + 现行 session / 路由事实	明确的任务边界与事实依据	事实缺口，后文乱猜	依据包
2. 理解与规划	拆成可验证子目标（登录→鉴权→登出→错误体）	可执行的步骤序列	一步到位大 Diff，状态不可恢复	推理核、计划对象
3. 工具行动	读改测，留下 Diff 与日志	真实的外部变更	只有建议，仓库不动	工具契约
4. 观察与验证	单测 + 接口探测；失败则回流	外部证据裁定过 / 不过	验证靠自述，CI 仍红	ReAct、证据裁定
5. 经验沉淀	把登出清理点遗漏写入回归用例 / 规则	系统能力的更新	同一坑下一轮重踩	记忆与学习

关键认识：Agent 不是一次生成，而是“目标—行动—反馈—改进”的持续循环。前一层解决的问题，会自然引出下一层能力；它们共同组成任务闭环。

步骤 1–2

想清楚再动手

契约与现行依据进系统；计划落成可验证子目标。对应后文：依据包、推理核边界、计划对象。

步骤 3–4

动手并证明

工具真改真测；观察结果裁定过/不过。对应后文：工具契约、ReAct 排障、证据裁定。

步骤 5

写回系统资产

失败模式进回归与规则，不进聊天坟墓。对应后文：经验沉淀。

环上全程

可恢复与可治理

Checkpoint、超时重试、权限与人工闸托住整环。对应后文：Harness、路由、治理。

认证交付的五步闭环与四条验证出口

flowchart LR Context["1. 目标与上下文\nSpec + 现行事实"] --> Plan["2. 理解与规划\n可验证子目标"] Plan --> Action["3. 工具行动\n读改测 + 日志"] Action --> Verify{"4. 观察与验证\nAcceptance 通过？"} Verify -->|通过| Learn["5. 经验沉淀\n证据、回归、规则"] Learn --> Done["可复查交付"] Verify -->|缺少事实| Context Verify -->|实现需修复| Action Verify -->|计划假设错误| Plan Verify -->|预算 / 风险触发| Human["人工闸或停止"] classDef flow fill:#eff6ff,stroke:#2563eb,color:#1e3a8a; classDef verify fill:#fffbeb,stroke:#f59e0b,color:#78350f; classDef stop fill:#fef2f2,stroke:#ef4444,color:#7f1d1d; class Context,Plan,Action,Learn,Done flow; class Verify verify; class Human stop;

图中最重要的不是从左到右的主线，而是验证节点发出的四条出口。失败后应该回到缺失能力对应的节点：缺事实补 Context，实现未过回到行动，计划前提错误回到规划，预算或权限越界则交给人工。没有这几条边，系统只是线性生成管道。

03 / 事实证据：T04 登出失效的一轮回流

小周试点里，登出失效修复的典型一圈——验证失败时系统该怎么走

认证一轮（示例）
目标：登出后 /me → 401
行动：patch session 清理 + 跑 auth.session.spec
观察：实测仍 200
验证：失败
回流：补上下文（现行清理路径）或重规划，禁止宣布完成

环上节点	本轮事实	正确系统动作	错误动作（第一版）
目标	验收句：登出后 401	保持目标不变，进入行动	改写成「尽量安全」糊目标
行动	patch + 跑测	留下 Diff、run-id、日志	只输出「建议你改这里」
观察	实测仍 200	写入状态：FAIL + 证据	忽略，或让模型辩解
验证	未满足 Acceptance	触发回流边	自称「应该好了」收工
回流	缺清理路径依据	补 Context 或重规划后再行动	再生成一整篇新方案

04 / 执行结论：闭环必须保留的三条边

画图时必须同时画上的三条边：

验证通过 → 完成 / 沉淀：只有外部证据齐，才允许收工。
验证失败 → 回流：回流目标只能是补上下文、重试、重规划或人工——不是「再写一篇总答案」。
预算/风险触发 → 停或人工闸：超时、越权、高风险写操作，必须有退出，不能无限转圈。

干货：自检一句——若把「验证失败」从架构图上擦掉，系统行为会不会变成「再生成一次」？会，说明你还没有闭环，只有生成管道。

补充对照：一次生成 vs 五步环

维度	一次生成（小周 v0）	五步环（要建成的形状）
流程	目标 → 长文方案 → 自称完成	目标 → 规划 → 行动 → 观察验证 → 沉淀 / 回流
失败处理	失败靠人肉发现	失败是一等公民边，默认回流
进度管理	进度在聊天里	进度在任务状态与 Checkpoint
经验积累	经验留在对话	经验进回归用例与规则

下一章起按环拆开：先钉推理核边界（LLM 只想下一步），再补 Context 与 Tool——没有眼和手，环在「行动 / 观察」处必断。

思考笔记：闭环不是“多跑几轮”，而是每轮都能改变系统状态

反复调用模型不等于闭环。只有当每一轮都新增了可追溯的事实、受控的外部行动、持久的任务状态或可复查的验证证据，系统才真的向交付结果推进。

五步环也因此不是固定的直线：认证失败时，系统必须知道该回到哪个节点、保留哪些已确认产物、由谁决定是否继续。把失败出口画清，才能让 Agent 在不确定中有序运行。

带着这个判断进入下一章：在这条闭环上，LLM 应该承担哪些推理职责，又有哪些事实和裁定绝不能交给它单独决定？

这一幕带走：闭环的默认失败动作必须画在图上；没画，系统就会「再生成一次完整答案」。五步齐，才谈得上 Agent。

Part 03 · 推理内核：LLM 只想下一步，不裁定事实

03 / 推理核

让它输出意图、计划、工具参数；别让它代替测试报告、接口实测和数据库。模型是环上的脑子，不是整套系统。

01 / 推理边界：小周为什么把 LLM 当成了整机

正如「PART 03 · LLM 基础」图示所强调的：LLM 是 Agent 的推理内核，但不是完整系统。它依赖提示词和上下文做概率生成，必须由外部能力补充事实与控制。

第一版对话框里，模型同时扮演了规划师、测试报告和「现网真相」：写出清理方案，又自行宣布「登出后应为 401」「我测过了」。一接 runner，全是自述。

定位错误：把 LLM 放在「完整 Agent」的位置，而不是「推理内核」。内核只负责想清楚下一步；事实查询与写操作必须交给工具和策略，完成裁定必须交给外部证据。

LLM 擅长把目标、已有证据和规则组合成下一步假设，但它并不天然拥有仓库、接口、数据库和 runner 的读取权限，更不能因为自己生成了一句话就让外部世界发生变化。把推理能力放大成事实权与执行权，是系统设计中最危险的角色混淆。

02 / 核心问题：哪些职责可以交给 LLM，哪些必须外置？

维度	LLM 在 Agent 中负责（推理内核）	LLM 的天然边界（绝对禁区）
核心能力	✅ 理解意图 ✅ 抽取信息 ✅ 生成计划 ✅ 选择工具 ✅ 解释结果	❌ 上下文有限 ❌ 知识可能过期 ❌ 输出非确定 ❌ 可能产生幻觉 ❌ 没有持久状态
认证场景示例	解析验收句、拆可验证步骤	「现网已经 401」（未探针）
认证场景示例	根据日志提出假设、填工具参数	「我测过了」（伪测试通过）
认证场景示例	在证据齐备时写交付摘要	「哈希可以换更安全的」（越权改禁区）
认证场景示例	解读失败日志，建议回流类型	用更长段落代替 `run_tests` 结果

内核输出

意图 · 计划 · 参数

例如：假设清理未调用 → 调用 read_file(session.ts) → 再决定是否 patch。

内核禁区

事实 · 写操作 · 完成声明

例如：未探针就宣布 401；未跑测就勾 Acceptance；口头改哈希算法。

边界的判断标准很简单：凡是会改变外部状态、确认外部事实，或决定任务是否完成的动作，都不能由模型文本单独裁定。模型可以提出“应该读取哪个文件”“应该运行哪条测试”，但读取、执行和裁定必须分别留下可追溯的系统记录。

03 / 事实证据：认证任务里为什么必须建立这些边界？

上下文有限——塞整仓会淹掉 session 关键路径；要靠依据包治理，不能靠「模型自己找」。
知识过时——训练数据不知道你们仓库 HEAD；现行实现必须工具读入。
输出非确定——同一失败可能给出不同假设；关键路径要靠检查点与状态机约束，不能靠一次抽卡。
会幻觉——会编造「已调用清理函数」「测试已绿」；凡事实句必须可追溯到工具返回。
无持久状态——对话一截断，进度就没；计划与 Checkpoint 必须外置（后文 Plan / Harness）。

设计自检：

方案里是否出现「以模型陈述代替查询 / 测试结果」？有 → 仍把 LLM 当整机。
完成条件是否依赖模型说「好了」？是 → 验证缺口仍在。
写文件 / 跑命令是否必须经 Tool 且可审计？否 → 行动缺口仍在。

04 / 执行结论：把推理内核放回五步环的正确位置

环上步骤	LLM 该做	LLM 不该单独做
目标与上下文	解析验收句、标出缺口问题	臆造现行 session 行为
理解与规划	拆子目标、标依赖	跳过检查点直接「全做完」
工具行动	选工具、填参数、解释冲突	假装已经 patch / 已跑测
观察与验证	解读日志、建议回流类型	裁定「已满足 Acceptance」
经验沉淀	归纳失败模式文案	不经评估就改生产策略

干货：换更强模型，只增强「想」的质量；不自动补上眼（Context/探针）、手（Tool）、记性（状态）和考官（外部验证）。

LLM 的受控输入、结构化输出与外部裁定

flowchart LR Spec["任务 Spec 与 Acceptance"] --> LLM["LLM 推理内核"] Context["受控 Context\n现行代码、日志、规则"] --> LLM LLM --> Intent["意图、计划、工具参数"] Intent --> Policy["策略与权限层"] Policy --> Tools["受控工具\nread / patch / test / probe"] Tools --> Evidence["工具返回\nDiff、日志、状态码"] Evidence --> Verifier{"外部验证器\n满足 Acceptance？"} Verifier -->|通过| Deliver["保存证据并交付"] Verifier -->|失败| Policy Policy -->|补充已验证事实| Context Evidence --> LLM classDef core fill:#eff6ff,stroke:#2563eb,color:#1e3a8a; classDef control fill:#fffbeb,stroke:#f59e0b,color:#78350f; classDef evidence fill:#f0fdf4,stroke:#22c55e,color:#166534; class Spec,Context,LLM,Intent core; class Policy,Tools,Verifier control; class Evidence,Deliver evidence;

图中 LLM 的输入只能来自任务规格和已经受控的事实，它的输出止步于意图、计划与参数。所有会影响仓库或交付结论的边，都经过策略层、工具和验证器；失败结果带着证据回到策略层和 Context，再为下一次推理提供依据。

补充示例：认证试点中的正确接法

LLM 可以输出

下一步意图与工具建议

任务判断：登出后 /me 仍返回 200，需要排查会话是否真正清理。

任务位置：当前处于「S3 · 登出后应返回 401」这一步。

建议动作：先读取 session.ts，再运行认证测试并探测 /me 的真实返回。

系统必须裁定

事实、验收与下一出口

真实观察：只接受工具实际返回的日志、Diff 与状态码，不采纳模型自述。

完成判断：逐条对照验收条件——登出后是否真的返回 401。

下一出口：由策略选择重试、重规划、补充依据或人工接管；模型不能自行宣布完成。

一句话分工：LLM 负责提出“接下来查什么”；系统负责用真实结果决定“到底发生了什么、下一步允许做什么”。

下一章：推理核要「想得准」，先得吃对依据——依据包如何被系统治理，而不是聊天里随便粘贴。

思考笔记：把 LLM 限在边界内，反而让系统更可靠

限制模型不能自证事实、不能直接写入、不能单独宣布完成，并不是削弱它，而是把它从不擅长承担的职责中解放出来。它可以专注于理解目标、解释证据和提出下一步，而系统可以用确定的接口与规则承担风险。

这也是“模型越强，系统边界越重要”的原因：推理越有说服力，越需要外部证据抵消语言带来的虚假确定性。

带着这个判断进入下一章：既然 LLM 只能基于已验证的事实推理，系统应该如何选择、标注、更新和淘汰进入 Context 的依据？

这一幕带走：模型负责想清楚下一步；事实、写操作与完成裁定交给工具和策略。LLM 是推理内核，不是整机。

Part 04 · 依据包：系统如何治理当前 Context

04 / Context

Context 不是聊天窗口里的粘贴堆，而是带元数据的可控集合——从哪来、约束什么、过期没有、谁可读，答不清就默认不可进高风险路径。

01 / Context 背景：为什么“塞更多”补不了事实缺口

正如「PART 04 · CONTEXT」图示所强调的：高质量上下文应当最小充分、来源清晰、可控且具备时效性。上下文不是越多越好，而是为当前任务提供最有效、最可信的事实。

小周第一版的本能是：把 Spec、半截代码、聊天结论一股脑贴进对话框。模型「看见」很多字，却 anchor 不住 session.ts 的 HEAD 与本轮红测日志——事实缺口还在，只是噪音更大。

与 01 篇的分工：人侧「证据包」讲怎么挑文件给 AI；本篇讲系统如何治理依据——条目要有来源、版本、权限、时效，进入与驱逐都有规则，而不是靠人手每次粘贴。

在 Agent 运行时，Context 应被视为一次任务计算出的受控对象，而不是对话历史的副产品。它要能回答：这一轮 T04 为什么读取这份 session.ts，它对应哪个 commit，能否被执行角色使用，以及任务基线变化后是否仍然有效。

02 / 核心问题：什么样的依据可以进入高风险路径？

登出失效排查轮次；每条都能回答元数据四问

维度	图示定义	认证现场治理标准（元数据四问）
1. 任务上下文	目标、约束、当前文件	验收句「登出后 401」来源：任务契约 v1.0 权限：全角色可读
2. 会话状态	已完成步骤、待确认事项	失败测试日志来源：CI / 本地 runner 版本：本轮 run-id 时效：仅本轮有效
3. 长期记忆	历史任务、偏好、经验	错误体规范来源：仓库文档版本：文档版本号用途：参考而非强制
4. 企业知识	制度、流程、专业资料	`session.ts` 现行实现来源：仓库 HEAD 版本：commit 哈希权限：执行角色可读写限域
5. 权限边界	哪些信息可以访问	生产密钥 / `.env` 状态：永不进入策略：硬拦截

元数据四问（每条必答）：

从哪来？契约 / HEAD / run-id / 文档版本——无来源则不可信。
约束什么？验收、实现、禁区，还是仅参考？
过期没有？commit 是否仍是当前任务基线？日志是否本轮？
谁可读可写？检索只读、执行限域写；密钥类永不进包。

这张表的重点不是文件名，而是“可解释性”：任何进入 T04 写操作路径的条目，都必须能说明它约束哪一个判断。没有来源的聊天结论不能和仓库 HEAD 享有同等地位；没有本轮 run-id 的测试日志也不能证明当前任务已通过。

03 / 事实证据：粘贴堆为何无法成为受控依据包

粘贴堆

小周 v0

整段 Spec + 随意代码片 +「上周有人说 JWT 更好」；无版本、无权限、无驱逐。

受控包

试点要建成的

按任务步骤装载最小集合；每条带来源/版本；越权路径与密钥进不了包。

装载

按步、按风险

T04 装 session + 红测日志；不必把注册表单、前端样式一并塞入。

驱逐

过期与越权出局

旧 run 日志、已废弃分支片段、越权文件——默认踢出高风险路径的上下文。

依据包的准入、使用、回写与失效

flowchart TB Spec["任务契约\nGoal / Acceptance / 禁区"] --> Gate["元数据准入校验\n来源 · 版本 · 权限 · 时效"] Head["仓库 HEAD\nsession.ts / auth 路由"] --> Gate Run["本轮工具结果\nrun-id / 探针 / 日志"] --> Gate Docs["已合并规范\n错误体 / 安全规则"] --> Gate Noise["旧日志 / 闲聊 / 外部教程\n密钥与 .env"] --> Reject["拒绝或降权"] Gate --> Context["T04 受控 Context\n最小充分依据集合"] Context --> LLM["推理内核只读"] Context --> Tools["执行角色按 ACL 使用"] Tools --> Run Baseline["任务基线或权限变化"] --> Invalidate["失效 / 驱逐 / 重新装载"] Invalidate --> Context classDef trusted fill:#eff6ff,stroke:#2563eb,color:#1e3a8a; classDef control fill:#fffbeb,stroke:#f59e0b,color:#78350f; classDef reject fill:#fef2f2,stroke:#ef4444,color:#7f1d1d; class Spec,Head,Run,Docs,Context,LLM,Tools trusted; class Gate,Baseline,Invalidate control; class Noise,Reject reject;

图中的准入门不是一次性过滤器。工具结果会作为本轮新事实重新进入校验；任务基线、权限或版本变化时，旧条目必须失效或重新装载。这样 Context 才能始终反映“当前可用的依据”，而不是累积越来越多的旧对话。

04 / 执行结论：把依据治理写成可执行规则

最小充分——只装本步验收与行动所需；多一条就要能回答「缺了会猜错什么」。
现行优先——HEAD / 本轮 run 优先于聊天记忆与外部博客结论。
禁区硬拦——密钥、.env、生产配置：策略层拒绝进入，不只靠模型「注意」。
变更可追——包内容变化写入任务日志（何时、因何步、增减了哪条）。
答不清则降权——元数据四问答不上的条目，默认不可进入写操作路径。

context_item:
  id: session-impl
  source: repo:HEAD:src/auth/session.ts
  version: commit:abc1234
  purpose: constrain_logout_cleanup
  acl: executor.read_write_limited
  expires: when_task_baseline_moves

never_load: [".env", "**/secrets/**", "prod-config/**"]

这些规则应由运行时执行，而不是写成希望模型遵守的说明。例如策略层检测到文件位于 never_load 时，应在进入模型前拒绝；检测到任务基线已移动时，应让旧的 session-impl 条目失效，并要求重新读取 HEAD。

补充对照：依据包装错会长什么样

错法	认证现场	纠正
整仓当 Context	关键清理函数被淹没	按 Tn 装载最小集合
无版本日志混用	用上轮绿测日志宣称本轮过	绑定本轮 run-id
闲聊结论进包	「JWT 更流行」冲击 session 方案	只收现行事实与已合并规范
密钥进窗口	泄漏进 Diff / 日志	策略永不装载 + 审计

干货：Context 工程的产出不是「更长的提示词」，而是可治理的依据集合。下一章补手：有了依据，还要通过 Tool 契约去读、去改、去测。

思考笔记：Context 的质量取决于可追溯性，不取决于字数

模型可以处理很长的文本，但无法自动判断哪些内容代表当前真相、哪些只是过期意见。高风险任务中，错误地相信一条旧日志或越权信息，往往比缺少一段说明更危险。

把 Context 做成带来源、版本、权限和时效的对象，意味着系统终于可以解释“为什么允许 Agent 基于这条信息行动”，也可以在事实变化后明确撤销这种许可。

带着这个判断进入下一章：当系统已经选出可用依据，Agent 又该通过怎样的工具接口去读取、修改和验证外部世界？

这一幕带走：依据包 = 带元数据的可控集合。答不清来源/版本/权限/时效的，默认不可进高风险路径。

Part 05 · 受控工具：感知与行动的接口契约

05 / Tool

没有工具，Agent 只能建议；有工具却无契约，等于把事故面交给幻觉。双手必须可描述、可授权、可审计、可验证。

01 / Tool 背景：为什么“能执行”不等于“可安全执行”

正如「PART 05 · TOOL CALLING」图示所强调的：Tool Calling 的重点不是“能调用”，而是“可控、可验证、可审计”。工具包含描述、参数、权限和返回结果；调用前必须检查必要性、完整性、授权与可验证性。

小周第一版没有真正的 Tool——模型输出「请在 session 清理函数里……」，人要自己改、自己跑测。接上「能执行」之后若放开无契约的 shell，问题会反转：什么都能动，却不知道谁授权、结果算不算数。

两端都危险：无工具 = 行动缺口（交不出认证）；无契约的全能工具 = 把生产交给概率。本层要的是受控接口，不是更多自由。

工具是 Agent 感知与行动的边界面。它既要让系统读取仓库、执行 patch、运行测试和探测接口，也要把每次行动限制在任务目标、角色权限和路径策略之内。没有这一层，LLM 的计划要么停留在建议，要么变成不可审计的任意执行。

02 / 核心问题：认证 Agent 最少需要哪些受控能力？

感知（读/探）与行动（改/测）成对出现；每条都有明确返回

read_file(path)       → 内容 | 失败
apply_patch(diff)      → 成功 | 冲突 | 拒绝（越权路径）
run_tests(selector)    → 绿/红 + 日志
http_probe(method,url) → status + body摘要

每个工具必须具备：
  描述 · JSON Schema · 权限 · 返回四态
返回四态：成功 / 业务失败 / 异常 / 可重试

维度	图示定义 / 分类	认证现场治理标准（契约要素）
1. 搜索检索	查询事实与知识	`read_file(path)`：描述明确、只读权限、返回内容或报错
2. 数据库 / API	读写业务数据	`http_probe(method, url)`：Schema 必填、返回 Status Code + Body 摘要
3. 文件办公	文档、表格、演示	`apply_patch(diff)`：限域写白名单路径、返回成功 / 冲突 / 拒绝
4. 浏览器系统	操作业务页面	`run_tests(selector)`：返回 Pass / Fail + 日志链接
5. 自动化脚本	执行重复动作	调用前四检：必要性、完整性、授权、可验证性
6. 外部系统	受控连接与返回	返回四态：成功 / 业务失败 / 异常 / 可重试

感知

read_file · http_probe

补事实缺口：读 HEAD 实现、测登出后 /me 真值。返回进入依据包，不进「模型自述」。

行动

apply_patch · run_tests

补行动与验证：限域改 session；用 runner 结果裁定，而不是「我测过了」。

“最小”不代表只有四个函数，而是每一类闭环需要都有唯一、可解释的入口：读文件与探针产生事实，patch 改变限域状态，测试把结果变成证据。把这些能力混成一个无边界的执行入口，会让权限、审计和失败处理全部失去抓手。

03 / 事实证据：工具契约如何约束每次调用？

件套	要写清什么	认证例
描述	做什么、不做什么	`apply_patch` 只改白名单路径，不执行任意 shell
Schema	参数类型与必填	`path` 必填；越界 path 直接拒
权限	谁在何种任务态可调	执行角色可 patch auth；检索角色只读
返回四态	成功/业务失败/异常/可重试	测红 = 业务失败（证据）；runner 崩溃 = 可重试

调用前四检（过不了就不准调）：

必要？本步验收是否真需要这次调用？
参数完整？Schema 校验过了吗？
当前角色授权？任务态与 ACL 允许吗？
结果如何验证？返回将对照哪条 Acceptance / 检查点？

从工具意图到审计、结果与回流的受控链路

flowchart LR LLM["LLM 输出\n工具名 + 参数"] --> Schema{"Schema 完整？"} Schema -->|否| Repair["返回参数错误\n要求重新规划"] Schema -->|是| ACL{"任务态与 ACL 允许？"} ACL -->|否| Reject["拒绝越权\n记录审计"] ACL -->|是| Execute["受控工具执行\nread / patch / test / probe"] Execute --> Audit["调用审计\nrun-id、参数、时间"] Audit --> Status{"返回四态"} Status -->|成功| Evidence["结果进入依据包\n对照 Acceptance"] Status -->|业务失败| Recover["保留红证\n回流当前步骤"] Status -->|异常 / 可重试| Retry["受限重试\n或升级重规划"] Status -->|拒绝| Human["人工闸或修改计划"] classDef core fill:#eff6ff,stroke:#2563eb,color:#1e3a8a; classDef gate fill:#fffbeb,stroke:#f59e0b,color:#78350f; classDef evidence fill:#f0fdf4,stroke:#22c55e,color:#166534; classDef stop fill:#fef2f2,stroke:#ef4444,color:#7f1d1d; class LLM,Execute,Audit core; class Schema,ACL,Status gate; class Evidence,Recover,Retry evidence; class Repair,Reject,Human stop;

图中每一层都在回答一个不能由模型文本代替的问题：参数是否完整、当前是否有权、外部调用实际发生了什么、结果属于哪种状态，以及该由谁处理下一步。只有这些信息写入任务日志，后续的验证、回流和复盘才有可靠输入。

04 / 执行结论：用受控接口替代危险接法

危险接法	后果	受控接法
无 Schema 全能 shell	任意命令、难审计、易越权	白名单工具 + Schema + 路径策略
只返回「成功/失败」一比特	无法归层、无法回流	返回四态 + 日志/摘要
模型声称已调用但未落审计	假行动、真幻觉	每次调用写 task 日志（谁、何时、参数、返回）
patch 无路径禁区	哈希 / `.env` 被改	拒绝越权路径；与依据包 never_load 对齐

干货：给「无 Schema 全能 shell」且无审计，不是赋能，是把生产交给概率。

补充示例：小周试点的一串合法调用

# T04 登出失效 · 受控调用序列（示意）
1) read_file("src/auth/session.ts")
   → 成功：内容入依据包（commit 绑定）
2) http_probe("GET", "/me")  # 登出后
   → 业务失败语义：status=200（相对验收 401）
3) apply_patch(diff_limited_to_session_cleanup)
   → 成功 | 若改到哈希路径 → 拒绝
4) run_tests("auth.session")
   → 绿/红 + 日志（run-id 入包）
5) 系统裁定：对照 Acceptance，决定下一跳
   （禁止：LLM 口头宣布「已修好」）

下一章：有了眼和手，局部不确定时如何边观察边行动——用 ReAct 排「登出仍 200」，但必须有退出条件，且长链路仍要 Plan 托底。

思考笔记：工具的自由度越高，契约越不能缺席

真正危险的不是 Agent 会调用工具，而是系统无法说明它为什么能调用、调用了什么、外部世界发生了什么，以及失败后由谁负责停止。工具契约把这些问题从模型的临场判断变成可执行的系统规则。

因此，工具设计的目标不是给模型一只更大的手，而是让每一次伸手都有范围、权限、记录和可验证的结果。这样，行动能力才能真正缩小交付缺口，而不是扩大事故面。

带着这个判断进入下一章：当根因尚不确定时，Agent 如何在受控工具范围内边观察、边推理、边行动，同时避免无限循环？

这一幕带走：工具契约 = 描述 · Schema · 权限 · 返回四态。写不清，Agent 的双手就会乱抓；无工具，则交不出认证。

Part 06 · ReAct 排障：登出仍 200 怎么查

06 / ReAct

局部不确定时，边观察边行动。ReAct 是探索器，不是整条认证交付的骨架——长链路仍要 Plan 托底，且必须有退出条件。

01 / ReAct 背景：何时应该在步骤内部启动短环

正如「PART 06 · REACT」图示所强调的：ReAct 用“推理—行动—观察”处理不确定问题，但必须严格遵守退出条件。证据已充分、目标已达成、风险触发或超过预算时，循环必须终止或升级。

小周接到 T04：验收要求登出后 /me → 401，实测 200。此时根因不确定（没清 session？探针带旧 Cookie？测错环境？），适合短环：观察 → 推理 → 行动 → 再观察，而不是一次性写完「完整修复方案」。

误用：整条认证（登录→鉴权→登出→错误体→PR）全靠 ReAct 裸转。步数一多，状态漂、预算爆、也没法从检查点恢复。ReAct 嵌在某一步内部；全局对齐交给下一章的计划对象。

启动短环前，系统至少要锁定三个东西：当前计划步骤是 T04、允许使用的工具集合、以及本步不可改变的验收句“登出后 GET /me 必须返回 401”。ReAct 可以探索原因，但不能在探索中偷偷扩大目标或跳过已确认的 Checkpoint。

02 / 核心问题：根因不确定时为什么不能直接给出完整修复？

“登出后仍 200”是一个症状，不是根因。它可能来自 session 清理遗漏、路由没有调用清理函数、测试或探针携带旧 Cookie，甚至是环境指向错误。若模型在没有观察证据前直接选中其中一个原因并修改多个模块，系统就把探索变成了范围失控的猜测。

ReAct 的作用是把大问题缩小为一系列可证伪假设：每次只基于最新工具返回提出一个下一步，执行一次限域调用，再用新的观察结果保留、收窄或推翻假设。这样，失败本身也会变成计划可消费的状态。

03 / 事实证据：T04 的一轮受控排障

观察：auth.session.spec 红；http_probe 登出后实际 200。
推理：会话可能未清理，或探针仍带旧 Cookie。
行动：read_file(session.ts)，定位清理函数与登出调用链。
再观察：登出路径未调用清理——假设被证据收窄。
调整：小 patch（限域）+ run_tests；步数封顶 8，超限升级重规划。

环节	图示定义	认证现场执行标准（T04 示例）
1. 观察	看见当前事实	输入：`auth.session.spec` 红；`http_probe` 返回 200。禁止：臆造「应该 401」或忽略红结果。
2. 推理	判断缺什么信息	提出可证伪假设：会话未清理或探针带旧 Cookie。禁止：同时开十个无关假设乱打。
3. 行动	调用工具获取信息	执行 `read_file(session.ts)` 定位清理函数。禁止：无 Schema shell；修改哈希禁区。
4. 再观察	读取新结果	发现登出路径未调用清理函数，用新证据收窄或推翻假设。
5. 调整	继续、结束或升级	证据充分则进入修复；步数超限则升级重规划。禁止：忽略失败继续「感觉好了」。

这一轮的关键产物不是“模型想到了清理函数”，而是连续的证据链：探针 200、读取到登出路径、定位到未调用清理、限域 patch、测试结果。每一项都带有工具返回和当前步骤标识，因此可以被下一轮、Plan 或人工接手者复用。

04 / 执行结论：退出条件必须写进系统

下列任一成立，结束本段 ReAct：

证据充分——根因已由工具返回钉死，可进入限域修复或交回 Plan。
目标达成——本步检查点转绿（如登出后 401）。
风险触发——要动禁区、生产配置、越权路径 → 人工闸。
预算用尽——步数 / token / 时间封顶 → 升级重规划，禁止空转。

干货：没有退出条件的 ReAct，就是预算粉碎机。小周试点把单步封顶设为 8；超限写入状态：escalate_replan。

T04 短环：仅在低风险且预算允许时继续

flowchart TB Start["Plan 当前步骤：T04\n验收：登出后 /me = 401"] --> Observe["观察\n测试、探针、日志"] Observe --> Reason["推理\n提出一个可证伪假设"] Reason --> Action["受控行动\n读文件或限域 patch"] Action --> NewObs["再观察\n获取新的工具证据"] NewObs --> Decide{"出口判断"} Decide -->|证据充分| Patch["进入限域修复\n或返回 Plan"] Decide -->|检查点转绿| Checkpoint["写入 Checkpoint\n结束短环"] Decide -->|仍有预算且低风险| Reason Decide -->|计划假设失效| Replan["升级重规划"] Decide -->|越权 / 高风险| Human["人工闸"] Decide -->|预算耗尽| Replan classDef flow fill:#eff6ff,stroke:#2563eb,color:#1e3a8a; classDef gate fill:#fffbeb,stroke:#f59e0b,color:#78350f; classDef success fill:#f0fdf4,stroke:#22c55e,color:#166534; classDef stop fill:#fef2f2,stroke:#ef4444,color:#7f1d1d; class Start,Observe,Reason,Action,NewObs flow; class Decide gate; class Patch,Checkpoint success; class Replan,Human stop;

图中的循环边只在“仍有预算且低风险”时成立。它保证 ReAct 能继续收集信息，却不会在根因不明时无限转圈；一旦触发重规划、人工闸或 Checkpoint，短环必须结束并把当前状态交回外层计划。

补充说明：ReAct 与五步环、Plan 的关系

适合

局部不确定

单步内根因不明、需交替读探与小改——如 T04 登出仍 200。

不适合

长交付骨架

用 ReAct 串完 S1–S5；进度只活在推理轨迹里，失败难回滚。

嵌套

步内短环

Plan 的某一步 Execute 时可开短 ReAct；改全局步骤顺序必须显式重规划。

证据

每步可审计

观察与行动都落工具日志；反思章再谈如何对照清单裁定出口。

思考笔记：ReAct 的价值是缩小不确定性，不是替代计划

短环擅长回答“当前这一步为什么失败”，不擅长保存长链路的目标、依赖和恢复点。把它用于整个认证流程，会让每轮探索都可能重写全局方向，最终失去可以复查的任务状态。

正确的关系是外层 Plan 决定要完成什么、当前在哪一步、失败后保留什么；ReAct 只在该步骤内部探索最小的下一次行动，并在达到出口条件时把证据写回外层。

带着这个判断进入下一章：既然认证交付是一条长链路，系统应如何把步骤、依赖、输入、验证和恢复点落成可执行的计划对象？

这一幕带走：ReAct 是局部探索器——边观察边行动，且必须有退出条件。认证全链路仍要计划对象托底。

Part 07 · 计划对象：长任务先落成可执行计划

07 / Plan

运行时计划 ≠ 人的待办清单。它是系统内对象：下一步只能消费已确认输出；失败写入状态机，不擦除 Checkpoint。

01 / Plan 背景：为什么长任务不能只靠 ReAct

正如「PART 07 · PLAN-AND-EXECUTE」图示所强调的：长任务先拆计划，再按步骤执行。计划负责目标分解和依赖排序，执行负责完成动作、记录状态与处理失败。

小周要交付的不是一个单点修复，而是一条认证链路：登录可用、未登录访问受保护接口返回 401、登出后会话失效、错误体符合约定，最后还要留下可复查的交付记录。这些结果存在先后依赖，也各自需要独立的外部证据。

Part 06 的 ReAct 短环适合处理“登出后 /me 为什么仍返回 200”这类局部不确定性；它不负责记住整条链路完成到哪里、哪项证据仍有效、失败后应从何处恢复。长任务因此要先落成计划对象，再在某个步骤内部按需启动短环。

关键区别：人的待办只是备忘；运行时计划是有状态的执行对象，记录依赖、输入、输出、验证、风险与恢复点。下一步只能消费已确认的 Checkpoint，而不是消费“模型说已经做好”的一句话。

02 / 核心问题：待办清单为什么不是运行时计划？

“先登录、再登出、最后写报告”看起来已经拆了步，但它仍无法回答运行时最关键的问题：S3 能否启动？它依赖的 S2 是否真的通过？失败是当前步骤的局部问题，还是需要修改全局依赖？另一个执行者接手时，应从哪里继续？

没有这些约束，长任务会退化为一串随时可被改写的自然语言。S3 失败时，系统可能重新跑一遍登录、覆盖已绿的测试结果，或让两个探索分支同时修改 session 文件。这样的“重来”既浪费成本，也让最终交付无法解释。

计划对象的职责：把任务拆成状态可迁移的节点，把“已经确认的事实”保存为 Checkpoint，并把可做的下一步限制在依赖满足的范围内。

03 / 事实证据：认证计划对象如何保存依赖与 Checkpoint？

认证任务在系统内不是一段 Prompt，而是一份可读取、可更新、可恢复的状态。下表中的每个步骤都声明了可消费的输入与可否决的验证结果；只有验证通过，输出才会成为下游可以使用的 Checkpoint。

任务：auth-delivery

S1 · 登录可用
  输入：任务契约
  输出：Checkpoint(login-ok)
  验证：登录测试通过

S2 · 未登录访问受保护接口
  依赖：S1 已确认
  输出：Checkpoint(guard-401)
  验证：无会话访问 /me → 401

S3 · 登出后会话失效
  依赖：S2 已确认
  输出：Checkpoint(logout-401)
  验证：登出后 /me → 401

S4 · 错误体安全
  依赖：S2、S3 已确认
  输出：Checkpoint(error-body)
  验证：错误体快照测试通过

S5 · 交付报告
  依赖：全部相关 Checkpoint
  输出：可复查的交付摘要

规则：S3 未确认 S2 时不得启动；失败写入状态机，已绿 Checkpoint 不得擦除。

步骤	依赖	验证（可否决）	失败时
S1 登录可用	契约	登录测绿	停在 S1；不进 S2
S2 受保护 401	S1	无会话 `/me`→401	回滚到 S1 Checkpoint
S3 登出 401	S2	登出后 `/me`→401	可嵌 ReAct；超限重规划
S4 错误体	S2\|S3	快照测绿	不擦除 S2/S3 已确认点
S5 报告	全部相关 Checkpoint	交付摘要可复查	缺证则不准宣称完成

补充说明：每个可执行步骤的六要素。输入与输出界定它消费和产生什么；工具限定行动边界；完成条件交给测试或探针裁定；风险标出需要收紧的操作；恢复点让失败能够回到最近的已确认事实。缺少其中任一项，Execute 都不应启动。

输入 · 输出

消费与交付

输入 = 已确认 Checkpoint / 依据包；输出 = 新 Checkpoint 或工件，供下一步消费。

工具 · 完成条件

怎么做、怎么算过

允许哪些 Tool；完成条件必须可外部验证（测绿 / 探针码），不是模型自述。

风险 · 恢复点

炸了回哪

标高风险（改 session）；恢复点 = 上一 Checkpoint，失败不从头聊天重来。

Plan vs Execute

分工

Plan 管全局对齐与依赖；Execute 管状态迁移、工具调用与失败写入。两者缺一，长任务必漂。

认证计划的依赖门槛、步内 ReAct 与显式重规划

flowchart TB S1["S1 登录可用"] --> C1["Checkpoint: login-ok"] C1 --> S2["S2 无会话 /me 返回 401"] S2 --> C2["Checkpoint: guard-401"] C2 --> S3["S3 登出后 /me 返回 401"] C2 --> S4["S4 错误体符合约定"] S3 --> C3["Checkpoint: logout-401"] C3 --> S4 S4 --> C4["Checkpoint: error-body"] C3 --> S5["S5 交付报告"] C4 --> S5 S3 -. "根因不确定" .-> React["受控 ReAct 短环"] React -. "超预算或假设失效" .-> Replan["显式 replan"] Replan --> S3 S5 --> Done["可复查交付"]

04 / 执行结论：全局变化必须显式重规划

计划不是模型一次性写出的静态清单，而是持续记录任务状态的系统对象。执行器只推进依赖已经满足的步骤；ReAct 只在当前步骤内提出假设、调用受控工具并收集证据。两者的边界必须清晰，才能避免局部排障悄悄改写全局任务。

步内 ReAct 可以调整假设和最小 patch，不得偷偷删除或重排全局步骤。
出现新增依赖、步骤顺序变化、恢复点改变或既有假设失效时，必须调用显式 replan：说明原因、保留已确认 Checkpoint，并生成带版本的新计划。
失败必须写入状态机：当前步骤、失败证据、已尝试动作和下一个出口。禁止擦除已绿 Checkpoint 来“假装没发生”。
S3 不得在 S2 未确认时启动；依赖边与人侧工序（01 篇）同构，只是现在由系统对象强制执行。

Plan-and-Execute 自检：

当前步骤的输入是否指向一个已确认的 Checkpoint？
完成条件是否可被 Tool 返回一票否决？
失败后恢复点是否明确？接手者能否不靠聊天续跑？
若要改步骤图，是否走了显式重规划而不是 ReAct 漂移？

下一章：步骤跑完或失败时，如何对照证据清单裁定——重试、重规划、补上下文还是人工。反思不是再生成一遍。

思考笔记：计划对象的价值不是预测未来，而是保护已确认的过去

长任务一定会遇到未知：测试可能暴露新约束，依赖可能变更，局部假设也会被推翻。计划对象不承诺一开始就把未来排得绝对正确；它先把已验证的结果沉淀为不可随意丢失的事实，再让后续变化在可审计的重规划中发生。

因此，好的计划不是步骤越多越好，而是每一步都能回答：我依据什么启动、成功由谁裁定、失败后保留什么、何时需要改变全局路径。

这一幕带走：Plan 管全局对齐；Execute 管状态与失败。下一步只消费已确认输出；改计划必须显式重规划。

Part 08 · 证据裁定：反思不是再生成一遍

08 / Reflection

「我再生成一版」不是反思。反思 = 对照证据清单做裁定：过 / 不过，以及下一出口是重试、重规划、补上下文还是人工。

01 / Reflection 背景：为什么步骤结束后还不能直接宣布完成

正如「PART 08 · REFLECTION」图示所强调的：可靠性来自规则、事实、测试或独立评审，而不是让模型“再想一次”。Reflection 要检查规则、比对事实、接受独立审核，并把失败送往明确出口。

Part 07 已经把认证任务落成了带依赖的计划对象，但一个步骤“执行结束”不等于它“交付完成”。以 S3 为例，模型可以完成 session 清理 patch，也可以写出“登出后应返回 401”的说明；只有测试、接口探针和变更边界都给出可追溯的结果，系统才有资格放行下游步骤。

小周第一版的习惯是让模型在失败后“再想一想 / 再写一版修复”。输出更长、语气更稳，却没有回看 runner、探针和规则引擎的真实返回。它并没有处理失败，只是把验证缺口换成了另一段生成内容。

定义：没有外部依据的“反思”，只是又一次幻觉彩排。真正的 Reflection 是裁定程序：证据清单是否齐全？Acceptance 是否逐条通过？失败应进入哪个出口？这些结论都必须写进状态机。

02 / 核心问题：模型自述为什么不能代替证据裁定？

模型对代码的解释、对测试的预测、甚至“我已经修复”的结论，都是待验证的假设，不是系统事实。反思的对象不是上一段自然语言，而是当前任务状态中可定位的证据：哪个工具在什么版本的工作区运行、得到了什么原始结果、这条结果对应哪一句验收条件。

如果证据缺少来源 ID，后续执行者就无法判断它是否过期；如果任一否决项仍红，Checkpoint 就不能写入；如果失败只留在聊天记录里，重试、补依据和人工交接都会失去依据。因此，Reflection 的首要动作是收证并对照，而非重新生成方案。

裁定边界：LLM 可以解释证据、提出下一步建议；测试 runner、接口探针、Diff 规则和权限策略才负责提供或否决事实。

03 / 事实证据：S3 结束后如何对照验收条件

每条必须可追溯到工具返回或规则引擎结果，不能来自模型自述

针对“登出后 GET /me 返回 401”这一验收句，系统不只看一条测试绿灯。它需要同时确认目标没有漂移、实现测试通过、真实接口行为符合预期，并且本轮改动没有越过哈希、环境配置等禁区。

环节	图示定义	认证现场执行标准（S3 登出验收）
1. 规则校验	是否完成目标？是否遗漏约束？字段是否完整？	契约验收句来源：任务 Spec v1.0 标准：目标仍是「登出后 `/me` → 401」，未漂移。
2. 事实比对	工具结果是否冲突？数据是否可追溯？结论是否有依据？	`auth.session.spec` & `http_probe` 来源：`run_tests` + run-id / probe 标准：用例全绿；实际状态码为 401。
3. 独立审核	评审 Agent、自动化测试、人工复核	Diff 禁区校验来源：路径 / 规则引擎标准：未改哈希、`.env`、越权文件。

清单三问（全「是」才允许宣布本步完成）：

每条证据是否有来源 ID（run-id / commit / probe-id）？
是否存在任一否决项未过？有 → 本步未完成。
模型陈述是否被当成证据？是 → 剔除，补工具调用。

收证、裁定与四出口：Reflection 的状态迁移

flowchart TB Step["S3 执行结束\n登出后 /me 应为 401"] --> Collect["收集本步证据\nrun-id / probe-id / diff 结果"] Collect --> Check{"逐条对照 Acceptance\n证据完整且全数通过？"} Check -->|是| Checkpoint["写入 Checkpoint: logout-401"] Checkpoint --> Next["放行后续步骤\nS4 错误体与 S5 报告"] Check -->|否| Classify{"失败属于哪一类？"} Classify -->|瞬时环境问题| Retry["限次重试\n保留同一计划版本"] Classify -->|步骤假设失效| Replan["显式 replan\n保留已绿 Checkpoint"] Classify -->|缺少事实依据| Enrich["补充 Context\n装载缺失规则或路径"] Classify -->|高风险或僵局| Human["人工闸\n生成交接摘要"] Retry --> Collect Replan --> Step Enrich --> Step

图中的菱形是裁定点，而不是模型“感觉是否完成”的位置。只有所有证据通过时，系统才创建 logout-401 Checkpoint；任一否决项失败，则先归类失败原因，再选择一条受控出口。这样失败会改变后续行动，却不会抹掉 S1、S2 等已经确认的结果。

04 / 执行结论：选择出口，并把决定写回状态

裁定失败并不等于“这次任务失败”。它要做的是把失败转译为下一次可以执行的动作：环境偶发问题重试，步骤前提错误重规划，事实不足补上下文，高风险或持续无进展则交由人工。出口的选择由证据类别决定，不由模型的表达自信决定。

重试

瞬时失败

例如 runner 超时、网络闪断。证据指向环境抖动，不改计划假设，限次重跑同一工具。

重规划

步骤假设错

例如清理策略需换方案。显式 replan，保留已确认 Checkpoint，不擦除 S1/S2 绿点。

补上下文

证据不足

例如缺错误码规范、缺现行清理路径。先 enrich 依据包，再行动——对应开篇的事实缺口。

人工

高风险 / 僵局

要动生产配置、禁区冲突、预算用尽仍无进展。停步并交接手简报，不靠模型硬闯。

出口	何时	认证例	写入状态
重试	瞬时失败	runner 超时	`retry_count++`
重规划	步骤假设错	清理策略需换方案	`replan(reason)`
补上下文	证据不足	缺错误码规范	`enrich_context(items)`
人工	高风险/僵局	要动生产配置	`human_gate`

收证——从本步工具日志与规则校验拉齐证据清单。
对照——逐条对照 Acceptance / 本步 verify；任一条否决 = 未完成。
归类——失败属于瞬时、假设错、证据不足，还是风险/僵局？
选出口——重试 / 重规划 / 补上下文 / 人工；写进状态机，禁止口头「再试试」。
通过则放行——打 Checkpoint，允许下一步消费；摘要可引用证据 ID。

S3 · Reflection 裁定（示意）

证据 1 · 认证测试
  来源：auth.session.spec · run:r7
  结果：FAIL
  期望：401
  实际：200

证据 2 · 登出后接口探针
  请求：GET /me
  来源：probe:p3
  实际状态：200

证据 3 · Diff 禁区校验
  规则：hash_paths_untouched
  结果：通过

裁定：enrich_context 或 replan（不是“再生成一版方案”）
下一步：加载现行 session 清理路径，再以预算 8 重跑 S3 ReAct
禁止：LLM 单独声明任务已完成

补充自检：假反思与真裁定的差别。前者用“再想一版”回避当前的外部结果；后者用证据清单否决或放行，并留下可接手的状态。任何无法写明证据 ID、失败分类和下一出口的结论，都不应称为 Reflection。

假反思	真裁定
「再想一版 / 再生成完整修复」	对照清单 → 选四个出口之一
模型说「应该好了」	probe/test 返回说了算
失败原因留在聊天里	原因码写入状态机，可交接
通过与否含糊	Checkpoint 要么打上，要么明确未完成

干货：Reflection 的质量 = 证据清单的可追溯性 × 出口的可执行性。下一章若要多角色，审核者做的就是这套裁定——先统一状态与交接格式，再分工。

思考笔记：反思的产物不该是一段更长的话，而应是一条可恢复的状态迁移

工程任务里，失败本身并不可怕；不可追溯的失败才会让系统失控。把失败原因、已验证事实、剩余预算和下一出口写进任务状态，下一位执行者才能在同一事实基础上继续，而不是重新猜测前面发生了什么。

所以，Reflection 不是给模型增加“自我评价”回合，而是给系统增加一次基于证据的决策。它决定此刻能否写入 Checkpoint，也决定失败应当如何被限制、被传递和被解决。

这一幕带走：没有外部依据的「反思」，只是又一次幻觉彩排。反思 = 收证 → 对照 → 选出口。

Part 09 · 多角色协议：先统一状态，再分工

09 / 分工机制

多个聊天窗口 ≠ Multi-Agent。没有 Task ID、状态版本、交接 Schema，只是噪声倍增。先统一状态，再谈分工。

01 / Multi-Agent 背景：为什么任务变长后会需要多个角色

正如「PART 09 · MULTI-AGENT」图示所强调的：复杂任务需要专业分工，而非一个万能 Agent。多角色的前提是职责明确、状态统一、交接完整并能追溯责任。

认证交付走到 S3 后，系统既要回看 session 清理路径和错误码规则，又要做限域修改、运行测试和接口探针，还要对照证据清单裁定下一出口。把这些动作交给同一个执行单元并非不可能，但当任务变长、风险上升或需要并行读取时，职责会自然分化为协调、检索、执行和审核。

小周试点中有人建议“一个窗口写登录，一个窗口写登出，一个窗口跑测”。表面上多了人手，实际上每个窗口各带一份 Spec 片段和进度。合并时 session.ts 冲突，两边都说自己测绿，却无法回答哪一份证据对应当前任务状态。

判定：没有共享 Task 状态的多窗口，不是 Multi-Agent，而是并行幻觉。多角色的前提是同一任务对象、同一版本时钟、同一交接格式；分工只是建立在这一共同事实之上的第二步。

02 / 核心问题：为什么分工前必须先解决状态分裂？

多角色真正的风险不在“谁来写代码”，而在多个角色基于不同的任务快照行动。若执行者拿着版本 12 的证据修改 session.ts，协调者已经把计划更新到版本 13，或审核者仍用旧验收句裁定结果，那么每一次交接都会把不一致放大。

因此，系统不能只给角色分配 Prompt，还必须规定共享状态的最小协议：任务身份把计划、Checkpoint 和日志归到同一对象；状态版本拒绝过期交接；交接 Schema 让阻塞点、证据、禁区与下一允许动作成为机器可读字段；同一路径的写锁防止两个执行者制造互相覆盖的事实。

先统一，再并行：可并行的是只读检索、测试观察和相互独立的文件范围；会修改同一任务状态或同一路径的动作，必须经过版本校验和单写者控制。

03 / 事实证据：S3 的一轮协作如何保持同一事实

下面的交接对象不是聊天摘要，而是协调、执行和审核共同读取的状态切片。接收者先校验 task_id 与 state_version，再确认依赖 Checkpoint、证据 ID 和禁止触碰的范围；任何字段不匹配，都应拒绝执行并返回协调角色。

Task ID

同一任务身份

例如 auth-delivery。所有角色读写的计划、Checkpoint、日志都挂在这个 ID 下。

状态版本

同一时钟

计划版本、Checkpoint 集合有版本号；角色交接时校验「我基于的版本是否仍是当前」。

交接 Schema

同一报文

交接必须带：阻塞点、证据 ID、禁区、下一允许动作——不是一段自由聊天。

写锁

同一文件单写者

两个执行同时改 session.ts → 状态必裂。

同一时刻对同一路径只授一个执行写权限。

handoff:
  task_id: auth-delivery
  state_version: 12
  from: executor
  to: reviewer
  checkpoint: guard-401
  evidence: [run:r7, probe:p3]
  block: logout still 200
  forbid: [hash_paths, .env]
  ask: pass | fail+reason_code

角色是运行时职责切分；可以由同一模型的不同提示和权限实现，不必等于四个人

环节	图示定义 / 角色	认证现场执行标准（S3 协作示例）
1. 协调 Agent	拆分与汇总	Task ID: `auth-delivery` 维护计划与状态版本，触发重规划；广播状态，不直接 patch。
2. 检索 Agent	获取资料与事实	Context Package：拉规范与现行代码，组装依据包；只读，不写仓库。
3. 分析 Agent	推理与判断	Logic & Analysis：提出假设、分析证据，产出结论与依据。
4. 执行 Agent	调用系统操作	Diff + run-id：限域 patch + 跑测 / 探针；白名单写，单写者锁。
5. 审核 Agent	检查风险与结果	Pass / Fail + Reason Code：对照证据裁定；只读证据，可打回不可偷改 Diff。

S3 的协作顺序：协调确认当前步为 S3、版本为 12 且 S2 已绿；检索将 session.ts HEAD 和红测日志装入依据包；执行者取得写锁后做限域 patch 并交出 Diff、run-id 和 probe-id；审核者仅凭这些证据裁定；协调者再依据原因码更新状态或创建新计划版本。

同一 Task ID 下的角色协作、写锁与证据裁定

flowchart TB State["共享任务状态\nauth-delivery · version 12\nCheckpoint: guard-401"] --> Coordinator["协调\n确认步骤、依赖与状态版本"] Coordinator --> Research["检索\n装载 session 路径与红测日志"] Research --> Package["依据包\n来源、版本、禁区"] Package --> Analyze["分析\n基于证据提出最小行动"] Analyze --> Lock{"session.ts 写锁\n是否可获取？"} Lock -->|是| Execute["执行\n限域 patch + 测试 + 探针"] Lock -->|否| Wait["等待或改走独立只读任务"] Execute --> Handoff["交接 Schema\nDiff · run-id · probe-id · version 12"] Handoff --> Review{"审核\n证据是否满足 S3 验收？"} Review -->|通过| Commit["写入 Checkpoint: logout-401\n状态版本递增"] Review -->|失败| Decision["原因码\nretry / enrich_context / replan / human_gate"] Decision --> Coordinator Commit --> Next["放行 S4 / S5"]

图中的共享状态是唯一的事实源。执行角色不能绕过写锁直接改文件，审核角色不能凭印象宣布通过，协调角色也不能忽略失败原因直接推进步骤。每次状态迁移都带版本号，因此旧交接一旦到达，就能被拒绝而不是悄悄覆盖新结果。

04 / 执行结论：让权限、交接与冲突处理进入协议

多角色不是增加更多“会思考的人”，而是把不同风险的动作交给边界清晰的职责。协调者维护计划但不直接 patch；检索者能读事实但不写仓库；执行者可以在白名单内写入但必须持锁；审核者能否决交付却不能偷改 Diff。职责和权限分开，才不会让一次协作又退化为不可解释的长对话。

交接前校验版本——接收者只接受与当前 task_id、state_version 一致的交接；不一致则拒绝并重新拉取状态。
同一路径单写者——一个执行者持有 session.ts 写锁期间，其他角色只能读取、等待或转做独立范围的任务。
审核只裁定证据——未得到 401 或缺少证据 ID，就写入失败原因码，不能用“看起来合理”放行。
冲突回到协调——版本过期、锁冲突、验收失败或风险升级，都回到协调角色选择等待、补依据、重规划或人工闸。

开多角色前自检：

是否只有一个 Task ID？
状态版本冲突时，是否拒绝过期交接？
同一文件是否保证单写者？
审核是否只基于证据 ID，而不是「看聊天感觉」？

补充自检：多窗口噪声与真多角色的差别。前者靠人肉同步上下文，后者让共享状态、交接字段和权限策略约束每一次行动。角色数量不是成熟度指标；只要任务状态仍分散在多个对话里，增加角色只会增加冲突面。

多窗口噪声	真多角色
各聊各的 Spec 片段	共享 Task 对象与计划版本
进度靠人肉同步	Checkpoint + 状态机广播
同时改同一文件	写锁 + 路径白名单
「帮我看看合不合理」	审核按证据清单出原因码
失败说不清谁负责	交接 Schema 可审计追责到角色

干货：先统一 Task ID、状态版本、交接 Schema，再谈多角色。下一章 Harness：把状态、Checkpoint、重试与交接落成可恢复的执行框架——单角色或多角色都靠它托底。

思考笔记：多角色的价值不是让任务更热闹，而是让责任边界可验证

当协调、检索、执行和审核各自拥有明确的输入、输出与权限，协作中的每个决定就可以被复查：谁基于哪版状态行动、谁修改了什么范围、谁用哪些证据放行或打回。没有这些边界，所谓分工只是在复制不确定性。

因此，先问“任务状态是否唯一、交接是否可拒绝、写入是否受控”，再问“要不要增加一个角色”。协议成立后，单模型、多模型或人工接手都可以在同一个任务对象上工作。

这一幕带走：多个聊天窗口 ≠ Multi-Agent。先统一状态与交接，再分工；同一文件同一时刻只能一个写者。

Part 10 · 执行框架：Harness 让认证可恢复

10 / Harness

会想、会调工具只够演示。进入工程要有执行控制框架——失败后能否不从头再来、接手者不靠聊天记录续上？不能，就还没有 Harness。

01 / Harness 背景：为什么单次跑通还不算工程交付

正如「PART 10 · HARNESS」图示所强调的：Harness 让 Agent 可运行、可恢复、可审计。它负责状态、重试、检查点、回滚和人机交接；不让 Agent 更聪明，却让复杂任务能稳定完成并被他人接手。

小周补上 Context、Tool、ReAct、Plan、Reflection 之后，单次演示已经可以修好登出。但工程现场不会总在一次连续对话里结束：进程可能被重启，CI 可能在夜间超时，执行者可能换班，或者 S3 的 patch 被证据裁定为有害。若进度只活在窗口里，任何中断都会把任务拉回“重新解释一遍需求”。

Harness 是围住执行过程的控制框架。它不替模型规划认证方案，而是保证任务在执行、验证、失败、回滚和交接之间有明确状态，使下一次行动只能从最近的已确认事实出发。

自检两问：① 失败后能否回到上一 Checkpoint 续跑，而不是重开聊天？② 接手者只凭 handoff 简报能否接着干，而不翻完整对话？有一问为否，Harness 未立住。

02 / 核心问题：中断之后系统凭什么知道该从哪里继续？

“继续处理登出问题”不是一个足够的恢复指令。系统必须知道当前任务是谁、处于什么状态、上一次改了什么、外部观察到了什么、哪一个 Checkpoint 仍然可信，以及下一步被允许做什么。没有这些字段，模型只能重新阅读对话并猜测任务进度，重试也可能在错误的工作区或错误的路径上发生。

恢复的关键不是保留更多聊天记录，而是把运行时状态外置成可读写的对象。它把过去的行动、当前失败和未来允许的出口绑定在同一个 task_id 下，并让恢复、回滚和交接都受状态机约束。

Harness 的边界：Plan 决定全局目标和依赖，Reflection 裁定证据与出口，Harness 负责把这些决定可靠地执行、保存、超时控制和交接出去。

03 / 事实证据：S3 失败时，Harness 保存了哪些可恢复状态？

登出失效步骤上的运行时切片；每字段都应可被系统读写，而不是写在聊天里

当探针观察到“登出后 GET /me 仍为 200”，Harness 不会把失败简化为一句“请再试一次”。它把当前验证状态、可回滚的 guard-401、最近 patch、原始观察与允许出口同时保存，供后续的 Reflection、ReAct 或人工接手使用。

task_id: auth-delivery
state: verifying
checkpoint: guard-401（可回滚）
last_action: apply_patch(session.ts) + run_tests(auth.session)
observation: GET /me after logout = 200 → FAIL
next: retry_test | rollback_to_guard | replan
handoff_brief: 阻塞点、日志路径、禁止动哈希

字段	含义	没有会怎样
`task_id`	任务身份（与多角色共享）	日志与状态对不上号
`state`	当前机态（规划/执行/验证/等待人工…）	不知该调工具还是该裁定
`checkpoint`	可回滚的已确认点	失败只能整任务重来
`last_action` / `observation`	最近行动与外部观察	Reflection 无输入
`next`	允许的下一出口集合	模型自由发挥「再生成」
`handoff_brief`	交接简报	换人靠翻聊天

① 任务状态

外置状态机

规划 / 执行 / 验证 / 回流 / 人工闸 / 完成。状态变迁写日志，不靠对话“我们到哪了”。

② Checkpoint

可回滚点

S2 guard-401 已绿则可回。S3 失败滚回 guard，不擦除 S1/S2。

③ 超时重试

预算与次数

工具调用有超时；瞬时失败限次重试；超限走 replan 或人工，禁止无限转。

④⑤ 回滚 · 交接

幂等与简报

写操作尽量幂等、能回则回；交接带阻塞点、证据路径、禁区——对接 Part 09 Schema。

Harness 状态、Checkpoint、恢复出口与人工交接

flowchart TB Start["从 Checkpoint: guard-401 恢复"] --> Load["载入任务快照\nstate · last_action · observation · next"] Load --> Execute["执行 S3\n限域 patch 或受控 ReAct"] Execute --> Verify{"测试与探针\n登出后 /me = 401？"} Verify -->|通过| Save["保存证据\n写入 Checkpoint: logout-401"] Save --> Done["放行后续步骤或交付"] Verify -->|runner 超时| Retry{"重试预算仍可用？"} Retry -->|是| Execute Retry -->|否| Escalate["记录异常态\nreplan 或 human_gate"] Verify -->|patch 有害或状态脏| Rollback["回滚到 guard-401\n保留失败证据"] Rollback --> Load Verify -->|进程中断或换人| Handoff["持久化 handoff_brief\n由接手者载入同一快照"] Handoff --> Load

图中每条返回边都回到一个可定位的状态，而不是回到新的聊天请求。超时先消耗有限重试预算，patch 有害则回到最近 Checkpoint，中断或换人则加载同一份持久化快照；无论从哪条边恢复，过去的证据都不会被重写。

04 / 执行结论：让恢复、回滚与交接成为受控动作

Harness 的价值不在于保存一份日志，而在于限制失败后的行动集合。运行时只能从 next 指定的出口中选择：瞬时问题可以重试，工作区受损可以回滚，计划前提错误需要重规划，高风险或预算耗尽则进入人工闸。这样，系统不会因为“想继续”就重新生成整套认证方案。

幂等——同一 patch / 同一测试选择器，重复执行不制造第二份混乱状态。
可审计——谁在何时对何路径做了何调用，进 task 日志。
可超时——挂死的 runner 必须被 Harness 杀掉并记异常态。
能回则回——优先回到 Checkpoint；不能回的高危写操作，路由到人工闸（下一章）。

S3 失败时 Harness 允许的 next（示例）：

retry_test——runner 超时类瞬时失败
rollback_to_guard——patch 有害或状态脏了
replan——清理策略假设错误
human_gate——要动生产配置 / 预算用尽

不在集合内的动作（如「再生成完整认证方案」）一律拒绝。

补充自检：演示与工程的分界。能一次跑绿的演示并不需要面对状态丢失、超时、重放或换人；工程系统必须在这些事件发生后仍能交代“现在在哪、依据什么、允许做什么、谁能接手”。

无 Harness（演示）	有 Harness（工程）
进度在聊天窗口	进度在 task 状态 + Checkpoint
失败后重开对话	从 guard-401 续跑或按 next 出口走
换人翻完整记录	handoff_brief 即可接手
工具挂死靠人发现	超时进入异常态并可选降级
写操作不可追溯	每次调用可审计、可限域回滚

干货：Harness 不替代推理，它约束执行。下一章风险路由：不同请求走不同控制强度——简单只读可以轻量，改生产必须人工审批前置。

思考笔记：可恢复的核心不是“永不失败”，而是失败后不丢失事实

认证任务里的失败不可避免：runner 会超时，假设会被推翻，执行者也会中断。Harness 并不试图消灭这些事件，而是让每个事件留下状态、证据和受限的恢复路径，使失败不会把已确认的工作重新变成猜测。

当恢复点、超时预算、写操作与交接格式都成为系统规则，Agent 才能从一次性演示迈向可长期运行的工程能力。

这一幕带走：Harness 五件套 = 任务状态 · Checkpoint · 超时重试 · 幂等回滚 · 日志交接。可恢复，才算进入工程。

Part 11 · 风险路由：别让所有请求走同一条路

11 / 路由

风险决定控制强度。策略表可配置，别靠模型「感觉该不该自动干」。路由必须前置——出了事再补审批，是事故流程，不是架构。

01 / Dynamic Routing 背景：为什么不同请求不能共用一条执行路径

正如「PART 11 · DYNAMIC ROUTING」图示所强调的：不同任务，应选择不同的模型、工具和控制路径。复杂度、风险、时效、敏感度与成本共同决定 Agent 如何运行。

认证系统里，“解释某个错误码”“分析会话泄漏”“查看带用户标识的日志”“修改生产会话配置”“合并主干”都可能来自同一个对话入口，但它们的风险、所需证据和允许工具完全不同。若全部走同一条自动管道，要么为了安全把简单只读请求也卡住，要么为了效率把高危写操作一并放行。

Part 10 的 Harness 负责让执行可恢复；风险路由负责在执行开始前决定这条请求需要多强的控制。它把模型、上下文、工具权限、预算和人工闸按风险组合成不同路径，而不是把所有判断交给模型的临场感觉。

错误默认：让模型自己判断“这次要不要人工审批”。风险档位与路径必须是可配置策略表，在调用工具之前就定好，而不是生成到一半再“感觉”一下。

02 / 核心问题：为什么模型不能自行决定控制强度？

模型擅长根据当前上下文提出行动建议，却不是权限和风险的最终裁判。它可能低估生产配置的影响，也可能在工具失败时为了完成任务而跳过验证。若风险判断发生在工具调用之后，审批、隔离、脱敏和预算限制就已失去意义。

因此，路由输入应由可检查的意图、资源和动作标签构成，例如“是否写入”“是否生产环境”“是否包含敏感标识”“是否触碰主干”。策略表据此返回固定的控制组合：可用工具、上下文隔离方式、模型档位、预算、是否需要人工批准，以及失败时的降级出口。

路由边界：模型可以协助补充分类信息，但只能在策略表允许的路径内行动；它无权把高危请求自行降级为“简单自动”。

03 / 事实证据：认证请求如何映射到不同控制路径

下面的路径表说明，风险路由不是给请求贴一个抽象标签，而是直接改变运行时配置。相同的认证领域任务，因资源和动作不同，会得到不同的工具集合、证据要求和人工介入位置。

路径	配置要点	认证例	控制强度
简单	轻量模型 + 只读工具	解释一个错误码	低：可全自动
复杂	强推理 + 多资料依据包	会话泄漏根因分析	中：自动但预算更紧
敏感	隔离上下文、脱敏	含用户标识的策略问答	中高：禁外泄、限工具
高危	人工审批 + 受控执行	改生产配置 / 合主干	高：先批后跑
降级	工具不可用转人工	CI 挂了人工跑测	强制：保交付不断

简单 / 复杂

自动可走通

只读解释、根因分析：可自动；复杂路径加强依据包与步数预算，仍可不经人工闸。

敏感

隔离再回答

用户标识、会话 cookie 片段：进隔离上下文，禁止写入共享日志明文，工具白名单收窄。

高危

先批后跑

合主干、改生产配置、动权限：Harness 停在 human_gate，审批通过才放开对应 Tool。

降级

工具挂了不装死

CI / runner 不可用：路由到人工跑测或只读说明路径，而不是假装测绿。

路由前置：五种路径在工具调用前进入不同控制门

flowchart TB Request["认证请求进入\n意图 + 资源 + 动作标签"] --> Classify{"策略表分类\n是否写入、生产、敏感、主干？"} Classify -->|只读低风险| Simple["简单路径\n轻量模型 + 只读工具"] Classify -->|复杂分析| Complex["复杂路径\n强推理 + 依据包 + 紧预算"] Classify -->|含敏感标识| Sensitive["敏感路径\n隔离 Context + 脱敏 + 窄 ACL"] Classify -->|生产写入或合主干| HighRisk["高危路径\nhuman_gate 在工具之前"] Simple --> Harness["带路径配置进入 Harness"] Complex --> Harness Sensitive --> Harness HighRisk --> Approval{"人工批准？"} Approval -->|通过| Harness Approval -->|拒绝| Stop["拒绝或转人工说明"] Harness --> Monitor{"运行中发现风险升级\n或工具不可用？"} Monitor -->|风险升级| HighRisk Monitor -->|工具不可用| Degrade["降级路径\n人工跑测或只读说明"] Monitor -->|无异常| Done["受控完成与证据归档"]

图中人工闸出现在高危工具调用之前，而不是执行到一半才补审批。运行中如果发现请求触及禁区，只能向上升级到更严格路径；如果 CI 或 runner 不可用，则进入降级出口，由人工补齐验证，而不是让模型宣布“应该测过”。

04 / 执行结论：策略前置，运行中只升级不私自降级

风险路由应在第一次工具调用前完成。Harness 读取的不是自由文本任务，而是已经带有路径标签和控制配置的任务状态；因此高危步骤的 next 中不会出现“直接修改生产配置”，敏感任务也不会把原始标识写入普通日志。

入站分类——按意图/资源/动作标签打档（简单·复杂·敏感·高危），规则优先于模型自评。
选路径配置——模型档位、工具 ACL、是否人工闸、预算上限从策略表取出。
再进 Harness——带着路径标签跑状态机；高危步的 next 不含“直接 apply_patch 生产”。
运行中可升级不可私自降级——发现要动禁区/合主干，只允许升到高危+人工；禁止执行角色自行降到“简单自动”。

route_table (示意):
  explain_error_code     → simple   (readonly, light_model)
  rootcause_session_leak → complex  (strong_model, enrich_context)
  qa_with_user_id        → sensitive(isolated_ctx, redact)
  merge_main | prod_cfg  → highrisk (human_gate_before_tools)
  ci_unavailable         → degrade  (human_test | readonly_explain)

# 入站：改生产会话时长
classify: highrisk
gate: human_approve
after_approve: allow apply_patch(prod-config) within window
deny_if: model_says "我自己看着办"

路由自检：

高危动作是否在调工具前就进入人工闸？
路径是否来自策略表，而非模型临场发挥？
降级路径是否避免“工具失败却宣称完成”？
敏感数据是否与普通任务上下文隔离？

补充对照：一条路与分路径的差别。统一路径要么把解释错误码也送人工审批，要么让合主干与只读问答同权；风险路由则让低风险请求保持轻量，同时把高危、敏感和工具失效路径放进明确的控制机制。

一条路走到底	风险路由
解释错误码也要人工批	简单路径全自动，体验与成本合理
合主干与只读问答同权	高危先批后跑，事故面可控
CI 挂了仍让模型“宣布测过”	降级转人工，验证不撒谎
出了事再补审批	路由前置，审批在架构里

干货：路由前置。出了事再补审批，是事故流程，不是架构。下一章：路径跑通后，把翻车经验沉淀成可回归资产——但演进必须受评估与权限约束。

思考笔记：风险路由的目标不是阻止自动化，而是让自动化停在正确的边界内

真正可用的 Agent 既不能把所有请求拖进人工流程，也不能把所有写操作伪装成低风险。路由的价值是把控制强度与实际影响匹配：低风险路径保持快，高风险路径在出手前被验证、被批准、被审计。

当路径来自策略表而非模型自评，系统才能在能力增强时保持边界稳定。下一步要演进的也不应是“放宽默认权限”，而是把每次翻车沉淀为更可靠的测试、规则和评估资产。

这一幕带走：风险决定控制强度。策略表路由前置；模型不负责临场发明该不该自动干。

Part 12 · 受控演进：把翻车写成资产

12 / Evolution

经验可以沉淀；无评估、无权限的自动改策略，不行。把翻车写成可执行资产，系统才会越跑越稳——否则「自进化」就是自毁开关。

01 / Self-Evolution 背景：为什么修好的经验不能只留在聊天里

正如「PART 12 · SELF-EVOLUTION」图示所强调的：Agent 可以持续优化，但必须在受控边界内演进。正确方式是“评估后更新”，而不是无边界自我修改。

小周修好“登出后 /me 仍返回 200”之后，如果结论只是“下次记得清 session”，下一周相似任务仍会踩同一个坑。经验沉淀是闭环的最后一步：把一次翻车转化为能被后续任务自动消费的回归用例、规则和评估集。

这不意味着 Agent 可以自行修改生产默认值、权限规则或路由策略。真正的演进先产出候选资产，再经过评估、审批、版本发布和可撤回控制；它让系统学会更早发现同类问题，而不是让系统获得无人看守的写权限。

时间	若只留在聊天	写成资产之后
本周 T04 翻车	「下次记得清 session」	抽出失败模式 + 提案用例/规则
合入前	无人复查是否还记得	过评估门槛 + 人工发布
下周同类任务	再踩同一坑	CI / ACL 自动拦住
规则误伤	不知道改过什么	回滚到上一资产版本

假演进：Agent 无人审计地改了「生产默认会话时长」或路由策略。那不叫进化，叫失控写操作——应走高危路径 + 治理，而不是 Evolution 旁路。

02 / 核心问题：为什么“记住教训”不是受控演进？

自然语言备忘无法被 CI、工具 ACL 或发布门禁执行，也没有来源、版本和回滚点。它既不能阻止同类改动再次破坏 session 清理，也无法说明一条新规则是谁在什么失败现场提出、验证过哪些反例，或误伤时如何恢复。

受控演进要求每条经验具备工程形态：能被自动运行的回归用例，能在工具调用前执行的规则，能在策略变更前裁定效果的评估集。候选资产必须保留与原任务证据的关联，默认处于 draft，而不是直接成为全局默认行为。

演进边界：Evolution 负责从失败中提案、验证和版本化；Governance 负责决定谁能发布、哪些资产触及高危范围，以及出了问题如何追责和撤回。

03 / 事实证据：一次认证翻车如何落成三类可执行资产

资产 = 可执行、可版本化、可回滚；不是自然语言备忘

S3 的失败证据表明 logout 路径没有调用清理逻辑。系统不应只保存这个根因描述，而应同时提出三类资产：用回归用例守住“登出后 /me 必须为 401”，用 ACL 规则限制无关哈希路径，用评估集检查错误体泄露与会话清理等策略变更的副作用。

回归用例

可自动复查

登出后 /me 必须 401；错误体不得含绝对路径。进 CI，下次改动自动挡。

规则

默认禁区

auth 任务默认禁止改哈希相关文件；写进 Tool ACL / 路由表，不只写在备忘录。

评估集

改策略前先测

错误体泄密、会话清理遗漏等用例集；策略或提示变更必须过评估门槛。

不沉淀

聊天里的「教训」

「下次注意清 session」只留在对话 → 换人、换会话即丢失。

资产类型	落点	谁消费	失败时
回归用例	测试库 / CI	Execute + 审核	红则不准宣称完成
规则 / ACL	Tool 权限与路由表	Harness 调工具前	越权直接拒绝
评估集	演进发布门禁	Evolution 流水线	未达标不准 publish

受控演进：从失败证据到版本化资产与可回滚发布

flowchart TB Failure["S3 失败证据\n登出后 /me = 200"] --> Archive["归档失败模式\nsymptom · root cause · task-id · evidence"] Archive --> Proposal["生成 draft 提案\n候选资产带来源"] Proposal --> Tests["回归用例\nlogout_me_must_401"] Proposal --> Rule["规则 / ACL\nauth_forbid_hash_paths"] Proposal --> Eval["评估项\nerror_body_no_abspath"] Tests --> Gate{"评估门槛\n回归与反例全通过？"} Rule --> Gate Eval --> Gate Gate -->|否| Revise["修订或拒绝提案\n保留评估记录"] Revise --> Proposal Gate -->|是| Approval{"发布审批\n是否允许进入默认策略？"} Approval -->|通过| Publish["版本化发布\nruleset v3 / test suite v2"] Approval -->|拒绝| Draft["保留 draft\n不改变生产行为"] Publish --> Monitor["运行监测\n误伤或漏拦？"] Monitor -->|是| Rollback["回滚上一资产版本"] Monitor -->|否| Reuse["后续任务自动消费资产"]

图中从失败到发布并不是一条直通线。提案先被拆成可验证资产，评估失败时退回 draft，审批拒绝时不改变默认策略；即使发布成功，也要保留版本和监测出口，确保误杀或漏拦可以退回上一版。

04 / 执行结论：演进必须经过评估、权限发布与可回滚

受控演进的输出不是“模型变得更聪明”，而是一组经过验证、授权且可撤回的工程资产。每次新资产进入默认路径前，都必须证明它能挡住原始失败而不过度误伤；发布本身属于高风险变更，应交给 Part 11 的高危路由和 Part 13 的治理机制。

留证归档——从 Harness 日志抽出失败模式（症状、根因、出口、task-id）。
提案资产——生成候选回归用例 / 规则 / 评估项，标注来源，状态为 draft。
评估门槛——在评估集上跑；未达门槛不准合入默认策略。
权限发布——合入规则表 / ACL / 用例库走审批（对接高危路由）。
可回滚——资产版本化；新规则误杀或漏拦，能退回上一版。

# 受控演进提案（示意）
proposal_id: evo-auth-logout-401
from_task: auth-delivery#r7
symptom: logout /me → 200
root_cause: cleanup not called on logout path
assets:
  - type: regression_test
    name: logout_me_must_401
  - type: rule
    name: auth_forbid_hash_paths
  - type: eval_case
    name: error_body_no_abspath
gate:
  eval_suite: auth-smoke
  min_pass_rate: 1.0
  approver: human
publish: ruleset@v3
rollback: ruleset@v2
forbid: auto_edit_prod_session_ttl

补充对照：真沉淀与假自进化的差别。前者把失败变成可运行、可审计、可回滚的资产；后者把“下次注意”留在聊天里，或让执行角色绕过评估与权限直接改变默认策略。

真沉淀（资产）	假自进化（失控）
回归用例进 CI	只在聊天里说「下次记得」
规则进 ACL / 路由表，可审计	模型临场「优化」生产默认值
评估集挡策略变更	无评估、夜里自动改提示/策略
版本化 + 可回滚	改完无法退回，事故面扩大
发布经权限与人工闸	执行角色绕过高危路由

演进自检（发布前全过）：

是否落成可执行资产（用例/规则/评估），而非自然语言备忘？
合入前是否过评估门槛？
失败能否回滚到上一资产版本？
是否有人/角色对发布负责并可被审计追到？

与下一章的衔接：沉淀补的是五步环最后一环，但不取代治理。权限、审计和人工闸决定谁能发布资产、谁能改高危配置；Evolution 只提案与版本化，Governance 管放行与追责。

思考笔记：系统真正“学会”的不是一句经验，而是一条可被否决的规则

一次失败只有被写成测试、规则或评估项，并经过反例验证，才会在未来的任务中稳定发挥作用。否则它仍只是某次对话里的记忆，既无法被自动执行，也无法在错误时被精确撤回。

演进越靠近默认策略和生产行为，越需要更严格的证据、审批与版本控制。让系统积累资产，不等于让系统自由改变自己。

这一幕带走：受控演进 = 留证 → 提案资产 → 评估门槛 → 权限发布 → 可回滚。无评估无权限的「自进化」，就是自毁开关。

Part 13 · 运行治理：权限、审计与人工闸

13 / Governance

能力越强，边界越要硬。治理不是附录，是闭环的一部分——越权操作若追不到「谁、何时、凭什么」，就还没治理。

01 / Governance 背景：为什么机制齐了仍可能越界

正如「PART 13 · 治理与安全」图示所强调的：治理决定 Agent 能否被企业放心使用。权限、审批、审计、数据边界和回滚机制，必须从设计阶段进入任务流程。

Context、Tool、Harness、路由能让认证 Agent 跑起来，也能让任务在失败时恢复；但它们不能自动回答“谁有权修改哈希”“谁能合并主干”“越权时谁来拦截”“事后能否证明这次行动的授权依据”。只要执行角色仍能静默修改禁区文件，前面的边界声明就只是文案。

运行治理把权限、审计、人工闸和撤回能力放进每一次行动的路径中。它不在任务结束后附加一份合规报告，而是在工具调用前限制动作、在调用时记录事实、在高危节点要求人类批准，并在错误发生后提供可追溯的恢复点。

治理自检一句：越权操作能否追到「谁、何时、凭什么授权」？不能，就还没治理——只有演示级能力栈。

02 / 核心问题：为什么 Prompt 里的禁区不能构成权限控制？

“不要改 .env 和密码哈希”写进 Prompt，只能影响模型的建议，不能阻止一次拥有全仓写权限的工具调用。模型可能误解路径，也可能在排障时为了让测试通过而扩大修改范围；一旦操作已发生，事后提醒无法把泄露的密钥或错误合并收回来。

因此，治理必须把约束变成系统可执行的规则：角色、路径和动作共同决定 ACL；每次调用被记录到不可篡改的审计事件；合主干、外发、权限变更和生产配置等高危动作在工具前停在人工闸；越权或有害变更则回到 Checkpoint 或上一资产版本。

治理边界：模型可以提出请求，不能自授权限；审核可以裁定证据，不能绕过 ACL；人工批准只放开明确的动作范围和有效时间，不授予无限制权限。

03 / 事实证据：认证合 PR 前，治理如何拦截并留下轨迹

认证交付进入合并阶段时，治理不依赖“大家都记得禁区”。执行者提交的 Diff、测试和探针证据先经过路径与 Schema 审计；审核者再用 Part 08 的证据清单裁定；若请求合主干，系统还必须验证人工闸已经批准。每一步都附着同一个 task_id 与证据 ID。

最小权限执行角色只能碰 auth 路径

操作审计每次 patch/测试可追

人工闸合主干、外发、权限变更

可撤回回到 Checkpoint

最小权限

角色 × 路径 × 动作

检索只读；执行限域写 auth；协调可改计划不可偷写业务文件；审核只读证据。哈希 / .env / 生产配置默认拒绝。

操作审计

每次调用可追

谁（角色/身份）、何时、调了何工具、参数摘要、返回四态、所属 task-id——进不可篡改日志。

人工闸

高危先批后跑

合主干、外发、权限变更、改生产配置：Harness 停在 human_gate，审批通过才放开对应 Tool（对接路由高危路径）。

可撤回

回到 Checkpoint

越权或有害 patch 被审计打回后，状态滚回上一 Checkpoint；资产发布可退版本（Part 12）。

执行交出 Diff + 测试/探针证据 ID；写锁范围内仅 auth 路径。
审计自动扫描：是否触及哈希禁区、是否缺少 run-id、是否绕过 Schema。
审核对照证据清单裁定（Part 08）；未 401 / 缺证 → 打回，原因码入库。
人工闸（若合主干）：人批通过后，才允许 merge 类工具；拒绝则保持分支隔离。
可撤回：已合并前发现问题 → 回 Checkpoint；规则误发 → 回滚 ruleset 版本。

# 审计打回示例（越权改哈希）
audit_event:
  task_id: auth-delivery
  actor: role:executor
  tool: apply_patch
  target: src/crypto/password_hash.ts
  decision: DENY
  reason_code: FORBIDDEN_PATH
  policy: auth_forbid_hash_paths@v3
  next: rollback_to_checkpoint(guard-401)
# 合主干
merge_main:
  requires: human_gate.approved
  evidence: [run:r9 green, probe:p5 401, audit:clean]
  else: block

治理前置：ACL、审计、人工闸与回滚不可绕过

flowchart TB Request["执行请求\napply_patch 或 merge_main"] --> ACL{"角色 × 路径 × 动作\nACL 是否允许？"} ACL -->|否| Deny["拒绝调用\n写入审计事件与原因码"] Deny --> Recover["回到 Checkpoint\n或转人工处理"] ACL -->|是| Scope{"是否在白名单范围\n且符合 Schema？"} Scope -->|否| Deny Scope -->|是| Execute["受控执行\n记录 actor · task-id · 参数摘要"] Execute --> Audit["审计扫描\n禁区、run-id、证据完整性"] Audit -->|不通过| Recover Audit -->|通过| Verify{"证据裁定\ntest / probe / diff 全通过？"} Verify -->|否| Recover Verify -->|是且非高危| Checkpoint["写入 Checkpoint\n允许后续步骤"] Verify -->|是且高危| Gate{"人工闸批准\n范围与时效仍有效？"} Gate -->|否| Block["保持分支隔离\n记录拒绝原因"] Gate -->|是| Merge["执行 merge / 发布\n审计归档"]

图中最重要的是两个“拒绝”位置：ACL 在写操作发生前阻止越权路径，人工闸在合主干或生产动作发生前阻止未经批准的高危变更。审计和证据裁定则确保“被允许执行”不等于“已验证可交付”。

04 / 执行结论：让最小权限、审计、人工闸与撤回不可绕过

治理是否成立，不取决于 Prompt 写得多严，而取决于系统是否能在关键节点拒绝行动并留下证据。执行角色应只有完成当前认证步骤所需的最小权限；每次工具调用都能关联到身份、授权、任务、参数摘要和结果；高危动作必须在调用前通过人工闸；任何打回或事故都必须有明确的恢复出口。

无治理	有治理
禁区只写在 Prompt 里	ACL + 策略在调工具前强制执行
改了什么靠聊天回忆	每次调用可审计追责
合主干与修 session 同权自动	高危人工闸前置
越权后无法回滚	Checkpoint / 资产版本可撤回
演进随便改默认策略	发布经权限与评估（Part 12）

治理四问（全「是」才算立住）：

执行角色是否物理上调不了禁区路径（而不只是「被提醒别调」）？
任意一次 patch/测试能否追到谁、何时、凭什么？
合主干 / 改生产是否必须经过人工闸？
打回或事故后能否回到 Checkpoint / 上一资产版本？

补充位置：治理横切整个闭环。路由决定是否进入高危路径，Harness 负责停与放，审计记录每次 Tool，审核根据证据裁定，演进发布也通过同一套权限。缺治理时，高危位置断开的不是“智能”，而是安全边界。

干货：能力越强，边界越要硬。治理不是上线后补的合规附件，而是认证 Agent 能持续跑的前提。

思考笔记：真正的治理不是多一道确认框，而是让越权动作根本无法发生

人工审批、审计日志和回滚机制都很重要，但它们不能替代工具层的硬限制。一个没有 ACL 的“请勿修改”提示，最终仍把安全寄托在模型是否听话；一个没有证据关联的审批，也无法解释批准了什么、为何批准。

当权限范围、审计事件、人工闸和恢复点共同生效时，系统才既能自动完成低风险工作，也能在高风险行动前可靠地停下来。

这一幕带走：最小权限 · 操作审计 · 人工闸 · 可撤回。追不到「谁、何时、凭什么」，就还没治理。

Part 14 · 架构整合：九项能力共同组成一个可持续运行的 Agent 系统

14 / 整合

各层都有了，才叫系统。缺一层，闭环在对应位置断开。机制地图 + 失败→缺层对照，是以后分诊 Agent 故障的两张底图。

01 / Architecture Integration：从方案生成器到能持续跑的认证 Agent

正如「PART 14 · 架构整合」图示所强调的：企业级 Agent 不是一个 Prompt，而是一套连接目标、能力、工具和治理的运行系统。控制平面贯穿所有节点，状态、权限、审计、人工升级与结果评估贯穿全程。

小周的第一版只是对话框里的“方案生成器”：它能解释认证该怎么改，却不知道仓库当前的真相、无法受控写入、不会保存任务进度，也不能用外部证据证明登出是否真正失效。本篇逐层补齐的目的，不是堆出一串 Agent 名词，而是让认证任务在真实工程环境中完整走完。

拼装后的系统应能装载 Spec 与现行依据，按计划推进，调用受控工具读改测，以证据裁定步骤结果，在失败时从 Checkpoint 回流或重规划，在高危操作前停止等待人工，并在进程中断或人员切换后从持久化状态继续。

拼装不是堆名词：每层都必须挂在同一条任务链路上。用手指描一遍“验证失败回流”，若无法指出它回到哪个状态、补哪类能力、由谁裁定，系统就还没有闭环。

02 / 核心问题：为什么组件齐全仍可能拼不成系统？

拥有 LLM、检索、工具、工作流和审计日志，不代表它们天然组成 Agent。若工具不消费计划状态、验证结果不写入 Checkpoint、风险路由在高危调用之后才执行，或失败经验无法回到测试与规则中，系统仍是一组彼此脱节的能力，最终会在某个边界重新退化为“再生成一版”。

系统拼装要解决的是职责和状态的连通性：Context 提供当前事实，Plan 限定下一步，Routing 和 Governance 决定能否行动，Tool 产生外部观察，Reflection 基于证据裁定，Harness 保存状态与恢复点，Evolution 将重复失败沉淀为资产。每一层都要有明确输入、输出与失败出口。

整体验收的误区：“每个模块都能演示”不等于“任务可以交付”。只有当成功、失败、高危和中断四类路径都能穿过这些层并返回可追溯状态时，才算一个能运行的系统。

03 / 事实证据：认证任务如何穿过整套运行机制

下表把抽象层映射到认证任务中的具体落点。它既是组件清单，也是分诊入口：现场出现“自称 401 但实测 200”“哈希被误改”“多轮后忘记进度”等症状时，先定位断在哪一层，再补对应机制，而不是盲目更换模型。

层	认证系统里落在哪	缺了会怎样	本篇章节
LLM	拆步、填参、读日志	无智能	Part 03
Context	契约 + 代码 + 日志依据包	瞎猜、踩禁区	Part 04
Tool	读改测探受控接口	只会说话	Part 05
ReAct / Plan	局部排障 + 全局计划对象	漂或空转	Part 06–07
Reflection	证据清单裁定出口	假完成	Part 08
Multi-Agent	统一状态后的职责切分	多窗口噪声 / 状态裂	Part 09
Harness	状态 / Checkpoint / 交接	演示级，不可恢复	Part 10
Routing	按风险选控制强度	过严或过松	Part 11
Evolution	翻车→可回归资产	重复踩坑 / 假自进化	Part 12
Governance	权限、审计、人工闸	事故与不可追责	Part 13

五阶段主线与失败、高危、演进三类受控出口

flowchart TB Spec["认证 Spec 与验收句"] --> Context["Context\n现行代码、规范、日志依据包"] Context --> Plan["Plan\n可验证步骤与 Checkpoint 依赖"] Plan --> Route["Routing + Governance\n风险档位、ACL、人工闸"] Route --> Harness["Harness\n任务状态、预算、写锁、恢复点"] Harness --> Tool["受控 Tool\n读代码、限域 patch、测试、探针"] Tool --> Observe["外部观察\nDiff、run-id、probe-id"] Observe --> Reflect{"Reflection\n证据是否满足验收？"} Reflect -->|通过| Checkpoint["写入 Checkpoint\n放行下一步或交付"] Checkpoint --> Plan Reflect -->|缺少事实| Enrich["补 Context"] Reflect -->|局部实现失败| React["ReAct 短环\n受控排障"] Reflect -->|计划假设失效| Replan["显式 replan"] Reflect -->|高危或预算耗尽| Human["人工闸 / 交接"] Enrich --> Plan React --> Harness Replan --> Plan Human --> Harness Reflect -->|重复失败模式| Evolution["Evolution\n回归用例、规则、评估资产"] Evolution --> Context

这张图的核心不是主线从左到右，而是四种失败出口和一条经验回流边。验证未通过时，系统不会重新生成整篇方案，而是根据证据回到 Context、当前执行步骤、Plan 或人工闸；重复失败再被沉淀为资产，影响后续任务的默认依据与规则。

现场一红，先对层，再补层——与开篇四个缺口同构，只是落在完整栈上

事实类

不知真值 / 瞎猜

缺 Context 或探针 Tool；补依据包与 http_probe / read_file。

行动类

只会建议

缺 Tool 契约或权限过死/过松；补受控双手，禁全能 shell。

状态类

不知跑到哪 / 难续

缺 Plan 对象或 Harness Checkpoint；进度外置，失败可回滚。

验证 / 安全类

假完成或事故

缺 Reflection、Routing 或 Governance；证据裁定 + 高危闸 + 审计。

症状	先查哪层	典型补法
自称 401，实测 200	Reflection / Tool	强制探针证据，禁止自述完成
方案对，仓库未改	Tool	接 apply_patch + 审计
多轮后进度丢失	Harness / Plan	Checkpoint + 状态机
哈希被「优化」	Context / Governance	禁区 ACL + 审计打回
合主干无审批	Routing / 治理	高危路径人工闸前置
同一坑每周重踩	Evolution	回归用例与规则资产化

04 / 执行结论：按闭环验收系统，而不是按模块打勾

系统是否拼装完成，应由任务行为裁定，而不是由组件数量裁定。对认证 Agent 来说，至少要能证明：输入有受控依据，执行有计划和权限约束，结果有测试与探针，失败有明确回流，高危有人工闸，中断后有可恢复状态，重复问题有资产化出口。

	对话框 v0	拼装后的认证 Agent
输入	Spec 粘贴堆	受控依据包 + 计划对象
执行	生成长文方案	Tool 限域读写测探
失败	再生成一版	Reflection 选出口 + Harness 回流
进度	活在聊天里	task 状态 + Checkpoint
高危	与只读同权	路由 + 人工闸 + 审计
经验	对话坟墓	受控演进资产

在架构图上描通以下路径，描不通则未拼完：

目标进入 → 依据装载 → 计划步进 → 工具行动
观察返回 → 证据裁定 → 验证失败回流（补上下文 / 重试 / 重规划 / 人工）
验证通过 → Checkpoint → 下一步或交付摘要
高危动作 → 路由高危 → 人工闸 → 审计记录
典型翻车 → 演进提案 → 评估发布 → 可回滚资产

干货：机制地图告诉你「有什么」；失败→缺层对照告诉你「坏了补哪」。两张底图够你分诊大多数「Agent 不闭环」。下一节只列通往产品的问题——规格与验收是 03 篇的事。

思考笔记：系统拼装的完成标志，不是“模型更强”，而是失败不再无处可去

单点能力再强，也无法替代一条可追溯的失败路径。真正能持续跑的认证 Agent，知道当前事实来自哪里、下一步为何被允许、失败应由谁裁定、该回到哪里，以及高危动作何时必须停下。

这也是本文从“裸对话交不出认证”走到“系统拼装”的最终判断：语言模型负责提出下一步，运行系统负责让每一步可执行、可验证、可恢复并且受治理。

这一幕带走：各层挂上五步环，才叫系统。描得出「验证失败回流」，才叫能持续跑的认证 Agent。

Part 15 · 机制到产品：先问清这张清单

过渡

吃透机制之后，下一问是：如何封成可验收的单个产品？本页只列问题，不填设计卡——规格与验收是 03 篇的事。

过渡 / Transition：为什么机制跑通后还不能直接做成产品

正如「PART 15 · 实战设计」图示所强调的：最终交付是一套完整方案，而不是一段孤立 Prompt。理解、行动、验证、治理与演进缺一项，就很难形成可靠 Agent。

小周现在有一张能跑的机制地图：缺口、五步环、依据包、工具、计划、裁定、Harness、路由、演进与治理。但这些是系统如何运行的语言，不是用户为什么购买、何时算完成、失败时看见什么的语言。若直接跳进“做个认证 Agent 产品”，很容易把机制名词包进界面，最终仍是一个更会聊天的外壳。

产品化的第一步不是画 UI 或补更多功能，而是把运行机制翻译成用户可感知、可选择、可验收的承诺：谁提出什么目标，系统可以处理到什么边界，用户依据什么确认结果，高危动作由谁批准，失败后如何接手。

边界：本过渡章不写 Job-to-be-Done、不填设计卡、不定定价与排期。只把「机制名词」换成「产品必须回答的问题」，交给 03 · 做成 Agent 产品。

01 / 核心问题：为什么“系统能力”不等于“产品承诺”？

系统可以拥有 Plan、Tool、Harness 和 Governance，但产品仍需决定这些能力对谁可见、何时触发、哪些动作被允许、发生失败时由谁承担后续责任。例如“支持自动修改认证逻辑”没有说明是允许修改哪个仓库、是否允许合主干、提交前需要哪些证据，也没有回答运营、研发和平台团队各自如何判断结果。

把机制直接当产品描述，会造成两个偏差：一是用户只能看见术语，看不见自己获得的工作结果；二是高危边界被藏在后台配置里，直到上线后才暴露为权限、审计和交接问题。产品需要将内部机制转换为外部契约、能力边界、状态可见性和审批体验。

过渡原则：机制负责回答“系统怎样做”；产品必须先回答“为谁做什么、做到何种程度、由什么证据证明、失败后谁能接住”。

02 / 事实证据：认证机制如何转译为产品必须回答的问题

下表不是功能列表，而是把每项运行机制转化为产品侧必须明确的决策。只要其中一项无法回答，团队就不应以“Agent 已能跑”为由直接承诺交付。

本篇机制	产品侧要回答（→ 03）
目标 / Context	用户目标与成功标准如何写成产品契约？
Plan / Tool	规划与工具能力如何规格化、对用户暴露到哪一层？
Harness / Reflection	状态恢复与验证如何对用户可见、可申诉？
Routing / Governance	权限与上线闸门如何成为产品约束而非后台彩蛋？
Evolution	产品如何吸收失败案例而不变成无人改配置？

仍是问题，不是答案；用来开会对齐，不是用来直接开工写 UI

落到认证场景，问题会变得具体：系统对运营同学承诺的是“完成邮箱登录联调”，还是“自动修改并合并认证代码”？是否把登出探针、Checkpoint 与红测直接展示给研发？人工闸拒绝后，产品状态是“等待处理”“需要补充授权”还是“任务终止”？这些都不能由后端机制替用户决定。

契约

谁在什么情况下算成功？

运营 / 研发 / 平台：各自眼里的「认证 Agent 做完了」是否同一句可否决验收？

能力边界

产品承诺改什么、不改什么？

是否允许自动合主干？哈希禁区是否对用户可见为「能力外」？

可见性

进度与证据怎么展示？

Checkpoint、红测、探针结果是否进产品 UI / 通知，还是只埋在日志？

闸门

谁批、批什么、超时怎么办？

人工闸的角色、SLA、拒绝后的产品状态机如何定义？

用户是谁？一次成功交付帮他少做哪几步不可跳过的人肉劳动？
成功标准能否写成对外契约（类似 Spec Acceptance），而不是「体验更好」？
工具与权限边界如何写成产品能力清单与「明确不做」？
失败时用户看到什么？回流 / 人工接管在产品里叫什么状态？
审计与合规要求是否进入上线门槛，而非上线后补？

从机制能力到可验收产品契约的必要转译

flowchart LR Mechanism["机制能力\nContext · Plan · Tool · Harness · Governance"] --> Translate["产品化转译\n将内部能力变成外部问题"] Translate --> Contract["目标与验收\n谁成功？何时完成？"] Translate --> Boundary["能力边界\n能改什么？明确不做什么？"] Translate --> Visibility["进度与证据\n用户看见哪些状态与结果？"] Translate --> Gate["权限与人工闸\n谁批？拒绝后如何处理？"] Contract --> ProductSpec["可验收产品规格\n进入 03 设计"] Boundary --> ProductSpec Visibility --> ProductSpec Gate --> ProductSpec ProductSpec --> Build["产品实现与验证"] Build --> Evidence["真实使用证据\n失败案例与反馈"] Evidence --> Translate

图中“产品化转译”是必要的中间层：它不让机制名词直接跳到功能页面，而是先形成目标、边界、可见性和闸门四类问题。只有这些问题被写成可验收规格，产品实现才有稳定的输入；真实使用中的反馈再回到问题与机制两侧继续校正。

03 / 执行结论：带着问题进入产品设计，而不是带着术语堆砌

进入 03 之前，团队不需要马上决定界面、定价或排期，但需要先达成四项最小对齐：用户与任务范围、可否决的成功标准、明确的能力与权限边界、失败与人工接管的产品状态。它们会成为下一篇产品契约、规格和验收的输入。

别这样做	带进 03 的做法
把 ReAct/Harness 名词塞进 PRD 当卖点	改成用户可感知的能力与验收句
未回答「谁算成功」就画架构	先用上表问题对齐契约，再谈封装
把治理留到上线后	把人工闸与权限写成产品约束问题

进入 03 前的对齐检查：

目标用户是否明确，以及一次成功交付替他减少了哪些不可跳过的人工作业？
成功是否能写成对外可否决的验收句，而不是“体验更好”？
产品承诺的自动化范围、禁区和人工闸是否已经可说明、可验证？
失败、回流、等待审批和人工接管是否有用户能理解的状态与责任归属？

干货：机制名可以收进抽屉；产品规格与验收是下一篇的事。问题清单问不清，做成的「产品」仍是会说话的外壳。

思考笔记：产品化不是把 Agent 包装起来，而是把责任边界交代清楚

用户不需要知道系统内部是否使用了 ReAct 或 Harness，但必须知道任务会推进到哪里、证据在哪里、哪些动作需要自己批准，以及失败后还能从哪里继续。把这些责任与状态说清楚，才是把机制变成可靠产品体验的开始。

因此，这一章只保留问题，不替下一篇提前填答案。先把必须共同承担的产品决策摆在台面上，后续的规格与设计才不会重新把闭环压扁成一个聊天入口。

这一幕带走：只列问题，不填设计卡。带着「机制→产品」问题清单进入 03，才谈得上可验收的单个 Agent 产品。

结语 · 认证 Agent 为何终于能闭环

收束 / Conclusion

从「会写一段方案」到「能跑完认证并证明」，靠的不是更长的 Prompt，而是一层层补齐运行时：眼、手、记性、考官、架子与闸门。

01 / 收束背景：认证 Agent 最终解决的到底是什么

正如全文所强调的：会说话不是闭环。补齐眼、手、记性、考官、架子与闸门——描得出「验证失败回流」，认证 Agent 才算终于能闭环。

第一版把 Spec 丢进对话框，十分钟生成完整方案与“伪测通过”。一接真实仓库与 CI，事实、行动、状态、验证四个缺口同时暴露：它不知道现行 session 实现，无法受控修改代码，不记得任务推进到哪一步，也不能证明登出后的 GET /me 是否真的返回 401。

小周没有继续更换模型或堆叠 Prompt，而是把认证任务放回运行系统：五步环定义任务形状，Context 和 Tool 提供事实与行动，ReAct 与 Plan 分开局部探索和全局依赖，Reflection 用证据裁定，Harness 保存状态和恢复点，Routing 与 Governance 管理风险，Evolution 把翻车写成资产。

维度	对话框 v0（演示级）	能闭环时（产品级）
完成声明	模型自述「应该 401」	探针 + 测试证据裁定
改仓库	只会建议	受控 Tool 限域 patch
失败后	再生成一整版	回流出口写进状态机
进度	活在聊天窗口	Checkpoint 可续跑
高危	与只读同权	路由 + 人工闸 + 审计

终于能闭环的原因：不是模型突然「懂认证了」，而是系统不再把语言智能误当成整机——缺层被显式补上，验证失败在图上有边可走。

02 / 核心问题：为什么会说话仍然不等于能交付？

模型可以把“如何修认证”解释得极具说服力，但交付不是一段回答，而是一条可验证的状态变化：代码是否落进正确工作区、测试与探针是否真的通过、失败时保留了哪些事实、高危操作是否被授权。任何一项仍由模型自述代替，闭环就会在那一层断开。

因此，认证 Agent 的完成标准也不是“生成了一份方案”或“模型认为已经修好”，而是外部证据确认验收条件，同时任务状态、权限轨迹和失败出口都可以被下一位执行者复查。智能负责选择下一步，系统负责限制、验证和保存每一步。

四个缺口

入口诊断

事实 · 行动 · 状态 · 验证——裸对话交不出认证的根因地图。

五步环

运行形状

目标→规划→行动→验证→沉淀；失败必须回流，禁止感觉收工。

眼与手

Context · Tool

依据包可治理；感知与行动有契约、权限与返回四态。

架子与闸

Harness · 路由 · 治理

可恢复、按风险分路径、越权可追可拦——持续跑的前提。

带走三样：机制地图 · 失败→缺层对照 · 通往产品的问题清单。

03 / 事实证据：认证闭环如何从目标走到可复查交付

下面的总图压缩了本文的最终判断。主线不以模型输出为终点，而以外部证据和 Checkpoint 为终点；失败不是重新生成的理由，而是根据证据回到补事实、修实现、重规划或人工闸的入口。只有这些出口存在，任务才会在中断、换人或风险升级时保持可控。

认证 Agent 总览：主线推进、证据裁定与四类失败出口

flowchart TB Goal["认证目标\n登出后 /me = 401"] --> Facts["受控依据\nSpec、现行代码、规则、日志"] Facts --> Plan["计划与状态\n步骤、依赖、Checkpoint"] Plan --> Guard["风险与治理\nACL、预算、人工闸"] Guard --> Action["受控行动\n读改测探"] Action --> Evidence["外部证据\nDiff、run-id、probe-id"] Evidence --> Judge{"证据裁定\n验收是否通过？"} Judge -->|通过| Checkpoint["保存 Checkpoint\n交付摘要可复查"] Checkpoint --> Deliver["认证可交付"] Judge -->|缺事实| ContextBack["补充依据包"] Judge -->|实现失败| Repair["受控 ReAct / 修复"] Judge -->|计划失效| Replan["显式重规划"] Judge -->|高危或超限| Human["人工闸 / 交接"] ContextBack --> Facts Repair --> Action Replan --> Plan Human --> Plan Judge -->|重复失败| Learn["沉淀回归用例、规则、评估"] Learn --> Facts

图中每一条回流边都对应本文的一类机制：补事实回到 Context，局部修复留在 ReAct 与 Tool，依赖变化走 Plan 的显式重规划，高危和超限进入人工闸，重复失败沉淀为 Evolution 资产。它们共同避免了“失败后重新开一个对话”的假闭环。

全文路径（回看用）：

开篇–01：真实案例 → 四个缺口
02–05：闭环地图 → 推理内核 → 依据包 → 受控工具
06–08：ReAct 排障 → 计划对象 → 证据裁定
09–11：多角色协议 → Harness → 风险路由
12–14：受控演进 → 运行治理 → 系统拼装
过渡：机制→产品问题清单（不填设计卡）

04 / 执行结论：以闭环能力判断 Agent，并带着问题进入产品设计

判断一个认证 Agent 是否成立，可以连续追问：它是否读取当前事实、以受控工具改变外部世界、让外部证据而非自述裁定完成、把失败写进可恢复状态、在高危处停下并留下授权轨迹、把重复失败沉淀为可回归资产？只要任一问题无法回答，系统就还停在演示级能力。

本篇到此停在系统理解 / 机制层：解释 Agent 缺什么、补哪层、边界在哪里。下一篇不再重复这些内部机制，而是把它们翻译为一个用户能理解、团队能验收、风险能承担的产品契约。

层	篇	一句话
用法	01 · 用好 AI 编程	契约 · 证据 · 工序 · 回流
机制	本篇 02	从会说话到能闭环
产品	03 · 做成 Agent 产品	从目标到可验收

下一步：带着过渡章的问题清单，把机制封成可验收产品 → 03 · 做成 Agent 产品：从目标到可验收

思考笔记：闭环不是让系统永远自动，而是让系统始终知道何时继续、何时停下

一个可靠的 Agent 不会把所有问题都自动解决。它在证据不足时补事实，在局部失败时修复，在计划失效时重规划，在高危和超限时交给人，在重复失败时留下资产。能够停下并说明原因，与能够继续执行同样重要。

这正是认证 Agent 从“会写方案”走到“能交付”的分水岭：每个结果都能追溯，每次失败都有出口，每个高危动作都有边界。

全文带走：会说话不是闭环。补齐眼、手、记性、考官、架子与闸门——描得出「验证失败回流」，认证 Agent 才算终于能闭环。

Last updated: 2026-08-07 · 结语与全文结构修订

← 用好 AI 编程做成 Agent 产品 →