@itpay/cli 2.1.47 → 2.1.49

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

@@ -1,95 +1,14 @@
-# Account login
+# `itpay auth login` / `itpay auth status`
 
-`itpay auth` binds the enrolled Agent Device to a real ItPay account through an official authorization handoff. It is used by Path A (trial exhausted → log in → keep querying) and any time a command returns `login_required`. Path B purchases do **not** require running `itpay auth login` first — account authentication can happen inside the protected checkout instead.
-
-## Syntax
+按当前命令返回的登录需要，或用户明确要求登录时，创建一次官方账号授权；准备购买不要求额外先登录，用户可在受保护页面认证。
 
 ```bash
-itpay auth login  [--json]
+itpay auth login [--json]
 itpay auth status [--json]
 ```
 
-Both commands require an enrolled Agent Device and use the current `--agent-type` and Backend (`ITPAY_BACKEND_URL`). The Agent never receives an account bearer token; binding reuses the stable device-account ownership mechanism.
-
-## `itpay auth login`
-
-Creates one official authorization request bound to this Backend, Device and Agent Instance, then stops. Repeating `auth login` while a valid request is open returns the same request — it does not rotate the QR code or create parallel sessions.
-
-```json
-{
-  "status": "auth_pending",
-  "result": {
-    "dashboard_auth_session_id": "das_...",
-    "expires_at": "2026-09-20T12:34:56Z",
-    "methods": ["phone", "email", "alipay", "wechat"]
-  },
-  "handoff": {
-    "url": "https://dev.itpay.ai/signin?dashboard_auth_session_id=das_...&start_token=...",
-    "qr_local_path": "...",
-    "qr_image_url": "...",
-    "markdown": "..."
-  },
-  "instruction": "把官方授权页或二维码交给用户。用户在页面内选择手机号验证码、邮箱或钱包完成登录；不要替用户输入手机号或验证码。",
-  "next": {
-    "command": "itpay auth status --json",
-    "reason": "用户完成页面登录后确认绑定",
-    "poll_after_ms": 5000
-  },
-  "recovery": []
-}
-```
-
-- `handoff.url` is the official sign-in page carrying this authorization request. The page offers phone-code verification, email verification, and wallet options — the user chooses; the Agent must not deep-link a single wallet and call it universal authorization.
-- The URL's `start_token` is valid only inside the official page handoff. Never log it, echo it in chat, or send it to another host.
-- When the user already finished login before `auth login` runs, the command returns `authenticated` directly.
-
-## `itpay auth status`
-
-Polls the open authorization request, then performs the device binding. Safe to run repeatedly and concurrently: only the requester Device/Instance can complete the binding.
-
-```json
-{
-  "status": "auth_pending",
-  "result": { "dashboard_auth_session_id": "das_...", "expires_at": "..." },
-  "instruction": "用户仍在官方页面完成登录；保留当前 handoff，不要生成新二维码。",
-  "next": { "command": "itpay auth status --json", "poll_after_ms": 5000 },
-  "recovery": []
-}
-```
-
-```json
-{
-  "status": "authenticated",
-  "result": {
-    "buyer_id": "buyer_...",
-    "bound": true,
-    "query_quota": [
-      { "service_id": "itpay-rail-exact", "policy": "free_registered", "remaining": null },
-      { "service_id": "itpay-rail-smart", "policy": "free_registered", "remaining": null }
-    ]
-  },
-  "instruction": "登录与绑定已完成，告知用户可继续之前的查询；已注册账号查询不消耗试用次数，仍受正常限流。",
-  "next": { "command": "itpay services run <service_id> --execution <pending_execution_id> --json", "reason": "恢复被额度暂停的原查询" },
-  "recovery": []
-}
-```
-
-Terminal and error states:
-
-| `status` | Meaning | Agent action |
-| --- | --- | --- |
-| `authenticated` | Device bound to a real account | Resume the original intent (a quota-blocked execution, the user's request) unchanged |
-| `auth_pending` | User has not finished the page | Keep the same handoff; poll with `poll_after_ms` |
-| `auth_expired` | Session expired before completion | Offer to start `itpay auth login` again; prior query input is still preserved server-side |
-| `login_required` | No open request, not bound | Run `itpay auth login` |
-| `auth_cancelled` / `auth_denied` | User declined or closed the page | Respect the refusal; do not silently re-open; the pending query stays resumable |
-| `auth_session_missing` | Saved authorization session no longer exists (404/410) | `auth status` stays read-only; an explicit `auth login` may create one new official session |
-| `auth_status_unknown` | Transport or temporary server failure while reading status | Keep the same saved session and reread later; do not open a second login |
+使用当前真实 Agent Type、Backend 与已登记设备，不向 Agent 提供账号 bearer token。login 返回官方 handoff 后立即按 Skill 展示；人自行选择手机号、钱包或邮箱，一种已验证身份即可登录，其他身份按需绑定。不得替用户输入验证码、提交旅客资料或选择另一个账号。
 
-## Rules
+status 读取原授权并完成当前设备绑定，不创建另一条登录。用户完成后沿返回的原执行完整恢复命令继续，保留原地点、日期、人数与输入；不重新查询、不新建执行、不再询问相同行程。仍 pending 时保留原入口并遵守当次有界等待；读取故障不等于授权过期或取消，不新建登录掩盖故障。
 
-- The human's phone number and SMS code are entered only on the official page — never through chat or CLI input. A `buyer_id`, a typed phone string, or a passenger phone is **not** proof of phone verification.
-- Verified email OR verified mainland phone both establish a valid login; the user picks on the page. Phone verification is not a prerequisite for registered free search — a verified email alone is sufficient.
-- Login never grants Vault content, passenger history, or another Agent's authority. Other devices/platforms enroll and authorize separately.
-- After `authenticated`, server-side identity is re-read; an anonymous execution blocked at the quota step resumes with `services run <service> --execution <id> --json` — no new execution, no re-asked itinerary.
-- Refusing or cancelling login deletes nothing: saved results and purchase options remain usable.
+认证成功不等于购买同意、已付款或获得已购内容授权。真实拒绝、取消、过期或绑定失败采用当次事实和适用动作，没有恢复动作就停止。保留设备身份和其他环境登记，不旋转私钥或换 Agent Type。

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