@itpay/cli 2.0.12 → 2.0.14

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

@@ -1,5 +1,7 @@
 # `itpay services events`
 
+> **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.
+
 ## 范围与意义
 
 按 sequence 升序读取一笔 Service Execution 的受限诊断事件。它只用于解释异常或支持排查，不是正常业务流程，不返回事件 ID、内部摘要、Provider 数据或受保护交付内容。

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

@@ -1,5 +1,7 @@
 # `itpay services get`
 
+> **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.
+
 ## 范围与意义
 
 读取一笔 Service Execution 的紧凑状态、关键节点和当前首选动作。它面向恢复和用户解释，不是原始 event dump。

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

@@ -1,5 +1,7 @@
 # `itpay services`
 
+> **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.
+
 ## 命令范围
 
 操作通用 Service Execution。CLI 不知道某个服务的业务流程；它读取服务合同中的 capability、input schema、价格、交付模式和服务端 next action。

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

@@ -1,11 +1,13 @@
 # `itpay services invoke`
 
+> **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.
+
 ## 范围与意义
 
 调用当前 phase 允许的非付费 Agent-visible capability。输入先按 capability schema 校验，校验失败不得迁移 execution 或记录 Provider 已调用。
 
 **上游：** `services start/next` 明确返回 invoke。
-**下游：** 候选结果、人工 action、付费 Quote 或新 execution。
+**下游：** 候选结果、人工 action 或付费 Quote。一次 invoke 没有结果或返回 Provider 错误时必须停止；只有用户之后明确提供新输入，才启动新的 execution。
 
 ## 语法与参数
 
@@ -33,9 +35,31 @@ itpay services invoke <service_execution_id> --capability <capability_id>
 }
 ```
 
-## 无结果与额度耗尽
+## 无结果
 
-无结果时明确说明 Provider 已返回空结果，并根据服务端 graph 决定重试同一 execution 或启动新 execution。额度耗尽时，普通单 Execution 流程返回完整的 `services checkout` 单项快捷命令；`services quote -> cart add --quote -> buy --cart` 只用于用户明确要求把多个独立 Execution 合并付款的高级流程。
+Provider 已收到请求但没有匹配项时，该 invocation 成功完成、提交一次真实额度消费并返回权威剩余额度。CLI 不提供可自动执行的下一步：Agent 必须展示 0 个结果并停止，不得缩短、改写或猜测输入。
+
+```json
+{
+  "status": "no_result",
+  "result": {
+    "service_execution_id": "<id>",
+    "capability_id": "company_name_suggestion",
+    "query": { "keyword": "北京赢在未来公司" },
+    "items": [],
+    "quota": { "remaining": 1, "limit": 3 }
+  },
+  "instruction": "没有找到与“北京赢在未来公司”匹配的结果。向用户展示本次为 0 个结果并停止。不要修改、缩短或猜测其他输入；只有用户明确提供新输入后，才能启动新的查询。",
+  "next": null,
+  "recovery": []
+}
+```
+
+文本输出只包含 execution、capability、keyword、`results: 0`、quota 和同一条 instruction；不得附带 Provider raw payload、Operation ID 或调试信息。
+
+## 额度耗尽
+
+额度耗尽时，普通单 Execution 流程返回完整的 `services checkout` 单项快捷命令；`services quote -> cart add --quote -> buy --cart` 只用于用户明确要求把多个独立 Execution 合并付款的高级流程。
 
 ```json
 {
@@ -73,13 +97,58 @@ itpay services invoke <service_execution_id> --capability <capability_id>
     "code": "provider_connection_unavailable",
     "message": "provider request was not sent; reserved quota was released"
   },
