ai

1. 什么是进度？ #

进度用于对长时间运行的操作提供状态更新。请求方可在请求中附带「进度令牌」，接收方在处理过程中发送进度通知，告知当前进度、总量和可选消息。

协议版本：2025-11-25

通俗理解	说明
进度条	像下载或安装时的进度条，让用户知道「完成了多少」
可选	进度跟踪是可选功能，接收方可选择不发送
通知	通过 `notifications/progress` 通知实现，无需请求方轮询

2. 本章你将学到 #

如何在请求中附带进度令牌
进度通知的格式与字段
行为要求与任务场景
实现建议

3. 流程概览 #

请求方 ──► 在请求中附带 progressToken
              │
              ▼
接收方 ──► 处理过程中发送多次 progress 通知
              │
              ▼
请求方 ──► 收到进度更新，可更新 UI（如进度条）
              │
              ▼
接收方 ──► 处理完成，发送方法响应

4. 请求中附带进度令牌 #

当一方希望接收进度更新时，在请求的 params._meta 中包含 progressToken：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "long_running_tool",
    "arguments": {},
    "_meta": {
      "progressToken": "abc123"
    }
  }
}

要求	说明
类型	`progressToken` 必须为字符串或整数
唯一性	在所有活跃请求中必须唯一

5. 进度通知 #

接收方在处理过程中可以发送进度通知：

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "abc123",
    "progress": 50,
    "total": 100,
    "message": "正在处理第 50 条记录..."
  }
}

字段	要求	说明
`progressToken`	必须	与请求中的令牌一致
`progress`	必须	当前进度值，必须随每次通知递增
`total`	可选	总量；未知时可省略
`message`	可选	人类可读的进度描述

progress 和 total 可为浮点数；message 应提供有意义的进度信息。

6. 行为要求 #

6.1 发送进度通知的一方 #

规则	说明
仅引用有效令牌	只能为活跃请求中提供的、与进行中操作关联的令牌发送通知
可选择性	可以选择不发送任何进度通知
频率	可以按认为合适的任意频率发送
完成后停止	操作完成后必须停止发送进度通知

6.2 任务场景 #

对于任务增强请求：

规则	说明
令牌延续	原始请求的 `progressToken` 在任务整个生命周期内有效，包括 `CreateTaskResult` 返回之后
相同令牌	任务的进度通知必须使用初始请求中的相同 `progressToken`
终止后停止	任务达到 `completed`、`failed` 或 `cancelled` 后必须停止发送进度通知

7. 流程示意 #

sequenceDiagram participant S as 请求方 participant R as 接收方 S->>R: 方法请求（含 progressToken: abc123） Note over R: 开始处理 R-->>S: 进度通知 (progress: 20, total: 100) R-->>S: 进度通知 (progress: 60, total: 100) R-->>S: 进度通知 (progress: 100, total: 100) R-->>S: 方法响应（操作完成）

典型场景：客户端调用「批量导入 1000 条数据」的工具，服务器每处理 100 条发送一次进度通知（progress: 100, 200, ..., 1000），客户端据此更新进度条。

8. 实现建议 #

建议	说明
跟踪令牌	双方应当跟踪活跃的 progressToken
速率限制	应当对进度通知实施速率限制，防止泛滥
完成后停止	进度通知必须在操作完成后停止

导航菜单