@danceiny/gotry 0.0.1-rc.8 → 0.2.0-rc.27

package/dist/capabilities/model-override.js

@@ -0,0 +1,38 @@
+/**
+ * LLM_MODEL 会话面覆盖(issue #77)。
+ *
+ * dsh settings 分层:schema 默认 < composition 配置(cordis patch)< 用户层
+ *(~/.dsh/settings.yaml)。bin/gotry-inner.js 已把 LLM_MODEL 注入 composition
+ * 层(agent-default-model 默认模型 + llm-deepseek 目录),但用户在 dsh web UI
+ * 选过模型时,用户层压过 composition 层——单靠 patch,.env 承诺仍落空。
+ *
+ * 这里在 agent/request 瀑布(dsh-agent-loop 每次发起 LLM 请求前解析
+ * provider/model 的闸口,dsh-agent installModelSelection 也在此处施加选择)挂
+ * 监听,post-next 覆盖 provider/model:本插件随 cordis patch 在根组装载,先于
+ * 任何 agent 创建;瀑布按注册序嵌套(先注册 = 最外层,post-next 最后生效),
+ * 因此显式 .env 意图压过一切持久层选择。内存态零持久化,进程退即散,不改写
+ * 用户 ~/.dsh 设置。
+ *
+ * GOTRY_LLM_MODEL 未设置时不挂监听:默认路径(组合配置或用户 web 设置)面不变。
+ *
+ * @module gotry/capabilities/model-override
+ */
+export const MODEL_OVERRIDE_ENV = 'GOTRY_LLM_MODEL';
+/**
+ * 挂载模型覆盖;返回是否实际挂载(未设环境变量或 ctx 无事件总线时为 false)。
+ * provider 固定 deepseek-official:llm-deepseek 是 gotry 组合里唯一持有
+ * DEEPSEEK_API_KEY/DEEPSEEK_BASE_URL 映射凭证的 provider 路由。
+ */
+export function installModelOverride(ctx, env = process.env) {
+    const model = env[MODEL_OVERRIDE_ENV];
+    if (!model || typeof ctx.on !== 'function')
+        return false;
+    ctx.on('agent/request', async (_payload, next) => {
+        const resolved = await next();
+        // 与 installModelSelection 同语义:选中项无 effort 时清掉继承值,回落
+        // provider 默认推理档——不把上一个模型的 effort 错配到被覆盖的模型上
+        const { reasoningEffort: _inherited, ...rest } = resolved;
+        return { ...rest, provider: 'deepseek-official', model };
+    });
+    return true;
+}

package/dist/capabilities/opensky.js