+  "result": {
+    "service_execution_id": "<id>",
+    "provider_called": false,
+    "quota": { "remaining": 3, "limit": 3 }
+  },
   "instruction": "Provider 请求未发出，预留免费额度已释放；当前 Execution 已失败。立即向用户报告 error.message 并停止，不要自动重试、不要继续同一 Execution，也不要进入任何付费路径。只有运营确认连接恢复且用户明确要求重新查询后，才启动新的 Service Execution。",
   "next": null,
   "recovery": []
 }
 ```
 
-该终态不允许 CLI 猜测网络修复、重复 invoke 或转入购买。连接恢复后也不能复用失败 Execution；必须同时满足“运营已确认恢复”和“用户明确要求再次查询”，才创建新 Execution。
+`result.quota` 是释放预留后的权威余额，不是请求前预留时的临时值。该终态不允许 CLI 猜测网络修复、重复 invoke 或转入购买。连接恢复后也不能复用失败 Execution；必须同时满足“运营已确认恢复”和“用户明确要求再次查询”，才创建新 Execution。
+
+## Provider 输入、临时和契约错误
+
+Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和额度事实。CLI 不读取 raw payload，也不自行推断错误种类。
+
+明确输入错误：
+
+```json
+{
+  "status": "error",
+  "error": { "code": "provider_input_rejected", "message": "输入的名称不合法" },
+  "result": {
+    "service_execution_id": "<id>",
+    "provider_called": true,
+    "quota": { "remaining": 0, "limit": 3 }
+  },
+  "instruction": "Provider 明确拒绝了该输入：输入的名称不合法。请向用户报告 error.message 和 result.quota 并停止。不要自行修改输入、不要重试、不要创建新 Execution；只有用户明确提供新输入后才能重新查询。",
+  "next": null,
+  "recovery": []
+}
+```
+
+契约错误：
+
+```json
+{
+  "status": "error",
+  "error": { "code": "provider_contract_mismatch", "message": "provider response did not match the published contract" },
+  "result": {
+    "service_execution_id": "<id>",
+    "provider_called": true,
+    "quota": { "remaining": 0, "limit": 3 }
+  },
+  "instruction": "Provider 响应与已发布契约不一致。这不是用户输入问题。立即停止，不要修改输入、不要重试、不要创建新 Execution，也不要进入付费路径；向用户报告平台故障和 result.quota。",
+  "next": null,
+  "recovery": []
+}
+```
+
+`provider_temporarily_unavailable` 同样必须停止且不得自动重试。输入错误、临时错误和契约错误都不得返回 `next.command` 或 recovery 命令；新的 Provider 请求只允许来自用户后续明确提出的新输入。
 
 ## Agent Type / Host
 

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

@@ -1,5 +1,7 @@
 # `itpay services list`
 
+> **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.
+
 ## 范围与意义
 
 恢复当前已登记设备或账号可见的 Service Execution 摘要。它不是批量 timeline 导出。

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

@@ -1,5 +1,7 @@
 # `itpay services next`
 
+> **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.
+
 ## 范围与意义
 
 读取一笔 Service Execution 的当前状态，并只返回一个首选下一步。若交付模式允许 Agent 直接读取，本命令同时返回完整 safe result。

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

@@ -1,5 +1,7 @@
 # `itpay services quote`
 
+> **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.
+
 ## 范围与意义
 
 为当前 Service Execution 的一个付费 Capability 准备 Quote Lock。它只锁定可信输入、候选来源、价格、币种和有效期，不创建 Cart、Checkout、订单或 Provider 调用。

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

@@ -1,5 +1,7 @@
 # `itpay services read-result`
 
+> **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.
+
 ## 范围与意义
 
 使用当前 Agent Device Authority，在用户创建的有效、未过期且范围匹配的 grant 内读取 Vault 保护结果。它不适用于 `agent_visible_result`。

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

@@ -1,5 +1,7 @@
 # `itpay services start`
 
+> **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.
+
 ## 范围与意义
 
 按 Catalog 中的 `service_id` 启动一次 Service Execution，并返回当前可执行的唯一首选动作。不会调用 Provider、创建 Checkout 或订单。

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

@@ -1,17 +1,19 @@
 # `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 包内置的完整 Agent Skill。与按 topic 渐进读取的 `docs` 不同，本命令故意一次返回完整 `SKILL.md`，用于首次 onboarding 和身份/session 规则恢复；不访问 Backend，不修改宿主配置或本地身份。
+读取 npm 包内置的完整 ItPay Agent Skill。与按 topic 渐进读取的 `docs` 不同，本命令故意一次返回完整 `SKILL.md`，用于首次 onboarding 和身份/session 规则恢复；不访问 Backend，不修改宿主配置或本地身份。
 
 ```bash
-itpay [--agent-type <agent_type>] skill show itpay-buyer [--json]
+itpay [--agent-type <agent_type>] skill show itpay [--json]
 ```
 
-当前只内置 `itpay-buyer`。`--json` 时完整 Markdown 位于 `result.content`；文本模式直接输出完整内容。
+当前只内置 `itpay`。该 Skill 是 Buyer 与未来 Seller 的共同入口，不再按角色拆分名称。`--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。
+所有 Agent Type 使用相同的 JSON 外壳、字段和命令参数。`workbuddy` 只在 `instruction` 中额外要求：写入 `~/.itpay-v3` 前把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`；权限被拒绝时停止，不切换 Node、不删除 identity、不处理 lock。它不改变输入或输出 schema。

package/docs/cli-reference/conventions.md

@@ -1,5 +1,7 @@
 # Output And Error Contract
 
