@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/capabilities/session-search.js

@@ -1,27 +1,55 @@
+/**
+ * 会话检索编排层(RFC §3.2):transport → adapter entry → networkHint 嗅探 → 解析 → ReadGuard → 证据链。
+ *
+ * 传输车道(2026-08-29 定案,RFC §2.2):**扩展桥为默认**——一次性安装的 MV3 扩展
+ * (GoTry Session Bridge)在自己标签页被动嗅探 batchSearch,零 Chrome 系统弹窗;
+ *  cdp(attach 日常 Chrome,Chrome 144+ 每连接弹权限框)降为显式后备
+ * (`GOTRY_SESSION_TRANSPORT=cdp` opt-in,诊断/测试用);persistent 仅测试。
+ *
+ * 证据链(L4 增补):[会话:ctrip-flight@ts] / [会话:ctrip-hotel@ts] = 用户本人会话内实时检索,非官方 API;
+ * 风控命中(verdict='challenged')= degraded,绝不重试、绝不绕过(合规支柱②)。
+ * 节律(§3.4):同站点 ≥30s 间隔 + 单调冷却;超间隔返回 verdict='cooldown'。
+ * 永不抛错;扩展车道 fail-closed(桥/扩展不可用即 verdict,零花费);测试/巡检用隔离 profile 与 stateRoot。
+ */
 import { openSession } from './session/transport.js';
 import { extensionCookieNames, extensionSearchJob, classifyBridgeFailure } from './session/extension-channel.js';
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { buildEntryUrl, NETWORK_HINTS, parseBatchSearch, LOGIN_COOKIE_NAMES, SITE_DOMAIN } from './session/adapters/ctrip-flight.js';
+import { randomUUID } from 'node:crypto';
+import { buildEntryUrl, NETWORK_HINTS, parseBatchSearchResult, LOGIN_COOKIE_NAMES, SITE_DOMAIN } from './session/adapters/ctrip-flight.js';
 import { buildHotelEntryUrl, parseCtripHotelList, HOTEL_SITE_HOST } from './session/adapters/ctrip-hotel.js';
-import { buildTrainEntryUrl, parseLeftTicketQuery, TRAIN_SITE_HOST } from './session/adapters/rail-12306.js';
+import { buildTrainEntryUrl, parseLeftTicketQueryResult, resolveTrainQueryTelecodes, validateTrainQueryResponseUrl } from './session/adapters/rail-12306.js';
+import { buildDidaEntryUrl, parseDidaRates, parseDidaRecommendHotels, parseDidaPrices, DIDA_NETWORK_HINTS, DIDA_SITE_DOMAIN, DIDA_LOGIN_COOKIE_NAMES } from './session/adapters/dida-portal.js';
 import { EXTENSION_STORE_URL } from './session/extension-bridge.js';
+/** 节律闸(§3.4):同站点最小间隔;导出仅测试用 */
 const MIN_INTERVAL_MS = 30_000;
 const lastCallAt = new Map();
 export function __resetRateLimiterForTest() {
     lastCallAt.clear();
 }
+let trainSessionTransportForTest;
+/** Isolated CDP collector seam; production uses openSession and never installs this. */
+export function __setTrainSessionTransportForTest(factory) {
+    trainSessionTransportForTest = factory ?? undefined;
+}
 const CHALLENGE_RE = /验证|滑块|captcha|verify/i;
+/** 把 transport 文案漂移收敛为稳定的产品 verdict；纯函数供回归覆盖。 */
 export function classifyTransportFailure(summary, cdpMode) {
-    return cdpMode && /日常 Chrome 未开调试端口|cdp attach 失败/.test(summary) ? 'needs-attach' : 'error';
+    return cdpMode && /日常 Chrome 未开调试端口|cdp attach 失败/.test(summary)
+        ? 'needs-attach'
+        : 'error';
 }
+/** 传输车道解析(纯函数,测试锚点):persistent=隔离 profile(测试自检);cdp=显式 opt-in;扩展=默认 */
 export function resolveTransportMode(profileDir) {
-    if (profileDir !== undefined) return 'persistent';
+    if (profileDir !== undefined)
+        return 'persistent';
     return (process.env.GOTRY_SESSION_TRANSPORT ?? '').trim().toLowerCase() === 'cdp' ? 'cdp' : 'extension';
 }
+/** Live browser transport is an explicit opt-in for smoke/full-suite callers. */
 export function sessionLiveEnabled(env = process.env) {
     return env.GOTRY_SESSION_LIVE === '1';
 }
