@itpay/cli 2.1.47 → 2.1.49

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

@@ -113,44 +113,8 @@ OpenClaw 额外明确没有默认入口：
 
 `next` 保持为空，因为 CLI 不能替 Agent 猜测其宿主平台；Agent 必须自行完成这次选择并继续执行，不得把技术选择或命令转交给用户。
 
-## Agent Type / Host
+## 宿主与限制
 
-| Agent Type | 默认 Host | instruction 重点 |
-| --- | --- | --- |
-| `codex-desktop` | `codex` | 桌面对话必须实际展示二维码和付款链接。 |
-| `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
-| `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `workbuddy` | `plain-chat` | 为 `~/.itpay-v3` 申请正常持久化权限；拒绝时报告受阻操作。Checkout 原样执行返回的 `present_files` action，打开渲染后的 Card Link。 |
-| `zcode` | `plain-chat` | Checkout 或授权返回后立即用 ZCode 内置浏览器打开 `handoff.url`；只有浏览器不可用时才展示同一个可点击链接。 |
-| `doubao-work` | `plain-chat` | Checkout 或授权时同时展示 `handoff.url` 和 `handoff.qr_image_url` 两个有标签的官方入口；优先让手机直接打开链接，二维码供保存或另一台设备扫码。 |
-| `kimi-code` | `terminal` | 使用标准 CLI 流程和终端展示，不增加 Kimi 专属命令。 |
-| `openclaw` | 无 | 必须显式提供当前入口；Telegram 使用原生 action，其他入口展示标准二维码和链接。 |
-
-显式 `--host` 可以在后续 commerce 命令覆盖默认 Host，但不会改变 Agent Type 或设备归属。
-
-同一类型的不同窗口、任务和聊天复用当前 Backend 下的同一个 Agent Instance。切换 Backend 会在同一本地私钥下建立独立服务端登记，不会把 dev/test/app 的 Device ID 混用。
-
-## 异常处理
-
-未知 target 返回：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "unsupported_agent_type",
-    "message": "unsupported install target: codex"
-  },
-  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, doubao-work, kimi-code, openclaw。",
-  "next": null,
-  "recovery": [
-    {
-      "command": "itpay install --json",
-      "reason": "列出正式支持的 Agent Type"
-    }
-  ]
-}
-```
+使用当前真实 Agent Type；同类型窗口复用当前 Backend 下的同一实例。显式 host 只改变展示，不改变身份、业务或同意。正式 Skill 与 render-hosts 拥有当前可用展示指引；原生工具不可用时同轮展示原官方URL，不为了图片或按钮反复排障。
 
-错误不会写入本地状态。不要把 `codex`、`terminal` 或 `claude-code` 等 Host 名称当成 Agent Type。
+未知 target 或参数错误按实际返回修正；本命令不写身份。准备设备统一使用 setup，不把 install、readyz、auth status 串成重复初始化链。

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

@@ -48,18 +48,8 @@ itpay orders [--limit <n>] [--status <status>] [--cursor <cursor>] [--host <host
 
 ## Agent 授权缺失
 
-```json
-{
-  "status": "human_authorization_required",
-  "result": { "intent": "list_purchase_history" },
-  "instruction": "需要用户确认一次身份和只读权限；执行 next.command 生成入口。",
-  "next": {
-    "command": "itpay vault access --json",
-    "reason": "创建一次账号读取授权"
-  },
-  "recovery": []
-}
-```
+授权缺失返回 human_authorization_required。上下文完整时只执行当次完整的账号授权 next 一次；缺 host/target 时 next=null，使用返回的不可执行完整模板从当前可信会话补齐，不把通用示例套到所有宿主。真实交付入口后停止，授权不等于购买或付款。
+
 
 用户完成后重新执行原始 `orders` 命令。CLI 不要求 Agent构造或粘贴 Buyer
 token，也不改用 Service Execution 猜测账号历史。
@@ -67,7 +57,7 @@ token，也不改用 Service Execution 猜测账号历史。
 当 `next_cursor` 非空时，`next.command` 使用同一 limit/status 和 Backend 返回的
 cursor 读取下一页。Agent 只在用户需要查看更多订单时执行，不能修改或猜测
 cursor。OpenClaw 的授权下一步必须保留原命令的 `--host` 和所需 `--target`；
-若原命令未提供，CLI 会用明确占位符要求 Agent 从当前可信会话补齐。
+若原命令未提供，next=null，并返回不可执行的完整输入模板，由Agent从当前可信会话补齐。
 
 无匹配订单使用 `status=no_orders`、`orders=[]` 和 `next=null`。无效 limit
 和 status 必须在 HTTP 前返回稳定合同错误。

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

@@ -8,7 +8,7 @@
 
 本命令不能创建 Cart、Checkout、订单或付款证明，也不能把 Payment Intent 的渠道状态当作订单已付款。
 
-**直接上游：** `buy`、`services checkout` 或 `checkout` 返回的同一组 `checkout_id` 与 display token。
+**直接上游：** 当前官方入口或原 `checkout` reader 返回的同一组 `checkout_id` 与 display token。
 
 **直接下游：** `checkout` 读取同一 Checkout 的权威付款、订单和履约状态。
 
@@ -82,29 +82,8 @@ API 安全合同要求后端验证 display token 是该 Checkout 当前有效的
 - `--refresh` 只更新该 Intent 的渠道动作；不能创建第二个 Intent 或 Checkout。
 - 响应丢失时重跑同一命令，不换 token 或 method。
 
-## 异常处理
-
-| 错误码 | Agent 处理 |
-|---|---|
-| `payment_method_invalid` | 改用 `alipay` 或 `wechatpay`；本次没有 HTTP 请求。 |
-| `checkout_token_required` | 从 `itpay next --json` 恢复同一 Checkout；禁止拼接其他 token。 |
-| `target_required` | 为当前 IM Host 补充真实 target。 |
-| `not_found` / token invalid | 视为同一个不透明资源错误，不探测 Checkout 是否属于他人。 |
-| `invalid_state` | 回到 `checkout` 读取当前终态，不创建替代资源。 |
-| `provider_payment_failed` | 保留同一 Checkout，稍后恢复；不声称已付款。 |
-| `payment_intent_failed` | 执行 `itpay next --json` 恢复现有句柄。 |
-
-## Agent Type / Host
-
-| Agent Type | 默认 Host | Instruction |
-|---|---|---|
-| `codex-desktop` | `codex` | 把安全 handoff 实际发到当前 Codex 对话，然后查询 Checkout。 |
-| `codex-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
-| `claude-code-desktop` | `claude-code` | 把安全 handoff 发到当前桌面对话。 |
-| `claude-code-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
-| `workbuddy` | `plain-chat` | 受控逃生入口返回 `handoff.url` 和可原样执行的 `present_files` action；打开一次后停止，不立即查询或创建替代付款。 |
-| `zcode` | `plain-chat` | 受控逃生入口返回 `handoff.url`；同时存在渠道动作时优先使用浏览器可打开的 `qr_image_url`，只有它缺失时才回退到 `mobile_wallet_url`。立即用内置浏览器打开并停止，浏览器不可用时才展示同一个链接。 |
-| `kimi-code` | `terminal` | 使用标准 CLI 终端展示渠道动作。 |
-| `openclaw` | 必须显式提供 | 按显式 Host 返回安全渠道动作；IM Host 仍要求真实 target。 |
-
-Host 只改变 instruction；Payment Intent ID、金额、状态、重试语义和权限必须一致。
+## 保护与展示
+
+仅在有明确授权的受控集成恢复中使用当前返回动作；普通 Agent 不自动调用 pay 或 buy --pay。错误按真实原因及原 Checkout 状态处理，不猜 token、换渠道掩盖未知结果或创建替代资源。
+
+当前 handoff 按正式 Skill 与 render-hosts 展示；没有原生工具或可选图片时直接展示原始官方URL，不把按钮／二维码当付款事实。Host 不改变金额、Payment Intent、权限、幂等和状态保护。

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

@@ -1,69 +1,11 @@
 # `itpay readyz`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The public package provides Buyer workflows; Seller authoring source is maintained separately.
-
-## 范围与意义
-
-检查当前官方 Backend 是否可用。默认使用生产环境 `https://app.itpay.ai`；仅测试时可通过 `ITPAY_BACKEND_URL=https://sandbox.itpay.ai` 选择官方沙箱环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
-
-**上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 、`https://sandbox.itpay.ai` 或 `https://dev.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
-**下游：** 实际宿主已声明时，执行同 Backend/type 的 `setup`；未声明时先 `install` 识别实际宿主。setup 后读取并启用同包 Skill，同版本不重复读取。
-
-## 语法与参数
+只检查官方 Backend 存活，不证明设备、登录或业务合同就绪，也不是业务失败后的必跑排障步骤。
 
 ```bash
 itpay readyz [--json]
 ```
 
-| 参数 | 必填 | 说明 |
-|---|---:|---|
-| `--json` | 否 | 返回标准 JSON。 |
-
-## 标准输出
-
-```json
-{
-  "status": "ready",
-  "result": { "backend": "available", "backend_url": "https://app.itpay.ai", "environment": "production" },
-  "instruction": "ItPay 正式环境 https://app.itpay.ai 可用。只证明后端存活；首次使用或更新后运行 setup，不自动登录或开始业务。",
-  "next": { "command": "itpay install --json", "reason": "识别实际宿主类型后执行 setup" },
-  "recovery": []
-}
-```
-
-沙箱环境返回同一 envelope，但明确标记环境并在每个后续命令中保留 sandbox Backend：
-
-```json
-{
-  "status": "ready",
-  "result": { "backend": "available", "backend_url": "https://sandbox.itpay.ai", "environment": "development" },
-  "instruction": "ItPay 开发环境 https://sandbox.itpay.ai 可用。只证明后端存活；首次使用或更新后运行 setup，不自动登录或开始业务。",
-  "next": { "command": "ITPAY_BACKEND_URL=https://sandbox.itpay.ai itpay install --json", "reason": "识别实际宿主类型后执行 setup" },
-  "recovery": []
-}
-```
-
-## 异常处理
-
-已收到 Backend 不可用响应等非传输异常时返回 `backend_unavailable`。尚未收到完整 HTTP 响应的临时传输失败使用 conventions 中对应的稳定 `network_*` 错误码；`readyz` 是 GET，按全局安全传输合同最多自动重试两次。有限尝试结束后本轮检查未完成，next=null、recovery=[]；网络恢复后可以重新检查，不得在失败时切换环境或继续下单。
-
-非官方 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://sandbox.itpay.ai"
-  },
-  "instruction": "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://sandbox.itpay.ai。",
-  "next": null,
-  "recovery": []
-}
-```
-
-业务命令取得兼容性合同但不匹配时，返回 `backend_contract_incompatible`；readyz 本身只证明存活。输出保留 `current_cli_version`、`current_api_contract_revision`、`platform_api_contract_revision`、`minimum_cli_version`、`maximum_cli_major`。minimum 是协议门槛，不是推荐制品。所有分发渠道均停止本轮、next=null、recovery=[]，由维护方提供已核验的配套制品；不要猜版本、降级或改变身份。
-
-## Agent Type / Host
+生产默认 app.itpay.ai，明确测试可选择 sandbox.itpay.ai 或 dev.itpay.ai；不切环境掩盖失败。返回 backend、backend_url、environment；声明 Agent Type 时保留该事实。首次安装或升级后用当前宿主的 setup，之后读取同包Skill。
 
