@itpay/cli 2.1.33 → 2.1.40

package/dist/src/client/backend.js

@@ -103,6 +103,11 @@ export class BackendClient {
     readBuyerVaultArtifact(artifactRef, sections) {
         return this.http.post(`/v1/vault/artifacts/${encodeURIComponent(artifactRef)}/reads`, sections.length ? { sections } : {});
     }
+    listRailAftercare(orderID) { return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/rail-aftercare`); }
+    createRailAftercare(orderID, input, idempotencyKey) { return this.http.post(`/v1/orders/${encodeURIComponent(orderID)}/rail-aftercare`, input, { idempotencyKey }); }
+    getRailAftercare(id) { return this.http.get(`/v1/rail-aftercare/${encodeURIComponent(id)}`); }
+    respondRailAftercare(id, input) { return this.http.post(`/v1/rail-aftercare/${encodeURIComponent(id)}/respond`, input); }
+    cancelRailAftercare(id, input) { return this.http.post(`/v1/rail-aftercare/${encodeURIComponent(id)}/cancel`, input); }
     // --- Refund ---
     createRefund(orderID, input, bearer, idempotencyKey) {
         const options = { ...(bearer ? { bearer } : {}), ...(idempotencyKey ? { idempotencyKey } : {}) };

package/dist/src/commands/aftercare.js

@@ -0,0 +1,12 @@
+import { serviceAdapter } from "../services/registry.js";
+import { CommandContractError } from "../services/shared/envelope.js";
+function adapter(identity) {
+    const capability = serviceAdapter(identity).aftercare;
+    if (!capability)
+        throw new CommandContractError("aftercare_unsupported", "Locked service does not support this aftercare operation", "使用原服务声明的售后入口，不套用其他业务规则。", []);
+    return capability;
+}
+export async function runAftercareList(backend, orderID) { const value = await backend.listRailAftercare(orderID); return adapter(value.execution_identity).directory(value, orderID); }
+export async function runAftercareGet(backend, id) { const value = await backend.getRailAftercare(id); return adapter(value.execution_identity).present(value); }
+export async function runAftercareCreate(backend, config, orderID, input) { const value = await backend.listRailAftercare(orderID); return adapter(value.execution_identity).create(backend, config, orderID, input); }
+export async function runAftercareRespond(backend, id, input, cancel = false) { const value = await backend.getRailAftercare(id); return adapter(value.execution_identity).respond(backend, id, input, cancel); }

package/dist/src/commands/buy.js

@@ -1,13 +1,4 @@
-// V3 `buy` flow:
-//   1. validate client context (host/target)
-//   2. create cart via POST /v1/carts
-//   3. create checkout via POST /v1/checkouts (consumes the cart)
-//   4. build a checkout_qr render plan + dispatch to host renderer
-//   5. [--pay] create payment intent → render payment QR → optionally SSE wait
-//   6. [--json] output JSON instead of terminal text
-//
-// The display token is passed to the renderer and persisted in the local cart
-// session so a restarted agent can resume the same checkout.
+import { buildCheckoutQRPlan } from "../render/checkout_plan.js";
 import { operationID } from "../state/config.js";
 import { validateContext } from "../state/client_context.js";
 import { dispatchRender } from "../render/index.js";
@@ -17,8 +8,7 @@ import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { formatMoney } from "../render/output.js";
 import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
-import { buildCheckoutHandoff, isLinkOnlyBrowserAgent, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
-import { qualifyItPayCommand } from "../state/agent_type.js";
+import { assertCheckoutPayable, buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
 export async function runBuy(backend, config, options) {
     const err = validateContext(options.host, options.target);
     if (err) {
@@ -62,6 +52,15 @@ export async function runBuy(backend, config, options) {
         ...(options.contact ? { delivery_contact: options.contact } : {}),
     };
     const checkout = await backend.createCheckout(checkoutRequest, idempotencyKey);
+    const authoritative = checkout.display_token
+        ? await backend.getCheckoutPresentation(checkout.checkout.checkout_id, checkout.display_token)
+        : undefined;
+    assertCheckoutPayable(checkout, authoritative, cart.cart_id, latestLine?.service_execution_id);
+    const current = authoritative?.checkout ?? checkout.checkout;
+    // Only the returned checkout's items are authoritative for the handoff.
+    if (!authoritative)
+        throw new Error("checkout presentation unavailable");
+    cart = { ...cart, items: authoritative.items, amount_minor: current.amount_minor, currency: current.currency };
     options.cartSession.rememberCheckout({
         checkoutID: checkout.checkout.checkout_id,
         displayToken: checkout.display_token,
@@ -245,50 +244,6 @@ async function waitForPaymentSSE(backend, checkoutID, displayToken, timeoutSec)
         });
     });
 }
-// --- checkout QR plan ---
-export function buildCheckoutQRPlan(input) {
-    const summary = input.localSimulation ? "在本机打开模拟付款入口；铁路与地图查询真实，授权、通知和交易模拟，不会扣款。" : `Scan the QR or open ${input.checkoutURL} to start the human checkout flow.`;
-    const isPayment = input.paymentIntentID != null;
-    const afterCommand = qualifyItPayCommand(`itpay checkout --id ${input.checkoutID} --token ${input.displayToken}${input.locale === "en" ? " --locale en" : ""} --json`, input.agentType);
-    const platform = {
-        text: summary,
-        links: [
-            { label: "打开付款页面", url: input.checkoutURL },
-        ],
-        buttons: [
-            { label: "打开收银台", kind: "url", url: input.checkoutURL },
-            ...(input.checkoutID
-                ? [{ label: "查询 Checkout 状态", kind: "callback", intent: "check_checkout_status", ref: input.checkoutID }]
-                : []),
-        ],
-        blocks: [],
-        ...(input.qrPNGURL ? { media: [{ url: input.qrPNGURL, label: "Branded QR", mimeType: "image/png" }] } : {}),
-    };
-    const plan = {
-        kind: isPayment ? "payment_qr" : "checkout_qr",
-        ...(input.localSimulation ? { localSimulation: true } : {}),
-        host: input.host,
-        summary,
-        url: input.qrPayload,
-        ...(isLinkOnlyBrowserAgent(input.agentType, platformKeyForHost(input.host)) && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
-        preferredQRSources: [input.qrPNGURL ?? input.qrPayload],
-        checkoutID: input.checkoutID,
-        platform,
-        afterActionCommand: afterCommand,
-        afterActionLabel: "扫码或点击链接完成支付后，执行以下命令查询状态：",
-    };
-    if (input.orderItems)
-        plan.orderItems = input.orderItems;
-    if (input.orderCurrency)
-        plan.orderCurrency = input.orderCurrency;
-    if (input.paymentMethod)
-        plan.paymentMethod = input.paymentMethod;
-    if (input.paymentStatus)
-        plan.paymentStatus = input.paymentStatus;
-    if (input.paymentIntentID)
-        plan.paymentIntentID = input.paymentIntentID;
-    return plan;
-}
 function fallbackCardURL(baseURL, checkoutID, displayToken) {
     const root = baseURL.replace(/\/$/, "");
     return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;
@@ -330,3 +285,4 @@ function absolutePublicURL(baseURL, value) {
         return value;
     }
 }
+export { buildCheckoutQRPlan } from "../render/checkout_plan.js";

package/dist/src/commands/cart.js

@@ -117,6 +117,8 @@ export async function runCartAddQuoteServer(options) {
         status: "quote_added",
         result: {
             cart_id: cart.cart_id,
+            service_quote_lock_id: options.serviceQuoteLockID,
+            service_execution_id: line.service_execution_id,
             item_count: cart.items.length,
             total: formatMoney(cart.amount_minor, cart.currency),
         },

package/dist/src/commands/catalog.js

@@ -1,7 +1,7 @@
 import { writeCommandEnvelope } from "./guidance.js";
 export async function runCatalogList(backend, options = {}) {
     const manifest = await backend.getCatalogManifest();
-    const services = manifest.manifest.items.map(summarizeService);
+    const services = manifest.manifest.items.map(item => summarizeService(item, options.locale ?? "zh-CN"));
     const firstServiceID = manifest.manifest.items.find((item) => item.service_id)?.service_id;
     const empty = services.length === 0;
     const jsonFlag = options.jsonOutput ? " --json" : "";
@@ -10,7 +10,7 @@ export async function runCatalogList(backend, options = {}) {
         result: { catalog_version: manifest.version, services },
         instruction: empty
             ? "当前没有已发布服务；本次目录读取结束，不猜测服务或自动重试。"
-            : "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
+            : options.locale === "en" ? "Explain the service, its operations and pricing; start only the declared operation matching the human request." : "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
         next: services.length === 1 && firstServiceID
             ? { command: `itpay services start ${firstServiceID}${jsonFlag}`, reason: "仅当当前服务符合用户请求时读取输入合同；不表示购买同意" }
             : null,
@@ -20,7 +20,18 @@ export async function runCatalogList(backend, options = {}) {
         plainResult: catalogPlainLines(manifest.version, services),
     });
 }
-function summarizeService(item) {
+function summarizeService(item, locale) {
+    const definition = item.service_definition;
+    if (definition) {
+        if (definition.schema_version !== "itpay.service-definition.v1")
+            return { service_id: item.service_id, title: item.title, description: "服务定义版本不受支持；升级CLI后读取，不猜操作。" };
+        return {
+            service_id: definition.service_id, title: definition.display_names[locale] ?? item.title,
+            entry: `itpay services start ${definition.service_id} --json`, definition_version: definition.definition_version,
+            ...(definition.guide ? { guide: `itpay docs show ${definition.guide.topic}` } : {}),
+            operations: definition.operations.map(op => ({ operation_id: op.id, title: op.display_names[locale], role: op.role, price: op.billing_mode === "dynamic" ? (locale === "en" ? (definition.adapter_key === "rail.v1" ? "Live quote; free queries do not mean free tickets" : "Live quote; confirm the locked amount") : (definition.adapter_key === "rail.v1" ? "实时报价；免费查询不等于免费车票" : "实时报价，以锁定报价为准")) : op.billing_mode === "free" ? (locale === "en" ? "Free query" : "免费查询") : typeof op.price_amount_minor === "number" && op.price_currency ? formatProductMoney(op.price_amount_minor, op.price_currency) : (locale === "en" ? "Fixed price missing; stop purchase preparation" : "固定价格事实缺失；停止准备购买"), requires_continuation: op.requires_continuation ?? false })),
+        };
+    }
     const flow = item.service_flow;
     const offer = item.variants?.[0];
     return {
@@ -28,11 +39,10 @@ function summarizeService(item) {
         ...(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" } : {}),
         ...(flow ? {
             discovery: {
                 title: flow.discovery.title,
-                description: flow.discovery.description,
+                description: flow.discovery.description ?? "",
                 ...(flow.discovery.free_quota_limit !== undefined ? { free_quota: flow.discovery.free_quota_limit } : {}),
                 ...(flow.discovery.paid_continuation ? {
                     paid_price: formatProductMoney(flow.discovery.paid_continuation.amount_minor, flow.discovery.paid_continuation.currency),
@@ -40,7 +50,7 @@ function summarizeService(item) {
             },
             primary_offer: {
                 title: flow.primary_service.title,
-                description: flow.primary_service.description,
+                description: flow.primary_service.description ?? "",
                 price: formatProductMoney(flow.primary_service.amount_minor, flow.primary_service.currency),
             },
         } : offer ? {
@@ -60,20 +70,25 @@ function catalogPlainLines(version, services) {
         if (service.entry)
             lines.push(`  entry: ${String(service.entry)}`);
         if (service.guide)
-            lines.push(`  entry: ${String(service.guide)}`);
+            lines.push(`  guide: ${String(service.guide)}`);
         if (service.description)
             lines.push(`  description: ${String(service.description)}`);
+        if (Array.isArray(service.operations))
+            for (const op of service.operations)
+                lines.push(`  operation: ${String(op.operation_id)} — ${String(op.title)}; ${String(op.price)}`);
         const discovery = service.discovery;
         if (discovery) {
             const quota = discovery.free_quota !== undefined ? `; free_quota: ${String(discovery.free_quota)}` : "";
             const paid = discovery.paid_price ? `; paid_price: ${String(discovery.paid_price)}` : "";
             lines.push(`  discovery: ${String(discovery.title)}${quota}${paid}`);
-            lines.push(`    ${String(discovery.description)}`);
+            if (discovery.description)
+                lines.push(`    ${String(discovery.description)}`);
         }
         const primary = service.primary_offer;
         if (primary) {
             lines.push(`  primary_offer: ${String(primary.title)}; price: ${String(primary.price)}`);
-            lines.push(`    ${String(primary.description)}`);
+            if (primary.description)
+                lines.push(`    ${String(primary.description)}`);
         }
     }
     return lines;

package/dist/src/commands/checkout_handoff.js

@@ -1,101 +1,13 @@
-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] },
-    };
-}
-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 workBuddyAction = isWorkBuddyPlainChat(input.agentType, input.platform);
-    if (workBuddyAction) {
-        handoff.agent_action = buildWorkBuddyPresentFilesAction(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: input.plan?.localSimulation
-            ? `本地实验：铁路与地图查询真实，授权、通知和交易模拟，不会扣款。在本机打开 handoff.url 模拟付款入口，金额 ${input.amount}；仅本机桌面可达。${workBuddyAction ? "按 handoff.agent_action 原样打开一次。" : "展示原入口。"}等待用户操作后读取同一 Checkout；不创建替代订单，用户声明不证明模拟付款已确认。`
-            : checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(mobileUrl)),
-    };
-}
-function checkoutHandoffInstruction(agentType, platform, amount, hasMobileLink) {
-    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；用户的话不是付款成功证明。`;
-    }
-    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；用户的话不是付款成功证明。`;
-    }
-    if (platform === "markdown") {
-        const mobileSentence = hasMobileLink ? "，并附 handoff.mobile_url 供手机端点击直达支付" : "";
-        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见${mobileSentence}，然后停止等待。不要创建新 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；用户的话不是付款成功证明。`;
-    }
-    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。`;
+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" });
     }
-    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；用户的话不是付款成功证明。`;
 }

