@itpay/cli 2.1.7 → 2.1.9

package/dist/src/client/backend.js

@@ -123,8 +123,9 @@ export class BackendClient {
     advanceServiceExecution(id, input, idempotencyKey) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(id)}/advance`, { input, idempotency_key: idempotencyKey });
     }
-    createRailPhoneLink() {
-        return this.http.post("/v1/rail/phone-links", {});
+    getServiceExecutionResultItemPage(serviceExecutionID, resultItemID, offset, limit) {
+        const qs = new URLSearchParams({ offset: String(offset), limit: String(limit) });
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/result-items/${encodeURIComponent(resultItemID)}?${qs}`);
     }
     invokeServiceCapability(serviceExecutionID, capabilityID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/capabilities/${encodeURIComponent(capabilityID)}/invoke`, input, { replaySafe: Boolean(input.idempotency_key) });

package/dist/src/commands/services.js

@@ -196,14 +196,13 @@ export async function runServicesInvoke(backend, config, serviceExecutionID, cap
     catch (error) {
         if (!(error instanceof HttpError) || error.code !== "verified_phone_required")
             throw error;
-        const link = await backend.createRailPhoneLink();
         writeCommandEnvelope({
             status: "human_action_required",
-            result: { service_execution_id: serviceExecutionID, ...link },
-            instruction: "请用户打开 verification_url，在 ItPay 网页验证手机号并确认连接当前 Agent。CLI 不接收手机号或验证码；等待用户完成后再重试查询。",
-            next: null,
-            recovery: [{ command: `itpay services invoke ${serviceExecutionID} --capability ${capabilityID}${formatInputOptions(input)} --json`, reason: "仅在用户完成网页验证后重试" }],
-        }, { ...options, plainResult: [`手机号验证：${link.verification_url}`] });
+            result: { service_execution_id: serviceExecutionID, error_code: "verified_phone_required" },
+            instruction: "需要在官方页面完成手机号验证后当前执行才能继续。运行 itpay auth login 打开官方登录页，完成手机号验证并绑定本设备后重试原命令；CLI 不接收手机号或验证码。",
+            next: { command: "itpay auth login --json", reason: "完成官方手机号验证并绑定当前设备" },
+            recovery: [{ command: `itpay services invoke ${serviceExecutionID} --capability ${capabilityID}${formatInputOptions(input)} --json`, reason: "仅在完成手机号验证与设备绑定后重试" }],
+        }, { ...options, plainResult: ["手机号验证：itpay auth login"] });
         return;
     }
     const envelope = invokedEnvelope(response, requestedCapability, readModel.capabilities, input);
@@ -770,6 +769,51 @@ export async function runServicesNext(backend, serviceExecutionID, options = {})
         plainResult: servicesNextPlainResult(envelope.result),
     });
 }
+export async function runServicesPage(backend, serviceExecutionID, resultItemID, options = {}) {
+    const offset = options.offset ?? 0;
+    const limit = options.limit ?? 5;
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new CommandContractError("offset_invalid", "--offset must be a non-negative integer", "offset 必须是非负整数；本次未读取服务端分页。", [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --json`, reason: "从第一页重新读取" }]);
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > 20) {
+        throw new CommandContractError("limit_invalid", "--limit must be an integer from 1 to 20", "limit 必须是 1 到 20 的整数；本次未读取服务端分页。", [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${offset} --json`, reason: "用默认页大小重试" }]);
+    }
+    const response = await backend.getServiceExecutionResultItemPage(serviceExecutionID, resultItemID, offset, limit);
+    const page = response.page;
+    const container = (page.result ?? page);
+    const catalogPage = (container.catalog_page ?? {});
+    const nextOffset = typeof catalogPage.next_offset === "number" ? catalogPage.next_offset : null;
+    const candidates = Array.isArray(container.candidates) ? container.candidates : [];
+    const envelope = {
+        status: candidates.length > 0 ? "result_page" : "result_page_end",
+        result: {
+            service_execution_id: response.service_execution_id,
+            service_capability_result_item_id: response.service_capability_result_item_id,
+            offset: catalogPage.offset ?? offset,
+            limit: catalogPage.limit ?? limit,
+            total: catalogPage.total ?? candidates.length,
+            count: catalogPage.count ?? candidates.length,
+            next_offset: nextOffset,
+            page,
+        },
+        instruction: "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。用普通语言向用户说明本页候选（车次、席别、时刻、费用口径），铁路应付与地面估算费用分开表述；不要提及 safe_payload、Execution 或内部 ID。",
+        next: nextOffset !== null
+            ? { command: `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${nextOffset} --json`, reason: "读取同版本结果的下一页" }
+            : null,
+        recovery: offset > 0
+            ? [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --json`, reason: "回到第一页" }]
+            : [],
+    };
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: candidates.map((candidate) => {
+            const c = candidate;
+            const title = typeof c.title === "string" ? c.title : JSON.stringify(c);
+            return `${title}`;
+        }),
+    });
+}
 export async function runServicesList(backend, options = {}) {
     const limit = options.limit ?? 10;
     if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
@@ -1005,6 +1049,18 @@ function servicesNextEnvelope(model) {
                 recovery: [],
             };
         }
