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

package/ts/capabilities/agent-reach.ts

@@ -77,7 +77,7 @@ export async function reach(q: { channel: string; method: string; args?: string[
   }
   const py = venvPython()
   if (!existsSync(py)) {
-    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs: 0, setup: 'gotry .venv 缺 python — 见 docs/tokens.md(agent-reach 安装)' }
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs: 0, setup: 'gotry .venv 缺 python——可选依赖未装配。补装:终端跑 npx gotry doctor --fix,或让用户看体检报告 npx gotry doctor' }
   }
   const args = Array.isArray(q.args) ? q.args : (q.args ? q.args.split(/\s+/).filter(Boolean) : [])
   const r = await run(py, [bridgeScript(), q.channel, q.method, ...args], q.timeoutMs ?? 30_000)
@@ -89,14 +89,14 @@ export async function reach(q: { channel: string; method: string; args?: string[
   } catch { /* 走下面的兜底 */ }
 
   if (r.err?.includes('ENOENT')) {
-    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv/bin/python 不可执行(装 agent-reach: 见 docs/tokens.md)' }
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv/bin/python 不可执行——补装:终端跑 npx gotry doctor --fix' }
   }
   if (parsed.ok === true) {
     return { ...base, ok: true, verdict: 'found', evidence: evidence('found'), latencyMs, data: parsed.data }
   }
   // 上游 agent_reach 包未装(bridge 自己的 exit 3 输出)
   if (parsed.error?.includes('agent_reach 未安装')) {
-    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv 缺 agent-reach(pip install agent-reach,见 docs/tokens.md)' }
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv 缺 agent-reach 包——补装:终端跑 npx gotry doctor --fix' }
   }
   // 未知渠道/方法:自描述,附上游清单(不拦 LLM,让它看清单自纠)
   if (r.code === 2) {
@@ -144,7 +144,7 @@ export async function reachStatus(timeoutMs = 90_000): Promise<ReachStatus> {
   const started = Date.now()
   const bin = resolve(repoRoot(), '.venv/bin/agent-reach')
   if (!existsSync(bin)) {
-    return { ok: false, via: 'not-installed', evidence: `[agent-reach:doctor@not-installed@${ts()}]`, latencyMs: 0, output: 'pip install agent-reach 于 .venv(见 docs/tokens.md)' }
+    return { ok: false, via: 'not-installed', evidence: `[agent-reach:doctor@not-installed@${ts()}]`, latencyMs: 0, output: 'Agent Reach 未装配(.venv 缺失)——可选依赖,补装:终端跑 npx gotry doctor --fix;或让助手调 gotry_doctor 看整体体检报告' }
   }
   const r = await run(bin, ['doctor'], timeoutMs)
   const output = (r.stdout || r.stderr).trim()

package/ts/capabilities/flyai.ts

@@ -1,5 +1,5 @@
 /**
- * FlyAI 官方通道能力层(飞猪开放平台,data-sources.md §8 / RFC user-session-data-rfc.md P0):
+ * FlyAI 官方通道能力层(飞猪开放平台,data-sources.md §8 / RFC docs/rfc/user-session-data-rfc.md P0):
  *
  * 链路(同构 anything.ts 的 CLI spawn 模式):
  *   gotry capabilities/flyai.ts
@@ -11,7 +11,10 @@
  *   - 只读:8 工具全只读,交易经 jumpUrl/detailUrl 由人完成(与 WriteGate 哲学同构);
  *   - 永不抛错:网络/超时/解析失败一律降级返回 verdict='error';
  *   - 证据链:成功 [实时API:flyai@ts];失败 [实时API:flyai@error@ts];
- *   - 无 key 可用;FLYAI_API_KEY 为可选增强(env 透传)。
+ *   - 匿名试用额度可用但共享易达限(2026-09-02 迪拜 session:429 Trial limit reached
+ *     被当通用 error,LLM 跨轮盲重试 4 次)——达限归类 verdict='needs-setup' +
+ *     setup 指引(申请正式 key 配 FLYAI_API_KEY),工具层据此阻断盲目重试。
+ *     FLYAI_API_KEY 已配时 env 透传,不再走试用额度。
  */
 
 import { spawn } from 'node:child_process'
@@ -86,11 +89,14 @@ export interface FlyaiResult {
   via: 'flyai' | 'flyai-error'
   evidence: string
   latencyMs: number
-  verdict: 'hit' | 'miss' | 'error'
+  /** needs-setup = 配置问题(试用额度达限/需正式 key),不是检索失败——工具层应阻断盲目重试 */
+  verdict: 'hit' | 'miss' | 'error' | 'needs-setup'
   kind: FlyaiKind
   options?: FlyaiOption[]
   hotels?: FlyaiHotelOption[]
   error?: string
+  /** 上游指引原话/补配指引(仅 needs-setup 时) */
+  setup?: string
 }
 
 interface RawItem {
@@ -245,6 +251,18 @@ export async function flyaiSearch(q: FlyaiQuery): Promise<FlyaiResult> {
   })
   const latencyMs = Date.now() - started
   if (r.error || r.code !== 0) {
+    // 试用额度达限(2026-09-02 迪拜 session 实况:exit 1 + MCP HTTP 429 "Trial limit
+    // reached")是配置问题不是瞬时故障——归 needs-setup 带补配指引,让工具层阻断
+    // LLM 拿同一把 429 跨轮盲重试;正式 key 经 FLYAI_API_KEY 配入后此路径不再触发。
+    const upstream = `${r.stderr}\n${r.stdout}`
+    if (/Trial limit reached|HTTP\s*429|\b429\b/.test(upstream)) {
+      return {
+        ...base, latencyMs, ok: false, via: 'flyai-error', verdict: 'needs-setup',
+        evidence: `[实时API:flyai@error@${ts}] trial quota exhausted`,
+        error: `FlyAI 匿名试用额度已用尽(上游 429):${upstream.replace(/\s+/g, ' ').slice(0, 160)}`,
+        setup: 'FlyAI 试用额度达限——到 flyai.open.fliggy.com 控制台申请正式 API Key,配入环境变量 FLYAI_API_KEY 即恢复;本会话请勿重试 gotry_flyai_search,机/火/酒改走 gotry_session_search(账号会话)或 web 检索推进。',
+      }
+    }
     return { ...base, latencyMs, ok: false, via: 'flyai-error', verdict: 'error', evidence: `[实时API:flyai@error@${ts}] ${r.error ?? `exit ${r.code}`}`, error: r.error ?? r.stderr.replace(/\s+/g, ' ').slice(0, 200) }
   }
   let items: RawItem[]

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

@@ -1,5 +1,5 @@
 /**
- * action-cache 本地自愈层(RFC user-session-data-rfc.md §3.2 / §2.3;Stagehand 云端缓存的本地化):
+ * action-cache 本地自愈层(RFC docs/rfc/user-session-data-rfc.md §3.2 / §2.3;Stagehand 云端缓存的本地化):
  *
  * 目的:会话检索的查询模式高度重复(同站点同类型搜索),首跑用 LLM/规则定位,后续走
  * 缓存的确定性载荷零成本重放;站点改版 → DOM 指纹失配 → miss → 重新定位并回写。

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

@@ -0,0 +1,238 @@
+/**
+ * 携程酒店站点适配器(2026-09-03 迪拜 session 复盘:账号会话面此前只有机票,
+ * 用户要「携程找酒店」时被迫撞 flyai 429 与打码 web 读页;会话面酒店从
+ * 「备份」实装为通道之一,rfc §2.2 同款只读纪律)。
+ *
+ *   - entry:https://hotels.ctrip.com/hotels/list?city=<id>&checkin=&checkout=&adult=N
+ *   - networkHints:酒店检索 XHR 的 URL 形态(接口名公开资料多版并存,**首个真会话
+ *     后校准**——D-13 同款边界);URL hint 未命中时由 content-main 的**形状嗅探**
+ *     兜底(响应 JSON 含酒店清单签名即转发),对接口改名免疫
+ *   - 解析:走形(walk)JSON 找「名字 + 价格」签名的条目数组,归一化最小字段;
+ *     页面/接口 JSON 是不可信输入(RFC §3.5)——本层只归形状,语义判定在工具层
+ *
+ * 只读:适配器不含任何提交/预订语义;URL 直开即零 DOM 交互;ReadGuard 对酒店
+ * 页面照常生效(下单/支付面 URL 仍被物理拦截)。
+ */
+
+/** 城市码表(**实测校准 2026-09-03**:每条 id 均经 hotels.ctrip.com list 页
+ * <title> 验证——探测法曾纠出 104=平遥县(传猜成都)等 5 处错猜,表内只收
+ * 验证过的 id;词表外 unresolved 逐字保留,调用方可显式传 cityId 覆盖) */
+const HOTEL_CITY_CODES: Record<string, string> = {
+  上海: '2', 北京: '1', 广州: '32', 深圳: '30', 成都: '28',
+  杭州: '17', 南京: '12', 苏州: '14', 无锡: '13', 扬州: '15', 镇江: '16',
+  青岛: '7', 厦门: '25', 珠海: '31', 三亚: '43', 海口: '42',
+  桂林: '33', 昆明: '34', 大理: '36', 丽江: '37', 西双版纳: '35',
+  贵阳: '38', 拉萨: '41', 乌鲁木齐: '39', 太原: '105', 长春: '158', 南通: '82',
+  敦煌: '11', 舟山: '19', 张家界: '27', 黄山市: '23', 九江: '24', 武夷山: '26',
+  迪拜: '220',
+}
+
+export interface AdapterEntry {
+  ok: boolean
+  url?: string
+  /** 词表外城市逐字保留(调用方提示:web 搜携程酒店 list 页取 city id 后带 cityId 重试) */
+  unresolved?: string[]
+}
+
+export interface HotelEntryQuery {
+  /** 目的地(中文);词表外须配 cityId */
+  to: string
+  /** 显式城市 id(携程/trip.com 酒店 list 页 URL 的 city= 数字;覆盖码表) */
+  cityId?: number | string
+  /** YYYY-MM-DD */
+  checkIn?: string
+  /** YYYY-MM-DD(与 checkIn 成对) */
+  checkOut?: string
+  adults?: number
+}
+
+export function buildHotelEntryUrl(q: HotelEntryQuery): AdapterEntry {
+  const unresolved: string[] = []
+  const cityId = String(q.cityId ?? '').trim() || HOTEL_CITY_CODES[q.to.trim()]
+  if (!cityId) unresolved.push(q.to)
+  if (unresolved.length > 0) {
+    return { ok: false, unresolved }
+  }
+  const params = new URLSearchParams({ city: cityId })
+  if (q.checkIn) params.set('checkin', q.checkIn)
+  if (q.checkOut) params.set('checkout', q.checkOut)
+  if (q.adults && q.adults > 0) params.set('adult', String(q.adults))
+  return { ok: true, url: `https://hotels.ctrip.com/hotels/list?${params.toString()}` }
+}
+
+/** networkHints:酒店检索 XHR 的 URL 形态(restapi/soa2/34951/fetchHotelList
+ * 为 2026-09-03 自 list 页一方确认的现行接口;其余为多版并存口径;命中即读) */
+export const HOTEL_NETWORK_HINTS = [
+  /hotels\.ctrip\.com\/(hotels\/api|domestic\/pc\/api)/i,
+  /GetHotelListBySOA|GetHotelListByCity|HotelSearch|hotelsearch/i,
+  /restapi\/soa2\/\d+\/fetchHotelList/i,
+]
+
+/** 形状嗅探签名:URL hint 未命中时的兜底(对接口改名免疫);大小上限由调用方先把关 */
+export function looksLikeHotelListBody(body: string): boolean {
+  if (!body || body.length > 2_000_000) return false
+  return /"hotelList"|"hotelMatchInfos"|"hotelName"/.test(body)
+}
+
+/** 酒店 page 域(content_scripts 注入面与 background 白名单的对账源) */
+export const HOTEL_SITE_HOST = 'hotels.ctrip.com'
+
+export interface SessionHotelOption {
+  /** 酒店名 */
+  name: string
+  /** 数字价(数值不可得时为 0;真实价以 jumpUrl 落地页为准) */
+  price: number
+  /** 价格原串(打码/区间等不可数值化的形态原样保留) */
+  priceRaw?: string
+  star?: number
+  /** 点评分(上游形态有数字有字符串,原样归一为字符串缺省) */
+  score?: string
+  address?: string
+  hotelId?: string
+  /** 酒店详情页跳转(由人完成预订;gotry 不碰) */
+  jumpUrl?: string
+}
+
+interface WalkCandidate {
+  name: string
+  price?: number
+  priceRaw?: string
+  star?: number
+  score?: string
+  address?: string
+  hotelId?: string
+}
+
+/** 条目签名:像不像一家酒店(名字类字段必有 + 价格类字段至少其一) */
+function hotelSignature(o: Record<string, unknown>): WalkCandidate | null {
+  const name = (o.hotelName ?? o.name ?? o.hotelNameEn) as unknown
+  if (typeof name !== 'string' || !name.trim()) return null
+  let price: number | undefined
+  let priceRaw: string | undefined
+  // 顶层扁平价(数字/字符串直给;字符串价是打码/区间形态,原样保留不数值化)
+  if (typeof o.price === 'number' && o.price > 0) price = o.price
+  else if (typeof o.price === 'string' && o.price.trim()) priceRaw = o.price.trim()
+  const probe = (v: unknown, seen = new Set<unknown>()): void => {
+    if (v == null || typeof v !== 'object') return
+    if (seen.has(v)) return
+    seen.add(v)
+    for (const [k, child] of Object.entries(v as Record<string, unknown>)) {
+      if (/^(avgPrice|totalPrice|price|amount|total|startPrice)$/i.test(k) && typeof child === 'number' && child > 0 && price === undefined) price = child
+      else if (/^(price|priceDisplay|amountText)$/i.test(k) && typeof child === 'string' && child.trim() && priceRaw === undefined) priceRaw = child.trim()
+      else probe(child, seen)
+    }
+  }
+  probe(o.priceInfo)
+  const flatPrice = o.totalPrice ?? o.avgPrice ?? o.minPrice
+  if (typeof flatPrice === 'number' && flatPrice > 0 && price === undefined) price = flatPrice
+  const flatRaw = o.priceText ?? o.priceDisplay
+  if (typeof flatRaw === 'string' && flatRaw.trim() && priceRaw === undefined) priceRaw = flatRaw.trim()
+  if (price === undefined && priceRaw === undefined) return null
+  const starRaw = o.star ?? o.level ?? o.hotelStar
+  const star = typeof starRaw === 'number' && starRaw > 0 ? starRaw : Number.isFinite(Number(starRaw)) && Number(starRaw) > 0 ? Number(starRaw) : undefined
+  const scoreRaw = o.score ?? o.commentScore ?? o.reviewScore
+  const score = scoreRaw == null ? undefined : String(scoreRaw)
+  const pos = o.position as Record<string, unknown> | undefined
+  const address = (typeof pos?.address === 'string' ? pos.address : undefined) ?? (typeof o.address === 'string' ? o.address : undefined)
+  const hotelId = (typeof o.hotelId === 'number' || typeof o.hotelId === 'string' ? String(o.hotelId) : undefined)
+    ?? (typeof o.hotelIdStr === 'string' ? o.hotelIdStr : undefined)
+  return { name: name.trim(), price, priceRaw, star, score, address, hotelId }
+}
+
+/** 结构化候选:携程现行 list 形态(**一方校准 2026-09-03**,取自 list 页官方
+ * 前端代码反查 + SSR initListData 实测):
+ *   - 条目 = hotelList[].hotelInfo{summary{hotelId,nameInfo{name,names[]},hotelStar{star},positionInfo},commentInfo{commentScore}}
+ *   - 价格 = roomInfo[].priceInfo.price(多房型取最低;页面 room_price 即读此);
+ *     priceToken 在而无 price = 加密价(fetchHotelListPrices 页面内存解密),
+ *     嗅探面拿不到明文——如实不报价,summary 指引到 jumpUrl 落地页
+ *   - displayPrice(如 "¥468")作 priceRaw 兜底;通用 price/amount 子树探测殿后
+ *   (直连复现 fetchHotelList 被 hotel-spider-defence 反爬 404——「让站点自己
+ *   发请求」正是会话桥的设计原因;官方前端为公开静态资产,路径自其中反查) */
+function ctripStructuredCandidate(item: Record<string, unknown>): WalkCandidate | null {
+  const info = item.hotelInfo as Record<string, unknown> | undefined
+  const summary = (info?.summary ?? item) as Record<string, unknown>
+  const nameInfo = summary.nameInfo as Record<string, unknown> | undefined
+  const names = nameInfo?.names
+  const nameRaw = nameInfo?.name ?? (Array.isArray(names) && names.length > 0 ? names[0] : undefined) ?? summary.hotelName ?? summary.name
+  if (typeof nameRaw !== 'string' || !nameRaw.trim()) return null
+  // 价格:roomInfo[].priceInfo 官方路径优先(数值 price 取 min;displayPrice/字符串价作 priceRaw)
+  let price: number | undefined
+  let priceRaw: string | undefined
+  let encrypted = false
+  const rooms = info?.roomInfo ?? item.roomInfo
+  if (Array.isArray(rooms)) {
+    for (const room of rooms) {
+      if (room == null || typeof room !== 'object') continue
+      const pi = (room as Record<string, unknown>).priceInfo as Record<string, unknown> | undefined
+      if (!pi) continue
+      if (typeof pi.price === 'number' && pi.price > 0) price = price === undefined ? pi.price : Math.min(price, pi.price)
+      if (typeof pi.price === 'string' && pi.price.trim() && !priceRaw) priceRaw = pi.price.trim()
+      if (typeof pi.displayPrice === 'string' && pi.displayPrice.trim() && !priceRaw) priceRaw = pi.displayPrice.trim()
+      if (pi.priceToken != null && pi.price === undefined) encrypted = true
+    }
+  }
+  // 兜底:条目子树 price/amount 探测(SSR 形态 productInfo.priceInfo.price 等)
+  if (price === undefined && !priceRaw) {
+    const priceProbe = (v: unknown, depth: number, seen: Set<unknown>): void => {
+      if (price !== undefined || depth > 6 || v == null || typeof v !== 'object' || seen.has(v)) return
+      seen.add(v)
+      for (const [k, child] of Object.entries(v as Record<string, unknown>)) {
+        if (/^(price|avgPrice|totalPrice|minPrice|amount)$/i.test(k) && typeof child === 'number' && child > 0) { price = child; return }
+        if (/^(price|displayPrice|amountText)$/i.test(k) && typeof child === 'string' && child.trim()) { priceRaw = priceRaw ?? child.trim(); continue }
+        priceProbe(child, depth + 1, seen)
+      }
+    }
+    priceProbe(item, 0, new Set())
+  }
+  // 加密价(priceToken 在而无明文 price):条目保留,价如实为 0——不伪造任何价
+  if (price === undefined && !priceRaw && !encrypted) return null
+  const starOf = summary.hotelStar as Record<string, unknown> | undefined
+  const starRaw = starOf?.star ?? summary.star
+  const star = typeof starRaw === 'number' && starRaw > 0 ? starRaw : undefined
+  const scoreRaw = ((info?.commentInfo ?? summary.commentInfo) as Record<string, unknown> | undefined)?.commentScore
+  const pos = summary.positionInfo as Record<string, unknown> | undefined
+  const address = (typeof pos?.address === 'string' ? pos.address : undefined) ?? (typeof summary.address === 'string' ? summary.address : undefined)
+  const hotelId = summary.hotelId != null ? String(summary.hotelId) : undefined
+  return { name: nameRaw.trim(), price, priceRaw, star, score: scoreRaw == null ? undefined : String(scoreRaw), address, hotelId }
+}
+
+/** 走形:深找第一个酒店签名数组(纯函数,fixture 测试锚点);malformed 一律返空,不抛错 */
+export function parseCtripHotelList(body: string, opts: { maxItems?: number } = {}): SessionHotelOption[] {
+  let raw: unknown
+  try {
+    raw = JSON.parse(body)
+  } catch {
+    return []
+  }
+  const out: SessionHotelOption[] = []
+  const maxItems = opts.maxItems ?? 20
+  const walk = (node: unknown, depth: number, seen: Set<unknown>): void => {
+    if (out.length >= maxItems || depth > 12 || node == null || typeof node !== 'object' || seen.has(node)) return
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        if (out.length >= maxItems) return
+        if (item == null || typeof item !== 'object' || Array.isArray(item)) continue
+        const cand = hotelSignature(item as Record<string, unknown>) ?? ctripStructuredCandidate(item as Record<string, unknown>)
+        if (!cand) continue
+        out.push({
+          name: cand.name,
+          price: cand.price ?? 0,
+          priceRaw: cand.priceRaw,
+          star: cand.star,
+          score: cand.score,
+          address: cand.address,
+          hotelId: cand.hotelId,
+          jumpUrl: cand.hotelId ? `https://hotels.ctrip.com/hotel/${cand.hotelId}` : undefined,
+        })
+      }
+      return
+    }
+    seen.add(node)
+    for (const child of Object.values(node as Record<string, unknown>)) {
+      walk(child, depth + 1, seen)
+      if (out.length >= maxItems) return
+    }
+  }
+  walk(raw, 0, new Set())
+  return out
+}

package/ts/capabilities/session/adapters/rail-12306.ts

@@ -0,0 +1,293 @@
+/**
+ * 12306 火车站点适配器(2026-09-03,继 ctrip-hotel 后会话面第三通道):
+ *   - entry:https://kyfw.12306.cn/otn/leftTicket/init?linktypeid=dc&fs=<城市名,电报码>&ts=<...>&date=YYYY-MM-DD&flag=N,N,Y
+ *     (电报码表官方站表全量校准 2026-09-03,129 城;曾纠出南宁 NIZ→NNZ 错码)
+ *   - networkHints:kyfw leftTicket/query(负载均衡变体 queryG/queryZ/queryA 等全部命中)
+ *   - 解析:leftTicket/query 返回 data.result[] 管道行(12306 经典 | 拼接格式)。
+ *     **第一方校准(2026-09-03)**:字段索引与站名映射(data.map[电报码])逐一
+ *     取自官方前端 queryLeftTicket_end_js.js 的 cN(result,map) 转换函数——旧版
+ *     公开常识索引与官方现行映射不符(站名/座位桶全错),真会话前即纠;行级
+ *     签名校验(车次码/时刻形态)继续兜住未来漂移:失配整行跳过,fail-visible
+ *
+ * 与机/酒通道的两点刻意差异:
+ *   - 无登录闸:12306 余票查询是公开面(登录只关系下单),无账号数据过手;
+ *     扩展照样只读被动嗅探(零写行为),证据链标注「公开查询面」
+ *   - 列表接口不含票价:如实只呈现 车次/时刻/历时/余票,票价以 12306 落地页为准
+ */
+
+/** 城市电报码表(**官方口径校准 2026-09-03**:全部条目逐一核对自
+ * kyfw.12306.cn/otn/resources/js/framework/station_name.js 官方全量站表
+ * ——曾借此抓出南宁 NIZ→NNZ 错码;代表站规则=城市同名站,fs/ts 用城市码
+ * 服务端扩到市内全部站。词表外 unresolved 逐字保留,调用方可显式传电报码
+ * 覆盖——kyfw 查询页 URL 里的 fs=城市,XXX 三位码;核对快照见
+ * data/stations-12306-verify.json) */
+export const STATION_TELECODES: Record<string, string> = {
+  "三亚": 'SEQ',
+  "上海": 'SHH',
+  "上饶": 'SRG',
+  "东莞": 'RTQ',
+  "中卫": 'ZWJ',
+  "中山": 'ZSQ',
+  "丽江": 'LHM',
+  "乌鲁木齐": 'WAR',
+  "乐山": 'IVW',
+  "九江": 'JJG',
+  "伊宁": 'YMR',
+  "佛山": 'FSQ',
+  "保山": 'BAM',
+  "六盘水": 'UMW',
+  "兰州": 'LZJ',
+  "包头": 'BTC',
+  "北京": 'BJP',
+  "北海": 'BHZ',
+  "十堰": 'SNN',
+  "南京": 'NJH',
+  "南充": 'NCW',
+  "南宁": 'NNZ',
+  "南昌": 'NCG',
+  "南通": 'NUH',
+  "南阳": 'NFF',
+  "厦门": 'XMS',
+  "台州": 'TEU',
+  "合肥": 'HFH',
+  "吉林": 'JLL',
+  "吐鲁番": 'TFR',
+  "呼和浩特": 'HHC',
+  "咸阳": 'XYY',
+  "哈密": 'HMR',
+  "哈尔滨": 'HBB',
+  "喀什": 'KSR',
+  "嘉兴": 'JXH',
+  "嘉峪关": 'JGJ',
+  "大同": 'DTV',
+  "大庆": 'DZX',
+  "大理": 'DKM',
+  "大连": 'DLT',
+  "天水": 'TSJ',
+  "天津": 'TJP',
+  "太原": 'TYV',
+  "宁波": 'NGH',
+  "安顺": 'ASW',
+  "宜宾": 'YKE',
+  "宜昌": 'YCN',
+  "宝鸡": 'BJY',
+  "岳阳": 'YYQ',
+  "常州": 'CZH',
+  "常德": 'VGQ',
+  "广州": 'GZQ',
+  "库尔勒": 'KLR',
+  "延安": 'YWY',
+  "开封": 'KFF',
+  "张掖": 'ZYJ',
+  "徐州": 'XCH',
+  "德阳": 'DYW',
+  "惠州": 'HCQ',
+  "成都": 'CDW',
+  "扬州": 'YLH',
+  "承德": 'CDP',
+  "抚顺": 'FET',
+  "拉萨": 'LSO',
+  "揭阳": 'JYA',
+  "新乡": 'XXF',
+  "无锡": 'WGH',
+  "日喀则": 'RKO',
+  "昆明": 'KMM',
+  "普洱": 'PEM',
+  "景德镇": 'JCG',
+  "曲靖": 'QJM',
+  "杭州": 'HZH',
+  "林芝": 'LZO',
+  "柳州": 'LZZ',
+  "株洲": 'ZZQ',
+  "格尔木": 'GRO',
+  "桂林": 'GLZ',
+  "梧州": 'WZZ',
+  "武汉": 'WHN',
+  "汉中": 'HOY',
+  "汕头": 'OTQ',
+  "沈阳": 'SYT',
+  "泉州": 'QYS',
+  "泸州": 'LUE',
+  "洛阳": 'LYF',
+  "济南": 'JNK',
+  "深圳": 'SZQ',
+  "温州": 'RZH',
+  "湛江": 'ZJZ',
+  "漳州": 'ZUS',
+  "潮州": 'CKQ',
+  "牡丹江": 'MDB',
+  "珠海": 'ZHQ',
+  "盐城": 'AFH',
+  "石家庄": 'SJP',
+  "福州": 'FZS',
+  "秦皇岛": 'QTP',
+  "绍兴": 'SOH',
+  "绵阳": 'MYW',
+  "芜湖": 'WHH',
+  "苏州": 'SZH',
+  "茂名": 'MDQ',
+  "莆田": 'PTS',
+  "衡阳": 'HYQ',
+  "襄阳": 'XFN',
+  "西宁": 'XNO',
+  "西安": 'XAY',
+  "西昌": 'ECW',
+  "贵阳": 'GIW',
+  "赣州": 'GZG',
+  "达州": 'RXW',
+  "遵义": 'ZYE',
+  "郑州": 'ZZF',
+  "重庆": 'CUW',
+  "金华": 'JBH',
+  "银川": 'YIJ',
+  "镇江": 'ZJH',
+  "长春": 'CCT',
+  "长沙": 'CSQ',
+  "阜阳": 'FYH',
+  "青岛": 'QDK',
+  "鞍山": 'AST',
+  "韶关": 'SNQ',
+  "香格里拉": 'EUM',
+  "香港": 'XJA',
+  "齐齐哈尔": 'QHX',
+  "龙岩": 'LYS',
+}
+
+export interface TrainEntryQuery {
+  from: string
+  to: string
+  /** YYYY-MM-DD */
+  date: string
+  /** 显式城市电报码(覆盖码表;kyfw 查询页 URL fs=城市,XXX 的三位码) */
+  fromStationTelecode?: string
+  toStationTelecode?: string
+}
+
+export interface AdapterEntry {
+  ok: boolean
+  url?: string
+  unresolved?: string[]
+}
+
+export function buildTrainEntryUrl(q: TrainEntryQuery): AdapterEntry {
+  const unresolved: string[] = []
+  const fromTc = (q.fromStationTelecode ?? '').trim().toUpperCase() || STATION_TELECODES[q.from.trim()]
+  const toTc = (q.toStationTelecode ?? '').trim().toUpperCase() || STATION_TELECODES[q.to.trim()]
+  if (!fromTc) unresolved.push(q.from)
+  if (!toTc) unresolved.push(q.to)
+  if (unresolved.length > 0 || !/^\d{4}-\d{2}-\d{2}$/.test(q.date)) {
+    return { ok: false, unresolved: unresolved.length > 0 ? unresolved : [q.date] }
+  }
+  const fs = encodeURIComponent(`${q.from.trim()},${fromTc}`)
+  const ts = encodeURIComponent(`${q.to.trim()},${toTc}`)
+  return { ok: true, url: `https://kyfw.12306.cn/otn/leftTicket/init?linktypeid=dc&fs=${fs}&ts=${ts}&date=${q.date}&flag=N,N,Y` }
+}
+
+/** networkHints:余票查询 XHR(queryG/Z/A/U 等负载均衡变体全命中) */
+export const TRAIN_NETWORK_HINTS = [/leftTicket\/query/i]
+
+/** 12306 页域(content_scripts 注入面与 background 白名单的对账源) */
+export const TRAIN_SITE_HOST = 'kyfw.12306.cn'
+
+export interface SessionTrainOption {
+  /** 车次(G1375 / K79 等) */
+  trainCode: string
+  fromStation: string
+  toStation: string
+  /** 出发/到达时刻(HH:MM;跨日由到达时刻本身表达,官方 DTO 无隔日字段) */
+  depTime: string
+  arrTime: string
+  /** 历时(分钟) */
+  durationMin: number
+  /** Y=可预订 / N=不可 / 其他上游原话 */
+  canWebBuy: string
+  /** 余票分桶(第一方校准索引,见 SEAT_BUCKETS;值原样:数字 / 有 / 无 / --) */
+  seats: Record<string, string>
+  /** 查询落地页(由人选车完成预订;gotry 不碰) */
+  jumpUrl?: string
+}
+
+/** 座位桶索引表(**第一方校准 2026-09-03**:逐字段取自 12306 官方前端
+ * queryLeftTicket_end_js.js 的 cN(result,map) 转换函数——旧版公开常识索引
+ * (19-28 段)与官方现行映射不符,首查前即纠);label=页面席别口径,未知席别
+ * 保留上游字段 id 原样 */
+const SEAT_BUCKETS: Array<{ index: number; field: string; label: string }> = [
+  { index: 20, field: 'gg_num', label: '其他(通勤)' },
+  { index: 21, field: 'gr_num', label: '高级软卧' },
+  { index: 22, field: 'qt_num', label: '其他' },
+  { index: 23, field: 'rw_num', label: '软卧(一等卧)' },
+  { index: 24, field: 'rz_num', label: '软座' },
+  { index: 25, field: 'tz_num', label: '特等座' },
+  { index: 26, field: 'wz_num', label: '无座' },
+  { index: 27, field: 'yb_num', label: 'yp_b(上游席别)' },
+  { index: 28, field: 'yw_num', label: '硬卧(二等卧)' },
+  { index: 29, field: 'yz_num', label: '硬座' },
+  { index: 30, field: 'ze_num', label: '二等座' },
+  { index: 31, field: 'zy_num', label: '一等座' },
+  { index: 32, field: 'swz_num', label: '商务座' },
+  { index: 33, field: 'srrb_num', label: '动卧' },
+]
+
+const TRAIN_CODE_RE = /^[GDCZTKYLSF]\d{1,5}[A-Z]?$/i
+const HHMM_RE = /^\d{2}:\d{2}$/
+
+/** 历时 "07:52" → 分钟 */
+function lishiToMin(s: string | undefined): number {
+  const m = /^(\d{1,3}):(\d{2})$/.exec((s ?? '').trim())
+  if (!m) return 0
+  return Number(m[1]) * 60 + Number(m[2])
+}
+
+/** 行级签名:车次码形态 + 时刻形态不符即整行跳过(索引漂移 fail-visible,不造数) */
+function rowToOption(row: string, stationMap: Record<string, string> | undefined, entryUrl: string): SessionTrainOption | null {
+  const f = row.split('|')
+  if (f.length < 34) return null
+  const trainCode = (f[3] ?? '').trim()
+  const depTime = (f[8] ?? '').trim()
+  const arrTime = (f[9] ?? '').trim()
+  if (!TRAIN_CODE_RE.test(trainCode) || !HHMM_RE.test(depTime) || !HHMM_RE.test(arrTime)) return null
+  // 官方 cN 口径:站名 = data.map[电报码](map 缺失/缺键时退电报码原样,不猜名)
+  const fromStation = stationMap?.[f[6] ?? ''] ?? (f[6] ?? '')
+  const toStation = stationMap?.[f[7] ?? ''] ?? (f[7] ?? '')
+  const seats: Record<string, string> = {}
+  for (const b of SEAT_BUCKETS) {
+    const v = (f[b.index] ?? '').trim()
+    if (v && v !== '--') seats[b.label] = v
+  }
+  return {
+    trainCode,
+    fromStation,
+    toStation,
+    depTime,
+    arrTime,
+    durationMin: lishiToMin(f[10]),
+    canWebBuy: (f[11] ?? '').trim(),
+    seats,
+    jumpUrl: entryUrl,
+  }
+}
+
+/** 解析 leftTicket/query 响应(纯函数,fixture 测试锚点;字段索引与站名映射
+ * 全部对齐 12306 官方前端 cN(result,map)——见 SEAT_BUCKETS 注释);
+ * malformed 一律返空,不抛错 */
+export function parseLeftTicketQuery(body: string, entryUrl: string, opts: { maxItems?: number } = {}): SessionTrainOption[] {
+  let raw: { data?: { result?: unknown; map?: Record<string, string> } }
+  try {
+    raw = JSON.parse(body) as typeof raw
+  } catch {
+    return []
+  }
+  const rows = raw.data?.result
+  if (!Array.isArray(rows)) return []
+  const map = (raw.data?.map && typeof raw.data.map === 'object') ? raw.data.map : undefined
+  const out: SessionTrainOption[] = []
+  for (const r of rows) {
+    if (typeof r !== 'string') continue
+    const opt = rowToOption(r, map, entryUrl)
+    if (opt) {
+      out.push(opt)
+      if (out.length >= (opts.maxItems ?? 30)) break
+    }
+  }
+  return out
+}