第15章 · Typed Tools、MCP 与可恢复 Agent

前置要求：掌握第14章 · 工业级 RAG 应用实战的检索服务与第9章 · TinyGPT 预训练与恢复的模型生成接口。

到第14章为止，模型只会"说话"。本章让它"做事"——查数据库、写文件、调 API。但一旦模型能动手，问题就变了：它的输出是不确定的，而副作用是真实的。所以本章的主角不是模型，而是套在模型外面的那层工程壳（harness）：模型的任何动作先过 schema 校验，再过风险策略，高风险动作必须拿到人类批准，每次执行前先写 checkpoint，重试靠幂等键保证副作用不重复。

这套东西对前端工程师应该非常眼熟：它就是一个 Redux 状态机加一层 HTTP 幂等中间件。学完本章，你会亲手实现一个最小 Agent harness，并用故障注入证明它"崩溃可恢复、重放不重复"。

FixtureModel 只证明 harness 合同，不证明 live planner 质量：本章实验用离线 fixture 模型驱动，验证的是状态机和副作用纪律，不宣称真实模型的规划能力。

本章目标

学完后你能做到：

把模型输出约束为可校验的 structured tool call，而不是直接执行任意文本。
实现 read-only、幂等可逆写入、高风险 HITL 和始终拒绝四类动作的分级策略。
用 checkpoint、idempotency key、超时/重试和 MCP protocol boundary 证明系统可恢复且无重复副作用。

阶段一：把 Agent 看成一个状态机

Agent 的每一步都是同一个循环：模型提出下一步动作（一段 structured tool call），系统把关后才执行。

直觉：Reducer，不是黑盒

Agent 的每一步都可以写成显式状态转移：

s_{t + 1} = δ (s_{t}, e_{t}, validate (a_{t}))

逐符号读：

$s_{t}$ ：第 $t$ 步的状态（AgentState：事件 id、步数、消息历史、待批准项、checkpoint 哈希）。
$e_{t}$ ：这一步到达的事件（用户输入、工具返回、超时信号……）。
$a_{t}$ ：模型提出的候选动作（一次工具调用）。
$validate (a_{t})$ ：先校验——schema 不合格的动作根本进不了转移函数。
$δ$ ：转移函数，给定旧状态、事件和合法动作，算出唯一的新状态。

前端类比：这就是 Redux reducer——(state, action) => newState 是纯函数，相同输入永远产生相同输出。第3章的 gradient_descent_step(param, grad, lr) = param - lr·grad 也是同一模式：每一步在旧值基础上做"增量更新 + 边界检查"——梯度裁剪防止步长过大，policy/HITL 防止副作用越界。

为什么 typed tool call 能降低编造风险？第3章的 cross entropy 衡量"期望 vs 实际"的差距；模型自由生成时输出空间是任意文本，schema 约束把它压缩到"合法 JSON"的已知子空间里——不是限制能力，而是把不确定性关进笼子。

Agent 工具调用全生命周期时序图

一个工业级的 Agent 架构，从用户发起请求到最终返回，中间有一套严密的防御性拦截网：

工具执行失败时的自愈闭环（Self-Correction）

当工具执行报错（如参数格式错、数据库无此记录、网络超时）时，千万不要直接向用户抛出未捕获异常。正确的工业实践是：将错误内容格式化为标准的 role: "tool" 消息喂回给大模型：

json

{
  "role": "tool",
  "tool_call_id": "call_987",
  "name": "query_database",
  "content": "{\"error\": \"NotFoundError\", \"message\": \"User 'alice' not found in tenant 42. Available tenants: [1, 2, 10].\"}"
}

大模型看到这个标准报错后，具备极强的根据错误上下文自动纠偏能力（例如自动换用正确的 tenant id 再次调用，或者委婉告诉用户该租户不存在）。这种把运行时错误变成下一次思考的提示词的心智，是构建韧性 Agent 的核心基石。

Agent 三大规划范式：ReAct vs Plan-and-Solve vs Reflexion（伯克利 CS294 核心准则）

在大模型智能体的系统架构中，模型如何规划并串联工具调用，存在三种主流演进范式：

范式名称	核心运行循环	优势机制	局限性与风险	典型适用业务场景
ReAct (Reasoning + Acting, Yao et al. 2022)	逐步交替推进：`Thought`（思考现状） $\to$ `Action`（调用工具） $\to$ `Observation`（观察反馈） $\to$ 下一轮思考	动态适应性极高：能够根据工具执行返回的真实观察即时调整策略，应对未知环境	长程规划易迷失：容易陷入局部死循环（如反复尝试同一失败策略），Token 消耗随步数线性膨胀	网页信息检索、未知环境排障、代码调试（探索型任务）
Plan-and-Solve (Wang et al. 2023)	先规划后执行：先生成完整任务分解图（DAG / Step 1..N），再交由 Worker 逐项求解	全局结构感清晰：有效消除无谓的试错循环；步骤之间易于做并发并行调度	静态脆弱性：一旦前置步骤的实际结果与最初预想产生重大偏差，静态计划容易失真	确定性业务审批流、报告生成、多表数据汇总（长流程任务）
Reflexion (Shinn et al. 2023)	试错 → 失败评估 → 自然语言反思 → 清空轨迹带经验重试	口头强化学习（Verbal RL）：无需微调权重，将失败经验提炼为文字存入情节记忆，释放被长日志撑爆的上下文	依赖评估器判定：需要有可验证的环境信号（如测试用例或规则断言）来判定是否失败	代码编写测试生成、多步决策游戏、数学定理证明（有清晰胜负判定）

Reflexion 的工程机制：如何防止 Agent 在连续错误中陷入死循环？

在复杂的 Agent 执行流中，如果缺乏容错与状态重置机制，连续失败的工具调用与冗长报错堆栈会迅速占满上下文窗口，甚至诱导模型陷入重复试错的死循环。

Reflexion（Shinn et al. 2023）给出了轻量化的工程解法：

失败触发诊断（Post-Mortem Reflection）：当工具返回错误或单元测试未通过时，暂停主循环，调度反思提示词：“请审视上述失败的执行轨迹，指出导致失败的根本假设错误，并总结一条简明的避免指南”；
情节记忆沉淀（Episodic Memory）：将生成的反思总结（例如：“上一次错误是因为查询时遗漏了 tenant_id，下次调用前必须先从上下文解析租户”）存入轻量记忆列表；
上下文回滚重置（Rollback & Re-run）：将刚才包含大量报错堆栈的冗长执行日志从活动上下文窗口中弹出清理，仅在下一次全新请求的 Prompt 顶部注入这段精炼的反思经验；
这种方式让模型以最小的 Token 成本获得了“经验提炼”的跨尝试自愈能力。

智能体自反思与情景记忆学习闭环：接收任务、工具调用、失败评估、文字反思、存入记忆并回滚重试

工业界主流生产实践：Plan-then-ReAct 混合架构：在顶层由 Planner 产出粗粒度的里程碑步骤计划（Plan）；而在落实每一个具体的子步骤时，调度 Worker 在该步骤内运行局部的 ReAct 闭环（带重试与自纠错），若连续失败则触发 Reflexion 反思回滚，既保证了全局路线不偏航，又保留了局部的动态适应与长程自愈韧性。

语法约束解码（Constrained Decoding / Grammar-Based Sampling）

尽管在 Prompt 中通过 JSON Schema 严格声明了工具入参，但在高并发生产环境中，基于纯文本生成的结构化输出仍存在千分之几的概率出现未闭合括号、尾随逗号等格式畸变，引发下游 JSON 解析失败。

**语法约束解码（Grammar-Constrained Decoding）**从解码层面系统消除了这一隐患：