+/** Deterministic offline observation used when the live session gate is closed. */
 export function offlineSessionFlightResult() {
     return {
         ok: false,
@@ -29,27 +57,27 @@ export function offlineSessionFlightResult() {
         evidence: '[会话:ctrip-flight@offline] GOTRY_SESSION_LIVE!=1; live transport not invoked',
         latencyMs: 0,
         verdict: 'error',
-        error: 'GOTRY_SESSION_LIVE=1 required for live session transport'
+        error: 'GOTRY_SESSION_LIVE=1 required for live session transport',
     };
 }
+/** Gate a caller before it can invoke the browser/session transport. */
 export async function gatedSessionFlightSearch(q, search = sessionFlightSearch, env = process.env) {
-    if (!sessionLiveEnabled(env)) return offlineSessionFlightResult();
+    if (!sessionLiveEnabled(env))
+        return offlineSessionFlightResult();
     return search(q);
 }
+/** 扩展车道 job 审计(ReadGuard 审计同款 JSONL,kind 区分;auditPath 缺省不落盘) */
 export function appendExtensionAudit(auditPath, entry) {
-    if (!auditPath) return;
+    if (!auditPath)
+        return;
     try {
-        const record = {
-            ts: new Date().toISOString(),
-            ...entry,
-            url: entry.url.slice(0, 400)
-        };
-        mkdirSync(dirname(auditPath), {
-            recursive: true
-        });
+        const record = { ts: new Date().toISOString(), ...entry, url: entry.url.slice(0, 400) };
+        mkdirSync(dirname(auditPath), { recursive: true });
         appendFileSync(auditPath, JSON.stringify(record) + '\n');
-    } catch  {}
+    }
+    catch { /* 审计失败不阻塞检索 */ }
 }
+/** 酒店城市码表未收录时的人话指引(纯函数,测试锚点) */
 export function hotelCityUnresolvedHint(cities) {
     return `城市 ${cities.join('/')} 不在携程酒店城市码表——先 web 搜「hotels.ctrip.com ${cities[0] ?? ''} 酒店」拿到 list 页 URL 里的 city= 数字,带 cityId 重试`;
 }
