@danceiny/gotry 0.0.1-rc.10

package/ts/capabilities/hbcli.ts

@@ -0,0 +1,152 @@
+/**
+ * hotelbyte-cli(hbcli)能力层封装:进程内 spawn bun + hbcli --json。
+ *
+ * 拿到外部资源信息能力的三条路径:
+ *   1. 实时 hbcli 调用(能力强,延迟 1-3s,需凭证 + 证书有效)
+ *   2. 静态数据包(data/hotels_2026.json)——证据标注 [静态包:估算]
+ *   3. 简易降级返回(什么都不查得到时,提供"工具暂不可用"而不是抛错)
+ *
+ * 证书/凭证/网络问题一律降级,不抛到调用方——能力层契约:永远返回一种结果。
+ *
+ * §7-1/§7-2 L4 不变量:证据链标注([实时API:hbcli@<ts>] / [静态包:估算]);
+ * 估算必须显式标记。这是 L4 与 L1 透明卡片的接缝。
+ */
+
+import { spawn } from 'node:child_process'
+
+export interface HbcliCallOptions {
+  /** hbcli 二进制路径(默认 'hbcli',依赖 PATH) */
+  hbcliBin?: string
+  /** 超时(ms) */
+  timeoutMs?: number
+  /** 凭证(token)——空时不传,hbcli 用本地默认 */
+  token?: string
+  /** 环境(uat/prod/dev);默认 uat */
+  env?: 'uat' | 'prod' | 'dev'
+}
+
+export interface HbcliCallResult {
+  /** 是否走了实时 hbcli */
+  via: 'hbcli-realtime' | 'hbcli-cache' | 'hbcli-error'
+  /** hbcli 退码 0=成功 */
+  exitCode: number
+  /** 解析后的 JSON(若 --json 模式输出可解析;否则为空) */
+  result: unknown
+  /** 证据链标注(L4 契约;无论成功失败都填) */
+  evidence: string
+  /** hbcli 原始 stdout/stderr(供调试,2000 字符上限) */
+  stdout?: string
+  stderr?: string
+  /** 经过的时长 */
+  latencyMs: number
+  /** 错误时降级原因 */
+  error?: string
+}
+
+/** 通用 hbcli JSON 调用封装:失败不抛,而是返回降级结果 */
+export async function callHbcliJson(
+  args: string[],
+  opts: HbcliCallOptions = {},
+): Promise<HbcliCallResult> {
+  const started = Date.now()
+  const bin = opts.hbcliBin ?? 'hbcli'
+  const timeoutMs = opts.timeoutMs ?? 15_000
+  const env = opts.env ?? 'uat'
+  const envVars: Record<string, string> = { HOTELBYTE_ENV: env }
+  if (opts.token) envVars['HOTELBYTE_TOKEN'] = opts.token
+
+  return new Promise((resolve) => {
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const child = spawn(bin, args, { env: { ...process.env, ...envVars } })
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true
+        child.kill('SIGKILL')
+        resolve({
+          via: 'hbcli-error', exitCode: -1, result: null,
+          evidence: `[实时API:hbcli@timeout@${new Date().toISOString()}]`,
+          latencyMs: Date.now() - started, error: `timeout after ${timeoutMs}ms`,
+        })
+      }
+    }, timeoutMs)
+    child.stdout.on('data', (d: Buffer) => { stdout += d.toString() })
+    child.stderr.on('data', (d: Buffer) => { stderr += d.toString() })
+    child.on('close', (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      const latencyMs = Date.now() - started
+      if (code !== 0) {
+        // 不抛错,降级返回。证据链显式标注:实时 API 调用失败+原因+时间戳。
+        resolve({
+          via: 'hbcli-error', exitCode: code ?? -1, result: null,
+          evidence: `[实时API:hbcli@error@${new Date().toISOString()}]`,
+          stderr: stderr.slice(0, 2000),
+          latencyMs, error: stderr.trim().slice(0, 200) || `exit ${code}`,
+        })
+        return
+      }
+      // 尝试 JSON 解析
+      const jStart = stdout.search(/[\{\[]/)
+      const jsonStr = jStart >= 0 ? stdout.slice(jStart) : ''
+      let result: unknown = null
+      if (jsonStr) {
+        try { result = JSON.parse(jsonStr) } catch { /* 非 JSON 输出,留给调用方处理 */ }
+      }
+      resolve({
+        via: 'hbcli-realtime', exitCode: 0, result,
+        evidence: `[实时API:hbcli@${new Date().toISOString()}]`,
+        stdout: stdout.slice(0, 2000), latencyMs,
+      })
+    })
+    child.on('error', (e) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      // ENOENT (二进制不存在) 等也走降级路径
+      resolve({
+        via: 'hbcli-error', exitCode: -1, result: null,
+        evidence: `[实时API:hbcli@spawn_error@${new Date().toISOString()}]`,
+        latencyMs: Date.now() - started, error: (e as Error).message,
+      })
+    })
+  })
+}
+
+/** 高层语义化封装:酒店列表查询(down-tier to 静态包 + 证据链标注) */
+export async function searchHotels(
+  query: { destination: string; checkIn?: string; checkOut?: string; adults?: number },
+  opts: HbcliCallOptions & { fallbackPath?: string } = {},
+): Promise<HbcliCallResult & { hotels?: unknown; summary: string }> {
+  // 旗标对齐上游 CLI v0.3.0(命令树扁平化后):--destination-name + --room-occupancies;
+  // hotel-list 无日期旗标(房价按上游当前窗口),checkIn/checkOut 留给 hotel-rates 跟进
+  const hbArgs = ['search', 'hotel-list', '--json', '--page-size', '10']
+  if (query.destination) hbArgs.push('--destination-name', query.destination)
+  if (query.adults) hbArgs.push('--room-occupancies', JSON.stringify([{ adultCount: query.adults, childrenAges: [] }]))
+  const live = await callHbcliJson(hbArgs, opts)
+  if (live.via === 'hbcli-realtime') {
+    return { ...live, hotels: live.result, summary: `${query.destination}:hbcli 实时返回${query.checkIn || query.checkOut ? '(日期不传上游 list,以当前窗口房价返回)' : ''}` }
+  }
+  // 降级:读静态包
+  const fallback = opts.fallbackPath
+  if (fallback) {
+    try {
+      const { readFile } = await import('node:fs/promises')
+      const pack = JSON.parse(await readFile(fallback, 'utf-8')) as Record<string, unknown>
+      return {
+        ...live,
+        hotels: pack,
+        summary: `${query.destination}:hbcli 不可用(${live.error ?? live.via}),降级到静态包`,
+      }
+    } catch { /* 静态包读不到也优雅降级 */ }
+  }
+  return { ...live, summary: `${query.destination}:hbcli 不可用且无静态包(仅返回错误)` }
+}
+
+/** 高层语义化封装:目的地列表(无数据依赖,通常 hbcli dest 命令可独立调通) */
+export async function listDestinations(opts: HbcliCallOptions = {}): Promise<HbcliCallResult & { destinations?: unknown }> {
+  const r = await callHbcliJson(['search', 'destinations', '--json'], opts)
+  return { ...r, destinations: r.result }
+}

