@itpay/cli 2.1.22 → 2.1.29

package/README.md

@@ -4,7 +4,7 @@ The official V3 CLI and the single ItPay entry point for services, purchases, ac
 
 ## One Entry Point, Several Human Intents
 
-`itpay` is the only public CLI entry point, and `$itpay` is its user-facing Skill invocation. The Agent first distinguishes a new service request, previously purchased content, order history, or a refund. Seller workflows will use the same entry point later and are not implemented yet.
+`itpay` is the only public CLI entry point, and `$itpay` is its user-facing Skill invocation. The Agent first distinguishes a new service request, previously purchased content, order history, or a refund. Seller workflows use the existing `itpay sell` entry point.
 
 ```bash
 npm install -g @itpay/cli
@@ -68,7 +68,7 @@ The local installation keeps one Ed25519 private key and a separate registration
 - `services start/invoke/action/checkout/next`: generic Service Execution flow.
 - `cart add/show/remove/clear/next`, `buy`: canonical Cart and ordinary Checkout flow.
 - `checkout`: authoritative payment and fulfillment recovery.
-- `services read-result`: read one human-granted protected result.
+- `services read-result`: read saved railway query pages or human-granted protected content.
 - `order`, `orders`: exact order and account order views.
 - `vault list/access/read`: find and read previously purchased content after time-limited human authorization.
 - `refund create/list/get/watch/cancel`: Refund Owner flow.

package/dist/src/commands/buy.js

@@ -135,7 +135,7 @@ export async function runBuy(backend, config, options) {
         });
     }
     // --- Output ---
-    if (options.jsonOutput) {
+    if (options.jsonOutput || platformKeyForHost(options.host) === "plain_chat") {
         const envelope = buildBuyEnvelope({
             cart,
             checkoutID,
@@ -148,7 +148,7 @@ export async function runBuy(backend, config, options) {
             ...(options.agentType ? { agentType: options.agentType } : {}),
             ...(options.target ? { target: options.target } : {}),
         });
-        writeCommandEnvelope(envelope, { jsonOutput: true, ...(options.output ? { output: options.output } : {}) });
+        writeCommandEnvelope(envelope, { jsonOutput: Boolean(options.jsonOutput), ...(options.output ? { output: options.output } : {}), ...(options.agentType ? { agentType: options.agentType } : {}) });
         return {
             kind: "checkout_rendered",
             plan,
@@ -219,7 +219,7 @@ function buildBuyEnvelope(input) {
         result,
         handoff: presentationHandoff.handoff,
         instruction: presentationHandoff.instruction,
-        next: { command: input.plan.afterActionCommand ?? `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "稍后查询同一笔 Checkout 状态" },
+        next: { command: input.plan.afterActionCommand ?? `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "仅用户完成付款或要求查询时，读取同一笔Checkout权威状态" },
         recovery: [],
     };
 }

package/dist/src/commands/cart.js

@@ -21,7 +21,7 @@ export function runCartAdd(session, options) {
             offer_id: item.offerID,
             quantity: item.quantity,
         },
-        instruction: "仅写入本地兼容草稿，未验证目录、价格或服务合同；不要把它当作 canonical Cart。",
+        instruction: "仅写入本地兼容草稿，未验证目录、价格或服务合同；不要把它当作 服务端购物车。",
         next: { command: "itpay cart show --local", reason: "检查本地草稿" },
         recovery: [],
     };
@@ -74,10 +74,10 @@ export async function runCartAddServer(options) {
         },
         instruction: serviceExecutionID
             ? "服务型项目已创建 Service Execution；先读取其当前步骤，不要直接进入普通 buy。"
-            : "普通项目已加入 canonical Cart；先检查购物车，再创建 Checkout。",
+            : "普通项目已加入 服务端购物车；先检查购物车，再创建 Checkout。",
         next: serviceExecutionID
             ? { command: `itpay services next ${serviceExecutionID} --json`, reason: "读取服务执行的当前步骤" }
-            : { command: "itpay cart next --json", reason: "检查 canonical Cart" },
+            : { command: "itpay cart next --json", reason: "检查 服务端购物车" },
         recovery: [],
     };
     writeCommandEnvelope(envelope, {
@@ -121,7 +121,7 @@ export async function runCartAddQuoteServer(options) {
             total: formatMoney(cart.amount_minor, cart.currency),
         },
         instruction: "付费服务报价已加入同一 Cart；每个项目仍保持独立 Execution 和交付。",
-        next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "确认项目齐全后创建一次合并付款" },
+        next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "仅已有购买授权且项目齐全时创建一次合并付款" },
         recovery: [{ command: "itpay cart show --json", reason: "检查当前合并 Cart" }],
     };
     writeCommandEnvelope(envelope, {
@@ -144,7 +144,7 @@ export function runCartRemove(session, options) {
             catalog_variant_id: options.catalogVariantID,
             offer_id: options.offerID,
         },
-        instruction: "本地兼容草稿已更新；这不代表任何 canonical Cart 或 Service Execution 已变更。",
+        instruction: "本地兼容草稿已更新；这不代表任何 服务端购物车 或 Service Execution 已变更。",
         next: { command: "itpay cart show --local --json", reason: "检查剩余本地草稿" },
         recovery: [],
     }, {
@@ -176,7 +176,7 @@ export async function runCartRemoveServer(backend, session, cartItemID, options
             cart_item_id: lineID,
             remaining_item_count: cart.items.length,
         },
-        instruction: "canonical Cart 已更新；被删除的最后一个 service-backed line 对应执行会由服务端一致性事务取消。",
+        instruction: "服务端购物车 已更新；被删除的最后一个 服务项目 对应执行会由服务端同时取消。",
         next: { command: "itpay cart next --json", reason: "检查剩余内容" },
         recovery: [],
     };
@@ -198,10 +198,10 @@ export function runCartShow(session, options = {}) {
         status: items.length > 0 ? "shown_local" : "local_empty",
         result: { currency: snap.currency, items },
         instruction: items.length > 0
-            ? "这是未验证的本地兼容草稿，只能用于明确的普通商品流程；不要把它当作 canonical Cart。"
+            ? "这是未验证的本地兼容草稿，只能用于明确的普通商品流程；不要把它当作 服务端购物车。"
             : "本地兼容草稿为空；从已发布目录重新选择项目。",
         next: items.length > 0
-            ? { command: "itpay buy --json", reason: "将普通本地草稿提交为 canonical Cart" }
+            ? { command: "itpay buy --json", reason: "将普通本地草稿提交为 服务端购物车" }
             : { command: "itpay catalog list --json", reason: "读取已发布目录" },
         recovery: [],
     };
@@ -215,7 +215,7 @@ export async function runCartShowServer(backend, session, options = {}) {
         writeCommandEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 canonical Cart 句柄；不要把本地草稿默认为服务端 Cart。",
+            instruction: "本地没有 服务端购物车 句柄；不要把本地草稿默认为服务端 Cart。",
             next: { command: "itpay catalog list --json", reason: "读取已发布目录" },
             recovery: [{ command: "itpay cart show --local --json", reason: "仅在明确需要时检查本地兼容草稿" }],
         }, {
@@ -241,7 +241,7 @@ export async function runCartShowServer(backend, session, options = {}) {
         },
         instruction: items.length > 0
             ? "使用 line 或 execution 句柄继续；不要使用内部 quote lock ID。"
-            : "canonical Cart 当前为空；从已发布目录选择项目。",
+            : "服务端购物车 当前为空；从已发布目录选择项目。",
         next: items.length > 0
             ? { command: "itpay cart next --json", reason: "取得当前首选动作" }
             : { command: "itpay catalog list --json", reason: "读取已发布目录" },
@@ -278,7 +278,7 @@ export async function runCartAbandonServer(backend, session, options = {}) {
         writeCommandEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 canonical Cart 句柄；未修改任何 Backend 或本地资源。",
+            instruction: "本地没有 服务端购物车 句柄；未修改任何 Backend 或本地资源。",
             next: { command: "itpay next --json", reason: "检查其他可恢复句柄" },
             recovery: [{ command: "itpay cart clear --local --json", reason: "仅在明确放弃本地草稿和句柄时执行" }],
         }, {
@@ -292,7 +292,7 @@ export async function runCartAbandonServer(backend, session, options = {}) {
     const envelope = {
         status: "abandoned",
         result: { cart_id: cart.cart_id, server_abandoned: true },
-        instruction: "canonical Cart 已放弃；Backend 已在同一事务中软删除 active lines，并取消其未付款 Service Execution。",
+        instruction: "服务端购物车 已放弃；服务端已清空有效项目，并取消关联的未付款服务执行。",
         next: { command: "itpay catalog list --json", reason: "仅在用户提出新需求时重新选择" },
         recovery: [],
     };
@@ -308,7 +308,7 @@ export async function runCartNext(backend, session, options = {}) {
         writeCartNextEnvelope({
             status: "cart_handle_missing",
             result: {},
-            instruction: "本地没有 canonical Cart 句柄；先恢复已有资源，不要创建重复 Cart。",
+            instruction: "本地没有 服务端购物车 句柄；先恢复已有资源，不要创建重复 Cart。",
             next: { command: "itpay next --json", reason: "检查其他可恢复句柄" },
             recovery: [{ command: "itpay services list --json", reason: "从服务端恢复当前设备的执行" }],
         }, options);
@@ -325,7 +325,7 @@ export async function runCartNext(backend, session, options = {}) {
                 cart_status: cart.status,
                 service_execution_id: unquotedServiceLine.service_execution_id,
             },
-            instruction: "该 Cart 包含 service-backed line；继续 Service Execution，不要从 Cart 猜 capability。",
+            instruction: "该 Cart 包含 服务项目；继续 Service Execution，不要从 Cart 猜 capability。",
             next: {
                 command: `itpay services next ${unquotedServiceLine.service_execution_id} --json`,
                 reason: "读取服务端最新执行状态",
@@ -355,7 +355,7 @@ export async function runCartNext(backend, session, options = {}) {
             instruction: cart.items.some((item) => item.service_quote_lock_id)
                 ? "服务报价已锁定输入和价格；确认项目齐全后使用同一 Cart 创建一次 Checkout。"
                 : "该 Cart 是普通购买流程；使用同一 Cart 创建 Checkout，不要重复添加商品。",
-            next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "继续 canonical Cart 结算" },
+            next: { command: `itpay buy --cart ${cart.cart_id} --json`, reason: "仅已有购买授权时继续服务端购物车结算" },
             recovery: [],
         };
     }

package/dist/src/commands/catalog.js

@@ -9,14 +9,11 @@ export async function runCatalogList(backend, options = {}) {
         status: empty ? "catalog_empty" : "listed",
         result: { catalog_version: manifest.version, services },
         instruction: empty
-            ? "当前没有已发布服务；稍后重试，不要猜测 service_id。"
+            ? "当前没有已发布服务；本次目录读取结束，不猜测服务或自动重试。"
             : "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
-        next: empty
-            ? { command: `itpay catalog list${jsonFlag}`, reason: "稍后重新读取已发布目录" }
-            : {
-                command: `itpay services start ${services.length === 1 && firstServiceID ? firstServiceID : "<service_id>"}${jsonFlag}`,
-                reason: "启动用户选择的服务",
-            },
+        next: services.length === 1 && firstServiceID
+            ? { command: `itpay services start ${firstServiceID}${jsonFlag}`, reason: "仅当当前服务符合用户请求时读取输入合同；不表示购买同意" }
+            : null,
         recovery: [],
     }, {
         ...options,
@@ -28,9 +25,10 @@ function summarizeService(item) {
     const offer = item.variants?.[0];
     return {
         service_id: item.service_id ?? null,
+        ...(item.service_id ? { entry: `itpay services start ${item.service_id} --json` } : {}),
         title: item.title,
         description: item.description ?? "",
-        ...(item.service_id?.startsWith("itpay-rail-") ? { guide: "itpay docs show rail-booking --json" } : {}),
+        ...(item.service_id?.startsWith("itpay-rail-") ? { guide: "itpay docs show rail-booking" } : {}),
         ...(flow ? {
             discovery: {
                 title: flow.discovery.title,
@@ -59,6 +57,10 @@ function catalogPlainLines(version, services) {
     for (const service of services) {
         lines.push(`service: ${String(service.title)}`);
         lines.push(`  service_id: ${String(service.service_id ?? "unavailable")}`);
+        if (service.entry)
+            lines.push(`  entry: ${String(service.entry)}`);
+        if (service.guide)
+            lines.push(`  entry: ${String(service.guide)}`);
         if (service.description)
             lines.push(`  description: ${String(service.description)}`);
         const discovery = service.discovery;

package/dist/src/commands/checkout.js

@@ -10,7 +10,7 @@ import { hostCapabilities, normalizeViewer } from "../state/client_context.js";
 import { DEFAULT_BASE_URL } from "../state/config.js";
 import { buildCheckoutQRPlan } from "./buy.js";
 import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
-import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+import { CommandContractError, plainValueLines, writeCommandEnvelope } from "./guidance.js";
 import { resolvePresentation, resolveRelay } from "./presentation.js";
 export async function runCheckoutPresentation(backend, options) {
     const present = options.present;
@@ -81,10 +81,6 @@ export async function runCheckoutPresentation(backend, options) {
         });
     }
     const envelope = pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, options.agentType, options.target);
-    const plainResult = checkoutPlainResult(envelope.result);
-    if (!options.jsonOutput && platformKeyForHost(host) === "terminal") {
-        plainResult.push("qr:", await renderTerminalQR(checkoutURL, "terminal"));
-    }
     // W5: deterministic presentation plan — business state first, then declared
     // capabilities. `present` is the explicit display request; without it (or
     // under --json alone) nothing opens.
@@ -143,6 +139,10 @@ export async function runCheckoutPresentation(backend, options) {
         wait_for: decision.communication.wait_for,
         must_convey: decision.communication.must_convey,
     };
+    const plainResult = checkoutPlainResult(envelope.result);
+    if (!options.jsonOutput && platformKeyForHost(host) === "terminal") {
+        plainResult.push("qr:", await renderTerminalQR(checkoutURL, "terminal"));
+    }
     writeCommandEnvelope(envelope, {
         ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
         ...(options.output ? { output: options.output } : {}),
@@ -213,11 +213,8 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, a
         instruction: railPassengersPending
             ? `${presentationHandoff.instruction} 请用户在受保护网页填写乘车人并确认报价；姓名、证件和手机号只在网页填写，不要贴到对话中。座位偏好仅为购票请求、购票时才提交给供应商且不保证满足；无法逐人提交的偏好将自动分配座位，以实际出票为准。`
             : presentationHandoff.instruction,
-        next: { command: nextCommand, reason: "稍后只查询同一 Checkout" },
-        recovery: [{
-                command: nextCommand,
-                reason: "付款时限由服务端统一确定，刷新不会延长；到期未支付自动取消后须重新核价下单，不要重发旧付款动作",
-            }],
+        next: { command: nextCommand, reason: "展示后停止；仅用户完成操作或要求核对时读取同一 Checkout" },
+        recovery: [],
     };
 }
 function terminalCheckoutEnvelope(presentation) {
@@ -263,7 +260,7 @@ function checkoutNeedsHumanHandoff(status) {
     return !new Set(["payment_succeeded", "completed", "failed", "expired", "refunded"]).has(status);
 }
 function checkoutPlainResult(result) {
-    return Object.entries(result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+    return plainValueLines(result);
 }
 function formatMoney(amountMinor, currency) {
     return `${(amountMinor / 100).toFixed(2)} ${currency}`;

package/dist/src/commands/docs.js

@@ -1,8 +1,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveOutput } from "../render/sink.js";
-import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+import { CommandContractError, shellArgument, 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 }));
@@ -23,7 +22,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 ${shellWord(normalized || "topic")} --json`, reason: "按关键词重新搜索" },
+            { command: `itpay docs search ${shellArgument(normalized || "topic")} --json`, reason: "按关键词重新搜索" },
         ]);
     }
     const envelope = {
@@ -33,14 +32,7 @@ export function runDocsShow(topic, options = {}) {
         next: null,
         recovery: [],
     };
-    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`);
+    writeCommandEnvelope(envelope, options);
 }
 export function runDocsSearch(query, options = {}) {
     const normalized = query.trim().toLowerCase();
@@ -103,6 +95,3 @@ 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,56 +15,79 @@ export class CommandContractError extends Error {
     code;
     instruction;
     recovery;
-    constructor(code, message, instruction, recovery) {
+    interaction;
+    constructor(code, message, instruction, recovery, interaction) {
         super(message);
         this.code = code;
         this.instruction = instruction;
         this.recovery = recovery;
+        this.interaction = interaction;
         this.name = "CommandContractError";
     }
 }
-// stdoutEnvelopeLimit is the hard byte budget for one emitted JSON envelope:
-// public rail pages/projections must fit 32 KiB end-to-end, so oversized
-// pretty output falls back to a compact line rather than spilling.
-const stdoutEnvelopeLimit = 32 * 1024;
+// 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.length <= stdoutEnvelopeLimit ? pretty : JSON.stringify(qualified) + "\n");
+        out(pretty);
         return;
     }
     out(`${qualified.status}\n`);
     const facts = "error" in qualified ? qualified.error : qualified.result ?? {};
     if (options.plainResult) {
-        for (const line of options.plainResult)
-            out(`${line}\n`);
+        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`);
+        }
     }
     else {
         for (const [key, fact] of Object.entries(facts)) {
-            out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
+            for (const line of plainValueLines(fact, key))
+                out(`${line}\n`);
         }
         if ("error" in qualified && qualified.result) {
             for (const [key, fact] of Object.entries(qualified.result)) {
-                out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
+                for (const line of plainValueLines(fact, key))
+                    out(`${line}\n`);
             }
         }
     }
     if ("handoff" in qualified && qualified.handoff) {
         for (const [key, fact] of Object.entries(qualified.handoff)) {
-            out(`handoff.${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
+            for (const line of plainValueLines(fact, `handoff.${key}`))
+                out(`${line}\n`);
         }
     }
     out(`instruction: ${qualified.instruction}\n`);
     if (qualified.next)
-        out(`next: ${qualified.next.command}\n`);
+        out(`next: ${qualified.next.command}\n  when: ${qualified.next.reason}\n`);
     if ("interaction" in qualified && qualified.interaction) {
-        out(`interaction: ${JSON.stringify(qualified.interaction)}\n`);
+        for (const line of plainValueLines(qualified.interaction, "interaction"))
+            out(`${line}\n`);
     }
     if ("communication" in qualified && qualified.communication) {
-        out(`communication: ${JSON.stringify(qualified.communication)}\n`);
+        for (const line of plainValueLines(qualified.communication, "communication"))
+            out(`${line}\n`);
     }
     if (qualified.recovery.length > 0) {
         out("recovery:\n");
@@ -123,19 +146,12 @@ export function errorRecoveryActions(error) {
         return [{
                 id: "inspect_service_execution",
                 label: "Inspect Service Execution before checkout",
-                command: "itpay services next <service_execution_id> --json",
+                command: "itpay services list --json",
             }];
     }
-    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.code === "cart_item_locked") {
+        return [{ id: "show_cart", label: "Inspect the locked cart", command: "itpay cart show --json",
+                reason: "读取已有购物内容和订单锁，不创建替代 checkout。" }];
     }
     if (error.status === 404) {
         return [{

package/dist/src/commands/install.js

@@ -17,7 +17,7 @@ const INSTRUCTIONS = {
     "codex-cli": "在 Codex CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
-    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回已渲染的付款 Card Link 和 present_files action；原样执行一次 action 打开 handoff.url，不要检查本地二维码文件。",
+    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，不要检查本地二维码文件。",
     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 命令和终端付款交接；不要切换到其他平台身份。",
@@ -53,7 +53,7 @@ export function runInstall(target, options = {}) {
             command: `itpay --agent-type ${normalized} readyz --json`,
             reason: "验证当前官方 ItPay API 的可用性",
         },
-        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看官方 Backend 和首次使用说明" }],
+        recovery: [],
     }, options);
 }
 function isInstallAgentType(value) {

package/dist/src/commands/order.js

@@ -1,3 +1,4 @@
+import { refundStateEnvelope } from "./refund.js";
 import { formatMoney } from "../render/output.js";
 import { appendFeedbackPostmortemInstruction, writeCommandEnvelope } from "./guidance.js";
 export async function runOrder(backend, orderID, options = {}) {
@@ -19,7 +20,7 @@ function orderEnvelope(order, delivery, lockedRefund) {
     let instruction = "订单状态已读取；当前没有可用交付入口。";
     let next = null;
     if (lockedRefund) {
-        instruction = "告诉用户退款处理中，原交付已按政策冻结。然后读取同一退款的权威状态；Agent 不读取交付、不创建授权或重复申请退款。";
+        instruction = refundStateEnvelope(lockedRefund, "shown").instruction;
         if (!refundTerminal) {
             next = { command: `itpay refund get ${lockedRefund.refund_request_id} --json`, reason: "读取退款的服务器状态" };
         }
@@ -41,9 +42,9 @@ function orderEnvelope(order, delivery, lockedRefund) {
     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: "刷新订单支付状态" };
+        next = { command: `itpay order ${order.order_id} --json`, reason: "展示后停止；仅用户说已付款或要求核对时读取同一订单，到期可核对原单" };
     }
     else if (!["delivered", "refunded", "failed", "cancelled"].includes(order.status)) {
         instruction = "先告诉用户订单仍在处理，已记录的付款和订单不需要重复创建；稍后查询同一订单，不要创建替代订单。";

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, writeCommandEnvelope } from "./guidance.js";
-import { accessContextInstruction, vaultAccessCommand } from "./vault.js";
+import { CommandContractError, shellArgument, writeCommandEnvelope } from "./guidance.js";
+import { accessContextInstruction, vaultAccessGuidance } 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: `需要用户确认一次身份和只读权限。执行 next.command 生成官方入口；用户完成后重新运行原始 orders 命令。${accessContextInstruction(options)}`,
-                next: { command: vaultAccessCommand(undefined, options), reason: "创建一次账号读取授权" },
+                instruction: `需要用户确认一次身份和只读权限。按当前动作或待填模板生成官方入口；用户完成后重新运行原始 orders 命令。${accessContextInstruction(options)}`,
+                ...vaultAccessGuidance(undefined, options),
                 recovery: [],
             }, {
                 ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
@@ -92,8 +92,3 @@ 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/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)}`),
     });
 }
