@itpay/cli 2.1.40 → 2.1.41

package/dist/src/commands/checkout.js

@@ -5,40 +5,11 @@ import { buildAgentChatHandoff } from "../render/markdown.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
 import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
-import { openInSystemBrowser } from "../render/browser.js";
-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, plainValueLines, writeCommandEnvelope } from "./guidance.js";
-import { resolvePresentation, resolveRelay } from "./presentation.js";
+import { writeCommandEnvelope } from "./guidance.js";
 export async function runCheckoutPresentation(backend, options) {
-    const present = options.present;
-    if (present !== undefined && !["auto", "browser", "image", "link", "none"].includes(present)) {
-        throw new CommandContractError("present_invalid", `--present must be one of auto|browser|image|link|none`, "使用支持的展示方式；未知参数已被拒绝。", []);
-    }
-    const relayRequested = Boolean(options.relayOption || options.confirmRelay || options.requestKey || options.relayStatus);
-    if (relayRequested && options.present && options.present !== "none") {
-        throw new CommandContractError("present_relay_conflict", "--present and --relay-* options are mutually exclusive", "展示和消息转发二选一；不要在同一次调用中同时开页面和发消息。", []);
-    }
-    if (options.noOpen && options.present === "browser") {
-        throw new CommandContractError("present_conflict", "--present browser conflicts with --no-open", "--no-open 与浏览器展示冲突；改用 --present link 或 image。", []);
-    }
-    if (options.relayStatus) {
-        // Read-only relay status. The backend exposes no relay routes yet, so the
-        // honest answer is unavailable — never a resend, never a guessed state.
-        writeCommandEnvelope({
-            status: "relay_unavailable",
-            result: { relay_id: options.relayStatus },
-            instruction: "当前 Backend 未提供消息转发状态查询；不要重发。读取原订单/Checkout 状态核对。",
-            next: { command: `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`, reason: "读取原 Checkout 当前状态" },
-            recovery: [],
-        }, {
-            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
-            ...(options.output ? { output: options.output } : {}),
-        });
-        return;
-    }
     const locale = normalizeCardLocale(options.locale);
     const presentation = await backend.getCheckoutPresentation(options.checkoutID, options.displayToken, locale === "en" ? locale : undefined);
     const host = options.host ?? "terminal";
@@ -51,13 +22,12 @@ export async function runCheckoutPresentation(backend, options) {
         });
         return;
     }
-    const checkoutURL = savedCheckoutURLOrFallback(options.savedCheckoutURL, options.checkoutID, options.displayToken, checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken));
+    const checkoutURL = checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken);
     const cardURL = localizeCardURL(absolutePublicURL(options.baseURL, presentation.card_url ?? checkoutCardURL(options.baseURL, options.checkoutID, options.displayToken)), locale);
     const qrPNGURL = absolutePublicURL(options.baseURL, presentation.card_png_url ?? presentation.qr_png_url ?? checkoutCardPNGURL(options.baseURL, options.checkoutID, options.displayToken));
     const localizedPNGURL = localizeCardURL(qrPNGURL, locale);
     const nextCommand = `itpay checkout --id ${options.checkoutID} --token ${options.displayToken}${locale === "en" ? " --locale en" : ""} --json`;
     const plan = buildCheckoutQRPlan({
-        localSimulation: backend.localSimulation,
         host,
         checkoutID: options.checkoutID,
         checkoutURL,
@@ -82,64 +52,6 @@ export async function runCheckoutPresentation(backend, options) {
         });
     }
     const envelope = pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, options.agentType, options.target);
-    // W5: deterministic presentation plan — business state first, then declared
-    // capabilities. `present` is the explicit display request; without it (or
-    // under --json alone) nothing opens.
-    // An explicit --viewer (including "unknown") wins over the host default.
-    const viewer = options.viewer ? normalizeViewer(options.viewer) : (host === "terminal" ? "desktop" : "unknown");
-    const locality = ["terminal", "codex", "claude-code"].includes(host) ? "same_device" : "unknown";
-    const decision = resolvePresentation({
-        business: {
-            commerce_policy: "allowed",
-            payment_state: "unpaid",
-            quote_valid: presentation.rail_quote?.expires_at
-                ? Date.parse(presentation.rail_quote.expires_at) > Date.now()
-                : true,
-            amount_minor: presentation.checkout.amount_minor,
-        },
-        viewer,
-        executor_locality: locality,
-        capabilities: hostCapabilities(host),
-        ...(explicitChoiceFor(options.present) ? { explicit_choice: explicitChoiceFor(options.present) } : {}),
-    });
-    const presentationResult = {
-        recommended: decision.recommended,
-        alternatives: decision.alternatives,
-        ...(decision.blocker ? { blocker: decision.blocker } : {}),
-    };
-    let dispatch = { status: "not_attempted" };
-    // Explicit --present browser may open even under --json (the flag IS the
-    // display request); --present auto under --json stays a plan and never opens.
-    const browserRequested = options.present === "browser"
-        || (options.present === "auto" && !options.jsonOutput && !options.noOpen && decision.recommended === "open_system_browser");
-    if (browserRequested && !options.noOpen && process.env.ITPAY_NO_BROWSER !== "1") {
-        const target = decision.recommended === "open_embedded_browser" ? decision.recommended : "open_system_browser";
-        dispatch = await openInSystemBrowser(checkoutURL, options.baseURL);
-        presentationResult.dispatched = { route: target, observation: dispatch.status };
-        // Dispatch proves the request was accepted — nothing about visibility.
-        if (dispatch.status === "dispatch_accepted") {
-            envelope.instruction += " 已发起在本机浏览器打开官方确认页；只有用户确认看到页面才视为已显示，没看到时改发链接。";
-        }
-        else {
-            envelope.instruction += " 浏览器打开未成功；按 handoff 链接展示，不要重复尝试同一方式。";
-        }
-    }
-    if (relayRequested) {
-        presentationResult.relay = resolveRelay({
-            ...(options.relayOption ? { relayOption: options.relayOption } : {}),
-            ...(options.confirmRelay ? { confirmRelay: options.confirmRelay } : {}),
-            ...(options.requestKey ? { requestKey: options.requestKey } : {}),
-            backendCapability: false,
-        });
-        envelope.instruction += " 消息转发当前不可用；不要声称已发送，改用现有官方入口展示。";
-    }
-    envelope.result = { ...envelope.result, presentation: presentationResult };
-    envelope.communication = {
-        schema_version: "itpay.communication.v1",
-        tell: decision.communication.tell,
-        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"));
@@ -150,21 +62,12 @@ export async function runCheckoutPresentation(backend, options) {
         plainResult,
     });
 }
-function explicitChoiceFor(present) {
-    switch (present) {
-        case "browser": return "open_system_browser";
-        case "link": return "show_link";
-        case "image": return "show_official_image";
-        default: return undefined;
-    }
-}
 function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, agentType, target) {
     const platform = platformKeyForHost(plan.host);
     const amount = formatMoney(presentation.checkout.amount_minor, presentation.checkout.currency);
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: plan.linkOnlyURL ?? checkoutURL,
-        mobileUrl: checkoutURL,
         amount,
         plan,
         ...(agentType ? { agentType } : {}),
@@ -175,46 +78,16 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, a
             : {}),
         ...(platform === "markdown" ? { markdown: buildAgentChatHandoff(plan).markdown } : {}),
     });
