@itpay/cli 2.1.34 → 2.1.41

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

@@ -1,27 +1,25 @@
 # `itpay services invoke`
 
-> **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.
+> **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.
 
 ## 范围与意义
 
 调用当前 phase 允许的非付费 Agent-visible capability。输入先按 capability schema 校验，校验失败不得迁移 execution 或记录 Provider 已调用。
 
 **上游：** `services start/next` 明确返回 invoke。
-**下游：** 候选结果、人工 action 或付费 Quote。此页的候选人工选择示例适用于相应的非铁路服务；铁路按 `rail-booking` 的已保存结果和委托选择合同。Provider 错误先按实际错误码和当前 execution 状态恢复，不猜新输入或自动新建。
+**下游：** 候选结果、人工 action 或付费 Quote。一次 invoke 没有结果或返回 Provider 错误时必须停止；只有用户之后明确提供新输入，才启动新的 execution。
 
 ## 语法与参数
 
 ```bash
 itpay services invoke <service_execution_id> --capability <capability_id>
-  [--input <key=value> ... | --input-json <file>] [--json]
+  [--input <key=value> ...] [--json]
 ```
 
-`--input` 可重复；必填 key 来自 `input_schema.required`，值按 schema 类型解析。Agent 不猜字段名。嵌套对象使用已有 JSON 文件读取方式 `--input-json <file>`；文件必须是完整对象，与 `--input` 二选一，冲突或解析失败不会调用供应商。
+`--input` 可重复；必填 key 来自 `input_schema.required`，值按 schema 类型解析。Agent 不猜字段名。
 
 ## 有结果输出
 
-以下是非铁路候选服务的示例。铁路使用 `services run` 和 `services read-result` 返回的范围、完整紧凑目录与当前动作；不要把这里的 `select_candidate` 人工动作套用到已授权委托的铁路选择。
-
 ```json
 {
   "status": "result_ready",

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

@@ -1,6 +1,6 @@
 # `itpay services list`
 
-> **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.
+> **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.
 
 ## 范围与意义
 

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

@@ -1,36 +1,34 @@
 # `itpay services next`
 
-> **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.
+> **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.
 
 ## 范围与意义
 
 读取一笔 Service Execution 的当前状态，并只返回一个首选下一步。若交付模式允许 Agent 直接读取，本命令同时返回完整 safe result。
 
 **上游：** `services start`、`invoke`、`action`、`checkout`，或一次中断恢复。  
-**下游：** 一个可执行命令、需要用户完成的候选选择或授权，或 Arazzo workflow 真正到达终态。
+**下游：** 一个可执行命令、需要用户完成的候选选择或授权，或 Graph 真正到达终态。
 
-本命令不返回原始 Backend DTO、capability 列表、内部 result ID/hash、Arazzo workflow、binding 或重复 guidance。
+本命令不返回原始 Backend DTO、capability 列表、内部 result ID/hash、graph、binding 或重复 guidance。
 
 Backend 会根据当前 capability 选择 `current_delivery`；完整 `delivery_bindings` 仅是历史记录。CLI 不按数组位置猜测当前交付，同一 Execution 后续产生的新交付会取代旧交付成为默认结果。
 
 ## 语法与参数
 
 ```bash
-itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapshot <snapshot_id>] [--json]
+itpay services next <service_execution_id> [--json]
 ```
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
 | `service_execution_id` | 是 | `services start` 或后续命令返回的 execution ID。 |
-| `--timeout <seconds>` | 否 | 同一执行上的有界只读等待，0–120 秒，默认 0；查询等待中的推荐命令使用 120。已有业务结果、真实用户动作或终态会提前返回。 |
-| `--since-snapshot <snapshot_id>` | 否 | rail.progressive.v2 增量读：传上次看到的 `snapshot_id`，未变化时只回扩展状态与 `result_not_updated`，不重复下发 journey 负载；永远不触发供应商调用。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
 需要有效 Agent Device session。命令不接受 Buyer token、capability 或服务输入。
 
-## 非铁路服务的候选选择
+## 候选选择
 
-免费或付费候选已经产生、Arazzo workflow 允许继续选择时，恢复输出必须包含当前 Result Set 的安全候选：
+免费或付费候选已经产生、Graph 允许继续选择时，恢复输出必须包含当前 Result Set 的安全候选：
 
 ```json
 {
@@ -50,9 +48,9 @@ itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapsh
 }
 ```
 
-该列表来自 Backend 的 `current_result_items`，CLI 不缓存或合并其他 Execution 的候选。铁路 Exact 的正常返回改走 `read-result` 已保存车次行及逐行 `detail.command`；Smart 的委托选票用 `select_delegated`（actor-type agent），只有用户亲自选定才用 `select_user_chosen`（actor-type human）。
+该列表来自 Backend 的 `current_result_items`，CLI 不缓存或合并其他 Execution 的候选。
 
-## 非铁路服务的 Agent-visible 结果
+## Agent-visible 结果
 
 ```json
 {
@@ -78,7 +76,7 @@ itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapsh
 }
 ```
 
-只有 Arazzo workflow 允许继续选择时才返回上述 `next`。若结果本身就是最终交付，instruction 要求用普通语言解释可公开字段并停止，且 `next: null`。文本输出可以保留 Agent 执行所需的 Execution 与 `delivery_mode`，但 Agent 不向用户暴露这些内部词、Result Item ID、Invocation ID 或 Hash。
+只有 Graph 允许继续选择时才返回上述 `next`。若结果本身就是最终交付，instruction 要求用普通语言解释可公开字段并停止，且 `next: null`。文本输出可以保留 Agent 执行所需的 Execution 与 `delivery_mode`，但 Agent 不向用户暴露这些内部词、Result Item ID、Invocation ID 或 Hash。
 
 ## Vault 交付
 
@@ -93,7 +91,7 @@ itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapsh
     "delivery_mode": "vault_artifact",
     "grant_status": "none"
   },
-  "instruction": "这是当前 Arazzo step 对应的交付；请用户在订单页面授权，未授权前不要读取或猜测内容。",
+  "instruction": "这是当前 Graph 步骤对应的交付；请用户在订单页面授权，未授权前不要读取或猜测内容。",
   "next": {
     "command": "itpay services read-result <id> --json",
     "reason": "仅在用户确认授权后执行"
@@ -143,7 +141,7 @@ itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapsh
     "grant_status": "active",
     "grant_expires_at": "<RFC3339 time>"
   },
-  "instruction": "这是当前 Arazzo step 对应的交付；用户授权有效，立即读取并遵守字段范围与到期时间。",
+  "instruction": "这是当前 Graph 步骤对应的交付；用户授权有效，立即读取并遵守字段范围与到期时间。",
   "next": {
     "command": "itpay services read-result <id> --json",
     "reason": "读取当前有效 grant 的结果"
@@ -197,89 +195,7 @@ itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapsh
 }
 ```
 
