@itpay/cli 2.1.48 → 2.1.49

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/未知付款先恢复原单，不补事后批准或创建替代订单。
-
-## 历史合同兼容与高级入口
-
-普通新服务使用 `services purchase` 完整确认与官方入口。此命令保留历史合同和高级兼容，为单个 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.

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

@@ -22,48 +22,13 @@ itpay services get <service_execution_id> [--json]
 
 命令使用当前签名 Agent Device session；可见范围由 Backend 按设备和已绑定 Buyer account 决定。
 
-## 标准输出
+## 当前状态与恢复
 
-```json
-{
-  "status": "shown",
-  "result": {
-    "service_execution_id": "<id>",
-    "service_id": "<service_id>",
-    "status": "<status>",
-    "phase": "<phase>",
-    "current_capability_id": "<optional capability>",
-    "updated_at": "<time>",
-    "timeline": [
-      {
-        "sequence": 1,
-        "step": "<public step>",
-        "status": "<status>",
-        "phase": "<phase>",
-        "occurred_at": "<time>"
-      }
-    ],
-    "delivery_mode": "<optional mode>"
-  },
-  "instruction": "时间线仅用于解释和恢复；按当前首选动作继续，不要重放已完成步骤。",
-  "next": { "command": "<state-derived command>", "reason": "继续当前首选动作" },
-  "recovery": [
-    { "command": "itpay services events <service_execution_id> --json", "reason": "仅在需要完整诊断事件时使用" }
-  ]
-}
-```
-
-当 execution 为 `failed`、`refunded` 或 `cancelled` 时，`next` 必须是 `null`；只允许通过 `services events` 诊断终止原因，不得建议重放 capability 或创建 Checkout。
-
-`timeline` 只保留最近 20 个公开节点；超过时增加 `timeline_truncated: true`。它不返回 event ID 或 `redacted_summary`。交付存在时可增加 `delivery_mode`；退款锁存在时增加 `access_locked` 和退款 ID/status，并优先返回锁定 instruction。
-
-订票类 Execution 的 `workflow:confirm_booking` 待确认/待修订状态不在 timeline 中展开细节——行程、`seat_options` 与当前 `draft_revision` 一律通过 `services next` 的 `booking_review_required` 投影读取；`get` 只用于确认执行仍处于可继续状态。
-
-## 异常处理
+返回原执行的安全状态、当前动作和最近20个公开节点；超出时 timeline_truncated=true。没有动作就停止，不从时间线推导重放步骤。需要诊断且当次明确建议时才读取 services events。
 
-默认不返回原始 events、Provider metadata、内部 bindings、Arazzo workflow、capability schema、candidate hash、client context 或完整 payload。需要完整但仍经服务端脱敏的事件时才运行 `services events`。
+购买材料、完整 review 和待填输入使用当次返回的完整模板，不手拼字段。缺合同、材料过期、权限拒绝或读取失败按实际原因处理，不能自动切到旧购买链或创建替代执行。
 
-execution 不存在或不属于当前身份时保留不透明 `not_found`，只恢复到 `itpay services list --json`；不得通过错误差异探测其他账号。
+退款访问锁优先于交付；failed/refunded/cancelled 等终态不创建 Checkout。历史已交付记录不证明当前授权仍有效。默认不返回供应商原始数据、凭据、内部binding或完整事件DTO。
 
 ## Agent Type / Host
 

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

@@ -1,49 +1,11 @@
-# `itpay services`
+# Service commands
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Seller-published workflows enter the same Buyer execution, Checkout, delivery, and refund state machine as ItPay services.
+发现公开服务与完整输入 → run原操作 → read-result/page读取保存结果 → 按委托选择 → purchase仅补必要同意 → 展示官方页面 → 读原订单。
 
-## 命令范围
+start的公开overview为定义发现；已有任务使用get/next。选择、输入、继续、购买及售后均以当前返回的完整模板和事实为准。CLI通用能力由锁定业务适配器解释，不按服务名称猜字段。明确多服务组合见cart-checkout；不是普通下单备用链。
 
-操作通用 Service Execution。CLI 不知道某个服务的业务流程；它读取服务合同中的 capability、input schema、价格、交付模式和服务端 next action。
+## 当前参数
 
-**上游：** Catalog 的 `service_id`。
-**下游：** 免费能力、人工动作、付费 Checkout、Agent-visible 交付或 Vault 授权交付。
+```text
 
-## 核心不变量
-
-- Execution 的边界由服务合同决定；铁路查询和购票使用不同 Execution，已有执行的等待与恢复保持原 ID。其他独立服务分别执行，其 Quote 可进入同一 Cart。
-- 任何 capability 输入都必须在状态写入、锁价、订单创建和 Provider 调用前通过 schema 校验。
-- `invoke` 只运行当前阶段允许且不需付款的 Agent-visible capability。
-- 依赖候选的付费 capability 必须继续来源 Execution；`action --candidate` 不能跨 Execution 搬运候选。
-- 普通已选服务使用 `services purchase` 读取完整确认、提交真实同意并交付官方页面；此操作不请求支付。
-- `services quote`、`cart add --quote`、`buy --cart` 保留为用户明确要求多服务组合的高级路径；旧 `services checkout` 保留已有执行兼容。
-- `agent_visible_result` 从 `services next` 读取；`vault_artifact` 只有人授权后才能 `read-result`。
-
-## 子命令
-
-- [`start`](start.md)
-- [`run`](run.md)
-- [`invoke`](invoke.md)
-- [`action`](action.md)
-- [`quote`](quote.md)
-- [`purchase`](purchase.md)
-- [`checkout`](checkout.md)
-- [`list`](list.md)
-- [`get`](get.md)
-- [`next`](next.md)
-- [`read-result`](read-result.md)
-- [`events`](events.md)
-
-直接运行 `itpay services` 显示 help。
-
-## 语法、输出与异常
-
-```bash
-itpay services --help
 ```
-
-输出当前子命令：运行已发布服务使用 `run`，查询推进使用 `next`，选定后的完整购买确认使用 `purchase`，深度诊断才使用 `get/events`。未知子命令返回参数错误和本 help，不创建 Execution。
-
-## Agent Type / Host
-
-所有正式支持的 Local Agent Type 共享状态机；Agent Type 只影响身份归属和 Host instruction，不允许影响 quota 规则或服务能力。