@itpay/cli 2.0.3 → 2.0.5

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

@@ -0,0 +1,85 @@
+# `itpay refund create`
+
+## 范围与意义
+
+为一笔订单提交退款意图。Refund Owner 从订单推导 Buyer、支付、金额、币种、消费事实和审核策略；Agent 只提交订单和用户原因。
+
+**上游：** `order <id>` 或用户明确提出退款。  
+**下游：** `refund watch <refund_request_id>`，或在 `can_cancel=true` 时由用户选择取消。
+
+退款成功落库与交付冻结是同一事务；CLI 不自行锁单，也不预测自动退款结果。
+
+## 语法与参数
+
+```bash
+itpay refund create --order <order_id> [--reason <reason>] [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `--order <order_id>` | 是 | 当前 Buyer 或已绑定 Agent 可见的订单。 |
+| `--reason <reason>` | 否 | 默认 `buyer_requested`；只记录用户原因，不决定政策。 |
+| `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
+
+CLI 使用 Device Authority 或已有 Buyer bearer，并用订单+原因生成稳定幂等操作 ID。不得提交退款金额、币种、支付 ID、消费状态或审核模式。
+
+## 标准输出
+
+```json
+{
+  "status": "requested",
+  "result": {
+    "refund_request_id": "<refund_id>",
+    "order_id": "<order_id>",
+    "decision_mode": "automatic",
+    "refund_status": "accepted",
+    "consumption_state": "unconsumed",
+    "access_locked": true,
+    "can_cancel": true
+  },
+  "instruction": "退款处理中，交付已冻结；不要 reveal、授权或读取结果。",
+  "next": {
+    "command": "itpay refund watch <refund_id> --json",
+    "reason": "跟踪同一退款"
+  },
+  "recovery": []
+}
+```
+
+`decision_mode` 的服务器枚举为 `automatic|manual`。已消费交付通常返回 `manual` / `policy_review_required`；instruction 明确等待人工审核。`status` 表示提交动作已完成，`result.refund_status` 才是退款状态机当前状态。
+
+若服务器返回退款终态，`next` 为 `null`。文本输出依次显示 result 字段、instruction 和一个 next，不输出支付或 Provider 内部数据。
+
+重复提交同一活跃退款时 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": "检查已有退款"
+    }
+  ]
+}
+```
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 使用相同 Device Authority、退款政策和输出。未绑定订单时不得改用新 Device ID、Buyer ID 或开发者权限绕过 Owner 鉴权。

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

@@ -0,0 +1,60 @@
+# `itpay refund get`
+
+## 范围与意义
+
+读取一笔当前身份可见退款的权威快照、交付锁和可取消性。它只请求一次，不轮询、不改变退款状态。
+
+**上游：** `refund create`、`refund list` 或之前的 `refund watch`。  
+**下游：** 非终态进入 `refund watch`；终态结束；`can_cancel=true` 时用户可另行选择取消。
+
+## 语法与参数
+
+```bash
+itpay refund get <refund_request_id> [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `refund_request_id` | 是 | Refund Owner 返回的退款 ID。 |
+| `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
+
+## 标准输出
+
+```json
+{
+  "status": "shown",
+  "result": {
+    "refund_request_id": "<id>",
+    "order_id": "<order_id>",
+    "decision_mode": "automatic",
+    "refund_status": "accepted",
+    "consumption_state": "unconsumed",
+    "access_locked": true,
+    "can_cancel": true
+  },
+  "instruction": "退款处理中，交付已冻结；不要 reveal、授权或读取结果。",
+  "next": {
+    "command": "itpay refund watch <refund_id> --json",
+    "reason": "跟踪同一退款"
+  },
+  "recovery": []
+}
+```
+
+`decision_mode` 为 `automatic|manual`；`refund_status`、`consumption_state`、`access_locked` 和 `can_cancel` 均直接来自 Refund Owner。文本输出显示同一组字段、instruction 和最多一个 next。
+
+## 终态
+
+- `succeeded`：instruction 明确“退款已成功；交付永久关闭”，`next=null`。
+- `cancelled/rejected`：说明交付资格可恢复，但旧 grant 不复活，需要用户重新授权，`next=null`。
+- `failed`：是否继续锁定以 `access_locked` 和 `failure_class` 的服务器裁定为准，`next=null`。
+
+CLI 不因为退款终态自行修改订单或 grant。
+
+## 异常处理
+
+不存在和不属于当前账号的退款都返回不透明 `not_found`。错误 instruction 要求核对当前账号/Agent 绑定，唯一恢复入口为 `itpay services list --json`；不得通过错误差异探测其他账号退款。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回完全相同的退款事实、instruction 和 next。Host 不改变 Refund Owner 状态或访问锁。

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

@@ -0,0 +1,33 @@
+# `itpay refund`
+
+## 命令范围
+
+创建、恢复、跟踪和取消退款申请。Refund Owner 决定政策和状态；CLI 只提交用户意图并展示服务端事实。
+
+**上游：** 已归属当前 Buyer/Agent 的订单。
+**下游：** 自动退款执行、Admin review、取消或终态。
+
+## 子命令
+
+- [`refund create`](create.md)
+- [`refund list`](list.md)
+- [`refund get`](get.md)
+- [`refund watch`](watch.md)
+- [`refund cancel`](cancel.md)
+
+兼容别名 `itpay refund --order <id>` 等价于 `refund create`，文档和 instruction 统一推荐子命令形式。
+
+退款创建成功即锁定对应交付；旧 Agent grant 不得继续读取。直接运行无参数 `itpay refund` 显示 help，不创建请求。
+
+## 语法、参数与标准输出
+
+```bash
+itpay refund --order <order_id> [--reason <reason>] [--json]
+itpay refund --help
+```
+
+兼容别名的参数、输出、instruction 和异常合同与 [`refund create`](create.md) 完全相同。无 `--order` 时只显示 help 和推荐的 `refund create` 语法，不发送请求。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种类型使用同一签名 Device Authority 和退款状态机；Host 不影响退款资格。

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

@@ -0,0 +1,68 @@
+# `itpay refund list`
+
+## 范围与意义
+
+列出指定订单的退款记录，按最新到最旧排序。
+
+**上游：** `order_id`。
+**下游：** `refund get/watch <refund_id>`。
+
+## 语法与参数
+
+```bash
+itpay refund list --order <order_id> [--json]
+```
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `--order` | 是 | 用户订单 `order_id`，不可猜测。 |
+| `--json` | 否 | 输出标准命令合同 JSON。 |
+
+## 标准输出
+
+```json
+{
+  "status": "listed",
+  "result": {
+    "order_id": "<order_id>",
+    "refunds": [
+      {
+        "refund_request_id": "<id>",
+        "status": "<status>",
+        "amount": "<amount> <currency>",
+        "created_at": "<RFC3339>"
+      }
+    ]
+  },
+  "instruction": "已有活跃退款；继续跟踪同一笔，不要为该订单重复创建。",
+  "next": { "command": "itpay refund get <refund_id> --json", "reason": "读取活跃退款" },
+  "recovery": []
+}
+```
+
+列表只返回选择退款所需的 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": []
+}
+```
+
+## 鉴权与异常处理
+
+允许订单 Owner 的 Buyer session、该订单的 order-scoped session，或绑定同一 Service Execution 的签名 Agent Device session。CLI 不自行判断归属；未知订单和无权访问统一按服务端不透明 `not_found` 处理。
+
+缺少 `--order` 必须在 HTTP 前返回 `order_required`。鉴权或归属失败时 instruction 要求核对订单，recovery 指向 `itpay services list --json`；不得通过错误差异泄露退款是否存在。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的业务字段、instruction 和 next 完全相同；本命令没有 Host 渲染差异。

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

@@ -0,0 +1,73 @@
+# `itpay refund watch`
+
+## 范围与意义
+
+轮询同一退款直到终态或 timeout。命令内部可以读取多次，但对外只输出一个最终信封，不把无变化轮询刷入 Agent 上下文。中断后可无副作用重跑。
+
+**上游：** active refund。  
+**下游：** `succeeded`、`failed`、`cancelled`、`rejected` 等终态，或稍后继续 watch。
+
+## 语法与参数
+
+```bash
+itpay refund watch <refund_request_id> [--interval <seconds>] [--timeout <seconds>] [--json]
+```
+
+| 参数 | 默认 | 约束 |
+| --- | --- | --- |
+| `refund_request_id` | 无 | 必填。 |
+| `--interval <seconds>` | `2` | 必须至少 1 秒。 |
+| `--timeout <seconds>` | `120` | 必须为正数；可使用小数。 |
+| `--json` | 关闭 | 输出一个可直接解析的 JSON 信封。 |
+
+非法轮询参数在第一次 HTTP 请求前失败。
+
+## 终态输出
+
+```json
+{
+  "status": "watch_complete",
+  "result": {
+    "refund_request_id": "<id>",
+    "order_id": "<order_id>",
+    "decision_mode": "automatic",
+    "refund_status": "succeeded",
+    "consumption_state": "unconsumed",
+    "access_locked": true,
+    "can_cancel": false
+  },
+  "instruction": "退款已成功；交付永久关闭。",
+  "next": null,
+  "recovery": []
+}
+```
+
+其他终态使用与 `refund get` 相同的锁、恢复资格和旧 grant 规则。
+
+## Timeout 输出
+
+Timeout 只表示本次 CLI 等待结束，不表示退款失败：
+
+```json
+{
+  "status": "watch_timeout",
+  "result": {
+    "refund_request_id": "<id>",
+    "last_status": "<status>",
+    "access_locked": true,
+    "can_cancel": true
+  },
+  "instruction": "退款仍在处理，稍后继续跟踪同一退款；不要重复申请。",
+  "next": {
+    "command": "itpay refund watch <refund_id> --json",
+    "reason": "恢复轮询"
+  },
+  "recovery": []
+}
+```
+
+网络、ID 或参数错误返回错误信封，并只建议 `itpay refund get <id> --json` 检查当前状态。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回相同退款事实。Desktop 不会把每次无变化轮询发送到用户对话；Host 不改变 timeout 或退款状态。

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

@@ -0,0 +1,43 @@
+# `itpay services action`
+
+## 范围与意义
+
+记录用户或 Agent 对 Service Execution 的结构化动作，例如选择候选、批准、拒绝或取消。它不直接调用付费 Provider。
+
+**上游：** `services invoke/next` 返回需要 action。
+**下游：** 候选选择成功时直接进入服务端允许的下一动作；其他动作通过更新后的 `services next` 恢复。
+
+## 语法与参数
+
+```bash
+itpay services action <service_execution_id> --action <action_type>
+  [--actor-type <actor_type>] [--actor-id <actor_id>]
+  [--status <pending|approved|rejected|expired|cancelled>]
+  [--candidate <rank> | --result-item <result_item_id>]
+  [--required-before <step>] [--input <key=value> ...] [--json]
+```
+
+普通 Agent 优先使用 `--candidate <rank>`。CLI 只从当前 Execution 的 `current_result_items` 解析 Result Item ID；Backend 再读取权威 Invocation 和 Stable Hash。Agent 不提交 Hash，也不能使用其他 Execution 或外部来源的候选。`--result-item` 只用于已持有当前 Execution 内部句柄的受控恢复，不应要求用户提供。
+
+## 标准输出
+
+```json
+{
+  "status": "candidate_selected",
+  "result": {
+    "service_execution_id": "<id>",
+    "candidate": { "rank": 2, "title": "<title>" }
+  },
+  "instruction": "候选已绑定到来源 Execution；后续动作必须继续使用该 Execution。",
+  "next": { "command": "itpay services quote <id> --capability <capability_id> --email <email> --json", "reason": "为已确认候选准备报价" },
+  "recovery": [{ "command": "itpay services next <id> --json", "reason": "重新读取服务端允许的动作" }]
+}
+```
+
+`next` 来自 action 写入后重新读取的类型化 `allowed_actions`，不是 CLI 根据服务名猜测。若后续不是报价，CLI 渲染该动作对应的通用命令；没有合法动作时返回 `next: null`。非候选 action 仍返回 `action_recorded` 并引导 `services next`。
+
+rank 不存在、属于旧结果集或其他 Execution、action 不允许、status 非法时均不写 action；返回结构化错误并引导同一 Execution 的 `services next`。相同候选重试幂等；同一结果集改选另一个候选返回冲突，不覆盖已批准事实。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。

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

@@ -0,0 +1,82 @@
+# `itpay services checkout`
+
+## 范围与意义
+
+为单个 Service Execution 快速创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。
+
+**上游：** `services next` 返回的 `prepare_quote` capability 和已验证输入。
+**下游：** 人完成 Checkout，随后 `checkout` 或 `services next`。
+
+## 语法与参数
+
+```bash
+itpay services checkout <service_execution_id> --capability <capability_id>
+  [--input <key=value> ...] [--email <delivery_email>]
+  [--host <host>] [--target <target>] [--qr-format <format>] [--qr-file <path>] [--json]
+
+itpay services checkout <service_execution_id> --resume
+  [--host <host>] [--target <target>] [--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": "<host_optional_path>", "markdown": "<host_optional_markdown>" },
+  "instruction": "把二维码和付款链接展示给用户；确认可见前不要查询状态，也不要创建新 Checkout。",
+  "next": { "command": "itpay checkout --id <checkout_id> --token <display_token>", "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,qr_local_path}`；普通文本模式在用户可见终端渲染二维码。 |
+| `claude-code-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
+| `claude-code-cli` | `handoff={url,qr_local_path}`；普通文本模式在用户可见终端渲染二维码。 |
+| `workbuddy` | `handoff={url,qr_local_path,qr_image_url}`；发送链接和可用二维码附件，原生行为后续细化。 |

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

@@ -0,0 +1,73 @@
+# `itpay services events`
+
+## 范围与意义
+
+按 sequence 升序读取一笔 Service Execution 的受限诊断事件。它只用于解释异常或支持排查，不是正常业务流程，不返回事件 ID、内部摘要、Provider 数据或受保护交付内容。
+
+**上游：** `services get/next` 无法解释异常状态，并明确建议读取事件。
+
+**下游：** 回到 `services next` 获取当前可执行动作；事件本身不能用于重放步骤。
+
+## 语法与参数
+
+```bash
+itpay services events <service_execution_id> [--after-sequence <n>] [--limit <n>] [--json]
+```
+
+| 参数 | 必填 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `service_execution_id` | 是 | - | 当前设备或账号可见的执行 ID。 |
+| `--after-sequence` | 否 | `0` | 只返回 sequence 大于该非负整数的事件。 |
+| `--limit` | 否 | `50` | 本页最多 `1..100` 条。 |
+| `--json` | 否 | false | 返回标准命令 envelope。 |
+
+CLI 在发起 HTTP 请求前校验数字参数。Backend 再执行归属鉴权和相同上限。
+
+## 标准输出
+
+```json
+{
+  "status": "listed",
+  "result": {
+    "service_execution_id": "<id>",
+    "after_sequence": 0,
+    "returned_count": 2,
+    "events": [
+      {
+        "sequence": 1,
+        "type": "<public_event_type>",
+        "status": "<public_status>",
+        "phase": "<public_phase>",
+        "capability_id": "<optional_capability_id>",
+        "occurred_at": "<time>"
+      }
+    ]
+  },
+  "instruction": "事件仅用于诊断；不要从事件重放业务步骤，回到 services next 获取当前动作。",
+  "next": {
+    "command": "itpay services next <id> --json",
+    "reason": "恢复正常服务流程"
+  },
+  "recovery": []
+}
+```
+
+当返回条数等于 limit 时，`recovery` 增加一条使用最后 sequence 的下一页命令。空页仍返回 `listed` 和 `returned_count: 0`。
+
+## 安全边界
+
+CLI 只投影：`sequence`、`type`、`status`、`phase`、可选 `capability_id`、`occurred_at`。即使 Backend DTO 包含 `service_execution_event_id`、重复 execution ID 或 `redacted_summary`，CLI 也不输出。
+
+不得输出 AppCode、Provider headers、raw payload、payload ref/hash、Buyer PII、token、签名、候选 hash、correlation ID 或 Admin note。
+
+## 异常处理
+
+| 错误 | 含义 | 恢复 |
+| --- | --- | --- |
+| `events_parameter_invalid` | sequence/limit 不是允许的整数。 | 查看本命令 help；未发 HTTP。 |
+| `service_events_failed` | Backend 不可用或读取失败。 | 回到 `services next` 或当前身份的 `services list`。 |
+| `not_found` | execution 不存在或不属于当前身份。 | 使用相同不透明错误，不区分两者。 |
+
+## Agent Type / Host
+
+五种正式 Agent Type 的事件字段、鉴权和 redaction 完全相同；Host 不影响可见性，也不产生 handoff。

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

@@ -0,0 +1,66 @@
+# `itpay services get`
+
+## 范围与意义
+
+读取一笔 Service Execution 的紧凑状态、关键节点和当前首选动作。它面向恢复和用户解释，不是原始 event dump。
+
+**上游：** execution ID。
+**下游：** 当前首选命令；深度诊断才使用 `events`。
+
+## 语法与参数
+
+```bash
+itpay services get <service_execution_id> [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `<service_execution_id>` | 是 | `services start/list/next` 返回的 execution ID。 |
+| `--json` | 否 | 输出单个标准 JSON envelope；默认输出相同事实的简洁文本。 |
+
+命令使用当前签名 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。
+
+## 异常处理
+
+默认不返回原始 events、Provider metadata、内部 bindings、graph projection、capability schema、candidate hash、client context 或完整 payload。需要完整但仍经服务端脱敏的事件时才运行 `services events`。
+
+execution 不存在或不属于当前身份时保留不透明 `not_found`，只恢复到 `itpay services list --json`；不得通过错误差异探测其他账号。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的状态、timeline、instruction 和 next 相同。本命令没有二维码或 Host handoff。

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

@@ -0,0 +1,45 @@
+# `itpay services`
+
+## 命令范围
+
+操作通用 Service Execution。CLI 不知道某个服务的业务流程；它读取服务合同中的 capability、input schema、价格、交付模式和服务端 next action。
+
+**上游：** Catalog 的 `service_id`。
+**下游：** 免费能力、人工动作、付费 Checkout、Agent-visible 交付或 Vault 授权交付。
+
+## 核心不变量
+
+- 一个 Execution 表示一个独立服务意图；多个意图分别执行、分别交付，但各自的 Quote 可以进入同一 Cart。
+- 任何 capability 输入都必须在状态写入、锁价、订单创建和 Provider 调用前通过 schema 校验。
+- `invoke` 只运行当前阶段允许且不需付款的 Agent-visible capability。
+- 依赖候选的付费 capability 必须继续来源 Execution；`action --candidate` 不能跨 Execution 搬运候选。
+- `services quote` 只创建 Quote Lock；`cart add --quote` 聚合交易；`buy --cart` 创建一次 Checkout。
+- `services checkout` 是单项快捷方式，内部复用 Quote、Cart 和 Checkout 的相同规则。
+- `agent_visible_result` 从 `services next` 读取；`vault_artifact` 只有人授权后才能 `read-result`。
+
+## 子命令
+
+- [`start`](start.md)
+- [`invoke`](invoke.md)
+- [`action`](action.md)
+- [`quote`](quote.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
+```
+
+输出十个子命令及一句选择规则：正常推进使用 `next`，深度诊断才使用 `get/events`。未知子命令返回参数错误和本 help，不创建 Execution。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 共享状态机；Agent Type 只影响身份归属和 Host instruction，不允许影响 quota 规则或服务能力。