@@ -1,33 +1,46 @@
+/**
+ * OpenSky 实时观测桥(免费匿名,~400 credits/天,~4 req/s burst):
+ * 查某 callsign 的飞机是否在 ADS-B 网络的当前观测里——航线层的实时印证。
+ *
+ * 契约(与 weather.ts / hbcli.ts 同构):
+ *   - 永不抛错:网络失败/超时/解析失败一律降级返回;
+ *   - 三值语义:命中=强肯定;查空≠证伪(ADS-B 覆盖有限,降权不排除);服务不可用=无结论;
+ *   - 证据链:成功 [实时API:opensky@ts];失败 [实时API:opensky@error@ts]。
+ *
+ * 接口面(2026-08 实际可达,匿名路径):
+ *   GET /api/states/all  — 当前全球 ADS-B 状态,~10000 架
+ *   GET /api/states/all?icao24=<hex>  — 单飞机
+ *   /api/flights/airport 历史查 = 需鉴权(匿名 403)
+ *
+ * 数据意义:与 OpenFlights 骨架(通航性)+ 静态班次包(班期时刻) 三值互补——
+ *   OpenFlights = 历史上是否通航过(offline)
+ *   flights_2026.json = 调研估算的班次时刻
+ *   OpenSky = 该 callsign 的飞机「现在」是否在观测网络里(实时刻正飞)
+ *
+ * v0.0.1-rc.3 +: 之前是 scripts/opensky-check.ts 一次性 CLI(M2 时设计为 7 天窗
+ * 历史校验,但匿名路径实际不可达),现升级为能力层封装 + dsh 插件工具。
+ */
 const BASE = 'https://opensky-network.org/api';
 async function fetchOpenSky(url, timeoutMs) {
     const ctrl = new AbortController();
-    const timer = setTimeout(()=>ctrl.abort(), timeoutMs);
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
     try {
         const res = await fetch(url, {
             signal: ctrl.signal,
-            headers: {
-                Accept: 'application/json',
-                'User-Agent': 'gotry/0.0.1-rc.3 (+https://github.com/Danceiny/gotry)'
-            }
+            headers: { Accept: 'application/json', 'User-Agent': 'gotry/0.0.1-rc.3 (+https://github.com/Danceiny/gotry)' },
         });
-        if (!res.ok) return {
-            ok: false,
-            error: `opensky HTTP ${res.status}${res.status === 429 ? ' (rate limited, 400 credits/day anonymous)' : ''}`
-        };
-        return {
-            ok: true,
-            data: await res.json()
-        };
-    } catch (e) {
-        return {
-            ok: false,
-            error: e.message.slice(0, 200)
-        };
-    } finally{
+        if (!res.ok)
+            return { ok: false, error: `opensky HTTP ${res.status}${res.status === 429 ? ' (rate limited, 400 credits/day anonymous)' : ''}` };
+        return { ok: true, data: await res.json() };
+    }
+    catch (e) {
+        return { ok: false, error: e.message.slice(0, 200) };
+    }
+    finally {
         clearTimeout(timer);
     }
 }
