@itpay/cli 2.0.30 → 2.0.32

package/docs/cli-reference/agent-types.md

@@ -10,10 +10,10 @@
 
 | Agent Type | 默认 Host | 初始 instruction 差异 |
 |---|---|---|
-| `codex-desktop` | `codex` | 返回可在 Codex 桌面对话中展示的本地二维码图片和付款链接，要求 Agent 将图片实际发到当前对话。 |
-| `codex-cli` | `terminal` | 在用户可见终端渲染二维码并输出付款链接；若用户不看该终端，要求改用正确 Host。 |
-| `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和付款链接，要求先展示再等待。 |
-| `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和链接，不声称已在桌面对话展示。 |
+| `codex-desktop` | `codex` | 返回可在 Codex 桌面对话中展示的本地二维码和官方链接，要求 Agent 将 handoff 实际发到当前对话。 |
+| `codex-cli` | `terminal` | 在用户可见终端渲染二维码并输出官方链接；若用户不看该终端，要求使用真实 Host。 |
+| `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和官方链接，要求先展示再等待。 |
+| `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和官方链接，不声称已在桌面对话展示。 |
 | `workbuddy` | `plain-chat` | 返回完整渲染的 HTML Card Link 和可原样执行的 `present_files` action；立即打开 Card Link，不返回或检查本地图片路径。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 引导，在用户可见终端渲染二维码和付款链接。 |
 | `openclaw` | 无；必须显式传入 | `--host telegram` 使用 OpenClaw 原生 `message` action；其他入口返回标准 HTTPS 二维码和付款链接。 |
@@ -35,7 +35,13 @@
 - session 失效时 CLI 只续期并重试原请求一次；再次失败立即返回。revoked v2 Device 不自动换身份。
 - 同一 Device 首次登记新的 Agent Type 时，CLI 只使用本地已登记且 Backend 仍接受的既有 Agent Instance 完成签名登记；被撤销的 Instance 会被跳过且不会恢复。若没有任何既有 Instance 可用，CLI 必须停止，不得重新登记 Device、旋转私钥或借用其他 Backend。
 
-## Checkout Handoff 最小合同
+## Human Handoff 最小合同
+
+Checkout 与账号读取授权使用相同的 Host 投影规则：`result` 是业务事实，
+`handoff` 是必须交给当前用户的操作入口。完整官方 handoff URL 可以展示；
+URL 内 credential 不得被提取、单独输出、记录或重建。
+
+### Checkout
 
 ```json
 {
@@ -77,3 +83,15 @@
 WorkBuddy instruction 必须要求 Agent 原样执行一次 `handoff.agent_action`，即调用 `present_files(files=[handoff.url])` 在右侧打开 Backend 已渲染的 HTML Card。调用成功后说明金额并停止；调用失败时只发送原始 `handoff.url` 并如实报告未自动打开。禁止把 `present_files` 用于本地文件或二维码 PNG，也不能下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式。
 
 OpenClaw Telegram 的 `handoff.agent_action` 是可原样执行的原生 `message` tool action。`presentation` 只包含标准 `blocks.buttons`：`📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用扁平 `value=itp:grant_confirmed:<checkout_id>`；二维码单独使用 action 的 `media`。CLI `instruction` 必须要求 Agent 原样执行该 action，不得改写 Presentation、换用其他消息工具或声称普通文本回复等同于已发送按钮。收到授权 callback 后立即执行 `next.command` 查询同一 Checkout，再只跟随后端返回的同一 Execution grant 流程；callback 只携带 Checkout ID，不携带 display token，也不证明付款或 grant 已生效。OpenClaw `target` 使用原生 chat target（如 `5559456744` 或 `-1001234567890:topic:42`），不添加 `telegram:` 前缀。
+
+### Purchased-content authorization
+
+`vault access` 使用相同字段集合，但不包含金额、Checkout ID、付款状态或付款
+查询命令。桌面 handoff 的 Markdown 标题和链接必须明确为“授权查看已购
+内容”；Terminal 显示授权二维码；WorkBuddy 用 `present_files` 打开完整
+`handoff.url`；OpenClaw 使用返回的图片/原生 action。
+
+授权 handoff 展示后 `next=null`。用户明确表示已完成时，Agent只重新执行
+产生授权要求的原始 `vault list`、`orders` 或 `vault read`，不得再次执行
+`vault access` 检查状态。图片展示失败时保留并发送同一个官方 URL，不创建
+替代请求。

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

