我给 MCP 长任务加进度条,五步只显示了一步

上一篇结尾我写了句话:写架构建议的时候最危险的一句话就是"代价不大",因为说这话的人通常没量过。

那篇量完,长任务这条线我以为是收尾了:任务原语解决超时和取消,持久化解决重启,拆解的账也算清楚了。三个问题,三个答案。

直到有个读者问我:任务跑了半分钟,界面上什么都没有,用户怎么知道它没死?

我愣了一下。前面三篇全在讲服务端怎么把任务跑完,没有一篇讲用户怎么看它跑到哪了。这是个更基础的问题------一个跑 30 秒的任务,哪怕最后结果完全正确,只要中间 30 秒没有任何反馈,用户的第一反应就是"卡了",然后刷新、重复提交、关掉页面。

这篇就把进度这件事实测一遍。结论先放这:进度通知在普通工具上是好的,换到任务原语上会只显示五分之一------而这恰恰是最需要进度条的场景。

进度通知不长在工具返回里

先说机制。MCP 的进度不是工具返回值的一部分,是一条独立的 JSON-RPC 通知:notifications/progress。

客户端调用工具时,在请求选项里挂一个 onprogress 回调。SDK 会自动给这次请求分配一个 token(就是请求的 id),塞进 params._meta.progressToken。服务端在 handler 里从 extra._meta 取出这个 token,然后每推进一步就发一条通知:

typescript 复制代码
server.registerTool("build_report", {
  inputSchema: {},
}, async (args, extra) => {
  const token = (extra._meta as any)?.progressToken;
  for (let i = 1; i <= 5; i++) {
    if (token !== undefined) {
      await extra.sendNotification({
        method: "notifications/progress",
        params: { progressToken: token, progress: i, total: 5, message: `第 ${i}/5 步` },
      });
    }
    await doOneStep(i);
  }
  return { content: [{ type: "text", text: "周报完成" }] };
});

客户端这一侧:

javascript 复制代码
await client.callTool(
  { name: "build_report", arguments: {} },
  undefined,
  { onprogress: (p) => console.log(`${p.progress}/${p.total} ${p.message}`) }
);

注意几个容易忽略的点:

  • 进度通知是 always allowed 的,不需要像 logging 那样在 server capabilities 里声明 logging。这是我一开始多写的东西。
  • token 是 SDK 自动塞的,客户端代码里看不到它。你没法手动指定一个字符串 token------客户端 _onprogress 里会 Number(progressToken) 拿它当数字去找回调,传字符串会匹配不上。
  • 如果 extra._meta.progressToken 是 undefined,上面那个 if 直接跳过,一条通知都不发,而且不报任何错。

最后这条是第一个坑。

第一个坑:不传回调,进度就凭空消失

我跑了个对照。同一段五步的工作,一次挂 onprogress,一次不挂。

挂了回调:

csharp 复制代码
[cli]  onprogress 1/5 "第 1/5 步"
[cli]  onprogress 2/5 "第 2/5 步"
[cli]  onprogress 3/5 "第 3/5 步"
[cli]  onprogress 4/5 "第 4/5 步"
[cli]  onprogress 5/5 "第 5/5 步"
[cli]  结果: 周报完成,共 5 步
[cli]  共收到进度回调 5 条

不挂回调:

csharp 复制代码
[cli]  结果: 周报完成,共 5 步
[cli]  共收到进度回调 0 条

服务端日志解释了原因:

ini 复制代码
[srv] sync 调用到达, progressToken=无

进度是客户端跟服务端要来的,不是服务端主动给的。 客户端不传回调,请求里就没有 _meta.progressToken,服务端连"该发给谁"都不知道。

这个设计和 HTTP 的 logging 完全不是一回事。做服务端的时候我总觉得"我发了通知客户端就能收到",其实协议里有没有这个 token,全看调用方那一下有没有挂回调。而且它是静默的:结果照样正确返回,只是进度条一直是空的,你从返回值里看不出任何异常。