-function refundStateEnvelope(refund, status) {
+export function refundStateEnvelope(refund, status) {
     const terminal = ["succeeded", "failed", "cancelled", "rejected"].includes(refund.status);
     let instruction = refund.decision_mode === "manual"
         ? "先告诉用户退款已进入人工审核，原交付保持冻结；人工审核不等于拒绝，等待服务器决定，不要重复申请或承诺结果。"
-        : "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不要重复申请、reveal、授权或读取结果。";
+        : "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不读取交付、不创建授权或重复申请。";
     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 ? "读取活跃退款" : "读取最新退款" }
-            : { command: `itpay refund create --order ${options.orderID} --json`, reason: "为该订单创建退款" },
+            : null,
         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: "cancelled",
+        status: refund.status,
         result: {
             refund_request_id: refund.refund_request_id,
             order_id: refund.order_id,
             access_locked: refund.access_locked,
         },
-        instruction: "退款已取消；如需交付，重新进入订单并取得新的授权。",
+        instruction: refund.status === "cancelled" ? "Backend确认退款已取消；如需交付，重新进入原订单核对当前权限，旧grant不自动复活；后端要求时取得新的授权。" : "Backend未确认取消；按返回的退款权威状态核对原订单，不重复提交取消。",
         next: { command: `itpay order ${refund.order_id} --json`, reason: "确认订单访问状态" },
         recovery: [],
     };