package/ts/capabilities/incident-log.ts

@@ -0,0 +1,148 @@
+/**
+ * 进程级事故日志(D-NEW 护栏):fsync append-only JSONL。
+ *
+ * 目的: dsh 0.1.1-rc.1 只接 SIGINT/SIGTERM,缺 uncaughtException/unhandledRejection——
+ * 任一插件 wasm/runtime 异常穿透到 node 层都会让整个 web UI 进程死亡,
+ * 现场不存。这次(Z3 WASM mk_bool_var 崩溃)教训:连个取证都没有。
+ *
+ * 设计: 进程级 handler 同步写盘(fsync),尽量在进程被杀前留下事故证据。
+ * handler 自身不再抛——再次抛出会绕过 handler,变成无声死亡。
+ *
+ * §11 状态面同步:事故日志是 gotry-state/incidents.jsonl,
+ * 用户可见(README 第 x 节),可清理。
+ */
+
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { ToolFailure } from '../src/tool-packet.ts'
+
+export type IncidentKind = 'uncaughtException' | 'unhandledRejection' | 'plugin_error' | 'tool_execute_error'
+
+export interface Incident {
+  ts: string
+  kind: IncidentKind
+  message: string
+  stack?: string
+  /** 来自哪个来源(plugin_name / service url 等) */
+  source?: string
+}
+
+/** 解析 gotry-state 绝对路径(stateRoot 可相对也可绝对) */
+export function resolveIncidentsPath(stateRoot: string, filename = 'incidents.jsonl'): string {
+  const root = isAbsolute(stateRoot)
+    ? stateRoot
+    : join(process.cwd(), stateRoot)
+  return join(root, 'gotry-state', filename)
+}
+
+function ensureDir(path: string): void {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+let installed = false
+let logPath: string | null = null
+
+/**
+ * 写入一条事故并 fsync。同步执行——handler 内异步无效。
+ * 自身 try/catch 自保,不让写入失败再抛一次把进程杀掉。
+ */
+export function recordIncident(inc: Incident, stateRoot?: string): boolean {
+  const target = stateRoot ? resolveIncidentsPath(stateRoot) : (logPath ?? resolveIncidentsPath('.'))
+  try {
+    ensureDir(target)
+    appendFileSync(target, JSON.stringify(inc) + '\n', { flag: 'a' })
+    // fsync: 让盘数据落定,免得被杀时缓冲丢
+    const fd = require('node:fs').openSync(target, 'a')
+    require('node:fs').fsyncSync(fd)
+    require('node:fs').closeSync(fd)
+    return true
+  } catch {
+    // 绝对不能在这里抛——我们正在处理已经抛过一次的进程级错误
+    return false
+  }
+}
+
+/**
+ * 安装进程级护栏:进程整个生命周期仅生效一次(重复调用安全)。
+ * 必须同步执行——异步发生在事件循环下一次,而 wasm 崩溃后已无下一轮。
+ *
+ * @returns 一个 disposer,卸载所有监听(测试场景使用)
+ */
+export function installProcessGuards(stateRoot: string, labels?: { uncaughtException?: string; unhandledRejection?: string }): () => void {
+  if (installed) return () => { /* 已装,no-op */ }
+  installed = true
+  logPath = resolveIncidentsPath(stateRoot)
+
+  const uncaughtHandler = (err: Error, origin: NodeJS.UncaughtExceptionOrigin | 'uncaughtException') => {
+    recordIncident({
+      ts: new Date().toISOString(),
+      kind: 'uncaughtException',
+      message: (err?.message ?? String(err)).slice(0, 2000),
+      stack: (err?.stack ?? '').slice(0, 4000),
+      source: labels?.uncaughtException ?? String(origin),
+    }, stateRoot)
+    // 不调用 process.exit——让 dsh/上级容器的重启策略负责;
+    // 如果 dsh 不接住,我们至少留下事故记录。
+  }
+
+  const rejectionHandler = (reason: unknown, promise: Promise<unknown>) => {
+    const msg = reason instanceof Error ? reason.message : String(reason)
+    const stack = reason instanceof Error ? (reason.stack ?? '') : ''
+    recordIncident({
+      ts: new Date().toISOString(),
+      kind: 'unhandledRejection',
+      message: msg.slice(0, 2000),
+      stack: stack.slice(0, 4000),
+      source: labels?.unhandledRejection ?? 'promise',
+    }, stateRoot)
+  }
+
+  process.on('uncaughtException', uncaughtHandler)
+  process.on('unhandledRejection', rejectionHandler)
+  return () => {
+    process.off('uncaughtException', uncaughtHandler)
+    process.off('unhandledRejection', rejectionHandler)
+    installed = false
+  }
+}
+
+/**
+ * 工具执行面异常隔离(D-NEW gotry 侧收尾):dsh 的一个工具 execute 抛错/拒绝
+ * 会沿 cordis 传到主循环,拖垮整个会话。包装后:降级为结构化错误返回给 LLM、
+ * 事故落盘,永不向上抛。落盘失败也不抛(双保险,仍返回结构化错误)。
+ * 失败形状 = ToolFailure(RFC S1 observation envelope 的失败分支,编译期对齐)。
+ */
+export function guardToolExecute<A, R>(name: string, stateRoot: string, execute: (args: A, exec: unknown) => R | Promise<R>): (args: A, exec: unknown) => Promise<R> {
+  return async (args: A, exec: unknown): Promise<R> => {
+    try {
+      return await execute(args, exec)
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e))
+      recordIncident({
+        ts: new Date().toISOString(),
+        kind: 'tool_execute_error',
+        message: `${name}: ${err.message}`.slice(0, 2000),
+        stack: (err.stack ?? '').slice(0, 4000),
+        source: name,
+      }, stateRoot)
+      const failure: ToolFailure = {
+        ok: false,
+        summary: `gotry_${name} 内部错误(已隔离,会话继续): ${err.message.slice(0, 300)}`,
+        evidence: `[incident:tool_execute_error@${new Date().toISOString()}]`,
+      }
+      return failure as R
+    }
+  }
+}
+
+/** CLI 调试:从命令行单独跑查看当前进程是否已挂护栏 */
+if (import.meta.url === `file://${fileURLToPath(import.meta.url)}` && process.argv[2] === '--smoke') {
+  const stateRoot = process.argv[3] ?? '.'
+  installProcessGuards(stateRoot, { uncaughtException: 'smoke', unhandledRejection: 'smoke' })
+  writeFileSync(resolveIncidentsPath(stateRoot) + '.smoke', 'ok')
+  // 触发一次未捕获,应被写盘(不真正杀进程——进程继续跑完)
+  setTimeout(() => Promise.reject(new Error('intentional smoke-rejection')), 50)
+  setTimeout(() => { console.log('SMOKE OK'); process.exit(0) }, 500)
+}