@@ -41,7 +41,7 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
 {
   "status": "completed",
   "result": { "checkout_id": "<checkout_id>", "payment": "verified", "order_id": "<optional_order_id>", "service_execution_id": "<optional_id>" },
-  "instruction": "Backend 已确认这笔付款。不要再次展示付款入口，不要调用 pay，不要创建新 Checkout 或 Execution。现在只执行 next.command，读取同一 Execution 的履约结果。",
+  "instruction": "告诉用户：付款已经确认，订单已经记录，不需要再次付款；结果会在同一订单下继续准备，如果最终无法交付，可以从原订单申请退款，处理方式由内容是否已使用决定。然后只执行 next.command 读取同一笔服务；Agent 不再展示付款入口或创建新订单，也不承诺退款结果。",
   "next": { "command": "itpay services next <service_execution_id> --json", "reason": "读取同一笔已付款 Service Execution" },
   "recovery": []
 }
@@ -49,6 +49,8 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
 
 已完成状态不得请求 QR PNG、生成二维码、输出附件指令或建议 `pay`。如果 Checkout 包含一个 Service Execution，下一步读取该 execution；通用订单则读取 `order_id`。`refunded`、`failed`、`expired` 同样不生成 handoff，只返回服务端终态和可用恢复方向。
 
+退款说明是用户保障，不是退款承诺。退款资格、自动/人工路径和最终结果仍由原订单的 Refund Owner 根据支付与消费事实决定。
+
 ## 异常处理
 
 token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout 正是本机保存的 Service Checkout 时，才返回对应 `services checkout <service_execution_id> --resume --json`；否则返回 `services list`，不能把另一个 execution 的 token 拼上去，也不能跳到 cart 或新建付款。

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

@@ -98,7 +98,7 @@ OpenClaw 额外明确没有默认入口：
       }
     ]
   },
