@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/dist/capabilities/session-search.js

@@ -1,23 +1,552 @@
+/**
+ * 会话检索编排层(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 { buildEntryUrl, NETWORK_HINTS, parseBatchSearch, LOGIN_COOKIE_NAMES, SITE_DOMAIN } from './session/adapters/ctrip-flight.js';
+import { extensionCookieNames, extensionSearchJob, classifyBridgeFailure, needsExtensionHint } from './session/extension-channel.js';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+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, parseLeftTicketQueryResult, resolveTrainQueryTelecodes, validateTrainQueryResponseUrl } from './session/adapters/rail-12306.js';
+import { buildDidaEntryUrl, parseDidaRates, parseDidaSearchCache, 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';
+/** Flight evidence can be persisted by the benchmark; extension-supplied error text is untrusted. */
+function flightBridgeFailureSummary(kind) {
+    switch (kind) {
+        case 'extension-not-connected': return needsExtensionHint();
+        case 'bridge-unavailable': return '扩展桥或端口池不可用；请检查本机服务后重试';
+        case 'timeout': return '扩展作业超时；请稍后重试';
+        case 'job-error': return '扩展作业失败；请检查扩展连接后重试';
+    }
+}
+/** 节律闸(§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;
-export async function sessionFlightSearch(q) {
+/** 把 transport 文案漂移收敛为稳定的产品 verdict；纯函数供回归覆盖。 */
+export function classifyTransportFailure(summary, cdpMode) {
+    return cdpMode && /日常 Chrome 未开调试端口|cdp attach 失败/.test(summary)
+        ? 'needs-attach'
+        : 'error';
+}
+/** 传输车道解析(纯函数,测试锚点):persistent=隔离 profile(测试自检);cdp=显式 opt-in;扩展=默认 */
+export function resolveTransportMode(profileDir) {
+    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,
+        via: 'session-ctrip-flight-error',
+        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',
+    };
+}
+/** 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();
+    return search(q);
+}
+/** 扩展车道 job 审计(ReadGuard 审计同款 JSONL,kind 区分;auditPath 缺省不落盘) */
+export function appendExtensionAudit(auditPath, entry) {
+    if (!auditPath)
+        return;
+    try {
+        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 { /* 审计失败不阻塞检索 */ }
+}
+/** 酒店城市码表未收录时的人话指引(纯函数,测试锚点) */
+export function hotelCityUnresolvedHint(cities) {
+    return `城市 ${cities.join('/')} 不在携程酒店城市码表——先 web 搜「hotels.ctrip.com ${cities[0] ?? ''} 酒店」拿到 list 页 URL 里的 city= 数字,带 cityId 重试`;
+}
+export async function sessionHotelSearch(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}`,
+    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,
+    });
+    // 日期对闸(与 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) {
+        const now = new Date();
+        const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+        if (q.checkIn < today || (q.checkOut ?? '') < q.checkIn) {
+            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 });
+    if (!entry.ok || !entry.url) {
+        return err('error', hotelCityUnresolvedHint(entry.unresolved ?? [q.to]));
+    }
+    const mode = resolveTransportMode(q.profileDir);
+    if (mode === 'extension') {
+        // ① 登录态快查(与机票同账号体系,票据 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 err(verdict, login.summary);
+        }
+        if (login.tickets.length === 0 && !q.allowAnonymous) {
+            return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)');
+        }
+        // ② 检索 job:后台标签 + 被动嗅探(URL hint + 形状兜底;扩展零写行为)
+        const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs, preferredOrigin: login.origin, preferredClientId: login.clientId });
+        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-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);
+        }
+        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)});按红线不重试不绕过,交还用户`);
+        }
+        const hotels = parseCtripHotelList(r.body);
+        const verdict = hotels.length > 0 ? 'hit' : 'miss';
+        return {
+            ok: true,
+            via: 'session-ctrip-hotel',
+            evidence: `[会话:${site}@${ts}] ${hotels.length} hotels;transport=extension(被动嗅探,零系统弹窗;扩展零写行为=物理只读)${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+            latencyMs: Date.now() - started,
+            verdict,
+            hotels,
+        };
+    }
+    // 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));
+        };
+        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 u = res.url();
+                const hostHit = u.includes(HOTEL_SITE_HOST);
+                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))) {
+                        body = text;
+                        settled = true;
+                        resolve();
+                    }
+                }
+                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 hotels = parseCtripHotelList(body);
+        const verdict = hotels.length > 0 ? 'hit' : 'miss';
+        return {
+            ok: true,
+            via: 'session-ctrip-hotel',
+            evidence: `[会话:${site}@${ts}] ${hotels.length} hotels;guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+            latencyMs: Date.now() - started,
+            verdict,
+            hotels,
+        };
+    }
+    catch (e) {
+        return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e));
+    }
+    finally {
+        await t.close();
+    }
+}
+/** 员工侧登录指引(纯函数,测试锚点):账密永不经 gotry——酒店 platform
+ * 凭据在 hotel-be portal「自动登录」跳板完成,dida 侧人只补验证码 */
+export function didaLoginHint() {
+    return '未检出你的 dida 登录态——在 hotel-be portal「供应商门户」页对该凭据点「自动登录」完成跳板登录(账密自动填充,你只补验证码);或调用 gotry_session_login(site=dida-portal)打开 dida 登录入口。登录在 dida 官网完成;gotry 永不经手密码/验证码/cookie 值';
+}
+/** dida 三类回包合并解析(推荐酒店 + 推荐价格 + 实时价;CDP 窗口收集与扩展 multiCollect 双车道同一合并语义) */
+function mergeDidaRatesBodies(bodies) {
+    // 查询态(驱动门户目的地搜索)拿到的 SearchCache = 该城市+日期下的酒店报价面,优先级最高;
+    // 推荐流是首页口径,仅在拿不到查询态结果时兜底。
+    if (bodies.searchCache) {
+        const scoped = parseDidaSearchCache(bodies.searchCache);
+        if (scoped.length > 0)
+            return scoped;
+    }
+    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 = '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 = buildDidaEntryUrl({ entryUrl: q.entryUrl });
+    if (!entry.ok || !entry.url) {
+        return err('error', 'entry URL 必须落在 https://portal.dida.com/ 域内');
+    }
+    const mode = resolveTransportMode(q.profileDir);
+    if (mode === 'extension') {
+        // ① 登录态快查:票据 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, preferredOrigin: login.origin, preferredClientId: login.clientId, ...(q.query ? { query: q.query } : {}) }, q.bridge);
+        appendExtensionAudit(q.auditPath, {
+            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-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 ?? '';
+        // 挑战判定(2026-09-21 修正):扩展车道**只认页面侧信号**——页面标题 + content-bridge
+        // 按 DOM 判定的 challenge 标记。此前拿 `r.bodies?.hotels`(供应商响应体)扫「验证|captcha」,
+        // 会把酒店名(实测:「曼彻斯特市中心丽笙酒店，经过验证的净零酒店」)误判成风控,
+        // 导致 dida 通道恒 challenged(channel rates 永远取不到)。
+        if (r.challenge === true || CHALLENGE_RE.test(title)) {
+            return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
+        }
+        // multiCollect 分桶回包 → 与 CDP 车道同语义合并;旧扩展单首包 → 退化 parseDidaRates 兜底
+        const rates = r.bodies
+            ? mergeDidaRatesBodies({ hotels: r.bodies.hotels ?? '', recommendPrices: r.bodies.recommendPrices ?? '', realtime: r.bodies.realtime ?? '', searchCache: r.bodies.searchCache ?? '' })
+            : parseDidaRates(r.body);
+        const verdict = rates.length > 0 ? 'hit' : 'miss';
+        return {
+            ok: true,
+            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,
-            error
+            rates,
+        };
+    }
+    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 = '';
+        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;
+                try {
+                    const text = await res.text();
+                    if (text) {
+                        body = text;
+                        responseUrl = u;
+                        settled = true;
+                        resolve();
+                    }
+                }
+                catch { /* 流式/竞态不可读则继续等下一个 */ }
+            });
+            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);
+        if (CHALLENGE_RE.test(title + headHtml)) {
+            return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`);
+        }
+        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 {
+        await t.close();
+    }
+}
+export async function sessionFlightSearch(q) {
+    const started = Date.now();
+    const ts = new Date().toISOString();
+    const site = 'ctrip-flight';
+    const err = (verdict, error, transportShape) => ({
+        ok: false, via: 'session-ctrip-flight-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict, error,
+        ...(transportShape ? { transportShape } : {}),
+    });
+    // 节律闸:超间隔即拒,不发起导航
     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`);
