@itpay/cli 2.0.2 → 2.0.5

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，不要新建 Execution。",
+  "next": { "command": "itpay services action <id> --action <action_type> --actor-type human --status approved --candidate <rank> --json", "reason": "记录用户选择" },
+  "recovery": []
+}
+```
+
+## 无结果与额度耗尽
+
+无结果时明确说明 Provider 已返回空结果，并根据服务端 graph 决定重试同一 execution 或启动新 execution。额度耗尽时返回付费 capability 的完整 `services quote` 命令，不要求 CLI 自己识别服务。
+
+```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；先向用户说明价格并确认购买。",
+  "next": {
+    "command": "itpay services quote <id> --capability <paid_capability_id> --input <key=value> --json",
+    "reason": "准备当前服务的付费 continuation 报价"
+  },
+  "recovery": []
+}
+```
+
+缺少 required input 时返回 `capability_input_invalid`，recovery 给出带占位符的同一 invoke 命令；CLI 和 Backend 都必须在 Provider 调用前拒绝，Backend 还必须在 execution/event/quota/invocation 写入前拒绝。错误调用付费 capability 时返回 `checkout_required` 和可直接运行的 quote 命令；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,162 @@
+# `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，不要新建 Execution。",
+  "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": "这是当前 Graph 步骤对应的交付。向用户展示编号和 safe_payload；如用户选择，必须在当前 Execution 提交对应 rank。",
+  "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": []
+}
+```
+
+其他执行阶段只返回 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,59 @@
+# `itpay services quote`
+
+## 范围与意义
+
+为当前 Service Execution 的一个付费 Capability 准备 Quote Lock。它只锁定可信输入、候选来源、价格、币种和有效期，不创建 Cart、Checkout、订单或 Provider 调用。
+
+**上游：** `services next` 返回 `prepare_quote`，以及当前 Execution 内已批准的候选或完整 required input。
+
+**下游：** `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。
+
+## 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,53 @@
+# `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。Buyer、Device 和 Agent instance 均来自签名 Agent session，不接受请求参数覆盖。
+
+## 标准输出
+
+```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 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 自动登记或刷新；仅无法恢复时返回明确 enrollment 错误。
+
+## 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/conventions.md

@@ -0,0 +1,94 @@
+# 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`。
+- `recovery`：成功时通常为空；失败或中断时最多两个动作。
+- 相同事实不得同时出现在顶层、`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` 状态有效。
+
+## 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 猜业务流程。
+

package/docs/cli-reference/index.md

@@ -0,0 +1,64 @@
+# ItPay CLI Command Reference
+
+本目录是 ItPay CLI 的规范性命令合同。它定义命令应向人和 Agent 返回什么、如何指导下一步，以及失败后如何恢复。当前实现与本文档不一致时，以本文档作为后续校准目标。
+
+企知道可以作为示例数据出现，但任何命令、字段、状态和 instruction 都不得依赖某个服务。服务差异只能来自 Catalog、Service Contract、Capability metadata 和服务端状态。
+
+## 使用约定
+
+- [输出与错误合同](conventions.md)
+- [Agent Type 与 Host](agent-types.md)
+- 所有示例中的 `<...>` 都是占位符，不得原样提交。
+- 所有 commerce 命令必须使用真实的 `--agent-type`，不得为刷新额度伪造类型。
+- 每条命令只返回当前步骤所需事实、一条 instruction、一个首选 next；异常时最多返回两个 recovery。
+
+## 命令目录
+
+### 环境与发现
+
+- [`itpay readyz`](commands/readyz.md) - 检查后端是否可用
+- [`itpay next`](commands/next.md) - 从本地保存的服务端句柄恢复下一步
+- [`itpay catalog`](commands/catalog/index.md)
+  - [`itpay catalog list`](commands/catalog/list.md)
+- [`itpay install`](commands/install.md) - 查看指定 Agent 的安装说明
+- [`itpay docs`](commands/docs/index.md)
+  - [`itpay docs list`](commands/docs/list.md)
+  - [`itpay docs show`](commands/docs/show.md)
+  - [`itpay docs search`](commands/docs/search.md)
+
+### 购物与支付
+
+- [`itpay cart`](commands/cart/index.md)
+  - [`itpay cart add`](commands/cart/add.md)
+  - [`itpay cart next`](commands/cart/next.md)
+  - [`itpay cart remove`](commands/cart/remove.md)
+  - [`itpay cart show`](commands/cart/show.md)
+  - [`itpay cart clear`](commands/cart/clear.md)
+- [`itpay buy`](commands/buy.md)
+- [`itpay checkout`](commands/checkout.md)
+- [`itpay pay`](commands/pay.md)
+- [`itpay order`](commands/order.md)
+- [`itpay orders`](commands/orders.md)
+
+### 退款
+
+- [`itpay refund`](commands/refund/index.md)
+  - [`itpay refund create`](commands/refund/create.md)
+  - [`itpay refund list`](commands/refund/list.md)
+  - [`itpay refund get`](commands/refund/get.md)
+  - [`itpay refund watch`](commands/refund/watch.md)
+  - [`itpay refund cancel`](commands/refund/cancel.md)
+
+### 通用服务执行
+
+- [`itpay services`](commands/services/index.md)
+  - [`itpay services start`](commands/services/start.md)
+  - [`itpay services invoke`](commands/services/invoke.md)
+  - [`itpay services action`](commands/services/action.md)
+  - [`itpay services quote`](commands/services/quote.md)
+  - [`itpay services checkout`](commands/services/checkout.md)
+  - [`itpay services list`](commands/services/list.md)
+  - [`itpay services get`](commands/services/get.md)
+  - [`itpay services next`](commands/services/next.md)
+  - [`itpay services read-result`](commands/services/read-result.md)
+  - [`itpay services events`](commands/services/events.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.2",
+  "version": "2.0.5",
   "description": "ItPay CLI for V3 checkout, payment, order, refund, and agent-facing render flows.",
   "type": "module",
   "bin": {