@@ -57,15 +85,11 @@ export async function sessionHotelSearch(q) {
     const started = Date.now();
     const ts = new Date().toISOString();
     const site = 'ctrip-hotel';
-    const err = (verdict, error)=>({
-            ok: false,
-            via: 'session-ctrip-hotel-error',
-            evidence: `[会话:${site}@error@${ts}] ${error}`,
-            latencyMs: Date.now() - started,
-            verdict,
-            error
-        });
-    if ((q.checkIn ? 1 : 0) !== (q.checkOut ? 1 : 0) || q.checkIn && !/^\d{4}-\d{2}-\d{2}$/.test(q.checkIn)) {
+    const err = (verdict, error) => ({
+        ok: false, via: 'session-ctrip-hotel-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict, error,
+    });
+    // 日期对闸(与 flyai hotel 同口径):成对且 YYYY-MM-DD;过去日期不发上游
+    if ((q.checkIn ? 1 : 0) !== (q.checkOut ? 1 : 0) || (q.checkIn && !/^\d{4}-\d{2}-\d{2}$/.test(q.checkIn))) {
         return err('error', 'checkIn/checkOut 须成对且为 YYYY-MM-DD(未定档期可不带日期)');
     }
     if (q.checkIn) {
@@ -75,74 +99,40 @@ export async function sessionHotelSearch(q) {
             return err('error', `入住 ${q.checkIn}/退房 ${q.checkOut ?? ''} 不是未来合法区间(今天 ${today})——向用户确认日期后再查`);
         }
     }
+    // 节律闸:超间隔即拒,不发起导航
     const last = lastCallAt.get(site) ?? 0;
     if (Date.now() - last < MIN_INTERVAL_MS) {
         return err('cooldown', `rate limit: last call ${Date.now() - last}ms ago, min ${MIN_INTERVAL_MS}ms`);
     }
     lastCallAt.set(site, Date.now());
-    const entry = buildHotelEntryUrl({
-        to: q.to,
-        cityId: q.cityId,
-        checkIn: q.checkIn,
-        checkOut: q.checkOut,
-        adults: q.adults
-    });
+    const entry = buildHotelEntryUrl({ to: q.to, cityId: q.cityId, checkIn: q.checkIn, checkOut: q.checkOut, adults: q.adults });
     if (!entry.ok || !entry.url) {
-        return err('error', hotelCityUnresolvedHint(entry.unresolved ?? [
-            q.to
-        ]));
+        return err('error', hotelCityUnresolvedHint(entry.unresolved ?? [q.to]));
     }
     const mode = resolveTransportMode(q.profileDir);
     if (mode === 'extension') {
-        const login = await extensionCookieNames({
-            site,
-            domain: SITE_DOMAIN.replace(/^\./, ''),
-            ticketNames: LOGIN_COOKIE_NAMES
-        });
+        // ① 登录态快查(与机票同账号体系,票据 cookie 名一致)
+        const login = await extensionCookieNames({ site, domain: SITE_DOMAIN.replace(/^\./, ''), ticketNames: LOGIN_COOKIE_NAMES });
         if (!login.ok) {
             const verdict = classifyBridgeFailure(login.kind);
             if (verdict === 'needs-extension') {
-                return {
-                    ok: false,
-                    via: 'session-ctrip-hotel-error',
-                    evidence: '[会话:ctrip-hotel-needs-extension@ts]',
-                    latencyMs: Date.now() - started,
-                    verdict,
-                    error: login.summary,
-                    installUrl: EXTENSION_STORE_URL,
-                    installAction: 'add-to-chrome'
-                };
+                return { ok: false, via: 'session-ctrip-hotel-error', evidence: '[会话:ctrip-hotel-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: login.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
             }
             return err(verdict, login.summary);
         }
         if (login.tickets.length === 0 && !q.allowAnonymous) {
             return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)');
         }
-        const r = await extensionSearchJob({
-            site,
-            url: entry.url,
-            timeoutMs: q.timeoutMs
-        });
+        // ② 检索 job:后台标签 + 被动嗅探(URL hint + 形状兜底;扩展零写行为)
+        const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs });
         appendExtensionAudit(q.auditPath, {
-            kind: 'extension-session-job',
-            site,
-            url: entry.url,
-            jobId: 'search',
-            result: r.ok ? r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"` : `${r.kind}:${r.summary.slice(0, 120)}`
+            kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+            result: r.ok ? (r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"`) : `${r.kind}:${r.summary.slice(0, 120)}`,
         });
         if (!r.ok) {
             const verdict = classifyBridgeFailure(r.kind);
             if (verdict === 'needs-extension') {
-                return {
-                    ok: false,
-                    via: 'session-ctrip-hotel-error',
-                    evidence: '[会话:ctrip-hotel-needs-extension@ts]',
-                    latencyMs: Date.now() - started,
-                    verdict,
-                    error: r.summary,
-                    installUrl: EXTENSION_STORE_URL,
-                    installAction: 'add-to-chrome'
-                };
+                return { ok: false, via: 'session-ctrip-hotel-error', evidence: '[会话:ctrip-hotel-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
             }
             return err(verdict, r.summary);
         }
@@ -159,35 +149,32 @@ export async function sessionHotelSearch(q) {
             evidence: `[会话:${site}@${ts}] ${hotels.length} hotels;transport=extension(被动嗅探,零系统弹窗;扩展零写行为=物理只读)${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
             latencyMs: Date.now() - started,
             verdict,
-            hotels
+            hotels,
         };
     }
-    const t = await openSession({
-        profileDir: q.profileDir,
-        headless: q.headless,
-        auditPath: q.auditPath,
-        mode: mode === 'persistent' ? 'persistent' : 'cdp',
-        newPage: true
-    });
+    // cdp/persistent 车道:与机票同构——挂监听等 NETWORK hint 回包(酒店用 HOTEL hints + 形状兜底)
+    const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true });
     if (!t.ok) {
         return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary);
     }
     try {
-        const loggedIn = async ()=>{
-            const cookies = await t.browser.cookies().catch(()=>[]);
-            return cookies.some((c)=>c.domain.includes(SITE_DOMAIN.replace(/^\./, '')) && LOGIN_COOKIE_NAMES.includes(c.name));
+        const loggedIn = async () => {
+            const cookies = await t.browser.cookies().catch(() => []);
+            return cookies.some((c) => c.domain.includes(SITE_DOMAIN.replace(/^\./, '')) && LOGIN_COOKIE_NAMES.includes(c.name));
         };
-        if (!await loggedIn() && !q.allowAnonymous) {
+        if (!(await loggedIn()) && !q.allowAnonymous) {
             return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)');
         }
         let settled = false;
         let body = '';
-        const heard = new Promise((resolve)=>{
-            t.page.on('response', async (res)=>{
-                if (settled) return;
+        const heard = new Promise((resolve) => {
+            t.page.on('response', async (res) => {
+                if (settled)
+                    return;
                 const u = res.url();
                 const hostHit = u.includes(HOTEL_SITE_HOST);
-                if (!hostHit) return;
+                if (!hostHit)
+                    return;
                 try {
                     const text = await res.text();
                     if (text && (hostHit && /hotels\.ctrip\.com\/(hotels\/api|domestic\/pc\/api)|GetHotelListBySOA|GetHotelListByCity|HotelSearch|hotelsearch/i.test(u) || text.length <= 2_000_000 && /"hotelList"|"hotelMatchInfos"|"hotelName"/.test(text))) {
@@ -195,17 +182,15 @@ export async function sessionHotelSearch(q) {
                         settled = true;
                         resolve();
                     }
-                } catch  {}
+                }
+                catch { /* 流式/竞态不可读则继续等下一个 */ }
             });
-            setTimeout(()=>resolve(), q.timeoutMs ?? 30_000);
-        });
-        await t.page.goto(entry.url, {
-            waitUntil: 'domcontentloaded',
-            timeout: 30_000
+            setTimeout(() => resolve(), q.timeoutMs ?? 30_000);
         });
+        await t.page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
         await heard;
-        const title = await t.page.title().catch(()=>'');
-        const headHtml = (await t.page.content().catch(()=>'')).slice(0, 5000);
+        const title = await t.page.title().catch(() => '');
+        const headHtml = (await t.page.content().catch(() => '')).slice(0, 5000);
         if (CHALLENGE_RE.test(title + headHtml)) {
             return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
         }
@@ -217,145 +202,320 @@ export async function sessionHotelSearch(q) {
             evidence: `[会话:${site}@${ts}] ${hotels.length} hotels;guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
             latencyMs: Date.now() - started,
             verdict,
-            hotels
+            hotels,
         };
-    } catch (e) {
+    }
+    catch (e) {
         return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e));
-    } finally{
+    }
+    finally {
         await t.close();
     }
 }
