@itpay/cli 2.1.34 → 2.1.41

package/dist/src/commands/checkout_handoff.js

@@ -17,30 +17,11 @@ export function buildWorkBuddyPresentFilesAction(url) {
         arguments: { files: [url] },
     };
 }
-function hasCompleteCheckoutTokens(url) {
-    if (!url) {
-        return false;
-    }
-    try {
-        const parsed = new URL(url);
-        return Boolean(parsed.searchParams.get("display_token") && parsed.searchParams.get("complete_exchange_token"));
-    }
-    catch {
-        return false;
-    }
-}
 export function buildCheckoutHandoff(input) {
-    const url = input.plan?.localSimulation && input.mobileUrl && hasCompleteCheckoutTokens(input.mobileUrl) ? input.mobileUrl : input.url;
-    const handoff = { url, ...(input.plan?.localSimulation ? { environment: "local_simulation", query: "live", transactions: "simulated" } : {}) };
-    // mobile_url is only emitted when the link carries the complete token pair;
-    // a display-token-only link cannot finish the same-device exchange after payment.
-    const mobileUrl = !input.plan?.localSimulation && hasCompleteCheckoutTokens(input.mobileUrl) ? input.mobileUrl : undefined;
-    if (mobileUrl) {
-        handoff.mobile_url = mobileUrl;
-    }
+    const handoff = { url: input.url };
     const workBuddyAction = isWorkBuddyPlainChat(input.agentType, input.platform);
     if (workBuddyAction) {
-        handoff.agent_action = buildWorkBuddyPresentFilesAction(url);
+        handoff.agent_action = buildWorkBuddyPresentFilesAction(input.url);
     }
     if (input.platform === "markdown") {
         if (input.localPath)
@@ -59,43 +40,24 @@ export function buildCheckoutHandoff(input) {
     }
     return {
         handoff,
-        instruction: input.plan?.localSimulation
-            ? `本地实验：铁路与地图查询真实，授权、通知和交易模拟，不会扣款。在本机打开 handoff.url 模拟付款入口，金额 ${input.amount}；仅本机桌面可达。${workBuddyAction ? "按 handoff.agent_action 原样打开一次。" : "展示原入口。"}等待用户操作后读取同一 Checkout；不创建替代订单，用户声明不证明模拟付款已确认。`
-            : `先展示官方入口，再做非必要记忆或日志；保留必需安全检查和宿主权限。${checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(mobileUrl))}`,
+        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount),
     };
 }
