@itpay/cli 2.0.3 → 2.0.7

package/docs/cli-reference/index.md

@@ -0,0 +1,65 @@
+# 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 skill show`](commands/skill.md) - 一次读取完整内置 Buyer Skill
+- [`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.3",
+  "version": "2.0.7",
   "description": "ItPay CLI for V3 checkout, payment, order, refund, and agent-facing render flows.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -1,154 +1,115 @@
 ---
 name: itpay-buyer
 description: >
-  Use the ItPay V3 CLI when a human asks an AI agent to discover services,
-  use a free capability, buy a paid result, show an ItPay checkout QR, recover
-  an interrupted purchase, or read a result covered by a temporary human grant.
+  Use the ItPay CLI when a human asks an Agent to discover services, use a
+  capability, buy a result, show a Checkout, recover an interrupted flow,
+  read a human-granted result, or manage a refund.
 ---
 
-# ItPay V3 Buyer
+# ItPay Buyer
 
-Use the CLI as the control surface. Do not recreate ItPay API calls or invent a
-service-specific workflow. The backend returns the next valid actions for each
-catalog item and Service Execution.
+Use the CLI as the only ItPay control surface. Do not recreate API calls or hardcode a service-specific sequence.
+
+## Critical Rules
+
+- Keep one honest Agent Type, one CLI/Node launcher, and one Host-approved permission context for the whole flow.
+- Treat `next.command` as the preferred continuation, not an unconditional command. If the current result already satisfies the user's stated goal, present it and stop.
+- Keep internal parsing, retries, sandbox diagnosis, and command translation out of the user response; report useful progress, results, and real human decisions only.
+- If Device state is not writable, stop. Do not switch Node, manually create lock files, delete identity, or rotate Agent Type.
 
 ## Bootstrap
 
 ```bash
 npm install -g @itpay/cli
-itpay readyz
-itpay docs show quickstart
+itpay readyz --json
+itpay skill show itpay-buyer --json
+itpay install --json
+itpay install <agent_type> --json
+itpay --agent-type <agent_type> readyz --json
 ```
 
-The CLI defaults to `https://app.itpay.ai`. Set `ITPAY_BACKEND_URL`
-only for an intentional override.
-
-Every commerce flow must identify the real runtime. Pass the global option
-immediately after `itpay`, or set `ITPAY_AGENT_TYPE` once:
-
-```bash
-itpay --agent-type codex-desktop catalog list --json
-```
+Follow each returned `next.command`. `readyz` deliberately points back to this complete Skill. If the Skill was read without an Agent Type, choose the real runtime with `install`; after typed `readyz`, read the Skill again and continue to Catalog.
 
-Examples include `codex-desktop`, `codex-cli`, `claude-code-desktop`,
-`claude-code-cli`, and the actual WorkBuddy/OpenClaw runtime name. Never rotate
-the type or local device files to obtain more free quota. The CLI enrolls one
-signed device under `~/.itpay-v3/device` and registers each runtime on it.
+Supported types are `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, and `workbuddy`. State the real stable runtime type honestly. Do not identify a window, chat, task, process, or model session as a new Agent.
 
-## Golden Flow
+## Identity And Sessions
 
-1. Discover, then use IDs returned by the CLI:
+- One local Ed25519 private key represents this ItPay installation. Never expose, copy, or rotate it to recover quota.
+- Device registrations are scoped by exact Backend API base URL. `dev`, `test`, and `app` therefore have separate server device IDs, quota lineage, Agent instances, and sessions while using the same local key.
+- Each Backend registration has one Agent Instance per `agent_type`. Different windows and chats of the same type reuse it; different types get separate instances under that registration.
+- Every commerce command must keep the explicit `--agent-type` returned in `next` and `recovery`, or use one stable `ITPAY_AGENT_TYPE`. Never fall back to another type previously used on the machine.
+- The CLI renews an expired or rejected device session and retries the same request exactly once. If that retry still fails, stop and report it; do not loop, create a new identity, or switch Agent Type.
+- A revoked v2 device is not replaced automatically. It requires an explicit operator recovery path.
+- If an operator confirms that one Backend registration database was reset, use `device recover --confirm-backend-reset` for that selected Backend only. This preserves the private key and every other Backend registration; never use it for ordinary session expiry or revocation.
+- `--host` selects presentation. `--target` is only the destination chat/channel/open ID required by some Hosts. Neither is business input or identity.
 
-```bash
-itpay --agent-type <agent_type> catalog list --json
-itpay --agent-type <agent_type> services start <service_id>
-```
+## Envelope Rule
 
-2. Ask the server for the next step:
+For every JSON response:
 
-```bash
-itpay --agent-type <agent_type> services next <service_execution_id> --json
-```
+1. Read `status` and `result` as current facts.
+2. Follow `instruction` when explaining or presenting those facts.
+3. Execute at most the one `next.command`, filling only explicit placeholders or required user data.
+4. Use `recovery` only when the normal next step cannot continue.
 
-3. Execute the first applicable command from `next_actions` unchanged. Typical
-commands are `services invoke`, `services action`, or `services checkout`.
-Do not infer a capability ID or hardcode one service's sequence.
+Do not print the whole envelope to the user. Return the useful result, a short explanation, and the next human action when needed.
 
-4. For a paid result, collect only contact fields requested by the CLI. Create
-the checkout with the exact server-selected capability:
+## Golden Flow
 
 ```bash
-itpay --agent-type <agent_type> services checkout <service_execution_id> \
-  --capability <capability_id> [--email <human_email>] --host <host> --json
+itpay --agent-type <agent_type> catalog list --json
+itpay --agent-type <agent_type> services start <service_id> --json
 ```
 
-Include `--email` only when the CLI's `next_actions` command includes it. For a
-protected delivery, explain that the address receives the order claim link;
-never invent an address. Agent-visible paid results do not require email.
-
-5. Show both handoff forms to the human:
+Then execute the exact `next.command` returned by each step. It may invoke a capability, ask for a selection, create a Checkout, wait for human action, return an Agent-visible result, or read a protected result after grant.
 
-- Attach `brand_qr_local_path` when `brand_qr_status` is `downloaded`.
-- Print `checkout_url` as a clickable link.
-- Keep `checkout_id`, `display_token`, and `service_execution_id` for recovery.
-- Do not substitute a provider QR or call `itpay pay` in the normal buyer flow.
+`services start` creates the Execution and returns the preferred capability plus its `required_input`. Put business values only in repeated `--input key=value` options on the returned `services invoke`, `services quote`, or `services checkout` command. For example, a company keyword belongs in `--input keyword=美团`; it never belongs in `--target`.
 
-6. After the human pays, claims, or grants access, re-read server state:
+Rules:
 
-```bash
-itpay --agent-type <agent_type> services next <service_execution_id> --json
-itpay --agent-type <agent_type> services get <service_execution_id> --json
-```
-
-7. Read protected output only when `next_actions` says the human grant is
-active:
-
-```bash
-itpay --agent-type <agent_type> services read-result <service_execution_id>
-```
-
-The grant is scoped to one Service Execution and expires after 15 minutes. It
-does not expose the buyer's other Vault artifacts, orders, or executions.
+- One independent service intent uses one Service Execution.
+- Every candidate list belongs to its source Service Execution. After a human selects a rank, submit the selection on that same Execution; never copy it into a new Execution or construct a candidate.
+- A normal single-Execution paid step uses the exact `services checkout` command returned by the CLI, but only after the instruction has made the price visible and the human explicitly agrees. The command internally uses the same Quote, Cart and Checkout rules.
+- `services quote -> cart add --quote -> buy --cart` is only for a human who explicitly asks to combine Quotes from multiple independent Executions. Never use it as a fallback when `services checkout` fails.
+- Ask for required email/contact fields; explain their delivery purpose and never invent them.
+- When Checkout is ready, make the amount, ItPay QR/image and URL visible on the current human surface, then stop. Do not query until the human completes the action or asks for status.
+- Normal payment happens on the ItPay Checkout page. `itpay pay` and `buy --pay` are operator escape hatches.
+- Payment is confirmed only by Backend Checkout or Order state.
+- Agent-visible results come from `services next`; do not call `read-result` for them.
+- Quota exhaustion, candidate selection, Checkout pending, payment verified and delivery each remain on the same Execution. Never create a replacement Execution to escape one of those states.
+- An Execution may have delivery history; always follow `services next` for the backend-selected current delivery instead of reusing an older result.
+- Protected results require a current human grant. The grant is scoped to one delivery, approved fields and frozen Agent audience, and expires after 15 minutes.
+- A pending refund locks every delivery path and revokes existing grants.
 
 ## Recovery
 
-Use server-backed recovery before creating anything again:
+Before creating anything again:
 
 ```bash
 itpay --agent-type <agent_type> next --json
 itpay --agent-type <agent_type> services list --json
 itpay --agent-type <agent_type> services next <service_execution_id> --json
 itpay --agent-type <agent_type> services checkout <service_execution_id> --resume --json
-itpay checkout --id <checkout_id> --token <display_token>
+itpay --agent-type <agent_type> checkout --id <checkout_id> --token <display_token> --json
+itpay --agent-type <agent_type> refund get <refund_request_id> --json
+itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 ```
 
-`--resume` reissues the handoff for the existing unpaid checkout. It must not
-create a second order. Local files cache recovery handles; canonical cart,
-quota, execution, checkout, delivery, and grant state comes from the backend.
+## Safety
 
-## Host Selection
+- Never invent service, capability, item, Checkout, Order, grant, or refund IDs.
+- Never expose Provider credentials, raw payloads, display tokens as standalone chat data, Buyer bearer tokens, or Device private keys.
+- Never bypass ownership, compatibility, quota, grant, or refund-lock errors.
+- Do not use `services events` in a normal flow; it is a bounded redacted diagnostic command.
+- Do not rotate Agent Type or local identity to reset free quota.
 
-`--agent-type` identifies the agent runtime. `--host` identifies where the
-human sees the output. They are separate.
-
-| Human surface | CLI options |
-| --- | --- |
-| Codex | `--host codex` |
-| Claude Code | `--host claude-code` |
-| Terminal | `--host terminal` |
-| Telegram | `--host telegram --target <chat_id>` |
-| Feishu/Lark | `--host feishu --target <id>` or `--host lark --target <id>` |
-
-Run `itpay install <host>` for host-specific setup.
-
-## Progressive Disclosure
-
-- Run one state-changing command at a time.
-- Return the useful result, a short explanation, and the next executable step.
-- Ask the human only for a missing required field such as delivery email.
-- When checkout is ready, visibly attach the QR and print the payment link.
-- Prefer CLI `next_actions`; do not dump internal timelines unless diagnosing.
-- Use `--json` for agent parsing and normal rendering for the human handoff.
-
-## Safety Rules
-
-1. Never invent catalog, service, capability, result-item, checkout, or order IDs.
-2. Never expose provider credentials, raw provider metadata, bearer tokens, or device private keys.
-3. Do not treat QR rendering or a human statement as payment confirmation.
-4. Do not call `itpay pay` or use `buy --pay` for a normal checkout; those are operator escape hatches.
-5. Do not create a new execution or checkout until recovery confirms the prior one is unusable.
-6. Do not claim protected access before `services read-result` succeeds.
-7. Do not invent admin, account, grant-creation, or provider-specific CLI commands.
-
-## Built-in Docs
+## Built-In Help
 
 ```bash
-itpay docs list
-itpay docs search <term>
-itpay docs show catalog-list
-itpay docs show cart-checkout
-itpay docs show payment-flow
-itpay docs show orders-refunds
-itpay docs show render-hosts
-itpay docs show install-and-setup
+itpay docs list --json
+itpay docs search <term> --json
+itpay docs show <topic> --json
+itpay skill show itpay-buyer --json
 ```
+
+The normative command contracts are packaged under `docs/cli-reference`.