@itpay/cli 2.0.3 → 2.0.7

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

@@ -0,0 +1,67 @@
+# `itpay services invoke`
+
+## 范围与意义
+
+调用当前 phase 允许的非付费 Agent-visible capability。输入先按 capability schema 校验，校验失败不得迁移 execution 或记录 Provider 已调用。
+
+**上游：** `services start/next` 明确返回 invoke。
+**下游：** 候选结果、人工 action、付费 Quote 或新 execution。
+
+## 语法与参数
+
+```bash
+itpay services invoke <service_execution_id> --capability <capability_id>
+  [--input <key=value> ...] [--json]
+```
+
+`--input` 可重复；必填 key 来自 `input_schema.required`，值按 schema 类型解析。Agent 不猜字段名。
+
+## 有结果输出
+
+```json
+{
+  "status": "result_ready",
+  "result": {
+    "service_execution_id": "<id>",
+    "capability_id": "<capability_id>",
+    "items": [{ "rank": 1, "title": "<title>", "safe_payload": {} }],
+    "quota": { "remaining": 2, "limit": 3 }
+  },
+  "instruction": "向用户展示编号和 safe_payload；若候选列表已满足用户目标，在此停止。仅在用户明确选择并希望继续时，才在当前 Execution 提交对应 rank。",
+  "next": { "command": "itpay services action <id> --action <action_type> --actor-type human --status approved --candidate <rank> --json", "reason": "记录用户选择" },
+  "recovery": []
+}
+```
+
+## 无结果与额度耗尽
+
+无结果时明确说明 Provider 已返回空结果，并根据服务端 graph 决定重试同一 execution 或启动新 execution。额度耗尽时，普通单 Execution 流程返回完整的 `services checkout` 单项快捷命令；`services quote -> cart add --quote -> buy --cart` 只用于用户明确要求把多个独立 Execution 合并付款的高级流程。
+
+```json
+{
+  "status": "quota_exhausted",
+  "result": {
+    "service_execution_id": "<id>",
+    "capability_id": "<capability_id>",
+    "items": [],
+    "quota": { "remaining": 0, "limit": 3 },
+    "checkout": {
+      "capability_id": "<paid_capability_id>",
+      "price": { "amount_minor": 10, "currency": "CNY" },
+      "delivery_email_required": false
+    }
+  },
+  "instruction": "免费额度已用完，本次没有调用 Provider，也尚未创建 Quote 或 Checkout。现在只向用户说明：‘继续当前请求需要支付 0.10 CNY，是否购买？’然后停止并等待用户明确回复。用户明确同意前，不要执行 next.command，不要新建 Execution，不要尝试其他 capability、quote、cart、buy、checkout 或 pay 命令。",
+  "next": {
+    "command": "itpay services checkout <id> --capability <paid_capability_id> --input <key=value> --json",
+    "reason": "仅在用户明确同意支付 0.10 CNY 后执行；否则停止"
+  },
+  "recovery": []
+}
+```
+
+缺少 required input 时返回 `capability_input_invalid`，recovery 给出带占位符的同一 invoke 命令；CLI 和 Backend 都必须在 Provider 调用前拒绝，Backend 还必须在 execution/event/quota/invocation 写入前拒绝。错误调用付费 capability 时不得给出购买旁路，只能回到同一 Execution 的 `services next`；execution 状态、event、ProviderCalled 均保持不变。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。

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