-export function trainStationUnresolvedHint(cities) {
-    return `城市 ${cities.join('/')} 不在 12306 城市电报码表——web 搜「12306 ${cities[0] ?? ''} 余票」拿到 kyfw 查询页 URL 里的 fs=城市,XXX 三位码,带 fromStationTelecode/toStationTelecode 重试`;
+/** 员工侧登录指引(纯函数,测试锚点):账密永不经 gotry——酒店 platform
+ * 凭据在 hotel-be portal「自动登录」跳板完成,dida 侧人只补验证码 */
+export function didaLoginHint() {
+    return '未检出你的 dida 登录态——在 hotel-be portal「供应商门户」页对该凭据点「自动登录」完成跳板登录(账密自动填充,你只补验证码);或调用 gotry_session_login(site=dida-portal)打开 dida 登录入口。登录在 dida 官网完成;gotry 永不经手密码/验证码/cookie 值';
 }
-export async function sessionTrainSearch(q) {
+/** dida 三类回包合并解析(推荐酒店 + 推荐价格 + 实时价;CDP 窗口收集与扩展 multiCollect 双车道同一合并语义) */
+function mergeDidaRatesBodies(bodies) {
+    const hotels = parseDidaRecommendHotels(bodies.hotels);
+    const recommendPrices = parseDidaPrices(bodies.recommendPrices);
+    const realtimeRates = parseDidaRates(bodies.realtime);
+    const pricesByHotel = new Map(recommendPrices.map((p) => [p.hotelId, p]));
+    const rates = [...realtimeRates];
+    for (const h of hotels) {
+        const p = pricesByHotel.get(h.hotelId);
+        rates.push({
+            hotelId: h.hotelId,
+            hotelName: h.name,
+            price: p?.price ?? 0,
+            ...(p?.currency ? { currency: p.currency } : {}),
+            ...(p?.priceDate ? { priceDate: p.priceDate } : {}),
+        });
+    }
+    return rates;
+}
+export async function sessionDidaSearch(q) {
     const started = Date.now();
     const ts = new Date().toISOString();
-    const site = 'train-12306';
-    const err = (verdict, error)=>({
-            ok: false,
-            via: 'session-train-12306-error',
-            evidence: `[会话:${site}@error@${ts}] ${error}`,
-            latencyMs: Date.now() - started,
-            verdict,
-            error
-        });
+    const site = 'dida-portal';
+    const err = (verdict, error) => ({
+        ok: false, via: 'session-dida-portal-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict, error,
+    });
+    // 节律闸:超间隔即拒,不发起导航
     const last = lastCallAt.get(site) ?? 0;
     if (Date.now() - last < MIN_INTERVAL_MS) {
         return err('cooldown', `rate limit: last call ${Date.now() - last}ms ago, min ${MIN_INTERVAL_MS}ms`);
     }
     lastCallAt.set(site, Date.now());
-    const entry = buildTrainEntryUrl({
-        from: q.from,
-        to: q.to,
-        date: q.date,
-        fromStationTelecode: q.fromStationTelecode,
-        toStationTelecode: q.toStationTelecode
-    });
+    const entry = buildDidaEntryUrl({ entryUrl: q.entryUrl });
     if (!entry.ok || !entry.url) {
-        return err('error', trainStationUnresolvedHint(entry.unresolved ?? [
-            q.from,
-            q.to
-        ]));
+        return err('error', 'entry URL 必须落在 https://portal.dida.com/ 域内');
     }
     const mode = resolveTransportMode(q.profileDir);
     if (mode === 'extension') {
-        const r = await extensionSearchJob({
-            site,
-            url: entry.url,
-            timeoutMs: q.timeoutMs
-        });
+        // ① 登录态快查:票据 cookie 名存在性(名字级;协议面不存在值字段)。
+        // 20s 窗口:桥常在本调用前才拉起,扩展 SW 可能已按 MV3 30s 节律休眠——
+        // job 在桥上按 capability 排队等轮询者,窗口覆盖一次 alarm 唤醒周期。
+        const login = await extensionCookieNames({ site, domain: DIDA_SITE_DOMAIN, ticketNames: DIDA_LOGIN_COOKIE_NAMES, timeoutMs: 20_000 }, q.bridge);
+        if (!login.ok) {
+            const verdict = classifyBridgeFailure(login.kind);
+            if (verdict === 'needs-extension') {
+                return { ok: false, via: 'session-dida-portal-error', evidence: '[会话:dida-portal-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: login.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
+            }
+            return err(verdict, login.summary);
+        }
+        if (login.tickets.length === 0 && !q.allowAnonymous) {
+            return err('needs-login', didaLoginHint());
+        }
+        // ② 检索 job:后台标签 + 被动嗅探(URL hint + 形状兜底;扩展零写行为)。
+        // multiCollect:find 页自发 hotels+recommendPrices 双流,单首包语义丢一半(2026-09-11)
+        const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs, multiCollect: true }, q.bridge);
         appendExtensionAudit(q.auditPath, {
-            kind: 'extension-session-job',
-            site,
-            url: entry.url,
-            jobId: 'search',
-            result: r.ok ? r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"` : `${r.kind}:${r.summary.slice(0, 120)}`
+            kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+            result: r.ok ? (r.timedOut ? 'timeout' : r.bodies ? `bodies hotels=${r.bodies.hotels?.length ?? 0}B prices=${r.bodies.recommendPrices?.length ?? 0}B` : `body ${r.body.length}B title="${r.title.slice(0, 60)}"`) : `${r.kind}:${r.summary.slice(0, 120)}`,
         });
         if (!r.ok) {
             const verdict = classifyBridgeFailure(r.kind);
             if (verdict === 'needs-extension') {
-                return {
-                    ok: false,
-                    via: 'session-train-12306-error',
-                    evidence: '[会话:train-12306-needs-extension@ts]',
-                    latencyMs: Date.now() - started,
-                    verdict,
-                    error: r.summary,
-                    installUrl: EXTENSION_STORE_URL,
-                    installAction: 'add-to-chrome'
-                };
+                return { ok: false, via: 'session-dida-portal-error', evidence: '[会话:dida-portal-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
             }
             return err(verdict, r.summary);
         }
         const title = r.title;
-        const head = r.body.slice(0, 5000);
+        const head = (r.bodies?.hotels ?? r.body).slice(0, 5000);
         if (CHALLENGE_RE.test(title + head)) {
             return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
         }
-        const trains = parseLeftTicketQuery(r.body, entry.url);
-        const verdict = trains.length > 0 ? 'hit' : 'miss';
+        // multiCollect 分桶回包 → 与 CDP 车道同语义合并;旧扩展单首包 → 退化 parseDidaRates 兜底
+        const rates = r.bodies
+            ? mergeDidaRatesBodies({ hotels: r.bodies.hotels ?? '', recommendPrices: r.bodies.recommendPrices ?? '', realtime: r.bodies.realtime ?? '' })
+            : parseDidaRates(r.body);
+        const verdict = rates.length > 0 ? 'hit' : 'miss';
         return {
             ok: true,
-            via: 'session-train-12306',
-            evidence: `[会话:${site}@${ts}] ${trains.length} trains;transport=extension(公开查询面,被动嗅探,零系统弹窗;扩展零写行为=物理只读)`,
+            via: 'session-dida-portal',
+            evidence: `[会话:${site}@${ts}] ${rates.length} rates;transport=extension(被动嗅探,零系统弹窗;扩展零写行为=物理只读)${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+            latencyMs: Date.now() - started,
+            verdict,
+            rates,
+        };
+    }
+    // cdp/persistent 车道:与机/酒同构——挂监听等 DIDA hints 回包
+    const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true });
+    if (!t.ok) {
+        return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary);
+    }
+    try {
+        const loggedIn = async () => {
+            const cookies = await t.browser.cookies().catch(() => []);
+            return cookies.some((c) => c.domain.includes(DIDA_SITE_DOMAIN) && DIDA_LOGIN_COOKIE_NAMES.includes(c.name));
+        };
+        if (!(await loggedIn()) && !q.allowAnonymous) {
+            return err('needs-login', didaLoginHint());
+        }
+        // 窗口式收集(2026-09-10 校准):find 页加载自发推荐流(酒店+价格两个接口)
+        // 与可能的实时价接口——按接口分类收 body,窗口结束统一合并解析。
+        const bodies = { hotels: '', recommendPrices: '', realtime: '' };
+        const collect = (text, url) => {
+            if (/SearchHomepageRecommendHotels/i.test(url))
+                bodies.hotels = text;
+            else if (/SearchHomepageRecommendPrices/i.test(url))
+                bodies.recommendPrices = text;
+            else if (/HotelPriceAPI\/SearchRealTime/i.test(url))
+                bodies.realtime = text;
+        };
+        const heard = new Promise((resolve) => {
+            t.page.on('response', async (res) => {
+                const u = res.url();
+                if (!DIDA_NETWORK_HINTS.some((re) => re.test(u)))
+                    return;
+                try {
+                    const text = await res.text();
+                    if (text)
+                        collect(text, u);
+                }
+                catch { /* 流式/竞态不可读则继续等下一个 */ }
+            });
+            setTimeout(resolve, q.timeoutMs ?? 30_000);
+        });
+        await t.page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+        await heard;
+        const title = await t.page.title().catch(() => '');
+        const headHtml = (await t.page.content().catch(() => '')).slice(0, 5000);
+        if (CHALLENGE_RE.test(title + headHtml)) {
+            return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
+        }
+        const rates = mergeDidaRatesBodies(bodies);
+        // 有推荐酒店或有实时价即视为通道产出;纯无价酒店如实标注价格待询
+        const priced = rates.filter((r) => r.price > 0).length;
+        const verdict = rates.length > 0 ? 'hit' : 'miss';
+        return {
+            ok: true,
+            via: 'session-dida-portal',
+            evidence: `[会话:${site}@${ts}] ${rates.length} hotels(${priced} priced);guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
             latencyMs: Date.now() - started,
             verdict,
-            trains
+            rates,
         };
     }
-    const t = await openSession({
-        profileDir: q.profileDir,
-        headless: q.headless,
-        auditPath: q.auditPath,
-        mode: mode === 'persistent' ? 'persistent' : 'cdp',
-        newPage: true
+    catch (e) {
+        return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e));
+    }
+    finally {
+        await t.close();
+    }
+}
+/** 车站电报码表未收录时的人话指引(纯函数,测试锚点) */
+export function trainStationUnresolvedHint(cities) {
+    return `城市 ${cities.join('/')} 不在 12306 城市电报码表——web 搜「12306 ${cities[0] ?? ''} 余票」拿到 kyfw 查询页 URL 里的 fs=城市,XXX 三位码,带 fromStationTelecode/toStationTelecode 重试`;
+}
+export async function sessionTrainSearch(q) {
+    const started = Date.now();
+    const ts = new Date().toISOString();
+    const site = 'train-12306';
+    const err = (verdict, error) => ({
+        ok: false, via: 'session-train-12306-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict,
+        outcome: { kind: 'transport-runtime-error', reason: error }, error,
     });
+    const parsedResult = (body, responseUrl, evidence, guardSuffix = '') => {
+        const outcome = parseLeftTicketQueryResult(body, entry.url, { maxItems: 30 });
+        if (outcome.kind === 'malformed') {
+            return {
+                ok: false,
+                via: 'session-train-12306-error',
+                evidence: `${evidence} typed-parse=malformed`,
+                latencyMs: Date.now() - started,
+                verdict: 'error',
+                outcome,
+                error: `12306 leftTicket/query 响应未通过 typed contract:${outcome.reason}`,
+            };
+        }
+        const request = resolveTrainQueryTelecodes({ from: q.from, to: q.to, date: q.date, fromStationTelecode: q.fromStationTelecode, toStationTelecode: q.toStationTelecode });
+        if (!request.ok) {
+            return {
+                ok: false,
+                via: 'session-train-12306-error',
+                evidence: `${evidence} typed-response-binding=unresolved`,
+                latencyMs: Date.now() - started,
+                verdict: 'error',
+                outcome,
+                trains: outcome.trains,
+                error: `12306 查询请求电报码未解析:${request.unresolved.join(',')}`,
+            };
+        }
+        const response = validateTrainQueryResponseUrl(responseUrl, request.telecodes);
+        if (!response.ok) {
+            return {
+                ok: false,
+                via: 'session-train-12306-error',
+                evidence: `${evidence} typed-response-binding=invalid`,
+                latencyMs: Date.now() - started,
+                verdict: 'error',
+                outcome,
+                trains: outcome.trains,
+                error: `12306 leftTicket/query 响应未绑定本次请求:${response.reason}`,
+            };
+        }
+        const fetchedAt = new Date().toISOString();
+        const batchId = randomUUID();
+        const collection = {
+            requested: { from: q.from, to: q.to, date: q.date },
+            request: request.telecodes,
+            response: response.binding,
+            batchId,
+            queryId: `session:12306-train:${batchId}`,
+            fetchedAt,
+        };
+        const trains = outcome.trains;
+        return {
+            ok: true,
+            via: 'session-train-12306',
+            evidence: `${evidence} ${guardSuffix}`.trim(),
+            latencyMs: Date.now() - started,
+            verdict: outcome.kind === 'recognized-nonempty' ? 'hit' : 'miss',
+            outcome,
+            collection,
+            trains,
+        };
+    };
+    // 节律闸:超间隔即拒,不发起导航
+    const last = lastCallAt.get(site) ?? 0;
+    if (Date.now() - last < MIN_INTERVAL_MS) {
+        return err('cooldown', `rate limit: last call ${Date.now() - last}ms ago, min ${MIN_INTERVAL_MS}ms`);
+    }
+    lastCallAt.set(site, Date.now());
+    const entry = buildTrainEntryUrl({ from: q.from, to: q.to, date: q.date, fromStationTelecode: q.fromStationTelecode, toStationTelecode: q.toStationTelecode });
+    if (!entry.ok || !entry.url) {
+        return err('error', trainStationUnresolvedHint(entry.unresolved ?? [q.from, q.to]));
+    }
+    const mode = resolveTransportMode(q.profileDir);
+    if (mode === 'extension') {
+        // 无登录闸(公开查询面):直接发起检索 job
+        const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs });
+        appendExtensionAudit(q.auditPath, {
+            kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+            result: r.ok ? (r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"`) : `${r.kind}:${r.summary.slice(0, 120)}`,
+        });
+        if (!r.ok) {
+            const verdict = classifyBridgeFailure(r.kind);
+            if (verdict === 'needs-extension') {
+                return { ok: false, via: 'session-train-12306-error', evidence: '[会话:train-12306-needs-extension@ts]', latencyMs: Date.now() - started, verdict, outcome: { kind: 'transport-runtime-error', reason: r.summary }, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
+            }
+            return err(verdict, r.summary);
+        }
+        const title = r.title;
+        const head = r.body.slice(0, 5000);
+        if (CHALLENGE_RE.test(title + head)) {
+            return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
+        }
+        return parsedResult(r.body, r.url, `[会话:${site}@${ts}] transport=extension(公开查询面,被动嗅探,零系统弹窗;扩展零写行为=物理只读)`);
+    }
+    // cdp/persistent 车道:与机/酒同构
+    const t = await (trainSessionTransportForTest
+        ? trainSessionTransportForTest()
+        : openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true }));
     if (!t.ok) {
         return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary);
     }
     try {
         let settled = false;
         let body = '';
-        const heard = new Promise((resolve)=>{
-            t.page.on('response', async (res)=>{
-                if (settled) return;
+        let responseUrl = '';
+        const heard = new Promise((resolve) => {
+            t.page.on('response', async (res) => {
+                if (settled)
+                    return;
                 const u = res.url();
-                if (!/leftTicket\/query/i.test(u)) return;
+                if (!/leftTicket\/query/i.test(u))
+                    return;
                 try {
                     const text = await res.text();
                     if (text) {
                         body = text;
+                        responseUrl = u;
                         settled = true;
                         resolve();
                     }
-                } catch  {}
+                }
+                catch { /* 流式/竞态不可读则继续等下一个 */ }
             });
-            setTimeout(()=>resolve(), q.timeoutMs ?? 25_000);
-        });
-        await t.page.goto(entry.url, {
-            waitUntil: 'domcontentloaded',
-            timeout: 30_000
+            setTimeout(() => resolve(), q.timeoutMs ?? 25_000);
         });
+        await t.page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
         await heard;
-        const title = await t.page.title().catch(()=>'');
-        const headHtml = (await t.page.content().catch(()=>'')).slice(0, 5000);
+        const title = await t.page.title().catch(() => '');
+        const headHtml = (await t.page.content().catch(() => '')).slice(0, 5000);
         if (CHALLENGE_RE.test(title + headHtml)) {
             return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
         }
-        const trains = parseLeftTicketQuery(body, entry.url);
-        const verdict = trains.length > 0 ? 'hit' : 'miss';
-        return {
-            ok: true,
-            via: 'session-train-12306',
-            evidence: `[会话:${site}@${ts}] ${trains.length} trains(公开查询面);guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}`,
-            latencyMs: Date.now() - started,
-            verdict,
-            trains
-        };
-    } catch (e) {
+        return parsedResult(body, responseUrl, `[会话:${site}@${ts}] 12306 公开查询面`, `guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}`);
+    }
+    catch (e) {
         return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e));
-    } finally{
+    }
+    finally {
         await t.close();
     }
 }
