Agent 实践

Agent 会围绕目标反复读取环境、提出行动、获得观察并调整下一步。它适合路径无法完全预先写定的任务，例如排查未知故障、跨多份资料研究，或在仓库中根据测试结果持续修改代码。

实践质量主要取决于五件事：行动能否被校验，观察能否被追溯，状态是否由外部系统维护，权限是否足够窄，完成是否由测试或业务规则证明。模型和工具只是其中一部分。

先判断是否需要 Agent

任务步骤固定、分支已知时，优先使用普通程序或 Workflow。它们更容易预测、测试和审计。例如每天把同一份 CSV 转成固定报表，不需要模型决定下一步。

当任务同时具备以下特征时，Agent 才开始有价值：

• 根因、资料位置或解决路径尚不明确。
• 下一步依赖刚刚获得的测试、搜索或工具结果。
• 需要在多个文件或系统之间保持任务状态。
• 结果可以通过测试、规则、来源或人工审批验证。

如果结果无法验证、行动代价很高，又缺少可靠的撤销方式，应先缩小任务范围。Agent 的自主程度不能超过系统的验证和恢复能力。

用同一个 Bug 理解四层能力

假设用户登录前访问 /settings，登录成功后却跳到首页 /。入口把已校验的地址写入 session['return_to']，登录回调却读取 session['next_path']，最终使用了默认地址。完成标准包括补回归测试、恢复站内相对路径、继续拒绝外部 URL、相关测试通过且没有无关改动。

解决这个问题可以逐层增加能力：

层次	解决的问题	本例中的作用
ReAct	根因未知时，怎样根据新观察选择下一步	运行失败测试、搜索代码、读取回调，再用定向测试确认根因
Plan-and-Execute	步骤多且有依赖时，怎样保存和修改计划	将复现、补测试、修复和验证写成带完成条件的计划
Harness	怎样让 Agent 在真实仓库中安全、可恢复地执行	限制路径和命令，保存权威状态、Gate、日志与检查点
Skill	怎样复用已经验证过的工作方法	把“复现—最小修改—回归测试—检查 diff”沉淀为可测试流程

这四层可以组合使用，也可以只取当前任务需要的部分。一个只读排障任务可能停在 ReAct；准备修改真实仓库时，再增加 Harness。

四篇沿用同一故障和根因，教学起点有所不同。ReAct 使用独立的只读模拟仓库，预先提供测试输出以讲清行动循环；Plan 从测试夹具尚未支持 returnTo 的状态开始，展示如何重规划；Harness 则说明真实执行环境怎样新增并运行这些测试。模拟代码用于解释各层职责，不代表同一个仓库快照可以按页面代码直接拼接。

统一五个工程概念

本系列使用同一组术语，避免模型输出、工具结果和系统事实混在一起：

• 行动请求：模型希望执行的工具与参数，请求本身没有授权效力。
• 未验证观察：工具返回的原始内容，仍需校验来源、结构和时效。
• 权威状态：宿主程序确认后的任务事实、预算、阶段和检查点。
• 外部验证：测试、退出码、Schema、业务不变量或人工审批提供的证据。
• 完成标准：任务开始前确定的验收条件，全部满足后才能成功。

一次运行可以生成很多合理文字，仍然可能没有完成任务。系统只根据权威状态和外部验证改变成功状态。

按当前问题继续阅读

• 需要设计跨层循环、停止条件与预算：阅读 Loop 工程，区分执行、任务、产品与系统循环的对象和出口。
• 根因未知，需要边观察边决定：从 ReAct 模式 开始，理解最小行动循环和停止条件。
• 任务步骤多、有依赖，计划还可能变化：阅读 Plan-and-Execute 模式，为每步增加依赖、done_when 和 Replan 预算。
• Agent 要在真实仓库中持续执行：阅读 Harness 工程，补齐工作区隔离、权限、Gate、日志、检查点和恢复。
• 同类任务已经反复成功：阅读 Skill，把经过验证的流程、脚本和参考资料封装起来，并用新任务验收。

第一次实践时，选择一个范围小、可回退、有现成验证方式的任务。先写目标、允许操作的资源、禁止动作和完成标准，再决定模型可以使用哪些工具。这样得到的 Agent 系统即使能力有限，也能解释自己做过什么，并在证据不足时停下来。