原理：将 JSON Schema 或 BNF 文法转化为一个有限状态机（FSM）或下推自动机（Pushdown Automaton）；
动态 Logits 掩码（Logits Masking）：在自回归生成的每一个 Token 步长，解码器先查询当前语法状态机：当前位置允许出现哪些字符？
- 例如：当刚刚输出了 {"name": ，下一个 Token 必须是引号 "；
- 解码器会将词表中所有不符合该语法规则的 Token 的 Logit 分数强行重置为 $- \infty$ ；
数学级绝对可靠：经过 Softmax 之后，非法 Token 的选中概率严格为 0。模型生成的字符在数学和物理上 100% 绝对符合目标 JSON Schema，彻底杜绝语法解析错误！主流推理引擎如 vLLM（Guided Decoding）、llama.cpp（GBNF）、Outlines 均已原生内置该技术。

并行工具调用

部分 provider 允许模型在单次 turn 中发出多个工具调用（parallel_tool_calls）。结果可能乱序返回，每个结果携带一个 tool_call_id 回指对应的调用——执行器必须按 tool_call_id 匹配结果，而不是按数组位置。

本仓库 engine.py 的主循环是顺序的：每次迭代只处理一个 action，执行一个工具，再回到模型。memory.py 的 group_tool_units 已经按 tool_call_id 配对 assistant tool_calls 与后续 tool 消息，为乱序结果处理预留了结构基础；真正的并行执行（多线程 / 异步并发）不在本课范围内。

内容块并集（content block union）

现代 provider API 把一条消息的 content 建模为块并集（block union），而非单一字符串。OpenAI 兼容层使用 text、tool_use、tool_result 三类块；Gemini 原生使用 text part、functionCall part、functionResponse part——语义等价，只是命名不同。部分模型（如 Claude extended thinking）还额外返回 thinking 块（模型生成的推理过程，可能签名、可能被回传给调用方，也可能仅在服务端使用）。

本仓库把消息内容建模为不透明字符串：AgentState.messages 里是 {"role": "user|assistant|tool", "content": str}（schemas.py），工具结果追加为 {"role": "tool", "name": ..., "content": ...}（engine.py 第 123–151 行），没有块并集结构。也就是说，本课 harness 的 content 字段承载的是序列化后的完整工具结果 JSON，不是联合体——它不会把 thinking 块单独暴露给调用方。

为什么 tool_use / tool_result 要按 id 而不是位置匹配：provider 可能乱序返回多个工具的结果，每个结果携带一个 tool_call_id 回指对应的调用块。按数组位置匹配会在乱序时把结果绑到错误的调用；按 id 匹配则无论返回顺序如何都能正确配对。memory.py 的 group_tool_units 正是按这个 id 把 assistant tool_calls 与后续 tool 消息编成原子单元。

从 API/CLI 到屏幕界面：GUI 智能体可执行动作空间（Executable Language Grounding）

在多数后端工程中，工具通常表现为结构化 API 或命令行脚本。然而在桌面与移动操作系统自动化场景中（如 OSWorld、OS-Kairos 等 GUI Agent），智能体必须直接操作图形交互界面。

**GUI 动作空间规范（Grounding Action Space）**将视觉感知与离散控制原子化：

CLICK <point>[[x, y]]</point>：在指定归一化屏幕坐标点触发指针点击，要求多模态模型具备亚像素级的视觉定位能力（Visual Grounding）；
TYPE [text]：在当前聚焦输入框写入字符串；
SCROLL [UP|DOWN|LEFT|RIGHT]：视口平移滚动以探索长页面隐蔽信息；
IMPOSSIBLE：当检测到网络断开、权限弹窗阻拦或当前界面根本不包含目标功能时，显式输出无法完成标记，终止无效盲目试错；
置信度自评机制（Self-Scoring）：在输出动作的同时输出预估把握评分（1–5 分），当评分低于安全阈值时主动中断并申请人类介入（HITL）。

本质统一性：无论执行介质是 HTTP 请求、SQL 语句还是屏幕像素点击，在 Agent 状态机视角下，它们都是具备**前置校验（Schema）、后置观察（Observation）与副作用评级（Privilege Level）**的标准 Typed Action。

交互观察

交互：Agent 主循环状态机

所谓 Agent，本质就是一个「LLM 推理 → 调工具 → 把结果塞回上下文」的 while 循环。

max_steps = 8工具失败率 = 20%

Idle

等待用户输入

step 0 / 8 · retry 0/3

→ think（user msg）

点「单步执行」开始

教学要点（红旗实验）：把失败率拉到 80%，反复点执行 —— Agent 会卡在 Execute 自旋，直到触发 3 次重试上限进 Error。没有 max_steps 和重试上限的 Agent 会烧光你的 token 预算。 这两个数字不是可选项，是生产环境的保险丝。

先点一遍 Idle → Think → SelectTool → Execute → Observe 主循环：调高工具失败率，观察重试分支和 Error 终态何时触发；每一次点击都应对应上面 $s_{t + 1} = δ (s_{t}, e_{t}, validate (a_{t}))$ 里的一条显式 transition，而不是一段不可追踪的文本流。

Shape 契约：数据模型与状态追踪图式先行

在观察任何控制流逻辑之前，先明确 Agent 状态机操作的核心数据结构：

python

@dataclass
class ToolSpec:
    """工具契约：Schema 先于 Execute"""
    name: str                                  # 1. 工具唯一标识符（如 read_file）
    description: str                           # 2. 供 LLM 理解的自然语言用途说明
    parameters: dict[str, Any]                 # 3. JSON Schema 参数约束定义
    risk_level: RiskLevel                      # 4. Progent 特权等级 (Level 0 ~ 2 / Forbidden)
    execute: Callable[[dict[str, Any]], Any]   # 5. 底层执行闭包

@dataclass
class AgentState:
    """Agent 状态快照：类似 Redux store 的纯数据模型"""
    event_id: str                              # 1. 全局唯一事件 ID
    step: int                                  # 2. 当前迭代轮次（防死循环熔断）
    messages: list[dict[str, Any]]             # 3. 序列化消息上下文轨迹
    pending_approval: dict[str, Any] | None    # 4. HITL 挂起审批令牌
    checkpoint_hash: str                       # 5. 持久化快照的 SHA-256 校验和

具象数据帧追踪（Trace Frame）：一个单步工具调用后的真实 AgentState 序列化快照：

json

{
  "event_id": "evt_101",
  "step": 2,
  "messages": [
    {"role": "user", "content": "读取 report.txt 并统计字数"},
    {"role": "assistant", "content": null, "tool_calls": [
      {"id": "call_01", "type": "function", "function": {"name": "read_file", "arguments": "{\"path\":\"report.txt\"}"}}
    ]},
    {"role": "tool", "tool_call_id": "call_01", "name": "read_file", "content": "{\"data\":\"Hello world\"}"}
  ],
  "pending_approval": null,
  "checkpoint_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

对象	shape/结构	约束
`ToolSpec`	`name + input_schema + risk + execute`	schema 先于 execute
`ToolResult`	`tool + status + output + idempotency_key`	`ok/replayed` 可重放；`uncertain` 必须停在 `reconcile_required`，不可自动重试；只有显式 `AgentEngine.reconcile_uncertain(..., outcome="confirmed")` 对账后才能继续，且不再次调用 executor
`AgentState`	`event_id + step + messages + pending_approval + checkpoint_hash`	step/time 有上限
approval	绑定 action/args/session/expiry	一次性、不可跨会话复用

阶段二：四类动作、Progent 权限分级与策略防御系统

在 Agent 系统中，不仅每个工具调用的风险不同，而且模型的意图与输出永远是不可信的输入。

为什么 Prompt 软约束在面对越狱与注入时形同虚设？

许多初学者容易产生一种工程幻觉，试图通过 System Prompt 约束智能体的行为：“你是一个安全的编程助手，请绝对不要删除文件，不要执行 rm -rf，不要访问系统根目录与 .env 凭据”。

这种基于自然语言提示词的软约束在工业界被证实是脆弱的：

概率采样的本质缺陷：LLM 本质上是一个无状态的自回归条件概率生成器，其内部不存在类似操作系统 CPU 特权环（Ring 0 内核态 vs Ring 3 用户态）或访问控制列表（ACL）的物理隔离概念；
直接越狱（Direct Jailbreak）：攻击者可以通过角色扮演、假借“系统灾难演练测试模式”或对抗性对抗样本（Adversarial Suffixes），诱导模型无视顶层 System Prompt 中的警告；
间接提示词注入（Indirect Prompt Injection）：当 Agent 读取未经审查的外部文档、网页或 GitHub Issue 时，攻击者在内容中预埋了伪装指令（例如：“”）。大模型在注意力机制计算中难以从物理上区分“真正合法的系统元指令”与“从外部抓取进来的不可信数据”，从而听从指令发起高危调用。

工程铁律：安全防线绝不能建立在模型的‘自觉性’或 Prompt 软约束之上。系统必须假设“模型随时可能产生非预期或恶意调用”，必须由外层的宿主执行内核（Harness Kernel）提供确定性的拦截与权限控制。

Progent 工业级权限分级系统（UC Berkeley CS294-280 L12）

借鉴现代操作系统能力机制（Linux Capabilities）与云端 IAM 的“最小特权原则”（Principle of Least Privilege），伯克利 Dawn Song 教授在 CS294-280 课程中系统提出了 Progent（Dual-granularity Privilege Management）双粒度特权管理框架：

1. 粗粒度特权等级（Privilege Levels）

级别	定义与典型示例	判定依据	内核执行策略
Level 0 (Safe Read-Only)	查阅文档、查询只读配置、计算哈希、计算器	动作完全无持久外部副作用，且不触碰私密数据	前置 Schema 校验通过后直接放行
Level 1 (Sandboxed / Reversible Write)	在指定临时目录写代码、更新缓存记录、创建本地测试文件	动作具有写入副作用，但在工作区沙箱内可控、可撤销或具备补偿事务	强制绑定 `idempotency_key` 并在隔离工作区中执行
Level 2 (High-Privilege / Destructive / Outbound)	删除生产文件、系统格式化、修改配置、外网网络请求（curl/webhook）、导出凭据	动作具备物理破坏性、不可逆或具有数据外泄（Exfiltration）风险	严禁模型自主下发！必须挂起，唤醒 HITL 人机协同审批
Forbidden (Always Denied)	格式化磁盘（`mkfs`）、倾倒系统私钥、提权后门（`chmod +s`）	违背系统底线的危险指令	内核直接拦截拒绝，不留任何审批通道

2. 细粒度策略 DSL 与规则集（Fine-grained Policy Rules）

在粗粒度分级之上，Progent 通过细粒度策略规则对入参进行确定性深度静态扫描：

工作区沙箱限制（Workspace Sandbox & Canonical Path）：
- 严禁信任模型直接传入的相对路径；
- 参数中的路径必须经由操作系统底层规范化（如 os.path.realpath），解析所有软链接与 ../；
- 强制校验解析后的绝对路径必须严格落在 workspace_root 之下。任何包含路径遍历（Path Traversal）的请求直接以 PermissionError 阻断！
受保护路径黑名单（Protected Paths Blocklist）：
- 即使路径在合法工作区内部，某些元数据与敏感凭据依然属于绝对受保护区；
- 坚决阻断对以下目录和文件的任何写/改/删操作：.git/（版本控制底座）、.env / *.env*（环境变量凭据）、*.pem / id_rsa*（私钥）、package-lock.json（非构建流程篡改）；
破坏性高危命令名单（Destructive Commands Blocklist）：
- 对命令行执行工具（如 bash, sh, powershell），建立正则模式特征库；
- 拦截包含 rm -rf, mkfs, dd if=, chmod 777, chown, kill -9, shutdown, drop database, truncate table 等高危破坏指令；
敏感环境变量与凭据防护（Sensitive Env Screening）：
- 任何涉及读取系统环境或写入日志的操作，严禁向外透传包含 API_KEY, SECRET, TOKEN, PASSWORD, DATABASE_URL 的键与值；
动态审批升权机制（Dynamic Privilege Escalation via HITL）：
- 当合法任务确需触发 Level 2 动作时，系统生成单次有效的签名审批凭据（ApprovalToken）；
- 该凭据通过 HMAC 严格绑定 (session_id, principal, tool, arguments_hash, expires_at)；
- 必须通过安全的带外信道（如独立运维弹窗或安全终端）由物理人类审批，杜绝跨会话或篡改参数的令牌重放。

最小 Python 拦截器实现：`assert_tool_policy`

以下是用纯标准库实现的最小确定性策略拦截器，完整落地上述 Progent 规范：

python

import os
import re
from dataclasses import dataclass
from typing import Any, Mapping

# 高危命令拦截正则模式
DESTRUCTIVE_CMD_PATTERNS = [
    r"\brm\s+-[rfRF]{1,3}\b",
    r"\bmkfs\b",
    r"\bdd\s+if=",
    r"\bchmod\s+777\b",
    r"\bkill\s+-9\b",
    r"\bdrop\s+database\b",
    r"\btruncate\s+table\b",
]

# 受保护敏感文件与目录后缀
PROTECTED_PATH_PATTERNS = [
    r"^\.git(/|\\|$)",
    r"^\.env(\.|$)",
    r"id_rsa",
    r"\.pem$",
    r"\.key$",
]

@dataclass(frozen=True)
class ToolPolicyContext:
    workspace_root: str
    session_id: str
    principal_role: str = "guest"
    approval_token: str | None = None

class PolicyViolationError(PermissionError):
    """抛出确定性策略拦截异常"""
    pass

def assert_tool_policy(
    tool_name: str,
    args: Mapping[str, Any],
    context: ToolPolicyContext,
) -> str:
    """Progent 最小策略拦截器：在执行器之前执行确定性安全断言。

    返回特权裁定: 'allowed_l0' | 'allowed_l1' | 'approval_required'
    """
    # 1. 检查环境变量敏感泄露
    for key, val in args.items():
        key_upper = str(key).upper()
        if any(secret in key_upper for secret in ("API_KEY", "SECRET", "TOKEN", "PASSWORD")):
            raise PolicyViolationError(f"Progent 拦截：禁止向工具入参传递敏感键名 {key}")

    # 2. 检查路径是否越界（工作区沙箱限制）
    if "path" in args or "filepath" in args:
        raw_path = str(args.get("path") or args.get("filepath"))
        workspace = os.path.realpath(context.workspace_root)
        resolved = os.path.realpath(os.path.join(workspace, raw_path))

        # 防止路径遍历攻击 (如 ../../etc/passwd)
        if not (resolved == workspace or resolved.startswith(workspace + os.sep)):
            raise PolicyViolationError(f"Progent 拦截：路径穿越越界尝试 {raw_path}")

        # 检查是否命中敏感保护文件
        rel_path = os.path.relpath(resolved, workspace)
        for pattern in PROTECTED_PATH_PATTERNS:
            if re.search(pattern, rel_path):
                raise PolicyViolationError(f"Progent 拦截：禁止访问受保护路径 {rel_path}")

    # 3. 检查命令工具的高危特征 (Shell 命令黑名单)
    if tool_name in ("bash", "execute_command", "shell_exec"):
        cmd = str(args.get("command", ""))
        for pattern in DESTRUCTIVE_CMD_PATTERNS:
            if re.search(pattern, cmd, re.IGNORECASE):
                raise PolicyViolationError(f"Progent 拦截：命中高危破坏性命令模式 '{pattern}'")

    # 4. 特权级别裁定与审批升权
    if tool_name in ("read_file", "search_docs", "calculate_hash"):
        return "allowed_l0"

    if tool_name in ("write_file", "append_log"):
        if not args.get("idempotency_key"):
            raise PolicyViolationError("Progent 拦截：Level 1 可逆写操作必须携带 idempotency_key")
        return "allowed_l1"

    # Level 2 动作：删除、网络通信、执行系统命令等
    if context.approval_token is None:
        raise PolicyViolationError(
            f"Progent 拦截：调用 Level 2 特权工具 '{tool_name}' 必须持有有效的人类 HITL 审批 Token"
        )
    return "allowed_l2_approved"

强制工具选择：providers 暴露 tool_choice（OpenAI 风格）或 tool_config（Gemini 风格），值可以是 "auto"、"none"、"required"，或强制指定某个函数（如 OpenAI 的 {"type":"function","function":{"name":"X"}}）。编排器在安全关键路径上必须强制工具——模型不得从自身权重生成答案——而普通路径留 "auto" 让模型自行判断。本仓库 tools.py 不暴露 tool_choice 机制，这是 provider 协议层面的概念，不是本课 harness 的能力。

工具注册表与工具上下文

注册表（ToolRegistry，tools.py）是一个名称索引的可用工具清单：register 把 ToolSpec 按 name 存入 self._specs，list_tools 返回所有已注册工具的排序列表。注册表把"系统里有哪些能力"和"这一轮模型选了哪个"分开——模型只能从已注册的集合里选，不能编造不存在的工具名；如果编造了，invoke 会返回 unknown_tool 状态而不进入 executor。

工具上下文（tool context）是执行工具时传入的运行时 scratch space，至少包含调用者身份和会话标识。本仓库通过 ToolRegistry.invoke 的参数传递：principal（Principal，决定 can_access ACL）和 session_id（决定幂等键的作用域）。工作目录、租户 ID、凭据 scope 等运行时上下文不得从模型参数里推断——模型参数是数据，不是环境配置。principal 是当前仓库唯一显式传入的身份字段；working directory 和 tenant 隔离不在本课范围内，生产系统需要独立注入。

关键纪律：schema 校验和 policy 判定都在 executor 之前。校验放在执行之后，等于先开枪再问打没打中——错误参数的工具已经被调用，副作用难以回滚。

阶段三：幂等、Checkpoint 与可恢复

幂等键：重试不等于重做

网络超时后重试是工程常态，但如果第一次请求其实已经成功，重试就会产生重复副作用（重复扣款、重复发信）。幂等键的语义：

e x e c u t e (k, a r g s) = e x e c u t e (k, a r g s) (第一次以外返回同一结果，不重复副作用)

逐符号读： $k$ 是调用方生成的幂等键（idempotency key）， $a r g s$ 是参数。同一 $(k, a r g s)$ 无论来几次，副作用只发生一次，后续调用返回第一次的结果。前端类比：这就是 HTTP 的 Idempotency-Key header，Stripe 用它防止重复扣款。思想上和第3章的 categorical_sample(probs, rng) 确定性采样同构：相同 state + input + seed 永远产生相同结果。

不确定结果不能自动重试：副作用可能已发生但结果未知（超时）时，状态必须停在 reconcile_required，保存 tool_uncertain trace，等待显式对账（outcome="confirmed"）后才继续——且不再调用 executor。

Checkpoint：崩溃后从哪续跑

每次执行副作用之前先写 checkpoint 记录意图；进程崩溃后按意图补偿或续跑。这和第3章的 momentum_update 保存 velocity 是同一个思想：记录"过去的轨迹"，让后续步骤从正确位置继续，而不是从头开始。前端类比：Redux persist——把 store 序列化到 localStorage，页面刷新后从最近快照恢复。

执行隔离：本仓库 engine.py 的 registry.invoke() 在同一进程内调用 spec.execute()，没有子进程或容器隔离。生产系统的隔离粒度从同进程（最薄）到子进程、容器、远程服务逐级递增，资源限制（CPU / 内存 / wall-clock）和故障影响半径也逐级变化。无论哪种隔离，每个工具至少要有 CPU、内存和 wall-clock 限制——没有限界的执行器就是未定义行为。

生产级沙箱执行环境（Sandboxed Execution Environment）

生产环境中的 Agent（尤其是具备代码编写或命令行执行能力的 Code Agent）绝对严禁直接在宿主机裸机上执行命令。一个失控的模型可能因为参数幻觉执行破坏性操作或扫描内网敏感端口。

工业级沙箱环境具备四层硬性纵深防御：

执行载体隔离等级：
- 轻量进程隔离：子进程 + restricted user（仅适合教学或受限只读场景）；
- 容器级隔离（Docker / gVisor / Kata Containers）：利用 Linux cgroups、namespaces 与专用安全内核隔离系统调用；
- 微虚拟机隔离（MicroVM, 如 AWS Firecracker）：毫秒级冷启动的极简独立内核虚机，提供硬件级 CPU 虚拟化隔离，是当前 OpenAI Code Interpreter 与主流云厂商的首选方案；
- WebAssembly 沙箱（Wasmtime / V8 isolate）：在内存和字节码层级提供绝对密封的无副作用纯净环境。
资源与生命周期硬约束：
- 无状态短暂生命周期（Ephemeral Lifecycle）：每个工具调用任务结束后，沙箱实例立刻销毁，严禁跨会话残留磁盘文件或环境污染；
- 硬配额限制：强制配置 CPU 核心数限制、内存硬上限（如 512MB OOM Killer）以及 Wall-clock 执行超时中断；
- 网络出站白名单（Egress Allowlist）：默认彻底阻断一切公网与内网连接，仅允许通过白名单代理访问受信任的业务域名，杜绝模型受提示注入（Prompt Injection）驱使外发敏感数据。

Naptime 范式：假说驱动的自调试执行与环境反馈闭环（DeepMind Project Zero）

在 UC Berkeley CS294-280 课程中，Google DeepMind 杰出科学家 Charles Sutton 剖析了 AI Agent 在真实世界挖掘并修复 0-day 漏洞的革命性突破——Naptime 架构（后演化为 Project Zero 著名的 "Big Sleep" 漏洞自主挖掘系统）。

1. 单步工具调用 vs. 假说驱动自调试的本质差异

传统教学中的 ReAct 或单步调用 Agent 往往假设“模型一次就能写对代码”；一旦执行器报错，模型便常常陷入抓瞎式的盲目重试，或者在长长报错堆栈的干扰下发生注意力漂移。

Naptime 构建了面向复杂工程与安全漏洞挖掘的假说驱动自调试（Hypothesis-Driven Self-Debugging）闭环：

其核心分为五步循环：

观察真实环境（Observe Environment & State）：收集编译器、测试套件、调试器（GDB/LLDB）与动态插桩工具（AddressSanitizer ASan、Valgrind）的真实执行输出；
提出根因假说（Formulate Hypothesis）：让模型分析错误现象并形式化提出根本原因假说（例如：“崩溃是由于第 42 行输入长度未做边界校验，导致堆缓冲区溢出”）；
构造最小复现（Construct Minimal POC / Repro）：编写最小可复现用例（POC）或针对性单元测试，在沙箱中精准重现该失败；
实施受控修补（Apply Patch）：在受限工作区实施代码变更；
闭环反思验证（Validate & Assess）：重新运行测试套件与 Sanitizer，观察是否消除异常且无引入存量回归（Zero Regression）。

2. Execution Feedback 架构模型与防御机制

为了支撑自调试循环的高效运转，执行引擎必须提供两层关键机制：

30s 熔断保护与 Wall-clock 硬超时（Hard Wall-clock Timeout）：
- 模型在自主调试代码时，极易因逻辑缺陷写出无限死循环（如 while (p != NULL) 未移动指针、死锁、无限递归）；
- 如果缺乏物理级外部看门狗（Watchdog），Agent 会永久阻塞卡死整个调度系统；
- 调度内核必须对单次执行设置严格的 Wall-clock 硬超时（工业级实践通常为 30s 熔断）。一旦时间耗尽，宿主操作系统直接向子进程发送 SIGKILL 强行终止，并向模型返回标准的超时错误结构：
  json
```
{
  "status": "timeout_exceeded",
  "timeout_seconds": 30.0,
  "message": "Execution terminated after 30s wall-clock limit. Check for infinite loops or blocking I/O."
}
```
异常结构化解析（Structured Exception Parsing）：
- 严禁将 500 行充满操作系统内部符号、动态库加载路径的裸 Traceback 直接倒给模型；这样做既浪费昂贵的 Token，又会稀释模型的注意力焦点；
- 执行器应当内置结构化提取逻辑，只打包核心诊断要素：
  - error_type：错误类型（如 IndexError, MemoryError, SIGSEGV）；
  - fault_location：触发崩溃的文件名与代码行（file:line）；
  - exception_message：异常简短原因；
  - truncated_stderr：截取错误发生点前后 10 行上下文，中间长文本进行可见截断；
- 把这些要素打包成标准结构化反馈，才能使模型高效进入下一次“假说检验”，而非陷入无序试错。

工具输出截断

一个工具可以返回比上下文窗口还多的字节；如果原样全部塞回 prompt，下一次请求会超出模型限制或被 provider 拒绝。memory.py 的 trim_to_token_budget 用滑动窗口截断消息历史，但它按 group_tool_units 定义的原子单元切割——一个 assistant tool_calls 和它对应的所有 tool 结果必须同时保留或同时丢弃，不能只截一半，否则 provider 会拒绝下一轮请求（因为 tool 消息找不到对应的 tool_calls id）。

截断必须是可见的：trace 里要记录哪些消息被丢弃（trim_to_token_budget 本身不写 trace，这是留给调用方的扩展点）；如果模型在一个被截断的工具结果上静默推理，调试时将无法区分"模型看到了完整结果"和"模型只看到了前 N 个 token"。本仓库的 placeholder_summarizer 在摘要前打 [占位摘要: 确定性截断拼接, 未经模型总结] 标记——这是同一个思想的另一面：被压缩的内容必须有痕迹。

每一步只推进一个状态；高风险动作先批准，故障重试复用同一个 idempotency key，不把重复副作用当成功。

before_toolcheckpoint saved · idempotency=write-001

before_toolcheckpoint saved · idempotency=write-001

这是离线状态机演示；真实合同由 python/agent_core、checkpoint 和安全测试证明，不连接任何工具或账号。

协作式取消：本仓库使用硬 max_seconds wall-clock 超时（engine.py 的 max_seconds 参数（默认 10.0 秒））；超时后进程直接终止工具。生产系统在此基础上加一个协作式 cancel token：编排器向工具传递可取消句柄，长时间运行的工具可以主动检查并提前退出，而不是被强制杀死。

停止原因分类（stop-reason taxonomy）

Provider 在每次 completion 的 finish_reason 字段报告终止条件，agent loop 必须对每种条件做不同处理：

终止条件	含义	agent loop 必须怎么做
`end_turn`	模型正常结束文本回复	正常流程，把文本追加进状态
`tool_use`	模型发起了工具调用	进入执行器，不得把工具调用当作文本回给用户
`max_tokens`	输出达到上限，可能被截断	工具参数的 JSON 可能不完整；`json.loads` 会抛异常，loop 应拒绝并让模型重试，不能把截断的 JSON 传给 executor
`stop_sequence`	模型命中了停止序列	同 `end_turn`，正常处理文本
`refusal`	模型明确拒绝执行	没有工具会运行；loop 应终止并把拒绝文本回给用户，不要重试
`pause_turn`	服务端长时间工具执行，模型暂停等待	loop 不应终止；应等工具完成后让模型继续推理

本仓库 engine.py 不检查 finish_reason。它的循环终止条件是："tool" in action（执行工具）、max_steps、timeout、模型返回错误、或模型返回纯文本（第 110–178 行）。finish_reason 是 provider 协议层面的概念，本课 harness 把它留给第16章的 transport 层处理；在第16章的 ChatResult 里可以读到它，但本仓库的状态机没有把它作为显式状态。

重试 × 幂等键的交互：如果一个 429 到达时工具已经提交了副作用，重试时必须用相同的幂等键重放已记录的结果，而不是再次执行。这就是幂等键必须在首次尝试之前就绑定的原因——事后补绑无法保证副作用不重复。engine.py 的 _persisted_result 方法通过扫描历史消息中同 key 的结果实现重放。

阶段四：MCP 是协议边界，不是授权边界

MCP（Model Context Protocol）定义了 Agent 与外部工具之间的通信协议（tools/list、tools/call）。本章的 mcp_adapter.py 只做协议适配：把 MCP 请求翻译给同一个 registry/policy 处理。

Model Context Protocol (MCP) 架构与工具调用状态机：宿主 Host、客户端 Client 与服务 Server 的 JSON-RPC 2.0 交互契约

TIP

初学者心智模型：MCP 为什么是大模型世界的“Type-C 协议”？

在 MCP 规范出现前，如果开发了一个本地 SQLite 查询工具，为了让 Claude Desktop、VS Code、Cursor 和自研 Agent 能调用它，必须为每个平台写一套专有的集成接口（面临 $N$ 个模型客户端 $\times M$ 个外部工具的 $N \times M$ 重复开发灾难）。

MCP 规范统一了通信契约：

Client 与 Server 彻底解耦：工具开发者只需写一个轻量 MCP Server，通过标准进程管道（stdio）或 HTTP SSE 暴露 tools/list（带 JSON Schema 的工具说明书）和 tools/call（执行入口）；
生态即插即用：任何支持 MCP 的宿主应用直接连接即可自动发现并调用工具；
不可混淆的边界意识：MCP 仅仅是传输与协商协议（“怎么传消息”），绝不能当成安全授权层。敏感文件过滤、写操作拦截与人机回环审批（Policy 引擎）必须由宿主应用牢牢掌控！

范围说明：MCP 规范还定义了 resources/、prompts/、sampling/ 和 roots/ 四类能力（2025-03 规范版本）。本仓库 adapter 只实现了 tools/list 和 tools/call，其余四类未覆盖——调用方不能假设通过本 adapter 可以访问这些能力。

最容易犯的错是把 MCP 当成授权层——它不是。MCP 只是"怎么说"，policy 才是"能不能做"。如果 MCP adapter 拿到裸 executor 的旁路，schema 校验和风险策略就全部被架空。前端类比：MCP ≈ OpenAPI spec——契约层，schema 先于实现；没有 schema 的调用是 undefined behavior。

可观测性：本仓库的 state.trace 是一个扁平的 {event, step, event_id} 列表；event_id 是对应 step 事件的稳定哈希，可视为 span id。生产系统用 trace_id（全链路唯一） + parent_span_id 组装父子调用链，通过 OTLP 导出到 tracing 后端。本课不引入 tracing 依赖，但 trace 的 event_id 设计保持了与 span 模型的兼容性。

阶段五：与 LangChain / LangGraph 的概念对照

本章先读懂自己写的最小 harness，再做框架对照。官方文档把 LangChain agents 放在较高层的模型/工具/agent loop 入口，把 LangGraph 放在可显式编排有状态工作流的较低层；两者的 API 和版本会变化，以阅读时的官方文档为准。

关注点	本课手写合同	LangChain 对照	LangGraph 对照	必须保留的判断
structured tool	`ToolSpec`、输入 schema、风险级别	模型/工具集成与 agent 入口	把 tool call 作为节点或边上的事件	框架的 tool decorator 不能替代本课的 schema/policy 测试
loop / routing	`engine.py` 的显式状态转移	高层 agent loop，适合先验证工具调用体验	graph state、节点、条件边，适合显式多步路由	先画 `s_t → validate → policy → execute → s_{t+1}`，再映射抽象
state / persistence	`AgentState`、checkpoint hash、恢复入口	由应用层决定状态和批准绑定	图状态与 checkpointer/恢复机制可作对照	持久化不自动等于幂等；仍要证明重复事件只有一次副作用
HITL / policy	`policy.py` 在 executor 前拒绝/暂停	需要显式 middleware/tool boundary	需要显式 interrupt/approval 节点和恢复路径	任何框架都不能绕过 schema、session、args、expiry 和人工批准
MCP	`mcp_adapter.py` 只做协议适配并复用 registry	仅把可能的集成视作 transport 层	仅把可能的集成视作 graph 节点边界	MCP 是协议边界，不是授权边界；以规范为准

"对照"是概念和 trace 对拍，不是把框架依赖加入课程基线，也不是框架质量背书。课程提供两条明确分开的执行线：

local_state_graph：仓库内 dependency-free 的四节点状态图，在每台机器上真实测量抽象的节点/边/步骤成本。当前对照已测量四列语义等价（另记录 4 个节点、6 条边、1 条条件边和每场景图步骤）；这只是结构化抽象成本，不是 wall-clock 性能或框架质量结论。默认基线快照见 evidence/13-framework-comparison-local-v2.json；未安装第三方依赖时的历史读回保留在 evidence/13-framework-availability-v1.json。
langgraph：只在隔离环境中显式安装并固定版本后运行的第三方适配。历史对照在隔离 Python 3.11.14 环境固定 langgraph==0.6.11 完成，四场景 trace 对拍四列全部 equal，证据见 evidence/13-framework-comparison-langgraph-v1.json 和 evidence/13-framework-availability-v2.json。

版本提醒：0.6.11 只是那份历史对照快照的冻结版本；第18章动手 lab 的当前基线是 requirements-agent.txt 里的 langgraph>=1.2,<2（实测 1.2.10）。不要把 0.6.11 装进第18章，也不要用第18章的 1.2.x 去复现 0.6.11 对照 JSON。该可选包不进入课程默认依赖，且只证明确定性 harness contract，不证明 provider 质量、性能或 learner mastery。不能因框架自动重试、内置 memory 或默认 agent 成功一次，就跳过本课的批准、重放和故障门。

bash

PYTHONPATH=python python scripts/run_framework_comparison.py \
  --framework local_state_graph \
  --output evidence/13-framework-comparison-local-v2.json

阶段六：动手实验

把 Agent 系统的四个工程底线钉死：所有工具调用必须先通过 schema 校验再执行；高风险工具必须得到带参数与会话绑定的批准 token 才可产生副作用；同一轨迹重放结果一致；崩溃后可从最近的 checkpoint 续跑。

环境准备

bash

cd <仓库根>
export PYTHONPATH="$PWD/python"

步骤

先在不接入真实模型的前提下画出并实现这一条不可跳过的状态转移：planner output → schema validate → policy/HITL → pre-execute checkpoint → executor → trace/terminal state。每个分支写明谁能改变状态、是否允许副作用、恢复从哪个 checkpoint 开始；MCP adapter 只能把 tools/list / tools/call 送到同一 registry，不能取得 executor 的旁路。随后才把一个冻结的 planner route 映射进去；没有真实 route 时保持 blocked，不要用 FixtureModel 成功伪装 planner 能力。
为四类风险各写一个最小 fixture；禁止通过删除高风险工具来让测试通过。
实现参数校验、风险策略、执行前 checkpoint、idempotency replay 和恢复入口。
用 MCP client/server 只做 tools/list / tools/call 协议适配，并复用同一个 registry/policy。

运行测试：

bash

PYTHONPATH=python python -m pytest \
  python/tests/test_tool_policy.py \
  python/tests/test_mcp_adapter.py \
  python/tests/test_agent_recovery.py -q

（选做框架对照）选一个只读工具和一个高风险 mock 工具：先运行本课手写 harness，再运行仓库内 local_state_graph，最后在隔离环境固定 LangGraph 版本后映射同一输入/输出。比较四列：schema 失败时的副作用计数、批准前状态、相同 idempotency key 的重放结果、中断后的 checkpoint 状态；脚本会把每列的 handwritten、framework 和 equal 并排保存，并额外记录节点/边/图步骤。LangGraph 不可用时只记录 not-measured，不能把 local_state_graph 冒充成 LangGraph 实测。框架可安装时，必须记录确切版本、安装范围、警告/失败和同一 fixture 的对拍结果。

预期输出与判定信号

text

判定信号（本环境实测为 12 passed，以你机器上 pytest 汇总为准，不要对「3 passed」字面值）：
  schema 校验通过的工具才能进入执行阶段
  高风险工具未带有效批准 token 不产生副作用
  同一轨迹重放结果与首次执行完全一致
  注入故障后从最近 checkpoint 恢复，状态可重建

概念图

图：Agent Harness 规划-执行-安全循环 — 用户目标经 Planner 分解为子任务，每个工具调用必须通过 Schema 前置校验和高风险 HITL 审批才能执行。核心是"plan → schema → tool → checkpoint → execute → observe → plan"的循环；崩溃时从最近 checkpoint 恢复。Policy 引擎是不可绕过的系统边界，MCP adapter 负责 typed tool 的注册和合同校验。下游第21章用 replay 机制回放 Agent 轨迹做评估，第22章把 checkpoint → eval → report 串成 artifact chain。

当前 python/agent_core/ 已有 schema、policy、checkpoint、engine、MCP adapter 和离线 FixtureModel。reconcile_uncertain 需要显式、可审计的 confirmed 决策，不能由模型自动写入。

阶段五：通用自主智能体（General Agent）演进——Manus 式 CodeAct 沙盒与长程上下文工程

在真实工业落地中，从早期单轮问答、ReAct 工具调用演进到今天类似 Manus、Cognition Devin 等自主数字员工（General Agent），智能体架构正在发生一场根本性的范式转移：从“受限的 JSON 工具参数组装”彻底转向“在隔离沙盒内运行任意代码的 CodeAct 闭环”。

1. 为什么顶级 Agent 弃用 JSON Tool Calling，转向 CodeAct？

在早期的 Function Calling 中，每个工具必须被描述为一个刚性的 JSON Schema。当任务需要执行复杂逻辑时，JSON 模式暴露出致命缺陷：

控制流断裂与多轮往返开销：如果需要对 100 个文件执行过滤并提取前 3 个文件中的关键字段，JSON Tool Call 需要模型发起数十次网络交互往返（Round-trip）；而 CodeAct 仅需模型编写一段包含 for 循环与 if 判断的 Python 脚本，在沙盒中一次性执行完毕；
中间海量数据直接污染上下文：工具调用的中间临时数据（如一个 50MB 的未处理 CSV 数据表）如果走 JSON 返回值，必须全量序列化并喂回模型的 Prompt 中，瞬间挤爆上下文窗口；而在 CodeAct 架构中，中间数据作为变量保留在沙盒内存或临时磁盘上，模型只需提取聚合摘要或打印关键前十行；
动态探索与现有工具组合性：现实世界的需求不可穷举，任何预先定义的静态 API 都会遇到能力盲区；但 Python 标准库与生态工具（Shell、Pandas、Playwright、AST）赋予了 Agent 像真实软件工程师一样的通用可塑性。

2. 视觉推演：Manus 级 CodeAct 沙盒执行与长程上下文修剪流

在观察下方架构流程图前，请先思考一个长程任务的核心瓶颈：如果一个复杂任务持续执行了 50 步以上，每步都产生几百行输出，模型的上下文长度和注意力漂移该如何解决？

图：Manus 级 CodeAct 沙盒执行与长程上下文自愈循环 — 核心工作流由七个严密阶段构成：

① 目标输入：接收多步、跨软件的开放性目标；
② 代码生成：Planner 不产生静态 JSON，而是生成具有控制逻辑的可执行 Python 脚本；
③ 沙盒执行：代码在进程或容器沙盒内运行，严格捕获标准输出、错误与变量字典（白盒见 python/agent_core/codeact_sandbox_runner.py 的 CodeActSandbox）；
④ 自愈机制：执行报错（如语法错误、缺少第三方库、API 变更）不直接中止任务，而是将错误 Traceback 转化为环境反馈，指导 Planner 快速修复；
⑤ 长程上下文修剪（Context Pruning）：超出近 $N$ 步的历史步骤被自动折叠为两行紧凑摘要，原始冗长输出从 Prompt 中剪除，防止注意力被历史垃圾冲垮；
⑥ 紧凑状态追踪：保留核心文件变动、最终关键输出和全局规划树；
⑦ 交付物闭环：在本地磁盘真正生成可复查的代码、文档或数据产物。

3. 长程任务（Long-Horizon）上下文修剪算法

在 python/agent_core/codeact_sandbox_runner.py 中，我们给出了生产级上下文修剪器 LongHorizonContextManager 的核心不变量：

近期步完整保留：最近执行的 $k$ 个活动步骤（Active Steps，如 $k = 3$ ）保留完整代码与截断后的实际输出，确保模型拥有最近行动的高清反馈；
远期步结构化折叠：超过窗口的历史步骤自动转为 Archived 状态，Prompt 中只保留：
markdown
```
### [Archived Step 1]
```python
df = pd.read_csv('data.csv')
summary = df.describe()
```
Outcome: SUCCESS. Preview: count mean std ... (Raw output folded to preserve context budget)
这样，即使执行 100 步，上下文消耗仍能被稳定约束在极低的固定预算内。

故障注入与预期信号

注入	预期失败信号	修复后证据
CodeAct 沙盒执行崩溃（如零除/语法错）	任务直接中断，未捕获报错	沙盒拦截异常生成 exit_code=1，自愈循环将 traceback 包装注入下一轮 Prompt，自愈测试通过
长程任务超过 10 步未修剪上下文	上下文长度线性爆炸，超出窗口引发 API 截断	启动 ContextManager 滚动折叠，远期步骤 raw stdout 自动剥离，Prompt token 稳定受控
副作用已发生后超时	不确定结果被自动重试，造成重复写入	状态停在 `reconcile_required`，保存 `tool_uncertain` trace；同一 key 只能返回不确定结果；显式确认后写入 `tool_reconciled`，继续文本步骤但不再执行副作用
批准前执行高风险写入	产生未批准事件	`approval_required` 且无副作用
MCP 传入裸 executor	绕过 registry/policy	protocol response 与本地 policy 一致
schema 校验放在执行之后	错误参数的工具已被调用、副作用难以回滚	校验前置，失败直接拒绝并提示模型重写参数
批准 token 不绑定参数与时限	旧 token 可被重放触发高风险工具	token 哈希绑定参数、会话 id 与有效期，由后端校验
副作用先于 checkpoint	进程崩溃后重放产生重复执行与数据污染	执行前先写 checkpoint 记录意图，崩溃后按意图补偿
工具返回文本当指令执行	工具输出被当作用户输入再次规划、产生提示注入	引擎将工具结果以 `role: "tool"` 消息追加进状态（`engine.py`），该角色不会被模型当作指令执行；第17章的 `<memory>` XML 边界是独立的、更强的隔离层，两者互补

本章验收

能画出 planner→schema→policy→executor 的状态转移

能解释幂等键为什么不重复副作用

能说出 MCP 是协议边界而非授权边界

能说出 Progent 双粒度权限（Level 0/1/2）与细粒度策略 DSL 规则

能画出 Naptime 假说驱动自调试闭环并解释 30s 熔断与结构化解析

能定位一个被破坏的 SSE fixture 中 tool_call_id 不匹配的原因

能解释 Manus 式 CodeAct 范式相比传统 JSON Tool Call 在循环与海量中间数据流转上的压倒性优势

能说明 Long-Horizon 上下文修剪器如何实现历史执行输出折叠并保证上下文预算稳定

不看资料，用 5–10 分钟回答：

用一个高风险写操作闭卷解释从模型候选到批准、checkpoint、执行和 trace 的每个边界；分别说明参数无效、批准过期和 timeout 后不确定副作用如何终止。
解释为什么单纯依靠 Prompt 约束智能体行为（如“请不要删除系统文件”）在面对越狱与间接提示注入时完全脆弱；Progent 是如何通过粗粒度特权等级（Level 0/1/2）与细粒度策略 DSL（路径规范化、保护路径黑名单、敏感环境变量、高危命令模式）构建确定性内核拦截网的？
Manus / General Agent 架构专题：为什么在超长多步工程任务中，CodeAct（可执行代码）比传统的 JSON Tool Calling 更具表达力和上下文经济性？如果一个任务需要连续执行 50 步，Long-horizon Context Manager 是如何通过主动修剪（Pruning）与折叠（Folding）防止上下文爆炸与注意力涣散的？
剖析单步工具调用与 Naptime / Project Zero 自调试闭环的本质差异；为什么真实的 0-day 漏洞挖掘和复杂代码调试需要“观察-假设-复现-修补-验证”闭环？30s 熔断看门狗和异常结构化解析分别防御什么风险？
对照 ReAct、Toolformer 与 MCP，解释"模型交替推理/行动""学习何时调用工具""工具协议"各解决什么；为什么三者都不能替代 policy、idempotency 或人工授权。
用 Redux reducer 类比解释 $s_{t + 1} = δ (s_{t}, e_{t}, validate (a_{t}))$ ：为什么每一步必须是"增量更新 + 边界检查"？
解释为什么 typed tool call 能降低编造风险：schema 把输出空间从"任意文本"压缩到"合法 JSON"子空间。
说明 checkpoint 和幂等键分工的不同：一个解决"崩溃后从哪续跑"，一个解决"重试会不会重复"。
调试题：打开 python/tests/test_agent_recovery.py 的故障注入场景，定位"副作用已发生后超时"如何触发 reconcile_required 状态，并说明为什么不能自动重试。（对照故障表第一行）

论文与延伸

ReAct: Synergizing Reasoning and Acting in Language Models（Yao 等，2023）
Toolformer: Language Models Can Teach Themselves to Use Tools（Schick 等，2023）
Progent: Dual-granularity Privilege Management for LLM Agents（Song 等，UC Berkeley CS294-280 L12）
From Naptime to Big Sleep: Using Large Language Models to Catch Vulnerabilities In The Wild（Google Project Zero / DeepMind, Sutton 等，CS294-280 L05）
选读：Chain-of-Thought Prompting（Wei 等，2022）：思维链是 prompt 工程，不是新结构，也不能替代 schema / policy。
规范阅读：Model Context Protocol Specification。
课程讲座：UC Berkeley CS294-280 (Spring 2025: Advanced Large Language Model Agents)
索引：必读论文

实验与参考

关联概念：术语表 - agent loop / tool schema / MCP
论文依据：必读论文 - ReAct / Toolformer / MCP spec

前端/Agent 迁移

这是全书最直接的工程迁移章节：把已有状态机、协议适配、重试、恢复和可观测性经验用于模型不确定输出。模型可以提出计划，但系统负责 schema、权限、审批、状态和副作用。

Agent loop ≈ Redux / XState：每个工具调用是 (state, event) → new_state 的纯函数转换；checkpoint 就像 Redux DevTools 的时间旅行——从任意快照重放整个状态序列。
Typed tool schema ≈ TypeScript + Zod：参数 schema 在规划阶段被校验，就像 Zod 在运行时拦截非法输入——两者都在"执行前"拦截错误。
MCP ≈ OpenAPI / tRPC：MCP 是 Agent 和外部工具之间的契约层；没有 schema 的调用是 undefined behavior。
Idempotency ≈ HTTP Idempotency-Key：高风险写操作带上幂等键，重试不产生重复副作用。
从教学 Harness 到自建自举 Agent（Zen 架构原语对照）：本章手写的最小状态机不是玩具代码的终点，而是工业级自建、可自举 Agent（如开源编码 Agent zen）的内核原语。工业级 Agent 设计的三大 Loop 不变量与本章直接同构：
1. 状态显式化（Explicit State）：会话上下文、工具返回观察值（Observation）、未决的人工审批必须是一等公民数据对象，状态转移显式可追溯，不隐藏在私有闭包中。
2. 单步可观测（Observable Step）：每次模型决策、工具调用、拦截与错误都输出结构化事件（Event），支持随时离线重放（Replay）与度量分析。
3. 执行有边界（Bounded Execution）：零依赖的紧凑原语胜过臃肿框架堆砌——用最少的核心原语（状态、工具契约、政策拦截）组合出自治能力，确保代码完全可读、完全可改、可自举进化。

资源 / 成本 / 隐私

FixtureModel、工具 registry 和 MCP adapter 在本地运行，默认无网络和副作用，预计 gross cost 为 0。trace 只保留脱敏结构化字段；任何真实凭据、cookie 和联系人数据都禁止作为 tool input。

Evidence

仓库当前机器证据（只读快照）

evidence/module-manifest-v1.json 中 13.evidence 指向当前文件：evidence/13-runtime-v1.json。这是当前 checkout 的脱敏机器运行记录，只覆盖该 JSON 记录的命令、指标、产物和已知失败；它不是学习者提交，也不能推出学习者已完成本章。

学习者提交模板（待填写，不是当前机器证据）

复制下面模板并填写自己的真实运行结果。所有 <...> 都是未填写状态；actual 和 artifacts 尤其不能被当作已运行或已通过。artifacts 必须替换为本次提交中真实存在的仓库相对路径。

yaml

schema: learn-llm.evidence.v1
module: 15-agent-tools
commit: <learner-commit-sha>
verified_at: <iso-date>
environment: <sanitized-python-device>
seed: 10
commands:
  - PYTHONPATH=python python -m pytest python/tests/test_tool_policy.py python/tests/test_mcp_adapter.py python/tests/test_agent_recovery.py -q
metrics:
  - name: schema_validity
    expected: 1.0
    actual: <recorded-value>
  - name: unapproved_side_effects
    expected: 0
    actual: <recorded-value>
  - name: recoverable_fault_recovery_rate
    expected: <versioned-threshold>
    actual: <recorded-value>
artifacts:
  - <learner-repo-relative-artifact-path>
cost:
  gross_usd: 0
  credit_usd: 0
licenses:
  - source: <source>
    version: <version>
    license: <license>
    attribution: <attribution>
    redistribution: <redistribution>
known_failures:
  - <sanitized-failure-or-none>

只跑 FixtureModel、没有批准绑定或没有故障恢复 trace 时，本章保持 gate。

下一步

进入第16章 · 真实大模型 API 实战：把手写 harness 接到真实 messages / SSE / function calling 往返；没有 API key 就走页面里的离线回放。

第15章 · Typed Tools、MCP 与可恢复 Agent ​

本章目标 ​

阶段一：把 Agent 看成一个状态机 ​

直觉：Reducer，不是黑盒 ​

Agent 工具调用全生命周期时序图 ​

工具执行失败时的自愈闭环（Self-Correction） ​

Agent 三大规划范式：ReAct vs Plan-and-Solve vs Reflexion（伯克利 CS294 核心准则） ​

Reflexion 的工程机制：如何防止 Agent 在连续错误中陷入死循环？ ​

语法约束解码（Constrained Decoding / Grammar-Based Sampling） ​

并行工具调用 ​

内容块并集（content block union） ​

从 API/CLI 到屏幕界面：GUI 智能体可执行动作空间（Executable Language Grounding） ​

交互观察 ​

交互：Agent 主循环状态机

Shape 契约：数据模型与状态追踪图式先行 ​

阶段二：四类动作、Progent 权限分级与策略防御系统 ​

为什么 Prompt 软约束在面对越狱与注入时形同虚设？ ​

Progent 工业级权限分级系统（UC Berkeley CS294-280 L12） ​

1. 粗粒度特权等级（Privilege Levels） ​

2. 细粒度策略 DSL 与规则集（Fine-grained Policy Rules） ​

最小 Python 拦截器实现：assert_tool_policy ​

工具注册表与工具上下文 ​

阶段三：幂等、Checkpoint 与可恢复 ​

幂等键：重试不等于重做 ​

Checkpoint：崩溃后从哪续跑 ​

生产级沙箱执行环境（Sandboxed Execution Environment） ​

Naptime 范式：假说驱动的自调试执行与环境反馈闭环（DeepMind Project Zero） ​

1. 单步工具调用 vs. 假说驱动自调试的本质差异 ​

2. Execution Feedback 架构模型与防御机制 ​

工具输出截断 ​

HITL、checkpoint 与幂等恢复

停止原因分类（stop-reason taxonomy） ​

阶段四：MCP 是协议边界，不是授权边界 ​

阶段五：与 LangChain / LangGraph 的概念对照 ​

阶段六：动手实验 ​

环境准备 ​

步骤 ​

预期输出与判定信号 ​

概念图 ​

阶段五：通用自主智能体（General Agent）演进——Manus 式 CodeAct 沙盒与长程上下文工程 ​

1. 为什么顶级 Agent 弃用 JSON Tool Calling，转向 CodeAct？ ​

2. 视觉推演：Manus 级 CodeAct 沙盒执行与长程上下文修剪流 ​

3. 长程任务（Long-Horizon）上下文修剪算法 ​

故障注入与预期信号 ​

本章验收 ​

论文与延伸 ​

实验与参考 ​

前端/Agent 迁移 ​

资源 / 成本 / 隐私 ​

Evidence ​

仓库当前机器证据（只读快照） ​

学习者提交模板（待填写，不是当前机器证据） ​

下一步 ​

第15章 · Typed Tools、MCP 与可恢复 Agent

本章目标

阶段一：把 Agent 看成一个状态机

直觉：Reducer，不是黑盒

Agent 工具调用全生命周期时序图

工具执行失败时的自愈闭环（Self-Correction）

Agent 三大规划范式：ReAct vs Plan-and-Solve vs Reflexion（伯克利 CS294 核心准则）

Reflexion 的工程机制：如何防止 Agent 在连续错误中陷入死循环？

语法约束解码（Constrained Decoding / Grammar-Based Sampling）

并行工具调用

内容块并集（content block union）

从 API/CLI 到屏幕界面：GUI 智能体可执行动作空间（Executable Language Grounding）

交互观察

Shape 契约：数据模型与状态追踪图式先行

阶段二：四类动作、Progent 权限分级与策略防御系统

为什么 Prompt 软约束在面对越狱与注入时形同虚设？

Progent 工业级权限分级系统（UC Berkeley CS294-280 L12）

1. 粗粒度特权等级（Privilege Levels）

2. 细粒度策略 DSL 与规则集（Fine-grained Policy Rules）

最小 Python 拦截器实现：`assert_tool_policy`

工具注册表与工具上下文

阶段三：幂等、Checkpoint 与可恢复

幂等键：重试不等于重做

Checkpoint：崩溃后从哪续跑

生产级沙箱执行环境（Sandboxed Execution Environment）

Naptime 范式：假说驱动的自调试执行与环境反馈闭环（DeepMind Project Zero）

1. 单步工具调用 vs. 假说驱动自调试的本质差异

2. Execution Feedback 架构模型与防御机制

工具输出截断

停止原因分类（stop-reason taxonomy）

阶段四：MCP 是协议边界，不是授权边界

阶段五：与 LangChain / LangGraph 的概念对照

阶段六：动手实验

环境准备

步骤

预期输出与判定信号

概念图

阶段五：通用自主智能体（General Agent）演进——Manus 式 CodeAct 沙盒与长程上下文工程

1. 为什么顶级 Agent 弃用 JSON Tool Calling，转向 CodeAct？

2. 视觉推演：Manus 级 CodeAct 沙盒执行与长程上下文修剪流

3. 长程任务（Long-Horizon）上下文修剪算法

故障注入与预期信号

本章验收

论文与延伸

实验与参考

前端/Agent 迁移

资源 / 成本 / 隐私

Evidence

仓库当前机器证据（只读快照）

学习者提交模板（待填写，不是当前机器证据）

下一步