@itpay/cli 2.1.48 → 2.1.49

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

@@ -1,178 +1,33 @@
-# `itpay buy`
+# itpay buy
 
-> **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.
+用于用户明确请求的普通多服务Cart购买。服务-backed行由当前cart next返回其服务动作；普通选择不绕过真实购买同意。
 
-## 范围与意义
-
-为普通 Catalog 项目或已绑定 Service Quote 的 canonical Cart 创建一个 ItPay Checkout，并按当前 Agent Type 把付款入口交给用户。命令只创建或恢复 ItPay Checkout，不把“用户说已付款”当作付款成功。
-
-未报价的 service-backed line 不可购买；命令停止并转向 `services next`。已通过 `cart add --quote` 锁定输入和价格的服务行可以合并结算，每个 Order Item 仍映射回独立 Execution、Capability 和交付路径。
-
-**直接上游：**
-
-- `cart add` 创建的 canonical Cart；
-- `cart add --local` 创建的本地兼容草稿；
-- Catalog 返回的一组完整 `item / variant / offer`；
-- 已知的普通 canonical `cart_id`。
-
-**直接下游：** `checkout` 查询同一 Checkout 的权威状态。付款确认后，再按其返回的 `next` 进入订单或服务履约。
-
-## 语法
-
-```bash
-itpay buy [--json]
-
-itpay buy --cart <cart_id> [--json]
-
-itpay buy \
-  --item <catalog_item_id> \
-  --variant <catalog_variant_id> \
-  --offer <offer_id> \
-  [--quantity <positive_integer>] [--json]
+```sh
+itpay cart next --json
 ```
 
-通用选项：
+随后使用返回的完整buy命令及参数（--help为当前参考）。它准备或恢复原官方Checkout，不自动请求付款。展示与付款事实规则见正式Skill，独立Cart用途见cart-checkout。
+
+## 当前参数
 
 ```text
