Coding Agent 与通用 Agent

PPT / Word

本质是 OOXML 格式的代码。

PDF 报告

可以由 Markdown、HTML 或 LaTeX 生成。

数据与图表

用 Python 脚本完成。

调研与 GUI

搜索和综合靠代码发 Web 请求并解析。成功的浏览器操作序列可以固化成代码（第九章）。

为什么用 Markdown，不用向量数据库

• 用户能直接打开、修改 Agent 的记忆，记错了删掉那一行就行
• 天然保留时间顺序，不会出现语义检索里的时间混淆
• 可以用 Git 做版本控制和回滚

能写文件，就能改自己的外部产物

例如第一次给某家银行打电话时，发现对方要提供开户行地址才能验证身份，Agent 可以先把这个发现记下来。一条记录什么时候能当作可靠的知识、指令或程序，还要靠更多轨迹和结果来验证（第九章“持续进化”）。

适用边界

开放任务型（深度调研、内容生成、数据处理）：需要的工具无法事先列全，代码是架构中枢。
垂直领域型（如客服）：任务空间相对封闭，架构围绕业务流程、领域工具和对话策略来搭，代码只是工具箱里的一件工具。即使这样，它仍然是精确计算、数据处理和规则校验离不开的基础能力。

项目指令文件：项目级的系统提示词

CLAUDE.md、AGENTS.md、.cursorrules 已经是事实标准，每次会话开始时自动注入上下文。README 写给人看，指令文件写的是给 Agent 的行为约定：

# CLAUDE.md
- 用 pnpm test 而不是 npm test
- 禁用 any 类型
- 不要改动 migrations/ 目录

SOUL.md 约定“Agent 是谁”，项目指令文件约定“在这个项目里该怎么干活”。它的内容不随任务变化，是最省的稳定前缀，对 KV Cache 友好。

各阶段要点

• 文档化：关键文档缺失时，先读代码库，写出架构概览、目录结构和测试指南。知识显式写出来，协作才高效。
• 需求澄清：“优化性能”要先问清目标（响应时间、内存还是吞吐）、能接受什么代价、瓶颈在哪。
• 设计文档：审查一份简洁的设计比审查几百行代码容易得多，是人类最省力的介入点。
• 测试与自审：测试失败就分析、定位、修改，直到全部通过；再通过阅读代码、跑 lint 或调用审查子 Agent 自审。
• 文档同步：过时的文档比没有文档更糟。

验收基线

什么算做完：测试套件、CI 管道、代码审查标准。

执行边界

能碰什么、不能碰什么：模块边界、依赖规则、权限控制。

反馈信号

自动判断对错：Linter 输出、测试结果、类型检查错误。

回退手段

出了问题怎么恢复：Git、沙盒隔离、快照回滚。

约束动作，不只约束结果

修数据库故障时把库删了重建，“修复”确实生效了，数据却没了；修编译错误时把代码全删了重写，编译确实过了，实现却没了。这类破坏性捷径总是存在，即使写进评估指标也常被绕过（第八章 reward hacking）。所以生产级 Harness 要对 rm -rf、删生产数据、覆盖未读文件这类动作专门检查并审批。在训练侧，对应的是第八章的 RLVP：奖励结果，惩罚路径。

API 层

限流（HTTP 429）、过载、超时、断连、输出触顶被截断。和任务内容无关，是基础设施的噪声。

工具层

幻觉调用、参数畸形、执行抛异常。最危险的是工具反复返回同一个错误，模型却原样反复重试。

上下文层

窗口溢出、压缩失败、轨迹结构损坏（例如工具调用缺少配对的结果）。

控制流层

死循环：反复做同样的事却没有进展。死亡螺旋：恢复逻辑自己调用 LLM 又出错，引起连锁反应。

网络出口控制

最容易被忽视，也最关键。默认断网，按需通过白名单代理放行少数目的地：包管理源、文档站点、任务明确需要的 API。即使恶意代码在沙盒里读到了敏感数据，没有出口也传不出去。

文件系统隔离

源码目录只读挂载，补丁经审查后落盘，或者把副本挂进可写工作区。生成物和中间文件放在单独的可写目录。~/.ssh、密钥、token 根本不挂载。

资源限额与超时

用 CPU、内存、磁盘配额和超时，防死循环、fork 炸弹和无限写盘。超时后要返回结构化错误，例如“执行超过 120 秒被终止，最后输出如下……”，不能静默杀掉进程。

第一重 · 提示词里的自然语言规则

帮模型理解政策、向用户解释。

第二重 · 参数即 checklist

为了填好 expected_*，模型得先查订单、逐条核对。查到经济舱没买保险时，它很可能在准备调用时就想起规则 5，于是不发起调用，直接建议“先购买保险再取消，或者改签”。这一层用来引导思考，不承担安全责任。

第三重 · 服务端真值校验守门

模型可能幻觉，也可能被注入操纵，同一上下文里的 Agent 难以自证清白。最后一道防线必须建在模型无法伪造的数据上。“独立验证”里的独立，既指独立的模型，也指独立的数据来源。

用 HTML 交付成果，替代 Markdown 汇报

相比一页页翻读的 Markdown，HTML 有三个优势：用可操作的演示说明系统怎么运行；用图表和可下钻的组件呈现数据；网站可以随工作推进持续完善，而不是结束时一次性产出的死物。作者为每个研究项目维护一个交互式网站，用来追溯实验数据（prompt、LLM 原始回复、judge 打分）、监控训练的“内科指标”（损失、梯度范数、学习率、困惑度、奖励、KL 散度、策略熵），以及展示系统的运行原理。你正在看的这个页面就是这种交付形式。

DNA 自复制

随机变异 + 自然选择。不理解自身，不能定向修改，经历了 37 亿年盲目试错。

Agent 自举

理解代码 + 定向设计。理解自身机制，有目的地创造，继承最佳实践。

从零写 Agent 时的常见缺陷

1. 上下文管理随意：不用标准上下文格式，把轨迹转成纯文本塞进上下文，放弃了结构化消息带来的 KV Cache 优化，工具调用循环有边界 bug
2. 工具设计不规范：描述简略，缺少使用边界和负面清单，参数没有具体示例
3. 技术选型滞后：倾向于用训练数据里最常见、但已经过时的模型和 API。解决办法是维护 SOTA 知识库，或者让 Agent 能搜索
4. 脱离外部生态：使用已废弃的 API、不再维护的库或有缺陷的模式

基于范例生成

最有效的办法不是在提示词里穷尽所有规则，而是给出高质量的 Agent 实现作为范例，让 Agent 在它的基础上改。范例本身就带着最佳实践，好的架构选择会自然保留下来。接到“开发新 Agent”的任务时，先复制自己（或另一个验证过的实现）的代码，再调整系统提示词、增删工具、改业务逻辑，保留架构框架。这就像基因的复制加变异。

一、成熟度来自 Harness

Coding Agent 成熟度高，是因为测试套件、类型系统、版本控制天然构成了 Harness。这个结论可以推广到其他 Agent 场景。

二、可靠性来自故障路径

Agent 是否可靠，不取决于模型犯不犯错，而取决于每类故障是否都有对应的检测、恢复、接管与终止路径。

三、代码是元能力

代码既是完成任务的手段，也是积累知识、创造工具、优化自身的机制。