上一篇结尾我写了句话:写架构建议的时候最危险的一句话就是"代价不大",因为说这话的人通常没量过。
那篇量完,长任务这条线我以为是收尾了:任务原语解决超时和取消,持久化解决重启,拆解的账也算清楚了。三个问题,三个答案。
直到有个读者问我:任务跑了半分钟,界面上什么都没有,用户怎么知道它没死?
我愣了一下。前面三篇全在讲服务端怎么把任务跑完,没有一篇讲用户怎么看它跑到哪了。这是个更基础的问题------一个跑 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 + 轮询这套机制。别抄结论,先确认你的任务模型和调用方式。