-  "instruction": "选择当前真实运行环境；同一 Agent 不要临时更换 Agent Type。",
+  "instruction": "识别当前真实运行平台，从 result.agent_types 选择对应 agent_type，并由 Agent 自行运行 itpay install <agent_type> --json；不要让用户运行命令，也不要临时更换 Agent Type。",
   "next": null,
   "recovery": [
     {
@@ -109,6 +109,8 @@ OpenClaw 额外明确没有默认入口：
 }
 ```
 
+`next` 保持为空，因为 CLI 不能替 Agent 猜测其宿主平台；Agent 必须自行完成这次选择并继续执行，不得把技术选择或命令转交给用户。
+
 ## Agent Type / Host
 
 | Agent Type | 默认 Host | instruction 重点 |

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

@@ -36,7 +36,7 @@ CLI 使用 Agent Device Authority。设备完成首次付款绑定后，已登
     "access_locked": false,
     "service_execution_id": "<service_execution_id>"
   },
-  "instruction": "根据 delivery_mode 使用对应读取入口；不要从订单摘要猜测受保护内容。",
+  "instruction": "先告诉用户订单已经找到并说明当前交付状态；再根据 delivery_mode 使用对应读取入口。不要从订单摘要猜测受保护内容。",
   "next": {
     "command": "itpay services next <service_execution_id> --json",
     "reason": "读取交付状态"
@@ -68,7 +68,7 @@ CLI 使用 Agent Device Authority。设备完成首次付款绑定后，已登
       "status": "accepted"
     }
   },
-  "instruction": "退款访问锁已生效；不要 reveal、创建 grant 或读取交付结果。",
+  "instruction": "告诉用户退款处理中，原交付已按政策冻结。然后读取同一退款的权威状态；Agent 不读取交付、不创建授权或重复申请退款。",
   "next": {
     "command": "itpay refund get <refund_request_id> --json",
     "reason": "读取退款的服务器状态"

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

@@ -1,85 +1,73 @@
 # `itpay orders`
 
-> **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.
-
 ## 范围与意义
 
-列出当前 account-scoped Buyer session 可见的订单摘要，用于恢复订单，不返回交付 payload。
-
-**上游：** Buyer 登录并取得 account-scoped session。
-**下游：** `order <id>`。
-
-## 语法与参数
+列出当前 ItPay 账号的安全订单摘要。网页登录 Buyer Session，或具有有效
+账号读取授权的 Local Device / MCP Connection 都可以使用。它不返回交付
+payload、Checkout、支付凭证或内部 Buyer ID。
 
 ```bash
-itpay orders [--limit <n>] [--status <status>] [--json]
+itpay orders [--limit <n>] [--status <status>] [--cursor <cursor>] [--host <host>] [--target <target>] [--json]
 ```
 
 | 参数 | 默认 | 说明 |
-|---|---:|---|
-| `--limit` | `20` | 最大订单数。 |
-| `--status` | 全部 | 可选：`pending_payment`、`paid`、`delivery_pending`、`delivered`、`failed`、`partially_refunded`、`refunded`、`cancelled`。 |
-| `--json` | 否 | 标准 JSON。 |
-
-`--limit` 必须是 `1..100` 的整数。命令固定使用最新优先排序，不暴露修改排序的参数。
+| --- | ---: | --- |
+| `--limit` | `20` | 最大订单数，必须是 `1..100`。 |
+| `--status` | 全部 | 可选订单状态过滤。 |
+| `--cursor` | 无 | Backend 返回的下一页游标；不得自行构造。 |
+| `--host` | Agent Type 默认值 | 授权缺失时保留当前展示 Host；OpenClaw 必须显式提供。 |
+| `--target` | 无 | OpenClaw 消息 Host 的可信会话目标。 |
+| `--json` | 否 | 输出标准 envelope。 |
 
-## 标准输出
+## Agent/网页登录通用成功输出
 
 ```json
 {
   "status": "listed",
   "result": {
-    "orders": [
-      {
-        "order_id": "<id>",
-        "order_code": "<IP-code>",
-        "status": "<status>",
-        "amount": "<amount> <currency>",
-        "created_at": "<RFC3339>"
-      }
-    ]
+    "orders": [{
+      "order_code": "<IP-code>",
+      "service_title": "<title>",
+      "subject_label": "<subject>",
+      "amount": "2.00 CNY",
+      "paid_at": "<RFC3339>",
+      "status": "delivered",
+      "vault_artifact_count": 1
+    }],
+    "next_cursor": null
   },
-  "instruction": "选择目标订单后读取详情；不要假设列表第一笔就是当前任务。",
-  "next": { "command": "itpay order <order_id> --json", "reason": "读取所选订单" },
-  "recovery": []
-}
-```
-
-订单列表不得包含 `checkout_id`、订单 items、交付 artifact、Vault ID 或交付 payload。无匹配订单时返回：
-
-```json
-{
-  "status": "no_orders",
-  "result": { "orders": [] },
-  "instruction": "当前账号没有符合条件的订单；不要猜测订单 ID。",
+  "instruction": "用编号、服务、购买对象、金额、时间、订单号和状态说明结果；不要假设第一笔就是用户要找的订单。",
   "next": null,
-  "recovery": [
-    { "command": "itpay services list --json", "reason": "恢复当前 Agent 设备可见的执行" }
-  ]
+  "recovery": []
 }
 ```
 
-## 异常处理
+网页登录路径可保留内部 `order_id` 以支持既有 `order <id>` 读取；Agent
+安全摘要路径只返回 Backend 已批准的 BuyerOrderSummary 字段。CLI 不把两种
+响应错误拼成同一种 DTO。
 
-结果按最新到最旧排列。缺少 Buyer session 时返回：
+## Agent 授权缺失
 
 ```json
 {
-  "status": "error",
-  "error": {
-    "code": "session_required",
-    "message": "account-scoped Buyer session is required"
+  "status": "human_authorization_required",
+  "result": { "intent": "list_purchase_history" },
+  "instruction": "需要用户确认一次身份和只读权限；执行 next.command 生成入口。",
+  "next": {
+    "command": "itpay vault access --json",
+    "reason": "创建一次账号读取授权"
   },
-  "instruction": "订单历史只对网页登录账号开放；不要伪造 Buyer token。Agent 可改为恢复当前设备绑定的 Service Execution。",
-  "next": null,
-  "recovery": [
-    { "command": "itpay services list --json", "reason": "恢复当前 Agent 设备可见的执行" }
-  ]
+  "recovery": []
 }
 ```
 
-无效 `--limit` 和 `--status` 必须在发起 HTTP 请求前返回 `limit_invalid` 或 `order_status_invalid`。Order-scoped session 返回服务端的 `account_scope_required`；CLI 不降级鉴权，也不要求 Agent 手工构造 Buyer token。
+用户完成后重新执行原始 `orders` 命令。CLI 不要求 Agent构造或粘贴 Buyer
+token，也不改用 Service Execution 猜测账号历史。
 
-## Agent Type / Host
+当 `next_cursor` 非空时，`next.command` 使用同一 limit/status 和 Backend 返回的
+cursor 读取下一页。Agent 只在用户需要查看更多订单时执行，不能修改或猜测
+cursor。OpenClaw 的授权下一步必须保留原命令的 `--host` 和所需 `--target`；
+若原命令未提供，CLI 会用明确占位符要求 Agent 从当前可信会话补齐。
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同；只允许展示格式差异。
+无匹配订单使用 `status=no_orders`、`orders=[]` 和 `next=null`。无效 limit
+和 status 必须在 HTTP 前返回稳定合同错误。

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

@@ -73,6 +73,8 @@ API 安全合同要求后端验证 display token 是该 Checkout 当前有效的
 - `failed`、`expired`、`refunded` 返回 `payment_unavailable`，不创建替代 Checkout。
 - 两者都只引导 `checkout --id ... --token ... --json` 读取服务端事实。
 
+`payment_verified` 的 instruction 必须先让 Agent 告诉用户付款已经确认、订单已记录且不需要再次付款；交付异常应恢复原订单并按 Refund Owner 的消费事实处理，不承诺自动、无条件或即时退款。Payment Intent 终态不是交付或退款终态，CLI 不据此替用户判断权益。
+
 ## 重试与刷新
 
 - 数据库以 `(checkout_id, payment_method_type)` 作为 Payment Intent 业务唯一键。

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

@@ -7,7 +7,7 @@
 检查当前官方 Backend 是否可用。默认使用生产环境 `https://app.itpay.ai`；仅测试时可通过 `ITPAY_BACKEND_URL=https://dev.itpay.ai` 选择官方开发环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
 
 **上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 或 `https://dev.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
-**下游：** 完整 `itpay` Skill，随后选择 Agent Type 或进入当前已支持的 Buyer Catalog。
+**下游：** 完整 `itpay` Skill；由 Agent 根据用户意图选择新服务、已购内容、订单或退款入口。
 
 ## 语法与参数
 
@@ -25,7 +25,7 @@ itpay readyz [--json]
 {
   "status": "ready",
   "result": { "backend": "available", "backend_url": "https://app.itpay.ai", "environment": "production" },
-  "instruction": "ItPay 可用；先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。sell 将来也使用同一入口，但当前尚未实现。",
+  "instruction": "ItPay 可用。先完整读取内置 Skill，再根据用户意图选择新服务、已购内容、订单或退款入口；不要默认开始购买。",
   "next": { "command": "itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
   "recovery": []
 }
@@ -37,7 +37,7 @@ itpay readyz [--json]
 {
   "status": "ready",
   "result": { "backend": "available", "backend_url": "https://dev.itpay.ai", "environment": "development" },
-  "instruction": "ItPay dev 可用；后续必须执行返回的完整命令，并继续使用同一个 dev Backend。先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。",
+  "instruction": "ItPay dev 可用。先完整读取内置 Skill，再根据用户意图选择新服务、已购内容、订单或退款入口；后续必须执行返回的完整命令并保持同一 dev Backend。",
   "next": { "command": "ITPAY_BACKEND_URL=https://dev.itpay.ai itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
   "recovery": []
 }

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

@@ -39,7 +39,7 @@ CLI 使用 Device Authority 或已有 Buyer bearer，并用订单+原因生成
     "access_locked": true,
     "can_cancel": true
   },
-  "instruction": "退款处理中，交付已冻结；不要 reveal、授权或读取结果。",
+  "instruction": "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不要重复申请、reveal、授权或读取结果。",
   "next": {
     "command": "itpay refund watch <refund_id> --json",
     "reason": "跟踪同一退款"
@@ -48,7 +48,7 @@ CLI 使用 Device Authority 或已有 Buyer bearer，并用订单+原因生成
 }
 ```
 
-`decision_mode` 的服务器枚举为 `automatic|manual`。已消费交付通常返回 `manual` / `policy_review_required`；instruction 明确等待人工审核。`status` 表示提交动作已完成，`result.refund_status` 才是退款状态机当前状态。
+`decision_mode` 的服务器枚举为 `automatic|manual`。未消费交付通常进入 `automatic`；已消费交付通常返回 `manual` / `policy_review_required`。两者只是政策路线：Agent 不得承诺自动路径一定成功、人工审核一定拒绝或具体到账时间。`status` 表示提交动作已完成，`result.refund_status` 才是退款状态机当前状态。
 
 若服务器返回退款终态，`next` 为 `null`。文本输出依次显示 result 字段、instruction 和一个 next，不输出支付或 Provider 内部数据。
 

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

@@ -34,7 +34,7 @@ itpay refund get <refund_request_id> [--json]
     "access_locked": true,
     "can_cancel": true
   },
-  "instruction": "退款处理中，交付已冻结；不要 reveal、授权或读取结果。",
+  "instruction": "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不要重复申请、reveal、授权或读取结果。",
   "next": {
     "command": "itpay refund watch <refund_id> --json",
     "reason": "跟踪同一退款"
@@ -47,12 +47,12 @@ itpay refund get <refund_request_id> [--json]
 
 ## 终态
 
-- `succeeded`：instruction 明确“退款已成功；交付永久关闭”，`next=null`。
-- `cancelled/rejected`：说明交付资格可恢复，但旧 grant 不复活，需要用户重新授权，`next=null`。
-- `failed + known_no_effect`：渠道请求确认未发送；Agent 不重试，由平台管理员决定是否重新执行，`next=null`。
-- `failed + retryable`：渠道明确返回可重试失败；Agent 不重试，等待平台管理员处理，`next=null`。
-- `failed + outcome_unknown`：渠道可能已受理；交付继续锁定，必须先对账，禁止重试或重复申请，`next=null`。
-- `failed + permanent`：渠道明确拒绝；停止并联系平台支持，`next=null`。
+- `succeeded`：先告诉用户退款已由 ItPay 确认成功，交付永久关闭，`next=null`。
+- `cancelled/rejected`：说明退款没有执行，交付资格可恢复，但旧 grant 不复活，需要用户重新授权，`next=null`。
+- `failed + known_no_effect`：说明退款请求确认未发送；Agent 不重试，由平台管理员决定是否重新执行，`next=null`。
+- `failed + retryable`：说明渠道明确返回可重试失败但 Agent 不会自行重试；等待平台管理员处理，`next=null`。
+- `failed + outcome_unknown`：说明渠道结果未知、交付继续锁定且必须先对账；禁止重试或重复申请，`next=null`。
+- `failed + permanent`：说明渠道明确拒绝本次退款；停止并联系平台支持，`next=null`。
 
 `decision_mode=manual` 只说明该退款采用人工裁定，不得覆盖上述失败终态的 instruction。CLI 永远不向 Agent 暴露 Provider 原始响应、签名、URL、支付标识或内部错误文本。
 

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

@@ -21,6 +21,14 @@
 
 退款创建成功即锁定对应交付；旧 Agent grant 不得继续读取。直接运行无参数 `itpay refund` 显示 help，不创建请求。
 
+## 用户服务口径
+
+- 先说明退款是否已提交、是否冻结交付、当前是自动路径还是人工审核，再给下一步。
+- 未消费交付通常进入自动路径；已消费交付通常进入人工审核。这描述处理路线，不保证成功或到账时间。
+- 只有 `refund_status=succeeded` 才能告诉用户退款成功。
+- `outcome_unknown` 必须解释为需要渠道对账，禁止重复申请或重放。
+- 不向用户倾倒 Provider、签名、网络或内部错误；不得把平台或渠道失败归咎于用户。
+
 ## 语法、参数与标准输出
 
 ```bash

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

@@ -38,7 +38,7 @@ itpay refund watch <refund_request_id> [--interval <seconds>] [--timeout <second
     "access_locked": true,
     "can_cancel": false
   },
-  "instruction": "退款已成功；交付永久关闭。",
+  "instruction": "先告诉用户退款已由 ItPay 确认成功，原交付永久关闭；不需要继续跟踪或重复申请。",
   "next": null,
   "recovery": []
 }
@@ -59,7 +59,7 @@ Timeout 只表示本次 CLI 等待结束，不表示退款失败：
     "access_locked": true,
     "can_cancel": true
   },
-  "instruction": "退款仍在处理，稍后继续跟踪同一退款；不要重复申请。",
+  "instruction": "先告诉用户退款仍在处理，Timeout 只表示本次等待结束，并不表示退款失败；稍后继续跟踪同一退款，不要重复申请或承诺结果。",
   "next": {
     "command": "itpay refund watch <refund_id> --json",
     "reason": "恢复轮询"

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

@@ -35,7 +35,7 @@ itpay services action <service_execution_id> --action <action_type>
       "delivery_email_required": true
     }
   },
-  "instruction": "候选已绑定到当前 Execution，但尚未购买后续服务。现在只向用户说明已选择的候选、后续价格和邮箱用途，然后询问是否购买并停止。用户明确同意并提供邮箱前，不要执行 next.command，不要创建新 Execution 或 Checkout。",
+  "instruction": "已选择 <title>。后续服务尚未购买。只向用户说明继续购买的价格和邮箱用途，请确认是否购买并提供邮箱，然后停止。用户明确同意并提供真实邮箱前，Agent 不执行 next.command，也不创建新的服务或付款页面。",
   "next": { "command": "itpay services checkout <id> --capability <capability_id> --email <email> --json", "reason": "仅在用户明确同意价格并提供真实邮箱后执行" },
   "recovery": [{ "command": "itpay services next <id> --json", "reason": "重新读取服务端允许的动作" }]
 }

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

@@ -29,7 +29,7 @@ itpay services invoke <service_execution_id> --capability <capability_id>
     "items": [{ "rank": 1, "title": "<title>", "safe_payload": {} }],
     "quota": { "remaining": 2, "limit": 3 }
   },
-  "instruction": "向用户展示编号和 safe_payload；若候选列表已满足用户目标，在此停止。仅在用户明确选择并希望继续时，才在当前 Execution 提交对应 rank。",
+  "instruction": "用编号、名称和可公开字段向用户说明候选；若候选列表已满足目标就停止。只有用户明确选择并希望继续时，才提交对应编号；不要向用户提及 safe_payload、Execution 或内部 ID。",
   "next": { "command": "itpay services action <id> --action <action_type> --actor-type human --status approved --candidate <rank> --json", "reason": "记录用户选择" },
   "recovery": []
 }
@@ -75,7 +75,7 @@ Provider 已收到请求但没有匹配项时，该 invocation 成功完成、
       "delivery_email_required": false
     }
   },
-  "instruction": "免费额度已用完，本次没有调用 Provider，也尚未创建 Quote 或 Checkout。现在只向用户说明：‘继续当前请求需要支付 0.10 CNY，是否购买？’然后停止并等待用户明确回复。用户明确同意前，不要执行 next.command，不要新建 Execution，不要尝试其他 capability、quote、cart、buy、checkout 或 pay 命令。",
+  "instruction": "免费额度已用完，本次没有发送到数据来源，也没有创建付款页面。只向用户说明：‘继续当前请求需要支付 0.10 CNY，是否购买？’然后停止等待。用户明确同意前，Agent 不执行 next.command，也不创建或尝试其他购买路径。",
   "next": {
     "command": "itpay services checkout <id> --capability <paid_capability_id> --input <key=value> --json",
     "reason": "仅在用户明确同意支付 0.10 CNY 后执行；否则停止"
@@ -102,7 +102,7 @@ Provider 已收到请求但没有匹配项时，该 invocation 成功完成、
     "provider_called": false,
     "quota": { "remaining": 3, "limit": 3 }
   },
-  "instruction": "Provider 请求未发出，预留免费额度已释放；当前 Execution 已失败。立即向用户报告 error.message 并停止，不要自动重试、不要继续同一 Execution，也不要进入任何付费路径。只有运营确认连接恢复且用户明确要求重新查询后，才启动新的 Service Execution。",
+  "instruction": "告诉用户本次查询没有发送到数据来源，免费额度已保留，然后停止。不要转述技术错误、自动重试或进入付费路径；只有服务恢复且用户明确要求重新查询后才能开始新的查询。",
   "next": null,
   "recovery": []
 }
@@ -125,7 +125,7 @@ Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和
     "provider_called": true,
     "quota": { "remaining": 0, "limit": 3 }
   },
-  "instruction": "Provider 明确拒绝了该输入：输入的名称不合法。请向用户报告 error.message 和 result.quota 并停止。不要自行修改输入、不要重试、不要创建新 Execution；只有用户明确提供新输入后才能重新查询。",
+  "instruction": "告诉用户数据来源明确表示当前输入无效，并按 result.quota 说明额度状态，然后停止。不要转述内部错误、自行修改输入、重试或创建新查询；只有用户明确提供新输入后才能重新查询。",
   "next": null,
   "recovery": []
 }
@@ -142,7 +142,7 @@ Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和
     "provider_called": true,
     "quota": { "remaining": 0, "limit": 3 }
   },
-  "instruction": "Provider 响应与已发布契约不一致。这不是用户输入问题。立即停止，不要修改输入、不要重试、不要创建新 Execution，也不要进入付费路径；向用户报告平台故障和 result.quota。",
+  "instruction": "告诉用户平台暂时无法正确解释数据来源的响应，这不是用户输入问题，并按 result.quota 说明额度状态。立即停止，不要修改输入、重试、创建新查询或进入付费路径。",
   "next": null,
   "recovery": []
 }

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

@@ -32,13 +32,13 @@ itpay services list [--limit <number>] [--json]
       { "service_execution_id": "<id>", "service_id": "<service_id>", "status": "<status>", "phase": "<phase>", "updated_at": "<time>" }
     ]
   },
-  "instruction": "结果按最新到最旧排列，默认只列最近 10 条；找不到目标时再扩大 limit。",
-  "next": { "command": "itpay services next <latest_service_execution_id> --json", "reason": "默认恢复最新执行" },
+  "instruction": "只有一条可恢复记录；继续读取同一笔服务。",
+  "next": { "command": "itpay services next <id> --json", "reason": "继续唯一可恢复的服务" },
   "recovery": []
 }
 ```
 
-不得为每条 execution 附加完整 guidance、capabilities、result items、events、candidate hash、client context 或内部 binding。若用户指定了另一条，Agent 应用该行 ID 替换默认最新 ID 后运行 `services next`。
+不得为每条 execution 附加完整 guidance、capabilities、result items、events、candidate hash、client context 或内部 binding。恰好一条记录时 CLI 返回对应的 `services next`；多条记录时 `next=null`，列表不能把“最新”当成“用户想要”，Agent 必须先用普通语言让用户选择。
 
 无结果时返回 `no_executions`、空数组和 `itpay catalog list --json`。
 

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

@@ -39,7 +39,7 @@ itpay services next <service_execution_id> [--json]
       { "rank": 1, "title": "<title>", "safe_payload": { "<public_field>": "<value>" } }
     ]
   },
