@itpay/cli 2.1.41 → 2.1.45

package/dist/src/services/rail/catalog.js

@@ -0,0 +1,261 @@
+import { CLI_VERSION, cliDistribution } from "../../state/config.js";
+export class RailCatalogEncodingError extends Error {
+    constructor(encoding) {
+        super(`catalog encoding ${JSON.stringify(encoding)} is not supported by CLI ${CLI_VERSION} ` +
+            `(${cliDistribution()}); obtain a compatible exact version through this installation channel. ` +
+            `The committed catalog is intact`);
+        this.name = "rail_catalog_encoding";
+    }
+}
+function scopeFromProfiles(value) {
+    const profiles = Array.isArray(value) ? value : [];
+    const selected = profiles.find((p) => Array.isArray(p) && Array.isArray(p[1]) && p[1].includes("balanced")) ?? profiles[0];
+    if (!Array.isArray(selected))
+        return { origin: "legacy_unknown", destination: "legacy_unknown",
+            duration_basis: "legacy_unknown", arrival_basis: "legacy_unknown", cost_basis: "legacy_unknown",
+            duration_minutes: null, estimated_total_cost: null, cost_incomplete: true };
+    const extras = selected[10] && typeof selected[10] === "object" ? selected[10] : {};
+    const total = typeof selected[9] === "number" && extras.ci !== true ? selected[9] / 100 : null;
+    return {
+        origin: extras.os ?? "legacy_unknown", destination: extras.ds ?? "legacy_unknown",
+        duration_basis: extras.db ?? "legacy_unknown", arrival_basis: extras.ab ?? "legacy_unknown",
+        cost_basis: extras.cb ?? "legacy_unknown", duration_minutes: selected[8] ?? null,
+        estimated_total_cost: total, cost_incomplete: extras.ci === true,
+    };
+}
+function asString(v) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function asIndex(v, bound) {
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v >= bound) {
+        throw new Error("shared_rows: index out of bounds");
+    }
+    return v;
+}
+function asObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function datedTime(date, value) {
+    const raw = asString(value);
+    if (!raw)
+        return null;
+    if (/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}/.test(raw))
+        return raw.replace("T", " ").slice(0, 16);
+    const short = raw.match(/^(\d{2}:\d{2})(?:\+(\d+))?$/);
+    const day = asString(date);
+    if (!short || !day)
+        return null;
+    if (!short[2])
+        return `${day} ${short[1]}`;
+    const shifted = new Date(`${day}T00:00:00Z`);
+    if (Number.isNaN(shifted.getTime()))
+        return null;
+    shifted.setUTCDate(shifted.getUTCDate() + Number(short[2]));
+    return `${shifted.toISOString().slice(0, 10)} ${short[1]}`;
+}
+function elapsedMinutes(departure, arrival) {
+    if (!departure || !arrival)
+        return null;
+    const start = Date.parse(departure.replace(" ", "T") + "Z");
+    const end = Date.parse(arrival.replace(" ", "T") + "Z");
+    return Number.isFinite(start) && Number.isFinite(end) && end >= start ? (end - start) / 60_000 : null;
+}
+function seatOffer(row, names) {
+    if (!Array.isArray(row))
+        return null;
+    const extras = asObject(row[7]);
+    const code = asString(row[1]);
+    return {
+        offer_ref: row[0], seat_type: code ?? null, seat_name: code ? names[code] ?? code : null,
+        inventory_status: row[2] ?? null, quantity: row[3] ?? null, unit_price_fen: row[4] ?? null,
+        eligible: row[5] === true, requires_quote: row[6] === true,
+        price_source: extras.s ?? "sale_price", quote_price_unverified: extras.u === true,
+        conflicted: extras.c === true,
+        ...(Array.isArray(extras.o) ? { price_observations_fen: extras.o } : {}),
+    };
+}
+function decodeRide(row, wait, stations, services) {
+    if (!Array.isArray(row)) {
+        const ride = asObject(row);
+        if (!Object.keys(ride).length)
+            throw new Error("rail catalog: malformed ride row");
+        const refs = Array.isArray(ride.service_refs) ? ride.service_refs : [];
+        const codes = [...new Set(refs.map((ref) => asObject(services[asString(ref) ?? ""]).tc)
+                .filter((code) => typeof code === "string" && code.length > 0))];
+        const departure = datedTime(ride.boarding_date, ride.departure_at ?? ride.departure);
+        const arrival = datedTime(ride.boarding_date, ride.arrival_at ?? ride.arrival);
+        return { train_codes: codes, train_code: codes.join("/"),
+            from_station: stations[asString(ride.from_station_code) ?? ""] ?? ride.from_station ?? null,
+            to_station: stations[asString(ride.to_station_code) ?? ""] ?? ride.to_station ?? null,
+            boarding_date: ride.boarding_date ?? null,
+            departure, arrival, duration_minutes: elapsedMinutes(departure, arrival),
+            wait_minutes: typeof wait === "number" ? wait : ride.wait_minutes ?? null,
+            same_run: ride.same_run === true, onboard_stops: Array.isArray(ride.onboard_stops) ? ride.onboard_stops : [],
+        };
+    }
+    const extras = asObject(row[8]);
+    const refs = Array.isArray(row[4]) ? row[4] : [];
+    const codes = [...new Set(refs.map((ref) => asObject(services[asString(ref) ?? ""]).tc)
+            .filter((code) => typeof code === "string" && code.length > 0))];
+    const base = row[0];
+    const departure = datedTime(base, extras.dep);
+    const arrival = datedTime(base, extras.arr);
+    return {
+        train_codes: codes, train_code: codes.join("/"),
+        from_station: stations[asString(row[2]) ?? ""] ?? row[2] ?? null,
+        to_station: stations[asString(row[3]) ?? ""] ?? row[3] ?? null,
+        boarding_date: base ?? null,
+        departure, arrival, duration_minutes: elapsedMinutes(departure, arrival),
+        wait_minutes: typeof wait === "number" ? wait : typeof row[5] === "number" ? row[5] : null,
+        same_run: row[6] === true, onboard_stops: Array.isArray(row[7]) ? row[7] : [],
+    };
+}
+function decodePlans(rawPlans, rawProfiles, packed, catalog, services, names, stations) {
+    const plans = Array.isArray(rawPlans) ? rawPlans : [];
+    const profiles = Array.isArray(rawProfiles) ? rawProfiles : [];
+    const preferred = profiles.find((profile) => Array.isArray(profile) && Array.isArray(profile[1]) && profile[1].includes("balanced")) ?? profiles[0];
+    const profile = Array.isArray(preferred) ? preferred : [];
+    const serviceIndex = Array.isArray(catalog.service_index) ? catalog.service_index : [];
+    const selectedPlan = packed && typeof profile[2] === "number" ? plans[asIndex(profile[2], plans.length)] :
+        plans.find((plan) => Array.isArray(plan) && plan[0] === profile[2]);
+    const selectedRef = Array.isArray(selectedPlan) ? selectedPlan[0] : null;
+    const decoded = plans.map((plan) => {
+        if (!Array.isArray(plan))
+            throw new Error("rail catalog: malformed ticket plan");
+        const refs = (Array.isArray(plan[1]) ? plan[1] : []).map((ref) => packed && typeof ref === "number" ? serviceIndex[asIndex(ref, serviceIndex.length)] : ref);
+        const extras = asObject(plan[7]);
+        const legs = refs.map((ref, index) => {
+            const service = asObject(services[asString(ref) ?? ""]);
+            const offers = Array.isArray(service.of) ? service.of : [];
+            const selectedOffer = plan[0] === selectedRef && Array.isArray(profile[3]) ? profile[3][index] : undefined;
+            const chosen = packed && typeof selectedOffer === "number" ? offers[asIndex(selectedOffer, offers.length)] :
+                offers.find((offer) => Array.isArray(offer) && offer[0] === selectedOffer);
+            return {
+                service_ref: ref ?? null, train_code: service.tc ?? null,
+                from_station: stations[asString(service.f) ?? ""] ?? service.f ?? null,
+                to_station: stations[asString(service.t) ?? ""] ?? service.t ?? null,
+                departure: datedTime(service.d, service.dep), arrival: datedTime(service.d, service.arr),
+                seat_options: offers.map((offer) => seatOffer(offer, names)).filter((offer) => offer !== null),
+                ...(chosen ? { selected_seat: seatOffer(chosen, names) } : {}),
+            };
+        });
+        const amount = asObject(plan[3]);
+        return {
+            ticket_plan_ref: plan[0], passenger_count: plan[2] ?? null,
+            purchase_support: plan[6] ?? "none", rail_amount_verified: plan[4] === true,
+            rail_amount_fen: { default: amount.def ?? null, minimum: amount.min ?? null, maximum: amount.max ?? null },
+            service_fee_fen: plan[5] ?? null, quote_price_unverified: extras.qu === true,
+            legs,
+        };
+    });
+    const selected = decoded.find((plan) => plan.ticket_plan_ref === selectedRef);
+    return { plans: decoded, ...(selected ? { selected } : {}) };
+}
+// _cn_route_text port: "南头 C7608 → 广州南换乘71分 → G2944 重庆西" — kept
+// byte-identical with the planner so a packed journey renders the same text
+// its object form carried.
+function regenerateRoute(ridePairs, rideTable, stations, services) {
+    const name = (code, fallback) => asString(stations[asString(code) ?? ""]) ?? asString(fallback) ?? asString(code) ?? "?";
+    const rides = ridePairs.map((pair) => {
+        if (!Array.isArray(pair) || pair.length !== 2)
+            throw new Error("shared_rows: malformed ride pair");
+        const src = rideTable[asIndex(pair[0], rideTable.length)];
+        if (!Array.isArray(src))
+            throw new Error("shared_rows: malformed ride row");
+        return { row: src, wait: pair[1] };
+    });
+    const first = rides[0];
+    if (first === undefined)
+        return "";
+    const trainCodes = (rideRow) => (Array.isArray(rideRow[4]) ? rideRow[4] : [])
+        .map((ref) => {
+        const svc = services[asString(ref) ?? ""];
+        return asString(svc?.tc);
+    })
+        .filter((c) => Boolean(c));
+    const waitOf = (ride) => typeof ride.wait === "number" ? ride.wait
+        : typeof ride.row[5] === "number" ? ride.row[5]
+            : undefined;
+    const sameRun = (rideRow) => rideRow[6] === true;
+    const parts = [`${name(first.row[2], undefined)} ${trainCodes(first.row).join("/")}`];
+    for (let i = 1; i < rides.length; i += 1) {
+        const prev = rides[i - 1].row;
+        const ride = rides[i];
+        const via = name(prev[3], undefined);
+        const wait = waitOf(ride);
+        parts.push(sameRun(ride.row)
+            ? wait !== undefined ? `${via}同车停${wait}分` : `${via}同车接续`
+            : wait !== undefined ? `${via}换乘${wait}分` : `${via}换乘`);
+        parts.push(`${trainCodes(ride.row).join("/")} ${name(ride.row[3], undefined)}`);
+    }
+    if (rides.length === 1) {
+        parts.push(name(first.row[3], undefined));
+    }
+    return parts.filter((s) => s.trim().length > 0).join(" → ");
+}
+// decodeRailCatalogJourneys returns one summary per committed combination in
+// catalog order. Legacy object-form catalogs (no `encoding`) pass through;
+// shared_rows.v1 rows are positional under journey_columns
+// [ref, route, rides, plans, gc, pr, profiles, tc, ev, rep, tw, risk].
+// Any other encoding throws RailCatalogEncodingError — an explicit upgrade
+// hint, never an empty catalog.
+export function decodeRailCatalogJourneys(catalog) {
+    const encoding = catalog["encoding"];
+    const layerMap = catalog["choice_layers"]?.["journey_layer"] ?? {};
+    const layerOf = (ref) => layerMap[ref] === "backup" ? "backup" : "main";
+    const stations = asObject(catalog.stations);
+    const services = asObject(catalog.services);
+    const seatNames = asObject(catalog.seat_names);
+    if (encoding === undefined || encoding === null) {
+        const rows = Array.isArray(catalog["journeys"]) ? catalog["journeys"] : [];
+        return {
+            packed: false,
+            journeys: rows.map((j) => {
+                const rec = (j ?? {});
+                const ref = asString(rec["ref"]) ?? asString(rec["journey_id"]) ?? "?";
+                const calculationScope = scopeFromProfiles(rec["profiles"]);
+                const rides = (Array.isArray(rec.rides) ? rec.rides : []).map((ride) => decodeRide(ride, null, stations, services));
+                const ticketPlans = decodePlans(rec.plans, rec.profiles, false, catalog, services, seatNames, stations);
+                return {
+                    ref,
+                    route: asString(rec["route"]) ?? asString(rec["route_text"]) ?? asString(rec["summary"]) ?? "",
+                    defaultLayer: layerOf(ref),
+                    rides,
+                    ...(calculationScope ? { calculation_scope: calculationScope } : {}),
+                    ticket_plans: ticketPlans.plans,
+                    ...(ticketPlans.selected ? { selected_plan: ticketPlans.selected } : {}),
+                };
+            }),
+        };
+    }
+    if (encoding !== "shared_rows.v1") {
+        throw new RailCatalogEncodingError(encoding);
+    }
+    const columns = catalog["journey_columns"];
+    if (!Array.isArray(columns) || columns[0] !== "ref" || columns[1] !== "route" || columns[2] !== "rides") {
+        throw new RailCatalogEncodingError(`${String(encoding)} (unexpected journey_columns)`);
+    }
+    const rideTable = (Array.isArray(catalog["ride_table"]) ? catalog["ride_table"] : []);
+    const journeys = (Array.isArray(catalog["journeys"]) ? catalog["journeys"] : []);
+    return {
+        packed: true,
+        journeys: journeys.map((row) => {
+            if (!Array.isArray(row))
+                throw new Error("shared_rows: journey row is not an array");
+            const ref = asString(row[0]) ?? "?";
+            const route = asString(row[1]) ??
+                (Array.isArray(row[2]) ? regenerateRoute(row[2], rideTable, stations, services) : "");
+            const rides = (Array.isArray(row[2]) ? row[2] : []).map((pair) => {
+                if (!Array.isArray(pair) || pair.length !== 2)
+                    throw new Error("shared_rows: malformed ride pair");
+                return decodeRide(rideTable[asIndex(pair[0], rideTable.length)], pair[1], stations, services);
+            });
+            const calculationScope = scopeFromProfiles(row[6]);
+            const ticketPlans = decodePlans(row[3], row[6], true, catalog, services, seatNames, stations);
+            return { ref, route, defaultLayer: layerOf(ref), rides,
+                ...(calculationScope ? { calculation_scope: calculationScope } : {}),
+                ticket_plans: ticketPlans.plans,
+                ...(ticketPlans.selected ? { selected_plan: ticketPlans.selected } : {}) };
+        }),
+    };
+}

