封面与导览

这本书解决什么问题

一个 agent 出事故，通常不是因为模型「不会」，而是因为系统缺了一层：

• 循环没有预算，跑到天亮；
• 工具没有契约，模型把「读取」当成「修改」；
• 沙箱只做了文件只读，网络却全开；
• 上下文把约束摘要掉了，模型「合理地」违反要求；
• 评估只看最终答案，看不到工具调用错误；
• trace 只有日志，没有 span，出事无法回放；
• 安全靠提示词，治理靠文档。

本书按「机制 → 上下文 → 评估 → 治理」的顺序，把这些层逐一补上。每一章都给出可运行的实验、失败复盘与观测命令；两个项目把所有层拼成一个能跑、能测、能审计的系统。

怎么读

三条路线的共同点是：先建立边界，再谈能力。没有边界的 agent，能力越强，事故越大。

两个项目

两个项目共享同一套 trace 字段与工具契约；项目二可以直接评估项目一的 agent。先做哪个都行，但建议至少把项目一的沙箱 runner 跑通，再做项目二的评估。

与另外两本书的边界

如果你在这本书里看到大段 fork/信号/反向传播的教科书讲解，那是缺陷，不是覆盖。请按 附录 A 覆盖矩阵 回查落点。

为什么写这本书

1. 一个尴尬的事实

到了 2026 年，几乎每个团队都能在一个下午做出「会调用工具的 agent」；但能把 agent 稳定运行一周、出事能定位、改版不回归的团队，仍然是少数。

差距不在模型。同一个模型，在 demo 里能修 bug，在生产里会重复退款；在评测集上能拿高分，在真实用户面前会引用错文档；在提示词里被要求「不要删除文件」，却因为一次网页注入把仓库清空。这些事故的根因，几乎都能归到同一类：把 agent 当成一次模型调用，而不是一个系统。

一次模型调用只需要关心输入、输出与价格。一个系统还要关心：

• 循环靠什么停，预算怎么分，失败怎么退；
• 工具的能力边界、参数来源、幂等性与权限；
• 进程、文件、网络、资源四层隔离；
• 上下文里哪些能压缩、哪些不能；
• 记忆怎么写入、检索、引用、删除；
• 规划与多智能体的收益是否大于协调成本；
• 评估的置信区间、回归门禁与成本约束；
• trace、日志、指标、回放；
• 注入、外泄、投毒与供应链；
• 审计、最小权限、人工审批与合规。

这些主题横跨操作系统、分布式系统、安全工程、统计与产品设计。单独看，每一块都有成熟文献；连起来，才是一个 agent 平台。这本书做的就是「连起来」，并且只写模型之外的那一层。

2. 为什么是现在

2025–2026 年，agent 的工程接口终于开始标准化：

• MCP 从 2024-11-05 走到 2025-11-25，再到 2026-07-28。最新版把协议改成无状态、用 server/discover 协商版本、用 MRTR 取代 server-initiated requests，并弃用了 Roots/Sampling/Logging。这意味着「initialize 握手 + 会话」不再是唯一前提，实现者必须理解版本矩阵。
• OpenAI function calling 与结构化输出把「工具 schema」变成了模型接口的一部分；strict、parallel_tool_calls、流式增量、tool_call_id 都有明确语义。
• OCI Runtime Spec 1.3.0 把进程、namespace、capability、seccomp、rlimit 的配置固定成 config.json；agent 沙箱不必自己发明一套。
• OpenTelemetry GenAI/MCP 语义约定让 trace 有了可交换的字段名；没有它，每个平台的 trace 都是一座孤岛。
• NIST AI RMF、ISO/IEC 42001、EU AI Act 把「审计、风险管理、人工监督」从最佳实践变成可检查的义务。

标准化的好处是：你不需要从零发明协议；坏处是：版本变化很快，把旧版当永恒会写出过时的代码。本书的处理方式是：给出基线版本 + 迁移路径 + 判断依据，而不是抄一份规范。

3. 这本书不做什么

它不教你训练模型，不教你写 Transformer，不教你 Linux 内核，也不教你 TCP 三次握手。这些是《深度学习导论》与《Linux 系统与内核》的领土。本书在需要时给出交叉引用，并明确「为什么这个边界会影响 agent」。

它也不是框架手册。LangChain、LlamaIndex、AutoGen 等框架会变，机制不会。书里的代码尽量只用标准库，目的是让你看清每一层在做什么；换成任何框架时，你知道该检查哪些点。

它更不是「最佳实践清单」。每个方法都有适用条件与失败边界；书里会写「什么时候不要用」，而不是只写「应该用」。

4. 你怎么用这本书

如果你只有一周：读第 1、2、5、9、10 章，跑通第 1 章与第 9 章实验，建立一个能观测、能评估的最小闭环。

如果你有一个月：按「平台工程路线」读 1–4、9–12，做项目二；遇到沙箱细节再回第 3、4 章。

如果你在做安全评审：读 1–4、11、12，把项目一的红队用例跑一遍，再用附录 B 的五条勘误检查现有系统。

每章末尾都有「本章陷阱」与「出口检查」。陷阱表是从真实事故里抽出来的；出口检查是进入下一章的最低门槛。不要跳过出口检查——后面的章节默认你已经会了。

5. 一个请求

这本书的示例都尽量可运行、可复现。如果你发现某段代码跑不通、某个版本号写错、某条结论与你的实践不符，请把它当成缺陷而不是「风格问题」：记录你的环境、命令与输出，对照 附录 B 的勘误格式提出来。

Agent 系统工程还在快速变化。比「记住结论」更重要的是：知道每个结论依赖哪个版本、哪条假设、哪次实验。这本书试图把这种可检验性写进正文，而不是留给你去猜。

范围、取舍与边界

1. 本书的范围

本书讨论「模型之外、系统之内」的 agent 工程层。用一句话界定：

给定一个（可能不可靠的）模型，如何构造一个有状态、有工具、有预算、可观测、可评估、可治理的执行系统。

具体覆盖：

2. 明确的非目标

以下内容不写，或只在边界处引用：

这张表说明什么：边界不是「不重要」，而是「已经有人写得更专业」。本书的价值在于把边界接到 agent 的决策点上，而不是重复教科书。

3. 版本基线

Agent 工程的最大事实是：接口在变。本书把版本写在正文里，而不是假设「最新版」。

结论要带条件：例如「在 Linux 6.8 上，Landlock ABI 4 支持 TCP bind/connect 限制」，而不是「Landlock 支持网络」。版本一换，结论可能就不成立。

4. 取舍：为什么有些主题只给一章

4.1 为什么安全只有一章

安全很容易写成一套独立的卷：注入、外泄、供应链、模型窃取、对抗样本……但 agent 的安全边界是能力边界：只要不可信数据不能获得执行权，大部分攻击就失去杠杆。第 11 章围绕这一条展开，把具体攻击当作「能力边界失效的症状」，而不是另起一套分类。

治理（第 12 章）同理：它不是安全的下游文档，而是「谁在什么条件下能批准什么」的执行流程。两章分工是：第 11 章管「攻击面与防御」，第 12 章管「授权、审计与责任」。

4.2 为什么评估与观测分开

评估回答「这次改动是不是更好」，观测回答「这次运行为什么这样」。两者的数据都来自 trace，但方法不同：评估需要数据集、采样、统计与门禁；观测需要 span 模型、属性、日志、指标与回放。合成一章会变成两份内容的压缩，双方都讲不透。

4.3 为什么项目是两章而不是附录

项目不是「练习题」，而是把前面所有层拼起来的验收。项目一压沙箱与工具协议，项目二压评估与平台。每个项目都按 Stage 组织，每个 Stage 有可运行的验收命令；跳过项目，前面的章节很容易停留在「知道」而不是「做过」。

5. 方法论：路径、边界、证据

本书每一节尽量按同一顺序展开：

1. 路径：这件事在真实系统里怎么发生？给出调用链、数据流或时间线。
2. 机制：为什么是这样？给出状态转移、协议字段、内核对象或统计公式。
3. 边界：什么时候不成立？给出反例、版本差异、失败条件。
4. 证据：怎么验证？给出可运行实验、观测命令或 trace 片段。

如果一个结论只有「路径」没有「边界」，它大概率是营销；如果只有「机制」没有「证据」，它大概率是猜测。三者都有，才值得写进书里。

6. 读者假设

我们假设你：

• 能读 Python 与 C，能用命令行；
• 知道进程、文件描述符、HTTP 的基本概念；
• 用过至少一个 LLM API，见过 tool calling 的 JSON；
• 不要求你会训练模型，也不要求你读过内核源码。

如果你缺其中某一项，书里会给出指向《Linux 系统与内核》或《深度学习导论》的具体章节，而不是让你去搜「XX 入门」。

能力矩阵与学习路线

1. 能力矩阵

读完这本书，你应该能在下面每一行打勾。打不了勾的，去对应章节补，不要靠「大概知道」。

这张表说明什么：它不是知识点清单，而是可演示的行为。每一项都对应一个你能跑的命令或能画出的图；说不出来，就是没学会。

2. 三条学习路线

路线 A · 平台工程（约 35–45 小时）

适合要搭 agent 平台、工具网关、沙箱执行环境的工程师。

路线 B · 应用开发（约 25–35 小时）

适合做垂直 agent（客服、研究、编码助手）的开发者。

路线 C · 安全与合规（约 20–30 小时）

适合安全评审、风控、合规工程师。

3. 每章怎么读

每章的结构是固定的，可以按同一节奏读：

1. 章首 chapter-index：先看「本章回答」与「读完你会」，判断是否需要读。
2. 导语与机制图：建立全局图景，不要急着看代码。
3. 定义与定理：这是骨架；跳过定义会让后面的代码失去约束。
4. 失败案例：先看事故，再看修复；事故比成功更有信息量。
5. 实验：一定自己跑一遍；输出与书里不一致时，先查环境与版本。
6. 章末陷阱表：复习时只看这张表；每一条都能回到正文。
7. 出口检查：做不出来的题，回到对应小节，不要往下翻。

4. 时间预算

总计约 60–80 小时（含项目）。如果只读不跑，时间减半，但能力也减半。

5. 先修与补课

补课的原则是「够用就停」：你不需要会写内核模块，只需要知道沙箱的边界在哪；不需要会训练模型，只需要知道 token 与上下文成本怎么算。

符号、代码与实验约定

1. 记号

数学里的 <、> 一律写成 \lt、\gt，避免 HTML 解析吞掉。字面美元符号写 \$。

2. 代码

Python

• 版本 3.11+；实验只用标准库，不要求 pip install。
• 类型标注尽量完整；数据类用 @dataclass。
• 错误用返回值或异常都要有明确边界；实验里优先返回结构化结果，便于观察。
• 入口脚本带 if __name__ == "__main__":，支持 --help。
• 测试用 unittest，命令固定为 python3 -m unittest discover -s experiments/chNN -v。

C

• C17 + POSIX；编译命令 cc -std=c17 -D_GNU_SOURCE -Wall -Wextra -Werror -O2 -g。
• Linux 专属代码标注「Linux 6.8 · Ubuntu 24.04」；macOS 上不能编译的，不假装能编译。
• 系统调用失败必须检查 errno，并打印可读原因。
• 不贴大段内核源码；只保留能说明路径的 5–25 行，并标注文件与函数。

Bash

• 脚本首行 #!/usr/bin/env bash；建议 set -euo pipefail。
• 管道语义要写清：pipefail 取最右非零，PIPESTATUS 保留每段。
• 资源限制要写清软/硬：ulimit -n 改软限，ulimit -Hn 改硬限。
• 作业控制要写清作用域：jobs 只列当前 shell 的作业，子 shell 看不到父 shell 的作业。

JSON / YAML

• JSON 不写注释；需要解释时在块后用表格。
• 字段名用 snake_case；协议字段（如 MCP 的 inputSchema）保持原样，不改成 snake_case。
• 时间统一 ISO 8601 UTC，例如 2026-10-19T01:22:31Z。

3. 语义盒

本书只用九种盒子：

