第五章学习笔记：Coding Agent 与通用 Agent
1. 本章最重要的结论
面向开放任务的通用 Agent，可以以 Coding Agent 为能力核心，以文件系统承载代码、数据、记忆和中间成果，再用 Harness 保证执行过程可控、结果可验证。
记住三个关键词：
- 代码是元能力：不仅调用已有工具，还能现场编写脚本、校验器和界面，创造完成任务所需的新能力。
- 文件系统是工作空间：将上下文之外的知识和进度保存下来，使任务可以继续、复查和复用。
- Harness 是运行保障：提供上下文、工具、约束、验证和纠正机制，让模型的能力转化为可靠的任务完成能力。
适用边界：开放任务难以预先枚举全部工具，因此特别需要代码生成；固定流程的客服等 Agent，核心也可以是领域工具和业务流程。
2. Coding Agent 怎样完成任务
2.1 七类基础工具
| 工具 | 作用 | 典型用途 |
|---|---|---|
| Code Interpreter | 在隔离环境执行代码 | 计算、统计、绘图 |
| Shell | 运行命令和程序 | 构建、测试、调用命令行工具 |
| Read | 读取文件 | 理解源码、配置、日志 |
| Write | 创建或重写文件 | 保存脚本和报告 |
| Edit | 局部修改文件 | 修复函数、更新配置 |
| Glob | 按路径模式找文件 | 找到所有*.py文件 |
| Grep | 按内容模式搜索 | 查找函数名、报错、TODO |
七类工具是一种能力拆分，并非必须对应七个独立接口。Shell 可以承载其中多项能力，专用工具则更方便限制范围、校验参数和返回结构化结果。
以整理 TODO 为例：
用户提出需求 → Grep 搜索 TODO → 必要时 Read 查看上下文 → 整理分类，复杂统计交给代码执行 → Write 保存清单 → 检查清单与搜索结果是否一致2.2 文件系统为什么重要
| 文件或目录 | 保存什么 | 学习要点 |
|---|---|---|
| 项目源码 | 可执行实现 | 能修改、测试和版本控制 |
项目指令文件，如AGENTS.md | 构建命令、风格、操作约定 | 让项目要求显式可见 |
MEMORY.md | 长期事实、偏好与经验 | 便于查看、纠错和追溯 |
| 日志与任务清单 | 已完成步骤、失败信息 | 支持跨轮次继续任务 |
| 报告、图表等产物 | 最终交付和中间结果 | 无需把全部内容放进上下文 |
写入记忆不等于获得可靠知识。一次成功经验仍需验证其适用范围、时效性和可重复性。
2.3 工程化工作流程
复杂任务需要更充分的设计与评审；简单修改可以裁剪流程。完成标准应包含验证结果，不能只看是否已经生成代码。测试通过也只证明已覆盖的性质，还需要核对需求和改动范围。
3. Harness：可靠性来自完整的反馈闭环
原文公式：Agent = Model + Harness。
| 工程组件 | 回答的问题 | 例子 |
|---|---|---|
| 验收基线 | 什么算完成？ | 测试、CI、审查标准 |
| 执行边界 | 可以采取哪些动作？ | 权限、模块边界、依赖规则 |
| 反馈信号 | 怎样发现错误？ | 类型检查、结构化异常、测试失败 |
| 回退手段 | 出错后怎样恢复？ | 分支、快照、沙盒 |
最适合 Agent 的任务同时具备两个条件：目标明确，结果可自动验证。目标不清楚，即使自动检查很完善，也可能持续优化错误的方向。
四条原则：
- 能程序化强制执行的约束，应落实到代码和权限机制中。
- 把可重复的验收步骤自动化。
- 尽快返回具体、结构化的错误信息。
- 为修改和执行准备可靠的回退路径。
还要检查过程：例如通过删除功能让测试通过，并不等于修复成功。Git 能恢复受版本管理的文件，但不能自动撤销已经发送的消息、转账或外部数据修改。
4. 故障处理：分类、恢复、接管、终止
4.1 四层故障与对应策略
| 层次 | 常见问题 | 处理重点 |
|---|---|---|
| API 层 | 限流、过载、超时、流中断 | 有上限的重试、退避、必要时降级 |
| 工具层 | 工具不存在、参数错误、执行异常 | 返回结构化错误，让模型改变输入或方案 |
| 上下文层 | 窗口溢出、压缩失败、消息配对缺失 | 管理上下文、校验轨迹结构、限制恢复次数 |
| 控制流层 | 重复无效操作、恢复逻辑递归失败 | 无进展检测、熔断、全局预算 |
先判断错误是否可重试。网络抖动可以重试；参数不合法、权限不足时，原样重试通常无效。
4.2 需要记住的机制
- 指数退避与随机抖动：失败后逐渐延长等待，并避免大量请求同时重试。
- 调用指纹：记录“工具名 + 参数”，结合执行结果和进展检测重复无效调用。
- 空闲看门狗：长连接建立后仍要检测是否持续收到输出。
- 恢复分级：重试 → 调整请求或降级 → 自动恢复失败后向用户说明。
- 局部故障隔离：失败只中止依赖它的操作，独立操作应继续。
- 全局终止条件：最大轮数、时间、费用和连续失败次数。
死亡螺旋示例：上下文溢出 → 结束钩子调用模型生成提交信息 → 再次溢出 → 再次触发钩子。解决思路是禁止错误处理路径递归触发同类模型调用，并设置递归深度上限。
4.3 跨模型接管与断点续写
轨迹宜保存为中立格式，再转换为目标模型的请求格式。工具名称、参数、结果以及接口提供的可读摘要可以保留；厂商专用凭证不能简单迁移。
流式输出中断时，补完的工具参数必须重新解析和校验。若工具已执行，还要核对执行记录，防止重复副作用。
工程补充：调用指纹用于检测重复，不足以单独保证业务操作幂等。支付、取消等操作还需要服务端幂等键、事务或执行状态记录。
5. 核心代码解读：取消订单工具
原文的cancel_reservation(...)展示了如何把业务规则写进执行工具。它依赖db、server_clock、log_mismatch和execute_cancellation，属于架构示例，不能直接独立运行。
5.1 参数为什么这样设计
| 参数 | 用途 | 能否作为政策事实 |
|---|---|---|
reservation_id | 指定要处理的订单 | 需要据此查库并校验访问权限 |
cancellation_reason | 陈述取消原因 | 不能据此认定航空公司已取消航班 |
expected_cabin_class | 模型陈述预期舱位 | 不能，服务端读取真实舱位 |
expected_has_insurance | 模型陈述预期保险状态 | 不能，服务端读取真实保险状态 |
expected_*是模型核对条件的提示和审计信息。原代码只在它们与数据库不一致时记录告警，不会直接据此批准或拒绝取消。
5.2 执行顺序
读取数据库订单 + 服务端当前时间 → 对比 expected_*，不一致则记录告警 → 已使用任何航段？是：拒绝 → 预订时间在未来？是：拒绝 → 预订后不超过 24 小时？是：取消 → 数据库显示航空公司已取消航班？是：取消 → 商务舱？是：取消 → 经济舱或基础经济舱？有保险则取消，否则拒绝 → 其他情况：拒绝这里使用的是多个带return的条件分支，一旦命中就结束函数。因此规则的顺序决定优先级：即使符合 24 小时条件或商务舱条件，只要已经使用航段，仍先被拒绝。
hours_since_booking <= 24包含恰好 24 小时；负值被提前排除。真实系统还需明确时间精度、时区和政策口径。
5.3 三层保障
自然语言规则：帮助理解政策和解释结果 ↓ 工具描述与参数：提示模型调用前核对条件 ↓ 服务端校验：用数据库真值决定是否允许执行关键点：模型即使误报“已购买保险”，也不能改变数据库事实；模型填写的取消原因，也不能替代数据库中的航班状态。
5.4 示例距离生产实现还缺什么
以下是阅读代码后的工程补充：
- 校验订单存在性、调用者身份和订单归属。
- 在事务或等效一致性机制中完成校验与执行，避免查完订单后状态发生变化。
- 处理重复取消、并发请求、执行失败和审计记录。
- 校验
cancellation_reason的取值；该参数在原示例函数体中没有参与决策。 expected_*是可选参数，能引导核对，但不能保证模型真的执行了查询步骤。
适合练习的测试：已使用航段、未来预订时间、恰好 24 小时、超过 24 小时的经济舱无保险、模型预期与数据库不一致。重点验证规则优先级和服务端事实来源。
6. 代码作为元能力的六类应用
| 方向 | 解决的问题 | 典型流程 | 验证重点 |
|---|---|---|---|
| 思考工具 | 精确计算与逻辑求解 | 自然语言 → 形式化代码 → 求解器 | 建模是否忠实于题意 |
| 业务规则 | 复杂条件和关键操作约束 | 理解政策 → 调用工具 → 服务端校验 | 真值来源、规则顺序、执行权限 |
| 多媒体生成 | PPT、视频、结构化图形 | 生成代码 → 渲染 → 审核 → 修改 | 实际视觉或音视频效果 |
| 系统适配器 | 接口差异和格式变化 | 观察样本 → 生成适配代码 → 回归验证 | 新旧格式与异常数据 |
| 生成式 UI | 表单、数据展示、界面定制 | 生成界面或查询 → 受控执行 → 展示 | 可用性、数据口径和权限 |
| Agent 自举 | 修复或创造 Agent | 参考成熟实现 → 定向修改 → 评测 | 架构、状态管理和任务完成率 |
6.1 用代码思考：执行精确不等于建模正确
原文选课例子：40 人中，45% 选物理，25% 两门都选，则只选物理的人数为：
physics=40*45//100both=40*25//100only_physics=physics-both# 8代码负责计算，但若模型写成“数学人数减交集人数”，程序仍可能正常运行，却回答了错误的问题。
这里整数除法适用于题目给定的整人数；不能对任意比例直接截断并当作真实人数。符号计算与数值计算也需区分：SymPy 可保留符号形式，NumPy、SciPy 常用于数值运算，结果可能存在浮点误差。
6.2 多媒体：必须看渲染结果
提议者—审核者循环：Proposer 编写代码，Reviewer 检查渲染截图或关键帧，再给出包含位置、问题、严重程度和修改建议的反馈。
拆分的价值还在上下文管理：提议者主要保存文本反馈；审核者主要检查当前版本，避免历史图片持续累积。循环在质量达标或预算耗尽时停止。
选生成方式时，看两个维度：是否能用少量参数精确描述，以及是否需要严格验证尺寸。结构化图表、参数化几何适合代码；自然纹理等丰富细节适合生成模型，也可以组合使用。
6.3 系统适配：自动修复前先识别变化性质
解析失败 → 收集样本和报错 → 判断格式变化 → 生成解析代码 → 新旧样本测试 → 更新格式变化可能是正常升级，也可能是上游 bug。自动兼容不能掩盖缺字段、错误类型或语义变化；需要保留异常证据并校验数据含义。
6.4 Artifact 模式：让数据直接流向展示端
用户问题 → LLM 生成 SQL → 受控执行层 → 数据库 ↓ 查询结果 → 表格或图表LLM 负责生成查询和展示逻辑，大量数据不必经过模型逐行复述。这样减少 token、延迟和转述错误，但 SQL 仍可能表达错误的统计口径。
执行层需要只读身份、SQL 解析与准入检查、参数化绑定，以及时间和行数限制。动态应用的数据访问必须经过稳定的权限层，由可信运行时绑定用户、租户等访问上下文。
6.5 自举：参考实现比从零生成更可控
先用确定性规则处理常见故障，再让模型分析长尾问题。创建新 Agent 时，以经过验证的实现为基础，修改角色、工具和业务逻辑，并保留成熟的消息格式、上下文管理和执行循环。
自举不会自动带来质量提升；必须通过测试和评测检查新版本是否退化。
7. 实现工具时的关键取舍
7.1 搜索方式
| 方式 | 适合什么线索 | 局限 |
|---|---|---|
| Glob | 已知文件名或路径模式 | 不检索内容 |
| Grep / ripgrep | 已知函数名、文本、错误消息 | 难以匹配不同措辞的语义 |
| 语义搜索 | 只知道“这段代码在做什么” | 需合理分块，并验证检索结果 |
| 符号搜索 | 定义、引用和调用关系 | 依赖语言解析和索引支持 |
7.2 编辑方式
| 方式 | 优点 | 易错点 |
|---|---|---|
| 差异描述 + 应用模型 | 分离修改意图与文本合并 | 合并可能选错位置 |
| 旧字符串 → 新字符串 | 行为直接、方便校验 | 原文不一致或匹配不唯一 |
| 行号范围替换 | 大段删除表达简洁 | 修改后行号发生偏移 |
| 类 Vim 命令 | 适合移动、重组文本 | 批量操作的状态难预测 |
| 首尾字符串定位 | 减少大段原文输出 | 必须保证边界组合唯一 |
7.3 效率优化
- 独立且支持并发的工具可以并行；流式参数完整并通过校验后才能执行。
- 大文件按需读取并附行号；长输出保存到文件，返回摘要和定位信息。
- 动态环境状态追加到上下文中，避免频繁改写稳定前缀。
- 有状态命令需要会话管理；并行任务也要避免共享目录或环境变量相互干扰。
- 文件修改后及时返回语法、类型和测试反馈。
8. 安全：把不可违反的规则放在可信执行层
原文的风险组合是：访问私有数据 + 接触不可信内容 + 对外通信能力。持久记忆会进一步放大风险，使恶意内容跨会话继续影响行为。
对应防线包括：
- 外部网页、日志和工具输出作为待分析数据处理，不能自动获得指令权限。
- 隔离文件系统和凭证，按需限制网络出口，设置资源配额和超时。
- 检查命令的结构、参数和实际副作用，不能只靠危险词黑名单。
- 审查进入长期记忆的内容，并保留来源和修订能力。
- 动态生成的业务代码使用受限身份访问数据，最终授权由稳定的数据层或受控数据服务执行。
需要区分：代码可执行不等于逻辑正确；测试通过不等于安全无漏洞；沙盒也不能替代数据库的访问权限控制。
9. 实验
实验5-8：https://blog.csdn.net/qq_42137576/article/details/166690630?spm=1011.2415.3001.5331