-本命令不渲染 Host 内容。若已声明 Agent Type，`result.agent_type` 会确认该类型，且返回的 `setup` 命令保留同一 `--agent-type` 与 Backend；未声明时返回 `install`。只有 authenticated 或成功 login_required 才证明设备可用，后者不代表已登录。权限拒绝或未知状态停止准备，不宣称 ready。
+不可用、网络或兼容问题按当次错误说明处理；有限尝试结束即停止，不循环检测、不登录或下单。minimum_cli_version 是协议门槛，不是已验证推荐包；兼容失败须维护方提供配套制品，不猜版本、不降级、不改身份。文本和JSON相同，不输出凭据。

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

@@ -37,27 +37,7 @@ itpay refund cancel <refund_request_id> [--reason <reason>] [--json]
 }
 ```
 
-不可取消时输出到 `stderr` 并以非零状态退出：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "refund_cancellation_too_late",
-    "message": "refund cancellation is too late"
-  },
-  "instruction": "取消未生效；以 Refund Owner 当前状态为准，不要重复退款或自行解除交付锁。",
-  "next": null,
-  "recovery": [
-    {
-      "command": "itpay refund get <refund_request_id> --json",
-      "reason": "读取当前权威状态"
-    }
-  ]
-}
-```
-
-出现 `not_found` 时同样只恢复到同一退款的 `refund get`，不借错误差异探测其他账号。取消成功只恢复重新申请交付授权的资格；旧 grant 永远不会复活。
+取消是否生效按当次服务端状态说明；结构化错误在当前文本／JSON出口返回，不承诺一定已取消，不重复提交或自行解除锁。取消成功只恢复按当前订单核对权限的资格，旧grant不自动复活。
 
 ## Agent Type / Host
 

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