盒子编号写在标题里，例如 定义 3.1.1；锚点在花括号里，例如 {#def-agent-systems.1.3.1.1}。跨章引用用 [@def-agent-systems.1.3.1.1]，构建期会解析成链接；写错锚点会构建失败，而不是静默失效。

4. 图

• 机制图优先 ASCII（<pre class="layout">）：可复制、可 diff、无外部依赖。

• 需要矢量图时用 tools/build_figures.py 生成到 src/assets/figures/，页面通过 mdBook 的 include 指令把片段引入（具体写法见任一含图章节的源文件，避免在说明页里触发真实文件引用）。

• 每张图有 <title>、<desc>、图注；图注以「读图：」开头，正文再给一句结论。

• SVG 的 id 以 as- 开头，全书唯一；不引用外部字体、图片或脚本。

• 动画只用于「过程」类机制（如循环）；开启「减少动态效果」时必须是静态可读的。

5. 实验目录

experiments/
  ch01/  mini_loop.py  test_mini_loop.py  README.md
  ch02/  mcp_stdio_server.py  mcp_client.py  test_protocol.py
  ...
  ch14/
  run_all.sh           # 统一入口：跑所有本机可跑的实验

约定：

• 每个目录至少一个可执行入口、一个测试、一个 README。
• 正文引用格式：python3 experiments/ch02/mcp_client.py --era 2026。
• 不把大文件、模型权重、网络依赖放进仓库；实验必须离线可跑。
• Linux 专属实验提供 verify-linux.sh；macOS 上运行会打印跳过原因，不伪装成功。

6. 环境变量

注意 TZ 的语义：空串不是「系统时区」，而是 UTC；tzdata 缺失时也是静默 UTC。第 10.7 节会用一个实验演示。

7. 版本写法

正文提到版本时，写在句子里，不写在脚注：

• 好：「在 Linux 6.8 上，Landlock ABI 4 支持 TCP bind/connect 限制。」
• 差：「Landlock 支持网络限制。」

接口字段同理：MCP 2026-07-28 的 server/discover、2025-11-25 的 initialize，都要带版本。读者需要知道结论的适用边界。

实验环境与工具链

1. 两个环境

本书的实验在两类机器上完成，能力不同，标注也不同：

正文里凡是 Linux 专属的命令或 C 代码，都会标「Linux 6.8 · Ubuntu 24.04」。在 macOS 上跑不了不是失败，但不能假装跑过；第 4 章的 verify-linux.sh 会明确打印跳过原因。

2. 软件版本

检查环境：

python3 --version
bash --version | head -1
cc --version | head -1
mdbook --version
mdbook-katex --version
python3 -c 'import markdown_it; print(markdown_it.__version__)'

预期输出里 Python 至少 3.11，mdBook 至少 0.4。版本低不一定会失败，但 book.toml 的预处理器协议在 0.4/0.5 之间有差异；遇到构建错误先对齐版本。

3. 获取与构建

git clone https://github.com/JUANWANG-BUAA/tutorials.git
cd tutorials/agent-systems

# 仅本书预览
mdbook serve --open

# 结构自检（推荐每次改完都跑）
python3 tools/check_book.py --verbose
python3 tools/check_chapter.py part1/ch01.md

# 覆盖矩阵：缺口必须为 0
python3 tools/build_coverage.py

# 生成 SVG 机制图（已提交生成物，改脚本后才需要重跑）
python3 tools/build_figures.py

mdbook serve 不包含根目录的搜索索引与术语数据；要得到与线上一致的站点，在仓库根运行 ./build.sh。本书的搜索索引配置在根 tools/build_search_js.mjs 的 BOOKS 表里。

4. 跑实验

统一入口：

bash experiments/run_all.sh

它按章节顺序运行本机可跑的实验，最后打印汇总。只跑一章：

python3 experiments/ch01/mini_loop.py --mode good
python3 -m unittest discover -s experiments/ch01 -v

约定：

• 所有 Python 实验离线、无第三方依赖；不读网络、不需要 API key。
• 需要真模型的实验（第 9 章的可选部分）会明确标注「需要 API key」，并提供确定性替身。
• 实验输出写到临时目录或 experiments/.out/，不污染仓库；.out/ 已在 .gitignore 中。
• Linux 专属实验：bash experiments/ch04/verify-linux.sh；macOS 上返回 0 但打印 SKIP，不冒充通过。

5. 一个最小验证

在开始读第 1 章之前，先确认三件事：

# 1) Python 能跑，且不依赖第三方包
python3 - <<'PY'
import sys, json, resource, subprocess
print(sys.version.split()[0], "ok")
PY

# 2) 能创建子进程并读到退出码
python3 - <<'PY'
import subprocess
p = subprocess.run(["sh", "-c", "exit 42"])
print("returncode =", p.returncode)
PY

# 3) jq 能解析一行 JSON
printf '%s\n' '{"step":1,"ok":true}' | jq -r '.step'

预期：Python 版本 ≥ 3.11；returncode = 42；jq 输出 1。第三条失败就先装 jq，第 1 章的 trace 观察会用到它。

6. 目录结构

agent-systems/
  book.toml              构建配置
  src/                   正文（SUMMARY.md 是唯一导航）
    part1/ … part4/      14 章
    projects/            项目总览
    appendix/            覆盖矩阵、勘误、参考
    assets/figures/      SVG 机制图片段
    assets/covers/       书封
  experiments/           每章一个可运行实验
  projects/              两个项目的完整实现
  tools/                 mathbook、check_book、build_coverage、build_figures
  theme/                 本书样式（shared/ 的符号链接 + 本书覆盖）
  写作规范/              写作契约、章节大纲、母本目录

src/ 里不放大文件；图是内联 SVG 片段，代码是可运行的短片段，完整实现放在 experiments/ 与 projects/。

7. 常见环境问题

1 Agent 的本质：循环、状态与工具

先说结论：agent 不是「更长的 prompt」，而是一个带状态、带工具、带预算的闭环控制器。模型只是控制器里的策略函数：它读当前状态，产出一个动作意图；真正执行动作、改变世界、记录结果的是宿主。把这句话拆开，就得到本书后续十三章的全部主题——协议是动作的语法，沙箱是动作的边界，上下文是状态的投影，评估是控制器的验收，可观测性是控制器的黑匣子。

为什么这件事值得单独写一本书？因为 2023 年以来的多数 agent 事故，并不是模型「不够聪明」，而是系统工程没做对：循环没有终止条件，状态只存在聊天记录里，工具没有幂等键，失败没有 trace，权限只靠一句「不要做危险操作」。这些问题与模型能力正交，换一个更强的模型也不会自动消失。

这一章先把最小的骨架立起来。后面每一章都会在这个骨架上加一层：第 2 章把「动作」变成协议，第 3、4 章把「执行」关进沙箱，第 5、6 章处理「状态」的投影与记忆，第 7、8 章讨论策略与控制结构，第 9–12 章回答「怎么知道它做对了、怎么在出错时复原」。骨架错了，后面每一层都会歪。

读图：横向是「一步」，弧线是「多步」。把 agent 与单次调用区分开的不是箭头数量，而是弧线闭合之后仍然存在的两样东西——状态与预算。状态让下一步知道上一步发生了什么，预算让循环知道何时必须停。没有这两样，所谓 agent 只是一个会重复调用 API 的脚本。

1.1 一次调用不是 agent：三个判据

先看三个真实系统，判断它们是不是 agent。

系统 A：客服问答。 用户提问，系统检索知识库，拼接提示词，调用一次模型，返回答案。没有工具调用，没有第二轮，没有跨请求状态。这是单轮 RAG，不是 agent。

系统 B：退款审批工作流。 用户提交退款，系统按固定顺序执行：查订单 → 查风控 → 若金额小于阈值自动通过，否则转人工。步骤是代码写死的，模型只在「生成给用户的解释」这一步被调用。这是工作流（workflow），不是 agent。它的控制流由人预先编排，模型不决定下一步做什么。

系统 C：代码修复助手。 它读 issue，自己决定先看哪个文件；调用 grep 找到相关函数；修改；跑测试；测试失败后读错误、再改；最多 20 步或 10 分钟。它有一个闭环、有工具、有跨步状态，还有预算。这是 agent。

三者都可能用同一个模型、同一套 API，差别不在模型，而在谁决定下一步、动作是否改变外部世界、状态是否跨步累积。

这个定义故意把 $\pi$ 与 $E$ 分开。很多实现把「模型输出」直接当成「已经执行」，于是把工具调用、参数校验、权限检查全塞进 prompt。这在 demo 里能跑，在生产里会出现三类问题：模型声称完成了但实际没执行；参数越权但没人拦；执行失败被模型当成成功继续往下走。把 $\pi$ 与 $E$ 分开，就是强迫宿主拥有一个可检查的执行层。

判据可以压成一张表。注意「有状态」不是「有聊天记录」：聊天记录只是会话状态的一部分，而且经常是最不可靠的一部分。

这张表说明什么：四个判据里，只有「工具」是模型侧能力，其余三个都是宿主侧工程。很多团队把资源全投在换模型上，却在这三处留空，结果 agent 的能力上去了，事故率也上去了。

1.1.1 三个边界案例

判据在极端案例上最容易看清。下面三个系统都「像」agent，但按定义只有一个真正跨过边界。

第一行值得单独说：只读工具也是工具。研究助手不会改文件，但它会决定「搜什么、读哪一页、要不要再搜」，下一步依赖上一步的网页内容。它的风险不是破坏系统，而是把不可信网页里的指令当成任务（第 11.2 节），或者把敏感查询发给外部搜索（第 11.3 节）。「没有写权限」不等于「没有风险」。

第二行暴露了另一个常见混淆：有工具调用不等于有闭环。评审机器人调用了一次 post_comment，但它不会根据评论是否成功、CI 是否通过来决定下一步；它甚至不知道评论发出去之后发生了什么。它的控制流是线性的，工具只是末端的副作用。

第三行则说明「模型参与」不等于「agent 控制」。ETL 的下一步由代码决定，模型只负责清洗。把它叫 agent 会导致错误的评估口径：你会去评估「模型选工具的能力」，而真正该评估的是清洗质量与管道可靠性。

1.2 循环：观察、决策、行动、更新

最小循环只有四件事，加上一个判定就是五阶段：

        ┌──────────────────────────────────────────────────────────┐
        │                       宿主（runtime）                     │
        │                                                          │
   ┌────▼─────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐   │
   │ ① 观察    │───▶│ ② 决策    │───▶│ ③ 行动    │───▶│ ④ 更新    │   │
   │ observe  │    │ decide   │    │ act      │    │ update   │   │
   └──────────┘    └──────────┘    └────┬─────┘    └────┬─────┘   │
        ▲                               │               │         │
        │                               ▼               ▼         │
        │                        ┌────────────┐   ┌──────────┐    │
        └────────────────────────│ 工具/环境   │   │ 状态+预算 │    │
                                 └────────────┘   └────┬─────┘    │
                                                       │          │
                                                  ┌────▼─────┐    │
                                                  │ ⑤ 终止？  │    │
                                                  └──────────┘    │
        └──────────────────────────────────────────────────────────┘
             终止 = 目标满足 ∨ 预算耗尽 ∨ 不可恢复错误 ∨ 人工中止

读图：四个阶段里，只有「决策」可能由模型完成；观察、行动、更新、终止都必须由宿主实现。把这条分清，能避免一种常见的架构错误——让模型在自然语言里「模拟」工具执行与状态更新，然后相信它写的总结。

1.2.1 一次 step 的精确语义

把循环写成状态转移，能暴露很多模糊实现里的问题：

输入：初始状态 s0，预算 B
t ← 0
while not done(s_t) and budget_left(B, t):
    a_t ← policy(s_t)                 # 可能失败、可能返回非法动作
    if a_t is terminate: break
    (s_{t+1}, o_t) ← execute(s_t, a_t) # 校验 → 授权 → 执行 → 观察
    s_{t+1} ← update(s_{t+1}, o_t)     # 把观察并入状态，扣预算
    t ← t + 1
return finalize(s_t, reason)

三个细节决定了实现质量：

1. policy 的失败不是异常，是状态。 模型超时、返回非法 JSON、调用不存在的工具，都应该变成一条观察（例如 {"ok": false, "error": "EINVAL"}），让下一步有机会纠正；直接把异常抛穿循环，等于放弃自愈。
2. execute 必须原子地返回「新状态 + 观察」。 如果工具已经产生副作用，但状态更新失败，下一轮会基于旧状态重复执行——这就是缺少幂等键时最危险的重复扣款/重复发信。
3. done 与 budget_left 由宿主判定，不由模型声明。 模型可以说「我完成了」，但宿主必须用可检查的条件确认：验收测试通过、目标字段非空、人工批准，或者显式调用 task.finish 并携带答案。

1.2.2 回合（turn）与步（step）不是一回事

产品文档常把「一轮对话」叫一个 turn。在 agent 里，一个用户回合可能包含几十个 step：读文件、搜索、改代码、跑测试、再改。把 turn 当 step 做预算，会出现两种极端：按对话轮数限流，复杂任务永远做不完；按 token 限流，简单任务被误杀。

这张表说明什么：预算要挂在正确的层级上。第 8 章讲多 agent 时，预算还会沿 agent 树传播；如果层级搞混，父子 agent 会各自以为自己还有额度，最后总成本翻倍。

1.2.3 终止：三种正确理由与三种错误理由

正确的终止理由只有三类：目标满足（验收通过）、预算耗尽（步数/时间/成本）、不可继续（不可恢复错误、权限拒绝、人工中止）。错误的终止理由很常见：

• 模型说「完成了」但没有任何可检查的证据；
• 模型陷入了重复动作，宿主误把「连续两次相同动作」当成「稳定」；
• 发生异常，外层 except 直接返回了空答案。

注意定理的前提：每个 step 必须真的消耗预算。如果实现里存在「空转 step」——不调用工具、不增加计数、只把同一条消息再喂给模型——上界就不成立。第 1.6 节的真实事故，正是空转 step 没有被计入预算。

1.2.4 事件驱动与时间驱动

上面的循环是「拉」模型：每一步主动调用策略。生产系统里还有两种变体，终止与状态语义不同，混用会出 bug。

事件驱动。 循环阻塞在一个事件队列上，事件可能来自工具完成、用户插话、定时器、外部 webhook。每个事件唤醒一次决策。好处是长任务不必空转轮询；坏处是「一次 step」不再由代码顺序定义，而是由事件批次定义。如果两个事件同时到达，状态更新必须串行化，否则会出现「基于旧状态做决策」的竞态。

时间驱动。 每隔固定时间 tick 一次，适合监控、巡检类 agent。它的预算必须包含「tick 次数」，否则一个 5 秒的 tick 跑一夜就是 17280 次决策。时间驱动还要处理「上一 tick 还没结束」的重叠：默认应跳过重叠 tick，而不是并发堆积。

这张表说明什么：预算的主分量要跟驱动模式匹配。用步数去限时间驱动，会在一次慢 tick 里失控；用墙钟去限拉取式，会在模型快速返回时过早终止。

1.2.5 错误分类：哪些错可以继续，哪些必须停

把「失败」当成一个布尔值，是循环实现里最常见的偷懒。失败至少分四类，处理方式完全不同：

这四类错误如果都走同一条 except，会出现两种极端：把权限错误当瞬时错误重试，触发告警风暴；把参数错误直接终止，放弃了模型自愈的机会。正确做法是在工具适配器里把底层异常翻译成这四类，并给出 retryable 与 suggested_action 字段（第 1.4.2 节）。

1.3 状态：世界、任务、会话、控制

状态是 agent 最容易偷懒的地方：把一切都塞进 messages，需要时再让模型「回忆」。这在短任务里可行，在长任务里必然出问题，因为消息会被截断、摘要、重排，而任务约束与预算余额不能被有损压缩。

这四层不是学术分类，而是四种不同的持久化需求。世界状态应该以外部系统为准，agent 只保存引用与版本号；任务状态应该可序列化、可人工编辑；会话状态可以压缩；控制状态必须精确、不可被模型改写。

┌─────────────────────────── run（一次执行） ───────────────────────────┐
│  control: steps=7  tools=4  tokens=18.2k  deadline=12:40:30  stop=null │
│                                                                        │
│  ┌──────────────────── task（一个可验收目标） ─────────────────────┐   │
│  │ goal: "修复 issue #482 的回归"                                  │   │
│  │ constraints: ["不得改 public API", "必须补测试"]                 │   │
│  │ subgoals: [reproduce ✓, locate ✓, patch ✓, test ✗, review ○]    │   │
│  └────────────────────────────────────────────────────────────────┘   │
│                                                                        │
│  ┌──────────────────── session（消息与观察） ─────────────────────┐   │
│  │ msg[0..12]  tool_result[0..3]  summary(旧消息)                  │   │
│  └────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────┘
             │ 引用 / 版本号
             ▼
┌──────────────────── world（外部事实，agent 不拥有） ────────────────────┐
│ git HEAD=9f2c1a  worktree=/tmp/agent-7f  issue.state=open  ci=red      │
└────────────────────────────────────────────────────────────────────────┘

读图：从下往上看，世界状态是唯一「agent 不拥有」的层。它只能通过工具读取或修改，并且必须带版本（git SHA、etag、行号）。中间三层是 agent 自己的记账；最上面的控制状态是唯一允许终止循环的层。把这四层混在一个 messages 数组里，等于把账本、合同和聊天记录订在一起——查账时谁也说不清哪一页算数。

1.3.1 状态快照与摘要

每步都存完整状态不现实：一个 200 KB 的工具结果乘 50 步就是 10 MB。实践中的折中是快照 + 增量：

• 快照只存可比较的关键字段：任务完成度、预算余额、世界版本号、当前子目标；
• 增量存本步的动作、参数、结果摘要与错误码；
• 大对象（文件内容、网页）存引用（路径 + 内容哈希 + 行号范围），需要时再取。

{
  "step": 3,
  "task": {"goal": "sum", "done": false, "subgoal": "write"},
  "world": {"root": "/tmp/mini-loop-7f", "files": ["numbers.txt", "sum.txt"]},
  "control": {"steps": 3, "tool_calls": 3, "stop_reason": null},
  "action": {"tool": "fs.write", "args": {"path": "sum.txt", "content": "23"}},
  "observation": {"ok": true, "bytes": 2},
  "refs": [{"kind": "file", "path": "numbers.txt", "sha256": "…"}]
}

这段 JSON 是 experiments/ch01/mini_loop.py 的 trace 记录（省略了部分字段）。关键点是 task 与 control 不依赖消息文本：即使把 messages 全部压缩成一句摘要，done 与 steps 仍然准确。

这个例题说明：状态分层不是为了「架构好看」，而是为了让不同的压缩策略作用于不同的层。会话状态可以有损，任务状态不能；世界状态甚至不该被 agent 复制，只该被引用。

1.3.2 状态哈希与幂等

当 agent 可能重试、崩溃恢复或多副本运行时，必须回答一个问题：这一步是否已经执行过？ 常见做法是给「动作 + 关键状态」算一个指纹：

import hashlib, json

def action_fingerprint(tool: str, args: dict, world_version: str) -> str:
    payload = json.dumps(
        {"tool": tool, "args": args, "world": world_version},
        sort_keys=True, separators=(",", ":"), ensure_ascii=False,
    ).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()[:16]

指纹相同不代表可以跳过：读操作幂等，写操作未必。正确做法是让工具自己声明幂等性，并由执行器维护一个 (fingerprint → result) 的结果表：

• 幂等工具：命中结果表直接返回旧结果，不重复执行；
• 非幂等工具：命中结果表说明「可能已经执行过」，必须查询外部系统确认，或要求调用方提供幂等键；
• 不可逆工具：默认拒绝自动重试，转人工确认（第 12 章）。

1.4 工具：从函数到动作接口

很多人把工具理解成「一个能被模型调用的函数」。这个理解漏掉了工程上最重要的部分：工具是动作接口，它必须说明自己能做什么、在什么前提下能做、做完之后世界变成什么样、失败能否重试、代价是多少、需要什么权限。

以「给订单退款」为例，一个合格的契约不是 refund(order_id, amount)，而是：

{
  "name": "billing.refund",
  "description": "对已支付的订单发起全额或部分退款。仅在用户明确要求退款、且订单状态为 paid 时使用。不要用于取消未支付订单。",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "pattern": "^ord_[A-Za-z0-9]{12}$"},
      "amount_cents": {"type": "integer", "minimum": 1, "maximum": 500000},
      "reason": {"type": "string", "enum": ["customer_request", "duplicate", "fraud"]},
      "idempotency_key": {"type": "string", "minLength": 16, "maxLength": 64}
    },
    "required": ["order_id", "amount_cents", "reason", "idempotency_key"],
    "additionalProperties": false
  },
  "preconditions": ["order.status == 'paid'", "amount_cents <= order.refundable_cents"],
  "effect": "irreversible_external",
  "idempotency": "required_key",
  "cost": {"money_cents": 0, "latency_p95_ms": 1800, "quota": "billing:100/hour"},
  "auth_scope": "billing:refund"
}

这段 JSON 里，真正防止事故的不是 input_schema，而是后面四行：preconditions 让执行器在退款前查订单状态；effect 告诉重试逻辑「这是不可逆的外部动作」；idempotency 要求调用方给出幂等键；auth_scope 把权限收缩到单一动作。模型只能看到前三个字段（名称、描述、schema），后五个字段是宿主与工具之间的契约，不应该全部暴露给模型——暴露权限范围反而会诱导模型去试探边界。

1.4.1 工具与 API 的三个差别

这张表说明什么：把一个内部 API 直接暴露成工具，通常会同时放大三类风险——模型误用、参数注入、权限过宽。工具层需要一层「适配器」，做参数归一化、权限检查、结果裁剪与错误翻译，而不是把 REST 端点原样贴给模型。

1.4.2 结果封装：让失败也能被决策

工具返回什么，决定了模型下一步能做什么。只返回成功数据，失败就只能靠异常；返回整个 HTTP 响应，模型会被无关字段淹没；返回自然语言，宿主又无法稳定处理。一个够用的结果封装至少包含六个字段：

错误对象里的 suggested_action 是给策略看的，不是给用户看的。例如 EINVAL 的 suggested_action 可以是「检查必填字段并重试一次」，EPERM 的则是「停止并请求人工授权」。把两者都写成「出错了，请重试」，等于让模型在权限问题上撞墙。

{
  "ok": false,
  "error": {
    "code": "EPERM",
    "message": "refund amount 90000 exceeds refundable 20000",
    "retryable": false,
    "suggested_action": "stop_and_request_human"
  },
  "refs": [{"kind": "order", "id": "ord_7Q2K9LmN4pXr", "version": 12}],
  "cost": {"latency_ms": 42, "money_cents": 0},
  "observed_at": "2026-10-19T01:22:31Z"
}

这段结果的关键不是 ok=false，而是 retryable=false 与 suggested_action。没有这两个字段，策略只能看到「失败」，然后凭运气选择重试或放弃；有了它们，循环可以把「不可重试」直接升级成终止或人工审批，而不是烧完预算才发现无解。

1.5 控制：预算、终止与死循环

预算不是「防止账单爆炸」的保险丝，而是控制器的一部分：它决定策略在多深的搜索里还能保持理性。一个没有预算概念的 agent，在遇到不确定时会倾向于「再试一次」，而每一次尝试都可能带来新的副作用。

为什么是向量而不是标量？因为不同资源的稀缺性不同：本地文件读取消耗步数与时间，不消耗 token；长上下文推理消耗 token 与金钱，不消耗工具配额；外部 API 调用消耗配额与延迟。只盯 token，会漏掉工具配额与墙钟；只盯步数，会漏掉一次调用 10 万 token 的推理。

1.5.1 停止条件的三层实现

一个可靠的停止条件要同时在三层实现，缺一层就会出现「以为停了其实没停」：

第三层最容易被忽略。如果工具是一个会阻塞的子进程，执行器可能在 read() 上永久等待，前两层根本没有机会运行。第 3 章会讲如何用进程组、pidfd 与 SIGKILL 做真正的墙钟超时；这里先记住：预算检查必须发生在不会阻塞的地方。

1.5.2 死循环检测：动作指纹与进展度量

重复动作有两种：一种是合理的重试（网络抖动），一种是病态的空转（观察没变，模型还在做同一件事）。区分它们需要「进展」的概念。

这个定理的工程价值在于把「防死循环」拆成三个可实现的检查：预算、指纹、进展度量。三者不需要都完美，但至少要有一个能在有限步内触发。

一个够用的指纹实现：

import hashlib, json

def fingerprint(action: dict, observation: dict) -> str:
    payload = json.dumps(
        {"a": action, "o": observation},
        sort_keys=True, separators=(",", ":"), ensure_ascii=False,
    ).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()[:12]

# 在循环里维护最近 k 个指纹；全部相同则判定无进展
window: list[str] = []
...
window.append(fingerprint(action, observation))
window = window[-5:]
if len(window) == 5 and len(set(window)) == 1:
    stop_reason = "no_progress"
    break

注意指纹包含观察，不只是动作。同一动作在不同观察下可能是合理的（例如轮询一个任务直到完成）；只有「动作与观察都不变」才说明系统卡住了。反过来，如果观察在变但任务完成度不涨，指纹检测不会触发，需要进展度量兜底。

1.5.3 预算分配：先给最贵的步骤留余量

预算不是平均分给每一步。agent 的步骤成本分布高度偏斜：读一个文件可能 50 ms，跑一次测试可能 90 秒，调用一次长上下文模型可能 3 美元。平均分配会导致两个问题：前面的廉价步骤花不掉预算，后面的昂贵步骤没额度；或者反过来，前置探索烧光额度，真正关键的验证做不了。

一个可操作的分配顺序是：

1. 先扣输出预留。 每次模型调用都要给输出留 token；输入塞满会导致回答截断，比输入超限更难发现。
2. 再扣验证预算。 测试、编译、人工审批这些「证明做对了」的步骤，必须优先于更多探索。
3. 再扣重试预算。 每个工具单独设重试上限，不要把全局重试次数当成所有工具共享。
4. 最后才是探索预算。 搜索、读文件、试错用剩余额度；额度不足时策略应降级为「少探索、多确认」。

B_total
 ├─ reserve_output      = 15%      # 每次调用的输出空间
 ├─ reserve_verify      = 25%      # 测试 / 编译 / 审批
 ├─ reserve_retry       = 10%      # 按工具分配，单工具 ≤ 3 次
 └─ explore             = 50%      # 搜索 / 读取 / 试错
      ├─ step  ≤ 60% of explore
      └─ token ≤ 100% of explore

这段分配不是行业标准，而是一个可解释的起点。真正的数值要按任务类型调：代码修复的验证成本高，reserve_verify 应该更大；客服问答的探索成本低，可以压缩 explore。关键是每一项都有名字、有上限、能在 trace 里看到消耗，而不是一个神秘的 max_iterations=100。

1.6 失败案例：一个停不下来的 agent

这是本书第一个真实复现的失败案例。为了可复现，它被压缩成一个确定性脚本；事故的形状与线上一致。

1.6.1 事故现场

任务：读 numbers.txt，求和，写入 sum.txt。一个看似正确的循环，跑出了下面的 trace：

python3 experiments/ch01/mini_loop.py --mode loop --max-steps 4 --trace /tmp/t.jsonl

{
  "answer": null,
  "mode": "loop",
  "steps": 4,
  "stop_reason": "max_steps",
  "trace_steps": 4
}

打开 trace，看到的是四次一模一样的动作：

jq -r '.decision.tool' /tmp/t.jsonl | sort | uniq -c

   4 fs.read

每一步的观察也都一样：

jq -r '[.step, .result.ok, (.state.control.steps|tostring), (.budget_before.steps_left|tostring)] | @tsv' /tmp/t.jsonl