-function checkoutHandoffInstruction(agentType, platform, amount, hasMobileLink) {
+function checkoutHandoffInstruction(agentType, platform, amount) {
     if (isWorkBuddyPlainChat(agentType, platform)) {
-        const mobileSentence = hasMobileLink
-            ? "，然后把 handoff.mobile_url 作为可点击链接发给用户，说明“手机端点开可直接跳转支付宝或微信支付；小程序内打不开时复制到手机浏览器打开即可”"
-            : "";
-        const failLinks = hasMobileLink ? "发送 handoff.url 与 handoff.mobile_url" : "发送原始 handoff.url";
-        return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}${mobileSentence}，然后停止等待。若工具失败，只${failLinks}，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (isZCodePlainChat(agentType, platform)) {
-        const mobileSentence = hasMobileLink
-            ? "，并把 handoff.mobile_url 发给用户备用（手机端点开可直接跳转支付宝或微信支付）"
-            : "";
-        const fallbackLinks = hasMobileLink ? "同一个可点击 handoff.url 与 handoff.mobile_url" : "同一个可点击 handoff.url";
-        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}${mobileSentence}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示${fallbackLinks}。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
-    }
-    if (agentType?.trim().toLowerCase() === "doubao-work" && platform === "plain_chat") {
-        const directLink = hasMobileLink ? "handoff.mobile_url" : "handoff.url";
-        const directLabel = hasMobileLink ? "手机直接打开收银台（可跳转支付宝/微信）" : "手机直接打开收银台";
-        return `Backend 尚未确认付款。在当前豆包工作对话中展示两个有标签的官方入口：将 ${directLink} 标为“${directLabel}”，将 handoff.qr_image_url 标为“二维码图片（保存或用另一台设备扫码）”。说明金额 ${amount} 后停止等待。不要解析或单独输出 URL credential，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (platform === "markdown") {
-        const mobileSentence = hasMobileLink ? "，并附 handoff.mobile_url 供手机端点击直达支付" : "";
-        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (platform === "terminal") {
-        const mobileSentence = hasMobileLink ? "，并展示 handoff.mobile_url 供手机端点击直达支付" : "";
-        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (agentType?.trim().toLowerCase() === "openclaw" && platform === "telegram") {
-        const failLinks = hasMobileLink ? "handoff.qr_image_url、金额、handoff.url 与 handoff.mobile_url" : "handoff.qr_image_url、金额和 handoff.url";
-        return `Backend 尚未确认付款或授权状态。立即使用 OpenClaw 原生 message tool，严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行；它会发送金额 ${amount}、二维码、📱 手机点这儿支付和 📋 已授权给我读。不得改写 presentation、换用其他消息工具、拆开按钮发送或用普通回复声称按钮已经发送。确认 message tool 调用成功后停止等待。收到 callback_data "itp:grant_confirmed:<checkout_id>" 时，表示用户声明已在收银台授权读取；立即执行 next.command 查询同一 Checkout，再只执行 Backend 返回的 next.command 进入同一 Execution 的 grant 流程。该 callback 不证明付款成功或 grant 已生效；Backend 未返回 grant_active 前不得读取或猜测结果。若原生 message tool 明确失败或当前 Telegram 未启用 inline buttons，只发送现有 ${failLinks}，报告按钮不可用并停止；不要创建新的 Checkout、Payment Intent 或 Execution。`;
+        return `Backend 尚未确认付款或授权状态。立即使用 OpenClaw 原生 message tool，严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行；它会发送金额 ${amount}、二维码、📱 手机点这儿支付和 📋 已授权给我读。不得改写 presentation、换用其他消息工具、拆开按钮发送或用普通回复声称按钮已经发送。确认 message tool 调用成功后停止等待。收到 callback_data "itp:grant_confirmed:<checkout_id>" 时，表示用户声明已在收银台授权读取；立即执行 next.command 查询同一 Checkout，再只执行 Backend 返回的 next.command 进入同一 Execution 的 grant 流程。该 callback 不证明付款成功或 grant 已生效；Backend 未返回 grant_active 前不得读取或猜测结果。若原生 message tool 明确失败或当前 Telegram 未启用 inline buttons，只发送现有 handoff.qr_image_url、金额和 handoff.url，报告按钮不可用并停止；不要创建新的 Checkout、Payment Intent 或 Execution。`;
     }
-    const urlList = hasMobileLink ? "handoff.url、handoff.mobile_url（手机端点击直达支付）和可用的 handoff.qr_image_url" : "handoff.url 和可用的 handoff.qr_image_url";
-    return `Backend 尚未确认付款。把 ${urlList} 实际发送到当前会话，说明金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    return `Backend 尚未确认付款。把 handoff.url 和可用的 handoff.qr_image_url 实际发送到当前会话，说明金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
 }

package/dist/src/commands/docs.js

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { CommandContractError, shellArgument, writeCommandEnvelope } from "./guidance.js";
+import { resolveOutput } from "../render/sink.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
 const commandDir = dirname(fileURLToPath(import.meta.url));
 export function runDocsList(options = {}) {
     const topics = loadDocs().map(({ topic, title, purpose }) => ({ topic, title, purpose }));
@@ -22,7 +23,7 @@ export function runDocsShow(topic, options = {}) {
     if (!doc) {
         throw new CommandContractError("doc_not_found", `doc topic not found: ${topic}`, "使用稳定 topic 名称；不要根据标题猜 topic。", [
             { command: "itpay docs list --json", reason: "列出全部 topic" },
-            { command: `itpay docs search ${shellArgument(normalized || "topic")} --json`, reason: "按关键词重新搜索" },
+            { command: `itpay docs search ${shellWord(normalized || "topic")} --json`, reason: "按关键词重新搜索" },
         ]);
     }
     const envelope = {
@@ -32,7 +33,14 @@ export function runDocsShow(topic, options = {}) {
         next: null,
         recovery: [],
     };
-    writeCommandEnvelope(envelope, options);
+    if (options.jsonOutput) {
+        writeCommandEnvelope(envelope, options);
+        return;
+    }
+    const out = resolveOutput(options.output);
+    out("shown\n");
+    out(`${JSON.stringify(doc, null, 2)}\n`);
+    out(`instruction: ${envelope.instruction}\n`);
 }
 export function runDocsSearch(query, options = {}) {
     const normalized = query.trim().toLowerCase();
@@ -76,10 +84,10 @@ function loadDocs() {
 function findDocsDir() {
     if (process.env.ITPAY_CLI_DOCS_DIR)
         return resolve(process.env.ITPAY_CLI_DOCS_DIR);
-    const packagePath = resolve(commandDir, "..", "..", "..", "docs", "agent", "buyer");
-    if (existsSync(packagePath))
-        return packagePath;
-    return resolve(commandDir, "..", "..", "docs", "agent", "buyer");
+    const sourcePath = resolve(commandDir, "..", "..", "docs", "agent", "buyer");
+    if (existsSync(sourcePath))
+        return sourcePath;
+    return resolve(commandDir, "..", "..", "..", "docs", "agent", "buyer");
 }
 function parseDoc(raw, file) {
     const value = JSON.parse(raw);
@@ -95,3 +103,6 @@ function parseDoc(raw, file) {
 function searchableText(doc) {
     return [doc.topic, doc.title, doc.purpose, ...(doc.search_terms ?? [])].join(" ").toLowerCase();
 }
+function shellWord(value) {
+    return /^[a-zA-Z0-9._-]+$/.test(value) ? value : JSON.stringify(value);
+}

package/dist/src/commands/guidance.js

@@ -15,82 +15,46 @@ export class CommandContractError extends Error {
     code;
     instruction;
     recovery;
-    interaction;
-    result;
-    constructor(code, message, instruction, recovery, interaction, result) {
+    constructor(code, message, instruction, recovery) {
         super(message);
         this.code = code;
         this.instruction = instruction;
         this.recovery = recovery;
-        this.interaction = interaction;
-        this.result = result;
         this.name = "CommandContractError";
     }
 }
-// Domain projections and pages own byte limits; serialization never truncates facts.
-export function plainValueLines(value, label = "", depth = 0) {
-    const indent = "  ".repeat(depth);
-    if (value === null || typeof value !== "object")
-        return [`${indent}${label ? `${label}: ` : ""}${String(value ?? "unknown")}`];
-    const lines = label ? [`${indent}${label}:`] : [];
-    const entries = Array.isArray(value) ? value.map((v, i) => [String(i + 1), v]) : Object.entries(value);
-    for (const [key, child] of entries)
-        lines.push(...plainValueLines(child, key, depth + (label ? 1 : 0)));
-    if (!entries.length)
-        lines.push(`${indent}  （无记录）`);
-    return lines;
-}
-export function shellArgument(value) {
-    if (/^[\p{L}\p{N}._:=/-]+$/u.test(value))
-        return value;
-    return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
 export function writeCommandEnvelope(value, options = {}) {
     const out = resolveOutput(options.output);
     const agentType = options.agentType ?? declaredAgentType();
     const qualified = qualifyEnvelope(value, agentType);
     if (options.jsonOutput) {
-        const pretty = JSON.stringify(qualified, null, 2) + "\n";
-        out(pretty);
+        out(JSON.stringify(qualified, null, 2) + "\n");
         return;
     }
     out(`${qualified.status}\n`);
     const facts = "error" in qualified ? qualified.error : qualified.result ?? {};
     if (options.plainResult) {
-        for (const line of options.plainResult) {
-            const command = line.match(/^(\s*(?:command|reader|entry): )(itpay .*)$/);
-            out(`${command ? command[1] + qualifyBackendCommand(qualifyItPayCommand(command[2], agentType)) : line}\n`);
-        }
+        for (const line of options.plainResult)
+            out(`${line}\n`);
     }
     else {
         for (const [key, fact] of Object.entries(facts)) {
-            for (const line of plainValueLines(fact, key))
-                out(`${line}\n`);
+            out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
         }
         if ("error" in qualified && qualified.result) {
             for (const [key, fact] of Object.entries(qualified.result)) {
-                for (const line of plainValueLines(fact, key))
-                    out(`${line}\n`);
+                out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
             }
         }
     }
     if ("handoff" in qualified && qualified.handoff) {
         for (const [key, fact] of Object.entries(qualified.handoff)) {
-            for (const line of plainValueLines(fact, `handoff.${key}`))
-                out(`${line}\n`);
+            out(`handoff.${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
         }
     }
     out(`instruction: ${qualified.instruction}\n`);
     if (qualified.next)
-        out(`next: ${qualified.next.command}\n  when: ${qualified.next.reason}\n`);
-    if ("interaction" in qualified && qualified.interaction) {
-        for (const line of plainValueLines(qualified.interaction, "interaction"))
-            out(`${line}\n`);
-    }
-    if ("communication" in qualified && qualified.communication) {
-        for (const line of plainValueLines(qualified.communication, "communication"))
-            out(`${line}\n`);
-    }
+        out(`next: ${qualified.next.command}\n`);
     if (qualified.recovery.length > 0) {
         out("recovery:\n");
         for (const action of qualified.recovery) {
@@ -102,10 +66,6 @@ export function writeCommandEnvelope(value, options = {}) {
 function qualifyEnvelope(value, agentType) {
     return {
         ...value,
-        result: qualifyCommandsDeep(value.result, agentType),
-        ...("handoff" in value && value.handoff ? { handoff: qualifyCommandsDeep(value.handoff, agentType) } : {}),
-        ...("interaction" in value && value.interaction ? { interaction: qualifyCommandsDeep(value.interaction, agentType) } : {}),
-        ...("communication" in value && value.communication ? { communication: qualifyCommandsDeep(value.communication, agentType) } : {}),
         next: value.next ? { ...value.next, command: qualifyBackendCommand(qualifyItPayCommand(value.next.command, agentType)) } : null,
         recovery: value.recovery.map((action) => ({
             ...action,
@@ -113,23 +73,6 @@ function qualifyEnvelope(value, agentType) {
         })),
     };
 }
-// Every `itpay ` command string anywhere in the envelope — result fields,
-// interaction recipes/templates, available_actions — keeps the same Agent
-// Type / Backend qualification as top-level next/recovery. Instruction prose
-// never starts with "itpay " so prose stays untouched.
-function qualifyCommandsDeep(value, agentType) {
-    if (typeof value === "string") {
-        return value.startsWith("itpay ")
-            ? qualifyBackendCommand(qualifyItPayCommand(value, agentType))
-            : value;
-    }
-    if (Array.isArray(value))
-        return value.map((item) => qualifyCommandsDeep(item, agentType));
-    if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, qualifyCommandsDeep(item, agentType)]));
-    }
-    return value;
-}
 export function errorRecoveryActions(error) {
     if (!(error instanceof HttpError))
         return [];
@@ -148,12 +91,19 @@ export function errorRecoveryActions(error) {
         return [{
                 id: "inspect_service_execution",
                 label: "Inspect Service Execution before checkout",
-                command: "itpay services list --json",
+                command: "itpay services next <service_execution_id> --json",
             }];
     }
-    if (error.code === "cart_item_locked") {
-        return [{ id: "show_cart", label: "Inspect the locked cart", command: "itpay cart show --json",
-                reason: "读取已有购物内容和订单锁，不创建替代 checkout。" }];
+    if (error.code === "cart_item_locked" || error.status === 409) {
+        return [
+            { id: "show_cart", label: "Inspect the canonical server cart", command: "itpay cart show" },
+            { id: "continue_checkout", label: "Continue the last locally remembered checkout", command: "itpay checkout" },
+            {
+                id: "recover_service_execution",
+                label: "List recoverable Service Executions if the local handoff is missing",
+                command: "itpay services list",
+            },
+        ];
     }
     if (error.status === 404) {
         return [{

package/dist/src/commands/install.js

@@ -8,19 +8,16 @@ export const INSTALL_AGENT_TYPES = [
     "claude-code-cli",
     "workbuddy",
     "zcode",
-    "doubao-work",
     "kimi-code",
     "openclaw",
 ];
-export const CODEX_WAIT_GUIDANCE = "Codex 宿主等待：保留完整工具返回，按实际返回的会话句柄及当前宿主续读工具收取最终输出，不要只取 stdout。若使用 functions.exec 包装，可用 text(await tools.exec_command(...))；内层有 session_id 时用 write_stdin，外层返回运行 cell 时才用 wait。没有该包装时按宿主实际工具操作。先收取最终输出，再执行 CLI 业务 next；不要重复提交。";
 const INSTRUCTIONS = {
     "codex-desktop": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "codex-cli": "在 Codex CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
-    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity；锁忙只用官方 device repair-lock。Checkout 返回已渲染的付款 Card Link 和 present_files action；原样执行一次 action 打开 handoff.url，不要检查本地二维码文件。",
+    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回已渲染的付款 Card Link 和 present_files action；原样执行一次 action 打开 handoff.url，不要检查本地二维码文件。",
     zcode: "在 ZCode 中始终传这个 Agent Type。Checkout 或授权返回 handoff.url 后，立即用 ZCode 内置浏览器打开；不要只粘贴文字链接或重建二维码。只有内置浏览器不可用时才展示同一个可点击链接。",
-    "doubao-work": "在豆包工作中始终传这个 Agent Type。Checkout 或授权返回后，同时展示 handoff.url 和 handoff.qr_image_url 两个有标签的官方入口；优先让用户在手机上直接打开链接，二维码供保存或另一台设备扫码。",
     "kimi-code": "保持 kimi-code Agent Type，使用标准 CLI 命令和终端付款交接；不要切换到其他平台身份。",
     openclaw: "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
 };
@@ -49,12 +46,12 @@ export function runInstall(target, options = {}) {
             ...installDefinition(normalized),
             default_api: DEFAULT_BASE_URL,
         },
-        instruction: INSTRUCTIONS[normalized] + (normalized.startsWith("codex-") ? ` ${CODEX_WAIT_GUIDANCE}` : ""),
+        instruction: INSTRUCTIONS[normalized],
         next: {
             command: `itpay --agent-type ${normalized} readyz --json`,
             reason: "验证当前官方 ItPay API 的可用性",
         },
-        recovery: [],
+        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看官方 Backend 和首次使用说明" }],
     }, options);
 }
 function isInstallAgentType(value) {

package/dist/src/commands/order.js

@@ -1,4 +1,3 @@
-import { refundStateEnvelope } from "./refund.js";
 import { formatMoney } from "../render/output.js";
 import { appendFeedbackPostmortemInstruction, writeCommandEnvelope } from "./guidance.js";
 export async function runOrder(backend, orderID, options = {}) {
@@ -20,7 +19,7 @@ function orderEnvelope(order, delivery, lockedRefund) {
     let instruction = "订单状态已读取；当前没有可用交付入口。";
     let next = null;
     if (lockedRefund) {
-        instruction = refundStateEnvelope(lockedRefund, "shown").instruction;
+        instruction = "告诉用户退款处理中，原交付已按政策冻结。然后读取同一退款的权威状态；Agent 不读取交付、不创建授权或重复申请退款。";
         if (!refundTerminal) {
             next = { command: `itpay refund get ${lockedRefund.refund_request_id} --json`, reason: "读取退款的服务器状态" };
         }
@@ -39,13 +38,6 @@ function orderEnvelope(order, delivery, lockedRefund) {
     else if (order.status === "cancelled") {
         instruction = "先告诉用户这笔订单已经取消，没有可继续的付款或交付；不要创建替代订单，除非用户另行提出新的购买。";
     }
-    else if (order.status === "pending_payment") {
-        const remaining = typeof order.payment_remaining_seconds === "number" && order.payment_remaining_seconds <= 0;
-        instruction = remaining
-            ? "付款时限已到，但订单权威状态仍为待付款；读取同一订单核对到账或终止结果。不要重复支付、重建订单或推测已取消，刷新不会延长期限。"
-            : `先告诉用户订单正在等待付款${order.payment_deadline_at ? `，付款截止时间为 ${order.payment_deadline_at}` : ""}，超时未支付会被自动取消；不要创建替代订单，也不要重复发起支付授权。`;
-        next = { command: `itpay order ${order.order_id} --json`, reason: "展示后停止；仅用户说已付款或要求核对时读取同一订单，到期可核对原单" };
-    }
     else if (!["delivered", "refunded", "failed", "cancelled"].includes(order.status)) {
         instruction = "先告诉用户订单仍在处理，已记录的付款和订单不需要重复创建；稍后查询同一订单，不要创建替代订单。";
         next = { command: `itpay order ${order.order_id} --json`, reason: "刷新订单状态" };
@@ -56,11 +48,6 @@ function orderEnvelope(order, delivery, lockedRefund) {
             order_id: order.order_id,
             ...(order.order_code ? { order_code: order.order_code } : {}),
             amount: formatMoney(order.amount_minor, order.currency),
-            ...(order.payment_deadline_at ? { payment_deadline_at: order.payment_deadline_at } : {}),
-            ...(typeof order.payment_remaining_seconds === "number"
-                ? { payment_remaining_seconds: order.payment_remaining_seconds }
-                : {}),
-            ...(order.server_now ? { server_now: order.server_now } : {}),
             ...(delivery ? { delivery_mode: delivery.delivery_mode } : {}),
             access_locked: Boolean(lockedRefund),
             ...(delivery?.service_execution_id ? { service_execution_id: delivery.service_execution_id } : {}),

package/dist/src/commands/orders.js

@@ -1,8 +1,8 @@
 import { HttpError } from "../client/http.js";
 import { formatMoney } from "../render/output.js";
 import { resolveOutput } from "../render/sink.js";
-import { CommandContractError, shellArgument, writeCommandEnvelope } from "./guidance.js";
-import { accessContextInstruction, vaultAccessGuidance } from "./vault.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+import { accessContextInstruction, vaultAccessCommand } from "./vault.js";
 const ORDER_STATUSES = new Set([
     "pending_payment",
     "paid",
@@ -30,8 +30,8 @@ export async function runListOrders(backend, config, options) {
             writeCommandEnvelope({
                 status: "human_authorization_required",
                 result: { intent: "list_purchase_history" },
-                instruction: `需要用户确认一次身份和只读权限。按当前动作或待填模板生成官方入口；用户完成后重新运行原始 orders 命令。${accessContextInstruction(options)}`,
-                ...vaultAccessGuidance(undefined, options),
+                instruction: `需要用户确认一次身份和只读权限。执行 next.command 生成官方入口；用户完成后重新运行原始 orders 命令。${accessContextInstruction(options)}`,
+                next: { command: vaultAccessCommand(undefined, options), reason: "创建一次账号读取授权" },
                 recovery: [],
             }, {
                 ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
@@ -92,3 +92,8 @@ function ordersPageCommand(cursor, options) {
     parts.push("--json");
     return parts.join(" ");
 }
+function shellArgument(value) {
+    if (/^[\p{L}\p{N}._:=/-]+$/u.test(value))
+        return value;
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

package/dist/src/commands/pay.js

@@ -53,7 +53,7 @@ function payEnvelope(intent, options) {
         instruction: payInstruction(options, verified, terminal, hasAction, amount),
         next: {
             command: `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`,
-            reason: verified ? "读取权威订单和履约状态" : "展示后停止；仅用户完成付款或要求核对时读取同一 Checkout",
+            reason: verified ? "读取权威订单和履约状态" : "读取同一 Checkout 的权威付款状态",
         },
         recovery: [],
     };

package/dist/src/commands/readyz.js

@@ -8,8 +8,8 @@ export async function runReadyz(backend, options = {}) {
         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，再根据用户意图选择新服务、已购内容、订单或退款入口；不要默认开始购买。",
+            ? "ItPay dev 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；后续必须执行返回的完整命令并保持同一 dev Backend。"
+            : "ItPay 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；不自动登录或开始业务。",
         next: { command: "itpay skill show itpay --json", reason: "加载完整操作与安全规则" },
         recovery: [],
     }, options);

package/dist/src/commands/refund.js

@@ -12,11 +12,11 @@ export async function runRefund(backend, config, options) {
         plainResult: Object.entries(envelope.result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`),
     });
 }
-export function refundStateEnvelope(refund, status) {
+function refundStateEnvelope(refund, status) {
     const terminal = ["succeeded", "failed", "cancelled", "rejected"].includes(refund.status);
     let instruction = refund.decision_mode === "manual"
         ? "先告诉用户退款已进入人工审核，原交付保持冻结；人工审核不等于拒绝，等待服务器决定，不要重复申请或承诺结果。"
-        : "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不读取交付、不创建授权或重复申请。";
+        : "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不要重复申请、reveal、授权或读取结果。";
     if (!refund.access_locked)
         instruction = "先告诉用户退款当前没有锁定交付；按服务器事实解释当前状态，不要自行推断退款结果、到账时间或交付资格。";
     if (refund.status === "succeeded")
@@ -73,7 +73,7 @@ export async function runListRefunds(backend, options) {
                 : "该订单没有退款记录；确认用户确实要求退款后再创建。",
         next: selected
             ? { command: `itpay refund get ${selected.refund_request_id} --json`, reason: active ? "读取活跃退款" : "读取最新退款" }
-            : null,
+            : { command: `itpay refund create --order ${options.orderID} --json`, reason: "为该订单创建退款" },
         recovery: [],
     };
     writeCommandEnvelope(envelope, {
@@ -96,13 +96,13 @@ export async function runGetRefund(backend, refundID, options = {}) {
 export async function runCancelRefund(backend, refundID, reason, options = {}) {
     const refund = await backend.cancelRefund(refundID, reason?.trim() || "buyer_cancelled");
     const envelope = {
-        status: refund.status,
+        status: "cancelled",
         result: {
             refund_request_id: refund.refund_request_id,
             order_id: refund.order_id,
             access_locked: refund.access_locked,
         },
-        instruction: refund.status === "cancelled" ? "Backend确认退款已取消；如需交付，重新进入原订单核对当前权限，旧grant不自动复活；后端要求时取得新的授权。" : "Backend未确认取消；按返回的退款权威状态核对原订单，不重复提交取消。",
+        instruction: "退款已取消；如需交付，重新进入订单并取得新的授权。",
         next: { command: `itpay order ${refund.order_id} --json`, reason: "确认订单访问状态" },
         recovery: [],
     };