@itpay/cli 2.1.48 → 2.1.49

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

@@ -1,65 +1,20 @@
-# `itpay services quote`
+# itpay services quote
 
-> **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.
+仅用于明确要求的独立多服务组合，或当前服务明确返回的动作。普通服务购买使用 services purchase。
 
-## 范围与意义
-
-为当前 Service Execution 的一个付费 Capability 准备 Quote Lock。它只锁定可信输入、候选来源、价格、币种和有效期，不创建 Cart、Checkout、订单或 Provider 调用。
-
-本命令是多 Execution 合并付款的高级入口。普通单 Execution 流程应使用 `services checkout`，不要把 `services quote` 当作 Checkout 失败后的替代路径。
-
-**上游：** 用户明确要求合并多个独立 Execution，且每个 Execution 的 Arazzo workflow 当前都允许 `prepare_quote`。
-
-**下游：** 读取当前服务器返回的有范围 `approve_purchase` 完整 JSON，默认 false；仅已有真实匹配批准时置 true 并记录。批准成功后再 `cart add --quote`，多个已批准 Quote 可加入同一 Cart。候选选择不等于价格批准。
-
-## 语法与参数
-
-```bash
-itpay services quote <service_execution_id> --capability <capability_id>
-  [--input <key=value> ...] [--email <delivery_email>] [--json]
+```sh
+itpay services quote <execution_id> --capability <capability_id> --input <key=value> --json
 ```
 
-| 参数 | 必填 | 说明 |
-|---|---:|---|
-| `service_execution_id` | 是 | 候选或输入所属的来源 Execution。 |
-| `--capability` | 是 | 当前 `allowed_actions` 明确允许报价的付费 Capability。 |
-| `--input` | 条件必填 | 不依赖已批准候选时，提供 schema 要求的输入；可重复。 |
-| `--email` | 条件必填 | 仅 `delivery_email_required=true` 时需要，必须来自用户；随 Quote Lock 持久化。 |
-| `--json` | 否 | 输出紧凑机器合同。 |
+实际参数见 --help；使用当前 capability 合同的完整输入。Quote只锁定对象、金额、币种及期限，不代表真实同意、付款或履约。已有原记录由代码处理；Agent只执行当次完整模板和适用动作。
 
-若 Capability 依赖候选，Backend 只从当前 Execution 的 approved Candidate Action 读取 Result Item、Invocation 和 Stable Hash；CLI 不重新提交公司名、候选 ID 或 Hash。
+## 当前参数
 
-交付联系信息属于 Quote 的锁定事实。多个 Quote 合并付款时，Checkout Owner 汇总它们的联系信息；相同字段值冲突时拒绝创建 Checkout，不由 CLI 选择或覆盖。
-
-## 标准输出
-
-```json
-{
-  "status": "quote_ready",
-  "result": {
-    "service_quote_lock_id": "<quote_id>",
-    "service_execution_id": "<execution_id>",
-    "capability_id": "<capability_id>",
-    "price": "<amount> <currency>",
-    "expires_at": "<RFC3339>"
-  },
-  "instruction": "报价已锁定当前 Execution 的可信输入和价格；可单独付款，也可与其他独立 Execution 的报价合并。",
-  "next": { "command": "itpay cart add --quote <quote_id> --json", "reason": "加入 canonical Cart" },
-  "recovery": [{ "command": "itpay services next <execution_id> --json", "reason": "重新读取当前 Execution 状态" }]
-}
+```text
+--capability <capability_id>
+--input <key=value>           input to lock into the paid service quote
+--email <delivery_email>
+--json                        output compact JSON
 ```
 
-不得返回 locked input、Candidate Hash、Provider 元数据或完整 Execution DTO。
-
-## 异常处理
-
-- `capability_not_quoteable`：Capability 不存在、免费或当前不可报价；回到同一 Execution 的 `services next`。
-- `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`。
-- Backend 不支持当前交易合同时返回 `backend_contract_incompatible`，必须停止，不能改用 `services checkout`、`cart`、`buy` 或 `pay` 绕过。
-
-## Agent Type / Host
-
-所有正式支持的 Local Agent Type 返回相同 Quote 事实、instruction 和 next。本命令不显示二维码；Agent Type 只作为设备与审计上下文，不改变价格或候选规则。
+`--input-json <file>` accepts the complete flat input returned in `file_content`; use it instead of `--input`, never together.

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