1	true	1	3
2	true	2	2
3	true	3	1
4	true	4	0

1.6.2 根因不是「模型笨」

脚本里的策略被故意写成永远返回 fs.read，模拟模型的一种真实行为：观察没有提供新信息，但策略仍然选择同一个动作。模型侧的原因是它没有「进展」的概念；宿主侧的原因是循环只检查了「是否完成」，没有检查「是否有进展」。

1.6.3 修复后的行为

在 mini_loop.py 的 loop 模式里加入指纹窗口后，max_steps=20 的运行会在第 4 步停止：

step 1  read  ok=true   fp=8f3a1c
step 2  read  ok=true   fp=8f3a1c   (repeat 1)
step 3  read  ok=true   fp=8f3a1c   (repeat 2)
step 4  read  ok=true   fp=8f3a1c   (repeat 3) → stop_reason=no_progress

这不是「让模型更聪明」，而是「让宿主更早发现没有进展」。在真实系统里，同样的逻辑可以把一次 40 分钟、$12 的失败运行压到 40 秒、$0.2。

1.6.4 修复的核心代码

修复不需要改策略，只需要在循环里加一个窗口和一个判定。下面是可移植的版本，直接插在 call_tool 之后、写 trace 之前：

import hashlib, json

def step_fingerprint(action: dict, observation: dict, world_version: str) -> str:
    payload = json.dumps(
        {"action": action, "observation": observation, "world": world_version},
        sort_keys=True, separators=(",", ":"), ensure_ascii=False,
    ).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()[:12]

WINDOW = 3
recent: list[str] = []

# 循环内，执行完动作之后
fp = step_fingerprint(action, result, state.world.version())
recent.append(fp)
recent = recent[-WINDOW:]
if len(recent) == WINDOW and len(set(recent)) == 1:
    state.control.stop_reason = "no_progress"
    break

三个细节决定了它是否可靠：

• 世界版本参与指纹。 如果两次读文件之间文件被外部改了，动作与结果可能相同，但世界版本变了；这不算无进展，应该允许继续。
• 窗口长度要大于合理重试次数。 如果网络重试允许 3 次，窗口设 3 会把正常重试误判为死循环；应设为「最大合理重试 + 1」。
• 判定放在执行之后、下一步之前。 这样最后一次重复动作的副作用已经发生，但不会再有第四次；如果要求更严格，可以在执行前用「动作 + 当前观察」预判，命中则直接拒绝执行。

1.7 最小内核：可运行的 120 行

experiments/ch01/mini_loop.py 把前面的概念压成一个可运行的内核：四层状态、三个工具、确定性策略、预算、trace。它不是生产框架，而是一把尺子：后面每章增加的能力，都可以问「它加在这个内核的哪一层」。

1.7.1 状态与预算

@dataclass
class Control:
    max_steps: int = 8
    max_tool_calls: int = 6
    steps: int = 0
    tool_calls: int = 0
    stop_reason: str | None = None

    def spend_step(self) -> bool:
        if self.steps >= self.max_steps:
            self.stop_reason = "max_steps"
            return False
        self.steps += 1
        return True

    def spend_tool(self) -> bool:
        if self.tool_calls >= self.max_tool_calls:
            self.stop_reason = "max_tool_calls"
            return False
        self.tool_calls += 1
        return True

关键行是 if self.steps >= self.max_steps 在自增之前：它保证第 max_steps+1 次申请失败，而不是先执行再发现超限。spend_tool 同理。两个函数都把原因写进 stop_reason，这样最外层不需要猜。

1.7.2 工具契约与执行

def call_tool(state: State, name: str, args: dict[str, Any]) -> dict[str, Any]:
    spec = TOOLS.get(name)
    if spec is None:
        return {"ok": False, "error": "ENOTOOL", "tool": name}
    if err := validate(spec, args):
        return {"ok": False, "error": "EINVAL", "detail": err}
    try:
        return spec.fn(state, args)
    except ValueError as exc:
        return {"ok": False, "error": "EINVAL", "detail": str(exc)}

这里有三层防御：未知工具、schema 校验失败、执行期参数错误。三者都返回结构化错误，而不是抛异常。返回的 dict 直接进入会话状态，下一步策略可以读到 error 并纠正。

1.7.3 循环与 trace

while not state.task.done:
    if not state.control.spend_step():
        break
    action = policy(state, mode)
    step = {"step": state.control.steps, "decision": action, ...}
    if not state.control.spend_tool():
        step["result"] = {"ok": False, "error": "EBUDGET"}
    else:
        step["result"] = call_tool(state, action["tool"], action.get("args", {}))
    state.session.messages.append(
        {"role": "tool", "name": action["tool"], "result": step["result"]}
    )
    step["state"] = state.snapshot()
    trace.append(step)

这段循环没有花哨的并发，但它满足了前面所有判据：闭环（策略读 messages）、工具（call_tool 改变 files）、状态（四层快照）、预算（两个 spend_*）。task.finish 把 task.done 置真，循环在下一轮条件判断时自然退出。

1.7.4 真实输出

正常路径：

python3 experiments/ch01/mini_loop.py --task sum --mode good

{
  "answer": "sum=23",
  "files": ["numbers.txt", "sum.txt"],
  "mode": "good",
  "steps": 3,
  "stop_reason": "done",
  "sum_txt": "23",
  "task": "sum",
  "trace_steps": 3
}

三步分别是：读文件、写结果、提交答案。最后一步的 trace 里可以看到 task.done=true 与预算余额：

{
  "budget_before": {"steps_left": 5, "tools_left": 4},
  "decision": {"args": {"answer": "sum=23"}, "tool": "task.finish"},
  "result": {"answer": "sum=23", "ok": true},
  "state": {
    "control": {"max_steps": 8, "max_tool_calls": 6, "steps": 3,
                "stop_reason": null, "tool_calls": 3},
    "files": ["numbers.txt", "sum.txt"],
    "task": {"answer": "sum=23", "done": true, "goal": "读取 numbers.txt，求和并写入 sum.txt"}
  },
  "step": 3
}

测试覆盖四条不变量：正常结束并写文件、预算终止、schema 拒绝额外字段、trace 可序列化为 JSONL。

python3 -m unittest discover -s experiments/ch01 -v

test_badarg_is_rejected_by_schema ... ok
test_good_run_finishes_and_writes_file ... ok
test_loop_hits_budget ... ok
test_trace_is_jsonl_serializable ... ok

----------------------------------------------------------------------
Ran 4 tests in 0.003s

OK

1.7.5 把策略换成真模型：只改一个函数

最小内核的 policy(state, mode) 是一个普通函数。接真实模型时，不需要改循环、工具、预算与 trace，只需要把它替换成一个适配器。适配器只做三件事：把状态投影成消息、调用模型、把模型输出解析成动作。

def model_policy(state: State) -> dict:
    """把模型输出解析成 {tool, args}；解析失败时返回一个可观察的错误动作。"""
    messages = build_messages(state)           # 第 5 章：预算、压缩、优先级
    resp = llm.chat(
        messages=messages,
        tools=[to_openai_tool(spec) for spec in TOOLS.values()],
        tool_choice="auto",
        parallel_tool_calls=False,
    )
    call = first_tool_call(resp)               # 第 2.3 节：流式增量与 index
    if call is None:
        return {"tool": "task.finish", "args": {"answer": resp.text or ""}}
    try:
        args = json.loads(call.arguments or "{}")
    except json.JSONDecodeError as exc:
        return {"tool": "__invalid__", "args": {"detail": str(exc)}}
    return {"tool": call.name, "args": args}

四个边界必须处理，否则适配器会成为新的故障源：

• 模型返回多个工具调用。 如果宿主按顺序执行，第二个可能基于第一个的旧观察；如果并行执行，副作用可能冲突。默认串行执行，并把「并行」当成显式能力（第 2.3 节）。
• 模型返回不存在的工具。 不要静默丢弃；返回 ENOTOOL 观察，让模型看到自己的错误。
• 参数不是合法 JSON。 同上，转成 EINVAL 观察，而不是抛异常。
• 模型直接给出最终文本而不调用 finish。 这要看产品语义：如果文本就是答案，可以包装成 task.finish；如果任务要求证据，应该拒绝并提示「请调用 finish 并附上验证结果」。

1.8 观测：一条轨迹的解剖

如果只能保留一种可观测性数据，选 trace，而不是日志或指标。日志解释单步的细节，指标回答趋势，trace 把「一次运行」还原成有因果关系的树。第 10 章会展开 trace 的模型与语义约定；这里先看最小版本。

一条 step 记录至少要有六个字段：

生产环境还要加：run_id、task_id、model、prompt_hash、tool_version、attempt、traceparent。没有 prompt_hash，你无法判断两次运行的差异来自提示词还是模型；没有 tool_version，工具升级导致的回归会被误判为模型退化。

1.8.1 三条观测命令

不需要先上平台，jq 就能回答大部分问题：

# 1) 每个工具被调用了多少次
jq -r '.decision.tool' trace.jsonl | sort | uniq -c | sort -nr

# 2) 哪些步骤失败了，错误码是什么
jq -r 'select(.result.ok == false) | [.step, .decision.tool, .result.error] | @tsv' trace.jsonl

# 3) 预算是怎么耗尽的
jq -r '[.step, .budget_before.steps_left, .budget_before.tools_left] | @tsv' trace.jsonl

第一条命令在 1.6 节的事故里给出了「4 次 fs.read」；第二条会给出 EINVAL 或 EBUDGET；第三条能看出预算是被步数还是工具调用先耗尽。三条都不需要额外依赖。

1.8.1 从 trace 到四个基本指标

trace 是原始材料；判断 agent 是否健康，还需要把它聚合成指标。最小的一组只有四个：

$$\text{成功率} = \frac{#{\text{stop_reason}=\text{done}}}{#{\text{runs}}},\qquad \text{平均步数} = \frac{1}{N}\sum_{i=1}^{N} T_i$$

$$\text{工具错误率} = \frac{#{\text{tool result ok=false}}}{#{\text{tool calls}}},\qquad \text{单次成本} = \frac{1}{N}\sum_{i=1}^{N} \left(c_{\text{in}} \cdot \text{in}_i + c_{\text{out}} \cdot \text{out}_i + c_{\text{tool}} \cdot \text{calls}_i\right)$$

四个指标要一起看。成功率上升但平均步数翻倍，可能是模型更谨慎，也可能是它在试错；工具错误率下降但单次成本上升，可能是重试策略从「快速失败」变成了「反复尝试」。只看一个指标，很容易把退化当成改进。

还要按终止原因分层，而不是只算总成功率：

这张表说明什么：done 的比例不是唯一目标。一个把 max_steps 调到 1000 的系统，成功率可能很高，但每次失败都烧掉 1000 步；一个把 no_progress 窗口设得很短的系统，成功率可能下降，但失败更快、更便宜。指标必须和预算、终止原因一起读。

1.8.2 采样与脱敏：trace 不能什么都记

trace 的默认倾向是「全记」，这在生产里会制造两类风险：存储成本失控，以及把 PII/密钥写进一个访问控制更弱的系统。一个可执行的策略是分层采样 + 字段级脱敏：

这张表说明什么：采样要按证据价值分配，而不是按体积平均。失败 run 的完整输入输出必须保留，因为下一次回归就靠它；成功 run 可以只留元数据。脱敏要在写入前做，而不是查询时做——查询时的脱敏很容易被一个 SELECT * 绕过。

step 6  run_tests  ok=false  error=ETIMEDOUT
step 7  task.finish answer="已修复并测试通过"

母本对应

读这张表要抓住两点：本书对 OS 与 DL 只做交叉引用，不重复讲 fork、信号、注意力；对 agent 新增层（循环、状态、工具契约）则给到可实现的细节。表中「背景」表示只借用一个概念，正文不会展开母本内容。

本章陷阱

这张表说明什么：十二个陷阱里，只有第 1 个是「概念不清」，其余都是工程缺失；它们不会因为换模型而消失。第 3 章与第 4 章会把第 5、7、11 条展开成可运行的边界。

本章出口检查

下一站：2 工具协议 把本章的「动作意图」变成三方都能校验的契约：JSON Schema、function calling 与 MCP 的两个版本。

2 工具协议：JSON Schema、function calling、MCP

第 1 章把工具定义成八字段契约，但那份契约还只是宿主内部的数据结构。一旦模型、宿主、工具分属三个进程甚至三个组织，契约就必须落到线上格式：模型怎么声明想调什么，宿主怎么校验与授权，工具怎么回传结果与错误，双方怎么确认彼此说的是同一版协议。协议解决的从来不是「模型会不会调用函数」，而是出现分歧时以谁为准。

这一章的主线是一条调用穿过三层边界：模型 provider 只产出意图，宿主把它变成可执行的调用，MCP 把调用送到工具进程。每穿过一层，信息都会丢失一部分；协议的价值是把丢失限制在可检测、可恢复的范围内。JSON Schema 约束参数形状，function calling 约束模型与宿主之间的一轮交换，MCP 约束宿主与工具之间的能力、调用、结果与错误，OAuth 则约束「谁有权让谁做什么」。

版本坐标必须先说清：MCP 最新规范是 2026-07-28，上一版是 2025-11-25。新实现应面向 2026-07-28，但必须能识别仍在使用 initialize 握手的旧 server。把 initialize 当永恒，或者把无状态当默认，都会在真实部署里翻车；本章会给两版对照表与迁移路径。

读图：从左到右是控制流，不是信任流。模型只产出 tool_calls；宿主做校验、授权、路由；MCP 只负责把调用送到 server。中间的请求帧里，参数可能来自网页、文件或另一个工具的输出，所以「schema 合法」不等于「可以执行」。底部两行是版本坐标：新版把 initialize 与协议级会话去掉了，新实现不应再把握手当默认前提。

2.1 三方与分层：模型只产出意图，宿主负责执行

先看一次调用里三个角色各自能决定什么。把这张表记住，后面所有协议细节都能挂上去。

很多实现把这张表压成一行：模型输出 JSON，宿主直接 json.loads 后调用函数。Demo 能跑，生产会出三类事故：模型声称做了但没做；参数越权但没人拦；执行失败被模型当成成功继续。三者都不是模型能力问题，而是宿主放弃了执行层。

┌──────────────────────────────────────────────────────────────┐
│ 模型 provider                                                 │
│   输入：messages + tools[]（名字、描述、JSON Schema）          │
│   输出：tool_calls[{id, name, arguments}]      ← 只是意图      │
└───────────────────────────┬──────────────────────────────────┘
                            │ ① 模型 API 边界（格式约束）
┌───────────────────────────▼──────────────────────────────────┐
│ 宿主 runtime                                                  │
│   解码 → 校验 → 授权 → 去重 → 路由 → 记账 → 回填观察           │
│   能拒绝、能改写、能延迟、能要求人工确认                        │
└───────────────────────────┬──────────────────────────────────┘
                            │ ② MCP / HTTP 边界（JSON-RPC 契约）
┌───────────────────────────▼──────────────────────────────────┐
│ MCP server / 工具进程                                          │
│   inputSchema 再校验 → 前置条件 → 副作用 → result/isError       │
│   持有凭证、文件句柄、数据库连接                                │
└──────────────────────────────────────────────────────────────┘
   ③ 进程/网络边界：OS 权限、沙箱、审计（第 3、4、11 章）

读图：三条横线是三种边界，不是三种信任。① 只保证模型输出可解析；② 只保证双方对帧格式一致；③ 才限制真实副作用。每跨一条边界，信息都会丢：模型看不到宿主的权限表，server 看不到模型为什么选它。协议的工作是把这种丢失变成可检测的偏差——id 对不上、schema 不合法、能力没声明、audience 不匹配，都能在造成副作用之前被拦下。

这个三元组是第 1 章八字段工具契约 定义 1.4.1 的线上投影：给模型看的部分变成 $E$，执行器内部的前置条件、幂等性、权限留在宿主；两者不是替代关系，而是同一契约的两个视图。

同一份意图，在两层协议里有两种编码。模型 API 层（OpenAI Chat Completions 形状）：

{
  "id": "call_demo_1",
  "type": "function",
  "function": {
    "name": "fs_read",
    "arguments": "{\"path\":\"seed.txt\"}"
  }
}

MCP 层：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "fs.read",
    "arguments": {"path": "seed.txt"}
  }
}

两个 JSON 说的是同一件事，但有三处关键差异。arguments 在模型层是字符串（可能是半截 JSON），到 MCP 层必须是对象；id 在模型层由 provider 生成、只在一次响应内有效，到 MCP 层由客户端生成、在一条连接上唯一；错误在模型层通常没有位置，只能塞进文本，到 MCP 层有 error 与 isError 两条通道。把这三处理顺，才算真正「支持工具调用」，而不只是会解析一个函数名。

反过来，协议不能替你做的事也要说清：它不判断一个工具该不该存在，不判断参数里的路径是否敏感，不判断调用者是否被诱导。这些属于权限、沙箱与安全（第 3、4、11 章）。协议只保证「如果一切按契约发生，双方看到的是同一件事」。

2.2 JSON Schema：约束、strict 与 2020-12

JSON Schema 是三方唯一共同读取的字段：模型据此生成参数，宿主据此预校验，server 据此最终校验。三方对同一份 schema 的理解只要有一点偏差，就会出现「模型觉得合法、宿主放行、server 崩溃」的缝隙。

先澄清六个最容易写反的语义：

required 与 additionalProperties 的组合值得单独记：{"required":["path"]} 允许 {"path":"a","extra":1}；要拒绝额外字段，必须显式写 "additionalProperties": false。很多「schema 校验过了但 server 炸了」的事故，就是宿主只查了 required，把多余字段原样转发。

integer 的判定也值得留意：2020-12 规定「零小数的数字」算整数，所以 1.0 合法；但不少实现直接按宿主语言类型判断（Python 的 isinstance(1.0, int) 为假），于是同一份 schema 在两个校验器上给出不同结果。跨语言时要么统一用整数传输，要么在边界显式规范化。

2.2.1 2020-12 与 draft-07 的差别

MCP 2026-07-28 规定：schema 没有 $schema 字段时，默认按 JSON Schema 2020-12 解释；实现必须支持 2020-12，可以额外支持其他方言。这条规定把「方言漂移」变成了显式错误，而不是静默的宽松解释。

这张表说明什么：schema 不是「一段永远兼容的 JSON」，它有方言。跨系统传输时，要么显式写 $schema，要么双方约定只使用交集子集；靠「应该差不多」会在大半年后炸。

2020-12 还有一个安全相关的细节：$ref 可以指向绝对 URI，但 MCP 明确要求实现不得默认解引用网络 URI。否则一个恶意 server 返回的 schema 就能让客户端去请求内网地址，形成 SSRF（第 2.8 节）。需要远程引用时，必须显式开启、限制主机、拒绝回环与私网地址、加超时与大小上限。

2.2.2 strict 模式：三个条件，不是一种方言

OpenAI 的 strict 不是 JSON Schema 的新方言，而是「把 schema 编译成受约束解码」的一组额外要求。要让 strict: true 真正生效，核心是三条结构要求：

1. 根是 object，且每一层 object 都写 "additionalProperties": false；
2. 每个在 properties 里出现的键都必须列进 required；
3. 「可选」用可空类型表达（例如 ["string","null"]），而不是从 required 里省略。

{
  "type": "object",
  "properties": {
    "path": {"type": "string"},
    "encoding": {"type": ["string", "null"], "enum": ["utf-8", "base64", null]}
  },
  "required": ["path", "encoding"],
  "additionalProperties": false
}

这段 schema 里，encoding 在语义上可选，但在结构上必填：调用方要么给 "utf-8"，要么给 null。这不是冗余，而是为了让受约束解码有确定的形状——模型不能「忘记」一个字段，只能显式选择空值。