-`succeeded` 退款改为“交付永久关闭”，并返回 `next: null`。取消、拒绝或确定未产生资金影响的失败退款不再阻塞，但旧 grant 不会复活；是否需要新的交付授权由当前 owner 状态与返回动作决定。
-
-## 额度暂停（试用/限流）
-
-查询 Execution 因免费试用耗尽或限流被暂停时，状态为 `login_required` 或 `rate_limited`（不是 `failed`）。Execution 保留输入，可用同一 `services run <service> --execution <id> --json` 恢复——登录后或限流窗口过后从额度节点继续，不重放已完成阶段，不要新建 Execution 或重述行程。
-
-```json
-{
-  "status": "login_required",
-  "result": {
-    "service_execution_id": "<id>",
-    "service_id": "itpay-rail-exact",
-    "admission": "login_required",
-    "query_quota": [
-      { "service_id": "itpay-rail-exact", "used": 2, "limit": 2, "remaining": 0 },
-      { "service_id": "itpay-rail-smart", "used": 0, "limit": 2, "remaining": 2 }
-    ]
-  },
-  "instruction": "如实告知该服务的免费试用次数与剩余；请用户登录后继续，原查询无需重新输入。",
-  "next": { "command": "itpay auth login --json", "reason": "官方登录绑定后继续免费查询" },
-  "recovery": [
-    { "command": "itpay services run itpay-rail-exact --execution <id> --json", "when": "auth_bound" }
-  ]
-}
-```
-
-`rate_limited` 只等待 `retry_after_ms` 后恢复同一执行；不需要登录、不扣试用。
-
-## 查询结果中的购买承接
-
-铁路查询结果项可携带服务端签发的购票承接 `booking_offer`：
-
-```json
-{
-  "rank": 1,
-  "title": "C6908 二等座 11:48→12:20",
-  "safe_payload": { "...": "..." },
-  "booking_offer": {
-    "service_id": "itpay-rail-booking",
-    "selection_token": "sel_...",
-    "expires_at": "2026-09-20T04:00:00Z"
-  }
-}
-```
-
-用户明确选择某班次/席别并要求购买时，用该 token 开启购票执行：
-
-```bash
-itpay services run itpay-rail-booking --input-json booking.json --json
-# booking.json: {"passengers": 1, "selection": {"token": "<selection_token>", "seat_type": "O"}}
-```
-
-`booking_offer` 只是受条件约束的可选承接：查询完成本身已满足查询目标，不自动购买。过期 token 不会因重读保存结果而恢复；按当前 owner 错误与用户原请求取得新的实时选择证据，不手工拼装 `legs` 绕过失效凭据。
-
-## 订票确认（booking review）
-
-`itpay-rail-booking` 在报价前停在 `workflow:confirm_booking` 人工确认节点。`services next` 返回 `booking_review_required`，`human_action.context.review` 携带服务端投影：`draft_revision`、`legs`（含可编码的 `seat_options`）、`notice_version` 等。乘客身份信息永不在此投影，也不经 CLI 提交。
-
-```json
-{
-  "status": "booking_review_required",
-  "result": {
-    "service_execution_id": "<id>",
-    "service_id": "itpay-rail-booking",
-    "human_action": {
-      "action_type": "workflow:confirm_booking",
-      "context": { "review": { "draft_revision": 1, "legs": [], "seat_options": {} } }
-    },
-    "required_fields": ["draft_revision", "passengers", "seat_type", "seat_preferences", "party_preference", "fallback", "notice_version", "accept_non_guaranteed"]
-  },
-  "instruction": "向用户展示行程与可选席别/座位偏好词表，并明确告知：座位偏好仅为请求、不保证分配。收集后经 --input-json 提交完整 JSON；draft_revision 以服务端当前值为准。",
-  "next": null,
-  "interaction": { "input_template": { "command": "itpay services action <id> --action workflow:confirm_booking --actor-type human --status approved --input-json <file> --json", "executable": false } },
-  "recovery": [{ "command": "itpay services next <id> --json", "reason": "重新读取当前 draft_revision 后重试" }]
-}
-```
-
-规则：
-
-- `seat_preferences` 逐乘客一条，`passenger_index` 从 0 起、人数 1–5、取值限该席别 `seat_options`；`party_preference`、`fallback=automatic_assignment`、`notice_version`、`accept_non_guaranteed=true` 全部必填。
-- `draft_revision` 必须等于投影值；服务端返回 `booking_review_changed` 时重新 `services next` 读取后重试，不得自行递增或重放旧 revision。
-- 付款暂停且 review 仍开放时，`next` 指向 Checkout 恢复，`recovery` 附带修订命令（`services action … confirm_booking --input-json`）——修订回到同一执行重新报价，不产生第二笔订单或付款。
-- 支付已在途/完成后 review 关闭，修订被拒绝；按返回的同一订单状态继续，不得新建执行。
+`succeeded` 退款改为“交付永久关闭”，并返回 `next: null`。取消、拒绝或确定未产生资金影响的失败退款不再阻塞，但旧 grant 不会复活；用户必须重新授权。
 
 ## 异常处理
 
@@ -294,12 +210,3 @@ itpay services get <service_execution_id> --json
 ## Agent Type / Host
 
 所有正式支持的 Local Agent Type 返回完全相同的状态、safe payload、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。
