很多人学会 async/await 后，会误以为异步编程已经结束。对普通 Web API 来说，这通常够用；对 Agent Runtime 来说，不够。 Runtime 面对的不是一次请求一次响应，而是长时间过程： 模型流式吐出 token 和 tool call delta； shell 命令持续
先把四个词分清楚。 Agent 是面向目标的执行体。它可以根据上下文选择下一步，可能调用工具，也可能直接回复。Agent 的核心不是'像人'，而是'根据状态作决策'。 Workflow 是预先编排好的流程。它可以包含模型节点，但节点顺序通常由工程师写死或由状态机明确控制。很多可靠系统会把 Agent
长任务一定会中断。问题是：失败后怎么继续，而不是重来？ Agent Runtime 一旦进入真实工程任务，就会遇到长运行：改多个文件、跑多轮测试、安装依赖、查文档、等待用户确认。长运行必然遇到中断。浏览器刷新、进程崩溃、网络超时、模型失败、用户临时离开，都可能打断 run。如果没有 checkpoi
ReAct 论文提出把 reasoning 与 acting 交错起来：模型可以在最终答案之前产生行动，行动结果再反过来影响后续推理。这个思想后来进入了工具调用产品形态：模型输出结构化 tool call，应用执行工具，再把 tool result 或 observation 传回模型。 但要注意，
写 Agent Runtime 之前，先补一门不太体面的课：异步任务和进程控制。 Agent Runtime 表面上是在调用模型，实际上是在管理一串可能很慢、会失败、有副作用、需要取消的异步任务。模型请求会流式返回，shell 命令会持续输出，文件系统可能被修改，用户可能中途按下取消，工具可能超时，
目标：给 MCP 工具接入增加风险分类和审批层。 功能范围： MCP 工具 discovery 后先做 risk classification； 高风险工具需要用户确认； 非交互模式使用 policy 自动裁决； 所有审批写入 audit log； 工具列表变化时更新模型上下文。 适合证明： MCP
MCP 让工具接入变容易，也让工具信任问题变复杂。一个 Server 暴露的工具描述不应被 runtime 无条件信任。规范本身也提醒，工具描述等行为注解应被视为不可信，除非来自可信 Server。 因此，MCP 工具审批建议按 Server 信任级别分层： Server 类型 默认策略 官方可信、
一个实际做法是把 MCP 工具包装成本地统一 ToolDefinition： 注意命名空间。不要让两个 MCP Server 的 search 工具互相覆盖。也不要直接相信工具描述里的'safe''read only'等文字；风险等级应由本地策略、Server 信任级别、工具名称、输入 schema
用 MCP TypeScript SDK 写一个本地 MCP Server，提供两个工具： readprojectfile； searchprojecttext。 然后让 miniagent： 启动时发现 MCP 工具； 将 MCP 工具映射到本地 Tool Registry； 为 MCP 工具加风
为每次 Agent run 输出 trace JSON，记录： model； prompt tokens； completion tokens； tool name； args； duration； success/failure； retry count； cost estimate； appro
MCP 不是模型协议，也不是 Agent Runtime 的替代品。它解决'工具和上下文如何被发现、描述和调用'。权限、调度、上下文预算、trace、checkpoint 和 eval，仍然是 runtime 的活。 可以这样理解： MCP Server 把能力暴露出来，Runtime 决定这些能力
为 miniagent 增加 checkpoint： 每个 step 前保存 precheckpoint； 工具执行后保存 postcheckpoint； 文件写入记录 patch 和 base hash； audit log 纳入 checkpoint； crash 后可以从最新 checkpoi
一个 checkpoint 至少包含： session id、run id、step id； message history 或其可重建引用； 当前计划和 stop condition 状态； tool call 计划、执行结果、是否有副作用； 审批记录； 文件系统变更摘要； token/cost/
golden task 是一组有代表性的任务。对 coding agent 来说，可以分为： 文件阅读任务； 代码搜索任务； 单文件编辑任务； 多文件编辑任务； 测试修复任务； 权限拒绝任务； 工具失败恢复任务； 上下文压缩任务； checkpoint/resume 任务。 每个 task 至少包含
Agent 出错后，最怕只剩一句'模型没做好'。这一章讲怎么查清楚。 没有 trace 的 Agent Runtime，就像没有采访记录的新闻调查。出错后只能凭印象复盘：模型好像看过文件，好像调用过工具，好像测试失败了，好像用户批准过。工程系统不能靠'好像'。 OpenTelemetry 把 tra
幂等性是恢复执行的核心词。一个工具如果重复执行不会造成额外副作用，就更容易恢复。例如读文件幂等，搜索幂等，纯计算幂等。写文件如果基于相同 base hash 应用同一个 patch，也可以设计成近似幂等。发邮件、支付、删除远程资源通常不幂等。 工具定义中应声明： 这会直接影响 resume 策略。
工具一旦进入 trace 和 eval，就不能随意改语义。比如 readfile 原来默认返回全文，后来默认只返回前 200 行；这会影响模型行为，也会影响 replay 结果。 版本演进的策略： 工具名稳定时，小改动写入 version 和 changelog； 输入 schema 增加可选字段通
入口包括 CLI 入口、IDE extension 激活入口、Web server 入口、worker 入口。入口读法： 找 package.json scripts 和 bin； 找 extension manifest； 找 server bootstrap； 找主 command handle
Agent 可以动态接入和移除工具；工具 schema 改变不会把 Agent 弄崩；MCP 工具仍然经过本地权限审批；模型供应商替换不影响 runtime 主循环。完成这一章，你的 miniagent 已经具备生态接入能力。
实现 Tool Permission Matrix： 对文件路径做 workspace whitelist； 对 shell 命令做风险分类； 对 destructive 操作默认拒绝； 对 write/network/install 操作生成 preview 并请求确认； 所有审批写入 audit