一个最小校验器的核心逻辑只有十几行。下面是 experiments/ch02/mcp_stdio_server.py 里实际使用的子集（省略了数值、布尔等分支）：

def validate(schema, value, path="$"):
    if schema.get("type") == "object":
        if not isinstance(value, dict):
            return [f"{path}: expected object"]
        errors = [f"{path}.{k}: required property is missing"
                  for k in schema.get("required", []) if k not in value]
        props = schema.get("properties", {})
        if schema.get("additionalProperties") is False:
            errors += [f"{path}.{k}: unexpected property" for k in value if k not in props]
        for key, sub in props.items():
            if key in value:
                errors += validate(sub, value[key], f"{path}.{key}")
        return errors
    if schema.get("type") == "string" and not isinstance(value, str):
        return [f"{path}: expected string"]
    return []

这段代码故意只覆盖本章用到的关键字。真实实现要用完整校验器，并且在宿主与 server 两侧各校验一次：宿主校验是为了在产生副作用前拦住明显错误，server 校验是因为宿主可能被绕过、也可能是另一个团队写的。

MCP 对 schema 还有两条工程约束：inputSchema/outputSchema 必须是合法 schema 对象，不能为 null；组合关键字（anyOf、oneOf、allOf、if/then/else）与 $defs 可能被恶意构造为校验器的 DoS 向量，实现应限制深度、子 schema 数量与单次校验时间。schema 本身也是不可信输入。

schema 描述的是单次调用的形状；一次调用在时间上的形状——谁先谁后、能否并行、流式片段怎么拼——由下一节的 function calling 决定。

2.3 function calling：tools、tool_choice、并行与流式

function calling 是模型 API 层的交换格式。不同 provider 的字段名不一样，但回路相同：宿主把工具目录放进请求，模型返回一个或多个调用意图，宿主执行后把结果按 id 回填，再次请求模型。先把 OpenAI Chat Completions 的形状走一遍，再对照 Responses API。

请求侧只保留关键字段：

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "fs_read",
        "description": "读取 workspace 内的 UTF-8 文本文件；path 必须是相对路径。",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string", "minLength": 1}},
          "required": ["path"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": false
}

模型返回的调用意图：

{
  "id": "chatcmpl_demo",
  "choices": [
    {
      "finish_reason": "tool_calls",
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_demo_1",
            "type": "function",
            "function": {
              "name": "fs_read",
              "arguments": "{\"path\":\"seed.txt\"}"
            }
          }
        ]
      }
    }
  ]
}

注意 arguments 是字符串，不是对象。它可能是 ""、"{}"、半截 JSON，或者带转义的嵌套 JSON；宿主必须自己 json.loads 并处理解析失败。把这一步交给模型「保证合法」是常见的错误：strict 能降低概率，但不能替代宿主的解析与校验。

tool_choice 有四种取值，用途完全不同：

parallel_tool_calls 在 Chat Completions 里默认是 true。并行不是免费的：两个写操作可能冲突，后一个可能依赖前一个的输出，两个调用可能对同一文件做「读—改—写」。宿主要么显式关闭并行，要么在收到多个调用后做依赖分析，把有冲突的调用串行化。判定规则可以很朴素：只读且参数无重叠的调用可并行；任何写调用默认串行，除非工具有幂等键且作用域不相交。

回填结果时，assistant 消息要原样带上 tool_calls，然后每个调用一条 role: "tool" 消息：

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_demo_1",
        "type": "function",
        "function": {"name": "fs_read", "arguments": "{\"path\":\"seed.txt\"}"}
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_demo_1",
    "content": "{\"path\":\"seed.txt\",\"bytes\":11,\"content\":\"alpha\\nbeta\\n\"}"
  }
]

三条不变量经常被违反：每个 tool_call 必须有且只有一条对应结果；tool_call_id 必须来自同一轮；未执行的调用也必须回填一条显式拒绝，不能静默丢弃。少一条，多数 provider 会直接返回 400；少数会容忍，但模型会在下一轮「忘记」自己调过什么。

2.3.1 流式：按 index 拼，不按到达顺序拼

流式响应里，tool_calls 是增量下发的。第一块通常带 index、id、type 与函数名，后续块只带 index 与 arguments 片段：

chunk 1  delta.tool_calls[0] = {index: 0, id: "call_demo_1", type: "function",
                                function: {name: "fs_read", arguments: ""}}
chunk 2  delta.tool_calls[0] = {index: 0, function: {arguments: "{\"path\":"}}
chunk 3  delta.tool_calls[0] = {index: 0, function: {arguments: "\"seed.txt\"}"}}
chunk 4  finish_reason = "tool_calls"

正确做法是维护 index -> {id, name, arguments_buffer} 的映射，每块按 index 追加，收到 finish_reason 后再统一 json.loads。三个细节：index 是调用在本次响应里的序号，不是数组下标，多个调用可能交错到达；id 与 name 只出现一次，后续块没有；arguments 片段可能在任意字节处切开，包括 UTF-8 多字节字符与转义序列，逐块解析必然失败。

2.3.2 Responses API 与 Chat Completions 的字段差异

两套接口表达同一回路，但字段层级不同。迁移时最容易错的不是名字，而是「谁包着谁」：

这张表说明什么：适配器不能只改字段名，还要改「状态放在哪」。Chat Completions 把历史放在 messages 里，Responses 把一部分历史放在服务端的 response 对象里；前者更容易审计与重放，后者更省往返。选哪个取决于你的可观测性与数据保留要求，不是哪个更新。

结构化输出（structured outputs）与工具参数是两件事。前者约束最终答案的形状，后者约束动作参数的形状。两者都用 JSON Schema，但失败语义不同：答案 schema 失败通常重试或降级为文本；参数 schema 失败应该变成一条 isError 观察，让模型改参数（第 2.7 节）。

宿主的执行伪代码可以压成十几行：

resp ← model.chat(messages, tools)
calls ← decode(resp)                  # 解析失败 → 回填 EINVAL，不重试模型
for c in calls:
    if c.name not in registry: result[c.id] ← ENOTOOL
    elif not validate(registry[c.name].schema, c.args): result[c.id] ← EINVAL
    elif not authorize(c): result[c.id] ← EPERM
if parallel and all_readonly(calls): run_concurrently(calls, deadline)
else: run_in_order(calls, deadline)
append(assistant_message_with_calls)
append(each result keyed by id)

四个边界必须显式处理：finish_reason == "length" 说明参数可能被截断，不能执行；content 与 tool_calls 同时存在时，文本可能是在解释调用，不能当最终答案；同一响应里出现重复 id 时，保留第一个、拒绝其余；finish_reason == "tool_calls" 但 tool_calls 为空，是 provider 异常，应重试一次而不是当成功。

到这里，模型与宿主之间的回路已经闭合。但宿主与工具之间还没有协议：工具可能是本地函数、另一个进程、一个远程服务，甚至别人家的 SaaS。下一节的 MCP 就是这后半段的通用语言。

2.4 MCP 原语：tools/resources/prompts 与能力协商

MCP（Model Context Protocol）是宿主与工具之间的 JSON-RPC 2.0 协议。它不替代模型 API，也不规定模型怎么选工具；它规定的是：工具如何声明自己、宿主如何调用、结果与错误如何回传、双方如何确认能力边界。用一句话概括：MCP 是工具侧的操作系统调用表——不是插件市场，也不是权限系统。

JSON-RPC 2.0 只有三种消息。request 带 id、method、params；response 必带同一 id（解析失败、id 不可读时可为 null），并在 result 与 error 中二选一；notification 没有 id，接收方不得回复。JSON-RPC 允许 id 为 null（不推荐），MCP 收紧为字符串或整数、不得为 null，且同一发送方未完成的请求 id 不得重复。错误对象固定三字段：code（整数）、message（一句话）、data（可选的结构化补充）。

{"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "nope"}}
{"jsonrpc": "2.0", "id": 7, "error": {"code": -32602, "message": "Unknown tool: nope"}}
{"jsonrpc": "2.0", "method": "notifications/cancelled", "params": {"requestId": 7}}

服务端有三个原语，控制点各不相同：

客户端侧在 2025-11-25 还有 roots、sampling、elicitation 三个能力；2026-07-28 只保留 elicitation（并且改为通过 MRTR 传递），roots 与 sampling 进入弃用。这个变化不是删功能，而是把「server 反向控制 client」改成「client 在一次请求内决定是否配合」。

tools/list 的响应包含工具名、描述、输入/输出 schema 与注解。下面是实验里真实返回的第一个工具（只保留一个，字段未改）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "tools": [
      {
        "name": "fs.read",
        "title": "Read a text file",
        "description": "读取 workspace 根目录内的 UTF-8 文本文件。path 必须是相对路径；不要用于读取二进制文件或目录。",
        "inputSchema": {
          "type": "object",
          "properties": {"path": {"type": "string", "minLength": 1, "maxLength": 200}},
          "required": ["path"],
          "additionalProperties": false
        },
        "outputSchema": {
          "type": "object",
          "properties": {
            "path": {"type": "string"},
            "bytes": {"type": "integer", "minimum": 0},
            "content": {"type": "string"}
          },
          "required": ["path", "bytes", "content"],
          "additionalProperties": false
        },
        "annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        }
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

三个字段值得停一下。outputSchema 让宿主可以在把结果喂给模型前校验结构；annotations 是提示，不是权限；ttlMs 与 cacheScope 是 2026 新增的缓存提示，前者说这份列表多久内可视为新鲜，后者说能否跨授权上下文共享。缓存不是可选的优化：没有 ttlMs 时客户端应按 0 处理，也就是每次都重新拉。

2.4.1 注解只是提示

规范明确要求：除非 server 可信，客户端必须把注解当作不可信。原因很直接——注解由 server 自己声明，一个被投毒的 server 可以把 rm -rf 标成 readOnlyHint: true。默认值也刻意保守：没声明就当作「可能破坏、可能不幂等、可能访问开放世界」。

规范建议工具名满足：长度 1–128，字符集为 ASCII 字母、数字、下划线、连字符与点，大小写敏感，同一 server 内唯一。聚合多个 server 的宿主必须处理重名，通常加 server 前缀；serverInfo.name 不保证唯一，不能拿它当命名空间。

2.4.2 resources 与 prompts

resources 面向「读数据」，URI 是标识符，不一定是文件路径。工具结果里可以返回 resource_link（让客户端自己决定要不要读）或 resource（内嵌内容）。前者适合大对象与需要权限的数据，后者适合小段上下文。

{"jsonrpc": "2.0", "id": 9, "method": "resources/read",
 "params": {"uri": "file:///tmp/ch02-mcp/seed.txt"}}

{"jsonrpc": "2.0", "id": 9, "result": {
  "contents": [{"uri": "file:///tmp/ch02-mcp/seed.txt", "mimeType": "text/plain",
                "text": "alpha\nbeta\n"}]}}

prompts 面向「用户主动选择的模板」：prompts/list 列出模板与参数，prompts/get 返回一组消息。它不应该被宿主自动注入——那是 system prompt 的职责；prompts 的语义是「用户点了一下这个模板」。

能力协商要回答三个问题：对方会不会回答这个方法（能力位）、我这个请求需不需要对方的能力（例如 MRTR 需要 elicitation）、回答了是否等于授权（不等于）。前两个问题决定「能不能调」，第三个问题决定「该不该执行」。很多实现只检查第一个，于是把「server 声明了 tools」误当成「这个调用者可以用所有 tools」。

三个原语解决「有什么、怎么调、结果是什么」；它们没有解决「第一次见面怎么确认对方是谁、说哪版」。这就是生命周期与版本协商。

2.5 生命周期：从 initialize 到无状态

MCP 的版本号是日期字符串，不是 semver。2026-07-28 指一份具体修订，不承诺与 2025-11-25 的补丁级兼容。两版之间不是小改：2026-07-28 把协议级会话与握手整个移除，改成每个请求自带元数据。理解这个断点，比记住字段名更重要。

2025-11-25（legacy）                        2026-07-28（modern）
client                 server               client                 server
  │ initialize           │                    │ server/discover      │
  │─────────────────────>│                    │─────────────────────>│
  │←─────────────────────│                    │←─────────────────────│
  │ notifications/       │                    │                      │
  │ initialized          │                    │  （没有握手，没有会话） │
  │─────────────────────>│                    │                      │
  │ tools/list           │                    │ tools/list           │
  │─────────────────────>│                    │─────────────────────>│
  │←─────────────────────│                    │←─────────────────────│
  │                      │                    │                      │
  connection = session                       每个请求自带 _meta
  断线重连必须重新握手                          断线重试换新 id（副作用仍需幂等）

读图：左边前两帧建立上下文，后面所有帧都依赖它；右边每一帧都是自包含的，server 不要求你复用同一条连接。代价从「连接建立时的往返」变成「每一帧的字节」；收益是任意请求可以落到任意实例，失败恢复不必重放握手。注意右边仍然可以有状态——购物车、事务、长任务——但状态必须由 server 显式发一个 handle，客户端在后续参数里带回来，而不是靠连接隐式维系。

2025-11-25 的握手长这样（实验 trace 的真实响应，已缩进）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {"listChanged": false},
      "resources": {"subscribe": true, "listChanged": false},
      "prompts": {"listChanged": false},
      "logging": {}
    },
    "serverInfo": {"name": "ch02-stdio-server", "version": "1.0.0"},
    "instructions": "教学 server：先 initialize，再发 initialized 通知。"
  }
}

客户端在 initialize 里给出自己支持的版本、能力与身份；server 返回它选的版本与能力；客户端再发 notifications/initialized，双方才进入操作阶段。版本不匹配时，server 返回自己支持的最新版，客户端若不支持就断开。这套协商只发生一次，之后的请求都默认沿用。

2026-07-28 把同样的信息拆进每一帧：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {"name": "ch02-client", "version": "1.0.0"},
      "io.modelcontextprotocol/clientCapabilities": {"elicitation": {}}
    }
  }
}

protocolVersion 与 clientCapabilities 是必填；clientInfo 是建议填。server 在处理请求前检查版本：不认识就返回 -32022 UnsupportedProtocolVersion，并在 data.supported 里列出自己支持的版本；缺字段返回 -32602。结果侧对应地带 _meta.io.modelcontextprotocol/serverInfo，但它是自报的，只能用于展示与排障，不能用于安全决策。客户端还要兼容旧 server：收到缺少 resultType 的结果时，必须按 complete 处理，而不是判协议错误。

两版的关键差异可以压成一张表。这张表建议直接放进你的迁移文档，而不是只留在脑子里：

这张表说明什么：2026 不是「加了几个字段」，而是把「连接即上下文」改成「请求即上下文」。所有依赖连接状态的设计——会话粘滞、GET 流广播、断点续传——都要重新设计。

方法可用性速查。 迁移时最常问的是「这个方法还在不在」，直接查表比翻 changelog 快：

这张表只列核心方法。扩展方法（如 UI、tasks）随扩展走，不在核心版本矩阵里。

2.5.1 MRTR：把反向请求变成两轮往返

旧版里，server 可以在处理 tools/call 的过程中反向发一个 elicitation/create 请求，等客户端返回后再继续。这要求连接保持、双向通道可用、server 记住中间状态。新版把这件事改成多轮往返（MRTR）：server 不主动发请求，而是返回一个 resultType: "input_required" 的结果，里面带 inputRequests；客户端收集输入后，用新的请求 id 重发原请求，并带上 inputResponses 与 requestState。

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "resultType": "input_required",
    "inputRequests": {
      "confirm_write": {
        "method": "elicitation/create",
        "params": {
          "mode": "form",
          "message": "允许写入 out.txt（5 字节）？",
          "requestedSchema": {
            "type": "object",
            "properties": {"confirm": {"type": "boolean"}},
            "required": ["confirm"],
            "additionalProperties": false
          }
        }
      }
    },
    "requestState": "eyJwIjogImV5SnBZWFFpT2pF...(省略)"
  }
}

server 只能请求客户端声明过的能力：clientCapabilities 里没有 elicitation 时，应返回 -32021 MissingRequiredClientCapability，而不是硬发一个 inputRequests。

requestState 是不透明字符串，客户端不得解析或修改，重试时原样带回。它让 server 不必在两次请求之间保存状态：需要记住的上下文（写哪个文件、内容哈希、过期时间）由 server 自己编码进去，并做完整性保护。这也意味着它经过客户端，必须当作攻击者可控输入：要校验 MAC、过期时间、主体、以及是否与本次参数匹配。实验里的 fs.write 就是这么做的；篡改尾部四个字符会得到 -32602。

生命周期解决「我们说的是不是同一版」；传输解决「帧怎么过去、断了怎么办」。后者才是事故高发区。

2.6 传输与可靠性：stdio、Streamable HTTP、取消与重试

2.6.1 stdio：一行一帧，stdout 只许协议

stdio 传输的规则少而硬：

• 每条消息是一行 JSON，消息内不得有裸换行（字符串里的换行由 JSON 转义成 \n）；
• server 从 stdin 读、往 stdout 写；stdout 只能写协议帧；
• 日志、调试输出、进度条一律写 stderr；客户端不应把 stderr 当错误信号；
• 所有消息共享一条通道，靠 JSON-RPC id 关联请求与响应，没有 per-request 流；
• 取消用 notifications/cancelled，因为 stdio 没有「关掉某条响应流」这种粒度；
• 关闭 stdin 是优雅停机的首要信号；不退出再升级到 SIGTERM、SIGKILL。

import json, sys

def write_frame(stream, frame):
    line = json.dumps(frame, ensure_ascii=False, separators=(",", ":"))
    assert "\n" not in line, "stdio frame must be one line"
    stream.write(line + "\n")
    stream.flush()

print() 调试是 stdio server 的第一号事故：一行 print("debug") 就会让客户端收到无法解析的帧，随后整条连接被判定为协议错误。更隐蔽的是第三方库把日志写到 stdout，或者 json.dumps 的 indent 参数把一帧拆成多行。

2.6.2 Streamable HTTP：一个端点，两种响应

Streamable HTTP 把每个 JSON-RPC 消息变成一次 POST。客户端必须同时接受两种响应：单个 JSON 对象，或一条 SSE 流。SSE 流里可以先有与本请求相关的 notifications/progress、notifications/message，最后才是最终响应；最终响应之后流应结束。

POST /mcp HTTP/1.1
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: fs.read

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fs.read","arguments":{"path":"seed.txt"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{"elicitation":{}}}}}

MCP-Protocol-Version 必须与 body 里 _meta 的版本一致；Mcp-Method 与 Mcp-Name 让网关不必解析 body 就能路由。头与 body 不一致时，server 必须返回 400 与 -32020 HeaderMismatch——这是防止「负载均衡按头路由、server 按 body 执行」的经典混淆。未知方法返回 404 加 -32601，以便与旧 HTTP+SSE server 的 404 区分。

旧版（2025-11-25）在这套机制之上还有四样东西：initialize 响应可带 Mcp-Session-Id，后续请求必须带上；GET 可以打开一条独立 SSE 流；DELETE 终止会话；Last-Event-ID 可以续传。2026-07-28 全部移除：只支持新版的 server 对 GET/DELETE 建议回 405，收到 Mcp-Session-Id 应忽略且不再签发，收到 Last-Event-ID 应忽略。SSE 断流不再可续，断掉的请求就是丢了，客户端必须用新的 id 重发。

安全性上，Streamable HTTP 有三条基线要求：校验 Origin，不合法回 403（防 DNS rebinding，MUST）；本地运行只绑 127.0.0.1（SHOULD）；所有连接都应认证（SHOULD）。前两条缺任何一条，一个恶意网页就可能驱动你本机的 MCP server。

2.6.3 可靠性：超时、取消与重试的边界

先看一张故障对照表。它的重点是第三列：客户端能不能确定副作用已经发生。

这张表说明什么：只有「确定没执行」的失败可以无条件重试。读超时、SSE 断流、会话过期都属于「不确定」，必须靠幂等键或去重表兜底；没有这两样，重试就是在赌。

