@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

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

@@ -1,23 +1,28 @@
+/**
+ * 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, rmSync } from 'node:fs';
+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('|')}`;
+    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);
 }
@@ -28,76 +33,79 @@ export class ActionCache {
     ttlMs;
     maxPerSite;
     now;
-    constructor(filePath, opts = {}){
+    constructor(filePath, opts = {}) {
         this.filePath = filePath;
         this.ttlMs = opts.ttlMs ?? 48 * 3600_000;
         this.maxPerSite = opts.maxEntriesPerSite ?? 50;
-        this.now = opts.now ?? (()=>new Date());
+        this.now = opts.now ?? (() => new Date());
     }
     load() {
-        if (this.loaded) return;
+        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);
+                for (const e of raw) {
+                    if (e?.key && e.domFingerprint && e.locator)
+                        this.entries.set(e.key, e);
                 }
             }
-        } catch  {}
+        }
+        catch { /* 损坏文件按空缓存处理 */ }
     }
     persist() {
         try {
-            mkdirSync(dirname(this.filePath), {
-                recursive: true
-            });
+            mkdirSync(dirname(this.filePath), { recursive: true });
             const tmp = this.filePath + '.tmp';
-            writeFileSync(tmp, JSON.stringify([
-                ...this.entries.values()
-            ], null, 0), 'utf8');
+            writeFileSync(tmp, JSON.stringify([...this.entries.values()], null, 0), 'utf8');
             writeFileSync(this.filePath, readFileSync(tmp, 'utf8'), 'utf8');
             try {
                 require('node:fs').rmSync(tmp);
-            } catch  {}
-        } catch  {}
+            }
+            catch { /* best effort */ }
+        }
+        catch { /* 持久化失败不阻塞内存路径 */ }
     }
+    /** 站点前缀条目数(LRU 淘汰用) */
     siteEntries(site) {
-        return [
-            ...this.entries.values()
-        ].filter((e)=>e.key.startsWith(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 (!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;
+        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,
+            key, domFingerprint, locator,
             createdAt: prev?.createdAt ?? ts,
             lastHitAt: ts,
-            hits: prev?.hits ?? 0
+            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);
+            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);
@@ -112,9 +120,7 @@ export class ActionCache {
         return site ? this.siteEntries(site).length : this.entries.size;
     }
 }
+/** 便捷入口:隔离 stateRoot 下的缓存文件路径 */
 export function actionCachePath(stateRoot) {
     return join(stateRoot, 'session-action-cache.json');
 }
-
-
-//# sourceURL=ts/capabilities/session/action-cache.ts

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

@@ -1,83 +1,140 @@
+/**
+ * 携程机票站点适配器(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'
+    上海: '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 (!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: false, unresolved: unresolved.length > 0 ? unresolved : [depDate] };
     }
-    return {
-        ok: true,
-        url: `https://flights.ctrip.com/online/list/oneway-${fromCode}-${toCode}?depdate=${depDate}`
-    };
+    return { ok: true, url: `https://flights.ctrip.com/online/list/oneway-${fromCode}-${toCode}?depdate=${depDate}` };
 }
-export const NETWORK_HINTS = [
-    /search\/api\/search\/batchSearch/
-];
-export const LOGIN_COOKIE_NAMES = [
-    'cticket',
-    'uid',
-    'uname',
-    'passport'
-];
+/** 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 [];
+    }
+    catch {
+        return { options: [], verdict: 'error' };
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { options: [], verdict: 'error' };
+    }
+    const data = raw.data;
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return { options: [], verdict: 'error' };
+    }
+    const list = raw.data.flightItineraryList;
+    if (!Array.isArray(list)) {
+        return { options: [], verdict: 'error' };
     }
     const out = [];
-    for (const it of raw.data?.flightItineraryList ?? []){
-        const seg = it.flightSegments?.[0];
-        const fl = seg?.flightList?.[0];
-        if (!fl?.flightNo || !fl.departureDateTime) continue;
-        const prices = (it.priceList ?? []).map((p)=>Number(p.adultPrice ?? 0)).filter((n)=>n > 0);
+    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: fl.flightNo,
-            airline: seg?.airlineName ?? '',
-            depDateTime: fl.departureDateTime ?? '',
-            arrDateTime: fl.arrivalDateTime ?? '',
-            depAirport: fl.departureAirportName ?? '',
-            arrAirport: fl.arrivalAirportName ?? '',
-            durationMin: Number(seg?.duration ?? 0) || 0,
+            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: fl.aircraftName
+            aircraft: typeof f.aircraftName === 'string' ? f.aircraftName : undefined,
         });
     }
-    return out;
+    return {
+        options: out,
+        verdict: out.length > 0 ? 'hit' : list.length === 0 ? 'miss' : 'error',
+    };
 }
-
-
-//# sourceURL=ts/capabilities/session/adapters/ctrip-flight.ts