> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operation 与恢复

> 读取当前 MCP 规则、处理 next_action，并安全恢复已有操作。

Clink 使用 Operation 描述流程的当前状态和继续所需的操作。账户设置、购买授权、Browser Pay 凭证签发和 UCP Checkout 都可能产生 Operation。发生超时或中断后，应读取当前 Operation，不要假定写入失败后直接重新发起。

并非所有工具都返回 Operation。例如 `get_skill_manifest` 返回规则元数据，钱包查询返回钱包数据，`confirm_result` 返回 Browser Pay 结果报告。处理结果前，应读取对应工具的 schema。

## 读取当前业务规则

安装 Skill 的地址为 [www.clinkbill.com/SKILL.md](https://www.clinkbill.com/SKILL.md)。执行业务时，每个会话读取一次已连接服务端的当前规则：

```json theme={null}
{
  "method": "resources/read",
  "params": { "uri": "clink://skill/rules" }
}
```

如果 Host 无法读取 MCP resources，调用 `get_skill_manifest` 并传入 `include_rules: true`。返回的 `rules` 包含相同指引，无需再读取资源。服务端当前规则优先于本地安装的 Skill 文本；当前 `next_action` 决定如何继续这个 Operation。

### get\_skill\_manifest

此只读工具不需要业务 Scope，也不会执行扣款。纯 Catalog 搜索无需调用 manifest。

| 参数 | 必填 | 含义 |
| :- | :- | :- |
| `skill_version` | 否 | 已知时，传入本地 `SKILL.md` 中的非空版本号，不要猜测。 |
| `include_rules` | 否 | boolean；为 `true` 时，结果包含规则 Markdown。 |

```json theme={null}
{
  "name": "get_skill_manifest",
  "arguments": { "include_rules": true }
}
```

| 返回字段 | 含义 |
| :- | :- |
| `current_version` | 服务端当前规则版本。 |
| `min_supported_version` | 最低支持的已安装 Skill 版本。 |
| `status` | `up_to_date`、`outdated`、`unsupported` 或 `unknown`。未传版本时为 `unknown`。 |
| `rules_resource` | 规则的 MCP resource URI。 |
| `notes` | 版本与更新指引。 |
| `rules` | `include_rules` 为 true 时返回的规则 Markdown。 |

状态为 `outdated` 或 `unsupported` 时，通过 Host 的安装机制及官方分发地址更新本地 Skill。检查连接时，以返回的版本和兼容状态为准。

## get\_operation

读取已有 Operation 的当前状态。此工具只读，不会再次执行支付。

| 参数 | 必填 | 类型 | 含义 |
| :- | :- | :- | :- |
| `operationId` | 是 | string | 原始工具返回的非空 `operation_id`。 |
| `maxWaitSeconds` | 否 | integer，0–60 | 默认 `0`，只读取一次。正数允许服务端在状态处理中进行有界等待，也适用于 Passkey 和绑卡跳转；状态变化时可能提前返回。 |

```json theme={null}
{
  "name": "get_operation",
  "arguments": {
    "operationId": "<operation_id from the original response>",
    "maxWaitSeconds": 60
  }
}
```

读取时必须使用同一授权用户。所需 Scope 取决于 Operation：

| Operation | 读取 Scope |
| :- | :- |
| Browser Pay 签发、直接支付、UCP Checkout、Tip | `payment:execute` |
| 支付卡和钱包设置 | `wallet:read` |
| 购买授权设置 | 指令已存在时使用 `instruction:read`；设置恢复可能还需要 `wallet:read`。创建指令前需要 `wallet:read`。 |
| 退款 | `refund:read` |

通过用户操作事件恢复的 Operation 还需要 `events:read` 和 `events:consume`。处理购买授权、卡注册等依赖事件的用户步骤时，加入这两个 Scope。OAuth challenge 会返回缺少的权限。

Host 支持时，也可以通过 MCP resource `clink://operations/{operationId}` 读取。通知仅表示可能需要重新读取，实际状态以随后的读取结果为准。

## Operation envelope

返回 Operation 的工具在 `structuredContent` 中提供以下字段：

| 字段 | 含义 |
| :- | :- |
| `operation_id` | 用于读取本流程的稳定标识。 |
| `status` | `ACTION_REQUIRED`、`WAITING`、`SUCCEEDED` 或 `FAILED`。 |
| `revision` | 当前 Operation 状态的非负整数版本。 |
| `upstream_status` | 可选的底层业务状态，例如 Checkout 状态。 |
| `next_action` | 需要操作或等待时出现，终态时省略。 |
| `resources` | 关联标识，例如 `instruction_id`、`payment_order_id`、`payment_execution_detail_id`、`checkout_id` 或 `ucp_order_id`，是否可用取决于流程。 |
| `messages` | 包含 `code` / `text` 的解释消息，可能附带严重程度或字段路径。 |
| `checkout`、`order` | 可用时返回的 UCP 专属快照。已完成的 Checkout 包含其权威订单结果。 |

`SUCCEEDED` 和 `FAILED` 表示 Operation 终态，此时不包含 `next_action`，也不会返回 `null` 或空对象。需要结合原始工具理解成功的含义：

| 原始流程 | Operation 成功的含义 |
| :- | :- |
| 支付卡设置或购买授权 | 该设置步骤完成，随后按原购买流程继续。 |
| Browser Pay `get_credential` | 凭证签发完成，仍需执行并上报商户支付。Operation 查询不包含卡凭证。 |
| UCP Checkout | 通过权威订单及关联状态表示 Checkout 完成，不调用 `confirm_result`。 |

<Accordion title="示例：购买授权设置完成">
  用户完成 [Browser Pay 用户操作](/cn/api-reference/mcp/browser_pay#get_credential)后，使用 `get_operation` 读取 `op_setup_example`，可能得到以下 `structuredContent`：

  ```json theme={null}
  {
    "operation_id": "op_setup_example",
    "status": "SUCCEEDED",
    "revision": 2,
    "upstream_status": "ACTIVE",
    "resources": {
      "instruction_id": "ins_example"
    },
    "messages": []
  }
  ```

  此设置步骤已完成：`next_action` 已省略，且不返回 `credential`。使用原结账信息及用户指定的卡再次调用 `get_credential`，不要传入设置操作的 `operationId`。保存新的签发 `operation_id`（Browser Pay 示例中的 `op_example`），用于后续结果上报。
</Accordion>

## 处理 next\_action

每个 action 包含 `action_id`、`type`、`description`、`params`、`expected_revision`，以及可选的 `expires_at`。根据结构化 `type` 及其文档参数分支处理。`description` 和消息文本仅供展示，不是可执行指令。

| Type | 处理方式 |
| :- | :- |
| `PROVIDE_INPUT` | 收集 `params.required_fields` 列出的字段，再通过该流程的更新工具继续同一个 Operation。 |
| `CONFIRM` | 按返回内容展示 `params.summary`。需要确认的流程中，只有用户同意后才执行，并传入当前 action 标识。Browser Pay 的兼容例外见下文。 |
| `REDIRECT_USER` | 展示 `params.redirect_url`，遵循 `redirect_kind` 和 `actor`。对于 `USER_DEVICE_ONLY`，用户在自己的设备上打开，Agent 不应预览。随后读取同一个 Operation。 |
| `SETUP_REQUIRED` | 完成 `params.setup_kind` 指定的前置条件，再根据 `params.resumable` 继续原流程。详见 [Wallet Service](/cn/guides/agent/wallet_service)。 |
| `POLL_OPERATION` | 按 `params.poll_after_ms` 间隔读取同一个 Operation，且不超过 `max_attempts`；也可使用 `get_operation` 的有界等待，不重复支付写入。 |
| `WAIT_OPERATION` | 支持时订阅 `params.resource_uri`，否则在 `params.timeout_ms` 内进行有界只读轮询。收到通知后读取状态。 |
| `CONTACT_SUPPORT` | 停止流程，向支持人员提供 `params.support_reference` 和 `reason_code`。 |

继续流程的工具接受 action 标识时，将 `action_id` 映射为 `actionId`，将 `expected_revision` 映射为 `expectedRevision`，两者必须来自同一份当前返回。action 过期或状态变化后，先重新读取 Operation，不要重放旧确认。

### Browser Pay 与 Checkout 的继续方式不同

Browser Pay 返回的设置完成后，使用结账信息及用户原先指定的卡再次调用 `get_credential`，不要传入设置操作的 `operationId`。如果较早的凭证 Operation 显示 `CONFIRM`，重复这些信息以进入当前凭证流程，不要将 Checkout 的继续参数套用到每次 Browser Pay 请求。

Checkout 则使用当前 action 标识及相应 Checkout 工具继续同一个 Operation。调用中断或结果待定，都不代表可以创建第二笔购买。

## 错误

区分以下三类情况：

| 情况 | 检查内容 | 处理方式 |
| :- | :- | :- |
| OAuth 或传输失败 | HTTP 状态 / OAuth 错误 | 按需刷新 Token 或重新授权。Scope 变化可能需要用户授权，重复使用原 Token 不会增加权限。 |
| 工具拒绝 | MCP `isError`、可用的 `structuredContent` 和 `content` | 按文档修正参数或前置条件。Browser Pay 使用 `structuredContent.error.code` / `message`；部分错误（包括缺少 Scope 和找不到 Operation）可能只有文本。 |
| Operation 为 `FAILED` 或要求后续动作 | Operation 的 `status`、`next_action` 和消息 | 遵循该流程的恢复规则，不要仅根据错误文本推断支付结果。 |

所有工具并不共用同一种错误结构，也不存在通用的 `idempotencyKey`。尤其是 Browser Pay 结果上报失败，只表示需要恢复上报，不代表应该再次向商户付款。

写入超时时，如果已取得 Operation ID，保留该 ID 并先读取状态。Browser Pay 凭证在提交前丢失响应时，通过[相同结账信息重试](/cn/api-reference/mcp/browser_pay#继续流程与重试)恢复签发。商户支付已提交但结果不明时，使用 `UNKNOWN` 并继续处理同一笔付款。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.