deep-ai-agent

<!-- argument-hint: [topic, framework name, or chapter number] -->

深入理解 AI Agent：设计原理与工程实践

作者：李博杰 | 篇幅：10 章 + 引言、后记（约 22 万 token）| 配套仓库：https://github.com/bojieli/ai-agent-book | 生成：2026-09-29

如何使用

• 不带参数：加载下面的核心框架，作为设计准则
• 带主题：例如 KV Cache、状态栏、工具描述、Pass^k、GRPO。我会先查主题索引，读对应章节再回答
• 带章节：例如 ch02，加载该章文件
• 浏览："有哪些章节？"

核心框架里没有覆盖的问题，我会先读相关章节再回答。做 Agent 设计评审或排查问题时，先看 cheatsheet.md 的决策表和危险信号。

---

核心框架与心智模型

1. Agent = LLM + 上下文 + 工具（Ch1）

• 三层读法：实现层（LLM / 上下文 / 工具）、直觉层（大脑 / 眼睛 / 手脚）、RL 层（Policy / Observation Space / Action Space）。
• 能力 = 观察空间 × 动作空间 × 模型。模型固定时，缺数据就补上下文，缺操作就补工具；先用模型替换实验判断瓶颈在模型还是在 Harness。
• ReAct 循环：想 → 做 → 看，直到响应中不再有工具调用。上下文 = 静态前缀（system + tools）+ 只追加的轨迹。
• Agent = Model + Harness。Harness 五要素：上下文管理、工具接口、约束、验证、纠正。只改 Harness 就能让 Terminal Bench 2.0 从 52.8% 升到 66.5%。
• Less structure, more intelligence：给清晰的目标和可组合的工具，程序只固化不变的边界；评估反复暴露稳定失败时，才升级为验证器或工作流。适配层终将被更强的模型内化（苦涩的教训）。
• 什么时候不用 Agent：优化提示词就能解决的不用；步骤固定或有合规顺序的，用工作流。
• 三层护栏：上下文层 < 执行层 < 数据层（越往后越难绕过）。安全校验只读结构化字段；不可逆操作要用上下文之外的机制复核，并有人在回路。

2. 上下文工程：前缀稳定，只追加（Ch2）

• KV Cache / Prompt Cache：从第一个不同的 token 起全部重算；缓存读取价格约为 1/10。缓存本身是架构约束：它决定提示词的顺序、动态信息放在哪里、子 Agent 怎么设计。有了 preserved thinking，前缀变动从性能问题变成正确性问题。
• 时间、状态、新工具这类动态信息追加到末尾，不改 system prompt 或 tools。工具结果一律用 tool 角色返回。
• 系统提示词要写成流程驱动的 SOP，不要堆规则；有歧义的业务规则由产品经理写成硬规则；few-shot 每类 2–3 个固定示例。
• 上下文学习是检索，不是推理：上下文窗口像一个"只有一半的检索引擎"，所以要主动提炼结论，不让模型每次从原始记录里重算。
• Agent 状态栏：代码维护 TODO、计数、时间、环境，作为 user 消息放在末尾，思考成本约降一个数量级。
• 压缩：超过窗口约 80% 才一次批量压缩；隔离优于压缩，大体积探索交给子 Agent。
• Skills 渐进式披露：目录（写成路由条件的 description）常驻，正文按需加载。
• 提示注入是上下文安全的核心威胁：外部内容永远只当数据，不当指令。

3. 记忆与知识（Ch3）

• 记忆能力分三层评估：基础回忆 → 多会话检索 → 主动服务。
• 双层架构：JSON Cards 常驻概览，细节用上下文感知检索按需取。User as Code 用确定性函数处理聚合和冲突。
• 冲突处理：只追加带时间的事实，在检索时判断（Mem0 v3 的 LoCoMo 从 71.4 升到 92.5）。
• RAG 默认用混合检索：稠密 + BM25 → RRF → 重排序。上下文感知检索能把失败率降 49%/67%。需要跨文档综合时才上 RAPTOR 或 GraphRAG；统计类和否定类问题要在索引期提炼摘要。
• 知识变更走 PR 流程：Proposer 提 diff，异源 Reviewer 对照证据审核，可回滚。

4. 工具：ACI 与能力形态（Ch4）

• 工具对应 Agent 的目标，而不是 API 端点（ACI、防呆）。大多数选错工具的原因是模型不知道工具"不能做什么"，所以描述要写清边界、反例和示例。
• 能力形态按四个维度决定：安全权限、参数复杂度、变更频率、模型能力。默认用通用执行器 + Skill；不可逆、需要审计、参数复杂或调用极频繁的，做专用工具。
• 参数必须原样传递，不做静默改写；需要组合多个工具时，用代码编排，中间结果不进入上下文。
• 工具很多（超过约 100 个）时，按需披露或主动发现（MCP-Zero、Tool Search），schema 追加到末尾以保住缓存。
• 执行安全分层：输入验证 → 权限 → 提议者-审核者（异源、能力相近）→ Sidecar 门控 → 事后验证 → 沙盒隔离 → 幂等设计。MCP 生态要防工具描述投毒和同名工具遮蔽。

