Operation 与恢复

Clink 使用 Operation 描述流程的当前状态和继续所需的操作。账户设置、购买授权、Browser Pay 凭证签发和 UCP Checkout 都可能产生 Operation。发生超时或中断后，应读取当前 Operation，不要假定写入失败后直接重新发起。并非所有工具都返回 Operation。例如 get_skill_manifest 返回规则元数据，钱包查询返回钱包数据，confirm_result 返回 Browser Pay 结果报告。处理结果前，应读取对应工具的 schema。

读取当前业务规则

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

{
  "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。

{
  "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 和绑卡跳转；状态变化时可能提前返回。

{
  "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`。

示例：购买授权设置完成

用户完成 Browser Pay 用户操作后，使用 get_operation 读取 op_setup_example，可能得到以下 structuredContent：

{
  "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），用于后续结果上报。

处理 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。
`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 凭证在提交前丢失响应时，通过相同结账信息重试恢复签发。商户支付已提交但结果不明时，使用 UNKNOWN 并继续处理同一笔付款。

概述

Clink MCP

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

读取当前业务规则

get_skill_manifest

get_operation

Operation envelope

处理 next_action

Browser Pay 与 Checkout 的继续方式不同

错误

​读取当前业务规则

​get_skill_manifest

​get_operation

​Operation envelope

​处理 next_action

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

​错误

读取当前业务规则

get_skill_manifest

get_operation

Operation envelope

处理 next_action

Browser Pay 与 Checkout 的继续方式不同

错误