@itpay/cli 2.1.4 → 2.1.5

package/dist/src/client/backend.js

@@ -123,6 +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", {});
+    }
     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/checkout.js

@@ -78,15 +78,36 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, a
             : {}),
         ...(platform === "markdown" ? { markdown: buildAgentChatHandoff(plan).markdown } : {}),
     });
+    const railQuote = presentation.rail_quote;
+    const railPassengersPending = presentation.checkout_details === "rail_passengers" && !presentation.rail_passengers_confirmed;
     return {
         status: "human_checkout_required",
         result: {
             checkout_id: presentation.checkout.checkout_id,
             payment: "pending",
             amount,
+            ...(railQuote ? { rail_quote: {
+                    passengers: railQuote.passengers,
+                    expires_at: railQuote.expires_at,
+                    legs: railQuote.legs.map((leg) => ({
+                        train_code: leg.train_code,
+                        travel_date: leg.travel_date,
+                        route: `${leg.from} → ${leg.to}`,
+                        time: `${leg.departure}–${leg.arrival}`,
+                        seat_name: leg.seat_name,
+                        ...(leg.seat_preferences?.length ? { seat_preferences: leg.seat_preferences } : {}),
+                        ...(leg.seat_request_planned ? {
+                            seat_request_planned: leg.seat_request_planned,
+                            auto_reason: leg.auto_reason ?? "none",
+                        } : {}),
+                    })),
+                } } : {}),
+            ...(railPassengersPending ? { rail_passengers_confirmed: false } : {}),
         },
         handoff: presentationHandoff.handoff,
-        instruction: presentationHandoff.instruction,
+        instruction: railPassengersPending
+            ? `${presentationHandoff.instruction} 请用户在受保护网页填写乘车人并确认报价；姓名、证件和手机号只在网页填写，不要贴到对话中。座位偏好仅为购票请求、购票时才提交给供应商且不保证满足；无法逐人提交的偏好将自动分配座位，以实际出票为准。`
+            : presentationHandoff.instruction,
         next: { command: nextCommand, reason: "稍后只查询同一 Checkout" },
         recovery: [],
     };

package/dist/src/commands/services.js

