对比/读书指南
用《深入理解 AI Agent》
读 pi 与 dsh
前两个手册回答的是「它是什么」——pi 和 dsh 各自怎么运作,每句话都挂着 path:line。
这本开源书回答的是另一个问题:「一个 harness 按道理应该有什么」。
前者让你看懂两份代码,后者让你能判断这两份代码缺了什么。
这篇笔记把书的框架落成两张体检表,每条判断都回到源码核对。
这本书是什么,为什么它正好补上我们的缺口
《深入理解 AI Agent:设计原理与工程实践》。作者把在图灵《AI Agent 实战营》和国科大的课程讲义, 加上在 Pine AI 做长流程、高风险任务(账单协商、退款投诉、订阅取消)的一线经验,重构成十章。 全部开源:正文、配图、109 个配套实验。
它只有一条主线,但有两个层次
全书反复使用的骨架只有一个,就是引言里那个公式:
但到了生产形态,同一条公式被展开成五格。这是全书对我们最有用的一个式子:
Agent = Model + Harness Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正 Agent <-> Environment
书把前三项叫「让 Agent 能做事」,后三项叫「让 Agent 不做错事」,并给出一条很强的时间判断: 早期框架都在做前三项,生产级系统的重心已经移到后三项。 佐证是它对 Claude Code 的观察——「它的 Harness 中绝大部分代码都是约束、验证与纠正,而非上下文与工具」。
它的结构:先建,再变强
| 部分 | 章 | 主题 | 这一章真正在回答什么 |
|---|---|---|---|
| 如何构建 Agent | 1 | AI Agent 入门 | 公式的三层理解、ReAct 循环、编排光谱、Harness 五要素 |
| 2 | 上下文工程 | 全书最关键:API 消息结构、KV Cache、提示工程、Skills、状态栏、压缩策略 | |
| 3 | 用户记忆与知识库 | 跨会话持久化:四种记忆格式、RAG 全栈、智能体化 RAG | |
| 4 | 工具 | 工具形态(专用/通用执行器/Skill)、MCP、工具太多怎么办 | |
| 5 | Coding Agent 与通用 Agent | 最贴近 pi 的一章:Coding Agent 的 Harness 实践、故障分类与恢复、代码作为元能力 | |
| 6 | 交互 | 观察与动作空间的扩展:异步事件、语音、Computer Use、机器人 | |
| 如何提升 能力 | 7 | Agent 的评估 | 评估环境、Pass@k 与 Pass^k、LLM-as-Judge、失败归因 |
| 8 | 模型后训练 | SFT / RL / 蒸馏:把能力写进参数 | |
| 9 | 持续进化 | 把经验写成知识、指令、程序、参数;有 dsh 专节 | |
| 10 | 多 Agent 协作 | 共享/不共享上下文、拓扑、Loop 工程、提议者-审核者、失败模式 |
它为什么对我们特别合适:书里直接点名了这两套系统
这是我在读之前没料到的。第一章的框架对比表里,两行就是我们要读的对象:
| 书里的行 | 核心定位 | 编排模式 | 开发方式 / 适用场景 |
|---|---|---|---|
| DeepSeek Harness | Agent 自进化框架 | 一切皆插件 | 代码优先,方便定制;面向 Agent 开发者、研究者 |
| Pi | 极简 Coding Agent 框架 | 自主 | 代码优先,方便定制;面向 Agent 开发者 |
出处:chapter1.md:442。 第九章还给了 dsh 一个完整专节 —— chapter9.md:228, 用 Cordis 论文的时间/空间可组合性解释了「为什么 dsh 要让主循环也变成插件」。这一层理论解释我们的 dsh 手册没有,值得补进去。
最大的收获:一把能同时量 pi 和 dsh 的尺子
我们之前比较 pi 和 dsh,用的是「代码行数、包数、插件数」——第 12 章里我自己也承认过,行数只能证明规模,不能证明质量。 书给的这把尺子不是数量,而是职责:一个 harness 该管五件事,看它每件管到什么程度。
五要素各自的判据(书里的原文要求)
| 要素 | 职责与核心原则 | 书给的实例 |
|---|---|---|
| Context 上下文 |
为模型提供感知信息;信息要充分,让 Agent 在每个决策点都基于足够的信息判断 | 系统提示词、知识库、Agent 状态栏、Sidecar 旁路查询 |
| Tools 工具接口 |
提供观察与行动手段;接口要清晰,命名直观、参数有例子、边界有说明 | MCP 工具、代码解释器、搜索工具 |
| Constrain 约束 |
设定行为边界;故障安全默认值,所有能力默认关闭,必须显式开放(像手机 App 权限管理) | Claude Code 中每个工具默认需要用户授权 |
| Verify 验证 |
自动判断结果对错;只看结构化数据(工具返回的 JSON 字段),不看模型自由生成的文本,因为后者可能已被提示注入操纵 | Linter、类型系统、工具调用结果校验 |
| Correct 纠正 |
发现问题时自动修正或回退;在确认无法恢复之前不暴露中间态 | 静默重试、接续生成、连续失败熔断、回退人工 |
出处:chapter1.md:263(Harness 工程), 与第二章至第五章的映射见 chapter1.md:506。
★ 两项体检:把五要素落到 pi 与 dsh 的源码
下面每一格都是我回到仓库里核过的,不是转述。判断标准统一:这一项是「框架内建」还是「推给宿主/外部」。
3.1 上下文管理:两边都强,风格相反
| 系统 | 做法 | 证据 |
|---|---|---|
| pi | 会话本身就是只增不改的树,落在 JSONL 里;压缩有明确的预算双参数:保留最近 20,000 token、预留 16,384 token | session-manager.ts:977 · settings-defaults.ts:11-12 |
| dsh | 先立一条原则:「Model-visible means logged」——每个模型请求都必须能从日志重建;插件想改消息内容,只能注册纯投影。会话格式还带代际规则:已提交的代际路径永不改名、替换或删除 | architecture.md:128 · architecture.md:126 |
书的第二章正好给了这套东西的理论名:只增不改(Append-only)。 而它对压缩的三种动机、以及「压缩必然破坏前缀缓存」的分析,比 pi 自己的博客更细—— 尤其是它指出「摘要旧轮 + 原样保留最近几轮」在 thinking 绑定前缀时会整段失效,而 pi 恰恰是保留最近 20k 的策略。 这不是说 pi 错了,而是说:书让你看见这个取舍的代价在哪。
3.2 工具接口:一个走「少而准」,一个走「可组合」
| 系统 | 做法 | 证据 |
|---|---|---|
| pi | 内置只有四个工具(read / write / edit / bash);规模问题用暴露级别解决——MCP 工具可以「声明给模型」「只给 codemode」「两者都不」,还有 tool_search 按需加载 |
docs/cli.md:156 · tools/read.ts:94 |
| dsh | 工具注册表本身就是一个插件(packages/core/tools);执行器还分成原生与 PTC 两种(tool-executor-native / tool-executor-ptc),工具集可按插件装载/卸载 |
architecture.md:11 |
书第四章把这个问题讲透了:工具超过一百个,模型选错的概率显著上升;全量平铺既吃 token 又每次变动都击穿 KV Cache。 它给的三层答案是「层次化按需加载 → 主动工具发现 → Skills」。 回头看:pi 的 codemode + tool_search 落在第二层,dsh 的插件化注册表落在更底层的「可组装」—— 两者都没走书里最轻的那条(Skills 当参考手册翻),这解释了为什么 pi 要一个 JS 沙箱、dsh 要一套插件生命周期。
3.3 约束:这是两边分歧最大的一格
| 系统 | 做法 | 证据 |
|---|---|---|
| pi | 没有逐次审批机制。文档写得很直白:「它不会在每次工具调用前请求批准」;安全边界来自操作系统或虚拟化,而不是对话框。「看着转录、项目信任、review 变更」都不构成安全边界 | docs/security.md:3 · security.md:7 |
| dsh | 有独立审批件:APPROVAL_POLICIES = ['ask', 'never'];沙箱拆成四个包(sandbox / sandbox-local / sandbox-policy / sandbox-windows-acl),并且是 dsh-base 的标配 |
user-approval/index.ts:71 · architecture.md:23 |
书把「故障安全默认值、能力默认关闭、显式开放」列为约束的核心原则,dsh 是这条原则的实现,pi 是刻意的反面。 但注意 pi 并非不设防——它把边界下移了一层:不是逐个动作问你,而是把整个进程关进容器。 这两种做法对应两种信任模型,书的判据并不判定谁对,但它会追问一句:你的默认值是什么? pi 的默认值是「全开 + 靠 OS 隔离」,dsh 的默认值是「可配置 ask/never + 多层沙箱」。
3.4 验证与纠正:两个开源 harness 都薄在这里
这一格是我读完书之后专门去搜的,结论比较意外,也比较有价值。
| 书要求的能力 | pi 的现状 | dsh 的现状 | 判断 |
|---|---|---|---|
| 验证:自动判断结果对错 | 内核不内置 linter/test 校验,靠外部 CI 与扩展 | 不在内核,靠 extensions 挂钩子 | 都推给外部 |
| 纠正:连续失败熔断 | 搜遍 packages/*/src 无 circuit / breaker 实现;durable/scheduler.ts 反而注明「计数可以交给 host,例如用于熔断」 |
同样未见内核熔断实现 | 都没有 |
| 纠正:最大迭代轮数上限 | 内核无 maxSteps / maxIterations;agent-loop.ts:188 是 while (true),跑到模型不再调用工具为止 |
同样未见 | 都没有 |
| 纠正:重复调用指纹 / 死循环检测 | 未见 | 未见 | 都没有 |
这不是「它们做得差」,而是定位不同。书在第五章明确说:生产级 harness 会维护一张「错误 → 恢复策略」的映射表, 每条恢复路径都有熔断上限,阈值来自真实会话统计(Claude Code 的「连续 3 次」来自一次会话连续失败三千余次的教训)。 Claude Code 是产品,所以它必须自带这些;pi 和 dsh 是框架,它们把这些留给宿主。 书对 Coding Agent 的四句原则里,前三句(约束优先、验证自动化、反馈结构化)都可以外置,第四句「回退要可靠」不行——而回退恰好是 git 的事。
→ 这一格已经单独展开成一篇:故障 → 恢复映射表——四层故障逐层核对两家的真实实现, 含「文档写了抖动但代码没做」这类实测发现与 6 条最小改造清单。
durable 调度层、pi 要把 durable 拆成独立包。
★ 五个设计模式,正好能在源码里指出来
书在第一章末尾一次性命名了五个「贯穿全书的设计模式」。我把它们当成检索关键词回仓库搜了一遍, 结果是:四个能一一对上,一个都找不到内建实现。这个对不上的那一个,恰好是最有信息量的。
| 模式 | 书的定义 | pi 的落点 | dsh 的落点 |
|---|---|---|---|
| 只增不改 Append-only |
状态以追加方式演进,已写下的不再回头改。换来可缓存、可重放、可审计 | 会话是 append-only 树,存 JSONL | 代际路径永不改名/替换/删除;模型可见即可重建 |
| 渐进式披露 Progressive Disclosure |
先给可检索的目录,按需加载细节。同时优化上下文预算与选择精度 | tool_search 加载 codemode / deferred 暴露的工具 |
工具注册表本身是可装卸插件,能力按插件层渐进装配 |
| 最小 diff + 可回滚 | 每次修改尽量小、带来源、可单独回滚,让归因成为可能 | edit 工具就是精确文本替换(每处必须唯一、不重叠) | patch 按 id 替换整行配置或插入新行,多层叠加有优先级 |
| 边界集 + 保留集 | 任何修改都要同时在「应当改变」与「不应影响」两批样本上验证 | 两边都无内建评估集——这正是书第七章存在的理由,也是两个仓库最该补的一课 | |
| 提议者—审核者 | 产出与评判由不共享上下文的两个角色承担;评判方看产物不看推理 | 内核无此机制 | 有能力挂:扩展钩子支持 waterfall 的 deny / ask / next |
dsh 钩子那条的证据:
hooks-claude-code/index.ts:243。
注意它在 packages/experimental/ 下——能力存在,但不在稳定面。
书的提示很值得记住:不能让同一个 Agent 自审。它引用 ICLR 2024 那篇《Large Language Models Cannot Self-Correct Reasoning Yet》—— 没有外部反馈时让模型自查自改,把正确答案改错的次数比把错误答案改对的次数更多。 所以「提议者—审核者」的最小不变量不是两个角色,而是审核者必须读到独立证据(测试输出、渲染结果、结构化参数), 而不是复述提议者的解释。这条判据可以直接拿来审你自己的扩展设计。
十章书 → 两本手册:读哪章、看哪页
左边是书,右边是我们已经写好的两本手册。不必按顺序读——按你当下想搞清的问题挑。
| 书的章节 | pi 手册对应 | dsh 手册对应 | 读完能补上的那一块 |
|---|---|---|---|
| 1 入门 · Harness 五要素 | 01 心智模型 | 01 心智模型 | 把「四层」升级成「五职责」,知道缺哪一环 |
| 2 上下文工程 | 06 会话与上下文 | 06 会话与上下文 | KV Cache 为什么会成为架构约束,压缩的三个动机 |
| 3 记忆与知识库 | 06 会话与上下文 | 06 上下文 | 跨会话持久化:pi 的会话树 vs dsh 的投影,还缺什么 |
| 4 工具 · 工具太多怎么办 | 05 关键机制 | 03 架构 | codemode / deferred / tool_search 为什么长这样 |
| 5 Coding Agent 实践 | 04 一次提问 | 04 一次 turn | 故障四层分类、恢复分级、中立轨迹格式(最该读) |
| 6 交互扩展 | — | 06 上下文(部分) | pi 和 dsh 都还没走到这一步,属前瞻 |
| 7 评估 | 09 演进对比 | 09 规模对比 | Pass@k 看上限、Pass^k 看可靠性;为什么行数不是质量 |
| 8 后训练 | 09 演进对比 | 09 规模对比 | dsh 的 llm 层为什么要插件化到适配 pi-ai |
| 9 持续进化 | 08 扩展 | 08 扩展 | dsh 专节:时间/空间可组合性,为什么主循环也得是插件 |
| 10 多 Agent · Loop 工程 | 07 刻意不做 | 10 子 Agent | 「模型可以提出完成,但不能批准自己的完成」 |
三条路线
- 第一章 Harness 工程那一节(约 40 分钟)→ 拿到五要素
- 第五章「Harness 工程在 Coding Agent 中的实践」+「故障与错误恢复」(约 80 分钟)
- 回到本篇第 03 节,对着两张体检表读一遍(约 20 分钟)
- 挑一格你最在意的,去源码里验证一次(约 40 分钟)
- 第一、二章精读:公式 → API 消息结构 → KV Cache → 压缩(约 3 小时)
- 第四、五章精读:工具规模问题、Coding Agent 全流程(约 3 小时)
- 第九章 dsh 专节 + Cordis 的时间/空间可组合性(约 1 小时)
- 第七章评估(Pass^k)与第十章 Loop 工程,各读一半(约 1.5 小时)
- 全书通读一遍,实验挑做(书给了 109 个,标注了难度星级)
- 做实验 4-1(主动工具发现)与 2-10(六种压缩策略对比)——这两个最能改变直觉
- 用第五章的「故障四层分类」给自己在用的 harness 写一份缺口清单
- 用第七章的「边界集 + 保留集」给一次改动做回归设计
三处需要校准的说法,和这本书不适合做的事
书很好,但它是「原则」视角,不是「实现」视角。原则会滞后于实现。我核对时发现三处需要校准,都记在这里。
| # | 书里的说法 | 仓库里的现状 | 结论 |
|---|---|---|---|
| 1 | 第四章说 pi「核心模块刻意不内置 MCP」,优先用 CLI + Skills,需要时再通过扩展接入 | pi 的 README 里已无 "Philosophy: No MCP";MCP 现在是内建扩展 builtin:mcp,有 /mcp 命令与 docs/mcp.md,还能按 codemode/deferred 控制暴露 |
已过时(书引的是 2025-11-02 博客与旧 README 锚点) |
| 2 | 第一章框架表把 Pi 记为「极简 Coding Agent 框架 / 自主」 | 这个定位今天仍然成立,但 pi 已有 codemode、扩展体系、durable 分支;「极简」现在指的是入口(4 个工具、2,541 行循环层),不是整包体积 | 需要补一句限定,否则容易误读 |
| 3 | 第二章讲压缩时指出:保留最近几轮 + 摘要旧轮,在 thinking 绑定前缀时会整段失效 | pi 正是这个策略:keepRecentTokens: 20000 保留最近、旧轮做结构化摘要;pi 自己的博客也承认压缩必然打断缓存 |
不是错,是可用的诊断——书给了你评估 pi 这个取舍的坐标 |