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

package/ts/capabilities/flyai.ts

@@ -32,7 +32,7 @@
 import { closeSync, openSync, readFileSync, unlinkSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { resolveFlyaiEndpoint, resolveFlyaiKey, type FlyaiKeySource } from './flyai-config.ts'
+import { normalizeEndpoint, resolveFlyaiEndpoint, resolveFlyaiKey, sha256Hex, type FlyaiKeySource } from './flyai-config.ts'
 import { spawnBounded } from './spawn-bounded.ts'
 
 export type FlyaiKind =
@@ -239,6 +239,8 @@ export interface FlyaiResult {
   verdict: FlyaiVerdict
   /** true = 已识别的上游普通网络/HTTP 5xx/429 瞬时失败，可交给 effect 层退避重试 */
   retryable?: boolean
+  /** 独立于重试：只在明确上游故障时计熔断；unknown 不增失败，也不宣称恢复。 */
+  upstreamHealth?: 'healthy' | 'unhealthy' | 'unknown'
   /** 存在时表示请求未得到可判定的上游响应，应 fail-closed 且只执行一次。 */
   localTermination?: FlyaiLocalTermination
   kind: FlyaiKind
@@ -411,7 +413,7 @@ export function parseFlyaiItemList(stdout: string): unknown[] {
 }
 
 /** 解析 stdout 中首个完整 JSON 对象(不限 itemList;ai-search 用) */
-export function parseFlyaiJsonEnvelope(stdout: string): Record<string, unknown> {
+export function parseFlyaiJsonEnvelope(stdout: string, accepts: (envelope: Record<string, unknown>) => boolean = () => true): Record<string, unknown> {
   let start = -1
   let depth = 0
   let inString = false
@@ -435,7 +437,12 @@ export function parseFlyaiJsonEnvelope(stdout: string): Record<string, unknown>
       depth -= 1
       if (depth === 0) {
         const candidate = stdout.slice(start, index + 1)
-        try { return JSON.parse(candidate) as Record<string, unknown> } catch { start = -1; depth = 0 }
+        try {
+          const parsed = JSON.parse(candidate) as Record<string, unknown>
+          if (accepts(parsed)) return parsed
+        } catch { /* prefix logs may contain balanced non-JSON braces */ }
+        start = -1
+        depth = 0
       }
     }
   }
@@ -749,6 +756,15 @@ const KIND_LABEL: Record<FlyaiKind, string> = {
   keyword: 'keyword', ai: 'ai', 'marriott-hotel': 'marriott hotel', 'marriott-package': 'marriott package',
 }
 
+/** 每种检索 × 生效 endpoint/key 隔离；Map 中只留下不可逆指纹。 */
+export function flyaiBreakerScope(kind: unknown): string {
+  const key = resolveFlyaiKey()
+  const endpoint = resolveFlyaiEndpoint().url
+  const identity = sha256Hex(JSON.stringify([normalizeEndpoint(endpoint) ?? endpoint, key.key ?? null]))
+  const safeKind = typeof kind === 'string' && Object.hasOwn(KIND_LABEL, kind) ? kind : 'invalid-kind'
+  return `${safeKind}:${identity}`
+}
+
 /**
  * FlyAI 官方只读检索(8 命令)— 任何失败走降级;不抛错。
  */
@@ -758,9 +774,9 @@ export async function flyaiSearch(q: FlyaiQuery): Promise<FlyaiResult> {
   const envContext = await runtimeEnvNote()
   const envNote = envContext.note
   const sensitive = envContext.sensitive
-  const safe = <T extends FlyaiResult>(result: T): T => safeFlyaiResult(result, sensitive)
+  const safe = (result: FlyaiResult): FlyaiResult => safeFlyaiResult({ upstreamHealth: 'unknown', retryable: false, ...result }, sensitive)
   const built = buildCliArgs(q)
-  if (built.error) return { ...badArg(q.kind, built.error, ts), ...envNote }
+  if (built.error) return safe({ ...badArg(q.kind, built.error, ts), ...envNote })
 
   const prefix = q.cliPrefixArgs ?? ['-y', '@fly-ai/flyai-cli@1.0.16']
   const r = await sh(q.cliBin ?? 'npx', [...prefix, ...built.args!], {
@@ -769,7 +785,6 @@ export async function flyaiSearch(q: FlyaiQuery): Promise<FlyaiResult> {
     signal: q.signal,
   })
   const latencyMs = Date.now() - started
-  const combined = `${r.stderr}\n${r.stdout}`
 
   if (r.cancelled) {
     return safe({
@@ -797,37 +812,55 @@ export async function flyaiSearch(q: FlyaiQuery): Promise<FlyaiResult> {
     return safe(localTerminationResult(q.kind, r.localTermination, r, latencyMs, ts, envNote))
   }
 
-  if (r.error || r.code !== 0 || /HTTP\s*(4\d\d|5\d\d)/.test(combined)) {
+  if (r.error || r.code !== 0 || explicitUpstreamFailure(r.stderr)) {
     return safe(classifyUpstreamFailure(q.kind, r, latencyMs, ts, envNote))
   }
 
+  // Validate the response envelope before accepting inventory for any kind.
+  // A business status is not an HTTP status; successful data is never scanned
+  // for fault words (for example an AI answer quoting an HTTP error).
+  let envelope: Record<string, unknown>
+  try {
+    envelope = parseFlyaiJsonEnvelope(r.stdout, candidate => ['data', 'status', 'error'].some(key => Object.hasOwn(candidate, key))
+      || explicitUpstreamFailure(nonEmptyText(candidate.message) ?? ''))
+  } catch (e) {
+    if (explicitUpstreamFailure(r.stdout)) return safe(classifyUpstreamFailure(q.kind, r, latencyMs, ts, envNote))
+    const raw = r.stdout.replace(/\s+/g, ' ').slice(0, 160)
+    return safe({
+      kind: q.kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict: 'error',
+      evidence: `[实时API:flyai@error@${ts}] parse failed: ${raw}`,
+      error: `failed to parse flyai output (${(e as Error).message}): ${raw}`,
+    })
+  }
+  const systemMessage = nonEmptyText(envelope.systemMessage)
+  const envelopeFailure = `${nonEmptyText(envelope.message) ?? ''}\n${envelope.error == null ? '' : JSON.stringify(envelope.error)}`
+  if (explicitUpstreamFailure(envelopeFailure)) {
+    return safe(classifyUpstreamFailure(q.kind, { ...r, stdout: envelopeFailure }, latencyMs, ts, envNote))
+  }
+  if ((envelope.status !== undefined && envelope.status !== 0) || envelope.error != null) {
+    return safe({
+      kind: q.kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict: 'error',
+      evidence: `[实时API:flyai@error@${ts}] upstream response status=${String(envelope.status ?? 'unknown')}`,
+      error: nonEmptyText(envelope.message) ?? 'FlyAI upstream response rejected the query',
+      ...(systemMessage ? { systemMessage } : {}),
+    })
+  }
+
   // ai-search:data 是自由形状,不走 itemList。
   if (q.kind === 'ai') {
-    let envelope: Record<string, unknown>
-    try {
-      envelope = parseFlyaiJsonEnvelope(r.stdout)
-    } catch (e) {
-      const raw = r.stdout.replace(/\s+/g, ' ').slice(0, 160)
-      return safe({
-        kind: q.kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict: 'error',
-        evidence: `[实时API:flyai@error@${ts}] parse failed: ${raw}`,
-        error: `failed to parse flyai ai output (${(e as Error).message}): ${raw}`,
-      })
-    }
-    const systemMessage = nonEmptyText(envelope.systemMessage)
-    if (envelope.status !== undefined && envelope.status !== 0) {
+    if (!Object.hasOwn(envelope, 'data')) {
       return safe({
         kind: q.kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict: 'error',
-        evidence: `[实时API:flyai@error@${ts}] ai status=${String(envelope.status)}`,
-        error: nonEmptyText(envelope.message) ?? 'ai-search upstream failure',
+        evidence: `[实时API:flyai@error@${ts}] malformed ai response: missing data`,
+        error: 'FlyAI ai response malformed: missing data member',
         ...(systemMessage ? { systemMessage } : {}),
       })
     }
     const aiData = envelope.data
-    const empty = aiData === undefined || aiData === null || aiData === ''
+    const empty = aiData === null || aiData === ''
       || (Array.isArray(aiData) && aiData.length === 0)
     return safe(JSON.parse(JSON.stringify({
-      kind: q.kind, ...envNote, latencyMs, ok: true, via: 'flyai',
+      kind: q.kind, ...envNote, latencyMs, ok: true, via: 'flyai', upstreamHealth: 'healthy',
       verdict: empty ? 'miss' : 'hit',
       ...(empty ? {} : { aiData }),
       ...(systemMessage ? { systemMessage } : {}),
@@ -835,22 +868,10 @@ export async function flyaiSearch(q: FlyaiQuery): Promise<FlyaiResult> {
     })) as FlyaiResult)
   }
 
-  let items: unknown[]
-  try {
-    items = parseFlyaiItemList(r.stdout) as RawItem[]
-  } catch (e) {
+  const data = envelope.data as { itemList?: unknown } | null
+  if (!Array.isArray(data?.itemList)) {
     const raw = r.stdout.replace(/\s+/g, ' ').slice(0, 160)
-    // Sentinel 限流:exit 0,stdout 为 {"message":"SentinelBlockException…"}
-    if (/Sentinel/i.test(raw)) {
-      return safe({
-        kind: q.kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict: 'error',
-        retryable: false,
-        evidence: `[实时API:flyai@error@${ts}] sentinel: ${raw}`,
-        error: `FlyAI Sentinel 限流:${raw}`,
-        setup: '平台 Sentinel 限流(恢复窗口未公开)——稍后重试,或改走 gotry_session_search(账号会话)。',
-      })
-    }
-    const reason = (e as Error).message
+    const reason = 'no complete FlyAI itemList JSON object'
     return safe({
       kind: q.kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict: 'error',
       retryable: false,
@@ -859,7 +880,17 @@ export async function flyaiSearch(q: FlyaiQuery): Promise<FlyaiResult> {
     })
   }
 
-  return safe(parseItemListResult(q.kind, items, latencyMs, ts, envNote, r.stdout))
+  return safe(parseItemListResult(q.kind, data.itemList, latencyMs, ts, envNote, r.stdout))
+}
+
+// Explicit protocol/transport evidence only. Bare business codes and generic
+// words such as "network" or "timeout" do not diagnose an upstream outage.
+const HTTP_FAILURE = /\bHTTP(?:\/[\d.]+)?\s*[:=]?\s*([45]\d\d)\b/i
+const TRANSPORT_FAILURE = /\b(?:ETIMEDOUT|ECONNRESET|ECONNREFUSED|ECONNABORTED|EHOSTUNREACH|ENETUNREACH|EAI_AGAIN)\b|socket hang up|fetch failed|network (?:error|failure|unreachable)|(?:request|connection) (?:timed out|timeout|reset|refused)/i
+
+function explicitUpstreamFailure(text: string): boolean {
+  return HTTP_FAILURE.test(text) || TRANSPORT_FAILURE.test(text)
+    || /Invalid API key|Trial limit reached|SentinelBlockException/i.test(text)
 }
 
 /** 当前进程 key 来源/endpoint 覆盖(仅展示,与 spawn 实际生效同源) */
@@ -886,39 +917,47 @@ function classifyUpstreamFailure(
 ): FlyaiResult {
   const upstream = `${r.stderr}\n${r.stdout}`.replace(/\s+/g, ' ').trim()
   const tag = (verdict: FlyaiVerdict, evidence: string, extra: Partial<FlyaiResult>): FlyaiResult =>
-    ({ kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict, evidence, ...extra })
+    ({ kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict, upstreamHealth: 'unknown', evidence, ...extra })
+  const httpStatus = Number(HTTP_FAILURE.exec(upstream)?.[1])
 
-  if (/Invalid API key|HTTP\s*401|\b401\b/.test(upstream)) {
+  if (/Invalid API key/i.test(upstream) || httpStatus === 401) {
     return tag('auth-error', `[实时API:flyai@error@${ts}] 401 invalid api key`, {
       retryable: false,
       error: `FlyAI 鉴权失败(401):${upstream.slice(0, 160)}`,
       setup: '当前 key 无效或已吊销——在本机终端运行 `gotry setup flyai` 重新设置并验证(模型无法替你输入 key);`gotry setup flyai --clear` 可清除错误 key,清除后仍可匿名试用。',
     })
   }
-  if (/HTTP\s*403|\b403\b/.test(upstream)) {
+  if (httpStatus === 403) {
     return tag('forbidden', `[实时API:flyai@error@${ts}] 403 forbidden`, {
       retryable: false,
       error: `FlyAI 拒绝访问(403):${upstream.slice(0, 160)}`,
       setup: '上游 403:核对该 key 的权限范围与控制台状态;如 endpoint 被 DEBUG_FLYAI_MCP_URL 覆盖,请确认指向。',
     })
   }
-  if (/Trial limit reached/.test(upstream)) {
+  if (/Trial limit reached/i.test(upstream)) {
     return tag('needs-setup', `[实时API:flyai@error@${ts}] trial quota exhausted`, {
       retryable: false,
       error: `FlyAI 匿名试用额度已用尽:${upstream.slice(0, 160)}`,
       setup: '打开 https://flyai.open.fliggy.com/console，登录后复制 API Key,本机运行 `gotry setup flyai` 配置并验证;本会话请勿盲重试 gotry_flyai_search,机/火/酒改走 gotry_session_search。',
     })
   }
-  if (/HTTP\s*429|\b429\b/.test(upstream)) {
+  if (/SentinelBlockException/i.test(upstream)) {
+    return tag('error', `[实时API:flyai@error@${ts}] sentinel`, {
+      retryable: false, upstreamHealth: 'unhealthy',
+      error: `FlyAI Sentinel 限流:${upstream.slice(0, 160)}`,
+      setup: '平台 Sentinel 限流（恢复窗口未公开）；稍后重试，或改走 gotry_session_search（账号会话）。',
+    })
+  }
+  if (httpStatus === 429) {
     return tag('rate-limited', `[实时API:flyai@error@${ts}] 429 rate limited`, {
-      retryable: true,
+      retryable: true, upstreamHealth: 'unhealthy',
       error: `FlyAI 普通限流(非试用达限):${upstream.slice(0, 160)}`,
       setup: '上游普通限流:稍候再查,勿高频连发;仍 429 请稍后或换 gotry_session_search。',
     })
   }
-  if (/timeout|timed out|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ECONNABORTED|EHOSTUNREACH|ENETUNREACH|EAI_AGAIN|socket|network|fetch failed|HTTP\s*5\d\d|\b5\d\d\b/i.test(upstream)) {
+  if (TRANSPORT_FAILURE.test(upstream) || httpStatus >= 500) {
     return tag('error', `[实时API:flyai@error@${ts}] transient upstream`, {
-      retryable: true,
+      retryable: true, upstreamHealth: 'unhealthy',
       error: `FlyAI 瞬时网络/上游错误:${upstream.slice(0, 160)}`,
       setup: '网络抖动或上游 5xx:稍后重试;持续失败请检查本机网络或改走 gotry_session_search。',
     })
@@ -982,7 +1021,7 @@ function parseItemListResult(
   const count = parsed.options.length
   const verdict: FlyaiVerdict = count > 0 ? 'hit' : 'miss'
   const evidence = `[实时API:flyai@${ts}] ${count}/${items.length} ${KIND_LABEL[kind]} options`
-  const common = { kind, ...envNote, latencyMs, ok: true, via: 'flyai' as const, verdict, evidence, ...(systemMessage ? { systemMessage } : {}) }
+  const common = { kind, ...envNote, latencyMs, ok: true, via: 'flyai' as const, upstreamHealth: 'healthy' as const, verdict, evidence, ...(systemMessage ? { systemMessage } : {}) }
 
   switch (kind) {
     case 'flight':
@@ -1088,7 +1127,9 @@ function parseHotelItems(items: unknown[]): ParsedItems<FlyaiHotelOption> {
     }
     const it = raw as RawItem
     const name = nonEmptyText(it.name)
-    const star = stringField(it, 'star')
+    // Unrated homestays may return whitespace (live Harbin response).
+    // Only this optional descriptive field permits blank text; types stay strict.
+    const star = typeof it.star === 'string' && !it.star.trim() ? undefined : stringField(it, 'star')
     const rawPrice = stringField(it, 'price')
     const rate = it.rate === undefined ? undefined : it.rate === null ? null : nonEmptyText(it.rate) ?? 'bad'
     const address = stringField(it, 'address')

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: [] }
+}