所以别指望"服务端加了进度通知"就完事。调用方不配合,你加的东西等于没写。

换成任务原语,进度条只走到 20%

上面这些在普通工具上都成立。真正的问题出在任务原语上。

回顾一下任务原语的执行模型:createTask 必须很快返回 taskId,真正的活在后台跑,客户端靠 tasks/get 轮询状态。也就是说,处理那次 tools/call 的请求在几毫秒内就结束了,而任务本身还要跑三秒。

我给任务版的 createTask 加了同样的进度通知,在后台循环里每步发一条:

typescript 复制代码
createTask: async (args, extra) => {
  const token = (extra._meta as any)?.progressToken;
  const task = await extra.taskStore.createTask({ ttl: 300_000 });

  void (async () => {
    for (let i = 1; i <= 5; i++) {
      await extra.sendNotification({
        method: "notifications/progress",
        params: { progressToken: token, progress: i, total: 5, message: `第 ${i}/5 步` },
      });
      await sleep(600);
    }
    // 写结果...
  })();

  return { task };
},

代码看起来毫无问题。跑出来是这样:

ini 复制代码
[cli]  onprogress 1/5 "第 1/5 步"
[cli]  taskCreated id=35534575
[cli]  taskStatus working
[cli]  taskStatus working
[cli]  taskStatus working
[cli]  taskStatus completed
[cli]  result: 周报完成,共 5 步
[cli]  共收到进度回调 1 条

五步只显示了一步。 进度条停在 20%,然后任务就完成了。

服务端日志给出了报错原文:

ini 复制代码
[srv] task createTask id=35534575 progressToken=2
[srv] task 后台推第 1 步进度 成功
[srv] task 后台推第 2 步进度 抛错: No connection established for request ID: 2
[srv] task 后台推第 3 步进度 抛错: No connection established for request ID: 2
[srv] task 后台推第 4 步进度 抛错: No connection established for request ID: 2
[srv] task 后台推第 5 步进度 抛错: No connection established for request ID: 2

No connection established for request ID: 2------这句话是整篇的关键。

为什么恰好只成功一条

不是随机的,是时序决定的。

sendNotification 绑的是发起那次请求的连接 。token 是 2,也就是那次 tools/call 的请求 id。后台任务第一步执行时(0 毫秒),请求还没返回,连接还在,所以第 1 条发出去了。

但 createTask 本身就是设计成立刻返回的。返回之后,那次请求结束,连接被回收,请求 id 2 对应的连接就不存在了。600 毫秒后后台推第 2 步,sendNotification 找不到连接,抛错。

而客户端看到的 taskStatus working,是 SDK 用 tasks/get 定时轮询出来的------那是另一条请求、另一条连接,跟进度通知走的不是一回事。

所以这里有个很别扭的错配:

  • 真正需要进度条的场景,是任务要在后台跑很久、请求早就返回了的场景
  • 而 notifications/progress 依赖的,恰恰是那条已经返回、已经死掉的请求连接

任务原语解决了生命周期,但把进度通知赖以为生的那条连接给拆了。 上一篇说任务原语解的是服务端生命周期、不解上下文;这篇补上另一半------它也不解进度推送。

解法一:把进度写进 statusMessage,让客户端来读

既然推不动,就别推了。改成客户端拉取。

任务对象上有个 statusMessage 字段,本来是给失败任务放诊断信息的,但协议没限定它只能在失败时用。后台每步更新一次:

javascript 复制代码
for (let i = 1; i <= 5; i++) {
  await store.updateTaskStatus(task.taskId, "working", `第 ${i}/5 步完成`);
  await sleep(600);
}

客户端拿到 taskId 之后,用 tasks/get 轮询:

csharp 复制代码
[cli] 拿到 taskId=9b774576,改轮询 tasks/get
[cli] getTask -> working "第 1/5 步完成"
[cli] getTask -> working "第 2/5 步完成"
[cli] getTask -> working "第 3/5 步完成"
[cli] getTask -> working "第 4/5 步完成"
[cli] getTask -> working "第 5/5 步完成"
[cli] getTask -> completed "第 5/5 步完成"

