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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danceiny/gotry",
-  "version": "0.2.0-rc.31",
+  "version": "0.2.0-rc.33",
   "description": "GoTry — 从出发到下一次出发的 AI 旅行 Agent(dsh 插件)。npm/源码入口共用锁定的 dsh runtime + README 安装路径。",
   "type": "module",
   "main": "ts/src/index.ts",
@@ -101,6 +101,9 @@
     "schemas/booking.surface.schema.json",
     "schemas/booking.intent.schema.json",
     "ts/src/booking-surface/",
+    "ts/src/tenant-seam/",
+    "ts/src/tenant-state/",
+    "ts/src/llm-price-table.ts",
     "ts/scripts/skeleton-check.ts",
     "ts/scripts/skeleton-integration-test.ts",
     "ts/scripts/async-collect.ts",
@@ -115,6 +118,7 @@
     "ts/capabilities/opensky.ts",
     "ts/capabilities/flyai.ts",
     "ts/capabilities/flyai-config.ts",
+    "ts/capabilities/hbcli-config.ts",
     "ts/capabilities/session-search.ts",
     "ts/capabilities/session/",
     "extension/",

package/ts/capabilities/flyai-config.ts

@@ -185,22 +185,22 @@ export function verifySecureMode(dir: string, file: string): { ok: boolean; erro
 /**
  * 官方 CLI 1.0.16 首次运行可能先创建 ~/.flyai 为 0755，并在其中写入
  * 0600 device-id。仅对当前用户拥有且本身不是 symlink 的配置目录收紧到
- * 0700；验证回执所在 ~/.gotry 仍严格拒绝既有 0755 目录。
+ * 0700。回执所在 ~/.gotry 采用相同迁移规则，兼容 doctor 创建的目录。
  */
-function prepareFlyaiConfigDir(dir: string, file: string): { ok: boolean; error?: string; unsupported?: boolean } {
+function preparePrivateDir(dir: string, file: string): { ok: boolean; error?: string; unsupported?: boolean } {
   if (process.platform === 'win32') return { ok: false, unsupported: true, error: 'Windows 无 0700/0600 权限位,安全写不支持' }
   try {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
     const entry = lstatSync(dir)
-    if (entry.isSymbolicLink()) return { ok: false, error: '.flyai 目录是符号链接,拒绝写入' }
-    if (!entry.isDirectory()) return { ok: false, error: '.flyai 路径不是目录,拒绝写入' }
+    if (entry.isSymbolicLink()) return { ok: false, error: '配置目录是符号链接,拒绝写入' }
+    if (!entry.isDirectory()) return { ok: false, error: '配置路径不是目录,拒绝写入' }
     if (typeof process.getuid === 'function' && entry.uid !== process.getuid()) {
-      return { ok: false, error: '.flyai 目录不属于当前用户,拒绝写入' }
+      return { ok: false, error: '配置目录不属于当前用户,拒绝写入' }
     }
     if ((entry.mode & 0o777) !== 0o700) chmodSync(dir, 0o700)
     const after = lstatSync(dir)
-    if (after.isSymbolicLink() || !after.isDirectory()) return { ok: false, error: '.flyai 目录状态发生变化,拒绝写入' }
-    if (typeof process.getuid === 'function' && after.uid !== process.getuid()) return { ok: false, error: '.flyai 目录所有者发生变化,拒绝写入' }
+    if (after.isSymbolicLink() || !after.isDirectory()) return { ok: false, error: '配置目录状态发生变化,拒绝写入' }
+    if (typeof process.getuid === 'function' && after.uid !== process.getuid()) return { ok: false, error: '配置目录所有者发生变化,拒绝写入' }
     return verifySecureMode(dir, file)
   } catch (e) {
     return { ok: false, error: (e as Error).message }
@@ -259,7 +259,7 @@ export function saveFlyaiKey(key: string, opts: FlyaiConfigPaths = {}): SaveFlya
   const read = readFlyaiConfig(configPath)
   if (!read.ok) return { ok: false, error: `原配置损坏,已拒绝覆盖(${read.error});请先人工修复 ${configPath}` }
 
-  const configDir = prepareFlyaiConfigDir(dirname(configPath), configPath)
+  const configDir = preparePrivateDir(dirname(configPath), configPath)
   if (!configDir.ok) return { ok: false, error: configDir.error }
   const write = atomicWriteJson(configPath, { ...read.data, FLYAI_API_KEY: text })
   if (!write.ok) return { ok: false, error: write.error }
@@ -297,7 +297,7 @@ export function clearFlyaiKey(opts: FlyaiConfigPaths = {}): ClearFlyaiKeyResult
         return { ok: false, source: 'none', error: `移除文件失败:${(e as Error).message}` }
       }
     } else {
-      const configDir = prepareFlyaiConfigDir(dirname(configPath), configPath)
+      const configDir = preparePrivateDir(dirname(configPath), configPath)
       if (!configDir.ok) return { ok: false, source: 'none', error: configDir.error }
       const write = atomicWriteJson(configPath, next)
       if (!write.ok) return { ok: false, source: 'none', error: write.error }
@@ -355,7 +355,9 @@ export function readFlyaiVerification(homeDir: string): FlyaiVerification | unde
 
 /** 原子写验证记录(权限硬校验);成功=true;失败不抛错 */
 export function writeFlyaiVerification(entry: FlyaiVerification, homeDir: string): boolean {
-  return atomicWriteJson(flyaiVerificationPath(homeDir), entry).ok
+  const path = flyaiVerificationPath(homeDir)
+  const prepared = preparePrivateDir(dirname(path), path)
+  return prepared.ok && atomicWriteJson(path, entry).ok
 }
 
 export function removeFlyaiVerification(homeDir: string): void {

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