@@ -7,7 +7,7 @@
 为一笔订单提交退款意图。Refund Owner 从订单推导 Buyer、支付、金额、币种、消费事实和审核策略；Agent 只提交订单和用户原因。
 
 **上游：** `order <id>` 或用户明确提出退款。  
-**下游：** `refund watch <refund_request_id>`，或在 `can_cancel=true` 时由用户选择取消。
+**下游：** 当前返回的同一退款get，按需读取且不自动循环等待，或在 `can_cancel=true` 时由用户选择取消。
 
 退款成功落库与交付冻结是同一事务；CLI 不自行锁单，也不预测自动退款结果。
 
@@ -41,7 +41,7 @@ CLI 使用 Device Authority 或已有 Buyer bearer，并用订单+原因生成
   },
   "instruction": "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不要重复申请、reveal、授权或读取结果。",
   "next": {
-    "command": "itpay refund watch <refund_id> --json",
+    "command": "itpay refund get <refund_id> --json",
     "reason": "跟踪同一退款"
   },
   "recovery": []
@@ -54,33 +54,9 @@ CLI 使用 Device Authority 或已有 Buyer bearer，并用订单+原因生成
 
 重复提交同一活跃退款时 Backend 返回已有请求，不创建第二笔；CLI 继续跟踪该 `refund_request_id`。
 