@@ -0,0 +1,61 @@
+# `itpay services list`
+
+## 范围与意义
+
+恢复当前已登记设备或账号可见的 Service Execution 摘要。它不是批量 timeline 导出。
+
+**上游：** 本地句柄丢失、404 recovery 或用户要求查看历史任务。
+**下游：** `services next <selected_id>`。
+
+## 语法与参数
+
+```bash
+itpay services list [--limit <number>] [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `--limit <number>` | 否 | 返回数量，默认 10；必须是 1 到 100 的整数。只有最近结果找不到目标时才扩大。 |
+| `--json` | 否 | 输出单个标准 JSON envelope；默认输出每条一行的简洁文本。 |
+
+命令使用签名 Agent Device session。Backend 按 `updated_at DESC` 返回当前设备或已绑定 Buyer account 可见的执行；CLI 保留该顺序，不在本地推断归属。
+
+## 标准输出
+
+```json
+{
+  "status": "listed",
+  "result": {
+    "executions": [
+      { "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": "默认恢复最新执行" },
+  "recovery": []
+}
+```
+
+不得为每条 execution 附加完整 guidance、capabilities、result items、events、candidate hash、client context 或内部 binding。若用户指定了另一条，Agent 应用该行 ID 替换默认最新 ID 后运行 `services next`。
+
+无结果时返回 `no_executions`、空数组和 `itpay catalog list --json`。
+
+非法 limit 在请求 Backend 前返回：
+
+```json
+{
+  "status": "error",
+  "error": { "code": "limit_invalid", "message": "--limit must be an integer from 1 to 100" },
+  "instruction": "使用 1 到 100 的整数 limit；本次未读取服务端列表。",
+  "next": null,
+  "recovery": [
+    { "command": "itpay services list --limit 10 --json", "reason": "使用默认上限重试" }
+  ]
+}
+```
+
+身份或 Backend 错误保留服务端错误码，只建议 `readyz` 和重新读取列表；不得猜测 ID。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 返回相同列表格式；Agent instance 权限决定可见范围。本命令没有 Host handoff。

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

@@ -0,0 +1,181 @@
+# `itpay services next`
+
+## 范围与意义
+
+读取一笔 Service Execution 的当前状态，并只返回一个首选下一步。若交付模式允许 Agent 直接读取，本命令同时返回完整 safe result。
+
+**上游：** `services start`、`invoke`、`action`、`checkout`，或一次中断恢复。  
+**下游：** 一个可执行命令、需要用户完成的候选选择或授权，或 Graph 真正到达终态。
+
+本命令不返回原始 Backend DTO、capability 列表、内部 result ID/hash、graph、binding 或重复 guidance。
+
+Backend 会根据当前 capability 选择 `current_delivery`；完整 `delivery_bindings` 仅是历史记录。CLI 不按数组位置猜测当前交付，同一 Execution 后续产生的新交付会取代旧交付成为默认结果。
+
+## 语法与参数
+
+```bash
+itpay services next <service_execution_id> [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `service_execution_id` | 是 | `services start` 或后续命令返回的 execution ID。 |
+| `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
+
+需要有效 Agent Device session。命令不接受 Buyer token、capability 或服务输入。
+
+## 候选选择
+
+免费或付费候选已经产生、Graph 允许继续选择时，恢复输出必须包含当前 Result Set 的安全候选：
+
+```json
+{
+  "status": "candidate_selection_available",
+  "result": {
+    "service_execution_id": "<id>",
+    "items": [
+      { "rank": 1, "title": "<title>", "safe_payload": { "<public_field>": "<value>" } }
+    ]
+  },
+  "instruction": "向用户展示编号和 safe_payload；若候选列表已满足用户目标，在此停止。仅在用户明确选择并希望继续时，才在当前 Execution 提交对应 rank。",
+  "next": {
+    "command": "itpay services action <id> --action select_candidate --actor-type human --status approved --candidate <rank> --json",
+    "reason": "仅在用户明确选择后锁定来源候选"
+  },
+  "recovery": []
+}
+```
+
+该列表来自 Backend 的 `current_result_items`，CLI 不缓存或合并其他 Execution 的候选。
+
+## Agent-visible 结果
+
+```json
+{
+  "status": "result_ready",
+  "result": {
+    "service_execution_id": "<id>",
+    "capability_id": "<capability_id>",
+    "delivery_mode": "agent_visible_result",
+    "items": [
+      {
+        "rank": 1,
+        "title": "<title>",
+        "safe_payload": { "<public_field>": "<value>" }
+      }
+    ]
+  },
+  "instruction": "付费模糊搜索已完成。现在把 items 中的编号、title 和 safe_payload 展示给用户，然后停止。本结果是 agent-visible，不要调用 read-result。若用户的目标只是搜索候选企业，任务已经完成；只有用户之后明确选择某个候选并要求继续时，才执行 next.command。不要自动购买后续报告。",
+  "next": {
+    "command": "itpay services action <id> --action select_candidate --actor-type human --status approved --candidate <rank> --json",
+    "reason": "仅在用户明确选择候选并要求继续时执行"
+  },
+  "recovery": []
+}
+```
+
+只有 Graph 允许继续选择时才返回上述 `next`。若结果本身就是最终交付，则 instruction 为“只使用 safe_payload，不调用 read-result”，且 `next: null`。文本输出依次显示 `status`、Execution、`delivery_mode`、候选及 instruction，不暴露 Result Item ID、Invocation ID 或 Hash。
+
+## Vault 交付
+
+未授权时不返回 result item 或 protected payload：
+
+```json
+{
+  "status": "human_authorization_required",
+  "result": {
+    "service_execution_id": "<id>",
+    "capability_id": "<capability_id>",
+    "delivery_mode": "vault_artifact",
+    "grant_status": "none"
+  },
+  "instruction": "这是当前 Graph 步骤对应的交付；请用户在订单页面授权，未授权前不要读取或猜测内容。",
+  "next": {
+    "command": "itpay services read-result <id> --json",
+    "reason": "仅在用户确认授权后执行"
+  },
+  "recovery": []
+}
+```
+
+有效 grant 存在时：
+
+```json
+{
+  "status": "grant_active",
+  "result": {
+    "service_execution_id": "<id>",
+    "capability_id": "<capability_id>",
+    "delivery_mode": "vault_artifact",
+    "grant_status": "active",
+    "grant_expires_at": "<RFC3339 time>"
+  },
+  "instruction": "这是当前 Graph 步骤对应的交付；用户授权有效，立即读取并遵守字段范围与到期时间。",
+  "next": {
+    "command": "itpay services read-result <id> --json",
+    "reason": "读取当前有效 grant 的结果"
+  },
+  "recovery": []
+}
+```
+
+额度耗尽或候选已确认并进入付费 continuation 时，`services next` 必须重复价格、用户确认原话、停止条件和禁止动作；普通单 Execution 的 next 使用 `services checkout`，不暴露 Quote/Cart/Buy 编排。
+
+已有 Checkout 时，Backend 返回 `resume_checkout`，CLI 只能恢复同一 Checkout：
+
+```json
+{
+  "status": "checkout_pending",
+  "result": {
+    "service_execution_id": "<id>",
+    "service_id": "<service_id>",
+    "phase": "checkout",
+    "allowed_actions": [{ "type": "resume_checkout", "requires_human": true }]
+  },
+  "instruction": "当前 Execution 已经有一笔 Checkout。不要创建新的 Quote、Cart、Checkout 或 Execution。现在只执行 next.command，恢复并展示同一 Checkout 的付款入口。",
+  "next": { "command": "itpay services checkout <id> --resume --json", "reason": "恢复同一 Checkout，不创建第二笔" },
+  "recovery": []
+}
+```
+
+付款已确认但 Provider 尚在履约时只能等待并再次读取同一 Execution；不得新建 Execution、Checkout 或再次付款。其他执行阶段只返回 Execution、service、phase、类型化 `allowed_actions` 和一个服务端状态导出的命令。CLI 只把 Backend 的动作类型渲染成命令，不执行 Publication 中的任意 shell 文本。完成或空结果后不得建议重放已失效的 invoke。
+
+## 退款访问锁
+
+订单存在 active 或永久退款锁时，该状态优先于 Agent-visible、Vault 和 grant guidance，不返回交付结果，也不再要求用户授权：
+
+```json
+{
+  "status": "delivery_locked",
+  "result": {
+    "service_execution_id": "<id>",
+    "access_locked": true,
+    "refund": {
+      "refund_request_id": "<refund_id>",
+      "status": "<refund_status>"
+    }
+  },
+  "instruction": "退款处理中，交付已冻结；不要 reveal、创建 grant 或读取结果。",
+  "next": {
+    "command": "itpay refund get <refund_id> --json",
+    "reason": "读取退款权威状态"
+  },
+  "recovery": []
+}
+```
+
+`succeeded` 退款改为“交付永久关闭”，并返回 `next: null`。取消、拒绝或确定未产生资金影响的失败退款不再阻塞，但旧 grant 不会复活；用户必须重新授权。
+
+## 异常处理
+
+execution 不存在或不属于当前设备/账号时返回错误信封，并仅建议：
+
+```text
+itpay services get <service_execution_id> --json
+```
+
+不要创建替代 execution 来掩盖归属或状态错误。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回完全相同的状态、safe payload、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。

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

@@ -0,0 +1,63 @@
+# `itpay services quote`
+
+## 范围与意义
+
+为当前 Service Execution 的一个付费 Capability 准备 Quote Lock。它只锁定可信输入、候选来源、价格、币种和有效期，不创建 Cart、Checkout、订单或 Provider 调用。
+
+本命令是多 Execution 合并付款的高级入口。普通单 Execution 流程应使用 `services checkout`，不要把 `services quote` 当作 Checkout 失败后的替代路径。
+
+**上游：** 用户明确要求合并多个独立 Execution，且每个 Execution 的 Graph 当前都允许 `prepare_quote`。
+
+**下游：** `cart add --quote`。多个独立 Execution 的 Quote 可以加入同一 Cart。
+
+## 语法与参数
+
+```bash
+itpay services quote <service_execution_id> --capability <capability_id>
+  [--input <key=value> ...] [--email <delivery_email>] [--json]
+```
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `service_execution_id` | 是 | 候选或输入所属的来源 Execution。 |
+| `--capability` | 是 | 当前 `allowed_actions` 明确允许报价的付费 Capability。 |
+| `--input` | 条件必填 | 不依赖已批准候选时，提供 schema 要求的输入；可重复。 |
+| `--email` | 条件必填 | 仅 `delivery_email_required=true` 时需要，必须来自用户；随 Quote Lock 持久化。 |
+| `--json` | 否 | 输出紧凑机器合同。 |
+
+若 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 状态" }]
+}
+```
+
+不得返回 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`：当前 Graph 不允许从当前 Execution 状态购买该 capability；不得换 capability、新建 Execution 或尝试其他购买命令，只回到同一 Execution 的 `services next`。
+- Backend 不支持当前交易合同时返回 `backend_contract_incompatible`，必须停止，不能改用 `services checkout`、`cart`、`buy` 或 `pay` 绕过。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回相同 Quote 事实、instruction 和 next。本命令不显示二维码；Agent Type 只作为设备与审计上下文，不改变价格或候选规则。

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

@@ -0,0 +1,98 @@
+# `itpay services read-result`
+
+## 范围与意义
+
+使用当前 Agent Device Authority，在用户创建的有效、未过期且范围匹配的 grant 内读取 Vault 保护结果。它不适用于 `agent_visible_result`。
+
+**上游：** `services next` 返回 `vault_artifact`，且用户已在订单页面授权。  
+**下游：** Agent 仅在 grant scope 和 TTL 内使用返回字段；没有自动后续命令。
+
+## 语法与参数
+
+```bash
+itpay services read-result <service_execution_id> [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `service_execution_id` | 是 | Vault 交付对应的 execution ID。 |
+| `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
+
+CLI 使用已登记设备的签名 session，不接受 Checkout token、Buyer token、`agent_device_id` 参数或开发者凭证。
+
+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 Type / Host
+
+同一 Buyer account 下已登记的 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 可按政策领取同一订单授权；每个类型仍需自己的有效 Device Authority。五种类型返回相同字段、TTL 和错误，不因 Host 扩大 grant scope。

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

@@ -0,0 +1,55 @@
+# `itpay services start`
+
+## 范围与意义
+
+按 Catalog 中的 `service_id` 启动一次 Service Execution，并返回当前可执行的唯一首选动作。不会调用 Provider、创建 Checkout 或订单。
+
+**上游：** `catalog list` 或服务端明确要求新 execution。
+**下游：** `services invoke`、`action`、`checkout` 或 `next`。
+
+## 语法与参数
+
+```bash
+itpay --agent-type <agent_type> 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": []
+}
+```
+
+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
+
+| 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

@@ -0,0 +1,17 @@
+# `itpay skill show`
+
+## 范围与意义
+
+读取 npm 包内置的完整 Agent Skill。与按 topic 渐进读取的 `docs` 不同，本命令故意一次返回完整 `SKILL.md`，用于首次 onboarding 和身份/session 规则恢复；不访问 Backend，不修改宿主配置或本地身份。
+
+```bash
+itpay [--agent-type <agent_type>] skill show itpay-buyer [--json]
+```
+
+当前只内置 `itpay-buyer`。`--json` 时完整 Markdown 位于 `result.content`；文本模式直接输出完整内容。
+
+未声明 Agent Type 时，`next` 是 `itpay install --json`。已声明时，`next` 是保留同一类型的 `catalog list --json`。未知名称返回 `skill_not_found`；包内文件缺失或损坏返回 `skill_unavailable` 并要求重装同版本 CLI。
+
+Skill 是操作和安全合同，不是服务端业务状态。执行时仍以每个命令当前 envelope 的 `result`、`instruction` 和 `next` 为准。
+
+所有 Agent Type 使用相同的 JSON 外壳、字段和命令参数。`workbuddy` 只在 `instruction` 中额外强调保持同一 Node/CLI launcher、持久写权限和减少内部诊断转述；它不改变输入或输出 schema。

package/docs/cli-reference/conventions.md

@@ -0,0 +1,97 @@
+# Output And Error Contract
+
+## 目标
+
+CLI 输出是给 Agent 执行的协议，不是后端 DTO 的调试转储。默认输出适合人阅读；`--json` 使用同一语义的稳定机器合同。调试事实只由明确的诊断命令返回。
+
+## 标准 JSON 外壳
+
+```json
+{
+  "status": "<command_state>",
+  "result": {},
+  "instruction": "<one concise instruction>",
+  "next": {
+    "command": "itpay <next-command>",
+    "reason": "<why this is next>"
+  },
+  "recovery": []
+}
+```
+
+规则：
+
+- `status`：当前命令的业务结果，不是 HTTP 状态。
+- `result`：仅包含当前步骤必须使用或向用户说明的事实。
+- `instruction`：一条可直接当作 Agent prompt 使用的自然语言指令，不复述 `result`。
+- `next`：最多一个首选动作；流程结束时为 `null`。
+- `next.command` 是状态机允许的首选延续，不是无条件执行指令；当前结果已满足用户目标时，Agent 应展示结果并停止。
+- `recovery`：成功时通常为空；失败或中断时最多两个动作。
+- 一旦命令声明 `--agent-type` 或 `ITPAY_AGENT_TYPE`，所有 ItPay `next.command` 和 `recovery.command` 都保留同一类型。
+- 相同事实不得同时出现在顶层、`agent_guidance`、`next_actions` 等多个位置。
+- 默认隐藏 buyer、device、contract version、compiled graph、quote lock、内部 event ID 等实现细节。
+- token、付款 URL 和本地二维码路径只在确实需要交给用户时返回，并不得写入日志型命令。
+
+## 默认文本输出
+
+文本输出与 JSON 字段一一对应，最多四段：
+
+```text
+<status summary>
+<necessary result lines>
+instruction: <what the agent must do>
+next: <one command>
+```
+
+无下一步时省略 `next`；无异常时省略 `recovery`。
+
+## 标准错误
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "<stable_error_code>",
+    "message": "<human-readable reason>"
+  },
+  "instruction": "<what not to do and what to correct>",
+  "next": null,
+  "recovery": [
+    { "command": "itpay <recovery-command>", "reason": "<reason>" }
+  ]
+}
+```
+
+错误必须满足：
+
+- 参数和前置条件在产生订单、锁价、扣费、Provider 调用或状态迁移前验证。
+- 不得只返回 `invalid_state`；必须说明当前状态和合法恢复入口。
+- 重试应复用同一 cart、checkout、execution、order 或 refund ID，不得默认创建新资源。
+- 用户口头说“已付款”不是支付事实；仅服务端 `verified` 状态有效。
+- `agent_device_session_required` 只触发一次 session 续期和同请求重试；第二次失败必须返回，不得循环或换身份。
+- `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
+
+## Instruction 模板
+
+Instruction 只回答当前最重要的一件事：
+
+```text
+说明结果的意义 + 明确 Agent 现在必须做或禁止做的动作。
+```
+
+示例：
+
+```text
+把付款二维码和链接展示给用户；确认用户可见前不要查询付款状态，也不要创建新 Checkout。
+```
+
+不得使用空洞 instruction，例如“继续下一步”“按需处理”“查看详情”。
+
+## 通用性边界
+
+- CLI 不识别企知道、企业查询、某个 capability 名称或某个字段名。
+- 必填输入来自 `input_schema.required`。
+- 是否收费来自 `requires_payment` 和价格元数据。
+- 是否需要邮箱来自 `delivery_email_required`。
+- 是否可直接给 Agent 来自 `agent_visible` / `delivery_mode`。
+- 下一步来自 Service Execution read model，不由 CLI 猜业务流程。