《Agent Runtime 工程化》第十一章 Agent Runtime 进阶学习路线

很多团队第一次做 Agent 优化，靠的是人工试用：今天问十个问题，感觉回答更顺了，工具调用少了一点，失败也少了。这样的判断可以作为直觉，但不能作为发布依据。Agent Runtime 的行为由模型、提示词、工具描述、上下文策略、权限策略和停止条件共同决定；任意一个变量变化，都可能让系统在某类任务上退步。

Eval Harness 的价值，是把这种模糊感受变成可重复证据。它至少要回答四个问题：

落地时先不要追求'全自动评测一切'。更稳的做法是分两层。

第一层是 mock replay。用固定的模型事件脚本测试 Runtime 逻辑，例如非法参数是否被拦截、权限拒绝后是否停止、checkpoint 恢复后是否重复执行工具。这一层不依赖真实模型，适合放进每次提交的 CI。

第二层是真实模型 smoke eval。它覆盖少量关键任务，观察端到端表现。真实模型会有波动，所以不要用字面答案做唯一标准；更适合用行为断言、文件 diff、测试命令和人工抽查组合。

从学习到实战，可以按这个顺序推进：

1. 定义 eval case schema；
2. 写 10 个手工 golden task；
3. 接入 mock provider；
4. 从 trace 生成 eval case 草稿；
5. 输出 Markdown 或 HTML 报告；
6. 把危险行为写成硬门禁；
7. 再接真实模型 smoke eval；
8. 让 PR 模板要求说明 eval 结果。

做到第 8 步，你就不再只是'会调模型'，而是能维护 Agent 行为质量的人。

11.3 路线 B：Context Budget Allocator，让长任务保持判断力

上下文工程不是 prompt 技巧，而是 Runtime 的信息调度。长任务中，模型真正需要的是当前目标、关键约束、最近行动、相关文件、失败证据和下一步可选工具。把所有历史都塞进去，模型不会因此更聪明；它只会更贵、更慢、更容易被旧信息干扰。

Context Budget Allocator 的目标，是把'给模型什么信息'变成可解释策略。一个可用设计至少包含四层：

实战里最容易踩的坑，是把 repo map 当作真实文件，把摘要当作事实。Repo map 只能告诉模型'可能该看哪里'；真正修改代码前，仍然要读取精确片段。摘要只能帮助维持背景，不能替代错误栈、测试输出和用户明确约束。

推荐实现一个 ContextBuildResult，每次构建上下文都输出报告：

type ContextBuildResult = {
  messages: RuntimeMessage[];
  report: {
    budget: number;
    used: number;
    mustKeep: string[];
    includedFiles: string[];
    summarized: string[];
    dropped: string[];
    reasons: Record<string, string>;
  };
};

这个报告应该进入 trace。将来模型答错时，先看 report：它是否看见了正确文件？是否丢掉了用户约束？是否把旧失败摘要误当成当前事实？这些问题比'换个模型试试'更接近工程真相。

这条路线可以继续深挖：

• 代码库结构摘要；
• semantic search 与 lexical search 的组合；
• IDE selection、diagnostics、terminal output 的优先级；
• 多轮任务中的历史压缩；
• 多 Agent 协作时的共享 context；
• 对超长工具输出的摘要和 artifact 管理。

11.4 路线 C：MCP 工具权限层，连接生态但不放弃边界

MCP 让外部工具接入变容易，也让工具边界变复杂。过去工具是你自己注册的函数；现在工具可能来自本地插件、团队内部 Server、第三方远程 Server。工具描述可能不完整，schema 可能变化，Server 信任等级也不同。把 MCP 工具原样暴露给模型，是一种偷懒。

一个成熟 Runtime 应该把 MCP 工具先包装成本地能力，再进入统一治理：

type McpToolPolicy = {
  serverId: string;
  trustLevel: "local_trusted" | "team_audited" | "third_party" | "unknown";
  namespace: string;
  riskLevel: RiskLevel;
  defaultDecision: "allow" | "ask" | "deny";
};

实战要点有三条。

第一，命名空间必须清楚。两个 Server 都叫 search 时，模型不能看到两个无法区分的工具。用 mcp.github.search_issues、mcp.docs.search_pages 这样的名字，虽然长一点，但边界清楚。

第二，风险不能只相信工具描述。工具说自己是'read only'，Runtime 仍然要结合 Server 来源、输入 schema、工具名称和用户授权判断。未知 Server 的写入工具默认应走确认，非交互模式下应拒绝。

第三，工具列表变化要进入上下文策略。tools/list 结果改变后，Tool Registry、模型工具描述和权限缓存都要刷新。恢复执行时，更要确认当时批准的工具是否仍是同一个 schema。

这条路线可以继续深挖：

• MCP Server discovery 和配置管理；
• OAuth、credential、环境变量传递边界；
• remote MCP 的网络安全；
• 工具列表缓存和变更通知；
• MCP sampling 与 Host 策略；
• 企业内部工具市场和审计。

11.5 路线 D：Checkpoint 与 Rollback，让长任务可以恢复

可恢复执行是 Agent Runtime 从脚本走向系统的分界线。长任务一定会中断，真正的问题是中断后能不能继续、能不能解释、能不能避免重复副作用。

Checkpoint 不是保存聊天记录。它至少要保存四类状态：

文件类任务可以先做 patch-based checkpoint。写文件前记录 base hash，写文件后记录 diff 和 current hash。回滚时先验证当前文件是否仍匹配 expected hash；如果用户又改过文件，就生成冲突报告，而不是强行覆盖。

