状态包括聊天历史、任务状态、工具执行记录、文件变更、UI 状态、用户配置。读时问： 状态存在内存、文件、数据库，还是 git？ 崩溃后能恢复到哪里？ 工具执行是否有 ledger？ 用户审批是否持久化？ 文件变更是否可回滚？ 长任务是否可以暂停和继续？ 这部分最能区分 demo 和系统。
一次线上失败，如果不能转化为 eval，它就会再次发生。建议流程： 1. 从 trace 中提取用户目标、关键上下文、工具调用和失败结果； 2. 去除 secret 和用户隐私； 3. 固化 workspace fixture； 4. 写 expected behavior； 5. 加入 CI； 6
run 生命周期通常包括： 初始化 session； 构建上下文； 调用模型； 解析响应； 执行工具； 写状态； 输出 UI event； 进入下一步或停止。 你要找的不是某个函数名，而是状态怎样流动。很多项目不会把它叫 runAgent，可能叫 task、controller、orchestrat
恢复流程要保守： 1. 找到最新完整 checkpoint； 2. 校验 workspace 状态； 3. 恢复 message history 和 run state； 4. 检查最后一个 tool call 是否已完成； 5. 对不可重复工具禁止自动重放； 6. 给模型注入恢复说明； 7. 从下
模型 span： provider； model； prompt tokens； completion tokens； latency； finish reason； tool call 数量； 是否触发上下文降级； response id 或 continuation metadata。 工具 s
Agent：根据目标和上下文选择下一步行动的执行体。 Agent Runtime：负责模型调用、工具调用、上下文、权限、状态、观测、恢复、评测和成本治理的运行系统。 Tool Calling：模型输出结构化工具调用，应用执行工具并把结果返回模型的接口能力。 Tool Registry：工具定义、sc
用 MCP TypeScript SDK 写一个本地 MCP Server，提供两个工具： readprojectfile； searchprojecttext。 然后让 miniagent： 启动时发现 MCP 工具； 将 MCP 工具映射到本地 Tool Registry； 为 MCP 工具加风
上下文构建往往是 coding agent 的核心竞争力。读时关注： system/developer 指令； 用户消息和历史保留； 文件读取策略； repo map； 最近修改； terminal output； diagnostics； selection/range； embedding 或检
读开源 Agent 项目，别一上来就钻进细节。本章给一套追主线的方法。 读开源 Agent 项目，最怕两种读法。一种是从 README 兴奋到插件列表，最后只记住产品功能；另一种是一头扎进代码细节，三天后迷失在 UI、配置和历史兼容里。Runtime 工程师读源码，要带着问题读，尤其要追执行链路。
先把地基打准：Agent Runtime 到底比普通 LLM App 多负责了什么？ 很多团队第一次做 Agent，架构图都很相似：用户输入，调用模型，模型说要用工具，程序执行工具，再把结果塞回模型。这个图没有错，但它像把报社写成'记者采访，编辑发稿'。编辑部还要选题、核实、排版、审稿、撤稿、归档、
一个最小 Agent Loop 可以写成这样： 这段伪代码故意没有把逻辑藏进框架名里。runtime 的关键责任全在其中：构建上下文、调用模型、校验工具、审批权限、执行工具、记录观察、判断停止。如果其中任何一步被省略，demo 仍然可能成功，生产系统却会变脆。 图 12：Agent Runtime
能力越大，边界越要清楚。本章谈权限和安全。 Agent 的能力来自工具，风险也来自工具。一个不会调用工具的模型，最多说错话；一个能执行命令、写文件、联网、访问数据库的 Agent，可能造成真实损失。Runtime 的安全目标不是把 Agent 绑住，而是让它在明确边界内做事；越过边界时，停下来请人确
为 miniagent 增加四个工具： editfile：写文件，但执行前必须生成 diff preview； applypatch：应用 patch，只允许 workspace 内路径； runcommand：执行命令，先做风险分类； searchcode：基于 rg 的只读搜索。 给每个工具加
实现 Tool Permission Matrix： 对文件路径做 workspace whitelist； 对 shell 命令做风险分类； 对 destructive 操作默认拒绝； 对 write/network/install 操作生成 preview 并请求确认； 所有审批写入 audit
这一章开始给工具'上户口'：它们不能只是函数列表。 在 demo 里，工具是几个函数。在生产 Agent Runtime 里，工具是一套能力治理系统。它既要让模型知道'能做什么'，也要让 runtime 知道'什么能做、什么不能做、怎么做、失败了算什么、谁批准过、结果能不能进上下文'。
入口包括 CLI 入口、IDE extension 激活入口、Web server 入口、worker 入口。入口读法： 找 package.json scripts 和 bin； 找 extension manifest； 找 server bootstrap； 找主 command handle
你不只是会 await，而是能解释异步任务如何取消、如何防泄漏、如何处理流式输出、如何把长日志变成模型可用的观察结果。做到这里，才有资格写第三章的最小 Agent Loop。
长对话中，不能无限保留全部消息。常用策略是： 最近 N 轮完整保留； 更早历史压缩成 session summary； 用户显式约束永久置顶； 已完成任务结果写入 memory； 失败原因和决策记录保留为 run notes。 滚动摘要有一个风险：摘要会丢细节，甚至引入轻微偏差。因此摘要应该标注来源
token budget 不只是技术限制，也是产品预算。一次 run 里，token 影响延迟、成本和可靠性。越长的上下文越不一定越好，因为模型注意力会被稀释，缓存命中也可能下降。 可以把上下文分为六层： 1. 系统与开发者指令； 2. 用户当前意图； 3. 近期完整对话； 4. 当前任务状态和计划
你应该能解释为什么 Agent 不能直接执行任意 shell；能为 MCP 工具设计权限审批策略；能区分 schema 校验、权限策略和用户确认；能保证恢复执行后不会重复越权。