-  "instruction": "向用户展示编号和 safe_payload；若候选列表已满足用户目标，在此停止。仅在用户明确选择并希望继续时，才在当前 Execution 提交对应 rank。",
+  "instruction": "用编号、名称和可公开字段向用户说明候选；若候选列表已满足目标就停止。只有用户明确选择并希望继续时，才提交对应编号；不要向用户提及 safe_payload、Execution 或内部 ID。",
   "next": {
     "command": "itpay services action <id> --action select_candidate --actor-type human --status approved --candidate <rank> --json",
     "reason": "仅在用户明确选择后锁定来源候选"
@@ -67,7 +67,7 @@ itpay services next <service_execution_id> [--json]
       }
     ]
   },
-  "instruction": "付费 Agent-visible 搜索已完成。现在把 items 中的编号、title 和 safe_payload 展示给用户，然后停止。本结果是 agent-visible，不要调用 read-result。若用户的目标只是候选搜索，任务已经完成；只有用户之后明确选择某个候选并要求继续时，才执行 next.command。不要自动购买后续报告。",
+  "instruction": "付费搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload 或自动购买后续报告。",
   "next": {
     "command": "itpay services action <id> --action select_candidate --actor-type human --status approved --candidate <rank> --json",
     "reason": "仅在用户明确选择候选并要求继续时执行"
@@ -76,7 +76,7 @@ itpay services next <service_execution_id> [--json]
 }
 ```
 
-只有 Graph 允许继续选择时才返回上述 `next`。若结果本身就是最终交付，则 instruction 为“只使用 safe_payload，不调用 read-result”，且 `next: null`。文本输出依次显示 `status`、Execution、`delivery_mode`、候选及 instruction，不暴露 Result Item ID、Invocation ID 或 Hash。
+只有 Graph 允许继续选择时才返回上述 `next`。若结果本身就是最终交付，instruction 要求用普通语言解释可公开字段并停止，且 `next: null`。文本输出可以保留 Agent 执行所需的 Execution 与 `delivery_mode`，但 Agent 不向用户暴露这些内部词、Result Item ID、Invocation ID 或 Hash。
 
 ## Vault 交付
 
@@ -118,7 +118,7 @@ itpay services next <service_execution_id> [--json]
       "failed_nodes": 0
     }
   },
-  "instruction": "用户已经完成授权，服务端正在按已发布执行图准备交付内容。不要再次付款、再次授权、新建 Execution 或调用 read-result；只执行 next.command 查询同一 Execution。",
+  "instruction": "告诉用户：授权已经完成，付费结果仍在同一订单下准备，不需要再次付款或授权。然后只执行 next.command 查询同一笔服务；Agent 不创建新服务、付款页面或数据请求，也不提前读取。",
   "next": {
     "command": "itpay services next <id> --json",
     "reason": "等待同一 Execution 的交付准备完成"
@@ -127,6 +127,8 @@ itpay services next <service_execution_id> [--json]
 }
 ```
 
