我给 MCP 长任务做了持久化,结果造出一堆僵尸

0 阅读8分钟

上一篇的结尾我写了一句话:InMemoryTaskStore 重启即丢,任务原语只解决「怎么问」,不解决「问的东西还在不在」。

那自然的下一步就是:自己写一个落盘的 store。

我花了一个下午写完了,六个方法、一个任务一个 JSON 文件、原子写。重启之后 tasks/get 照样能返回任务,状态是 working。我以为成了。

然后我发现这个任务永远不会结束。

不是慢,是永远不会。没有报错,没有超时,tasks/get 每隔一秒老老实实返回一次 working,状态消息停在「正在读取笔记」,一直到 TTL 把记录清掉为止。

状态存下来了,执行没存下来。  这两件事在代码里只差几行,但在语义上差了一整个分布式任务系统。

先看这个 store 长什么样

TaskStore 是个很普通的接口,六个方法:

createTask(taskParams, requestId, request, sessionId?)   // 建任务
getTask(taskId, sessionId?)                              // 查状态
updateTaskStatus(taskId, status, statusMessage?)         // 改状态
storeTaskResult(taskId, status, result)                  // 存结果
getTaskResult(taskId, sessionId?)                        // 取结果
listTasks(cursor?, sessionId?)                           // 列表

实现很简单:一个任务一个文件,文件名就是 taskId。

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」。

有一处不能省:建任务时得把原始请求一起存下来。

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(没有任何东西会再推进它)

然后客户端来查:

getTask -> working "正在读取笔记" (距重启 445ms)
getTask -> working "正在读取笔记" (距重启 2456ms)
getTask -> working "正在读取笔记" (距重启 4465ms)
...
getTask -> working "正在读取笔记" (距重启 20540ms)

十几秒过去了,状态一动不动。

原因很直白:推进任务的是 createTask 里那个 void runBackground(...)。那是一个跑在进程内存里的 async 函数,进程被 SIGKILL 的那一刻,它跟着一起没了。磁盘上的 JSON 只记录了「这个任务正在进行中」,没有任何东西会再把它推下去。

这就是僵尸任务:记录活着,执行死了。

更难受的是客户端那边。它看到的是持续的 working,只能一直轮询。我让它去取结果:

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 的实现只要几行:

for (const { task } of store.scanWorking()) {
  await store.storeTaskResult(task.taskId, "failed", {
    content: [{ type: "text", text: "服务重启,任务已中断" }],
  });
}

效果很干脆:客户端在重启后 444 毫秒就拿到了终态,不会傻等。

我认为这是大多数项目应该默认选的那一个。理由不是它更优雅,而是它的失败方式最诚实:任务确实没跑完,就告诉客户端没跑完,让上层决定要不要重试。重试的逻辑本来就在客户端(或者模型)那边,服务端不该替它假装还在努力。

resume 看起来最贴心,但它是三种里最危险的,下一节说。

resume 的代价:没有断点,只能从头跑

先看它能用:

  重新执行:8b4ed415 预计 15000ms(从头跑,没有断点)
getTask -> working "[续] 正在读取笔记" (距重启 445ms)
...
getTask -> completed "已完成" (距重启 16521ms)

15 秒的任务,重启后 16.5 秒完成。看起来没问题。

但注意那句「从头跑」。我把杀进程的时间点从第 3 秒挪到第 12 秒——也就是任务已经跑完 80%、摘要都快生成好了——再重启:

>>> 强杀服务(SIGKILL,模拟发版/宕机)
  重新执行:0c841912 预计 15000ms(从头跑,没有断点)
getTask -> completed "已完成" (距重启 16524ms)
[server] 任务完成 0c841912 耗时=15014ms

前面那 12 秒白跑了,重启后又完整跑了 15 秒。

一个 15 秒的任务,累计消耗 27 秒计算量,其中 12 秒是纯浪费——相当于一次完整执行的 80%。如果这个任务里有一次 API 调用、一次数据库写入、一次发消息,那 27 秒里就有两次副作用。

所以 resume 有两个前提,缺一不可:

  1. 任务必须幂等,否则重跑就是重复写入。这一条上一篇讲过,tasks/get 的轮询和写操作的幂等是两件独立的事
  2. 任务最好可分片,每片做完就落一个检查点,重启后从最后一个检查点继续

第二条我们完全没有做。真实的做法是把任务切成 N 段,每段结束写一次进度:

// 每片做完,把进度也写进 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 距今的时间在持续变大。

我把重启后的轮询结果连时间戳一起打出来:

任务 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,这个值就往前跳。所以在客户端只要算一个数:

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 秒的任务,然后什么都不做:

2 秒后   -> working "正在读取笔记"
10 秒后  -> {"error":{"code":-32602,"message":"Failed to retrieve task: Task not found"}}

于是同一个 -32602 Task not found,现在可能意味着三件完全不同的事:

  • 这个 taskId 从来不存在(客户端抄错了)
  • 服务重启过,记录丢了
  • 任务跑太久,TTL 到期被清理了

客户端没法区分,只能一律当作「重来吧」。对排障的人来说,这三种情况要查的地方完全不同。

顺带一个坑:落盘的记录不会自己消失。内存 store 重启就清空,磁盘上的文件不会。ttl: null 意味着永不清理,一年后你的目录里会有多少文件,取决于你的调用量。我的实现是在读取时懒清理:

private expired(rec: Record_): boolean {
  const { ttl, createdAt } = rec.task;
  if (ttl == null) return false;
  return this.now() > Date.parse(createdAt) + ttl;
}

读的时候顺手删。缺点是没人读的任务永远不删;如果在意,得配一个定时扫盘的任务。这件事在内存版本里完全不存在,属于「持久化引入的新工作量」。

我还写错了一个字段

fail 策略第一次跑出来是这样:

getTask -> failed "正在读取笔记" (距重启 445ms)

状态是 failed,消息是「正在读取笔记」。原因是我在 storeTaskResult 里只改了 status,没动 statusMessage——上一篇吐槽过 SDK 有这个毛病,轮到我自己写 store,一模一样地踩了。

改法是终态时强制覆盖:

rec.task = {
  ...rec.task,
  status,
  statusMessage: status === "completed" ? "已完成" : "已失败",
  lastUpdatedAt: new Date().toISOString(),
};

改完:

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,除非你已经把任务切成了带检查点的分片,否则别开——它给你的是「最终成功」的错觉,代价是双倍的副作用。

最后一句:我原来以为持久化是个存储问题,写完才明白它是个调度问题。存下来容易,接着跑很难。  这大概是所有任务系统的共同命运。