@itpay/cli 2.1.41 → 2.1.44

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

@@ -0,0 +1,96 @@
+# Account login
+
+`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 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 |
+
+## Rules
+
+- 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.
+- Seller authoring uses `itpay sell auth` separately.

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

@@ -1,6 +1,6 @@
 # `itpay buy`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -169,6 +169,7 @@ itpay buy \
 | `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；其他入口直接展示图片和链接。 |
 

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

@@ -1,6 +1,10 @@
 # `itpay cart add`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
+
+## 服务报价的批准边界
+
+服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay cart clear`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay cart`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 命令范围
 

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

@@ -1,6 +1,10 @@
 # `itpay cart next`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
+
+## 服务报价的批准边界
+
+服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay cart remove`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay cart show`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay catalog`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 命令范围
 

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

@@ -1,6 +1,6 @@
 # `itpay catalog list`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -40,7 +40,7 @@ itpay catalog list [--json]
 
 ## 异常处理
 
-输出不得包含 snapshot、manifest 原文、compiled graph 或 Provider secret。服务为空时返回 `catalog_empty`，要求稍后重试，不猜服务 ID。
+输出不得包含 snapshot、manifest 原文、Arazzo workflow 或 Provider secret。服务为空时返回 `catalog_empty`，要求稍后重试，不猜服务 ID。
 
 ## Agent Type / Host
 

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

@@ -1,6 +1,6 @@
 # `itpay checkout`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -13,7 +13,10 @@
 
 ```bash
 itpay checkout [--id <checkout_id>] [--token <display_token>]
-  [--host <host>] [--target <target>] [--locale <zh-CN|en>] [--json]
+  [--host <host>] [--target <target>] [--locale <zh-CN|en>]
+  [--present <auto|browser|image|link|none>] [--no-open] [--viewer <desktop|mobile|unknown>]
+  [--relay-option <ref>] [--confirm-relay] [--request-key <key>] [--relay-status <relay_id>]
+  [--json]
 ```
 
 省略 `--id/--token` 时只能使用本机保存的一组完整句柄；不得把其他 Checkout 的 token 拼接使用。
@@ -22,6 +25,12 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
 
 `--locale` 默认 `zh-CN`，可显式使用 `en`。它只改变重新渲染的 Card 文案，不改变 Checkout、付款、授权或恢复状态。
 
+展示控制（display plane，不创建任何新的付款路径）：
+
+- `--present` 一次只选一种展示方式：`browser` 打开系统浏览器、`image` 展示官方二维码图片、`link` 给出可点击链接、`none` 只说明状态、`auto`（默认）按宿主能力选择一种。`--json` 下默认只返回展示计划而不执行打开；显式 `--present browser` 即是一次打开请求。`ITPAY_NO_BROWSER=1` 与 `--no-open` 都禁止打开浏览器。已付款、已退款或报价失效的 Checkout 不会发起任何展示动作，只读取原状态。
+- `--viewer` 告知用户正在看哪类设备：`mobile` 时不会把二维码当作同机可读方式；`desktop` 时才考虑打开浏览器。
+- 消息转发（relay）要求服务端已签发的脱敏联系人引用 `--relay-option`、稳定幂等键 `--request-key` 和显式人类同意 `--confirm-relay`，三者缺一不可；CLI 不自行发送短信或邮件。`--relay-status <relay_id>` 只读取一次既有转发结果，绝不重发。`--present` 与 relay 互斥。当前 Backend 未提供 relay 能力时会如实返回不可用。
+
 ## 等待付款输出
 
 ```json
@@ -77,6 +86,7 @@ token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout
 | `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`。 |
 

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

@@ -1,10 +1,12 @@
 # `itpay device` / `itpay device recover`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围
 