@@ -22,7 +22,7 @@ itpay services read-result <service_execution_id> [--snapshot <snapshot_id>] [--
 | `--snapshot <snapshot_id>` | 否 | 单独使用时读取该 Smart 已提交快照的紧凑线路页；与 `--journey` 配合时读取该线路详情页。 |
 | `--offset <offset>` | 否 | Exact / Smart 保存结果从零开始的页偏移；不改变快照或重新查询。 |
 | `--limit <limit>` | 否 | 保存结果当前页条数，1–20；Exact默认20条，Smart默认3条完整线路或3个票计划；必要时按最终输出字节缩小整行页。 |
-| `--all` | 否 | 显式兼容读取 Exact / Smart 保存目录全量；输出可能很大，常规读取应沿当前页的 next.command。 |
+| `--all` | 否 | 显式读取 Exact / Smart 保存目录全量；输出可能很大，常规读取应沿当前页的 next.command。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
 Exact 执行按 offset/limit 读取已保存车次，返回 total、offset、count 和同一 read-result 的续页入口；不会把前100条冒充完整范围。Smart 使用 `--snapshot` 读取固定快照的默认小页，或用 `--journey` 读一条线路的票计划页；按返回的 next.command 续读同快照。这些读取不走 Vault grant。其他服务不带选择器时保持原授权路径。
@@ -35,77 +35,10 @@ CLI 使用已登记设备的签名 session，不接受 Checkout token、Buyer to
 
 CLI 直接请求 Backend 的当前有效 Grant。历史 `delivery_bindings` 不作为访问判断；Backend 负责验证当前 Vault、Agent instance、Buyer、scope、TTL 和退款锁。
 
-## 标准输出
-
-```json
-{
-  "status": "granted_result_ready",
-  "result": {
-    "service_execution_id": "<id>",
-    "grant_expires_at": "<RFC3339 time>",
-    "granted_fields": ["<field>"],
-    "payload": { "<granted_field>": "<value>" }
-  },
-  "instruction": "结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。",
-  "next": null,
-  "recovery": []
-}
-```
-
-文本输出显示相同的 execution、到期时间、字段名和 payload，不附带 Vault ID、grant ID 或原始 scope。
-
-## 异常处理
-
-没有当前有效 Vault Grant（包括只有 Agent-visible 历史交付、未授权、过期、撤销或 wrong-scope）时，Backend 返回 `agent_access_denied`。CLI 指向：
-
-```text
-itpay services next <id> --json
-```
-
-不要从历史 Delivery Binding 推断当前模式，也不要使用数据库、Admin API 或新 Device ID 绕过授权。
-
-退款访问锁由 Backend 在读取 Vault payload 的同一事务中拒绝：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "delivery_locked_by_refund",
-    "message": "delivery is locked by refund <refund_id>"
-  },
-  "instruction": "退款访问锁已生效；不要 reveal、创建 grant 或读取交付结果。",
-  "next": null,
-  "recovery": [
-    {
-      "command": "itpay refund get <refund_id> --json",
-      "reason": "读取退款权威状态"
-    }
-  ]
-}
-```
-
-其他 `agent_access_denied` 返回：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "agent_access_denied",
-    "message": "<server reason>"
-  },
-  "instruction": "请用户在订单页面重新授权；不要使用开发者权限绕过授权或退款锁。",
-  "next": null,
-  "recovery": [
-    {
-      "command": "itpay services next <id> --json",
-      "reason": "检查交付模式和 grant 状态"
-    }
-  ]
-}
-```
+## 结果与授权边界
 
-一个 grant 只允许读取对应订单、execution、Agent instance 和批准字段。拒绝时不得改用数据库、Admin API 或新 Device ID 绕过。
+铁路保存结果直接给完整业务行、范围／限制、同快照详情和可用方案的完整购买模板，不要求 Agent 写解析器。完整线路按当前页的 next 续读；只有需要比较时才翻页，不把局部范围说成全网最优。
 