-const upper = (s)=>s.trim().toUpperCase();
+const upper = (s) => s.trim().toUpperCase();
 export async function verifyFlight(query) {
     const started = Date.now();
     const ts = new Date().toISOString();
@@ -38,37 +51,35 @@ export async function verifyFlight(query) {
     if (!r.ok) {
         return {
             verdict: 'unavailable',
-            callsign: cs,
-            airport,
-            sampleSize: 0,
-            hits: [],
+            callsign: cs, airport,
+            sampleSize: 0, hits: [],
             evidence: `[实时API:opensky@error@${ts}] ${r.error}`,
             via: 'opensky-error',
-            latencyMs,
-            error: r.error
+            latencyMs, error: r.error,
         };
     }
+    // /api/states/all → { time, states: Array<17 元素数组> }
+    // [0 icao24, 1 callsign, 2 origin_country, 3 time_position, 4 last_contact,
+    //  5 lon, 6 lat, 7 baro_altitude, 8 on_ground, ...]
     const rawStates = (r.data ?? {}).states ?? [];
-    const observed = rawStates.filter((row)=>(row[1] ?? '').trim().toUpperCase().includes(cs)).map((row)=>({
-            icao24: String(row[0] ?? ''),
-            callsign: (row[1] ?? '').trim() || null,
-            lastSeen: Number(row[4] ?? 0),
-            firstSeen: Number(row[4] ?? 0),
-            estArrivalAirport: airport
-        }));
+    const observed = rawStates
+        .filter(row => (row[1] ?? '').trim().toUpperCase().includes(cs))
+        .map(row => ({
+        icao24: String(row[0] ?? ''),
+        callsign: (row[1] ?? '').trim() || null,
+        lastSeen: Number(row[4] ?? 0),
+        firstSeen: Number(row[4] ?? 0),
+        estArrivalAirport: airport,
+    }));
     const verdict = observed.length > 0 ? 'observed' : 'not_observed';
-    const evidence = observed.length > 0 ? `[实时API:opensky@${ts}] ✅ 全球 ADS-B 当前观测命中 ${cs} (${observed.length} 架)` : `[实时API:opensky@${ts}] ○ 当前 ADS-B 全球观测列表未见 ${cs}(ADS-B 覆盖有限,不作否定结论)`;
+    const evidence = observed.length > 0
+        ? `[实时API:opensky@${ts}] ✅ 全球 ADS-B 当前观测命中 ${cs} (${observed.length} 架)`
+        : `[实时API:opensky@${ts}] ○ 当前 ADS-B 全球观测列表未见 ${cs}(ADS-B 覆盖有限,不作否定结论)`;
     return {
-        verdict,
-        callsign: cs,
-        airport,
+        verdict, callsign: cs, airport,
         sampleSize: rawStates.length,
-        hits: observed,
-        evidence,
+        hits: observed, evidence,
         via: 'opensky',
-        latencyMs
+        latencyMs,
     };
 }
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/opensky.ts

package/dist/capabilities/resilience.js

@@ -0,0 +1,191 @@
+/**
+ * 外部依赖韧性原语(issue #16 采纳,ADR-18):effect_interpreter.v1 解译器层的横切面。
+ *
+ * 对外通道的三类故障形态在此归一一处,能力层 handler(永不抛错契约)零改写:
+ *   - 指数退避重试 withRetry:只对「瞬时类失败」按策略重试,不改变单次失败语义;
+ *   - 断路器 CircuitBreaker:closed→open→half-open,连续失败达阈值即熔断,
+ *     冷却后放行单探测——保护配额与上游,拒绝也是显式结构化观察(不抛错);
+ *
+ * 策略边界(issue #16 三个解译器主张在本仓的保守落法,详见 docs/design/effect-interpreter.md):
+ *   - 重试只属于被判定「值得重试」的瞬时失败;风控/挑战/限流类上游明确说「不」的
+ *     失败(如 FlyAI Sentinel)永不重试——重试是放大器,不是修复器;
+ *   - 断路器状态是进程内瞬态(同 session-search 节律闸的先例),重启即重置;
+ *     不把瞬态熔断写盘成持久资产。
+ */
+/** 第 failedAttempt 次失败后的等待时长(纯函数,单测锁定 500→1000→2000 封顶链) */
+export function backoffDelayMs(policy, failedAttempt) {
+    const raw = policy.baseDelayMs * 2 ** (Math.max(1, failedAttempt) - 1);
+    return Math.min(raw, policy.maxDelayMs);
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * 带指数退避的受控重试:handler 本身永不抛错(能力层契约),这里兼容抛错的
+ * 「裸调用方」——异常按 isRetryable(result=null, error) 判定后并入同一计数。
+ * 重试只针对瞬时失败;上限到点即返回最后结果,永不向上抛。
+ */
+export async function withRetry(fn, policy, onBackoff) {
+    const sleep = policy.sleep ?? defaultSleep;
+    const maxAttempts = Math.max(1, policy.maxAttempts);
+    let attempts = 0;
+    let backoffMs = 0;
+    const abortableSleep = (ms) => {
+        const signal = policy.signal;
+        if (signal?.aborted)
+            return Promise.resolve('aborted');
+        // The injected sleep is part of the retry contract. Keep its rejection
+        // visible to callers, while making an abort win the race and consuming a
+        // later rejection so cancellation cannot create an unhandled rejection.
+        if (!signal)
+            return sleep(ms).then(() => 'slept');
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer;
+            const cleanup = () => signal.removeEventListener('abort', onAbort);
+            const finish = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                cleanup();
+                resolve(outcome);
+            };
+            const onAbort = () => finish('aborted');
+            const onSleepResolved = () => finish('slept');
+            const onSleepRejected = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (policy.sleep) {
+                void Promise.resolve().then(() => policy.sleep(ms)).then(onSleepResolved, onSleepRejected);
+            }
+            else {
+                timer = setTimeout(onSleepResolved, ms);
+            }
+        });
+    };
+    for (;;) {
+        if (policy.signal?.aborted) {
+            return { result: null, error: null, attempts, backoffMs, aborted: true };
+        }
+        attempts += 1;
+        let result = null;
+        let error = null;
+        try {
+            result = await fn();
+        }
+        catch (e) {
+            error = e;
+        }
+        if (policy.signal?.aborted) {
+            return { result: null, error, attempts, backoffMs, aborted: true };
+        }
+        const retryable = policy.isRetryable?.(result, error)
+            ?? (error != null || result?.ok === false);
+        if (attempts < maxAttempts && retryable) {
+            const delay = backoffDelayMs(policy, attempts);
+            onBackoff?.(attempts, delay);
+            backoffMs += delay;
+            if (await abortableSleep(delay) === 'aborted') {
+                return { result: null, error, attempts, backoffMs, aborted: true };
+            }
+            continue;
+        }
+        return { result, error, attempts, backoffMs, aborted: false };
+    }
+}
+/**
+ * 断路器(每效应一个实例):
+ *   closed    常态放行;连续失败达 failureThreshold → open;
+ *   open      拒绝(new attempts=0,.fail-fast 保护上游/配额);冷却满 openMs → half-open;
+ *   half-open 仅放行单个探测:onSuccess → closed 清零;onFailure → 重新 open(冷却重启)。
+ * 「失败」按效应的 isFailure 语义计数(一次调用一次计数,重试耗尽才计,非每 attempt)。
+ */
+export class CircuitBreaker {
+    o;
+    consecutiveFailures = 0;
+    openedAt = 0;
+    generation = 0;
+    nextTokenId = 0;
+    probeToken = null;
+    constructor(o) {
+        this.o = o;
+    }
+    threshold() {
+        return Math.max(1, this.o.failureThreshold);
+    }
+    now() {
+        return (this.o.now ?? Date.now)();
+    }
+    state() {
+        if (this.openedAt > 0 && this.now() - this.openedAt >= this.o.openMs)
+            return 'half-open';
+        if (this.openedAt > 0)
+            return 'open';
+        return 'closed';
+    }
+    /** 发起一次调用前问闸:open 回 {allowed:false}(调用方须返回显式降级观察,不重试) */
+    canAttempt() {
+        const s = this.state();
+        if (s === 'closed')
+            return { allowed: true, state: s, token: this.makeToken(false) };
+        if (s === 'open')
+            return { allowed: false, state: s };
+        // half-open:单探测语义——已有探测在途拒其余并发
+        if (this.probeToken)
+            return { allowed: false, state: s };
+        this.generation += 1;
+        const token = this.makeToken(true);
+        this.probeToken = token;
+        return { allowed: true, state: s, token };
+    }
+    /**
+     * half-open 探测被取消:仅令牌持有者释放所有权,不把 probe 永久卡死,
+     * 也不让旧 closed 调用或旧 generation 释放新探测。
+     */
+    releaseProbe(token) {
+        if (token?.probe !== true || this.probeToken !== token || this.state() !== 'half-open')
+            return;
+        this.probeToken = null;
+        this.generation += 1;
+    }
+    /** 一次解译调用成功(非 isFailure)——清零;half-open 探测成功即回 closed */
+    onSuccess(token) {
+        if (!this.owns(token))
+            return;
+        this.consecutiveFailures = 0;
+        this.openedAt = 0;
+        if (token?.probe === true || (!token && this.probeToken !== null)) {
+            this.probeToken = null;
+            this.generation += 1;
+        }
+    }
+    /** 一次解译调用失败(含重试耗尽)——半开探测失败 = 重新开闸 */
+    onFailure(token) {
+        if (!this.owns(token))
+            return;
+        if (token?.probe === true || (!token && this.probeToken !== null))
+            this.probeToken = null;
+        this.consecutiveFailures += 1;
+        if (this.openedAt > 0 || this.consecutiveFailures >= this.threshold()) {
+            this.openedAt = this.now();
+            this.generation += 1;
+        }
+    }
+    makeToken(probe) {
+        return Object.freeze({ generation: this.generation, probe, id: ++this.nextTokenId });
+    }
+    owns(token) {
+        // Keep the direct CircuitBreaker API backwards-compatible for callers
+        // that settle the currently active call without retaining its token.
+        if (!token)
+            return true;
+        if (token.probe)
+            return this.probeToken === token && this.state() === 'half-open';
+        return token.generation === this.generation && this.probeToken === null;
+    }
+}