+付款确认后仍处于 `wait`/Provider running 时，instruction 必须说明订单和付款已保留、用户不需要再次付款；若 Execution 最终失败，Agent 应恢复同一订单及退款状态，不能自动创建新购买或承诺退款。终态 `failed` 只允许说明本次服务没有正常完成，并读取现有事件用于诊断；不得把技术错误直接归咎于用户。
+
 有效 grant 存在时：
 
 ```json
@@ -184,7 +186,7 @@ itpay services next <service_execution_id> [--json]
       "status": "<refund_status>"
     }
   },
-  "instruction": "退款处理中，交付已冻结；不要 reveal、创建 grant 或读取结果。",
+  "instruction": "告诉用户退款仍在处理，原交付已按政策冻结。然后读取同一退款的权威状态；Agent 不读取交付、不创建授权或重复申请。",
   "next": {
     "command": "itpay refund get <refund_id> --json",
     "reason": "读取退款权威状态"

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

@@ -1,33 +1,50 @@
 # `itpay skill` / `itpay skill 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.
-
 ## 范围与意义
 
-读取 npm 包内置的完整 ItPay Agent Skill。与按 topic 渐进读取的 `docs` 不同，本命令故意一次返回完整 `SKILL.md`，用于首次 onboarding 和身份/session 规则恢复；不访问 Backend，不修改宿主配置或本地身份。
+读取 npm 包内置的完整 ItPay Agent Skill。Skill 是面向白板 Agent 的精简
+入口：帮助其理解用户意图、选择第一条命令并正确读取后续 CLI envelope。
+完整参数和状态合同由 `itpay docs` 按 topic 渐进提供，不重复塞入 Skill。
 
