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

package/dist/capabilities/effect.js

@@ -23,9 +23,9 @@
  * 本层只让「每条通道」更可替换、可熔断、可 mock。
  */
 import { CircuitBreaker, withRetry, } from './resilience.js';
-import { flyaiSearch } from './flyai.js';
+import { flyaiBreakerScope, flyaiSearch } from './flyai.js';
 import { checkAvail, hotelRates, searchHotels } from './hbcli.js';
-import { sessionFlightSearch, sessionHotelSearch, sessionTrainSearch, sessionDidaSearch } from './session-search.js';
+import { sessionFlightSearch, sessionFlightGuiSearch, sessionHotelGuiSearch, sessionHotelSearch, sessionTrainSearch, sessionDidaSearch } from './session-search.js';
 import { geocodePlace, getClimate, getForecast } from './weather.js';
 import { verifyFlight } from './opensky.js';
 import { anythingSearch } from './anything.js';
@@ -86,8 +86,12 @@ const DEFAULT_HANDLERS = {
     HBCLI_CHECK_AVAIL: (p) => checkAvail({ ratePkgId: p.ratePkgId }, { hbcliBin: p.hbcliBin, timeoutMs: p.timeoutMs }),
     /** 用户本人登录态会话检索(浏览器解译通道:扩展桥默认 + cdp 显式后备;ReadGuard+节律闸) */
     SESSION_FLIGHT_SEARCH: (p) => sessionFlightSearch(p),
+    /** 携程机票 GUI 车道(2026-10-14 实装;gotry 隔离匿名窗口驱动 PC 表单,往返/任意城市原生;匿名公开价) */
+    SESSION_FLIGHT_GUI_SEARCH: (p) => sessionFlightGuiSearch(p),
     /** 用户本人登录态会话酒店检索(2026-09-03 实装;同浏览器解译通道,风控红线同款) */
     SESSION_HOTEL_SEARCH: (p) => sessionHotelSearch(p),
+    /** 携程酒店 GUI 车道(2026-10-14 实装,#664;匿名窗口驱动表单,cityId 码表退出主链路) */
+    SESSION_HOTEL_GUI_SEARCH: (p) => sessionHotelGuiSearch(p),
     /** 12306 余票会话检索(2026-09-03 实装;公开查询面,无登录闸;同浏览器解译通道) */
     SESSION_TRAIN_SEARCH: (p) => sessionTrainSearch(p),
     /** Dida 供应商门户实时价会话检索(2026-09-09 实装;hotel-be portal integration 迁移线) */
@@ -133,8 +137,8 @@ const hbcliTimeout = (r) => {
 const HBCLI_RETRY = { maxAttempts: 2, baseDelayMs: 300, maxDelayMs: 1_000 };
 /**
  * 渠道韧性策略表(权威面;docs/design/effect-interpreter.md §3 同表逐行有依据):
- *   - FLYAI:瞬时代码级错误重试 1 次;连续 3 次 error(含 Sentinel)熔断 60s 保护配额;
- *     试用额度达限(429)归 needs-setup,永不重试;
+ *   - FLYAI:明确瞬时故障重试 1 次；同 kind/endpoint/key 连续 3 次明确
+ *     上游健康故障（含 Sentinel）熔断 60s；业务、配置与未知失败不计熔断；
  *   - HBCLI:仅 timeout 类失败重试 1 次(冷启动建后端 session 可超时,重试即恢复);
  *     ENOENT/退码类永不重试(上游契约「候选路径是切换不是重试」),熔断同上;
  *     RATES/CHECK_AVAIL 同族,且价格面无静态降级(fail-closed,不估算房价——
@@ -159,7 +163,12 @@ const SPECS = {
             // Only explicit transient classification permits retry; terminal failures stay final.
             return result?.retryable === true;
         },
-        isFailure: defaultIsFailure,
+        isFailure: r => r?.upstreamHealth === 'unhealthy',
+        isNeutral: r => {
+            const health = r?.upstreamHealth;
+            return health !== 'healthy' && health !== 'unhealthy';
+        },
+        breakerScope: p => flyaiBreakerScope(p?.kind),
     },
     HBCLI_HOTEL_SEARCH: {
         channel: 'cli',
@@ -190,12 +199,24 @@ const SPECS = {
         breaker: null,
         isFailure: defaultIsFailure,
     },
+    SESSION_FLIGHT_GUI_SEARCH: {
+        channel: 'browser',
+        retry: null,
+        breaker: null,
+        isFailure: defaultIsFailure,
+    },
     SESSION_HOTEL_SEARCH: {
         channel: 'browser',
         retry: null,
         breaker: null,
         isFailure: defaultIsFailure,
     },
+    SESSION_HOTEL_GUI_SEARCH: {
+        channel: 'browser',
+        retry: null,
+        breaker: null,
+        isFailure: defaultIsFailure,
+    },
     SESSION_TRAIN_SEARCH: {
         channel: 'browser',
         retry: null,
@@ -286,9 +307,12 @@ export function declinedObservation(effect, trace) {
         summary: trace.declined === 'aborted'
             ? `${effect} 检索已取消，未产生新的查询结果。`
             : trace.declined === 'circuit-open'
-                ? `${effect} 通道被断路器开启保护(连续失败达到阈值,冷却中)——不要立即重试,换其他工具或稍后再试;原因见 trace 证据链`
+                ? trace.breaker === 'half-open'
+                    ? `${effect} 通道的恢复探测正在进行；等待当前探测结果后再查询，或使用其他工具。`
+                    : `${effect} 通道被断路器开启保护（连续上游故障达到阈值，冷却中）；${typeof trace.retryAfterMs === 'number' ? `约 ${Math.ceil(trace.retryAfterMs / 1_000)} 秒后可发起恢复探测` : '稍后可发起恢复探测'}，当前可使用其他工具。`
                 : `${effect} 未登记效应(effect_interpreter.v1 注册表外,生产解译器拒绝)`,
         evidence: trace.evidence.join(';'),
+        ...(trace.retryAfterMs !== undefined ? { retryAfterMs: trace.retryAfterMs } : {}),
     };
 }
 const defaultBreakers = new Map();
@@ -314,16 +338,18 @@ export function makeProductionInterpreter(opts = {}) {
         const br = (() => {
             if (!spec.breaker)
                 return null;
-            const existing = breakers.get(fx.effect);
+            const key = spec.breakerScope ? `${fx.effect}:${spec.breakerScope(fx.params)}` : fx.effect;
+            const existing = breakers.get(key);
             if (existing)
                 return existing;
             const created = new CircuitBreaker({ ...spec.breaker, ...(opts.now ? { now: opts.now } : {}) });
-            breakers.set(fx.effect, created);
+            breakers.set(key, created);
             return created;
         })();
         const gate = br?.canAttempt() ?? { allowed: true, state: 'closed', token: undefined };
         if (!gate.allowed) {
-            const trace = { effect: fx.effect, channel: spec.channel, attempts: 0, backoffMs: 0, breaker: gate.state, declined: 'circuit-open', evidence: [`[效应:${fx.effect}@${ts}] breaker=${gate.state} 拒绝(冷却中,不重试)`] };
+            const retryAfterMs = 'retryAfterMs' in gate ? gate.retryAfterMs : undefined;
+            const trace = { effect: fx.effect, channel: spec.channel, attempts: 0, backoffMs: 0, breaker: gate.state, declined: 'circuit-open', ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), evidence: [`[效应:${fx.effect}@${ts}] breaker=${gate.state} 拒绝${retryAfterMs !== undefined ? ` retryAfterMs=${retryAfterMs}` : '（恢复探测在途）'}`] };
             return { result: null, trace };
         }
         const policy = spec.retry
@@ -346,9 +372,16 @@ export function makeProductionInterpreter(opts = {}) {
             };
             return { result: null, trace: abortedTrace };
         }
-        const failed = outcome.error != null || spec.isFailure(outcome.result);
-        if (br)
-            failed ? br.onFailure(gate.token) : br.onSuccess(gate.token);
+        const neutral = spec.isNeutral?.(outcome.result, outcome.error) === true;
+        const failed = !neutral && (outcome.error != null || spec.isFailure(outcome.result));
+        if (br) {
+            if (neutral)
+                br.releaseProbe(gate.token);
+            else if (failed)
+                br.onFailure(gate.token);
+            else
+                br.onSuccess(gate.token);
+        }
         const breakerState = br?.state() ?? 'off';
         const evidence = [`[效应:${fx.effect}@${ts}] attempts=${outcome.attempts} backoff=${outcome.backoffMs}ms breaker=${breakerState}`];
         return {

package/dist/capabilities/flyai-config.js

@@ -134,9 +134,9 @@ export function verifySecureMode(dir, file) {
 /**
  * 官方 CLI 1.0.16 首次运行可能先创建 ~/.flyai 为 0755，并在其中写入
  * 0600 device-id。仅对当前用户拥有且本身不是 symlink 的配置目录收紧到
- * 0700；验证回执所在 ~/.gotry 仍严格拒绝既有 0755 目录。
+ * 0700。回执所在 ~/.gotry 采用相同迁移规则，兼容 doctor 创建的目录。
  */
-function prepareFlyaiConfigDir(dir, file) {
+function preparePrivateDir(dir, file) {
     if (process.platform === 'win32')
         return { ok: false, unsupported: true, error: 'Windows 无 0700/0600 权限位,安全写不支持' };
     try {
@@ -144,19 +144,19 @@ function prepareFlyaiConfigDir(dir, file) {
             mkdirSync(dir, { recursive: true, mode: 0o700 });
         const entry = lstatSync(dir);
         if (entry.isSymbolicLink())
-            return { ok: false, error: '.flyai 目录是符号链接,拒绝写入' };
+            return { ok: false, error: '配置目录是符号链接,拒绝写入' };
         if (!entry.isDirectory())
-            return { ok: false, error: '.flyai 路径不是目录,拒绝写入' };
+            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 目录状态发生变化,拒绝写入' };
+            return { ok: false, error: '配置目录状态发生变化,拒绝写入' };
         if (typeof process.getuid === 'function' && after.uid !== process.getuid())
-            return { ok: false, error: '.flyai 目录所有者发生变化,拒绝写入' };
+            return { ok: false, error: '配置目录所有者发生变化,拒绝写入' };
         return verifySecureMode(dir, file);
     }
     catch (e) {
@@ -225,7 +225,7 @@ export function saveFlyaiKey(key, opts = {}) {
     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 });
@@ -267,7 +267,7 @@ export function clearFlyaiKey(opts = {}) {
             }
         }
         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);
@@ -303,7 +303,9 @@ export function readFlyaiVerification(homeDir) {
 }
 /** 原子写验证记录(权限硬校验);成功=true;失败不抛错 */
 export function writeFlyaiVerification(entry, homeDir) {
-    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) {
     try {

package/dist/capabilities/flyai.js

@@ -31,7 +31,7 @@
 import { closeSync, openSync, readFileSync, unlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { resolveFlyaiEndpoint, resolveFlyaiKey } from './flyai-config.js';
+import { normalizeEndpoint, resolveFlyaiEndpoint, resolveFlyaiKey, sha256Hex } from './flyai-config.js';
 import { spawnBounded } from './spawn-bounded.js';
 function nonEmptyText(value) {
     if (typeof value !== 'string')
@@ -132,7 +132,7 @@ export function parseFlyaiItemList(stdout) {
         : 'no complete FlyAI itemList JSON object');
 }
 /** 解析 stdout 中首个完整 JSON 对象(不限 itemList;ai-search 用) */
-export function parseFlyaiJsonEnvelope(stdout) {
+export function parseFlyaiJsonEnvelope(stdout, accepts = () => true) {
     let start = -1;
     let depth = 0;
     let inString = false;
@@ -166,12 +166,13 @@ export function parseFlyaiJsonEnvelope(stdout) {
             if (depth === 0) {
                 const candidate = stdout.slice(start, index + 1);
                 try {
-                    return JSON.parse(candidate);
-                }
-                catch {
-                    start = -1;
-                    depth = 0;
+                    const parsed = JSON.parse(candidate);
+                    if (accepts(parsed))
+                        return parsed;
                 }
+                catch { /* prefix logs may contain balanced non-JSON braces */ }
+                start = -1;
+                depth = 0;
             }
         }
     }
@@ -463,6 +464,14 @@ const KIND_LABEL = {
     flight: 'flight', train: 'train', hotel: 'hotel', poi: 'poi',
     keyword: 'keyword', ai: 'ai', 'marriott-hotel': 'marriott hotel', 'marriott-package': 'marriott package',
 };
+/** 每种检索 × 生效 endpoint/key 隔离；Map 中只留下不可逆指纹。 */
+export function flyaiBreakerScope(kind) {
+    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 命令)— 任何失败走降级;不抛错。
  */
@@ -472,10 +481,10 @@ export async function flyaiSearch(q) {
     const envContext = await runtimeEnvNote();
     const envNote = envContext.note;
     const sensitive = envContext.sensitive;
-    const safe = (result) => safeFlyaiResult(result, sensitive);
+    const safe = (result) => safeFlyaiResult({ upstreamHealth: 'unknown', retryable: false, ...result }, sensitive);
     const built = buildCliArgs(q);
     if (built.error)
-        return { ...badArg(q.kind, built.error, ts), ...envNote };
+        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], {
         timeoutMs: q.timeoutMs ?? 30_000,
@@ -483,7 +492,6 @@ export async function flyaiSearch(q) {
         signal: q.signal,
     });
     const latencyMs = Date.now() - started;
-    const combined = `${r.stderr}\n${r.stdout}`;
     if (r.cancelled) {
         return safe({
             kind: q.kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict: 'cancelled',
@@ -507,60 +515,65 @@ export async function flyaiSearch(q) {
     if (r.localTermination) {
         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;
+    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.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;
-        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.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 } : {}),
             evidence: `[实时API:flyai@${ts}] ai-search ${empty ? 'empty' : 'data returned'}`,
         })));
     }
-    let items;
-    try {
-        items = parseFlyaiItemList(r.stdout);
-    }
-    catch (e) {
+    const data = envelope.data;
+    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.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,
@@ -568,7 +581,15 @@ export async function flyaiSearch(q) {
             error: `failed to parse flyai output (${reason}): ${raw}`,
         });
     }
-    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) {
+    return HTTP_FAILURE.test(text) || TRANSPORT_FAILURE.test(text)
+        || /Invalid API key|Trial limit reached|SentinelBlockException/i.test(text);
 }
 /** 当前进程 key 来源/endpoint 覆盖(仅展示,与 spawn 实际生效同源) */
 async function runtimeEnvNote() {
@@ -587,38 +608,46 @@ async function runtimeEnvNote() {
 /** 非 0 退出 / HTTP 4xx-5xx 文本 → 故障闭集分类 */
 function classifyUpstreamFailure(kind, r, latencyMs, ts, envNote) {
     const upstream = `${r.stderr}\n${r.stdout}`.replace(/\s+/g, ' ').trim();
-    const tag = (verdict, evidence, extra) => ({ kind, ...envNote, latencyMs, ok: false, via: 'flyai-error', verdict, evidence, ...extra });
-    if (/Invalid API key|HTTP\s*401|\b401\b/.test(upstream)) {
+    const tag = (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/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。',
         });
@@ -676,7 +705,7 @@ function parseItemListResult(kind, items, latencyMs, ts, envNote, rawStdout) {
     const count = parsed.options.length;
     const verdict = 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', verdict, evidence, ...(systemMessage ? { systemMessage } : {}) };
+    const common = { kind, ...envNote, latencyMs, ok: true, via: 'flyai', upstreamHealth: 'healthy', verdict, evidence, ...(systemMessage ? { systemMessage } : {}) };
     switch (kind) {
         case 'flight':
         case 'train':
@@ -781,7 +810,9 @@ function parseHotelItems(items) {
         }
         const it = raw;
         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/dist/capabilities/hbcli-config.js

@@ -0,0 +1,156 @@
+/** 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.js';
+import { hbcliBinCandidates } from './hbcli.js';
+import { spawnBounded } from './spawn-bounded.js';
+export const HBCLI_REGISTRATION_URL = 'https://hotelbyte.com/zh/guides/sandbox-verification';
+const ENVIRONMENT = 'uat';
+const ENTRY = `openapi:${ENVIRONMENT}`;
+export function hbcliCredentialRoot(options) {
+    return options.env?.STAICLI_HOME?.trim() || join(options.homeDir ?? homedir(), '.staicli');
+}
+export function hbcliCredentialPath(options) { return join(hbcliCredentialRoot(options), 'credentials.json'); }
+export function hbcliVerificationPath(homeDir) { return join(homeDir, '.gotry', 'hbcli-verification.json'); }
+function safeEntry(path, directory) {
+    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.code === 'ENOENT';
+    }
+}
+export function readHbcliCredentials(options) {
+    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 = JSON.parse(bytes);
+        return data && typeof data === 'object' && !Array.isArray(data) ? { ok: true, data: data, bytes } : { ok: false };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function fingerprint(data) {
+    const entry = data[ENTRY];
+    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) {
+    try {
+        const path = hbcliVerificationPath(home);
+        if (!safeEntry(join(home, '.gotry'), true) || !safeEntry(path, false))
+            return undefined;
+        const v = JSON.parse(readFileSync(path, 'utf8'));
+        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) {
+    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) {
+    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, options) {
+    const path = hbcliCredentialPath(options);
+    return readHbcliCredentials(options).ok && prepareDirectory(hbcliCredentialRoot(options)) && atomicWriteJson(path, data).ok;
+}
+export function writeHbcliVerification(data, verdict, options) {
+    const hash = fingerprint(data), home = options.homeDir ?? homedir();
+    if (!hash || !prepareDirectory(join(home, '.gotry')))
+        return false;
+    const entry = { 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) {
+    if (safeEntry(join(homeDir, '.gotry'), true) && safeEntry(hbcliVerificationPath(homeDir), false)) {
+        try {
+            rmSync(hbcliVerificationPath(homeDir), { force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+export function withHbcliCredentials(data, appKey, appSecret) {
+    return { ...data, [ENTRY]: { appKey, appSecret } };
+}
+export function withoutHbcliCredentials(data) {
+    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, appSecret, options, signal) {
+    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 = { ...(options.env ?? process.env), STAICLI_HOME: root, HOTELBYTE_ENV: ENVIRONMENT };
+        delete env.HOTELBYTE_TOKEN;
+        let result;
+        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;
+        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 });
+    }
+}