@@ -34,6 +34,7 @@ export async function runServicesStart(backend, serviceID, options = {}) {
     const capabilitySummary = capability ? {
         capability_id: capability.capability_id,
         required_input: requiredInput,
+        input_schema: capability.input_schema,
         ...(capability.free_quota_limit !== undefined ? { free_quota_limit: capability.free_quota_limit } : {}),
     } : null;
     writeCommandEnvelope({
@@ -45,7 +46,7 @@ export async function runServicesStart(backend, serviceID, options = {}) {
             capability: capabilitySummary,
         },
         instruction: capability
-            ? "填写首选 capability 的 required_input；一次只提交当前 execution 所代表的服务意图。"
+            ? "填写首选 capability 的 required_input；一次只提交当前 execution 所代表的服务意图。" + locationInputInstruction(capability.input_schema)
             : "当前没有可直接调用的 capability；读取服务端下一步，不要猜测 capability。",
         next: {
             command,
@@ -67,10 +68,34 @@ export async function runServicesStart(backend, serviceID, options = {}) {
         ],
     });
 }
+function locationConfirmationEnvelope(executionID, capabilityID, input, confirmation) {
+    input = (confirmation.input ?? input);
+    const endpoints = (confirmation.endpoints ?? []);
+    const choices = Object.fromEntries(endpoints.map((endpoint) => [endpoint.side, "<用户选择的候选 id>"]));
+    return {
+        status: "location_confirmation_required",
+        result: { service_execution_id: executionID, query: input, location_confirmation: confirmation },
+        instruction: "尚未查票。仅向用户确认 endpoints 中有歧义的地点，展示真实候选名称、地址和高德链接。不要自行选择候选、把区域改成车站或重复调用原查询。用户选择后保留原输入，带 location_confirmation 回到同一服务。没有候选时请用户补充已知城市或准确地名，再使用修正输入查询。",
+        next: null,
+        recovery: confirmation.can_resume ? [{
+                command: `itpay services invoke ${executionID} --capability ${capabilityID}${formatInputOptions({ ...input,
+                    location_confirmation: { plan_id: confirmation.plan_id, token: confirmation.token, choices } })} --json`,
+                reason: "仅在用户明确选择后替换 choices 并执行；30 分钟有效",
+            }] : [],
+    };
+}
 function requiredInputFields(schema) {
     const required = schema?.required;
     return Array.isArray(required) ? required.filter((field) => typeof field === "string") : [];
 }
+function locationInputInstruction(schema) {
+    const properties = schema?.properties;
+    if (!properties?.origin_location || !properties?.destination_location)
+        return "";
+    if (!properties.location_confirmation)
+        return " 地点保留用户已知最完整名称或城市范围；不要编造坐标或把城市改成同名车站。坐标及其他可选字段严格按当前 input_schema 提交。";
+    return " 地点输入：先向用户说明本服务接受两个地点或城市范围。已有可信高德 GCJ-02 坐标时，可用 --input 'origin_location={\"lng\":113.0,\"lat\":23.0,\"coordinate_system\":\"gcj02\",\"source\":\"amap\"}'（数值必须替换为真实查询结果，destination_location 同理）；没有地图能力时，直接传用户已知最完整的 origin/destination，可附 origin_city/destination_city。不要编造坐标、补猜地址或把深圳等城市改成深圳站；精确站查须明确站名。用户只给城市、县或镇就保留区域意图，不追问门牌。明确地点由服务自动解析；只有返回 location_confirmation 才展示候选名称、地址和高德链接，等待用户选择，禁止自行选第一项。";
+}
 export async function runServicesInvoke(backend, config, serviceExecutionID, capabilityID, input, options = {}) {
     const readModel = await backend.getServiceExecution(serviceExecutionID);
     const requestedCapability = readModel.capabilities.find((capability) => capability.capability_id === capabilityID);
@@ -91,10 +116,26 @@ export async function runServicesInvoke(backend, config, serviceExecutionID, cap
             }]);
     }
     const idempotencyKey = await operationID(config, `service.invoke:${serviceExecutionID}:${capabilityID}:${stableInput(input)}`);
