本书统一使用以下术语。 turn 是一次用户与系统的交互轮次。用户提出一个任务，是一个 turn 的开始。 step 是 runtime 在一个 turn 内的一次模型决策或工具执行推进。一次 turn 可以有很多 step。 run 是一次完整执行，从收到用户请求到最终回答、失败或取消。长任务中，
第八章 Checkpoint、Resume、Rollback：8.3 gitbased checkpoint 另一种做法是借助 git。每个 step 或关键写入点创建临时 commit、stash、worktree 或 patch 文件。 gitbased 的优点是成熟、可审计、适合代码项目。缺点
Tool Registry 不是一个 Map<string, Function。它至少保存以下信息： 这些字段不是装饰。description 会影响模型是否选择工具；inputSchema 负责校验；riskLevel 进入权限审批；timeoutMs 进入执行器；outputPolicy 进入上
上下文构建往往是 coding agent 的核心竞争力。读时关注： system/developer 指令； 用户消息和历史保留； 文件读取策略； repo map； 最近修改； terminal output； diagnostics； selection/range； embedding 或检
用户说'回滚'时，可能有三种意思： 回滚文件到某个 checkpoint； 回滚对话状态，让 Agent 忘记某段计划； 回滚外部副作用，例如撤销 API 操作。 Runtime 必须区分这三件事。文件 patch 可以回滚，对话状态可以恢复，外部副作用通常只能补偿，不能直接撤销。比如创建了 Git
模型调用失败时，runtime 可以重试；但要分清失败类型。 网络抖动可以重试；限流需要退避；上下文超限需要重新构建上下文；模型不支持某个 schema 特性，需要 schema 降级；工具调用格式不合法，可以让模型重试一次；安全策略拒绝，不应换模型绕过。 一个清晰的模型错误分类： 类型 处理 RA
完成本书和毕业项目后，你应能做到： 从零实现一个 TypeScript Agent Runtime； 讲清楚 tool call loop 的完整生命周期； 设计工具 schema、权限模型和审批流； 解决 context 超限与历史压缩； 实现 checkpoint、resume、rollback
一个成熟 runtime 必须支持取消。取消不是'UI 不显示了'，而是从用户操作一路传播到模型请求、工具执行、子进程和资源清理。 这段代码只是开始。上线后的 runtime 需要把 AbortSignal 传给 HTTP client、模型 SDK、工具 executor、子进程管理器。任何一层吞
能力越大，边界越要清楚。本章谈权限和安全。 Agent 的能力来自工具，风险也来自工具。一个不会调用工具的模型，最多说错话；一个能执行命令、写文件、联网、访问数据库的 Agent，可能造成真实损失。Runtime 的安全目标不是把 Agent 绑住，而是让它在明确边界内做事；越过边界时，停下来请人确
恢复流程要保守： 1. 找到最新完整 checkpoint； 2. 校验 workspace 状态； 3. 恢复 message history 和 run state； 4. 检查最后一个 tool call 是否已完成； 5. 对不可重复工具禁止自动重放； 6. 给模型注入恢复说明； 7. 从下
Agent 迟早要接外部工具。本章讨论怎么接，以及怎么避免被某个供应商或协议绑死。 Agent Runtime 不能永远只使用本地写死的工具。它需要连接数据库、浏览器、设计工具、代码托管平台、内部系统、文档库和企业权限系统。MCP 的出现，正是为了解决 LLM 应用与外部数据、工具之间缺少统一连接方
MCP Tools 规范里，Client 通过 tools/list 发现可用工具，通过 tools/call 调用工具。工具包含名称、描述和输入 schema。Server 声明 tools capability 后，必须响应 tools/list；工具列表可以为空，也可以随时间变化。 对 run
真实模型有随机性、网络波动和供应商变化。Eval 需要两层： 第一层用 deterministic mock model 测 runtime 逻辑。它按照脚本返回固定 tool calls，用来验证 schema 校验、权限、checkpoint、trace、停止条件。 第二层用真实模型测端到端能力
一次线上失败，如果不能转化为 eval，它就会再次发生。建议流程： 1. 从 trace 中提取用户目标、关键上下文、工具调用和失败结果； 2. 去除 secret 和用户隐私； 3. 固化 workspace fixture； 4. 写 expected behavior； 5. 加入 CI； 6
日志不是 trace。日志多半给开发者看，trace 应能还原运行路径。读项目时找： 每次模型调用是否记录； token usage 是否记录； tool call args 是否脱敏； tool result 是否保存； latency 是否可见； 错误是否分类； 用户确认是否入 log； 是否能
一个 Agent trace 至少包含： span 至少包含： 不要把 trace 做成聊天 transcript。聊天记录回答'说了什么'，trace 回答'系统做了什么'。
无论选哪个方向，最终交付都应包括： 设计文档； 最小实现； 单元测试； 至少 5 个 eval 或 fixture； trace/log 示例； README 使用说明； 失败场景说明； 安全和隐私影响说明； 后续工作清单。 PR 描述建议结构： 一个好 PR 不只是'代码能跑'，还要让维护者相信你
trace 很敏感。它可能包含用户代码、命令输出、环境变量、文件路径、API 响应、模型输入输出。生产系统中，trace 需要： secret 脱敏； 访问控制； 保留期限； 采样策略； 用户可删除机制； 外部导出审计。 不要为了调试方便，把所有 trace 原样传到第三方系统。可观测追求的不是越多
《Agent Runtime 工程化：从工具调用循环到可恢复执行系统》电子版系列完整目录，收录系列导读、12 章导读、全部小节与附录链接。
Agent：根据目标和上下文选择下一步行动的执行体。 Agent Runtime：负责模型调用、工具调用、上下文、权限、状态、观测、恢复、评测和成本治理的运行系统。 Tool Calling：模型输出结构化工具调用，应用执行工具并把结果返回模型的接口能力。 Tool Registry：工具定义、sc
