让工具生成一份报告,服务端可能需要几分钟。客户端如果一直等同一次请求返回,网络断开后就很难判断工作还在进行,还是已经结束。上一篇讨论了重试写操作的收据,这次继续看拿到任务编号之后,界面怎样可靠地跟踪后续执行。
MCP Tasks扩展 把长操作表示成可查询的任务。客户端保存任务编号,服务端维护执行状态,连接恢复后继续查询。它适合报告生成、构建和批处理等耗时工作;是否启用任务方式,需要客户端与服务端支持相应扩展。官方概览
本文依据2026-07-28版Tasks扩展。这个版本用tasks/get返回状态及最终结果,字段为pollIntervalMs;不要把旧版tasks/result、pollInterval示例拼进同一套实现。下面围绕一个"生成任务统计报告"的客户端适配器展开,重点是状态如何解释、轮询如何结束,以及怎样避免界面误报成功。
一、结构介绍:一次查询和一个任务有不同的生命周期
考虑两个时间尺度:一次HTTP或JSON-RPC查询可能很快返回,后台生成报告却仍在运行。
因此,客户端至少保存两组信息:
| 对象 | 示例 | 用途 |
|---|---|---|
| 查询请求 | 第3次状态读取 | 跟踪这一次网络调用 |
| 后台任务 | report-7 | 跨多次查询识别同一份工作 |
界面上"正在读取状态"消失,只说明这一轮查询结束。它不能据此把"生成报告"也打上完成勾。
我们把适配器分为三个部分:获取任务快照的readTask、解释快照的classify、驱动轮询的watchTask。readTask负责网络与协议封装;classify只做确定性分类;watchTask决定继续等待还是返回一个可展示的结果。
服务端内部可分成请求入口、持久任务记录和执行worker。请求入口给出任务编号,worker更新任务记录,查询读取记录;客户端关闭页面不应让记录随页面内存一起消失。官方架构

二、最容易误读的两个"完成"
现行扩展的任务快照有working、input_required、completed、failed和cancelled等状态。tasks/get自身的标准结果可以带resultType: "complete",此时任务status仍可能是working。任务completed还可能携带isError: true的工具结果;failed则对应任务执行中的JSON-RPC错误。Tasks规范
这意味着成功至少要分层看:
text
状态查询正常返回
↓ 检查任务status
任务进入completed
↓ 检查工具结果isError
业务结果可按成功展示
在本文的报告页面,分类规则如下。这是客户端的展示设计,kind名称由应用自行定义:
| 观察到的情况 | 页面状态kind | 处理 |
|---|---|---|
| working | pending | 保留进度,继续查询 |
| input_required | needs-input | 交给输入处理流程 |
| completed且isError不为true | succeeded | 展示报告结果 |
| completed且isError为true | tool-error | 展示工具层错误 |
| failed | rpc-error | 展示协议执行错误 |
| cancelled | cancelled | 展示取消状态 |
| 查询断开或等待预算耗尽 | unknown | 保留任务编号,允许继续查询 |
unknown是本地观察状态,不写回服务器,也不冒充MCP任务状态。它表达"这次观察无法继续给出结论"。这比把网络失败涂成"报告生成失败"更准确:网络恢复之后,同一个任务仍有可能返回成功结果。
三、轮询为什么要串行
如果每隔一秒无条件发一次查询,而某轮请求花了三秒,就会出现多次查询同时在途。旧快照晚到时,页面可能先显示完成,又退回处理中。
本文选择上一轮结束后再等待、再发下一轮。同一个watchTask最多只有一个查询在途,自然避免它自己制造的响应倒序。若用户切换任务或同时启动两个观察器,界面层还需要按当前任务编号和观察器代次过滤旧结果,这与前文处理筛选条件过期响应的原则一致。

