第二章 · 设计自己的 Agent

Agent 可以怎样继续生长

这一章不要求你立刻写代码。目标是让任何功能设想都能被拆成一张工程图： 它何时触发、需要知道什么、能做什么、怎样证明成功，以及什么事情绝不能越界。

01 最小内核

loop + context + tools

02 可靠执行

补丁、测试、重试、日志

03 长期任务

恢复、压缩、记忆、预算

04 协作系统

子 Agent、并行、worktree

05 Agent 平台

Skills、MCP、Hooks、自动化

核心判断

大多数新功能改的是 Agent 框架，不是模型本身。

设计方法

先确定信息、动作、验证和边界，再让 AI 编写实现。

本章实验

把自己的想法填进功能设计卡，并保存为下一次讨论的输入。

01

一个功能不是按钮，而是九个部件

“让 Agent 自动修复测试”听起来是一项功能，但还不能直接实现。只有把它拆成下面九块， 才能判断需要改主循环、增加工具，还是补充状态与安全策略。

触发+上下文+决策+工具+状态+验证+权限+失败+输出
触发条件什么时候开始，是用户命令、测试失败、定时器，还是外部事件？
所需上下文模型做决定前必须看到哪些文件、日志、规则和历史？
决策规则模型要在什么候选动作之间选择，何时应该询问人类？
可调用工具框架需要提供哪些真实动作，参数和返回值是什么？
中间状态尝试次数、当前假设、任务进度和后台进程保存在哪里？
成功验证什么外部证据能证明结果正确，而不是模型自己觉得正确？
权限边界哪些目录、命令、网络地址和外部操作可以访问？
失败处理超时、重复、工具报错和无解时怎样退出或恢复？
用户输出最终展示结论、diff、证据、风险，还是等待审批的动作？

02

新功能可以插在循环的六个位置

不必一想到新功能就重写整个 Agent。先点击下面的位置，观察它分别会改变哪段数据流。

模型调用前：准备它这一轮能看到的世界

适合加入仓库搜索、记忆检索、规则加载、上下文压缩和敏感信息过滤。

先问：这项功能需要给模型补充什么信息？

03

十个扩展方向

这些方向并不互斥。一个真实功能通常会同时跨过两到四层。

01感知与上下文

代码搜索、仓库地图、网页、图片、数据库、IDE 诊断。

Agent 能看见什么？
02工具与行动

补丁、Git、浏览器、部署、外部 API、后台进程。

Agent 能真正做什么？
03规划与决策

Plan 模式、任务拆解、优先级、模型路由、重复检测。

Agent 怎样选择下一步？
04记忆与学习

会话摘要、项目知识、用户偏好、经验修正与遗忘。

什么应该跨轮次保留？
05验证与反思

测试、lint、类型检查、截图、第二意见和验收标准。

怎样用证据证明成功？
06权限与安全

审批、沙箱、网络策略、密钥保护、审计与撤销。

哪些动作绝不能只靠模型自觉？
07多 Agent 协作

专业角色、隔离上下文、并行探索、worktree 和汇总。

任务怎样拆，结果怎样合？
08交互与界面

流式进度、审批、diff、时间线、打断、转向和恢复。

人类怎样理解并控制过程？
09自动化运行

定时器、文件监听、Webhook、队列、后台任务和通知。

没有人盯着时如何可靠工作？
10观测与优化

轨迹、Token、费用、延迟、缓存、评测和失败回放。

怎样知道系统正在变好？

04 · 互动实验

把自己的想法变成功能设计卡

选择一个示例观察九个部件怎样配合，也可以直接改成自己的设想。 内容只保存在当前浏览器的本地存储中。

设计卡预览 自动修复测试失败

05

验证闭环：不要让模型给自己判满分

模型说“完成了”只是一个文本判断。可靠 Agent 会寻找外部证据，并把失败结果带回下一轮。

观察

测试失败、用户目标、当前 diff

→
假设

判断根因和最小修改

→
行动

修改代码或配置

→
证据

测试、构建、截图、审查

↺ 失败就继续
证据层级例子特点
确定性检查语法、lint、类型检查、测试退出码成本低，适合每次修改后运行。
行为检查集成测试、浏览器交互、接口响应更接近真实使用，但准备成本更高。
独立审查只读审查 Agent、规则扫描、安全检查补充难以写成断言的问题。
人类验收产品判断、风险接受、主观质量留给真正需要价值判断的部分。

06

记忆系统：难点不是存，而是取舍

把所有历史永久塞进 prompt 不是记忆系统，只会让上下文越来越混乱。

提取哪些内容值得记
→
存储放在哪种记忆里
→
检索何时重新取出
→
校验是否仍然正确
→
遗忘过期时删除或降权
当前任务状态

正在做什么、已经完成什么、下一步是什么。

会话摘要

压缩早期过程，保留目标、决定和关键证据。

项目知识

构建命令、目录职责、约定和常见故障。

用户偏好

讲解深度、审批习惯、输出形式和长期目标。

07

权限与安全：判断层和物理边界要分开

审批是在问“这次应该允许吗”，沙箱是在保证“即使判断错了也越不过边界”。

判断层 权限策略与审批

允许、询问、拒绝；根据工具、命令、路径和副作用决定。

执行层 操作系统沙箱

限制可写目录、网络、进程和系统资源，模型无法自行绕开。

追溯层 日志、diff 与撤销

记录发生了什么，让人类可以检查、恢复并改进规则。

08

多 Agent：先隔离噪声，再追求并行

子 Agent 的第一价值不是“人多力量大”，而是让主线程保留需求和关键决策， 把搜索日志、测试输出和大范围探索放进独立上下文。

主 Agent 目标、边界、决策、汇总
探索 Agent

只读搜索相关代码，返回地图和证据。

实现 Agent

在独立 worktree 中完成有边界的修改。

测试 Agent

运行验证，压缩日志并归纳失败原因。

审查 Agent

只看需求和 diff，寻找回归与缺失测试。

适合并行

代码探索、资料查找、测试、日志分析、独立审查。

谨慎并行

同时修改相同文件、共享数据库迁移、需要连续产品决策的工作。

09

扩展系统：每一种机制负责不同问题

机制它负责什么适合的例子
指令文件长期告诉 Agent 应该怎样工作。构建命令、代码规范、审查要求。
Skills封装可复用的工作方法和参考材料。发布流程、故障排查、文档生成。
MCP连接 Agent 之外的数据和真实动作。GitHub、设计稿、数据库、内部系统。
Hooks在生命周期节点运行确定性程序。拦截密钥、修改后 lint、结束前验证。
Plugins打包并分发技能、工具、Hooks 和配置。团队统一安装一套工程工作流。
SDK / Server把 Agent 循环嵌入自己的产品。IDE、网页控制台、CI 和内部平台。
模型决定下一步
+
Skill告诉它怎么做
+
MCP给它外部手脚
+
Hook强制固定规则
+
Plugin安装与分发

10

从当前代码出发的升级路线

顺序的原则是先让单 Agent 可靠，再增加记忆和协作。勾选状态会保存在当前浏览器。