+--host <host>                   client host (terminal, telegram, feishu,
+--target <target>               chat id / channel id / open id for IM hosts
+--item <catalog_item_id>
+--variant <catalog_variant_id>
+--offer <offer_id>
+--cart <cart_id>                existing canonical server cart id
+--quantity <n>                  quantity (default: "1")
 --ref <client_reference_id>
 --contact-email <email>
 --contact-phone <phone>
---require-contact <email,phone>
---host <host>
---target <target>
---locale <zh-CN|en>
---qr-format <unicode|utf8|ansi|terminal>
---qr-file <path>
---pay
---method <alipay|wechatpay>
---no-wait
---timeout <positive_seconds>
---json
-```
-
-## 参数合同
-
-| 参数 | 必填 | 规则 |
-|---|---:|---|
-| `--cart` | 条件必填 | 使用一个已存在的普通或全量已报价 canonical Cart。不能和 inline 三元组同时使用。 |
-| `--item` | 条件必填 | Inline 购买时必须与 `--variant`、`--offer` 一起提供。只能使用 Catalog 返回值。 |
-| `--variant` | 条件必填 | 同上。 |
-| `--offer` | 条件必填 | 同上。 |
-| `--quantity` | 否 | 正整数，默认 `1`；只用于 inline 项目。 |
-| `--ref` | 否 | 调用方自己的业务引用；不承担幂等职责。 |
-| `--contact-email` | 条件必填 | 普通 Cart 或兼容旧 Quote 缺少所需邮箱时使用，值必须来自用户；新版 Service Quote 会自动携带已确认邮箱。 |
-| `--contact-phone` | 条件必填 | `--require-contact` 包含 `phone` 时必填，值必须来自用户。 |
-| `--require-contact` | 否 | 只接受 `email`、`phone`；缺失时先询问用户，禁止 Agent 编造。 |
-| `--host` | 条件必填 | 通常由 `--agent-type` 推导；`openclaw` 必须显式传当前入口。只改变 handoff 展示，不改变交易事实。 |
-| `--target` | 条件必填 | 要求目标会话的 IM Host 必须提供；OpenClaw 从当前可信会话上下文传入。 |
-| `--locale` | 否 | Payment Card 语言，默认 `zh-CN`；可使用 `en`。只改变 Card 文案，不改变交易事实。 |
-| `--qr-format` | 否 | 非 JSON 的终端渲染选项。 |
-| `--qr-file` | 否 | 非 JSON handoff 的明确二维码文件路径。 |
-| `--pay` | 否 | 创建 Payment Intent 的集成/运维入口；普通 Agent 流程只展示 Checkout。 |
-| `--method` | 否 | 只接受 `alipay` 或 `wechatpay`，默认 `alipay`；仅随 `--pay` 生效。 |
-| `--no-wait` | 否 | 只能与 `--pay` 一起使用。 |
-| `--timeout` | 否 | 等待付款事件的正整数秒数，默认 `120`。 |
-| `--json` | 否 | 输出本文定义的紧凑机器合同，不输出字符二维码或图片二进制。 |
-
-不传 `--cart` 或 inline 三元组时，命令使用本机保存的 active canonical Cart；若没有，则使用本地普通草稿创建 canonical Cart。两者都没有时返回 `cart_empty`。
-
-## 标准 JSON 输出
-
-### 等待用户付款
-
-```json
-{
-  "status": "human_checkout_required",
-  "result": {
-    "checkout_id": "<checkout_id>",
-    "payment": "pending",
-    "amount": "<amount> <currency>",
-    "item_count": 1
-  },
-  "handoff": {
-    "url": "<tokenized_checkout_url>",
-    "qr_local_path": "<desktop_optional_host_ready_file>",
-    "markdown": "<desktop_only_optional_markdown>",
-    "qr_image_url": "<chat_host_optional_absolute_https_png>",
-    "agent_action": "<openclaw_telegram_only_native_message_action>"
-  },
-  "instruction": "<current_host_instruction>",
-  "next": {
-    "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
-    "reason": "稍后查询同一笔 Checkout 状态"
-  },
-  "recovery": []
-}
-```
-
-`handoff` 只保留当前 Host 可以使用的字段。不得返回二维码 base64、镜像路径数组、renderer 状态或原始后端 DTO。`agent_action` 只允许出现在 `openclaw + telegram`。
-
-**Instruction：** 必须使用下方 Agent Type 表定义的展示动作；展示完成或失败后停止。OpenClaw Telegram 必须原样执行 `handoff.agent_action`，不得改写 Presentation 或用普通回复冒充按钮已发送。收到 `itp:grant_confirmed:<checkout_id>` 表示用户声明已授权读取，应立即执行 `next.command` 查询同一 Checkout，再只跟随后端 grant 状态；该 callback 本身不证明付款或 grant active。
-
-### `--pay` 已观察到付款事件
-
-```json
-{
-  "status": "payment_event_observed",
-  "result": {
-    "checkout_id": "<checkout_id>",
-    "payment": "verified",
-    "amount": "<amount> <currency>",
-    "item_count": 1,
-    "payment_intent_id": "<payment_intent_id>",
-    "payment_intent_status": "<provider_status>"
-  },
-  "instruction": "已观察到付款确认事件；读取同一 Checkout 的权威完成状态，不要再次付款。",
-  "next": {
-    "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
-    "reason": "读取订单和履约句柄"
-  },
-  "recovery": []
-}
+--require-contact <fields>      comma-separated required contact fields:
+--qr-format <format>            unicode|utf8|ansi|terminal
+--qr-file <path>                explicit QR file path
+--locale <locale>               payment card language: zh-CN|en (default:
+--pay                           explicit controlled integration only; creates a payment intent
+--method <alipay|wechatpay>     payment method for --pay (default: "alipay")
+--no-wait                       do not wait after an explicitly authorized --pay
+--timeout <seconds>             max seconds to wait for payment (default:
+--json                          output JSON instead of terminal text
 ```
-
-事件观察不是订单 DTO。Agent 必须执行 `next.command`，不能自行宣称履约完成。
-
-## 幂等与中断恢复
-
-- CLI 在本机 `operations.json.d/`（dev 使用独立目录）中为 `checkout.create:<cart_id>` 保存一条不可变、owner-only 的稳定幂等记录；不同操作不共享全局锁。
-- HTTP 请求通过 `Idempotency-Key` 提交该键。
-- Checkout 响应丢失时，重跑同一命令会复用已保存的 canonical Cart 和同一幂等键。
-- 后端返回同一个待处理 Checkout，并轮换新的交接 token；不会创建第二笔订单。
-- Service Quote Cart 的联系信息由 Quote Lock 汇总；正常流程无需在 `buy` 重复传邮箱，旧 Quote 可显式补充。
-- Checkout 成功保存后，active Cart 句柄被清除，只保留 Checkout（以及可选 Service Execution）恢复句柄。
-- 不确定命令执行到哪一步时，先运行 `itpay next --json`，不得重新拼一笔购买。
-
-## 异常处理
-
-| 错误码 | 含义 | Agent 处理 |
-|---|---|---|
-| `buy_source_invalid` | Inline 三元组不完整，或与 `--cart` 混用。 | 从 Catalog 重新读取完整 ID，或只保留 `--cart`。 |
-| `cart_empty` | 没有本地草稿或 active canonical Cart。 | 执行 `catalog list`，不要猜 ID。 |
-| `missing_contact` | 缺少调用方声明的 required contact。 | 向用户询问后重跑同一命令；禁止编造。 |
-| `contact_field_invalid` | `--require-contact` 包含不支持字段。 | 只使用 `email`、`phone`。 |
-| `payment_method_invalid` | 付款方式不是允许值。 | 使用 `alipay` 或 `wechatpay`。 |
-| `buy_parameter_invalid` | quantity/timeout 非正整数，或 `--no-wait` 未配 `--pay`。 | 修正参数；本次不创建资源。 |
-| `service_quote_required` | Cart 含尚未绑定 Quote 的 Service Execution。 | 原样执行返回的 `services next <id> --json`；不要绕过 Quote 输入校验。 |
-| `idempotency_conflict` | 同一幂等操作被用于不同请求。 | 保留句柄并执行 `itpay next --json`，不要换键重建。 |
-| `buy_failed` | 非传输层的未知命令错误。 | 先执行 `itpay next --json` 或 `cart next --json` 恢复现有资源。传输失败使用 conventions 中的稳定 `network_*` 错误码。 |
-
-所有参数错误都必须在 HTTP 和本地 Cart 变更前被拒绝。服务 Cart 只有每条 service-backed line 都绑定有效 Quote 时才能创建 Checkout；付款后 Backend 按 Order Item 分别推进 Execution。
-
-## Agent Type / Host
-
-| Agent Type | 默认 Host | JSON handoff | Instruction |
-|---|---|---|---|
-| `codex-desktop` | `codex` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 `handoff.markdown` 原样发到当前 Codex 对话，确认二维码和链接可见后等待。 |
-| `codex-cli` | `terminal` | `url` | 非 JSON 模式在用户可见终端渲染二维码；始终保留付款链接。 |
-| `claude-code-desktop` | `claude-code` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 Markdown handoff 发到当前桌面对话，不能只输出本地路径。 |
-| `claude-code-cli` | `terminal` | `url` | 在用户可见终端展示；不能声称桌面对话已收到图片。 |
-| `workbuddy` | `plain-chat` | `url,agent_action` | 原样执行一次 `present_files(files=[url])`，在右侧打开完整渲染的 HTML Card Link，然后停止。 |
-| `zcode` | `plain-chat` | `url` | 立即用 ZCode 内置浏览器打开 URL；只有浏览器不可用时才展示同一个可点击链接。 |
-| `doubao-work` | `plain-chat` | `url,qr_image_url` | 展示“手机直接打开收银台”和“二维码图片（保存或用另一台设备扫码）”两个有标签的官方入口，说明金额后停止。 |
-| `kimi-code` | `terminal` | `url` | 使用标准 CLI 非 JSON 终端二维码和链接。 |
-| `openclaw` | 必须显式 | Telegram 返回 `url,qr_image_url,agent_action`；其他入口返回 `url,qr_image_url` | Telegram 执行原生 `message` action；其他入口直接展示图片和链接。 |
-
-显式 `--host` 可以覆盖展示方式，但不会改变 Agent Type、设备身份、金额、权限或交易状态。
-
-OpenClaw 缺少 `--host`，或 IM Host 缺少 `--target` 时，必须在创建 Cart/Checkout 前分别返回 `host_required` 或 `target_required`。

package/docs/cli-reference/commands/cart/add.md

@@ -2,6 +2,8 @@
 
 > **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.
 
+本命令仅用于用户明确要求的独立多服务Cart，不能作为普通购买或错误恢复旁路。
+
 ## 服务报价的批准边界
 
 服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。
@@ -65,7 +67,7 @@ Catalog 模式下 `--item`、`--variant`、`--offer` 必须成组且来自同一
     "offer_id": "<offer_id>",
     "quantity": 1
   },
-  "instruction": "仅写入本地兼容草稿，未验证目录、价格或服务合同；不要把它当作 canonical Cart。",
+  "instruction": "仅写入本地未验证草稿，未验证目录、价格或服务合同；不要把它当作 canonical Cart。",
   "next": { "command": "itpay cart show --local", "reason": "检查本地草稿" },
   "recovery": []
 }

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

@@ -4,7 +4,7 @@
 
 ## 命令范围
 
-管理 canonical server Cart。Catalog line 可以创建 Service Execution；已准备好的 Service Quote 则通过 `cart add --quote` 加入 Cart。Cart 聚合交易，但不合并 Execution、候选归属或交付。
+仅在用户明确要求组合独立服务时管理 canonical server Cart。Catalog line 可以创建 Service Execution；已准备好的 Service Quote 则通过 `cart add --quote` 加入 Cart。Cart 聚合交易，但不合并 Execution、候选归属或交付。
 
 **上游：** Catalog item、variant、offer 和服务输入。
 **下游：** Service Execution、Quote 聚合或 `buy`。
@@ -17,7 +17,7 @@
 - [`cart show`](show.md)
 - [`cart clear`](clear.md)
 
-`--local` 只用于显式本地草稿兼容，不得用于 service-backed flow。直接运行 `itpay cart` 显示 help。
+`--local` 只用于显式本地未验证草稿，不得用于 service-backed flow。直接运行 `itpay cart` 显示 help。
 
 ## 语法、输出与异常
 

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

@@ -2,6 +2,8 @@
 
 > **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.
 
+本命令仅用于用户明确要求的独立多服务Cart，不能作为普通购买或错误恢复旁路。
+
 ## 服务报价的批准边界
 
 服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。

package/docs/cli-reference/commands/cart/show.md

@@ -15,7 +15,7 @@
 itpay cart show [--json] [--local]
 ```
 
-默认只读取本地保存的 canonical Cart 句柄并调用服务端。`--local` 只查看显式本地兼容草稿，不发 HTTP，也不会把该草稿解释成 canonical Cart。
+默认只读取本地保存的 canonical Cart 句柄并调用服务端。`--local` 只查看显式本地未验证草稿，不发 HTTP，也不会把该草稿解释成 canonical Cart。
 
 ## 标准输出
 
@@ -36,27 +36,7 @@ itpay cart show [--json] [--local]
 
 canonical 输出不得包含 Catalog variant/offer、line input、Service quote lock、完整 Service Execution 或重复 guidance。空 Cart 的 next 改为 `catalog list --json`。
 
-显式 local draft 返回 `shown_local` 或 `local_empty`：
-
-```json
-{
-  "status": "shown_local",
-  "result": {
-    "currency": "CNY",
-    "items": [
-      {
-        "catalog_item_id": "<item_id>",
-        "catalog_variant_id": "<variant_id>",
-        "offer_id": "<offer_id>",
-        "quantity": 1
-      }
-    ]
-  },
-  "instruction": "这是未验证的本地兼容草稿，只能用于明确的普通商品流程；不要把它当作 canonical Cart。",
-  "next": { "command": "itpay buy --json", "reason": "将普通本地草稿提交为 canonical Cart" },
-  "recovery": []
-}
-```
+显式 local draft 只展示未验证草稿（shown_local/local_empty）；不验证目录或价格，不能作为原购买恢复或授权替代。要继续独立Cart时只按当前返回的完整动作，不由示例生成新的购买命令。
 
 ## 异常处理
 

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

@@ -6,7 +6,7 @@
 
 读取已发布的服务目录，帮助 Agent 发现可启动的通用服务。Catalog 只描述产品和入口，不执行服务、不创建购物车。
 
-**上游：** `readyz`。
+**上游：** setup并启用同包Skill后，用户提出新服务需求。
 **下游：** [`catalog list`](list.md)，然后按目录中的 `service_id` 使用 `services start`。
 
 ## 子命令

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

@@ -1,47 +1,13 @@
 # `itpay catalog list`
 
-> **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.
-
-## 范围与意义
-
-列出当前 published Catalog。每个项目先说明用户真正购买的主服务，再说明免费或付费的辅助能力，避免把辅助消歧误称为最终服务。
-
-**上游：** `readyz`。
-**下游：** `services start <service_id>`。
-
-## 语法与参数
+读取已发布服务与公开操作，不运行服务、不创建资源。用户已有任务时沿原执行恢复，不重新发现一遍目录。
 
 ```bash
 itpay catalog list [--json]
 ```
 
-## 标准输出
-
-```json
-{
-  "status": "listed",
-  "result": {
-    "catalog_version": "<version>",
-    "services": [
-      {
-        "service_id": "<service_id>",
-        "title": "<product title>",
-        "description": "<what the user receives>",
-        "discovery": { "title": "<helper title>", "description": "<optional helper>", "free_quota": 3, "paid_price": "<optional price>" },
-        "primary_offer": { "title": "<offer title>", "description": "<deliverable>", "price": "<price>" }
-      }
-    ]
-  },
-  "instruction": "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
-  "next": { "command": "itpay --agent-type <agent_type> services start <service_id> --json", "reason": "启动用户选择的服务" },
-  "recovery": []
-}
-```
-
-## 异常处理
-
-输出不得包含 snapshot、manifest 原文、Arazzo workflow 或 Provider secret。服务为空时返回 `catalog_empty`，要求稍后重试，不猜服务 ID。
+返回 catalog_version 和服务摘要：公开 definition 包含服务名、用途、版本、entry、operation角色／价格及是否需要continuation。查询免费不等于票款免费；报价以当前确认材料为准。不存在定义时不猜operation或价格。
 
-## Agent Type / Host
+只有一项服务时 next 可提供该服务的完整入口，仍须匹配用户意图；多个服务时 next=null，由 Agent 根据原需求选当前 entry。不把带 service_id 或 agent_type 占位符的示意命令当成可执行next。空目录结束读取，不自动重试或猜ID。
 
-所有正式支持的 Local Agent Type 使用同一产品内容；只允许排版不同。
+输出不含manifest原文、供应商凭据或内部工作流。当前参数与实际错误来自help／运行返回；所有宿主目录事实一致。

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

@@ -6,7 +6,7 @@
 
 读取并恢复一笔已存在 Checkout 的公开展示状态。它不创建新 Checkout，也不把“用户说已付款”当作付款成功。
 
-**上游：** `buy` 或 `services checkout` 返回的 `checkout_id` 与 display token。
+**上游：** `services purchase`、明确独立Cart的 `buy` 或原 Checkout reader 返回的 `checkout_id` 与 display token。
 **下游：** 继续授权/付款、读取关联 Service Execution，或结束等待。
 
 ## 语法与参数
@@ -74,20 +74,6 @@ token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout
 }
 ```
 
-## Agent Type / Host
+## 宿主交付
 
-等待付款时：
-
-| Agent Type | Handoff |
-|---|---|
-| `codex-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
-| `codex-cli` | `url`；普通文本模式渲染终端二维码。 |
-| `claude-code-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
-| `claude-code-cli` | `url`；普通文本模式渲染终端二维码。 |
-| `workbuddy` | 返回 `url,agent_action`；原样执行一次 `present_files(files=[url])` 打开完整渲染的 HTML Card Link，不生成本地文件。 |
-| `zcode` | 返回 `url`；立即用 ZCode 内置浏览器打开，不只粘贴文字链接，也不生成或重建二维码文件。 |
-| `doubao-work` | 返回 `url,qr_image_url`；展示手机直达收银台链接和官方二维码图片链接，说明金额后停止。 |
-| `kimi-code` | `url`；普通文本模式渲染标准终端二维码。 |
-| `openclaw` | Telegram 为 `url,qr_image_url,agent_action`；instruction 强制原样执行 action。`📋 已授权给我读` callback 触发同一 Checkout 查询，再由 Backend 决定是否进入 grant 读取；其他显式 Host 为 `url,qr_image_url`。 |
-
-完成、退款或失效状态下所有 Agent Type 都只返回同一状态和下一步，不渲染二维码。OpenClaw 的 `--target` 必须使用原生 chat target 并传入展示层，不能添加 `telegram:` 前缀或被 CLI 参数解析后丢弃。
+采用正式 Skill 和当前 handoff 的宿主动作；原生工具不可用或可选图片失败时同轮展示原官方URL，不创建替代付款资源。callback与人的付款陈述都不证明支付；完成、退款或失效状态不再生成付款展示。

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

@@ -1,39 +1,10 @@
-# `itpay device`
+# itpay device
 
-`itpay` is the single public CLI entry point; `$itpay` is its user-facing Skill invocation.
+保持当前设备身份和实际Agent Type。正常授权与会话续期由CLI处理；业务错误不能触发身份替换或缓存清理。安装准备见install-and-setup，当前账号登录见identity-and-sessions。
 
-## Stable identity and ordinary recovery
+## 当前操作
 
-The original Ed25519 key stays at its existing location. Old `identity.json` v1/v2 is read-only compatibility data. Normal authorization does not acquire legacy locks, inspect processes, or create transition tickets/archives. Old lock files remain untouched.
-
-Each official Backend, actual Agent Type and current key fingerprint has its own atomic session cache. On a rejected session the CLI invalidates only that context, renews it, and retries the original request once. A second failure stops. Corrupt identity, missing original key, permission denial or unknown results never cause automatic key replacement. Do not delete identity, switch runtime/type or disable host protection.
-
-## `itpay device recover`
-
-Only after an operator confirms the selected Backend registration database was reset:
-
-```sh
-itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
-```
-
-This invalidates the selected Backend's caches, preserves the key, old identity and other Backend contexts, and returns a same-Backend/type `auth status` command. It does not contact the Backend itself or authorize business. Missing type or confirmation fails before mutation. Do not use it for expiry, revocation, quota or an unconfirmed failure.
-
-Success status is `backend_cache_invalidated` or `backend_cache_absent`; `result.invalidated_agent_types` records the affected types. The next device check proves the original key to the selected Backend and reuses its authoritative Device/key/quota lineage. No token or private key appears in output.
-
-## `itpay device repair-lock`
-
-```sh
-itpay device repair-lock --json
-```
-
-Compatibility explanation only: status `device_legacy_lock_unmanaged`, lock_status `unmanaged`, identity preserved. No legacy file is read, moved or deleted. This does not claim a lock was repaired. Ordinary authorization needs no lock cleanup.
-
-## `itpay device reset-key`
-
-This version does not support automatic device key reset. The command name and existing type/confirmation guards remain recognized:
-
-```sh
-itpay --agent-type <agent_type> device reset-key --confirm-key-reset --json
-```
-
-It returns nonzero `device_key_reset_unavailable`, next=null, recovery=[]; the original identity is unchanged. Do not delete a key manually, install an older version to reset it, or present this command as a recovery action. Restoring safe explicit key replacement requires a separately reviewed implementation.
+- status：读取当前设备状态。
+- recover：仅运营已确认当前Backend登记库重置，且用户明确授权时，带--confirm-backend-reset处理该Backend缓存。保留设备身份及其他环境状态；不是普通失败恢复动作。
+- repair-lock、reset-key：当前不可用，不能作为恢复动作；不改身份。reset-key保留--confirm-key-reset参数识别并返回明确错误。
+- --agent-type、--json：使用实际宿主类型和结构化输出。全部参数以当前--help为准；未知结果停止，不删除身份。

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

@@ -46,7 +46,7 @@ itpay docs show <topic> --json
 
 ## 异常处理
 
-随包文档目录缺失、文件损坏或合同字段不完整时返回 `docs_unavailable`，不暴露本地包路径；recovery 固定为重新安装当前 CLI 版本。
+随包文档缺失、损坏或合同字段不完整时按真实错误停止；由原安装方式修复当前制品，不生成另装全局CLI的恢复链。
 
 ## Agent Type / Host
 

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

@@ -45,25 +45,7 @@ itpay docs show <topic> [--json]
 
 ## 异常处理
 
-topic 不存在返回 `doc_not_found`：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "doc_not_found",
-    "message": "doc topic not found: <topic>"
-  },
-  "instruction": "使用稳定 topic 名称；不要根据标题猜 topic。",
-  "next": null,
-  "recovery": [
-    { "command": "itpay docs list --json", "reason": "列出全部 topic" },
-    { "command": "itpay docs search <topic> --json", "reason": "按关键词重新搜索" }
-  ]
-}
-```
-
-文档文件损坏使用 `docs_unavailable`，与 `docs list` 相同。
+topic 不存在按当前返回使用稳定topic名称；文档缺失／损坏使用真实错误停止，由原安装方式修复，不猜标题、编造命令或另装全局CLI。
 
 ## Agent Type / Host
 

package/docs/cli-reference/commands/feedback/submit.md

@@ -3,7 +3,7 @@
 ## 范围与意义
 
 在当前 Local Agent 完成一笔已有 Order 后，记录一次最小、安全的服务复盘。用户评分
-和原话均为可选；Agent 即使没有收到评分或评论，也要提交已知的服务结果上下文。CLI
+和原话均为可选；Agent 即使没有收到评分或评论，可以提交已知的安全服务结果上下文，复盘可选且不延迟交付。CLI
 通过 Feedback 专用选项接口选择真实项目，再调用现有 Feedback Owner。用户不需要知道
 Order ID、Order Item ID、Device 或 Agent Instance。
 
@@ -98,7 +98,7 @@ CLI 不读取或上传 Host 对话、WorkBuddy/ZCode sandbox 日志或其他本
 未评分时成功结果省略 `rating`。同一 submitter 在用户后来补充评分或评论时会更新
 现有记录并重新进入 `new`，不是创建第二条。
 
-如果用户没有给出评分或评论，Agent 仍提交 Context；成功 instruction 改为“无需打扰
+如果用户没有给出评分或评论，Agent 可选提交安全 Context；成功 instruction 改为“无需打扰
 用户”，不得声称用户表达过意见。
 
 ## 多项目 JSON
@@ -119,21 +119,9 @@ CLI 不读取或上传 Host 对话、WorkBuddy/ZCode sandbox 日志或其他本
 }
 ```
 
-## 错误合同
-
-| 状态/错误 | 行为 |
-| --- | --- |
-| `order_required` | 使用当前 exact Agent 的 `services list` 恢复原服务；找不到时指向官方订单页或原 Local Agent，不用账号订单/Vault 绕过。 |
-| `feedback_rating_invalid` | 用户提供了评分但格式不是 1–5；不提交、不猜测。 |
-| `feedback_note_too_long` | 请用户缩短；不截断、不提交。 |
-| `feedback_unavailable` | 该 Order 当前没有可反馈项目；不猜 ID。 |
-| `feedback_item_invalid` | 重新使用返回的项目 rank；不提交。 |
-| `feedback_not_available_for_agent` | 当前 Agent 不能代该订单提交；指向官方订单页或原 Local Agent，不切身份绕过。 |
-| `feedback_rejected` | 输入未被记录；只有用户修正明确输入后才重试。 |
-| `feedback_submission_unknown` | 无法确认是否记录；停止自动重试，只有用户明确要求后才再次提交。 |
-
-Feedback POST 不做自动 transport retry。虽然 Backend 使用 upsert，重放仍会更新记录
-并追加事件，CLI 不能把它当成无副作用查询。
+## 记录边界
+
+按实际返回的项目、权限与输入要求处理；缺真实评分不猜，无法确认记录结果就停止自动重试。Feedback POST 不做自动 transport retry；后台upsert仍会追加事件，不能当只读查询。原账号级读取授权、MCP或其他Agent历史不赋予写权限；不换身份绕过。复盘可选，不打断结果／官方入口交付。
 
 ## Agent Type / Host
 

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、权限、幂等和状态保护。