@itpay/cli 2.1.18 → 2.1.22

package/dist/src/commands/skill.js

@@ -24,7 +24,7 @@ export function runSkillShow(name, options = {}) {
         result: { skill: ITPAY_SKILL, content },
         instruction: agentType
             ? agentType === "workbuddy"
-                ? "完整读取并遵守 Skill；把自己视为服务用户的代理，先理解用户要购买新服务、查看已购内容、查询订单还是处理退款，并先解释用户权益，再选择对应的第一条命令。保持 workbuddy 和同一 Node/CLI launcher。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。"
+                ? "完整读取并遵守 Skill；按用户意图选择第一条命令。保持 workbuddy 和同一 CLI launcher，并为 ~/.itpay-v3 申请宿主允许的持久化权限；权限被拒时报告受阻操作，不删除 identity。"
                 : `完整读取并遵守 Skill；把自己视为服务用户的代理，先理解用户意图和解释用户权益，再选择购买、已购内容、订单或退款对应的第一条命令。当前 Agent Type 是 ${agentType}，后续命令保持不变。`
             : "完整读取并遵守 Skill；先如实选择当前运行环境对应的 Agent Type。",
         next: agentType

package/dist/src/main.js

@@ -7,7 +7,7 @@ import { runServicesRun } from "./commands/services.js";
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
 import { BackendOverrideError, CLI_VERSION, cliDistribution, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
-import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./state/device_authority.js";
+import { DeviceAuthority, DeviceAuthorizationError, DeviceLockBusyError, 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";
@@ -116,6 +116,7 @@ function reportCLIError(error, contract) {
     const backendOverrideError = error instanceof BackendOverrideError ? error : undefined;
     const deviceError = error instanceof DeviceAuthorizationError ? error : undefined;
     const stateError = error instanceof DeviceStateError ? error : undefined;
+    const lockError = error instanceof DeviceLockBusyError ? error : undefined;
     const transportError = error instanceof HttpTransportError ? error : undefined;
     const httpRecovery = errorRecoveryActions(error).map((action) => ({
         command: action.command,
@@ -154,24 +155,30 @@ function reportCLIError(error, contract) {
             command: "itpay skill show itpay --json",
             reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
         }] : [];
+    const lockRecovery = lockError ? [{
+            command: "itpay device repair-lock --json",
+            reason: "检查锁持有者；只回收已退出进程留下的锁，不改变设备身份",
+        }] : [];
     const authorizationInstruction = stateError
         ? "当前运行环境无法写入 owner-only Device 状态；请保持同一 Node、CLI 和 Agent Type，在允许持久写入 ~/.itpay-v3 的执行环境中重试。不要手工创建 lock、删除 identity 或换运行时碰运气。"
-        : error instanceof HttpError && error.code === "agent_device_session_required"
-            ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
-            : deviceError?.code === "agent_device_revoked"
-                ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
-                : deviceKeyResettable && deviceError?.status === 500
-                    ? "服务端未能完成设备登记。先原样重试一次原命令：服务端会把已登记的同一公钥幂等挂回原设备。若仍返回 internal_error（Backend 未含该修复），执行 itpay device reset-key --confirm-key-reset 生成全新密钥后重试。"
-                    : deviceKeyResettable
-                        ? "服务端记录显示当前设备私钥已不再有效（已轮换或与既有登记冲突）。执行 itpay device reset-key --confirm-key-reset 生成全新密钥并重新登记。"
-                        : deviceError
-                            ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
-                            : undefined;
-    if (contract || commandError || backendOverrideError) {
+        : lockError
+            ? "另一个进程仍在更新本地身份。执行 recovery 检查；若持有者仍活跃，等待后继续原任务，不要删除锁或重建身份。"
+            : error instanceof HttpError && error.code === "agent_device_session_required"
+                ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
+                : deviceError?.code === "agent_device_revoked"
+                    ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
+                    : deviceKeyResettable && deviceError?.status === 500
+                        ? "服务端未能完成设备登记。先原样重试一次原命令：服务端会把已登记的同一公钥幂等挂回原设备。若仍返回 internal_error（Backend 未含该修复），执行 itpay device reset-key --confirm-key-reset 生成全新密钥后重试。"
+                        : deviceKeyResettable
+                            ? "服务端记录显示当前设备私钥已不再有效（已轮换或与既有登记冲突）。执行 itpay device reset-key --confirm-key-reset 生成全新密钥并重新登记。"
+                            : deviceError
+                                ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
+                                : undefined;
+    if (contract || commandError || backendOverrideError || lockError || stateError) {
         writeCommandEnvelope({
             status: "error",
             error: {
-                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
+                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? lockError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
             ...(requiredCLIVersion ? {
@@ -219,7 +226,7 @@ function reportCLIError(error, contract) {
                                                     ? "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。"
                                                     : "网络在完整响应前中断；当前写操作没有安全重放合同，因此 CLI 未自动重试。按 recovery 查询权威状态；不要原样重放或创建替代 Checkout、Execution、Payment 或 Refund。"
                                                 : backendOverrideError
-                                                    ? "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://sandbox.itpay.ai。"
+                                                    ? "移除 ITPAY_BACKEND_URL 使用正式环境，或按当前测试目标准确设置为 https://sandbox.itpay.ai 或 https://dev.itpay.ai。不要通过切换环境规避当前错误。"
                                                     : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
             recovery: incompatible
@@ -228,9 +235,9 @@ function reportCLIError(error, contract) {
                     : []
                 : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
                     ? []
-                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : lockError ? lockRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
-            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError ? { jsonOutput: process.argv.includes("--json") } : {}),
+            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError || lockError || stateError ? { jsonOutput: process.argv.includes("--json") } : {}),
             output: (text) => { process.stderr.write(text); },
         });
         process.exitCode = 1;
@@ -331,6 +338,30 @@ for (const action of ["login", "status"]) {
 }
 // --- device ---------------------------------------------------------------
 const deviceCmd = program.command("device").description("Recover the current official Backend registration after an operator-confirmed reset");
+deviceCmd
+    .command("repair-lock")
+    .description("Safely inspect and recover a local Device identity lock left by an exited process")
+    .option("--json", "output JSON instead of terminal text")
+    .action((options) => {
+    try {
+        const config = loadConfig();
+        const status = new DeviceAuthority({
+            baseURL: config.baseURL,
+            ...(config.agentType ? { requestedAgentType: config.agentType } : {}),
+            compatibilityHeaders: {},
+        }).repairLock();
+        writeCommandEnvelope({
+            status: status === "recovered" ? "device_lock_recovered" : status === "active" ? "device_lock_active" : "device_lock_absent",
+            result: { lock_status: status, device_identity_preserved: true },
+            instruction: status === "active" ? "本地身份正由存活进程更新；稍后继续原任务。" : "本地锁无需进一步处理；继续原任务。",
+            next: null,
+            recovery: [],
+        }, { jsonOutput: Boolean(options.json), plainResult: [`lock: ${status}`, "device_identity: preserved"] });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "device_lock_repair_failed", instruction: "本地锁无法安全检查；保留设备身份并联系维护者。" });
+    }
+});
 deviceCmd
     .command("recover")
     .description("Forget only the current official Backend registration while preserving the local private key")
@@ -1382,7 +1413,7 @@ services
     .argument("<result_item_id>")
     .option("--offset <offset>", "zero-based candidate offset", Number, 0)
     .option("--cursor <cursor>", "opaque v2 page cursor (rcur_<offset>); takes precedence over --offset")
-    .option("--limit <limit>", "page size (1-20)", Number, 5)
+    .option("--limit <limit>", "page size (1-20)", Number, 20)
     .option("--json", "output JSON")
     .action(async (serviceExecutionID, resultItemID, options) => {
     const config = loadConfig();
@@ -1634,12 +1665,16 @@ services
     .description("Show the next recommended agent action for a Service Execution")
     .argument("<service_execution_id>")
     .option("--since-snapshot <snapshot_id>", "delta read: suppress the journey payload when unchanged")
+    .option("--timeout <seconds>", "wait up to 120 seconds for a useful result on this execution", (value) => Number(value))
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesNext(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), sinceSnapshot: options.sinceSnapshot });
+        if (options.timeout !== undefined && (!Number.isInteger(options.timeout) || options.timeout < 0 || options.timeout > 120)) {
+            throw new Error("--timeout must be an integer from 0 to 120");
+        }
+        await runServicesNext(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), sinceSnapshot: options.sinceSnapshot, timeoutSeconds: options.timeout });
     }
     catch (error) {
         reportCLIError(error, {

package/dist/src/render/markdown.js

@@ -24,9 +24,6 @@ export function buildAgentChatHandoff(plan) {
     if (plan.orderItems?.length) {
         lines.push(`项目：${plan.orderItems.map((item) => `${item.title} x${item.quantity}`).join("、")}`);
     }
-    if (plan.afterActionCommand) {
-        lines.push("", `付款后查询：\`${plan.afterActionCommand}\``);
-    }
     return {
         type: "send_payment_handoff",
         must_send_to_user: true,

package/dist/src/state/account_auth.js

@@ -200,9 +200,13 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                 }
                 catch (error) {
                     if (error instanceof AuthRequestError && (error.httpStatus === 404 || error.httpStatus === 410)) {
-                        return sessionGone(env, purpose, baseURL, open.sessionID);
+                        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+                        // The explicit login call may open one fresh session now. Status
+                        // remains read-only and still reports the missing old session.
+                    }
+                    else {
+                        return authStatusUnknown(open.sessionID);
                     }
-                    return authStatusUnknown(open.sessionID);
                 }
             }
         }

package/dist/src/state/cart_session.js

@@ -55,9 +55,12 @@ export class CartSession {
             ...(this.state.lastDisplayToken ? { lastDisplayToken: this.state.lastDisplayToken } : {}),
             ...(this.state.lastCheckoutURL ? { lastCheckoutURL: this.state.lastCheckoutURL } : {}),
         };
+        const contents = JSON.stringify(toSave, null, 2);
+        if (existsSync(path) && readFileSync(path, "utf-8") === contents)
+            return;
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
-        writeFileSync(temporary, JSON.stringify(toSave, null, 2), { encoding: "utf-8", mode: 0o600 });
+        writeFileSync(temporary, contents, { encoding: "utf-8", mode: 0o600 });
         chmodSync(temporary, 0o600);
         renameSync(temporary, path);
         chmodSync(path, 0o600);

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.18";
+export const CLI_VERSION = "2.1.22";
 export const API_CONTRACT_REVISION = "sha256:2f9fbcdc5cd0630910abb52671304cc019e348e9a778017ec92ddc3513b3639f";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/dist/src/state/device_authority.js

@@ -43,12 +43,25 @@ export class DeviceAuthority {
     }
     async ensureAuthorization() {
         if (!this.pending) {
-            this.pending = withFileLock(`${this.statePath}.lock`, () => this.prepareAuthorization()).finally(() => {
+            this.pending = this.cachedAuthorization() ?? withFileLock(`${this.statePath}.lock`, () => this.prepareAuthorization());
+            this.pending = this.pending.finally(() => {
                 this.pending = undefined;
             });
         }
         return this.pending;
     }
+    cachedAuthorization() {
+        const agentType = this.requestedAgentType;
+        if (!agentType)
+            return undefined;
+        const state = this.readState();
+        const registration = state?.registrations[this.backendKey];
+        const session = registration?.sessions[agentType];
+        if (!registration?.agentInstances[agentType] || !session || Date.parse(session.expiresAt) <= Date.now() + 60_000)
+            return undefined;
+        const privateKey = this.readPrivateKey();
+        return privateKey ? Promise.resolve({ state: registration, agentType, session, privateKey }) : undefined;
+    }
     async recoverAuthorization() {
         await withFileLock(`${this.statePath}.lock`, async () => {
             const state = this.readState();
@@ -61,6 +74,9 @@ export class DeviceAuthority {
             this.writeState(state);
         });
     }
+    repairLock() {
+        return inspectAndRecoverLock(`${this.statePath}.lock`);
+    }
     async recoverBackendReset() {
         return withFileLock(`${this.statePath}.lock`, async () => {
             const state = this.readState();
@@ -236,6 +252,7 @@ export class DeviceAuthority {
             method: "POST",
             headers: { "Content-Type": "application/json", Accept: "application/json", ...this.compatibilityHeaders, ...extraHeaders },
             body,
+            signal: AbortSignal.timeout(15_000),
         });
         const payload = await response.json().catch(() => ({}));
         if (!response.ok)
@@ -300,6 +317,13 @@ export class DeviceStateError extends Error {
         this.name = "DeviceStateError";
     }
 }
+export class DeviceLockBusyError extends Error {
+    code = "device_lock_busy";
+    constructor() {
+        super("ItPay device identity is being updated by another process");
+        this.name = "DeviceLockBusyError";
+    }
+}
 function emptyDeviceState() {
     return { schemaVersion: "itpay.device.v2", registrations: {} };
 }
@@ -344,9 +368,9 @@ async function withFileLock(path, run) {
     catch (error) {
         throw asDeviceStatePathError(error, "prepare_lock") ?? error;
     }
-    const ownerToken = randomUUID();
+    const ownerToken = `${process.pid}:${randomUUID()}`;
     let acquired = false;
-    for (let attempt = 0; attempt < 200; attempt += 1) {
+    for (let attempt = 0; attempt < 800; attempt += 1) {
         try {
             writeFileSync(path, ownerToken, { encoding: "utf8", flag: "wx", mode: 0o600 });
             chmodSync(path, 0o600);
@@ -357,20 +381,12 @@ async function withFileLock(path, run) {
             const code = error.code;
             if (code !== "EEXIST")
                 throw asDeviceStateError(error, "acquire_lock") ?? error;
-            try {
-                if (Date.now() - statSync(path).mtimeMs > 30_000)
-                    moveLockAside(path, "stale", "remove_stale_lock");
-            }
-            catch (statError) {
-                if (statError.code !== "ENOENT") {
-                    throw asDeviceStateError(statError, "inspect_lock") ?? statError;
-                }
-            }
+            inspectAndRecoverLock(path);
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
     if (!acquired)
-        throw new Error("timed out waiting for ItPay device identity lock");
+        throw new DeviceLockBusyError();
     try {
         return await run();
     }
@@ -378,6 +394,46 @@ async function withFileLock(path, run) {
         releaseLock(path, ownerToken);
     }
 }
+function inspectAndRecoverLock(path) {
+    let token;
+    let age;
+    try {
+        const lockStat = statSync(path);
+        age = Date.now() - lockStat.mtimeMs;
+        token = lockStat.isDirectory() ? "" : readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "absent";
+        throw asDeviceStateError(error, "inspect_lock") ?? error;
+    }
+    const ownerPID = /^(\d+):[0-9a-f-]+$/.exec(token)?.[1];
+    if (ownerPID) {
+        try {
+            process.kill(Number(ownerPID), 0);
+            return "active";
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                return "active";
+        }
+    }
+    else if (age <= 30_000) {
+        return "active";
+    }
+    // Recheck the exact owner before moving the lock; another process may have renewed it.
+    try {
+        if (token ? readFileSync(path, "utf8") !== token : !statSync(path).isDirectory())
+            return "active";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "absent";
+        throw asDeviceStateError(error, "inspect_lock") ?? error;
+    }
+    moveLockAside(path, "stale", "remove_stale_lock");
+    return "recovered";
+}
 function releaseLock(path, ownerToken) {
     try {
         if (readFileSync(path, "utf8") !== ownerToken)

package/dist/src/state/task_journal.js

@@ -45,6 +45,8 @@ export class TaskJournal {
     observe(serviceExecutionID, stage, resumeCommand) {
         const file = this.readFile();
         const existing = file.tasks[serviceExecutionID];
+        if (existing && existing.stage === stage && (resumeCommand === undefined || existing.resume_command === resumeCommand))
+            return;
         file.tasks[serviceExecutionID] = {
             service_execution_id: serviceExecutionID,
             ...(existing?.service_id ? { service_id: existing.service_id } : {}),

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

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "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.",
@@ -32,11 +32,12 @@
     }
   ],
   "agent_rules": [
-    "The Backend Cart is business truth; ~/.itpay-v3/cart.json only stores local recovery handles and explicit drafts.",
+    "The Backend Cart is business truth; the current backend-isolated local cart state file only stores local recovery handles and explicit drafts.",
     "Run the exact next.command returned by the CLI. Do not extract or invent a capability from a raw list.",
-    "One service intent uses one Service Execution. Start another execution for another independent intent.",
+    "Railway query and booking use distinct Service Executions for one purchase journey. Start another execution for an independent intent.",
     "Ask for email only when the selected capability requires protected delivery; never invent contact data.",
-    "A lost Checkout response is retried with the same Cart and persisted idempotency operation."
+    "A lost Checkout response is retried with the same Cart and persisted idempotency operation.",
+    "A single railway service checkout normally follows its booking execution; Cart is used only when the returned flow calls for it."
   ],
   "forbidden": [
     "Do not call ordinary buy for a service-backed Cart line.",

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

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "catalog-list",
   "title": "Browse ItPay V3 Service Catalog",
   "purpose": "Explain available services, outcomes, conditions, and prices in human language without exposing catalog identifiers.",
@@ -20,7 +20,8 @@
     "item_format": "Explain the title, what the human receives, any auxiliary discovery step, and the published price.",
     "service_flow": "Explain discovery as an auxiliary identity-confirmation step, including free quota and paid continuation. Present primary_service as the actual paid outcome. Read all values from the manifest.",
     "variant_selection": "Internal IDs are for the Agent's next command only and are never shown or requested from the human.",
-    "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically."
+    "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically.",
+    "railway": "Railway entries point to itpay docs show rail-booking --json; use its query and booking contracts instead of a generic start→invoke→cart sequence."
   },
   "agent_rules": [
     "Use catalog list only when the human asks for a new service, not when they want an earlier purchase.",
@@ -28,15 +29,32 @@
     "Explain the customer journey from service_flow instead of presenting every variant as an unrelated service.",
     "State free quota, paid continuation price, email requirement, and claim purpose exactly as published; do not exaggerate or omit conditions.",
     "Ask the human to choose only when multiple services could satisfy the goal; never make them choose an internal variant or offer ID.",
-    "After services start, submit service keywords only through the returned capability command's --input key=value options; --target is never a search keyword."
+    "Use each service’s returned input contract; railway planning and booking follow rail-booking, not a universal Cart route."
   ],
   "human_language": {
-    "prefer": ["服务", "查询", "报告", "免费次数", "价格", "你会得到什么"],
-    "avoid": ["service_id", "variant_id", "offer_id", "capability", "manifest"]
+    "prefer": [
+      "服务",
+      "查询",
+      "报告",
+      "免费次数",
+      "价格",
+      "你会得到什么"
+    ],
+    "avoid": [
+      "service_id",
+      "variant_id",
+      "offer_id",
+      "capability",
+      "manifest"
+    ]
   },
   "next_docs": [
     {
-      "condition": "Buyer selected a service and wants to purchase",
+      "condition": "Railway service selected",
+      "topic": "rail-booking"
+    },
+    {
+      "condition": "Non-rail Buyer selected a service and wants to purchase",
       "topic": "cart-checkout",
       "file": "docs/agent/buyer/cart-checkout.json"
     }

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

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "identity-and-sessions",
   "title": "Device Identity And Session Recovery",
   "purpose": "Explain stable local identity, official Backend-scoped registrations, Agent Type instances, and bounded automatic session recovery.",
@@ -12,7 +12,7 @@
   ],
   "identity_model": {
     "local_key": "One owner-only Ed25519 private key for the local installation.",
-    "backend_registration": "One registration per official Backend: app.itpay.ai by default and sandbox.itpay.ai only with the exact test override.",
+    "backend_registration": "One registration per configured official Backend. Follow the current CLI backend allowlist; do not switch to evade failures.",
     "agent_instance": "One instance per agent_type under each Backend registration; same-type windows and chats reuse it.",
     "presentation": "Host and target route output only and never identify the Agent or provide business input."
   },
@@ -26,10 +26,10 @@
     "Re-enrolling a public key the Backend already holds re-attaches to the existing device and quota lineage after proof-of-possession; it never creates a duplicate device. If enrollment verification keeps failing with internal_error, or returns agent_device_key_rotated or agent_device_key_conflict, `itpay device reset-key --confirm-key-reset` is the supported way to start over with a fresh key."
   ],
   "local_state_recovery": [
-    "Device state updates use an atomic directory lock and owner-only atomic file replacement; no lock file is opened with fs.open or fs.openSync.",
+    "Device state uses an owner-only atomic file replacement and a lock that the CLI can inspect. On a stale lock, run the returned device repair-lock command; it only reclaims a proven stale owner.",
     "Operation idempotency uses one immutable owner-only record per operation key. Different commands and Agent processes do not share a global operation-journal lock; legacy operations.json is read only.",
     "On device_state_unwritable, use the reported operation and errno to diagnose the failing stage without exposing local paths; keep the same Agent Type and CLI/Node launcher, restore Host-approved persistent access to ~/.itpay-v3, then retry the original command.",
-    "Do not manually create or delete state locks, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
+    "Do not delete a live lock, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
   ],
   "commands": [
     {
@@ -51,19 +51,24 @@
       "intent": "abandon the local device key after the Backend refuses to complete enrollment with it (persistent internal_error, agent_device_key_rotated, or agent_device_key_conflict)",
       "command": "itpay device reset-key --confirm-key-reset --json",
       "success_signal": "the local private key is discarded and the next command enrolls as a brand-new device"
+    },
+    {
+      "intent": "repair only a proven stale local device lock",
+      "command": "itpay device repair-lock --json",
+      "success_signal": "the CLI reports whether the lock was stale and reclaimed; an active owner stays protected"
     }
   ],
   "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 production traffic to use https://app.itpay.ai. Use https://sandbox.itpay.ai only for an explicit test and keep the complete returned Backend-prefixed command for that entire flow.",
+    "Production defaults to https://app.itpay.ai; explicit sandbox or dev testing uses https://sandbox.itpay.ai or https://dev.itpay.ai. Keep the complete returned Backend-prefixed command for that flow.",
     "After automatic recovery fails, stop and report the exact code, selected official Backend, 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 redirect the CLI to dev, local, an IP, or any custom Backend; only the exact official sandbox.itpay.ai test override is allowed.",
+    "Do not switch Backend to evade a failure. Allowed public URLs are app.itpay.ai, sandbox.itpay.ai and dev.itpay.ai; local loopback requires the explicit CLI development flag.",
     "Do not use --target as identity or service input."
   ],
   "next_docs": [
@@ -93,10 +98,10 @@
   ],
   "auth_session_states": {
     "stages": "The CLI now reports the auth session stage exactly as the server returns it: waiting_provider (show the handoff and wait), email_verification_required (the human must verify the emailed code on the auth page), merge_confirmation_required (an existing account matches — the human must confirm the merge on the auth page), provider_pending/pending (generic wait), completed (session done — bind it, do not restart).",
-    "terminal_states": "auth_expired/auth_denied/auth_cancelled/auth_failed mean this session is over; say so plainly and start a NEW session only if the human still wants in — never keep polling a dead one.",
-    "transport_unknown": "auth_session_unknown means a network error while polling — the outcome is unknown. Keep waiting on the SAME session (it may still complete); do NOT restart auth, and do not assume denial.",
-    "missing": "auth_session_not_found means the cached session is gone server-side; start a new login.",
-    "completed_resume": "When login completes, itpay auth login resumes the remembered pending service execution automatically when one exists — you do not need to find it yourself.",
+    "terminal_states": "auth_expired/auth_denied/auth_cancelled/auth_failed mean this session is over; say so plainly and respect denial or cancellation. Start a new session only on an explicit login request; never keep polling a dead one.",
+    "transport_unknown": "auth_status_unknown means a network error while polling — the outcome is unknown. Keep waiting on the SAME session (it may still complete); do NOT restart auth, and do not assume denial.",
+    "missing": "auth_session_missing means the cached session is gone. An explicit auth login opens one fresh official session in that call; auth status stays read-only.",
+    "completed_resume": "After login completes, execute the returned command to resume the same paused service execution. Login does not silently run that command.",
     "path_b": "A buyer who reaches checkout without a login completes identity inside the protected checkout page; never force a separate itpay auth login first."
   }
 }

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

@@ -1,7 +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.",
+  "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.",
@@ -32,23 +32,24 @@
     }
   ],
   "agent_rules": [
-    "Start with install, identify the current real runtime from result.agent_types, run itpay install <agent_type> --json yourself, and then execute each returned next.command unchanged until the Skill is loaded.",
+    "For first setup or a runtime change, identify the real Agent Type once, run itpay install <agent_type> --json yourself, and follow its setup continuation until the packaged Skill is loaded. Ordinary service requests start from the Skill's service command, without repeating install or readyz.",
     "After setup, tell the human only that ItPay is ready; never ask them to run setup commands or explain technical setup steps.",
     "Use the CLI distribution already provided by the current npm package, Skill, or plugin; update only through that distribution's own instructions.",
-    "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL https://sandbox.itpay.ai; no other Backend is allowed.",
+    "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_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and use only the exact distribution-specific update recovery returned by the CLI; never replace its version with latest.",
     "After upgrading, require itpay --version to equal result.required_cli_version before running readyz again; never change Agent Type or Device identity to recover compatibility.",
     "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, doubao-work, kimi-code, or openclaw.",
     "For compatibility, a global --agent-type codex declaration is normalized immediately to codex-desktop; all registration, output, and returned commands use codex-desktop. Never generate the alias, and do not use codex as an install target.",
-    "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai and sandbox.itpay.ai.",
+    "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai, sandbox.itpay.ai and dev.itpay.ai.",
     "Within each official Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
     "Agent Type identifies the runtime. Host and target only select a presentation destination; load render-hosts only when a handoff cannot be shown.",
     "Keep the exact Agent Type in every next or recovery command; do not fall back to a type previously used by another runtime.",
-    "Do not change Agent Type or rotate local identity to reset quota or recover a failed command."
+    "Do not change Agent Type or rotate local identity to reset quota or recover a failed command.",
+    "Skillhub and local host bundles are separate installed artifacts; verify their version and packaged Skill/docs instead of assuming an npm update changed them."
   ],
   "forbidden": [
     "Do not use terminal, claude-code, or plain-chat as Agent Types. Do not generate codex as an Agent Type; it is accepted only as a legacy global declaration and becomes codex-desktop before any request.",
-    "Do not set or suggest any Backend except the default https://app.itpay.ai or the exact test override https://sandbox.itpay.ai.",
+    "Do not set or suggest a Backend outside the CLI allowlist: https://app.itpay.ai, https://sandbox.itpay.ai, https://dev.itpay.ai; local loopback requires the CLI development flag. Do not switch Backend to evade a failure.",
     "Do not claim that install writes host configuration or registers a device; it only prints instructions.",
     "Do not create a new identity for a different window, task, chat, or process of the same Agent Type."
   ],

package/docs/agent/buyer/orders-refunds.json

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "orders-refunds",
   "title": "Order, Delivery, Customer Care And Refund Recovery",
   "purpose": "Explain paid-order and delivery problems to the human, then read or manage the same owned Order without guessing payment, consumption, or refund state.",
@@ -34,16 +34,16 @@
     {
       "intent": "cancel before provider submission",
       "command": "itpay --agent-type <agent_type> refund cancel <refund_request_id> --json",
-      "success_signal": "the Refund Owner cancels the request and requires a new delivery authorization"
+      "success_signal": "the Refund Owner returns the current cancellation and access state; old grants do not revive"
     }
   ],
   "agent_rules": [
     "Act as the human's ItPay service representative: explain payment, delivery, access, and refund facts in plain language before giving the next action.",
     "After verified payment, say the Order is recorded and the human must not pay again. Recover that same Order or Service Execution if delivery is delayed or fails.",
     "ItPay derives payment, amount, currency, account ownership, and refund policy from the owned order; explain only their user-facing meaning.",
-    "Unconsumed delivery normally follows the automatic policy; consumed delivery normally requires manual review. These are policy routes, not promises of a successful or instant refund.",
+    "Read this order’s current refund policy. Railway return depends on supplier ticket facts and may require manual review; platform refund status alone does not prove a train ticket was returned.",
     "A refund request freezes all delivery paths and revokes existing grants immediately.",
-    "Cancellation or rejection restores eligibility but never reactivates an old grant.",
+    "Cancellation or rejection follows the returned order policy and never reactivates an old grant automatically.",
     "Use get or watch after interruption; do not infer success from elapsed time.",
     "Never switch CLI/MCP lanes or identities to recover an order or refund error.",
     "A read-only MCP Agent may explain policy and order facts, but directs refund actions to the ItPay Dashboard or a full Local CLI Agent."