package/dist/src/services/rail/checkout.js

@@ -0,0 +1,19 @@
+export function railCheckoutItinerary(booking, presentation) {
+    const review = booking.workflow?.human_action?.context?.review;
+    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) {
+        const itinerary = { legs, passengers: quote?.passengers ?? review?.passengers ?? null, purchase_unit: "journey" };
+        const itineraryTitle = legs.map(leg => [leg.train_code, leg.from_station, "->", leg.to_station].filter(value => typeof value === "string" && value.length).join(" ")).join(" / ");
+        return { itinerary, itineraryTitle };
+    }
+    return {};
+}

package/dist/src/services/rail/fulfillment.js

@@ -0,0 +1,76 @@
+export 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,
+    };
+}
+export 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.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 } : {}),
+        ...(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, total_legs: rail.legs.length, message: rail.message, legs },
+    };
+    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",
+            result: { ...result, ...(orderID ? { aftercare: { command: `itpay order ${orderID} --json`, when: "仅用户请求核对订单或售后时" } } : {}) },
+            instruction: `告诉用户：车票已出票，座位以实际出票为准，平台不提供 12306 票号，可在订单页核对行程。不要在对话中索要乘车人身份信息。${detailsPending ? "部分席位信息未能同步，请前往 12306 核对行程；不要重复购买。" : ""}`,
+            next: null,
+            recovery: [],
+        };
+    }
+    if (rail.state === "manual_review") {
+        return {
+            status: "manual_review",
+            result,
+            instruction: `告诉用户：付款已确认，已出票 ${rail.issued_legs}/${rail.legs.length}，其余需要人工核对；请勿重复付款或重新下单，已出票的车票会保留。未知结果先对账，退款按对应段处理，不承诺整笔退款或时效。`,
+            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: `告诉用户：付款已确认，已出票 ${rail.issued_legs}/${rail.legs.length}，后台继续处理；付款成功不代表整程出票，请勿重复购买或再次付款。稍后只读取同一任务。`,
+            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: [],
+    };
+}

