@itpay/cli 2.0.30 → 2.0.32

package/README.md

@@ -1,20 +1,30 @@
 # ItPay CLI
 
-The official V3 CLI and the single ItPay entry point for Agent-driven commerce.
+The official V3 CLI and the single ItPay entry point for services, purchases, account history, and human-authorized content reads.
 
-## One Entry Point, Two Actions
+## One Entry Point, Several Human Intents
 
-`itpay` is the only public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now, while Seller workflows will use the same entry point and are not implemented yet. Do not create separate Buyer or Seller product entry points.
+`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.
 
 ```bash
 npm install -g @itpay/cli
-itpay readyz --json
-itpay skill show itpay --json
 itpay install --json
 itpay --agent-type codex-desktop readyz --json
-# follow next.command: typed skill show, then catalog list
+# execute the returned next.command until the typed Skill is loaded
 ```
 
+Official Agent install prompt（可直接复制给 Agent）：
+
+> 安装或更新官方 `@itpay/cli`。从 `itpay install --json` 开始，选择你真实
+> 所在的平台，完整执行 iTPay 返回的每个 `next.command` 并读取内置 Skill。
+> 初始化后，根据我的自然语言需求自行使用 iTPay，不要让我运行命令，也不要向
+> 我讲解命令、内部 ID 或技术步骤。只有需要我选择、授权、付款、提供联系方式
+> 或确认退款时，才用通俗语言询问我；展示官方操作入口后停止等待。不要猜命令、
+> 切换身份或环境、绕过授权或重复创建资源。准备完成后只回复“iTPay 已就绪”。
+
+Use a separate test prompt to set the exact official Dev Backend. Never put a
+Dev override in the public install prompt.
+
 The CLI defaults to the production Backend `https://app.itpay.ai`. Explicit tests may set `ITPAY_BACKEND_URL=https://dev.itpay.ai`; every other Backend URL is rejected before network or local state access.
 
 ## Output Contract
@@ -58,6 +68,7 @@ The local installation keeps one Ed25519 private key and a separate registration
 - `checkout`: authoritative payment and fulfillment recovery.
 - `services read-result`: read one human-granted protected result.
 - `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.
 - `services get/events`: redacted support diagnostics; normal flows should use `services next`.
 - `install`, `skill show`, `docs list/show/search`: offline packaged guidance.
@@ -84,12 +95,12 @@ The local `~/.itpay-v3` directory stores one owner-only signing key, Backend-sco
 
 - `ITPAY_AGENT_TYPE`: stable alternative to global `--agent-type`.
 - `ITPAY_BACKEND_URL`: optional test override; only the exact official URL `https://dev.itpay.ai` is accepted. Unset it for production.
-- `ITPAY_BEARER_TOKEN`: account-scoped Buyer session for account-only commands such as `orders`.
+- `ITPAY_BEARER_TOKEN`: optional account-scoped browser session for legacy account reads. Local Agents normally use signed Device Authority plus the time-limited human authorization returned by `vault access`.
 - `ITPAY_CART_SESSION_PATH`: local recovery-state path override.
 - `ITPAY_CURRENCY`: ordinary Cart currency, default `CNY`.
 - `ITPAY_IDEMPOTENCY_KEY`: explicit operation key for deterministic testing; normal use persists operation IDs automatically.
-- `ITPAY_IDE_IMAGE_ATTACH=0`: disable local Checkout image download when the runtime filesystem is read-only.
-- `ITPAY_IDE_IMAGE_DIR_OVERRIDE`: override the local Checkout image directory.
+- `ITPAY_IDE_IMAGE_ATTACH=0`: disable local Checkout and authorization image download when the runtime filesystem is read-only.
+- `ITPAY_IDE_IMAGE_DIR_OVERRIDE`: override the local handoff image directory.
 
 Provider credentials, Buyer identity, payment provider choice, amount, refund policy, quota, grant scope, and delivery access are never client-owned environment settings.
 

package/dist/src/client/backend.js

