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

package/dist/src/index.js

@@ -42,6 +42,8 @@ import { generateItineraryDeckExport } from '../capabilities/itinerary-deck-expo
 import { interpretEffect, declinedObservation } from '../capabilities/effect.js';
 import { customerSendCode, customerLogin } from '../capabilities/hbcli.js';
 import { FLYAI_POI_CATEGORIES } from '../capabilities/flyai.js';
+import { registerGotryWebApi } from './gotry-web-api.js';
+import { registerArtifactDeliveries } from './artifact-delivery.js';
 import { createFlyaiSetupTool } from './flyai-setup-tool.js';
 import { appendFacts, loadFactRegistry } from '../capabilities/fact-log.js';
 import { factsFromFlyai, factsFromHotel, factsFromSession, factsFromSessionTrain } from './bookable-facts.js';
@@ -429,6 +431,10 @@ export function apply(ctx, config, seams = {}) {
     // 固定 policy 保证评测可复现,不走路由。GOTRY_HANDOFF_CHILD=1 是收集器
     // 派生的后台规划会话:唯一出口 converge + 长 leash——前台转后台,后台
     // 必须产出最终交付物,不得再次 handoff(否则无限递归)。
+    if (!rawBenchmarkEnvironmentConfigPath) {
+        registerGotryWebApi(ctx, config.stateRoot ?? '.', config.hbcliBin);
+        registerArtifactDeliveries(ctx);
+    }
     const handoffChild = process.env.GOTRY_HANDOFF_CHILD === '1';
     installTurnDeadline(ctx, handoffChild
         ? { fixedPolicy: { softMs: 300_000, hardMs: 900_000, exit: 'converge' } }
@@ -1299,10 +1305,15 @@ export function apply(ctx, config, seams = {}) {
             const resp = itp.result;
             const dir = await ensureStateDir(config.stateRoot);
             const isLive = resp.via === 'hbcli-realtime';
-            const evidence = isLive ? resp.evidence : '[静态包:估算]';
+            const staticStays = resp.hotels?.stays;
+            const hasEstimate = Array.isArray(staticStays) && staticStays.length > 0;
+            const liveList = resp.hotels?.list;
+            const verdict = isLive ? (liveList?.length ? 'hit' : 'miss') : hasEstimate ? 'estimated' : 'error';
+            const evidence = hasEstimate ? '[静态包:估算]' : resp.evidence;
             await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `hotel_search:${resp.via}`).catch(() => { });
             const payload = {
-                ok: true,
+                ok: isLive || hasEstimate,
+                verdict,
                 hotels: resp.hotels ?? null,
                 evidence,
                 destination: q.destination,
@@ -1310,6 +1321,7 @@ export function apply(ctx, config, seams = {}) {
                 latency_ms: Date.now() - started,
                 summary: resp.summary,
                 error: resp.error,
+                ...(verdict !== 'hit' ? await routingField('search-hotel', 'hbcli-hotel') : {}),
                 ...(dateNotes.length ? { date_notes: dateNotes } : {}),
             };
             return JSON.parse(JSON.stringify(payload));
@@ -1336,13 +1348,14 @@ export function apply(ctx, config, seams = {}) {
                 };
             }
             const h = r.hotels;
-            const liveCount = Array.isArray(h) ? h.length : 0;
+            const liveList = h?.list;
+            const liveCount = Array.isArray(liveList) ? liveList.length : 0;
             // 静态包是 {meta, stays} 对象而非数组(issue #24:此前计数恒 0 → UI 显示「无结果」)
             const stays = !Array.isArray(h) && h && typeof h === 'object' ? h.stays : undefined;
             const staticCount = Array.isArray(stays) ? stays.length : 0;
             const tag = r.via === 'hbcli-realtime'
-                ? (liveCount ? `实时 ${liveCount} 家` : '实时')
-                : staticCount ? `静态包 ${staticCount} 块` : (liveCount ? `${liveCount} 家` : '无结果');
+                ? `实时 ${liveCount} 家`
+                : staticCount ? `静态包 ${staticCount} 块` : '查询未完成';
             return {
                 card: 'generic',
                 title: `酒店:${r.destination ?? ''} ${tag}`,
@@ -1725,8 +1738,9 @@ export function apply(ctx, config, seams = {}) {
         description: routed('gotry_session_search', 'Search on the USER\'S OWN browser session (Ctrip kind="flight"(default)/"hotel"; 12306 kind="train" — public query face, no login needed). '
             + 'Consent gate: the FIRST call in a session asks the user via the runtime approval card; once granted it holds for the session, a refusal revokes it for the session (no repeat prompting). '
             + 'Transport: Stai Travel Bridge browser extension (one-time install) — the agent side never talks to Chrome debugging, ZERO system dialogs; read-only by construction (the extension never issues requests; it only passively forwards the site\'s own search responses; agent NEVER touches credentials/captcha; on captcha it stops and returns challenged). '
-            + 'kind="flight": from/to 中文城市名 + date YYYY-MM-DD — sniffs the site search API for structured options. Evidence [会话:ctrip-flight@ts]. '
-            + 'kind="hotel": to=目的地中文, cityId? = the numeric city= in a hotels.ctrip.com list URL (web-search it when the destination is outside the built-in city table), checkIn?/checkOut? (YYYY-MM-DD), adults?; hotel prices are the user\'s real logged-in prices. Evidence [会话:ctrip-hotel@ts]. '
+            + 'kind="flight": from/to city or airport names (Chinese/English) + date YYYY-MM-DD; unknown names resolve from supplier metadata, ambiguous names require confirmation; optional fromCityCode/toCityCode are explicit Ctrip three-letter codes — sniffs the site search API for structured options. '
+            + 'ui?="bridge" (default; the user\'s own logged-in session, real member prices) | "gui" (gotry opens its OWN isolated anonymous Chrome window and drives the Ctrip PC search form — roundtrip via backDate? and ANY city by construction: the site\'s own autocomplete resolves cities; anonymous public prices, NOT logged-in prices; verdicts carry anonymous=true; result-binding iteration tracked in #661). Evidence [会话:ctrip-flight@ts] / [会话:ctrip-flight-gui@ts]. '
+            + 'kind="hotel": to=destination name, country? for same-name disambiguation; cityId? = explicit numeric city= from a Ctrip hotel list URL; otherwise resolves from the hotel destination service, checkIn?/checkOut? (YYYY-MM-DD), adults?; hotel prices are the user\'s real logged-in prices. Evidence [会话:ctrip-hotel@ts]. '
             + 'kind="dida": Dida supplier-portal realtime hotel rates on the employee\'s own logged-in session (hotel-be portal integration line) — no from/to needed; the portal find page\'s own requests are sniffed passively. Rates carry ratePlanId/referenceNo for the server-side booking chain. Evidence [会话:dida-portal@ts]. '
             + 'kind="train": from/to/date(YYYY-MM-DD) + fromStationTelecode?/toStationTelecode? (three-letter codes in the kyfw query URL, for cities outside the built-in table) — 12306 left-ticket query (public face): train codes, times, durations, seat availability; the list API carries NO prices (prices live on the 12306 page). Evidence [会话:train-12306@ts]. '
             + 'verdict needs-login = call gotry_session_login (opens the Ctrip login entry in the user\'s own foreground tab — no terminal, no credentials through GoTry); '
@@ -1739,15 +1753,20 @@ export function apply(ctx, config, seams = {}) {
         // execute 内归一后走原条件闸,结构化报错不崩。flyai 因 kind required 仍在宿主权即拒。
         parameters: {
             kind: { type: 'string', enum: ['flight', 'hotel', 'train', 'dida'], description: '默认 flight 机票;hotel 携程酒店(用户登录态真实价);train 12306 余票(公开面);dida 供应商门户实时价(员工登录态)' },
-            from: { type: 'string', description: '出发城市中文(词表内),如 上海——kind=flight|train 必填' },
+            from: { type: 'string', description: '出发城市名（机票支持中英文及机场名，自动解析），如 上海——kind=flight|train 必填' },
             to: { type: 'string', description: '到达城市中文——kind=flight|train 必填;kind=hotel 时为目的地(必填)' },
             date: { type: 'string', description: '出发日期 YYYY-MM-DD——kind=flight|train 必填,须为今天或未来' },
-            cityId: { type: 'integer', description: '携程酒店 city= 数字,仅 kind=hotel;目的地码表外时 web 搜 hotels.ctrip.com list URL 取 city=' },
+            fromCityCode: { type: 'string', description: '显式携程出发城市／机场三字码，仅 kind=flight；同名城市确认后使用' },
+            toCityCode: { type: 'string', description: '显式携程到达城市／机场三字码，仅 kind=flight；同名城市确认后使用' },
+            cityId: { type: 'integer', description: '显式携程酒店 city= 数字，仅 kind=hotel；未提供时自动解析酒店目的地，不能使用机票城市码' },
+            country: { type: 'string', description: '目的地国家中英文，仅 kind=hotel；用于同名城市消歧，例如 阿联酋' },
             checkIn: { type: 'string', description: '入住日 YYYY-MM-DD,仅 kind=hotel 可选' },
             checkOut: { type: 'string', description: '退房日 YYYY-MM-DD,仅 kind=hotel 可选' },
             adults: { type: 'integer', description: '成人数,仅 kind=hotel 可选' },
             fromStationTelecode: { type: 'string', description: '出发站三位电报码,仅 kind=train;城市码表外时填(kyfw 查询页 URL 里)' },
             toStationTelecode: { type: 'string', description: '到达站三位电报码,仅 kind=train,同上' },
+            backDate: { type: 'string', description: '回程日期 YYYY-MM-DD,仅 kind=flight;存在即往返检索——须 ui=gui(GUI 车道站点表单原生往返;bridge 车道不知往返 URL 形状,不猜)' },
+            ui: { type: 'string', enum: ['bridge', 'gui'], description: 'kind=flight|hotel:bridge(默认,用户登录态被动嗅探)|gui(gotry 隔离匿名窗口驱动 PC 表单——flight 往返/任意城市原生+低价日历;hotel 任意目的地原生(cityId 码表不在主链路);匿名公开价)' },
         },
         output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String(v.summary ?? JSON.stringify(v).slice(0, 600)) }] },
         async execute(args, _exec) {
@@ -1824,17 +1843,17 @@ export function apply(ctx, config, seams = {}) {
             }
             if (q.kind === 'hotel') {
                 if (!q.to) {
-                    return { ok: false, summary: 'kind=hotel 需要 to(目的地中文;城市码表外带 cityId=携程酒店 list 页 URL 里的 city= 数字)' };
+                    return { ok: false, summary: 'kind=hotel 需要 to（目的地名称）；自动解析城市，同名城市可带 country 或确认后的 cityId' };
                 }
                 const itp = await runSessionEffect({
-                    effect: 'SESSION_HOTEL_SEARCH',
+                    effect: q.ui === 'gui' ? 'SESSION_HOTEL_GUI_SEARCH' : 'SESSION_HOTEL_SEARCH',
                     params: {
-                        to: q.to, cityId: q.cityId, checkIn: q.checkIn, checkOut: q.checkOut, adults: q.adults,
+                        to: q.to, country: q.country, cityId: q.cityId, checkIn: q.checkIn, checkOut: q.checkOut, adults: q.adults,
                         auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
                     },
                 });
                 if (!itp.result)
-                    return declinedObservation('SESSION_HOTEL_SEARCH', itp.trace);
+                    return declinedObservation(q.ui === 'gui' ? 'SESSION_HOTEL_GUI_SEARCH' : 'SESSION_HOTEL_SEARCH', itp.trace);
                 const r = itp.result;
                 await noteChannel('session:ctrip-hotel', r.verdict);
                 // D-26(issue #118):exact-date 会话酒店 hit/miss 落账(摸底无档期不落;cooldown 是节律闸非结论,不落)
@@ -1856,14 +1875,19 @@ export function apply(ctx, config, seams = {}) {
                 }));
             }
             if (!q.from || !q.to || !q.date) {
-                return { ok: false, summary: '需要 from/to(中文城市名,词表内)与 date(YYYY-MM-DD);酒店/火车检索分别用 kind=hotel / kind=train' };
+                return { ok: false, summary: '需要 from/to（城市或机场名）与 date（YYYY-MM-DD）;酒店/火车检索分别用 kind=hotel / kind=train' };
             }
             // 效应解译层(ADR-18):SESSION 通道策略=永不重试/不熔断,节律闸在渠道内;
             // 解译器只做分发与证据拼装,verdict 语义(risk 型 needs-login/challenged)原样透传
+            // GUI 车道(2026-10-14):ui=gui → gotry 隔离匿名窗口驱动 PC 表单(往返 backDate/任意城市原生)。
+            if (q.ui !== undefined && q.ui !== 'bridge' && q.ui !== 'gui') {
+                return { ok: false, summary: 'kind=flight 的 ui 只接受 bridge(默认,登录态被动嗅探)|gui(隔离匿名窗口驱动表单)' };
+            }
             const itp = await runSessionEffect({
-                effect: 'SESSION_FLIGHT_SEARCH',
+                effect: q.ui === 'gui' ? 'SESSION_FLIGHT_GUI_SEARCH' : 'SESSION_FLIGHT_SEARCH',
                 params: {
-                    from: q.from, to: q.to, date: q.date,
+                    from: q.from, to: q.to, date: q.date, fromCityCode: q.fromCityCode, toCityCode: q.toCityCode,
+                    ...(q.backDate ? { backDate: q.backDate } : {}),
                     // ADR-15 收尾:ReadGuard 审计在生产工具路径同样落盘(此前仅测试传隔离 stateRoot 才有 JSONL)
                     auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
                 },
@@ -1876,8 +1900,12 @@ export function apply(ctx, config, seams = {}) {
             const avMapS = await loadAirlineAirportMap();
             await appendFacts(config.stateRoot ?? '.', factsFromSession({ origin: q.from, destination: q.to, date: q.date }, r, new Date().toISOString(), avMapS?.city_alias));
             const top = (r.options ?? []).slice(0, 8).map(o => `${o.flightNo} ${o.airline} ${o.depDateTime.slice(11, 16)}→${o.arrDateTime.slice(11, 16)} ¥${o.price}`);
+            const lane = q.ui === 'gui' ? `GUI 车道(携程,匿名公开价${q.backDate ? ',往返' : ''})` : '会话检索(携程,用户本人登录态)';
+            const cal = (r.calendar ?? []).slice(0, 14).map(d => `${d.date} ${d.price !== undefined ? `¥${d.price}` : (d.priceRaw ?? '?')}`);
+            const calBlock = cal.length > 0 ? `\n低价日历(匿名公开价,该航线哪些日期有票):\n${cal.join(' | ')}` : '';
+            const urlBlock = q.ui === 'gui' && r.listUrl ? `\nlistUrl(站点真实形状,#663 URL 教师):${r.listUrl.slice(0, 160)}` : '';
             const summary = r.verdict === 'hit'
-                ? `${q.from}→${q.to} ${q.date} 会话检索(携程,用户本人登录态)前 ${top.length} 条:\n${top.join('\n')}\n${r.evidence}`
+                ? `${q.from}→${q.to} ${q.date} ${lane}${(r.options ?? []).length > 0 ? ` 行情前 ${top.length} 条:\n${top.join('\n')}` : ''}${calBlock}${urlBlock}\n${r.evidence}`
                 : `会话检索未取回(${r.verdict}):${r.error ?? ''} ${r.evidence}`;
             return JSON.parse(JSON.stringify({
                 ...r, summary,

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Stai Travel Bridge",
-  "version": "0.2.0.30",
+  "version": "0.2.0.32",
   "description": "Stai 连接获准的旅行检索与供应商门户：检索结果经本机或授权后端桥接；门户可触发一次性登录代填，扩展不持久保存凭据。",
   "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnuzBX8rT8+RZKEUip5VRA0cY056pExy9PNdN9YCiuY3dgglRbcIBhjuFJoR6EX3/MaUv82vJVyItRVrowXLTwDk4WZof0vwFgKL0zBK304PC46pUaAKTSu1PgXeL1+j5KTAGz/9a9+RnPdbj7jND5rM/MOmBHNPVPpp1NlwxRGIgF9OxHSOfXORcH4Iyte1aJSFUJbFtNS/DaE5D+KjyupPLyIqVN/dCiKnNsTCEHQB9ngeli665PFp76hkccHQQZ4sVuMLS4zBPcazUsp1kcnW+xsQoUATkODTCY+Pzk3zUVF1QOESTjRCVnbNi8tkO43RMRs2q63gX/3inFivcEwIDAQAB",
   "permissions": [
@@ -56,5 +56,5 @@
       "run_at": "document_start"
     }
   ],
-  "version_name": "0.2.0-rc.30"
+  "version_name": "0.2.0-rc.32"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danceiny/gotry",
-  "version": "0.2.0-rc.30",
+  "version": "0.2.0-rc.32",
   "description": "GoTry — 从出发到下一次出发的 AI 旅行 Agent(dsh 插件)。npm/源码入口共用锁定的 dsh runtime + README 安装路径。",
   "type": "module",
   "main": "ts/src/index.ts",
@@ -44,7 +44,10 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-tool"
+        "@deepseek-ai/dsh-client-ui-tool",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
       ]
     }
   },
@@ -57,6 +60,8 @@
     "bin/",
     "ts/src/index.ts",
     "ts/src/flyai-setup-tool.ts",
+    "ts/src/gotry-web-api.ts",
+    "ts/src/artifact-delivery.ts",
     "ts/src/subagent-job-id-guard.ts",
     "ts/src/benchmark-environment-bridge.ts",
     "ts/src/benchmark-tool-isolation.ts",
@@ -110,6 +115,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')