-
-## 渐进规划（rail.progressive.v2）
-
-智能铁路规划服务在执行读模型上附带 `rail_planning` 投影：`readiness`（pending/ready/expired）、`search.expansion_status`（queued/running/paused/complete/cancelled/failed/expired）、`recommendation` 与 `alternatives` 行程卡片、以及服务端给出的完整 `available_actions` 命令。
-
-- `running`/`queued`：稍后按 `next.command` 增量轮询同一执行；不要重新发起查询。
-- `paused`：首批结果已就绪、扩展暂停等待用户意图；`expand_search` 是唯一会再消耗供应商配额的动作。
-- `complete`：扩展收敛；比较任务已满足就展示推荐并停止，购买委托则按明确规则选择。
-- 选票走 `select_journey` 动作：卡片的 `select_delegated` 供已授权委托的 Agent 选择，`select_user_chosen` 仅用于用户亲自选定；乘车人身份信息永远只在受保护 Checkout 页面填写。

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

@@ -1,6 +1,6 @@
 # `itpay services quote`
 
-> **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.
+> **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.
 
 ## 范围与意义
 
@@ -8,7 +8,7 @@
 
 本命令是多 Execution 合并付款的高级入口。普通单 Execution 流程应使用 `services checkout`，不要把 `services quote` 当作 Checkout 失败后的替代路径。
 
-**上游：** 用户明确要求合并多个独立 Execution，且每个 Execution 的 Arazzo workflow 当前都允许 `prepare_quote`。
+**上游：** 用户明确要求合并多个独立 Execution，且每个 Execution 的 Graph 当前都允许 `prepare_quote`。
 
 **下游：** `cart add --quote`。多个独立 Execution 的 Quote 可以加入同一 Cart。
 
@@ -57,7 +57,7 @@ itpay services quote <service_execution_id> --capability <capability_id>
 - `capability_input_invalid`：缺少 required input；不创建 Quote、Cart 或 Checkout。
 - `delivery_email_required`：先说明邮箱用于交付 claim link，再询问用户；禁止代填。
 - 候选未确认、来自其他 Execution、Quote 已存在冲突：Backend 拒绝且不改变 Execution。
-- `service_quote_not_allowed`：当前 Arazzo workflow 不允许从当前 Execution 状态购买该 capability；不得换 capability、新建 Execution 或尝试其他购买命令，只回到同一 Execution 的 `services next`。
+- `service_quote_not_allowed`：当前 Graph 不允许从当前 Execution 状态购买该 capability；不得换 capability、新建 Execution 或尝试其他购买命令，只回到同一 Execution 的 `services next`。
 - Backend 不支持当前交易合同时返回 `backend_contract_incompatible`，必须停止，不能改用 `services checkout`、`cart`、`buy` 或 `pay` 绕过。
 
 ## Agent Type / Host

package/docs/cli-reference/commands/services/read-result.md

@@ -1,36 +1,25 @@
 # `itpay services read-result`
 
-> **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.
+> **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.
 
 ## 范围与意义
 
-同一命令读取三种已保存结果：铁路 Exact 车次按页读取为紧凑业务行、铁路 Smart 快照分页紧凑车次目录，或持有效 grant 读取 Vault 保护内容。铁路读取免费、只读且不重新调用供应商。
+使用当前 Agent Device Authority，在用户创建的有效、未过期且范围匹配的 grant 内读取 Vault 保护结果。它不适用于 `agent_visible_result`。
 