package/dist/src/services/rail/guide.js

@@ -0,0 +1,110 @@
+import { serviceInputTemplate } from "../shared/input.js";
+// Declared at execution creation: the client understands the rail.progressive.v2
+// response format (rail_planning projection, snapshot paging, rsel_ handles).
+// The server alone decides service version, quota and provider credentials.
+export const RAIL_PROGRESSIVE_FEATURES = ["rail.progressive.v2"];
+export const RAIL_ENDPOINT_BRIEF = "查询前先留下2–4行端点理解摘要：两端各指哪里、是车站/行政范围/具体地点、依据及未确定事实，再说明日期/人数/时限与Exact/Smart选择。对话或现有route-brief.txt二选一；已有摘要沿用，只更新变化项。含义不清先澄清，定位待核验不等于含义不清；勿凭字尾猜类型。";
+export const RAIL_SERVICE_GUIDANCE = {
+    "itpay-rail-exact": {
+        when_to_use: "已知可信站对时先用本服务核验直达；城市需求可先形成有依据的站对假设。只覆盖这一站对，不代表全城市最优。只有明确可靠路线知识可直接用；大概率判断先短查，受阻且清晰双站可Exact核验。查询前记录两端含义、类别、依据、未知事实和Exact/Smart选择；格式见已读rail-booking。",
+        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: "<用户日期 YYYY-MM-DD>" },
+        ],
+        input_example: { origin: "<已核实出发站名>", destination: "<已核实到达站名>", travel_date: "<用户出行日期 YYYY-MM-DD>" },
+        notes: [
+            "本服务只接受这三个字段，多传字段会被供应商拒绝",
+            "查询为空只说明这一已解析站对；允许中转可用Smart保持双站；改变用户指定站须先取得同意",
+        ],
+    },
+    "itpay-rail-smart": {
+        when_to_use: "需要广泛站点比较、中转或具体地址接驳时使用；有可信站对且只需先核验直达可用 Exact。只有明确可靠路线知识可直接用；大概率判断先短查，受阻且清晰双站可Exact核验。查询前记录两端含义、类别、依据、未知事实和Exact/Smart选择；格式见已读rail-booking。",
+        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: "<用户日期 YYYY-MM-DD>" },
+        ],
+        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: "depart_before", description: "不晚于该时间出发" },
+            { name: "arrive_before", description: "不晚于该时间到达" },
+            { name: "user_query", description: "旅行需求原话，最多4096 UTF-8字节；时间等明确条件仍填写对应结构化字段" },
+            { name: "seat_preferences", description: "已确认的席别代码数组，不填写旅客身份" },
+            { name: "priority", enum: "balanced|fastest|cheapest|safest|flexible", description: "方案偏好" },
+            { name: "duration_basis", enum: "rail|door_to_door", description: "最快默认按铁路全程含换乘；明确要求且接驳证据完整时可按门到门" },
+            { name: "max_transfers", description: "允许中转次数，0-2" },
+            { name: "passengers", description: "成人乘客整数 1-5；不填写身份资料" },
+        ],
+        input_example: { origin: "<用户出发地点>", destination: "<用户目的地>", travel_date: "<用户出行日期 YYYY-MM-DD>", priority: "fastest", passengers: 1 },
+        notes: [
+            "位置有歧义时会进入位置确认步骤，请用户选定后继续同一执行",
+            "推荐结果含每趟车的席别与余票；购票在后续受保护流程完成",
+        ],
+    },
+};
+export function railServiceGuidance(serviceID, schema) {
+    const guidance = RAIL_SERVICE_GUIDANCE[serviceID];
+    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 各填完整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；端点/日期新查询可复用有效事实" },
+        ]).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 混用", "唯一地点直接解析；真实候选只确认有歧义一端；地图等待按可续用状态恢复，终态有新证据才用返回新查询模板，无动作则停止"],
+    };
+}
+export const WORKFLOW_STEP_GUIDANCE = {
+    input: { meaning: "输入校验", hint: "核对本服务的输入契约和服务端错误码；本执行的输入不能凭猜测修复" },
+    quota: { meaning: "额度检查", hint: "查看实际额度及授权状态；只按返回的登录或等待动作处理" },
+    geo: { meaning: "位置解析", hint: "查看实际地点解析错误；有歧义时让用户选择返回的候选" },
+    geo_confirm: { meaning: "确认后位置解析", hint: "核对服务端记录的候选与用户实际选择" },
+    resolved: { meaning: "位置解析复核", hint: "查看未满足的实际位置条件" },
+    resolved_after_confirm: { meaning: "位置确认复核", hint: "核对已确认地点与服务端复核结果" },
+    search: { meaning: "供应商车次检索", hint: "查看供应商返回的错误码与当前站对；不要推断是字段或站名错误" },
+    catalog: { meaning: "可行车次计算", hint: "查看已保存结果和实际过滤原因；不要无原因改日期或站点" },
+    recommend: { meaning: "方案推荐", hint: "查看已保存候选和实际推荐失败原因；不要无原因放宽条件" },
+    delivery: { meaning: "交付", hint: "读取当前执行状态；已有订单或付款状态不明时先核实，不重建" },
+};
+export function locationInputInstruction(schema) {
+    const properties = schema?.properties;
+    if (properties?.endpoints)
+        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 " " + 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 才展示候选名称、地址和高德链接，等待用户选择，禁止自行选第一项。";
+}
+// Compatibility normalization belongs only to the declared rail adapter.
+export function railInputTemplate(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 = serviceInputTemplate(schema, known);
+    // Current Smart exposes endpoints through oneOf rather than top-level required.
+    // Preserve a supplied legacy branch; otherwise use the complete declared pair.
+    if (properties?.endpoints && !known.origin && !known.destination && !result.endpoints)
+        result.endpoints = serviceInputTemplate(properties.endpoints);
+    if (properties?.accept_non_guaranteed)
+        result.accept_non_guaranteed = false;
+    return result;
+}
+export function railOverviewInstruction(topic) {
+    return `尚未创建执行或查询。先读 ${topic} 服务指南、理解用户完整地点与约束，形成简短路线摘要后选择操作；查询结果不是价格同意。`;
+}