-    const railQuote = presentation.rail_quote;
-    const railPassengersPending = presentation.checkout_details === "rail_passengers" && !presentation.rail_passengers_confirmed;
     return {
         status: "human_checkout_required",
         result: {
             checkout_id: presentation.checkout.checkout_id,
             payment: "pending",
             amount,
-            ...(railQuote ? { rail_quote: {
-                    passengers: railQuote.passengers,
-                    expires_at: railQuote.expires_at,
-                    legs: railQuote.legs.map((leg) => ({
-                        train_code: leg.train_code,
-                        travel_date: leg.travel_date,
-                        route: `${leg.from} → ${leg.to}`,
-                        time: `${leg.departure}–${leg.arrival}`,
-                        seat_name: leg.seat_name,
-                        ...(leg.seat_preferences?.length ? { seat_preferences: leg.seat_preferences } : {}),
-                        ...(leg.seat_request_planned ? {
-                            seat_request_planned: leg.seat_request_planned,
-                            auto_reason: leg.auto_reason ?? "none",
-                        } : {}),
-                    })),
-                } } : {}),
-            ...(railPassengersPending ? { rail_passengers_confirmed: false } : {}),
-            ...(presentation.payment_deadline_at ? { payment_deadline_at: presentation.payment_deadline_at } : {}),
-            ...(typeof presentation.payment_remaining_seconds === "number"
-                ? { payment_remaining_seconds: presentation.payment_remaining_seconds }
-                : {}),
-            ...(presentation.server_now ? { server_now: presentation.server_now } : {}),
-            ...(presentation.verified_sms_contact ? { verified_sms_contact: presentation.verified_sms_contact } : {}),
-            ...(presentation.account_phone_option?.masked_recipient
-                ? { account_phone_option: { masked_recipient: presentation.account_phone_option.masked_recipient } }
-                : {}),
         },
         handoff: presentationHandoff.handoff,
-        instruction: railPassengersPending
-            ? `${presentationHandoff.instruction} 请用户在受保护网页填写乘车人并确认报价；姓名、证件和手机号只在网页填写，不要贴到对话中。座位偏好仅为购票请求、购票时才提交给供应商且不保证满足；无法逐人提交的偏好将自动分配座位，以实际出票为准。`
-            : presentationHandoff.instruction,
-        next: { command: nextCommand, reason: "展示后停止；仅用户完成操作或要求核对时读取同一 Checkout" },
+        instruction: presentationHandoff.instruction,
+        next: { command: nextCommand, reason: "稍后只查询同一 Checkout" },
         recovery: [],
     };
 }