-**上游：** 铁路查询的已保存结果入口，或 `services next` 返回 `vault_artifact` 且用户已在订单页面授权。
-**下游：** 铁路紧凑行中使用逐行 `detail.command` 读取购买条件；Vault 仅在 grant scope 和 TTL 内使用返回字段。
+**上游：** `services next` 返回 `vault_artifact`，且用户已在订单页面授权。  
+**下游：** Agent 仅在 grant scope 和 TTL 内使用返回字段；没有自动后续命令。
 
 ## 语法与参数
 
 ```bash
-itpay services read-result <service_execution_id> [--snapshot <snapshot_id>] [--journey <journey_id>] [--offset <offset>] [--limit <limit>] [--all] [--json]
+itpay services read-result <service_execution_id> [--json]
 ```
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `service_execution_id` | 是 | 铁路查询或 Vault 交付对应的 execution ID。 |
-| `--journey <journey_id>` | 否 | rail.progressive.v2 规划明细：读取指定 journey 的分段与席别选项；票计划按页返回。免费、属主校验、不触发供应商调用。 |
-| `--snapshot <snapshot_id>` | 否 | 单独使用时读取该 Smart 已提交快照的紧凑线路页；与 `--journey` 配合时读取该线路详情页。 |
-| `--offset <offset>` | 否 | Exact / Smart 保存结果从零开始的页偏移；不改变快照或重新查询。 |
-| `--limit <limit>` | 否 | 保存结果当前页条数，1–20；Exact默认20条，Smart默认3条完整线路或3个票计划；必要时按最终输出字节缩小整行页。 |
-| `--all` | 否 | 显式兼容读取 Exact / Smart 保存目录全量；输出可能很大，常规读取应沿当前页的 next.command。 |
+| `service_execution_id` | 是 | Vault 交付对应的 execution ID。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
-Exact 执行按 offset/limit 读取已保存车次，返回 total、offset、count 和同一 read-result 的续页入口；不会把前100条冒充完整范围。Smart 使用 `--snapshot` 读取固定快照的默认小页，或用 `--journey` 读一条线路的票计划页；按返回的 next.command 续读同快照。这些读取不走 Vault grant。其他服务不带选择器时保持原授权路径。
-
-Smart 保存目录按本次主推荐、其他合格线路、不可用或资格未知的诊断线路排列；`total` 仍是全部已保存时刻组合数，`qualification_counts` 分别说明当前合格、不合格、未知数。诊断线路保留车次、时刻和 `qualification_reasons`，其 `detail.command` 用于查看事实与原因，不表示可以购买。只有 `qualification_status=eligible` 且逐段票方案完整时，才给当前购买入口。历史快照缺资格字段按未知展示。`--all` 仍读取全部事实，不会重新查询铁路。
-
-进度中的“保存组合”是具体车次与时刻组合数，不是不同站序数；“合格线路”按组合去重，profile 是同一组合下可推荐的席别及接驳选项数。模型实际调用和看到的合格组合以快照 coverage 为准；未穷尽范围不能称全网最优。推荐说明只披露当前方案实际涉及的地面交通、无座、跨日和分段票限制。
-
 CLI 使用已登记设备的签名 session，不接受 Checkout token、Buyer token、`agent_device_id` 参数或开发者凭证。
 
 CLI 直接请求 Backend 的当前有效 Grant。历史 `delivery_bindings` 不作为访问判断；Backend 负责验证当前 Vault、Agent instance、Buyer、scope、TTL 和退款锁。

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

@@ -1,6 +1,6 @@
 # `itpay services start`
 
-> **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.
+> **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.
 
 ## 范围与意义
 