-## Agent Type / Host
+Vault 结果返回当前 grant 批准字段、TTL 与 payload；历史交付不能代替有效授权。授权不足、过期或退款锁按当前返回的真实原因和原任务动作处理；不能借新 Device、Admin、数据库或旧grant绕过。一个grant不扩展到其他订单、execution或Agent实例。
 
-同一 Buyer account 下已登记的正式 Local Agent Type 可按政策领取同一订单授权；每个类型仍需自己的有效 Device Authority。所有类型返回相同字段、TTL 和错误，不因 Host 扩大 grant scope。
+文本与 JSON 使用相同事实。可见授权／官方入口按正式Skill与render-hosts展示，缺宿主信息只补可信上下文，不创建替代购买。没有适用动作时停止。

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

@@ -1,152 +1,23 @@
-# `itpay services run`
+# itpay services run
 
-## 范围与意义
-
-运行 Catalog 中已发布的通用 Buyer workflow。CLI 只提交服务声明要求的输入，并复用现有 Service Execution、Checkout、交付和退款命令；它不解释或执行 Seller 提供的任意命令文本。
-
-没有提供输入且未指定现有 execution 时，本命令创建一次 Execution，返回已发布的 JSON input schema，并要求 Agent 继续同一 Execution。已有 Execution 必须通过 `--execution` 恢复，不能创建替代 Execution。
-
-## 语法与参数
-
-```bash
-itpay services run <service_id>
-  [--input-json <file>]
-  [--execution <service_execution_id>]
-  [--timeout <seconds>]
-  [--host <host>]
-  [--target <target>]
-  [--json]
-```
-
-| 参数 | 说明 |
-| --- | --- |
-| `service_id` | Catalog 返回的服务 ID。恢复时必须与 Execution 所属服务一致。 |
-| `--input-json` | UTF-8 JSON 文件；顶层必须是 object，并符合服务发布的 input schema；文件不超过 256 KiB。文件不可读、非合法 JSON 或顶层非 object 时在本地报 `workflow_input_invalid`，不发生网络写。 |
-| `--execution` | 恢复同一 Execution。不得用它切换服务或绕过原状态。 |
-| `--timeout` | 本次等待 workflow 状态变化的秒数，默认 120，范围 0–600；超时只返回当前状态。 |
-| `--host` / `--target` | Host 展示上下文，不是业务输入或 Buyer 身份。 |
-| `--json` | 输出稳定 JSON 信封。 |
-
-## 缺少输入
-
-```json
-{
-  "status": "input_required",
-  "result": {
-    "service_execution_id": "<execution_id>",
-    "service_id": "<service_id>",
-    "input_schema": { "type": "object", "required": ["<field>"] }
-  },
-  "instruction": "根据服务声明填写输入，然后继续同一服务执行。",
-  "next": {
-    "command": "itpay services run <service_id> --execution <execution_id> --input-json <file> --json",
-    "reason": "提交买家输入"
-  },
-  "recovery": []
-}
-```
-
-Agent 必须展示 schema 所需信息并等待用户提供真实输入；不得猜值，也不得为补输入创建新 Execution。
-
-铁路 Smart 新版 schema 使用 `endpoints.origin` / `endpoints.destination`，每端独立填写区域 `area`、具体地点 `place` 或准确车站 `station` 与原文 `text`；类型未确定可省略 `kind`。区域、地点和车站的九种组合共用这一输入。以当前执行返回的 `input_schema` 为准：旧 v4 执行仍使用旧字段；新版不可混填旧 `origin` / `destination`、坐标或锁站布尔值。地点/日期实质变更发起关联新查询，沿已保存结果返回的 `new_query_template` 填写真实变化；偏好、人数和期限在相同端点/日期下使用已有 `refine_preferences` 动作。
-
-## 执行与付款
-
-提供输入后，CLI 使用稳定 idempotency key 向同一 Execution 提交一次。`queued` 或 `running` 只轮询该 Execution。进入付款步骤时，CLI 调用现有 `services checkout`，返回其标准 `human_checkout_required` 输出和 Host handoff；不会实现第二套付款逻辑。
-
-付款完成后即使 CLI 已退出，Backend 仍继续该 workflow。再次运行：
-
-```bash
-itpay services run <service_id> --execution <execution_id> --json
-```
-
-只恢复当前状态。交付、Vault 授权和退款继续使用 `services next`、`services read-result`、`vault` 与 `refund` 的既有合同。
-
-## 免费试用额度与 `login_required`
-
-铁路查询类服务对未登录设备提供按服务独立计数的免费试用（`itpay-rail-exact` 与 `itpay-rail-smart` 各 2 次，互不共享）。额度在查询产生供应商副作用前由服务端原子记账：地点确认、内部多阶段、轮询和已保存结果分页不重复扣次；参数校验失败且未执行查询时不扣次。
-
-试用耗尽时，查询在供应商调用**之前**被暂停，Execution 不失败，已提交的输入服务端保留：
-
-```json
-{
-  "status": "login_required",
-  "result": {
-    "service_execution_id": "<execution_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": "该服务的免费查询次数已用完（exact 2/2，smart 仍剩 2/2）。请用户在官方页面完成登录后继续免费查询；本次查询输入已保留，登录后恢复同一执行即可，不要新建执行或让用户重述行程。smart 额度属于另一类服务，不能拿它顶替 exact 查询。",
-  "next": {
-    "command": "itpay auth login --json",
-    "reason": "完成官方登录绑定后继续免费查询"
-  },
-  "recovery": [
-    {
-      "command": "itpay services run itpay-rail-exact --execution <execution_id> --json",
-      "when": "auth_bound",
-      "reason": "登录绑定完成后恢复同一查询执行"
-    }
-  ]
-}
-```
-
-`query_quota` 如实报告各查询服务自己的 `used`、`limit`、`remaining`。是否暂停只以本次服务端 `admission` 为准；已有结果先正常交付，不把另一服务的额度当作本次授权。
-
-登录绑定完成后，再次运行同一条 `services run <service> --execution <id> --json`（不带输入文件）：服务端重新读取当前设备绑定身份，被暂停的 Execution 从额度节点继续，不重放已成功的供应商调用，不要求重新输入。`failed`、`recovery_required` 或已完成付款的 Execution 不能以这种方式恢复。
-
-## `rate_limited`
-
-已注册账号查询不设累计次数上限，但受正常每分钟限流：
-
-```json
-{
-  "status": "rate_limited",
-  "result": {
-    "service_execution_id": "<execution_id>",
-    "service_id": "<service_id>",
-    "admission": "rate_limited",
-    "retry_after_ms": 42000
-  },
-  "instruction": "触发正常限流；等待后恢复同一执行，不要新建查询。",
-  "next": {
-    "command": "itpay services run <service_id> --execution <execution_id> --json",
-    "after_ms": 42000,
-    "reason": "限流窗口过后继续同一查询"
-  },
-  "recovery": []
-}
-```
-
-限流不是收费、不是试用耗尽、不需要重新登录。等待中不得重复扣试用或发起新的供应商请求。
-
-## 公开操作与完整购买承接
-
-铁路是一项 `itpay-rail` 服务，`query_exact`、`query_smart`、`prepare_purchase` 是固定定义内的操作。查询输入按返回模板填写 `{ "input": { ... } }`；不要把内部实现当三项公开服务重新发现。
+执行公开定义返回的当前 operation 或继续原执行。先读取该定义/原结果提供的完整 input_template；复制 file_content 到文件，只填声明的缺失字段。
 
 ```sh
-itpay services run itpay-rail --operation query_exact --input-json query.json --json
+itpay services run <service_id> --operation <operation_id> --input-json <file> --json
 ```
 
