《深入理解 AI Agent》第一章读书笔记

第一章读书笔记：AI Agent 入门

书：《深入理解 AI Agent：设计原理与工程实践》 · 第 1 章 读法：本文管「读懂书」，每节末尾的 🔍 是源码路标，指向配套文档《01-第一章-ZCode源码对照》里对应的真实实现。

一、核心公式：Agent = LLM + 上下文 + 工具

Agent = 大脑 + 眼睛 + 手脚：

两个容易忽略的限定：

1. 加号是工程组件的组合，不是 RL 的形式化定义；三组件可映射到 RL 概念但非严格等同
2. 公式只描述 Agent 边界之内——Environment 不在公式里，但 Agent ↔ Environment 是闭环交互的两方（图 1-1 的双层结构：外层交互环，内层 Model–Harness）

生产形态展开：

Agent = Model + Harness Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正

书里特意澄清：Harness 是「Agent 边界内、模型之外」的运行与治理层——沙箱的权限机制属于 Harness，沙箱里随行动变化的文件属于 Environment；物理部署位置不决定归属（仿真环境和 Agent 同进程，它仍是 Environment）。

🔍 对照：仓库结构就是这条公式的物理形状——provider/（Model 侧）薄薄一片，harness 各包占九成体积。见源码对照·第 1 站。

二、最重要的工程判断：扩展眼睛和手脚

底层模型固定时，提升 Agent 表现最主要的系统工程手段，就是重新定义或扩展观察空间与动作空间。

很多看似「需要更聪明模型」的问题其实是接口问题。两个案例：

• Manus：把 Deep Research / Coding / Computer Use 三条线的观察+动作空间取并集 → 通用性来自接口边界的扩大
• OpenClaw：接口再外推一层——消息渠道（WhatsApp/Telegram…）做观察入口 + 本地 Gateway 连云应用与文件系统

共同特征：开放式动作空间（不是从几个按钮里选）、内部思考、持续交互调整。

🔍 对照：ZCode 的两个空间扩展——zcode-cua（浏览器/桌面控制）和 MCP 工具总线（mcp__服务__工具 三段命名挂载外部能力）。见源码对照·第 4 站。

三、上下文的五个组成部分（API 视角）

静态前缀（对话中不变）：

1. 系统提示词——Agent 的「岗位说明书」，含用户记忆与动态环境状态
2. 工具定义——名称/描述/参数 schema

动态轨迹（随交互增长）： 3. 用户消息（可能含 RAG 检索的外部知识） 4. 模型回复（reasoning + content + tool_calls，三者不必同时出现） 5. 工具执行结果——下一步思考的直接依据

Agent 的上下文 = 静态前缀 + 轨迹

实验 1-1（消融）的三个反直觉发现：

• 去掉工具定义 → Agent 不会沉默，会给一份格式工整、语气笃定、数据来自参数记忆的幻觉答案（和真答案排版一模一样）；约束词只能降低概率，不能消除
• 去掉工具结果 → 盲目重试直到耗尽迭代预算
• 衡量组件重要性的标准：它承载的信息能否从别处重建——reasoning 可从工具结果重建时，丢掉几乎没有代价
• 最重要的一条：「给出了回答」≠「完成了任务」

🔍 对照：context/builder.ts 里系统提示词的真实组装方式——不是一段话，是一叠可组合的 Section。见源码对照·第 2 站。

四、ReAct 循环

想 → 做 → 看，循环直到任务完成。书的最小骨架：

trajectory = [user_request]
repeat:
    context = stable_prefix + trajectory
    decision = Model(context)
    trajectory.append(decision)
    if decision has no tool call:
        return decision.answer
    for call in decision.tool_calls:        # 独立调用可并行
        validated_call = Harness.validate(call)
        observation = Environment.execute(validated_call)
        trajectory.append(observation)

注意骨架里 Harness.validate 已经出现——验证不是外挂，长在循环里。轨迹的价值：可解释、可调试、可分析、可沉淀（进知识库或 RL 训练）。

🔍 对照：教科书伪代码是 5 行，ZCode 的实现是一个 10 相位状态机——多出来的相位（AwaitingPermission、AggregatingResults）正是书里「约束」要素渗入循环骨架的痕迹。见源码对照·第 1 站（本篇最重要的一站）。

