《Agent Runtime 工程化：生产级 AI Agent 架构、运行时与工程实践》 这是一套面向工程师、技术负责人和 AI 产品架构师的 Agent Runtime 工程化读本。全书按章发布，从最小工具调用循环开始，逐步进入工具系统、上下文工程、MCP、权限安全、可恢复执行、trace、eval 和产品级实战。 读者不需要把它当成零散教程。更好的读法是按章推进：先建立
《Agent Runtime 工程化：从工具调用循环到可恢复执行系统》电子版系列完整目录，收录系列导读、12 章导读、全部小节与附录链接。
术语是否统一：Runtime、Agent Loop、tool call、observation、checkpoint、trace、eval。 所有'截至 20260812'的事实是否需要更新。 图片中的文字是否清晰准确。 代码是否按目标 Node.js 版本跑通。 权限、安全、隐私段落是否避免绝对化
章节 代码主题 第 1 章 Agent Loop 伪代码 第 2 章 timeout、AbortSignal、子进程执行器 第 3 章 ModelResponse、ToolCall、最小工具 第 4 章 ToolDefinition、风险等级、审批请求 第 5 章 Context Builder 输
附录 B miniagent 学习路线 第 1 周：实现只读 miniagent。完成 listfiles、readfile、shellreadonly，输出 trace JSON。 第 2 周：实现工具治理。加入 editfile、applypatch、runcommand、searchcode，
Agent：根据目标和上下文选择下一步行动的执行体。 Agent Runtime：负责模型调用、工具调用、上下文、权限、状态、观测、恢复、评测和成本治理的运行系统。 Tool Calling：模型输出结构化工具调用，应用执行工具并把结果返回模型的接口能力。 Tool Registry：工具定义、sc
完成本书和毕业项目后，你应能做到： 从零实现一个 TypeScript Agent Runtime； 讲清楚 tool call loop 的完整生命周期； 设计工具 schema、权限模型和审批流； 解决 context 超限与历史压缩； 实现 checkpoint、resume、rollback
回看全书，我们走过了这条线： 1. 理解 Runtime 比 LLM App 多承担什么； 2. 补齐 Node 异步、取消、进程管理； 3. 写出最小 Agent Loop； 4. 把工具系统治理起来； 5. 给上下文建立预算和调试报告； 6. 接入 MCP 和 Provider Adapter；
无论选哪个方向，最终交付都应包括： 设计文档； 最小实现； 单元测试； 至少 5 个 eval 或 fixture； trace/log 示例； README 使用说明； 失败场景说明； 安全和隐私影响说明； 后续工作清单。 PR 描述建议结构： 一个好 PR 不只是'代码能跑'，还要让维护者相信你
目标：实现可恢复执行。 功能范围： 每轮工具执行前创建 checkpoint； 文件修改保存 patch； 支持恢复文件状态； 支持恢复 session 状态； 进程崩溃后继续 run； 恢复后不重复执行高风险工具。 适合证明： 状态管理； 可恢复执行； 可靠性工程； coding agent 长任
目标：给 MCP 工具接入增加风险分类和审批层。 功能范围： MCP 工具 discovery 后先做 risk classification； 高风险工具需要用户确认； 非交互模式使用 policy 自动裁决； 所有审批写入 audit log； 工具列表变化时更新模型上下文。 适合证明： MCP
目标：给 Agent 增加上下文预算分配器。 功能范围： 对历史消息、文件片段、工具结果、repo map 分配 token； 超限时按优先级降级； 生成 context debug report； 在 UI 或日志中解释'为什么包含/丢弃某项'。 适合证明： 上下文工程； token 成本治理；
目标：给一个开源 coding agent 或你的 miniagent 增加 Eval Harness。 功能范围： 录制真实任务 trace； 从 trace 生成 eval case 草稿； 支持本地 replay； 输出成功率、失败类型、平均 token、平均耗时； CI 中设置回归门禁。 适
最后要交一件能拿得出手的东西：一个可展示、可维护、可验收的 runtime feature。 毕业项目不能只是再写一个 demo。它应该证明你理解 Agent Runtime 的工程闭环：需求从真实问题来，方案能解释权衡，代码能集成现有系统，行为可观测，效果可评测，失败可恢复，文档能让别人维护。 本
你能在一个陌生 Agent 项目中快速定位入口、run 生命周期、工具系统、上下文构建、权限审批和状态保存；能提出一个不浮夸、可落地的 PR 级改造点。做到这里，你已经具备二开大型 Agent 项目的阅读方法。
选择 Cline、Continue、aider、OpenHands、Codex CLI 中任意两个，用十问模板读源码。每个项目画一张执行链路图，并指出一个你认为可以改进的 runtime feature。
每个项目输出一篇 1500 到 3000 字笔记，结构固定： 固定模板的价值，是让你能横向比较项目，而不是每篇笔记都重新发明结构。
日志不是 trace。日志多半给开发者看，trace 应能还原运行路径。读项目时找： 每次模型调用是否记录； token usage 是否记录； tool call args 是否脱敏； tool result 是否保存； latency 是否可见； 错误是否分类； 用户确认是否入 log； 是否能
状态包括聊天历史、任务状态、工具执行记录、文件变更、UI 状态、用户配置。读时问： 状态存在内存、文件、数据库，还是 git？ 崩溃后能恢复到哪里？ 工具执行是否有 ledger？ 用户审批是否持久化？ 文件变更是否可回滚？ 长任务是否可以暂停和继续？ 这部分最能区分 demo 和系统。
上下文构建往往是 coding agent 的核心竞争力。读时关注： system/developer 指令； 用户消息和历史保留； 文件读取策略； repo map； 最近修改； terminal output； diagnostics； selection/range； embedding 或检
