@itpay/cli 2.0.14 → 2.0.16

package/docs/cli-reference/commands/install.md

@@ -4,9 +4,9 @@
 
 ## 范围与意义
 
-读取当前 CLI 内置的 Agent Type 安装合同。它只说明 npm 安装、默认 API、默认 Host 和下一条验证命令；不修改宿主配置、不登记设备，也不调用 Backend。
+读取当前 CLI 内置的 Agent Type 运行合同。它只说明默认 API、默认 Host 和下一条验证命令；不安装 CLI、不修改宿主配置、不登记设备，也不调用 Backend。
 
-**上游：** 安装或更新 `@itpay/cli`。
+**上游：** 当前 npm CLI 或平台 bundle 已经可执行。
 
 **下游：** 使用真实 Agent Type 执行 `readyz`，随后读取完整 Skill 和 Catalog。
 
@@ -18,10 +18,10 @@ itpay install [target] [--json]
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `target` | 否 | 五种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
+| `target` | 否 | 七种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
 | `--json` | 否 | 返回标准命令 envelope；推荐 Agent 使用。 |
 
-正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`。
+正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw`。
 
 ## 指定 Agent Type 输出
 
@@ -31,28 +31,53 @@ itpay install [target] [--json]
   "result": {
     "agent_type": "codex-desktop",
     "default_host": "codex",
-    "default_api": "https://app.itpay.ai",
-    "install_command": "npm install -g @itpay/cli"
+    "default_api": "https://app.itpay.ai"
   },
   "instruction": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
   "next": {
     "command": "itpay --agent-type codex-desktop readyz --json",
-    "reason": "验证固定生产 ItPay API 的可用性"
+    "reason": "验证当前官方 ItPay API 的可用性"
   },
   "recovery": [
     {
       "command": "itpay docs show install-and-setup",
-      "reason": "查看固定生产后端和首次使用说明"
+      "reason": "查看官方 Backend 和首次使用说明"
     }
   ]
 }
 ```
 
-`result` 是客观安装事实；`instruction` 只解释当前 Agent Type 的展示责任；`next` 只有一条可执行验证命令。
+`result` 是客观运行时事实；`instruction` 只解释当前 Agent Type 的展示责任；`next` 只有一条可执行验证命令。任何 target 都不得返回 npm 安装命令。
+
+OpenClaw 额外明确没有默认入口：
+
+```json
+{
+  "status": "instructions_ready",
+  "result": {
+    "agent_type": "openclaw",
+    "default_host": null,
+    "host_required": true,
+    "native_hosts": ["telegram"],
+    "default_api": "https://app.itpay.ai"
+  },
+  "instruction": "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
+  "next": {
+    "command": "itpay --agent-type openclaw readyz --json",
+    "reason": "验证当前官方 ItPay API 的可用性"
+  },
+  "recovery": [
+    {
+      "command": "itpay docs show install-and-setup",
+      "reason": "查看官方 Backend 和首次使用说明"
+    }
+  ]
+}
+```
 
 ## 列表输出
 
-省略 target 或传 `list` 时返回五组 `agent_type/default_host`，不重复每种类型的完整 instruction：
+省略 target 或传 `list` 时返回七组运行时定义，不重复每种类型的完整 instruction：
 
 ```json
 {
@@ -63,7 +88,14 @@ itpay install [target] [--json]
       { "agent_type": "codex-cli", "default_host": "terminal" },
       { "agent_type": "claude-code-desktop", "default_host": "claude-code" },
       { "agent_type": "claude-code-cli", "default_host": "terminal" },
-      { "agent_type": "workbuddy", "default_host": "plain-chat" }
+      { "agent_type": "workbuddy", "default_host": "plain-chat" },
+      { "agent_type": "kimi-code", "default_host": "terminal" },
+      {
+        "agent_type": "openclaw",
+        "default_host": null,
+        "host_required": true,
+        "native_hosts": ["telegram"]
+      }
     ]
   },
   "instruction": "选择当前真实运行环境；同一 Agent 不要临时更换 Agent Type。",
@@ -86,6 +118,8 @@ itpay install [target] [--json]
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止，不切换 Node、不删除 identity、不处理 lock。Checkout 返回 `qr_image_url` 时按 instruction 调用 `present_files`。 |
+| `kimi-code` | `terminal` | 使用标准 CLI 流程和终端展示，不增加 Kimi 专属命令。 |
+| `openclaw` | 无 | 必须显式提供当前入口；Telegram 使用原生 action，其他入口展示标准二维码和链接。 |
 
 显式 `--host` 可以在后续 commerce 命令覆盖默认 Host，但不会改变 Agent Type 或设备归属。
 
@@ -102,7 +136,7 @@ itpay install [target] [--json]
     "code": "unsupported_agent_type",
     "message": "unsupported install target: codex"
   },
-  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy。",
+  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, kimi-code, openclaw。",
   "next": null,
   "recovery": [
     {

package/docs/cli-reference/commands/next.md

@@ -86,4 +86,4 @@ Checkout 句柄返回：
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的状态、instruction 和下一步完全相同。本命令不产生二维码或 Host handoff。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的状态、instruction 和下一步完全相同。本命令不产生二维码或 Host handoff。

package/docs/cli-reference/commands/readyz.md

@@ -4,9 +4,9 @@
 
 ## 范围与意义
 
-检查固定生产 Backend `https://app.itpay.ai` 是否可用。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
+检查当前官方 Backend 是否可用。默认使用生产环境 `https://app.itpay.ai`；仅测试时可通过 `ITPAY_BACKEND_URL=https://dev.itpay.ai` 选择官方开发环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
 
-**上游：** CLI 安装；Backend 固定为 `https://app.itpay.ai`，不可由运行时环境覆盖。
+**上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 或 `https://dev.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
 **下游：** 完整 `itpay` Skill，随后选择 Agent Type 或进入当前已支持的 Buyer Catalog。
 
 ## 语法与参数
@@ -24,42 +24,93 @@ itpay readyz [--json]
 ```json
 {
   "status": "ready",
-  "result": { "backend": "available" },
+  "result": { "backend": "available", "backend_url": "https://app.itpay.ai", "environment": "production" },
   "instruction": "ItPay 可用；先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。sell 将来也使用同一入口，但当前尚未实现。",
   "next": { "command": "itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
   "recovery": []
 }
 ```
 
+开发环境返回同一 envelope，但明确标记环境并在每个后续命令中保留 dev Backend：
+
+```json
+{
+  "status": "ready",
+  "result": { "backend": "available", "backend_url": "https://dev.itpay.ai", "environment": "development" },
+  "instruction": "ItPay dev 可用；后续必须执行返回的完整命令，并继续使用同一个 dev Backend。先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。",
+  "next": { "command": "ITPAY_BACKEND_URL=https://dev.itpay.ai itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
+  "recovery": []
+}
+```
+
 ## 异常处理
 
-连接失败时返回 `backend_unavailable`，要求等待 `https://app.itpay.ai` 恢复后重试同一命令，不得切换后端或继续下单。
+连接失败时返回 `backend_unavailable`，要求等待当前官方 Backend 恢复后重试同一完整命令，不得在失败时切换环境或继续下单。
+
+非官方 URL 返回 `backend_override_forbidden`，且不提供自动 recovery：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "backend_override_forbidden",
+    "message": "ITPAY_BACKEND_URL only supports https://app.itpay.ai or https://dev.itpay.ai"
+  },
+  "instruction": "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://dev.itpay.ai。",
+  "next": null,
+  "recovery": []
+}
+```
 
-CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不匹配时，返回一个可执行且版本固定的恢复动作：
+CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不匹配时，返回一个可执行且版本固定的分发专属恢复动作。npm CLI 示例：
 
 ```json
 {
   "status": "error",
   "error": {
     "code": "backend_contract_incompatible",
-    "message": "CLI 2.0.14 contract sha256:client is incompatible with platform v3.example contract sha256:server (minimum CLI 2.0.15, maximum major 2)"
+    "message": "CLI 2.0.15 contract sha256:client is incompatible with platform v3.example contract sha256:server (minimum CLI 2.0.16, maximum major 2)"
   },
   "result": {
-    "current_cli_version": "2.0.14",
-    "required_cli_version": "2.0.15"
+    "current_cli_version": "2.0.15",
+    "required_cli_version": "2.0.16"
   },
   "instruction": "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。",
   "next": null,
   "recovery": [
     {
-      "command": "npm install -g @itpay/cli@2.0.15",
+      "command": "npm install -g @itpay/cli@2.0.16",
       "reason": "安装 Backend 指定的兼容 CLI 版本"
     }
   ]
 }
 ```
 
-只允许使用 Backend 返回的 `minimum_cli_version` 生成精确 npm 版本。兼容性合同不可用、缺少合法版本或仅有无法验证的错误文本时，仍须停止且不得猜测安装版本。
+OpenClaw bundle 的同一错误改为：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "backend_contract_incompatible",
+    "message": "<same compatibility fact>"
+  },
+  "result": {
+    "current_cli_version": "2.0.15",
+    "required_cli_version": "2.0.16"
+  },
+  "instruction": "当前 OpenClaw Skill bundle 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，更新 Skill 后启动新会话并确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要运行 npm、切换 Agent Type 或删除 Device 身份。",
+  "next": null,
+  "recovery": [
+    {
+      "command": "openclaw skills update itpay",
+      "reason": "更新包含 Backend 指定 CLI 版本的 ItPay Skill bundle"
+    }
+  ]
+}
+```
+
+Kimi bundle 使用其 plugin 更新入口，不返回 npm 命令。只允许使用 Backend 返回的 `minimum_cli_version` 生成精确版本要求；兼容性合同不可用、缺少合法版本或仅有无法验证的错误文本时，仍须停止且不得猜测安装版本。
 
 ## Agent Type / Host
 

package/docs/cli-reference/commands/refund/cancel.md

@@ -61,4 +61,4 @@ itpay refund cancel <refund_request_id> [--reason <reason>] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的业务字段、instruction 和 recovery 相同；该命令没有二维码或宿主渲染差异。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的业务字段、instruction 和 recovery 相同；该命令没有二维码或宿主渲染差异。

package/docs/cli-reference/commands/refund/create.md

@@ -84,4 +84,4 @@ CLI 使用 Device Authority 或已有 Buyer bearer，并用订单+原因生成
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 使用相同 Device Authority、退款政策和输出。未绑定订单时不得改用新 Device ID、Buyer ID 或开发者权限绕过 Owner 鉴权。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 使用相同 Device Authority、退款政策和输出。未绑定订单时不得改用新 Device ID、Buyer ID 或开发者权限绕过 Owner 鉴权。

package/docs/cli-reference/commands/refund/index.md

@@ -32,4 +32,4 @@ itpay refund --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种类型使用同一签名 Device Authority 和退款状态机；Host 不影响退款资格。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种类型使用同一签名 Device Authority 和退款状态机；Host 不影响退款资格。

package/docs/cli-reference/commands/refund/list.md

@@ -67,4 +67,4 @@ itpay refund list --order <order_id> [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的业务字段、instruction 和 next 完全相同；本命令没有 Host 渲染差异。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的业务字段、instruction 和 next 完全相同；本命令没有 Host 渲染差异。

package/docs/cli-reference/commands/services/action.md

@@ -47,4 +47,4 @@ rank 不存在、属于旧结果集或其他 Execution、action 不允许、stat
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。

package/docs/cli-reference/commands/services/checkout.md

@@ -34,7 +34,7 @@ itpay services checkout <service_execution_id> --resume
     "locked_input": { "<required_key>": "<value>" },
     "amount": "<amount> <currency>"
   },
-  "handoff": { "url": "<checkout_url>", "qr_local_path": "<desktop_optional_path>", "qr_image_url": "<workbuddy_optional_absolute_https_png>", "markdown": "<desktop_optional_markdown>" },
+  "handoff": { "url": "<checkout_url>", "qr_local_path": "<desktop_optional_path>", "qr_image_url": "<chat_optional_absolute_https_png>", "markdown": "<desktop_optional_markdown>", "agent_action": "<openclaw_telegram_optional_native_message_action>" },
   "instruction": "<exact_agent_type_instruction>",
   "next": { "command": "itpay checkout --id <checkout_id> --token <display_token> --json", "reason": "仅在用户完成付款操作或要求查询后，读取同一 Checkout 的权威状态" },
   "recovery": []
@@ -82,6 +82,8 @@ itpay services checkout <service_execution_id> --resume
 | `claude-code-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
 | `claude-code-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
 | `workbuddy` | `handoff={url,qr_image_url?}`；有 `qr_image_url` 时读取完整值并作为 `files` 数组唯一元素调用 `present_files`；没有时直接发送金额与 `url`，不得调用 `present_files`。两者随后都停止，不得检查或生成本地文件。 |
+| `kimi-code` | `handoff={url}`；复用标准 CLI 终端展示。 |
+| `openclaw` | 必须显式传 Host；Telegram 还必须传 Target，并返回原生 `message` action；其他入口返回标准 `url,qr_image_url`。 |
 
 WorkBuddy 的准确 instruction 语义必须完整包含：
 
@@ -90,3 +92,5 @@ Backend 尚未确认付款。读取 handoff.qr_image_url 的完整字符串，
 ```
 
 若 `qr_image_url` 缺失，准确 instruction 必须改为：说明本次没有可展示二维码，发送金额与 `handoff.url`，明确不要调用 `present_files`，然后遵守相同停止和付款证明规则。
+
+OpenClaw 的 Host/Target 校验必须发生在读取 execution 后、创建 Checkout 前；校验失败不能调用 Checkout 创建接口。Telegram `agent_action` 的 URL action 使用 Checkout URL，callback 只包含 Checkout ID，不包含 display token，也不是付款证明。

package/docs/cli-reference/commands/services/events.md

@@ -72,4 +72,4 @@ CLI 只投影：`sequence`、`type`、`status`、`phase`、可选 `capability_id
 
 ## Agent Type / Host
 
-五种正式 Agent Type 的事件字段、鉴权和 redaction 完全相同；Host 不影响可见性，也不产生 handoff。
+七种正式 Agent Type 的事件字段、鉴权和 redaction 完全相同；Host 不影响可见性，也不产生 handoff。

package/docs/cli-reference/commands/services/get.md

@@ -65,4 +65,4 @@ execution 不存在或不属于当前身份时保留不透明 `not_found`，只
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的状态、timeline、instruction 和 next 相同。本命令没有二维码或 Host handoff。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的状态、timeline、instruction 和 next 相同。本命令没有二维码或 Host handoff。

package/docs/cli-reference/commands/services/index.md

@@ -44,4 +44,4 @@ itpay services --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 共享状态机；Agent Type 只影响身份归属和 Host instruction，不允许影响 quota 规则或服务能力。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 共享状态机；Agent Type 只影响身份归属和 Host instruction，不允许影响 quota 规则或服务能力。

package/docs/cli-reference/commands/services/invoke.md

@@ -152,4 +152,4 @@ Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。

package/docs/cli-reference/commands/services/list.md

@@ -60,4 +60,4 @@ itpay services list [--limit <number>] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 返回相同列表格式；Agent instance 权限决定可见范围。本命令没有 Host handoff。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回相同列表格式；Agent instance 权限决定可见范围。本命令没有 Host handoff。

package/docs/cli-reference/commands/services/read-result.md

@@ -97,4 +97,4 @@ itpay services next <id> --json
 
 ## Agent Type / Host
 
-同一 Buyer account 下已登记的 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 可按政策领取同一订单授权；每个类型仍需自己的有效 Device Authority。五种类型返回相同字段、TTL 和错误，不因 Host 扩大 grant scope。
+同一 Buyer account 下已登记的 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 可按政策领取同一订单授权；每个类型仍需自己的有效 Device Authority。七种类型返回相同字段、TTL 和错误，不因 Host 扩大 grant scope。

package/docs/cli-reference/conventions.md

@@ -6,6 +6,12 @@
 
 CLI 输出是给 Agent 执行的协议，不是后端 DTO 的调试转储。默认输出适合人阅读；`--json` 使用同一语义的稳定机器合同。调试事实只由明确的诊断命令返回。
 
+## 命令变更交付顺序
+
+任何命令行为或 JSON 合同变更都必须先更新对应 CLI reference 和打包 Agent 文档，再从文档补测试和实现代码。最后实际执行文档中的命令，只标准化动态 ID、token、签名 URL 和时间戳，逐字段核对输出。
+
+实际输出不符合文档时先修实现。若产品合同确实要变，必须先重新修改并审查文档，不能用事后改文档掩盖实现偏差。
+
 ## 标准 JSON 外壳
 
 ```json
@@ -74,7 +80,7 @@ next: <one command>
 - `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
 - WorkBuddy 在运行会持久化 `~/.itpay-v3` 的 ItPay Bash 命令前，必须把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`。若用户拒绝该权限，命令尚未执行：停止并报告，不得切换 Node、删除 identity、手工处理 lock 或换 Agent Type。
 - `provider_input_rejected` 只表示 Provider 明确声明输入无效；`provider_contract_mismatch` 表示响应无法按已发布契约解释，绝不能归咎于用户输入。两者都必须停止且没有自动 recovery。
-- `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供一个精确的 `npm install -g @itpay/cli@<version>` recovery。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
+- `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供升级 recovery。npm 分发返回精确的 `npm install -g @itpay/cli@<version>`；平台 bundle 返回该平台的 Skill/plugin 更新动作。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
 
 ## Instruction 模板
 

package/docs/skill-bundle-rollout/01-mcp-authentication.md

@@ -0,0 +1,256 @@
+# 核心任务一：MCP 专用认证系统
+
+状态：待实施
+
+## 1. Current State
+
+### CLI Device Authority
+
+当前 `src/state/device_authority.ts`：
+
+- 每个本地安装生成一把 Ed25519 私钥。
+- 私钥和 Device 状态存放在 `~/.itpay-v3/device`，owner-only 权限。
+- 一个 production Device registration 下按 `agent_type` 建立 Agent Instance。
+- CLI 通过 challenge 签名取得短期 Device session。
+- 受保护请求使用 `Authorization: ItPayDevice ...` 加请求签名。
+- session 失效只续期一次；已撤销的 v2 registration 不会静默替换。
+
+这套系统回答的是“哪个本地 Agent 设备在调用”，不是“哪个付费用户连接了 MCP”。
+
+### Buyer Bearer
+
+`src/state/config.ts` 可以从 `ITPAY_BEARER_TOKEN` 读取账号 Bearer token，供 `orders` 等账号范围命令使用。它是外部注入能力，不是平台 OAuth 连接系统，不应直接扩展成把 token 写进 Skill bundle。
+
+### 问题
+
+云端 Chat 平台不能稳定访问用户电脑上的 `~/.itpay-v3`。即使 Skill 在沙箱里写出同名目录，那也是平台执行容器的临时身份，不是用户本机身份，也不能作为订阅、订单或支付权限的长期主键。
+
+## 2. Target Behavior
+
+新增远程 MCP OAuth 通道：
+
+```text
+Platform -> OAuth authorize -> ItPay login/consent
+         <- authorization code
+Platform -> token endpoint (code + PKCE)
+         <- access token + refresh token
+Platform -> MCP tool + Bearer access token
+MCP      -> validate issuer/audience/scope/expiry
+MCP      -> principal.user_id
+Backend  -> account/entitlement/order authorization
+```
+
+完成后：
+
+- MCP 通过 ItPay 用户身份追踪收费、套餐、订单与权限。
+- CLI 继续通过 Device Authority 追踪本地 Agent 设备和 Agent Instance。
+- 用户可以显式把 Device 关联到同一 ItPay account，但关联不改变认证方式。
+- 两套 token 具有不同 issuer/audience、Header scheme、存储位置和撤销域。
+- 后端授权逻辑接收统一 principal，但不混淆 principal 类型。
+
+不应该改变：
+
+- 现有 CLI 私钥位置、Device 注册协议、签名格式和一次性 session 恢复规则。
+- 默认 `https://app.itpay.ai`，且仅允许准确 `https://dev.itpay.ai` 测试 override 的官方 Backend 规则。
+- Checkout 外部人类确认和服务端支付状态权威性。
+
+## 3. Scope
+
+### In scope
+
+- ItPay OAuth Authorization Server 所需的 authorize、token、refresh、revoke 和 metadata。
+- MCP resource server 的 Bearer token 验证。
+- PKCE、state、精确 redirect URI、scope、audience、过期和撤销。
+- OAuth subject 到现有 ItPay `user_id` 的映射。
+- 平台 OAuth client/connection 记录。
+- MCP 工具级 scope 与敏感写操作确认策略。
+- CLI Device 与用户账号的可选显式关联。
+- 审计日志、最小化返回、测试账号和平台审核所需演示凭据。
+
+### Out of scope
+
+- 重写 CLI Device Authority。
+- 让 MCP 读取或迁移本地 Device 私钥。
+- 让平台 Access Token 代替支付确认。
+- 在聊天内容中采集支付卡、支付密码、验证码、钱包私钥。
+- 为每个平台建立独立 ItPay 用户表。
+
+## 4. 认证边界
+
+### Principal 类型
+
+后端至少明确区分：
+
+```ts
+type Principal =
+  | { kind: "device"; deviceId: string; agentInstanceId: string; agentType: string }
+  | { kind: "user"; userId: string; oauthClientId: string; scopes: string[] };
+```
+
+不要求实际代码使用这个 TypeScript 类型，但授权层必须保留等价区分。禁止根据“有 Authorization Header”就把两者当成同一种账号。
+
+### Header 与 audience
+
+| 通道 | Header | audience | 用途 |
+| --- | --- | --- | --- |
+| CLI | `Authorization: ItPayDevice <session>` + 签名 Headers | Device API | 本地设备、Agent Instance、设备额度与执行 |
+| MCP | `Authorization: Bearer <oauth_access_token>` | ItPay MCP resource | 用户账号、套餐、订单和 MCP 工具 |
+
+Bearer token 不能被 CLI Device middleware 接受；Device session 不能被 MCP middleware 接受。鉴权失败返回 401，授权不足返回 403，不做静默降级。
+
+### 服务端身份关系
+
+建议关系而非第二套用户系统：
+
+```text
+itpay_users
+  id
+
+oauth_clients
+  client_id
+  platform
+  redirect_uris
+  status
+
+oauth_grants
+  user_id -> itpay_users.id
+  client_id -> oauth_clients.client_id
+  scopes
+  revoked_at
+
+agent_devices
+  optional_linked_user_id -> itpay_users.id
+```
+
+Access token 的 `sub` 是稳定、不可猜测的 ItPay 用户 subject。若需要减少跨客户端关联，应使用 pairwise subject，并在服务端映射回同一 `user_id`；不要把 email、ChatGPT 用户名或平台会话 ID 当主键。
+
+## 5. Implementation Steps
+
+### Step 1：冻结现有 CLI 认证合同
+
+依赖：无。
+
+- 为现有 Device enrollment、session、请求签名、401 单次恢复补齐合同测试。
+- 记录 Device API 可访问的路由集合。
+- 确认 MCP 改动不会修改 `src/state/device_authority.ts` 的持久化 schema。
+
+完成条件：加入 MCP 中间件前后，现有 CLI 测试结果和本地身份文件保持一致。
+
+### Step 2：定义 OAuth issuer 和 MCP resource
+
+依赖：Step 1。
+
+- 选择正式 issuer，例如 `https://auth.itpay.ai`；若沿用 `app.itpay.ai`，也必须保持独立 OAuth 路径和密钥用途。
+- 发布标准 Authorization Server metadata 和 MCP Protected Resource metadata。
+- 明确 production MCP URL、resource audience、redirect URI 注册规则和允许的平台 client。
+- Authorization Code 必须使用 PKCE；禁止 implicit flow 和 Resource Owner Password flow。
+
+完成条件：平台可以发现授权端点，redirect URI 不能通配，code 只能使用一次且短期有效。
+
+### Step 3：实现登录、同意和 token 生命周期
+
+依赖：Step 2。
+
+- 用户在 ItPay 页面完成登录；平台不能代收 ItPay 密码。
+- consent 页面展示 client、scope、数据用途和撤销入口。
+- access token 短期有效；refresh token 轮换并检测重放。
+- 支持单 grant 撤销、全设备/全连接撤销和用户主动断开平台。
+- 密钥轮换保留合理验证窗口；日志不记录原始 token 或 authorization code。
+
+完成条件：登录、刷新、过期、撤销、重放和错误 redirect URI 均有自动测试。
+
+### Step 4：在 MCP 服务建立认证和工具授权
+
+依赖：Step 3。
+
+- MCP 入口只接受匹配 issuer、audience、签名、有效期和未撤销 grant 的 Bearer token。
+- 每个工具声明并验证最小 scope。
+- 只读工具与创建 Checkout、退款等写工具分开。
+- 敏感写工具保留平台确认和 ItPay 服务端幂等键。
+- 工具响应去掉 token、内部用户 ID、Device ID、调试 payload 和不必要个人数据。
+
+建议第一版 scope：
+
+| Scope | 能力 |
+| --- | --- |
+| `catalog:read` | 浏览公开目录 |
+| `checkout:write` | 创建或恢复当前用户的 Checkout handoff |
+| `orders:read` | 读取当前用户订单摘要 |
+| `refunds:write` | 按既有退款政策发起退款请求 |
+
+不要第一版就增加通配 scope。
+
+完成条件：越权工具返回 403；不能通过参数替换其他用户 ID；写操作保持幂等。
+
+### Step 5：关联账号而不合并凭据
+
+依赖：Step 3、Step 4。
+
+- MCP OAuth grant 直接绑定 ItPay `user_id`。
+- 本地 Device 若需要账号能力，通过网页显式关联到同一 `user_id`。
+- 关联只写服务端关系，不把 OAuth refresh token 写入 `~/.itpay-v3/device`，也不把 Device 私钥传到服务端或 MCP。
+- 解除关联不删除 Device 身份；撤销 OAuth 不删除 Device registration。
+
+完成条件：分别撤销任一通道不会破坏另一通道；同一用户的订单权限由服务端政策决定。
+
+### Step 6：平台审核材料与运维
+
+依赖：Step 4。
+
+- 建立无 MFA、无短信/邮件确认、无内网依赖的审核测试账号，仅含固定测试数据和限额。
+- 准备 privacy policy、terms、support、数据删除和撤销说明。
+- 记录 client、user、tool、scope、结果和 request ID；不记录 secret。
+- 对 token 签发、失败登录、撤销、敏感工具建立告警。
+
+完成条件：审核者可以独立完成正向和负向测试；运营可以按 user/client 撤销连接。
+
+## 6. API / Data / Type Changes
+
+预计涉及，具体路由名在服务端仓库调研后确定：
+
+- OAuth metadata、authorize、token、revoke 端点。
+- MCP protected resource metadata。
+- OAuth client、grant、refresh-token family、consent/audit 数据。
+- 统一但保留 `device`/`user` 区分的 principal 类型。
+- MCP tool scope 和平台 action annotation。
+
+CLI 公共命令和 `~/.itpay-v3/device` schema：无计划变更。
+
+## 7. Tests / Verification
+
+### 单元测试
+
+- PKCE verifier、redirect URI、state、code 单次消费。
+- issuer/audience/scope/expiry/signature/revocation。
+- refresh rotation 和旧 token 重放。
+- Device/Bearer scheme 互相拒绝。
+
+### 集成测试
+
+- 完整 OAuth 登录、MCP 调用、刷新、撤销。
+- 同一 ItPay 用户从两个平台 client 登录。
+- MCP OAuth 登录后，本地 CLI Device ID 和私钥 hash 不变。
+- Device 撤销后 MCP grant 仍按自身状态工作；反向亦然。
+- 订单、Checkout、退款的跨用户越权测试。
+
+### 手动验证
+
+- ChatGPT Connect/Disconnect。
+- 另一个支持远程 MCP OAuth 的平台连接。
+- 本地 CLI 同时运行并完成 `readyz`、目录、Checkout 恢复。
+
+## 8. Risks / Uncertainties
+
+- MCP 服务端代码不在当前 CLI 仓库，本文件定义合同，实施前必须在对应服务端仓库重新追踪现有用户/session 模块。
+- 各平台对动态 client registration、redirect URI 和 token metadata 的细节可能不同；以平台实际连接测试为准。
+- OpenAI 对金融交易和 PCI 数据有额外限制。MCP 只编排外部 Checkout，不把 OAuth 登录等同于付款授权。
+- `ITPAY_BEARER_TOKEN` 的长期定位需要服务端确认；第一版不删除、不重命名，也不让 MCP 依赖该环境变量。
+
+## 9. Checkpoint
+
+本任务不需要改动当前 CLI 身份即可开始。实施时只有以下情况停下确认：
+
+- 现有服务端没有可复用的 ItPay 用户主表；
+- 必须改变 Device principal 或 quota 归属；
+- 需要引入新的支付授权行为；
+- 平台要求与这里冲突的 token 传递方式。