@@ -261,7 +134,7 @@ function checkoutNeedsHumanHandoff(status) {
     return !new Set(["payment_succeeded", "completed", "failed", "expired", "refunded"]).has(status);
 }
 function checkoutPlainResult(result) {
-    return plainValueLines(result);
+    return Object.entries(result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
 }
 function formatMoney(amountMinor, currency) {
     return `${(amountMinor / 100).toFixed(2)} ${currency}`;
@@ -270,20 +143,6 @@ function checkoutPageURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
     return `${root}/checkout/${encodeURIComponent(checkoutID)}?display_token=${encodeURIComponent(displayToken)}`;
 }
-function savedCheckoutURLOrFallback(savedURL, checkoutID, displayToken, fallback) {
-    if (!savedURL) {
-        return fallback;
-    }
-    try {
-        const parsed = new URL(savedURL);
-        const belongsToCheckout = parsed.pathname === `/checkout/${checkoutID}`;
-        const sameToken = parsed.searchParams.get("display_token") === displayToken;
-        return belongsToCheckout && sameToken ? savedURL : fallback;
-    }
-    catch {
-        return fallback;
-    }
-}
 function checkoutCardURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
     return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;

package/dist/src/commands/checkout_handoff.js

@@ -1,13 +1,63 @@
-export * from "../render/checkout_handoff.js";
-import { CommandContractError } from "../services/shared/envelope.js";
-// Presentation owns the clock, original cart and payment facts for every handoff.
-export function assertCheckoutPayable(checkout, authoritative, cartID, sourceExecutionID) {
-    const current = authoritative?.checkout ?? checkout.checkout;
-    const payableStates = ["draft", "quote_bound", "auth_required", "payment_required"];
-    const deadlineClosed = authoritative?.payment_remaining_seconds === 0 ||
-        (current.expires_at !== undefined && (!authoritative?.server_now || Date.parse(current.expires_at) <= Date.parse(authoritative.server_now)));
-    if ((current.cart_id && current.cart_id !== cartID) || !payableStates.includes(current.status) || authoritative?.payment_intents.some(intent => !["failed", "cancelled", "expired"].includes(intent.status)) || deadlineClosed || !checkout.display_token) {
-        throw new CommandContractError("checkout_not_payable", "original checkout is not a current payable entry", "原Checkout不可作为新付款入口；核对原订单。过期不续期，付款处理中或未知不重放，不换购物车或幂等键创建替代购买。", sourceExecutionID ? [{ command: `itpay services next ${sourceExecutionID} --json`, reason: "读取来源执行的原订单与付款事实" }] : [], undefined, { cart_id: cartID, checkout_id: current.checkout_id, checkout_status: current.status,
-            reason: deadlineClosed ? "payment_window_closed" : "checkout_not_payable" });
+import { buildOpenClawTelegramAction } from "../render/telegram.js";
+export function shouldPrepareLocalCheckoutImage(platform) {
+    return platform === "markdown";
+}
+export function isWorkBuddyPlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "workbuddy" && platform === "plain_chat";
+}
+export function isZCodePlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "zcode" && platform === "plain_chat";
+}
+export function isLinkOnlyBrowserAgent(agentType, platform) {
+    return isWorkBuddyPlainChat(agentType, platform) || isZCodePlainChat(agentType, platform);
+}
+export function buildWorkBuddyPresentFilesAction(url) {
+    return {
+        tool: "present_files",
+        arguments: { files: [url] },
+    };
+}
+export function buildCheckoutHandoff(input) {
+    const handoff = { url: input.url };
+    const workBuddyAction = isWorkBuddyPlainChat(input.agentType, input.platform);
+    if (workBuddyAction) {
+        handoff.agent_action = buildWorkBuddyPresentFilesAction(input.url);
+    }
+    if (input.platform === "markdown") {
+        if (input.localPath)
+            handoff.qr_local_path = input.localPath;
+        if (input.markdown)
+            handoff.markdown = input.markdown;
+    }
+    else if (input.platform === "plain_chat" && input.qrImageURL && !isLinkOnlyBrowserAgent(input.agentType, input.platform)) {
+        handoff.qr_image_url = input.qrImageURL;
+    }
+    else if (input.platform === "telegram" && input.qrImageURL) {
+        handoff.qr_image_url = input.qrImageURL;
+    }
+    if (input.agentType?.trim().toLowerCase() === "openclaw" && input.platform === "telegram" && input.plan && input.target) {
+        handoff.agent_action = buildOpenClawTelegramAction(input.plan, input.target);
+    }
+    return {
+        handoff,
+        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount),
+    };
+}
+function checkoutHandoffInstruction(agentType, platform, amount) {
+    if (isWorkBuddyPlainChat(agentType, platform)) {
+        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)) {
+        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (platform === "markdown") {
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (platform === "terminal") {
+        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (agentType?.trim().toLowerCase() === "openclaw" && platform === "telegram") {
+        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。`;
     }
+    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

@@ -1 +1,134 @@
-export * from "../services/shared/envelope.js";
+import { HttpError } from "../client/http.js";
+import { resolveOutput } from "../render/sink.js";
+import { declaredAgentType, qualifyItPayCommand } from "../state/agent_type.js";
+import { qualifyBackendCommand } from "../state/config.js";
+export function isTerminalServiceExecutionStatus(status) {
+    return status === "failed" || status === "refunded" || status === "cancelled";
+}
+export function appendFeedbackPostmortemInstruction(instruction, outcome) {
+    const invitation = outcome === "delivered"
+        ? "结果解释完毕后，Agent 必须为同一订单提交一次安全服务复盘；用户评分和评论均可选，只在用户明确给出时忠实附上，不得猜分或上传对话、报告正文、联系方式和原始日志。"
+        : "先完成同一订单的恢复和退款权利解释；处理清楚后，Agent 必须为同一订单提交一次安全服务复盘。只附上用户明确表达的评分或卡壳点，不得猜测。";
+    return `${instruction} ${invitation}`;
+}
+export class CommandContractError extends Error {
+    code;
+    instruction;
+    recovery;
+    constructor(code, message, instruction, recovery) {
+        super(message);
+        this.code = code;
+        this.instruction = instruction;
+        this.recovery = recovery;
+        this.name = "CommandContractError";
+    }
+}
+export function writeCommandEnvelope(value, options = {}) {
+    const out = resolveOutput(options.output);
+    const agentType = options.agentType ?? declaredAgentType();
+    const qualified = qualifyEnvelope(value, agentType);
+    if (options.jsonOutput) {
+        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)
+            out(`${line}\n`);
+    }
+    else {
+        for (const [key, fact] of Object.entries(facts)) {
+            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)) {
+                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)) {
+            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`);
+    if (qualified.recovery.length > 0) {
+        out("recovery:\n");
+        for (const action of qualified.recovery) {
+            out(`  - ${action.command}\n`);
+            out(`    reason: ${action.reason}\n`);
+        }
+    }
+}
+function qualifyEnvelope(value, agentType) {
+    return {
+        ...value,
+        next: value.next ? { ...value.next, command: qualifyBackendCommand(qualifyItPayCommand(value.next.command, agentType)) } : null,
+        recovery: value.recovery.map((action) => ({
+            ...action,
+            command: qualifyBackendCommand(qualifyItPayCommand(action.command, agentType)),
+        })),
+    };
+}
+export function errorRecoveryActions(error) {
+    if (!(error instanceof HttpError))
+        return [];
+    if (error.code === "agent_identity_required") {
+        return [{ id: "inspect_agent_setup", label: "Inspect supported Agent Type setup", command: "itpay install --json" }];
+    }
+    if (error.code === "agent_device_session_required") {
+        return [{
+                id: "read_agent_session_rules",
+                label: "Read ItPay identity and session recovery rules",
+                command: "itpay skill show itpay --json",
+                reason: "The CLI already attempted one automatic session renewal; do not rotate identity or loop retries.",
+            }];
+    }
+    if (error.code === "quota_exhausted" || error.code === "checkout_required") {
+        return [{
+                id: "inspect_service_execution",
+                label: "Inspect Service Execution before checkout",
+                command: "itpay services next <service_execution_id> --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.status === 404) {
+        return [{
+                id: "recover_service_executions",
+                label: "List visible Service Executions and follow their next instruction",
+                command: "itpay services list",
+            }];
+    }
+    if (error.status === 502 || error.status === 503 || error.status === 504) {
+        return [{
+                id: "retry_after_backend_recovers",
+                label: "Retry after the selected official Backend is reachable",
+                command: "itpay readyz",
+            }];
+    }
+    return [];
+}
+export function printErrorRecovery(error, output) {
+    const recovery = errorRecoveryActions(error);
+    if (recovery.length === 0)
+        return;
+    const out = resolveOutput(output);
+    out("recovery:\n");
+    for (const action of recovery) {
+        out(`  - ${action.label}\n`);
+        out(`    ${action.command}\n`);
+    }
+}

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,28 +1,13 @@
-import { HttpError } from "../client/http.js";
-import { serviceAdapter } from "../services/registry.js";
-import { refundStateEnvelope } from "./refund.js";
 import { formatMoney } from "../render/output.js";
 import { appendFeedbackPostmortemInstruction, writeCommandEnvelope } from "./guidance.js";
 export async function runOrder(backend, orderID, options = {}) {
     const order = await backend.getOrder(orderID);
     const [delivery, refundResponse] = await Promise.all([
-        order.status === "delivered" ? backend.getOrderDeliveryAccess(orderID).catch(error => {
-            // Metadata ownership never grants account-protected delivery access.
-            if (error instanceof HttpError && ["not_found", "account_scope_required", "access_denied"].includes(error.code))
-                return undefined;
-            throw error;
-        }) : Promise.resolve(undefined),
+        order.status === "delivered" ? backend.getOrderDeliveryAccess(orderID) : Promise.resolve(undefined),
         backend.listOrderRefunds(orderID),
     ]);
     const lockedRefund = refundResponse.refunds.find((refund) => refund.access_locked);
-    let envelope = orderEnvelope(order, delivery, lockedRefund);
-    for (const identity of order.service_identities ?? []) {
-        const capability = serviceAdapter(identity).aftercare;
-        if (capability) {
-            envelope = await capability.order(backend, order, envelope);
-            break;
-        }
-    }
+    const envelope = orderEnvelope(order, delivery, lockedRefund);
     writeCommandEnvelope(envelope, {
         ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
         ...(options.output ? { output: options.output } : {}),
@@ -34,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: "读取退款的服务器状态" };
         }
@@ -53,32 +38,16 @@ 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: "刷新订单状态" };
     }
-    if (order.status === "partially_refunded") {
-        instruction = "订单已部分退款；核对本次退款金额及其他履约事实，不能推断整单全部退款。平台交付访问按返回权限保持锁定，不恢复旧授权。";
-        next = null;
-    }
     return {
         status: order.status,
         result: {
             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: [],
     };