@itpay/cli 2.1.22 → 2.1.33

package/dist/src/commands/vault.js

@@ -1,7 +1,7 @@
 import { HttpError } from "../client/http.js";
-import { requiresTarget } from "../state/client_context.js";
+import { requiresTarget, validateContext } from "../state/client_context.js";
 import { formatMoney } from "../render/output.js";
-import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+import { CommandContractError, shellArgument, writeCommandEnvelope } from "./guidance.js";
 import { buildVaultHandoff } from "./vault_handoff.js";
 function outputOptions(options, plainResult) {
     return {
@@ -19,21 +19,21 @@ export async function runVaultList(backend, input) {
         const value = await backend.listBuyerVaultArtifacts(input);
         writeCommandEnvelope({
             status: value.items.length ? "vault_listed" : "no_vault_artifacts",
-            result: { items: value.items, next_cursor: value.next_cursor || null },
+            result: { items: value.items.map(item => ({ ...item, amount: formatMoney(item.amount_minor, item.currency), reader: { command: vaultReadCommand(item.artifact_ref, [], input), reason: "读取这一已购内容" } })), next_cursor: value.next_cursor || null },
             instruction: value.items.length
-                ? "用编号、服务名称、内容主体、购买时间、金额和订单号说明匹配结果，不要向用户显示内部内容标识。一个精确匹配可按用户原始查看意图继续读取；多个匹配必须让用户选择。"
+                ? "用编号、服务名称、内容主体、购买时间、金额和订单号说明匹配结果，不要向用户显示内部内容标识。一个精确匹配可按用户原始查看意图继续读取；已有任务可明确匹配时读取对应行；只有真实歧义才让用户选择。"
                 : "当前账号没有匹配的已购内容。向用户说明没有找到，不要猜测内容标识、自动购买或发起新的服务查询。",
-            next: null,
+            next: value.next_cursor ? { command: `itpay vault list --limit ${input.limit}${input.query ? ` --query ${shellArgument(input.query)}` : ""} --cursor ${shellArgument(value.next_cursor)}${contextFlags(input)} --json`, reason: "读取同一筛选的下一页" } : null,
             recovery: [],
-        }, outputOptions(input, value.items.map((item, index) => `${index + 1}. ${item.service_title}${item.subject_label ? ` · ${item.subject_label}` : ""} · ${formatMoney(item.amount_minor, item.currency)} · ${item.purchased_at} · ${item.order_code} · ${item.order_status}`)));
+        }, outputOptions(input));
     }
     catch (error) {
         if (error instanceof HttpError && error.code === "vault_authorization_required") {
             writeCommandEnvelope({
                 status: "human_authorization_required",
                 result: { intent: "list_purchased_content", query: input.query ?? "" },
-                instruction: `需要用户确认一次身份和只读权限。执行 next.command 生成官方入口，不要声称链接已经创建；用户完成后重新运行原始 vault list 命令。${accessContextInstruction(input)}`,
-                next: { command: vaultAccessCommand(undefined, input), reason: "创建一次账号读取授权" }, recovery: [],
+                instruction: `需要用户确认一次身份和只读权限。按当前动作或待填模板生成官方入口，不要声称链接已经创建；用户完成后重新运行原始 vault list 命令。${accessContextInstruction(input)}`,
+                ...vaultAccessGuidance(undefined, input), recovery: [],
             }, outputOptions(input));
             return;
         }
@@ -41,6 +41,9 @@ export async function runVaultList(backend, input) {
     }
 }
 export async function runVaultAccess(backend, artifactRef, options) {
+    const issue = validateContext(options.host, options.target);
+    if (issue)
+        throw new CommandContractError(issue.code, issue.message, "先补齐当前可信会话的真实宿主和目标；尚未创建授权请求。", [], { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: { command: vaultAccessCommand(artifactRef, options), required_input: issue.code === "target_required" ? ["target"] : ["host"], executable: false } });
     const value = await backend.createVaultAccessRequest(artifactRef
         ? { purpose: "artifact_reveal", artifact_ref: artifactRef }
         : { purpose: "account_window" });
@@ -90,23 +93,23 @@ export async function runVaultRead(backend, artifactRef, sections, options) {
                 : value.status === "result_preparing"
                     ? "这份已购内容仍在准备。稍后只重试同一 read，不要重新授权、购买或调用 Provider。"
                     : "这份已购内容当前不可用。停止，不要重试、重新购买或绕过退款锁。",
-            next: null, recovery: [],
+            next: value.status === "result_preparing" ? { command: vaultReadCommand(artifactRef, normalized, options), reason: "稍后读取同一内容及原sections；不重新授权或购买" } : null, recovery: [],
         }, outputOptions(options));
     }
     catch (error) {
         if (error instanceof HttpError && error.code === "artifact_authorization_required") {
             writeCommandEnvelope({
                 status: "human_authorization_required", result: { artifact_ref: artifactRef },
-                instruction: `这份内容需要用户单独确认读取权限。执行 next.command 生成一次官方入口；用户完成后重新运行原始 read，不要重复创建授权请求。${accessContextInstruction(options)}`,
-                next: { command: vaultAccessCommand(artifactRef, options), reason: "创建一次内容读取授权" }, recovery: [],
+                instruction: `这份内容需要用户单独确认读取权限。按当前动作或待填模板生成一次官方入口；用户完成后重新运行原始 read，不要重复创建授权请求。${accessContextInstruction(options)}`,
+                ...vaultAccessGuidance(artifactRef, options), recovery: [],
             }, outputOptions(options));
             return;
         }
         if (error instanceof HttpError && error.code === "vault_authorization_required") {
             writeCommandEnvelope({
                 status: "human_authorization_required", result: { artifact_ref: artifactRef },
-                instruction: `账号读取授权已缺失或过期。执行 next.command 生成一次官方入口；用户完成后重新运行原始 read。${accessContextInstruction(options)}`,
-                next: { command: vaultAccessCommand(undefined, options), reason: "创建一次账号读取授权" }, recovery: [],
+                instruction: `账号读取授权已缺失或过期。按当前动作或待填模板生成一次官方入口；用户完成后重新运行原始 read。${accessContextInstruction(options)}`,
+                ...vaultAccessGuidance(undefined, options), recovery: [],
             }, outputOptions(options));
             return;
         }
@@ -121,7 +124,7 @@ export function vaultAccessCommand(artifactRef, options) {
     const host = options.host ?? (openClaw ? "<host>" : undefined);
     if (host)
         parts.push("--host", host);
-    const target = options.target ?? (openClaw && (!options.host || requiresTarget(options.host)) ? "<target>" : undefined);
+    const target = options.target ?? (((openClaw && !options.host) || (options.host && requiresTarget(options.host))) ? "<target>" : undefined);
     if (target)
         parts.push("--target", shellArgument(target));
     parts.push("--json");
@@ -132,10 +135,14 @@ export function accessContextInstruction(options) {
         ? " 将 <host> 和 <target> 替换为当前可信 OpenClaw 会话的真实值，不要照抄占位符或猜测目标。"
         : "";
 }
-function shellArgument(value) {
-    if (value.startsWith("<") && value.endsWith(">"))
-        return value;
-    if (/^[\p{L}\p{N}._:=/-]+$/u.test(value))
-        return value;
-    return `'${value.replaceAll("'", `'"'"'`)}'`;
+function contextFlags(options) {
+    return `${options.host ? ` --host ${options.host}` : ""}${options.target ? ` --target ${shellArgument(options.target)}` : ""}`;
+}
+function vaultReadCommand(artifact, sections, options) {
+    return `itpay vault read --artifact ${shellArgument(artifact)}${sections.map(section => ` --section ${shellArgument(section)}`).join("")}${contextFlags(options)} --json`;
+}
+export function vaultAccessGuidance(artifact, options) {
+    const command = vaultAccessCommand(artifact, options);
+    const missing = [...(options.agentType === "openclaw" && !options.host ? ["host"] : []), ...(options.host && requiresTarget(options.host) && !options.target || options.agentType === "openclaw" && !options.host && !options.target ? ["target"] : [])];
+    return missing.length ? { next: null, interaction: { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: { command, required_input: missing, executable: false } } } : { next: { command, reason: "创建一次官方只读授权入口；用户完成后恢复原reader" } };
 }

package/dist/src/main.js

@@ -25,7 +25,7 @@ import { runCancelRefund, runGetRefund, runListRefunds, runRefund, runWatchRefun
 import { runCartAdd, runCartAddQuoteServer, runCartAddServer, runCartAbandonServer, runCartClear, runCartNext, runCartRemove, runCartRemoveServer, runCartShow, runCartShowServer, } from "./commands/cart.js";
 import { CommandContractError, errorRecoveryActions, printErrorRecovery, writeCommandEnvelope } from "./commands/guidance.js";
 import { runDocsList, runDocsShow, runDocsSearch } from "./commands/docs.js";
-import { runInstall } from "./commands/install.js";
+import { INSTALL_AGENT_TYPES, runInstall } from "./commands/install.js";
 import { runSkillShow } from "./commands/skill.js";
 import { runNext } from "./commands/next.js";
 import { runVaultAccess, runVaultList, runVaultRead } from "./commands/vault.js";
@@ -139,17 +139,12 @@ function reportCLIError(error, contract) {
     const providerContractMismatch = error instanceof HttpError && error.code === "provider_contract_mismatch";
     const capabilityInputInvalid = error instanceof HttpError && error.code === "capability_input_invalid";
     const deviceKeyResettable = Boolean(deviceError && (deviceError.code === "agent_device_key_rotated" ||
-        deviceError.code === "agent_device_key_conflict" ||
-        (deviceError.enrollmentFailed && deviceError.status === 500)));
+        deviceError.code === "agent_device_key_conflict"));
     const deviceRecovery = deviceError ? [
         {
             command: "itpay skill show itpay --json",
             reason: "读取 ItPay 身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
         },
-        ...(deviceKeyResettable ? [{
-                command: "itpay device reset-key --confirm-key-reset --json",
-                reason: "服务端拒绝以当前私钥完成设备登记；生成全新 Ed25519 密钥并重新登记（旧设备身份在服务端保留为孤儿，不影响新身份和额度谱系）",
-            }] : []),
     ] : [];
     const stateRecovery = stateError ? [{
             command: "itpay skill show itpay --json",
@@ -167,10 +162,10 @@ function reportCLIError(error, contract) {
                 ? "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 生成全新密钥后重试。"
+                    : deviceError?.enrollmentFailed && deviceError.status === 500
+                        ? "服务端未能完成设备登记；保持原密钥和Agent Type，说明系统故障，待服务端恢复后继续原任务。不要重置身份。"
                         : deviceKeyResettable
-                            ? "服务端记录显示当前设备私钥已不再有效（已轮换或与既有登记冲突）。执行 itpay device reset-key --confirm-key-reset 生成全新密钥并重新登记。"
+                            ? "服务端拒绝当前设备私钥登记（轮换或冲突）。停止自动恢复；换钥会放弃旧身份，旧执行访问不会迁移。仅用户或运营明确决定放弃旧身份后，按 device reset-key 帮助执行。"
                             : deviceError
                                 ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
                                 : undefined;
@@ -181,7 +176,7 @@ function reportCLIError(error, contract) {
                 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 ? {
+            ...(commandError?.result ? { result: commandError.result } : requiredCLIVersion ? {
                 result: {
                     current_cli_version: CLI_VERSION,
                     required_cli_version: requiredCLIVersion,
@@ -220,7 +215,7 @@ function reportCLIError(error, contract) {
                                     : providerRejected
                                         ? "告诉用户数据来源没有接受本次请求，但没有说明是输入错误，并按 result.quota 说明额度状态，然后停止。不要转述内部错误、修改输入、重试或创建新查询。"
                                         : capabilityInputInvalid
-                                            ? "告诉用户当前输入不完整或格式不正确；数据来源尚未调用，额度没有变化。不要转述技术错误或原样重试；用户提供修正信息后继续同一次服务。"
+                                            ? "Agent按当前合同模板修正字段和JSON层级，保留用户原始需求，继续同一次服务。不要让用户修技术输入，只有真实业务歧义才询问。"
                                             : transportError
                                                 ? transportError.attempts > 1
                                                     ? "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。"
@@ -229,6 +224,7 @@ function reportCLIError(error, contract) {
                                                     ? "移除 ITPAY_BACKEND_URL 使用正式环境，或按当前测试目标准确设置为 https://sandbox.itpay.ai 或 https://dev.itpay.ai。不要通过切换环境规避当前错误。"
                                                     : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
+            ...(commandError?.interaction ? { interaction: commandError.interaction } : {}),
             recovery: incompatible
                 ? requiredCLIVersion
                     ? [distributionUpgradeAction(requiredCLIVersion)]
@@ -238,7 +234,7 @@ function reportCLIError(error, contract) {
                     : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : lockError ? lockRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
             ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError || lockError || stateError ? { jsonOutput: process.argv.includes("--json") } : {}),
-            output: (text) => { process.stderr.write(text); },
+            output: (text) => { process.stdout.write(text); },
         });
         process.exitCode = 1;
         return;
@@ -323,7 +319,7 @@ for (const action of ["login", "status"]) {
             // and non-JSON output is human-readable instead of a raw JSON dump.
             const envelope = {
                 status: String(result.status ?? "error"),
-                result: (result.result ?? result),
+                result: (result.result ?? Object.fromEntries(Object.entries(result).filter(([key]) => !["status", "instruction", "next", "recovery", "handoff"].includes(key)))),
                 ...(result.handoff ? { handoff: result.handoff } : {}),
                 instruction: typeof result.instruction === "string" ? result.instruction : "按返回状态继续。",
                 next: (result.next ?? null),
@@ -422,8 +418,11 @@ deviceCmd
     .action(async (options) => {
     const config = loadConfig();
     try {
+        if (!config.agentType || !INSTALL_AGENT_TYPES.some(type => type === config.agentType)) {
+            throw new CommandContractError("agent_type_required", "supported Agent Type required before key reset", "先按真实宿主配置正式支持的Agent Type；尚未修改本地密钥。", [{ command: "itpay install --json", reason: "读取当前宿主配置" }]);
+        }
         if (!options.confirmKeyReset) {
-            throw new CommandContractError("key_reset_confirmation_required", "--confirm-key-reset is required", "仅当服务端拒绝以当前私钥完成设备登记（internal_error、agent_device_key_rotated 或 agent_device_key_conflict）时使用；会放弃本地设备身份并重新登记，旧设备在服务端保留为孤儿。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
+            throw new CommandContractError("key_reset_confirmation_required", "--confirm-key-reset is required", "仅在用户或运营明确决定放弃旧身份后使用；会丢弃本地私钥，旧执行访问不会迁移。internal_error 需服务端恢复，不能换钥。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
         }
         const reset = await new DeviceAuthority({
             baseURL: config.baseURL,
@@ -437,9 +436,9 @@ deviceCmd
                 private_key_preserved: false,
                 server_side_device: "orphaned_under_previous_key",
             },
-            instruction: "本地设备私钥已重置；下一次需要设备身份的命令会以全新 Ed25519 密钥重新登记并获得新的额度谱系。服务端旧设备记录保留为孤儿；如需清理请走运营流程。",
+            instruction: "本地设备私钥已重置；下一次需要设备身份的命令会以全新 Ed25519 密钥重新登记；这不能恢复旧身份的订单或用于刷新额度。服务端旧设备记录保留为孤儿；如需清理请走运营流程。",
             next: {
-                command: `itpay --agent-type ${config.agentType ?? "<agent_type>"} services list --limit 1 --json`,
+                command: `itpay --agent-type ${config.agentType} services list --limit 1 --json`,
                 reason: "用无业务写入的签名请求完成新密钥的重新登记",
             },
             recovery: [],
@@ -1402,7 +1401,7 @@ services
     catch (error) {
         reportCLIError(error, {
             jsonOutput: Boolean(options.json), code: "workflow_run_failed",
-            instruction: "按服务输入声明补齐参数；已有 execution 时继续该执行。", recovery: [],
+            instruction: "本次操作失败；按已返回的具体原因和恢复动作处理。没有恢复动作时停止，不猜字段或重复创建购买。", recovery: [],
         });
     }
 });
@@ -1477,12 +1476,18 @@ services
     .argument("<service_execution_id>")
     .requiredOption("--capability <capability_id>")
     .option("--input <key=value>", "redacted input summary", collectOption, [])
+    .option("--input-json <file>", "JSON object containing the complete capability input")
     .option("--json", "output JSON")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesInvoke(backend, config, serviceExecutionID, options.capability, parseKeyValueList(options.input), { jsonOutput: Boolean(options.json) });
+        const recovery = [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前动作要求" }];
+        if (options.inputJson && options.input.length > 0) {
+            throw new CommandContractError("capability_input_invalid", "--input and --input-json cannot be combined", "嵌套输入用 --input-json <file>，扁平输入用 --input key=value，二选一；本次未调用供应商。", recovery);
+        }
+        const input = options.inputJson ? readInputJsonObject(options.inputJson, "capability_input_invalid", recovery) : parseKeyValueList(options.input);
+        await runServicesInvoke(backend, config, serviceExecutionID, options.capability, input, { jsonOutput: Boolean(options.json) });
     }
     catch (error) {
         reportCLIError(error, {
@@ -1687,22 +1692,28 @@ services
 });
 services
     .command("read-result")
-    .description("Read a human-granted service result for this agent")
+    .description("Read saved railway results or human-granted service content")
     .argument("<service_execution_id>")
-    .option("--snapshot <snapshot_id>", "rail.progressive.v2: read one journey from a committed planning snapshot")
+    .option("--snapshot <snapshot_id>", "Smart: saved snapshot catalog; add --journey for a journey detail. Exact: saved station-pair rows without --snapshot")
     .option("--journey <journey_id>", "rail.progressive.v2: journey id to read")
+    .option("--offset <offset>", "saved journey offset", Number, 0)
+    .option("--limit <limit>", "rows per page (1-20): Exact 20, Smart 3", Number)
+    .option("--all", "read every saved journey page")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesReadResult(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), snapshot: options.snapshot, journey: options.journey });
+        await runServicesReadResult(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), snapshot: options.snapshot, journey: options.journey,
+            offset: options.offset, limit: options.limit, all: Boolean(options.all) });
     }
     catch (error) {
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
-            code: "agent_access_denied",
-            instruction: "请用户在订单页面重新授权；不要使用开发者权限绕过授权或退款锁。",
+            code: error instanceof HttpError && error.code === "agent_access_denied" ? "agent_access_denied" : "service_result_read_failed",
+            instruction: error instanceof HttpError && error.code === "agent_access_denied"
+                ? "请用户在订单页面重新授权；不要使用开发者权限绕过授权或退款锁。"
+                : "读取同一服务的已保存结果；若快照已不可读，先查看该服务当前状态和有效动作。",
             recovery: [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "检查交付模式和 grant 状态" }],
         });
     }

package/dist/src/render/qr.js

@@ -20,7 +20,7 @@ export async function renderTerminalQR(url, format) {
     });
 }
 export async function writeLocalPNG(url) {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "itpay-v3-"));
+    const dir = await fs.mkdtemp(path.join(process.env.ITPAY_STATE_DIR || os.tmpdir(), "itpay-v3-"));
     const filePath = path.join(dir, `itpay-${randomUUID()}.png`);
     await QRCode.toFile(filePath, url, {
         type: "png",

package/dist/src/state/account_auth.js

@@ -1,12 +1,11 @@
 import { createHash } from 'node:crypto';
-import { homedir } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
 import { writeLocalPNG } from '../render/qr.js';
 import { TaskJournal } from './task_journal.js';
 import { taskJournalPath } from './config.js';
 export function sellerAuthPath(baseURL, env = process.env, purpose = "seller") {
-    return resolve(env.HOME || homedir(), '.itpay-v3', `${purpose}-${createHash('sha256').update(baseURL).digest('hex').slice(0, 16)}.json`);
+    return resolve(stateDir(env), `${purpose}-${createHash('sha256').update(baseURL).digest('hex').slice(0, 16)}.json`);
 }
 function read(baseURL, env = process.env, purpose = "seller") {
     const path = sellerAuthPath(baseURL, env, purpose);
@@ -59,11 +58,11 @@ const TERMINAL_SESSION_STATES = {
     },
     cancelled: {
         status: 'auth_cancelled',
-        instruction: '用户在官方页取消了授权。如仍需登录，重新运行 itpay auth login。',
+        instruction: '用户在官方页取消了授权；停止登录。只有用户明确重新要求授权时才发起新的登录。',
     },
     denied: {
         status: 'auth_denied',
-        instruction: '官方授权被拒绝。重新运行 itpay auth login 生成新请求。',
+        instruction: '官方授权被拒绝；停止登录，不自动创建新请求。只有用户明确重新要求授权时才重新登录。',
     },
 };
 class AuthRequestError extends Error {
@@ -215,7 +214,10 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
         const url = new URL(result.start_url, baseURL);
         const sameOrigin = url.origin === new URL(baseURL).origin;
         const alipay = url.origin === 'https://openauth.alipay.com' && url.pathname === '/oauth2/publicAppAuthorize.htm' && !url.username && !url.password;
-        if (!sameOrigin && !alipay)
+        const local = response.headers.get('X-ItPay-Environment') === 'local_simulation'
+            && new URL(baseURL).protocol === 'http:' && new URL(baseURL).hostname === '127.0.0.1'
+            && url.protocol === 'http:' && url.hostname === '127.0.0.1' && !url.username && !url.password;
+        if (!sameOrigin && !alipay && !local)
             throw new Error('Unexpected authorization origin');
         const fragment = new URLSearchParams(url.hash.replace(/^#dashboard-auth\?/, ''));
         const state = url.searchParams.get('state')?.split('.');
@@ -289,7 +291,7 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                     status: terminal.status,
                     result: { dashboard_auth_session_id: state.sessionID, stage: progress.status },
                     instruction: terminal.instruction,
-                    next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
+                    next: ['denied', 'cancelled'].includes(progress.status) ? null : { command: 'itpay auth login --json', reason: '需要登录时重新发起官方授权' },
                     recovery: [],
                 };
             }
@@ -327,3 +329,4 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
     save({ baseURL, sessionToken: token, expiresAt: session.expires_at }, env);
     return { status: 'authenticated', base_url: baseURL, expires_at: session.expires_at };
 }
+import { stateDir } from "./config.js";

package/dist/src/state/config.js

@@ -15,8 +15,8 @@ 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.22";
-export const API_CONTRACT_REVISION = "sha256:2f9fbcdc5cd0630910abb52671304cc019e348e9a778017ec92ddc3513b3639f";
+export const CLI_VERSION = "2.1.33";
+export const API_CONTRACT_REVISION = "sha256:80d69dbad36debbe4bdfbe468127a934c87b657e7795f369bb04de54863da476";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";
@@ -65,8 +65,8 @@ function stateFilename(filename, baseURL) {
     const dot = filename.lastIndexOf(".");
     return dot < 0 ? `${filename}.${suffix}` : `${filename.slice(0, dot)}.${suffix}${filename.slice(dot)}`;
 }
-function stateDir(env) {
-    return resolve(env.HOME || homedir(), CART_SESSION_DEFAULT_DIR);
+export function stateDir(env = process.env) {
+    return env.ITPAY_STATE_DIR ? resolve(env.ITPAY_STATE_DIR) : resolve(env.HOME || homedir(), CART_SESSION_DEFAULT_DIR);
 }
 export function cartSessionPath(env = process.env) {
     if (env.ITPAY_CART_SESSION_PATH) {

package/dist/src/state/device_authority.js

@@ -1,6 +1,5 @@
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign, } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 const PROTECTED_PATHS = ["/v1/agent-device-account-bindings", "/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds", "/v1/me", "/v1/vault", "/v1/rail/phone-links"];
 export class DeviceAuthority {
@@ -17,7 +16,7 @@ export class DeviceAuthority {
         this.backendKey = normalizeBackendKey(options.baseURL);
         this.requestedAgentType = options.requestedAgentType;
         this.compatibilityHeaders = options.compatibilityHeaders;
-        const root = resolve(homedir(), ".itpay-v3", "device");
+        const root = resolve(stateDir(), "device");
         this.statePath = options.statePath ?? resolve(root, "identity.json");
         this.privateKeyPath = options.privateKeyPath ?? resolve(root, "device-private.pem");
         this.fetchImpl = (options.fetchImpl ?? globalThis.fetch).bind(globalThis);
@@ -470,3 +469,4 @@ function asDeviceStatePathError(error, operation) {
     const code = error.code;
     return code === "EEXIST" ? new DeviceStateError(operation, code) : asDeviceStateError(error, operation);
 }
+import { stateDir } from "./config.js";

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

@@ -35,7 +35,7 @@
     "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.",
     "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.",
+    "Only non-rail capabilities explicitly requiring delivery email may ask its purpose and value. Railway notification contact belongs to the protected checkout page with verified account email reuse; the Agent must not guess or collect it in chat.",
     "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."
   ],

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

@@ -21,7 +21,7 @@
     "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.",
-    "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."
+    "railway": "Railway entries point to itpay docs show rail-booking; 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.",

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

@@ -23,7 +23,7 @@
     "When a previously unseen Agent Type is registered under an existing Device, the CLI skips locally known Agent Instances that the Backend reports as revoked and uses the first remaining valid Instance. It never reactivates a revoked Instance or replaces the Device; if none is valid, registration stops.",
     "When the Backend reports agent_device_not_found (HTTP 404) for a locally known registration — for example after the Backend registration database was rebuilt — the CLI drops only that Backend's registration and re-enrolls once with the same private key, re-attaching to the same device and quota lineage where the Backend still holds the key.",
     "A revoked v2 registration requires explicit operator recovery; it is never silently replaced.",
-    "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."
+    "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. An internal_error is a server failure: preserve the key and wait for service recovery. If enrollment returns agent_device_key_rotated or agent_device_key_conflict, stop automatic recovery. Only an explicit human/operator decision to abandon the old identity permits reset-key; old execution access does not migrate."
   ],
   "local_state_recovery": [
     "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.",
@@ -47,11 +47,6 @@
       "command": "itpay --agent-type <agent_type> device recover --confirm-backend-reset --json",
       "success_signal": "only the selected Backend registration is removed and the private key and other Backend registration remain"
     },
-    {
-      "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",
@@ -103,5 +98,6 @@
     "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."
-  }
+  },
+  "key_reset_decision": "Only after explicit user/operator acceptance of abandoning the old identity, consult device reset-key help; this is not automatic error recovery, and old execution access does not migrate."
 }

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

@@ -41,6 +41,7 @@
     "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.",
+    "A railway order can contain 1–3 legs paid together and issued separately. Report all-issued only when every leg is issued; retain issued tickets on a partial failure or unknown result. Railway return and platform refund follow per-leg supplier facts; do not promise a full refund or create replacement tickets.",
     "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 follows the returned order policy and never reactivates an old grant automatically.",
@@ -92,5 +93,11 @@
     "交付失败",
     "没有收到结果",
     "能不能退"
-  ]
+  ],
+  "rail_notifications": {
+    "channels": "Delivery notices reach the checkout-confirmed contact: email always works; a verified mainland SMS recipient is optional and checkout-scoped. The passenger phone, the login phone and the notification recipient are independent facts.",
+    "status_read": "Use the current returned reader for ticket state; order summaries do not expose per-leg notification delivery records. Do not infer a sent or delivered notification.",
+    "truthfulness": "Provider acceptance is not delivery; an uncertain send outcome is reconciled, not silently retried. A notification failure never changes ticket or refund state; report it as a delivery detail, not an order failure.",
+    "unavailable": "If SMS is not configured or a recipient is unverified, email still satisfies the contact policy — never present an unverified phone as enabled."
+  }
 }

package/docs/agent/buyer/payment-flow.json

@@ -30,6 +30,7 @@
     "Normal buyer flow opens the ItPay Checkout page; itpay pay and buy --pay are operator escape hatches.",
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
     "Obtain only missing required agreement or material price/term changes. Reuse a valid explicit confirmation for unchanged terms; never invent it.",
+    "For a railway journey, show one official checkout for all legs: one total/payment, separate issuance. The page shares its authoritative payment_deadline_at/server_now/payment_remaining_seconds; reaching zero requires reading current status, not declaring cancellation.",
     "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
     "Use only the handoff fields returned for the current Host. Load render-hosts if the official handoff is not visible.",
     "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",

package/docs/agent/buyer/purchased-content.json

@@ -35,7 +35,7 @@
   "authorization_flow": [
     "Run the original list, orders, or read command.",
     "OpenClaw must pass its current trusted host and required target on the original command so the authorization continuation preserves the real presentation destination.",
-    "If it returns human_authorization_required, run only its next.command once.",
+    "If it returns human_authorization_required and context is complete, run its executable next.command once. If next is null or context/consent is missing, fill the returned interaction/input_template first; never invent host, target or consent.",
     "Make the returned handoff genuinely visible and stop.",
     "After the human says authorization is complete, rerun the original read command unchanged.",
     "Never rerun vault access as a status check."

package/docs/agent/buyer/quickstart.json

@@ -27,7 +27,7 @@
     "refund_or_paid_problem": "Resume the known Order or Refund before creating anything new.",
     "service_feedback": "Finish the original order outcome first, then submit one safe Agent postmortem; include a rating or comment only when the human explicitly gives it.",
     "ambiguous": "Ask whether the human wants an earlier purchase or a new query before calling ItPay.",
-    "railway": "Known railway intent: itpay docs show rail-booking --json. Read once, then follow its Exact/Smart route."
+    "railway": "Known railway intent: itpay docs show rail-booking. Read once, then follow its Exact/Smart route."
   },
   "commands": [
     {
@@ -39,11 +39,11 @@
   "agent_rules": [
     "Use the CLI as the control surface; infer the human's intent before the first command and never hardcode a service workflow.",
     "Treat result as current facts, instruction as how to use those facts, next as the preferred executable action, and recovery as exceptional paths.",
-    "Run one state-changing command at a time. Treat next.command as the preferred continuation: execute it unchanged after filling required user data only when the current result has not already satisfied the user's goal.",
+    "Run one state-changing command at a time. Treat next.command as the preferred continuation: execute it unchanged only when its required values are already present; fill a non-executable input_template separately only when the current result has not already satisfied the user's goal.",
     "Keep the same explicit Agent Type through next and recovery commands; same-type windows reuse one Backend Agent Instance.",
     "When testing sandbox, execute every returned command unchanged so its ITPAY_BACKEND_URL=https://sandbox.itpay.ai prefix is preserved.",
-    "Use --target only for a Host presentation destination. Put capability business values in --input key=value exactly as required by the schema.",
-    "Ask the user for required email or contact values and explain their purpose; never invent them.",
+    "Use --target only for a Host presentation destination. Use --input key=value only for simple scalars; nested objects use a small JSON file with the existing --input-json command.",
+    "For non-rail delivery that explicitly requires email, ask only that missing value and explain its purpose. Railway identity and notification contact are handled on the protected official checkout page; never guess them.",
     "Explain useful service facts in ordinary language; never ask the human to run commands or learn internal IDs.",
     "Normal payment uses the returned ItPay Checkout handoff.",
     "A railway query execution and its separate booking execution may serve one purchase intent; keep both references."
@@ -106,5 +106,6 @@
     "rating",
     "target",
     "input"
-  ]
+  ],
+  "reading_results": "Read normal CLI text directly, or parse the complete --json envelope with the host file reader. If saving stdout to a file, first check the command exit code, then read the whole file with cat or the existing file tool. Keep stderr separate; do not use head, tail, regex or a custom script to recover truncated results. Write complex input as a small JSON file and use --input-json."
 }