-`itpay device` 只显示该命令组的帮助并退出，不访问 Backend、不读取或修改身份。当前唯一子命令是 `recover`。
+`itpay device` 只显示该命令组的帮助并退出，不访问 Backend、不读取或修改身份。当前子命令是 `repair-lock`（检查并修复已退出进程留下的本地锁）、`recover`（运营确认 Backend 重置后删除本地登记）和 `reset-key`（服务端拒绝当前私钥登记时放弃本地密钥）。
+
+`itpay device repair-lock --json` 只检查本地锁，保留 Device identity；活跃锁返回 `device_lock_active`，过期锁修复后返回 `device_lock_recovered`，无锁返回 `device_lock_absent`。
 
 仅在运营明确确认当前 Backend 的 Device 登记数据库已重建或清空后，删除本地该 Backend 的 v2 registration：
 
@@ -12,18 +14,29 @@
 itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 ```
 
-命令只作用于当前官方 Backend 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。默认是 `https://app.itpay.ai`；显式测试可使用准确的 `ITPAY_BACKEND_URL=https://dev.itpay.ai`。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 会保留同一 Backend，是重新登记入口。
+命令只作用于当前官方 Backend 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。默认是 `https://app.itpay.ai`；显式测试可使用准确的 `ITPAY_BACKEND_URL=https://sandbox.itpay.ai`。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 会保留同一 Backend，是重新登记入口。
 
 同一台电脑上的多个 Local Agent Type 共享本地 Device key，但各自使用独立 Agent
 Instance。CLI 只在原子更新 Device state 时使用短期本地锁；释放和 stale recovery
 通过 rename 完成，不依赖 Host 删除文件，因此 WorkBuddy 等 sandbox 的
 safe-delete/trash shim 不应阻断正常命令。该锁不在 Backend，不会让另一台电脑或
 另一个 Buyer 等待。遇到本地锁错误时不得删除 `~/.itpay-v3/device`、切换 Agent
-Type 或执行 `device recover`；应保留身份并重试原命令一次，持续失败时报告
-`device_state_unwritable` 或 lock timeout。
+Type 或执行 `device recover`；锁忙用 `itpay device repair-lock --json` 检查，只回收已退出进程的锁。写盘权限错误按返回事实恢复宿主允许的持久写入权限后重试原命令，保持原身份。
 
 缺少确认参数返回 `backend_reset_confirmation_required`。普通 session 失效由 CLI 自动续期；revoked、quota、权限或未知 Backend 故障不得使用本命令。所有 Agent Type 使用相同输入和输出合同。
 
+## `itpay device reset-key`
+
+仅在确认当前密钥不可恢复，且服务端返回 `agent_device_key_rotated` / `agent_device_key_conflict` 时使用；`internal_error` 是服务端故障，不能据此重置身份。必须指定真实 Agent Type 并取得明确确认。这是本地操作，不访问 Backend：
+
+```bash
+itpay --agent-type <agent_type> device reset-key --confirm-key-reset --json
+```
+
+命令删除本地 Ed25519 私钥并清空所有 Backend 的本地登记记录；下一次需要设备身份的命令会以全新密钥重新登记为新设备。服务端旧设备记录保留为孤儿，不会被删除或复用；原设备的额度谱系不迁移。正常续期与登记由 CLI 既有逻辑处理；仅在用户或运营明确决定放弃旧身份后才可执行换钥，旧执行访问不会迁移。锁超时使用 repair-lock，不重复登记或换钥。
+
+缺少确认参数返回 `key_reset_confirmation_required`；本地文件操作失败返回 `device_key_reset_failed`。本命令不得删除 Cart、operation journal 或 `~/.itpay-v3` 的其他内容。
+
 ## 参数
 
 | 参数 | 必填 | 说明 |
@@ -55,9 +68,3 @@ Type 或执行 `device recover`；应保留身份并重试原命令一次，持
 当前 Backend 已无本地登记时，`status` 为 `backend_registration_absent`、`removed_agent_types=[]`，其余合同不变。文本输出只包含 Backend、registration 状态、私钥保留和其他 Backend 保留四项，不输出私钥、公钥、Device ID、Agent Instance ID、session、token 或本地文件内容。
 
 缺少 Agent Type 返回 `agent_type_required`；缺少确认返回 `backend_reset_confirmation_required`。其他本地恢复失败返回 `device_recovery_failed`。所有失败都必须发生在删除 registration 前；本命令不得删除整把 Device identity、Cart、operation journal 或其他 Backend 登记。