五步全读到,一步不漏。

拉取为什么可靠?因为每次 tasks/get 都是一条新请求、新连接,读的是服务端的 taskStore,不依赖任何历史连接。任务跑在后台、客户端隔多久来问、中间断没断线,都不影响。

代价是轮询本身:我的实验里 600 毫秒一次,任务 3 秒,问了 6 次(含最后一次 completed)。真实系统里这个频率要自己权衡------问得密,进度跟手但请求多;问得疏,省钱但进度条一格一格跳。

解法二:用 callToolStream,但它会丢帧

SDK 还有个省事的办法:callToolStream。它内部会帮你轮询,把任务状态变化直接推成事件流。

我一开始测它的时候,客户端一条 taskStatus 都没收到。查了半天,发现是我自己踩了第十二篇写过的坑:没先调 listTools(),callToolStream 会静默退化成同步调用,任务模式根本没启用。

补上 listTools() 之后,它确实能把 statusMessage 推出来:

csharp 复制代码
[cli] taskCreated id=317bdbc8
[cli] taskStatus working "第 1/5 步完成"
[cli] taskStatus working "第 2/5 步完成"
[cli] taskStatus working "第 4/5 步完成"
[cli] taskStatus completed "第 5/5 步完成"

对照服务端日志:

ini 复制代码
[srv] 更新 statusMessage=第 1/5 步
[srv] 更新 statusMessage=第 2/5 步
[srv] 更新 statusMessage=第 3/5 步
[srv] 更新 statusMessage=第 4/5 步
[srv] 更新 statusMessage=第 5/5 步

服务端更新了 5 次,客户端只看到 4 帧,第 3 步那帧丢了。 completed 那次覆盖掉了中间状态,第 5 步的"完成"和第 5 步的进度挤在了一起。

这个不是 bug 级别的严重问题,但要看清楚它的定位:callToolStream 给的是粗粒度的状态播报,不是可靠的进度传输。它适合告诉用户"还在跑 / 跑完了",不适合做那种精确的百分比进度条。

要每一步都不丢,还是得自己轮询 tasks/get。

一个跟前面几篇相反的结论:进度不花 token

写到这我顺手算了一笔账。第七、八两篇我算工具定义和返回值的 token 账,结论都是"进上下文的东西会被反复计费"。进度通知呢?

一条进度通知的 JSON 是这么大:

json 复制代码
{"method":"notifications/progress","params":{"progressToken":2,"progress":1,"total":5,"message":"第 1/5 步"}}

32 个 tokens(cl100k_base,离线数)。5 条一共 160 tokens。

但这 160 个 tokens 一分钱都不花。因为进度通知是带外通道:它走 JSON-RPC 通知,客户端拿去渲染进度条,不会作为消息回灌给模型,不进下一轮的 prompt。

这跟第七、八篇的返回值账形成了对照:

  • 工具返回值会进上下文,被后续每一轮重发,所以要精简
  • 进度通知不进上下文,随便发,多细都行

所以进度这件事,不用省。你可以每 100 毫秒推一次,可以带详细 message,可以带百分比、当前文件名、已处理条数------它不会撑爆上下文。真正的成本在网络包和客户端渲染上,不在模型的 token 账上。

唯一要克制的是别把本该放返回值的内容塞进进度消息里。进度消息是给人看的提示,不是给模型看的数据。模型拿不到它,也做不了决策。

怎么选

三件事分开看:

第一,先确定你的任务以什么方式调用。

  • 普通工具(handler 里同步跑完):用 notifications/progress,前提调用方挂了 onprogress。这是最标准的进度通道。
  • 任务原语(后台跑):放弃 sendNotification,用 statusMessage + tasks/get 轮询。

第二,调用方不配合时要有兜底。

