无论选哪个方向，最终交付都应包括： 设计文档； 最小实现； 单元测试； 至少 5 个 eval 或 fixture； trace/log 示例； README 使用说明； 失败场景说明； 安全和隐私影响说明； 后续工作清单。 PR 描述建议结构： 一个好 PR 不只是'代码能跑'，还要让维护者相信你
trace 很敏感。它可能包含用户代码、命令输出、环境变量、文件路径、API 响应、模型输入输出。生产系统中，trace 需要： secret 脱敏； 访问控制； 保留期限； 采样策略； 用户可删除机制； 外部导出审计。 不要为了调试方便，把所有 trace 原样传到第三方系统。可观测追求的不是越多
《Agent Runtime 工程化：从工具调用循环到可恢复执行系统》电子版系列完整目录，收录系列导读、12 章导读、全部小节与附录链接。
Agent：根据目标和上下文选择下一步行动的执行体。 Agent Runtime：负责模型调用、工具调用、上下文、权限、状态、观测、恢复、评测和成本治理的运行系统。 Tool Calling：模型输出结构化工具调用，应用执行工具并把结果返回模型的接口能力。 Tool Registry：工具定义、sc
最后要交一件能拿得出手的东西：一个可展示、可维护、可验收的 runtime feature。 毕业项目不能只是再写一个 demo。它应该证明你理解 Agent Runtime 的工程闭环：需求从真实问题来，方案能解释权衡，代码能集成现有系统，行为可观测，效果可评测，失败可恢复，文档能让别人维护。 本
一次失败任务可以从 trace 里定位原因；你能区分模型问题、工具问题、权限问题、上下文问题和 runtime 问题；trace 中没有明文 secret；每个失败都能转化为一个潜在 eval case。
模型供应商的工具调用接口并不完全一致。Runtime 应有自己的 provider adapter： 这样做的好处是： 可切换 OpenAI、Anthropic、本地模型或 Vercel AI SDK； 可统一 stream event； 可把 provider 原生 tool call 转成本地
token budget 不只是技术限制，也是产品预算。一次 run 里，token 影响延迟、成本和可靠性。越长的上下文越不一定越好，因为模型注意力会被稀释，缓存命中也可能下降。 可以把上下文分为六层： 1. 系统与开发者指令； 2. 用户当前意图； 3. 近期完整对话； 4. 当前任务状态和计划
建立 evals/ 目录： 10 个文件编辑任务； 10 个工具调用任务； 10 个失败恢复任务； 每个任务有 fixture、prompt、expected、policy； CI 中运行 mock replay； 成功率低于阈值则失败； 输出报告包含成功率、平均 step、平均 token、失败类
第八章 Checkpoint、Resume、Rollback：8.2 patchbased checkpoint 对 coding agent 来说，文件系统状态是第一等公民。最轻量的做法是 patchbased checkpoint：每次工具执行前后记录 diff。 优点： 存储小； 容易审计；
成功率重要，但不够。还要看： 平均 step 数； 平均 tool call 数； 平均 token； 平均耗时； 权限请求次数； 用户拒绝后是否停止； 相同错误重复次数； 输出是否引用证据； 文件 diff 是否最小； 回滚是否成功。 一个 runtime 策略可能成功率略高，但成本翻倍、工具调用
工具结果、日志、文件片段进入模型上下文前，应经过 secret scanning。至少检查： API key； OAuth token； 私钥； .env； cloud credential； 数据库连接串； 内部域名和个人信息。 发现 secret 后，不要把原文注入模型。可以替换成 REDACT
回滚不丢对话上下文；恢复不重复执行高风险工具；文件状态和 session 状态能对应到同一个 checkpoint；trace 可以说明恢复从哪一步开始。做到这里，runtime 才从脚本接近系统。
用户审批不能只当 UI 事件。对 runtime 来说，它是一条系统事实，每次都应写入 audit log： 恢复执行时，这些记录尤其重要。已经被拒绝的危险工具，不能因为进程重启就再次自动执行。已经批准的一次性操作，也不应无限期复用授权。
读开源 Agent 项目，别一上来就钻进细节。本章给一套追主线的方法。 读开源 Agent 项目，最怕两种读法。一种是从 README 兴奋到插件列表，最后只记住产品功能；另一种是一头扎进代码细节，三天后迷失在 UI、配置和历史兼容里。Runtime 工程师读源码，要带着问题读，尤其要追执行链路。
coding agent 需要理解仓库。直接把所有文件塞进上下文不可行，所以需要 repo map。 repo map 可以包含： 目录树； 关键入口文件； 导出的函数、类、类型； import/export 关系； 最近修改文件； 测试文件与源文件对应关系； README、配置文件、路由文件摘要。
术语是否统一：Runtime、Agent Loop、tool call、observation、checkpoint、trace、eval。 所有'截至 20260812'的事实是否需要更新。 图片中的文字是否清晰准确。 代码是否按目标 Node.js 版本跑通。 权限、安全、隐私段落是否避免绝对化
目标：实现可恢复执行。 功能范围： 每轮工具执行前创建 checkpoint； 文件修改保存 patch； 支持恢复文件状态； 支持恢复 session 状态； 进程崩溃后继续 run； 恢复后不重复执行高风险工具。 适合证明： 状态管理； 可恢复执行； 可靠性工程； coding agent 长任
写一个能演示的 Agent 很快。写一个能稳定跑的 Agent 很慢。慢在三件事上。 第一，模型输出不是普通函数返回值。它可能少字段、多字段、把 JSON 写坏、重复调用工具、误解工具描述，或者在工具失败后编一个像真的观察结果。Runtime 要把模型输出当作不可信输入处理。 第二，工具不是纯计算。
实现一个 Context Builder： 用户当前消息固定保留； 最近 6 轮完整保留； 旧历史压缩为 summary； 大文件只保留摘要和关键片段； 工具结果按重要度截断； 输出 context debug report。 准备一份 200K token 的模拟历史，压缩进 32K / 64K
