@danceiny/gotry 0.0.1-rc.18 → 0.0.1-rc.20

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/anything.ts

@@ -3,10 +3,17 @@
  *
  * 链路(同构 hbcli.ts):
  *   gotry capabilities/anything.ts
- *     → spawn hbcli search anything [keywords...] --json <opts>
- *       → hotel-be /api/search/anything
+ *     → spawn hbcli --json search anything <kw> [opts]
+ *       → hotel-be /api/search/anything(httpdispatch 自动注册;httpdispatch 路由面)
  *         → search/service/geography.go func Anything (mixed 城市+酒店搜索)
  *
+ * wire 契约(2026-09-07 对齐上游源码;SearchItem = FuzzySearchItem + hotel):
+ *   req  { keyword, contentType?, context.destinationId?, minHotelCount? }
+ *   resp { candidates: [{ type: 'city'|'place'|'hotel',
+ *                         region?:  { id, name:{en,zh,ar}, coordinates:{centerLat,centerLng}, countryCode, … },
+ *                         place?:   { latlngCoordinator },
+ *                         matchScore?, hotel?: { id, name:{en,zh,ar}, star, latlngCoordinator:{google|gaode:{lat,lng} } } }] }
+ *
  * 三值语义:
  *   - hit:  命中候选(混合 city/hotel,maybe-coords)
  *   - miss: hbcli exit 0,但 candidates 为空(查无结果)
@@ -22,33 +29,36 @@
  */
 
 import { spawn } from 'node:child_process'
+import { hbcliBinCandidates } from './hbcli.ts'
 
 export interface AnythingQuery {
   /** 多词以空格 join,与 hbcli argument-parser 一致;前后 trim。空则报错(unless contentType 强限定) */
   keyword: string
   /** 'city' | 'hotel' | undefined(混合) */
   contentType?: 'city' | 'hotel'
-  /** 限定子区域 ID(可选) */
+  /** 限定子区域 ID(上游 SearchReq.context.destinationId) */
   parentDestinationId?: string | number
   /** 默认 12_000 ms */
   timeoutMs?: number
-  /** 显式 hbcli 路径(默认 'hbcli',从 $PATH 找) */
+  /** 显式 hbcli 路径(默认 'hbcli',从 $PATH 找;默认名自动回退 ~/.local/bin 等已知安装位) */
   hbcliBin?: string
 }
 
 export interface AnythingHit {
   type: 'city' | 'hotel' | 'place'
-  /** FuzzySearchItem name(or hotel name);fallback 为 region.Name */
+  /** i18n name 解析(zh 优先,产品中文优先;回退 en/ar) */
   name: string
-  /** score / 0..1(若返回) */
+  /** matchScore(文本相关度,越高越匹配) */
   score?: number
-  /** lat/lng(若 region 给出) */
+  /** lat/lng(region.center 或 hotel/place latlngCoordinator,若给出) */
   latitude?: number
   longitude?: number
-  /** city id(若有) */
+  /** city id(region.id;酒店候选为所属 destinationId) */
   destinationId?: string
   /** hotel id(若有) */
   hotelId?: string
+  /** 星级(酒店候选,若返回) */
+  star?: number
 }
 
 export interface AnythingResult {
@@ -63,16 +73,46 @@ export interface AnythingResult {
   error?: string
 }
 
+/** 上游 i18n.I18N {en,zh,ar};tolerant 读取(字段可能缺省,老字符串形态也兜住) */
+type I18N = { en?: string; zh?: string; ar?: string } | string | undefined
+
+function i18nText(v: I18N): string {
+  if (!v) return ''
+  if (typeof v === 'string') return v
+  return v.zh || v.en || v.ar || ''
+}
+
+/** hotel-be Latlng:{lat,lng};google/gaode 双源取先非零者 */
+function latlngOf(coord: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } } | undefined): { latitude?: number; longitude?: number } {
+  for (const src of [coord?.google, coord?.gaode]) {
+    const lat = typeof src?.lat === 'number' ? src.lat : undefined
+    const lng = typeof src?.lng === 'number' ? src.lng : undefined
+    if (lat !== undefined && lng !== undefined && (lat !== 0 || lng !== 0)) return { latitude: lat, longitude: lng }
+  }
+  return {}
+}
+
 interface RawSearchResp {
   candidates?: RawSearchItem[]
 }
+/** hotel-be SearchItem wire 形状(FuzzySearchItem + hotel,2026-09-07 对齐源码) */
 interface RawSearchItem {
   type?: string
-  name?: string
-  label?: string
-  region?: { id?: string; name?: string; latitude?: number; longitude?: number; typeScore?: number; name_en?: string; name_zh?: string }
-  hotel?: { id?: string; name?: string; latitude?: number; longitude?: number }
-  score?: number
+  matchScore?: number
+  region?: {
+    id?: string | number
+    name?: I18N
+    countryCode?: string
+    coordinates?: { centerLat?: number; centerLng?: number }
+  }
+  place?: { latlngCoordinator?: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } } }
+  hotel?: {
+    id?: string | number
+    name?: I18N
+    star?: number
+    destinationId?: string | number
+    latlngCoordinator?: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } }
+  }
 }
 
 function sh(cmd: string, args: string[], opts: { timeoutMs: number; env: NodeJS.ProcessEnv }) {
@@ -115,8 +155,20 @@ function sh(cmd: string, args: string[], opts: { timeoutMs: number; env: NodeJS.
   })
 }
 