客户端不传回调、不调 listTools(),进度都会静默消失。如果你的进度是刚需(比如给用户看的长任务界面),客户端那一侧的代码要当作契约的一部分来维护,不能只改服务端。

第三,进度要可靠就自己轮询,要省事就用 callToolStream。

callToolStream 会丢帧,适合"跑完没"这种粗状态;精确的百分比和步骤名,用 tasks/get 逐次读。

还有一条不太显眼但很实用:任务型工具最好别只注册任务入口 。第十二篇讲过 taskSupport: optional 允许客户端不支持任务时退化成同步调用------那种情况下进度又走回 notifications/progress 那条路了。你在服务端写的进度逻辑,得覆盖两种出口,不能只管一条。

总结

  • 进度通知 notifications/progress 是客户端跟服务端要来的:不传 onprogress 就没有 _meta.progressToken,服务端一条不发,且不报错
  • 普通工具上进度通知工作正常,同步跑五步能收到完整的 5/5 条
  • 任务原语下后台 sendNotification 只能成功一条 ,第 2 步起报 No connection established for request ID: 2------通知绑的是那条已经返回、已经关闭的请求连接
  • 根因是错配:任务原语拆掉了进度通知赖以生存的连接,越是长任务越明显
  • 可靠解法是把进度写进任务对象的 statusMessage,客户端用 tasks/get 轮询,实测 5/5 条不丢
  • callToolStream 能自动推 statusMessage,但会丢帧(5 次更新只看到 4 帧),只适合粗粒度状态
  • 进度通知不进模型上下文,32 tokens/条但不计费,跟工具返回值的 token 账完全相反------进度可以放心做细

长任务这条线写到第四篇,我越来越觉得它不是一个技术问题,是一个"信息传给谁"的问题:生命周期是服务端自己的事,进度是用户的事,token 是模型的事。三件事各有各的通道,混在一起就会出这种"服务端明明推了、用户就是看不到"的怪事。

适用边界 :以上结论基于本地 Streamable HTTP + SDK 1.30,五步、每步 600 毫秒的模拟任务。进度通知的连接行为跟传输实现强相关------stdio 下请求连接的表现和 HTTP 不同,callToolStream 丢不丢帧也取决于轮询间隔和服务端更新频率。你的任务若只有两三秒,进度条本来就没太大意义,用 callToolStream 的粗状态足够;只有当任务长到用户会不耐烦、且需要精确反馈时,才值得自己维护 statusMessage + 轮询这套机制。别抄结论,先确认你的任务模型和调用方式。

相关推荐
TsingtaoAI10 分钟前
VeyForge:构建具身智能的AI 3D资产与Sim-to-Real数据引擎
人工智能·机器学习
螺丝钉tina33 分钟前
[Playwright] [21][AI] 千问生成测试的完整 mini demo
人工智能
高洁011 小时前
世界模型的因果内核:从预测表象到理解机制
人工智能·python·深度学习·transformer·迁移学习
Forget the Dream1 小时前
Spring AI 2.0 系列(三):ChatClient 与 ChatModel:Spring AI 2.0 的两层职责
java·人工智能·spring·springai
syso_稻草人1 小时前
qwen-image-2.1 姿态控制拆解:SDPose 提骨架 + Fun-ControlNet-Union 锁姿势,换人换景不换姿势
人工智能·stable diffusion·prompt·提示词优化·qwen-image
Baihai_IDP1 小时前
大模型 API 真的在赔本赚吆喝吗?聊聊 Token 背后的真实成本
人工智能·llm·aigc
数字融合1 小时前
透明化视频动态三维重建空间数据零核心技术
人工智能·python·virtualenv
谙弆悕博士1 小时前
多智能体架构详解:黑板共享架构(共享存储交互型)
人工智能·架构·大模型·agent·多智能体·黑板架构·anggraph
AI创界者2 小时前
Python 进阶实战(五十四章):大模型推理网关终极架构——分布式全局前缀 Trie 缓存同步与多网关高可用协同调度
人工智能·python·aigc