定理的工程含义不是「不要重试」，而是「重试必须与幂等设计配套」。三条可执行的规则：读操作与显式幂等键的写操作可以重试；不可逆写默认不自动重试，转人工或查询外部状态；所有重试计入独立预算，带指数退避与抖动，且不能重试 EPERM/EACCES 这类权限错误。

取消也不是「保证没执行」。客户端发 notifications/cancelled，或者关掉 SSE 响应流，server 应尽快停止，但副作用可能已经发生。取消的语义是「别再往下做」，不是「把已经做的撤回」。需要撤回的场景要靠补偿动作，而不是取消。

观测一次协议会话，不需要抓包工具，客户端已经把帧写成了 JSONL：

python3 experiments/ch02/mcp_client.py --era 2026 --root /tmp/ch02-mcp \
  --trace experiments/ch02/trace-2026.jsonl --quiet
jq -r 'select(.dir=="recv" and .frame.error) | [.frame.id, .frame.error.code, .frame.error.message] | @tsv' \
  experiments/ch02/trace-2026.jsonl

checks: ok=28 fail=0
7	-32602	Unknown tool: nope
8	-32601	Method not found: tools/frobnicate
9	-32602	Invalid params: missing _meta
10	-32022	Unsupported protocol version
14	-32602	Invalid params: bad requestState

这五行覆盖了五类协议错误：未知工具、未知方法、缺元数据、版本不支持，以及被篡改的 requestState。它们都没有走到工具执行层——这正是「在副作用之前失败」的样子。第 2.7 节会把「哪些错误该走这条通道、哪些该走 isError」讲清。

2.7 结果与错误：isError、结构化内容与错误码

协议里最容易偷懒的决定，是把所有失败都塞进一条通道。MCP 给了两条：JSON-RPC 的 error，与工具结果里的 isError: true。选错的代价很具体——模型看不到本可以自纠的参数错误，或者宿主把一次可恢复的业务失败当成连接崩溃。

先看错误码的分区。JSON-RPC 2.0 把 -32768..-32000 整段保留给协议自身与实现，其中 -32000..-32099 是实现自定义的服务器错误区。MCP 再把这一段切开：-32000..-32019 是遗留实现用过的，新代码不应再分配；-32020..-32099 保留给规范。这条分区规则是 2026-07-28 才明确的，旧实现里各种自定义码混用，是迁移时的主要噪音源。

这张表说明什么：「模型能不能改」是分通道的第一判据。参数类型错、枚举越界、日期格式错，模型看到具体原因后有机会改对，应走 isError；方法不存在、版本不支持、头不匹配，模型改不了，走 JSON-RPC error 让宿主处理。规范明确把「输入校验错误」列为工具执行错误，而不是协议错误，原因就在这里。

结果侧的内容也有结构。content 是给模型看的非结构化块数组（text/image/audio/resource_link/resource），structuredContent 是给程序校验的结构化值。规范建议：返回结构化内容时，同时把序列化 JSON 放进一个 text 块，兼容只认 content 的旧客户端。structuredContent 与模型的「结构化输出」是两件事：前者是 server 产出的结果数据，后者是约束模型生成的 schema。

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "resultType": "complete",
    "content": [
      {"type": "text", "text": "{\"error\": {\"code\": \"EINVAL\", \"message\": \"$.a: expected number, got str\", \"retryable\": true}}"}
    ],
    "structuredContent": {
      "error": {"code": "EINVAL", "message": "$.a: expected number, got str", "retryable": true}
    },
    "isError": true
  }
}

这段是实验里的真实响应（缩进调整过）。三个字段各司其职：isError 告诉宿主「这是工具层失败，不是连接失败」；content 让模型能读到原因；structuredContent.error 给宿主稳定的机器码与 retryable。错误对象里不要放栈、SQL、内部 URL 或 token——它们既可能泄密，也会把模型的注意力带偏。

一个可复用的错误对象建议包含以下六个字段，缺一个就会让某一方靠猜：

code 与 message 的分工要固定：程序读 code，模型读 message，人读 suggested_action。三者混用会导致「改文案破坏了监控」或「模型看不懂机器码」。

宿主收到不同错误时的策略：

这张表说明什么：错误处理不是 try/except，而是一棵决策树。树的第一层是「通道」，第二层是「可重试性」，第三层才是「文案」。把三层压成一层，必然出现「权限错误重试三次」或「参数错误直接终止」这两种极端。

再看一眼 trace 里的分布，确认失败都发生在该发生的层：

jq -r 'select(.dir=="recv" and .frame.result) | [.frame.result.resultType, .frame.result.isError] | @tsv' \
  experiments/ch02/trace-2026.jsonl | sort | uniq -c

   2 complete	
   4 complete	false
   2 complete	true
   1 input_required	

两行 complete 没有 isError 字段，是 server/discover 与 tools/list；四个成功调用、两个工具级失败、一个 MRTR 中间结果。协议错误不在这个统计里，因为它们走 error 通道，被前一条 jq 单独筛出。把两张表放在一起，才能回答「失败有多少、分别在哪一层」。

2.8 授权：OAuth 2.1、audience 与 confused deputy

前面所有协议都假设「调用者有权」。真实系统里，这个假设要靠 OAuth 2.1 兑现。MCP 的授权模型很明确：受保护的 MCP server 是 OAuth 2.1 资源服务器，MCP client 是 OAuth 客户端，授权服务器（AS）可以是独立服务。server 不签发 token，只验证 token；client 不为 server 保存密码，只持有 AS 签发的、绑定到该 server 的 token。

一次完整的授权流程：

1. client 不带 token 请求，server 返回 401，并在 WWW-Authenticate 里给出 resource_metadata 与所需 scope；
2. client 拉取受保护资源元数据（RFC 9728），从中找到 AS；
3. client 通过 AS 元数据（RFC 8414 或 OIDC Discovery）找到授权端点与 token 端点；
4. client 注册：优先用 CIMD（Client ID Metadata Documents），退回预注册或 DCR；
5. client 生成 PKCE 参数，带 resource（RFC 8707）发起授权请求；
6. 用户授权后，client 用 code + verifier + resource 换 token，并校验 iss（RFC 9207）；
7. 之后每次请求都带 Authorization: Bearer <token>；server 校验签名、过期、audience 与 scope。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

这条 401 是发现流程的起点，不是终点。客户端不应硬编码 AS 地址，也不应假设所有 server 共用一个 AS；元数据里的 authorization_servers 才是权威来源。

这张表说明什么：MCP 没有发明授权，它把一组现成 RFC 组合成一条最小路径。工程上不要自己发明「用 API key 代替 OAuth」的捷径——那会同时失去 audience、过期、撤销与审计。

scope 的粒度是设计题，不是越细越好。按「一个用户能理解的授权单元」切：files:read、files:write、issues:write，而不是按每个工具切一个 scope。太细会让用户在授权页面上点几十次，最终形成「全部同意」的肌肉记忆；太粗则一次授权覆盖所有危险动作。可行的折中是「粗 scope + 每工具映射 + 运行时 step-up」：初始只申请只读，遇到写操作返回 403 insufficient_scope，客户端把当前 scope 与挑战里的 scope 取并集再授权，且限制重试次数。

2.8.1 token 透传与 confused deputy

规范里有两句很短、但经常被忽略的 MUST：MCP server 不得接受不是发给它的 token；不得接受或中转任何其他 token。违反这两句，就会得到 token passthrough（透传）与 confused deputy（混淆代理）。confused deputy 的成立需要两个条件：代理拥有调用者没有的权限；代理在调用者的请求上使用了该权限，却没有校验调用者是否有权。

2.8.2 其余四类授权事故

SSRF。 客户端要拉取 resource_metadata 与 AS 元数据，这两个 URL 都可能由不可信的 server 提供。恶意 server 可以让客户端请求 http://127.0.0.1:8500/v1/... 或云元数据地址。控制：只允许 HTTPS、主机 allowlist、拒绝回环/链路本地/私网、禁止重定向、超时与响应大小上限、记录实际拉取的 URL。schema 的远程 $ref 同理（第 2.2 节）。

状态句柄劫持。 2025 的 Mcp-Session-Id 如果是可猜测的短字符串，攻击者可以冒充他人会话；2026 的显式 handle 也常被当成 bearer token 使用。控制：高熵、不可解析、绑定主体、每次调用校验归属、设置 TTL、泄露后可撤销。handle 是名字，不是能力——server 每次都要重新授权。

本地 server 失配。 stdio server 通常以当前用户权限运行，能读用户能读的一切。它不是安全边界，也不应接收 HTTP 世界的 token。正确做法是从环境或 OS keychain 取该 server 专用的最小凭证，并用第 3、4 章的沙箱与权限把它的能力收紧。把本地 server 当成「可信内网」是常见错觉。

开放重定向与 mix-up。 授权响应可能被重定向到攻击者控制的 URI；多 AS 环境下，客户端可能把 code 发给错误的 AS。控制：严格匹配注册的 redirect_uri、校验 iss、把 PKCE verifier 与 AS 绑定、拒绝不在元数据里的端点。

这张表把 2.8.1 的两类也列进来，共六类；其中只有 SSRF 是「网络层」问题，其余都是「把认证当授权」或「把句柄当能力」。授权设计的核心不是接上 OAuth，而是让每一个副作用都能回答「这是谁授权的」。

2.9 互操作与迁移：版本矩阵、弃用与事故复盘

两版协议会长期共存。迁移的第一件事不是改代码，而是画矩阵：你的客户端是什么时代，对端 server 是什么时代，组合起来会发生什么。

这张表说明什么：兼容不是「支持所有版本」，而是「在每一格都有确定行为」。最危险的一格是「2026 客户端 × 仅 2025 server」：如果没有探测，客户端会把 -32600/-32601 当成致命错误，或者更糟——旧 server 不校验握手，直接把 tools/call 当 legacy 语义执行。

弃用项也要列清楚。弃用不等于立刻不可用，而是「仍能工作，但新实现不应采用，未来版本会移除」：

一个双时代适配器的骨架如下。关键点不是代码量，而是把「探测」「编解码」「错误映射」三件事分开，别让它们散落在业务逻辑里：

class EraAdapter:
    def __init__(self, transport):
        self.transport = transport
        self.era = None          # "2025" | "2026"

    def detect(self):
        if self.transport == "stdio":
            resp = self.rpc("server/discover", meta=modern_meta())
            if "result" in resp:
                self.era = "2026"
                return self.era
            if resp.get("error", {}).get("code") == -32022:
                # modern server，只是版本不支持：按 supported 选，不回退
                self.era = "2026"
                self.version = pick(resp["error"]["data"]["supported"])
                return self.era
            # 其他错误或超时：legacy
            self.era = "2025"
            self.initialize_legacy()
            return self.era
        # HTTP：先发 modern 请求；400 时先看 body 是否是已知 modern 错误
        resp, status = self.post_modern("tools/list")
        if status == 200:
            self.era = "2026"
        elif is_known_modern_error(resp):
            raise ProtocolError(resp)      # 不要回退
        else:
            self.era = "2025"
            self.initialize_legacy()
        return self.era

    def call_tool(self, name, args):
        if self.era == "2026":
            return self.rpc("tools/call", {"name": name, "arguments": args,
                                           "_meta": modern_meta()})
        return self.rpc("tools/call", {"name": name, "arguments": args})

这段骨架省略了认证、超时与重试，但保留了最重要的分支：modern 错误不触发回退。把 -32022 当成「对方是旧版」是最常见的误判——它恰恰说明对方是新版，只是不支持你请求的版本。

把两个时代跑一遍。 协议细节读到这里，最好的验收是让两版真的跑起来。实验目录里的客户端会启动 server 子进程，逐帧打印，并对关键路径做断言：

python3 experiments/ch02/mcp_client.py --era 2026 --root /tmp/ch02-mcp \
  --trace experiments/ch02/trace-2026.jsonl --quiet
python3 experiments/ch02/mcp_client.py --era 2025 --root /tmp/ch02-mcp \
  --trace experiments/ch02/trace-2025.jsonl --quiet
python3 -m unittest discover -s experiments/ch02 -v

checks: ok=28 fail=0
checks: ok=19 fail=0

28 条断言覆盖 2026 的发现、列表、成功调用、参数错误、未知工具、未知方法、缺元数据、版本不支持、MRTR 往返与 requestState 篡改；19 条覆盖 2025 的握手顺序、ping、资源读取、订阅通知与 legacy 错误码。把请求序列单独抽出来看，能直接读出「哪些帧是正常路径、哪些是负例」：

jq -r 'select(.dir=="send") | [.frame.id, .frame.method] | @tsv' \
  experiments/ch02/trace-2026.jsonl

1	server/discover
2	tools/list
3	tools/call
4	tools/call
5	tools/call
6	tools/call
7	tools/call
8	tools/frobnicate
9	tools/list
10	tools/list
11	tools/call
12	tools/call
13	tools/call
14	tools/call
	notifications/cancelled

读这段输出：id 5、6、7、8、9、10、14 是负例（路径逃逸、类型错误、未知工具、未知方法、缺 _meta、旧版本、篡改状态）；id 11 与 12 是 MRTR 的两轮，必须是两个不同的 id——它们是两次独立请求，第二次带上 inputResponses 与 requestState；最后一行的通知没有 id，因为它不需要响应。正常路径是 1–4 与 12–13，其余都在验证「失败发生在正确的层」。

测试输出（完整；耗时因机器而异）：

test_call_and_legacy_error_code (test_protocol.Test2025.test_call_and_legacy_error_code) ... ok
test_discover_is_unknown_in_2025 (test_protocol.Test2025.test_discover_is_unknown_in_2025) ... ok
test_handshake_is_required (test_protocol.Test2025.test_handshake_is_required) ... ok
test_initialized_notification_is_required (test_protocol.Test2025.test_initialized_notification_is_required) ... ok
test_missing_resource_uses_legacy_code (test_protocol.Test2025.test_missing_resource_uses_legacy_code) ... ok
test_ping_logging_and_resources (test_protocol.Test2025.test_ping_logging_and_resources) ... ok
test_call_success (test_protocol.Test2026.test_call_success) ... ok
test_discover (test_protocol.Test2026.test_discover) ... ok
test_initialize_is_gone (test_protocol.Test2026.test_initialize_is_gone) ... ok
test_input_validation_is_tool_error (test_protocol.Test2026.test_input_validation_is_tool_error) ... ok
test_missing_meta (test_protocol.Test2026.test_missing_meta) ... ok
test_mrtr_request_state_is_integrity_protected (test_protocol.Test2026.test_mrtr_request_state_is_integrity_protected) ... ok
test_mrtr_round_trip (test_protocol.Test2026.test_mrtr_round_trip) ... ok
test_stdout_is_pure_json (test_protocol.Test2026.test_stdout_is_pure_json) ... ok
test_tools_list_is_stable_and_has_schemas (test_protocol.Test2026.test_tools_list_is_stable_and_has_schemas) ... ok
test_unknown_method (test_protocol.Test2026.test_unknown_method) ... ok
test_unknown_tool_is_protocol_error (test_protocol.Test2026.test_unknown_tool_is_protocol_error) ... ok
test_wrong_version (test_protocol.Test2026.test_wrong_version) ... ok
test_client_2025 (test_protocol.TestClientEndToEnd.test_client_2025) ... ok
test_client_2026 (test_protocol.TestClientEndToEnd.test_client_2026) ... ok

----------------------------------------------------------------------
Ran 20 tests in 0.652s

OK

test_stdout_is_pure_json 值得单独说：它把 server 的所有 stdout 行重新 json.loads 一遍，任何一行日志混进来都会失败。这类测试比「功能对不对」更早发现问题，因为它把传输层的硬约束变成了可执行的断言。

母本对应

读这张表要抓住两点：对 OS 与网络只做边界引用，不重复讲信号、管道、TCP 的重传；对协议新增层（schema、function calling、MCP、OAuth 组合）则给到可实现的细节。表中「背景」表示只借用一个概念，正文不展开母本内容。

本章陷阱

这张表说明什么：十二条里，前七条偏「格式与回路」，后五条偏「边界、错误与权限」。它们的共同点是都不会靠换模型消失；换一个更强的模型，只会让越权调用发生得更流畅。第 3、4 章会把第 11、12 条展开成进程、文件、网络与 capability 的具体边界。

本章出口检查

下一站：3 沙箱 把「工具能做什么」收紧为「进程、文件、网络、资源四层边界」，让协议里的授权承诺落到内核能执行的限制上。

3 沙箱：进程、文件、网络、资源限制

第 2 章把动作变成了协议，但协议只说明「能调用什么」，不说明「调用之后能碰到什么」。一个代码 agent 的工具调用，最终会落到宿主的真实对象上：一个 PID、一个目录项、一条 socket、一页内存。模型在自然语言里说「我只读一个文件」，内核看到的却是一次 openat；说「我跑一下测试」，内核看到的是 fork、execve、若干次 write，以及一个可能比父进程活得更久的进程组。

沙箱要处理的正是这层落差。它不是一条命令，也不是一个「安全模式」开关，而是四层边界的组合：进程边界决定谁能被创建、谁能被杀死；文件边界决定路径能解析到哪里；网络边界决定包能发到哪里；资源边界决定一次失控最多能烧掉多少。四层挡的事故不同，缺一层就有对应的逃逸路径。第 4 章会把「丢权」的手段（capability、seccomp、landlock、user namespace）补上；这一章先把边界本身画清楚。

先给结论：沙箱的价值不在于「限制得多」，而在于每一层都能说出它挡的是哪一类事故，以及它挡不住什么。一个只设了 30 秒超时的 runner，挡不住 fork 炸弹，也挡不住子进程在父进程死后继续写文件；一个只读的 rootfs，挡不住把读到的内容从网络发出去。下面从 agent 能做什么开始，逐层收紧。

读图：四层是四种失败模式的一一对应，不是四个可选的加固项。图下方的「共同前提」属于第 4 章：低权限 UID、no_new_privs、最小 capability、seccomp 与 landlock。没有这一行，四层边界只是「建议」；有了这一行，越界才会变成 EPERM 而不是「下次注意」。

3.1 威胁模型：代码 agent 能做什么

先把「代码 agent」拆成动作。一个能读文件、改文件、跑命令、装依赖、访问 URL 的 agent，其工具面通常包含下面几类。每一类都对应一个真实的系统对象，而不是一段文本。

这张表说明什么：agent 的「能力」不是工具描述里的几句话，而是这些对象上的操作权限。工具描述可以写「仅用于读取项目文件」，但内核只认路径和 fd；如果路径能解析到 /etc/shadow，描述不会替你拦住。

这个定义故意把「进程数」放在 $R$ 而不是 $P$。进程组解决的是「怎么杀」，pids.max 解决的是「能生多少」；两者经常被混为一谈，后果是一个能杀干净但已经被 fork 炸弹拖垮的宿主。

把四层画成一张机制图。注意箭头不是「依次执行」，而是「同一动作同时受四层约束」；任何一层缺失，动作就从那个缺口出去。

                    ┌──────────────────────────────────────────┐
                    │        agent 的一次 tool call             │
                    │   run("python3 main.py") / read(path)     │
                    └───────────────────┬──────────────────────┘
                                        │
          ┌──────────────┬──────────────┼──────────────┬──────────────┐
          ▼              ▼              ▼              ▼
   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
   │  进程边界   │ │  文件边界   │ │  网络边界   │ │  资源边界   │
   │ fork/exec  │ │ rootfs     │ │ netns      │ │ rlimit     │
   │ pgid/setsid│ │ mount ns   │ │ veth       │ │ cgroup v2  │
   │ wait/pidfd │ │ openat2    │ │ DNS/egress │ │ wall clock │
   └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘
         │              │              │              │
         ▼              ▼              ▼              ▼
   超时只杀父进程    读到宿主密钥     把数据 POST 出去   fork 炸弹/磁盘满
   孤儿继续写文件    符号链接逃逸     打 169.254.169.254  cgroup OOM