-    const response = await backend.invokeServiceCapability(serviceExecutionID, capabilityID, {
-        idempotency_key: idempotencyKey,
-        redacted_summary: input,
-    });
+    let response;
+    try {
+        response = await backend.invokeServiceCapability(serviceExecutionID, capabilityID, {
+            idempotency_key: idempotencyKey,
+            redacted_summary: input,
+        });
+    }
+    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}`] });
+        return;
+    }
     const envelope = invokedEnvelope(response, requestedCapability, readModel.capabilities, input);
     writeCommandEnvelope(envelope.value, {
         ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
@@ -103,6 +144,13 @@ export async function runServicesInvoke(backend, config, serviceExecutionID, cap
     });
 }
 function invokedEnvelope(response, requestedCapability, capabilities, input) {
+    if (response.execution_request_id) {
+        const id = response.execution.service_execution_id;
+        return { value: { status: "running", result: { service_execution_id: id, execution_request_id: response.execution_request_id },
+                instruction: "查询已排队或正在运行。告知用户稍候，只读取同一任务的状态；不要重新发起查询，也不要把暂未返回结果说成没有车。",
+                next: { command: `itpay services next ${id} --json`, reason: "稍后读取同一查询结果" }, recovery: [] },
+            plainResult: ["status: running", `service_execution_id: ${id}`] };
+    }
     const items = response.result_items.map((item) => ({
         rank: item.rank,
         title: item.display_title,
@@ -118,11 +166,51 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
         items,
         ...(quota ? { quota } : {}),
     };
+    const preview = response.invocation?.safe_result_preview;
+    if (!response.effective_quota?.exhausted && preview?.search_status === "LOCATION_CONFIRMATION_REQUIRED" && preview.location_confirmation) {
+        return { value: locationConfirmationEnvelope(response.execution.service_execution_id, requestedCapability.capability_id, input, preview.location_confirmation),
+            plainResult: [JSON.stringify(preview.location_confirmation)] };
+    }
+    if (typeof preview?.catalog_total === "number") {
+        baseResult.catalog = {
+            total: preview.catalog_total,
+            recommendation: preview.recommendation,
+            decision_source: preview.decision_source,
+            coverage: preview.coverage,
+            notices: preview.notices,
+            search_status: preview.search_status,
+            searched_scope: preview.searched_scope,
+            effective_policy_hash: preview.effective_policy_hash,
+            api_cost: preview.api_cost,
+            stage_timestamps: preview.stage_timestamps,
+            page: preview.catalog_page,
+            journey_summary: preview.journey_summary,
+            journeys: preview.journeys,
+            train_services: preview.train_services,
+            resolved_locations: preview.resolved_locations,
+        };
+    }
     let status = items.length > 0 ? "result_ready" : "no_result";
     let instruction = items.length > 0
         ? "用编号、名称和可公开字段向用户说明候选；若候选列表已满足目标就停止。只有用户明确选择并希望继续时，才提交对应编号；不要向用户提及 safe_payload、Execution 或内部 ID。"
         : `没有找到与“${queryText(input)}”匹配的结果。向用户展示本次为 0 个结果并停止。不要修改、缩短或猜测其他输入；只有用户明确提供新输入后，才能启动新的查询。`;
+    if (items.length === 0 && Array.isArray(preview?.notices)) {
+        const railNotice = preview.notices.find((notice) => {
+            if (!notice || typeof notice !== "object")
+                return false;
+            const value = notice;
+            return ["RAIL_TRANSFER_SCOPE_LIMIT", "RAIL_TRANSFER_SEARCH_INCOMPLETE"].includes(String(value.code)) && typeof value.message === "string";
+        });
+        if (railNotice)
+            instruction = `向用户展示官方提示：${railNotice.message} 不要断言该行程必须多次中转或没有车。等待用户选择分段查询的起终点，不自动更换输入或重试。`;
+    }
     let next = null;
+    if (items.length > 0 && baseResult.catalog) {
+        instruction = "先向用户说明排在首位的推荐方案和其他方案的时间、费用与便利性取舍。items 包含本次返回的合格候选，用户不满意时继续从该列表比较，不必重复查票。搜索是否完成、目录是否截断、覆盖范围和模型降级以 catalog 为准；不能把部分结果说成完整搜索。费用尚需购票前核验。姓名、身份证和手机号仅在 ItPay 网页填写。";
+    }
+    if (items.length > 0 && preview?.journey_summary) {
+        instruction = "先按 journey_summary 报告本次已查询范围内的可用车次、换乘走法和实际乘车组合数量，不能用 catalog.total 或 items 数量冒充车次或组合数。按 journeys 展示组合，推荐置顶，保留全部组合和 train_services 车次列表供用户查看。每组先说明乘坐哪些车、在哪里真正换车以及等待多久；rides.onboard_stops 是同车接续停站，无需下车，可能需车内换座，不计入换乘次数。席别、余票、价格及接驳是组合下的选择，通过 candidate_ids 查对应 items；确认具体选择后才使用该 item 的编号，不猜席别或自动付款。30 分钟只是在已确认便捷换乘站点的筛选下限，不是接续保证。不得把多段票称为已可购买的套票；以 purchase_supported 为准。覆盖不完整、截断和模型仅看短名单时必须说明。姓名、身份证和手机号只在 ItPay 网页填写。";
+    }
     if (response.effective_quota?.exhausted) {
         status = "quota_exhausted";
         instruction = "免费额度已用完且本次没有调用 Provider。当前没有可购买的 continuation；只读取同一 Execution 的服务端恢复方向。";
@@ -159,6 +247,8 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
     else if (items.length === 0) {
         next = null;
     }
+    if (preview?.resolved_locations)
+        instruction += " 按 resolved_locations 说明实际解析地点；区域级位置仅是范围代表点，接驳时间不是从用户精确位置计算的。";
     return {
         value: { status, result: baseResult, instruction, next, recovery: [] },
         plainResult: serviceResultPlainLines(baseResult),
@@ -177,6 +267,14 @@ function serviceResultPlainLines(result) {
     }
     if (items.length === 0)
         lines.push("results: 0");
+    const catalog = result.catalog;
+    if (catalog?.resolved_locations)
+        lines.push(`resolved_locations: ${JSON.stringify(catalog.resolved_locations)}`);
+    if (catalog?.journey_summary) {
+        for (const key of ["journey_summary", "train_services", "journeys"]) {
+            lines.push(`${key}: ${JSON.stringify(catalog[key])}`);
+        }
+    }
     if (result.quota)
         lines.push(`quota: ${JSON.stringify(result.quota)}`);
     if (result.checkout)
@@ -212,6 +310,8 @@ function checkoutCommand(serviceExecutionID, capability, input, fillMissing = tr
     return `itpay services checkout ${serviceExecutionID} --capability ${capability.capability_id}${formatInputOptions(lockedInput)}${capability.delivery_email_required ? " --email <email>" : ""} --json`;
 }
 function capabilityPrice(capability) {
+    if (capability.pricing_method === "rail_fare_plus_fee")
+        return "实时票款 + 每张票 2 元服务费（最终金额以锁定报价为准）";
     return capability.price_amount_minor !== undefined && capability.price_currency
         ? formatMoney(capability.price_amount_minor, capability.price_currency)
         : "当前发布价格";
@@ -279,7 +379,7 @@ function formatInputOptions(input) {
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([key, value]) => String(value) === "<value>"
         ? ` --input ${key}=<value>`
-        : ` --input ${shellArgument(`${key}=${String(value)}`)}`)
+        : ` --input ${shellArgument(`${key}=${typeof value === "object" && value !== null ? JSON.stringify(value) : String(value)}`)}`)
         .join("");
 }
 function shellArgument(value) {
@@ -652,11 +752,176 @@ export async function runServicesReadResult(backend, serviceExecutionID, options
         plainResult: servicesNextPlainResult(envelope.result),
     });
 }
+function railLegSeatSummary(seat) {
+    return {
+        passenger_index: seat.passenger_index,
+        ...(seat.seat_type_name ? { seat_type_name: seat.seat_type_name } : {}),
+        ...(seat.seat_label || seat.coach_no || seat.seat_no
+            ? { seat: seat.seat_label ?? [seat.coach_no ? `${seat.coach_no}车` : "", seat.seat_no ?? ""].join("") }
+            : {}),
+        confirmed: seat.confirmed,
+    };
+}
+function railBookingEnvelope(model) {
+    const rail = model.rail_booking;
+    const execution = model.execution;
+    const orderID = (model.current_delivery ?? model.delivery_bindings.at(-1))?.order_id;
+    const legs = rail.legs.map((leg) => ({
+        leg_index: leg.leg_index,
+        state: leg.state,
+        issued: leg.issued,
+        ...(leg.details_pending ? { details_pending: true } : {}),
+        ...(leg.supplier_state ? { supplier_state: leg.supplier_state } : {}),
+        ...(leg.train_code ? { train_code: leg.train_code } : {}),
+        ...(leg.travel_date ? { travel_date: leg.travel_date } : {}),
+        ...(leg.from || leg.to ? { route: `${leg.from ?? ""} → ${leg.to ?? ""}` } : {}),
+        ...(leg.departure || leg.arrival ? { time: `${leg.departure ?? ""}–${leg.arrival ?? ""}` } : {}),
+        ...(leg.seat_name ? { seat_name: leg.seat_name } : {}),
+        ...(leg.seat_request ? { seat_request: leg.seat_request } : {}),
+        ...(leg.seat_preferences?.length ? { seat_preferences: leg.seat_preferences } : {}),
+        ...(leg.seats?.length ? { seats: leg.seats.map(railLegSeatSummary) } : {}),
+    }));
+    const result = {
+        service_execution_id: execution.service_execution_id,
+        ...(orderID ? { order_id: orderID } : {}),
+        rail: { state: rail.state, issued_legs: rail.issued_legs, legs },
+        ...(model.workflow ? { workflow: model.workflow } : {}),
+    };
+    if (rail.state === "issued") {
+        const detailsPending = rail.legs.some((leg) => leg.details_pending);
+        return {
+            status: "issued",
+            result,
+            instruction: `告诉用户：车票已出票，座位以实际出票为准，平台不提供 12306 票号，可在订单页核对行程。不要在对话中索要乘车人身份信息。${detailsPending ? "部分席位信息未能同步，请前往 12306 核对行程；不要重复购买。" : ""}`,
+            next: orderID ? { command: `itpay order ${orderID} --json`, reason: "查看订单及退款入口" } : null,
+            recovery: [],
+        };
+    }
+    if (rail.state === "manual_review") {
+        return {
+            status: "manual_review",
+            result,
+            instruction: "告诉用户：付款已确认，订单需要人工核对；请勿重复付款或重新下单，已出票的车票会保留。不要承诺退款结果或时效。",
+            next: orderID ? { command: `itpay order ${orderID} --json`, reason: "查看同一订单当前状态" } : null,
+            recovery: [],
+        };
+    }
+    // A rail booking run only exists after a verified payment, so payment is
+    // confirmed here — but only `pending` actually means supplier issuance is in
+    // flight. Any state added later falls back to a conservative re-read instead
+    // of claiming issuance.
+    if (rail.state === "pending") {
+        return {
+            status: "issuing",
+            result,
+            instruction: "告诉用户：付款已确认，后台正在出票；付款成功不代表已出票，请勿重复购买或再次付款。稍后只读取同一任务。",
+            next: { command: `itpay services next ${execution.service_execution_id} --json`, reason: "稍后读取同一出票任务" },
+            recovery: [],
+        };
+    }
+    return {
+        status: "processing",
+        result,
+        instruction: `告诉用户：付款已确认，订单处理状态待确认（${rail.state}）；付款成功不代表已出票，请勿重复购买或再次付款。稍后只读取同一任务。`,
+        next: { command: `itpay services next ${execution.service_execution_id} --json`, reason: "稍后读取同一出票任务" },
+        recovery: [],
+    };
+}
+function terminalExecutionEnvelope(model) {
+    const execution = model.execution;
+    const currentDelivery = model.current_delivery ?? model.delivery_bindings.at(-1);
+    if (!isTerminalServiceExecutionStatus(execution.status) ||
+        (model.workflow_entry && (currentDelivery || serviceDeliveryMode(model) === "agent_visible_result") && ["completed", "delivery_completed"].includes(execution.status))) {
+        return null;
+    }
+    const paid = model.checkout_bindings.some((binding) => binding.status === "payment_verified") || Boolean(currentDelivery?.order_id);
+    const paidFailure = execution.status === "failed" && paid;
+    return {
+        status: execution.status,
+        result: {
+            service_execution_id: execution.service_execution_id,
+            service_id: execution.service_id,
+            phase: execution.phase,
+            ...(currentDelivery?.order_id ? { order_id: currentDelivery.order_id } : {}),
+        },
+        instruction: execution.status === "refunded"
+            ? "告诉用户这笔服务已经退款并永久结束。Agent 不重放服务步骤、不创建付款页面或尝试读取旧交付。"
+            : paidFailure
+                ? appendFeedbackPostmortemInstruction("告诉用户：付款和订单已经记录，但本次服务没有正常完成，不需要再次付款或重新下单。然后从同一订单检查退款状态；Agent 不重放服务步骤、创建付款页面或再次调用数据来源，也不把技术故障归咎于用户。", "failed")
+                : "告诉用户本次服务已经结束且没有可继续的交付。Agent 不重放服务步骤或创建付款页面。",
+        next: null,
+        recovery: [
+            ...(paidFailure
+                ? [{
+                        command: currentDelivery?.order_id
+                            ? `itpay order ${currentDelivery.order_id} --json`
+                            : "itpay orders --json",
+                        reason: "恢复同一笔已付款订单及其退款状态",
+                    }]
+                : []),
+            {
+                command: `itpay services events ${execution.service_execution_id} --json`,
+                reason: "仅在需要诊断终止原因时读取事件",
+            },
+        ],
+    };
+}
 function servicesNextEnvelope(model) {
     const execution = model.execution;
     const currentDelivery = model.current_delivery ?? model.delivery_bindings.at(-1);
     const lockedRefund = model.refunds.find((refund) => refund.access_locked);
-    if (model.workflow_entry && !lockedRefund && !["completed", "delivery"].includes(model.workflow?.status ?? "")) {
+    if (lockedRefund) {
+        const terminal = lockedRefund.status === "succeeded";
+        return {
+            status: "delivery_locked",
+            result: {
+                service_execution_id: execution.service_execution_id,
+                access_locked: true,
+                refund: {
+                    refund_request_id: lockedRefund.refund_request_id,
+                    status: lockedRefund.status,
+                },
+            },
+            instruction: terminal
+                ? "告诉用户退款已由 ItPay 确认成功，原交付永久关闭。Agent 停止读取和跟踪，不再创建授权。"
+                : "告诉用户退款仍在处理，原交付已按政策冻结。然后读取同一退款的权威状态；Agent 不读取交付、不创建授权或重复申请。",
+            next: terminal ? null : {
+                command: `itpay refund get ${lockedRefund.refund_request_id} --json`,
+                reason: "读取退款权威状态",
+            },
+            recovery: [],
+        };
+    }
+    const latestRun = model.execution_requests?.filter((request) => request.execution_kind === "service.execution.run").at(-1);
+    if (latestRun && ["pending", "started"].includes(latestRun.status)) {
+        return {
+            status: "running",
+            result: { service_execution_id: execution.service_execution_id, execution_request_id: latestRun.execution_request_id },
+            instruction: "任务仍在排队或执行中，稍后读取同一任务。不要重新查票、重复提交输入或把等待状态当作零结果。",
+            next: { command: `itpay services next ${execution.service_execution_id} --json`, reason: "稍后读取同一任务状态" },
+            recovery: [],
+        };
+    }
+    // A terminal execution wins over the rail read model: a failed, cancelled,
+    // or refunded run must not render as still issuing. Completed executions
+    // keep the rail view so issued seats stay visible.
+    if (model.rail_booking && isTerminalServiceExecutionStatus(execution.status) && !["completed", "delivery_completed"].includes(execution.status)) {
+        const terminal = terminalExecutionEnvelope(model);
+        if (terminal)
+            return terminal;
+    }
+    if (model.rail_booking)
+        return railBookingEnvelope(model);
+    if (latestRun && ["failed", "cancelled"].includes(latestRun.status) && !model.workflow_entry) {
+        return {
+            status: latestRun.status,
+            result: { service_execution_id: execution.service_execution_id },
+            instruction: "本次任务未完成，需要检查同一任务的处理记录；这不表示没有结果。不要自动重新发起。",
+            next: null,
+            recovery: [{ command: `itpay services events ${execution.service_execution_id} --json`, reason: "读取同一任务的处理记录" }],
+        };
+    }
+    if (model.workflow_entry && !["completed", "delivery"].includes(model.workflow?.status ?? "")) {
         const id = execution.service_execution_id;
         const paymentVerified = model.payment_bindings.some((binding) => binding.status === "payment_verified") || model.checkout_bindings.some((binding) => binding.status === "payment_verified");
         const state = model.workflow?.status === "payment" && paymentVerified ? "running" : model.workflow?.status ?? "input_required";
@@ -702,62 +967,17 @@ function servicesNextEnvelope(model) {
             recovery: [],
         };
     }
-    if (lockedRefund) {
-        const terminal = lockedRefund.status === "succeeded";
-        return {
-            status: "delivery_locked",
-            result: {
-                service_execution_id: execution.service_execution_id,
-                access_locked: true,
-                refund: {
-                    refund_request_id: lockedRefund.refund_request_id,
-                    status: lockedRefund.status,
-                },
-            },
-            instruction: terminal
-                ? "告诉用户退款已由 ItPay 确认成功，原交付永久关闭。Agent 停止读取和跟踪，不再创建授权。"
-                : "告诉用户退款仍在处理，原交付已按政策冻结。然后读取同一退款的权威状态；Agent 不读取交付、不创建授权或重复申请。",
-            next: terminal ? null : {
-                command: `itpay refund get ${lockedRefund.refund_request_id} --json`,
-                reason: "读取退款权威状态",
-            },
-            recovery: [],
-        };
-    }
-    if (isTerminalServiceExecutionStatus(execution.status) && !(model.workflow_entry && (currentDelivery || serviceDeliveryMode(model) === "agent_visible_result") && ["completed", "delivery_completed"].includes(execution.status))) {
-        const paid = model.checkout_bindings.some((binding) => binding.status === "payment_verified") || Boolean(currentDelivery?.order_id);
-        const paidFailure = execution.status === "failed" && paid;
-        return {
-            status: execution.status,
-            result: {
-                service_execution_id: execution.service_execution_id,
-                service_id: execution.service_id,
-                phase: execution.phase,
-                ...(currentDelivery?.order_id ? { order_id: currentDelivery.order_id } : {}),
-            },
-            instruction: execution.status === "refunded"
-                ? "告诉用户这笔服务已经退款并永久结束。Agent 不重放服务步骤、不创建付款页面或尝试读取旧交付。"
-                : paidFailure
-                    ? appendFeedbackPostmortemInstruction("告诉用户：付款和订单已经记录，但本次服务没有正常完成，不需要再次付款或重新下单。然后从同一订单检查退款状态；Agent 不重放服务步骤、创建付款页面或再次调用数据来源，也不把技术故障归咎于用户。", "failed")
-                    : "告诉用户本次服务已经结束且没有可继续的交付。Agent 不重放服务步骤或创建付款页面。",
-            next: null,
-            recovery: [
-                ...(paidFailure
-                    ? [{
-                            command: currentDelivery?.order_id
-                                ? `itpay order ${currentDelivery.order_id} --json`
-                                : "itpay orders --json",
-                            reason: "恢复同一笔已付款订单及其退款状态",
-                        }]
-                    : []),
-                {
-                    command: `itpay services events ${execution.service_execution_id} --json`,
-                    reason: "仅在需要诊断终止原因时读取事件",
-                },
-            ],
-        };
-    }
+    const terminalEnvelope = terminalExecutionEnvelope(model);
+    if (terminalEnvelope)
+        return terminalEnvelope;
     const currentItems = model.current_result_items ?? [];
+    const latestInvocation = model.provider_invocations.at(-1);
+    const latestPreview = latestInvocation?.safe_result_preview;
+    if (currentItems.length === 0 && latestPreview?.search_status === "LOCATION_CONFIRMATION_REQUIRED" && latestPreview.location_confirmation) {
+        const capability = model.capabilities.find((item) => item.capability_id === latestInvocation?.capability_id && item.phase === execution.phase && !item.requires_payment);
+        if (capability)
+            return locationConfirmationEnvelope(execution.service_execution_id, capability.capability_id, (latestInvocation?.request_summary ?? {}), latestPreview.location_confirmation);
+    }
     const delivery = currentDelivery;
     const deliveryMode = serviceDeliveryMode(model);
     const candidateSelection = model.allowed_actions?.find((action) => action.type === "select_candidate");
@@ -888,7 +1108,7 @@ function servicesNextEnvelope(model) {
                 ? "告诉用户付款和订单已经确认，结果仍在同一笔服务中处理，不需要再次付款；如果最终无法交付，将从原订单检查退款路径。稍后只执行 next.command；Agent 不创建新服务、付款页面或数据请求，也不承诺退款结果。"
                 : preferred?.requires_human
                     ? "当前下一步需要用户明确选择；先展示必要信息并等待确认。"
-                    : preferred ? "执行服务端返回的唯一首选动作；不要猜测其他 capability。" : "当前没有后续动作。",
+                    : preferred ? "执行服务端返回的唯一首选动作；不要猜测其他 capability。" + locationInputInstruction(model.capabilities.find((item) => item.capability_id === preferred.capability_id)?.input_schema) : "当前没有后续动作。",
         next,
         recovery: [{ command: `itpay services get ${execution.service_execution_id} --json`, reason: "仅在当前动作异常时检查时间线" }],
     };
@@ -1039,6 +1259,17 @@ export function collectOption(value, previous = []) {
     return previous;
 }
 function parseValue(value) {
+    // Structured inputs (objects/arrays) are passed as JSON; a string that merely
+    // starts with a JSON delimiter but is not valid JSON stays a string — the
+    // backend schema validates the field type either way.
+    if (value.startsWith("{") || value.startsWith("[")) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
     if (value === "true")
         return true;
     if (value === "false")

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.4";
-export const API_CONTRACT_REVISION = "sha256:7f8e09ecee0ab32e3eed3690341fa5bbf6d955dbb464fd79ce0e340667b1085e";
+export const CLI_VERSION = "2.1.5";
+export const API_CONTRACT_REVISION = "sha256:42659989d533d5a43c4ab92eb2455bcbbc6456e799fa4c2b6587de77f06b95f7";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

package/dist/src/state/device_authority.js

@@ -2,7 +2,7 @@ import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, ran
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-const PROTECTED_PATHS = ["/v1/agent-device-account-bindings", "/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds", "/v1/me", "/v1/vault"];
+const PROTECTED_PATHS = ["/v1/agent-device-account-bindings", "/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds", "/v1/me", "/v1/vault", "/v1/rail/phone-links"];
 export class DeviceAuthority {
     baseURL;
     backendKey;

package/docs/cli-reference/commands/services/invoke.md

@@ -20,6 +20,14 @@ itpay services invoke <service_execution_id> --capability <capability_id>
 
 ## 有结果输出
 
+火车票目录：`items` 保留服务端返回的全部合格方案，不按推荐数量截断。
+`result.catalog` 带搜索覆盖范围、模型来源和推荐引用；`recommended=true` 的方案排在首位。
+本地 Agent 应先解释首推及不同取舍，用户不满意时可继续查看同一次返回的完整列表。
+智能规划返回 `verified_phone_required` 时，先完成 ItPay 网页手机号验证，不在 CLI 收集手机号、身份证或姓名。
+该错误发生在供应商调用和额度预占之前。
+本地验证环境中 CLI 会返回 `verification_url`，用户在该网页验证手机号并确认连接 Agent。
+完成后重试同一条 invoke；不在终端输入或回传手机验证码。
+
 ```json
 {
   "status": "result_ready",
@@ -153,3 +161,5 @@ Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和
 ## Agent Type / Host
 
 所有正式支持的 Local Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。
+
+本地模拟购票阶段：用户选定候选后才提交选择，并使用 `services quote --capability book_ticket` 获取实时票款加每张 2 元服务费的锁定报价。精确查询需在报价输入中指定候选里可售的 `seat_type`；智能方案沿用所选席别。`pricing_method=rail_fare_plus_fee` 不代表总价 2 元。乘客资料仅在 Checkout 网页填写。本地出票结果明确标记 `simulation=true`，不表示真实出票。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {