@itpay/cli 2.1.29 → 2.1.34

package/dist/src/commands/services.js

@@ -34,9 +34,10 @@ function journalTaskState(serviceExecutionID, envelope, env) {
     }
 }
 const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
+const RAIL_ENDPOINT_BRIEF = "查询前先留下2–4行端点理解摘要：两端各指哪里、是车站/行政范围/具体地点、依据及未确定事实，再说明日期/人数/时限与Exact/Smart选择。对话或现有route-brief.txt二选一；已有摘要沿用，只更新变化项。含义不清先澄清，定位待核验不等于含义不清；勿凭字尾猜类型。";
 const RAIL_SERVICE_GUIDANCE = {
     "itpay-rail-exact": {
-        when_to_use: "已知可信站对时先用本服务核验直达；城市需求可先形成有依据的站对假设。只覆盖这一站对，不代表全城市最优。首次查询前先留2–4行路线摘要，具体方法：itpay docs show rail-booking。",
+        when_to_use: "已知可信站对时先用本服务核验直达；城市需求可先形成有依据的站对假设。只覆盖这一站对，不代表全城市最优。只有明确可靠路线知识可直接用；大概率判断先短查，受阻且清晰双站可Exact核验。查询前记录两端含义、类别、依据、未知事实和Exact/Smart选择；格式见已读rail-booking。",
         input_fields: [
             { name: "origin", required: true, description: "已核实出发铁路站完整名称，不能以同名站代替区域", example: "<已核实出发站>" },
             { name: "destination", required: true, description: "已核实到达铁路站完整名称", example: "<已核实到达站>" },
@@ -49,7 +50,7 @@ const RAIL_SERVICE_GUIDANCE = {
         ],
     },
     "itpay-rail-smart": {
-        when_to_use: "需要广泛站点比较、中转或具体地址接驳时使用；有可信站对且只需先核验直达可用 Exact。首次查询前先留2–4行路线摘要，具体方法：itpay docs show rail-booking。",
+        when_to_use: "需要广泛站点比较、中转或具体地址接驳时使用；有可信站对且只需先核验直达可用 Exact。只有明确可靠路线知识可直接用；大概率判断先短查，受阻且清晰双站可Exact核验。查询前记录两端含义、类别、依据、未知事实和Exact/Smart选择；格式见已读rail-booking。",
         input_fields: [
             { name: "origin", required: true, description: "出发地：已知最完整的位置名或区域（城市/区县/地址均可）", example: "<原始完整地点>" },
             { name: "destination", required: true, description: "目的地：与 origin 同样的位置规则", example: "<已核实到达站>" },
@@ -79,21 +80,67 @@ const RAIL_SERVICE_GUIDANCE = {
 };
 function railServiceGuidance(serviceID, schema) {
     const guidance = RAIL_SERVICE_GUIDANCE[serviceID];
-    if (serviceID !== "itpay-rail-smart" || !guidance || !schema?.properties?.endpoints)
+    if (serviceID !== "itpay-rail-smart" || !guidance)
         return guidance;
+    const properties = schema?.properties;
+    if (!properties?.endpoints)
+        return properties?.origin && properties?.destination ? guidance : undefined;
     return {
         ...guidance,
         input_fields: [
-            { name: "endpoints", required: true, description: "origin/destination 各填 kind(area/place/station) 与完整 text；不确定 kind 可省略" },
+            { name: "endpoints", required: true, description: "origin/destination 各填完整text；类别有依据时填kind(area/place/station)。仅对象含义明确、类别确实待核验时可省略kind；完整名称合法，坐标可选，不靠省略kind猜城市" },
             { name: "travel_date", required: true, description: "用户出行日期 YYYY-MM-DD" },
         ],
         optional_fields: (guidance.optional_fields ?? []).filter((field) => !["origin_city", "destination_city", "origin_location", "destination_location"].includes(field.name)).concat([
             { name: "reuse_from", description: "同 owner 的已保存 Exact result_item_id 或 Smart snapshot_id；端点/日期新查询可复用有效事实" },
-        ]),
-        input_example: { endpoints: { origin: { kind: "area", text: "<用户出发市县镇完整名称>" }, destination: { kind: "station", text: "<已核实到达站名>" } }, travel_date: "<用户出行日期 YYYY-MM-DD>" },
-        notes: ["仅用当前 input_schema 支持的端点写法；不要与旧 origin/destination 混用", "唯一地点直接解析；真实歧义只询问有缺口的一端，外部故障按当前执行恢复"],
+        ]).filter(field => properties[field.name] !== undefined),
+        input_example: { endpoints: { origin: { kind: "place", text: "<用户原始完整具体地点>" }, destination: { kind: "area", text: "<用户原始完整行政范围>" } }, travel_date: "<用户出行日期 YYYY-MM-DD>" },
+        notes: ["仅用当前 input_schema 支持的端点写法；不要与旧 origin/destination 混用", "唯一地点直接解析；真实候选只确认有歧义一端；地图等待按可续用状态恢复，终态有新证据才用返回新查询模板，无动作则停止"],
     };
 }
+// Generate only declared required fields and preserve safe known query facts.
+// Authorization and passenger identity are never synthesized into templates.
+function serviceInputTemplate(schema, known = {}) {
+    const properties = schema.properties;
+    if (properties?.endpoints && !properties.origin && !properties.destination && !known.endpoints && (typeof known.origin === "string" || typeof known.destination === "string")) {
+        known = { ...known, endpoints: { origin: { text: known.origin }, destination: { text: known.destination } } };
+    }
+    if (properties?.travel_date && !known.travel_date && typeof known.date === "string")
+        known = { ...known, travel_date: known.date };
+    const result = {};
+    for (const field of new Set([...requiredInputFields(schema), ...Object.keys(known).filter(field => properties?.[field] !== undefined)])) {
+        const rule = properties?.[field] ?? {};
+        if (field === "accept_non_guaranteed") {
+            result[field] = false;
+            continue;
+        }
+        if (rule.type === "object") {
+            const value = known[field];
+            result[field] = serviceInputTemplate(rule, value && typeof value === "object" && !Array.isArray(value) ? value : {});
+        }
+        else if (known[field] !== undefined && (rule.type === undefined || rule.type === "array" && Array.isArray(known[field]) || rule.type === "string" && typeof known[field] === "string" || rule.type === "boolean" && typeof known[field] === "boolean" || ["integer", "number"].includes(String(rule.type)) && typeof known[field] === "number"))
+            result[field] = known[field];
+        else if (rule.const !== undefined)
+            result[field] = rule.const;
+        else if (rule.default !== undefined)
+            result[field] = rule.default;
+        else if (Array.isArray(rule.enum) && rule.enum.length)
+            result[field] = rule.enum[0];
+        else if (rule.type === "integer" || rule.type === "number")
+            result[field] = typeof rule.minimum === "number" ? rule.minimum : 1;
+        else if (rule.type === "boolean")
+            result[field] = false;
+        else if (rule.type === "array")
+            result[field] = [];
+        else
+            result[field] = `<${field}>`;
+    }
+    for (const field of ["kind", "text", "station_code", "poi_id", "adcode", "location", "travel_date", "passengers", "priority", "user_query", "depart_after", "depart_before", "arrive_by", "arrive_before", "seat_preferences", "max_transfers", "duration_basis"]) {
+        if (properties?.[field] && known[field] !== undefined)
+            result[field] = known[field];
+    }
+    return result;
+}
 const WORKFLOW_STEP_GUIDANCE = {
     input: { meaning: "输入校验", hint: "核对本服务的输入契约和服务端错误码；本执行的输入不能凭猜测修复" },
     quota: { meaning: "额度检查", hint: "查看实际额度及授权状态；只按返回的登录或等待动作处理" },
@@ -119,17 +166,22 @@ export async function runServicesStart(backend, serviceID, options = {}) {
     });
     if (response.workflow_entry) {
         const guidance = railServiceGuidance(serviceID, response.workflow_entry.input_schema);
+        if (serviceID === "itpay-rail-smart" && !guidance) {
+            writeCommandEnvelope({ status: "contract_unavailable", result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID }, instruction: "当前执行缺少可用输入合同；只读取一次同执行合同，仍缺失则报告系统缺口并停止，不猜旧Smart写法。", next: { command: `itpay services get ${response.execution.service_execution_id} --json`, reason: "读取当前执行锁定的输入合同一次" }, recovery: [] }, options);
+            return;
+        }
         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 是待填示意，必须替换用户真实值），然后继续同一服务执行。不要臆造字段名。" : "根据服务声明填写输入，然后继续同一服务执行。",
+            instruction: guidance ? RAIL_ENDPOINT_BRIEF + "按 result.guidance 逐项填写输入（when_to_use 说明本服务适用场景、input_fields 是必填契约、input_example 是待填示意，必须替换用户真实值），然后继续同一服务执行。不要臆造字段名。" : "根据服务声明填写输入，然后继续同一服务执行。",
             next: null,
             interaction: {
                 schema_version: "itpay.interaction.v1",
                 stage: "input_required",
                 input_template: {
                     command: `itpay services run ${serviceID} --execution ${response.execution.service_execution_id} --input-json <file> --json`,
-                    required_input: ["file"],
+                    input: guidance?.input_example ?? serviceInputTemplate(response.workflow_entry.input_schema),
+                    required_input: ["file", ...requiredInputFields(response.workflow_entry.input_schema)],
                     executable: false,
                 },
             },
@@ -201,11 +253,11 @@ function locationConfirmationEnvelope(executionID, capabilityID, input, confirma
         ? reason === "STATION_LOCATION_EVIDENCE_REQUIRED"
             ? "尚未查票。车站身份已知，但 Smart 缺少该站地理坐标证据；请说明此系统缺口。若用户仅要双站直达，可按原站名使用 Exact；不要要求用户换站。"
             : reason === "ADDRESS_REQUIRED" || reason === "ADMINISTRATIVE_AREA_UNRESOLVED"
-                ? "尚未查票。请只向用户询问该端点缺少的具体地址或行政归属；保留另一端和已有条件，得到信息后发起关联新查询。"
+                ? "尚未查票。先用已有上下文、地图或浏览补该端地点证据；含义仍不清且影响范围才问用户一个关键问题。保留另一端和原条件；只有返回完整新查询模板且已有新证据才另查，没有模板则停止，不猜旧执行输入。"
                 : reason === "COORDINATE_IDENTITY_UNVERIFIED" || reason === "COORDINATE_NAME_MISMATCH"
                     ? "尚未查票。提交的地点名称和坐标尚未得到一致证据；请核实该端点的真实名称或位置，保留另一端，不要把坐标声明当成人工确认。"
-                    : "尚未查票。地点证据不足；请说明返回的具体原因与受影响端点，不要把外部故障当作用户地点歧义。"
-        : "尚未查票。仅向用户确认有真实歧义的端点，展示候选名称、地址和高德链接。用户选择后保留原输入，回到同一服务。";
+                    : "尚未查票。地点证据不足；说明返回的原因与受影响端，先补真实证据，不改kind绕过、不把外部故障当用户歧义。当前无候选确认或完整新查询模板则停止。"
+        : "尚未查票。仅向用户确认真实地点歧义，展示候选名称、地址和高德链接。具体住宅仍是目的地，附近车站只作候选；不得把选地点改成锁车站。用户选择后保留原输入，回到同一服务。";
     return {
         status: "location_confirmation_required",
         result: { service_execution_id: executionID, query: input, location_confirmation: confirmation },
@@ -233,12 +285,12 @@ function requiredInputFields(schema) {
 function locationInputInstruction(schema) {
     const properties = schema?.properties;
     if (properties?.endpoints)
-        return " 两端分别填写 endpoints.origin/destination 的 kind 与完整 text；不确定 kind 可省略。区域保留范围、精确车站仅在目录验证后锁定。不要混用旧 origin/destination、手填锁站或伪造坐标。唯一地点会自动解析；只有真实多候选才让用户选返回的候选 id，地图失败应按当前执行恢复。";
+        return " " + RAIL_ENDPOINT_BRIEF + " 两端分别填写 endpoints.origin/destination 的完整text；有类别依据就填kind，只有对象含义明确而类别待核验时可省略。区域保留范围、精确车站仅在目录验证后锁定。不要混用旧 origin/destination、手填锁站或伪造坐标。唯一地点会自动解析；只有真实多候选才让用户选返回的候选 id，地图失败应按当前执行恢复。";
     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 才展示候选名称、地址和高德链接，等待用户选择，禁止自行选第一项。";
+        return " " + RAIL_ENDPOINT_BRIEF + " 地点保留用户已知最完整名称或城市范围；不要编造坐标或把城市改成同名车站。坐标及其他可选字段严格按当前 input_schema 提交。";
+    return " " + RAIL_ENDPOINT_BRIEF + " 地点输入：保留两个地点或城市范围。已有可信高德 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);
@@ -527,10 +579,13 @@ export async function runServicesAction(backend, serviceExecutionID, actionType,
     catch (error) {
         if (error instanceof HttpError && ["booking_review_invalid", "booking_review_changed", "booking_review_locked"].includes(error.code)) {
             throw new CommandContractError(error.code, error.message, error.code === "booking_review_invalid"
-                ? "确认输入与当前草稿不符。重新读取同一booking的review模板，席别使用返回的代码，不填显示名或猜新值。若仅修正代码写法，且车次、实际席别、人数、价格及条款等已确认内容未变，可沿用用户已有明确确认后提交；草稿实质变化或缺少真实同意时，先请用户确认变化内容。"
+                ? "确认输入与当前草稿不符。使用返回 interaction.input_template.input 当前review模板，席别使用返回的代码，不填显示名或猜新值。若仅修正代码写法，且车次、实际席别、人数、价格及条款等已确认内容未变，可沿用用户已有明确确认后提交；草稿实质变化或缺少真实同意时，先请用户确认变化内容。"
                 : error.code === "booking_review_changed"
-                    ? "草稿版本已变化；重新读取同一booking的当前review与revision，经用户核对后再提交。"
-                    : "当前购买已有付款尝试；读取同一booking及订单状态，不创建新订单或重做付款。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取同一booking的当前状态与review" }]);
+                    ? "草稿版本已变化；使用同一booking的当前review模板。仅技术修正且车次、实际席别、人数、价格及条款未变时沿用已有明确同意；实质变化或缺少真实同意才补确认。"
+                    : "当前购买已有付款尝试；读取同一booking及订单状态，不创建新订单或重做付款。", error.payload?.review ? [] : [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取同一booking的当前状态与review" }], error.payload?.review?.input_template ? {
+                schema_version: "itpay.interaction.v1", stage: "booking_review_required",
+                input_template: { command: `itpay services action ${serviceExecutionID} --action ${actionType} --actor-type human --status approved --input-json <file> --json`, input: error.payload?.review.input_template, required_input: ["file"], executable: false },
+            } : undefined, { service_execution_id: serviceExecutionID, review: error.payload?.review, input_errors: error.payload?.input_errors });
         }
         throw error;
     }
@@ -672,22 +727,21 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
     try {
         const booking = await backend.getServiceExecution(serviceExecutionID);
         if (booking.execution.service_id === "itpay-rail-booking") {
-            const leg = booking.rail_booking?.legs?.[0];
             const review = booking.workflow?.human_action?.context?.review;
-            const reviewLeg = Array.isArray(review?.legs) ? review.legs[0] : undefined;
-            const facts = leg ?? reviewLeg;
-            if (facts) {
-                const safe = facts;
-                itinerary = { travel_date: safe.travel_date, train_code: safe.train_code,
-                    from_station: safe.from ?? safe.from_station, to_station: safe.to ?? safe.to_station,
-                    departure: safe.departure, arrival: safe.arrival,
-                    seat_name: safe.seat_name ?? safe.seat_type_name,
-                    passengers: review?.passengers ?? safe.passengers ?? null };
-                itineraryTitle = [facts.travel_date, facts.train_code,
-                    facts.from ?? facts.from_station,
-                    "→", facts.to ?? facts.to_station,
-                    facts.seat_name ?? facts.seat_type_name]
-                    .filter((value) => typeof value === "string" && value.length > 0).join(" ");
+            const presentation = await backend.getCheckoutPresentation(checkoutID, displayToken);
+            const quote = presentation.rail_quote;
+            const facts = quote?.legs ?? booking.rail_booking?.legs ?? (Array.isArray(review?.legs) ? review.legs : []);
+            const legs = facts.filter(value => value && typeof value === "object").map(value => {
+                const leg = value;
+                return { travel_date: leg.travel_date, train_code: leg.train_code,
+                    from_station: leg.from || leg.from_station || `站点代码 ${String(leg.from_station_code ?? "未知")}（名称暂缺）`,
+                    to_station: leg.to || leg.to_station || `站点代码 ${String(leg.to_station_code ?? "未知")}（名称暂缺）`,
+                    departure: leg.departure ?? leg.departure_time, arrival: leg.arrival ?? leg.arrival_time,
+                    arrival_days: leg.arrival_days, seat_name: leg.seat_name || leg.seat_type_name || `席别代码 ${String(leg.seat_type ?? "未知")}（名称暂缺）` };
+            });
+            if (legs.length) {
+                itinerary = { legs, passengers: quote?.passengers ?? review?.passengers ?? null, purchase_unit: "journey" };
+                itineraryTitle = legs.map(leg => [leg.train_code, leg.from_station, "->", leg.to_station].filter(value => typeof value === "string" && value.length).join(" ")).join(" / ");
             }
         }
     }
@@ -695,6 +749,7 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
         // Checkout already exists; a display-only title lookup cannot hide its official handoff.
     }
     const plan = buildCheckoutQRPlan({
+        localSimulation: backend.localSimulation,
         host,
         checkoutID,
         checkoutURL,
@@ -741,8 +796,10 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
         });
     }
     const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, options.agentType, options.target);
-    if (itinerary)
+    if (itinerary) {
         envelope.result = { ...envelope.result, itinerary };
+        envelope.instruction = "整程一次付款，各段分别出票；展示入口不等于付款，付款成功不等于全部出票。" + envelope.instruction;
+    }
     const plainResult = plainValueLines(envelope.result);
     if (!options.jsonOutput && platform === "terminal") {
         plainResult.push("qr:", await renderTerminalQR(checkoutURL, options.qrFormat ?? "terminal"));
@@ -888,7 +945,7 @@ export async function runServicesPage(backend, serviceExecutionID, resultItemID,
     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 response = await backend.getServiceExecutionResultItemPage(serviceExecutionID, resultItemID, offset, limit, limit === 1 ? undefined : "summary");
     const page = response.page;
     const container = (page.result ?? page);
     const exactCandidate = limit === 1 && Array.isArray(container.candidates) && container.candidates.length === 1
@@ -934,6 +991,8 @@ export async function runServicesPage(backend, serviceExecutionID, resultItemID,
             offset: catalogPage.offset ?? offset,
             limit: catalogPage.limit ?? limit,
             total: catalogPage.total ?? candidates.length,
+            requested_limit: limit,
+            truncated_reason: container.journey_page?.truncated_reason ?? null,
             count: catalogPage.count ?? candidates.length,
             next_offset: nextOffset,
             ...(journeys.length ? { journeys: journeys.map(value => compactRailJourney(value, serviceExecutionID, resultItemID)) }
@@ -1010,6 +1069,7 @@ function writeSavedRailPage(envelope, options, key, offset, continuation) {
                 throw new CommandContractError("saved_row_too_large", "saved row exceeds the readable page limit", "这条已保存记录超过当前页面大小；事实仍保留，请读取该条详情。", rows[0]?.detail?.command ? [rows[0].detail] : []);
             }
             rows.pop();
+            result.truncated_reason = "cli_output_byte_budget";
             result.count = rows.length;
             if (key === "trains")
                 result.read_count = rows.length;
@@ -1092,13 +1152,14 @@ export async function runServicesReadResult(backend, serviceExecutionID, options
         const journeys = [];
         let nextOffset = offset;
         let total = 0;
+        let truncatedReason = null;
         let qualificationCounts;
         let planID;
         let queryRevision;
         while (nextOffset !== null) {
             let response;
             try {
-                response = await backend.getServiceExecutionResultItemPage(serviceExecutionID, options.snapshot, nextOffset, limit);
+                response = await backend.getServiceExecutionResultItemPage(serviceExecutionID, options.snapshot, nextOffset, limit, "summary");
             }
             catch (error) {
                 if (error instanceof HttpError && error.code === "result_not_pageable") {
@@ -1116,6 +1177,7 @@ export async function runServicesReadResult(backend, serviceExecutionID, options
             const rows = Array.isArray(container.journeys) ? container.journeys : [];
             total = typeof page?.total === "number" ? page.total : rows.length;
             qualificationCounts = page?.qualification_counts ?? qualificationCounts;
+            truncatedReason = page?.truncated_reason ?? truncatedReason;
             journeys.push(...rows.map((card) => compactRailJourney(card, serviceExecutionID, options.snapshot)));
             const following = page?.next_offset;
             if (typeof following === "number" && following <= nextOffset)
@@ -1133,6 +1195,8 @@ export async function runServicesReadResult(backend, serviceExecutionID, options
                 query_revision: queryRevision,
                 total,
                 qualification_counts: qualificationCounts,
+                requested_limit: limit,
+                truncated_reason: truncatedReason,
                 offset,
                 count: journeys.length,
                 next_offset: nextOffset,
@@ -1142,7 +1206,7 @@ export async function runServicesReadResult(backend, serviceExecutionID, options
                 ? "此历史快照没有完整资格计数；线路仅供核对铁路事实，不能据此认定可购买。沿同快照 detail.command 查看详情。"
                 : qualificationCounts.eligible === 0
                     ? `查到 ${total} 个时刻组合，当前 0 条满足购票资格。请读取诊断线路的 detail.command 查看具体原因；修改条件须依据用户意愿。`
-                    : "这是同一已保存快照的完整线路分页；合格线路已排在前面。若问题需要全部方案，沿 next.command 读完再一次回答；未知费用不能当免费。购票条件用合格线路的 detail.command，价格与余票在购买前实时报价。",
+                    : `已查范围内合格时刻组合 ${qualificationCounts.eligible}；本次展示 ${journeys.length} 个方案（首屏优先既有主方案/代表，计数不是中转通道数）。最快/低价须按对应方案和比较范围说明；未全范围排序只能说已读方案中。更多条件优先同快照调整偏好或沿 next 有序读所需页，不随机翻页、不无条件读完组合。未知费用不能当免费；detail.command 读取席别和整程购买条件，购买前实时报价。`,
             next: nextOffset === null ? null : { command: `itpay services read-result ${serviceExecutionID} --snapshot ${options.snapshot} --offset ${nextOffset} --limit ${limit} --json`, reason: "仅当前问题还需未读线路时继续；已有合格完整结果可答复或按委托继续" },
             recovery: [],
         }, {
@@ -1174,7 +1238,7 @@ export async function runServicesReadResult(backend, serviceExecutionID, options
                 ticket_plan_offset: planOffset,
                 ticket_plans: selected.map(plan => compactRailTicketPlan(plan, detail.journey.qualification_status === "eligible")),
             },
-            instruction: "同一线路的完整车次与席别方案。已有所需席别和有效凭据即可按真实委托继续；只需比较则答复并停止，需要其他席别才读下一页。中转各段独立购买，无联合锁票或接续保证；购买前受保护 Checkout 实时报价。",
+            instruction: "同一线路的完整车次与席别方案。已有所需席别和有效凭据即可按真实委托继续；只需比较则答复并停止，需要其他席别才读下一页。使用所选 ticket_plan 的整程 booking_template：一个 booking、统一报价、一个官方付款入口，各段分别出票，无联合锁票或接续保证。未返回整程模板时不能拼不同方案的腿或退回逐腿付款，按同一执行恢复。身份资料只在受保护 Checkout 页面填写。",
             next: nextOffset === null ? null : { command: `itpay services read-result ${serviceExecutionID} --snapshot ${detail.snapshot_id} --journey ${options.journey} --offset ${nextOffset} --limit ${planLimit} --json`, reason: "仅需要其他席别时读取；已满足用户条件则停止翻页" },
             ...(detail.journey?.booking_support === "single_leg" ? { interaction: {
                     schema_version: "itpay.interaction.v1", stage: "query_results_ready",
@@ -1259,6 +1323,8 @@ function railBookingEnvelope(model) {
         leg_index: leg.leg_index,
         state: leg.state,
         issued: leg.issued,
+        ...(leg.error_code ? { error_code: leg.error_code } : {}),
+        arrival_days: leg.arrival_days ?? 0,
         ...(leg.details_pending ? { details_pending: true } : {}),
         ...(leg.supplier_state ? { supplier_state: leg.supplier_state } : {}),
         ...(leg.train_code ? { train_code: leg.train_code } : {}),
@@ -1273,9 +1339,9 @@ function railBookingEnvelope(model) {
     const result = {
         service_execution_id: execution.service_execution_id,
         ...(orderID ? { order_id: orderID } : {}),
-        rail: { state: rail.state, issued_legs: rail.issued_legs, legs },
+        rail: { state: rail.state, issued_legs: rail.issued_legs, total_legs: rail.legs.length, message: rail.message, legs },
     };
-    if (rail.state === "issued") {
+    if (rail.state === "issued" && rail.issued_legs === rail.legs.length && rail.legs.length > 0) {
         const detailsPending = rail.legs.some((leg) => leg.details_pending);
         return {
             status: "issued",
@@ -1289,7 +1355,7 @@ function railBookingEnvelope(model) {
         return {
             status: "manual_review",
             result,
-            instruction: "告诉用户：付款已确认，订单需要人工核对；请勿重复付款或重新下单，已出票的车票会保留。不要承诺退款结果或时效。",
+            instruction: `告诉用户：付款已确认，已出票 ${rail.issued_legs}/${rail.legs.length}，其余需要人工核对；请勿重复付款或重新下单，已出票的车票会保留。未知结果先对账，退款按对应段处理，不承诺整笔退款或时效。`,
             next: orderID ? { command: `itpay order ${orderID} --json`, reason: "查看同一订单当前状态" } : null,
             recovery: [],
         };
@@ -1302,7 +1368,7 @@ function railBookingEnvelope(model) {
         return {
             status: "issuing",
             result,
-            instruction: "告诉用户：付款已确认，后台正在出票；付款成功不代表已出票，请勿重复购买或再次付款。稍后只读取同一任务。",
+            instruction: `告诉用户：付款已确认，已出票 ${rail.issued_legs}/${rail.legs.length}，后台继续处理；付款成功不代表整程出票，请勿重复购买或再次付款。稍后只读取同一任务。`,
             next: { command: `itpay services next ${execution.service_execution_id} --json`, reason: "稍后读取同一出票任务" },
             recovery: [],
         };
@@ -1315,6 +1381,29 @@ function railBookingEnvelope(model) {
         recovery: [],
     };
 }
+// Public summaries and saved details use the same evidenced units and scopes.
+function railJourneyFacts(card) {
+    const offer = card.representative_offer;
+    const metrics = card.representative_metrics;
+    const minor = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+    const time = (value) => typeof value === "string" ? Date.parse(/(?:Z|[+-]\d{2}:\d{2})$/.test(value) ? value.replace(" ", "T") : `${value.replace(" ", "T")}+08:00`) : NaN;
+    const start = time(card.rides?.[0]?.departure), end = time(card.rides?.at(-1)?.arrival);
+    return {
+        rail_fare_fen: minor(offer?.fare_minor), service_fee_fen: minor(offer?.service_fee_minor),
+        rail_payable_fen: minor(offer?.rail_payable_minor), currency: offer?.currency ?? null,
+        price_basis: "铁路应付参考额=铁路票价+各票段服务费；不含未知地面费用，以新报价为准。",
+        rail_duration_minutes: Number.isFinite(start) && Number.isFinite(end) && end >= start ? Math.round((end - start) / 60000) : null,
+        door_to_door_minutes: metrics?.duration_basis === "door_to_door" ? minor(metrics.door_to_door_min) : null,
+        ...(metrics?.duration_basis !== "door_to_door" ? { ground_time_note: "接驳未完整核验，不能把铁路时长称为门到门时间。" } : {}),
+        estimated_trip_total: metrics?.estimated_total_cost ?? null,
+        estimate_basis: "仅是已核验费用范围的估算，不是含全部地面费用的实付额。",
+    };
+}
+function publicBookingSupport(card) {
+    if (card.booking_support !== "separate_legs_only")
+        return card.booking_support;
+    return card.qualification_status === "eligible" && card.ticket_plans?.some(plan => plan.qualification_status === "eligible" && plan.booking_input) ? "journey" : "read_only";
+}
 function compactRailJourney(card, serviceExecutionID, snapshotID) {
     if (!card.journey_id)
         throw new Error("saved journey has no stable ID");
@@ -1333,14 +1422,6 @@ function compactRailJourney(card, serviceExecutionID, snapshotID) {
         leg_index: raw.leg_index, seat_type: raw.seat_type, seat_name: raw.seat_name,
         availability: raw.availability_text, remaining: raw.inventory_exact === true ? raw.remaining : null,
     }));
-    const railwayTime = (value) => {
-        if (typeof value !== "string")
-            return NaN;
-        const time = value.replace(" ", "T");
-        return Date.parse(/(?:Z|[+-]\d{2}:\d{2})$/.test(time) ? time : `${time}Z`);
-    };
-    const start = railwayTime(rides[0]?.departure);
-    const end = railwayTime(rides.at(-1)?.arrival);
     return {
         journey_ref: card.journey_id,
         ...(card.profile_refs?.balanced ? { profile_ref: card.profile_refs.balanced } : {}),
@@ -1357,17 +1438,20 @@ function compactRailJourney(card, serviceExecutionID, snapshotID) {
                 required_input: ["file", "真实席别选择及人数"] },
         } : {}),
         ...(ticketSeats.length ? { seats: ticketSeats } : {}),
+        booking_support: publicBookingSupport(card),
+        ...(publicBookingSupport(card) === "read_only" ? { purchase_recovery: { command: `itpay services next ${serviceExecutionID} --json`, reason: "历史快照无整程凭据；读取同一执行合法准备路径，不拆单" } } : {}),
+        ticket_plan_refs: (card.ticket_plans ?? []).map(plan => plan.ticket_plan_ref),
+        transfer_wait_minutes: card.transfer_wait_minutes ?? [],
+        ground_summary: card.ground_summary ?? null,
         passengers: card.passengers ?? offer?.ticket_offers?.[0]?.passengers ?? null,
         availability: card.availability ?? "unknown",
         qualification_status: card.qualification_status ?? "unknown",
         ...(card.qualification_reasons?.length ? { qualification_reasons: card.qualification_reasons } : {}),
-        ...(offer ? { rail_payable_fen: offer.rail_payable_minor, currency: offer.currency } : { rail_payable_fen: null }),
-        estimated_trip_total: metrics?.estimated_total_cost ?? null,
+        ...railJourneyFacts(card),
         cost_basis: metrics?.cost_basis ?? "unknown",
         duration_basis: metrics?.duration_basis ?? "unknown",
         timezone: "Asia/Shanghai",
         ...(card.risk_notes?.length ? { risk_notes: card.risk_notes } : {}),
-        rail_duration_minutes: Number.isFinite(start) && Number.isFinite(end) && end >= start ? Math.round((end - start) / 60000) : null,
         ...(card.observed_at ? { observed_at: card.observed_at } : {}),
         detail: { command: `itpay services read-result ${serviceExecutionID} --snapshot ${snapshotID} --journey ${card.journey_id} --json`,
             reason: card.qualification_status === "eligible" ? "读取此完整线路的席别、报价和购买条件" : "读取此线路的铁路事实和不可购买原因" },
@@ -1380,19 +1464,23 @@ function compactRailTicketPlan(raw, journeyEligible) {
     return {
         ticket_plan_ref: raw.ticket_plan_ref,
         passengers: raw.passenger_count ?? (Array.isArray(raw.ticket_offers) ? raw.ticket_offers[0]?.passengers : null) ?? null,
-        purchase_support: raw.purchase_support ?? "none",
+        purchase_support: raw.purchase_support === "separate_legs_only" ? "read_only" : raw.purchase_support ?? "none",
+        ...(legs.length > 1 && !raw.booking_input ? { booking_unavailable: "这份快照只有历史铁路事实，没有完整整程购买凭据；不能拆腿或拼接其他快照凭据。读取同一执行当前状态，按其购买准备或过期恢复动作继续。" } : {}),
         qualification_status: raw.qualification_status ?? "unknown",
         qualification_reasons: raw.qualification_reasons ?? [],
         rail_amount_fen: raw.rail_amount_fen ?? null,
         service_fee_fen: raw.service_fee_fen ?? null,
         price_verified: raw.rail_amount_verified === true,
+        ...(journeyEligible && raw.qualification_status === "eligible" && raw.booking_input && typeof raw.booking_input === "object" ? {
+            booking_template: { command: "itpay services run itpay-rail-booking --input-json <journey.json> --json", executable: false, ticket_plan_ref: raw.ticket_plan_ref, input_example: raw.booking_input, required_input: ["file", "passengers"] },
+        } : {}),
         legs: legs.map((leg, index) => ({
             leg_index: index,
             travel_date: leg.travel_date ?? tickets.find(ticket => ticket.leg_index === index)?.travel_date ?? null,
             ...(() => {
                 const ticket = tickets.find(ticket => ticket.leg_index === index) ?? (tickets[index]?.leg_index === undefined ? tickets[index] : undefined);
                 const offer = ticket?.booking_offer;
-                return offer?.service_id && offer.selection_token && journeyEligible && raw.qualification_status === "eligible" ? {
+                return legs.length === 1 && offer?.service_id && offer.selection_token && journeyEligible && raw.qualification_status === "eligible" ? {
                     booking_template: { command: `itpay services run ${offer.service_id} --input-json <购票.json> --json`, executable: false,
                         ticket_plan_ref: raw.ticket_plan_ref, leg_index: index,
                         seat_choices: [{ seat_type: ticket?.seat_type, seat_name: ticket?.seat_name }],
@@ -1400,7 +1488,7 @@ function compactRailTicketPlan(raw, journeyEligible) {
                             passengers: ticket?.passengers ?? raw.passenger_count ?? "<真实人数>" },
                         required_input: ["file", "真实人数", "该方案席别代码"],
                     },
-                } : { booking_unavailable: "本段没有当前可用的服务端凭据；不能猜代码或例行重查。保留快照，按当前执行的恢复动作处理；过期凭据需真实新验证。" };
+                } : legs.length > 1 ? {} : { booking_unavailable: "本段没有当前可用的服务端凭据；不能猜代码或例行重查。保留快照，按当前执行的恢复动作处理；过期凭据需真实新验证。" };
             })(),
             train_code: leg.train_code ?? null,
             from_station: leg.from_station ?? null, from_station_code: leg.from_station_code ?? null,
@@ -1426,21 +1514,23 @@ function railJourneySummary(card, serviceExecutionID, snapshotID) {
         route: (card.route_names?.length ? card.route_names : card.route ?? []).join("→"),
         ...(trains.length ? { trains } : {}),
         ...(first?.departure || last?.arrival ? { time: `${first?.departure ?? ""}–${last?.arrival ?? ""}` } : {}),
-        ...(offer ? { price: formatMoney(offer.rail_payable_minor, offer.currency) } : { price: "unknown" }),
+        ...(offer && typeof offer.rail_payable_minor === "number" ? { price: formatMoney(offer.rail_payable_minor, offer.currency) } : { price: "unknown" }),
+        ...railJourneyFacts(card),
         ...(metrics ? { calculation_scope: {
                 origin: metrics.origin_scope ?? "legacy_unknown", destination: metrics.destination_scope ?? "legacy_unknown",
                 duration_basis: metrics.duration_basis ?? "legacy_unknown", arrival_basis: metrics.arrival_basis ?? "legacy_unknown",
                 cost_basis: metrics.cost_basis ?? "legacy_unknown",
-                duration_minutes: metrics.door_to_door_min ?? null,
+                duration_minutes: metrics.duration_basis === "door_to_door" ? metrics.door_to_door_min ?? null : railJourneyFacts(card).rail_duration_minutes,
             } } : {}),
         ...(card.decision_role ? { decision_role: card.decision_role } : {}),
         ...(card.explanation?.length ? { explanation: card.explanation } : {}),
         ...(card.reason_codes?.length ? { reason_codes: card.reason_codes } : {}),
         ...(card.tradeoff_codes?.length ? { tradeoff_codes: card.tradeoff_codes } : {}),
         ...(card.recommended_profile ? { recommended_profile: card.recommended_profile,
-            price_basis: "price为默认购票方案参考价；推荐对应的席别、接驳及总价以recommended_profile为准，按其中ticket_plan_ref/offer_refs查看并确认后下单。" } : {}),
+            recommended_price_basis: "推荐席别及已核验接驳估算以recommended_profile为准；按其ticket_plan_ref/offer_refs读取完整方案，新报价确认后下单。" } : {}),
         availability: card.availability,
-        booking_support: card.booking_support,
+        booking_support: publicBookingSupport(card),
+        ...(publicBookingSupport(card) === "read_only" ? { purchase_recovery: { command: `itpay services next ${serviceExecutionID} --json`, reason: "历史快照无整程凭据；读取同一执行当前合法购买准备路径，不拆单" } } : {}),
         ...(card.observed_at ? { observed_at: card.observed_at } : {}),
         ...(card.risk_notes?.length ? { risk_notes: card.risk_notes } : {}),
         ...(card.booking_support === "single_leg"
@@ -1513,7 +1603,7 @@ function railPlanningEnvelope(model) {
         ...(plan.notices?.length ? { notices: plan.notices } : {}),
         ...(plan.recommendation ? { recommendation: railJourneySummary(plan.recommendation, se, plan.catalog_snapshot_id ?? plan.snapshot_id) } : {}),
         ...(cards.length ? { journeys: cards } : {}),
-        ...(plan.snapshot_id ? { full_result: { command: `itpay services read-result ${se} --snapshot ${plan.snapshot_id} --json`, meaning: "读取已保存的完整目录；推荐和journeys仅是摘要" } } : {}),
+        ...((plan.catalog_snapshot_id ?? plan.snapshot_id) ? { full_result: { command: `itpay services read-result ${se} --snapshot ${plan.catalog_snapshot_id ?? plan.snapshot_id} --json`, meaning: "读取已保存的完整目录；推荐和journeys仅是摘要" } } : {}),
         ...(!hasEligible && ["paused", "complete", "expired"].includes(expansion) && plan.query_input && plan.catalog_snapshot_id ? { new_query_template: {
                 command: "itpay services run itpay-rail-smart --input-json <file> --json",
                 executable: false,
@@ -1531,7 +1621,7 @@ function railPlanningEnvelope(model) {
             if (plan.search?.reason === "ground_evidence_required") {
                 return {
                     status: "awaiting_input", result,
-                    instruction: "已查到铁路班次，但具体地址的接驳或出站证据不足，无法验证到达时限；剩余站对未继续查询，不能说没有车。向用户说明已查范围，并请其补充准确起终点地址或可验证的接驳/出站信息；取得新事实后再按其要求重新规划，不要默认扩大铁路搜索。",
+                    instruction: `已查到铁路班次，但具体地址的接驳或出站证据不足，${plan.query_input?.arrive_before || plan.query_input?.arrive_by ? "无法验证用户要求的到达时限" : "尚不能核验相应地点条件或门到门时间"}；剩余站对未继续查询，不能说没有车。说明已查范围和缺失事实，请补充准确起终点地址或可验证的接驳/出站信息；补齐后按原要求规划，不默认扩大搜索。`,
                     next: null, recovery: [],
                 };
             }
@@ -1703,6 +1793,14 @@ function terminalExecutionEnvelope(model) {
         ],
     };
 }
+const RAIL_LOCATION_EVIDENCE_REASONS = new Set(["endpoint_kind_conflict", "place_identity_uncertain", "endpoint_adcode_name_conflict", "endpoint_poi_name_conflict", "endpoint_station_name_code_conflict", "location_evidence_required", "coordinate_name_mismatch", "area_scope_too_broad", "address_required", "administrative_area_unresolved", "station_location_evidence_required", "coordinate_identity_unverified"]);
+const RAIL_QUOTE_FAILURE_GUIDANCE = {
+    quote_source_unavailable: "实时车票数据暂不可用；保留原选择，稍后按用户意愿重新核验，不创建替代订单。",
+    quote_train_changed: "所选车次的时刻或运行信息已变化；向用户说明并征询是否重新查票。",
+    quote_seat_changed: "所选席别已变化；向用户说明并征询新的席别选择。",
+    quote_seat_unavailable: "所选席别当前无足够余票；告知用户并由其决定是否换方案。",
+    quote_refresh_expired: "实时报价过程超时；保留原选择，不把旧价当可付款价格。",
+};
 function servicesNextEnvelope(model) {
     const execution = model.execution;
     const currentDelivery = model.current_delivery ?? model.delivery_bindings.at(-1);
@@ -1713,7 +1811,7 @@ function servicesNextEnvelope(model) {
             next: refundState.next ? { command: `itpay refund get ${lockedRefund.refund_request_id} --json`, reason: "读取同一退款权威状态" } : null };
     }
     const latestRun = model.execution_requests?.filter((request) => request.execution_kind === "service.execution.run").at(-1);
-    if (latestRun && ["pending", "started"].includes(latestRun.status)) {
+    if (latestRun && ["pending", "started"].includes(latestRun.status) && model.workflow?.status !== "failed") {
         return {
             status: "running",
             result: { service_execution_id: execution.service_execution_id, execution_request_id: latestRun.execution_request_id },
@@ -1725,7 +1823,7 @@ function servicesNextEnvelope(model) {
     // 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)) {
+    if (model.rail_booking && model.workflow?.human_action?.context?.quote_recovery !== true && isTerminalServiceExecutionStatus(execution.status) && !["completed", "delivery_completed"].includes(execution.status)) {
         const terminal = terminalExecutionEnvelope(model);
         if (terminal)
             return terminal;
@@ -1748,7 +1846,7 @@ function servicesNextEnvelope(model) {
         const workflowReason = model.workflow?.failure?.reason_code ?? model.workflow?.error_code;
         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";
-        if (["quota_paused", "failed"].includes(state) && workflowReason !== "area_scope_too_broad" && (model.workflow?.dependency ||
+        if (["quota_paused", "failed"].includes(state) && !RAIL_LOCATION_EVIDENCE_REASONS.has(workflowReason ?? "") && (model.workflow?.dependency ||
             /^amap_/.test(workflowReason ?? ""))) {
             const dependency = model.workflow?.dependency;
             const resumable = state === "quota_paused" && dependency?.retryable === true;
@@ -1762,28 +1860,37 @@ function servicesNextEnvelope(model) {
                 recovery: [],
             };
         }
-        if (state === "failed" && workflowReason === "area_scope_too_broad") {
-            return { status: "awaiting_input", result: { service_execution_id: id, reason: "area_scope_too_broad", failure: model.workflow?.failure, affected_endpoint: model.workflow?.failure?.endpoint ?? model.workflow?.dependency?.endpoint, input_template: { endpoints: { [model.workflow?.dependency?.endpoint ?? "<受影响侧>"]: { kind: "area", text: "<市县镇完整名称>" } } } },
-                instruction: "区域范围是省或国家。只补充受影响端点的市、县或镇；保留另一端、日期与用户约束。修正模板：endpoints.<受影响侧>={kind:area,text:<市县镇完整名称>}。",
-                next: null, recovery: [] };
-        }
-        if (state === "failed" && ["address_required", "administrative_area_unresolved", "station_location_evidence_required", "coordinate_identity_unverified"].includes(workflowReason ?? "")) {
+        if (state === "failed" && RAIL_LOCATION_EVIDENCE_REASONS.has(workflowReason ?? "")) {
             const code = workflowReason;
-            return {
-                status: "awaiting_input",
-                result: { service_execution_id: id, service_id: execution.service_id, reason: code, affected_endpoint: model.workflow?.failure?.endpoint, failure: model.workflow?.failure,
-                    ...(["address_required", "administrative_area_unresolved"].includes(code) ? { new_query_template: {
-                            command: `itpay services run ${execution.service_id} --input-json <补全原始需求.json> --json`, executable: false,
-                            required_input: ["仅补受影响端点", "原始日期人数时限偏好"],
-                            instruction: "原执行输入已锁定；按原需求保留另一端与所有约束，只补缺失信息后提交新输入，不在旧执行伪造修改。"
-                        } } : {}) },
-                instruction: code === "station_location_evidence_required"
-                    ? "尚未查票。车站身份已知，Smart 缺少车站坐标证据；请说明此系统缺口，不要求用户换站。双锁站直达可另用 Exact。"
-                    : code === "coordinate_identity_unverified"
-                        ? "尚未查票。名称与提交坐标缺少一致证据；请核实受影响端点的准确地点，保留其余出行条件。"
-                        : "尚未查票。地点缺少必要地址或行政归属；只请用户补充受影响端点，保留另一端及原条件。",
-                next: null, recovery: [],
-            };
+            const affected = model.workflow?.failure?.endpoint ?? model.workflow?.dependency?.endpoint;
+            const query = model.workflow?.query_input ?? {};
+            const endpoints = query.endpoints && typeof query.endpoints === "object" ? query.endpoints : {};
+            const stationPair = [endpoints.origin, endpoints.destination].every(endpoint => endpoint?.kind === "station" && typeof endpoint.text === "string" && endpoint.text.trim() && typeof endpoint.station_code === "string" && /^[A-Z]{3}$/.test(endpoint.station_code));
+            if (code === "station_location_evidence_required") {
+                const exactInput = stationPair && typeof query.travel_date === "string" ? { origin: endpoints.origin.text, destination: endpoints.destination.text, travel_date: query.travel_date } : undefined;
+                return { status: "system_evidence_required", result: { service_execution_id: id, service_id: execution.service_id, reason: code, affected_endpoint: affected, failure: model.workflow?.failure, query,
+                        ...(exactInput ? { new_query_template: { command: "itpay services run itpay-rail-exact --input-json <双锁站直达.json> --json", input: exactInput, executable: false, required_input: ["file"], instruction: "当前明确双锁站可核验直达；Exact只覆盖这一站对，仍按原人数、时限和偏好核对结果。" } } : {}) },
+                    instruction: "尚未查票。车站身份已知，但Smart缺车站坐标证据；这是系统证据缺口，不要求用户填技术坐标或换站。" + (exactInput ? "当前双锁站可按完整模板另用Exact核验直达，原需求见query。" : "本路线Smart暂受系统证据限制，当前无可执行恢复；停止并交由维护方补证据。"), next: null, recovery: [] };
+            }
+            if (affected !== "origin" && affected !== "destination")
+                return { status: "input_evidence_required", result: { service_execution_id: id, reason: code, failed_step: model.workflow?.failure?.step_id, failure: model.workflow?.failure, query }, instruction: "地点问题未明确受影响侧，当前无可提交修正模板；保留原需求，停止并核对服务端事实，不猜另一端或坐标。", next: null, recovery: [] };
+            const properties = model.workflow_entry.input_schema.properties;
+            if (!properties?.endpoints && properties?.[affected] === undefined)
+                return { status: "contract_unavailable", result: { service_execution_id: id, reason: code, failed_step: model.workflow?.failure?.step_id, failure: model.workflow?.failure, query }, instruction: "旧查询已终止，当前锁定合同缺少可用地点字段；保留原需求并停止，不猜新旧模板或隐藏字段。", next: null, recovery: [] };
+            const input = { ...Object.fromEntries(Object.entries(query).filter(([key]) => properties?.[key] !== undefined)), ...serviceInputTemplate(model.workflow_entry.input_schema, query) };
+            const identityConflict = ["endpoint_kind_conflict", "endpoint_adcode_name_conflict", "endpoint_poi_name_conflict", "endpoint_station_name_code_conflict", "coordinate_name_mismatch"].includes(code);
+            const replacement = code === "area_scope_too_broad" ? { kind: "area", text: "<受影响端的市县镇完整名称>" } : { ...(endpoints[affected]?.kind ? { kind: endpoints[affected].kind } : {}), text: code === "coordinate_identity_unverified" ? "<已核实与地点身份一致的完整地址或地点名>" : "<已补充行政归属的完整地址或地点名>" };
+            const endpointContract = properties?.endpoints !== undefined && (query.endpoints !== undefined || !properties.origin || !properties.destination);
+            if (endpointContract)
+                input.endpoints = { ...endpoints, [affected]: replacement };
+            else {
+                input[affected] = replacement.text;
+                delete input[`${affected}_location`];
+            }
+            const originalPlace = endpoints[affected]?.text ?? query[affected];
+            return { status: "awaiting_input", result: { service_execution_id: id, service_id: execution.service_id, reason: code, failed_step: model.workflow?.failure?.step_id, classification: "location_evidence_required", affected_endpoint: affected, original_place: originalPlace, ...(model.workflow?.failure?.resolved_scope ? { resolved_scope: model.workflow.failure.resolved_scope } : {}), failure: model.workflow?.failure, query,
+                    new_query_template: { command: `itpay services run ${execution.service_id} --input-json <补全原始需求.json> --json`, input, executable: false, required_input: ["file", endpointContract ? `endpoints.${affected}.text` : affected], ...(endpointContract ? { correction_fields: ["text", "kind", "poi_id", "location"].filter(field => { const side = properties?.endpoints?.properties?.[affected]; return !!side?.properties?.[field]; }) } : {}), instruction: "旧执行输入已锁定；补真实地点后将完整input写入JSON文件，按此命令提交新查询，保留另一端、日期、人数和所有原约束。" } },
+                instruction: `旧执行已终止，尚未查票。${identityConflict ? "名称、类别或位置证据存在冲突；先核实返回原因，不能修改kind绕过。" : "完整地点名称合法，但尚缺唯一身份证据；可先用地图或浏览短查，不要求必填门牌或坐标。"}新证据确定类别且原意未变可纠正kind；改变目的地或扩大范围须先取得真实同意。保留原地点及范围；${affected === "origin" ? "出发端" : "到达端"}原文见original_place。有新证据后只补充${affected === "origin" ? "出发端" : "到达端"}${code === "area_scope_too_broad" ? "的市县镇范围" : code === "coordinate_identity_unverified" ? "的已核实地点身份；已移除未核实坐标，不猜坐标" : "的完整地点和行政归属"}。使用当前完整new_query_template；不能在旧执行伪造修改，也不能直接提交占位符。`, next: null, recovery: [] };
         }
         if (state === "failed" && ["login_required", "rate_limited"].includes(workflowReason ?? "")) {
             const login = workflowReason === "login_required";
@@ -1807,7 +1914,7 @@ function servicesNextEnvelope(model) {
                 recovery: [resume],
             };
         }
-        if (state === "human_action" && model.workflow?.human_action) {
+        if ((state === "human_action" || (state === "failed" && model.workflow?.human_action?.context?.quote_recovery === true)) && model.workflow?.human_action) {
             const action = model.workflow.human_action;
             const requiredFields = requiredInputFields(action.input_schema);
             const rawPlaces = action.context?.places;
@@ -1837,9 +1944,10 @@ function servicesNextEnvelope(model) {
                     status: "confirmation_required",
                     result: { service_execution_id: id, service_id: execution.service_id,
                         human_action: { action_type: action.action_type, input_schema: action.input_schema },
-                        required_fields: requiredFields, sides,
+                        required_fields: requiredFields, sides, query: model.workflow?.query_input,
                         ...(sides.some(side => side.status !== "resolved" && !side.candidates?.length && ["ADDRESS_REQUIRED", "ADMINISTRATIVE_AREA_UNRESOLVED"].includes(side.reason ?? "")) ? {
                             new_query_template: { command: `itpay services run ${execution.service_id} --input-json <补全原始需求.json> --json`, executable: false,
+                                input: serviceInputTemplate(model.workflow_entry.input_schema, model.workflow?.query_input ?? {}),
                                 required_input: ["补缺失端点", "保留原始日期人数时限偏好及已确认端点"], instruction: "原执行锁定输入；补全原需求后用新查询，不提交不存在的候选。" },
                         } : {}) },
                     instruction: sides.some(side => side.status !== "resolved" && !side.candidates?.length)
@@ -1874,12 +1982,12 @@ function servicesNextEnvelope(model) {
                     ? review.requirements_remaining
                     : undefined;
                 return {
-                    status: "booking_review_required",
-                    result: { service_execution_id: id, service_id: execution.service_id, review,
+                    status: state === "failed" ? "quote_recovery_required" : "booking_review_required",
+                    result: { service_execution_id: id, service_id: execution.service_id, review, ...(state === "failed" ? { failure: model.workflow?.failure } : {}),
                         action_type: action.action_type, required_fields: requiredFields,
                         ...(requirementsRemaining ? { requirements_remaining: requirementsRemaining } : {}) },
                     ...(reviewURL ? { handoff: { url: reviewURL, kind: "booking_review" } } : {}),
-                    instruction: `${reviewURL ? "官方确认页见 handoff.url，打开不等于确认；沿用已知人数和席别。" : "当前草稿见 review。"} 对照对话只补缺失选择或真实条款同意；无字母偏好自动分配，不默认问字母。仅代码修正且车次、实际席别、人数、价格及条款不变，沿用已有明确确认；实质变化只核对变化。提交当前 draft_revision/notice_version 及必要字段，未得真实同意不能填 accept_non_guaranteed；座位请求不保证分配。身份信息只在官方 Checkout 页填写。`,
+                    instruction: `${state === "failed" ? `${typeof model.workflow?.failure?.affected_leg === "number" ? `第${model.workflow.failure.affected_leg + 1}段` : ""}报价失败：${RAIL_QUOTE_FAILURE_GUIDANCE[model.workflow?.failure?.reason_code ?? ""] ?? "报价核验未完成。"} 当前无完整报价、无付款入口。按用户意愿有界地重新核验一次同一购买；复制下方当前确认模板，未变条款沿用真实同意，价格/车次/席别/人数/条款变化须确认差异。无票或车次变化时先让用户决定，不能自动换路线。支付尝试后不得修订。 ` : ""}${reviewURL ? "官方确认页见 handoff.url，打开不等于确认；沿用已知人数和席别。" : "当前草稿见 review。"} 对照对话只补缺失选择或真实条款同意；无字母偏好自动分配，不默认问字母。仅代码修正且车次、实际席别、人数、价格及条款不变，沿用已有明确确认；实质变化只核对变化。复制 interaction.input_template.input；自动分配使用该对象数组，不传 null 或字符串。只有用户本人已接受当前条款，才把 accept_non_guaranteed 改为 true；选车或委托选票不等于条款同意，false是未同意保护而非模板错误。缺同意时仅用 review.consent_question 问一次；没有该文案时说明座位/卧铺偏好可能自动分配，并按当前notice补整程条款。已有充分同意且条件不变则不再问。身份信息只在官方 Checkout 页填写。`,
                     next: null,
                     interaction: {
                         schema_version: "itpay.interaction.v1",
@@ -1887,6 +1995,8 @@ function servicesNextEnvelope(model) {
                         input_template: {
                             command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved --input-json <file> --json`,
                             required_input: ["file", ...requiredFields],
+                            input: review.input_template && typeof review.input_template === "object"
+                                ? review.input_template : serviceInputTemplate(action.input_schema ?? {}, review),
                             executable: false,
                         },
                     },
@@ -1916,35 +2026,33 @@ function servicesNextEnvelope(model) {
             command = `itpay services checkout ${id} --json`;
         // input_required: the resume command needs a real file path — expose it as
         // a non-executable input_template, not a fake `next.command`.
+        const guidance = railServiceGuidance(execution.service_id, model.workflow_entry?.input_schema);
         const inputTemplate = state === "input_required"
             ? {
                 command: `itpay services run ${execution.service_id} --execution ${id} --input-json <file> --json`,
-                required_input: ["file"],
+                input: serviceInputTemplate(model.workflow_entry?.input_schema ?? {}, Object.keys(model.workflow?.query_input ?? {}).length ? (model.workflow?.query_input ?? {}) : guidance?.input_example ?? {}),
+                required_input: ["file", ...requiredInputFields(model.workflow_entry?.input_schema)],
                 executable: false,
             }
             : undefined;
-        const guidance = railServiceGuidance(execution.service_id, model.workflow_entry?.input_schema);
+        if (state === "input_required" && execution.service_id === "itpay-rail-smart" && !guidance) {
+            return { status: "contract_unavailable", result: { service_execution_id: id, service_id: execution.service_id }, instruction: "当前锁定合同缺失；读取一次同执行合同后仍缺失就停止，不猜新旧输入结构。", next: { command: `itpay services get ${id} --json`, reason: "获取锁定合同一次" }, recovery: [] };
+        }
         const failedStep = recovery ? model.workflow?.failure?.step_id : 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 providerErrorCode = typeof failedInvocation?.error_code === "string" && failedInvocation.error_code ? failedInvocation.error_code : undefined;
-        const quoteFailure = execution.service_id === "itpay-rail-booking" ? {
-            quote_source_unavailable: "实时车票数据暂不可用；保留原选择，稍后按用户意愿重新核验，不创建替代订单。",
-            quote_train_changed: "所选车次的时刻或运行信息已变化；向用户说明并征询是否重新查票。",
-            quote_seat_changed: "所选席别已变化；向用户说明并征询新的席别选择。",
-            quote_seat_unavailable: "所选席别当前无足够余票；告知用户并由其决定是否换方案。",
-            quote_refresh_expired: "实时报价过程超时；保留原选择，不把旧价当可付款价格。",
-        }[providerErrorCode ?? ""] : undefined;
-        const failureCode = model.workflow?.failure?.reason_code ?? providerErrorCode ?? model.workflow?.error_code;
+        const quoteFailure = execution.service_id === "itpay-rail-booking" ? RAIL_QUOTE_FAILURE_GUIDANCE[(model.workflow?.failure?.reason_code === "workflow_failed" ? providerErrorCode : model.workflow?.failure?.reason_code) ?? providerErrorCode ?? ""] : undefined;
+        const failureCode = model.workflow?.failure?.reason_code === "workflow_failed" && providerErrorCode && RAIL_QUOTE_FAILURE_GUIDANCE[providerErrorCode] ? providerErrorCode : model.workflow?.failure?.reason_code ?? providerErrorCode ?? model.workflow?.error_code;
         const failedInstruction = recovery
             ? quoteFailure
-                ? quoteFailure
+                ? `${typeof model.workflow?.failure?.affected_leg === "number" ? `第${model.workflow.failure.affected_leg + 1}段报价失败。` : ""}${quoteFailure} 当前整程未取得完整有效报价，没有付款入口；保留同一购买和未变化的选择，当前没有可提交恢复动作，停止；需要用户决定或系统处理，不能靠反复 get/next 重新报价，不能收取其余段款项或重复创建购买。`
                 : failedStepGuidance
                     ? `执行在「${failedStepGuidance.meaning}」步失败${failureCode ? `（错误码：${failureCode}）` : ""}：${failedStepGuidance.hint}。先核对原因和当前执行状态，不要盲目重放。`
                     : state === "failed"
-                        ? `执行已失败${failureCode ? `（错误码：${failureCode}）` : ""}且不可续用；核对服务端原因、订单与付款事实后再决定下一步。`
+                        ? `执行已失败${failureCode ? `（错误码：${failureCode}）` : ""}且不可续用；${execution.service_id === "itpay-rail-booking" || paymentVerified ? "核对服务端原因、订单与付款事实" : "保留原地点和约束，核对服务端原因；当前没有可执行恢复则停止，不重复读取终态"}后再决定下一步。`
                         : "执行未完成，请按步骤错误处理；不要重建执行或重复调用。"
             : undefined;
         return {
@@ -1967,8 +2075,8 @@ function servicesNextEnvelope(model) {
                     ? (model.workflow?.human_action?.context?.review
                         ? "服务已到付款步骤，可直接 Checkout 付款；如需调整席别/座位偏好，先用 confirm_booking 动作修订（会重新报价并锁定新价），完成后再付款。"
                         : "服务已到付款步骤，使用现有 Checkout 完成扫码付款。")
-                    : guidance
-                        ? "按 result.guidance 的字段契约填写输入后继续同一服务执行；不要臆造字段名。"
+                    : state === "input_required" && guidance
+                        ? RAIL_ENDPOINT_BRIEF + "按 result.guidance 的字段契约填写输入后继续同一服务执行；不要臆造字段名。"
                         : "继续读取同一执行；缺少输入时按服务声明补齐。"),
             next: recovery || inputTemplate ? null : { command, reason: "继续当前流程" },
             ...(inputTemplate || (state === "payment" && model.workflow?.human_action?.context?.review) ? {
@@ -1985,7 +2093,7 @@ function servicesNextEnvelope(model) {
                     } : {}),
                 },
             } : {}),
-            recovery: recovery && state === "failed"
+            recovery: recovery && state === "failed" && !["itpay-rail-exact", "itpay-rail-smart"].includes(execution.service_id)
                 ? [{ command: `itpay services get ${id} --json`, reason: "核对本执行的错误、结果和付款事实" }]
                 : [],
         };
@@ -2460,6 +2568,36 @@ export async function runServicesRun(backend, config, serviceID, input, options
         await runServicesNext(backend, id, options);
     }
     catch (cause) {
+        if (cause instanceof HttpError && cause.code === "capability_input_invalid") {
+            const schema = cause.payload?.input_schema;
+            const executionID = cause.payload?.service_execution_id ?? id;
+            throw new CommandContractError(cause.code, cause.message, "Agent按当前模板自行修正错误字段和JSON层级，保留已有摘要的端点含义及原地点/日期/人数，不重复研究或事后补写冒充查询前摘要；不要向用户询问技术字段。只有真实业务歧义才问人；使用返回的执行身份恢复，未创建时用原服务。", schema ? [] : [{ command: executionID ? `itpay services get ${executionID} --json` : "itpay catalog list --json", reason: "获取当前锁定合同；仍缺合同则停止，不猜旧写法" }], schema ? { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: {
+                    command: `itpay services run ${serviceID}${executionID ? ` --execution ${executionID}` : ""} --input-json <file> --json`,
+                    input: serviceInputTemplate(schema, input), required_input: ["file", ...requiredInputFields(schema)], executable: false,
+                } } : undefined, { service_id: serviceID, ...(executionID ? { service_execution_id: executionID } : {}), execution_created: cause.payload?.execution_created ?? Boolean(executionID), ...(typeof cause.payload?.provider_called === "boolean" ? { provider_called: cause.payload.provider_called } : {}), input_errors: cause.payload?.input_errors ?? [cause.message], ...(schema ? { input_schema: schema } : {}) });
+        }
+        if (cause instanceof HttpError && ["invalid_selection", "selection_wrong_buyer"].includes(cause.code ?? "")) {
+            const reason = cause.payload?.reason;
+            const inputInvalid = reason === "input_constraint_invalid";
+            throw new CommandContractError(cause.code, cause.message, inputInvalid ? "输入违反当前完整计划约束。读取原查询的完整购买模板，修正人数、完整段数和顺序；不要追加未声明字段或拆单。"
+                : cause.code === "selection_wrong_buyer" ? "当前身份无权使用这份购买凭据。停止；不要切换身份绕过，也不展示其他买家资料。"
+                    : reason === "stored_selection_inconsistent" ? "服务端凭据与已存目录不一致，补参数无法修复。停止购买并提供诊断标识 stored_selection_inconsistent；不猜字段、不重新创建购买。"
+                        : "购买凭据未通过校验，原因尚未确定且没有安全自动恢复。停止，不把推测报成原因或追加隐藏字段。", inputInvalid ? [{ command: "itpay services list --json", reason: "定位原查询并读取当前完整购买模板" }, { command: "itpay docs show rail-booking --json", reason: "读取正式输入约束" }] : [], undefined, { service_id: serviceID, ...(id ? { service_execution_id: id } : {}), ...(reason ? { reason } : {}), execution_created: Boolean(id) });
+        }
+        if (cause instanceof HttpError && cause.code === "rail_selection_expired") {
+            const expiry = cause.payload?.selection_expiry;
+            const bookingID = expiry?.booking_execution_id ?? id;
+            const refreshInput = !bookingID && expiry?.safe_new_query && ["itpay-rail-smart", "itpay-rail-exact"].includes(expiry.query_service_id) ? expiry.query_input : undefined;
+            const refresh = refreshInput !== undefined;
+            throw new CommandContractError(cause.code, cause.message, refresh ? "刚才余票信息已过时，按原条件刷新一次真实库存（可能消耗查询额度）；不需要重复批准同条件查票。有价格、库存或条款变化再确认；不复用旧库存、不换站或日期。"
+                : bookingID ? "保留原购买执行，先读取订单与付款事实；不要重新查票、创建替代购买或重复付款。"
+                    : "旧选择凭据已过期，历史详情不能续期；缺少完整原查询条件或安全购买状态证据，停止自动刷新。", bookingID ? [{ command: `itpay services next ${bookingID} --json`, reason: "核对原购买执行和付款状态" }] : [], refreshInput && expiry ? { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: {
+                    command: `itpay services run ${expiry.query_service_id} --input-json <file> --json`, input: refreshInput, required_input: ["file"], executable: false,
+                } } : undefined, { service_id: serviceID, ...(bookingID ? { service_execution_id: bookingID } : {}), ...(expiry ? { selection_expiry: expiry } : {}) });
+        }
+        if (cause instanceof HttpError && cause.code === "rail_journey_selection_required") {
+            throw new CommandContractError(cause.code, cause.message, "整程必须使用原查询当前完整 ticket plan 的 selections 模板；手填 legs 只兼容单腿。缺少整程模板时读取原方案；不拆单、不拼腿、不擅自换站或日期。", [{ command: "itpay services list --json", reason: "找回原查询并读取其完整方案模板" }, { command: "itpay docs show rail-booking --json", reason: "读取正式整程输入合同" }], undefined, { service_id: serviceID, ...(id ? { service_execution_id: id } : {}) });
+        }
         if (cause instanceof HttpError && cause.code === "rail_seat_code_invalid" && id) {
             throw new CommandContractError(cause.code, cause.message, "席别必须使用原查询 booking_template.seat_choices 中与名称对应的代码，不能填“二等座”等显示名。用原 selection token 与真实人数修正输入，继续同一booking execution；若只是代码写法修正且车次、席别名称、人数等购买条件未变，沿用用户已给的确认，不再重复询问。", [{ command: `itpay services next ${id} --json`, reason: "读取同一booking当前状态后修正输入" }]);
         }