-## 异常处理
+## 输入与原单保护
 
-缺少 `--order` 时在 HTTP 前返回 `order_required`，要求恢复当前 Service Execution，不猜订单 ID。
-
-订单不可见、已退款、无可退款支付或状态不允许时 fail closed：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "<server_error_code>",
-    "message": "<server reason>"
-  },
-  "instruction": "确认订单属于当前账号且可退款；不要修改金额、支付或消费事实。",
-  "next": null,
-  "recovery": [
-    {
-      "command": "itpay order <order_id> --json",
-      "reason": "检查订单和交付锁"
-    },
-    {
-      "command": "itpay refund list --order <order_id> --json",
-      "reason": "检查已有退款"
-    }
-  ]
-}
-```
+创建来自用户真实退款意图；缺少订单或状态不允许时按当次错误和原订单读取处理，不猜ID、不改变金额或消费事实。技术格式由 Agent 修正，退款范围／选择缺失才问用户。没有当前合法动作就停止，不用新申请掩盖原请求结果未知。
 
 ## Agent Type / Host
 

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

@@ -7,7 +7,7 @@
 读取一笔当前身份可见退款的权威快照、交付锁和可取消性。它只请求一次，不轮询、不改变退款状态。
 
 **上游：** `refund create`、`refund list` 或之前的 `refund watch`。  
-**下游：** 非终态进入 `refund watch`；终态结束；`can_cancel=true` 时用户可另行选择取消。
+**下游：** 非终态按需读取返回的同一退款get，不自动watch；终态结束；`can_cancel=true` 时用户可另行选择取消。
 
 ## 语法与参数
 
@@ -36,7 +36,7 @@ itpay refund get <refund_request_id> [--json]
   },
   "instruction": "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不要重复申请、reveal、授权或读取结果。",
   "next": {
-    "command": "itpay refund watch <refund_id> --json",
+    "command": "itpay refund get <refund_id> --json",
     "reason": "跟踪同一退款"
   },
   "recovery": []
@@ -47,7 +47,7 @@ itpay refund get <refund_request_id> [--json]
 
 ## 终态
 
-- `succeeded`：先告诉用户退款已由 ItPay 确认成功，交付永久关闭，`next=null`。
+- `succeeded`：退款钱款已由ItPay确认成功；按原订单核对实际金额范围、履约和访问锁，不能推断整单全部退款或线下服务已使用，`next=null`。
 - `cancelled/rejected`：说明退款没有执行，交付资格依当前订单和 owner 状态判断；旧 grant 不复活，按返回动作决定是否需要新的授权，`next=null` 时不自行创建。
 - `failed + known_no_effect`：说明退款请求确认未发送；Agent 不重试，由平台管理员决定是否重新执行，`next=null`。
 - `failed + retryable`：说明渠道明确返回可重试失败但 Agent 不会自行重试；等待平台管理员处理，`next=null`。

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

@@ -17,7 +17,7 @@
 - [`refund watch`](watch.md)
 - [`refund cancel`](cancel.md)
 
-兼容别名 `itpay refund --order <id>` 等价于 `refund create`，文档和 instruction 统一推荐子命令形式。
+普通退款统一使用 `refund create` 子命令；铁路退款／改签使用原订单返回的 aftercare 完整模板。
 
 退款创建成功即锁定对应交付；旧 Agent grant 不得继续读取。直接运行无参数 `itpay refund` 显示 help，不创建请求。
 
@@ -32,11 +32,11 @@
 ## 语法、参数与标准输出
 
 ```bash
