pi × DeepSeek Harness 读书指南 总览 读懂 dsh 逐项深挖 故障与恢复 dsh 学习手册 pi 学习手册

对比/读书指南

Reading Guide

用《深入理解 AI Agent》
读 pi 与 dsh

前两个手册回答的是「它是什么」——pi 和 dsh 各自怎么运作,每句话都挂着 path:line。 这本开源书回答的是另一个问题:「一个 harness 按道理应该有什么」。 前者让你看懂两份代码,后者让你能判断这两份代码缺了什么。 这篇笔记把书的框架落成两张体检表,每条判断都回到源码核对。

书 《深入理解 AI Agent》 版本 2.0 10 章 / 109 实验 / 15 语种 许可 Apache-2.0 锚定 commit dbc046e
01

这本书是什么,为什么它正好补上我们的缺口

《深入理解 AI Agent:设计原理与工程实践》。作者把在图灵《AI Agent 实战营》和国科大的课程讲义, 加上在 Pine AI 做长流程、高风险任务(账单协商、退款投诉、订阅取消)的一线经验,重构成十章。 全部开源:正文、配图、109 个配套实验。

它只有一条主线,但有两个层次

全书反复使用的骨架只有一个,就是引言里那个公式:

Agent = LLM + 上下文 + 工具
大脑 + 眼睛 + 手脚。严格说「眼睛」是粗略类比——上下文里还包括工具定义,所以模型「看到」的信息里也包含「有哪些手脚可用」。
— 引言

但到了生产形态,同一条公式被展开成五格。这是全书对我们最有用的一个式子:

chapter1.md:271-275
Agent = Model + Harness
Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正
Agent <-> Environment

书把前三项叫「让 Agent 能做事」,后三项叫「让 Agent 不做错事」,并给出一条很强的时间判断: 早期框架都在做前三项,生产级系统的重心已经移到后三项。 佐证是它对 Claude Code 的观察——「它的 Harness 中绝大部分代码都是约束、验证与纠正,而非上下文与工具」。

它的结构:先建,再变强

部分章主题这一章真正在回答什么
如何构建
Agent
1AI Agent 入门公式的三层理解、ReAct 循环、编排光谱、Harness 五要素
2上下文工程全书最关键:API 消息结构、KV Cache、提示工程、Skills、状态栏、压缩策略
3用户记忆与知识库跨会话持久化:四种记忆格式、RAG 全栈、智能体化 RAG
4工具工具形态(专用/通用执行器/Skill)、MCP、工具太多怎么办
5Coding Agent 与通用 Agent最贴近 pi 的一章:Coding Agent 的 Harness 实践、故障分类与恢复、代码作为元能力
6交互观察与动作空间的扩展:异步事件、语音、Computer Use、机器人
如何提升
能力
7Agent 的评估评估环境、Pass@k 与 Pass^k、LLM-as-Judge、失败归因
8模型后训练SFT / RL / 蒸馏:把能力写进参数
9持续进化把经验写成知识、指令、程序、参数;有 dsh 专节
10多 Agent 协作共享/不共享上下文、拓扑、Loop 工程、提议者-审核者、失败模式

它为什么对我们特别合适:书里直接点名了这两套系统

这是我在读之前没料到的。第一章的框架对比表里,两行就是我们要读的对象:

书里的行核心定位编排模式开发方式 / 适用场景
DeepSeek HarnessAgent 自进化框架一切皆插件代码优先,方便定制;面向 Agent 开发者、研究者
Pi极简 Coding Agent 框架自主代码优先,方便定制;面向 Agent 开发者

出处:chapter1.md:442。 第九章还给了 dsh 一个完整专节 —— chapter9.md:228, 用 Cordis 论文的时间/空间可组合性解释了「为什么 dsh 要让主循环也变成插件」。这一层理论解释我们的 dsh 手册没有,值得补进去。

02

最大的收获:一把能同时量 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。

为什么这把尺子比「行数」有用:行数会随重构大幅波动,职责不会。 一个 harness 是不是「成熟」,取决于它有没有把后三项做进代码—— 而且必须是代码,不是文档。书里那句话很硬:「能用代码强制的规则就不要用文档建议……前者是『做不了』,后者只是『建议别做』。」
03