@@ -58,11 +58,13 @@ export class BackendClient {
     getOrderDeliveryAccess(orderID) {
         return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/delivery-access`);
     }
-    listAccountOrders(limit, status, bearer) {
+    listAccountOrders(limit, status, bearer, cursor) {
         const qs = new URLSearchParams({ limit: String(limit) });
         if (status) {
             qs.set("status", status);
         }
+        if (cursor)
+            qs.set("cursor", cursor);
         return this.http.get(`/v1/me/orders?${qs}`, bearer ? { bearer } : {});
     }
     getVaultAccountStatus() {

package/dist/src/commands/checkout.js

@@ -110,7 +110,7 @@ function terminalCheckoutEnvelope(presentation) {
     const recovery = [];
     if (payment === "verified") {
         status = "completed";
-        instruction = "Backend 已确认这笔付款。不要再次展示付款入口，不要调用 pay，不要创建新 Checkout 或 Execution。现在只执行 next.command，读取同一 Execution 的履约结果。";
+        instruction = "告诉用户：付款已经确认，订单已经记录，不需要再次付款；结果会在同一订单下继续准备，如果最终无法交付，可以从原订单申请退款，处理方式由内容是否已使用决定。然后只执行 next.command 读取同一笔服务；Agent 不再展示付款入口或创建新订单，也不承诺退款结果。";
         next = serviceExecutionIDs.length === 1
             ? { command: `itpay services next ${serviceExecutionIDs[0]} --json`, reason: "读取同一笔已付款 Service Execution" }
             : presentation.completed_order_id

package/dist/src/commands/guidance.js

@@ -57,49 +57,6 @@ export function writeCommandEnvelope(value, options = {}) {
         }
     }
 }
-export function attachAgentGuidance(payload, guidance) {
-    return {
-        ...payload,
-        agent_guidance: guidance,
-    };
-}
-export function printAgentGuidance(guidance, output) {
-    const out = resolveOutput(output);
-    const agentType = declaredAgentType();
-    out(`${guidance.summary}\n`);
-    if (guidance.visible_results?.length) {
-        out("results:\n");
-        for (const item of guidance.visible_results) {
-            out(`  ${item.rank}. ${item.title}\n`);
-            for (const [key, value] of Object.entries(item.safe_payload)) {
-                if (key === "name" || key === "company_name" || value === "" || value === undefined || value === null)
-                    continue;
-                out(`     ${key}: ${String(value)}\n`);
-            }
-        }
-    }
-    if (guidance.next_actions.length === 0) {
-        out("next actions: none\n");
-    }
-    else {
-        out("next actions:\n");
-        for (const action of guidance.next_actions) {
-            out(`  - ${action.label}\n`);
-            out(`    ${qualifyBackendCommand(qualifyItPayCommand(action.command, agentType))}\n`);
-            if (action.requires_human)
-                out("    requires human confirmation\n");
-            if (action.reason)
-                out(`    reason: ${action.reason}\n`);
-        }
-    }
-    if (guidance.recovery.length > 0) {
-        out("recovery:\n");
-        for (const action of guidance.recovery) {
-            out(`  - ${action.label}\n`);
-            out(`    ${qualifyBackendCommand(qualifyItPayCommand(action.command, agentType))}\n`);
-        }
-    }
-}
 function qualifyEnvelope(value, agentType) {
     return {
         ...value,
@@ -110,181 +67,31 @@ function qualifyEnvelope(value, agentType) {
         })),
     };
 }
-export function buildCartGuidance(cart, serviceModel) {
-    const serviceLine = latestServiceLine(cart);
-    if (serviceLine?.service_execution_id) {
-        const serviceGuidance = serviceModel
-            ? buildServiceReadModelGuidance(serviceModel)
-            : buildServiceHandleGuidance(serviceLine.service_execution_id, serviceLine.service_capability_id);
-        return {
-            ...serviceGuidance,
-            kind: "cart_service_execution",
-            summary: `cart ${cart.cart_id}: service-backed line ${lineID(serviceLine)} is ready for Service Execution`,
-            state: {
-                ...serviceGuidance.state,
-                cart_id: cart.cart_id,
-                cart_item_id: lineID(serviceLine),
-                service_capability_id: serviceLine.service_capability_id,
-            },
-        };
-    }
-    if (cart.items.length === 0) {
-        return {
-            kind: "empty_cart",
-            summary: `cart ${cart.cart_id}: empty`,
-            state: { cart_id: cart.cart_id, status: cart.status },
-            next_actions: [
-                {
-                    id: "browse_catalog",
-                    label: "Browse services",
-                    command: "itpay catalog list",
-                },
-            ],
-            recovery: [],
-        };
-    }
-    return {
-        kind: "cart_checkout_ready",
-        summary: `cart ${cart.cart_id}: ready for checkout`,
-        state: { cart_id: cart.cart_id, status: cart.status, amount_minor: cart.amount_minor, currency: cart.currency },
-        next_actions: [
-            {
-                id: "checkout_cart",
-                label: "Create ItPay checkout",
-                command: `itpay buy --cart ${cart.cart_id} --host <client> --contact-email <email>`,
-                requires_human: true,
-                reason: "The human must review and pay on the ItPay checkout page.",
-            },
-        ],
-        recovery: [
-            {
-                id: "show_cart",
-                label: "Inspect current server cart",
-                command: "itpay cart show",
-            },
-        ],
-    };
-}
-export function buildServiceStartedGuidance(response) {
-    return buildServiceGuidance({
-        execution: response.execution,
-        capabilities: response.capabilities,
-    });
-}
-export function buildServiceReadModelGuidance(model) {
-    return buildServiceGuidance({
-        execution: model.execution,
-        capabilities: model.capabilities,
-        resultItems: model.result_items,
-        checkoutBindings: model.checkout_bindings,
-        deliveryBindings: model.delivery_bindings,
-    });
-}
-export function buildServiceInvokedGuidance(response, capabilities = []) {
-    return buildServiceGuidance({
-        execution: response.execution,
-        capabilities,
-        resultItems: response.result_items,
-        ...(response.next_actions ? { backendNextActions: response.next_actions } : {}),
-        ...(response.effective_quota ? { effectiveQuota: response.effective_quota } : {}),
-        providerCalled: response.provider_called,
-    });
-}
-export function buildServiceActionGuidance(action) {
-    const serviceExecutionID = action.service_execution_id;
-    return {
-        kind: "service_action_recorded",
-        summary: `service execution ${serviceExecutionID}: action ${action.action_type} recorded`,
-        state: {
-            service_execution_id: serviceExecutionID,
-            action_type: action.action_type,
-            status: action.status,
-            result_item_id: action.result_item_id,
-        },
-        next_actions: [
-            {
-                id: "inspect_service_execution",
-                label: "Read updated Service Execution state",
-                command: `itpay services next ${serviceExecutionID} --json`,
-            },
-        ],
-        recovery: [
-            {
-                id: "timeline",
-                label: "Inspect full timeline",
-                command: `itpay services get ${serviceExecutionID}`,
-            },
-        ],
-    };
-}
-export function buildServiceHandleGuidance(serviceExecutionID, checkoutCapabilityID) {
-    const actions = [
-        {
-            id: "inspect_service_execution",
-            label: "Read Service Execution state and capabilities",
-            command: `itpay services next ${serviceExecutionID} --json`,
-        },
-    ];
-    if (checkoutCapabilityID) {
-        actions.push({
-            id: "checkout_service",
-            label: "Create checkout after human confirmation",
-            command: `itpay services checkout ${serviceExecutionID} --capability ${checkoutCapabilityID} --json`,
-            requires_human: true,
-            reason: "Inspect the Service Execution first; the CLI will request delivery contact only when the selected capability requires it.",
-        });
-    }
-    return {
-        kind: "service_execution_handle",
-        summary: `service execution ${serviceExecutionID}: inspect before invoking`,
-        state: { service_execution_id: serviceExecutionID },
-        next_actions: actions,
-        recovery: [],
-    };
-}
 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",
-            },
-        ];
+        return [{ id: "inspect_agent_setup", label: "Inspect supported Agent Type setup", command: "itpay install --json" }];
     }
     if (error.code === "agent_device_session_required") {
-        return [
-            {
+        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 [
-            {
+        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: "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",
@@ -293,22 +100,18 @@ export function errorRecoveryActions(error) {
         ];
     }
     if (error.status === 404) {
-        return [
-            {
+        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 [
-            {
+        return [{
                 id: "retry_after_backend_recovers",
                 label: "Retry after the selected official Backend is reachable",
                 command: "itpay readyz",
-            },
-        ];
+            }];
     }
     return [];
 }
@@ -323,207 +126,3 @@ export function printErrorRecovery(error, output) {
         out(`    ${action.command}\n`);
     }
 }
-function buildServiceGuidance(input) {
-    const execution = input.execution;
-    const capabilities = input.capabilities ?? [];
-    const prePurchase = firstPrePurchaseCapability(capabilities);
-    const paid = firstPaidCapability(capabilities);
-    const resultItem = input.resultItems?.[0];
-    const checkoutID = input.checkoutBindings?.at(-1)?.checkout_id;
-    const delivery = input.deliveryBindings?.[0];
-    const deliveryMode = String(delivery?.redacted_summary?.delivery_mode ?? (delivery?.vault_artifact_id ? "vault_artifact" : ""));
-    const backendCheckout = input.backendNextActions?.find((action) => action.kind === "create_checkout");
-    const nextActions = [];
-    const recovery = [
-        {
-            id: "timeline",
-            label: "Inspect full timeline",
-            command: `itpay services get ${execution.service_execution_id}`,
-        },
-    ];
-    if (isTerminalServiceExecutionStatus(execution.status)) {
-        // Terminal executions are inspectable, but no command may advance or replay them.
-    }
-    else if (deliveryMode === "agent_visible_result" && (input.resultItems?.length ?? 0) > 0) {
-        nextActions.push({
-            id: "use_agent_visible_result",
-            label: "Use the safe candidate list shown above",
-            command: `itpay services next ${execution.service_execution_id} --json`,
-            reason: "This result is already visible to the agent. Do not call services read-result; that command is only for Vault deliveries authorized by a human.",
-        });
-    }
-    else if (execution.status === "completed" || execution.next_action === "completed") {
-        nextActions.push({
-            id: "inspect_order_or_grant",
-            label: "Inspect order, claim, or grant from the checkout/order owner",
-            command: "itpay orders --limit 20",
-            requires_human: true,
-            reason: "Delivery visibility is controlled by the human account and grant flow.",
-        });
-    }
-    else if (execution.phase === "delivery" || execution.next_action === "view_delivery") {
-        const grantStatus = String(delivery?.grant_status ?? "");
-        if (grantStatus === "active") {
-            nextActions.push({
-                id: "read_granted_result",
-                label: "Read the human-granted service result",
-                command: `itpay services read-result ${execution.service_execution_id}`,
-                reason: "The human granted temporary agent access to this delivery.",
-            });
-        }
-        else {
-            nextActions.push({
-                id: grantStatus === "expired" ? "ask_human_to_reauthorize" : "wait_for_human_agent_grant",
-                label: grantStatus === "expired" ? "Ask the human to authorize AI access again" : "Wait for human AI-access authorization",
-                command: `itpay services get ${execution.service_execution_id}`,
-                requires_human: true,
-                reason: grantStatus === "expired"
-                    ? "The 15 minute human grant expired."
-                    : "The human must approve AI access on the Credential page.",
-            });
-        }
-    }
-    else if (execution.next_action === "pay_checkout" || execution.status === "checkout_pending") {
-        nextActions.push({
-            id: "open_existing_checkout",
-            label: "Open the existing ItPay checkout handoff",
-            command: `itpay services checkout ${execution.service_execution_id} --resume --json`,
-            requires_human: true,
-            reason: checkoutID
-                ? `Checkout ${checkoutID} already exists; reissue a short-lived handoff without creating another checkout.`
-                : "Recover the existing checkout handoff from Service Execution owner facts.",
-        });
-    }
-    else if (execution.checkout_required || execution.next_action === "create_checkout") {
-        const capabilityID = backendCheckout?.capability_id ?? paid?.capability_id ?? input.checkoutCapabilityID ?? execution.current_capability_id;
-        if (capabilityID) {
-            const checkoutCapability = capabilities.find((capability) => capability.capability_id === capabilityID);
-            const emailRequired = checkoutCapability?.delivery_email_required === true;
-            nextActions.push({
-                id: "checkout_service",
-                label: "Create ItPay checkout for the paid service capability",
-                command: `itpay services checkout ${execution.service_execution_id} --capability ${capabilityID}${emailRequired ? " --email <email>" : ""} --json`,
-                requires_human: true,
-                reason: emailRequired
-                    ? deliveryEmailGuidance(checkoutCapability?.delivery_email_purpose)
-                    : "This capability returns an agent-visible result after payment and does not require a delivery email.",
-            });
-        }
-        else {
-            nextActions.push({
-                id: "inspect_capabilities",
-                label: "Inspect capabilities before checkout",
-                command: `itpay services get ${execution.service_execution_id}`,
-            });
-        }
-    }
-    else if ((input.providerCalled || execution.next_action === "select_candidate") && (input.resultItems?.length ?? 0) === 0) {
-        // Terminal empty result: a later explicit human request starts a new flow.
-    }
-    else if (needsHumanSelection(execution, resultItem)) {
-        nextActions.push({
-            id: "select_result_item",
-            label: "Ask the human to select a result item, then submit the selection",
-            command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank>`,
-            requires_human: true,
-            reason: "Do not choose a candidate without explicit human confirmation.",
-        });
-    }
-    else if (prePurchase) {
-        const action = {
-            id: "invoke_capability",
-            label: `Invoke ${prePurchase.capability_id}`,
-            command: `itpay services invoke ${execution.service_execution_id} --capability ${prePurchase.capability_id} --input key=value --json`,
-        };
-        if (prePurchase.free_quota_limit) {
-            action.reason = `One keyword per execution. Free quota limit: ${prePurchase.free_quota_limit} per ${prePurchase.quota_subject || "subject"}.`;
-        }
-        nextActions.push(action);
-    }
-    else {
-        nextActions.push({
-            id: "inspect_service_execution",
-            label: "Read Service Execution state",
-            command: `itpay services next ${execution.service_execution_id} --json`,
-        });
-    }
-    return {
-        kind: "service_execution",
-        summary: `service execution ${execution.service_execution_id}: ${execution.status}/${execution.phase}${input.effectiveQuota ? `, quota ${input.effectiveQuota.remaining}/${input.effectiveQuota.limit}` : ""}`,
-        state: {
-            service_execution_id: execution.service_execution_id,
-            service_id: execution.service_id,
-            status: execution.status,
-            phase: execution.phase,
-            current_capability_id: execution.current_capability_id,
-            checkout_required: execution.checkout_required,
-            next_action: execution.next_action,
-            delivery: delivery
-                ? {
-                    status: delivery.status,
-                    delivery_mode: deliveryMode || undefined,
-                    vault_artifact_id: delivery.vault_artifact_id,
-                    vault_status: delivery.vault_status,
-                    vault_payload_state: delivery.vault_payload_state,
-                    reveal_status: delivery.reveal_status,
-                    grant_status: delivery.grant_status ?? "missing",
-                    grant_expires_at: delivery.grant_expires_at,
-                }
-                : undefined,
-            capabilities: capabilities.map((capability) => ({
-                capability_id: capability.capability_id,
-                agent_visible: capability.agent_visible,
-                requires_payment: capability.requires_payment,
-                vault_required: capability.vault_required,
-                delivery_email_required: capability.delivery_email_required,
-                delivery_email_purpose: capability.delivery_email_purpose,
-                price_amount_minor: capability.price_amount_minor,
-                price_currency: capability.price_currency,
-                free_quota_limit: capability.free_quota_limit,
-            })),
-            result_items: (input.resultItems ?? []).map((item) => ({
-                result_item_id: item.service_capability_result_item_id,
-                rank: item.rank,
-                display_title: item.display_title,
-                safe_payload: item.safe_payload,
-            })),
-            effective_quota: input.effectiveQuota,
-        },
-        next_actions: nextActions,
-        recovery,
-        ...(input.resultItems?.length
-            ? { visible_results: input.resultItems.map((item) => ({ rank: item.rank, title: item.display_title, safe_payload: item.safe_payload })) }
-            : {}),
-    };
-}
-function deliveryEmailGuidance(purpose) {
-    switch (purpose) {
-        case "receipt":
-            return "Ask the human for their email. It is used to send the order receipt; never invent or substitute an address.";
-        case "claim":
-            return "Ask the human for their email. It is used to send the protected result claim link; never invent or substitute an address.";
-        case "receipt_and_claim":
-            return "Ask the human for their email. It is used to send the order receipt and protected result claim link; never invent or substitute an address.";
-        default:
-            return "Ask the human for the required email and state only the Backend-declared purpose; never invent or substitute an address.";
-    }
-}
-function firstPrePurchaseCapability(capabilities) {
-    return capabilities.find((capability) => capability.agent_visible && !capability.requires_payment)
-        ?? capabilities.find((capability) => capability.agent_visible);
-}
-function firstPaidCapability(capabilities) {
-    return (capabilities.find((capability) => capability.requires_payment && capability.vault_required) ??
-        capabilities.find((capability) => capability.requires_payment));
-}
-function needsHumanSelection(execution, resultItem) {
-    if (execution.phase !== "pre_purchase")
-        return false;
-    return execution.next_action === "select_candidate" || execution.next_action === "human_action_required" || resultItem !== undefined;
-}
-function latestServiceLine(cart) {
-    return [...cart.items].reverse().find((item) => item.service_execution_id);
-}
-function lineID(line) {
-    return line.cart_item_id ?? line.line_item_id ?? line.checkout_item_id ?? "<unknown_line>";
-}