-所选行程详情返回完整准备购买模板，含 `continuation.service_execution_id`、`continuation.snapshot_id` 和 `input.selections`。原样保留当前 owner、快照、完整段数、席别代码和人数，写入文件并执行其命令。不要手拼腿、站码、时刻、付款批准或缺失的 snapshot。一次整程对应一个 booking、一个官方付款入口，各段分别出票。
+公共 operation 文件有外层 input，并按返回保留 continuation。已有执行加 --execution <execution_id>；购买确认文件的形状由 purchase 模板决定，不能混用。
 
-旧 `itpay-rail-exact/smart/booking` ID 仅用于已有执行和历史模板的兼容恢复；新公共模板与旧凭据共用原购买去重。存在或未知购买先恢复，过期库存不等于能新建购买。
+--timeout 控制本次等待（默认120秒，0表示立即返回）；查询累计自动等待由原任务日志记录，恢复不重置。读取 status/result 和当次 next；没有可执行动作就停止。完整铁路路线理解见 rail-booking；必要购买同意见正式 Skill。创建结果未知不自动重发，已知执行编号必须保留。
 
-候选选择不等于价格和条款同意。正常流程读取返回的 `services purchase` 完整确认；已有真实、匹配价格/上限/条款/主体的同意可复用，缺失或实质变化才补确认。服务端核对实际报价并衔接原有批准；旧执行的 approve_purchase 模板保留原范围保护。付款与出票事实仍由后端及官方页确认。
+## 当前参数
 
-## 终态和异常
-
-- 成功、付款、交付、授权、退款锁等状态使用既有命令的标准信封，不额外包装 Seller 专用格式。
-- 既有 Checkout、身份、兼容性和网络错误保持原错误码、instruction 与 recovery；`services run` 不得覆盖可执行的邮箱、登录、升级或状态恢复指令。
-- 如果创建 Execution 后未收到完整响应，返回 `workflow_start_outcome_unknown`，只允许先执行 `itpay services list --json` 查找刚创建的 Execution；不得直接重跑 `services run` 创建替代 Execution。
-- `recovery_required` 或 `failed` 返回当前 workflow step，`next: null`，并明确禁止重建 Execution 或重放结果未知的 Provider 请求。
-- service 不匹配、输入文件不是 JSON object、timeout 越界或 Backend 错误返回 `workflow_run_failed`。
-- `--timeout` 到期不是失败，只返回同一 Execution 当前可恢复状态。
-
-## Agent Type / Host
-
-所有 Local Agent Type 共享同一状态机和 JSON 事实。Host 只改变付款链接、二维码或附件的展示方式，不改变身份、价格、workflow 或交付权限。
+```text
+--operation <operation_id>  operation declared by the public service
+--input-json <file>         JSON object containing the service input
+--execution <execution_id>  resume the same execution
+--timeout <seconds>         maximum wait before returning current progress
+--host <host>
+--target <target>
+--json                      output JSON
+```

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

@@ -1,59 +1,17 @@
 # `itpay services start`
 
-> **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.
+## 读取服务入口
 
-## 范围与意义
-
-公开 service_definition 入口只返回固定版本的服务总览与操作，未创建 execution、未调用 Provider。铁路总览指向 rail-booking：首次实际查询前理解端点并写短摘要。使用返回的操作模板执行 `services run --operation … --input-json <file>`。
-
-旧内部 service_id 仍兼容启动一次 Service Execution，并返回当前合法动作，不创建 Checkout 或订单。以下执行示例属于旧入口。
-
-**上游：** `catalog list` 或服务端明确要求新 execution。
-**下游：** `services invoke`、`action`、`checkout` 或 `next`。
-
-## 语法与参数
+从 `catalog list` 选择公开 service_definition，读取固定版本的总览、声明操作和完整输入模板。公开总览不创建 execution、不调用 Provider；不要把读取总览当作已查询库存。
 
 ```bash
-itpay --agent-type <agent_type> services start <service_id>
-  [--host <host>] [--target <target>] [--json]
+itpay services start <service_id> [--host <host>] [--target <target>] [--json]
 ```
 
-`service_id` 必须来自 Catalog。`--target` 只用于需要稳定消息目标的 Host，例如 chat/channel/open ID；它不是搜索词或其他业务输入。Buyer、Device 和 Agent instance 均来自签名 Agent session，不接受请求参数覆盖。
-
-本命令不接收 capability 业务输入。它返回 `required_input` 和一条 `services invoke`（或其他当前合法动作）命令；把真实值填入那条命令的重复 `--input key=value`。例如企业关键词是 `--input keyword=美团`，不是 `--target 美团`。
-
-## 标准输出
-
-```json
-{
-  "status": "ready",
-  "result": {
-    "service_execution_id": "<execution_id>",
-    "service_id": "<service_id>",
-    "phase": "<phase>",
-    "capability": {
-      "capability_id": "<capability_id>",
-      "required_input": ["<field>"],
-      "free_quota_limit": 3
-    }
-  },
-  "instruction": "填写首选 capability 的 required_input；一次只提交当前 execution 所代表的服务意图。",
-  "next": {
-    "command": "itpay --agent-type <agent_type> services invoke <execution_id> --capability <capability_id> --input <key=value> --json",
-    "reason": "执行当前允许的能力"
-  },
-  "recovery": []
-}
-```
+`service_id` 来自当前目录。`--host` 对应实际宿主，`--target` 是该宿主需要的稳定消息目标，不是业务输入。Buyer、Device 和 Agent instance 来自签名会话，不可通过参数覆盖。
 
