上一篇的结尾我写了一句话:InMemoryTaskStore 重启即丢,任务原语只解决「怎么问」,不解决「问的东西还在不在」。
那自然的下一步就是:自己写一个落盘的 store。
我花了一个下午写完了,六个方法、一个任务一个 JSON 文件、原子写。重启之后 tasks/get 照样能返回任务,状态是 working。我以为成了。
然后我发现这个任务永远不会结束。
不是慢,是永远不会。没有报错,没有超时,tasks/get 每隔一秒老老实实返回一次 working,状态消息停在「正在读取笔记」,一直到 TTL 把记录清掉为止。
状态存下来了,执行没存下来。 这两件事在代码里只差几行,但在语义上差了一整个分布式任务系统。
先看这个 store 长什么样
TaskStore 是个很普通的接口,六个方法:
scss
createTask(taskParams, requestId, request, sessionId?) // 建任务
getTask(taskId, sessionId?) // 查状态
updateTaskStatus(taskId, status, statusMessage?) // 改状态
storeTaskResult(taskId, status, result) // 存结果
getTaskResult(taskId, sessionId?) // 取结果
listTasks(cursor?, sessionId?) // 列表
实现很简单:一个任务一个文件,文件名就是 taskId。
typescript
private write(taskId: string, rec: Record_) {
// 先写临时文件再 rename,避免重启时读到半个 JSON
const tmp = `${this.file(taskId)}.tmp`;
fs.writeFileSync(tmp, JSON.stringify(rec, null, 2));
fs.renameSync(tmp, this.file(taskId));
}
rename 在同一个文件系统上是原子的,这是落盘最省事也最可靠的一招。比起「打开文件、写入、关闭」,它多出来的一步恰好挡住了「写到一半被 kill」。
有一处不能省:建任务时得把原始请求一起存下来。
javascript
async createTask(taskParams, _requestId, request) {
const task = {
taskId: randomUUID().replace(/-/g, ""),
status: "working",
ttl: taskParams.ttl ?? null,
createdAt: new Date().toISOString(),
lastUpdatedAt: new Date().toISOString(),
pollInterval: taskParams.pollInterval ?? 1000,
};
// origin 存下原始请求,重启后才知道这个任务原本要干什么
this.write(task.taskId, { task, origin: request });
return task;
}
没有 origin,重启时你只知道有个任务在跑,但不知道它要跑什么。这个字段不在 Task 类型里,得自己在存储层加。
第一次重启:看起来一切正常
建一个 15 秒的任务,跑到第 3 秒强杀服务(SIGKILL,模拟发版或宕机),再用同样的数据目录重启。
重启后的第一件事是扫一遍遗留任务:
启动策略=zombie,发现 1 个遗留任务
保留原样:dcdaf478 仍是 working(没有任何东西会再推进它)
然后客户端来查:
rust
getTask -> working "正在读取笔记" (距重启 445ms)
getTask -> working "正在读取笔记" (距重启 2456ms)
getTask -> working "正在读取笔记" (距重启 4465ms)
...
getTask -> working "正在读取笔记" (距重启 20540ms)
十几秒过去了,状态一动不动。
原因很直白:推进任务的是 createTask 里那个 void runBackground(...)。那是一个跑在进程内存里的 async 函数,进程被 SIGKILL 的那一刻,它跟着一起没了。磁盘上的 JSON 只记录了「这个任务正在进行中」,没有任何东西会再把它推下去。
这就是僵尸任务:记录活着,执行死了。
更难受的是客户端那边。它看到的是持续的 working,只能一直轮询。我让它去取结果:
sql
tasks/result -> MCP error -32001: Request timed out
第一次跑到这里,它等了 61 秒才返回。所以「持久化 store」这个改动,把一个「重启后立刻报错」的场景,变成了「客户端安静地一直等」------比起上一篇那个 InMemory 版本,用户体验反而更差了。
三种重启策略
既然知道了问题在哪,重启时就有三种处理方式。我都跑了一遍。
| 策略 | 做法 | 客户端看到什么 | 实测 |
|---|---|---|---|
zombie |
什么都不做 | 永远 working,直到 TTL |
轮询 20 秒无变化 |
fail |
全部标成 failed |
重启后 0.4 秒内失败 | failed "已失败",距重启 444ms |
resume |
全部重新执行 | 从头再跑一遍,最终成功 | 距重启 16.5 秒 completed |
fail 的实现只要几行:
less
for (const { task } of store.scanWorking()) {
await store.storeTaskResult(task.taskId, "failed", {
content: [{ type: "text", text: "服务重启,任务已中断" }],
});
}
效果很干脆:客户端在重启后 444 毫秒就拿到了终态,不会傻等。
我认为这是大多数项目应该默认选的那一个。理由不是它更优雅,而是它的失败方式最诚实:任务确实没跑完,就告诉客户端没跑完,让上层决定要不要重试。重试的逻辑本来就在客户端(或者模型)那边,服务端不该替它假装还在努力。
resume 看起来最贴心,但它是三种里最危险的,下一节说。
resume 的代价:没有断点,只能从头跑
先看它能用:
rust
重新执行:8b4ed415 预计 15000ms(从头跑,没有断点)
getTask -> working "[续] 正在读取笔记" (距重启 445ms)
...
getTask -> completed "已完成" (距重启 16521ms)
15 秒的任务,重启后 16.5 秒完成。看起来没问题。
但注意那句「从头跑」。我把杀进程的时间点从第 3 秒挪到第 12 秒------也就是任务已经跑完 80%、摘要都快生成好了------再重启:
csharp
>>> 强杀服务(SIGKILL,模拟发版/宕机)
重新执行:0c841912 预计 15000ms(从头跑,没有断点)
getTask -> completed "已完成" (距重启 16524ms)
[server] 任务完成 0c841912 耗时=15014ms
前面那 12 秒白跑了,重启后又完整跑了 15 秒。
一个 15 秒的任务,累计消耗 27 秒计算量,其中 12 秒是纯浪费------相当于一次完整执行的 80%。如果这个任务里有一次 API 调用、一次数据库写入、一次发消息,那 27 秒里就有两次副作用。
所以 resume 有两个前提,缺一不可:
- 任务必须幂等 ,否则重跑就是重复写入。这一条上一篇讲过,
tasks/get的轮询和写操作的幂等是两件独立的事 - 任务最好可分片,每片做完就落一个检查点,重启后从最后一个检查点继续
第二条我们完全没有做。真实的做法是把任务切成 N 段,每段结束写一次进度:
javascript
// 每片做完,把进度也写进 store
await store.updateTaskStatus(taskId, "working", `已完成 ${done}/${total}`);
await store.saveCheckpoint(taskId, { done, cursor });
重启时读 checkpoint,从 cursor 继续。这样 12 秒的进度就还在,代价只是重跑最后一片。
这件事协议帮不了你。 MCP 的 Task 结构里只有 status 和 statusMessage,没有 progress、没有 cursor、没有 checkpoint。statusMessage 是个给人看的字符串,不是给你恢复现场用的。真想恢复,得在自己的 store 里加字段------这也意味着你的 store 实现已经不再是「通用 TaskStore」,而是绑定了具体业务。
这也是我为什么更推荐 fail:它不需要你承诺「任务可恢复」,而 resume 一旦做不彻底,就是在制造重复副作用。
客户端怎么识别僵尸
服务端能识别僵尸,因为它知道自己重启过。但客户端不知道------它只看到一个一直在 working 的任务。
有个信号能用:lastUpdatedAt 距今的时间在持续变大。
我把重启后的轮询结果连时间戳一起打出来:
ini
任务 9cb561cb createdAt 01:27:42.510Z lastUpdatedAt 01:27:42.510Z
轮询 + 37ms status=working lastUpdatedAt 距今 7s
轮询 + 3049ms status=working lastUpdatedAt 距今 10s
轮询 + 6059ms status=working lastUpdatedAt 距今 13s
轮询 + 9071ms status=working lastUpdatedAt 距今 16s
注意「距今」那一列:7、10、13、16,每秒长 3 秒,和我的轮询间隔完全同步。这说明这条记录在第一次轮询之前就没再被写过 ,lastUpdatedAt 停在原地。
对比一个健康的任务:每到一个阶段边界,服务端会写一次 updateTaskStatus,这个值就往前跳。所以在客户端只要算一个数:
ini
const t = await client.experimental.tasks.getTask(taskId);
const staleMs = Date.now() - Date.parse(t.lastUpdatedAt);
if (t.status === "working" && staleMs > STALE_THRESHOLD_MS) {
// 大概率是僵尸:记录还在,但没人推进它
}
这个阈值有个前提:得大于你任务里最长的一段「不上报」时间 。我的实现只在阶段边界上报,两个边界之间是 5 秒,那阈值设 30 秒就够。如果一个任务中间有 60 秒的 await,阈值就得往上抬,否则会误判成僵尸。
换句话说,这个检测手段能不能用,取决于你有没有把「上报」做成常态。statusMessage 这个东西上一篇我嫌它是个给人看的字符串,现在发现它还有个副作用:它被写入的频率,正好等于心跳的频率。
僵尸的最后归宿:TTL 到期,变成「查无此任务」
僵尸任务不会永远挂在那儿。createTask 时传的 TTL 一到,记录就被清掉。
我把 TTL 设成 8 秒,建一个 30 秒的任务,然后什么都不做:
rust
2 秒后 -> working "正在读取笔记"
10 秒后 -> {"error":{"code":-32602,"message":"Failed to retrieve task: Task not found"}}
于是同一个 -32602 Task not found,现在可能意味着三件完全不同的事:
- 这个 taskId 从来不存在(客户端抄错了)
- 服务重启过,记录丢了
- 任务跑太久,TTL 到期被清理了
客户端没法区分,只能一律当作「重来吧」。对排障的人来说,这三种情况要查的地方完全不同。
顺带一个坑:落盘的记录不会自己消失 。内存 store 重启就清空,磁盘上的文件不会。ttl: null 意味着永不清理,一年后你的目录里会有多少文件,取决于你的调用量。我的实现是在读取时懒清理:
kotlin
private expired(rec: Record_): boolean {
const { ttl, createdAt } = rec.task;
if (ttl == null) return false;
return this.now() > Date.parse(createdAt) + ttl;
}
读的时候顺手删。缺点是没人读的任务永远不删;如果在意,得配一个定时扫盘的任务。这件事在内存版本里完全不存在,属于「持久化引入的新工作量」。
我还写错了一个字段
fail 策略第一次跑出来是这样:
rust
getTask -> failed "正在读取笔记" (距重启 445ms)
状态是 failed,消息是「正在读取笔记」。原因是我在 storeTaskResult 里只改了 status,没动 statusMessage------上一篇吐槽过 SDK 有这个毛病,轮到我自己写 store,一模一样地踩了。
改法是终态时强制覆盖:
ini
rec.task = {
...rec.task,
status,
statusMessage: status === "completed" ? "已完成" : "已失败",
lastUpdatedAt: new Date().toISOString(),
};
改完:
rust
getTask -> failed "已失败" (距重启 444ms)
这条值得单独拎出来 :自定义 store 时,status 和 statusMessage 是两个字段,任何一处只改一个,都会产出自相矛盾的记录。SDK 不会替你兜,它只是把 store 里的东西原样转发给客户端。
那到底要不要持久化
我的结论是:看你的任务丢了之后,客户端能不能自己重来。
| 情况 | 建议 |
|---|---|
| 任务可重跑、无副作用(生成摘要、算统计) | fail + 客户端重试,最省事 |
| 任务有副作用但幂等(写库带幂等键) | fail + 重试,幂等键兜底 |
| 任务有副作用且不幂等(发消息、下单) | 必须做检查点,或者干脆别做成任务 |
| 任务超过几分钟、失败代价高 | 上检查点 + resume,但要接受额外复杂度 |
| 只是本地自己用 | 内存 store 就够,重启丢了重来一次 |
还有一个更根本的选择:把长任务拆成多个短任务 。一个 15 秒的任务,拆成三次 5 秒的 tools/call,每一步都是普通工具调用,客户端自己串起来。这样:
- 不需要任务原语
- 不需要持久化 store
- 中途失败重跑最后一步,前面的进度还在
- 模型每一步都能看到中间结果,还能改主意
代价是模型得多调几次工具,多花点 token。但如果你的任务本来就能切成阶段,这个代价比「实现一个带检查点的分布式任务存储」低太多了。上一篇我推荐用任务原语解决长任务,这一篇想补一句:先确认它真的不能拆。
总结
TaskStore只有六个方法,落盘实现不难:一个任务一个 JSON,写临时文件 + rename保证原子createTask必须把原始请求(origin)一起存下来,否则重启后不知道任务要干什么- 把状态持久化,得到的是「永远在 working」的僵尸任务,不是「任务活下来了」:推进任务的 async 函数跟着进程一起死了
- 三种重启策略里,
fail最诚实也最省事;resume看起来贴心,但没有检查点就是重跑,12 秒的进度会整个丢掉 - MCP 的
Task结构里没有progress、没有cursor、没有checkpoint,可恢复性得自己在 store 里加字段,加了就不再通用 - TTL 到期后僵尸会变成
-32602 Task not found,和「不存在」「重启丢了」共用同一个错误码,客户端无法区分 - 客户端侧唯一可靠的僵尸信号是
lastUpdatedAt是否停滞(实测每次轮询「距今」都线性增长),阈值要大于任务里最长的不上报间隔 - 落盘引入的新工作量:TTL 清理(内存版本里不存在这个问题)
- 自定义 store 时
status和statusMessage必须一起改,否则会出现failed+ 「正在读取笔记」这种记录
适用边界 :如果你的任务都能在几十秒内跑完、失败了重跑一次也无所谓,那这篇整篇都不用看------内存 store 加 fail 策略就够了,重启丢几个任务比维护一套检查点便宜得多。真正需要落盘的是两种情况:任务有不能重复的副作用,或者任务时间长到「重跑一次」本身就很贵。至于 resume,除非你已经把任务切成了带检查点的分片,否则别开------它给你的是「最终成功」的错觉,代价是双倍的副作用。
最后一句:我原来以为持久化是个存储问题,写完才明白它是个调度问题。存下来容易,接着跑很难。 这大概是所有任务系统的共同命运。