package/dist/capabilities/session/action-cache.js

@@ -0,0 +1,126 @@
+/**
+ * action-cache 本地自愈层(RFC docs/rfc/user-session-data-rfc.md §3.2 / §2.3;Stagehand 云端缓存的本地化):
+ *
+ * 目的:会话检索的查询模式高度重复(同站点同类型搜索),首跑用 LLM/规则定位,后续走
+ * 缓存的确定性载荷零成本重放;站点改版 → DOM 指纹失配 → miss → 重新定位并回写。
+ *
+ * 设计原则(Stagehand「错误的缓存点击比慢更糟」的被动失效):
+ *   - key = site + action + 参数模板(%from%/%to%/%date% 变量化,同型查询共享条目);
+ *   - 每条目绑 domFingerprint(快照/接口形状的 sha256 指纹);lookup 时现场指纹与条目不符 = miss(即使 key 命中);
+ *   - miss 即回写(记录新定位),过期(默认 48h)与容量(每 site 默认 50 条,LRU)被动淘汰;
+ *   - 纯函数 + JSON 文件持久化(隔离 stateRoot;损坏文件按空缓存处理,永不抛错)。
+ *
+ * P2 切片:模块+确定性测试先行;消费方(P2 美团适配器/a11y 兜底)下一切片接线。
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** 把具体查询参数变量化为模板 key:日期→%date%,from/to 语义序在前,其余参数按字典序尾随 */
+export function templateKey(site, action, params) {
+    const val = (k) => (k === 'date' ? '%date%' : (params[k] ?? '').trim());
+    const head = ['from', 'to', 'date'].filter((k) => k in params).map(val);
+    const tail = Object.keys(params).filter((k) => !['from', 'to', 'date'].includes(k)).sort().map(val);
+    return `${site}:${action}:${[...head, ...tail].join('|')}`;
+}
+/** 指纹:快照/接口形状文本 → sha256 前 16 位(微改版即失配——宁可 miss 不可错点) */
+export function fingerprint(shapeText) {
+    return createHash('sha256').update(shapeText).digest('hex').slice(0, 16);
+}
+export class ActionCache {
+    filePath;
+    entries = new Map();
+    loaded = false;
+    ttlMs;
+    maxPerSite;
+    now;
+    constructor(filePath, opts = {}) {
+        this.filePath = filePath;
+        this.ttlMs = opts.ttlMs ?? 48 * 3600_000;
+        this.maxPerSite = opts.maxEntriesPerSite ?? 50;
+        this.now = opts.now ?? (() => new Date());
+    }
+    load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            if (existsSync(this.filePath)) {
+                const raw = JSON.parse(readFileSync(this.filePath, 'utf8'));
+                for (const e of raw) {
+                    if (e?.key && e.domFingerprint && e.locator)
+                        this.entries.set(e.key, e);
+                }
+            }
+        }
+        catch { /* 损坏文件按空缓存处理 */ }
+    }
+    persist() {
+        try {
+            mkdirSync(dirname(this.filePath), { recursive: true });
+            const tmp = this.filePath + '.tmp';
+            writeFileSync(tmp, JSON.stringify([...this.entries.values()], null, 0), 'utf8');
+            writeFileSync(this.filePath, readFileSync(tmp, 'utf8'), 'utf8');
+            try {
+                require('node:fs').rmSync(tmp);
+            }
+            catch { /* best effort */ }
+        }
+        catch { /* 持久化失败不阻塞内存路径 */ }
+    }
+    /** 站点前缀条目数(LRU 淘汰用) */
+    siteEntries(site) {
+        return [...this.entries.values()].filter((e) => e.key.startsWith(site + ':'));
+    }
+    /** 命中三条件:key 存在 + 未过期 + 指纹一致;命中计 hits 并惰性落盘 */
+    lookup(key, domFingerprint, site) {
+        this.load();
+        const e = this.entries.get(key);
+        if (!e)
+            return null;
+        if (this.now().getTime() - Date.parse(e.lastHitAt || e.createdAt) > this.ttlMs) {
+            this.entries.delete(key);
+            this.persist();
+            return null;
+        }
+        if (e.domFingerprint !== domFingerprint)
+            return null; // 改版:被动失效,等 record 回写
+        e.hits += 1;
+        e.lastHitAt = this.now().toISOString();
+        this.persist();
+        void site;
+        return e;
+    }
+    /** miss 后回写(重新定位的产物);同 key 覆盖;超容 LRU 淘汰最旧 */
+    record(key, domFingerprint, locator, site) {
+        this.load();
+        const ts = this.now().toISOString();
+        const prev = this.entries.get(key);
+        this.entries.set(key, {
+            key, domFingerprint, locator,
+            createdAt: prev?.createdAt ?? ts,
+            lastHitAt: ts,
+            hits: prev?.hits ?? 0,
+        });
+        const siteList = this.siteEntries(site);
+        if (siteList.length > this.maxPerSite) {
+            const victim = siteList.sort((a, b) => Date.parse(a.lastHitAt) - Date.parse(b.lastHitAt))[0];
+            if (victim)
+                this.entries.delete(victim.key);
+        }
+        this.persist();
+        return this.entries.get(key);
+    }
+    invalidate(key) {
+        this.load();
+        this.entries.delete(key);
+        this.persist();
+    }
+    size(site) {
+        this.load();
+        return site ? this.siteEntries(site).length : this.entries.size;
+    }
+}
+/** 便捷入口:隔离 stateRoot 下的缓存文件路径 */
+export function actionCachePath(stateRoot) {
+    return join(stateRoot, 'session-action-cache.json');
+}

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

