@itpay/cli 2.0.12 → 2.0.14

package/README.md

@@ -1,17 +1,21 @@
 # ItPay CLI
 
-The official V3 CLI for Agent-driven ItPay service discovery, checkout, delivery, order recovery, and refunds.
+The official V3 CLI and the single ItPay entry point for Agent-driven commerce.
+
+## One Entry Point, Two Actions
+
+`itpay` is the only 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, while Seller workflows will use the same entry point and are not implemented yet. Do not create separate Buyer or Seller product entry points.
 
 ```bash
 npm install -g @itpay/cli
 itpay readyz --json
-itpay skill show itpay-buyer --json
+itpay skill show itpay --json
 itpay install --json
 itpay --agent-type codex-desktop readyz --json
 # follow next.command: typed skill show, then catalog list
 ```
 
-The default API is `https://app.itpay.ai`. Set `ITPAY_BACKEND_URL` only for an intentional environment override.
+The production Backend is permanently pinned to `https://app.itpay.ai`. Runtime environment variables cannot redirect the CLI to another Backend.
 
 ## Output Contract
 
@@ -42,11 +46,11 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 
 `--agent-type` identifies the stable runtime and registered Agent instance. Every returned ItPay command preserves it. Different windows or chats of the same type reuse one Agent Instance; they are not separate identities. `--host` only selects the human presentation surface, and `--target` only routes output to a Host destination. Use `itpay install <agent_type> --json` for the exact responsibility.
 
-The local installation keeps one Ed25519 private key. Each normalized Backend API base URL (`dev`, `test`, `app`, or local) has an independent server device registration, quota lineage, Agent instances, and sessions. A rejected session is renewed and the same request is retried once; revoked v2 registrations are never silently replaced.
+The local installation keeps one Ed25519 private key and one production Device registration for `https://app.itpay.ai`, with one Agent Instance per Agent Type. A rejected session is renewed and the same request is retried once; revoked v2 registrations are never silently replaced.
 
 ## Command Families
 
-- `readyz`, `catalog list`: compatibility and discovery.
+- `readyz`: fixed production Backend liveness; `catalog list`: compatibility-gated discovery.
 - `services start/invoke/action/checkout/next`: generic Service Execution flow.
 - `cart add/show/remove/clear/next`, `buy`: canonical Cart and ordinary Checkout flow.
 - `checkout`: authoritative payment and fulfillment recovery.
@@ -71,11 +75,10 @@ itpay --agent-type <agent_type> services checkout <service_execution_id> --resum
 itpay checkout --id <checkout_id> --token <display_token> --json
 ```
 
-The local `~/.itpay-v3` directory stores one owner-only signing key, Backend-scoped Device registrations and Agent instances, idempotency operations, and recovery handles. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
+The local `~/.itpay-v3` directory stores one owner-only signing key, the `https://app.itpay.ai` Device registration and Agent instances, idempotency operations, and recovery handles. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
 
 ## Environment
 
-- `ITPAY_BACKEND_URL`: deliberate API override.
 - `ITPAY_AGENT_TYPE`: stable alternative to global `--agent-type`.
 - `ITPAY_BEARER_TOKEN`: account-scoped Buyer session for account-only commands such as `orders`.
 - `ITPAY_CART_SESSION_PATH`: local recovery-state path override.
@@ -91,10 +94,14 @@ Provider credentials, Buyer identity, payment provider choice, amount, refund po
 ```bash
 npm run lint
 npm test
+npm run test:coverage
 npm run test:package
 npm run pack:dry-run
 ```
 
+`npm install` configures the repository's pre-commit hook. Every commit must pass
+`npm run lint` and `npm test`; do not bypass the hook for pull-request changes.
+
 Source boundaries:
 
 - `src/main.ts`: parser and error-envelope wiring.

package/dist/src/commands/compatibility.js