-Start API 只提供免费额度上限，不提供当前剩余额度，因此本命令不得虚构 `remaining`。不得输出全部 capability DTO、contract version、Arazzo workflow、buyer/device ID 或重复 guidance。若服务不存在，recovery 为 `catalog list`。设备 session 由 CLI 自动登记或刷新；401 `agent_device_session_required` 仅续期并重试一次，仍失败时返回错误，不循环。
+本命令不接收业务输入。使用返回的声明操作与完整 `input_template.file_content` 写 JSON 文件，再执行该模板的 `services run --operation … --input-json <file>`；保留外层 `input` 与返回的 continuation。占位模板须填入实际值后执行，不猜字段或 operation。
 
-## Agent Type / Host
+铁路首次实际查询前按 `rail-booking` 理解完整端点、用户锁站与约束，必要时短查，留下2–4行路线摘要，再查询。查询结果、详情和整程购买沿当前返回动作继续；购买仅补缺失的真实同意。
 
-| Agent Type | 默认行为 |
-|---|---|
-| `codex-desktop` | 登记该类型并使用 `codex` Host instruction。 |
-| `codex-cli` | 登记该类型并使用 terminal instruction。 |
-| `claude-code-desktop` | 登记该类型并使用 `claude-code` Host instruction。 |
-| `claude-code-cli` | 登记该类型并使用 terminal instruction。 |
-| `workbuddy` | 登记该类型并使用 plain-chat instruction。 |
+只使用当前返回的合法动作。缺少声明合同或不兼容时保留原执行并停止，不绕过检查创建替代执行。免费额度上限不是当前剩余额度；登录、权限与外部故障按实际错误恢复。

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

@@ -43,8 +43,7 @@ Skill 不能默认把 Agent 引向 Catalog：用户可能要读取以前购买
 ```
 
 未知 Skill 名称返回 `skill_not_found`；包内文件缺失或损坏返回
-`skill_unavailable`。除完整已发布 Skill 内容外，不得附加本地路径、安装
-目录、环境变量、Device 状态或 Backend 数据。
+`skill_unavailable`。正常读取只返回完整同包 Skill，不附加设备或Backend数据；读取错误仅采用当次允许的同包路径和真实原因，不猜安装目录。
 
 `workbuddy` 只在 instruction 中增加既有的本地权限要求；不改变输入、输出
 schema 或意图路由。

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

@@ -44,24 +44,6 @@ Agent不得提取、单独输出、记录或重建其中的 credential；但不
 失效。因此本命令只能按读取命令返回的 `next` 执行一次，不能用重复执行
 `vault access` 检查状态。
 
-## Host handoff
+## 宿主交付
 
-| Agent Type / Host | `handoff` keys |
-| --- | --- |
-| `codex-desktop / codex` | `url, qr_local_path, markdown` |
-| `claude-code-desktop / claude-code` | `url, qr_local_path, markdown` |
-| `codex-cli / terminal` | `url`；文本模式同时渲染终端二维码 |
-| `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` |
-
-桌面二维码下载失败时保留 `handoff.url`，instruction 必须要求如实说明图片
-未显示并发送同一个 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` 检查状态。
+使用当前 handoff 和正式 Skill／render-hosts；原生工具或可选图片不可用时，同轮给出原官方URL，不创建替代授权、不把未展示说成成功。授权交付后停止，人完成后只运行最初的reader。host只改变展示，不扩展权限。

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