@@ -0,0 +1,141 @@
+/**
+ * 携程机票站点适配器(RFC §3.2 首个适配器;PoC 已识别接口面,data-sources.md §8):
+ *   - entry:URL 参数直开(https://flights.ctrip.com/online/list/oneway-{from}-{to}?depdate=YYYY-MM-DD)
+ *   - networkHints:主搜索接口 search/api/search/batchSearch(POST,~550KB,国内票同走)
+ *   - 解析:flightItineraryList[].flightSegments[0].flightList[0] + priceList 最小 adultPrice
+ *     (schema 实测 2026-08-28,见 data-sources.md §8)
+ * 只读:适配器不含任何提交/预订语义;URL 直开即零 DOM 交互。
+ */
+/** 城市三字码表(小起步集;词表外 unresolved 逐字保留,不做开放式猜测——ADR-12 同款边界) */
+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',
+};
+export function buildEntryUrl(from, to, depDate) {
+    const unresolved = [];
+    const fromCode = CITY_CODES[from];
+    const toCode = CITY_CODES[to];
+    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] };
+    }
+    return { ok: true, url: `https://flights.ctrip.com/online/list/oneway-${fromCode}-${toCode}?depdate=${depDate}` };
+}
+/** networkHints:响应 URL 命中即视为搜索回包(对 UI 改版免疫,只怕接口改版) */
+export const NETWORK_HINTS = [/search\/api\/search\/batchSearch/];
+/**
+ * 登录态检测(用户自己的账号,不是匿名实例——founder 2026-08-28 纠偏):
+ * 任一登录票据 cookie 存在即视为已登录;名单基于公开常识,首个真登录后校准(D-13)。
+ */
+export const LOGIN_COOKIE_NAMES = ['cticket', 'uid', 'uname', 'passport'];
+export const SITE_DOMAIN = '.ctrip.com';
+/** 安全取字符串字段(任意来源字段都可能是 null/undefined/数字/对象) */
+function asString(v) {
+    return typeof v === 'string' ? v : '';
+}
+/** 安全取正数(无法解析按 0 返,绝不伪造价格) */
+function asPositiveNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0;
+}
+/** 解析 batchSearch 响应(纯函数,fixture 测试锚点);malformed 一律返空,不抛错 */
+export function parseBatchSearch(body) {
+    return parseBatchSearchResult(body).options;
+}
+/**
+ * 结构化解析(issue #279):返回选项 + 三态判语。
+ *   - `hit`  = 已识别合法结构 + 至少一个有效行程
+ *   - `miss` = 已识别合法空(data.flightItineraryList 是空数组)
+ *   - `error`= 形状未识别(JSON 解析失败 / 非对象根 / data 缺失或非对象 /
+ *              flightItineraryList 不是数组 / 非空数组没有可用行程)——未知响应
+ *              不可静默收敛为 miss
+ * 绝不发明价格、航班号、机场、时刻;混合数组保留有效项,全畸形数组报 error。
+ */
+export function parseBatchSearchResult(body) {
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch {
+        return { options: [], verdict: 'error', shape: 'invalid_json' };
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { options: [], verdict: 'error', shape: 'root_not_object' };
+    }
+    const data = raw.data;
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return { options: [], verdict: 'error', shape: 'data_not_object' };
+    }
+    const list = raw.data.flightItineraryList;
+    if (!Array.isArray(list)) {
+        return { options: [], verdict: 'error', shape: 'itinerary_list_not_array' };
+    }
+    const out = [];
+    for (const it of list) {
+        if (it === null || typeof it !== 'object' || Array.isArray(it))
+            continue;
+        const item = it;
+        const segs = item.flightSegments;
+        if (!Array.isArray(segs) || segs.length === 0)
+            continue;
+        const seg = segs[0];
+        if (seg === null || typeof seg !== 'object' || Array.isArray(seg))
+            continue;
+        const segObj = seg;
+        const fl = segObj.flightList;
+        if (!Array.isArray(fl) || fl.length === 0)
+            continue;
+        const flight = fl[0];
+        if (flight === null || typeof flight !== 'object' || Array.isArray(flight))
+            continue;
+        const f = flight;
+        if (typeof f.flightNo !== 'string' || !f.flightNo)
+            continue;
+        if (typeof f.departureDateTime !== 'string' || !f.departureDateTime)
+            continue;
+        // 缺 priceList 延续旧合同为「有航班、价格未知」;显式非数组与畸形价项
+        // 属未知响应,整项跳过。若响应里没有其他有效项,最终判 error 而非 miss。
+        if (item.priceList !== undefined && !Array.isArray(item.priceList))
+            continue;
+        const priceList = item.priceList ?? [];
+        const prices = [];
+        let malformedPrice = false;
+        for (const p of priceList) {
+            if (p === null || typeof p !== 'object' || Array.isArray(p)) {
+                malformedPrice = true;
+                break;
+            }
+            const adultPrice = p.adultPrice;
+            if (adultPrice === undefined)
+                continue;
+            if (typeof adultPrice !== 'number' || !Number.isFinite(adultPrice)) {
+                malformedPrice = true;
+                break;
+            }
+            if (adultPrice > 0)
+                prices.push(adultPrice);
+        }
+        if (malformedPrice)
+            continue;
+        out.push({
+            flightNo: f.flightNo,
+            airline: asString(segObj.airlineName),
+            depDateTime: asString(f.departureDateTime),
+            arrDateTime: asString(f.arrivalDateTime),
+            depAirport: asString(f.departureAirportName),
+            arrAirport: asString(f.arrivalAirportName),
+            durationMin: asPositiveNumber(segObj.duration),
+            price: prices.length > 0 ? Math.min(...prices) : 0,
+            aircraft: typeof f.aircraftName === 'string' ? f.aircraftName : undefined,
+        });
+    }
+    return {
+        options: out,
+        verdict: out.length > 0 ? 'hit' : list.length === 0 ? 'miss' : 'error',
+        shape: out.length > 0 ? 'itinerary_rows_usable' : list.length === 0 ? 'itinerary_list_empty' : 'itinerary_rows_unusable',
+    };
+}