轮询间隔读取每轮返回的pollIntervalMs,而不是只看首次响应。等待总预算由应用决定。预算用尽时退出观察,保留taskId供下一次继续;没有明确操作意图时,不因为页面等待结束就擅自取消远端任务。
任务记录也有保留期限。恢复查询应考虑ttlMs;记录过期后,"查不到"不能反推历史上"从未执行"。真正需要长期审计的业务结果,应保存在业务自己的记录里。
四、完整实例:一个可测试的观察器
保存为task-watch.mjs,用Node.js运行。这个程序通过注入的readTask读取解包后的任务结果对象;末尾用固定快照模拟状态变化,不连接外部服务。接入真实MCP传输时,由readTask发送tasks/get并处理JSON-RPC错误,网络超时也在该层设置。
javascript
import assert from "node:assert/strict";
function classify(task) {
switch (task.status) {
case "working":
return "pending";
case "input_required":
return "needs-input";
case "completed":
if (!task.result || typeof task.result !== "object") {
throw new Error("completed缺少结果");
}
return task.result.isError === true
? "tool-error" : "succeeded";
case "failed":
if (!task.error || typeof task.error !== "object") {
throw new Error("failed缺少错误");
}
return "rpc-error";
case "cancelled":
return "cancelled";
default:
throw new Error("无法识别的任务状态");
}
}
async function watchTask(taskId, readTask, {
budgetMs = 10000,
now = () => performance.now(),
sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
} = {}) {
const deadline = now() + budgetMs;
let lastTask;
while (now() < deadline) {
let task;
try {
task = await readTask(taskId);
} catch (error) {
return { kind: "unknown", taskId,
reason: "读取状态失败", detail: String(error) };
}
if (task.taskId !== taskId) {
throw new Error("返回了其他任务的快照");
}
lastTask = task;
const kind = classify(task);
if (kind !== "pending") {
return { kind, taskId, task };
}
const interval = task.pollIntervalMs ?? 1000;
if (!Number.isInteger(interval) || interval < 0) {
throw new Error("轮询间隔格式错误");
}
// 本客户端至少等待1毫秒,避免零间隔忙循环。
const delay = Math.max(interval, 1);
if (now() + delay >= deadline) break;
await sleep(delay);
}
return { kind: "unknown", taskId,
reason: "本轮等待预算已用完", task: lastTask };
}
const base = {
resultType: "complete",
taskId: "report-7",
createdAt: "2026-11-15T08:00:00Z",
lastUpdatedAt: "2026-11-15T08:00:01Z",
ttlMs: 60000
};
const pending = { ...base, status: "working", pollIntervalMs: 1000 };
const success = { ...base, status: "completed",
result: { content: [{ type: "text", text: "报告已就绪" }] } };
let clock = 0;
const waits = [];
const snapshots = [pending,
{ ...pending, pollIntervalMs: 2000 }, success];
let reads = 0;
const options = {
now: () => clock,
sleep: async ms => { waits.push(ms); clock += ms; }
};
const result = await watchTask("report-7", async id => {
assert.equal(id, "report-7");
reads += 1;
return snapshots.shift();
}, options);
assert.equal(result.kind, "succeeded");
assert.equal(reads, 3);
assert.deepEqual(waits, [1000, 2000]);
assert.equal(classify({ ...success,
result: { isError: true, content: [] } }), "tool-error");
assert.equal(classify({ ...base, status: "failed",
error: { code: -32603, message: "执行错误" } }), "rpc-error");
assert.equal(classify({ ...base, status: "input_required",
inputRequests: {} }), "needs-input");
assert.equal(classify({ ...base, status: "cancelled" }), "cancelled");
const unavailable = await watchTask("report-7", async () => {
throw new Error("连接断开");
}, options);
assert.equal(unavailable.kind, "unknown");
const timedOut = await watchTask("report-7", async () => pending,
{ ...options, budgetMs: 500 });
assert.equal(timedOut.kind, "unknown");
await assert.rejects(() => watchTask("report-7", async () =>
({ ...success, taskId: "other" }), options), /其他任务/);
assert.throws(() => classify({ ...base, status: "completed" }), /缺少结果/);
console.log("读取次数:" + reads);
console.log("等待间隔:" + waits.join(","));
console.log("最终分类:" + result.kind);
console.log("状态、断连、预算、错配与缺失结果检查通过");
运行:
bash
node task-watch.mjs
输出:
text
读取次数:3
等待间隔:1000,2000
最终分类:succeeded
状态、断连、预算、错配与缺失结果检查通过
这里注入虚拟时钟和sleep,让间隔测试不必真实等待三秒;验证的是状态解释、调度顺序和边界分支。readTask每次只消耗一个快照,只有await完成后才可能进入下一轮。
budgetMs限制继续轮询和等待的预算,不会强行中断已经进入的readTask。真实适配层必须为单次请求设置超时或取消信号;否则一次永不结束的网络调用仍会让观察器挂住。任务TTL与客户端等待预算也不同:一个决定服务端记录保留多久,另一个决定本次界面愿意等多久。
五、接入时保留哪些边界
校验结果结构。 示例只检查状态分流所需的字段。生产适配层还应按协议Schema校验快照,并按具体工具的结果契约检查报告字段。isError不为true只能说明未声明工具错误,不能替代业务字段验证。
输入请求独立处理。 观察器遇到needs-input时交还上层,不持续空转。现行扩展通过tasks/update回传输入响应;取消使用tasks/cancel,取消确认也不保证后台已经停下。相关流程应由独立交互处理,不用重新提交原始生成报告请求代替。输入与取消语义
查询不等于授权。 服务端每次读取任务都要验证调用者能否访问对应记录。taskId是定位信息,不能拿"知道编号"当作权限。
不把断连自动升级为重新执行。 当前例子在读取失败时返回unknown,页面可提供"继续查询"。这个按钮应继续使用已有taskId;"重新生成"属于新的业务动作,应单独呈现,避免用户无意间启动第二份报告。
如果操作本来就在很短时间内完成,普通工具结果足够;长任务机制会增加存储、状态恢复和客户端分支。对于确实需要跨连接追踪的工作,这些成本换来的是明确、可恢复的执行记录,而非一个持续旋转却没有依据的加载图标。
六、🧠 思维导图
#mermaid-svg-g2INfrbQOgPktaYL{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-g2INfrbQOgPktaYL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-g2INfrbQOgPktaYL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-g2INfrbQOgPktaYL .error-icon{fill:#552222;}#mermaid-svg-g2INfrbQOgPktaYL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-g2INfrbQOgPktaYL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-g2INfrbQOgPktaYL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-g2INfrbQOgPktaYL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-g2INfrbQOgPktaYL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-g2INfrbQOgPktaYL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-g2INfrbQOgPktaYL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-g2INfrbQOgPktaYL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-g2INfrbQOgPktaYL .marker.cross{stroke:#333333;}#mermaid-svg-g2INfrbQOgPktaYL svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-g2INfrbQOgPktaYL p{margin:0;}#mermaid-svg-g2INfrbQOgPktaYL .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-g2INfrbQOgPktaYL .cluster-label text{fill:#333;}#mermaid-svg-g2INfrbQOgPktaYL .cluster-label span{color:#333;}#mermaid-svg-g2INfrbQOgPktaYL .cluster-label span p{background-color:transparent;}#mermaid-svg-g2INfrbQOgPktaYL .label text,#mermaid-svg-g2INfrbQOgPktaYL span{fill:#333;color:#333;}#mermaid-svg-g2INfrbQOgPktaYL .node rect,#mermaid-svg-g2INfrbQOgPktaYL .node circle,#mermaid-svg-g2INfrbQOgPktaYL .node ellipse,#mermaid-svg-g2INfrbQOgPktaYL .node polygon,#mermaid-svg-g2INfrbQOgPktaYL .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-g2INfrbQOgPktaYL .rough-node .label text,#mermaid-svg-g2INfrbQOgPktaYL .node .label text,#mermaid-svg-g2INfrbQOgPktaYL .image-shape .label,#mermaid-svg-g2INfrbQOgPktaYL .icon-shape .label{text-anchor:middle;}#mermaid-svg-g2INfrbQOgPktaYL .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-g2INfrbQOgPktaYL .rough-node .label,#mermaid-svg-g2INfrbQOgPktaYL .node .label,#mermaid-svg-g2INfrbQOgPktaYL .image-shape .label,#mermaid-svg-g2INfrbQOgPktaYL .icon-shape .label{text-align:center;}#mermaid-svg-g2INfrbQOgPktaYL .node.clickable{cursor:pointer;}#mermaid-svg-g2INfrbQOgPktaYL .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-g2INfrbQOgPktaYL .arrowheadPath{fill:#333333;}#mermaid-svg-g2INfrbQOgPktaYL .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-g2INfrbQOgPktaYL .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-g2INfrbQOgPktaYL .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-g2INfrbQOgPktaYL .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-g2INfrbQOgPktaYL .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-g2INfrbQOgPktaYL .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-g2INfrbQOgPktaYL .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-g2INfrbQOgPktaYL .cluster text{fill:#333;}#mermaid-svg-g2INfrbQOgPktaYL .cluster span{color:#333;}#mermaid-svg-g2INfrbQOgPktaYL div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-g2INfrbQOgPktaYL .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-g2INfrbQOgPktaYL rect.text{fill:none;stroke-width:0;}#mermaid-svg-g2INfrbQOgPktaYL .icon-shape,#mermaid-svg-g2INfrbQOgPktaYL .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-g2INfrbQOgPktaYL .icon-shape p,#mermaid-svg-g2INfrbQOgPktaYL .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-g2INfrbQOgPktaYL .icon-shape .label rect,#mermaid-svg-g2INfrbQOgPktaYL .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-g2INfrbQOgPktaYL .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-g2INfrbQOgPktaYL .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-g2INfrbQOgPktaYL :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} MCP长任务
身份与存储
持久任务编号
保留期限
状态解释
查询完成不等于任务完成
区分工具错误
串行观察
遵守轮询间隔
断连保留未知
输入与取消单独处理
七、总结
总结要点
任务编号把一次长操作串过多个短查询。保存编号和必要的恢复信息,连接断开后才有继续观察的依据。
状态解释决定界面是否可信。查询返回、任务结束、业务成功是不同层次,completed仍要检查工具结果;网络断开只说明当前观察受阻。
串行轮询使客户端行为容易验证。每轮读取当前间隔,限制观察预算,并把单次网络超时放在传输适配层处理,才能避免无限等待和旧状态回写。
下一篇随笔继续看长任务中的人工输入:任务等待确认时,如何关联输入请求、避免重复弹窗,并在恢复页面后继续处理。
👉 如果你觉得这篇文章对你有所帮助,欢迎点赞、收藏、分享!😊