五、Harness 工程：模型之外的竞争力

生产级 Harness 的绝大部分代码是约束、验证与纠正，而不是上下文与工具本身（Claude Code 为例）。

三个核心构建原则（Anthropic）：保持简单 / 保持透明 / 设计好 ACI（从 Agent 视角设计接口，防呆 Poka-yoke：SIM 卡缺角、微波炉门联锁）。

《苦涩的教训》与 Harness 的节奏：模型会持续吃掉 Harness（few-shot、JSON 容错、提示词改写都已被内化），但节奏比想象慢——训练以月计，业务约束无法一次内化。模型此刻的能力边界，就是 Harness 此刻的价值所在；模型每内化一层，Harness 卸下一层，转而兜底新的前沿。

🔍 对照：bash-command-permission-policy.ts 里的高危命令集合与 shell 包装器解析——「约束」的代码长相。见源码对照·第 3 站。

六、工程范式演进弧线

提示工程 ⊂ 上下文工程 ⊂ Harness 工程 ⊂ Loop 工程 ⊂ Graph 工程（层层包含，不是替代）

例证：LangChain 在 Terminal Bench 2.0 从 52.8% → 66.5%，换的不是模型，是 Harness（自检、循环检测、思考策略）。模型能力趋同时，竞争优势转移到模型之外。

七、编排模式：工作流 vs 自主 Agent

选择顺序：先单次调用 → 再工作流 → 最后才自主 Agent。

两条高级心法：

• Manus 的「Less structure, more intelligence」：程序只固化必须永远成立的边界（权限、不得覆盖原始数据、原子发布），把边界内的决策空间还给模型
• 混合形态：Agent 先把工作流写出来，工作流再去执行——自主生成确定性

🔍 对照：ZCode 里两套编排并存——agent/（ReAct 自主）+ dynamic-workflow/（我写编排脚本、执行时退回确定性、journal 提供只增不改状态）。见源码对照·第 6 站。

八、护栏三层（按被绕过的难度排序，越往下越硬）

1. 上下文层（管能看到什么）：分类器/审核/规则过滤——结构性上限：同一上下文里的 Agent 难以判断自己是否已被注入
2. 执行层（管能做什么）：工具风险评级、沙箱、最小权限、人在回路——必须由上下文之外的机制完成，否则和被注入的 Agent 一起沦陷
3. 数据层（管世界最终被改成什么样）：行级安全、约束校验——即使前两层全破，越权仍在数据层被拒绝

人工干预两个触发：超过失败阈值 / 高风险操作。护栏还要防误拒绝（合法但形式敏感的任务被错杀）。

九、五个贯穿全书的设计模式

1. 提议者—审核者：产出与评判分离，审核者看产物不看推理过程（前提：自审不可靠）
2. 渐进式披露：目录常驻、细节按需加载（Skills 是典型形态）
3. 只增不改：追加式演进 → 可缓存、可重放、可审计（KV Cache 前缀稳定性的来源）
4. 边界集 + 保留集：每次修改在「应改变的」和「不应影响的」两组样本上同时验证
5. 最小 diff + 可回滚：小改动、带来源、可单独回滚 → 归因成为可能

🔍 对照：skills 加载的三个硬常数（250 字符 / 20000 token 预算 / cacheHint）——渐进式披露落成三行配置。见源码对照·第 5 站。

十、思考题（挑了四道最值得想的）

• Q1 只能加一项：更强模型 / 更丰富上下文 / 更多工具，选哪个？什么条件下改变？
• Q3 「模型即 Agent」越来越自主，为什么 Harness 反而更重要？
• Q4 除了工具结果缺失，还有什么会让 Agent 死循环？怎么设计检测与终止？
• Q7 delete_file 删普通文件 vs 删系统文件——动态风险评级怎么做？（提示：对照源码第 3 站的 HIGH_RISK_ROOT_COMMANDS 思考「命令级」之外还需要什么粒度）

一句话总结

模型是大脑，上下文是眼睛，工具是手脚；模型固定时，能力杠杆在接口；模型商品化后，竞争力在 Harness——让 Agent 从「能做事」走到「可靠地做事」。