读图：四个缺口对应四类事故，而不是四种「加固等级」。一个系统可以文件只读、网络全通，此时它挡的是「改坏文件」，不是「泄露文件」；也可以网络默认拒绝、文件全通，此时它挡的是「外发」，不是「删库」。评估一个沙箱，先问「它声称挡哪一类」，再问「这一类的最小复现能不能穿过去」。

这张表说明什么：每一层都有明确的「挡不住」。工程上不是追求「全部挡住」，而是把挡不住的部分放到下一层（例如进程组挡不住 setsid，就加 cgroup kill；openat2 挡不住已打开 fd，就在 exec 前关闭 fd）。下一节从进程层开始。

3.2 进程边界：fork/exec/wait、进程组与退出状态

进程边界要回答两个问题：谁能被创建，以及谁能被杀死。第一个问题靠 PID 命名空间、UID、pids.max；第二个问题靠进程组、会话、pidfd 与 cgroup。很多 runner 只做了「创建」，没做「杀死」，于是超时之后留下一个继续写文件的孤儿。

先看一次工具调用的真实路径。subprocess.Popen 在 POSIX 上通常走 fork（或 posix_spawn）+ execve：子进程先复制父进程的地址空间与 fd 表，再把自己替换成目标程序。waitpid 负责回收已退出的子进程；不回收就留下僵尸（Z），僵尸不占 CPU，但占 PID 表项。

import os
import subprocess
import sys

proc = subprocess.Popen(
    [sys.executable, "main.py"],
    cwd="/tmp/agent-7f/workspace",
    stdin=subprocess.DEVNULL,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    start_new_session=True,   # 子进程调用 setsid()，成为新会话/新进程组的首领
    close_fds=True,
)

start_new_session=True 是关键行。它让子进程成为新会话的首领，进程组 ID 等于子进程 PID；之后父进程可以用 os.killpg(proc.pid, SIGKILL) 一次杀掉整组。没有这一行，子进程继承 runner 的进程组，killpg 会误伤 runner 自己，而只 kill(proc.pid) 又杀不到孙进程。

3.2.1 进程组、会话与「谁能被杀死」

进程组（process group）是一组可以一起接收信号的进程；会话（session）是一组进程组的集合，通常与一个控制终端关联。setpgid(0, 0) 把当前进程放进以自己为组长的新组；setsid() 创建新会话并成为组长，前提是调用者不是组长。shell 的作业控制、kill %1、kill(-pgid, sig) 都建立在这两个概念上。

这张表说明什么：kill(-pgid) 的覆盖范围是「仍在组里的进程」，不是「整棵进程树」。一个孙进程只要调用 setsid()，就脱离了原组；此时 kill(-pgid) 返回成功（组还在），但那个孙进程毫发无伤。要覆盖它，需要 cgroup cgroup.kill、PID 命名空间（杀 PID 1）、或 subreaper + 遍历 /proc。

runner (pid 400, pgid 400)
  │
  ├── python main.py (pid 401, pgid 400)      ← start_new_session 后 pgid=401
  │     ├── sh -c "pytest" (pid 402, pgid 401)
  │     │     └── pytest (pid 403, pgid 401)
  │     └── server (pid 404, pgid 404)        ← 自己调了 setsid，逃出 401
  │
  └── 另一个 tool (pid 405, pgid 405)

超时处理：
  kill(401)        → 只死 python，402/403/404 继续跑
  kill(-401)       → 死 401/402/403，404 继续跑
  cgroup.kill      → 死 cgroup 内全部，包括 404

读图：三种杀法的覆盖范围逐层扩大，但只有第三种能处理「自己 setsid 的孙进程」。这不是说每次都要上 cgroup：如果工具只跑一个短命令，kill(-pgid) 足够；如果工具会启动服务、包管理器、测试框架，就必须假设它会创建新会话。判断标准不是「我们的代码不会这么做」，而是「被注入的代码会不会这么做」。

3.2.2 wait status：0x2a00 不是退出码 42 的「低字节」

这是本章最容易写错、也最容易在代码里埋 bug 的地方。waitpid 返回的 status 是内核编码，不是退出码。编码规则是：

• 低 7 位（bit 0–6）是终止信号；若进程正常退出，这 7 位为 0；
• 第 8 位（bit 7，掩码 0x80）是 core dump 标志；
• 高字节（bit 8–15）才是退出码，且只在 WIFEXITED(status) 为真时有效。

所以 status = 0x2a00 的解读是：

0x2a00 = 0010 1010 0000 0000
         └─ 高字节 0x2a = 42
                    └─ 低字节 0x00：低 7 位为 0，表示「正常退出」，不是退出码 0

WIFEXITED(0x2a00) 为真；若 status = 0x2a00，则 WEXITSTATUS(status) = 0x2a = 42（即 (status >> 8) & 0xff）。如果代码写 status & 0xff，得到的是 0x00，会把一次失败当成成功。低字节 0x00 只表示「正常退出」，不是退出码 0；它只说明低 7 位终止信号为 0。

import os

pid, status = os.waitpid(child_pid, 0)
if os.WIFEXITED(status):
    code = os.WEXITSTATUS(status)          # 正确：0x2a00 -> 42
elif os.WIFSIGNALED(status):
    sig = os.WTERMSIG(status)              # 信号编号，不含 core 位
    core = os.WCOREDUMP(status)            # 第 8 位
else:
    code = None                            # stopped/continued，按场景处理

把四种常见 status 列成表。注意 0x0100 与 0x2a00 的低字节都是 0x00，但退出码分别是 1 和 42；只看低字节无法区分。

这张表说明什么：判断「成功/失败」不能看低字节，也不能看 status == 0；必须先 WIFEXITED，再 WEXITSTATUS。被信号终止时没有退出码，只有信号编号；把 WTERMSIG 当退出码，会把 SIGKILL 记成 9，和真正的 exit(9) 混在一起。

下面是在 macOS 上实际跑出的输出（os.fork + os.waitpid，与 Linux 的编码一致）：

python3 - <<'PY'
import os, signal

def show(label, status):
    print(f"{label}: status={status:#06x} WIFEXITED={os.WIFEXITED(status)} "
          f"WEXITSTATUS={os.WEXITSTATUS(status) if os.WIFEXITED(status) else '-'} "
          f"WIFSIGNALED={os.WIFSIGNALED(status)} "
          f"WTERMSIG={os.WTERMSIG(status) if os.WIFSIGNALED(status) else '-'}")

pid = os.fork()
if pid == 0:
    os._exit(42)
_, status = os.waitpid(pid, 0)
show("exit42", status)

pid = os.fork()
if pid == 0:
    os.kill(os.getpid(), signal.SIGTERM)
    os._exit(1)
_, status = os.waitpid(pid, 0)
show("sigterm", status)

pid = os.fork()
if pid == 0:
    os.abort()
_, status = os.waitpid(pid, 0)
show("abort", status)
PY

exit42: status=0x2a00 WIFEXITED=True WEXITSTATUS=42 WIFSIGNALED=False WTERMSIG=-
sigterm: status=0x000f WIFEXITED=False WEXITSTATUS=- WIFSIGNALED=True WTERMSIG=15
abort: status=0x0006 WIFEXITED=False WEXITSTATUS=- WIFSIGNALED=True WTERMSIG=6

第三行 abort 在这台机器上得到 0x0006，没有 core 位；core 是否产生取决于 RLIMIT_CORE 与系统配置，不能假设 SIGSEGV 一定带 0x80。判断 core 要用 WCOREDUMP(status)，不要手写 status & 0x80——后者在「正常退出且退出码高位为 1」时会误判。

subprocess 已经把 waitpid 的编码解码成 returncode：正常退出是非负数，信号终止是负数（如 -9）。所以用 subprocess 时不要再次 status & 0xff；只有直接调用 os.waitpid、os.waitid 或 C 的 wait 时，才需要自己解码。

3.2.3 /proc/PID/stat 的 exit_code 也不能直接当低 8 位

Linux 的 /proc/<pid>/stat 有一个 exit_code 字段。proc_pid_stat(5) 把它列在第 52 个字段（since Linux 3.5），并明确说明：它是「the thread’s exit status in the form reported by waitpid(2)」。也就是说，它同样是 wait 编码，不是「低 8 位退出码」。awk '{print $52}' /proc/<pid>/stat 能取到字段，但不应该作为契约：

• 字段位置不是稳定 ABI，内核版本与文档可能有差异；用固定 $52 的脚本会在升级后静默读错列。
• 该字段标记为 [PT]，受 ptrace 访问检查影响；权限不足时可能显示 0，不能据此判断「正常退出」。
• 即使读到了值，也要按 WIFEXITED / WEXITSTATUS 解码，不能 & 0xff。

优先用 waitid 或 waitpid。waitid 的 siginfo_t.si_status 已经是「退出码或信号编号」本身，不再编码：si_code == CLD_EXITED 时它是退出码，CLD_KILLED / CLD_DUMPED 时它是信号编号。这比解析 /proc 更可靠，也不依赖字段位置。

import os

pid = os.fork()
if pid == 0:
    os._exit(42)

info = os.waitid(os.P_PID, pid, os.WEXITED | os.WNOWAIT)
print(info.si_code, info.si_status)   # CLD_EXITED, 42
os.waitpid(pid, 0)                    # WNOWAIT 只观察，仍需回收

si_code 1 CLD_EXITED 1 si_status 42

这段输出说明 waitid 的 si_status 是「42」，不是 0x2a00。信号终止时 si_code 为 CLD_KILLED，si_status 是信号编号（如 15），不是编码后的 status；WNOWAIT 让父进程先观察再回收，适合「先记录退出原因，再清理」的 runner，不回收仍是僵尸。

3.2.4 孤儿、僵尸与 subreaper

父进程先死、子进程还活着，子进程成为孤儿，被 reparent 到 init（PID 1）或最近的 subreaper。孤儿不是错误状态，它会继续运行、继续写文件、继续占资源。僵尸是另一种状态：子进程已死，父进程还没 wait，留下一个 Z 表项；僵尸不执行代码，但占 PID。

这张表说明什么：ps 里的 PPID=1 是孤儿的最直接证据；STAT=Z 是僵尸的最直接证据。两者经常同时出现：父进程被 kill 后，孙进程变孤儿；孙进程退出后，如果 init 没及时回收，会短暂变僵尸。

Linux 可以用 prctl(PR_SET_CHILD_SUBREAPER, 1) 把当前进程声明为 subreaper：它的后代成为孤儿时，优先 reparent 给它，而不是 init。这样 runner 可以 waitpid(-1, ...) 逐个回收，避免「孤儿被 init 收养后失联」。PR_SET_PDEATHSIG 只能在「父线程死亡」时给子进程发一个信号，不解决孙进程，也有父进程在 prctl 之前死亡的竞态，不能当进程树管理方案。

_, status = os.waitpid(pid, 0)
ok = (status & 0xff) == 0

3.3 文件边界：rootfs、挂载与 openat2

文件边界要回答一个比「读还是写」更具体的问题：这个路径最终解析到哪个 inode？ agent 可以传 ../../etc/passwd，可以传一个指向宿主目录的符号链接，可以在检查与打开之间把链接换掉，也可以继承一个早已打开的目录 fd。只在字符串层面做 startswith("/workspace")，挡不住其中任何一种。

3.3.1 chroot 不是安全边界

chroot("/newroot") 改变进程的根目录，但不改变三样东西：当前工作目录、已打开的 fd、进程的 capability。三条经典逃逸路径：cwd 在根外（chroot 不改 cwd，相对路径仍可访问根外）；已打开的目录 fd（子进程 fchdir(fd) 后相对路径落在宿主）；保留 CAP_SYS_CHROOT/CAP_SYS_ADMIN（能再次 chroot、mount、mknod）。

所以 chroot 只能作为「路径命名空间」的粗粒度整形，不能单独当沙箱。真正的 rootfs 切换要在 mount namespace 里做 pivot_root，并在 exec 前关闭无关 fd、丢掉 capability（第 4 章）。

3.3.2 pivot_root 与 mount namespace

pivot_root(new_root, put_old) 把当前进程的根切换到 new_root，并把旧根挂到 put_old 下；随后 umount2(put_old, MNT_DETACH) 把旧根摘掉。它要求调用者拥有 CAP_SYS_ADMIN（通常在 user namespace 内），new_root 是一个挂载点，put_old 在 new_root 之下。

/* Linux 6.8 / Ubuntu 24.04；示意，未在本机编译 */
unshare(CLONE_NEWNS);
mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL);   /* 阻止挂载传播到宿主 */
mount("rootfs", "/newroot", NULL, MS_BIND | MS_REC, NULL);
chdir("/newroot");
pivot_root(".", ".");
umount2(".", MNT_DETACH);                            /* 摘掉旧根 */
chdir("/");

mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL) 这一行经常被省略。没有它，容器内的挂载可能传播回宿主 mount namespace；一个 mount --bind 就能把宿主目录映射进来。挂载传播是文件边界的一部分，不是「容器启动细节」。

pivot_root(".", ".") 是常见技巧：先把 cwd 切到新根，再把新旧根都设为 .，调用后旧根挂在当前目录上，直接 umount2(".", MNT_DETACH) 即可。它比「先建 put_old 目录再挂」少一次路径操作，也少一个可被替换的目录项。

3.3.3 bind mount、overlayfs 与只读 rootfs

一个 agent 的文件布局通常由三层组成：

这张表说明什么：只读 rootfs 只保护「系统文件不被改」，不保护「工作区不被写满」，也不保护「临时目录不成为逃逸通道」。/tmp 用 tmpfs 并设 size=，既限制容量，又避免落到宿主磁盘；noexec 防止把可执行文件写进 /tmp 再运行，但如果测试需要执行工作区里的二进制，就不能对 /workspace 一律 noexec。

bind mount 把宿主的一个目录映射进容器。它很方便，也很危险：如果 bind 的源是 /var/run/docker.sock、/proc、/sys 或宿主 home，容器内的进程就获得了对应能力。实践中的规则是「只 bind 工作区，且源目录由 runner 独占创建」；不要 bind 宿主的 /tmp，因为宿主 /tmp 里可能有其他进程的 socket 与临时凭证。

overlayfs 用「只读下层 + 可写上层的合并视图」实现「镜像不变、容器可写」：

# Linux 6.8 / Ubuntu 24.04；需要 CAP_SYS_ADMIN（可在 user namespace 内）
mount -t overlay overlay \
  -o lowerdir=/images/base,upperdir=/run/agent/upper,workdir=/run/agent/work \
  /run/agent/merged

upperdir 与 workdir 必须在同一个文件系统上；upperdir 建议放在 tmpfs 或独立卷上，避免写满宿主根分区。overlayfs 的 whiteout 机制会让「删除下层文件」变成「在上层写一个白字符设备」，因此上层不是普通的「差异目录」，不能随便让 agent 直接操作。对 agent 来说，更简单的做法是「只读镜像 + 可写 workspace」，而不是把整个 / 做成 overlay。

3.3.4 openat2：把「检查」变成「原子解析」

openat2(2) 是 Linux 5.6 引入的扩展，核心是 struct open_how 里的 resolve 位掩码。它把「路径解析策略」交给内核，在一次系统调用里完成，避免用户态「先 realpath 再 open」的 TOCTOU 竞态。

这张表说明什么：RESOLVE_BENEATH 与 RESOLVE_IN_ROOT 不是同义词。前者要求路径不能向上逃，绝对路径直接拒绝；后者把 dirfd 当根，绝对路径会被解释为「根下的路径」。如果 agent 传入 /workspace/a.txt，用 BENEATH 会失败，用 IN_ROOT 会解析成 <dirfd>/workspace/a.txt；选哪个取决于你的 API 接受相对路径还是绝对路径。

/* Linux 5.6+；glibc 无 wrapper，需要 syscall(SYS_openat2, ...) */
#include <fcntl.h>
#include <linux/openat2.h>
#include <sys/syscall.h>
#include <unistd.h>

int safe_open(int dirfd, const char *path) {
    struct open_how how = {
        .flags = O_RDONLY | O_CLOEXEC,
        .resolve = RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS | RESOLVE_NO_MAGICLINKS,
    };
    return (int)syscall(SYS_openat2, dirfd, path, &how, sizeof(how));
}

这段代码的关键不是 O_RDONLY，而是 resolve 三个标志：BENEATH 挡住 .. 与绝对路径，NO_SYMLINKS 挡住链接替换，NO_MAGICLINKS 挡住 /proc/self/fd。O_NOFOLLOW 只能管最后一个分量；如果路径中间有一个符号链接，它照样会跟过去。openat2 的 NO_SYMLINKS 管所有分量，这是它与 O_NOFOLLOW 的核心差别。

openat2 的错误码也要读对：EXDEV 表示「解析试图逃出根」，ELOOP 表示「遇到不允许的链接」，EAGAIN 表示「RESOLVE_BENEATH/IN_ROOT 在竞态下无法保证，可重试」，EINVAL 表示「标志未知或组合非法」。把 EXDEV 当成「文件不存在」会让 agent 以为路径写错，反复重试；正确做法是把它翻译成 EPATH，并终止这次工具调用。

3.3.5 路径穿越与符号链接竞态

最常见的错误实现是：

from pathlib import Path

root = Path("/tmp/agent-7f/workspace").resolve()
target = (root / user_path).resolve()
if not str(target).startswith(str(root) + "/"):
    raise PermissionError("escape")
fd = open(target, "rb")          # ← 检查与打开之间，链接可能被换掉

这段代码有四个问题：

1. resolve() 之后再 open() 不是原子的；攻击者可以在两步之间把 target 换成指向 /etc/shadow 的符号链接。
2. startswith(str(root) + "/") 对 root 本身、大小写不敏感文件系统、.. 归一化后的边界都要额外处理；用 Path.relative_to 更稳，但仍不是原子。
3. 如果 user_path 是绝对路径，root / user_path 会得到绝对路径，直接跳出 root；Path 的 / 运算符对绝对右操作数不做「拼接」。
4. 没有处理 magic link；/proc/self/fd/N 可以指向任意已打开对象。

正确的顺序是「用内核的解析器做边界」：打开 root 的 fd，用 openat2(root_fd, rel, RESOLVE_BENEATH|...)；或者逐段 openat(..., O_NOFOLLOW|O_DIRECTORY)，每段都校验 fstat 的 st_dev/st_ino。检查与使用必须是同一个 fd，而不是同一个字符串。

O_NOFOLLOW 只拒绝最后一段是符号链接；如果最后一段是普通文件，但它的父目录是符号链接，O_NOFOLLOW 不会拦。要逐段拒绝，必须对每个中间目录也用 O_NOFOLLOW | O_DIRECTORY，或者直接用 openat2 的 NO_SYMLINKS。

3.3.6 fd 继承与 close-on-exec

fork 复制整个 fd 表；exec 默认保留所有没有 FD_CLOEXEC 的 fd。一个被泄漏的目录 fd 可以绕过 chroot：子进程 fchdir(fd) 后，相对路径就落在宿主目录里。一个被泄漏的 socket 可以让子进程绕过网络策略：它不需要新建连接，直接写继承来的 fd。

这张表说明什么：close-on-exec 是「默认不传」，不是「默认传」。Python 的 subprocess 默认 close_fds=True，但父进程自己 os.open 的 fd 如果没有设 non-inheritable，仍可能被 fork 后的子进程继承；PEP 446 让 Python 3.4+ 打开的 fd 默认 non-inheritable，但 os.dup、C 扩展、第三方库可能改变这一点。runner 应该在 preexec_fn 或 close_range 里做一次兜底关闭，而不是相信每个库都守规矩。

3.4 网络边界：netns、DNS 与 egress

