@itpay/cli 2.0.5 → 2.0.8

package/dist/src/commands/services.js

@@ -69,8 +69,7 @@ export async function runServicesInvoke(backend, config, serviceExecutionID, cap
         throw new CommandContractError("capability_not_found", `capability ${capabilityID} is not available on service execution ${serviceExecutionID}`, "使用 Service Execution 当前返回的 capability_id，不要猜测名称。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前可用 capability" }]);
     }
     if (requestedCapability.requires_payment) {
-        const command = quoteCommand(serviceExecutionID, requestedCapability, input);
-        throw new CommandContractError("checkout_required", `capability ${capabilityID} requires checkout and cannot be invoked directly`, "该 capability 需要付款；先向用户确认购买，再创建报价。", [{ command, reason: "锁定可信输入和价格" }]);
+        throw new CommandContractError("checkout_required", `capability ${capabilityID} requires checkout and cannot be invoked directly`, "付费 capability 不能直接 invoke。不要尝试 quote、cart、buy、checkout 或 pay 作为旁路；只恢复同一 Execution 的当前合法动作。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取同一 Execution 的当前合法动作" }]);
     }
     const missingInput = missingRequiredInput(requestedCapability.input_schema, input);
     if (missingInput.length > 0) {
@@ -111,12 +110,12 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
     };
     let status = items.length > 0 ? "result_ready" : "no_result";
     let instruction = items.length > 0
-        ? "向用户展示编号和 safe_payload；用户选择后只在当前 Execution 提交对应 rank，不要新建 Execution。"
+        ? "向用户展示编号和 safe_payload；若候选列表已满足用户目标，在此停止。仅在用户明确选择并希望继续时，才在当前 Execution 提交对应 rank。"
         : "Provider 已返回空结果；不要重放当前 execution，按下一步恢复。";
     let next = null;
     if (response.effective_quota?.exhausted) {
         status = "quota_exhausted";
-        instruction = "免费额度已用完且本次未调用 Provider；先向用户说明价格并确认购买。";
+        instruction = "免费额度已用完且本次没有调用 Provider。当前没有可购买的 continuation；只读取同一 Execution 的服务端恢复方向。";
         const checkoutAction = response.next_actions?.find((action) => action.kind === "create_checkout");
         const checkoutCapability = capabilities.find((capability) => capability.capability_id === checkoutAction?.capability_id);
         if (checkoutCapability) {
@@ -127,9 +126,11 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
                 } : {}),
                 delivery_email_required: checkoutCapability.delivery_email_required,
             };
+            const price = capabilityPrice(checkoutCapability);
+            instruction = purchaseConfirmationInstruction("quota_exhausted", price, checkoutCapability.delivery_email_required);
             next = {
-                command: quoteCommand(response.execution.service_execution_id, checkoutCapability, input),
-                reason: "准备当前服务的付费 continuation 报价",
+                command: checkoutCommand(response.execution.service_execution_id, checkoutCapability, input),
+                reason: `仅在用户明确同意支付 ${price} 后执行；否则停止`,
             };
         }
         else {
@@ -183,12 +184,54 @@ function missingRequiredInput(schema, input) {
         return typeof input[field] === "string" && String(input[field]).trim() === "";
     });
 }