@@ -44,7 +44,7 @@ itpay --agent-type <agent_type> services start <service_id>
 }
 ```
 
-Start API 只提供免费额度上限，不提供当前剩余额度，因此本命令不得虚构 `remaining`。不得输出全部 capability DTO、contract version、Arazzo workflow、buyer/device ID 或重复 guidance。若服务不存在，recovery 为 `catalog list`。设备 session 由 CLI 自动登记或刷新；401 `agent_device_session_required` 仅续期并重试一次，仍失败时返回错误，不循环。
+Start API 只提供免费额度上限，不提供当前剩余额度，因此本命令不得虚构 `remaining`。不得输出全部 capability DTO、contract version、graph ID、buyer/device ID 或重复 guidance。若服务不存在，recovery 为 `catalog list`。设备 session 由 CLI 自动登记或刷新；401 `agent_device_session_required` 仅续期并重试一次，仍失败时返回错误，不循环。
 
 ## Agent Type / Host
 

package/docs/cli-reference/commands/vault/access.md

@@ -27,8 +27,7 @@ itpay vault access [--artifact <artifact_ref>] [--host <host>] [--target <target
   "handoff": {
     "url": "https://app.itpay.ai/vault/access/...",
     "qr_local_path": "<desktop-optional-local-path>",
-    "markdown": "<desktop-optional-host-ready-markdown>",
-    "qr_image_url": "<chat-host-optional-absolute-https-png>"
+    "markdown": "<desktop-optional-host-ready-markdown>"
   },
   "instruction": "说明这是当前智能体的只读授权，实际展示 handoff，然后停止；用户完成后重新运行最初的读取命令。",
   "next": null,
@@ -54,7 +53,6 @@ Agent不得提取、单独输出、记录或重建其中的 credential；但不
 | `claude-code-cli / terminal` | `url`；文本模式同时渲染终端二维码 |
 | `workbuddy / plain-chat` | `url, agent_action` |
 | `zcode / plain-chat` | `url`；立即用内置浏览器打开，浏览器不可用时才展示可点击链接 |
-| `doubao-work / plain-chat` | `url, qr_image_url`；展示“直接打开授权页”和“授权二维码图片（保存或用另一台设备扫码）”两个有标签的官方入口 |
 | `kimi-code / terminal` | `url`；文本模式同时渲染终端二维码 |
 | `openclaw / telegram` | `url, qr_image_url, agent_action` |
 | `openclaw / other` | `url, qr_image_url` |
@@ -63,5 +61,3 @@ Agent不得提取、单独输出、记录或重建其中的 credential；但不
 未显示并发送同一个 URL；不得创建替代请求。
 
 ZCode 不接收图片路径或二维码 URL。instruction 必须要求 Agent立即用内置浏览器打开完整 `handoff.url`，然后停止等待；不得只粘贴文字链接或重建二维码。仅当内置浏览器明确不可用时才展示同一个可点击链接。
-
-Doubao Work 的两个字段都是必需项。若兼容 Backend 未直接返回二维码 URL，CLI 必须从同一官方授权入口派生 Backend 的对应二维码端点；无法安全派生时命令必须明确失败，不得返回缺字段的 handoff。instruction 必须要求 Agent 同时展示完整 `handoff.url` 与 `handoff.qr_image_url`，清楚区分直接打开与跨设备扫码用途，然后停止等待。不得解析 credential、下载或重建二维码，也不得重复执行 `vault access` 检查状态。

package/docs/cli-reference/conventions.md

@@ -1,6 +1,6 @@
 # Output And Error Contract
 
-> **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.
+> **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.
 
 ## 目标
 
@@ -37,7 +37,7 @@ CLI 输出是给 Agent 执行的协议，不是后端 DTO 的调试转储。默
 - `recovery`：成功时通常为空；失败或中断时最多两个动作。
 - 一旦命令声明 `--agent-type` 或 `ITPAY_AGENT_TYPE`，所有 ItPay `next.command` 和 `recovery.command` 都保留同一类型。
 - 相同事实不得同时出现在顶层、`agent_guidance`、`next_actions` 等多个位置。
-- 默认隐藏 buyer、device、contract version、Arazzo workflow、quote lock、内部 event ID 等实现细节。
+- 默认隐藏 buyer、device、contract version、compiled graph、quote lock、内部 event ID 等实现细节。
 - token、付款 URL 和本地二维码路径只在确实需要交给用户时返回，并不得写入日志型命令。
 
 ## 默认文本输出
@@ -78,9 +78,11 @@ next: <one command>
 - 用户口头说“已付款”不是支付事实；仅服务端 `verified` 状态有效。
 - `agent_device_session_required` 只触发一次 session 续期和同请求重试；第二次失败必须返回，不得循环或换身份。
 - `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
-- WorkBuddy 需通过宿主的正常权限机制允许 CLI 持久化 `~/.itpay-v3`。若被拦截，报告受阻操作和宿主原因；不切换 Node、删除 identity 或猜测性处理活跃 lock。
+- WorkBuddy 在运行会持久化 `~/.itpay-v3` 的 ItPay Bash 命令前，必须把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`。若用户拒绝该权限，命令尚未执行：停止并报告，不得切换 Node、删除 identity、手工处理 lock 或换 Agent Type。
 - `provider_input_rejected` 只表示 Provider 明确声明输入无效；`provider_contract_mismatch` 表示响应无法按已发布契约解释，绝不能归咎于用户输入。两者都必须停止且没有自动 recovery。
-- `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供升级 recovery。npm 分发返回精确的 `npm install -g @itpay/cli@<version>`；平台 bundle 返回该平台的 Skill/plugin 更新动作。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
+minimum_cli_version 仅为协议门槛，不是经过核验的推荐制品。兼容失败保留当前 CLI/API、平台API及版本窗口事实；next=null、recovery=[]，停止本轮并请求维护方提供配套包，不猜版本或换身份。
+
+
 
 ## 网络传输失败与自动重试
 