-`itpay skill` 只显示该命令组的帮助并退出，不读取 Skill 内容。
+本命令不访问 Backend，不修改宿主配置或本地身份。
 
 ```bash
 itpay [--agent-type <agent_type>] skill show itpay [--json]
 ```
 
-当前只内置 `itpay`。该 Skill 是 Buyer 与未来 Seller 的共同入口，不再按角色拆分名称。`--json` 时完整 Markdown 位于 `result.content`；文本模式直接输出完整内容。
+当前只内置 `itpay`。`--json` 时完整 Markdown 位于 `result.content`；文本
+模式直接输出完整内容。
+
+## 已声明 Agent Type
 
 ```json
 {
   "status": "shown",
   "result": { "skill": "itpay", "content": "<complete_packaged_SKILL.md>" },
-  "instruction": "完整读取并遵守 Skill；先如实选择当前运行环境对应的 Agent Type。",
-  "next": { "command": "itpay install --json", "reason": "选择真实且稳定的 Agent Type" },
+  "instruction": "完整读取 Skill，理解当前用户需求，再选择对应的第一条命令；保持当前 Agent Type。",
+  "next": null,
   "recovery": []
 }
 ```
 
-已声明 Agent Type 时 instruction 确认规范类型，`next.command` 保留该类型并指向 `catalog list --json`。除完整已发布 Skill 内容外，不得附加本地路径、安装目录、环境变量、Device 状态或 Backend 数据。
+Skill 不能默认把 Agent 引向 Catalog：用户可能要读取以前购买的内容、查看
+订单或处理退款。Agent 必须先完成意图判断。当前命令的 `next` 固定为
+`null`。
+
+## 未声明 Agent Type
+
+未声明时 instruction 要求先选择真实运行环境，`next` 为：
 