-
-## `itpay device status --json`
-
-先核验当前 Backend 合同，再通过既有设备挑战与签名验证获取当前认证事实。首次可能登记设备及该宿主，后续复用同一私钥和登记，强制验证当前服务端状态而非只读取缓存。成功返回 `device_ready`、agent_type、expires_at、backend_url 与 account_binding=unavailable；不返回 token/私钥/签名，不读取业务或订单。不支持账号绑定读取不等于未登录，也不提供不存在的 auth login。
-
---json 输出标准 envelope；普通文本直接可读。合同、身份或网络故障停止本轮，next=null，不自动重建身份、登录或交易。

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

@@ -1,6 +1,6 @@
 # `itpay docs`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 命令范围
 

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

@@ -1,6 +1,6 @@
 # `itpay docs list`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay docs search`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay docs show`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay install`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -18,10 +18,10 @@ itpay install [target] [--json]
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `target` | 否 | 八种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
+| `target` | 否 | 九种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
 | `--json` | 否 | 返回标准命令 envelope；推荐 Agent 使用。 |
 
-正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`zcode`、`kimi-code`、`openclaw`。
+正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`zcode`、`doubao-work`、`kimi-code`、`openclaw`。
 
 ## 指定 Agent Type 输出
 
@@ -77,7 +77,7 @@ OpenClaw 额外明确没有默认入口：
 
 ## 列表输出
 
-省略 target 或传 `list` 时返回八组运行时定义，不重复每种类型的完整 instruction：
+省略 target 或传 `list` 时返回九组运行时定义，不重复每种类型的完整 instruction：
 
 ```json
 {
@@ -90,6 +90,7 @@ OpenClaw 额外明确没有默认入口：
       { "agent_type": "claude-code-cli", "default_host": "terminal" },
       { "agent_type": "workbuddy", "default_host": "plain-chat" },
       { "agent_type": "zcode", "default_host": "plain-chat" },
+      { "agent_type": "doubao-work", "default_host": "plain-chat" },
       { "agent_type": "kimi-code", "default_host": "terminal" },
       {
         "agent_type": "openclaw",
@@ -120,8 +121,9 @@ OpenClaw 额外明确没有默认入口：
 | `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止。Checkout 原样执行返回的 `present_files` action，打开渲染后的 Card Link。 |
+| `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，其他入口展示标准二维码和链接。 |
 
@@ -140,7 +142,7 @@ OpenClaw 额外明确没有默认入口：
     "code": "unsupported_agent_type",
     "message": "unsupported install target: codex"
   },
-  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, kimi-code, openclaw。",
+  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, doubao-work, kimi-code, openclaw。",
   "next": null,
   "recovery": [
     {

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

@@ -1,6 +1,6 @@
 # `itpay next`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay order`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay pay`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,12 +1,12 @@
 # `itpay readyz`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
-检查当前官方 Backend 是否可用。默认使用生产环境 `https://app.itpay.ai`；仅测试时可通过 `ITPAY_BACKEND_URL=https://dev.itpay.ai` 选择官方开发环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
+检查当前官方 Backend 是否可用。默认使用生产环境 `https://app.itpay.ai`；仅测试时可通过 `ITPAY_BACKEND_URL=https://sandbox.itpay.ai` 选择官方沙箱环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
 
-**上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 或 `https://dev.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
+**上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 或 `https://sandbox.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
 **下游：** 完整 `itpay` Skill；由 Agent 根据用户意图选择新服务、已购内容、订单或退款入口。
 
 ## 语法与参数