package/ts/capabilities/opensky.ts

@@ -0,0 +1,121 @@
+/**
+ * OpenSky 实时观测桥(免费匿名,~400 credits/天,~4 req/s burst):
+ * 查某 callsign 的飞机是否在 ADS-B 网络的当前观测里——航线层的实时印证。
+ *
+ * 契约(与 weather.ts / hbcli.ts 同构):
+ *   - 永不抛错:网络失败/超时/解析失败一律降级返回;
+ *   - 三值语义:命中=强肯定;查空≠证伪(ADS-B 覆盖有限,降权不排除);服务不可用=无结论;
+ *   - 证据链:成功 [实时API:opensky@ts];失败 [实时API:opensky@error@ts]。
+ *
+ * 接口面(2026-08 实际可达,匿名路径):
+ *   GET /api/states/all  — 当前全球 ADS-B 状态,~10000 架
+ *   GET /api/states/all?icao24=<hex>  — 单飞机
+ *   /api/flights/airport 历史查 = 需鉴权(匿名 403)
+ *
+ * 数据意义:与 OpenFlights 骨架(通航性)+ 静态班次包(班期时刻) 三值互补——
+ *   OpenFlights = 历史上是否通航过(offline)
+ *   flights_2026.json = 调研估算的班次时刻
+ *   OpenSky = 该 callsign 的飞机「现在」是否在观测网络里(实时刻正飞)
+ *
+ * v0.0.1-rc.3 +: 之前是 scripts/opensky-check.ts 一次性 CLI(M2 时设计为 7 天窗
+ * 历史校验,但匿名路径实际不可达),现升级为能力层封装 + dsh 插件工具。
+ */
+
+export interface FlightLiveQuery {
+  /** 航班号/呼号(如 EK329 / CA985);大小写都行 */
+  callsign: string
+  /** 调用方所属机场 ICAO 四字码(用于地理命中),不传只返回 obs 状态 */
+  airport?: string
+  /** 超时(ms);默认 10_000 */
+  timeoutMs?: number
+}
+
+export interface FlightHit {
+  icao24: string
+  callsign: string | null
+  /** OpenSky states/all 用 last_contact 列作为时间戳代理 */
+  lastSeen: number
+  firstSeen: number
+  /** 调用方传入的机场(OpenSky states/all 不返回) */
+  estArrivalAirport: string | null
+}
+
+export interface FlightVerifyResult {
+  verdict: 'observed' | 'not_observed' | 'unavailable'
+  callsign: string
+  airport: string | null
+  sampleSize: number
+  hits?: FlightHit[]
+  evidence: string
+  via: 'opensky' | 'opensky-error'
+  latencyMs: number
+  error?: string
+}
+
+const BASE = 'https://opensky-network.org/api'
+
+async function fetchOpenSky(url: string, timeoutMs: number): Promise<{ ok: boolean; data?: unknown; error?: string }> {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  try {
+    const res = await fetch(url, {
+      signal: ctrl.signal,
+      headers: { Accept: 'application/json', 'User-Agent': 'gotry/0.0.1-rc.3 (+https://github.com/Danceiny/gotry)' },
+    })
+    if (!res.ok) return { ok: false, error: `opensky HTTP ${res.status}${res.status === 429 ? ' (rate limited, 400 credits/day anonymous)' : ''}` }
+    return { ok: true, data: await res.json() }
+  } catch (e) {
+    return { ok: false, error: (e as Error).message.slice(0, 200) }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+const upper = (s: string): string => s.trim().toUpperCase()
+
+export async function verifyFlight(query: FlightLiveQuery): Promise<FlightVerifyResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const cs = upper(query.callsign)
+  const airport = query.airport ? upper(query.airport) : null
+  const r = await fetchOpenSky(`${BASE}/states/all`, query.timeoutMs ?? 10_000)
+  const latencyMs = Date.now() - started
+
+  if (!r.ok) {
+    return {
+      verdict: 'unavailable',
+      callsign: cs, airport,
+      sampleSize: 0, hits: [],
+      evidence: `[实时API:opensky@error@${ts}] ${r.error}`,
+      via: 'opensky-error',
+      latencyMs, error: r.error,
+    }
+  }
+
+  // /api/states/all → { time, states: Array<17 元素数组> }
+  // [0 icao24, 1 callsign, 2 origin_country, 3 time_position, 4 last_contact,
+  //  5 lon, 6 lat, 7 baro_altitude, 8 on_ground, ...]
+  const rawStates: unknown[][] = ((r.data ?? {}) as { states?: unknown[][] }).states ?? []
+  const observed: FlightHit[] = rawStates
+    .filter(row => ((row[1] ?? '') as string).trim().toUpperCase().includes(cs))
+    .map(row => ({
+      icao24: String(row[0] ?? ''),
+      callsign: ((row[1] ?? '') as string).trim() || null,
+      lastSeen: Number(row[4] ?? 0),
+      firstSeen: Number(row[4] ?? 0),
+      estArrivalAirport: airport,
+    }))
+
+  const verdict: FlightVerifyResult['verdict'] = observed.length > 0 ? 'observed' : 'not_observed'
+  const evidence = observed.length > 0
+    ? `[实时API:opensky@${ts}] ✅ 全球 ADS-B 当前观测命中 ${cs} (${observed.length} 架)`
+    : `[实时API:opensky@${ts}] ○ 当前 ADS-B 全球观测列表未见 ${cs}(ADS-B 覆盖有限,不作否定结论)`
+
+  return {
+    verdict, callsign: cs, airport,
+    sampleSize: rawStates.length,
+    hits: observed, evidence,
+    via: 'opensky',
+    latencyMs,
+  }
+}

package/ts/capabilities/session/action-cache.ts

@@ -0,0 +1,148 @@
+/**
+ * action-cache 本地自愈层(RFC user-session-data-rfc.md §3.2 / §2.3;Stagehand 云端缓存的本地化):
+ *
+ * 目的:会话检索的查询模式高度重复(同站点同类型搜索),首跑用 LLM/规则定位,后续走
+ * 缓存的确定性载荷零成本重放;站点改版 → DOM 指纹失配 → miss → 重新定位并回写。
+ *
+ * 设计原则(Stagehand「错误的缓存点击比慢更糟」的被动失效):
+ *   - key = site + action + 参数模板(%from%/%to%/%date% 变量化,同型查询共享条目);
+ *   - 每条目绑 domFingerprint(快照/接口形状的 sha256 指纹);lookup 时现场指纹与条目不符 = miss(即使 key 命中);
+ *   - miss 即回写(记录新定位),过期(默认 48h)与容量(每 site 默认 50 条,LRU)被动淘汰;
+ *   - 纯函数 + JSON 文件持久化(隔离 stateRoot;损坏文件按空缓存处理,永不抛错)。
+ *
+ * P2 切片:模块+确定性测试先行;消费方(P2 美团适配器/a11y 兜底)下一切片接线。
+ */
+
+import { createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export interface ActionCacheEntry {
+  /** site:action:参数化模板 key,如 ctrip-flight:search:%from%->%to%:%date% */
+  key: string
+  /** 建条目时的 DOM/接口形状指纹;lookup 现场指纹必须一致才命中 */
+  domFingerprint: string
+  /** 确定性重放载荷(消费方自定义:URL 模板/selector 序列/解析器名) */
+  locator: Record<string, string>
+  createdAt: string
+  lastHitAt: string
+  hits: number
+}
+
+export interface ActionCacheOptions {
+  /** 条目 TTL ms,默认 48h(对齐 Stagehand) */
+  ttlMs?: number
+  /** 每站点条目上限(LRU 淘汰),默认 50 */
+  maxEntriesPerSite?: number
+  /** 覆盖「现在」(测试注入) */
+  now?: () => Date
+}
+
+/** 把具体查询参数变量化为模板 key:日期→%date%,from/to 语义序在前,其余参数按字典序尾随 */
+export function templateKey(site: string, action: string, params: Record<string, string>): string {
+  const val = (k: string): string => (k === 'date' ? '%date%' : (params[k] ?? '').trim())
+  const head = ['from', 'to', 'date'].filter((k) => k in params).map(val)
+  const tail = Object.keys(params).filter((k) => !['from', 'to', 'date'].includes(k)).sort().map(val)
+  return `${site}:${action}:${[...head, ...tail].join('|')}`
+}
+
+/** 指纹:快照/接口形状文本 → sha256 前 16 位(微改版即失配——宁可 miss 不可错点) */
+export function fingerprint(shapeText: string): string {
+  return createHash('sha256').update(shapeText).digest('hex').slice(0, 16)
+}
+
+export class ActionCache {
+  private entries = new Map<string, ActionCacheEntry>()
+  private loaded = false
+  private readonly ttlMs: number
+  private readonly maxPerSite: number
+  private readonly now: () => Date
+
+  constructor(private readonly filePath: string, opts: ActionCacheOptions = {}) {
+    this.ttlMs = opts.ttlMs ?? 48 * 3600_000
+    this.maxPerSite = opts.maxEntriesPerSite ?? 50
+    this.now = opts.now ?? (() => new Date())
+  }
+
+  private load(): void {
+    if (this.loaded) return
+    this.loaded = true
+    try {
+      if (existsSync(this.filePath)) {
+        const raw = JSON.parse(readFileSync(this.filePath, 'utf8')) as ActionCacheEntry[]
+        for (const e of raw) {
+          if (e?.key && e.domFingerprint && e.locator) this.entries.set(e.key, e)
+        }
+      }
+    } catch { /* 损坏文件按空缓存处理 */ }
+  }
+
+  private persist(): void {
+    try {
+      mkdirSync(dirname(this.filePath), { recursive: true })
+      const tmp = this.filePath + '.tmp'
+      writeFileSync(tmp, JSON.stringify([...this.entries.values()], null, 0), 'utf8')
+      writeFileSync(this.filePath, readFileSync(tmp, 'utf8'), 'utf8')
+      try { require('node:fs').rmSync(tmp) } catch { /* best effort */ }
+    } catch { /* 持久化失败不阻塞内存路径 */ }
+  }
+
+  /** 站点前缀条目数(LRU 淘汰用) */
+  private siteEntries(site: string): ActionCacheEntry[] {
+    return [...this.entries.values()].filter((e) => e.key.startsWith(site + ':'))
+  }
+
+  /** 命中三条件:key 存在 + 未过期 + 指纹一致;命中计 hits 并惰性落盘 */
+  lookup(key: string, domFingerprint: string, site: string): ActionCacheEntry | null {
+    this.load()
+    const e = this.entries.get(key)
+    if (!e) return null
+    if (this.now().getTime() - Date.parse(e.lastHitAt || e.createdAt) > this.ttlMs) {
+      this.entries.delete(key)
+      this.persist()
+      return null
+    }
+    if (e.domFingerprint !== domFingerprint) return null // 改版:被动失效,等 record 回写
+    e.hits += 1
+    e.lastHitAt = this.now().toISOString()
+    this.persist()
+    void site
+    return e
+  }
+
+  /** miss 后回写(重新定位的产物);同 key 覆盖;超容 LRU 淘汰最旧 */
+  record(key: string, domFingerprint: string, locator: Record<string, string>, site: string): ActionCacheEntry {
+    this.load()
+    const ts = this.now().toISOString()
+    const prev = this.entries.get(key)
+    this.entries.set(key, {
+      key, domFingerprint, locator,
+      createdAt: prev?.createdAt ?? ts,
+      lastHitAt: ts,
+      hits: prev?.hits ?? 0,
+    })
+    const siteList = this.siteEntries(site)
+    if (siteList.length > this.maxPerSite) {
+      const victim = siteList.sort((a, b) => Date.parse(a.lastHitAt) - Date.parse(b.lastHitAt))[0]
+      if (victim) this.entries.delete(victim.key)
+    }
+    this.persist()
+    return this.entries.get(key)!
+  }
+
+  invalidate(key: string): void {
+    this.load()
+    this.entries.delete(key)
+    this.persist()
+  }
+
+  size(site?: string): number {
+    this.load()
+    return site ? this.siteEntries(site).length : this.entries.size
+  }
+}
+
+/** 便捷入口:隔离 stateRoot 下的缓存文件路径 */
+export function actionCachePath(stateRoot: string): string {
+  return join(stateRoot, 'session-action-cache.json')
+}

package/ts/capabilities/session/adapters/ctrip-flight.ts

@@ -0,0 +1,107 @@
+/**
+ * 携程机票站点适配器(RFC §3.2 首个适配器;PoC 已识别接口面,data-sources.md §8):
+ *   - entry:URL 参数直开(https://flights.ctrip.com/online/list/oneway-{from}-{to}?depdate=YYYY-MM-DD)
+ *   - networkHints:主搜索接口 search/api/search/batchSearch(POST,~550KB,国内票同走)
+ *   - 解析:flightItineraryList[].flightSegments[0].flightList[0] + priceList 最小 adultPrice
+ *     (schema 实测 2026-08-28,见 data-sources.md §8)
+ * 只读:适配器不含任何提交/预订语义;URL 直开即零 DOM 交互。
+ */
+
+/** 城市三字码表(小起步集;词表外 unresolved 逐字保留,不做开放式猜测——ADR-12 同款边界) */
+const CITY_CODES: Record<string, string> = {
+  上海: 'sha', 北京: 'bjs', 广州: 'can', 深圳: 'szx', 成都: 'ctu', 昆明: 'kmg',
+  大理: 'dlu', 丽江: 'ljg', 西安: 'sia', 杭州: 'hgh', 三亚: 'syx', 厦门: 'xmn',
+  重庆: 'cqg', 青岛: 'taa', 长沙: 'csx', 武汉: 'wuh', 南京: 'nkg', 郑州: 'cgo',
+  贵阳: 'kwe', 桂林: 'kwl', 西双版纳: 'jhg', 香格里拉: 'dig',
+}
+
+export interface AdapterEntry {
+  ok: boolean
+  url?: string
+  /** 词表外城市逐字保留(调用方降级无日期/无线路搜索) */
+  unresolved?: string[]
+}
+
+export function buildEntryUrl(from: string, to: string, depDate: string): AdapterEntry {
+  const unresolved: string[] = []
+  const fromCode = CITY_CODES[from]
+  const toCode = CITY_CODES[to]
+  if (!fromCode) unresolved.push(from)
+  if (!toCode) unresolved.push(to)
+  if (unresolved.length > 0 || !/^\d{4}-\d{2}-\d{2}$/.test(depDate)) {
+    return { ok: false, unresolved: unresolved.length > 0 ? unresolved : [depDate] }
+  }
+  return { ok: true, url: `https://flights.ctrip.com/online/list/oneway-${fromCode}-${toCode}?depdate=${depDate}` }
+}
+
+/** networkHints:响应 URL 命中即视为搜索回包(对 UI 改版免疫,只怕接口改版) */
+export const NETWORK_HINTS = [/search\/api\/search\/batchSearch/]
+
+/**
+ * 登录态检测(用户自己的账号,不是匿名实例——founder 2026-08-28 纠偏):
+ * 任一登录票据 cookie 存在即视为已登录;名单基于公开常识,首个真登录后校准(D-13)。
+ */
+export const LOGIN_COOKIE_NAMES = ['cticket', 'uid', 'uname', 'passport']
+export const SITE_DOMAIN = '.ctrip.com'
+
+export interface SessionFlightOption {
+  flightNo: string
+  airline: string
+  depDateTime: string
+  arrDateTime: string
+  depAirport: string
+  arrAirport: string
+  durationMin: number
+  price: number
+  aircraft?: string
+}
+
+interface RawBatch {
+  status?: number
+  data?: {
+    flightItineraryList?: Array<{
+      flightSegments?: Array<{
+        airlineName?: string
+        duration?: number
+        flightList?: Array<{
+          flightNo?: string
+          departureAirportName?: string
+          arrivalAirportName?: string
+          departureDateTime?: string
+          arrivalDateTime?: string
+          aircraftName?: string
+        }>
+      }>
+      priceList?: Array<{ adultPrice?: number }>
+    }>
+  }
+}
+
+/** 解析 batchSearch 响应(纯函数,fixture 测试锚点);malformed 一律返空,不抛错 */
+export function parseBatchSearch(body: string): SessionFlightOption[] {
+  let raw: RawBatch
+  try {
+    raw = JSON.parse(body) as RawBatch
+  } catch {
+    return []
+  }
+  const out: SessionFlightOption[] = []
+  for (const it of raw.data?.flightItineraryList ?? []) {
+    const seg = it.flightSegments?.[0]
+    const fl = seg?.flightList?.[0]
+    if (!fl?.flightNo || !fl.departureDateTime) continue
+    const prices = (it.priceList ?? []).map((p) => Number(p.adultPrice ?? 0)).filter((n) => n > 0)
+    out.push({
+      flightNo: fl.flightNo,
+      airline: seg?.airlineName ?? '',
+      depDateTime: fl.departureDateTime ?? '',
+      arrDateTime: fl.arrivalDateTime ?? '',
+      depAirport: fl.departureAirportName ?? '',
+      arrAirport: fl.arrivalAirportName ?? '',
+      durationMin: Number(seg?.duration ?? 0) || 0,
+      price: prices.length > 0 ? Math.min(...prices) : 0,
+      aircraft: fl.aircraftName,
+    })
+  }
+  return out
+}