@@ -363,14 +523,10 @@ export async function sessionFlightSearch(q) {
     const started = Date.now();
     const ts = new Date().toISOString();
     const site = 'ctrip-flight';
-    const err = (verdict, error)=>({
-            ok: false,
-            via: 'session-ctrip-flight-error',
-            evidence: `[会话:${site}@error@${ts}] ${error}`,
-            latencyMs: Date.now() - started,
-            verdict,
-            error
-        });
+    const err = (verdict, error) => ({
+        ok: false, via: 'session-ctrip-flight-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict, error,
+    });
+    // 节律闸:超间隔即拒,不发起导航
     const last = lastCallAt.get(site) ?? 0;
     if (Date.now() - last < MIN_INTERVAL_MS) {
         return err('cooldown', `rate limit: last call ${Date.now() - last}ms ago, min ${MIN_INTERVAL_MS}ms`);
@@ -382,55 +538,29 @@ export async function sessionFlightSearch(q) {
     }
     const mode = resolveTransportMode(q.profileDir);
     if (mode === 'extension') {
-        const login = await extensionCookieNames({
-            site,
-            domain: SITE_DOMAIN.replace(/^\./, ''),
-            ticketNames: LOGIN_COOKIE_NAMES
-        });
+        // ① 登录态快查:票据 cookie 名存在性(免标签页,秒回;needs-login 不再先付一次导航成本)
+        const login = await extensionCookieNames({ site, domain: SITE_DOMAIN.replace(/^\./, ''), ticketNames: LOGIN_COOKIE_NAMES });
         if (!login.ok) {
             const verdict = classifyBridgeFailure(login.kind);
             if (verdict === 'needs-extension') {
-                return {
-                    ok: false,
-                    via: 'session-ctrip-flight-error',
-                    evidence: '[会话:ctrip-flight-needs-extension@ts]',
-                    latencyMs: Date.now() - started,
-                    verdict,
-                    error: login.summary,
-                    installUrl: EXTENSION_STORE_URL,
-                    installAction: 'add-to-chrome'
-                };
+                return { ok: false, via: 'session-ctrip-flight-error', evidence: '[会话:ctrip-flight-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: login.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
             }
             return err(verdict, login.summary);
         }
+        // 登录态闸:用户自己的账号;匿名默认拒(allowAnonymous 仅链路自检且证据标自检态)
         if (login.tickets.length === 0 && !q.allowAnonymous) {
             return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)');
         }
-        const r = await extensionSearchJob({
-            site,
-            url: entry.url,
-            timeoutMs: q.timeoutMs
-        });
+        // ② 检索 job:后台标签 + MAIN-world 被动嗅探(检索请求由站点自己发出,扩展零写行为)
+        const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs });
         appendExtensionAudit(q.auditPath, {
-            kind: 'extension-session-job',
-            site,
-            url: entry.url,
-            jobId: 'search',
-            result: r.ok ? r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"` : `${r.kind}:${r.summary.slice(0, 120)}`
+            kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+            result: r.ok ? (r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"`) : `${r.kind}:${r.summary.slice(0, 120)}`,
         });
         if (!r.ok) {
             const verdict = classifyBridgeFailure(r.kind);
             if (verdict === 'needs-extension') {
-                return {
-                    ok: false,
-                    via: 'session-ctrip-flight-error',
-                    evidence: '[会话:ctrip-flight-needs-extension@ts]',
-                    latencyMs: Date.now() - started,
-                    verdict,
-                    error: r.summary,
-                    installUrl: EXTENSION_STORE_URL,
-                    installAction: 'add-to-chrome'
-                };
+                return { ok: false, via: 'session-ctrip-flight-error', evidence: '[会话:ctrip-flight-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
             }
             return err(verdict, r.summary);
         }
@@ -439,78 +569,86 @@ export async function sessionFlightSearch(q) {
         if (CHALLENGE_RE.test(title + head)) {
             return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
         }
-        const options = parseBatchSearch(r.body);
-        const verdict = options.length > 0 ? 'hit' : 'miss';
+        const parsed = parseBatchSearchResult(r.body);
+        if (parsed.verdict === 'error') {
+            return err('error', `batchSearch 响应形状异常(非合法空响应;options=0 不视为 miss):body ${r.body.length}B 头 ${r.body.slice(0, 80)}`);
+        }
+        const options = parsed.options;
+        const verdict = parsed.verdict === 'hit' ? 'hit' : 'miss';
         return {
             ok: true,
             via: 'session-ctrip-flight',
             evidence: `[会话:${site}@${ts}] ${options.length} options;transport=extension(被动嗅探,零系统弹窗;扩展零写行为=物理只读)${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
             latencyMs: Date.now() - started,
             verdict,
-            options
+            options,
         };
     }
-    const t = await openSession({
-        profileDir: q.profileDir,
-        headless: q.headless,
-        auditPath: q.auditPath,
-        mode: mode === 'persistent' ? 'persistent' : 'cdp',
-        newPage: true
-    });
+    // 人机共治纪律:检索一律开自己的新标签页(绝不劫持用户已有页面),用完关自己的页
+    // cdp 车道(显式 GOTRY_SESSION_TRANSPORT=cdp opt-in)与 persistent(测试隔离 profile)
+    const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true });
     if (!t.ok) {
+        // cdp 未开端口或握手失败 → needs-attach(一次性用户动作);persistent 启动失败仍走 error。
+        // transport 的“端口未开”在连接前返回,文案不含 `cdp attach 失败`,两种形态都要归入同一用户门禁。
         return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary);
     }
     try {
-        const loggedIn = async ()=>{
-            const cookies = await t.browser.cookies().catch(()=>[]);
-            return cookies.some((c)=>c.domain.includes(SITE_DOMAIN.replace(/^\./, '')) && LOGIN_COOKIE_NAMES.includes(c.name));
+        // 登录态闸:用户自己的账号,不是匿名实例——匿名态按 onAnonymous 处置(默认 fail)
+        const loggedIn = async () => {
+            const cookies = await t.browser.cookies().catch(() => []);
+            return cookies.some((c) => c.domain.includes(SITE_DOMAIN.replace(/^\./, '')) && LOGIN_COOKIE_NAMES.includes(c.name));
         };
-        if (!await loggedIn() && !q.allowAnonymous) {
+        if (!(await loggedIn()) && !q.allowAnonymous) {
             return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)');
         }
+        // 先挂监听再导航(Playwright network 模式):命中 networkHint 的第一个响应即搜索回包
         let settled = false;
         let body = '';
-        const heard = new Promise((resolve)=>{
-            t.page.on('response', async (res)=>{
-                if (settled) return;
+        const heard = new Promise((resolve) => {
+            t.page.on('response', async (res) => {
+                if (settled)
+                    return;
                 const u = res.url();
-                if (!NETWORK_HINTS.some((re)=>re.test(u))) return;
+                if (!NETWORK_HINTS.some((re) => re.test(u)))
+                    return;
                 try {
                     body = await res.text();
-                } catch  {}
+                }
+                catch { /* 流式/竞态不可读则继续等下一个 */ }
                 if (body) {
                     settled = true;
                     resolve();
                 }
             });
-            setTimeout(()=>resolve(), q.timeoutMs ?? 25_000);
-        });
-        await t.page.goto(entry.url, {
-            waitUntil: 'domcontentloaded',
-            timeout: 30_000
+            // 超时也结算:miss/error 由后续判定
+            setTimeout(() => resolve(), q.timeoutMs ?? 25_000);
         });
+        await t.page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
         await heard;
-        const title = await t.page.title().catch(()=>'');
-        const headHtml = (await t.page.content().catch(()=>'')).slice(0, 5000);
+        const title = await t.page.title().catch(() => '');
+        const headHtml = (await t.page.content().catch(() => '')).slice(0, 5000);
         if (CHALLENGE_RE.test(title + headHtml)) {
             return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
         }
-        const options = parseBatchSearch(body);
-        const verdict = options.length > 0 ? 'hit' : 'miss';
+        const parsed = parseBatchSearchResult(body);
+        if (parsed.verdict === 'error') {
+            return err('error', `batchSearch 响应形状异常(非合法空响应;options=0 不视为 miss):body ${body.length}B 头 ${body.slice(0, 80)}`);
+        }
+        const options = parsed.options;
+        const verdict = parsed.verdict === 'hit' ? 'hit' : 'miss';
         return {
             ok: true,
             via: 'session-ctrip-flight',
             evidence: `[会话:${site}@${ts}] ${options.length} options;guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
             latencyMs: Date.now() - started,
             verdict,
-            options
+            options,
         };
-    } catch (e) {
+    }
+    catch (e) {
         return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e));
-    } finally{
+    }
+    finally {
         await t.close();
     }
 }
-
-
-//# sourceURL=ts/capabilities/session-search.ts