package/dist/src/services/rail/invocation.js

@@ -0,0 +1,54 @@
+import { plainValueLines } from "../shared/envelope.js";
+import { locationConfirmationEnvelope } from "./query.js";
+export function railInvocationProjection(response, requestedCapability, input, itemCount) {
+    const baseResult = {};
+    let instruction;
+    const preview = response.invocation?.safe_result_preview;
+    const notices = Array.isArray(preview?.notices) ? preview.notices.map((notice) => {
+        if (!notice || typeof notice !== "object" || !("code" in notice) || !("message" in notice) || typeof notice.message !== "string")
+            return notice;
+        if (!["RAIL_TRANSFER_SCOPE_LIMIT", "RAIL_TRANSFER_SEARCH_INCOMPLETE"].includes(String(notice.code)))
+            return notice;
+        return { ...notice, message: notice.message.replace(/可按主要枢纽分段查询[。；]?/g, "") };
+    }) : preview?.notices;
+    if (!response.effective_quota?.exhausted && preview?.search_status === "LOCATION_CONFIRMATION_REQUIRED" && preview.location_confirmation) {
+        return { early: { value: locationConfirmationEnvelope(response.execution.service_execution_id, requestedCapability.capability_id, input, preview.location_confirmation),
+                plainResult: plainValueLines(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,
+            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,
+        };
+    }
+    if (itemCount === 0 && Array.isArray(notices)) {
+        const railNotice = 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} 说明本次已查范围和未完成原因，按服务端提供的当前动作恢复；不能据此断言没有车，不默认扩大范围或让用户另选分段站点。`;
+    }
+    if (itemCount > 0 && baseResult.catalog) {
+        instruction = "先向用户说明排在首位的推荐方案和其他方案的时间、费用与便利性取舍。items 包含本次返回的合格候选，用户不满意时继续从该列表比较，不必重复查票。搜索是否完成、目录是否截断、覆盖范围和模型降级以 catalog 为准；不能把部分结果说成完整搜索。费用尚需购票前核验。姓名、身份证和手机号仅在 ItPay 网页填写。";
+    }
+    if (itemCount > 0 && preview?.journey_summary) {
+        instruction = "先按 journey_summary 报告本次已查询范围内的可用车次、换乘走法和实际乘车组合数量，不能用 catalog.total 或 items 数量冒充车次或组合数。按 journeys 展示组合，推荐置顶，保留全部组合和 train_services 车次列表供用户查看。每组先说明乘坐哪些车、在哪里真正换车以及等待多久；rides.onboard_stops 是同车接续停站，无需下车，可能需车内换座，不计入换乘次数。席别、余票、价格及接驳是组合下的选择，通过 candidate_ids 查对应 items；确认具体选择后才使用该 item 的编号，不猜席别或自动付款。30 分钟只是在已确认便捷换乘站点的筛选下限，不是接续保证。不得把多段票称为已可购买的套票；以 purchase_supported 为准。覆盖不完整、截断和模型仅看短名单时必须说明。姓名、身份证和手机号只在 ItPay 网页填写。";
+    }
+    return { ...(baseResult.catalog ? { catalog: baseResult.catalog } : {}), ...(instruction ? { instruction } : {}), ...(preview?.resolved_locations ? { suffix: " 按 resolved_locations 说明实际解析地点；区域级位置仅是范围代表点，接驳时间不是从用户精确位置计算的。" } : {}) };
+}

package/dist/src/services/rail/page.js

@@ -0,0 +1,76 @@
+import { compactRailJourney } from "./results.js";
+import { exactTrainRow } from "./query.js";
+import { publicPurchaseTemplate } from "../shared/platform.js";
+import { writeCommandEnvelope, plainValueLines } from "../shared/envelope.js";
+export function renderRailResultPage(response, serviceExecutionID, resultItemID, offset, limit, options) {
+    const page = response.page;
+    const container = (page.result ?? page);
+    const exactCandidate = limit === 1 && Array.isArray(container.candidates) && container.candidates.length === 1
+        ? container.candidates[0] : undefined;
+    if (exactCandidate && typeof exactCandidate.train_code === "string" && Array.isArray(exactCandidate.seats)) {
+        const offer = exactCandidate.booking_offer;
+        const { booking_offer: _bookingOffer, ...candidateFacts } = exactCandidate;
+        const seats = exactCandidate.seats.filter((seat) => seat.purchase_supported === true);
+        writeCommandEnvelope({
+            status: "exact_train_detail",
+            result: {
+                service_execution_id: serviceExecutionID, result_item_id: resultItemID, result_offset: offset,
+                candidate: candidateFacts,
+                ...(offer?.service_id && offer.selection_token ? { booking_template: {
+                        command: `itpay services run ${offer.service_id} --input-json <file> --json`,
+                        executable: false, required_input: ["file", "passengers", "seat_type"],
+                        seat_choices: seats.map((choice) => ({ seat_type: choice.seat_type, seat_name: choice.seat_name })),
+                        input_example: { selection: { token: offer.selection_token, seat_type: "<用户授权席别对应代码>" }, passengers: "<真实人数>" },
+                        ...(publicPurchaseTemplate(exactCandidate.purchase_operation) ?? {}),
+                    } } : {}),
+            },
+            instruction: offer?.selection_token
+                ? "这是已保存车次的当前详情；只按 purchase_supported 席别代码、库存与报价状态选择。购票模板的人数须按用户真实需求填写；查询价需在后续报价确认。若用户仅要求比较，答复后停止。"
+                : "这条车次当前没有可用的购买凭据；说明席别与余票事实，不要猜测代码或构造订单。",
+            next: null, recovery: [],
+        }, { ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+        });
+        return;
+    }
+    // rail.progressive.v2 saved pages key journeys/journey_page; legacy result
+    // items key candidates/catalog_page. Both are committed, read-only slices.
+    const v2Page = (container.journey_page ?? {});
+    const catalogPage = (container.catalog_page ?? v2Page);
+    const nextOffset = typeof catalogPage.next_offset === "number" ? catalogPage.next_offset : null;
+    const journeys = Array.isArray(container.journeys) ? container.journeys : [];
+    const candidates = Array.isArray(container.candidates) ? container.candidates : journeys;
+    const envelope = {
+        status: candidates.length > 0 ? "result_page" : "result_page_end",
+        result: {
+            service_execution_id: response.service_execution_id,
+            ...(response.service_capability_result_item_id ? { service_capability_result_item_id: response.service_capability_result_item_id } : {}),
+            ...(response.snapshot_id ? { snapshot_id: response.snapshot_id } : {}),
+            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)) }
+                : candidates.some(value => typeof value === "object" && value !== null && "train_code" in value)
+                    ? { candidates: candidates.map((value, index) => exactTrainRow(value, serviceExecutionID, resultItemID, (catalogPage.offset ?? offset) + index)) } : { page }),
+        },
+        instruction: "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。先读完所需页，再合并回答用户；不要逐页播报。",
+        next: nextOffset !== null
+            ? { command: response.snapshot_id
+                    ? `itpay services page ${serviceExecutionID} ${resultItemID} --cursor rcur_${nextOffset} --limit ${limit} --json`
+                    : `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${nextOffset} --limit ${limit} --json`,
+                reason: "读取同版本结果的下一页" }
+            : null,
+        recovery: offset > 0
+            ? [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --json`, reason: "回到第一页" }]
+            : [],
+    };
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: plainValueLines(envelope.result),
+    });
+}

package/dist/src/services/rail/pagination.js

@@ -0,0 +1,6 @@
+import { writeSavedPage } from "../shared/pagination.js";
+export function writeSavedRailPage(envelope, options, key, offset, continuation) {
+    envelope.instruction += " 每页可能因字节预算少于limit；只沿返回next_offset，不算偏移、不并行读无关页。";
+    writeSavedPage(envelope, options, key, offset, continuation, (result, count) => { if (key === "trains")
+        result.read_count = count; });
+}