package/dist/src/commands/install.js

@@ -25,7 +25,7 @@ export function runInstall(target, options = {}) {
         writeCommandEnvelope({
             status: "install_targets",
             result: { agent_types: agentTypes },
-            instruction: "选择当前真实运行环境；同一 Agent 不要临时更换 Agent Type。",
+            instruction: "识别当前真实运行平台，从 result.agent_types 选择对应 agent_type，并由 Agent 自行运行 itpay install <agent_type> --json；不要让用户运行命令，也不要临时更换 Agent Type。",
             next: null,
             recovery: [{ command: "itpay docs show install-and-setup", reason: "查看安装与环境说明" }],
         }, {

package/dist/src/commands/order.js

@@ -19,17 +19,27 @@ function orderEnvelope(order, delivery, lockedRefund) {
     let instruction = "订单状态已读取；当前没有可用交付入口。";
     let next = null;
     if (lockedRefund) {
-        instruction = "退款访问锁已生效；不要 reveal、创建 grant 或读取交付结果。";
+        instruction = "告诉用户退款处理中，原交付已按政策冻结。然后读取同一退款的权威状态；Agent 不读取交付、不创建授权或重复申请退款。";
         if (!refundTerminal) {
             next = { command: `itpay refund get ${lockedRefund.refund_request_id} --json`, reason: "读取退款的服务器状态" };
         }
     }
     else if (delivery?.service_execution_id) {
-        instruction = "根据 delivery_mode 使用对应读取入口；不要从订单摘要猜测受保护内容。";
+        instruction = "告诉用户订单已经找到并说明当前交付状态。然后使用返回的读取入口；Agent 不向用户提及 delivery_mode，也不从订单摘要猜测受保护内容。";
         next = { command: `itpay services next ${delivery.service_execution_id} --json`, reason: "读取交付状态" };
     }
+    else if (order.status === "failed") {
+        instruction = "先告诉用户这笔订单没有正常交付，不需要重复付款或重新下单；先检查原订单是否已有退款，再由用户决定是否申请。";
+        next = { command: `itpay refund list --order ${order.order_id} --json`, reason: "检查同一订单的退款状态" };
+    }
+    else if (order.status === "refunded") {
+        instruction = "先告诉用户这笔订单已经退款，原交付不可继续读取；不要再次付款或尝试恢复旧授权。";
+    }
+    else if (order.status === "cancelled") {
+        instruction = "先告诉用户这笔订单已经取消，没有可继续的付款或交付；不要创建替代订单，除非用户另行提出新的购买。";
+    }
     else if (!["delivered", "refunded", "failed", "cancelled"].includes(order.status)) {
-        instruction = "订单尚未进入交付终态；稍后查询同一订单，不要创建替代订单。";
+        instruction = "先告诉用户订单仍在处理，已记录的付款和订单不需要重复创建；稍后查询同一订单，不要创建替代订单。";
         next = { command: `itpay order ${order.order_id} --json`, reason: "刷新订单状态" };
     }
     return {