@@ -31,21 +31,21 @@ itpay readyz [--json]
 }
 ```
 
-开发环境返回同一 envelope，但明确标记环境并在每个后续命令中保留 dev Backend：
+沙箱环境返回同一 envelope，但明确标记环境并在每个后续命令中保留 sandbox Backend：
 
 ```json
 {
   "status": "ready",
-  "result": { "backend": "available", "backend_url": "https://dev.itpay.ai", "environment": "development" },
-  "instruction": "ItPay dev 可用。先完整读取内置 Skill，再根据用户意图选择新服务、已购内容、订单或退款入口；后续必须执行返回的完整命令并保持同一 dev Backend。",
-  "next": { "command": "ITPAY_BACKEND_URL=https://dev.itpay.ai itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
+  "result": { "backend": "available", "backend_url": "https://sandbox.itpay.ai", "environment": "development" },
+  "instruction": "ItPay sandbox 可用。先完整读取内置 Skill，再根据用户意图选择新服务、已购内容、订单或退款入口；后续必须执行返回的完整命令并保持同一 sandbox Backend。",
+  "next": { "command": "ITPAY_BACKEND_URL=https://sandbox.itpay.ai itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
   "recovery": []
 }
 ```
 
 ## 异常处理
 
-已收到 Backend 不可用响应等非传输异常时返回 `backend_unavailable`。尚未收到完整 HTTP 响应的临时传输失败使用 conventions 中对应的稳定 `network_*` 错误码；`readyz` 是 GET，按全局安全传输合同最多自动重试两次。两类错误都要求等待当前官方 Backend 恢复后重试同一完整命令，不得在失败时切换环境或继续下单。
+已收到 Backend 不可用响应等非传输异常时返回 `backend_unavailable`。尚未收到完整 HTTP 响应的临时传输失败使用 conventions 中对应的稳定 `network_*` 错误码；`readyz` 是 GET，按全局安全传输合同最多自动重试两次。有限尝试结束后本轮检查未完成，next=null、recovery=[]；网络恢复后可以重新检查，不得在失败时切换环境或继续下单。
 
 非官方 URL 返回 `backend_override_forbidden`，且不提供自动 recovery：
 
@@ -54,15 +54,15 @@ itpay readyz [--json]
   "status": "error",
   "error": {
     "code": "backend_override_forbidden",
-    "message": "ITPAY_BACKEND_URL only supports https://app.itpay.ai or https://dev.itpay.ai"
+    "message": "ITPAY_BACKEND_URL only supports https://app.itpay.ai or https://sandbox.itpay.ai"
   },
-  "instruction": "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://dev.itpay.ai。",
+  "instruction": "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://sandbox.itpay.ai。",
   "next": null,
   "recovery": []
 }
 ```
 
-minimum_cli_version 仅为协议门槛，不是经过核验的推荐制品。兼容失败保留当前 CLI/API、平台API及版本窗口事实；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
 

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

@@ -1,6 +1,6 @@
 # `itpay refund cancel`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay refund create`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay refund get`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -48,7 +48,7 @@ itpay refund get <refund_request_id> [--json]
 ## 终态
 
 - `succeeded`：先告诉用户退款已由 ItPay 确认成功，交付永久关闭，`next=null`。
-- `cancelled/rejected`：说明退款没有执行，交付资格可恢复，但旧 grant 不复活，需要用户重新授权，`next=null`。
+- `cancelled/rejected`：说明退款没有执行，交付资格依当前订单和 owner 状态判断；旧 grant 不复活，按返回动作决定是否需要新的授权，`next=null` 时不自行创建。
 - `failed + known_no_effect`：说明退款请求确认未发送；Agent 不重试，由平台管理员决定是否重新执行，`next=null`。
 - `failed + retryable`：说明渠道明确返回可重试失败但 Agent 不会自行重试；等待平台管理员处理，`next=null`。
 - `failed + outcome_unknown`：说明渠道结果未知、交付继续锁定且必须先对账；禁止重试或重复申请，`next=null`。

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

@@ -1,6 +1,6 @@
 # `itpay refund`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 命令范围
 

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

@@ -1,6 +1,6 @@
 # `itpay refund list`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay refund watch`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义