外部副作用要单独看待。发邮件、创建 issue、提交订单、执行数据库迁移，这些动作通常不能简单 rollback。更真实的设计是补偿动作：关闭 issue、发送更正邮件、执行 down migration。Runtime API 不应把这些都叫 undo，而应区分 rollback_files、restore_session 和 compensate_external_action。

继续深入时，重点看：

• durable execution；
• idempotency key；
• tool ledger；
• crash recovery；
• 文件系统快照；
• session DB；
• 人机协同暂停和恢复；
• 外部副作用补偿。

11.6 路线 E：Observability，把失败变成资产

可观测不是最后加一个 dashboard。它应该从最小 runtime 开始就存在：每次 run 有 ID，每次工具调用有 ID，每次权限决定有证据，每次上下文构建有报告。

进阶学习中，Trace 路线可以这样走：

这条路线的关键是克制。不要把所有内容都发到观测平台，不要用 trace 替代内容仓库，不要为了调试方便保存 secret。好的 trace 是证据索引，不是隐私风险集合。

11.7 路线 F：产品化 Runtime，跨过 demo 的最后一段

真实产品里的 Agent Runtime 还要面对：

• 多用户和组织权限；
• 模型供应商和计费策略；
• 插件与技能市场；
• UI 事件和长任务状态；
• 审计和数据保留；
• 失败重试和用户通知；
• 部署、升级和兼容；
• 团队协作和配置治理。

这些内容不会在一个 mini-agent 中完全展开，但读者要知道它们存在。产品化不是把 loop 包一层界面，而是把 runtime 的每个边界放到用户、组织和运维环境中重新审视。

一个实用判断是：当你准备把 Agent 给别人长期使用时，至少问七个问题：

11.8 从学习样例到真实项目模块

本书前面的 mini-agent 是学习样例，不是产品模板。真实项目会多出很多约束：用户权限、组织策略、审计要求、成本预算、模型供应商差异、插件生态、隐私合规、UI 交互、团队协作。你要做的不是把书里的代码复制进公司项目，而是把书里的运行机制映射到目标系统。

进入真实项目时，可以按这张检查表拆解：

每个问题都能对应一个 PR。好的二开不是'我加了一个大功能'，而是'我收紧了一个 runtime 边界，并用测试和 trace 证明它有效'。

11.9 90 天学习计划

如果读者希望把本书内容转成个人学习计划，可以按 90 天推进。

这不是固定课表，而是节奏建议。每两周必须有可运行产物。Agent Runtime 是工程能力，不能只靠阅读建立。

11.10 持续学习闭环

Agent Runtime 的学习闭环可以浓缩成一条路线：

1. 先写最小 loop，理解模型、工具、观察结果如何往返；
2. 再写工具系统，学会 schema、权限和失败分类；
3. 接着写上下文预算，让长任务不失忆、不爆窗；
4. 接 MCP 和 Provider Adapter，理解生态接入和模型差异；
5. 加 checkpoint、trace、eval，把可靠性变成系统能力；
6. 读开源项目，把这些机制映射到真实代码；
7. 回到自己的项目，选一个痛点做可验证改造；
8. 把失败写进 eval，把经验写进设计文档，再进入下一轮。

这条路线不会因为某个模型、框架或协议更新而失效。工具会变，模型会变，接口会变，但 Runtime 要解决的问题很稳定：状态、边界、恢复、证据和反馈。

11.11 读完本书后应具备的能力

完成本书后，你应能做到：

• 解释 Agent、Workflow、Tool、Runtime 的边界；
• 设计一个 TypeScript/Node.js 版最小 Agent Loop；
• 为工具设计 schema、风险等级、输出策略和失败语义；
• 建立上下文预算、repo map、滚动摘要和 debug report；
• 接入 MCP Server，并处理动态工具变化和信任分层；
• 设计 shell、文件、网络、安装、破坏性操作的权限策略；
• 实现 checkpoint、resume、rollback 的核心数据结构；
• 用 trace 定位模型、工具、权限、上下文或 runtime 问题；
• 用 eval harness 做回归门禁，而不是靠感觉判断好坏；
• 读懂主流开源 coding agent 的执行链路，并提出 PR 级改造方案；
• 在真实产品里讨论成本、隐私、审批、恢复和发布风险。

如果你能做到这些，你已经不只是 Agent 的使用者，而是能参与构建 AI Agent 基础设施的工程师。

系列文章目录

• 《Agent Runtime 工程化》完整目录
• 《Agent Runtime 工程化》第一章 Agent Runtime 全景
• 《Agent Runtime 工程化》第二章 TypeScript / Node Runtime 基础
• 《Agent Runtime 工程化》第三章 最小 Agent Loop
• 《Agent Runtime 工程化》第四章 工具系统设计
• 《Agent Runtime 工程化》第五章 上下文工程
• 《Agent Runtime 工程化》第六章 MCP 与 Provider 抽象
• 《Agent Runtime 工程化》第七章 权限与安全边界
• 《Agent Runtime 工程化》第八章 Checkpoint、Resume、Rollback
• 《Agent Runtime 工程化》第九章 可观测与 Trace
• 《Agent Runtime 工程化》第十章 Eval Harness 与 CI 回归
• 《Agent Runtime 工程化》第十一章 Agent Runtime 进阶学习路线
• 《Agent Runtime 工程化》第十二章 hermes-agent 产品级实战
• 《Agent Runtime 工程化》附录