@danceiny/gotry 0.0.1-rc.15 → 0.0.1-rc.17

package/ts/capabilities/session/static-flight-golden.ts

@@ -0,0 +1,209 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { SessionComparableRecord, SessionComparableSegment } from './benchmark.ts'
+
+export type GoldenSource = 'manual' | 'flyai' | 'static'
+
+export interface StaticFlightRouteLeg {
+  from_iata: string
+  to_iata: string
+  carrier_codes: string[]
+}
+
+export interface StaticFlightRoute {
+  query_id: string
+  from_city: string
+  to_city: string
+  route_kind: 'direct' | 'transfer'
+  legs: StaticFlightRouteLeg[]
+}
+
+export interface StaticFlightSnapshot {
+  schema_version: 'sf-static-routes.v1'
+  source: {
+    name: string
+    url: string
+    revision: string
+    license: string
+    retrieved_at: string
+    limitations: string[]
+  }
+  routes: StaticFlightRoute[]
+}
+
+export interface StaticGoldenResolution {
+  requested_source: 'static'
+  effective_source: 'static-openflights+manual-band' | 'manual-golden'
+  record: SessionComparableRecord
+  fallback_reason?: string
+  estimated_fields: string[]
+  provenance: {
+    route_source: string
+    route_revision: string
+    route_license: string
+    band_source: 'sf-golden-manifest.json'
+  }
+}
+
+export function parseGoldenSource(args: string[]): GoldenSource {
+  const raw = args.find((arg) => arg.startsWith('--golden='))?.slice('--golden='.length) ?? 'manual'
+  if (raw === 'manual' || raw === 'flyai' || raw === 'static') return raw
+  throw new Error(`不支持的 golden vendor: ${raw}`)
+}
+
+export function loadStaticFlightSnapshot(
+  path = join(import.meta.dirname, '..', '..', 'data', 'sf-static-routes.json'),
+): StaticFlightSnapshot {
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+  if (!isRecord(parsed) || parsed.schema_version !== 'sf-static-routes.v1') {
+    throw new Error(`invalid static snapshot schema_version: ${String(isRecord(parsed) ? parsed.schema_version : undefined)}`)
+  }
+  const source = parsed.source
+  if (!isRecord(source)
+    || !['name', 'url', 'revision', 'license', 'retrieved_at'].every((key) => typeof source[key] === 'string')
+    || !Array.isArray(source.limitations)
+    || !source.limitations.every((item) => typeof item === 'string')) {
+    throw new Error('invalid static snapshot source')
+  }
+  if (!Array.isArray(parsed.routes) || !parsed.routes.every(isStaticFlightRoute)) {
+    throw new Error('invalid static snapshot routes')
+  }
+  return parsed as unknown as StaticFlightSnapshot
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isStaticFlightRoute(value: unknown): boolean {
+  if (!isRecord(value)
+    || typeof value.query_id !== 'string'
+    || typeof value.from_city !== 'string'
+    || typeof value.to_city !== 'string'
+    || (value.route_kind !== 'direct' && value.route_kind !== 'transfer')
+    || !Array.isArray(value.legs)
+    || value.legs.length === 0) return false
+  return value.legs.every((leg) => isRecord(leg)
+    && typeof leg.from_iata === 'string'
+    && typeof leg.to_iata === 'string'
+    && Array.isArray(leg.carrier_codes)
+    && leg.carrier_codes.every((carrier) => typeof carrier === 'string'))
+}
+
+function provenance(snapshot?: StaticFlightSnapshot): StaticGoldenResolution['provenance'] {
+  return {
+    route_source: snapshot?.source.url ?? '',
+    route_revision: snapshot?.source.revision ?? '',
+    route_license: snapshot?.source.license ?? '',
+    band_source: 'sf-golden-manifest.json',
+  }
+}
+
+function formatWithOffset(timestampMs: number, offset: string): string {
+  const sign = offset.startsWith('-') ? -1 : 1
+  const [hours, minutes] = offset.slice(1).split(':').map(Number)
+  const offsetMinutes = sign * ((hours ?? 0) * 60 + (minutes ?? 0))
+  const local = new Date(timestampMs + offsetMinutes * 60_000).toISOString().slice(0, 19)
+  return `${local}${offset}`
+}
+
+function buildSegments(
+  query: { from: string; to: string },
+  route: StaticFlightRoute,
+  manualSegment: SessionComparableSegment,
+): SessionComparableSegment[] | null {
+  if (route.route_kind === 'direct' && route.legs.length === 1) {
+    return [{
+      from: query.from,
+      to: query.to,
+      departure_at: manualSegment.departure_at,
+      arrival_at: manualSegment.arrival_at,
+      transport_number: `${route.legs[0]!.carrier_codes[0]}-STATIC`,
+    }]
+  }
+  if (route.route_kind !== 'transfer' || route.legs.length !== 2) return null
+  const departureMs = Date.parse(manualSegment.departure_at)
+  const arrivalMs = Date.parse(manualSegment.arrival_at)
+  if (!Number.isFinite(departureMs) || !Number.isFinite(arrivalMs) || arrivalMs <= departureMs) return null
+  const offset = manualSegment.departure_at.match(/([+-]\d{2}:\d{2})$/)?.[1] ?? '+08:00'
+  const totalMinutes = Math.floor((arrivalMs - departureMs) / 60_000)
+  if (totalMinutes < 90) return null
+  const layoverMinutes = Math.min(60, Math.floor(totalMinutes / 3))
+  const travelMinutes = totalMinutes - layoverMinutes
+  const firstTravelMinutes = Math.floor(travelMinutes / 2)
+  const secondDepartureMs = arrivalMs - (travelMinutes - firstTravelMinutes) * 60_000
+  const middle = route.legs[0]!.to_iata
+  return [
+    {
+      from: query.from,
+      to: middle,
+      departure_at: manualSegment.departure_at,
+      arrival_at: formatWithOffset(departureMs + firstTravelMinutes * 60_000, offset),
+      transport_number: `${route.legs[0]!.carrier_codes[0]}-STATIC`,
+    },
+    {
+      from: middle,
+      to: query.to,
+      departure_at: formatWithOffset(secondDepartureMs, offset),
+      arrival_at: manualSegment.arrival_at,
+      transport_number: `${route.legs[1]!.carrier_codes[0]}-STATIC`,
+    },
+  ]
+}
+
+export function resolveStaticGolden(input: {
+  query: { id: string; from: string; to: string; date: string }
+  manualRecord: SessionComparableRecord
+  snapshot?: StaticFlightSnapshot
+  snapshotError?: string
+  warn?: (message: string) => void
+}): StaticGoldenResolution {
+  const route = input.snapshot?.routes.find((candidate) => candidate.query_id === input.query.id)
+  let fallbackReason: string | undefined
+  if (input.snapshotError) {
+    fallbackReason = `static snapshot unavailable: ${input.snapshotError}`
+  } else if (!route) {
+    fallbackReason = `static route missing for ${input.query.id}`
+  } else if (route.from_city !== input.query.from || route.to_city !== input.query.to) {
+    fallbackReason = `static route mismatch for ${input.query.id}`
+  } else if (route.legs.some((leg) => leg.carrier_codes.length === 0)) {
+    fallbackReason = `static carrier coverage missing for ${input.query.id}`
+  }
+
+  const manualSegment = input.manualRecord.route_segments[0]
+  const segments = !fallbackReason && route && manualSegment
+    ? buildSegments(input.query, route, manualSegment)
+    : null
+  if (!fallbackReason && !segments) fallbackReason = `static route cannot form comparable record for ${input.query.id}`
+
+  if (fallbackReason) {
+    input.warn?.(`[sf-live-benchmark] static vendor failed for ${input.query.id}: ${fallbackReason}; fallback=manual-golden`)
+    return {
+      requested_source: 'static',
+      effective_source: 'manual-golden',
+      record: input.manualRecord,
+      fallback_reason: fallbackReason,
+      estimated_fields: [],
+      provenance: provenance(input.snapshot),
+    }
+  }
+
+  return {
+    requested_source: 'static',
+    effective_source: 'static-openflights+manual-band',
+    record: {
+      ...input.manualRecord,
+      route_segments: segments!,
+      journey_type: route!.route_kind,
+      source: 'static-openflights+manual-band',
+    },
+    estimated_fields: [
+      'route_segments[].departure_at',
+      'route_segments[].arrival_at',
+      'route_segments[].transport_number',
+      'price',
+    ],
+    provenance: provenance(input.snapshot),
+  }
+}

package/ts/capabilities/session/wizard.ts

@@ -0,0 +1,140 @@
+/**
+ * 会话扩展 onboarding wizard(RFC user-session-data-rfc.md §3.3,ADR-21 上架后重设)。
+ *
+ * 单一职责(2026-09-02 重设):**只做 Node 端两件事**——
+ *   ① 扩展文件从源落位到 `~/.gotry/extension`(幂等)
+ *   ② source/dest 静态预检 + manifest.key 校验(给 health-watch 前的快照)
+ *
+ * 浏览器商店安装是浏览器的事,dsh 渲染 verdict.installUrl 是 dsh UI 的事;
+ * gotry **不再**弹 GUI 面板(pbcopy/osascript/zenity/msg)、不再 open 浏览器、
+ * 不再写一墙文字 CLI 指引。任何"装到能用"的 UX 都由浏览器商店 + dsh UI 分担。
+ *
+ * 历史形态回顾:
+ * - 2026-08-30 初版:5 步编排 + 剪贴板 + GUI 面板 + 健康探活(全栈闭环初衷好,但越界管了浏览器)
+ * - 2026-09-02 上架后:缩为 2 步(ensure + watch precheck),纯 Node 职责
+ *
+ * 接口契约:
+ * - `runOnboardingWizard({ dryRun, extensionDir?, sourceDir? })` 返回 2 步 OnboardingResult
+ * - `defaultExtensionDir()` / `describeExtensionDir()` 留作公开工具
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export interface OnboardingStep {
+  step: 'ensure-extension-files' | 'watch-extension-ready'
+  status: 'ok' | 'skip' | 'fail'
+  summary: string
+}
+
+export interface OnboardingOptions {
+  /** 零网络零浏览器;只校验命令编排与输出形态;run-all §40 必走 */
+  dryRun?: boolean
+  /** 扩展落位目录(默认 ~/.gotry/extension) */
+  extensionDir?: string
+  /** 源扩展目录(默认仓库 ./extension/,随 npm 装入 dist/extension) */
+  sourceDir?: string
+}
+
+export interface OnboardingResult {
+  ok: boolean
+  steps: OnboardingStep[]
+  extensionDir: string
+}
+
+const DEFAULT_SOURCE_DIR_CANDIDATES = [
+  join(process.cwd(), 'extension'),
+  join(process.cwd(), 'dist', 'extension'),
+  join(process.cwd(), 'ts', '..', 'extension'),
+]
+
+function resolveExtensionSourceDir(): string {
+  for (const candidate of DEFAULT_SOURCE_DIR_CANDIDATES) {
+    if (existsSync(join(candidate, 'manifest.json'))) return candidate
+  }
+  return DEFAULT_SOURCE_DIR_CANDIDATES[0]!
+}
+
+export function defaultExtensionDir(): string {
+  return join(homedir(), '.gotry', 'extension')
+}
+
+/** 落位扩展文件(幂等);缺源/源不全会 fail-soft,提示用户重跑 `gotry setup` */
+function ensureExtensionFiles(source: string, target: string, dryRun: boolean): OnboardingStep {
+  if (dryRun) return { step: 'ensure-extension-files', status: 'skip', summary: '[dry-run] skip 扩展落位' }
+  try {
+    if (!existsSync(source) || !existsSync(join(source, 'manifest.json'))) {
+      return { step: 'ensure-extension-files', status: 'fail', summary: `源扩展目录缺失 manifest.json: ${source}(先跑 npx gotry setup 落位)` }
+    }
+    mkdirSync(target, { recursive: true })
+    const required = ['manifest.json', 'background.js', 'content-main.js', 'content-bridge.js']
+    for (const f of required) {
+      const src = join(source, f)
+      if (!existsSync(src)) return { step: 'ensure-extension-files', status: 'fail', summary: `源扩展缺 ${f}(重新 npm install 或 gotry setup)` }
+      copyFileSync(src, join(target, f))
+    }
+    return { step: 'ensure-extension-files', status: 'ok', summary: `扩展已落位 ${target}(manifest+3 文件)` }
+  } catch (e) {
+    return { step: 'ensure-extension-files', status: 'fail', summary: `扩展落位失败: ${e instanceof Error ? e.message.slice(0, 120) : String(e)}` }
+  }
+}
+
+/** 静态预检:落位目录可见 + manifest.key 存在(扩展 ID 稳定)+ 源未新于 dest */
+async function watchExtensionReady(dryRun: boolean, sourceDir: string, extensionDir: string): Promise<OnboardingStep> {
+  if (dryRun) return { step: 'watch-extension-ready', status: 'skip', summary: '[dry-run] skip health-watch precheck' }
+  if (!existsSync(extensionDir) || !existsSync(join(extensionDir, 'manifest.json'))) {
+    return { step: 'watch-extension-ready', status: 'fail', summary: `落位缺失 manifest.json:${extensionDir}` }
+  }
+  try {
+    const srcStat = statSync(sourceDir)
+    const dstStat = statSync(extensionDir)
+    if (srcStat.mtimeMs > dstStat.mtimeMs) {
+      return { step: 'watch-extension-ready', status: 'fail', summary: `扩展文件可能过期(源比落位新);重跑 npx gotry setup` }
+    }
+    const manifest = JSON.parse(await (await import('node:fs/promises')).readFile(join(extensionDir, 'manifest.json'), 'utf8'))
+    if (typeof manifest.key !== 'string' || manifest.key.length < 100) {
+      return { step: 'watch-extension-ready', status: 'fail', summary: 'manifest.key 缺失或过短,扩展 ID 不能稳定' }
+    }
+  } catch (e) {
+    return { step: 'watch-extension-ready', status: 'fail', summary: `静态预检失败: ${e instanceof Error ? e.message.slice(0, 120) : String(e)}` }
+  }
+  return { step: 'watch-extension-ready', status: 'ok', summary: '扩展文件就绪(manifest.key 校验通过,后台轮询就绪态由 health-watch 接管)' }
+}
+
+/**
+ * 主入口(2 步):①扩展落位 ②watch precheck 静态预检。
+ * 真 health-watch 由 health-watch.ts 单独负责,不并入 wizard。
+ */
+export async function runOnboardingWizard(opts: OnboardingOptions = {}): Promise<OnboardingResult> {
+  const dryRun = opts.dryRun ?? false
+  const extensionDir = opts.extensionDir ?? defaultExtensionDir()
+  const sourceDir = opts.sourceDir ?? resolveExtensionSourceDir()
+
+  const steps: OnboardingStep[] = []
+  steps.push(ensureExtensionFiles(sourceDir, extensionDir, dryRun))
+  steps.push(await watchExtensionReady(dryRun, sourceDir, extensionDir))
+
+  const ok = steps.every((s) => s.status !== 'fail')
+  return { ok, steps, extensionDir }
+}
+
+/** stdout 人话化打印(给 bootstrap 子进程单行 JSON 输出之外的兜底形态) */
+export function printWizardResult(result: OnboardingResult, destination: NodeJS.WritableStream = process.stdout): void {
+  const tag = (s: OnboardingStep): string => {
+    if (s.status === 'ok') return '✅'
+    if (s.status === 'skip') return '⏭ '
+    return '❌'
+  }
+  for (const s of result.steps) {
+    destination.write(`${tag(s)} ${s.step}: ${s.summary}\n`)
+  }
+  destination.write(`extensionDir=${result.extensionDir}; overall=${result.ok ? 'ok' : 'has-failures'}\n`)
+}
+
+/** 公开诊断探针(bootstrap 报告用) */
+export function describeExtensionDir(extensionDir: string): { exists: boolean; fileCount: number; hasManifest: boolean } {
+  if (!existsSync(extensionDir)) return { exists: false, fileCount: 0, hasManifest: false }
+  const files = readdirSync(extensionDir)
+  return { exists: true, fileCount: files.length, hasManifest: files.includes('manifest.json') }
+}