-未声明 Agent Type 时，`next` 是 `itpay install --json`。已声明时，`next` 是保留同一类型的 `catalog list --json`。未知名称返回 `skill_not_found`；包内文件缺失或损坏返回 `skill_unavailable` 并要求重装同版本 CLI。
+```json
+{
+  "command": "itpay install --json",
+  "reason": "选择真实且稳定的 Agent Type"
+}
+```
 
-Skill 是操作和安全合同，不是服务端业务状态。执行时仍以每个命令当前 envelope 的 `result`、`instruction` 和 `next` 为准。
+未知 Skill 名称返回 `skill_not_found`；包内文件缺失或损坏返回
+`skill_unavailable`。除完整已发布 Skill 内容外，不得附加本地路径、安装
+目录、环境变量、Device 状态或 Backend 数据。
 
-所有 Agent Type 使用相同的 JSON 外壳、字段和命令参数。`workbuddy` 只在 `instruction` 中额外要求：写入 `~/.itpay-v3` 前把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`；权限被拒绝时停止，不切换 Node、不删除 identity、不处理 lock。它不改变输入或输出 schema。
+`workbuddy` 只在 instruction 中增加既有的本地权限要求；不改变输入、输出
+schema 或意图路由。

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

@@ -3,12 +3,15 @@
 ## 语法
 
 ```bash