+        if (state === "quota_paused") {
+            const login = model.workflow?.error_code !== "rate_limited";
+            const resume = { command: `itpay services run ${execution.service_id} --execution ${id} --json`, reason: "登录或限流窗口后继续同一执行" };
+            const quota = model.quota ? { bucket: model.quota.bucket, subject_type: model.quota.subject_type, limit: model.quota.limit, remaining: model.quota.remaining } : undefined;
+            return {
+                status: login ? "login_required" : "rate_limited",
+                result: { service_execution_id: id, service_id: execution.service_id, ...(quota ? { quota } : {}) },
+                instruction: login ? "匿名免费额度已用完。使用 itpay auth login 完成官方登录并绑定当前 Agent，然后继续同一执行；不要重新发起查询，不需要付款。" : "已达到登录账号每分钟查询上限。请等到下一分钟后继续同一执行，不要连续重试。",
+                next: login ? { command: "itpay auth login --json", reason: "登录后继续同一查询执行" } : resume,
+                recovery: [resume],
+            };
+        }
         if (state === "human_action" && model.workflow?.human_action) {
             const action = model.workflow.human_action;
             const requiredFields = requiredInputFields(action.input_schema);
@@ -1039,6 +1095,17 @@ function servicesNextEnvelope(model) {
                     recovery: [],
                 };
             }