package/ts/capabilities/session-login.ts

@@ -14,6 +14,9 @@
  */
 
 import { openSession } from './session/transport.ts'
+import { extensionCookieNames, extensionOpenLogin, classifyBridgeFailure } from './session/extension-channel.ts'
+import { EXTENSION_STORE_URL } from './session/extension-bridge.ts'
+import { resolveTransportMode } from './session-search.ts'
 
 export interface LoginTarget {
   domain: string
@@ -48,11 +51,14 @@ export interface SessionLoginResult {
   via: 'session-login' | 'session-login-error'
   evidence: string
   latencyMs: number
-  verdict: 'logged-in' | 'pending' | 'needs-attach' | 'error'
+  verdict: 'logged-in' | 'pending' | 'needs-attach' | 'needs-extension' | 'error'
   site: string
   /** 已检出的登录票据 cookie 名(名字,非值——本模块永不读取/存储/回传任何 cookie 值) */
   tickets?: string[]
   error?: string
+  /** needs-extension 时给出 Chrome Web Store URL —— dsh UI 应直接渲成可点链接(浏览器自己当安装器,gotry 不插手) */
+  installUrl?: string
+  installAction?: 'add-to-chrome'
 }
 
 function err(site: string, verdict: SessionLoginResult['verdict'], error: string, started: number, ts: string): SessionLoginResult {
@@ -74,7 +80,7 @@ export async function pollTicketNames(browser: { cookies(): Promise<CookieLike[]
 /**
  * 产品化登录引导(永不抛错;登录由用户在携程官网完成,gotry 只做名称级存在性检查)。
  * verdict:logged-in=已检出票据;pending=登录入口已打开、用户尚未完成(不阻塞,可稍后再查);
- * needs-attach=用户 Chrome 未开调试端口(一次性开关指引);error=其余降级。
+ * needs-extension=扩展桥未连接(一次性安装指引,默认车道);needs-attach=cdp 车道下用户 Chrome 未开调试端口;error=其余降级。
  */
 export async function sessionLogin(q: SessionLoginQuery = {}): Promise<SessionLoginResult> {
   const started = Date.now()
@@ -84,6 +90,10 @@ export async function sessionLogin(q: SessionLoginQuery = {}): Promise<SessionLo
   if (!target) {
     return err(site, 'error', `未知站点 ${site}(可选 ${Object.keys(LOGIN_TARGETS).join('/')})`, started, ts)
   }
+  // 扩展车道(默认):零 CDP、零系统弹窗——cookie 名快查 + 登录入口 job
+  if (resolveTransportMode() === 'extension') {
+    return sessionLoginViaExtension(site, target, q, started, ts)
+  }
   // 人机共治纪律:开自己的新标签页并置前台——用户必须看见登录页(2026-08-29 founder:
   // 「我根本就看不到登录页面」,此前误劫持用户既有标签页);closeOwnPage=false 把登录页留给用户
   const t = await openSession({ mode: 'cdp', guard: false })
@@ -143,4 +153,55 @@ export async function sessionLogin(q: SessionLoginQuery = {}): Promise<SessionLo
     await t.close().catch(() => { /* ignore */ })
     return err(site, 'error', e instanceof Error ? e.message : String(e), started, ts)
   }
+}
+
+/**
+ * 扩展车道登录引导(2026-08-29 传输层方案 C):语义与 cdp 车道一致——
+ * 自动检测优先(票据名在 = 零弹窗直接确认);未检出才开登录入口 job(置前台,标签留给用户);
+ * 只读轮询票据名,永不接触 cookie 值。verdict:logged-in | pending | needs-extension | error。
+ */
+async function sessionLoginViaExtension(site: string, target: LoginTarget, q: SessionLoginQuery, started: number, ts: string): Promise<SessionLoginResult> {
+  const evidenceTag = `[会话:${site}-login@${ts}]`
+  const quick = (verdict: SessionLoginResult['verdict'], error: string): SessionLoginResult => {
+    const base: SessionLoginResult = {
+      ok: false, via: 'session-login-error', evidence: `[会话:login-error@${ts}] ${error.slice(0, 200)}`,
+      latencyMs: Date.now() - started, verdict, site, error: error.slice(0, 400),
+    }
+    // needs-extension:浏览器自己当安装器,gotry 不弹面板不开剪贴板——只把商店 URL 给 dsh UI
+    if (verdict === 'needs-extension') base.installUrl = EXTENSION_STORE_URL
+    if (verdict === 'needs-extension') base.installAction = 'add-to-chrome'
+    return base
+  }
+  // 自动检测优先:先只读票据名——已登录则零交互直接确认(与 cdp 车道同一语义,founder「UI 里有自动检测吗」)
+  const pre = await extensionCookieNames({ site, domain: target.domain, ticketNames: target.names, timeoutMs: 8_000 })
+  if (!pre.ok) return quick(classifyBridgeFailure(pre.kind) === 'needs-extension' ? 'needs-extension' : 'error', pre.summary)
+  if (pre.tickets.length > 0) {
+    return {
+      ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'logged-in', site, tickets: pre.tickets,
+      evidence: `${evidenceTag} 自动检测:票据 cookie 已在(先前登录已生效)——[${pre.tickets.join(', ')}](只读名字,0 网页交互,零弹窗)`,
+    }
+  }
+  // 未检出 → 开登录入口标签(置前台,绝不劫持用户已有页面;登录在携程官网完成)
+  const opened = await extensionOpenLogin({ site, url: target.entryUrl, timeoutMs: 15_000 })
+  if (!opened.ok) return quick(classifyBridgeFailure(opened.kind) === 'needs-extension' ? 'needs-extension' : 'error', opened.summary)
+  const waitMs = Math.min(Math.max(q.waitMs ?? 90_000, 0), 300_000)
+  const pollMs = Math.min(Math.max(q.pollMs ?? 3_000, 500), 10_000)
+  const deadline = Date.now() + waitMs
+  let tickets: string[] = []
+  while (Date.now() < deadline) {
+    await new Promise<void>((resolve) => setTimeout(resolve, pollMs))
+    const poll = await extensionCookieNames({ site, domain: target.domain, ticketNames: target.names, timeoutMs: 8_000 })
+    if (poll.ok) tickets = poll.tickets
+    if (tickets.length > 0) break
+  }
+  if (tickets.length > 0) {
+    return {
+      ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'logged-in', site, tickets,
+      evidence: `${evidenceTag} 票据 cookie 已检出 [${tickets.join(', ')}](只读名字;登录在你自己的浏览器里完成,gotry 全程未接触任何密码/验证码/cookie 值)`,
+    }
+  }
+  return {
+    ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'pending', site, tickets: [],
+    evidence: `${evidenceTag} 登录入口已在你的 Chrome 置前打开(${target.label});在标签页里正常登录完成后再说一声「继续查」即可——gotry 只检查"是否已登录",永不收集你的账号信息`,
+  }
 }

package/ts/capabilities/session-search.ts

@@ -1,16 +1,25 @@
 /**
  * 会话检索编排层(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] = 用户本人会话内实时检索,非官方 API;
  * 风控命中(verdict='challenged')= degraded,绝不重试、绝不绕过(合规支柱②)。
  * 节律(§3.4):同站点 ≥30s 间隔 + 单调冷却;超间隔返回 verdict='cooldown'。
- * 永不抛错;transport 必带 ReadGuard(fail-closed);测试/巡检用隔离 profile 与 stateRoot。
+ * 永不抛错;扩展车道 fail-closed(桥/扩展不可用即 verdict,零花费);测试/巡检用隔离 profile 与 stateRoot。
  */
 
 import { openSession } from './session/transport.ts'
+import { extensionCookieNames, extensionSearchJob, classifyBridgeFailure } from './session/extension-channel.ts'
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
 import { buildEntryUrl, NETWORK_HINTS, parseBatchSearch, LOGIN_COOKIE_NAMES, SITE_DOMAIN, type SessionFlightOption } from './session/adapters/ctrip-flight.ts'
+import { EXTENSION_STORE_URL } from './session/extension-bridge.ts'
 
-export type SessionVerdict = 'hit' | 'miss' | 'error' | 'challenged' | 'cooldown' | 'needs-login' | 'needs-attach'
+export type SessionVerdict = 'hit' | 'miss' | 'error' | 'challenged' | 'cooldown' | 'needs-login' | 'needs-attach' | 'needs-extension'
 
 export interface SessionSearchResult {
   ok: boolean
@@ -20,6 +29,9 @@ export interface SessionSearchResult {
   verdict: SessionVerdict
   options?: SessionFlightOption[]
   error?: string
+  /** needs-extension 时给出 Chrome Web Store URL —— dsh UI 应直接渲成可点链接(浏览器自己当安装器,gotry 不插手) */
+  installUrl?: string
+  installAction?: 'add-to-chrome'
 }
 
 export interface SessionFlightQuery {
@@ -54,6 +66,49 @@ export function classifyTransportFailure(summary: string, cdpMode: boolean): Ext
     : 'error'
 }
 
+/** 传输车道解析(纯函数,测试锚点):persistent=隔离 profile(测试自检);cdp=显式 opt-in;扩展=默认 */
+export function resolveTransportMode(profileDir?: string): 'cdp' | 'persistent' | 'extension' {
+  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: Partial<Pick<NodeJS.ProcessEnv, 'GOTRY_SESSION_LIVE'>> = process.env): boolean {
+  return env.GOTRY_SESSION_LIVE === '1'
+}
+
+/** Deterministic offline observation used when the live session gate is closed. */
+export function offlineSessionFlightResult(): SessionSearchResult {
+  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: SessionFlightQuery,
+  search: (query: SessionFlightQuery) => Promise<SessionSearchResult> = sessionFlightSearch,
+  env: Partial<Pick<NodeJS.ProcessEnv, 'GOTRY_SESSION_LIVE'>> = process.env,
+): Promise<SessionSearchResult> {
+  if (!sessionLiveEnabled(env)) return offlineSessionFlightResult()
+  return search(q)
+}
+
+/** 扩展车道 job 审计(ReadGuard 审计同款 JSONL,kind 区分;auditPath 缺省不落盘) */
+export function appendExtensionAudit(auditPath: string | undefined, entry: { kind: 'extension-session-job'; site: string; url: string; jobId: string; result: string }): void {
+  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 async function sessionFlightSearch(q: SessionFlightQuery): Promise<SessionSearchResult> {
   const started = Date.now()
   const ts = new Date().toISOString()
@@ -74,8 +129,55 @@ export async function sessionFlightSearch(q: SessionFlightQuery): Promise<Sessio
     return err('error', `unresolved entry: ${(entry.unresolved ?? []).join('/')} 不在城市码表`)
   }
 
+  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)
+      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' as const }
+      }
+      return err(verdict, login.summary)
+    }
+    // 登录态闸:用户自己的账号;匿名默认拒(allowAnonymous 仅链路自检且证据标自检态)
+    if (login.tickets.length === 0 && !q.allowAnonymous) {
+      return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)')
+    }
+    // ② 检索 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)}`,
+    })
+    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' as const }
+      }
+      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 options = parseBatchSearch(r.body)
+    const verdict: SessionVerdict = options.length > 0 ? '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,
+    }
+  }
+
   // 人机共治纪律:检索一律开自己的新标签页(绝不劫持用户已有页面),用完关自己的页
-  const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: q.profileDir ? '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 失败`,两种形态都要归入同一用户门禁。