1. 从京东二面那道题说起Agent 断点续跑到底难在哪先还原一下场景。面试官问的是一套 Agent 批量处理 200 份文档跑到第 137 份时进程崩了你怎么处置很多人的第一反应是「重启从头再跑一遍」。这个回答在 5 分钟以内的短任务里没毛病但放到长周期 Agent 上就是灾难——前 136 份文档消耗的模型调用时长、Token 开销全部白费而且重跑过程中还可能再次崩在同一个位置。Agent 断点续跑checkpoint resume要解决的核心问题是让一个长时间运行的任务具备「记忆能力」崩了之后能从最近一个成功完成的执行单元继续而不是从零开始。它和普通的 API 重试不是一回事。API 重试解决的是单次调用失败断点续跑解决的是整个任务链路的执行状态恢复。为什么长周期 Agent 格外脆弱我梳理下来有三个原因。第一上下文污染。Agent 跑了几十上百轮之后对话历史里堆满了过期的工具返回、重复的指令、无效的中间结果。模型越来越难判断「我现在到底做到哪一步了」输出质量断崖式下降。第二Token 成本膨胀。每一轮推理都要把累计的完整对话重新提交给模型轮次越多单次调用的输入 Token 越大成本呈线性甚至超线性增长。跑到第 137 份文档时单次请求可能已经背着几万 Token 的历史包袱。第三缺少恢复锚点。进程被 kill、网络抖动、模型接口抛异常这些在长任务里几乎必然发生。如果唯一的留存信息就是那份不断膨胀的对话上下文那它本身可能就是崩溃的诱因靠它恢复并不可靠。所以正确的思路不是「怎么让 Agent 不崩」而是「崩了之后怎么用一份干净、可靠的状态快照恢复」。这份快照要能回答三个问题任务目标是什么、哪些最小执行单元已经完成、工作空间的真实状态是什么。接下来我会以 Claude Code 这类工具链为例把状态持久化配置和中断重放验证一步步拆开你可以跟着复现一次完整的续跑流程。2. TaoToken 前置准备给 Agent 接上稳定的 API 底座断点续跑要落地前提是 Agent 的模型调用链路本身是可观测、可恢复的。如果 API 层频繁超时、报错信息含糊你连「崩在哪一步」都定位不了更别提续跑。所以第一步是把模型接入层搭稳。我这边用的是 TaoToken 作为模型调用入口它兼容 Anthropic 和 OpenAI 两套协议Claude Code、Cline、Codex 这类工具都能直接对接。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个不加 UTM 参数。你需要先拿到一个 API Key。进入控制台创建密钥https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建时建议按项目命名比如agent-resume-demo方便后面排查是哪个任务的调用出了问题。拿到 Key 之后先别急着配 Agent用一次最简单的对话请求验证链路通不通。打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 选一个模型发一条消息能正常返回就说明 Key 和网络都没问题。这一步看起来简单但它是后面所有断点续跑验证的基础。因为断点续跑的核心动作之一是「从中断点重新发起请求」如果 API 层本身不稳定你根本分不清是任务逻辑崩了还是网络崩了。我试过在 API 不稳定的情况下调试续跑逻辑结果排查了半天发现是请求超时白白浪费时间。对于要跑长任务的场景建议在 TaoToken 控制台里留意一下用量和调用记录。断点续跑的一个关键收益就是省 Token你得能看到「续跑后实际消耗了多少」才能验证这套机制有没有生效。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。如果你打算长期跑编码类 Agent 任务可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它更适合高频、长周期的调用场景配合断点续跑能把单位任务的成本压下来。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各协议的 Base URL 和参数说明配置前扫一眼能少踩坑。3. 可复制配置状态快照 Claude Code 接入三件套这一节是重点我会给出可以直接复制的配置片段。断点续跑的状态持久化我建议用一个 JSON 文件来存进度快照结构尽量简单别一上来就上数据库。先看状态快照文件agent_state.json{ task_id: doc-extract-2024, goal: 解析 200 份文档并抽取结构化字段写入数据库, total_units: 200, completed_units: [1, 2, 3, 136], current_unit: 137, last_success_index: 136, token_used: 48210, workspace: { output_dir: ./output, db_cursor: 136, git_commit: a1b2c3d }, updated_at: 2024-06-01T03:12:44Z }几个字段的用意completed_units记录已成功完成的最小单元last_success_index是恢复时的起点依据token_used用来核算续跑省了多少成本workspace里的db_cursor和git_commit是客观状态锚点恢复前要核对。关键原则断点必须在最小执行单元完全成功之后再写入。不要提前写否则会把「执行到一半报错」的步骤误标为已完成恢复时直接跳过留下脏数据。接下来是 Claude Code 的接入配置。Claude Code 通过环境变量读取 Base URL 和 Key三件套是 Base URL、API Key、Model ID缺一不可。在~/.claude/settings.json里配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Cline 或 Codex配置位置不同但三件套一致。Cline 在 VS Code 设置里填 Base URL 和 KeyModel ID 选对应模型Codex 则写在~/.codex/auth.json{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }注意auth.json里的字段名要和工具版本匹配不同版本可能用OPENAI_BASE_URL之类的键名配置前对照接入文档确认一下。再补一个断点写入的伪代码逻辑方便你嵌到自己的脚本里import json, os STATE_FILE agent_state.json def load_state(): if os.path.exists(STATE_FILE): with open(STATE_FILE) as f: return json.load(f) return {last_success_index: 0, completed_units: [], token_used: 0} def save_state(state): with open(STATE_FILE, w) as f: json.dump(state, f, ensure_asciiFalse, indent2) def process_documents(docs): state load_state() start state[last_success_index] for i in range(start, len(docs)): result extract(docs[i]) # 调用模型抽取 write_to_db(result) # 先落库 state[last_success_index] i 1 state[completed_units].append(i 1) state[token_used] result[usage][total_tokens] save_state(state) # 成功后再写断点这段逻辑的核心就是「先完成、再落盘」。write_to_db成功之后才更新last_success_index保证断点永远指向真正完成的最后一个单元。4. 验证请求与成功结果复现一次完整续跑配置写完得实际验证一遍。我按「跑到一半手动中断 → 重新启动 → 从断点续跑」这个流程走一遍你可以照着复现。第一步准备 10 份测试文档故意在第 5 份处理完之后手动 kill 进程。观察agent_state.json此时last_success_index应该是 5completed_units是[1,2,3,4,5]。第二步重新启动任务脚本。脚本读取状态文件发现last_success_index5于是从第 6 份开始处理而不是从第 1 份。第三步观察日志输出。正常的话你会看到类似[INFO] 加载断点状态已完成 5 个单元 [INFO] 从第 6 份文档继续处理 [INFO] 处理文档 6/10 ... 成功 [INFO] 处理文档 7/10 ... 成功 ... [INFO] 全部完成本次续跑消耗 Token: 12030第四步核对结果。检查数据库里 1 到 10 份文档的结构化数据是否齐全有没有重复写入或遗漏。再对比token_used字段续跑只消耗了后 5 份的 Token前 5 份没有重复计费。如果你用 Claude Code 跑的是编码类任务验证方式类似让 Agent 改一批文件中途 CtrlC 中断然后重新发起任务看它是否从上次改到一半的文件继续而不是把所有文件重改一遍。这里可以用 git status 核对工作区确认没有重复改动。一个容易忽略的点恢复之前先核对工作空间的客观状态。比如db_cursor是不是真的到了 136git_commit是不是和快照里一致。如果工作区被别的操作改过直接按快照恢复可能会出错。客观事实比模型「自述做到哪了」可靠得多。5. 常见报错排查401、local proxy failed、reading choices断点续跑调试过程中报错基本集中在 API 接入层和状态读取层。我把几个高频错误和对应排查方法列出来。401 UnauthorizedKey 无效或没被正确读取。先确认ANTHROPIC_API_KEY或auth.json里的 Key 没有多余空格再去 TaoToken 控制台看这个 Key 是否被禁用或额度耗尽。如果是 Claude Code检查settings.json的 JSON 格式有没有写错比如少了逗号导致整个 env 块没生效。local proxy failed / connection refused通常是 Base URL 写错或本地网络问题。确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api不要多加路径或斜杠。如果工具本身带代理设置检查有没有冲突。Error reading choices / 返回结构解析失败这类错误多出现在用 OpenAI 协议对接 Claude 模型时返回体字段和预期不符。核对 Model ID 是否和协议匹配Claude 系列走 Anthropic 协议别混用。接入文档里有各模型的协议对照表。OAuth 相关报错Claude Code 某些版本会走 OAuth 流程如果你用的是 API Key 模式需要在配置里显式关闭 OAuth 或指定ANTHROPIC_API_KEY。报错信息里出现oauth字样时优先检查是不是工具在尝试用登录态而不是 Key。断点文件读取失败 / JSON 解析错误状态文件写坏了。常见原因是进程在写文件时被 kill导致 JSON 不完整。解决办法是写入时先写临时文件再原子替换def save_state(state): tmp STATE_FILE .tmp with open(tmp, w) as f: json.dump(state, f, ensure_asciiFalse, indent2) os.replace(tmp, STATE_FILE) # 原子替换避免半截文件排查顺序建议先确认 API 层能通用模型对话页面发一条消息再确认配置三件套齐全Base URL Key Model ID最后才查状态文件逻辑。很多「续跑不生效」的问题根子其实在 API 没接通任务根本没跑起来。6. 把断点续跑用起来从验证到长期编码验证通过之后这套机制就可以往真实场景迁移了。如果你跑的是长期编码或 Agent 类任务配合 Coding Plan 能把成本控制得更细https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。断点续跑省的是「重复执行的 Token」Coding Plan 优化的是「单位调用的成本」两者叠加效果更明显。再回到开头那道面试题。面试官真正想听的不是「我会重启」而是「我知道怎么让任务具备记忆、怎么在崩溃后从断点恢复、怎么核算省下的成本」。这三件事对应到工程上就是状态快照设计、断点写入时机、恢复前的客观状态核对。最后留一个实用习惯每次任务启动时先打印一行「本次从第 N 个单元开始」让续跑行为在日志里可见。这样下次再崩你打开终端看到的第一行就知道它有没有正确接上而不是面对一个空白会话发呆。
的核心技术与实战)