package/docs/cli-reference/index.md

@@ -2,7 +2,7 @@
 
 本目录是 ItPay CLI 的规范性命令合同。它定义命令应向人和 Agent 返回什么、如何指导下一步，以及失败后如何恢复。当前实现与本文档不一致时，以本文档作为后续校准目标。
 
-> **统一产品边界：** `itpay` 是唯一公开的 CLI 入口，`$itpay` 是对应的用户侧 Skill 调用方式。当前入口同时覆盖购买新服务、查询订单、查看经用户授权的已购内容和退款；Seller 流程使用同一入口的 `itpay sell` 命令。不得为这些意图拆分新的产品入口。
+> **统一产品边界：** `itpay` 是唯一公开的 CLI 入口，`$itpay` 是对应的用户侧 Skill 调用方式。当前入口同时覆盖购买新服务、查询订单、查看经用户授权的已购内容和退款；Seller 流程未来仍使用同一入口，当前尚未实现。不得为这些意图拆分新的产品入口。
 
 企知道可以作为示例数据出现，但任何命令、字段、状态和 instruction 都不得依赖某个服务。服务差异只能来自 Catalog、Service Contract、Capability metadata 和服务端状态。
 
@@ -34,7 +34,6 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay catalog list`](commands/catalog/list.md)
 - [`itpay install`](commands/install.md) - 查看指定 Agent 的安装说明
 - [`itpay skill show`](commands/skill.md) - 一次读取完整内置 ItPay Skill
-- [`itpay auth login / status`](commands/auth.md) - 官方登录并绑定当前已登记 Agent，继续免费查询
 - [`itpay device recover`](commands/device.md) - 仅恢复运营已确认重建的 Backend registration
 - [`itpay docs`](commands/docs/index.md)
   - [`itpay docs list`](commands/docs/list.md)
@@ -79,7 +78,6 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
 ### 通用服务执行
 
 - [`itpay services`](commands/services/index.md)
-  - [`itpay services run`](commands/services/run.md)
   - [`itpay services start`](commands/services/start.md)
   - [`itpay services invoke`](commands/services/invoke.md)
   - [`itpay services action`](commands/services/action.md)
@@ -88,10 +86,5 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay services list`](commands/services/list.md)
   - [`itpay services get`](commands/services/get.md)
   - [`itpay services next`](commands/services/next.md)
-  - [`itpay services page`](commands/services/page.md)
   - [`itpay services read-result`](commands/services/read-result.md)
   - [`itpay services events`](commands/services/events.md)
-
-- [Sell: create, test and submit services](commands/sell.md)
-
-- [Run a published service](commands/services/run.md)

package/docs/skill-bundle-rollout/01-mcp-authentication.md