-function checkoutCommand(serviceExecutionID, capability, input) {
+function checkoutCommand(serviceExecutionID, capability, input, fillMissing = true) {
     const lockedInput = { ...input };
-    for (const field of missingRequiredInput(capability.input_schema, lockedInput))
-        lockedInput[field] = "<value>";
+    if (fillMissing) {
+        for (const field of missingRequiredInput(capability.input_schema, lockedInput))
+            lockedInput[field] = "<value>";
+    }
     return `itpay services checkout ${serviceExecutionID} --capability ${capability.capability_id}${formatInputOptions(lockedInput)}${capability.delivery_email_required ? " --email <email>" : ""} --json`;
 }
+function capabilityPrice(capability) {
+    return capability.price_amount_minor !== undefined && capability.price_currency
+        ? formatMoney(capability.price_amount_minor, capability.price_currency)
+        : "当前发布价格";
+}
+function purchaseConfirmationInstruction(context, price, deliveryEmailRequired, candidateTitle = "") {
+    if (context === "quota_exhausted") {
+        return deliveryEmailRequired
+            ? `免费额度已用完，本次没有调用 Provider，也尚未创建 Quote 或 Checkout。现在只向用户说明：继续当前请求需要支付 ${price}，交付还需要用户邮箱；请确认是否购买并提供邮箱。然后停止并等待。用户明确同意并提供真实邮箱前，不要执行 next.command，不要新建 Execution，不要尝试其他 capability、quote、cart、buy、checkout 或 pay 命令。`
+            : `免费额度已用完，本次没有调用 Provider，也尚未创建 Quote 或 Checkout。现在只向用户说明：“继续当前请求需要支付 ${price}，是否购买？”然后停止并等待用户明确回复。用户明确同意前，不要执行 next.command，不要新建 Execution，不要尝试其他 capability、quote、cart、buy、checkout 或 pay 命令。`;
+    }
+    const selected = candidateTitle ? `已选择 ${candidateTitle}。` : "当前候选已经确认。";
+    return deliveryEmailRequired
+        ? `${selected}候选已绑定到当前 Execution，但尚未购买后续服务。现在只向用户说明：继续购买后续服务需要支付 ${price}，并提供用于发送交付认领链接的邮箱；请确认是否购买并提供邮箱。然后停止。用户明确同意并提供真实邮箱前，不要执行 next.command，不要创建新 Execution 或 Checkout。`
+        : `${selected}候选已绑定到当前 Execution，但尚未购买后续服务。现在只向用户说明：“继续购买后续服务需要支付 ${price}，是否购买？”然后停止。用户明确同意前，不要执行 next.command，不要创建新 Execution 或 Checkout。`;
+}
+function paidContinuation(model, action, input) {
+    if (!action.capability_id)
+        return null;
+    const capability = model.capabilities.find((item) => item.capability_id === action.capability_id && item.requires_payment);
+    if (!capability)
+        return null;
+    const price = capabilityPrice(capability);
+    const stateBacked = model.execution.status === "quota_exhausted" || model.execution.status === "human_action_approved";
+    return {
+        capability,
+        price,
+        checkout: {
+            capability_id: capability.capability_id,
+            ...(capability.price_amount_minor !== undefined && capability.price_currency ? {
+                price: { amount_minor: capability.price_amount_minor, currency: capability.price_currency },
+            } : {}),
+            delivery_email_required: capability.delivery_email_required,
+        },
+        next: {
+            command: checkoutCommand(model.execution.service_execution_id, capability, input, !stateBacked),
+            reason: `仅在用户明确同意支付 ${price}${capability.delivery_email_required ? " 并提供真实邮箱" : ""}后执行；否则停止`,
+        },
+    };
+}
 function quoteCommand(serviceExecutionID, capability, input) {
     const lockedInput = { ...input };
     for (const field of missingRequiredInput(capability.input_schema, lockedInput))
@@ -232,14 +275,20 @@ export async function runServicesAction(backend, serviceExecutionID, actionType,
     if (selection && actionType === "select_candidate" && response.status === "approved") {
         const updated = await backend.getServiceExecution(serviceExecutionID);
         const preferred = updated.allowed_actions?.[0];
-        const next = preferred ? serviceAllowedActionCommand(updated, preferred) : null;
+        const continuation = preferred?.type === "prepare_quote"
+            ? paidContinuation(updated, preferred, {})
+            : null;
+        const next = continuation?.next ?? (preferred ? serviceAllowedActionCommand(updated, preferred) : null);
         writeCommandEnvelope({
             status: "candidate_selected",
             result: {
                 service_execution_id: response.service_execution_id,
                 candidate: { rank: selection.rank, title: selection.title },
+                ...(continuation ? { checkout: continuation.checkout } : {}),
             },
-            instruction: "候选已绑定到来源 Execution；后续动作必须继续使用该 Execution。",
+            instruction: continuation
+                ? purchaseConfirmationInstruction("candidate_selected", continuation.price, continuation.capability.delivery_email_required, selection.title)
+                : "候选已绑定到来源 Execution；后续动作必须继续使用该 Execution。",
             next,
             recovery: [{
                     command: `itpay services next ${response.service_execution_id} --json`,
@@ -294,7 +343,9 @@ async function resolveCandidateSelection(backend, serviceExecutionID, actionType
     };
 }
 function actionInputError(serviceExecutionID, message, code = "service_action_invalid") {
-    return new CommandContractError(code, message, "使用当前 safe result 中的合法 action 和 candidate rank；需要人确认时先询问用户。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "重新读取当前可选动作" }]);
+    return new CommandContractError(code, message, code === "candidate_not_found"
+        ? "当前 rank 不存在或当前候选集不可用。不要新建 Execution，不要重新 invoke，不要构造候选 ID；只恢复同一 Execution 当前仍然有效的候选。"
+        : "使用当前 safe result 中的合法 action 和 candidate rank；需要人确认时先询问用户。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "重新读取同一 Execution 的当前可选动作" }]);
 }
 export async function runServicesCheckout(backend, config, serviceExecutionID, capabilityID, options = {}) {
     const deliveryContact = {
@@ -373,7 +424,7 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
         ...(config.baseURL ? { baseURL: config.baseURL } : {}),
         ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
     });
-    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan);
+    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, config.baseURL);
     const plainResult = [
         `service_execution_id: ${response.binding.service_execution_id}`,
         `checkout_id: ${checkoutID}`,
@@ -578,28 +629,35 @@ function servicesNextEnvelope(model) {
         };
     }
     const currentItems = model.current_result_items ?? [];
+    const delivery = model.current_delivery ?? model.delivery_bindings.at(-1);
+    const deliveryMode = serviceDeliveryMode(model);
     const candidateSelection = model.allowed_actions?.find((action) => action.type === "select_candidate");
     if (candidateSelection && currentItems.length > 0) {
+        const paidCapability = delivery?.capability_id
+            ? model.capabilities.find((capability) => capability.capability_id === delivery.capability_id && capability.requires_payment)
+            : undefined;
         return {
             status: "candidate_selection_available",
             result: {
                 service_execution_id: execution.service_execution_id,
+                ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
+                ...(deliveryMode ? { delivery_mode: deliveryMode } : {}),
                 items: currentItems.map((item) => ({
                     rank: item.rank,
                     title: item.display_title,
                     safe_payload: item.safe_payload,
                 })),
             },
-            instruction: "向用户展示编号和 safe_payload；用户选择后只在当前 Execution 提交对应 rank，不要新建 Execution。",
+            instruction: paidCapability
+                ? "付费 Agent-visible 搜索已完成。现在把 items 中的编号、title 和 safe_payload 展示给用户，然后停止；不要调用 read-result。若用户目标只是候选搜索，任务已经完成。只有用户之后明确选择某个候选并要求继续时，才执行 next.command；不要自动购买后续报告。"
+                : "向用户展示编号和 safe_payload；若候选列表已满足用户目标，在此停止。仅在用户明确选择并希望继续时，才在当前 Execution 提交对应 rank。",
             next: {
                 command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
-                reason: "仅在用户明确选择后锁定来源候选",
+                reason: paidCapability ? "仅在用户明确选择候选并要求继续时执行" : "仅在用户明确选择后锁定来源候选",
             },
             recovery: [],
         };
     }
-    const delivery = model.current_delivery ?? model.delivery_bindings.at(-1);
-    const deliveryMode = serviceDeliveryMode(model);
     if (deliveryMode === "agent_visible_result") {
         const items = currentItems.map((item) => ({
             rank: item.rank,
@@ -617,7 +675,7 @@ function servicesNextEnvelope(model) {
             },
             instruction: items.length > 0
                 ? selection
-                    ? "这是当前 Graph 步骤对应的交付。向用户展示编号和 safe_payload；如用户选择，必须在当前 Execution 提交对应 rank。"
+                    ? "Agent-visible 搜索已完成。向用户展示 items 中的编号、title 和 safe_payload，然后停止；不要调用 read-result。只有用户明确选择候选并要求继续时，才执行 next.command。"
                     : "这是当前 Graph 步骤对应的交付；结果已可供 Agent 使用，只使用 safe_payload。"
                 : "Agent-visible 交付已完成但没有结果项；不要调用 read-result 或重放当前 execution。",
             next: selection ? {
@@ -651,6 +709,23 @@ function servicesNextEnvelope(model) {
     }
     const allowedActions = model.allowed_actions ?? [];
     const preferred = allowedActions[0];
+    if (preferred?.type === "prepare_quote") {
+        const continuation = paidContinuation(model, preferred, {});
+        if (continuation) {
+            return {
+                status: execution.status,
+                result: {
+                    service_execution_id: execution.service_execution_id,
+                    service_id: execution.service_id,
+                    phase: execution.phase,
+                    checkout: continuation.checkout,
+                },
+                instruction: purchaseConfirmationInstruction(execution.status === "quota_exhausted" ? "quota_exhausted" : "candidate_selected", continuation.price, continuation.capability.delivery_email_required),
+                next: continuation.next,
+                recovery: [],
+            };
+        }
+    }
     const next = preferred ? serviceAllowedActionCommand(model, preferred) : null;
     return {
         status: execution.status,
@@ -664,9 +739,13 @@ function servicesNextEnvelope(model) {
                 requires_human: action.requires_human,
             })),
         },
-        instruction: preferred?.requires_human
-            ? "当前下一步需要用户明确选择；先展示必要信息并等待确认。"
-            : preferred ? "执行服务端返回的唯一首选动作；不要猜测其他 capability。" : "当前没有后续动作。",
+        instruction: preferred?.type === "resume_checkout"
+            ? "当前 Execution 已经有一笔 Checkout。不要创建新的 Quote、Cart、Checkout 或 Execution。现在只执行 next.command，恢复并展示同一 Checkout 的付款入口。"
+            : preferred?.type === "wait"
+                ? "付款已确认，Provider 正在处理当前 Execution。不要新建 Execution、Checkout 或再次付款；稍后只执行 next.command 查询同一 Execution。"
+                : preferred?.requires_human
+                    ? "当前下一步需要用户明确选择；先展示必要信息并等待确认。"
+                    : preferred ? "执行服务端返回的唯一首选动作；不要猜测其他 capability。" : "当前没有后续动作。",
         next,
         recovery: [{ command: `itpay services get ${execution.service_execution_id} --json`, reason: "仅在当前动作异常时检查时间线" }],
     };
@@ -692,17 +771,10 @@ function serviceAllowedActionCommand(model, action) {
                 reason: "仅在用户明确选择后提交当前候选 rank",
             };
         case "prepare_quote": {
-            if (!capability)
-                return null;
-            const selectionBacked = model.execution.status === "human_action_approved";
-            const input = selectionBacked
-                ? {}
-                : Object.fromEntries(requiredInputFields(capability.input_schema).map((field) => [field, "<value>"]));
-            return {
-                command: `itpay services quote ${executionID} --capability ${capability.capability_id}${formatInputOptions(input)}${capability.delivery_email_required ? " --email <email>" : ""} --json`,
-                reason: selectionBacked ? "为已确认候选准备报价" : "为当前输入准备报价",
-            };
+            return paidContinuation(model, action, {})?.next ?? null;
         }
+        case "resume_checkout":
+            return { command: `itpay services checkout ${executionID} --resume --json`, reason: "恢复同一 Checkout，不创建第二笔" };
         case "wait":
             return { command: `itpay services next ${executionID} --json`, reason: "等待 durable execution 推进" };
         case "view_delivery":
@@ -826,7 +898,7 @@ function parseValue(value) {
         return Number(value);
     return value;
 }
-function buildServicesCheckoutEnvelope(response, checkoutURL, plan) {
+function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL) {
     const checkout = response.checkout;
     const platform = platformKeyForHost(plan.host);
     const handoff = { url: checkoutURL };
@@ -837,8 +909,9 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan) {
         handoff.markdown = buildAgentChatHandoff(plan).markdown;
     }
     else if (platform === "plain_chat" && checkout.qr_png_url) {
-        handoff.qr_image_url = checkout.qr_png_url;
+        handoff.qr_image_url = absolutePublicURL(baseURL, checkout.qr_png_url);
     }
+    const amount = formatMoney(checkout.checkout.amount_minor, checkout.checkout.currency);
     return {
         status: "human_checkout_required",
         result: {
@@ -846,13 +919,13 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan) {
             checkout_id: checkout.checkout.checkout_id,
             capability_id: checkoutCapabilityID(response),
             locked_input: response.locked_input,
-            amount: formatMoney(checkout.checkout.amount_minor, checkout.checkout.currency),
+            amount,
         },
         handoff,
-        instruction: checkoutInstruction(platform),
+        instruction: checkoutInstruction(platform, amount),
         next: {
-            command: `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token}`,
-            reason: "跟踪同一笔 Checkout",
+            command: `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token} --json`,
+            reason: "仅在用户完成付款操作或要求查询后，读取同一 Checkout 的权威状态",
         },
         recovery: [],
     };
@@ -860,12 +933,20 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan) {
 function checkoutCapabilityID(response, fallback = "") {
     return response.capability_id || fallback;
 }
-function checkoutInstruction(platform) {
+function checkoutInstruction(platform, amount) {
     if (platform === "markdown")
-        return "把 handoff.markdown 原样发送到当前桌面对话；二维码和链接可见前不要查询状态或新建 Checkout。";
+        return `把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 都已实际对用户可见，然后停止等待。不要立即执行 next.command，不要创建第二个 Checkout、Execution 或调用 pay；用户完成付款操作或要求查询后，只执行 next.command。`;
     if (platform === "terminal")
-        return "在用户可见终端展示二维码和付款链接；可见前不要查询状态或新建 Checkout。";
-    return "把付款链接和可用二维码附件发送给用户；可见前不要查询状态或新建 Checkout。";
+        return `在用户可见终端展示二维码、付款链接和金额 ${amount}，然后停止等待。不要立即执行 next.command，不要创建第二个 Checkout、Execution 或调用 pay；用户完成付款操作或要求查询后，只执行 next.command。`;
+    return `现在只做以下动作：1）把 handoff.url 作为可点击付款链接发送给用户；2）优先把 handoff.qr_local_path 作为图片附件发送，不能发送本地附件时使用 handoff.qr_image_url；3）明确告诉用户本次金额是 ${amount}；4）发送完成后停止并等待用户操作。不要立即执行 next.command，不要创建第二个 Checkout，不要新建 Execution，不要调用 pay。用户表示已经完成付款或要求查询状态后，只执行 next.command；用户的话本身不是付款成功证明。`;
+}
+function absolutePublicURL(baseURL, value) {
+    try {
+        return new URL(value, baseURL.endsWith("/") ? baseURL : `${baseURL}/`).toString();
+    }
+    catch {
+        return value;
+    }
 }
 function formatMoney(amountMinor, currency) {
     return `${(amountMinor / 100).toFixed(2)} ${currency}`;

package/dist/src/commands/skill.js

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { declaredAgentType } from "../state/agent_type.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+const commandDir = dirname(fileURLToPath(import.meta.url));
+const BUYER_SKILL = "itpay-buyer";
+export function runSkillShow(name, options = {}) {
+    const normalized = name.trim().toLowerCase();
+    if (normalized !== BUYER_SKILL) {
+        throw new CommandContractError("skill_not_found", `skill not found: ${name}`, `当前 CLI 只内置 ${BUYER_SKILL}；不要猜测 Skill 名称。`, [{ command: `itpay skill show ${BUYER_SKILL} --json`, reason: "读取完整 Buyer Skill" }]);
+    }
+    let content;
+    try {
+        content = readFileSync(findSkillPath(), "utf8");
+    }
+    catch {
+        throw new Error("packaged skill is unavailable: itpay-buyer");
+    }
+    validateSkill(content);
+    const agentType = options.agentType ?? declaredAgentType();
+    const envelope = {
+        status: "shown",
+        result: { skill: BUYER_SKILL, content },
+        instruction: agentType
+            ? agentType === "workbuddy"
+                ? "完整读取并遵守 Skill；保持 workbuddy、同一 Node/CLI launcher 和可持久写入 Device 状态的执行权限。内部诊断不要逐步转述给用户。"
+                : `完整读取并遵守 Skill；当前 Agent Type 是 ${agentType}，后续命令保持不变。`
+            : "完整读取并遵守 Skill；先如实选择当前运行环境对应的 Agent Type。",
+        next: agentType
+            ? { command: "itpay catalog list --json", reason: "按 Skill 开始发现服务" }
+            : { command: "itpay install --json", reason: "选择真实且稳定的 Agent Type" },
+        recovery: [],
+    };
+    writeCommandEnvelope(envelope, {
+        ...options,
+        ...(agentType ? { agentType } : {}),
+        plainResult: content.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n"),
+    });
+}
+function findSkillPath() {
+    if (process.env.ITPAY_CLI_SKILLS_DIR) {
+        return resolve(process.env.ITPAY_CLI_SKILLS_DIR, BUYER_SKILL, "SKILL.md");
+    }
+    const packagePath = resolve(commandDir, "..", "..", "..", "skills", BUYER_SKILL, "SKILL.md");
+    if (existsSync(packagePath))
+        return packagePath;
+    return resolve(commandDir, "..", "..", "skills", BUYER_SKILL, "SKILL.md");
+}
+function validateSkill(content) {
+    const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+    if (!frontmatter || !/^name:\s*itpay-buyer\s*$/m.test(frontmatter) || !/^description:\s*(?:>|\S)/m.test(frontmatter)) {
+        throw new Error("invalid packaged skill: itpay-buyer");
+    }
+}

package/dist/src/main.js

@@ -3,6 +3,7 @@
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
 import { CLI_VERSION, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
+import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./state/device_authority.js";
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.js";
 import { HttpError } from "./client/http.js";
@@ -15,9 +16,10 @@ import { runOrder } from "./commands/order.js";
 import { runListOrders } from "./commands/orders.js";
 import { runCancelRefund, runGetRefund, runListRefunds, runRefund, runWatchRefund } from "./commands/refund.js";
 import { runCartAdd, runCartAddQuoteServer, runCartAddServer, runCartAbandonServer, runCartClear, runCartNext, runCartRemove, runCartRemoveServer, runCartShow, runCartShowServer, } from "./commands/cart.js";
-import { CommandContractError, printErrorRecovery, writeCommandEnvelope } from "./commands/guidance.js";
+import { CommandContractError, errorRecoveryActions, printErrorRecovery, writeCommandEnvelope } from "./commands/guidance.js";
 import { runDocsList, runDocsShow, runDocsSearch } from "./commands/docs.js";
 import { runInstall } from "./commands/install.js";
+import { runSkillShow } from "./commands/skill.js";
 import { runNext } from "./commands/next.js";
 import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckout, runServicesEvents, runServicesGet, runServicesInvoke, runServicesList, runServicesNext, runServicesReadResult, runServicesQuote, runServicesStart, } from "./commands/services.js";
 const program = new Command();
@@ -25,7 +27,7 @@ program
     .name("itpay")
     .description("V3 ItPay CLI — checkout, payment, order, and refund commands")
     .option("--agent-type <type>", "agent runtime type used for device enrollment and client-specific guidance")
-    .version("2.0.5");
+    .version(CLI_VERSION);
 function withHost(value) {
     const host = normalizeHost(value);
     if (!host) {
@@ -80,16 +82,50 @@ function resolveCheckoutPresentationArgs(input) {
 }
 function reportCLIError(error, contract) {
     const commandError = error instanceof CommandContractError ? error : undefined;
+    const deviceError = error instanceof DeviceAuthorizationError ? error : undefined;
+    const stateError = error instanceof DeviceStateError ? error : undefined;
+    const httpRecovery = errorRecoveryActions(error).map((action) => ({
+        command: action.command,
+        reason: action.reason ?? action.label,
+    }));
+    const identityRecovery = error instanceof HttpError &&
+        (error.code === "agent_identity_required" || error.code === "agent_device_session_required");
+    const incompatible = error instanceof HttpError && (error.code === "client_upgrade_required" ||
+        error.code === "client_compatibility_headers_required" ||
+        error.code === "platform_release_unavailable" ||
+        (error.status === 404 && error.code === "unknown_error"));
+    const backendInternal = error instanceof HttpError && error.status === 500 && error.code === "internal_error";
+    const deviceRecovery = deviceError ? [{
+            command: "itpay skill show itpay-buyer --json",
+            reason: "读取身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
+        }] : [];
+    const stateRecovery = stateError ? [{
+            command: "itpay skill show itpay-buyer --json",
+            reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
+        }] : [];
+    const authorizationInstruction = stateError
+        ? "当前运行环境无法写入 owner-only Device 状态；请保持同一 Node、CLI 和 Agent Type，在允许持久写入 ~/.itpay-v3 的执行环境中重试。不要手工创建 lock、删除 identity 或换运行时碰运气。"
+        : error instanceof HttpError && error.code === "agent_device_session_required"
+            ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
+            : deviceError?.code === "agent_device_revoked"
+                ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
+                : deviceError
+                    ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
+                    : undefined;
     if (contract || commandError) {
         writeCommandEnvelope({
             status: "error",
             error: {
-                code: commandError?.code ?? (error instanceof HttpError ? error.code : contract?.code ?? "command_failed"),
+                code: incompatible ? "backend_contract_incompatible" : commandError?.code ?? (error instanceof HttpError ? error.code : stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
-            instruction: commandError?.instruction ?? contract?.instruction ?? "检查命令参数后重试。",
+            instruction: incompatible
+                ? "当前 Backend 不支持本 CLI 所需的交易合同。立即停止；不要尝试 services quote、services checkout、cart、buy 或 pay 作为替代路径。需要先同步 CLI 与 Backend 版本。"
+                : backendInternal
+                    ? "Backend 内部故障；立即停止并向用户报告。不要重试、检查或删除 Device 身份、创建替代 Execution、切换 Backend，或尝试 quote、checkout、cart、buy、pay 等付费路径。"
+                    : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
-            recovery: commandError?.recovery ?? contract?.recovery ?? [],
+            recovery: incompatible || backendInternal ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
             ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : {}),
             output: (text) => { process.stderr.write(text); },
@@ -123,9 +159,10 @@ program
     .description("Probe the V3 backend readiness endpoint")
     .option("--json", "output JSON instead of terminal text")
     .action(async (options) => {
-    const backend = newBackendClient(loadConfig());
+    const config = loadConfig();
+    const backend = newBackendClient(config);
     try {
-        await runReadyz(backend, { jsonOutput: Boolean(options.json) });
+        await runReadyz(backend, { jsonOutput: Boolean(options.json), ...(config.agentType ? { agentType: config.agentType } : {}) });
     }
     catch (error) {
         reportCLIError(error, {
@@ -139,6 +176,81 @@ program
         });
     }
 });
+// --- device ---------------------------------------------------------------
+const deviceCmd = program.command("device").description("Recover local Device registration state after an operator-confirmed Backend reset");
+deviceCmd
+    .command("recover")
+    .description("Forget only the selected Backend registration while preserving the local private key")
+    .option("--confirm-backend-reset", "confirm that an operator reset the selected Backend registration database")
+    .option("--json", "output JSON instead of terminal text")
+    .action(async (options) => {
+    const config = loadConfig();
+    try {
+        if (!config.agentType) {
+            throw new CommandContractError("agent_type_required", "agent type is required for Backend-scoped Device recovery", "如实声明当前 Agent Type；恢复后必须用同一类型重新登记。", [{ command: "itpay install --json", reason: "选择当前真实 Agent Type" }]);
+        }
+        if (!options.confirmBackendReset) {
+            throw new CommandContractError("backend_reset_confirmation_required", "--confirm-backend-reset is required", "仅在运营已确认当前 Backend 的 Device 登记数据库被重建或清空后执行；普通 session 失效或 revoked 不得使用。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
+        }
+        const recovered = await new DeviceAuthority({
+            baseURL: config.baseURL,
+            requestedAgentType: config.agentType,
+            compatibilityHeaders: {},
+        }).recoverBackendReset();
+        writeCommandEnvelope({
+            status: recovered.removed ? "backend_registration_removed" : "backend_registration_absent",
+            result: {
+                backend: config.baseURL,
+                removed_agent_types: recovered.agentTypes,
+                private_key_preserved: true,
+                other_backend_registrations_preserved: true,
+            },
+            instruction: "只读列出 Service Executions，以同一私钥和 Agent Type 重新登记当前 Backend；不要删除 ~/.itpay-v3 或切换运行时。",
+            next: {
+                command: `itpay --agent-type ${config.agentType} services list --limit 1 --json`,
+                reason: "用无业务写入的签名请求重新登记当前 Backend",
+            },
+            recovery: [],
+        }, {
+            jsonOutput: Boolean(options.json),
+            plainResult: [
+                `backend: ${config.baseURL}`,
+                `registration: ${recovered.removed ? "removed" : "already absent"}`,
+                "private_key: preserved",
+                "other_backends: preserved",
+            ],
+        });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "device_recovery_failed",
+            instruction: "仅恢复运营已确认重建的当前 Backend；不要删除整个 Device identity。",
+            recovery: [{ command: "itpay docs show identity-and-sessions --json", reason: "检查 Device 恢复边界" }],
+        });
+    }
+});
+// --- skill ----------------------------------------------------------------
+const skillCmd = program.command("skill").description("Read complete packaged Agent skills");
+skillCmd
+    .command("show")
+    .description("Show one complete packaged skill")
+    .argument("<name>", "skill name")
+    .option("--json", "output JSON instead of terminal text")
+    .action((name, options) => {
+    const config = loadConfig();
+    try {
+        runSkillShow(name, { jsonOutput: Boolean(options.json), ...(config.agentType ? { agentType: config.agentType } : {}) });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "skill_unavailable",
+            instruction: "内置 Skill 缺失或损坏；重新安装同版本 CLI 后重试。",
+            recovery: [{ command: `npm install -g @itpay/cli@${CLI_VERSION}`, reason: "恢复随包发布的 Skill" }],
+        });
+    }
+});
 program
     .command("next")
     .description("Show the next recommended agent action from remembered server handles")

package/dist/src/state/agent_type.js

@@ -0,0 +1,19 @@
+export function declaredAgentType(env = process.env, argv = process.argv) {
+    if (env.ITPAY_AGENT_TYPE)
+        return env.ITPAY_AGENT_TYPE;
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (value === "--agent-type")
+            return argv[index + 1];
+        if (value?.startsWith("--agent-type="))
+            return value.slice("--agent-type=".length);
+    }
+    return undefined;
+}
+export function qualifyItPayCommand(command, agentType) {
+    if (!agentType || !/^[a-z0-9-]+$/.test(agentType))
+        return command;
+    if (!command.startsWith("itpay ") || /^itpay\s+--agent-type(?:=|\s)/.test(command))
+        return command;
+    return `itpay --agent-type ${agentType} ${command.slice("itpay ".length)}`;
+}

package/dist/src/state/config.js

@@ -6,11 +6,12 @@ import { mkdirSync } from "node:fs";
 import { resolve } from "node:path";
 import { HttpClient } from "../client/http.js";
 import { BackendClient } from "../client/backend.js";
+import { declaredAgentType } from "./agent_type.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
-export const CLI_VERSION = "2.0.5";
-export const API_CONTRACT_REVISION = "sha256:3e6b650c62fa54eb8b9ea6b86857cfef594313871e2bf1b9f3ca4ff3cc6e1612";
+export const CLI_VERSION = "2.0.8";
+export const API_CONTRACT_REVISION = "sha256:47d42ab7bbe74a806b9ec989384b28ad715ffcf05a5eb913449b8bc224ffcf49";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";
@@ -25,7 +26,7 @@ export function cartSessionPath(env = process.env) {
 export function loadConfig(env = process.env) {
     const baseURL = env.ITPAY_BACKEND_URL || DEFAULT_BASE_URL;
     const bearerToken = env.ITPAY_BEARER_TOKEN || undefined;
-    const agentType = env.ITPAY_AGENT_TYPE || agentTypeFromArgv(process.argv);
+    const agentType = declaredAgentType(env);
     const checkoutCurrency = env.ITPAY_CURRENCY || "CNY";
     const idempotencyKey = env.ITPAY_IDEMPOTENCY_KEY || `cli_${shortRandom()}`;
     const ideImageAttach = env.ITPAY_IDE_IMAGE_ATTACH !== "0";
@@ -62,19 +63,10 @@ export function newBackendClient(config) {
             "X-ItPay-Contract-Revision": API_CONTRACT_REVISION,
         },
         requestAuthorizer: (input) => authority.authorizationHeaders(input),
+        recoverAuthorization: () => authority.recoverAuthorization(),
     });
     return new BackendClient(http);
 }
-function agentTypeFromArgv(argv) {
-    for (let index = 0; index < argv.length; index += 1) {
-        const value = argv[index];
-        if (value === "--agent-type")
-            return argv[index + 1];
-        if (value?.startsWith("--agent-type="))
-            return value.slice("--agent-type=".length);
-    }
-    return undefined;
-}
 function shortRandom() {
     return Math.random().toString(36).slice(2, 10) + Math.random().toString(36).slice(2, 6);
 }