-itpay refund --order <order_id> [--reason <reason>] [--json]
+itpay refund create --order <order_id> [--reason <reason>] [--json]
 itpay refund --help
 ```
 
-兼容别名的参数、输出、instruction 和异常合同与 [`refund create`](create.md) 完全相同。无 `--order` 时只显示 help 和推荐的 `refund create` 语法，不发送请求。
+创建参数与边界见 refund create；无参数的分组只显示help，不发送请求。
 
 ## Agent Type / Host
 

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

@@ -44,20 +44,7 @@ itpay refund list --order <order_id> [--json]
 
 列表只返回选择退款所需的 ID、状态、金额和创建时间，不返回退款原因、消费证据、Admin 信息或支付渠道元数据。服务端按 `created_at DESC` 排序；CLI 优先引导至第一笔活跃退款，否则引导至最新记录。
 
-无记录时：
-
-```json
-{
-  "status": "empty",
-  "result": { "order_id": "<order_id>", "refunds": [] },
-  "instruction": "该订单没有退款记录；确认用户确实要求退款后再创建。",
-  "next": {
-    "command": "itpay refund create --order <order_id> --json",
-    "reason": "为该订单创建退款"
-  },
-  "recovery": []
-}
-```
+无记录时 status=empty、refunds=[]、next=null。空列表不代表用户已同意退款；只有真实退款请求才按当前订单事实使用完整创建入口，不能自动提交。
 
 ## 鉴权与异常处理
 

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

@@ -4,7 +4,7 @@
 
 ## 范围与意义
 
-轮询同一退款直到终态或 timeout。命令内部可以读取多次，但对外只输出一个最终信封，不把无变化轮询刷入 Agent 上下文。中断后可无副作用重跑。
+有界读取同一退款，直到状态变化、人工／结果未知、终态或 timeout。命令内部可以读取多次，但对外只输出一个最终信封，不把无变化轮询刷入 Agent 上下文。中断后可无副作用重跑。
 
 **上游：** active refund。  
 **下游：** `succeeded`、`failed`、`cancelled`、`rejected` 等终态，或稍后继续 watch。
@@ -19,7 +19,7 @@ itpay refund watch <refund_request_id> [--interval <seconds>] [--timeout <second
 | --- | --- | --- |
 | `refund_request_id` | 无 | 必填。 |
 | `--interval <seconds>` | `2` | 必须至少 1 秒。 |
-| `--timeout <seconds>` | `120` | 必须为正数；可使用小数。 |
+| `--timeout <seconds>` | `20` | 必须为正数；可使用小数。 |
 | `--json` | 关闭 | 输出一个可直接解析的 JSON 信封。 |
 
 非法轮询参数在第一次 HTTP 请求前失败。
@@ -38,7 +38,7 @@ itpay refund watch <refund_request_id> [--interval <seconds>] [--timeout <second
     "access_locked": true,
     "can_cancel": false
   },
-  "instruction": "先告诉用户退款已由 ItPay 确认成功，原交付永久关闭；不需要继续跟踪或重复申请。",
+  "instruction": "先说明本次退款钱款已由ItPay确认成功；按原订单核对实际金额范围、履约及访问锁，不推断整单全部退款，不恢复旧授权或重复申请。",
   "next": null,
   "recovery": []
 }
@@ -46,29 +46,9 @@ itpay refund watch <refund_request_id> [--interval <seconds>] [--timeout <second
 
 其他终态使用与 `refund get` 相同的锁、恢复资格和旧 grant 规则。特别是 `failed` 必须按 `failure_class` 区分 `known_no_effect`、`retryable`、`outcome_unknown` 和 `permanent`；任何一种都不向 Agent 返回重试命令。
 
-## Timeout 输出
+## 等待边界
 
-Timeout 只表示本次 CLI 等待结束，不表示退款失败：
-
-```json
-{
-  "status": "watch_timeout",
-  "result": {
-    "refund_request_id": "<id>",
-    "last_status": "<status>",
-    "access_locked": true,
-    "can_cancel": true
-  },
-  "instruction": "先告诉用户退款仍在处理，Timeout 只表示本次等待结束，并不表示退款失败；稍后继续跟踪同一退款，不要重复申请或承诺结果。",
-  "next": {
-    "command": "itpay refund watch <refund_id> --json",
-    "reason": "恢复轮询"
-  },
-  "recovery": []
-}
-```
-
-网络、ID 或参数错误返回错误信封，并只建议 `itpay refund get <id> --json` 检查当前状态。
+人工审核、outcome_unknown或关键状态变化立即交回权威快照，不继续等待，也不把人工审核覆盖成超时。等待到期只说明本次等待结束；非终态的next只读同一退款一次 get，不自动接力watch。只有用户需要时沿当次条件读取原退款。失败按failure_class保留停止和对账边界，不重复申请或承诺到账。
 
 ## Agent Type / Host
 

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

@@ -1,13 +1,6 @@
 # `itpay services action`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The public package provides Buyer workflows; Seller authoring source is maintained separately.
-
-## 范围与意义
-
-记录用户或 Agent 对 Service Execution 的结构化动作，例如选择候选、批准、拒绝或取消。它不直接调用付费 Provider。
-
-**上游：** `services invoke/next` 返回需要 action。
-**下游：** 候选选择成功时直接进入服务端允许的下一动作；其他动作通过更新后的 `services next` 恢复。
+只记录当前执行明确允许的结构化选择、批准、拒绝或取消，不直接调用付费供应商。使用返回的完整输入模板；真实委托由 Agent 如实转述，不冒充 human。
 
 ## 语法与参数
 
@@ -36,36 +29,14 @@ itpay services action <service_execution_id> --action <action_type>
 | `workflow:expand_search` | 有界新增查询 | 仅在扩展暂停（`expansion_status=paused`）时可用；必须带服务端下发的 `action_request_id`（`pa_…`）与 `expected_query_revision`，一轮一柄、用完作废。 |
 | `workflow:refine_preferences` | 无（本地重排） | 用 `--input-json` 提交偏好补丁，对已保存证据重排序。 |
 | `workflow:stop_search` | 无 | 停止未发送的扩展任务；不影响已开始或已完成的出票。 |
-| `select_journey` | 无 | 用户亲自选定用 `--actor-type human`；用户已明确委托按规则代选用 `--actor-type agent --input selection_mode=delegated`。两者都带服务端返回的 `journey_id`，仅记录选择，后续购买仍走既有报价与受保护 Checkout。 |
+| `select_journey` | 无 | 用户亲自选定用 `--actor-type human`；用户已明确委托按规则代选用 `--actor-type agent --input selection_mode=delegated`。两者都带服务端返回的 `journey_id`，仅记录选择，后续购买使用当前完整 purchase 确认与官方页面。 |
 
 同一 `action_request_id` 相同内容重放返回原受理结果；相同 ID 不同内容会被判冲突。过期 `expected_query_revision` 的新动作被拒绝。
 
-## 标准输出
-
-```json
-{
-  "status": "candidate_selected",
-  "result": {
-    "service_execution_id": "<id>",
-    "candidate": { "rank": 2, "title": "<title>" },
-    "checkout": {
-      "capability_id": "<paid_capability_id>",
-      "price": { "amount_minor": 50, "currency": "CNY" },
-      "delivery_email_required": true
-    }
-  },
-  "instruction": "已选择 <title>。后续服务尚未购买。只向用户说明继续购买的价格和邮箱用途，请确认是否购买并提供邮箱，然后停止。用户明确同意并提供真实邮箱前，Agent 不执行 next.command，也不创建新的服务或付款页面。",
-  "next": { "command": "itpay services checkout <id> --capability <capability_id> --email <email> --json", "reason": "仅在用户明确同意价格并提供真实邮箱后执行" },
-  "recovery": [{ "command": "itpay services next <id> --json", "reason": "重新读取服务端允许的动作" }]
-}
-```
-
-`next` 来自 action 写入后重新读取的类型化 `allowed_actions`，不是 CLI 根据服务名猜测。普通单 Execution 的付费 continuation 使用 `services checkout`；候选选择本身不代表用户已经同意购买。没有合法动作时返回 `next: null`。非候选 action 仍返回 `action_recorded` 并引导 `services next`。
-
-rank 不存在、属于旧结果集或其他 Execution、action 不允许、status 非法时均不写 action；返回结构化错误并且只引导同一 Execution 的 `services next`。不得新建 Execution、重新 invoke 或构造候选 ID。相同候选重试幂等；同一结果集改选另一个候选返回冲突，不覆盖已批准事实。
+## 当前输出与购买
 
-订票类 `workflow:confirm_booking` 动作要求嵌套输入（`passengers`、`seat_type`、逐乘客 `seat_preferences`、`draft_revision`、`notice_version` 等），一律经 `--input-json <file>` 提交完整 JSON 对象。`draft_revision` 必须等于 `services next` 投影的 `context.review.draft_revision`；服务端拒绝 `booking_review_changed` 时重新读取后重试，不得自行递增。乘客姓名、证件号等身份信息不在此提交，仍由受保护 Checkout 页收集。
+候选选择成功时，若当前合同支持购买准备，直接返回原执行的完整 purchase review。已有明确同意覆盖当前主体、范围、人数、价格策略和条款就沿用；仅补缺失同意，不要求重复确认或先给邮箱。联系资料在受保护官方页填写。
 
-## Agent Type / Host
+`next` 必须是当前适用的完整命令；仍有待填字段则是 `executable:false` 的完整 `file_content` 模板。没有合法动作就停止。普通购买不由 Agent 串联 quote、approve、cart 或 services checkout。
 
-所有正式支持的 Local Agent Type 行为相同。真实条款同意仍需人确认；在用户已明确委托选择且规则未变时，Agent 可执行返回的委托选择动作，不得冒充 human。
+同一选择、报价、付款未知和已有批准的幂等保护由服务端执行；不能新建 execution、猜候选ID或覆盖批准事实。订票技术修正使用原 selection 和当前 review；仅代码写法修正且购买内容未变时沿用已有真实同意。草稿实质变化或真实同意缺失才补确认，不自行递增 revision。旅客身份资料只在受保护页面提交。

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

@@ -1,119 +1,22 @@
-# `itpay services checkout`
+# itpay services checkout
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The public package provides Buyer workflows; Seller authoring source is maintained separately.
+恢复已知服务的原 Checkout 时，使用当次返回的具体命令。普通已选服务通过 services purchase 准备官方入口，不手工编排报价和购物车。
 
-## 服务报价的批准边界
+参数以 --help 及当前模板为准。保留同意范围、付款期限和未知结果保护；展示权威原入口，不创建替代购买。缺材料/过期/存储故障按当前返回处理，不自行切换路径。
 
-服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。
-
-## 范围与意义
-
-为单个 Service Execution 快速创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。
-
-未注册/未登录用户不要求先执行 `itpay auth login`（Path B）：官方 checkout 页内完成必要的钱包认证、创建或复用账号并取得页面权限；人在页面上确认旅客、通知联系方式和最终报价后付款。支付确认沿用既有设备绑定机制，不再独立绑定。checkout 内完成账号认证不等于账号已通过手机号验证；钱包显示名、账号手机号与乘车人身份互相独立。
-
-**通知联系方式（铁路单）：** 订单级联系策略要求至少一个可用通道——邮箱，或在 checkout 页内经验证的大陆手机号（order-contact 验证码只校验收件人，不创建/合并登录身份）。有效邮箱即可独立完成 checkout；SMS 不是必填项，SMS 能力未配置时不得阻塞邮箱通道。该策略仅适用于铁路订单，企知道等既有服务的联系策略不变。乘客证件手机号、账号登录手机号与通知收件人是三个独立事实，互不替代。
-
-**上游：** `services next` 返回的 `prepare_quote` capability 和已验证输入。铁路购票执行必须先通过 `workflow:confirm_booking` review（见 `services next` 的 `booking_review_required`），后端才生成可支付报价；review 开放期间不创建 Checkout。
-**下游：** 人完成 Checkout，随后 `checkout` 或 `services next`。
-
-## 语法与参数
-
-```bash
-itpay services checkout <service_execution_id> --capability <capability_id>
-  [--input <key=value> ...] [--email <delivery_email>]
-  [--host <host>] [--target <target>] [--locale <zh-CN|en>]
-  [--qr-format <format>] [--qr-file <path>] [--json]
-
-itpay services checkout <service_execution_id> --resume
-  [--host <host>] [--target <target>] [--locale <zh-CN|en>] [--json]
-```
-
-创建时 `--capability` 必填。最终 locked input 必须满足 capability schema：显式输入来自 `--input`，服务端也可以按已发布 contract 从当前 Execution 的已批准 action 解析输入。解析后仍缺字段时，必须在创建 Quote、Cart 或 Checkout 前失败。只有 `delivery_email_required=true` 才要求 `--email`，并必须先向用户解释邮箱用于发送可 claim 的交付链接。`--resume` 复用同一个 Checkout 并轮换 handoff token，不再索取输入或邮箱。
-
-## 标准输出
-
-```json
-{
-  "status": "human_checkout_required",
-  "result": {
-    "service_execution_id": "<id>",
-    "checkout_id": "<checkout_id>",
-    "capability_id": "<logical_capability_id>",
-    "locked_input": { "<required_key>": "<value>" },
-    "amount": "<amount> <currency>"
-  },
-  "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": []
-}
-```
-
-`capability_id` 是 service contract 中 Agent 可调用的逻辑 ID，不是 `scc_...` 数据库记录 ID。`locked_input` 是后端按 capability policy 最终解析并校验后的输入，不由 CLI 根据服务名称推断。
-
-普通文本输出保持同一事实顺序。桌面 Host 输出可直接转发的 `handoff.markdown`；终端 Host 额外渲染一个可扫码终端二维码；`--json` 不内嵌终端二维码或图片二进制。
-
-不得返回 quote lock、单独 token、重复 next actions、镜像路径数组或渲染器内部原因。缺输入、缺必填邮箱、phase 不允许时不得创建任何付款资源。恢复时 token 失效应重发同一 Checkout handoff，不创建第二个 Checkout。
-
-## 异常处理
-
-缺少付费 capability 输入：
-
-```json
-{
-  "status": "error",
-  "error": { "code": "capability_input_invalid", "message": "missing required capability input: <field>" },
-  "instruction": "补齐付费 capability 的 required_input；本次没有创建 quote、Checkout 或订单。",
-  "next": null,
-  "recovery": [{ "command": "itpay services checkout <service_execution_id> --capability <capability_id> --input <field>=<value> --json", "reason": "提交完整且会被锁定的服务输入" }]
-}
-```
-
-缺少交付邮箱：
-
-```json
-{
-  "status": "error",
-  "error": { "code": "delivery_email_required", "message": "delivery email is required before creating this service checkout" },
-  "instruction": "该 capability 的交付链接会发送到用户邮箱；先向用户说明用途并询问邮箱，不要代填。",
-  "next": null,
-  "recovery": [{ "command": "itpay services checkout <service_execution_id> --capability <capability_id> --email <email> --json", "reason": "使用用户提供的邮箱创建 Checkout" }]
-}
-```
-
-## Agent Type / Host
-
-| Agent Type | Instruction |
-|---|---|
-| `codex-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
-| `codex-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
-| `claude-code-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
-| `claude-code-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
-| `workbuddy` | `handoff={url,agent_action}`；原样执行一次 `present_files(files=[url])` 打开完整渲染的 HTML Card Link，然后停止；不得检查或生成本地文件。 |
-| `zcode` | `handoff={url}`；立即用 ZCode 内置浏览器打开，然后停止；只有浏览器不可用时才展示同一个可点击链接。 |
-| `doubao-work` | `handoff={url,qr_image_url}`；在当前对话中展示手机直达收银台链接和官方二维码图片链接，说明金额后停止。 |
-| `kimi-code` | `handoff={url}`；复用标准 CLI 终端展示。 |
-| `openclaw` | 必须显式传 Host；Telegram 还必须传 OpenClaw 原生 Target，并返回必须原样执行的 `message` action；其他入口返回标准 `url,qr_image_url`。 |
-
-WorkBuddy 的准确 instruction 语义必须完整包含：
+## 当前参数
 
 ```text
-Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
+--capability <capability_id>
+--input <key=value>           input to lock into the paid service quote
+--email <delivery_email>
+--resume                      reissue the existing checkout handoff without
+--host <host>                 client host (terminal, codex, telegram, feishu,
+--target <target>             chat id / channel id / open id for IM hosts
+--qr-format <format>          unicode|utf8|ansi|terminal
+--qr-file <path>              explicit QR file path
+--locale <locale>             payment card language: zh-CN|en (default:
+--json                        output JSON instead of terminal text
 ```
 
-ZCode 的准确 instruction 语义必须完整包含：
-
-```text
-Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
-```
-
-Doubao Work 的准确 instruction 语义必须完整包含：
-
-```text
-Backend 尚未确认付款。在当前豆包工作对话中展示两个有标签的官方入口：将 handoff.url 标为“手机直接打开收银台”，将 handoff.qr_image_url 标为“二维码图片（保存或用另一台设备扫码）”。说明金额后停止等待。不要解析或单独输出 URL credential，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
-```
-
-`--locale` 默认 `zh-CN`，可显式使用 `--locale en`。语言只影响 Card 渲染，不改变 Checkout、付款或恢复状态。
-
-OpenClaw 的 Host/Target 校验必须发生在读取 execution 后、创建 Checkout 前；校验失败不能调用 Checkout 创建接口。Telegram `agent_action.arguments.presentation` 只使用 `blocks.buttons`，其中 `📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用 `value=itp:grant_confirmed:<checkout_id>`。准确 instruction 必须要求 Agent 立即用原生 `message` tool 原样执行 `handoff.agent_action`，不得改写 Presentation、换工具或用普通回复冒充按钮已发送。收到该 callback 表示用户声明已在收银台授权读取；Agent 立即执行 `next.command` 查询同一 Checkout，再只按 Backend 返回的 `next.command` 进入同一 Execution grant 流程。callback 不包含 display token，也不证明付款或 grant active；Backend 未返回 `grant_active` 前不得读取结果。
+`--input-json <file>` accepts the complete flat input returned in `file_content`; use it instead of `--input`, never together.