+            const review = action.context?.review;
+            if (review) {
+                return {
+                    status: "booking_review_required",
+                    result: { service_execution_id: id, service_id: execution.service_id, human_action: action,
+                        required_fields: requiredFields },
+                    instruction: "向用户展示 context.review 中的行程（legs）与可选席别/座位偏好词表（seat_options），并明确告知：座位偏好仅为请求、不保证分配（对应 notice_version 文案须经用户同意）。收集乘客人数、席别与每位乘客偏好后，按 required_fields 组装完整 JSON 对象，经 --input-json <file> 提交——draft_revision 必须等于服务端当前值，被拒绝（booking_review_changed）时重新读取后重试。乘客姓名/证件等身份信息不在此提交，仍走受保护 Checkout 页。",
+                    next: { command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved --input-json <file> --json`, reason: "提交用户确认后的行程确认/修订" },
+                    recovery: [{ command: `itpay services next ${id} --json`, reason: "重新读取当前 draft_revision 后重试" }],
+                };
+            }
             return {
                 status: "confirmation_required",
                 result: { service_execution_id: id, service_id: execution.service_id, human_action: action },
@@ -1083,7 +1150,9 @@ function servicesNextEnvelope(model) {
             },
             instruction: failedInstruction
                 ?? (state === "payment"
-                    ? "服务已到付款步骤，使用现有 Checkout 完成扫码付款。"
+                    ? (model.workflow?.human_action?.context?.review
+                        ? "服务已到付款步骤，可直接 Checkout 付款；如需调整席别/座位偏好，先用 confirm_booking 动作修订（会重新报价并锁定新价），完成后再付款。"
+                        : "服务已到付款步骤，使用现有 Checkout 完成扫码付款。")
                     : guidance
                         ? "按 result.guidance 的字段契约填写输入后继续同一服务执行；不要臆造字段名。"
                         : "继续读取同一执行；缺少输入时按服务声明补齐。"),
@@ -1093,7 +1162,9 @@ function servicesNextEnvelope(model) {
                     { command: `itpay services start ${execution.service_id} --json`, reason: "修正输入后重新发起（本执行已终止不能续用）" },
                     ...(guidance ? [{ command: "itpay docs show rail-booking --json", reason: "查看本服务输入字段契约与示例" }] : []),
                 ]
-                : [],
+                : state === "payment" && model.workflow?.human_action?.context?.review
+                    ? [{ command: `itpay services action ${id} --action ${model.workflow.human_action.action_type} --actor-type human --status approved --input-json <file> --json`, reason: "付款前修订席别/座位偏好（draft_revision 以服务端为准）" }]
+                    : [],
         };
     }
     const terminalEnvelope = terminalExecutionEnvelope(model);
@@ -1143,6 +1214,31 @@ function servicesNextEnvelope(model) {
             safe_payload: item.safe_payload,
         }));
         const selection = model.allowed_actions?.find((action) => action.type === "select_candidate");
+        const railCatalog = currentItems.some((item) => {
+            const container = (item.safe_payload?.result ?? item.safe_payload);
+            return container?.catalog_page !== undefined || container?.cost_semantics !== undefined;
+        });
+        const pageRecovery = currentItems.flatMap((item) => {
+            const container = (item.safe_payload?.result ?? item.safe_payload);
+            const catalogPage = container?.catalog_page;
+            const nextOffset = catalogPage?.next_offset;
+            return typeof nextOffset === "number"
+                ? [{ command: `itpay services page ${execution.service_execution_id} ${item.service_capability_result_item_id} --offset ${nextOffset} --json`, reason: "读取已保存结果的同版本下一页，不重新查询、不消耗额度" }]
+                : [];
+        });
+        const railCostGuidance = "铁路应付只含票价加服务费（quoted_total_minor）；地面接驳是单独估算（estimated_ground_minor），两者相加是已知估算（estimated_door_to_door_minor），不是收款额。";
+        const instruction = (delivery?.order_id
+            ? appendFeedbackPostmortemInstruction(items.length > 0
+                ? selection
+                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
+                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
+                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。", "delivered")
+            : items.length > 0
+                ? selection
+                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
+                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
+                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。")
+            + (railCatalog && items.length > 0 ? ` ${railCostGuidance}` : "");
         return {
             status: items.length > 0 ? "result_ready" : "no_result",
             result: {
@@ -1152,22 +1248,12 @@ function servicesNextEnvelope(model) {
                 delivery_mode: deliveryMode,
                 items,
             },
-            instruction: delivery?.order_id
-                ? appendFeedbackPostmortemInstruction(items.length > 0
-                    ? selection
-                        ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
-                        : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
-                    : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。", "delivered")
-                : items.length > 0
-                    ? selection
-                        ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
-                        : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
-                    : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。",
+            instruction,
             next: selection ? {
                 command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
                 reason: "仅在用户明确选择后锁定来源候选",
             } : null,
-            recovery: [],
+            recovery: pageRecovery,
         };
     }
     if (deliveryMode === "vault_artifact") {
@@ -1496,6 +1582,7 @@ export async function runServicesRun(backend, config, serviceID, input, options
             const started = await backend.startServiceExecution({
                 service_id: serviceID,
                 client_context: { host: options.host ?? "terminal", ...(options.target ? { target: options.target } : {}) },
+                ...(input !== undefined ? { input } : {}),
             });
             id = started.execution.service_execution_id;
             if (!started.workflow_entry) {
@@ -1513,6 +1600,9 @@ export async function runServicesRun(backend, config, serviceID, input, options
         if (input !== undefined) {
             model = await backend.advanceServiceExecution(id, input, `workflow-input:${id}`);
         }
+        else if (model.workflow?.status === "quota_paused") {
+            model = await backend.advanceServiceExecution(id, undefined, `workflow-resume:${id}`);
+        }
         const until = Date.now() + (options.timeoutSeconds ?? 120) * 1000;
         const sleep = options.sleep ?? ((milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)));
         const paid = () => model.payment_bindings.some((binding) => binding.status === "payment_verified") || model.checkout_bindings.some((binding) => binding.status === "payment_verified");

package/dist/src/main.js

@@ -1,6 +1,6 @@
 import { agentAuth } from "./state/account_auth.js";
 import { registerSell } from "./sell/commands.js";
-import { readFileSync as readWorkflowInputFile } from "node:fs";
+import { readFileSync as readWorkflowInputFile, statSync as statWorkflowInputFile } from "node:fs";
 import { runServicesRun } from "./commands/services.js";
 // V3 CLI entrypoint. Each command maps 1:1 to a route family in
 // services/backend/internal/httpapi/handlers/*.go. Commands only
@@ -29,7 +29,7 @@ import { runInstall } from "./commands/install.js";
 import { runSkillShow } from "./commands/skill.js";
 import { runNext } from "./commands/next.js";
 import { runVaultAccess, runVaultList, runVaultRead } from "./commands/vault.js";
-import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckout, runServicesEvents, runServicesGet, runServicesInvoke, runServicesList, runServicesNext, runServicesReadResult, runServicesQuote, runServicesStart, } from "./commands/services.js";
+import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckout, runServicesEvents, runServicesGet, runServicesInvoke, runServicesList, runServicesNext, runServicesPage, runServicesReadResult, runServicesQuote, runServicesStart, } from "./commands/services.js";
 const program = new Command();
 program
     .name("itpay")
@@ -137,10 +137,19 @@ function reportCLIError(error, contract) {
     const providerInputRejected = error instanceof HttpError && error.code === "provider_input_rejected";
     const providerContractMismatch = error instanceof HttpError && error.code === "provider_contract_mismatch";
     const capabilityInputInvalid = error instanceof HttpError && error.code === "capability_input_invalid";
-    const deviceRecovery = deviceError ? [{
+    const deviceKeyResettable = Boolean(deviceError && (deviceError.code === "agent_device_key_rotated" ||
+        deviceError.code === "agent_device_key_conflict" ||
+        (deviceError.enrollmentFailed && deviceError.status === 500)));
+    const deviceRecovery = deviceError ? [
+        {
             command: "itpay skill show itpay --json",
             reason: "读取 ItPay 身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
-        }] : [];
+        },
+        ...(deviceKeyResettable ? [{
+                command: "itpay device reset-key --confirm-key-reset --json",
+                reason: "服务端拒绝以当前私钥完成设备登记；生成全新 Ed25519 密钥并重新登记（旧设备身份在服务端保留为孤儿，不影响新身份和额度谱系）",
+            }] : []),
+    ] : [];
     const stateRecovery = stateError ? [{
             command: "itpay skill show itpay --json",
             reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
@@ -151,9 +160,13 @@ function reportCLIError(error, contract) {
             ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
             : deviceError?.code === "agent_device_revoked"
                 ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
-                : deviceError
-                    ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
-                    : undefined;
+                : deviceKeyResettable && deviceError?.status === 500
+                    ? "服务端未能完成设备登记。先原样重试一次原命令：服务端会把已登记的同一公钥幂等挂回原设备。若仍返回 internal_error（Backend 未含该修复），执行 itpay device reset-key --confirm-key-reset 生成全新密钥后重试。"
+                    : deviceKeyResettable
+                        ? "服务端记录显示当前设备私钥已不再有效（已轮换或与既有登记冲突）。执行 itpay device reset-key --confirm-key-reset 生成全新密钥并重新登记。"
+                        : deviceError
+                            ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
+                            : undefined;
     if (contract || commandError || backendOverrideError) {
         writeCommandEnvelope({
             status: "error",
@@ -359,6 +372,53 @@ deviceCmd
         });
     }
 });
+deviceCmd
+    .command("reset-key")
+    .description("Discard the local Ed25519 device key and all Backend registrations so the next command enrolls as a new device")
+    .option("--confirm-key-reset", "confirm that the current device key must be abandoned and a new identity created")
+    .option("--json", "output JSON instead of terminal text")
+    .action(async (options) => {
+    const config = loadConfig();
+    try {
+        if (!options.confirmKeyReset) {
+            throw new CommandContractError("key_reset_confirmation_required", "--confirm-key-reset is required", "仅当服务端拒绝以当前私钥完成设备登记（internal_error、agent_device_key_rotated 或 agent_device_key_conflict）时使用；会放弃本地设备身份并重新登记，旧设备在服务端保留为孤儿。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
+        }
+        const reset = await new DeviceAuthority({
+            baseURL: config.baseURL,
+            ...(config.agentType ? { requestedAgentType: config.agentType } : {}),
+            compatibilityHeaders: {},
+        }).resetDeviceKey();
+        writeCommandEnvelope({
+            status: "device_key_reset",
+            result: {
+                removed_backend_registrations: reset.removedBackends,
+                private_key_preserved: false,
+                server_side_device: "orphaned_under_previous_key",
+            },
+            instruction: "本地设备私钥已重置；下一次需要设备身份的命令会以全新 Ed25519 密钥重新登记并获得新的额度谱系。服务端旧设备记录保留为孤儿；如需清理请走运营流程。",
+            next: {
+                command: `itpay --agent-type ${config.agentType ?? "<agent_type>"} services list --limit 1 --json`,
+                reason: "用无业务写入的签名请求完成新密钥的重新登记",
+            },
+            recovery: [],
+        }, {
+            jsonOutput: Boolean(options.json),
+            plainResult: [
+                `removed_backend_registrations: ${reset.removedBackends.join(", ") || "none"}`,
+                "private_key: rotated (previous key discarded)",
+                "server_side_device: orphaned under previous key",
+            ],
+        });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "device_key_reset_failed",
+            instruction: "仅在确认要放弃当前设备私钥时使用；普通 session 失效或 revoked 不需要本命令。",
+            recovery: [{ command: "itpay docs show identity-and-sessions --json", reason: "检查 Device 恢复边界" }],
+        });
+    }
+});
 // --- skill ----------------------------------------------------------------
 const skillCmd = program.command("skill").description("Read complete packaged Agent skills");
 skillCmd
@@ -1231,6 +1291,25 @@ vault
     }
 });
 // --- service execution ----------------------------------------------------
+const WORKFLOW_INPUT_JSON_MAX_BYTES = 256 * 1024;
+function readInputJsonObject(file, code, recovery) {
+    let parsed;
+    try {
+        if (statWorkflowInputFile(file).size > WORKFLOW_INPUT_JSON_MAX_BYTES) {
+            throw new CommandContractError(code, `--input-json file exceeds ${WORKFLOW_INPUT_JSON_MAX_BYTES} bytes`, "输入文件过大；只提交服务端 input_schema 声明的字段。", recovery);
+        }
+        parsed = JSON.parse(readWorkflowInputFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof CommandContractError)
+            throw error;
+        throw new CommandContractError(code, `--input-json is not readable valid JSON: ${error instanceof Error ? error.message : String(error)}`, "确认文件存在且为合法 JSON；按服务端 input_schema 字段填写。", recovery);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new CommandContractError(code, "--input-json must contain a JSON object", "确认输入必须是 JSON 对象；按服务端 input_schema 字段填写。", recovery);
+    }
+    return parsed;
+}
 const services = program.command("services").description("Generic V3 Service Execution commands");
 services
     .command("run")
@@ -1245,10 +1324,11 @@ services
     .action(async (serviceID, options) => {
     const config = loadConfig();
     try {
-        const input = options.inputJson ? JSON.parse(readWorkflowInputFile(options.inputJson, "utf8")) : undefined;
-        if (input !== undefined && (!input || typeof input !== "object" || Array.isArray(input))) {
-            throw new Error("input JSON must be an object");
-        }
+        const input = options.inputJson
+            ? readInputJsonObject(options.inputJson, "workflow_input_invalid", [
+                { command: `itpay services run ${serviceID} --json`, reason: "重新读取服务输入声明" },
+            ])
+            : undefined;
         if (!Number.isFinite(options.timeout) || options.timeout < 0 || options.timeout > 600) {
             throw new Error("timeout must be between 0 and 600 seconds");
         }
@@ -1267,6 +1347,35 @@ services
         });
     }
 });
+services
+    .command("page")
+    .description("Read one page of a saved service result set (same stored version, no re-query, no quota)")
+    .argument("<service_execution_id>")
+    .argument("<result_item_id>")
+    .option("--offset <offset>", "zero-based candidate offset", Number, 0)
+    .option("--limit <limit>", "page size (1-20)", Number, 5)
+    .option("--json", "output JSON")
+    .action(async (serviceExecutionID, resultItemID, options) => {
+    const config = loadConfig();
+    const backend = newBackendClient(config);
+    try {
+        await runServicesPage(backend, serviceExecutionID, resultItemID, {
+            offset: options.offset,
+            limit: options.limit,
+            jsonOutput: Boolean(options.json),
+        });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "service_page_failed",
+            instruction: "分页读取的是已保存的同版本结果；不要重新发起查询或新建 execution。",
+            recovery: [
+                { command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前结果页与合法动作" },
+            ],
+        });
+    }
+});
 services
     .command("start")
     .description("Start a contract-backed service execution")
@@ -1333,12 +1442,18 @@ services
     .option("--result-item <service_capability_result_item_id>")
     .option("--required-before <step>")
     .option("--input <key=value>", "action input snapshot", collectOption, [])
+    .option("--input-json <file>", "JSON object containing the full action input snapshot")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesAction(backend, serviceExecutionID, options.action, parseKeyValueList(options.input), {
+        const recovery = [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前动作要求" }];
+        if (options.inputJson && options.input.length > 0) {
+            throw new CommandContractError("service_action_invalid", "--input and --input-json cannot be combined", "--input 与 --input-json 只能二选一：嵌套结构用 --input-json <file>，扁平键值用 --input key=value。", recovery);
+        }
+        const fileInput = options.inputJson ? readInputJsonObject(options.inputJson, "service_action_invalid", recovery) : {};
+        await runServicesAction(backend, serviceExecutionID, options.action, { ...fileInput, ...parseKeyValueList(options.input) }, {
             ...(options.actorType ? { actorType: options.actorType } : {}),
             ...(options.actorId ? { actorID: options.actorId } : {}),
             ...(options.status ? { status: options.status } : {}),

package/dist/src/state/account_auth.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
+import { writeLocalPNG } from '../render/qr.js';
 export function sellerAuthPath(baseURL, env = process.env, purpose = "seller") {
     return resolve(env.HOME || homedir(), '.itpay-v3', `${purpose}-${createHash('sha256').update(baseURL).digest('hex').slice(0, 16)}.json`);
 }
@@ -37,7 +38,13 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
     if (backend) {
         const current = await backend.agentAccountStatus();
         if (current.status === 'authenticated')
-            return current;
+            return {
+                status: 'authenticated',
+                result: { bound: true, phone_verified: current.phone_verified === true },
+                instruction: '设备已绑定账号，可继续之前的查询或购买；登录不附带任何额外授权。',
+                next: { command: 'itpay services run <service_id> --execution <pending_execution_id> --json', reason: '恢复被额度暂停的原执行' },
+                recovery: [],
+            };
     }
     async function request(path, init = {}) {
         const response = await fetcher(baseURL + path, { ...init, redirect: 'error', signal: AbortSignal.timeout(15000) });
@@ -46,7 +53,28 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
         return response;
     }
     if (action === 'login') {
-        const response = await request('/v1/dashboard/auth-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ provider: 'alipay', return_to: backend ? '/' : '/seller' }) });
+        if (backend) {
+            const open = read(baseURL, env, purpose);
+            if (open?.sessionID && open.pollToken && open.startToken) {
+                try {
+                    const current = await (await request(`/v1/dashboard/auth-sessions/${encodeURIComponent(open.sessionID)}?poll_token=${encodeURIComponent(open.pollToken)}`)).json();
+                    if (['created', 'waiting_provider', 'email_verification_required', 'merge_confirmation_required'].includes(current.status)) {
+                        const url = open.authURL ?? '';
+                        const qr = url ? await writeLocalPNG(url).catch(() => undefined) : undefined;
+                        return {
+                            status: 'auth_pending',
+                            result: { dashboard_auth_session_id: open.sessionID, expires_at: current.expires_at, methods: ['phone', 'email', 'alipay', 'wechat'] },
+                            handoff: { url, ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}) },
+                            instruction: '已有进行中的官方授权请求，沿用同一链接或二维码；不要生成新请求。用户在页面内选择手机号验证码、邮箱或钱包完成登录。',
+                            next: { command: 'itpay auth status --json', reason: '用户完成页面登录后确认绑定', poll_after_ms: 5000 },
+                            recovery: [],
+                        };
+                    }
+                }
+                catch { /* fall through to a fresh request */ }
+            }
+        }
+        const response = await request('/v1/dashboard/auth-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ return_to: backend ? '/' : '/seller' }) });
         const result = await response.json();
         const url = new URL(result.start_url, baseURL);
         const sameOrigin = url.origin === new URL(baseURL).origin;
@@ -60,7 +88,25 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
             : url.searchParams.get('start_token') || fragment.get('start_token');
         if (!startToken || !result.poll_token || !result.dashboard_auth_session_id)
             throw new Error('Incomplete authorization response');
-        save({ baseURL, sessionID: result.dashboard_auth_session_id, pollToken: result.poll_token, startToken }, env, purpose);
+        save({ baseURL, sessionID: result.dashboard_auth_session_id, pollToken: result.poll_token, startToken, authURL: url.href }, env, purpose);
+        if (backend) {
+            const qr = await writeLocalPNG(url.href).catch(() => undefined);
+            return {
+                status: 'auth_pending',
+                result: {
+                    dashboard_auth_session_id: result.dashboard_auth_session_id,
+                    expires_at: result.expires_at,
+                    methods: ['phone', 'email', 'alipay', 'wechat'],
+                },
+                handoff: {
+                    url: url.href,
+                    ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}),
+                },
+                instruction: '把官方授权页或二维码交给用户。用户在页面内选择手机号验证码、邮箱或钱包完成登录；不要替用户输入手机号或验证码，start_token 不要写入聊天记录。',
+                next: { command: 'itpay auth status --json', reason: '用户完成页面登录后确认绑定', poll_after_ms: 5000 },
+                recovery: [],
+            };
+        }
         return { status: 'authorization_required', authorization_url: url.href, instruction: `Complete ItPay login in the browser, then run ${command}.` };
     }
     const state = read(baseURL, env, purpose);
@@ -77,14 +123,50 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
         return { status: 'login_required' };
     const path = `/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}`;
     const progress = await (await request(`${path}?poll_token=${encodeURIComponent(state.pollToken)}`)).json();
-    if (progress.status !== 'completed')
+    if (progress.status !== 'completed') {
+        if (backend) {
+            if (progress.status === 'expired') {
+                rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+                return {
+                    status: 'auth_expired',
+                    result: { dashboard_auth_session_id: state.sessionID },
+                    instruction: '授权请求已过期。重新运行 itpay auth login 生成新请求；之前的查询输入在服务端保留，可恢复。',
+                    next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
+                    recovery: [],
+                };
+            }
+            if (progress.status === 'failed' || progress.status === 'cancelled' || progress.status === 'denied') {
+                rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+                return {
+                    status: progress.status === 'failed' ? 'auth_denied' : `auth_${progress.status}`,
+                    result: { dashboard_auth_session_id: state.sessionID },
+                    instruction: '官方授权未通过或被取消。重新运行 itpay auth login 生成新请求。',
+                    next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
+                    recovery: [],
+                };
+            }
+            return {
+                status: 'auth_pending',
+                result: { dashboard_auth_session_id: state.sessionID },
+                instruction: '用户仍在官方页面完成登录；保留当前 handoff，不要生成新二维码或新请求。',
+                next: { command: 'itpay auth status --json', reason: '轮询同一授权请求', poll_after_ms: 5000 },
+                recovery: [],
+            };
+        }
         return { status: progress.status, instruction: 'Finish login and email verification in the browser.' };
+    }
     if (backend) {
         const result = await backend.bindAgentAccount({ dashboard_auth_session_id: state.sessionID, start_token: state.startToken });
         if (result.status !== 'authenticated')
             throw new Error('Agent binding did not complete');
         rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-        return result;
+        return {
+            status: 'authenticated',
+            result: { bound: true, phone_verified: result.phone_verified === true },
+            instruction: '登录与绑定已完成，告知用户可继续之前的查询；已注册账号查询不消耗试用次数，仍受正常限流。',
+            next: { command: 'itpay services run <service_id> --execution <pending_execution_id> --json', reason: '恢复被额度暂停的原查询' },
+            recovery: [],
+        };
     }
     const claimed = await request(`${path}/claim?start_token=${encodeURIComponent(state.startToken)}`, { method: 'POST' });
     const token = /(?:^|[, ]+)itpay_buyer_session=([^;]+)/.exec(claimed.headers.get('set-cookie') ?? '')?.[1];

package/dist/src/state/config.js

@@ -15,8 +15,8 @@ import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.1.7";
-export const API_CONTRACT_REVISION = "sha256:42659989d533d5a43c4ab92eb2455bcbbc6456e799fa4c2b6587de77f06b95f7";
+export const CLI_VERSION = "2.1.9";
+export const API_CONTRACT_REVISION = "sha256:66a95bbc5ec9d7b35747cf87206c63dd45983f26de21afab582d8dd63bf198f7";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";