package/dist/src/commands/guidance.js

@@ -1,184 +1 @@
-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;
-    interaction;
-    result;
-    constructor(code, message, instruction, recovery, interaction, result) {
-        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);
-        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`);
-        }
-    }
-    else {
-        for (const [key, fact] of Object.entries(facts)) {
-            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)) {
-                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)) {
-            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  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`);
-    }
-    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,
-        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,
-            command: qualifyBackendCommand(qualifyItPayCommand(action.command, 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 [];
-    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 list --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.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`);
-    }
-}
+export * from "../services/shared/envelope.js";

package/dist/src/commands/install.js

@@ -12,6 +12,7 @@ export const INSTALL_AGENT_TYPES = [
     "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；付款交接只应显示在用户可见终端。",
@@ -48,7 +49,7 @@ export function runInstall(target, options = {}) {
             ...installDefinition(normalized),
             default_api: DEFAULT_BASE_URL,
         },
-        instruction: INSTRUCTIONS[normalized],
+        instruction: INSTRUCTIONS[normalized] + (normalized.startsWith("codex-") ? ` ${CODEX_WAIT_GUIDANCE}` : ""),
         next: {
             command: `itpay --agent-type ${normalized} readyz --json`,
             reason: "验证当前官方 ItPay API 的可用性",

package/dist/src/commands/order.js

@@ -1,14 +1,28 @@
+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) : Promise.resolve(undefined),
+        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),
         backend.listOrderRefunds(orderID),
     ]);
     const lockedRefund = refundResponse.refunds.find((refund) => refund.access_locked);
-    const envelope = orderEnvelope(order, delivery, lockedRefund);
+    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;
+        }
+    }
     writeCommandEnvelope(envelope, {
         ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
         ...(options.output ? { output: options.output } : {}),
@@ -50,6 +64,10 @@ function orderEnvelope(order, delivery, lockedRefund) {
         instruction = "先告诉用户订单仍在处理，已记录的付款和订单不需要重复创建；稍后查询同一订单，不要创建替代订单。";
         next = { command: `itpay order ${order.order_id} --json`, reason: "刷新订单状态" };
     }
+    if (order.status === "partially_refunded") {
+        instruction = "订单已部分退款；核对本次退款金额及其他履约事实，不能推断整单全部退款。平台交付访问按返回权限保持锁定，不恢复旧授权。";
+        next = null;
+    }
     return {
         status: order.status,
         result: {