@@ -0,0 +1,134 @@
+# Local Device 与远程 MCP OAuth 边界
+
+状态：current boundary；服务端实现以 `itpay-ai/compose` 为准。
+最后核对：2026-08-10。
+
+## 1. 本文负责什么
+
+本文只定义 CLI/平台包必须遵守的身份选择和凭据保管规则。
+
+服务端 OAuth 协议、Connection、workload delegation、Buyer 和 Vault 数据
+模型由 Compose 仓库的 V3 文档、Schema、OpenAPI 和代码负责。CLI 仓库不再
+维护一份重复的 OAuth Server 实施计划。
+
+## 2. Local Device Authority
+
+本地 CLI 使用：
+
+```text
+~/.itpay-v3/device/device-private.pem
+~/.itpay-v3/device/identity.json
+```
+
+`src/state/device_authority.ts`：
+
+- 生成/保存本地 Ed25519 私钥；
+- 按 Backend base URL 保持独立 Device registration；
+- 按显式 Agent Type 解析 exact Agent Instance；
+- 用 challenge 签名取得短期 Device Session；
+- 对受保护请求签名并防重放；
+- 只对可恢复 session 执行一次续期和同请求重放；
+- 不静默替换被吊销 Device。
+
+这些文件表示本地工作负载，不表示网页登录 Token，也不能被复制进平台
+bundle。
+
+## 3. 远程 MCP OAuth
+
+云端 MCP 客户端使用标准 OAuth Connection：
+
+```text
+MCP client
+-> Authorization Code + PKCE
+-> ItPay login/consent
+-> client stores Access/Refresh Token
+-> ItPay MCP validates token
+-> exact MCP Connection
+-> Buyer-less workload delegation to Backend
+```
+
+平台客户端负责 Token 持久化、刷新和断线重连。以下位置都不能保存或打印
+OAuth Token：
+
+- CLI；
+- `~/.itpay-v3`；
+- Skill / Plugin；
+- `bundle.lock.json`；
+- 模型提示、tool 参数或 tool 输出；
+- Git 仓库；
+- Backend 普通 API 日志。
+
+十分钟 Access Token 到期应由 Refresh Token 自动续期，不得让用户每十分钟
+重新扫码。Vault 短期授权到期是独立事件，只重新请求 Vault 授权。
+
+## 4. 两条线路不能混用
+
+| 属性 | Local CLI | Remote MCP |
+| --- | --- | --- |
+| caller | Device + exact Agent Instance | exact MCP Connection |
+| credential owner | 用户本机 CLI | MCP client/platform |
+| Authorization | `ItPayDevice` + signed headers | OAuth Bearer at MCP resource |
+| server hop | CLI -> Backend | Platform -> MCP -> delegated Backend |
+| durable revoke | Device/Agent | Connection/Grant |
+| Buyer relationship | explicit Device binding | OAuth Connection binding |
+
+互斥规则：
+
+- Backend Device middleware 不接受 MCP Bearer；
+- MCP resource 不接受 Device Session；
+- CLI 不读取 MCP Token；
+- MCP 不读取 `~/.itpay-v3`；
+- 撤销一个通道不删除另一个通道；
+- 两个通道可指向同一 Buyer，但 Vault 临时授权按 exact audience 分开。
+
+## 5. 平台路由
+
+平台 Skill 在开始业务动作前选择线路：
+
+```text
+persistent local shell and bundled CLI and no explicit MCP -> CLI
+pure cloud -> MCP
+explicit MCP request -> MCP
+explicit CLI request -> CLI
+```
+
+同一任务不能：
+
+- 同时调用两条线路；
+- 在失败后静默 fallback；
+- 用 email、昵称、Agent Type 或平台名推断 Buyer；
+- 用 Device/MCP 重连重置免费额度或资源归属。
+
+## 6. 跨平台 Buyer Vault 读取
+
+Local Device 与 MCP Connection 可以读取同一 Buyer Vault，但必须分别完成：
+
+1. durable caller authentication；
+2. exact-audience temporary Vault window；
+3. 对需要首次揭示的工件完成 artifact-specific consent。
+
+CLI/MCP 连接不等于持续读取授权，OAuth 登录也不等于首次揭示或退款授权。
+
+最终产品、API、Schema 和测试合同由 Compose 文档
+`V3_CROSS_PLATFORM_BUYER_VAULT_READ_IMPLEMENTATION_PLAN.md` 负责。
+
+## 7. 平台不兼容时
+
+如果平台不能安全完成标准 OAuth 或保存/刷新 Token：
+
+- 有本地 Shell 时使用 bundled CLI；
+- 没有本地 Shell 时标记 MCP 不支持；
+- 不接受静态 personal bearer；
+- 不要求用户在聊天中粘贴 Token；
+- 不把 Token做成普通 Skill setting。
+
+## 8. 验证门禁
+
+- CLI 升级前后 Device ID 和私钥 hash 不变；
+- MCP 连接/刷新/撤销不修改 Local Device 文件；
+- Device 与 MCP auth scheme 互相拒绝；
+- 两个 Connection 与两个 Agent Instance 的 Vault audience 相互隔离；
+- Access Token 刷新无需用户或模型参与；
+- Vault window 到期不会销毁 OAuth/Device durable identity；
+- 日志、bundle、tool output 和 repo secret scan 无凭据；
+- 平台失败时没有静默线路切换。