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

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

package/dist/capabilities/session/adapters/ctrip-flight.js

@@ -6,23 +6,58 @@
  *     (schema 实测 2026-08-28,见 data-sources.md §8)
  * 只读:适配器不含任何提交/预订语义;URL 直开即零 DOM 交互。
  */
-/** 城市三字码表(小起步集;词表外 unresolved 逐字保留,不做开放式猜测——ADR-12 同款边界) */
-const CITY_CODES = {
+import { resolveCtripFlightCity, cityResolutionHint } from '../ctrip-city.js';
+/**
+ * 离线起步缓存;未命中由编排层查询供应商城市数据(ctrip-city.ts),不推断航线覆盖。
+ * 码表只做性能优化,不在主链路上(显式码/供应商解析是正路)。
+ * 实测校准(2026-10-14):香港=hkg/迪拜=dxb 经 list 页实证——合法组合 HTTP 200 且
+ * title 含航线名(「中国香港(HKG)到迪拜(阿联酋)(DXB)机票预订」),非法组合 302 跳
+ * international/search(该 200/302 判别式即真数据校准手段)。
+ */
+export const CITY_CODES = {
     上海: 'sha', 北京: 'bjs', 广州: 'can', 深圳: 'szx', 成都: 'ctu', 昆明: 'kmg',
     大理: 'dlu', 丽江: 'ljg', 西安: 'sia', 杭州: 'hgh', 三亚: 'syx', 厦门: 'xmn',
     重庆: 'cqg', 青岛: 'taa', 长沙: 'csx', 武汉: 'wuh', 南京: 'nkg', 郑州: 'cgo',
     贵阳: 'kwe', 桂林: 'kwl', 西双版纳: 'jhg', 香格里拉: 'dig',
+    香港: 'hkg', 迪拜: 'dxb',
 };
-export function buildEntryUrl(from, to, depDate) {
+/** Resolve unknown names against current supplier metadata before inventory navigation. */
+export async function resolveFlightEntryUrl(from, to, depDate, codes = {}, resolve = resolveCtripFlightCity, backDate) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(depDate))
+        return { ok: false, unresolved: [depDate], error: '出发日期需要 YYYY-MM-DD' };
+    for (const c of [codes.fromCode, codes.toCode])
+        if (c !== undefined && !/^[a-z]{3}$/i.test(c))
+            return { ok: false, error: '城市／机场码必须是三个英文字母' };
+    const resolveCode = async (name, explicit) => {
+        const known = explicit ?? (/^[a-z]{3}$/i.test(name.trim()) ? name.trim() : undefined);
+        if (known)
+            return { code: known };
+        const result = await resolve(name);
+        return result.ok ? { code: result.city.code } : { error: cityResolutionHint(name, result) };
+    };
+    const [origin, destination] = await Promise.all([resolveCode(from, codes.fromCode), resolveCode(to, codes.toCode)]);
+    if (!origin.code || !destination.code)
+        return { ok: false, unresolved: [!origin.code ? from : '', !destination.code ? to : ''].filter(Boolean), error: [origin.error, destination.error].filter(Boolean).join('；') };
+    return buildEntryUrl(from, to, depDate, { fromCode: origin.code, toCode: destination.code }, backDate);
+}
+export function buildEntryUrl(from, to, depDate, codes = {}, backDate) {
     const unresolved = [];
-    const fromCode = CITY_CODES[from];
-    const toCode = CITY_CODES[to];
+    // 显式码优先(形状合格才采纳),词表只是缓存——任何城市都可经显式码成行。
+    const fromCode = codes.fromCode === undefined ? CITY_CODES[from.trim()] : /^[a-z]{3}$/i.test(codes.fromCode) ? codes.fromCode.toLowerCase() : undefined;
+    const toCode = codes.toCode === undefined ? CITY_CODES[to.trim()] : /^[a-z]{3}$/i.test(codes.toCode) ? codes.toCode.toLowerCase() : undefined;
     if (!fromCode)
         unresolved.push(from);
     if (!toCode)
         unresolved.push(to);
-    if (unresolved.length > 0 || !/^\d{4}-\d{2}-\d{2}$/.test(depDate)) {
-        return { ok: false, unresolved: unresolved.length > 0 ? unresolved : [depDate] };
+    const badDate = !/^\d{4}-\d{2}-\d{2}$/.test(depDate)
+        || (backDate !== undefined && (!/^\d{4}-\d{2}-\d{2}$/.test(backDate) || backDate <= depDate));
+    if (unresolved.length > 0 || badDate) {
+        return { ok: false, unresolved: unresolved.length > 0 ? unresolved : [badDate ? (backDate !== undefined && backDate <= depDate ? backDate : depDate) : depDate], ...(backDate !== undefined && backDate <= depDate ? { error: `回程(${backDate})须晚于去程(${depDate})` } : {}) };
+    }
+    // 往返形状(2026-10-14 GUI URL 教师实测定稿):round-{code}0-{code}0?depdate=去_回&cabin=y_s
+    // ——此前 roundtrip-{3字码}?depdate&retdate 的猜测形状实测 302,已废弃。
+    if (backDate) {
+        return { ok: true, url: `https://flights.ctrip.com/online/list/round-${fromCode}0-${toCode}0?depdate=${depDate}_${backDate}&cabin=y_s&adult=1&child=0&infant=0` };
     }
     return { ok: true, url: `https://flights.ctrip.com/online/list/oneway-${fromCode}-${toCode}?depdate=${depDate}` };
 }

package/dist/capabilities/session/adapters/ctrip-hotel.js

@@ -13,10 +13,11 @@
  * 只读:适配器不含任何提交/预订语义;URL 直开即零 DOM 交互;ReadGuard 对酒店
  * 页面照常生效(下单/支付面 URL 仍被物理拦截)。
  */
-/** 城市码表(**实测校准 2026-09-03**:每条 id 均经 hotels.ctrip.com list 页
+import { resolveCtripHotelCity, hotelResolutionHint } from '../ctrip-city.js';
+/** 离线兼容缓存(**实测校准 2026-09-03**:每条 id 均经 hotels.ctrip.com list 页
  * <title> 验证——探测法曾纠出 104=平遥县(传猜成都)等 5 处错猜,表内只收
  * 验证过的 id;词表外 unresolved 逐字保留,调用方可显式传 cityId 覆盖) */
-const HOTEL_CITY_CODES = {
+export const HOTEL_CITY_CODES = {
     上海: '2', 北京: '1', 广州: '32', 深圳: '30', 成都: '28',
     杭州: '17', 南京: '12', 苏州: '14', 无锡: '13', 扬州: '15', 镇江: '16',
     青岛: '7', 厦门: '25', 珠海: '31', 三亚: '43', 海口: '42',
@@ -24,10 +25,22 @@ const HOTEL_CITY_CODES = {
     贵阳: '38', 拉萨: '41', 乌鲁木齐: '39', 太原: '105', 长春: '158', 南通: '82',
     敦煌: '11', 舟山: '19', 张家界: '27', 黄山市: '23', 九江: '24', 武夷山: '26',
     迪拜: '220',
+    // Verified against the official list page and its displayed destination/date
+    // controls on 2026-10-07; https://hotels.ctrip.com/hotels/list?city=5
+    哈尔滨: '5',
 };
+export async function resolveHotelEntryUrl(q, resolve = resolveCtripHotelCity) {
+    if (q.cityId !== undefined)
+        return buildHotelEntryUrl(q);
+    const result = await resolve(q.to, q.country);
+    if (!result.ok)
+        return { ok: false, unresolved: [q.to], error: hotelResolutionHint(q.to, result) };
+    return buildHotelEntryUrl({ ...q, cityId: result.city.id });
+}
 export function buildHotelEntryUrl(q) {
     const unresolved = [];
-    const cityId = String(q.cityId ?? '').trim() || HOTEL_CITY_CODES[q.to.trim()];
+    const candidate = q.cityId === undefined ? HOTEL_CITY_CODES[q.to.trim()] : String(q.cityId).trim();
+    const cityId = candidate && /^[1-9]\d{0,9}$/.test(candidate) ? candidate : undefined;
     if (!cityId)
         unresolved.push(q.to);
     if (unresolved.length > 0) {
@@ -220,3 +233,39 @@ export function parseCtripHotelList(body, opts = {}) {
     walk(raw, 0, new Set());
     return out;
 }
+/** Only an explicit empty hotel array proves a miss; parser failure proves nothing. */
+export function classifyCtripHotelList(body) {
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch {
+        return { shape: 'malformed', hotels: [] };
+    }
+    const envelope = raw;
+    if (envelope?.success === false || envelope?.ok === false
+        || (envelope?.code !== undefined && envelope.code !== 0 && envelope.code !== '0')
+        || /^(failure|error)$/i.test(String(envelope?.ResponseStatus?.Ack ?? ''))) {
+        return { shape: 'unrecognized', hotels: [] };
+    }
+    const hotels = parseCtripHotelList(body);
+    if (hotels.length > 0)
+        return { shape: 'parsed', hotels };
+    let emptyList = false;
+    let unparsedItems = false;
+    const inspectHotelLists = (node, depth) => {
+        if (depth > 12 || node === null || typeof node !== 'object')
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (['hotelList', 'hotelMatchInfos'].includes(key) && Array.isArray(value)) {
+                if (value.length === 0)
+                    emptyList = true;
+                else
+                    unparsedItems = true;
+            }
+            inspectHotelLists(value, depth + 1);
+        }
+    };
+    inspectHotelLists(raw, 0);
+    return { shape: emptyList && !unparsedItems ? 'recognized-empty' : 'unrecognized', hotels: [] };
+}

package/dist/capabilities/session/ctrip-city.js

@@ -0,0 +1,186 @@
+/** Public supplier city metadata, independent of inventory and account sessions. */
+export const CTRIP_CITY_CATALOG_URL = 'https://m.ctrip.com/restapi/soa2/17909/SearchBoxRecommend';
+export const CTRIP_CITY_SUGGEST_URL = 'https://flights.ctrip.com/international/search/api/poi/search';
+export const CTRIP_HOTEL_CITY_URL = 'https://m.ctrip.com/restapi/soa2/34951/getHotelKeywords';
+const normalized = (s) => s.normalize('NFKC').trim().replace(/^中国(?=香港|澳门)/, '').toLowerCase();
+const text = (v) => typeof v === 'string' ? v.trim() : '';
+const code = (v) => /^[a-z]{3}$/i.test(text(v)) ? text(v).toUpperCase() : undefined;
+const object = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+export function parseCtripCityCatalog(value) {
+    const root = object(value);
+    if (object(root.ResponseStatus).Ack !== 'Success' || object(root.responseHead).errorCode !== '0' || !Array.isArray(root.recommendGroupList))
+        throw new Error('unrecognized city catalog');
+    const records = [];
+    let visited = 0;
+    const walk = (v, depth = 0) => {
+        if (++visited > 20_000 || depth > 12)
+            throw new Error('city catalog bounds');
+        if (Array.isArray(v)) {
+            for (const item of v)
+                walk(item, depth + 1);
+            return;
+        }
+        const r = object(v), c = code(r.code), name = text(r.name);
+        if (c && name && Number(r.id) > 0) {
+            records.push({ name, code: c, aliases: [name, text(r.eName), text(r.nameEn), text(r.namePy), text(r.specName)].filter(Boolean), context: text(r.specName) || undefined, requiresQualification: r.sameSpecCity === 1 });
+            if (Array.isArray(r.airportlst))
+                for (const item of r.airportlst) {
+                    const a = object(item), ac = code(a.code), an = text(a.name);
+                    if (ac && an)
+                        records.push({ name: an, code: ac, aliases: [an], context: name, airport: true });
+                }
+        }
+        for (const [key, child] of Object.entries(r))
+            if (key !== 'airportlst' && child && typeof child === 'object')
+                walk(child, depth + 1);
+    };
+    walk(root.recommendGroupList);
+    return records;
+}
+export function parseCtripCitySuggestions(value) {
+    const root = object(value);
+    if (!Array.isArray(root.Data))
+        throw new Error('unrecognized city suggestions');
+    const records = [];
+    let visited = 0;
+    const walk = (items, depth = 0) => {
+        if (depth > 5)
+            throw new Error('city suggestion bounds');
+        for (const value of items) {
+            if (++visited > 2_000)
+                throw new Error('city suggestion bounds');
+            const r = object(value), c = code(r.Code), name = text(r.Name);
+            if (c && name && [3, 4, 5].includes(Number(r.Type)))
+                records.push({
+                    name, code: c, aliases: [name, text(r.EName), text(r.NameAlias), text(r.ShortSpell)].filter(Boolean),
+                    context: [text(r.Country), text(r.Province)].filter(Boolean).join(' / ') || undefined, airport: Number(r.Type) === 3,
+                });
+            if (Array.isArray(r.Datas))
+                walk(r.Datas, depth + 1);
+            // Nearby cities must not be substituted for the requested destination.
+        }
+    };
+    walk(root.Data);
+    return records;
+}
+export function matchCtripCity(query, records) {
+    const input = normalized(query);
+    const matches = records.filter(r => r.code.toLowerCase() === input || r.aliases.some(a => normalized(a) === input));
+    const unique = [...new Map(matches.map(r => [`${r.code}:${r.context ?? ''}`, r])).values()];
+    // A city and its airport may share one code. An explicitly typed code remains exact.
+    const codes = new Set(unique.map(r => r.code));
+    if (codes.size === 1 && /^[a-z]{3}$/i.test(query.trim()))
+        return { ok: true, city: unique[0] };
+    if (unique.length === 1 && (!unique[0].requiresQualification || normalized(unique[0].context ?? '') === input))
+        return { ok: true, city: unique[0] };
+    return { ok: false, reason: unique.length ? 'ambiguous' : 'not-found', candidates: unique.slice(0, 8) };
+}
+async function readMetadata(url, init, fetcher) {
+    const response = await fetcher(url, { ...init, signal: AbortSignal.timeout(8_000), redirect: 'error' });
+    if (!response.ok || !response.body)
+        throw new Error('city metadata unavailable');
+    const reader = response.body.getReader(), chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 512_000)
+                throw new Error('city metadata bounds');
+            chunks.push(value);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}
+let catalog;
+const catalogBody = {
+    head: { cver: '3', cid: '', extension: [{ name: 'source', value: 'ONLINE' }, { name: 'sotpGroup', value: 'CTrip' }, { name: 'sotpLocale', value: 'zh-CN' }] },
+    locale: 'zh-CN', departureCity: '', dataType: 0,
+};
+export async function resolveCtripFlightCity(query, fetcher = fetch) {
+    if (!query.trim() || query.length > 120)
+        return { ok: false, reason: 'not-found', candidates: [] };
+    if (fetcher === fetch && process.env.GOTRY_SESSION_LIVE === '0')
+        return { ok: false, reason: 'unavailable', candidates: [] };
+    try {
+        const load = () => readMetadata(CTRIP_CITY_CATALOG_URL, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(catalogBody) }, fetcher).then(parseCtripCityCatalog);
+        let records;
+        if (fetcher !== fetch)
+            records = await load();
+        else {
+            if (!catalog || Date.now() - catalog.at > 3_600_000)
+                catalog = { at: Date.now(), promise: load() };
+            try {
+                records = await catalog.promise;
+            }
+            catch {
+                catalog = undefined;
+                records = [];
+            }
+        }
+        const matched = matchCtripCity(query, records);
+        if (matched.ok || matched.reason === 'ambiguous')
+            return matched;
+        const url = new URL(CTRIP_CITY_SUGGEST_URL);
+        url.searchParams.set('key', query.trim().toUpperCase());
+        url.searchParams.set('filterAirport', 'false');
+        return matchCtripCity(query, parseCtripCitySuggestions(await readMetadata(url.href, {}, fetcher)));
+    }
+    catch {
+        return { ok: false, reason: 'unavailable', candidates: [] };
+    }
+}
+export function cityResolutionHint(query, result) {
+    if (result.reason === 'ambiguous')
+        return `城市「${query}」有多个候选，请确认城市或机场码：${result.candidates.map(c => `${c.name} ${c.code}${c.context ? `（${c.context}）` : ''}`).join('；')}`;
+    return `unresolved 城市「${query}」：${result.reason === 'unavailable' ? '携程城市解析服务暂不可用' : '供应商城市候选未精确匹配'}；请确认城市／机场名称，或提供 fromCityCode／toCityCode。城市解析失败不能证明该航线无库存或不受支持。`;
+}
+export function parseCtripHotelCities(value) {
+    const root = object(value), data = object(root.data), keywords = object(data.mainKeywordList).keywords;
+    if (object(root.ResponseStatus).Ack !== 'Success' || data.htlSpiderActionErrorCode || !Array.isArray(keywords) || keywords.length > 1_000)
+        throw new Error('hotel city metadata unavailable');
+    const records = [];
+    for (const item of keywords) {
+        const r = object(item), k = object(object(r.keyword).keywordContentInfo), region = object(object(r.controlInfo).regionInfo);
+        const display = object(region.displayCityModel), basic = object(region.basicCityModel), id = String(basic.cityId ?? '');
+        if (k.tripType !== 'CT' || !/^[1-9]\d{0,9}$/.test(id))
+            continue;
+        if (k.keywordCode !== undefined && String(k.keywordCode) !== id)
+            throw new Error('hotel city ID conflict');
+        const titles = Array.isArray(k.displayTexts) ? k.displayTexts.map(object).filter(t => t.key === 'MAIN_TITLE').map(t => text(t.value)) : [];
+        const name = text(display.cityName) || text(display.destinationName);
+        if (!name)
+            continue;
+        records.push({ id, name, aliases: [name, text(display.destinationName), text(display.destinationNameEN), ...titles].filter(Boolean),
+            countries: [text(display.countryName), text(display.countryNameEN)].filter(Boolean),
+            context: [text(display.countryName), text(display.provinceName)].filter(Boolean).join(' / ') });
+    }
+    return records;
+}
+export async function resolveCtripHotelCity(query, country, fetcher = fetch) {
+    if (!query.trim() || query.length > 120 || (country?.length ?? 0) > 120)
+        return { ok: false, reason: 'not-found', candidates: [] };
+    if (fetcher === fetch && process.env.GOTRY_SESSION_LIVE === '0')
+        return { ok: false, reason: 'unavailable', candidates: [] };
+    try {
+        const value = await readMetadata(CTRIP_HOTEL_CITY_URL, { method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ head: { platform: 'PC', bu: 'HBU', group: 'ctrip', locale: 'zh-CN' }, queryInfo: { keyword: query.trim(), actionType: 'destination' } }) }, fetcher);
+        const input = normalized(query);
+        const candidates = parseCtripHotelCities(value).filter(c => (!country || c.countries.some(a => normalized(a) === normalized(country))) && c.aliases.some(a => normalized(a) === input));
+        const unique = [...new Map(candidates.map(c => [c.id, c])).values()];
+        return unique.length === 1 ? { ok: true, city: unique[0] } : { ok: false, reason: unique.length ? 'ambiguous' : 'not-found', candidates: unique.slice(0, 8) };
+    }
+    catch {
+        return { ok: false, reason: 'unavailable', candidates: [] };
+    }
+}
+export function hotelResolutionHint(query, result) {
+    if (result.reason === 'ambiguous')
+        return `城市「${query}」有多个候选，请确认国家或城市：${result.candidates.map(c => `${c.name}（${c.context}，cityId=${c.id}）`).join('；')}`;
+    return `城市「${query}」${result.reason === 'unavailable' ? '的携程酒店城市解析服务暂不可用' : '未精确匹配供应商城市候选'}；可提供 country 消歧，或携程酒店 list 页 city= 数字作为 cityId。城市解析失败不能证明目的地不受支持。`;
+}

package/dist/capabilities/session/extension-bridge.js

@@ -513,7 +513,14 @@ export function createBridgeJobQueue(opts = {}) {
                 const settle = armSettle(entry, resolve);
                 entry.resolve = settle;
                 entry.timer = setTimeout(() => {
-                    settle({ ok: false, reason: 'timeout', summary: `扩展未在 ${timeoutMs}ms 内回包(标签页无嗅探命中或扩展已停用)` });
+                    const stage = entry.claimedOrigin === undefined ? 'queued' : 'claimed';
+                    const task = full.kind === 'cookie-names' ? '登录态检查' : full.kind === 'search' ? '检索' : '登录页打开';
+                    settle({
+                        ok: false, reason: 'timeout', jobKind: full.kind, stage,
+                        summary: stage === 'queued'
+                            ? `扩展${task}等待领取超时（${timeoutMs}ms）；尚未执行，请检查扩展是否支持当前站点或正在处理其他作业`
+                            : `扩展${task}已领取但未在 ${timeoutMs}ms 内回传；请检查扩展运行错误与桥连接`,
+                    });
                 }, timeoutMs);
                 if (!dispatchToParked(entry))
                     queue.push(entry);