@danceiny/gotry 0.2.0-rc.30 → 0.2.0-rc.32

package/ts/capabilities/hbcli-config.ts

@@ -0,0 +1,128 @@
+/** Official hbcli credential-file contract; no credentials enter tool results. */
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { atomicWriteJson, sha256Hex } from './flyai-config.ts'
+import { hbcliBinCandidates } from './hbcli.ts'
+import { spawnBounded } from './spawn-bounded.ts'
+
+export const HBCLI_REGISTRATION_URL = 'https://hotelbyte.com/zh/guides/sandbox-verification'
+const ENVIRONMENT = 'uat'
+const ENTRY = `openapi:${ENVIRONMENT}`
+export interface HbcliConfigOptions { homeDir?: string; env?: NodeJS.ProcessEnv; hbcliBin?: string }
+export type HbcliSetupVerdict = 'hit' | 'miss' | 'no-suppliers'
+interface Verification { schema: 'gotry.hbcli-verification.v1'; fingerprint: string; verdict: HbcliSetupVerdict; at: string }
+
+export function hbcliCredentialRoot(options: HbcliConfigOptions): string {
+  return options.env?.STAICLI_HOME?.trim() || join(options.homeDir ?? homedir(), '.staicli')
+}
+export function hbcliCredentialPath(options: HbcliConfigOptions): string { return join(hbcliCredentialRoot(options), 'credentials.json') }
+export function hbcliVerificationPath(homeDir: string): string { return join(homeDir, '.gotry', 'hbcli-verification.json') }
+
+function safeEntry(path: string, directory: boolean): boolean {
+  try {
+    const entry = lstatSync(path)
+    return !entry.isSymbolicLink() && (directory ? entry.isDirectory() : entry.isFile())
+      && (typeof process.getuid !== 'function' || entry.uid === process.getuid())
+  } catch (e) { return (e as NodeJS.ErrnoException).code === 'ENOENT' }
+}
+export function readHbcliCredentials(options: HbcliConfigOptions): { ok: true; data: Record<string, unknown>; bytes?: string } | { ok: false } {
+  const root = hbcliCredentialRoot(options), file = hbcliCredentialPath(options)
+  try {
+    if (!isAbsolute(root) || !safeEntry(root, true) || !safeEntry(file, false)) return { ok: false }
+    if (!existsSync(file)) return { ok: true, data: {} }
+    const bytes = readFileSync(file, 'utf8'), data: unknown = JSON.parse(bytes)
+    return data && typeof data === 'object' && !Array.isArray(data) ? { ok: true, data: data as Record<string, unknown>, bytes } : { ok: false }
+  } catch { return { ok: false } }
+}
+function fingerprint(data: Record<string, unknown>): string | undefined {
+  const entry = data[ENTRY] as { appKey?: unknown; appSecret?: unknown } | undefined
+  return typeof entry?.appKey === 'string' && entry.appKey.trim() && typeof entry.appSecret === 'string' && entry.appSecret.trim()
+    ? sha256Hex(JSON.stringify([ENVIRONMENT, entry.appKey, entry.appSecret])) : undefined
+}
+function readReceipt(home: string): Verification | undefined {
+  try {
+    const path = hbcliVerificationPath(home)
+    if (!safeEntry(join(home, '.gotry'), true) || !safeEntry(path, false)) return undefined
+    const v = JSON.parse(readFileSync(path, 'utf8')) as Verification
+    return v.schema === 'gotry.hbcli-verification.v1' && typeof v.fingerprint === 'string'
+      && ['hit', 'miss', 'no-suppliers'].includes(v.verdict) && Number.isFinite(Date.parse(v.at)) ? v : undefined
+  } catch { return undefined }
+}
+export function hbcliSetupStatus(options: HbcliConfigOptions) {
+  const read = readHbcliCredentials(options), hash = read.ok ? fingerprint(read.data) : undefined
+  const receipt = readReceipt(options.homeDir ?? homedir())
+  const envToken = Boolean(options.env?.HOTELBYTE_TOKEN?.trim())
+  const matches = !envToken && hash && receipt?.fingerprint === hash
+  return { ok: true, configured: envToken || Boolean(hash), writable: read.ok && !envToken && process.platform !== 'win32',
+    source: envToken ? 'env' : hash ? 'config' : 'none', environment: ENVIRONMENT,
+    verified: Boolean(matches && receipt?.verdict !== 'no-suppliers'),
+    ...(matches && receipt ? { verdict: receipt.verdict, checkedAt: receipt.at } : {}), registrationUrl: HBCLI_REGISTRATION_URL }
+}
+
+function prepareDirectory(dir: string): boolean {
+  try {
+    if (process.platform === 'win32' || !isAbsolute(dir) || !safeEntry(dir, true)) return false
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+    if (!safeEntry(dir, true)) return false
+    chmodSync(dir, 0o700)
+    return true
+  } catch { return false }
+}
+export function writeHbcliCredentials(data: Record<string, unknown>, options: HbcliConfigOptions): boolean {
+  const path = hbcliCredentialPath(options)
+  return readHbcliCredentials(options).ok && prepareDirectory(hbcliCredentialRoot(options)) && atomicWriteJson(path, data).ok
+}
+export function writeHbcliVerification(data: Record<string, unknown>, verdict: HbcliSetupVerdict, options: HbcliConfigOptions): boolean {
+  const hash = fingerprint(data), home = options.homeDir ?? homedir()
+  if (!hash || !prepareDirectory(join(home, '.gotry'))) return false
+  const entry: Verification = { schema: 'gotry.hbcli-verification.v1', fingerprint: hash, verdict, at: new Date().toISOString() }
+  return safeEntry(hbcliVerificationPath(home), false) && atomicWriteJson(hbcliVerificationPath(home), entry).ok
+}
+export function removeHbcliVerification(homeDir: string): void {
+  if (safeEntry(join(homeDir, '.gotry'), true) && safeEntry(hbcliVerificationPath(homeDir), false)) {
+    try { rmSync(hbcliVerificationPath(homeDir), { force: true }) } catch { /* best effort */ }
+  }
+}
+export function withHbcliCredentials(data: Record<string, unknown>, appKey: string, appSecret: string): Record<string, unknown> {
+  return { ...data, [ENTRY]: { appKey, appSecret } }
+}
+export function withoutHbcliCredentials(data: Record<string, unknown>): Record<string, unknown> {
+  const next = { ...data }; delete next[ENTRY]; return next
+}
+
+/** Verify through the existing CLI bridge, with a private disposable credential root.
+ * An upstream no-suppliers verdict is retained separately from a completed query.
+ */
+export async function verifyHbcliCandidate(appKey: string, appSecret: string, options: HbcliConfigOptions, signal: AbortSignal): Promise<{ verdict: HbcliSetupVerdict | 'error' | 'cancelled'; error?: string }> {
+  const root = mkdtempSync(join(tmpdir(), 'gotry-hbcli-verify-'))
+  try {
+    if (!atomicWriteJson(join(root, 'credentials.json'), withHbcliCredentials({}, appKey, appSecret)).ok) {
+      return { verdict: 'error', error: '无法创建隔离的验证环境。' }
+    }
+    const checkIn = new Date(); checkIn.setUTCDate(checkIn.getUTCDate() + 1)
+    const checkOut = new Date(checkIn); checkOut.setUTCDate(checkOut.getUTCDate() + 1)
+    const args = ['--json', '--env', ENVIRONMENT, 'search', 'hotel-list', '--destination-name', '上海',
+      '--check-in', checkIn.toISOString().slice(0, 10), '--check-out', checkOut.toISOString().slice(0, 10),
+      '--room-occupancies', '[{"adultCount":2,"childrenAges":[]}]', '--page-size', '1']
+    const env: NodeJS.ProcessEnv = { ...(options.env ?? process.env), STAICLI_HOME: root, HOTELBYTE_ENV: ENVIRONMENT }
+    delete env.HOTELBYTE_TOKEN
+    let result: Awaited<ReturnType<typeof spawnBounded>> | undefined
+    for (const bin of hbcliBinCandidates(options.hbcliBin ?? options.env?.GOTRY_HBCLI_BIN ?? 'hbcli', options.homeDir)) {
+      result = await spawnBounded(bin, args, { env, signal, timeoutMs: 20_000 })
+      if (!/ENOENT/.test(result.error ?? '') || signal.aborted) break
+    }
+    if (signal.aborted || result?.aborted) return { verdict: 'cancelled', error: '验证已取消，旧配置保留。' }
+    if (!result || result.error || result.timedOut || result.drainTimedOut || result.groupReaped === false || result.code !== 0) {
+      return { verdict: 'error', error: 'HotelByte 验证未完成，请检查 hbcli 安装、网络和凭证；旧配置保留。' }
+    }
+    let value: { code?: unknown; list?: unknown }
+    try { value = JSON.parse(result.stdout) } catch { return { verdict: 'error', error: 'HotelByte 回包无法识别，旧配置保留。' } }
+    if (value?.code === 300010002 || value?.code === '300010002') return { verdict: 'no-suppliers' }
+    if (!value || (value.code !== undefined && value.code !== 0 && value.code !== '0') || !Array.isArray(value.list)
+      || value.list.some(item => !item || typeof item !== 'object' || Array.isArray(item))) {
+      return { verdict: 'error', error: 'HotelByte 未接受凭证或返回了无效的查询结果；旧配置保留。' }
+    }
+    return { verdict: value.list.length ? 'hit' : 'miss' }
+  } finally { rmSync(root, { recursive: true, force: true }) }
+}

package/ts/capabilities/hbcli.ts

@@ -32,7 +32,7 @@ export interface HbcliCallOptions {
 export interface HbcliCallResult {
   /** 是否走了实时 hbcli */
   via: 'hbcli-realtime' | 'hbcli-cache' | 'hbcli-error'
-  /** hbcli 退码 0=成功 */
+  /** hbcli 进程退出码；零不代表 API 业务成功 */
   exitCode: number
   /** 解析后的 JSON(若 --json 模式输出可解析;否则为空) */
   result: unknown
@@ -99,6 +99,24 @@ async function attemptHbcli(
   if (jsonStr) {
     try { result = JSON.parse(jsonStr) } catch { /* 非 JSON 输出,留给调用方处理 */ }
   }
+  // CLI exit status describes the process, not the API verdict. hbcli can exit
+  // zero with an API error envelope (for example an unconfigured supplier pool).
+  const code = (result as { code?: unknown } | null)?.code
+  const invalid = result === null
+  const upstreamFailure = code !== undefined && code !== 0 && code !== '0'
+  if (invalid || upstreamFailure) {
+    const msg = (result as { msg?: unknown; message?: unknown } | null)?.msg
+      ?? (result as { message?: unknown } | null)?.message
+    const detail = code === 300010002 || code === '300010002'
+      ? '当前账号没有可用供应商；库存查询未完成'
+      : typeof msg === 'string' ? msg.slice(0, 200) : 'API request failed'
+    return {
+      via: 'hbcli-error', exitCode: 0, result: null,
+      evidence: `[实时API:hbcli@error@${ts}]`,
+      stdout: r.stdout.slice(0, 2000), latencyMs,
+      error: invalid ? 'failed to parse hbcli output as JSON' : `hbcli upstream code ${String(code)}: ${detail}`,
+    }
+  }
   return {
     via: 'hbcli-realtime', exitCode: 0, result,
     evidence: `[实时API:hbcli@${ts}]`,
@@ -177,7 +195,7 @@ export async function searchHotels(
   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)
+  let live = await callHbcliJson(hbArgs, opts)
   // 取消立即结束:不读静态包、不产出命中/无结果/估算,也不计上游故障
   if (opts.signal?.aborted || /abort/i.test(live.error ?? '')) {
     const ts = new Date().toISOString()
@@ -188,6 +206,15 @@ export async function searchHotels(
       latencyMs: live.latencyMs, error: `aborted by host signal${cleanupError}`, summary: `酒店「${query.destination}」检索已取消,未产生事实`,
     }
   }
+  const list = (live.result as { list?: unknown } | null)?.list
+  if (live.via === 'hbcli-realtime' && (!Array.isArray(list)
+    || list.some(item => item === null || typeof item !== 'object' || Array.isArray(item)))) {
+    live = {
+      ...live, via: 'hbcli-error', result: null,
+      evidence: `[实时API:hbcli@error@${new Date().toISOString()}]`,
+      error: 'invalid hotel-list response: expected list array of hotels; inventory not observed',
+    }
+  }
   if (live.via === 'hbcli-realtime') {
     // summary 即模型面(render 只透 summary):必须自带紧凑数据行 + 证据链,
     // 否则模型只看到「实时返回」占位一句话(issue #195 实锤)。
@@ -297,7 +324,7 @@ export async function checkAvail(
  * ~/.staicli/credentials.json)——hbcli 侧 customer 档是最低优先级凭据(无
  * portal/API-key 凭据时才生效),登录不劫持既有凭据。本层不透出 token 值
  * (CLI 只回 token_saved,凭据留在 CLI 仓内,不进 gotry 会话/日志)。
- * auth 命令族要求 hbcli 带 register 支持(npm 0.0.4 起;0.0.3 报 unknown
+ * auth 命令族要求 hbcli 带 register 支持(官方原生 0.0.4 起;0.0.3 报 unknown
  * command,经 hbcli-error 面优雅失败)。
  */
 export async function customerSendCode(

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

@@ -7,12 +7,21 @@
  * 只读:适配器不含任何提交/预订语义;URL 直开即零 DOM 交互。
  */
 
-/** 城市三字码表(小起步集;词表外 unresolved 逐字保留,不做开放式猜测——ADR-12 同款边界) */
-const CITY_CODES: Record<string, string> = {
+import { resolveCtripFlightCity, cityResolutionHint, type CityResolution } from '../ctrip-city.ts'
+
+/**
+ * 离线起步缓存;未命中由编排层查询供应商城市数据(ctrip-city.ts),不推断航线覆盖。
+ * 码表只做性能优化,不在主链路上(显式码/供应商解析是正路)。
+ * 实测校准(2026-10-14):香港=hkg/迪拜=dxb 经 list 页实证——合法组合 HTTP 200 且
+ * title 含航线名(「中国香港(HKG)到迪拜(阿联酋)(DXB)机票预订」),非法组合 302 跳
+ * international/search(该 200/302 判别式即真数据校准手段)。
+ */
+export 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',
+  香港: 'hkg', 迪拜: 'dxb',
 }
 
 export interface AdapterEntry {
@@ -20,16 +29,43 @@ export interface AdapterEntry {
   url?: string
   /** 词表外城市逐字保留(调用方降级无日期/无线路搜索) */
   unresolved?: string[]
+  error?: string
 }
 
-export function buildEntryUrl(from: string, to: string, depDate: string): AdapterEntry {
+/** Resolve unknown names against current supplier metadata before inventory navigation. */
+export async function resolveFlightEntryUrl(from: string, to: string, depDate: string,
+  codes: { fromCode?: string; toCode?: string } = {},
+  resolve: (query: string) => Promise<CityResolution> = resolveCtripFlightCity,
+  backDate?: string): Promise<AdapterEntry> {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(depDate)) return { ok: false, unresolved: [depDate], error: '出发日期需要 YYYY-MM-DD' }
+  for (const c of [codes.fromCode, codes.toCode]) if (c !== undefined && !/^[a-z]{3}$/i.test(c)) return { ok: false, error: '城市／机场码必须是三个英文字母' }
+  const resolveCode = async (name: string, explicit?: string) => {
+    const known = explicit ?? (/^[a-z]{3}$/i.test(name.trim()) ? name.trim() : undefined)
+    if (known) return { code: known }
+    const result = await resolve(name)
+    return result.ok ? { code: result.city.code } : { error: cityResolutionHint(name, result) }
+  }
+  const [origin, destination] = await Promise.all([resolveCode(from, codes.fromCode), resolveCode(to, codes.toCode)])
+  if (!origin.code || !destination.code) return { ok: false, unresolved: [!origin.code ? from : '', !destination.code ? to : ''].filter(Boolean), error: [origin.error, destination.error].filter(Boolean).join('；') }
+  return buildEntryUrl(from, to, depDate, { fromCode: origin.code, toCode: destination.code }, backDate)
+}
+
+export function buildEntryUrl(from: string, to: string, depDate: string, codes: { fromCode?: string; toCode?: string } = {}, backDate?: string): AdapterEntry {
   const unresolved: string[] = []
-  const fromCode = CITY_CODES[from]
-  const toCode = CITY_CODES[to]
+  // 显式码优先(形状合格才采纳),词表只是缓存——任何城市都可经显式码成行。
+  const fromCode = codes.fromCode === undefined ? CITY_CODES[from.trim()] : /^[a-z]{3}$/i.test(codes.fromCode) ? codes.fromCode.toLowerCase() : undefined
+  const toCode = codes.toCode === undefined ? CITY_CODES[to.trim()] : /^[a-z]{3}$/i.test(codes.toCode) ? codes.toCode.toLowerCase() : undefined
   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] }
+  const badDate = !/^\d{4}-\d{2}-\d{2}$/.test(depDate)
+    || (backDate !== undefined && (!/^\d{4}-\d{2}-\d{2}$/.test(backDate) || backDate <= depDate))
+  if (unresolved.length > 0 || badDate) {
+    return { ok: false, unresolved: unresolved.length > 0 ? unresolved : [badDate ? (backDate !== undefined && backDate <= depDate ? backDate : depDate) : depDate], ...(backDate !== undefined && backDate <= depDate ? { error: `回程(${backDate})须晚于去程(${depDate})` } : {}) }
+  }
+  // 往返形状(2026-10-14 GUI URL 教师实测定稿):round-{code}0-{code}0?depdate=去_回&cabin=y_s
+  // ——此前 roundtrip-{3字码}?depdate&retdate 的猜测形状实测 302,已废弃。
+  if (backDate) {
+    return { ok: true, url: `https://flights.ctrip.com/online/list/round-${fromCode}0-${toCode}0?depdate=${depDate}_${backDate}&cabin=y_s&adult=1&child=0&infant=0` }
   }
   return { ok: true, url: `https://flights.ctrip.com/online/list/oneway-${fromCode}-${toCode}?depdate=${depDate}` }
 }

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

@@ -14,10 +14,12 @@
  * 页面照常生效(下单/支付面 URL 仍被物理拦截)。
  */
 
-/** 城市码表(**实测校准 2026-09-03**:每条 id 均经 hotels.ctrip.com list 页
+import { resolveCtripHotelCity, hotelResolutionHint, type HotelCityResolution } from '../ctrip-city.ts'
+
+/** 离线兼容缓存(**实测校准 2026-09-03**:每条 id 均经 hotels.ctrip.com list 页
  * <title> 验证——探测法曾纠出 104=平遥县(传猜成都)等 5 处错猜,表内只收
  * 验证过的 id;词表外 unresolved 逐字保留,调用方可显式传 cityId 覆盖) */
-const HOTEL_CITY_CODES: Record<string, string> = {
+export const HOTEL_CITY_CODES: Record<string, string> = {
   上海: '2', 北京: '1', 广州: '32', 深圳: '30', 成都: '28',
   杭州: '17', 南京: '12', 苏州: '14', 无锡: '13', 扬州: '15', 镇江: '16',
   青岛: '7', 厦门: '25', 珠海: '31', 三亚: '43', 海口: '42',
@@ -25,6 +27,9 @@ const HOTEL_CITY_CODES: Record<string, string> = {
   贵阳: '38', 拉萨: '41', 乌鲁木齐: '39', 太原: '105', 长春: '158', 南通: '82',
   敦煌: '11', 舟山: '19', 张家界: '27', 黄山市: '23', 九江: '24', 武夷山: '26',
   迪拜: '220',
+  // Verified against the official list page and its displayed destination/date
+  // controls on 2026-10-07; https://hotels.ctrip.com/hotels/list?city=5
+  哈尔滨: '5',
 }
 
 export interface AdapterEntry {
@@ -32,6 +37,7 @@ export interface AdapterEntry {
   url?: string
   /** 词表外城市逐字保留(调用方提示:web 搜携程酒店 list 页取 city id 后带 cityId 重试) */
   unresolved?: string[]
+  error?: string
 }
 
 export interface HotelEntryQuery {
@@ -39,6 +45,7 @@ export interface HotelEntryQuery {
   to: string
   /** 显式城市 id(携程/trip.com 酒店 list 页 URL 的 city= 数字;覆盖码表) */
   cityId?: number | string
+  country?: string
   /** YYYY-MM-DD */
   checkIn?: string
   /** YYYY-MM-DD(与 checkIn 成对) */
@@ -46,14 +53,23 @@ export interface HotelEntryQuery {
   adults?: number
 }
 
+export async function resolveHotelEntryUrl(q: HotelEntryQuery,
+  resolve: (query: string, country?: string) => Promise<HotelCityResolution> = resolveCtripHotelCity): Promise<AdapterEntry> {
+  if (q.cityId !== undefined) return buildHotelEntryUrl(q)
+  const result = await resolve(q.to, q.country)
+  if (!result.ok) return { ok: false, unresolved: [q.to], error: hotelResolutionHint(q.to, result) }
+  return buildHotelEntryUrl({ ...q, cityId: result.city.id })
+}
+
 export function buildHotelEntryUrl(q: HotelEntryQuery): AdapterEntry {
   const unresolved: string[] = []
-  const cityId = String(q.cityId ?? '').trim() || HOTEL_CITY_CODES[q.to.trim()]
+  const candidate = q.cityId === undefined ? HOTEL_CITY_CODES[q.to.trim()] : String(q.cityId).trim()
+  const cityId = candidate && /^[1-9]\d{0,9}$/.test(candidate) ? candidate : undefined
   if (!cityId) unresolved.push(q.to)
   if (unresolved.length > 0) {
     return { ok: false, unresolved }
   }
-  const params = new URLSearchParams({ city: cityId })
+  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))
@@ -236,3 +252,34 @@ export function parseCtripHotelList(body: string, opts: { maxItems?: number } =
   walk(raw, 0, new Set())
   return out
 }
+
+/** Only an explicit empty hotel array proves a miss; parser failure proves nothing. */
+export function classifyCtripHotelList(body: string): {
+  shape: 'parsed' | 'recognized-empty' | 'malformed' | 'unrecognized'
+  hotels: SessionHotelOption[]
+} {
+  let raw: unknown
+  try { raw = JSON.parse(body) } catch { return { shape: 'malformed', hotels: [] } }
+  const envelope = raw as { code?: unknown; success?: unknown; ok?: unknown; ResponseStatus?: { Ack?: unknown } } | null
+  if (envelope?.success === false || envelope?.ok === false
+    || (envelope?.code !== undefined && envelope.code !== 0 && envelope.code !== '0')
+    || /^(failure|error)$/i.test(String(envelope?.ResponseStatus?.Ack ?? ''))) {
+    return { shape: 'unrecognized', hotels: [] }
+  }
+  const hotels = parseCtripHotelList(body)
+  if (hotels.length > 0) return { shape: 'parsed', hotels }
+  let emptyList = false
+  let unparsedItems = false
+  const inspectHotelLists = (node: unknown, depth: number): void => {
+    if (depth > 12 || node === null || typeof node !== 'object') return
+    for (const [key, value] of Object.entries(node)) {
+      if (['hotelList', 'hotelMatchInfos'].includes(key) && Array.isArray(value)) {
+        if (value.length === 0) emptyList = true
+        else unparsedItems = true
+      }
+      inspectHotelLists(value, depth + 1)
+    }
+  }
+  inspectHotelLists(raw, 0)
+  return { shape: emptyList && !unparsedItems ? 'recognized-empty' : 'unrecognized', hotels: [] }
+}

package/ts/capabilities/session/ctrip-city.ts

@@ -0,0 +1,158 @@
+/** Public supplier city metadata, independent of inventory and account sessions. */
+export const CTRIP_CITY_CATALOG_URL = 'https://m.ctrip.com/restapi/soa2/17909/SearchBoxRecommend'
+export const CTRIP_CITY_SUGGEST_URL = 'https://flights.ctrip.com/international/search/api/poi/search'
+export const CTRIP_HOTEL_CITY_URL = 'https://m.ctrip.com/restapi/soa2/34951/getHotelKeywords'
+export interface CtripCity {
+  name: string
+  code: string
+  aliases: string[]
+  context?: string
+  airport?: boolean
+  requiresQualification?: boolean
+}
+export type CityResolution =
+  | { ok: true; city: CtripCity }
+  | { ok: false; reason: 'ambiguous' | 'not-found' | 'unavailable'; candidates: CtripCity[] }
+const normalized = (s: string) => s.normalize('NFKC').trim().replace(/^中国(?=香港|澳门)/, '').toLowerCase()
+const text = (v: unknown) => typeof v === 'string' ? v.trim() : ''
+const code = (v: unknown) => /^[a-z]{3}$/i.test(text(v)) ? text(v).toUpperCase() : undefined
+const object = (v: unknown): Record<string, unknown> => v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {}
+
+export function parseCtripCityCatalog(value: unknown): CtripCity[] {
+  const root = object(value)
+  if (object(root.ResponseStatus).Ack !== 'Success' || object(root.responseHead).errorCode !== '0' || !Array.isArray(root.recommendGroupList)) throw new Error('unrecognized city catalog')
+  const records: CtripCity[] = []
+  let visited = 0
+  const walk = (v: unknown, depth = 0) => {
+    if (++visited > 20_000 || depth > 12) throw new Error('city catalog bounds')
+    if (Array.isArray(v)) { for (const item of v) walk(item, depth + 1); return }
+    const r = object(v), c = code(r.code), name = text(r.name)
+    if (c && name && Number(r.id) > 0) {
+      records.push({ name, code: c, aliases: [name, text(r.eName), text(r.nameEn), text(r.namePy), text(r.specName)].filter(Boolean), context: text(r.specName) || undefined, requiresQualification: r.sameSpecCity === 1 })
+      if (Array.isArray(r.airportlst)) for (const item of r.airportlst) {
+        const a = object(item), ac = code(a.code), an = text(a.name)
+        if (ac && an) records.push({ name: an, code: ac, aliases: [an], context: name, airport: true })
+      }
+    }
+    for (const [key, child] of Object.entries(r)) if (key !== 'airportlst' && child && typeof child === 'object') walk(child, depth + 1)
+  }
+  walk(root.recommendGroupList)
+  return records
+}
+
+export function parseCtripCitySuggestions(value: unknown): CtripCity[] {
+  const root = object(value)
+  if (!Array.isArray(root.Data)) throw new Error('unrecognized city suggestions')
+  const records: CtripCity[] = []
+  let visited = 0
+  const walk = (items: unknown[], depth = 0) => {
+    if (depth > 5) throw new Error('city suggestion bounds')
+    for (const value of items) {
+      if (++visited > 2_000) throw new Error('city suggestion bounds')
+      const r = object(value), c = code(r.Code), name = text(r.Name)
+      if (c && name && [3, 4, 5].includes(Number(r.Type))) records.push({
+        name, code: c, aliases: [name, text(r.EName), text(r.NameAlias), text(r.ShortSpell)].filter(Boolean),
+        context: [text(r.Country), text(r.Province)].filter(Boolean).join(' / ') || undefined, airport: Number(r.Type) === 3,
+      })
+      if (Array.isArray(r.Datas)) walk(r.Datas, depth + 1)
+      // Nearby cities must not be substituted for the requested destination.
+    }
+  }
+  walk(root.Data)
+  return records
+}
+
+export function matchCtripCity(query: string, records: CtripCity[]): CityResolution {
+  const input = normalized(query)
+  const matches = records.filter(r => r.code.toLowerCase() === input || r.aliases.some(a => normalized(a) === input))
+  const unique = [...new Map(matches.map(r => [`${r.code}:${r.context ?? ''}`, r])).values()]
+  // A city and its airport may share one code. An explicitly typed code remains exact.
+  const codes = new Set(unique.map(r => r.code))
+  if (codes.size === 1 && /^[a-z]{3}$/i.test(query.trim())) return { ok: true, city: unique[0]! }
+  if (unique.length === 1 && (!unique[0]!.requiresQualification || normalized(unique[0]!.context ?? '') === input)) return { ok: true, city: unique[0]! }
+  return { ok: false, reason: unique.length ? 'ambiguous' : 'not-found', candidates: unique.slice(0, 8) }
+}
+
+type CityFetch = typeof fetch
+async function readMetadata(url: string, init: RequestInit, fetcher: CityFetch): Promise<unknown> {
+  const response = await fetcher(url, { ...init, signal: AbortSignal.timeout(8_000), redirect: 'error' })
+  if (!response.ok || !response.body) throw new Error('city metadata unavailable')
+  const reader = response.body.getReader(), chunks: Uint8Array[] = []
+  let size = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.byteLength
+      if (size > 512_000) throw new Error('city metadata bounds')
+      chunks.push(value)
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  } finally { await reader.cancel().catch(() => {}) }
+}
+let catalog: { at: number; promise: Promise<CtripCity[]> } | undefined
+const catalogBody = {
+  head: { cver: '3', cid: '', extension: [{ name: 'source', value: 'ONLINE' }, { name: 'sotpGroup', value: 'CTrip' }, { name: 'sotpLocale', value: 'zh-CN' }] },
+  locale: 'zh-CN', departureCity: '', dataType: 0,
+}
+export async function resolveCtripFlightCity(query: string, fetcher: CityFetch = fetch): Promise<CityResolution> {
+  if (!query.trim() || query.length > 120) return { ok: false, reason: 'not-found', candidates: [] }
+  if (fetcher === fetch && process.env.GOTRY_SESSION_LIVE === '0') return { ok: false, reason: 'unavailable', candidates: [] }
+  try {
+    const load = () => readMetadata(CTRIP_CITY_CATALOG_URL, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(catalogBody) }, fetcher).then(parseCtripCityCatalog)
+    let records: CtripCity[]
+    if (fetcher !== fetch) records = await load()
+    else {
+      if (!catalog || Date.now() - catalog.at > 3_600_000) catalog = { at: Date.now(), promise: load() }
+      try { records = await catalog.promise } catch { catalog = undefined; records = [] }
+    }
+    const matched = matchCtripCity(query, records)
+    if (matched.ok || matched.reason === 'ambiguous') return matched
+    const url = new URL(CTRIP_CITY_SUGGEST_URL)
+    url.searchParams.set('key', query.trim().toUpperCase())
+    url.searchParams.set('filterAirport', 'false')
+    return matchCtripCity(query, parseCtripCitySuggestions(await readMetadata(url.href, {}, fetcher)))
+  } catch { return { ok: false, reason: 'unavailable', candidates: [] } }
+}
+
+export function cityResolutionHint(query: string, result: Exclude<CityResolution, { ok: true }>): string {
+  if (result.reason === 'ambiguous') return `城市「${query}」有多个候选，请确认城市或机场码：${result.candidates.map(c => `${c.name} ${c.code}${c.context ? `（${c.context}）` : ''}`).join('；')}`
+  return `unresolved 城市「${query}」：${result.reason === 'unavailable' ? '携程城市解析服务暂不可用' : '供应商城市候选未精确匹配'}；请确认城市／机场名称，或提供 fromCityCode／toCityCode。城市解析失败不能证明该航线无库存或不受支持。`
+}
+
+export interface CtripHotelCity { id: string; name: string; aliases: string[]; countries: string[]; context: string }
+export type HotelCityResolution = { ok: true; city: CtripHotelCity } | { ok: false; reason: 'ambiguous' | 'not-found' | 'unavailable'; candidates: CtripHotelCity[] }
+export function parseCtripHotelCities(value: unknown): CtripHotelCity[] {
+  const root = object(value), data = object(root.data), keywords = object(data.mainKeywordList).keywords
+  if (object(root.ResponseStatus).Ack !== 'Success' || data.htlSpiderActionErrorCode || !Array.isArray(keywords) || keywords.length > 1_000) throw new Error('hotel city metadata unavailable')
+  const records: CtripHotelCity[] = []
+  for (const item of keywords) {
+    const r = object(item), k = object(object(r.keyword).keywordContentInfo), region = object(object(r.controlInfo).regionInfo)
+    const display = object(region.displayCityModel), basic = object(region.basicCityModel), id = String(basic.cityId ?? '')
+    if (k.tripType !== 'CT' || !/^[1-9]\d{0,9}$/.test(id)) continue
+    if (k.keywordCode !== undefined && String(k.keywordCode) !== id) throw new Error('hotel city ID conflict')
+    const titles = Array.isArray(k.displayTexts) ? k.displayTexts.map(object).filter(t => t.key === 'MAIN_TITLE').map(t => text(t.value)) : []
+    const name = text(display.cityName) || text(display.destinationName)
+    if (!name) continue
+    records.push({ id, name, aliases: [name, text(display.destinationName), text(display.destinationNameEN), ...titles].filter(Boolean),
+      countries: [text(display.countryName), text(display.countryNameEN)].filter(Boolean),
+      context: [text(display.countryName), text(display.provinceName)].filter(Boolean).join(' / ') })
+  }
+  return records
+}
+export async function resolveCtripHotelCity(query: string, country?: string, fetcher: CityFetch = fetch): Promise<HotelCityResolution> {
+  if (!query.trim() || query.length > 120 || (country?.length ?? 0) > 120) return { ok: false, reason: 'not-found', candidates: [] }
+  if (fetcher === fetch && process.env.GOTRY_SESSION_LIVE === '0') return { ok: false, reason: 'unavailable', candidates: [] }
+  try {
+    const value = await readMetadata(CTRIP_HOTEL_CITY_URL, { method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ head: { platform: 'PC', bu: 'HBU', group: 'ctrip', locale: 'zh-CN' }, queryInfo: { keyword: query.trim(), actionType: 'destination' } }) }, fetcher)
+    const input = normalized(query)
+    const candidates = parseCtripHotelCities(value).filter(c => (!country || c.countries.some(a => normalized(a) === normalized(country))) && c.aliases.some(a => normalized(a) === input))
+    const unique = [...new Map(candidates.map(c => [c.id, c])).values()]
+    return unique.length === 1 ? { ok: true, city: unique[0]! } : { ok: false, reason: unique.length ? 'ambiguous' : 'not-found', candidates: unique.slice(0, 8) }
+  } catch { return { ok: false, reason: 'unavailable', candidates: [] } }
+}
+export function hotelResolutionHint(query: string, result: Exclude<HotelCityResolution, { ok: true }>): string {
+  if (result.reason === 'ambiguous') return `城市「${query}」有多个候选，请确认国家或城市：${result.candidates.map(c => `${c.name}（${c.context}，cityId=${c.id}）`).join('；')}`
+  return `城市「${query}」${result.reason === 'unavailable' ? '的携程酒店城市解析服务暂不可用' : '未精确匹配供应商城市候选'}；可提供 country 消歧，或携程酒店 list 页 city= 数字作为 cityId。城市解析失败不能证明目的地不受支持。`
+}

package/ts/capabilities/session/extension-bridge.ts

@@ -133,7 +133,7 @@ export interface ExtensionJobResult {
 
 export type SubmitOutcome =
   | { ok: true; result: ExtensionJobResult; origin?: string; clientId?: string }
-  | { ok: false; reason: 'bridge-unavailable' | 'extension-not-connected' | 'timeout'; summary: string }
+  | { ok: false; reason: 'bridge-unavailable' | 'extension-not-connected' | 'timeout'; summary: string; jobKind?: ExtensionJobKind; stage?: 'queued' | 'claimed' }
 
 export interface SessionJobHandle {
   submit(job: Omit<ExtensionJob, 'jobId'>, opts?: { timeoutMs?: number; extensionWaitMs?: number; preferredOrigin?: string; preferredClientId?: string }): Promise<SubmitOutcome>
@@ -668,7 +668,14 @@ export function createBridgeJobQueue(opts: BridgeJobQueueOptions = {}): BridgeJo
         const settle = armSettle(entry, resolve)
         entry.resolve = settle
         entry.timer = setTimeout(() => {
-          settle({ ok: false, reason: 'timeout', summary: `扩展未在 ${timeoutMs}ms 内回包(标签页无嗅探命中或扩展已停用)` })
+          const stage = entry.claimedOrigin === undefined ? 'queued' : 'claimed'
+          const task = full.kind === 'cookie-names' ? '登录态检查' : full.kind === 'search' ? '检索' : '登录页打开'
+          settle({
+            ok: false, reason: 'timeout', jobKind: full.kind, stage,
+            summary: stage === 'queued'
+              ? `扩展${task}等待领取超时（${timeoutMs}ms）；尚未执行，请检查扩展是否支持当前站点或正在处理其他作业`
+              : `扩展${task}已领取但未在 ${timeoutMs}ms 内回传；请检查扩展运行错误与桥连接`,
+          })
         }, timeoutMs)
         if (!dispatchToParked(entry)) queue.push(entry)
         // 扩展未上线:有界等待(桥刚拉起时扩展 ≤5s 即连上);宽限过仍无 → 立即 no-spend 失败,不空耗