-const upperFirst = (s: string): string => (s ? s[0]!.toUpperCase() + s.slice(1) : s)
-const lowerFirst = (s: string): string => (s ? s[0]!.toLowerCase() + s.slice(1) : s)
+/** --json 必须在子命令前(cli.ts 全局旗标预扫描只认子命令前位置;JSON 错误也走结构化 stderr) */
+function buildArgs(keyword: string, q: AnythingQuery): string[] {
+  const args = ['--json', 'search', 'anything', keyword]
+  if (q.contentType) args.push('--content-type', q.contentType)
+  if (q.parentDestinationId !== undefined) args.push('--destination-id', String(q.parentDestinationId))
+  return args
+}
+
+/** 旧版 CLI 无 search anything 子命令时的可行动升级指引(issue #195:裸 unknown command 读起来像工具坏了) */
+function upgradeHint(stderr: string): string | null {
+  return /unknown command/i.test(stderr)
+    ? 'hbcli 版本过旧(无 search anything 子命令)——请升级:hbcli update,或重跑 npx gotry setup'
+    : null
+}
 
 /** Anything 通用搜索 — 任何搜索失败走降级;不抛错 */
 export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult> {
@@ -131,27 +183,25 @@ export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult>
       error: 'keyword is required',
     }
   }
-  const bin = q.hbcliBin ?? 'hbcli'
-  const args = [bin, 'search', 'anything', kw]
-  if (q.contentType) args.push('--content-type', q.contentType)
-  if (q.parentDestinationId !== undefined) {
-    args.push('--parent-destination-id', String(q.parentDestinationId))
+  const args = buildArgs(kw, q)
+  // spawn 级失败(ENOENT)按已知安装位回退(hbcli.ts callHbcliJson 同款);其余失败无重试意义
+  const candidates = hbcliBinCandidates(q.hbcliBin ?? 'hbcli')
+  let r: { code: number; stdout: string; stderr: string; error?: string } = { code: -1, stdout: '', stderr: '' }
+  for (let i = 0; i < candidates.length; i++) {
+    r = await sh(candidates[i]!, args, { timeoutMs: q.timeoutMs ?? 12_000, env: process.env })
+    if (!(r.error && i < candidates.length - 1)) break
   }
-
-  const r = await sh(bin, args.slice(1), {
-    timeoutMs: q.timeoutMs ?? 12_000,
-    env: process.env,
-  })
   const latencyMs = Date.now() - started
 
   if (r.error || r.code !== 0) {
+    const raw = r.error ?? `${r.stderr.slice(0, 200)} (exit ${r.code})`
     return {
       ok: false,
       via: 'hbcli-anything-error',
-      evidence: `[实时API:hbcli-anything@error@${ts}] ${r.error ?? `exit ${r.code}`}`,
+      evidence: `[实时API:hbcli-anything@error@${ts}] ${raw}`,
       latencyMs,
       verdict: 'error',
-      error: r.error ?? `${r.stderr.slice(0, 200)} (exit ${r.code})`,
+      error: upgradeHint(r.stderr) ?? raw,
     }
   }
 
@@ -174,15 +224,19 @@ export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult>
   const hits: AnythingHit[] = rawItems.map((it) => {
     const region = it.region ?? {}
     const hotel = it.hotel ?? {}
-    const isHotel = it.type === 'hotel' || it.type === 'SupplierHotelList' || Boolean(hotel.id)
+    const isHotel = it.type === 'hotel' || Boolean(hotel.id)
+    const hotelCoords = latlngOf(hotel.latlngCoordinator)
+    const placeCoords = latlngOf(it.place?.latlngCoordinator)
+    const center = region.coordinates ?? {}
     return {
-      type: (isHotel ? 'hotel' : (it.type === 'place' || it.type === 'City' ? lowerFirst(it.type) : 'city')) as AnythingHit['type'],
-      name: it.name ?? region.name_en ?? region.name ?? hotel.name ?? '?',
-      score: it.score ?? region.typeScore,
-      latitude: hotel.latitude ?? region.latitude,
-      longitude: hotel.longitude ?? region.longitude,
-      destinationId: region.id,
-      hotelId: hotel.id,
+      type: (isHotel ? 'hotel' : (it.type === 'place' ? 'place' : 'city')) as AnythingHit['type'],
+      name: i18nText(hotel.name) || i18nText(region.name) || '?',
+      score: it.matchScore,
+      latitude: hotelCoords.latitude ?? placeCoords.latitude ?? (typeof center.centerLat === 'number' ? center.centerLat : undefined),
+      longitude: hotelCoords.longitude ?? placeCoords.longitude ?? (typeof center.centerLng === 'number' ? center.centerLng : undefined),
+      destinationId: hotel.destinationId !== undefined ? String(hotel.destinationId) : (region.id !== undefined ? String(region.id) : undefined),
+      hotelId: hotel.id !== undefined ? String(hotel.id) : undefined,
+      star: typeof hotel.star === 'number' && hotel.star > 0 ? hotel.star : undefined,
     }
   })
 
@@ -196,6 +250,3 @@ export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult>
     totalCandidates: rawItems.length,
   }
 }
-
-// noop exports to keep file shape consistent with hbcli.ts
-export const _ = { upperFirst }

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/hbcli.ts

@@ -142,19 +142,66 @@ export async function callHbcliJson(
   return last!
 }
 
+/** 上游 i18n 名称容错读取(zh 优先,中文优先产品口径;回退 en/ar) */
+function i18nName(v: { zh?: string; en?: string; ar?: string } | string | undefined): string {
+  if (!v) return ''
+  if (typeof v === 'string') return v
+  return v.zh || v.en || v.ar || ''
+}
+
+/**
+ * 实时 hotelList 响应 → 模型可读紧凑行(id/名称/星级/最低价)。
+ * issue #195:render 面只透 summary,若 summary 不含数据,模型只看到
+ * 「实时返回」四个字——工具调用等于白调。id 必须在行内,hotel-rates 的入参
+ * 就来自这里。上游 wire:HotelListResp{list:[Hotel{id,name:{en,zh},star,minPrice:{amount,currency}}]}。
+ */
+function hotelLines(result: unknown, max = 8): string {
+  const list = (result as { list?: unknown } | null)?.list
+  if (!Array.isArray(list) || list.length === 0) return ''
+  const lines: string[] = []
+  for (const item of list.slice(0, max)) {
+    const h = item as {
+      id?: string | number
+      name?: { zh?: string; en?: string; ar?: string }
+      star?: number
+      minPrice?: { amount?: number; currency?: string }
+    }
+    const name = i18nName(h.name) || `hotel ${h.id ?? '?'}`
+    const star = typeof h.star === 'number' && h.star > 0 ? ` ${h.star}★` : ''
+    const price = h.minPrice && typeof h.minPrice.amount === 'number'
+      ? ` 低至 ${h.minPrice.amount}${h.minPrice.currency ? ` ${h.minPrice.currency}` : ''}`
+      : ''
+    lines.push(`- id=${h.id ?? '?'} ${name}${star}${price}`)
+  }
+  if (list.length > max) lines.push(`…(共 ${list.length} 家,仅列前 ${max})`)
+  return lines.join('\n')
+}
+
 /** 高层语义化封装:酒店列表查询(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 跟进
+  // 旗标对齐上游 CLI(hotelbyte-com/hotelbyte-cli):--destination-name + --room-occupancies;
+  // hotel-list 支持日期旗标(--check-in/--check-out,上游帮助文档在册)——issue #195 教训:
+  // 「日期不传上游」会让实时价退化为当前窗口价,用户要下周五的房给的是今天的价。
   const hbArgs = ['search', 'hotel-list', '--json', '--page-size', '10']
   if (query.destination) hbArgs.push('--destination-name', query.destination)
+  if (query.checkIn) hbArgs.push('--check-in', query.checkIn)
+  if (query.checkOut) hbArgs.push('--check-out', query.checkOut)
   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,以当前窗口房价返回)' : ''}` }
+    // summary 即模型面(render 只透 summary):必须自带紧凑数据行 + 证据链,
+    // 否则模型只看到「实时返回」占位一句话(issue #195 实锤)。
+    const list = (live.result as { list?: unknown[] } | null)?.list
+    const n = Array.isArray(list) ? list.length : 0
+    const dateTag = query.checkIn
+      ? `入住 ${query.checkIn}${query.checkOut ? ` → 退房 ${query.checkOut}` : ''}`
+      : '未传日期(上游按当前窗口价)'
+    const lines = hotelLines(live.result)
+    const summary = `${query.destination}:hbcli 实时 ${n} 家(${dateTag})${lines ? `\n${lines}` : ''}\n${live.evidence}`
+    return { ...live, hotels: live.result, summary }
   }
   // 降级原因人话化(issue #24):hbcli 未安装时按 gotry setup 指引(npm 安装期已
   // 自动跑过官方脚本;PATH 未含 ~/.local/bin 时上方候选路径也已兜住),
@@ -176,7 +223,9 @@ export async function searchHotels(
         return {
           ...live,
           hotels: { stays: matched },
-          summary: `${query.destination}:hbcli 实时源不可用(${reason}),已降级到静态包(公开渠道估算,非实时),命中 ${matched.length} 个住宿块`,
+          // summary 即模型面:静态块内容(note/options/recommendation)直接内联,
+          // 模型不必再猜「命中 N 块」里有什么(issue #195)
+          summary: `${query.destination}:hbcli 实时源不可用(${reason}),已降级到静态包(公开渠道估算,非实时),命中 ${matched.length} 个住宿块:\n${JSON.stringify(matched).slice(0, 1600)}`,
         }
       }
       return {

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
+}