网络边界要回答：这个进程能把包发到哪里，能把哪些名字解析成地址？ 只配一个 HTTP_PROXY 环境变量不算边界，因为环境变量只约束「愿意遵守它的 HTTP 客户端」；agent 可以 socket() 直接连 IP，可以发 DNS 查询，可以用 ICMP，可以走 IPv6。网络隔离必须落在内核的路由与过滤上。

3.4.1 netns + veth：先把「没有路由」做出来

Linux 的 network namespace 给进程一套独立的网卡、路由表、iptables/nftables 规则与 /proc/net。新建的 netns 只有 loopback，且默认是 down 的；没有 veth 就没有任何出口。这是最强的默认拒绝：不是「先放行再过滤」，而是「根本没有路」。

# Linux 6.8 / Ubuntu 24.04；需要 root 或 CAP_NET_ADMIN
ip netns add agent-7f
ip link add veth-host type veth peer name veth-agent
ip link set veth-agent netns agent-7f

ip addr add 10.7.0.1/24 dev veth-host
ip link set veth-host up

ip netns exec agent-7f ip link set lo up
ip netns exec agent-7f ip addr add 10.7.0.2/24 dev veth-agent
ip netns exec agent-7f ip link set veth-agent up
ip netns exec agent-7f ip route add default via 10.7.0.1

这段脚本建了一对 veth，把一端放进 netns，给两端配地址，并在 netns 内加默认路由。此时 agent 的包会走到宿主侧的 veth-host；宿主是否转发、是否 NAT、是否过滤，决定了它能不能出网。不要配默认路由，除非你确实要让它出网；只配到代理地址的 /32 路由，是更常见的做法。

这张表说明什么：netns 本身只提供「独立的网络栈」，不自动提供「安全的出口」。第三行有 NAT，公网与元数据都通；第四行才把「能到哪」收缩到代理一个地址。代理仍然是可达的，所以代理自身的 SSRF 防护不能省。

3.4.2 默认拒绝的 egress 规则

在 netns 内用 nftables 做默认拒绝，只放行代理地址与已建立连接。规则顺序很重要：ct state established,related accept 要放在 drop 之前，否则回包也被丢。

# Linux 6.8 / Ubuntu 24.04；在 agent netns 内执行
nft add table inet agent
nft add chain inet agent out '{ type filter hook output priority 0; policy drop; }'
nft add rule inet agent out oifname "lo" accept
nft add rule inet agent out ip daddr 10.7.0.1 tcp dport 3128 accept
nft add rule inet agent out ct state established,related accept
nft add rule inet agent out ip daddr 169.254.169.254 drop
nft add rule inet agent out ip6 daddr fd00:ec2::254 drop

这段规则的意思是：默认丢弃所有出站，只允许 loopback、代理 10.7.0.1:3128、已建立连接的回包；元数据地址显式丢弃（即使前面的规则漏了，也有兜底）。inet 表同时覆盖 IPv4 与 IPv6；如果只用 ip 表，IPv6 流量会从另一条路出去。policy drop 是核心，不是最后那条 drop。

代理地址最好用独立的 bridge/veth，不要用宿主默认网关。否则 agent 可以扫 10.7.0.1 上的其他端口，找到宿主的内部服务。代理只监听一个端口，并且只接受来自 agent 网段的连接；代理进程本身以低权限运行，不能访问云元数据。

3.4.3 DNS：固定解析器，解析结果要钉住

DNS 是网络边界里最容易被忽略的一层。如果沙箱为了装包放行了 DNS（很多镜像需要），agent 就可以把数据编码进查询：<base32-secret>.attacker.example 这样的查询会到达攻击者的权威服务器。允许任意 DNS 就等于允许一条低速外带通道。

三种做法，强度递增：

1. 固定 /etc/resolv.conf：只指向一个受控 resolver，禁止 agent 修改；resolver 只解析 allowlist 内的名字。
2. 本地 resolver + 固定映射：在 netns 内跑一个只读的 DNS 代理，把 allowlist 名字映射到固定 IP，其他名字返回 NXDOMAIN；同时只允许到该 resolver 的 53 端口。
3. 不做 DNS，直接连 IP：代理地址用 IP 写死，agent 只能访问代理；代理负责对外的名字解析与 allowlist。这是最强、也最容易审计的形态。

DNS rebinding 是「固定解析器」也挡不住的一类攻击：攻击者控制一个域名，第一次解析返回公网 IP，通过你的 allowlist 检查；TTL 设得很短，第二次解析返回 127.0.0.1 或 169.254.169.254，客户端重新解析后就连到了内网。防御不是「再查一次 DNS」，而是：

• 在受控 resolver 里解析一次，把 IP 钉住，后续连接直接用 IP；
• 连接后 getpeername() 再校验一次对端地址，拒绝 loopback、link-local、private、multicast；
• 在 netns 层默认拒绝这些地址段，即使应用层被骗也出不去；
• 代理不要跟随任意重定向；重定向目标也要重新做地址校验。

SSRF 的入口不止「用户给了一个 URL」。agent 读到的网页、工具返回的 JSON、MCP server 的描述，都可能包含 URL。常见目标包括：

这张表说明什么：只封 169.254.169.254 不够。IPv6 有独立的元数据地址，私网有大量等价目标，URL 还可以用十进制/八进制/十六进制 IP、IPv4-mapped IPv6（::ffff:169.254.169.254）、DNS rebinding、HTTP 重定向来绕过字符串匹配。正确做法是「解析成 IP 后按地址段拒绝」，而不是「URL 里不包含某个字符串」。

3.4.4 为什么 HTTP 代理不能单独当隔离

代理是应用层组件，它只能约束「愿意把请求交给它」的客户端。下面每一条都能绕过只配了 HTTP_PROXY 的沙箱：

• raw socket：socket.connect(("169.254.169.254", 80)) 不读 HTTP_PROXY；
• DNS：getaddrinfo 走系统 resolver，查询本身就能外带数据；
• 非 HTTP 协议：ICMP、gRPC、Redis、Postgres、WebSocket 都可以直接连；
• 代理的 CONNECT：如果代理允许任意 CONNECT，HTTPS 只是把目标藏在隧道里；
• 代理自身：代理运行在宿主网络里，可能能访问元数据；它被 SSRF 利用时，沙箱的 netns 也救不了；
• IPv6：只给代理配了 IPv4 规则，IPv6 可能仍然可路由。

所以网络边界要「两层一起用」：netns + 默认拒绝把「能到达的地址」收缩到代理；代理再做「允许哪些域名/路径/方法」的应用层策略。前者是内核强制，后者是业务策略；只有前者，代理被绕过；只有后者，raw socket 不受约束。

3.5 资源边界：rlimit、cgroup v2 与墙钟

资源边界要回答：一次失控最多能烧掉多少？ 这里的「资源」至少包括 CPU 时间、地址空间、fd 数、进程数、单文件大小、磁盘总量、墙钟。它们由三套不同的机制管理：rlimit 管每进程，cgroup v2 管聚合，墙钟由外部计时器管。混用这三套机制，会出现「设了限制但没生效」的假象。

3.5.1 rlimit：软限、硬限与「每进程」

getrlimit 返回 (soft, hard)：soft 是当前生效的限制，hard 是 soft 的上界。非特权进程可以降低 soft 或 hard，可以把 soft 提高到不超过 hard，但不能提高 hard；提高 hard 需要 CAP_SYS_RESOURCE。setrlimit 在越界时返回 EPERM 或 EINVAL。

这张表说明什么：六个限制里没有一个能单独给出「总资源上限」。RLIMIT_NPROC 按 UID 计数，在共享账号上会误伤；RLIMIT_FSIZE 只管单文件，agent 可以写一万个 1 MiB 文件；RLIMIT_AS 管虚拟地址空间，不管 RSS，也不管 page cache。真正的聚合限制要靠 cgroup。

在 Python 里设置 rlimit，要放在 preexec_fn 里，让它在 fork 之后、exec 之前生效：

import resource

def apply_limits(cpu_s: int, fsize: int, nofile: int) -> None:
    resource.setrlimit(resource.RLIMIT_CORE, (0, 0))
    resource.setrlimit(resource.RLIMIT_CPU, (cpu_s, cpu_s + 1))
    resource.setrlimit(resource.RLIMIT_FSIZE, (fsize, fsize))
    resource.setrlimit(resource.RLIMIT_NOFILE, (nofile, nofile))
    # macOS 上 RLIMIT_AS 可能直接 ValueError；Linux 上才设
    # resource.setrlimit(resource.RLIMIT_AS, (as_bytes, as_bytes))

RLIMIT_CPU 的软限设为 cpu_s、硬限设为 cpu_s + 1：软限到时先发 SIGXCPU，进程可以捕获并做清理；如果它继续跑，硬限到时 SIGKILL。只设软限不设硬限，进程可以忽略 SIGXCPU 继续烧 CPU；只设硬限不设软限，进程没有清理机会。

实际跑一次，观察 RLIMIT_NOFILE 与 RLIMIT_CPU 的效果：

python3 experiments/ch03/sandbox_runner.py \
  --code 'import resource; print(resource.getrlimit(resource.RLIMIT_NOFILE))' \
  --nofile 32

{"ok": true, "exit_code": 0, "signal": null, "timed_out": false,
 "stdout": "(32, 32)\n", "stderr": ""}

python3 experiments/ch03/sandbox_runner.py \
  --code 'while True: pass' --cpu 1 --timeout 5

{"ok": false, "exit_code": null, "signal": 24, "signal_name": "SIGXCPU",
 "timed_out": false, "duration_ms": 1013}

第二行说明 RLIMIT_CPU 到点时进程收到 SIGXCPU（24），不是 SIGKILL；它在约 1 秒后死掉，早于 5 秒墙钟。如果进程捕获并忽略 SIGXCPU，硬限 2 秒会补一个 SIGKILL。这也是为什么 RLIMIT_CPU 不能替代墙钟：一个 sleep(3600) 的进程 CPU 时间为 0，永远不会触发 RLIMIT_CPU。

ulimit 是 shell 对 rlimit 的封装，但它的默认行为经常被记错。bash 5.3 的 help ulimit 与 man bash 都写明：不带 -S/-H 时，同时设置软限和硬限。下面是在本机实际跑出的序列：

bash -c '
printf "start soft=%s hard=%s\n" "$(ulimit -Sn)" "$(ulimit -Hn)"
ulimit -Sn 4096
printf "after -S 4096: soft=%s hard=%s\n" "$(ulimit -Sn)" "$(ulimit -Hn)"
ulimit -Hn 8192
printf "after -H 8192: soft=%s hard=%s\n" "$(ulimit -Sn)" "$(ulimit -Hn)"
ulimit -Hn 4096
ulimit -Hn unlimited
'

start soft=1048575 hard=unlimited
after -S 4096: soft=4096 hard=unlimited
after -H 8192: soft=4096 hard=8192
bash: line 8: ulimit: open files: cannot modify limit: Operation not permitted

这段输出说明三件事：-S 只改软限，-H 只改硬限；硬限不能低于软限，所以 -Hn 4096 与软限相等时可以，低于 4096 会 EINVAL；非特权进程不能把硬限从 8192 抬回 unlimited，报 Operation not permitted。如果写成 ulimit -n 512，硬限也会被一起改成 512：

bash -c 'printf "before soft=%s hard=%s\n" "$(ulimit -Sn)" "$(ulimit -Hn)"; ulimit -n 512; printf "after soft=%s hard=%s\n" "$(ulimit -Sn)" "$(ulimit -Hn)"'

before soft=1048575 hard=unlimited
after soft=512 hard=512

所以「ulimit 默认只改软限」对 POSIX shell 与 zsh 成立，对 bash 不成立：bash 不带 -S/-H 时同时改两者。要可移植地只改软限，写 ulimit -S；要只改硬限，写 ulimit -H；软限不得超过硬限，跨 shell 的脚本不要依赖默认值。

3.5.2 rlimit 是每进程，不是聚合

这就是为什么「给每个子进程设 256 MiB」不等于「这个 agent 最多用 256 MiB」。一个 fork 炸弹不需要每个进程都吃满 256 MiB；它只需要制造足够多的进程，让页表、内核栈、调度器一起把宿主拖慢。聚合限制要放在 cgroup 的 memory.max 与 pids.max 上。

3.5.3 cgroup v2：memory.max、pids.max、cpu.max

cgroup v2 是统一的层级：一个进程属于一个 cgroup，资源限制写在 cgroup 目录的文件里。对 agent 沙箱，最常用的是四个文件：

这张表说明什么：memory.max 与 pids.max 是聚合限制，正好补上 rlimit 的缺口；cpu.max 是带宽限制，不是「CPU 时间配额」，它按周期限流，进程不会被杀，只会被 throttled。memory.oom.group=1 很重要：默认 OOM 只杀一个进程，agent 可能留下一个「父进程死了、子进程还在写」的半死状态；设 1 让整个 cgroup 一起死。

# Linux 6.8 / Ubuntu 24.04；需要 cgroup v2 且已挂载 /sys/fs/cgroup
CG=/sys/fs/cgroup/agent-7f
mkdir -p "$CG"
echo 268435456 > "$CG/memory.max"
echo 64 > "$CG/pids.max"
echo "50000 100000" > "$CG/cpu.max"
echo 1 > "$CG/memory.oom.group"
echo $$ > "$CG/cgroup.procs"

这段脚本把当前 shell 放进 cgroup，并设 256 MiB 内存、64 个任务、0.5 CPU。cpu.max 的两个数字是「配额 周期」，单位微秒；50000 100000 表示每 100 ms 最多跑 50 ms，即 0.5 个 CPU。pids.max 统计的是任务（线程也算），不是进程；一个多线程 Python 进程可能一个进程就占十几个任务。

观测 cgroup 的状态。下面为便于阅读，把文件名标在值前；cat 本身只输出值，不输出这些标签：

cat "$CG/memory.current" "$CG/memory.max"
cat "$CG/memory.events"
cat "$CG/pids.current" "$CG/pids.max" "$CG/pids.events"
cat "$CG/cgroup.events"
cat "$CG/cpu.stat"

memory.current=184549376
memory.max=268435456
max 3
oom 1
oom_kill 1
oom_group_kill 1
pids.current=7
pids.max=64
max 0
populated 1
frozen 0
nr_periods 21
nr_throttled 4
throttled_usec 82031

这段输出是 Linux-only 的形态（本机 macOS 没有 cgroup v2）；数值会随负载变化，字段名是稳定的。memory.events 的 max 3 表示「三次接近上限」，oom 1/oom_kill 1 表示真的发生了 OOM；pids.events 的 max 0 表示没有触发进程数上限；cpu.stat 的 nr_throttled 4 表示被限流四次。排障时先看事件计数，再看 current，否则只能看到「现在没事」，看不到「刚刚差点出事」。

cgroup.kill 是收尸的最后一招：向 cgroup.kill 写 1，内核会杀掉 cgroup 及其子 cgroup 的所有进程，且能处理并发 fork 与进程迁移。它比 kill(-pgid) 更强，因为不依赖进程组关系；比遍历 /proc 更可靠，因为没有「遍历时又 fork 一个」的竞态。代价是需要 cgroup v2 与写权限。

echo 1 > "$CG/cgroup.kill"

如果需要「先冻结、再检查、再决定」，用 cgroup.freeze：写 1 后进程被停止，cgroup.events 的 frozen 变为 1；检查完再解冻或 kill。冻结不是终止，冻结的进程仍然占着内存与 PID；它适合「取现场」而不是「省资源」。

3.5.4 墙钟与 CPU 时间不是一回事

这张表说明什么：四类限制互补，不能互相替代。RLIMIT_CPU=2 对一个 sleep(3600) 完全无效；墙钟超时对一个 200 ms 的忙循环可能太晚；memory.max 管不住磁盘；磁盘配额管不住 fd 泄漏。一个可靠的 runner 至少要有「墙钟 + CPU + 内存/进程数 + 输出上限」四道。

墙钟超时的实现要避免两个坑：一是只在循环里检查 time.time() > deadline，当子进程阻塞在 read() 时循环根本没机会跑；二是用 signal.alarm，它只作用于当前线程，且阻塞系统调用可能被 SA_RESTART 重启。正确做法是「父进程 poll + 独立计时器 + 到点 killpg」，或者用 pidfd/cgroup.kill；时间检查必须在不会被子进程阻塞的地方执行。

3.5.5 磁盘：RLIMIT_FSIZE 之外的总量

RLIMIT_FSIZE 限制单个文件，不限制文件数量，也不限制目录总大小。agent 可以写一万个 1 MiB 文件，绕过单文件限制，把磁盘写满。总磁盘限制要靠：

• tmpfs size=：把 /tmp 与工作区放在 tmpfs，超出 size 直接 ENOSPC，且不落宿主磁盘；
• 文件系统配额：XFS project quota、ext4 的 quota，按目录/项目限制总量；
• 独立卷：给每个 run 一个固定大小的卷，run 结束就删；
• 预检 + 监控：启动前检查可用空间，运行中定期 du，超过阈值就终止；
• 输出上限：stdout/stderr 也要限，否则一个 print 循环就能把日志盘写满。

ENOSPC 应该被当作不可重试错误：重试只会继续写，可能把宿主其他服务也拖垮。runner 要把 ENOSPC 翻译成 EDISK，保留现场（哪些文件、多大），清理临时目录后再报告失败。

3.6 组合：从 rlimit 到 OCI config.json

前面五节是「每一层怎么做」。真实系统不会为每一层写一套独立的启动代码；它把这些策略交给一个容器运行时，运行时再翻译成 clone/unshare/mount/setrlimit/cgroup 写入。OCI Runtime Spec 就是这层翻译的契约：一个 bundle 里有 config.json 和 rootfs，运行时读 config.json，创建容器并执行 process.args。

agent 沙箱不必自己实现 OCI。你可以用 runc/crun/youki，也可以用云厂商的沙箱服务；但你必须理解 config.json 的每个字段对应哪一层，否则「配了容器」仍然可能留下缺口。下面是一份最小但完整的配置，字段按 1.3.0 版本写。

{
  "ociVersion": "1.3.0",
  "process": {
    "terminal": false,
    "user": {"uid": 65534, "gid": 65534},
    "args": ["python3", "/workspace/main.py"],
    "env": ["PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/workspace", "LANG=C.UTF-8"],
    "cwd": "/workspace",
    "capabilities": {"bounding": [], "effective": [], "inheritable": [], "permitted": [], "ambient": []},
    "rlimits": [
      {"type": "RLIMIT_CPU", "soft": 2, "hard": 3},
      {"type": "RLIMIT_NOFILE", "soft": 64, "hard": 64},
      {"type": "RLIMIT_FSIZE", "soft": 8388608, "hard": 8388608}
    ],
    "noNewPrivileges": true
  },
  "root": {"path": "rootfs", "readonly": true},
  "mounts": [
    {"destination": "/workspace", "type": "bind", "source": "/tmp/agent-7f/workspace",
     "options": ["rbind", "rw", "nosuid", "nodev"]},
    {"destination": "/tmp", "type": "tmpfs", "source": "tmpfs",
     "options": ["nosuid", "nodev", "noexec", "size=64m"]}
  ],
  "linux": {
    "namespaces": [{"type": "pid"}, {"type": "network"}, {"type": "mount"},
                   {"type": "ipc"}, {"type": "uts"}, {"type": "user"}, {"type": "cgroup"}],
    "uidMappings": [{"containerID": 0, "hostID": 100000, "size": 65536}],
    "gidMappings": [{"containerID": 0, "hostID": 100000, "size": 65536}],
    "resources": {
      "memory": {"limit": 268435456, "swap": 0, "disableOOMKiller": false},
      "cpu": {"quota": 50000, "period": 100000},
      "pids": {"limit": 64}
    },
    "seccomp": {"defaultAction": "SCMP_ACT_ERRNO", "architectures": ["SCMP_ARCH_X86_64"]}
  },
  "hooks": {
    "createRuntime": [{"path": "/usr/bin/agent-hook", "args": ["agent-hook", "setup"], "timeout": 5}],
    "poststop": [{"path": "/usr/bin/agent-hook", "args": ["agent-hook", "cleanup"], "timeout": 5}]
  },
  "annotations": {"org.example.agent.run_id": "run-7f"}
}

