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

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 });
+    }
+}

package/dist/capabilities/hbcli.js

@@ -65,6 +65,24 @@ async function attemptHbcli(bin, args, opts) {
         }
         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?.code;
+    const invalid = result === null;
+    const upstreamFailure = code !== undefined && code !== 0 && code !== '0';
+    if (invalid || upstreamFailure) {
+        const msg = result?.msg
+            ?? result?.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}]`,
@@ -138,7 +156,7 @@ export async function searchHotels(query, opts = {}) {
         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();
@@ -149,6 +167,15 @@ export async function searchHotels(query, opts = {}) {
             latencyMs: live.latencyMs, error: `aborted by host signal${cleanupError}`, summary: `酒店「${query.destination}」检索已取消,未产生事实`,
         };
     }
+    const list = live.result?.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 实锤)。
@@ -247,7 +274,7 @@ export async function checkAvail(query, opts = {}) {
  * ~/.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(email, opts = {}) {

package/dist/capabilities/resilience.js

@@ -108,7 +108,7 @@ export async function withRetry(fn, policy, onBackoff) {
 export class CircuitBreaker {
     o;
     consecutiveFailures = 0;
-    openedAt = 0;
+    openedAt = null;
     generation = 0;
     nextTokenId = 0;
     probeToken = null;
@@ -122,9 +122,9 @@ export class CircuitBreaker {
         return (this.o.now ?? Date.now)();
     }
     state() {
-        if (this.openedAt > 0 && this.now() - this.openedAt >= this.o.openMs)
+        if (this.openedAt !== null && this.now() - this.openedAt >= this.o.openMs)
             return 'half-open';
-        if (this.openedAt > 0)
+        if (this.openedAt !== null)
             return 'open';
         return 'closed';
     }
@@ -134,7 +134,7 @@ export class CircuitBreaker {
         if (s === 'closed')
             return { allowed: true, state: s, token: this.makeToken(false) };
         if (s === 'open')
-            return { allowed: false, state: s };
+            return { allowed: false, state: s, retryAfterMs: Math.max(0, Math.min(this.o.openMs, this.o.openMs - (this.now() - this.openedAt))) };
         // half-open:单探测语义——已有探测在途拒其余并发
         if (this.probeToken)
             return { allowed: false, state: s };
@@ -158,7 +158,7 @@ export class CircuitBreaker {
         if (!this.owns(token))
             return;
         this.consecutiveFailures = 0;
-        this.openedAt = 0;
+        this.openedAt = null;
         if (token?.probe === true || (!token && this.probeToken !== null)) {
             this.probeToken = null;
             this.generation += 1;
@@ -171,7 +171,7 @@ export class CircuitBreaker {
         if (token?.probe === true || (!token && this.probeToken !== null))
             this.probeToken = null;
         this.consecutiveFailures += 1;
-        if (this.openedAt > 0 || this.consecutiveFailures >= this.threshold()) {
+        if (this.openedAt !== null || this.consecutiveFailures >= this.threshold()) {
             this.openedAt = this.now();
             this.generation += 1;
         }