@@ -27,69 +556,131 @@ export async function sessionFlightSearch(q) {
     if (!entry.ok || !entry.url) {
         return err('error', `unresolved entry: ${(entry.unresolved ?? []).join('/')} 不在城市码表`);
     }
-    const t = await openSession({
-        profileDir: q.profileDir,
-        headless: q.headless,
-        auditPath: q.auditPath,
-        mode: q.profileDir ? 'persistent' : 'cdp'
-    });
+    const mode = resolveTransportMode(q.profileDir);
+    if (mode === 'extension') {
+        // ① 登录态快查:票据 cookie 名存在性(免标签页,秒回;needs-login 不再先付一次导航成本)
+        const login = await extensionCookieNames({ site, domain: SITE_DOMAIN.replace(/^\./, ''), ticketNames: LOGIN_COOKIE_NAMES });
+        if (!login.ok) {
+            const verdict = classifyBridgeFailure(login.kind);
+            const summary = flightBridgeFailureSummary(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: summary, transportShape: 'precheck_unavailable', installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
+            }
+            return err(verdict, summary, 'precheck_unavailable');
+        }
+        // 登录态闸:用户自己的账号;匿名默认拒(allowAnonymous 仅链路自检且证据标自检态)
+        if (login.tickets.length === 0 && !q.allowAnonymous) {
+            return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)', 'needs_login');
+        }
+        // ② 检索 job:后台标签 + MAIN-world 被动嗅探(检索请求由站点自己发出,扩展零写行为)
+        const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs, preferredOrigin: login.origin, preferredClientId: login.clientId });
+        const auditShape = (shape) => appendExtensionAudit(q.auditPath, {
+            kind: 'extension-session-job', site, url: 'https://flights.ctrip.com', jobId: 'search', result: shape,
+        });
+        if (!r.ok) {
+            auditShape('search_job_unavailable');
+            const verdict = classifyBridgeFailure(r.kind);
+            const summary = flightBridgeFailureSummary(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: summary, transportShape: 'search_job_unavailable', installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' };
+            }
+            return err(verdict, summary, 'search_job_unavailable');
+        }
+        const title = r.title;
+        const head = r.body.slice(0, 5000);
+        if (CHALLENGE_RE.test(title + head)) {
+            auditShape('challenge_page');
+            return err('challenged', '风控/验证码命中；按红线不重试不绕过，交还用户', 'challenge_page');
+        }
+        if (r.timedOut) {
+            auditShape('sniff_timeout');
+            return err('error', 'batchSearch 嗅探超时：页面未收到可解析回包；本次检索未完成', 'sniff_timeout');
+        }
+        const parsed = parseBatchSearchResult(r.body);
+        auditShape(parsed.shape);
+        if (parsed.verdict === 'error') {
+            return err('error', `batchSearch 响应形状异常（${parsed.shape}；非合法空响应）`, parsed.shape);
+        }
+        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,
+            transportShape: parsed.shape,
+            options,
+        };
+    }
+    // 人机共治纪律:检索一律开自己的新标签页(绝不劫持用户已有页面),用完关自己的页
+    // 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) {
-        if (q.profileDir === undefined && /cdp attach 失败/.test(t.summary)) return err('needs-attach', t.summary);
-        return err('error', t.summary);
+        // 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.context.cookies([
-                `https://flights${SITE_DOMAIN.replace(/^\./, '')}/`
-            ]).catch(()=>[]);
-            return cookies.some((c)=>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) {
-            return err('needs-login', '匿名实例——先跑 scripts/session-login.ts 用用户自己的账号建立登录态(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)});按红线不重试不绕过,交还用户`);
+            return err('challenged', '风控/验证码命中；按红线不重试不绕过，交还用户', 'challenge_page');
+        }
+        if (body.length === 0)
+            return err('error', 'batchSearch 嗅探超时：页面未收到可解析回包；本次检索未完成', 'sniff_timeout');
+        const parsed = parseBatchSearchResult(body);
+        if (parsed.verdict === 'error') {
+            return err('error', `batchSearch 响应形状异常（${parsed.shape}；非合法空响应）`, parsed.shape);
         }
-        const options = parseBatchSearch(body);
-        const verdict = options.length > 0 ? 'hit' : 'miss';
+        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
+            transportShape: parsed.shape,
+            options,
         };
-    } catch (e) {
+    }
+    catch (e) {
         return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e));
-    } finally{
+    }
+    finally {
         await t.close();
     }
 }
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/session-search.ts