【随笔】MCP长任务:查询已经返回,为什么任务还没有完成

让工具生成一份报告,服务端可能需要几分钟。客户端如果一直等同一次请求返回,网络断开后就很难判断工作还在进行,还是已经结束。上一篇讨论了重试写操作的收据,这次继续看拿到任务编号之后,界面怎样可靠地跟踪后续执行。

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仍要检查工具结果;网络断开只说明当前观察受阻。

串行轮询使客户端行为容易验证。每轮读取当前间隔,限制观察预算,并把单次网络超时放在传输适配层处理,才能避免无限等待和旧状态回写。

下一篇随笔继续看长任务中的人工输入:任务等待确认时,如何关联输入请求、避免重复弹窗,并在恢复页面后继续处理。

👉 如果你觉得这篇文章对你有所帮助,欢迎点赞、收藏、分享!😊

相关推荐
FRing0318 分钟前
vue2干货总结11(短信验证、登录功能、统一处理错误(响应拦截器)、将token信息存入vuex、vuex持久化处理)
开发语言·前端·javascript·vue.js·vue2
泯泷21 分钟前
改一个字,整段都红了?——中文内容差异对比的算法与协议设计
前端·javascript·typescript
玄魂34 分钟前
小红书/抖音图文排版利器——一个杂志风skill
人工智能·agent·视觉设计
afumu1 小时前
免费 API 满地都是,为什么还有人做「让网页 AI 干活」这种东西
javascript·chrome·浏览器
Java与AI落地1 小时前
别再正则抠 JSON 了:用 Spring AI 的 entity() 把模型输出变成对象
后端
云起SAAS1 小时前
本地生活同城多商户商城系统源码源码 合伙人分红加区域代理加排队返现
前端·javascript·后端
写标小何1 小时前
AI 标书工具技术架构解析:从文件解析到排版导出的工程实践
人工智能
敖老师1 小时前
DeepSeek Harness Web 版从装到用:dsh web 启动、接入本地 Ollama 全流程
人工智能
阿里云大数据AI技术1 小时前
DataWorks AI 数据生成:一条配置,量产多行业的仿真级业务数据
人工智能