@itpay/cli 2.1.4 → 2.1.6

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

@@ -12,6 +12,65 @@ import { renderTerminalQR } from "../render/qr.js";
 import { buildCheckoutQRPlan } from "./buy.js";
 import { appendFeedbackPostmortemInstruction, CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, } from "./guidance.js";
 const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
+const RAIL_SERVICE_GUIDANCE = {
+    "itpay-rail-exact": {
+        when_to_use: "出发和到达都是明确的火车站名时使用本服务（直达查询，最快）。只有城市、模糊位置或想要方案推荐时改用 itpay-rail-smart。",
+        input_fields: [
+            { name: "origin", required: true, description: "出发火车站名（如'古镇'），不能是城市或地址", example: "古镇" },
+            { name: "destination", required: true, description: "到达火车站名（如'广州南'）", example: "广州南" },
+            { name: "travel_date", required: true, description: "出行日期 YYYY-MM-DD；字段名必须是 travel_date，'date' 等别名无效", example: "2026-09-19" },
+        ],
+        input_example: { origin: "古镇", destination: "广州南", travel_date: "2026-09-19" },
+        notes: [
+            "本服务只接受这三个字段，多传字段会被供应商拒绝",
+            "站名不确定就改用 itpay-rail-smart 先解析位置，不要在两个服务之间反复试错",
+        ],
+    },
+    "itpay-rail-smart": {
+        when_to_use: "只有城市名、模糊位置或需要中转规划与方案推荐时使用本服务；平台负责把位置解析到车站。",
+        input_fields: [
+            { name: "origin", required: true, description: "出发地：已知最完整的位置名或区域（城市/区县/地址均可）", example: "中山古镇" },
+            { name: "destination", required: true, description: "目的地：与 origin 同样的位置规则", example: "广州南" },
+            { name: "travel_date", required: true, description: "出行日期 YYYY-MM-DD；字段名必须是 travel_date", example: "2026-09-19" },
+        ],
+        optional_fields: [
+            { name: "origin_city", description: "出发地城市提示，辅助位置解析" },
+            { name: "destination_city", description: "目的地城市提示" },
+            { name: "origin_location", description: "已知坐标对象（高德 GCJ-02）" },
+            { name: "destination_location", description: "目的地坐标对象" },
+            { name: "depart_after", description: "不早于该时间出发" },
+            { name: "arrive_before", description: "不晚于该时间到达" },
+            { name: "priority", enum: "balanced|fastest|cheapest|safest|flexible", description: "方案偏好" },
+            { name: "max_transfers", description: "允许中转次数，0-2" },
+        ],
+        input_example: { origin: "中山古镇", destination: "广州南", travel_date: "2026-09-19", priority: "fastest" },
+        notes: [
+            "位置有歧义时会进入位置确认步骤，请用户选定后继续同一执行",
+            "推荐结果含每趟车的席别与余票；购票在后续受保护流程完成",
+        ],
+    },
+};
+function railServiceGuidance(serviceID) {
+    return RAIL_SERVICE_GUIDANCE[serviceID];
+}
+const WORKFLOW_STEP_GUIDANCE = {
+    input: { meaning: "输入校验", hint: "对照服务声明的输入契约补齐字段后重新发起" },
+    quota: { meaning: "额度检查", hint: "免费额度或限流未通过；登录或稍后重试" },
+    geo: { meaning: "位置解析", hint: "检查 origin/destination 是否为真实地名；可附 origin_city 或坐标对象提示" },
+    search: { meaning: "供应商车次检索", hint: "最常见是字段名错误（必须是 travel_date）或站名不存在；按 itpay docs show rail-booking 核对输入" },
+    catalog: { meaning: "可行车次计算", hint: "位置已解析但无可行车次；换日期或换站点重试" },
+    recommend: { meaning: "方案推荐", hint: "候选集无法产出推荐；放宽条件或换日期重试" },
+    delivery: { meaning: "交付", hint: "结果组装失败；稍后重试或联系运营" },
+};
+function failedWorkflowStep(steps) {
+    if (!steps)
+        return undefined;
+    for (const [step, status] of Object.entries(steps)) {
+        if (status === "failure" && step !== "failure")
+            return step;
+    }
+    return undefined;
+}
 export async function runServicesStart(backend, serviceID, options = {}) {
     const host = options.host ?? "terminal";
     const response = await backend.startServiceExecution({
@@ -23,7 +82,8 @@ export async function runServicesStart(backend, serviceID, options = {}) {
         },
     });
     if (response.workflow_entry) {
-        writeCommandEnvelope({ status: "input_required", result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID, input_schema: response.workflow_entry.input_schema }, instruction: "根据服务声明填写输入，然后继续同一服务执行。", next: { command: `itpay services run ${serviceID} --execution ${response.execution.service_execution_id} --input-json <file> --json`, reason: "提交买家输入" }, recovery: [] }, { ...options });
+        const guidance = railServiceGuidance(serviceID);
+        writeCommandEnvelope({ status: "input_required", result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID, input_schema: response.workflow_entry.input_schema, ...(guidance ? { guidance } : {}) }, instruction: guidance ? "按 result.guidance 逐项填写输入（when_to_use 说明本服务适用场景、input_fields 是必填契约、input_example 可直接照抄），然后继续同一服务执行。不要臆造字段名。" : "根据服务声明填写输入，然后继续同一服务执行。", next: { command: `itpay services run ${serviceID} --execution ${response.execution.service_execution_id} --input-json <file> --json`, reason: "提交买家输入" }, recovery: [] }, { ...options });
         return;
     }
     const capability = response.capabilities.find((item) => item.phase === response.execution.phase && !item.requires_payment);