@@ -10,6 +10,11 @@ export async function requirePlatformCompatibility(backend) {
     throw new HttpError(426, {
         code: "client_upgrade_required",
         message: `CLI ${CLI_VERSION} contract ${API_CONTRACT_REVISION} is incompatible with platform ${platform.platform_revision} contract ${platform.api_contract_revision} (minimum CLI ${platform.minimum_cli_version}, maximum major ${platform.maximum_cli_major})`,
+        minimum_cli_version: platform.minimum_cli_version,
+        maximum_cli_major: platform.maximum_cli_major,
+        platform_revision: platform.platform_revision,
+        api_contract_revision: platform.api_contract_revision,
+        upgrade_command: `npm install -g @itpay/cli@${platform.minimum_cli_version}`,
     }, "CLI is incompatible with the active ItPay platform release");
 }
 function compareVersions(left, right) {

package/dist/src/commands/docs.js

@@ -92,6 +92,7 @@ function findDocsDir() {
 function parseDoc(raw, file) {
     const value = JSON.parse(raw);
     if (typeof value.schema_version !== "string" ||
+        typeof value.product_scope !== "string" ||
         typeof value.topic !== "string" ||
         typeof value.title !== "string" ||
         typeof value.purpose !== "string") {

package/dist/src/commands/guidance.js

@@ -25,7 +25,7 @@ export function writeCommandEnvelope(value, options = {}) {
         return;
     }
     out(`${qualified.status}\n`);
-    const facts = "result" in qualified ? qualified.result : qualified.error;
+    const facts = "error" in qualified ? qualified.error : qualified.result;
     if (options.plainResult) {
         for (const line of options.plainResult)
             out(`${line}\n`);
@@ -34,6 +34,11 @@ export function writeCommandEnvelope(value, options = {}) {
         for (const [key, fact] of Object.entries(facts)) {
             out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
         }
+        if ("error" in qualified && qualified.result) {
+            for (const [key, fact] of Object.entries(qualified.result)) {
+                out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
+            }
+        }
     }
     if ("handoff" in qualified && qualified.handoff) {
         for (const [key, fact] of Object.entries(qualified.handoff)) {
@@ -252,8 +257,8 @@ export function errorRecoveryActions(error) {
         return [
             {
                 id: "read_agent_session_rules",
-                label: "Read identity and session recovery rules",
-                command: "itpay skill show itpay-buyer --json",
+                label: "Read ItPay identity and session recovery rules",
+                command: "itpay skill show itpay --json",
                 reason: "The CLI already attempted one automatic session renewal; do not rotate identity or loop retries.",
             },
         ];
@@ -299,14 +304,9 @@ export function errorRecoveryActions(error) {
         return [
             {
                 id: "retry_after_backend_recovers",
-                label: "Retry after the ItPay backend is reachable",
+                label: "Retry after app.itpay.ai is reachable",
                 command: "itpay readyz",
             },
-            {
-                id: "check_backend_url",
-                label: "Check the configured backend URL",
-                command: "echo $ITPAY_BACKEND_URL",
-            },
         ];
     }
     return [];
@@ -417,13 +417,7 @@ function buildServiceGuidance(input) {
         }
     }
     else if ((input.providerCalled || execution.next_action === "select_candidate") && (input.resultItems?.length ?? 0) === 0) {
-        nextActions.push({
-            id: "start_refined_search",
-            label: "Start a new execution with a more specific company name",
-            command: `itpay services start ${execution.service_id}`,
-            requires_human: true,
-            reason: "No candidates were found. This execution is finished; use one new execution per new keyword.",
-        });
+        // Terminal empty result: a later explicit human request starts a new flow.
     }
     else if (needsHumanSelection(execution, resultItem)) {
         nextActions.push({
@@ -433,12 +427,6 @@ function buildServiceGuidance(input) {
             requires_human: true,
             reason: "Do not choose a candidate without explicit human confirmation.",
         });
-        nextActions.push({
-            id: "start_another_search",
-            label: "Search another company in a new execution",
-            command: `itpay services start ${execution.service_id}`,
-            reason: "This execution has completed its one keyword lookup; do not reuse it for another keyword.",
-        });
     }
     else if (prePurchase) {
         const action = {

package/dist/src/commands/install.js

@@ -13,7 +13,7 @@ const INSTRUCTIONS = {
     "codex-cli": "在 Codex CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
-    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type；Checkout 返回 qr_image_url 时，必须按当次 instruction 调用 present_files 在右侧打开二维码，不要检查本地二维码文件。",
+    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回 qr_image_url 时，按当次 instruction 调用 present_files 在右侧打开二维码，不要检查本地二维码文件。",
 };
 export function runInstall(target, options = {}) {
     if (!target || target === "list") {
@@ -48,9 +48,9 @@ export function runInstall(target, options = {}) {
         instruction: INSTRUCTIONS[normalized],
         next: {
             command: `itpay --agent-type ${normalized} readyz --json`,
-            reason: "验证 CLI 与默认 ItPay API 的兼容性",
+            reason: "验证固定生产 ItPay API 的可用性",
         },
-        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看环境覆盖和首次使用说明" }],
+        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看固定生产后端和首次使用说明" }],
     }, options);
 }
 function isInstallAgentType(value) {

package/dist/src/commands/readyz.js

@@ -5,8 +5,8 @@ export async function runReadyz(backend, options = {}) {
     writeCommandEnvelope({
         status: response.status,
         result: { backend: "available", ...(options.agentType ? { agent_type: options.agentType } : {}) },
-        instruction: "ItPay 可用；先完整读取内置 Buyer Skill，再开始服务流程。",
-        next: { command: "itpay skill show itpay-buyer --json", reason: "加载完整操作与安全规则" },
+        instruction: "ItPay 可用；先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。sell 将来也使用同一入口，但当前尚未实现。",
+        next: { command: "itpay skill show itpay --json", reason: "加载完整操作与安全规则" },
         recovery: [],
     }, options);
 }

package/dist/src/commands/services.js

@@ -106,13 +106,14 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
     const baseResult = {
         service_execution_id: response.execution.service_execution_id,
         capability_id: requestedCapability.capability_id,
+        query: input,
         items,
         ...(quota ? { quota } : {}),
     };
     let status = items.length > 0 ? "result_ready" : "no_result";
     let instruction = items.length > 0
         ? "向用户展示编号和 safe_payload；若候选列表已满足用户目标，在此停止。仅在用户明确选择并希望继续时，才在当前 Execution 提交对应 rank。"
-        : "Provider 已返回空结果；不要重放当前 execution，按下一步恢复。";
+        : `没有找到与“${queryText(input)}”匹配的结果。向用户展示本次为 0 个结果并停止。不要修改、缩短或猜测其他输入；只有用户明确提供新输入后，才能启动新的查询。`;
     let next = null;
     if (response.effective_quota?.exhausted) {
         status = "quota_exhausted";
@@ -148,9 +149,7 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
         };
     }
     else if (items.length === 0) {
-        next = response.provider_called
-            ? { command: `itpay services start ${response.execution.service_id}`, reason: "为新的服务输入启动新 execution" }
-            : { command: `itpay services next ${response.execution.service_execution_id} --json`, reason: "读取服务端恢复动作" };
+        next = null;
     }
     return {
         value: { status, result: baseResult, instruction, next, recovery: [] },
@@ -162,11 +161,18 @@ function serviceResultPlainLines(result) {
         `service_execution_id: ${String(result.service_execution_id)}`,
         `capability_id: ${String(result.capability_id)}`,
     ];
+    const items = result.items;
+    const query = result.query;
+    if (query) {
+        for (const [key, value] of Object.entries(query))
+            lines.push(`${key}: ${String(value)}`);
+    }
+    if (items.length === 0)
+        lines.push("results: 0");
     if (result.quota)
         lines.push(`quota: ${JSON.stringify(result.quota)}`);
     if (result.checkout)
         lines.push(`checkout: ${JSON.stringify(result.checkout)}`);
-    const items = result.items;
     if (items.length > 0) {
         lines.push("items:");
         for (const item of items) {
@@ -178,6 +184,10 @@ function serviceResultPlainLines(result) {
     }
     return lines;
 }
+function queryText(input) {
+    const value = Object.values(input).find((item) => typeof item === "string" && item.trim() !== "");
+    return typeof value === "string" ? value : JSON.stringify(input);
+}
 function missingRequiredInput(schema, input) {
     return requiredInputFields(schema).filter((field) => {
         if (!(field in input) || input[field] === null || input[field] === undefined)
@@ -695,12 +705,12 @@ function servicesNextEnvelope(model) {
                 ? selection
                     ? "Agent-visible 搜索已完成。向用户展示 items 中的编号、title 和 safe_payload，然后停止；不要调用 read-result。只有用户明确选择候选并要求继续时，才执行 next.command。"
                     : "这是当前 Graph 步骤对应的交付；结果已可供 Agent 使用，只使用 safe_payload。"
-                : "Agent-visible 交付已完成但没有结果项；不要调用 read-result 或重放当前 execution。",
+                : "Agent-visible 交付已完成但有 0 个结果。向用户展示空结果并停止；不要调用 read-result、重放当前 Execution、修改输入或创建新 Execution。",
             next: selection ? {
                 command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
                 reason: "仅在用户明确选择后锁定来源候选",
             } : null,
-            recovery: items.length > 0 ? [] : [{ command: `itpay services get ${execution.service_execution_id} --json`, reason: "检查交付时间线" }],
+            recovery: [],
         };
     }
     if (deliveryMode === "vault_artifact") {

package/dist/src/commands/skill.js

@@ -4,27 +4,27 @@ import { fileURLToPath } from "node:url";
 import { declaredAgentType } from "../state/agent_type.js";
 import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
 const commandDir = dirname(fileURLToPath(import.meta.url));
-const BUYER_SKILL = "itpay-buyer";
+const ITPAY_SKILL = "itpay";
 export function runSkillShow(name, options = {}) {
     const normalized = name.trim().toLowerCase();
-    if (normalized !== BUYER_SKILL) {
-        throw new CommandContractError("skill_not_found", `skill not found: ${name}`, `当前 CLI 只内置 ${BUYER_SKILL}；不要猜测 Skill 名称。`, [{ command: `itpay skill show ${BUYER_SKILL} --json`, reason: "读取完整 Buyer Skill" }]);
+    if (normalized !== ITPAY_SKILL) {
+        throw new CommandContractError("skill_not_found", `skill not found: ${name}`, `当前 CLI 只内置 ${ITPAY_SKILL}；不要猜测 Skill 名称。`, [{ command: `itpay skill show ${ITPAY_SKILL} --json`, reason: "读取完整 ItPay Skill" }]);
     }
     let content;
     try {
         content = readFileSync(findSkillPath(), "utf8");
     }
     catch {
-        throw new Error("packaged skill is unavailable: itpay-buyer");
+        throw new Error("packaged skill is unavailable: itpay");
     }
     validateSkill(content);
     const agentType = options.agentType ?? declaredAgentType();
     const envelope = {
         status: "shown",
-        result: { skill: BUYER_SKILL, content },
+        result: { skill: ITPAY_SKILL, content },
         instruction: agentType
             ? agentType === "workbuddy"
-                ? "完整读取并遵守 Skill；保持 workbuddy、同一 Node/CLI launcher 和可持久写入 Device 状态的执行权限。内部诊断不要逐步转述给用户。"
+                ? "完整读取并遵守 Skill；保持 workbuddy 和同一 Node/CLI launcher。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。"
                 : `完整读取并遵守 Skill；当前 Agent Type 是 ${agentType}，后续命令保持不变。`
             : "完整读取并遵守 Skill；先如实选择当前运行环境对应的 Agent Type。",
         next: agentType
@@ -40,16 +40,16 @@ export function runSkillShow(name, options = {}) {
 }
 function findSkillPath() {
     if (process.env.ITPAY_CLI_SKILLS_DIR) {
-        return resolve(process.env.ITPAY_CLI_SKILLS_DIR, BUYER_SKILL, "SKILL.md");
+        return resolve(process.env.ITPAY_CLI_SKILLS_DIR, ITPAY_SKILL, "SKILL.md");
     }
-    const packagePath = resolve(commandDir, "..", "..", "..", "skills", BUYER_SKILL, "SKILL.md");
+    const packagePath = resolve(commandDir, "..", "..", "..", "skills", ITPAY_SKILL, "SKILL.md");
     if (existsSync(packagePath))
         return packagePath;
-    return resolve(commandDir, "..", "..", "skills", BUYER_SKILL, "SKILL.md");
+    return resolve(commandDir, "..", "..", "skills", ITPAY_SKILL, "SKILL.md");
 }
 function validateSkill(content) {
     const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
-    if (!frontmatter || !/^name:\s*itpay-buyer\s*$/m.test(frontmatter) || !/^description:\s*(?:>|\S)/m.test(frontmatter)) {
-        throw new Error("invalid packaged skill: itpay-buyer");
+    if (!frontmatter || !/^name:\s*itpay\s*$/m.test(frontmatter) || !/^description:\s*(?:>|\S)/m.test(frontmatter)) {
+        throw new Error("invalid packaged skill: itpay");
     }
 }

package/dist/src/main.js

@@ -26,7 +26,7 @@ import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckou
 const program = new Command();
 program
     .name("itpay")
-    .description("V3 ItPay CLI — checkout, payment, order, and refund commands")
+    .description("V3 ItPay CLI — one entry point for buy workflows and future sell workflows")
     .option("--agent-type <type>", "agent runtime type used for device enrollment and client-specific guidance")
     .version(CLI_VERSION);
 function withHost(value) {
@@ -95,17 +95,22 @@ function reportCLIError(error, contract) {
         error.code === "client_compatibility_headers_required" ||
         error.code === "platform_release_unavailable" ||
         (error.status === 404 && error.code === "unknown_error"));
+    const requiredCLIVersion = incompatible && error instanceof HttpError && /^\d+\.\d+\.\d+$/.test(error.payload?.minimum_cli_version ?? "")
+        ? error.payload.minimum_cli_version
+        : undefined;
     const backendInternal = error instanceof HttpError && error.status === 500 && error.code === "internal_error";
     const providerConnectionUnavailable = error instanceof HttpError && error.code === "provider_connection_unavailable";
     const providerTemporary = error instanceof HttpError && error.code === "provider_temporarily_unavailable";
     const providerRejected = error instanceof HttpError && error.code === "provider_rejected";
+    const providerInputRejected = error instanceof HttpError && error.code === "provider_input_rejected";
+    const providerContractMismatch = error instanceof HttpError && error.code === "provider_contract_mismatch";
     const capabilityInputInvalid = error instanceof HttpError && error.code === "capability_input_invalid";
     const deviceRecovery = deviceError ? [{
-            command: "itpay skill show itpay-buyer --json",
-            reason: "读取身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
+            command: "itpay skill show itpay --json",
+            reason: "读取 ItPay 身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
         }] : [];
     const stateRecovery = stateError ? [{
-            command: "itpay skill show itpay-buyer --json",
+            command: "itpay skill show itpay --json",
             reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
         }] : [];
     const authorizationInstruction = stateError
@@ -124,21 +129,50 @@ function reportCLIError(error, contract) {
                 code: incompatible ? "backend_contract_incompatible" : commandError?.code ?? (error instanceof HttpError ? error.code : stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
+            ...(requiredCLIVersion ? {
+                result: {
+                    current_cli_version: CLI_VERSION,
+                    required_cli_version: requiredCLIVersion,
+                },
+            } : error instanceof HttpError && error.payload?.service_execution_id ? {
+                result: {
+                    service_execution_id: error.payload.service_execution_id,
+                    provider_called: error.payload.provider_called === true,
+                    ...(error.payload.effective_quota ? {
+                        quota: {
+                            remaining: error.payload.effective_quota.remaining,
+                            limit: error.payload.effective_quota.limit,
+                        },
+                    } : {}),
+                },
+            } : {}),
             instruction: incompatible
-                ? "立即向用户报告 error.message 并结束本次任务。不要运行任何其他 itpay、npm、which、device、docs、cart、orders 或 services 命令；不要寻找、安装或切换其他 CLI。只有运营明确提供兼容 CLI 后，才能在新的任务中重新开始。"
+                ? requiredCLIVersion
+                    ? "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。"
+                    : "立即向用户报告 error.message 并结束本次任务。Backend 未提供可验证的兼容 CLI 版本；不要运行其他 ItPay 或 npm 命令，不要猜测版本、切换 Agent Type 或删除 Device 身份。"
                 : backendInternal
                     ? "Backend 内部故障；立即停止并向用户报告。不要重试、检查或删除 Device 身份、创建替代 Execution、切换 Backend，或尝试 quote、checkout、cart、buy、pay 等付费路径。"
                     : providerConnectionUnavailable
                         ? "Provider 请求未发出，预留免费额度已释放；当前 Execution 已失败。立即向用户报告 error.message 并停止，不要自动重试、不要继续同一 Execution，也不要进入任何付费路径。只有运营确认连接恢复且用户明确要求重新查询后，才启动新的 Service Execution。"
                         : providerTemporary
-                            ? "上游服务暂时不可用；向用户逐字报告 error.message 并停止，不要自动重试。请求是否可能计费以 Backend 的消费事实为准；只有用户明确要求再次查询后，才可按 next/recovery 重新开始。"
-                            : providerRejected
-                                ? "上游拒绝了本次输入；向用户逐字报告 error.message 并停止，不要重试同一 Execution。Provider 已收到响应，本次请求可能计费；只有用户提供修正后的输入后，才可按 next/recovery 继续。"
-                                : capabilityInputInvalid
-                                    ? "输入未通过本地校验，上游尚未被调用且用户额度未变化。向用户逐字报告 error.message 并停止，不要原样重试或运行其他恢复命令。用户提供修正后的输入后，继续使用当前未结束的 Execution。"
-                                    : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
+                            ? "上游服务暂时不可用；向用户逐字报告 error.message 和 result.quota 并停止，不要自动重试、不要创建新 Execution。只有用户之后明确提出新请求，才可重新开始。"
+                            : providerInputRejected
+                                ? `Provider 明确拒绝了该输入：${error instanceof Error ? error.message : String(error)}。请向用户报告 error.message 和 result.quota 并停止。不要自行修改输入、不要重试、不要创建新 Execution；只有用户明确提供新输入后才能重新查询。`
+                                : providerContractMismatch
+                                    ? "Provider 响应与已发布契约不一致。这不是用户输入问题。立即停止，不要修改输入、不要重试、不要创建新 Execution，也不要进入付费路径；向用户报告平台故障和 result.quota。"
+                                    : providerRejected
+                                        ? "Provider 拒绝了本次请求，但未声明这是输入错误；向用户逐字报告 error.message 和 result.quota 并停止。不要修改输入、不要重试、不要创建新 Execution。"
+                                        : capabilityInputInvalid
+                                            ? "输入未通过本地校验，上游尚未被调用且用户额度未变化。向用户逐字报告 error.message 并停止，不要原样重试或运行其他恢复命令。用户提供修正后的输入后，继续使用当前未结束的 Execution。"
+                                            : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
-            recovery: incompatible || backendInternal || providerConnectionUnavailable || providerTemporary || providerRejected || capabilityInputInvalid ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+            recovery: incompatible
+                ? requiredCLIVersion
+                    ? [{ command: `npm install -g @itpay/cli@${requiredCLIVersion}`, reason: "安装 Backend 指定的兼容 CLI 版本" }]
+                    : []
+                : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
+                    ? []
+                    : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
             ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : {}),
             output: (text) => { process.stderr.write(text); },
@@ -175,17 +209,15 @@ program
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await requirePlatformCompatibility(backend);
         await runReadyz(backend, { jsonOutput: Boolean(options.json), ...(config.agentType ? { agentType: config.agentType } : {}) });
     }
     catch (error) {
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
             code: "backend_unavailable",
-            instruction: "检查 ITPAY_BACKEND_URL 后重试；后端恢复前不要继续下单。",
+            instruction: "固定生产后端 https://app.itpay.ai 当前不可用；后端恢复前不要继续下单，也不要切换到其他地址。",
             recovery: [
-                { command: "echo $ITPAY_BACKEND_URL", reason: "确认当前 Backend URL" },
-                { command: "itpay readyz", reason: "重试可用性检查" },
+                { command: "itpay readyz", reason: "重试固定生产后端的可用性检查" },
             ],
         });
     }
@@ -194,14 +226,14 @@ program
 const deviceCmd = program.command("device").description("Recover local Device registration state after an operator-confirmed Backend reset");
 deviceCmd
     .command("recover")
-    .description("Forget only the selected Backend registration while preserving the local private key")
+    .description("Forget only the app.itpay.ai registration while preserving the local private key")
     .option("--confirm-backend-reset", "confirm that an operator reset the selected Backend registration database")
     .option("--json", "output JSON instead of terminal text")
     .action(async (options) => {
     const config = loadConfig();
     try {
         if (!config.agentType) {
-            throw new CommandContractError("agent_type_required", "agent type is required for Backend-scoped Device recovery", "如实声明当前 Agent Type；恢复后必须用同一类型重新登记。", [{ command: "itpay install --json", reason: "选择当前真实 Agent Type" }]);
+            throw new CommandContractError("agent_type_required", "agent type is required for app.itpay.ai Device recovery", "如实声明当前 Agent Type；恢复后必须用同一类型重新登记。", [{ command: "itpay install --json", reason: "选择当前真实 Agent Type" }]);
         }
         if (!options.confirmBackendReset) {
             throw new CommandContractError("backend_reset_confirmation_required", "--confirm-backend-reset is required", "仅在运营已确认当前 Backend 的 Device 登记数据库被重建或清空后执行；普通 session 失效或 revoked 不得使用。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);

package/dist/src/state/config.js

@@ -1,4 +1,5 @@
-// CLI configuration loader. Reads config from environment only. Checkout
+// CLI configuration loader. The production Backend is pinned to app.itpay.ai;
+// environment variables configure only non-Backend runtime details. Checkout
 // display-token persistence belongs to the cart session file, protected with
 // owner-only permissions. Provider secrets are explicitly out of scope here.
 import { homedir } from "node:os";
@@ -10,8 +11,8 @@ import { declaredAgentType } from "./agent_type.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
-export const CLI_VERSION = "2.0.12";
-export const API_CONTRACT_REVISION = "sha256:ea7d716f444a01e9d0109f12a53b56ce16d5ab813795a18a7a63f24a8c752073";
+export const CLI_VERSION = "2.0.14";
+export const API_CONTRACT_REVISION = "sha256:7f4c40b082292bf823631bcd37d452f4a8537153e30636d5eb3a2b24a77ce602";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";
@@ -24,7 +25,7 @@ export function cartSessionPath(env = process.env) {
     return resolve(dir, CART_SESSION_FILENAME);
 }
 export function loadConfig(env = process.env) {
-    const baseURL = env.ITPAY_BACKEND_URL || DEFAULT_BASE_URL;
+    const baseURL = DEFAULT_BASE_URL;
     const bearerToken = env.ITPAY_BEARER_TOKEN || undefined;
     const agentType = declaredAgentType(env);
     const checkoutCurrency = env.ITPAY_CURRENCY || "CNY";

package/docs/agent/buyer/cart-checkout.json

@@ -1,6 +1,7 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
+  "product_scope": "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.",
   "topic": "cart-checkout",
   "title": "Canonical Cart And Checkout Routing",
   "purpose": "Use the canonical server Cart and route service-backed lines through Service Execution without hardcoded service logic.",
@@ -43,8 +44,20 @@
     "Do not treat QR display as payment verification."
   ],
   "next_docs": [
-    { "condition": "Checkout handoff is ready", "topic": "payment-flow" },
-    { "condition": "Host rendering needs clarification", "topic": "render-hosts" }
+    {
+      "condition": "Checkout handoff is ready",
+      "topic": "payment-flow"
+    },
+    {
+      "condition": "Host rendering needs clarification",
+      "topic": "render-hosts"
+    }
   ],
-  "search_terms": ["cart", "checkout", "service execution", "resume", "contact"]
+  "search_terms": [
+    "cart",
+    "checkout",
+    "service execution",
+    "resume",
+    "contact"
+  ]
 }

package/docs/agent/buyer/catalog-list.json

@@ -1,6 +1,7 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
+  "product_scope": "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.",
   "topic": "catalog-list",
   "title": "Browse ItPay V3 Service Catalog",
   "purpose": "Teach the agent how to browse and display available catalog services to the buyer.",

package/docs/agent/buyer/identity-and-sessions.json

@@ -1,18 +1,19 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
+  "product_scope": "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.",
   "topic": "identity-and-sessions",
   "title": "Device Identity And Session Recovery",
-  "purpose": "Explain stable local identity, Backend-scoped registrations, Agent Type instances, and bounded automatic session recovery.",
+  "purpose": "Explain stable local identity, the fixed app.itpay.ai production registration, Agent Type instances, and bounded automatic session recovery.",
   "when_to_use": [
     "A different Agent window or runtime starts using an existing CLI installation.",
     "The CLI reports device_state_unwritable, or the Backend reports agent_identity_required, agent_device_session_required, or agent_device_revoked.",
-    "The configured ITPAY_BACKEND_URL changes between dev, test, and app."
+    "An operator confirms that the app.itpay.ai Device registration database was reset."
   ],
   "identity_model": {
     "local_key": "One owner-only Ed25519 private key for the local installation.",
-    "backend_registration": "One independent server registration per normalized Backend API base URL.",
-    "agent_instance": "One instance per agent_type under each Backend registration; same-type windows and chats reuse it.",
+    "backend_registration": "One production Device registration for https://app.itpay.ai; runtime environment variables cannot redirect the CLI.",
+    "agent_instance": "One instance per agent_type under the production registration; same-type windows and chats reuse it.",
     "presentation": "Host and target route output only and never identify the Agent or provide business input."
   },
   "automatic_recovery": [
@@ -29,36 +30,56 @@
   "commands": [
     {
       "intent": "reload the complete rules",
-      "command": "itpay --agent-type <agent_type> skill show itpay-buyer --json",
+      "command": "itpay --agent-type <agent_type> skill show itpay --json",
       "success_signal": "the full Skill is returned and next keeps the same Agent Type"
     },
     {
-      "intent": "confirm the selected Backend is available",
+      "intent": "confirm app.itpay.ai is available",
       "command": "itpay --agent-type <agent_type> readyz --json",
       "success_signal": "Backend is available and onboarding returns to the Skill"
     },
     {
-      "intent": "recover after an operator-confirmed reset of the selected Backend registration database",
+      "intent": "recover after an operator-confirmed reset of the app.itpay.ai Device registration database",
       "command": "itpay --agent-type <agent_type> device recover --confirm-backend-reset --json",
-      "success_signal": "only the selected Backend registration is removed; the private key and other Backend registrations remain"
+      "success_signal": "only the app.itpay.ai registration is removed and the private key remains"
     }
   ],
   "agent_rules": [
     "Use the real runtime type and keep it stable across every command in the flow.",
     "Keep the same CLI/Node launcher and Host-approved permission context for the whole flow.",
     "Treat a new window, chat, task, or process of the same runtime as the same Agent Type, not a new identity.",
-    "Expect dev, test, and app to have separate device IDs, quota lineage, Agent instances, and sessions even on the same machine.",
-    "After automatic recovery fails, stop and report the exact code, Backend URL, Agent Type, and command family without exposing private keys or tokens."
+    "Expect all production CLI traffic to use https://app.itpay.ai; do not set or suggest a Backend URL override.",
+    "After automatic recovery fails, stop and report the exact code, app.itpay.ai, Agent Type, and command family without exposing private keys or tokens."
   ],
   "forbidden": [
     "Do not delete ~/.itpay-v3, rotate the key, switch Agent Type, or repeatedly retry to obtain fresh quota.",
     "Do not use device recover for session expiry, revocation, quota recovery, or an unconfirmed Backend failure.",
-    "Do not copy a server device ID from one Backend registration into another.",
+    "Do not redirect the CLI to dev, test, local, or any non-app.itpay.ai Backend.",
     "Do not use --target as identity or service input."
   ],
   "next_docs": [
-    { "condition": "Identity is healthy", "topic": "quickstart" },
-    { "condition": "Need setup details", "topic": "install-and-setup" }
+    {
+      "condition": "Identity is healthy",
+      "topic": "quickstart"
+    },
+    {
+      "condition": "Need setup details",
+      "topic": "install-and-setup"
+    }
   ],
-  "search_terms": ["identity", "device", "session", "login", "authentication", "agent type", "backend", "revoked", "recover", "unwritable", "lock", "window", "chat"]
+  "search_terms": [
+    "identity",
+    "device",
+    "session",
+    "login",
+    "authentication",
+    "agent type",
+    "backend",
+    "revoked",
+    "recover",
+    "unwritable",
+    "lock",
+    "window",
+    "chat"
+  ]
 }