5. Coding Agent 与代码元能力（Ch5）

• 七个核心工具：Code Interpreter、Bash、Read、Write、Edit、Glob、Grep，再加项目指令文件（CLAUDE.md、AGENTS.md）。
• Harness 四原则：约束优先于指导、验证自动化、反馈快且结构化、回退可靠（验收基线、执行边界、反馈信号、回退手段）。
• 分级故障恢复：先分类可否重试 → 退避重试 → 降级 → 最后才暴露给用户，每条路径设熔断；用重复调用指纹和空闲看门狗检测卡死。
• 安全：用命令语义解析代替关键字黑名单；致命三要素（私有数据 + 不可信内容 + 外部通信，持久记忆会放大风险）；只忠于委托方。
• 代码是元能力：可以做思考工具、规则约束（参数 checklist + 服务端真值）、多媒体生成（Proposer-Reviewer 渲染反馈）、Artifact 模式、生成式 UI（A2UI）和 Agent 自举。

6. 交互：沿模态与时机扩展（Ch6）

• 回合制只是约定，不是环境的性质。事件处理分取消式、队列式、并行式，只在安全点消费事件；同步接口上用占位 result 加任务句柄（initiate_*）实现异步。
• 语音：快慢思考分离，前台快模型维持对话，后台慢模型推理。
• Computer Use：能拿到 DOM 或 Accessibility Tree 就用结构化索引，否则用 SoM 或坐标预测；世界模型只能用来比较候选动作，不能代替验收。
• 机器人：只开放有边界的技能工具，每步都重新观察；VLA 配合动作分块。

7. 评估：把分数变成决策（Ch7）

• 四个环节：成功定义 → 任务来源 → 验证方式 → 决策。评估对象是模型 + Harness。
• 高风险业务报 Pass^k，不报 Pass@k（p=0.6 时 Pass@5≈99%，Pass^5≈7.8%）。
• 环境要有真实的用户模拟（渐进式信息透露、双控、事实锚定）和可靠的验证器（FAIL_TO_PASS + PASS_TO_PASS），并防止数据泄漏。
• LLM-as-a-Judge：Rubric 四准则加 Veto；多源异构评判并交换位置。
• 失败归因到首错 → 转成端到端回归和轨迹前缀回归用例。
• 统计：100 个用例的 95% 置信区间约 ±9pp，要配对检验、多种子。分数下降时先审评测系统本身。每轮只改一个变量。

8. 后训练：先验 > 环境 > 算法（Ch8）

• 按诊断选阶段：pass@k≈0 → Mid-training；格式解析失败 → SFT 或约束解码；已有非零成功率且有可靠奖励 → RL。SFT 偏记忆，RL 偏泛化（GeneralPoints 的 OOD 成功率，RL 从 23.6% 升到 41.2%，SFT 降到 13.7%）。
• GRPO 用组内相对优势；on-policy 要求训练与推理引擎的数值一致（长序列会放大 log prob 误差）。
• 奖励设计：RLVR 可验证奖励；RLVP 奖励结果、惩罚路径；警惕 reward seeking。
• 样本效率：拒绝采样、On-Policy Distillation、OPSD；生产中的问题案例转成 DPO 数据，同时看边界集和保留集。
• LoRA 挂到所有主要矩阵，学习率约为全参的 10 倍。

9. 持续进化：证据 → 验证 → 更新 → 发布（Ch9）

• 三层验证器：结果 → 过程 → 质量，最先建结果验证器；证据不足的案例不进入学习。
• 四种更新载体：知识库、Prompt/Skill、程序/Harness、参数。能用代码判定的写进 Harness。
• 更新只做带来源的最小 diff，在边界集（必须改善）和保留集（不能退化）上同时测。要分别测"更新能力"和"受益能力"：Skill 写对了也可能没被加载或没被遵循。
• 在线循环只记录证据，离线循环负责提案和验证；可信根（验证器、门槛、审计日志）必须在被修改者的权限之外。外部内容永远不能写成 Skill 里的指令。

10. 多 Agent：只有引入新信息才值得（Ch10）

• 新信息判据：协作只有引入执行、视觉、工具反馈这类生成时拿不到的信息，才优于等计算量的单 Agent。
• 两个维度分类：上下文共享与否 × 协作拓扑，再借用操作系统的成熟方案（IPC、进程管理、并发控制）。
• 共享上下文时只切换 system prompt 和工具；不共享时用移交包加虚拟文件系统。角色差异只在知识或风格上时用 Skill，涉及权限时用独立 Agent。
• 控制平面：消息信封、进度文件、级联终止、settle_once。Loop 工程让验证器来判定何时停止（MEA 循环）。
• 最强的模型给 Planner 或 Manager（弱规划者是最关键的瓶颈）。失败模式：拜占庭故障、同质趋同、理解债。

---

章节索引

#	标题	关键框架
ch01	AI Agent 入门（含引言、后记）	Agent=LLM+上下文+工具、Harness 五要素、ReAct、工作流 vs 自主、三层护栏、模型选型
ch02	上下文工程	消息角色、KV/Prompt Cache、缓存作为约束、系统提示词、Skills、状态栏、压缩、子 Agent 隔离
ch03	用户记忆和知识库	三层次记忆评估、JSON Cards、User as Code、混合检索、RAPTOR/GraphRAG、上下文感知检索
ch04	工具	ACI、专用工具 vs Skill、工具描述、MCP/Skill Hub、主动工具发现、Sidecar、幂等
ch05	Coding Agent 与通用 Agent	七工具、Harness 四原则、故障恢复与熔断、致命三要素、代码元能力、A2UI
ch06	交互：观察与动作空间的扩展	事件处理三策略、任务句柄、快慢思考、Computer Use/SoM、VLA、世界模型
ch07	Agent 的评估	Pass^k、τ²-bench 双控、验证器、Rubric/Veto、失败归因、统计显著性、可观测性
ch08	模型后训练	Mid-training/SFT/RL 选择、GRPO、训推一致、RLVR/RLVP、蒸馏、LoRA
ch09	Agent 的持续进化	三层轨迹验证、四种更新载体、变更契约、边界集/保留集、睡眠学习、可信根
ch10	多 Agent 协作	新信息判据、共享/隔离上下文、控制平面、Loop 工程/MEA、A2A、失败模式、Agent 社会

主题索引

• A2A / 消息总线 / 协作拓扑 → ch10
• A2UI / 生成式 UI / Artifact → ch05
• ACI / 工具描述 / 参数保真 → ch01, ch04
• Agent Skills / 渐进式披露 → ch02, ch04, ch09
• Agent 状态栏 → ch02
• Chat Template / 消息角色 / tool_call_id → ch02
• Coding Agent 七工具 / CLAUDE.md → ch05
• Computer Use / GUI 定位 / SoM → ch06
• GRPO / PPO / RL 算法 → ch08
• Harness 工程 → ch01, ch05, ch09
• KV Cache / Prompt Cache / 缓存友好 → ch02, ch04
• LLM-as-a-Judge / Rubric → ch07
• Loop 工程 / MEA / Graph 工程 → ch01, ch10
• LoRA / SFT / Mid-training → ch08
• MCP / Skill Hub / 工具供应链安全 → ch04
• Pass@k / Pass^k → ch07, ch08
• RAG / 混合检索 / 重排序 → ch03
• ReAct 循环 → ch01, ch02
• Sidecar / 提议者-审核者 → ch04, ch05, ch10
• τ²-bench / SWE-bench / OSWorld / AndroidWorld → ch07, ch09
• VLA / 机器人 / XLeRobot → ch06
• 上下文压缩 / Context Rot → ch02
• 故障恢复 / 熔断 / 看门狗 → ch01, ch05
• 后训练阶段选择 → ch08
• 护栏 / 人在回路 → ch01, ch04
• 记忆评估 / 记忆存储格式 → ch03
• 经验知识 / 系统提示学习 → ch09
• 沙盒 / microVM / 命令语义解析 → ch04, ch05
• 失败归因 / 回归用例 → ch07, ch09
• 提示注入 / 致命三要素 → ch02, ch04, ch05, ch09
• 统计显著性 / 配对比较 → ch07
• 推测执行 / 世界模型 → ch06
• 系统提示词（SOP、few-shot、业务规则） → ch02
• 异步事件 / 打断 / 任务句柄 → ch06
• 语音 / 全双工 / 快慢思考 → ch06
• 蒸馏 / OPSD / 拒绝采样 → ch08
• 主动工具发现 / Tool Search → ch02, ch04
• 子 Agent 隔离 → ch02, ch10
• 自我修改 / 可信根 / 睡眠学习 → ch09
• 奖励设计 / RLVR / RLVP / reward seeking → ch08
• 模型选型 → ch01, ch07

配套文件

• glossary.md：全部关键术语及定义
• patterns.md：全部技术与设计模式（何时用、怎么做、权衡）
• cheatsheet.md：决策表、阈值、危险信号

---

范围与限制

本 skill 只覆盖书中内容。书中的模型、产品和 benchmark 数字对应成书时（2025–2026 年）的状态，模型迭代很快，用于决策前请在自己的任务上重新评估。原书的 115 张图片没有读取。配套实验代码见 bojieli/ai-agent-book 各章的 chapterX/ 目录。