@@ -34,6 +94,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 +106,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 +128,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 +176,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 +204,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 +226,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 +307,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 +327,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 +370,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 +439,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 +812,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";
@@ -685,6 +1010,21 @@ function servicesNextEnvelope(model) {
             command = `itpay services checkout ${id} --json`;
         if (state === "input_required")
             command = `itpay services run ${execution.service_id} --execution ${id} --input-json <file> --json`;
+        const guidance = railServiceGuidance(execution.service_id);
+        const failedStep = recovery ? failedWorkflowStep(model.workflow?.steps) : undefined;
+        const failedStepGuidance = failedStep ? WORKFLOW_STEP_GUIDANCE[failedStep] : undefined;
+        const failedInvocation = recovery
+            ? [...model.provider_invocations].reverse().find((item) => typeof item.status === "string" && item.status.startsWith("failed"))
+            : undefined;
+        const errorDetail = typeof failedInvocation?.error_message === "string" && failedInvocation.error_message ? failedInvocation.error_message : undefined;
+        const providerErrorCode = typeof failedInvocation?.error_code === "string" && failedInvocation.error_code ? failedInvocation.error_code : undefined;
+        const failedInstruction = recovery
+            ? failedStepGuidance
+                ? `执行在「${failedStepGuidance.meaning}」步失败：${failedStepGuidance.hint}${errorDetail ? `。供应商返回：${errorDetail}` : ""}。本执行已终止不能续用；修正后用同一服务新建执行重试，不要盲目重放。`
+                : state === "failed"
+                    ? `执行已失败${failedStep ? `（失败步骤：${failedStep}）` : ""}且不可续用；修正输入后用同一服务新建执行重试。`
+                    : "执行未完成，请按步骤错误处理；不要重建执行或重复调用。"
+            : undefined;
         return {
             status: state,
             result: {
@@ -692,72 +1032,38 @@ function servicesNextEnvelope(model) {
                 service_id: execution.service_id,
                 workflow: model.workflow,
                 ...(state === "input_required" ? { input_schema: model.workflow_entry.input_schema } : {}),
+                ...(guidance && state === "input_required" ? { guidance } : {}),
+                ...(failedStep ? { failed_step: failedStep, ...(failedStepGuidance ? { failed_step_meaning: failedStepGuidance.meaning } : {}) } : {}),
+                ...(providerErrorCode ? { provider_error_code: providerErrorCode } : {}),
+                ...(errorDetail ? { error_detail: errorDetail } : {}),
+                ...(recovery ? { retryable: state === "failed" } : {}),
             },
-            instruction: recovery
-                ? "执行未完成，请按步骤错误处理；不要重建执行或重复调用。"
-                : state === "payment"
+            instruction: failedInstruction
+                ?? (state === "payment"
                     ? "服务已到付款步骤，使用现有 Checkout 完成扫码付款。"
-                    : "继续读取同一执行；缺少输入时按服务声明补齐。",
+                    : guidance
+                        ? "按 result.guidance 的字段契约填写输入后继续同一服务执行；不要臆造字段名。"
+                        : "继续读取同一执行；缺少输入时按服务声明补齐。"),
             next: recovery ? null : { command, reason: "继续当前流程" },
-            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: "仅在需要诊断终止原因时读取事件",
-                },
-            ],
+            recovery: recovery && state === "failed"
+                ? [
+                    { command: `itpay services start ${execution.service_id} --json`, reason: "修正输入后重新发起（本执行已终止不能续用）" },
+                    ...(guidance ? [{ command: "itpay docs show rail-booking --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 +1194,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 +1345,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.6";
+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/agent/buyer/rail-booking.json

@@ -0,0 +1,80 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
+  "topic": "rail-booking",
+  "title": "Railway Query, Planning, and Ticket Booking",
+  "purpose": "Choose the right railway service for the buyer's situation, submit the exact input contract each service expects, and follow the protected booking flow without inventing field names.",
+  "when_to_use": [
+    "The buyer wants train schedules, routes, or tickets.",
+    "A railway service execution fails at the geo, search, catalog, or recommend step.",
+    "The buyer only knows a city or fuzzy location rather than a station name.",
+    "The buyer asks about seat preferences, refunds, or ticket issuance status."
+  ],
+  "service_selection": {
+    "itpay-rail-exact": "Use when the buyer knows BOTH the exact departure and arrival railway station names (e.g. 古镇 → 广州南). Direct train query, fastest path. Do NOT use it with only a city or fuzzy location.",
+    "itpay-rail-smart": "Use when the buyer has a city name, an area, an address, or wants transfer planning and recommendations. The platform resolves locations to stations itself; never silently convert a city into its namesake station.",
+    "svc_qizhidao_company_lookup": "Not a railway service; do not mix intents."
+  },
+  "input_contract": {
+    "itpay-rail-exact": {
+      "required": {
+        "origin": "Departure railway station name only, e.g. 古镇. Not a city or an address.",
+        "destination": "Arrival railway station name only, e.g. 广州南.",
+        "travel_date": "Travel date in YYYY-MM-DD. The field name must be exactly travel_date; aliases like date are rejected."
+      },
+      "optional": "None. additionalProperties is false — extra fields are rejected by the provider.",
+      "example": {"origin": "古镇", "destination": "广州南", "travel_date": "2026-09-19"}
+    },
+    "itpay-rail-smart": {
+      "required": {
+        "origin": "Fullest known departure location: city, district, area, or address is all acceptable.",
+        "destination": "Fullest known arrival location, same rule as origin.",
+        "travel_date": "Travel date in YYYY-MM-DD. The field name must be exactly travel_date."
+      },
+      "optional": {
+        "origin_city": "Departure city hint that helps location resolution.",
+        "destination_city": "Arrival city hint.",
+        "origin_location": "Known coordinate object (AMap GCJ-02).",
+        "destination_location": "Destination coordinate object.",
+        "depart_after": "Do not depart before this time.",
+        "arrive_before": "Do not arrive after this time.",
+        "priority": "One of balanced | fastest | cheapest | safest | flexible.",
+        "max_transfers": "Integer 0-2, allowed transfer count."
+      },
+      "example": {"origin": "中山古镇", "destination": "广州南", "travel_date": "2026-09-19", "priority": "fastest"}
+    }
+  },
+  "flow": [
+    "services start <service> --json returns input_required plus the guidance block for rail services.",
+    "Submit input with services run <service> --execution <id> --input-json <file> --json on the SAME execution.",
+    "itpay-rail-smart may stop at a location confirmation step; show the candidate places to the buyer, then continue the same execution after the human confirms.",
+    "After a train and seat are chosen, the booking flow moves to a protected checkout page: passenger identity data is entered by the human on that page, never through the CLI.",
+    "Payment success does not mean the ticket is issued. Issuance is asynchronous; keep reading the same execution with services next.",
+    "If seat details are still syncing after issuance, advise the buyer to verify the itinerary on 12306 instead of repeating the query."
+  ],
+  "failure_handling": {
+    "failed_step": "The CLI reports failed_step and failed_step_meaning in the result when a workflow fails.",
+    "geo": "Location resolution failed: check origin/destination are real place names, or attach origin_city/coordinate hints, then start a NEW execution (a failed execution is terminal).",
+    "search": "Supplier query failed: most commonly a wrong field name (must be travel_date) or a nonexistent station name; recheck input against this doc.",
+    "catalog_or_recommend": "Location resolved but no feasible trains: change the date or stations.",
+    "general_rule": "Never replay a failed execution and never guess different field names; correct the input and start a new execution of the same service."
+  },
+  "seat_preferences": {
+    "meaning": "A buyer's seat-letter preference may be planned per leg before payment. The plan is submitted to the supplier when encodable; unsupported combinations fall back to automatic assignment.",
+    "letters": "Evidence-backed letters only: O=ABCDF (second class), M=ACDF (first class), 9=ACF (business class). Other layouts auto-assign.",
+    "boundary": "Never claim a preference was fulfilled before supplier confirmation; check the issued seat in the order/status output."
+  },
+  "agent_rules": [
+    "Pick the service by the buyer's input precision: exact station names → itpay-rail-exact; anything fuzzier → itpay-rail-smart.",
+    "Never invent input field names. If the guidance block or this doc does not list a field, do not send it.",
+    "Never ask the buyer for passenger names, ID numbers, or phone numbers in chat; those are collected only on the protected checkout page.",
+    "Do not repeat or replay a failed execution; correct the input and start a new one.",
+    "Do not claim payment equals ticket issuance; issuance is asynchronous and confirmed only by the issued seat status."
+  ],
+  "human_language": {
+    "prefer": ["车次", "出发站", "到达站", "出行日期", "座位", "余票", "出票中", "已出票"],
+    "avoid": ["workflow", "execution", "provider", "seat_source", "candidate_id"]
+  },
+  "search_terms": ["rail", "railway", "train", "ticket", "火车", "火车票", "高铁", "车票", "车次", "seat", "booking", "rail-booking"]
+}

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.6",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {