@itpay/cli 2.1.45 → 2.1.46

package/README.md

@@ -6,26 +6,16 @@ The official V3 CLI and the single ItPay entry point for services, purchases, ac
 
 `itpay` is the only public CLI entry point, and `$itpay` is its user-facing Skill invocation. The Agent first distinguishes a new service request, previously purchased content, order history, or a refund. Seller workflows use the existing `itpay sell` entry point.
 
+Follow the official setup link for the authorized channel and matching Backend. Standard npm can use a host-managed persistent tool location or a global prefix; retain one exact executable.
+
 ```bash
-npm install -g @itpay/cli
-itpay install --json
-itpay --agent-type codex-desktop readyz --json
-# execute the returned next.command until the typed Skill is loaded
+itpay setup --agent-type <actual_type> --json
+# read and enable the same-package Skill returned by setup
 ```
 
-Official Agent install prompt（可直接复制给 Agent）：
-
-> 安装或更新官方 `@itpay/cli`。从 `itpay install --json` 开始，选择你真实
-> 所在的平台，完整执行 iTPay 返回的每个 `next.command` 并读取内置 Skill。
-> 初始化后，根据我的自然语言需求自行使用 iTPay，不要让我运行命令，也不要向
-> 我讲解命令、内部 ID 或技术步骤。只有需要我选择、授权、付款、提供联系方式
-> 或确认退款时，才用通俗语言询问我；展示官方操作入口后停止等待。不要猜命令、
-> 切换身份或环境、绕过授权或重复创建资源。准备完成后只回复“iTPay 已就绪”。
-
-Use a separate test prompt to set the exact official Dev Backend. Never put a
-Dev override in the public install prompt.
+使用宿主允许的持久安装方式运行官方 ItPay CLI，不要求全局安装。固定本次安装的入口、实际 Agent Type 和 Backend。首次使用或更新后运行 setup；setup_ready 证明设备准备完成，账号授权状态单独列出。完整读取当前包 Skill，并按宿主方式保存启用；同版本已读且已启用时无需重复。业务请求需要真人授权时使用返回的官方入口，不以安装授权代替购买同意。安装位置变化不要求清除设备身份。
 
-The CLI defaults to the production Backend `https://app.itpay.ai`. Explicit sandbox runs may set `ITPAY_BACKEND_URL=https://sandbox.itpay.ai`; every other Backend URL is rejected before network or local state access.
+The CLI defaults to the production Backend `https://app.itpay.ai`. Explicit test runs may set `ITPAY_BACKEND_URL=https://sandbox.itpay.ai` or `https://dev.itpay.ai`; nonofficial Backend URLs are rejected before network or local state access.
 
 ## Output Contract
 
@@ -134,3 +124,7 @@ Source boundaries:
 Use `itpay services run <service_id> --input-json ./input.json --json` for a published workflow. The input file must contain a JSON object matching the service input schema. With no input file, the CLI reports required fields and a command to continue the same execution.
 
 Use `itpay services run <service_id> --execution <execution_id> --json` to resume. At payment, the CLI uses the existing Checkout QR/card handoff. The backend continues after verified payment even if the CLI exits. `--timeout <seconds>` controls initial status polling (default 120, maximum 600). Use existing order/refund commands for refund requests; an application is not a successful refund until its final status confirms success.
+
+## Agent preparation
+
+Install the official package using standard npm in one host-permitted persistent tool location or a global prefix. Retain the exact callable entry. Run `itpay setup --agent-type <actual_type> --json`, then read and enable its same-package Skill before business commands. Account login is separate and occurs only when needed. See [setup](docs/cli-reference/commands/setup.md).

package/dist/src/commands/install.js

@@ -30,7 +30,7 @@ export function runInstall(target, options = {}) {
         writeCommandEnvelope({
             status: "install_targets",
             result: { agent_types: agentTypes },
-            instruction: "识别当前真实运行平台，从 result.agent_types 选择对应 agent_type，并由 Agent 自行运行 itpay install <agent_type> --json；不要让用户运行命令，也不要临时更换 Agent Type。",
+            instruction: "识别当前真实运行平台，从 result.agent_types 选择对应 agent_type，并由 Agent 自行运行 itpay setup --agent-type <agent_type> --json；不要让用户运行命令，也不要临时更换 Agent Type。",
             next: null,
             recovery: [{ command: "itpay docs show install-and-setup", reason: "查看安装与环境说明" }],
         }, {
@@ -51,13 +51,13 @@ export function runInstall(target, options = {}) {
         },
         instruction: INSTRUCTIONS[normalized] + (normalized.startsWith("codex-") ? ` ${CODEX_WAIT_GUIDANCE}` : ""),
         next: {
-            command: `itpay --agent-type ${normalized} readyz --json`,
-            reason: "验证当前官方 ItPay API 的可用性",
+            command: `itpay --agent-type ${normalized} setup --json`,
+            reason: "准备当前宿主并确认设备与账号状态",
         },
         recovery: [],
     }, options);
 }
-function isInstallAgentType(value) {
+export function isInstallAgentType(value) {
     return INSTALL_AGENT_TYPES.includes(value);
 }
 function installDefinition(agentType) {

package/dist/src/commands/readyz.js

@@ -7,12 +7,10 @@ export async function runReadyz(backend, options = {}) {
     writeCommandEnvelope({
         status: response.status,
         result: { backend: "available", backend_url: backendURL, environment, ...(options.agentType ? { agent_type: options.agentType } : {}) },
-        instruction: environment === "development"
-            ? `ItPay 开发环境 ${backendURL} 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；后续必须执行返回的完整命令并保持同一 Backend。`
-            : "ItPay 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；不自动登录或开始业务。",
+        instruction: `ItPay ${environment === "development" ? "开发" : "正式"}环境 ${backendURL} 可用。只证明后端存活；首次使用或更新后运行 setup，不自动登录或开始业务。`,
         next: options.agentType
-            ? { command: "itpay auth status --json", reason: "检查同一 Backend 和宿主的设备访问；login_required 不代表已登录" }
-            : { command: "itpay install --json", reason: "选择实际宿主，再检查设备访问；尚未读本包 Skill 时先完整读取" },
+            ? { command: "itpay setup --json", reason: "确认同一 Backend 和宿主的设备及账号准备状态" }
+            : { command: "itpay install --json", reason: "识别实际宿主类型后执行 setup" },
         recovery: [],
     }, options);
 }

package/dist/src/commands/setup.js

@@ -0,0 +1,37 @@
+import { requirePlatformCompatibility } from "./compatibility.js";
+import { agentAuth } from "../state/account_auth.js";
+import { CLI_VERSION } from "../state/config.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+import { INSTALL_AGENT_TYPES, isInstallAgentType } from "./install.js";
+import { packagedSkill } from "./skill.js";
+export function validateSetup(agentType) {
+    if (!agentType || !isInstallAgentType(agentType)) {
+        throw new CommandContractError("unsupported_agent_type", "setup requires a supported actual Agent Type", `准备未完成：宿主类型。可用类型：${INSTALL_AGENT_TYPES.join(", ")}。`, [{ command: "itpay install --json", reason: "识别实际宿主类型" }]);
+    }
+    try {
+        return packagedSkill().path;
+    }
+    catch (error) {
+        const cause = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+            ? error.code : "invalid_packaged_skill";
+        throw new CommandContractError("packaged_skill_unavailable", "current package Skill is missing or invalid", "准备未完成：同包 Skill 不可读取。按返回原因确认宿主正常读取权限或恢复原位置的完整官方包。", [], undefined, { failure_stage: "packaged_skill", cause_code: cause });
+    }
+}
+export async function runSetup(backend, config, skillPath, options = {}) {
+    await requirePlatformCompatibility(backend);
+    const account = await agentAuth("status", config.baseURL, backend, undefined, undefined, { readOnlyStatus: true });
+    if (!account || typeof account !== "object" || !("status" in account)
+        || (account.status !== "authenticated" && account.status !== "login_required")) {
+        const detail = account && typeof account === "object" && "result" in account
+            && account.result && typeof account.result === "object" && !Array.isArray(account.result)
+            ? account.result : {};
+        throw new CommandContractError("setup_status_unconfirmed", "device or account status is unconfirmed", "设备或账号状态尚未确认，本次准备未完成。保留现有身份，按返回的原因处理。", [], undefined, { failure_stage: "account_status", ...detail });
+    }
+    writeCommandEnvelope({ status: "setup_ready", result: {
+            cli_version: CLI_VERSION, backend_url: config.baseURL, agent_type: config.agentType,
+            device_status: "ready", account_status: account.status, skill_path: skillPath, skill_version: CLI_VERSION,
+        }, instruction: account.status === "authenticated"
+            ? "设备已准备好，已有账号授权可继续使用。读取并启用下方 Skill 后，按用户需求开始。"
+            : "设备已准备好。读取并启用下方 Skill 后即可开始；需要账号的功能会再请用户授权。",
+        next: null, recovery: [] }, options);
+}

package/dist/src/commands/skill.js

@@ -11,12 +11,20 @@ export function runSkillShow(name, options = {}) {
     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" }]);
     }
+    const original = packagedSkill();
     let content;
     try {
         content = readFileSync(findSkillPath(), "utf8");
     }
-    catch {
-        throw new Error("packaged skill is unavailable: itpay");
+    catch (error) {
+        if (process.env.ITPAY_CLI_SKILLS_DIR) {
+            const cause = error && typeof error === "object" && "code" in error ? String(error.code) : "read_failed";
+            throw new CommandContractError("skill_override_unavailable", "configured Skill cannot be read", "覆盖路径不可读取；当前包原文可用。直接读取 result.skill_path 并按宿主方式启用，不另装全局包。", [], undefined, { skill_path: original.path, cause_code: cause });
+        }
+        throw error;
+    }
+    if (content !== original.content) {
+        throw new CommandContractError("skill_override_mismatch", "configured Skill differs from the current package", "覆盖路径中的 Skill 不是当前包原文。直接读取 result.skill_path 并按宿主方式启用，不使用陈旧或改写内容。", [], undefined, { skill_path: original.path });
     }
     validateSkill(content);
     const agentType = options.agentType ?? declaredAgentType();
@@ -27,8 +35,8 @@ export function runSkillShow(name, options = {}) {
         result: { skill: ITPAY_SKILL, content },
         instruction: agentType
             ? agentType === "workbuddy"
-                ? "完整读取并遵守 Skill；按用户意图选择第一条命令。保持 workbuddy 和同一 CLI launcher，并为 ~/.itpay-v3 申请宿主允许的持久化权限；权限被拒时报告受阻操作，不删除 identity。"
-                : `完整读取并遵守 Skill；把自己视为服务用户的代理，先理解用户意图和解释用户权益，再选择购买、已购内容、订单或退款对应的第一条命令。当前 Agent Type 是 ${agentType}，后续命令保持不变。`
+                ? "完整读取原文并按宿主技能方式保存启用；按用户意图选择第一条业务命令。保持 workbuddy、同一入口和 Backend；只有实际持久化操作被拒时才沿宿主正式流程申请所需权限，拒绝后报告受阻操作，不删除 identity。"
+                : `完整读取原文并按宿主技能方式保存启用；把自己视为服务用户的代理，先理解用户意图和解释用户权益，再选择购买、已购内容、订单或退款对应的第一条命令。当前 Agent Type 是 ${agentType}，后续命令保持不变。`
             : "完整读取并遵守 Skill；先如实选择当前运行环境对应的 Agent Type。",
         next: agentType
             ? null
@@ -41,14 +49,23 @@ export function runSkillShow(name, options = {}) {
         plainResult: content.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n"),
     });
 }
-function findSkillPath() {
-    if (process.env.ITPAY_CLI_SKILLS_DIR) {
+export function packagedSkill() {
+    const path = findSkillPath(false);
+    const content = readFileSync(path, "utf8");
+    validateSkill(content);
+    return { path, content };
+}
+function findSkillPath(allowOverride = true) {
+    if (allowOverride && process.env.ITPAY_CLI_SKILLS_DIR) {
         const configuredRoot = resolve(process.env.ITPAY_CLI_SKILLS_DIR);
         const directPath = resolve(configuredRoot, "SKILL.md");
         if (existsSync(directPath))
             return directPath;
         return resolve(configuredRoot, ITPAY_SKILL, "SKILL.md");
     }
+    const bundlePath = resolve(commandDir, "skills", ITPAY_SKILL, "SKILL.md");
+    if (existsSync(bundlePath))
+        return bundlePath;
     const packagePath = resolve(commandDir, "..", "..", "..", "skills", ITPAY_SKILL, "SKILL.md");
     if (existsSync(packagePath))
         return packagePath;

package/dist/src/main.js

@@ -7,12 +7,13 @@ import { runServicesRun } from "./commands/services.js";
 // services/backend/internal/httpapi/handlers/*.go. Commands only
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
-import { BackendOverrideError, API_CONTRACT_REVISION, CLI_VERSION, cliDistribution, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
+import { BackendOverrideError, API_CONTRACT_REVISION, CLI_VERSION, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
 import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./state/device_authority.js";
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.js";
 import { HttpError } from "./client/http.js";
 import { HttpTransportError } from "./client/transport.js";
+import { runSetup, validateSetup } from "./commands/setup.js";
 import { runReadyz } from "./commands/readyz.js";
 import { runBuy } from "./commands/buy.js";
 import { runCatalogList } from "./commands/catalog.js";
@@ -39,9 +40,9 @@ program
     .version(CLI_VERSION)
     .addHelpText("after", `
 Agent quick start:
-  1. Run: itpay install --json
-  2. Select the real Agent Type and execute each returned next.command unchanged.
-  3. Read the packaged Skill, then route the human's natural-language intent.
+  1. Use one official package in the host's permitted persistent npm location.
+  2. Run: itpay setup --agent-type <actual_type> --json
+  3. Read and enable the returned same-package Skill before business commands.
 
 Common human intents:
   New service or query       catalog list
@@ -251,22 +252,9 @@ function docsErrorFallback(jsonOutput) {
         jsonOutput,
         code: "docs_unavailable",
         instruction: "内置文档缺失或损坏；通过当前分发方式恢复同版本 CLI 后重试。",
-        recovery: [distributionUpgradeAction(CLI_VERSION)],
+        recovery: [],
     };
 }
-function distributionUpgradeAction(version) {
-    switch (cliDistribution()) {
-        case "openclaw-skill-bundle":
-            return { command: "openclaw skills update itpay", reason: `更新包含 ItPay CLI ${version} 的 Skill bundle` };
-        case "kimi-plugin-bundle":
-            return {
-                command: "/plugins install https://github.com/itpay-ai/itpay-plugin-kimi-work",
-                reason: `更新包含 ItPay CLI ${version} 的 Kimi plugin`,
-            };
-        default:
-            return { command: `npm install -g @itpay/cli@${version}`, reason: "恢复当前 CLI 版本的完整安装包" };
-    }
-}
 program
     .command("readyz")
     .description("Probe the V3 backend readiness endpoint")
@@ -290,6 +278,20 @@ program
         });
     }
 });
+program.command("setup")
+    .description("Prepare this actual Agent and report device/account readiness without starting login")
+    .option("--json", "output JSON instead of terminal text")
+    .action(async (options) => {
+    try {
+        const config = loadConfig();
+        const skillPath = validateSetup(config.agentType);
+        await runSetup(newBackendClient(config), config, skillPath, { jsonOutput: Boolean(options.json) });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "setup_failed", initialization: true,
+            instruction: "准备未完成；保留现有身份，按返回的具体原因处理。", recovery: [] });
+    }
+});
 const authCmd = program.command("auth").description("Log in and bind this enrolled Agent to your ItPay account");
 for (const action of ["login", "status"]) {
     authCmd.command(action).option("--json", "output JSON").action(async (options) => {
@@ -444,7 +446,7 @@ skillCmd
             jsonOutput: Boolean(options.json),
             code: "skill_unavailable",
             instruction: "内置 Skill 缺失或损坏；通过当前分发方式恢复同版本 CLI 后重试。",
-            recovery: [distributionUpgradeAction(CLI_VERSION)],
+            recovery: [],
         });
     }
 });

package/dist/src/state/account_auth.js

@@ -33,8 +33,8 @@ export function sellerSessionToken(baseURL, env = process.env) {
 export function sellerAuth(action, baseURL, env = process.env, fetcher = fetch) {
     return accountAuth(action, baseURL, env, fetcher);
 }
-export function agentAuth(action, baseURL, backend, env = process.env, fetcher = fetch) {
-    return accountAuth(action, baseURL, env, fetcher, backend);
+export function agentAuth(action, baseURL, backend, env = process.env, fetcher = fetch, options = {}) {
+    return accountAuth(action, baseURL, env, fetcher, backend, options.readOnlyStatus === true && action === 'status');
 }
 // AUTH01: dashboard session stages stay distinct — the human must know exactly
 // what the official page still needs instead of a generic "pending".
@@ -141,12 +141,17 @@ function authenticatedEnvelope(env, phoneVerified) {
     }
     return { status: 'authenticated', result, instruction, next, recovery: [] };
 }
-async function accountAuth(action, baseURL, env, fetcher, backend) {
+async function accountAuth(action, baseURL, env, fetcher, backend, readOnlyStatus = false) {
     const purpose = backend ? 'agent-login' : 'seller';
     const command = backend ? 'itpay auth status' : 'itpay sell auth status';
     if (backend) {
         try {
             const current = await backend.agentAccountStatus();
+            if (current.status !== 'authenticated' && current.status !== 'login_required')
+                throw new Error('Unexpected account binding status');
+            // Preparation must not poll, bind or consume a saved browser authorization.
+            if (readOnlyStatus)
+                return { status: current.status, result: { bound: current.status === 'authenticated' }, instruction: '设备账号状态已读取。', next: null, recovery: [] };
             if (current.status === 'authenticated')
                 return authenticatedEnvelope(env, current.phone_verified === true);
         }
@@ -155,7 +160,7 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                 throw error;
             // AUTH03: even the binding-status probe can hit transport failure; the
             // truthful state is "unknown", never an implicit unbound or a fresh login.
-            return authStatusUnknown(read(baseURL, env, purpose)?.sessionID, error, "account_binding_probe");
+            return authStatusUnknown(readOnlyStatus ? undefined : read(baseURL, env, purpose)?.sessionID, error, "account_binding_probe");
         }
     }
     async function request(path, init = {}) {

package/dist/src/state/config.js

@@ -15,7 +15,7 @@ import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.1.45";
+export const CLI_VERSION = "2.1.46";
 export const API_CONTRACT_REVISION = "sha256:c1e1f459c1d3844f6eeae21535b532abb2e48c3e320173c4faccd62992890dcd";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/docs/agent/buyer/install-and-setup.json

@@ -4,42 +4,32 @@
   "product_scope": "itpay is the public CLI entry point for Buyer services and existing itpay sell Seller workflows.",
   "topic": "install-and-setup",
   "title": "Install And Identify The ItPay Agent Runtime",
-  "purpose": "Select the real Agent Type, verify one official Backend, and load the packaged Skill through one linear setup path.",
+  "purpose": "Install in one host-permitted persistent npm location, prepare the real Agent once, and enable the same-package Skill.",
   "when_to_use": [
     "The CLI is being installed or upgraded.",
     "The agent needs to confirm its stable runtime identity and default output Host."
   ],
   "commands": [
     {
-      "intent": "read this installed package Skill before network checks",
-      "command": "itpay skill show itpay --json",
-      "success_signal": "complete packaged Skill is read; the same version need not be read twice"
-    },
-    {
-      "intent": "list supported Agent Types",
+      "intent": "identify actual supported Agent Type if needed",
       "command": "itpay install --json",
-      "success_signal": "status is install_targets and exactly nine supported Agent Type definitions are returned"
+      "success_signal": "select actual agent_type without asking the human"
     },
     {
-      "intent": "read setup for the real runtime",
-      "command": "itpay install <agent_type> --json",
-      "success_signal": "status is instructions_ready and next is a readyz command using that exact Agent Type"
+      "intent": "prepare device and report authoritative account state",
+      "command": "itpay setup --agent-type <agent_type> --json",
+      "success_signal": "setup_ready with device_status ready and account_status authenticated or login_required; not proof Skill is enabled"
     },
     {
-      "intent": "verify the selected official Backend",
-      "command": "<execute the exact next.command returned by install>",
-      "success_signal": "ready proves Backend liveness only; retain the actual Agent Type and Backend, then verify device access"
-    },
-    {
-      "intent": "verify device access after Backend liveness",
-      "command": "itpay auth status --json",
-      "success_signal": "authenticated or successful login_required proves device access; pending/unknown is not ready"
+      "intent": "read and enable complete same-package Skill",
+      "command": "itpay skill show itpay --json",
+      "success_signal": "read original Skill and persist it using the host official skill mechanism; retain actual path/version"
     }
   ],
   "agent_rules": [
-    "For first setup, read the complete Skill from this installed package before network checks. Select the actual Agent Type once through install and retain the same launcher and Backend. Do not reread the same version Skill, repeat initialization for ordinary tasks, or start login or business to prove setup.",
-    "Run installation separately and preserve full output and its exit code. Nonzero stops preparation even if an older CLI runs. Same-version reuse requires verified executable, registry channel target, contract and official source; do not force or bypass host protection.",
-    "Report ItPay ready only after Backend and device checks succeed; otherwise preparation is incomplete. Account login is not required for setup.",
+    "Use standard npm with one host-permitted persistent tool location or global prefix. Fix the exact entry, actual Agent Type and Backend; do not change HOME/npm configuration or an existing project dependency. Do not use floating npx.",
+    "Run setup once after installation or upgrade, then read and enable the current package Skill before business. Same-version already-read/enabled Skill needs no repeat. No automatic login or business to prove setup.",
+    "Preserve actual npm error and nonzero exit. ENOTEMPTY is an old package/retirement directory conflict, not proof host policy forbids writes; broker wrappers do not establish the underlying cause. Stop repeated installation; only precisely authorized old-package cleanup, never identity deletion. setup_ready requires authoritative device/account checks; unknown/404/incompatibility is not ready.",
     "The current public setup link selects the channel and matching contract: latest/app for production, next/dev for beta. Do not let an old bundle or memory override this choice.",
     "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL the configured official test Backend only when explicitly requested; follow the CLI allowlist.",
     "If Backend compatibility cannot be verified, stop this round. minimum_cli_version is a protocol floor, not a verified matching artifact. Ask the maintainer for the matching distribution; do not guess a version or downgrade.",

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

@@ -8,7 +8,7 @@
 
 **上游：** 当前 npm CLI 或平台 bundle 已经可执行。
 
-**下游：** 先读取本包完整 Skill，使用真实 Agent Type 执行 `readyz`，再按返回的同 Backend/type 命令检查 `auth status`。authenticated 或成功 login_required 才证明设备访问可用；后者仍未登录，不自动发起授权或业务。
+**下游：** 使用真实 Agent Type 执行 `setup`，再读取并启用同包 Skill。authenticated 或成功 login_required 才证明设备访问可用；后者仍未登录，不自动发起授权或业务。
 
 ## 语法与参数
 
@@ -35,8 +35,8 @@ itpay install [target] [--json]
   },
   "instruction": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
   "next": {
-    "command": "itpay --agent-type codex-desktop readyz --json",
-    "reason": "验证当前官方 ItPay API 的可用性"
+    "command": "itpay --agent-type codex-desktop setup --json",
+    "reason": "准备当前宿主并确认设备与账号状态"
   },
   "recovery": [
     {
@@ -63,8 +63,8 @@ OpenClaw 额外明确没有默认入口：
   },
   "instruction": "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
   "next": {
-    "command": "itpay --agent-type openclaw readyz --json",
-    "reason": "验证当前官方 ItPay API 的可用性"
+    "command": "itpay --agent-type openclaw setup --json",
+    "reason": "准备当前宿主并确认设备与账号状态"
   },
   "recovery": [
     {
@@ -100,7 +100,7 @@ OpenClaw 额外明确没有默认入口：
       }
     ]
   },
-  "instruction": "识别当前真实运行平台，从 result.agent_types 选择对应 agent_type，并由 Agent 自行运行 itpay install <agent_type> --json；不要让用户运行命令，也不要临时更换 Agent Type。",
+  "instruction": "识别当前真实运行平台，从 result.agent_types 选择对应 agent_type，并由 Agent 自行运行 itpay setup --agent-type <agent_type> --json；不要让用户运行命令，也不要临时更换 Agent Type。",
   "next": null,
   "recovery": [
     {

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

@@ -7,7 +7,7 @@
 检查当前官方 Backend 是否可用。默认使用生产环境 `https://app.itpay.ai`；仅测试时可通过 `ITPAY_BACKEND_URL=https://sandbox.itpay.ai` 选择官方沙箱环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
 
 **上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 、`https://sandbox.itpay.ai` 或 `https://dev.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
-**下游：** 实际宿主已声明时，执行同 Backend/type 的 `auth status`；未声明时先 `install` 选择实际宿主。首次准备先读本包 Skill，同版本不重复读取。
+**下游：** 实际宿主已声明时，执行同 Backend/type 的 `setup`；未声明时先 `install` 识别实际宿主。setup 后读取并启用同包 Skill，同版本不重复读取。
 
 ## 语法与参数
 
@@ -25,8 +25,8 @@ itpay readyz [--json]
 {
   "status": "ready",
   "result": { "backend": "available", "backend_url": "https://app.itpay.ai", "environment": "production" },
-  "instruction": "ItPay 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；不自动登录或开始业务。",
-  "next": { "command": "itpay install --json", "reason": "选择实际宿主，再检查设备访问；尚未读本包 Skill 时先完整读取" },
+  "instruction": "ItPay 正式环境 https://app.itpay.ai 可用。只证明后端存活；首次使用或更新后运行 setup，不自动登录或开始业务。",
+  "next": { "command": "itpay install --json", "reason": "识别实际宿主类型后执行 setup" },
   "recovery": []
 }
 ```
@@ -37,8 +37,8 @@ itpay readyz [--json]
 {
   "status": "ready",
   "result": { "backend": "available", "backend_url": "https://sandbox.itpay.ai", "environment": "development" },
-  "instruction": "ItPay 开发环境 https://sandbox.itpay.ai 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；后续必须执行返回的完整命令并保持同一 Backend。",
-  "next": { "command": "ITPAY_BACKEND_URL=https://sandbox.itpay.ai itpay install --json", "reason": "选择实际宿主，再检查设备访问；尚未读本包 Skill 时先完整读取" },
+  "instruction": "ItPay 开发环境 https://sandbox.itpay.ai 可用。只证明后端存活；首次使用或更新后运行 setup，不自动登录或开始业务。",
+  "next": { "command": "ITPAY_BACKEND_URL=https://sandbox.itpay.ai itpay install --json", "reason": "识别实际宿主类型后执行 setup" },
   "recovery": []
 }
 ```
@@ -66,4 +66,4 @@ itpay readyz [--json]
 
 ## Agent Type / Host
 
-本命令不渲染 Host 内容。若已声明 Agent Type，`result.agent_type` 会确认该类型，且返回的 `auth status` 命令保留同一 `--agent-type` 与 Backend；未声明时返回 `install`。只有 authenticated 或成功 login_required 才证明设备可用，后者不代表已登录。权限拒绝或未知状态停止准备，不宣称 ready。
+本命令不渲染 Host 内容。若已声明 Agent Type，`result.agent_type` 会确认该类型，且返回的 `setup` 命令保留同一 `--agent-type` 与 Backend；未声明时返回 `install`。只有 authenticated 或成功 login_required 才证明设备可用，后者不代表已登录。权限拒绝或未知状态停止准备，不宣称 ready。

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

@@ -0,0 +1,13 @@
+# `itpay setup`
+
+Use the host's permitted persistent npm installation or a normal global install. Fix that exact executable for all commands; installation location does not change the device identity directory.
+
+```sh
+itpay setup --agent-type <actual_type> --json
+```
+
+Run once after installation or upgrade. Unsupported/missing type and unavailable same-package Skill fail before network access. This command reads authoritative device/account status using existing authentication; it does not install, launch login or run business commands.
+
+`setup_ready` returns `cli_version`, `backend_url`, `agent_type`, `device_status: ready`, `account_status: authenticated|login_required`, absolute `skill_path` and package-bound `skill_version`. `next` is null. Read the original Skill and enable it using the host mechanism before business; setup does not claim either happened. Repeated setup preserves identity and existing authorization. Account unknown, missing endpoint or incompatible Backend fails with nonzero exit and the actual reason.
+
+For testing set `ITPAY_BACKEND_URL=https://dev.itpay.ai` on every invocation; production defaults to app.itpay.ai. Do not switch environments to hide failure. `install`, `readyz` and `auth status` remain diagnostic/compatibility commands, not a required initialization chain.

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

@@ -48,3 +48,11 @@ Skill 不能默认把 Agent 引向 Catalog：用户可能要读取以前购买
 
 `workbuddy` 只在 instruction 中增加既有的本地权限要求；不改变输入、输出
 schema 或意图路由。
+
+## 同包启用
+
+setup 返回当前包的绝对 Skill 路径；完整读取原文，按宿主正式技能安装方式保存启用。同版本已读且启用时无需重复保存；宿主不支持持久发现时记录准确路径与限制，不声称跨会话自动发现已验证。
+
+兼容 `ITPAY_CLI_SKILLS_DIR` 的直接/父目录路径，但其内容必须与当前包原文完全一致。陈旧或改写内容返回非0 `skill_override_mismatch`，给出同包 `result.skill_path` 供直接读取，不宣称已启用。缺包/文档错误只指向原安装方式，不生成会另装全局包的恢复命令。
+
+覆盖路径不可读但原包有效时，返回 `skill_override_unavailable` 和实际读取原因、同包路径；不会把它误报为包损坏或建议另装全局包。

package/docs/cli-reference/index.md

@@ -20,7 +20,7 @@
 itpay [--agent-type <agent_type>] [--version] [--help]
 ```
 
-不带子命令时显示帮助并退出，不访问 Backend、不读取或修改业务状态。`--version` 只输出当前 CLI 版本；`--help` 只输出命令树。全局 `--agent-type` 必须放在子命令前，并由每个返回的 ItPay `next.command` / `recovery.command` 原样保留其规范值。
+不带子命令时显示帮助并退出，不访问 Backend、不读取或修改业务状态。`--version` 只输出当前 CLI 版本；`--help` 只输出命令树。`--agent-type` 可置于子命令前或 setup 参数中，并由每个返回的 ItPay `next.command` / `recovery.command` 原样保留其规范值。
 
 Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcommand]` 只显示对应帮助，语义等同于在目标命令上使用 `--help`；它们不访问 Backend、不读写本地业务状态，也没有 JSON 输出合同。
 
@@ -28,6 +28,8 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
 
 ### 环境与发现
 
+- [`itpay setup`](commands/setup.md) - 一次准备设备并单独报告账号状态
+
 - [`itpay readyz`](commands/readyz.md) - 检查后端是否可用
 - [`itpay next`](commands/next.md) - 从本地保存的服务端句柄恢复下一步
 - [`itpay catalog`](commands/catalog/index.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.45",
+  "version": "2.1.46",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
@@ -83,5 +83,5 @@
     "qrcode",
     "zod"
   ],
-  "gitHead": "b4fdf3aea1cac3db41a3b369102a3383f6455b1e"
+  "gitHead": "f36dd8f312628558aaff7e293348c508ed467664"
 }

package/skills/itpay/SKILL.md

@@ -14,9 +14,11 @@ human the useful result or action, not the internal steps.
 
 ## Installation readiness
 
-The current setup link chooses the channel: production is latest/app; beta is next/dev. Keep this choice even if old memory or a bundled CLI suggests another version. Run any installation separately, read its full output and preserve its exit code; a failed installation ends preparation even when an old CLI still runs. Reuse requires verified executable, current channel version, contract and official package source. Do not force installation or bypass host protection.
+使用宿主允许的持久安装方式运行官方 ItPay CLI，不要求全局安装。固定本次安装的入口、实际 Agent Type 和 Backend。首次使用或更新后运行 setup；setup_ready 证明设备准备完成，账号授权状态单独列出。完整读取当前包 Skill，并按宿主方式保存启用；同版本已读且已启用时无需重复。业务请求需要真人授权时使用返回的官方入口，不以安装授权代替购买同意。安装位置变化不要求清除设备身份。
 
-Read this installed package Skill before network checks. Select the actual Agent Type from `itpay install --json` and retain the same executable and Backend. readyz proves liveness only; after success, `itpay auth status --json` checks device access and binding. A successful authenticated or login_required response proves the device request worked; login_required does not require login during setup. Preserve any existing authorization. Unknown, missing-command, compatibility or exhausted network checks end this round without guessing commands/versions or reporting ready. minimum_cli_version is a protocol floor, not a verified artifact recommendation. Do not use services, orders or paid operations to prove installation. Already read same-version Skill needs no repeat.
+The public setup link selects latest/app for production or next/dev for testing. Use standard npm in the host's permitted persistent tool location or global prefix; choose one location and keep the verified entry for every returned command. Do not use floating npx, change HOME/npm configuration, modify an existing project's dependencies, or bypass protection. Preserve npm's actual output and exit status; failed installation is not ready even when an older executable runs.
+
+Run `itpay setup --agent-type <actual_type> --json` once after installation or upgrade. Read and enable this exact package Skill before business commands. If the host cannot persist or discover a Skill, record its accurate persistent path and that limitation; do not claim it has been enabled. No repeated install/readyz/auth sequence is needed for ordinary tasks. Unknown, incompatible, or unavailable device/account status stops preparation; preserve identity and report the actual cause. Do not start login or business merely to prove readiness.
 
 ## Choose one entry