★ 两项体检:把五要素落到 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 条最小改造清单。

这一格怎么用:如果你要拿 pi 或 dsh 去做无人值守的长时任务,书这一章就是你的缺口清单。 「无步数上限 + 无熔断 + 无死循环检测」在交互式使用下几乎无害(你在看着), 在长时运行下就是三个真问题——这也解释了为什么 dsh 要单独做 durable 调度层、pi 要把 durable 拆成独立包。
04

★ 五个设计模式,正好能在源码里指出来

书在第一章末尾一次性命名了五个「贯穿全书的设计模式」。我把它们当成检索关键词回仓库搜了一遍, 结果是:四个能一一对上,一个都找不到内建实现。这个对不上的那一个,恰好是最有信息量的。

模式书的定义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》—— 没有外部反馈时让模型自查自改,把正确答案改错的次数比把错误答案改对的次数更多。 所以「提议者—审核者」的最小不变量不是两个角色,而是审核者必须读到独立证据(测试输出、渲染结果、结构化参数), 而不是复述提议者的解释。这条判据可以直接拿来审你自己的扩展设计。

05

十章书 → 两本手册:读哪章、看哪页

左边是书,右边是我们已经写好的两本手册。不必按顺序读——按你当下想搞清的问题挑。

书的章节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「模型可以提出完成,但不能批准自己的完成」

三条路线

路线 A · 3 小时
只想补最短的那块。
  1. 第一章 Harness 工程那一节(约 40 分钟)→ 拿到五要素
  2. 第五章「Harness 工程在 Coding Agent 中的实践」+「故障与错误恢复」(约 80 分钟)
  3. 回到本篇第 03 节,对着两张体检表读一遍(约 20 分钟)
  4. 挑一格你最在意的,去源码里验证一次(约 40 分钟)
路线 B · 一整天
想真正理解「为什么是这些设计」。
  1. 第一、二章精读:公式 → API 消息结构 → KV Cache → 压缩(约 3 小时)
  2. 第四、五章精读:工具规模问题、Coding Agent 全流程(约 3 小时)
  3. 第九章 dsh 专节 + Cordis 的时间/空间可组合性(约 1 小时)
  4. 第七章评估(Pass^k)与第十章 Loop 工程,各读一半(约 1.5 小时)
路线 C · 两周
想把这套东西用在自己项目里。
  1. 全书通读一遍,实验挑做(书给了 109 个,标注了难度星级)
  2. 做实验 4-1(主动工具发现)与 2-10(六种压缩策略对比)——这两个最能改变直觉
  3. 用第五章的「故障四层分类」给自己在用的 harness 写一份缺口清单
  4. 用第七章的「边界集 + 保留集」给一次改动做回归设计
06

三处需要校准的说法,和这本书不适合做的事

书很好,但它是「原则」视角,不是「实现」视角。原则会滞后于实现。我核对时发现三处需要校准,都记在这里。

#书里的说法仓库里的现状结论
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 这个取舍的坐标

它不适合做的事

不要拿它当 API 手册
书里的代码是 Py骨架,刻意「不展开具体实现」。要抄实现还是得回仓库——这正是我们两个手册的用处。
不要指望它评审某个具体仓库
书对 pi 和 dsh 的论述集中在框架定位与 dsh 的可组合性理论,没有逐文件核对。本篇第 03 节做的正是这个补齐工作。
不要跳过实验
109 个实验里带星级的那些,是全书唯一「可复现」的部分。压缩策略对比、主动工具发现、跨厂商轨迹接管这三个,读结论和跑一遍是两种理解。
两本手册与这本书的关系,一句话说清: 书给你判据,手册给你证据。 单看书,你会知道 harness 该有约束、验证、纠正,但不知道 pi 和 dsh 到底有没有; 单看手册,你会知道每个文件在做什么,但不知道它为什么该存在、缺了什么。 把两边叠起来,才有第 03 节那两张表——而那两张表,才是这次读书真正的产物。

本章学习记录

记录仅保存在当前浏览器。