这份 JSON 里没有一行是「装饰」：root.readonly 是文件边界，linux.namespaces 是进程/文件/网络边界，linux.resources 是资源边界。示例按 x86_64 写；ARM 主机把 SCMP_ARCH_X86_64 改成 SCMP_ARCH_AARCH64。seccomp 只有默认拒绝，真实配置还要按镜像生成 syscalls 白名单；空 allowlist 连 execve 都会被拒。下面逐项映射。

这张表说明什么：OCI 字段与内核机制不是一一对应的「配置项」，而是「策略 → 机制」的翻译。process.rlimits 翻译成 setrlimit，linux.resources.memory.limit 翻译成 memory.max，root.readonly 翻译成 mount 的只读重挂载。运行时可能跳过它不支持的字段；配置写完必须用 runc spec/crun spec 生成基线，再用 jq 检查关键字段是否真的存在。

3.6.1 字段级的坑

process.args 不是 shell 命令。写 "args": ["sh", "-c", "pytest -q"] 会启动一个 shell，shell 会做词法展开、通配、变量替换；agent 传入的参数里如果含 ;、$()、反引号，就会被 shell 解释。要么直接 ["pytest", "-q"]，要么把用户输入作为单独的参数传给一个不做 shell 解释的程序。这个坑与第 2 章的工具参数校验是同一个问题的两层：schema 管语法，OCI 管执行。

process.capabilities 的五个集合要一起清空。只清 effective，permitted/inheritable 还在，进程仍可能通过 capset 把能力提回来；bounding 是能力的上界，不清 bounding，后续 exec 仍可能获得文件 capability。第 4 章会展开五集合与降权顺序，这里先记住「空数组不是省略，是显式清空」。

linux.namespaces 不写 network，容器就继承宿主的网络栈；不写 pid，容器内能看到宿主进程；不写 user，容器内的 root 就是宿主 root（除非运行时另有映射）。很多人以为「容器默认隔离所有 namespace」，实际上 OCI 只创建你列出的 namespace；没列的继承运行时。把七个都列出来，再按需要去掉，不要反过来。

linux.resources.memory.limit 与 process.rlimits 的 RLIMIT_AS 不是一回事：前者是 cgroup 聚合内存，后者是每进程地址空间。memory.limit 到顶会触发 OOM killer；RLIMIT_AS 到顶让 mmap 返回 ENOMEM。两者都配，才有「单进程不超、总量也不超」的效果。

hooks 是最容易被忽视的提权面。createRuntime 在宿主 namespace 执行，createContainer 在容器 namespace 执行，poststop 在容器删除后执行；它们的 path 是宿主路径，不是容器内路径。一个可写的 hook 脚本等于一个宿主执行入口。生产环境应把 hook 路径设为只读、由 runner 独占，且不要把 agent 可写的目录放进 hook 的搜索路径。

3.6.2 版本与兼容性

OCI Runtime Spec 1.3.0 于 2025-11-04 发布，延续 1.x 的向后兼容；prestart 钩子已废弃，推荐 createRuntime/createContainer/startContainer。不同运行时（runc、crun、youki）对字段的支持程度不同，尤其是 linux.resources.unified、idmap 挂载、seccomp 的 listenerPath。不要假设「写了就一定生效」；用运行时的 spec 命令生成基线，再在目标内核上做一次 strace -f 验证关键系统调用。

3.7 失败案例：fork 炸弹、磁盘写满与孤儿进程

三类事故在代码 agent 上反复出现，因为它们的触发条件都很普通：一个死循环、一次大文件写入、一个超时。下面每个案例都按「触发条件 → 观测证据 → 修复」写；能在本机复现的给出真实输出，只能在 Linux 上复现的明确标注。

3.7.1 fork 炸弹：先耗尽 PID，再拖垮调度器

shell 里的经典写法是 :(){ :|:& };:：定义一个名为 : 的函数，函数体把自己通过管道喂给自己并在后台运行。每次调用产生两个新进程，进程数指数增长。Python 版本更直白：

import os

while True:
    try:
        os.fork()
    except OSError:
        break

这段代码不要在没有 pids.max 的宿主上运行。它的目的不是「算得快」，而是让 PID 表、内核栈、调度器一起过载；即使每个进程只睡一秒，宿主也会因为上下文切换而失去响应。RLIMIT_NPROC 能挡一部分，但它按真实 UID 计数：runner 和 agent 共用一个账号时，限制 agent 也会限制 runner 自己；多租户下更不可靠。

Linux 上的观测证据是 pids.current 贴近 pids.max，pids.events 的 max 持续增加，应用层看到 fork: Resource temporarily unavailable（EAGAIN）。这些命令只能在 cgroup v2 环境跑：

# Linux 6.8 / Ubuntu 24.04
cat /sys/fs/cgroup/agent-7f/pids.current
cat /sys/fs/cgroup/agent-7f/pids.max
cat /sys/fs/cgroup/agent-7f/pids.events

修复不是「让 agent 别写 fork 炸弹」，而是让它写了也炸不穿：

• pids.max 设成一个够用的小值（例如 64），fork 到上限直接 EAGAIN；
• memory.oom.group=1，内存到顶时整组一起死，不留下半死状态；
• 超时后写 cgroup.kill，不依赖进程组；
• 监控 pids.events 的 max，突增就告警并终止 run。

pids.max 统计任务数，线程也算。一个 16 线程的 Python 进程会占 17 个任务；把 pids.max 设成 8 会让正常的多线程工具直接失败。限制值要按「最大合法并发 + 余量」定，不是越小越好。

3.7.2 磁盘写满：ENOSPC 不是「再试一次」

代码 agent 很容易写满磁盘：下载依赖、生成构建产物、把测试日志追加到同一个文件、在循环里 print。如果工作区与宿主根分区共享，受害的不只是这个 run，而是整台机器。下面是在 macOS 上用 8 MiB 磁盘映像复现的真实现场：

hdiutil create -size 8m -fs HFS+ -volname TinySandbox /tmp/tiny.dmg
hdiutil attach /tmp/tiny.dmg -nobrowse -mountpoint /tmp/tinymnt
dd if=/dev/zero of=/tmp/tinymnt/fill.bin bs=1048576
echo "dd_rc=$?"
df -h /tmp/tinymnt

dd: /tmp/tinymnt/fill.bin: No space left on device
8+0 records in
7+0 records out
7340032 bytes transferred in 0.000857 secs (8564798133 bytes/sec)
dd_rc=1
/dev/disk10s1   8.0Mi   7.2Mi   788Ki    91%       3  4.3G    0%   /private/tmp/tinymnt

这段输出有三个关键点：写入在 7 MiB 处失败，文件停在 7340032 字节（不是「要么全写、要么不写」）；df 显示 788 KiB 可用，但 HFS+ 的元数据与保留块让实际可用空间更小；dd 返回 1，但很多程序会忽略 write 的短写，继续报告成功。agent 如果在 write 后不检查返回值，就会把一个截断的文件当成完整产物。

修复要分三层：

1. 隔离：工作区放在独立卷或 tmpfs 上，设 size=；不要与宿主根分区共享。
2. 限额：RLIMIT_FSIZE 限制单文件；XFS project quota 或卷大小限制总量；输出重定向到有上限的日志文件。
3. 语义：把 ENOSPC 翻译成不可重试的 EDISK，保留「哪些文件、写了多少、剩余空间」的证据，清理后终止；不要自动重试同一个写操作。

RLIMIT_FSIZE 只能限制单文件。agent 可以写一万个 1 MiB 文件，仍然把卷写满；所以「单文件限制 + 卷配额」要一起用。df 的可用空间也不是安全余量：ext4 默认给 root 保留 5%，HFS+/APFS 有元数据开销，容器镜像层还有写时复制。

3.7.3 孤儿进程：父进程死了，写文件的还在

这是本章最值得亲手复现的案例。experiments/ch03/orphan_demo.py 启动一个父进程，父进程再启动一个子进程；子进程睡 1.5 秒后写 late.txt。演示脚本先只 kill 父进程：

python3 experiments/ch03/orphan_demo.py

parent pid=91455 pgid=91455
sent SIGKILL to parent only
late.txt exists: True
late.txt content: 'still alive'

父进程收到 SIGKILL 后立即死亡，子进程被 reparent 到 PID 1，继续睡完 1.5 秒并写文件。此时 runner 已经认为「超时，进程已终止」，但磁盘上多了一个 late.txt。如果这个文件是构建产物、迁移脚本或上传标记，下游会基于一个「不该存在」的结果继续。

修复只改一行：向进程组发信号，而不是向父 PID 发信号。

python3 experiments/ch03/orphan_demo.py --kill-group

parent pid=91475 pgid=91475
sent SIGKILL to process group
late.txt exists: False

os.killpg(pgid, SIGKILL) 覆盖父进程与仍在同一进程组的子进程。它仍然挡不住 setsid() 的孙进程；那需要 cgroup cgroup.kill 或 PID 命名空间。修复分四层：killpg 覆盖同组；PR_SET_CHILD_SUBREAPER + waitpid(-1) 回收被 reparent 的后代；cgroup.kill 覆盖逃组后代；PID 命名空间把「杀 PID 1」变成「杀整棵树」。

$ ps -o pid,ppid,pgid,stat,etime,command -p 81234 -p 81235
  PID  PPID  PGID STAT ELAPSED COMMAND
81234     1 81234 Ss     03:12:41 /usr/bin/python3 -m pytest
81235 81234 81234 S      03:12:40 /usr/bin/python3 -m pytest

这张表说明什么：三个事故的修复都不在模型侧，而在 runner 的收尸、限额与清理顺序。把它们写成回归用例，比在提示词里写「不要运行危险命令」有效得多。

3.8 观测：/proc、waitid、cgroup.events 与 shell 语义

沙箱出问题时，最危险的不是「进程还在跑」，而是「你以为它已经停了」。观测要回答三个问题：进程树现在是什么形状、退出原因到底是什么、资源是在哪一层触顶的。下面按「先看进程，再看退出，再看资源，最后看 shell 封装」的顺序给出可跑命令。

3.8.1 进程树：ps 的五个列

ps -o pid,ppid,pgid,stat,etime,cmd 是 Linux 上的常用组合；macOS 的 ps 不认 cmd，要用 command 或 comm。下面是在本机跑出的真实输出（父子两行，父进程用 start_new_session=True 启动）：

ps -o pid,ppid,pgid,stat,etime,comm -p 92251 -p 92256

  PID  PPID  PGID STAT ELAPSED COMM
92251 92248 92251 Ss     00:00 /Users/juanwang/miniconda3/bin/python3
92256 92251 92251 S      00:00 /Users/juanwang/miniconda3/bin/python3

读法：两行的 PGID 都是 92251，说明子进程与父进程同组；STAT 的 Ss 表示「可中断睡眠 + 会话首领」，S 表示「可中断睡眠」。如果子进程的 PPID 变成 1，它已经是孤儿；如果 STAT 是 Z，它是僵尸；如果 PGID 与父进程不同，它已经 setsid 或 setpgid。这三个信号比「进程还在不在」更有信息量。

3.8.2 退出与资源：/proc、waitid、cgroup.events

Linux 上，/proc/<pid>/status 给出进程的凭证与安全状态，重点看这些字段：

这张表说明什么：/proc/<pid>/status 是「进程现在有什么权」的直接证据，比读配置文件可靠。容器里如果 CapEff 不是 0，agent 可能通过 mount、ptrace、chroot 绕过文件边界；第 4 章会讲怎么把五集合清空并验证。

Linux 上再补四条命令：cat /proc 看权，findmnt 看挂载，ss 看连接，strace -f 看子进程实际发起的系统调用。最后一条需要 ptrace 权限，生产内核常禁用。

# Linux 6.8 / Ubuntu 24.04；本机 macOS 没有 /proc、ss、strace
PID=12345  # 换成目标子进程的 pid
cat "/proc/$PID/status" | grep -E '^(Name|State|PPid|Uid|CapEff|NoNewPrivs|Seccomp):'
findmnt -T /workspace -o TARGET,SOURCE,FSTYPE,OPTIONS
ss -ltnp
strace -f -e trace=process,openat2,connect -p "$PID"

waitid 在 3.2.3 已经给出 si_status 的真实输出：CLD_EXITED 时是 42，CLD_KILLED 时是 15，不需要再解码。排障时优先用它而不是 /proc/<pid>/stat 的 exit_code 字段：后者是 wait 编码，字段位置还可能随内核/文档变化。

cgroup v2 的 cgroup.events 与 memory.events 回答「这个 cgroup 现在有没有活进程、有没有被冻结、有没有 OOM 过」：

populated 1
frozen 0

populated 1 表示还有活进程；frozen 0 表示没被冻结。如果超时后 populated 仍是 1，说明收尸没完成；如果 frozen 1，进程被停住了但还没死，仍占内存与 PID。配合 memory.events 的 oom_kill、pids.events 的 max，可以区分「被 OOM 杀」「被进程数限制挡住」「被墙钟杀」三种终止原因。

3.8.3 shell 语义：pipefail、PIPESTATUS、ulimit、jobs

runner 经常用 shell 包一层命令，于是 shell 的语义变成了沙箱语义的一部分。四个最常写错的点，下面都给出本机实际输出。

pipefail 取最右非零，PIPESTATUS 保留每一段。 默认情况下，管道状态是最后一段的状态；set -o pipefail 后，状态是「最右边那个非零」；PIPESTATUS 数组保留每一段。

bash -c '
false | true | false
printf "no pipefail: status=%s parts=%s\n" "$?" "${PIPESTATUS[*]}"
set -o pipefail
(exit 3) | (exit 5) | true
printf "pipefail:    status=%s parts=%s\n" "$?" "${PIPESTATUS[*]}"
'

no pipefail: status=1 parts=1 0 1
pipefail:    status=5 parts=3 5 0

第二行说明：pipefail 取的是最右边的非零 5，不是最左边的 3；每段状态仍在 PIPESTATUS 里（3 5 0）。要判断「哪一段失败」，必须读 PIPESTATUS；只看 $? 会把「第三段失败」和「第一段失败」混为一谈。注意 PIPESTATUS 会被下一条命令覆盖，必须在管道之后立刻保存。

ulimit 的软/硬限。 3.5.1 已经给出完整输出：-S 只改软限，-H 只改硬限；bash 不带选项时同时改两者，所以「默认只改软限」是误记；软限不得超过硬限；非特权不能抬高硬限。写脚本时显式写 ulimit -S 或 ulimit -H，不要依赖默认值。

jobs 是当前 shell 的作业表。 父 shell 能看到后台作业，显式子 shell 看不到：

bash -c '
sleep 30 &
echo "parent jobs -p:"
jobs -p
echo "explicit subshell jobs -p:"
( jobs -p )
kill %1 2>/dev/null
wait 2>/dev/null
'

parent jobs -p:
92008
explicit subshell jobs -p:

jobs -p 在父 shell 输出 92008，在 ( ... ) 子 shell 输出为空。原因不是「子 shell 没继承变量」，而是作业表属于 shell 进程本身，子 shell 是另一个进程。bash 对 $(jobs -p) 这类单内建命令替换有优化，可能仍能读到父表；不要把命令替换当作隔离检查，要确定作业表边界就用显式子 shell 或直接读 ps。

这张表说明什么：观测命令要对应「哪一层」；ps 看进程关系，waitid 看退出语义，cgroup 文件看资源事件，PIPESTATUS 看管道语义。四类混在一起看，容易把「进程还在」误判成「资源没超」，或把「管道最后一段成功」误判成「整个命令成功」。

3.9 实验：Python 沙箱 runner

experiments/ch03/sandbox_runner.py 把前面四层里「应用层能自己做」的部分压成一个可运行的最小实现。它不替代容器，也不假装自己是安全边界；它要证明的是：超时、限额、收尸、输出截断、路径拒绝这五件事，用标准库就能做对，而且可以被测试固定下来。

这张表说明什么：五件事分别落在不同层，但共享一个结果结构；agent 拿到的是 exit_code/signal/timed_out/output_limited/error，而不是一段需要再解析的 stderr。结果结构比实现更重要，因为它让上层能稳定决策。

核心循环只有十几行：

proc = subprocess.Popen(
    [sys.executable, "-I", str(script)],
    cwd=root, start_new_session=True, close_fds=True,
    stdout=out_fh, stderr=err_fh, stdin=subprocess.DEVNULL,
    preexec_fn=lambda: apply_limits(cpu_s, fsize, nofile),
)
deadline = time.monotonic() + timeout_s
while proc.poll() is None:
    if time.monotonic() >= deadline:
        timed_out = True
        os.killpg(proc.pid, signal.SIGKILL)
        break
    if out_size() + err_size() > max_output_bytes * 2:
        output_limited = True
        os.killpg(proc.pid, signal.SIGKILL)
        break
    time.sleep(0.01)
returncode = proc.wait(timeout=2.0)

三个细节：-I 让子进程忽略 PYTHON* 环境与用户 site，减少「环境变量注入」；close_fds=True 防止父进程 fd 泄漏；proc.wait(timeout=2.0) 在 killpg 后再等一次，确认收尸完成，而不是发完信号就走。

实际运行（输出用 jq 只保留关键字段）：

python3 experiments/ch03/sandbox_runner.py --code 'print(6*7)' \
  | jq -c '{ok,exit_code,signal,timed_out,stdout}'

{"ok":true,"exit_code":0,"signal":null,"timed_out":false,"stdout":"42\n"}

python3 experiments/ch03/sandbox_runner.py --code 'import sys; sys.exit(42)' \
  | jq -c '{ok,exit_code,signal,timed_out}'
python3 experiments/ch03/sandbox_runner.py --code 'import time; time.sleep(10)' \
  --timeout 0.5 | jq -c '{ok,exit_code,signal,timed_out,duration_ms}'
python3 experiments/ch03/sandbox_runner.py --code 'print("x"*200000)' \
  --max-output 4096 | jq -c '{ok,output_limited,stdout_truncated,bytes}'

{"ok":false,"exit_code":42,"signal":null,"timed_out":false}
{"ok":false,"exit_code":null,"signal":9,"timed_out":true,"duration_ms":503}
{"ok":false,"output_limited":true,"stdout_truncated":true,"bytes":{"stdout":200001,"stderr":0}}

路径逃逸的拒绝发生在启动子进程之前：

python3 experiments/ch03/sandbox_runner.py \
  --file /tmp/ch03-outside/escape.py --workspace /tmp/ch03-ws \
  | jq -c '{ok,exit_code,error,detail}'

{"ok":false,"exit_code":null,"error":"EPATH","detail":"/tmp/ch03-outside/escape.py -> /private/tmp/ch03-outside/escape.py is outside /private/tmp/ch03-ws"}

测试覆盖七条不变量：正常退出、非零退出、超时杀进程组、输出超限、路径逃逸（含符号链接）、NOFILE 限额、wait status 解码。真实输出：

python3 -m unittest discover -s experiments/ch03 -v

test_decode_wait_status ... ok
test_nofile_limit_is_applied ... ok
test_nonzero_exit_is_not_success ... ok
test_normal_exit ... ok
test_output_limit_truncates ... ok
test_path_escape_is_rejected ... ok
test_timeout_kills_process_group ... ok

----------------------------------------------------------------------
Ran 7 tests in 2.571s

OK

experiments/ch03/README.md 给出完整命令。runner 本身是跨平台的（macOS/Linux），但它只覆盖应用层边界；cgroup、netns、OCI 都是 Linux-only，正文中的命令标注为「Linux 6.8 / Ubuntu 24.04」，没有在本机 macOS 上运行过。RLIMIT_AS 在 macOS 上跳过，并在结果的 rlimits.as_enforced 里标 false。

母本对应