@@ -44,23 +44,10 @@ itpay vault list [--query <text>] [--limit <1..50>] [--cursor <cursor>] [--host
 
 ## 授权缺失
 
-```json
-{
-  "status": "human_authorization_required",
-  "result": {
-    "intent": "list_purchased_content",
-    "query": "<original-query-or-empty>"
-  },
-  "instruction": "需要用户确认一次身份和只读权限；执行 next.command 生成入口，不要声称链接已经创建。",
-  "next": {
-    "command": "itpay vault access --json",
-    "reason": "创建一次账号读取授权"
-  },
-  "recovery": []
-}
-```
+授权缺失返回 human_authorization_required。上下文完整时只执行当次完整的账号授权 next 一次；缺 host/target 时 next=null，使用返回的不可执行完整模板从当前可信会话补齐，不把通用示例套到所有宿主。真实交付入口后停止，授权不等于购买或付款。
+
 
 授权完成后只重新运行原始 `vault list` 命令，保留 query、limit 和 cursor。
 无效 limit/cursor 在 HTTP 前返回稳定错误。授权过期不自动重试、不创建新
 Device。OpenClaw 的授权下一步保留原命令的 `--host` 和所需 `--target`；若原
-命令没有提供，CLI 使用明确占位符要求 Agent 从当前可信会话补齐。
+命令没有提供，next=null，并返回不可执行的完整输入模板，由Agent从当前可信会话补齐。

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

@@ -37,4 +37,4 @@ Agent不得向用户展示或要求用户输入 `artifact_ref`。
 
 账号或内容授权完成后都只恢复原始 read；`vault access` 不是状态查询命令。
 OpenClaw 应把当前可信会话的 `--host` 和所需 `--target` 传给 read，使授权下一
-步可以原样保留展示目标；没有上下文时 CLI 只返回明确占位符，不猜测目标。
+步可以原样保留展示目标；没有上下文时 next=null，CLI返回不可执行的完整输入模板，不猜测目标。

package/docs/cli-reference/conventions.md

@@ -94,7 +94,7 @@ CLI 只把“尚未收到完整 HTTP 响应”的临时传输异常映射为稳
 - `network_socket_error`
 - `network_transport_failed`
 
-所有命令的 JSON 错误继续使用标准错误外壳，并额外返回：
+传输错误继续使用标准外壳及实际尝试事实；以下是结构示意，不提供可执行命令：
 
 ```json
 {
@@ -103,7 +103,7 @@ CLI 只把“尚未收到完整 HTTP 响应”的临时传输异常映射为稳
   "result": { "attempts": 3, "automatic_retry_performed": true },
   "instruction": "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。",
   "next": null,
-  "recovery": [{ "command": "itpay <same-resource-read-command>", "reason": "读取同一资源的权威状态" }]
+  "recovery": []
 }
 ```
 

package/docs/cli-reference/index.md

@@ -10,7 +10,7 @@
 
 - [输出与错误合同](conventions.md)
 - [Agent Type 与 Host](agent-types.md)
-- 所有示例中的 `<...>` 都是占位符，不得原样提交。
+- 语法与结构示意中的 `<...>` 都不可执行；实际 next/recovery 只能使用当前返回的完整命令，待填字段使用 executable:false 的完整 file_content 模板。
 - 所有 commerce 命令必须使用真实的 `--agent-type`，不得为刷新额度伪造类型。
 - 每条命令只返回当前步骤所需事实、一条 instruction、一个首选 next；异常时最多返回两个 recovery。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.48",
+  "version": "2.1.49",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
@@ -26,9 +26,7 @@
     "docs/agent/buyer/orders-refunds.json",
     "docs/agent/buyer/payment-flow.json",
     "docs/agent/buyer/purchased-content.json",
-    "docs/agent/buyer/quickstart.json",
     "docs/agent/buyer/rail-booking.json",
-    "docs/agent/buyer/rail-fast-checkout.json",
     "docs/agent/buyer/render-hosts.json",
     "docs/agent/buyer/service-feedback.json",
     "docs/cli-reference/agent-types.md",
@@ -142,5 +140,5 @@
     "url": "git+https://github.com/itpay-ai/cli.git"
   },
   "itpayBundleFormat": "buyer-esm-v1",
-  "gitHead": "5165ffbbcac542b4348996deebcad10280e3e88c"
+  "gitHead": "4737843bf7284dafb143f493f484b4a9ceb884d3"
 }