Coding Agent 与通用 Agent

第五章学习笔记：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 工程化工作流程

#mermaid-svg-ybOlKTKVG6lwf3aQ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-ybOlKTKVG6lwf3aQ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ybOlKTKVG6lwf3aQ .error-icon{fill:#552222;}#mermaid-svg-ybOlKTKVG6lwf3aQ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ybOlKTKVG6lwf3aQ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ybOlKTKVG6lwf3aQ .marker.cross{stroke:#333333;}#mermaid-svg-ybOlKTKVG6lwf3aQ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ybOlKTKVG6lwf3aQ p{margin:0;}#mermaid-svg-ybOlKTKVG6lwf3aQ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-ybOlKTKVG6lwf3aQ .cluster-label text{fill:#333;}#mermaid-svg-ybOlKTKVG6lwf3aQ .cluster-label span{color:#333;}#mermaid-svg-ybOlKTKVG6lwf3aQ .cluster-label span p{background-color:transparent;}#mermaid-svg-ybOlKTKVG6lwf3aQ .label text,#mermaid-svg-ybOlKTKVG6lwf3aQ span{fill:#333;color:#333;}#mermaid-svg-ybOlKTKVG6lwf3aQ .node rect,#mermaid-svg-ybOlKTKVG6lwf3aQ .node circle,#mermaid-svg-ybOlKTKVG6lwf3aQ .node ellipse,#mermaid-svg-ybOlKTKVG6lwf3aQ .node polygon,#mermaid-svg-ybOlKTKVG6lwf3aQ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ybOlKTKVG6lwf3aQ .rough-node .label text,#mermaid-svg-ybOlKTKVG6lwf3aQ .node .label text,#mermaid-svg-ybOlKTKVG6lwf3aQ .image-shape .label,#mermaid-svg-ybOlKTKVG6lwf3aQ .icon-shape .label{text-anchor:middle;}#mermaid-svg-ybOlKTKVG6lwf3aQ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ybOlKTKVG6lwf3aQ .rough-node .label,#mermaid-svg-ybOlKTKVG6lwf3aQ .node .label,#mermaid-svg-ybOlKTKVG6lwf3aQ .image-shape .label,#mermaid-svg-ybOlKTKVG6lwf3aQ .icon-shape .label{text-align:center;}#mermaid-svg-ybOlKTKVG6lwf3aQ .node.clickable{cursor:pointer;}#mermaid-svg-ybOlKTKVG6lwf3aQ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ybOlKTKVG6lwf3aQ .arrowheadPath{fill:#333333;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ybOlKTKVG6lwf3aQ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ybOlKTKVG6lwf3aQ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ybOlKTKVG6lwf3aQ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ybOlKTKVG6lwf3aQ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ybOlKTKVG6lwf3aQ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ybOlKTKVG6lwf3aQ .cluster text{fill:#333;}#mermaid-svg-ybOlKTKVG6lwf3aQ .cluster span{color:#333;}#mermaid-svg-ybOlKTKVG6lwf3aQ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ybOlKTKVG6lwf3aQ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ybOlKTKVG6lwf3aQ rect.text{fill:none;stroke-width:0;}#mermaid-svg-ybOlKTKVG6lwf3aQ .icon-shape,#mermaid-svg-ybOlKTKVG6lwf3aQ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ybOlKTKVG6lwf3aQ .icon-shape p,#mermaid-svg-ybOlKTKVG6lwf3aQ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ybOlKTKVG6lwf3aQ .icon-shape .label rect,#mermaid-svg-ybOlKTKVG6lwf3aQ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ybOlKTKVG6lwf3aQ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ybOlKTKVG6lwf3aQ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ybOlKTKVG6lwf3aQ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 失败
通过
阅读仓库和项目文档
理解需求与验收标准
按复杂度制定方案
实现代码
运行测试与检查
根据反馈定位问题
审查改动与同步文档
交付结果与验证证据

复杂任务需要更充分的设计与评审；简单修改可以裁剪流程。完成标准应包含验证结果，不能只看是否已经生成代码。测试通过也只证明已覆盖的性质，还需要核对需求和改动范围。

3. Harness：可靠性来自完整的反馈闭环

原文公式：Agent = Model + Harness。

工程组件	回答的问题	例子
验收基线	什么算完成？	测试、CI、审查标准
执行边界	可以采取哪些动作？	权限、模块边界、依赖规则
反馈信号	怎样发现错误？	类型检查、结构化异常、测试失败
回退手段	出错后怎样恢复？	分支、快照、沙盒

最适合 Agent 的任务同时具备两个条件：目标明确，结果可自动验证。目标不清楚，即使自动检查很完善，也可能持续优化错误的方向。

四条原则：

1. 能程序化强制执行的约束，应落实到代码和权限机制中。
2. 把可重复的验收步骤自动化。
3. 尽快返回具体、结构化的错误信息。
4. 为修改和执行准备可靠的回退路径。

还要检查过程：例如通过删除功能让测试通过，并不等于修复成功。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 // 100
both = 40 * 25 // 100
only_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