-itpay vault access [--artifact <artifact_ref>] [--json]
+itpay vault access [--artifact <artifact_ref>] [--host <host>] [--target <target>] [--json]
 ```
 
-- 无 `--artifact`：请求当前 Device + Agent Instance 的账号 Vault 窗口。
-- 有 `--artifact`：请求该内容的首次/敏感读取授权；必须已经有账号窗口。
-- CLI 不接受时长、Buyer ID、回调 URL、MCP Connection ID 或 start token 参数。
+- 无 `--artifact`：请求当前 Local Device + Agent Instance 的账号读取授权。
+- 有 `--artifact`：请求首次或敏感内容读取授权；必须已有账号授权。
+- `--host` 只选择展示方式，默认由 Agent Type 推导。
+- OpenClaw 必须显式提供当前 `--host`；原生消息 Host 需要 `--target`。
+- CLI 不接受时长、Buyer ID、回调 URL、MCP Connection ID、浏览器 Session
+  或 start token 参数。
 
 ## 标准 JSON
 
@@ -19,14 +22,39 @@ itpay vault access [--artifact <artifact_ref>] [--json]
     "request_id": "<id>",
     "purpose": "account_window",
     "artifact_ref": null,
-    "request_expires_at": "<RFC3339>",
-    "authorization_url": "https://app.itpay.ai/vault/access/...",
-    "qr_png_url": "https://app.itpay.ai/v1/vault/access-requests/.../qr.png"
+    "request_expires_at": "<RFC3339>"
   },
-  "instruction": "直接打开官方 authorization_url（桌面可展示 qr_png_url），然后停止等待用户；不要重复创建请求。",
+  "handoff": {
+    "url": "https://app.itpay.ai/vault/access/...",
+    "qr_local_path": "<desktop-optional-local-path>",
+    "markdown": "<desktop-optional-host-ready-markdown>"
+  },
+  "instruction": "说明这是当前智能体的只读授权，实际展示 handoff，然后停止；用户完成后重新运行最初的读取命令。",
   "next": null,
   "recovery": []
 }
 ```
 
-同一 pending request 会返回同一 request_id 并轮换 start token；旧链接立即失效。终态请求不复用。
+完整 `handoff.url` 是 Backend 批准交给当前用户的短期入口。CLI、Skill 和
+Agent不得提取、单独输出、记录或重建其中的 credential；但不得因为 URL
+包含 credential 而拒绝展示完整官方 handoff。
+
+同一 pending request 会复用 request ID 并轮换入口 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` |
+| `kimi-code / terminal` | `url`；文本模式同时渲染终端二维码 |
+| `openclaw / telegram` | `url, qr_image_url, agent_action` |
+| `openclaw / other` | `url, qr_image_url` |
+
+桌面二维码下载失败时保留 `handoff.url`，instruction 必须要求如实说明图片
+未显示并发送同一个 URL；不得创建替代请求。