模型 span： provider； model； prompt tokens； completion tokens； latency； finish reason； tool call 数量； 是否触发上下文降级； response id 或 continuation metadata。 工具 s
一个 Agent trace 至少包含： span 至少包含： 不要把 trace 做成聊天 transcript。聊天记录回答'说了什么'，trace 回答'系统做了什么'。
Agent 出错后，最怕只剩一句'模型没做好'。这一章讲怎么查清楚。 没有 trace 的 Agent Runtime，就像没有采访记录的新闻调查。出错后只能凭印象复盘：模型好像看过文件，好像调用过工具，好像测试失败了，好像用户批准过。工程系统不能靠'好像'。 OpenTelemetry 把 tra
回滚不丢对话上下文；恢复不重复执行高风险工具；文件状态和 session 状态能对应到同一个 checkpoint；trace 可以说明恢复从哪一步开始。做到这里，runtime 才从脚本接近系统。
为 miniagent 增加 checkpoint： 每个 step 前保存 precheckpoint； 工具执行后保存 postcheckpoint； 文件写入记录 patch 和 base hash； audit log 纳入 checkpoint； crash 后可以从最新 checkpoi
用户说'回滚'时，可能有三种意思： 回滚文件到某个 checkpoint； 回滚对话状态，让 Agent 忘记某段计划； 回滚外部副作用，例如撤销 API 操作。 Runtime 必须区分这三件事。文件 patch 可以回滚，对话状态可以恢复，外部副作用通常只能补偿，不能直接撤销。比如创建了 Git
幂等性是恢复执行的核心词。一个工具如果重复执行不会造成额外副作用，就更容易恢复。例如读文件幂等，搜索幂等，纯计算幂等。写文件如果基于相同 base hash 应用同一个 patch，也可以设计成近似幂等。发邮件、支付、删除远程资源通常不幂等。 工具定义中应声明： 这会直接影响 resume 策略。
恢复流程要保守： 1. 找到最新完整 checkpoint； 2. 校验 workspace 状态； 3. 恢复 message history 和 run state； 4. 检查最后一个 tool call 是否已完成； 5. 对不可重复工具禁止自动重放； 6. 给模型注入恢复说明； 7. 从下
第八章 Checkpoint、Resume、Rollback：8.3 gitbased checkpoint 另一种做法是借助 git。每个 step 或关键写入点创建临时 commit、stash、worktree 或 patch 文件。 gitbased 的优点是成熟、可审计、适合代码项目。缺点
第八章 Checkpoint、Resume、Rollback：8.2 patchbased checkpoint 对 coding agent 来说，文件系统状态是第一等公民。最轻量的做法是 patchbased checkpoint：每次工具执行前后记录 diff。 优点： 存储小； 容易审计；
一个 checkpoint 至少包含： session id、run id、step id； message history 或其可重建引用； 当前计划和 stop condition 状态； tool call 计划、执行结果、是否有副作用； 审批记录； 文件系统变更摘要； token/cost/
长任务一定会中断。问题是：失败后怎么继续，而不是重来？ Agent Runtime 一旦进入真实工程任务，就会遇到长运行：改多个文件、跑多轮测试、安装依赖、查文档、等待用户确认。长运行必然遇到中断。浏览器刷新、进程崩溃、网络超时、模型失败、用户临时离开，都可能打断 run。如果没有 checkpoi
你应该能解释为什么 Agent 不能直接执行任意 shell；能为 MCP 工具设计权限审批策略；能区分 schema 校验、权限策略和用户确认；能保证恢复执行后不会重复越权。
实现 Tool Permission Matrix： 对文件路径做 workspace whitelist； 对 shell 命令做风险分类； 对 destructive 操作默认拒绝； 对 write/network/install 操作生成 preview 并请求确认； 所有审批写入 audit
用户审批不能只当 UI 事件。对 runtime 来说，它是一条系统事实，每次都应写入 audit log： 恢复执行时，这些记录尤其重要。已经被拒绝的危险工具，不能因为进程重启就再次自动执行。已经批准的一次性操作，也不应无限期复用授权。
MCP 让工具接入变容易，也让工具信任问题变复杂。一个 Server 暴露的工具描述不应被 runtime 无条件信任。规范本身也提醒，工具描述等行为注解应被视为不可信，除非来自可信 Server。 因此，MCP 工具审批建议按 Server 信任级别分层： Server 类型 默认策略 官方可信、
coding agent 很容易倾向'缺包就装'。但安装依赖是供应链入口。Runtime 至少应要求： 展示包名和版本； 优先使用 lockfile； 对陌生包提高审批等级； 对 install scripts 保持警惕； 必要时使用 ignorescripts； 记录 package manage
工具结果、日志、文件片段进入模型上下文前，应经过 secret scanning。至少检查： API key； OAuth token； 私钥； .env； cloud credential； 数据库连接串； 内部域名和个人信息。 发现 secret 后，不要把原文注入模型。可以替换成 REDACT
Shell 是 Agent Runtime 中最危险也最有用的工具。建议把命令分级： 等级 示例 策略 safe read pwd, ls, rg, cat, sed, wc 可自动执行，限制路径和输出 write touch, mv, cp, applypatch 需要 diff 或 previe
最基本的边界是 workspace。读写文件工具必须把路径解析到工作区内，禁止 ../ 逃逸，禁止跟随不可信符号链接访问外部敏感路径。 这段代码不是完整沙箱，但它表达了原则：所有文件能力都必须经过路径边界检查。不要把模型生成的路径直接交给文件系统。
