项目 重点 Cline TS Agent Runtime、IDE/CLI 产品形态、工具审批、MCP Continue IDE 集成、上下文 provider、模型配置 aider repo map、git diff、命令行结对编程体验 OpenHands sandbox、任务自动化、agent 平
你应该能解释上下文不足时的降级顺序；能说明 repo map 与直接读文件的关系；能通过 debug report 解释模型为什么知道或不知道某个事实。做到这里，Agent 才有长任务的记忆力。
工具一旦进入 trace 和 eval，就不能随意改语义。比如 readfile 原来默认返回全文，后来默认只返回前 200 行；这会影响模型行为，也会影响 replay 结果。 版本演进的策略： 工具名稳定时，小改动写入 version 和 changelog； 输入 schema 增加可选字段通
实现一个 Context Builder： 用户当前消息固定保留； 最近 6 轮完整保留； 旧历史压缩为 summary； 大文件只保留摘要和关键片段； 工具结果按重要度截断； 输出 context debug report。 准备一份 200K token 的模拟历史，压缩进 32K / 64K
建议降级顺序： 1. 删除已确认无关的工具日志； 2. 压缩旧历史； 3. 长工具结果改摘要； 4. 大文件改为结构摘要 + 关键片段； 5. repo map 降级为目录树 + 入口文件； 6. 最后才缩短当前用户意图周边内容。 安全策略、用户明确要求、当前目标、最近失败原因，不应轻易被挤掉。 上
读完本章，你应该能清楚解释 Agent、Workflow、Tool、Runtime 的边界；能说出 step、turn、run、trace、session、checkpoint 的区别；能解释一个 Agent 为什么会卡死、乱调工具、爆 token；也能看懂本书后续所有章节围绕的是同一个运行闭环，而
选三个项目：Cline、Codex CLI、aider。分别画出一次用户请求如何走到工具调用的链路图。你不需要读完整个仓库，但要回答： 1. 用户输入进入哪里？ 2. 模型调用在哪里发生？ 3. 工具在哪里注册？ 4. 工具调用结果如何回到模型？ 5. 权限审批或确认在哪里发生？ 6. 日志或 tr
章节 代码主题 第 1 章 Agent Loop 伪代码 第 2 章 timeout、AbortSignal、子进程执行器 第 3 章 ModelResponse、ToolCall、最小工具 第 4 章 ToolDefinition、风险等级、审批请求 第 5 章 Context Builder 输
无论选哪个方向，最终交付都应包括： 设计文档； 最小实现； 单元测试； 至少 5 个 eval 或 fixture； trace/log 示例； README 使用说明； 失败场景说明； 安全和隐私影响说明； 后续工作清单。 PR 描述建议结构： 一个好 PR 不只是'代码能跑'，还要让维护者相信你
为 miniagent 增加 checkpoint： 每个 step 前保存 precheckpoint； 工具执行后保存 postcheckpoint； 文件写入记录 patch 和 base hash； audit log 纳入 checkpoint； crash 后可以从最新 checkpoi
先把四个词分清楚。 Agent 是面向目标的执行体。它可以根据上下文选择下一步，可能调用工具，也可能直接回复。Agent 的核心不是'像人'，而是'根据状态作决策'。 Workflow 是预先编排好的流程。它可以包含模型节点，但节点顺序通常由工程师写死或由状态机明确控制。很多可靠系统会把 Agent
本阶段建议只实现三个工具。 listfiles：列目录。只读，但要限制在 workspace 内。 readfile：读文件。只读，但要限制大小和行数。 shellreadonly：执行只读 shell 命令。只允许白名单命令，例如 pwd、ls、find、rg、cat、sed、wc。不要在入门阶段
工具 schema 有两个读者。模型用它决定怎么调用工具，runtime 用它判断调用是否合法。 以 readfile 为例： 不要把 schema 发给模型后就放心。模型返回的参数必须再次校验。校验失败不该让程序崩溃，应当变成一条 observation： 这很关键。工具参数错了，并不总是任务失败
目标：实现可恢复执行。 功能范围： 每轮工具执行前创建 checkpoint； 文件修改保存 patch； 支持恢复文件状态； 支持恢复 session 状态； 进程崩溃后继续 run； 恢复后不重复执行高风险工具。 适合证明： 状态管理； 可恢复执行； 可靠性工程； coding agent 长任
第一类失败是非法参数。模型传了不存在的路径、错误类型、缺字段。处理方式是 schema 校验 + observation 反馈。 第二类失败是工具不存在。模型调用了没注册的工具。处理方式是返回 UNKNOWNTOOL，并把可用工具列表简短提示给模型。 第三类失败是输出过大。处理方式是截断、摘要、引用
幂等性是恢复执行的核心词。一个工具如果重复执行不会造成额外副作用，就更容易恢复。例如读文件幂等，搜索幂等，纯计算幂等。写文件如果基于相同 base hash 应用同一个 patch，也可以设计成近似幂等。发邮件、支付、删除远程资源通常不幂等。 工具定义中应声明： 这会直接影响 resume 策略。
本书统一使用以下术语。 turn 是一次用户与系统的交互轮次。用户提出一个任务，是一个 turn 的开始。 step 是 runtime 在一个 turn 内的一次模型决策或工具执行推进。一次 turn 可以有很多 step。 run 是一次完整执行，从收到用户请求到最终回答、失败或取消。长任务中，
第八章 Checkpoint、Resume、Rollback：8.3 gitbased checkpoint 另一种做法是借助 git。每个 step 或关键写入点创建临时 commit、stash、worktree 或 patch 文件。 gitbased 的优点是成熟、可审计、适合代码项目。缺点
工具失败不应只有 error: string。至少分为： 类型 例子 Runtime 行为 INVALIDARGUMENTS 参数缺字段、类型错 反馈模型重新调用 NOTFOUND 文件不存在 提示可选路径或要求搜索 PERMISSIONDENIED 用户拒绝或策略拒绝 停止或让模型寻找低风险方案
实现一个可取消的命令执行器： 支持 cwd； 支持 stdout/stderr 流式事件； 支持 timeout； 支持 AbortSignal； 支持最大输出限制； 返回 exit code、signal、duration； 中断后清理子进程。 用三个命令测试它：
