Agent Mentor Learn

术语表

74 个术语，来自《状态管理与持久化：让长任务经得起中断》。正文首次出现时可悬停查看释义。

术语释义来源
记忆指喂给模型看的上下文内容，用来回答「模型看见了什么」这个问题；本课以 NOTES.md 为例，记忆可能已经落盘，也可能还停留在这一轮响应文字里、尚未落盘。How we built our multi-agent research system — Anthropic Engineering
执行状态指 harness 进程自己攥着的运行现场，例如 messages 数组、轮次与用量计数器、还没落账的工具调用，默认只活在进程内存里，不专门落盘就会随进程一起被回收。How we built our multi-agent research system — Anthropic Engineering
messages 数组harness 内存里保存的完整对话历史，是模型对之前发生过什么的全部认知来源，也是检查点里最大、最不能省略的一块。How we built our multi-agent research system — Anthropic Engineering
turns记录当前已经跑过多少轮的计数器，恢复时需要原样接续，用来判断是否触发最大轮次这类停止条件。How we built our multi-agent research system — Anthropic Engineering
tokensUsed累计消耗的 token 用量计数器，恢复时需要从检查点接续，供后续的上下文压缩阈值判断使用。How we built our multi-agent research system — Anthropic Engineering
pendingToolUse检查点里专门标记「模型已经点名要用的工具、结果还没落账」这种半吊子状态的字段，值是 null 或形如 {id, name, input} 的记录。How we built our multi-agent research system — Anthropic Engineering
NOTES.md本系列课程里用来存放任务进展摘要的记忆载体，写在磁盘上，进程崩溃不受影响，重启后还能被读回来塞进 prompt。How we built our multi-agent research system — Anthropic Engineering
悬空的工具调用指模型已经点名要用某个工具、但结果还没有塞回 messages 时进程崩溃，导致这次调用在检查点里没有留下配对结果的状态。How we built our multi-agent research system — Anthropic Engineering
彩虹部署一种把流量从旧版本逐步切到新版本的部署方式，用来避免打断正在运行的 Agent，因为部署时 Agent 可能正处在流程的任意一步。How we built our multi-agent research system — Anthropic Engineering
stop_reason驱动 harness 循环的关键信号，循环靠判断 stop_reason 是否等于 tool_use 来决定要不要继续执行工具、发起下一轮请求。How we built our multi-agent research system — Anthropic Engineering
runAgent本系列课程里驱动 harness 主循环的函数名，内部维护 messages、turns、tokensUsed 等状态，并根据 stop_reason 决定是否继续循环。How we built our multi-agent research system — Anthropic Engineering
磁盘产出任务运行过程中生成、并已经写到磁盘上的成果文件，例如 report.md，进程崩溃不影响它，和执行状态、记忆是三个不同的分类。How we built our multi-agent research system — Anthropic Engineering
harness本课程里反复出现的说法，指包裹在模型调用之外、负责维持循环运行与执行状态的宿主程序，检查点、效果台账、reconcile 这些机制都装在它里面。The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026)
检查点把执行现场——messages、turns、tokensUsed、悬空的工具调用——序列化写到磁盘上、让进程重启后还能读到的动作与产物，是配合模型适应力使用的一类确定性护栏。How we built our multi-agent research system — Anthropic Engineering
checkpoint.json本课程约定的检查点文件名，里面装着 version、task、turns、tokensUsed、messages、pendingToolUse 六个字段，构成一份可被恢复的执行现场快照。How we built our multi-agent research system — Anthropic Engineering
versioncheckpoint.json 里的协议版本号字段，用来让恢复逻辑先确认自己认不认识这份文件的格式，版本不对就该拒绝装载，而不是硬着头皮解析。How we built our multi-agent research system — Anthropic Engineering
taskcheckpoint.json 里记录原始用户任务文字的字段，让重启后的宿主代码知道这份现场对应哪个任务，便于向用户报告恢复进度。How we built our multi-agent research system — Anthropic Engineering
saveCheckpoint把当前 state 对象写入磁盘的函数，正确实现要求先写临时文件、再用 fs.renameSync 原子改名，而不是直接覆盖写正式文件。How we built our multi-agent research system — Anthropic Engineering
存档点 A一轮循环里的第一个落盘时机，发生在模型响应到达之后、工具执行之前，此时把这次的 tool_use 块记进 pendingToolUse 再落盘。How we built our multi-agent research system — Anthropic Engineering
存档点 B一轮循环里的第二个落盘时机，发生在工具结果全部追加进 messages 之后，此时把 pendingToolUse 置回 null 再落盘一次。How we built our multi-agent research system — Anthropic Engineering
临时文件原子写入检查点时先写入的中间文件（如 checkpoint.json.tmp），写完整之后再通过改名替换成正式文件，避免直接覆盖写导致文件写坏。How we built our multi-agent research system — Anthropic Engineering
fs.renameSync在同一文件系统上执行的原子改名操作，操作系统保证目录项要么完整指向新文件、要么保持指向旧文件，不存在写了一半的中间状态。How we built our multi-agent research system — Anthropic Engineering
覆盖写直接用 fs.writeFileSync 覆盖同一份检查点文件的写法，写入过程不是原子操作，进程被打断会留下一份既不是旧版本也不是新版本的截断内容。How we built our multi-agent research system — Anthropic Engineering
/rewindClaude Code 里用来回到某条历史消息的命令，即便退出后又恢复了会话，依然可以继续使用，因为检查点是跟着会话一起保存的。Checkpointing — Claude Code Docs
Claude Code本课程用作产品级对照的真实工具，它的检查点在每条用户消息之前自动捕获代码状态，粒度按「用户说了一句话」切分，和本课程为无人值守长任务设计的检查点协议不是同一套。Checkpointing — Claude Code Docs
断点恢复进程重启后，读取检查点、重建执行现场，让循环从崩溃前的位置接着往前走，而不是从第 1 轮重新开始的整套流程。How we built our multi-agent research system — Anthropic Engineering
loadCheckpoint读取并解析检查点文件的函数，需要校验 version 字段，版本不匹配就直接抛错拒绝装载，而不是尝试用旧代码解析新格式或反之。How we built our multi-agent research system — Anthropic Engineering
reconcile处理悬空调用的对账函数，根据 pendingToolUse 指向的工具是否只读、以及能否确认其执行状态，决定直接重跑还是补一条 is_error 的 tool_result。Handle tool calls — Claude API
READ_ONLY_TOOLSreconcile 用来判断一个工具是不是只读的集合，例如 read_file、grep、list_dir、web_search，命中集合的工具可以在恢复时直接安全重跑。Handle tool calls — Claude API
只读工具副作用为零的工具，比如读文件、检索，不管调用一次还是多次，外部世界都不会因此多出或改变什么，恢复时可以直接重跑取真实结果。Handle tool calls — Claude API
高影响工具发邮件、写库、创建工单这类会改动外部世界的工具，恢复时不能无条件重跑，必须先确认这次调用是否已经真的执行过。Handle tool calls — Claude API
is_errortool_result 内容块里的可选字段，设为 true 表示这次工具执行出了状况，让模型知道并自己判断如何应对，而不是让恢复流程假装什么都没发生。Handle tool calls — Claude API
tool_result回传给模型的工具执行结果内容块，协议要求每一个 tool_use 都必须有配对的 tool_result，通过 tool_use_id 认领，集中放在下一条 user 消息里。Handle tool calls — Claude API
tool_use模型响应里点名要调用某个工具的内容块，包含 id、name、input 等字段，恢复时如果它没有配对的 tool_result 就构成悬空调用。Handle tool calls — Claude API
MAX_TURNS循环的最大轮次上限，是一种停止条件，恢复后 turns 必须原样接续，才能让这道阀继续正确起作用，不会被反复崩溃恢复绕开。Building Effective AI Agents — Anthropic Engineering
CHECKPOINT_VERSION代码里约定的检查点协议版本常量，loadCheckpoint 用它和文件里的 version 字段比对，不一致就抛错拒绝装载。How we built our multi-agent research system — Anthropic Engineering
幂等一个操作执行一次和执行多次，最终效果相同，就是幂等的；判断标准是效果，也就是对外部世界留下的最终状态，而不是每次调用返回值是否完全一样。How we built our multi-agent research system — Anthropic Engineering
效果台账把哪些副作用已经真实发生单独落盘的记录，以 tool_use_id 为键，让恢复时能从查不清楚升级成查得清楚。How we built our multi-agent research system — Anthropic Engineering
effects.json效果台账的落盘文件，以 tool_use_id 为键记录工具名、结果、发生时间等信息，写入时机要早于对应轮次的存档点 B。How we built our multi-agent research system — Anthropic Engineering
tool_use_id模型每次点名工具时自带的唯一标识符，恢复重放时不会变，天然可以当成幂等键，让台账把同一次调用和它自己认成一件事。Handle tool calls — Claude API
至少一次恢复重放天生带有的执行语义，进程可能在工具真的执行成功之后、结果还没来得及落账之前崩掉，单看检查点分不清这次调用到底跑没跑。How we built our multi-agent research system — Anthropic Engineering
loadEffects读取效果台账文件的函数，遇到文件不存在或解析失败时返回空对象，把它当成空台账处理，不阻塞整个恢复流程。How we built our multi-agent research system — Anthropic Engineering
saveEffects把效果台账写回磁盘的函数，采用先写临时文件再原子改名的方式，且必须在工具执行成功、拿到真实结果之后才调用，不能提前写。How we built our multi-agent research system — Anthropic Engineering
HIGH_IMPACT标记高影响工具的集合，例如 send_email、create_ticket、delete_file，在真正执行之前要先经过审批阀确认。How we built our multi-agent research system — Anthropic Engineering
审批阀高影响工具在真正执行之前设置的确认环节，负责回答「这件事该不该做」，和效果台账回答的「这件事做没做过」是两个不同的问题。How we built our multi-agent research system — Anthropic Engineering
ensure_ticket把「创建」改造成「确保存在」的工具设计范例，按标题查重，已存在就直接返回，不存在才新建，终态不随调用次数变化，因此天然幂等。How we built our multi-agent research system — Anthropic Engineering
追加式的写入效果是累加的写入方式，例如往数组末尾追加一行、往日志文件末尾加一条记录，每调用一次外部世界就真的多出一份东西，通常不幂等。How we built our multi-agent research system — Anthropic Engineering
覆盖式的写入效果是覆盖的写入方式，例如把某一行设成固定值、整体覆盖式的 write_file，调用一次和调用十次终态相同，通常天然幂等。How we built our multi-agent research system — Anthropic Engineering
runToolUses执行一轮里所有工具调用的函数，接入效果台账与审批阀之后，顺序变成先查幂等闸、再走审批阀、最后才真正执行工具并落账。How we built our multi-agent research system — Anthropic Engineering
回退任务没有崩溃、但走歪了的时候，把决策现场拨回还没走歪的那一轮重新开始；拨回的是决策现场，不是外部世界已经发生的动作。Checkpointing — Claude Code Docs
分叉从同一现场复制出两条独立时间轴分别去跑，用于不确定哪条路线更好、需要各跑一遍再比较结果的场景。Checkpointing — Claude Code Docs
rewindTo从按轮次留存的检查点序列里，取出指定轮次现场的函数，默认取该轮里最后落盘的存档点。Checkpointing — Claude Code Docs
forkFrom从某一轮的检查点现场复制出一条独立时间轴的函数，新时间轴带上自己的检查点序列和一份空白的效果台账，与主线互不干扰。Checkpointing — Claude Code Docs
turn-014-A.json按轮次留存检查点序列时的命名范例，文件名里带上轮次号与存档点字母，让恢复和回退都能精确定位到某一轮的某个存档点。Checkpointing — Claude Code Docs
pickLatestPoint在按轮次留存的检查点序列里，找出某一轮里最后落盘的存档点的函数，依据 A、B 字典序排列后取最后一个来判断。Checkpointing — Claude Code Docs
/branchClaude Code 提供的分叉命令，在保留原会话完整不动的前提下，另起一条时间轴去尝试别的路子。Checkpointing — Claude Code Docs
--fork-sessionclaude --continue --fork-session 命令里的分叉参数，和 /branch 一样用于另起一条独立时间轴而不影响原会话。Checkpointing — Claude Code Docs
决策现场检查点真正拨回的对象，即 messages、turns、pendingToolUse 这些自己定义进快照的状态字段，不同于外部世界已经落地的真实动作。Checkpointing — Claude Code Docs
干跑模式分叉期间为了避免两条时间轴各自真实触发同一个高影响工具、造成双份副作用，而临时切换成不真正执行外部动作的模式。How we built our multi-agent research system — Anthropic Engineering
检查点序列按轮次留存下来的一组检查点文件，而不是覆盖式地只保留最新一份，是支持回退与分叉的前提；分叉出来的时间轴各自带着自己独立的一份。Checkpointing — Claude Code Docs
Git管代码本身永久、可协作历史的版本控制系统，和检查点管的分钟级会话现场、效果台账管的外部副作用记录，三者各管一段、互不替代。Checkpointing — Claude Code Docs
CRASH_AFTER用来控制模拟崩溃发生时机的环境变量，例如 CRASH_AFTER=after-effect-write:3 表示在第 3 次工具执行结果落账之后立刻触发模拟崩溃。How we built our multi-agent research system — Anthropic Engineering
SimulatedCrash用于模拟进程被杀死的专门异常类型，main() 只在最外层捕获这一种异常，打印日志并用退出码 137 退出，让演示读起来像一次真实的进程被杀。How we built our multi-agent research system — Anthropic Engineering
crashPoint受环境变量控制的模拟崩溃触发函数，在每完成一次台账落盘时把当前是第几次落盘拼成标签，和 CRASH_AFTER 比对，一致就抛出 SimulatedCrash。How we built our multi-agent research system — Anthropic Engineering
--resume命令行入口用来判断这次启动是要从检查点恢复、还是从头清空开始的标志位，带上它就走 loadCheckpoint 和 reconcile 的恢复路径。How we built our multi-agent research system — Anthropic Engineering
响应队列验证桥段里用来替代真实模型客户端的桩，按固定顺序吐出预先写好的响应，让任务在哪几轮调用哪个工具、模型何时收尾都成为可以断言的常量。How we built our multi-agent research system — Anthropic Engineering
makeStubClient根据传入的响应队列构造桩模型客户端的工厂函数，用于在验证桥段里替代真实的 client.messages.create 调用。How we built our multi-agent research system — Anthropic Engineering
main()程序入口函数，只做一件判断，即命令行有没有带 --resume，据此决定是走恢复路径还是清理旧文件从头开始，并统一捕获 SimulatedCrash 打印退出。How we built our multi-agent research system — Anthropic Engineering
三分流reconcile 处理悬空调用的三条分支：台账命中直接复用、台账未命中且只读就直接重跑、台账未命中且有副作用就补 is_error 交还模型判断。Handle tool calls — Claude API
先执行、后记录效果台账写入的纪律，必须先拿到工具执行的真实结果，才能把这条记录写进台账，顺序颠倒会把「还没跑」误记成「已完成」。How we built our multi-agent research system — Anthropic Engineering
137约定俗成用来表示进程被 SIGKILL 杀死的退出码，验证桥段里用它让模拟崩溃的演示读起来像一次真实的进程被杀，而不是一段难看的堆栈。How we built our multi-agent research system — Anthropic Engineering
半截的检查点指检查点文件在写入过程中被中断、导致 JSON.parse 失败的损坏状态；正确做法是把错误明确抛出来，提示删除重开，而不是悄悄猜着补全。How we built our multi-agent research system — Anthropic Engineering
验证桥段用固定响应队列和受控崩溃点搭建起来的测试方法，把模型会说什么、进程会死在哪这些原本不确定的东西钉成常量，让恢复行为可以被逐条断言。How we built our multi-agent research system — Anthropic Engineering
分寸只在复杂度确实能明显改善结果时才考虑往系统里添加机制的原则，检查点、效果台账、回退分叉这些机制都不是默认多多益善，要按任务规模取舍。Building Effective AI Agents — Anthropic Engineering