+> **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.
+
 ## 目标
 
 CLI 输出是给 Agent 执行的协议，不是后端 DTO 的调试转储。默认输出适合人阅读；`--json` 使用同一语义的稳定机器合同。调试事实只由明确的诊断命令返回。
@@ -70,6 +72,9 @@ next: <one command>
 - 用户口头说“已付款”不是支付事实；仅服务端 `verified` 状态有效。
 - `agent_device_session_required` 只触发一次 session 续期和同请求重试；第二次失败必须返回，不得循环或换身份。
 - `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
+- WorkBuddy 在运行会持久化 `~/.itpay-v3` 的 ItPay Bash 命令前，必须把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`。若用户拒绝该权限，命令尚未执行：停止并报告，不得切换 Node、删除 identity、手工处理 lock 或换 Agent Type。
+- `provider_input_rejected` 只表示 Provider 明确声明输入无效；`provider_contract_mismatch` 表示响应无法按已发布契约解释，绝不能归咎于用户输入。两者都必须停止且没有自动 recovery。
+- `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供一个精确的 `npm install -g @itpay/cli@<version>` recovery。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
 
 ## Instruction 模板
 

package/docs/cli-reference/index.md

@@ -2,6 +2,8 @@
 
 本目录是 ItPay CLI 的规范性命令合同。它定义命令应向人和 Agent 返回什么、如何指导下一步，以及失败后如何恢复。当前实现与本文档不一致时，以本文档作为后续校准目标。
 
+> **统一产品边界：** `itpay` 是唯一公开的 CLI 入口，`$itpay` 是对应的用户侧 Skill 调用方式。在同一个产品入口下，两个顶层 commerce 动作是 `buy` 和 `sell`：Buyer 流程当前可用；Seller 流程未来仍使用同一入口，当前尚未实现。不得拆分出独立 Buyer 或 Seller 产品入口。
+
 企知道可以作为示例数据出现，但任何命令、字段、状态和 instruction 都不得依赖某个服务。服务差异只能来自 Catalog、Service Contract、Capability metadata 和服务端状态。
 
 ## 使用约定
@@ -21,7 +23,7 @@
 - [`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 skill show`](commands/skill.md) - 一次读取完整内置 ItPay Skill
 - [`itpay docs`](commands/docs/index.md)
   - [`itpay docs list`](commands/docs/list.md)
   - [`itpay docs show`](commands/docs/show.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.12",
-  "description": "ItPay CLI for V3 checkout, payment, order, refund, and agent-facing render flows.",
+  "version": "2.0.14",
+  "description": "The single ItPay CLI entry point for buy workflows and future sell workflows.",
   "type": "module",
   "bin": {
     "itp": "bin/itp",
@@ -43,6 +43,7 @@
   "devDependencies": {
     "@types/node": "^22.7.5",
     "@types/qrcode": "^1.5.5",
+    "c8": "^10.1.3",
     "tsx": "^4.19.2",
     "typescript": "^5.6.3"
   },
@@ -52,12 +53,14 @@
     "start": "node dist/src/main.js",
     "lint": "tsc -p tsconfig.json --noEmit",
     "clean": "rm -rf dist",
-    "check": "npm run lint && npm test && npm run test:package",
+    "check": "npm run lint && npm run test:coverage && npm run test:package",
     "pack:dry-run": "npm run clean && npm run build && npm pack --dry-run --ignore-scripts",
+    "prepare": "node scripts/install-git-hooks.mjs",
     "test:package": "npm run clean && npm run build && node scripts/package-smoke.mjs",
     "prepack": "npm run clean && npm run build",
     "prepublishOnly": "npm run check",
     "test": "tsx --test tests/*.test.ts",
+    "test:coverage": "c8 --all --src src --extension .ts --exclude=src/client/types.ts --exclude=tests/** --exclude=scripts/** --reporter=text --reporter=lcov --check-coverage --lines 85 --statements 85 --functions 90 --branches 70 npm test",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/skills/{itpay-buyer → itpay}/SKILL.md

@@ -1,28 +1,38 @@
 ---
-name: itpay-buyer
+name: itpay
 description: >
-  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.
+  Use the single ItPay entry point when a human asks an Agent to buy or sell
+  through ItPay. Buyer workflows cover service discovery, purchase, Checkout,
+  delivery, recovery, and refunds. Seller workflows are not yet implemented.
 ---
 
-# ItPay Buyer
+# ItPay
 
 Use the CLI as the only ItPay control surface. Never recreate API calls or hardcode a service-specific sequence.
 
-## Envelope Rule
+## One Entry Point, Two Action Domains
+
+- `itpay` is the only CLI entry point, and `$itpay` is the only user-facing Skill invocation. Never create or route users to a separate Buyer or Seller entry point.
+- `buy` and `sell` are the two top-level ItPay action domains.
+- Buyer workflows are available now. Seller workflows will use this same `itpay` entry point, but are not implemented in the current release.
+- Do not invent Seller commands, onboarding, listings, or successful Seller state before that workflow ships.
+
+## Critical Rules
 
-- Keep one honest Agent Type, CLI/Node launcher, and Host permission context. Supported types: `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, `workbuddy`.
+- The production CLI Backend is fixed to `https://app.itpay.ai`. Never use an environment variable, alternate launcher, or recovery path to redirect it.
+- Keep one honest Agent Type, one CLI/Node launcher, and one Host-approved permission context for the whole flow. Supported types: `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, `workbuddy`.
+- WorkBuddy: before any ItPay Bash command that persists `~/.itpay-v3`, set the Shell tool parameter `dangerouslyDisableSandbox` to `true`. If the human denies that permission, the command did not run: stop and report it.
 - Windows, tasks, chats, processes, and model sessions are not new Agents. Never rotate Agent Type or identity to reset quota.
-- Read `status` and `result` as facts, follow `instruction`, and execute at most the applicable `next.command`; use `recovery` only when it cannot continue.
-- `next.command` is not unconditional. If the result satisfies the user's goal, present useful facts and stop; never dump the whole envelope.
+- 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 --json
-itpay skill show itpay-buyer --json
+itpay skill show itpay --json
 itpay install --json
 itpay install <agent_type> --json
 itpay --agent-type <agent_type> readyz --json
@@ -30,13 +40,28 @@ itpay --agent-type <agent_type> readyz --json
 
 Follow the returned `next.command`. After typed `readyz`, read this complete Skill again, then continue to Catalog.
 
+If `backend_contract_incompatible` returns `result.required_cli_version`, stop every ItPay business command. Run only its exact `npm install -g @itpay/cli@<version>` recovery; never substitute `latest`. Confirm `itpay --version` exactly matches the required version, then restart with typed `readyz`. Never change Agent Type or Device identity to bypass compatibility.
+
 ## Identity And Sessions
 
-- One local Ed25519 private key represents this installation. Never expose, copy, delete, or rotate it during normal recovery.
-- `dev`, `test`, and `app` have separate Device registrations under the same key. Each registration has one Agent Instance per `agent_type`; same-type windows reuse it.
-- Keep the returned `--agent-type` on every commerce command, or use one stable `ITPAY_AGENT_TYPE`. `--host` is presentation and `--target` is routing; neither is identity or business input.
-- The CLI may renew a rejected/expired session and retry once. If it still fails or Device state is not writable, stop; do not loop, switch Node, edit locks, inspect credentials, or change identity.
-- Use `device recover --confirm-backend-reset` only after an operator confirms that Backend was reset. It preserves the key and other Backend registrations.
+- One local Ed25519 private key represents this ItPay installation. Never expose, copy, or rotate it to recover quota.
+- The CLI uses one production Device registration at `https://app.itpay.ai` with 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 the `https://app.itpay.ai` Device registration database was reset, use `device recover --confirm-backend-reset`. This preserves the private key; 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.
+
+## Envelope Rule
+
+For every JSON response:
+
+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.
+
+Do not print the whole envelope to the user. Return the useful result, a short explanation, and the next human action when needed.
 
 ## Golden Flow
 
@@ -91,6 +116,8 @@ Reuse the same Execution and Checkout. Never start another Execution, create ano
 
 `provider_connection_unavailable` is a terminal exception: Backend confirms no Provider request was sent and releases the reservation, then fails that Execution. Stop with no recovery command. Only after an operator confirms connectivity is restored and the human explicitly asks to query again may you start a new Execution.
 
+`no_result` is a completed Provider call with zero items. Show the query, zero results, and the returned quota, then stop. Never shorten, rewrite, or guess another input. `provider_input_rejected`, `provider_temporarily_unavailable`, and `provider_contract_mismatch` are also terminal for the current request: report the exact safe message and quota facts, run no recovery command, and wait for a new explicit human request.
+
 ## Safety
 
 - Never invent service, capability, item, Checkout, Order, grant, or refund IDs.
@@ -105,7 +132,7 @@ Reuse the same Execution and Checkout. Never start another Execution, create ano
 itpay docs list --json
 itpay docs search <term> --json
 itpay docs show <topic> --json
-itpay skill show itpay-buyer --json
+itpay skill show itpay --json
 ```
 
 Normative command contracts are packaged under `docs/cli-reference`.