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

package/dist/capabilities/session/health-watch.js

@@ -0,0 +1,215 @@
+/**
+ * 扩展健康检查 + 自动重放(issue #21 onboarding UX,P3.6 gotry-session-onboarding-goal,
+ * RFC docs/rfc/user-session-data-rfc.md §3.3)。
+ *
+ * 动机:首次 `sessionFlightSearch` 遇 `needs-extension` 时,旧版要求用户装完扩展后**自己重跑命令**;
+ * 本模块把「用户手工重跑」改成「后台有界轮询 + 扩展一就位自动重放同一 query_id」——
+ * 用户装完扩展零后续动作,gotry 自己感知到 ready 后立刻跑同一条 query。
+ *
+ * 形态:
+ * - `startExtensionHealthWatch({ timeoutMs, intervalMs, probe })` 启后台轮询。
+ *   probe 是异步检测函数(默认 GET http://127.0.0.1:{port}/status,扩展 ≤30s 心跳一次,
+ *   1.5 倍容差 EXTENSION_CONNECTED_WINDOW_MS=45s;§38 已经验证扩展心跳节奏)。
+ * - 命中 ready → 调用方自动重放(query_id / args 不变;同一证据文件覆盖)。
+ * - 超时(timeoutMs 默认 120_000)→ 返回 'timeout',调用方降级回 `needs-extension` 错误面。
+ *
+ * 离线合同(run-all §40 onboarding-tests 5/5):
+ * - 三时序分支:probe 0ms ready / 中途 ready / 120s+1ms 超时;
+ * - 同 query_id 重放语义(参数透传);
+ * - 取消语义(timeoutMs=0 立即 timeout;cancel() 立即返回 'cancelled');
+ * - 重放上限(防止 watch 反复 ready/抖动导致无限重放;maxRetries 默认 1)。
+ *
+ * 纪律:
+ * - 不引 GUI 依赖;只 spawn `node:http` 探活(已经在扩展桥验证过,§38 24 断言覆盖);
+ * - 不持锁、不轮询文件、不读 dsh-runtime 共享状态;
+ * - 不污染扩展桥 single-instance;probe 走独立短连接。
+ */
+import { request } from 'node:http';
+import { BRIDGE_PORTS, EXTENSION_CONNECTED_WINDOW_MS, } from './extension-bridge.js';
+/**
+ * 双因子 probe(默认):心跳 + 业务探针(cookie-names)。
+ * 心跳通过只能证 SW 跑着;业务探针通过证 chrome.cookies 权限齐——二者同过才算
+ * 扩展真正 ready。wizard 必须双因子(用户刚装的扩展可能权限不全),上线 session
+ * 检索可传 `businessProbe:false` 跳业务探针(避免每次检索额外打一次 cookie-names)。
+ *
+ * 不直接 import extension-channel.ts(避免环)—用 dynamic import 懒拿。
+ */
+export async function combinedProbe(opts, businessProbe) {
+    if (!(await defaultProbe(opts)))
+        return false;
+    if (!businessProbe)
+        return true;
+    try {
+        // 动态 import 避免 health-watch ↔ extension-channel 双向环
+        const channel = await import('./extension-channel.js');
+        const bridge = await import('./extension-bridge.js');
+        // 双因子探针需要常驻桥(wizard 期间):keepBridge=true 透传到 bridge 单例
+        bridge.getOrCreateSessionBridge({ keepBridge: opts.keepBridge === true });
+        // 心跳已 ready(刚 defaultProbe 通过)= 扩展一定在线;cookie-names 超时给 8s,
+        // 比心跳间隔 5s 长——保证 tick 间不会撞死 cookie job
+        const cookie = await channel.extensionCookieNames({
+            site: 'ctrip-flight',
+            domain: 'ctrip.com',
+            ticketNames: ['cticket', 'uid'],
+            timeoutMs: 8_000,
+        });
+        // cookie-names.ok = true 表示扩展 SW 真能调 chrome.cookies.getAll(权限齐全);
+        // cookie-names.ok = true + names = [] 也算 ok(用户没登携程但扩展权限齐)。
+        // cookie-names.ok = false 分两类:bridge-unavailable/extension-not-connected(心跳 false 时) / timeout(扩展没回包)——
+        // 后者更可能是 SW 卡了,不应当 ready。但 wizard 必须严格:让用户明确知道权限缺或登录缺。
+        return cookie.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 默认 probe:GET http://127.0.0.1:{port}/status,看 extensionConnected: true
+ * (扩展心跳 ≤30s 一刷,窗口 EXTENSION_CONNECTED_WINDOW_MS=45s 容差)。
+ * 不在端口池内挑一个试——端口是已启动桥的事实,直接拿 opts.ports[0] 或 8791。
+ * 测试可注入 fake probe 跳过网络。
+ */
+export async function defaultProbe(opts) {
+    const ports = opts.ports ?? [...BRIDGE_PORTS];
+    for (const port of ports) {
+        const ok = await new Promise((resolve) => {
+            const req = request({ host: '127.0.0.1', port, path: '/status', method: 'GET', timeout: 2_000 }, (res) => {
+                if (!res.statusCode || res.statusCode >= 400) {
+                    resolve(false);
+                    return;
+                }
+                let buf = '';
+                res.setEncoding('utf8');
+                res.on('data', (c) => { buf += c; });
+                res.on('end', () => {
+                    try {
+                        const payload = JSON.parse(buf);
+                        resolve(payload.extensionConnected === true);
+                    }
+                    catch {
+                        resolve(false);
+                    }
+                });
+                res.on('error', () => resolve(false));
+            });
+            req.on('error', () => resolve(false));
+            req.on('timeout', () => { req.destroy(); resolve(false); });
+            req.end();
+        });
+        if (ok)
+            return true;
+    }
+    return false;
+}
+export function startExtensionHealthWatch(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 120_000;
+    const intervalMs = opts.intervalMs ?? 5_000;
+    const maxRetries = opts.maxRetries ?? 1;
+    const businessProbe = opts.businessProbe ?? true;
+    // 关键:wizard 期间需要常驻桥(keepBridge=true 透传到 getOrCreateSessionBridge),
+    // 否则启桥后 wizard main 一退桥就退,扩展心跳发不进来。
+    // 用 dynamic import 避免与 extension-bridge 顶层环(channel 也引 bridge,但 health-watch 引 channel/bridge 双向会死循环)
+    const probe = opts.probe ?? (async () => {
+        // 先确保桥存在 + keepBridge
+        const bridge = await import('./extension-bridge.js');
+        const created = await bridge.getOrCreateSessionBridge({ keepBridge: opts.keepBridge === true, ports: opts.ports });
+        // The default path must keep scanning the canonical pool: another GoTry
+        // process may already own the extension-connected bridge. An explicit
+        // port override is an isolation boundary, so probe only the bridge that
+        // this process actually bound (including an ephemeral `0` request).
+        const probeOpts = created.ok && opts.ports
+            ? { ...opts, ports: [created.bridge.port] }
+            : opts;
+        return combinedProbe(probeOpts, businessProbe);
+    });
+    const now = opts.now ?? Date.now;
+    const state = { cancelled: false, readyCount: 0, resolveOutcome: null };
+    const finish = (outcome) => {
+        if (state.resolveOutcome) {
+            const resolve = state.resolveOutcome;
+            state.resolveOutcome = null;
+            resolve(outcome);
+        }
+    };
+    // 取消信号 -> 立刻 timeout-ish 终态(不进 ready 路径)
+    const onAbort = () => {
+        state.cancelled = true;
+        finish({ ready: false, reason: 'cancelled', attempts: state.readyCount, waitedMs: 0 });
+    };
+    opts.signal?.addEventListener('abort', onAbort, { once: true });
+    const waitReady = () => new Promise((resolve) => {
+        if (state.cancelled) {
+            resolve({ ready: false, reason: 'cancelled', attempts: 0, waitedMs: 0 });
+            return;
+        }
+        if (timeoutMs === 0) {
+            resolve({ ready: false, reason: 'timeout', attempts: 0, waitedMs: 0 });
+            return;
+        }
+        state.resolveOutcome = resolve;
+        const deadline = now() + timeoutMs;
+        let attempts = 0;
+        let waitedMs = 0;
+        const tick = async () => {
+            if (state.cancelled || state.resolveOutcome === null)
+                return;
+            attempts += 1;
+            try {
+                const ready = await probe();
+                if (ready && !state.cancelled) {
+                    state.readyCount += 1;
+                    waitedMs = timeoutMs - Math.max(0, deadline - now());
+                    // readyCount > maxRetries → 视为抖动,继续等(避免一次性重放洪流)
+                    if (state.readyCount <= maxRetries) {
+                        finish({ ready: true, attempts, waitedMs: waitedMs > 0 ? waitedMs : 0 });
+                        return;
+                    }
+                }
+            }
+            catch { /* probe 失败继续轮询,不挡主流程 */ }
+            waitedMs = timeoutMs - Math.max(0, deadline - now());
+            if (now() >= deadline) {
+                finish({ ready: false, reason: 'timeout', attempts, waitedMs });
+                return;
+            }
+            // 间隔 = intervalMs;若剩余时间 < intervalMs 则最后一次等剩余时间
+            const remaining = deadline - now();
+            const delay = Math.min(intervalMs, Math.max(0, remaining));
+            if (delay <= 0) {
+                finish({ ready: false, reason: 'timeout', attempts, waitedMs });
+                return;
+            }
+            setTimeout(tick, delay);
+        };
+        void tick();
+    });
+    return {
+        waitReady,
+        cancel: () => onAbort(),
+        get readyCount() { return state.readyCount; },
+    };
+}
+/**
+ * 自动重放 wrapper:首次调用走 fetch(返回 needs-extension) → 启 watch →
+ * 扩展 ready → 同 query 重放。语义:用户侧**只看到一条 query 的最终结果**;
+ * 中间产物(query_id 标记 + 尝试次数)落 evidence 文件,便于离线追溯。
+ *
+ * 这是 §3.3「用户零手工重跑」的对外契约:调用方把 fetch 包成 withAutoRetryOnExtension,
+ * 用户装完扩展→自然出结果;用户不装→等 120s 后返回 needs-extension,而不是「再跑一次试试」。
+ */
+export async function withAutoRetryOnExtension(args) {
+    const first = await args.fetch();
+    if (!args.isExtensionNeeded(first)) {
+        return { result: first, retried: false, attempts: 1, outcome: { ready: true, attempts: 0, waitedMs: 0 } };
+    }
+    const watch = startExtensionHealthWatch(args.watch ?? {});
+    const outcome = await watch.waitReady();
+    if (!outcome.ready) {
+        return { result: first, retried: false, attempts: 1, outcome };
+    }
+    const retriedResult = await (args.retry ?? args.fetch)();
+    return { result: retriedResult, retried: true, attempts: 2, outcome };
+}
+/** 留作运行时只读检查,防止扩展心跳节律假设漂移(§38 防漂移同款语义) */
+export const HEALTH_WATCH_INTERVAL_FLOOR_MS = 1_000;
+export const HEALTH_WATCH_INTERVAL_CEIL_MS = EXTENSION_CONNECTED_WINDOW_MS - 1_000;

package/dist/capabilities/session/read-guard.js

@@ -0,0 +1,107 @@
+/**
+ * ReadGuard:会话检索面的只读物理隔离(RFC docs/rfc/user-session-data-rfc.md §3.3)。
+ *
+ * 写不是「被禁止的行为」,是「不存在的原语」——WriteGate(L0-L4)的检索态前置:
+ *   ① 网络层:route 拦截——命中硬支付模式(任意方法)或写方法+写URL模式 → abort + 审计落盘;
+ *   ② DOM 层:提交类按钮文本黑名单,从快照/断言文本中剔除(模型看不到可点的提交件);
+ *   ③ fail-closed:guard 未装上,session transport 不允许导航(openSession 装不上即整会话失败)。
+ *
+ * 审计:append-only JSONL(session-incidents.jsonl,对齐 incident-log 惯例),隔离 stateRoot。
+ * 注意:搜索接口多为 POST(如携程 batchSearch),因此写判定必须「方法 × URL 模式」双因子,
+ * 不能一刀切禁 POST——batchSearch 不含写词,放行。
+ */
+import { mkdirSync, appendFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** 硬支付模式:任意方法(含 GET)都视为写——进支付/收银面本身就是风险 */
+const HARD_PAY_RE = /\/(pay|payment|cashier)(\/|\?|$)/i;
+/** 驼峰复合写词(OTA 常见 /submitOrder、/createOrder):段式正则漏接,单列 */
+const WRITE_COMPOUND_RE = /(submitorder|createorder|placeorder|cancelorder|refundorder|orderconfirm|orderpay|confirmpay)/i;
+/** 写词 URL 模式:仅在写方法(POST/PUT/DELETE/PATCH)下触发 */
+const WRITE_URL_RE = /\/(order|orders|submit|trade|booking|book|purchase|buy|create|cancel|refund)(\/|\?|$)/i;
+const WRITE_METHODS = new Set(['POST', 'PUT', 'DELETE', 'PATCH']);
+/** DOM 提交件文本黑名单(§3.3-②):命中即从可交互面剔除 */
+export const SUBMIT_TEXT_RE = /下单|去支付|支付|预订|订票|购买|提交订单|确认订单/;
+/** 网络层写判定(纯函数,测试锚点) */
+export function classifyRequest(method, url) {
+    if (HARD_PAY_RE.test(url) || WRITE_COMPOUND_RE.test(url))
+        return 'block';
+    if (WRITE_METHODS.has(method.toUpperCase()) && WRITE_URL_RE.test(url))
+        return 'block';
+    return 'allow';
+}
+/** DOM 层提交件过滤(纯函数,测试锚点):true=剔除 */
+export function isSubmitText(text) {
+    return SUBMIT_TEXT_RE.test(text ?? '');
+}
+/**
+ * 装上网络层守卫(fail-closed 的「closed」在调用方:openSession 装不上 guard 即失败,不给无 guard 的会话)。
+ * 审计落 auditPath(JSONL append);auditPath 缺省不落盘(仅内存计数)。
+ */
+export async function attachReadGuard(ctx, auditPath) {
+    let blocked = 0;
+    let total = 0;
+    await ctx.route('**/*', async (route) => {
+        const req = route.request();
+        total += 1;
+        const verdict = classifyRequest(req.method(), req.url());
+        if (verdict === 'block') {
+            blocked += 1;
+            if (auditPath) {
+                const entry = { ts: new Date().toISOString(), kind: 'blocked-write-request', method: req.method(), url: req.url().slice(0, 400) };
+                try {
+                    mkdirSync(dirname(auditPath), { recursive: true });
+                    appendFileSync(auditPath, JSON.stringify(entry) + '\n');
+                }
+                catch { /* 审计失败不阻塞拦截本身 */ }
+            }
+            await route.abort('blockedbyclient');
+            return;
+        }
+        await route.continue();
+    });
+    return {
+        blockedCount: () => blocked,
+        requestCount: () => total,
+    };
+}
+/**
+ * puppeteer 版守卫:对既有页面与新建页面全部开启请求拦截,写请求 abort + 审计。
+ * 与 playwright 版共用 classifyRequest 判定与审计条目(单一事实源)。
+ */
+export async function attachReadGuardPuppeteer(browser, auditPath) {
+    let blocked = 0;
+    let total = 0;
+    const wire = (page) => {
+        void (async () => {
+            try {
+                await page.setRequestInterception(true);
+                page.on('request', async (req) => {
+                    total += 1;
+                    const verdict = classifyRequest(req.method(), req.url());
+                    if (verdict === 'block') {
+                        blocked += 1;
+                        if (auditPath) {
+                            const entry = { ts: new Date().toISOString(), kind: 'blocked-write-request', method: req.method(), url: req.url().slice(0, 400) };
+                            try {
+                                mkdirSync(dirname(auditPath), { recursive: true });
+                                appendFileSync(auditPath, JSON.stringify(entry) + '\n');
+                            }
+                            catch { /* 审计失败不阻塞拦截本身 */ }
+                        }
+                        await req.abort('blockedbyclient').catch(() => { });
+                        return;
+                    }
+                    await req.continue().catch(() => { });
+                });
+            }
+            catch { /* 已关闭的 target 容忍 */ }
+        })();
+    };
+    for (const p of await browser.pages())
+        wire(p);
+    browser.on('targetcreated', (t) => {
+        if (t.type() === 'page')
+            void t.page().then(wire).catch(() => { });
+    });
+    return { blockedCount: () => blocked, requestCount: () => total };
+}

package/dist/capabilities/session/static-flight-golden.js

@@ -0,0 +1,150 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function parseGoldenSource(args) {
+    const raw = args.find((arg) => arg.startsWith('--golden='))?.slice('--golden='.length) ?? 'manual';
+    if (raw === 'manual' || raw === 'flyai' || raw === 'static')
+        return raw;
+    throw new Error(`不支持的 golden vendor: ${raw}`);
+}
+export function loadStaticFlightSnapshot(path = join(import.meta.dirname, '..', '..', 'data', 'sf-static-routes.json')) {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isRecord(parsed) || parsed.schema_version !== 'sf-static-routes.v1') {
+        throw new Error(`invalid static snapshot schema_version: ${String(isRecord(parsed) ? parsed.schema_version : undefined)}`);
+    }
+    const source = parsed.source;
+    if (!isRecord(source)
+        || !['name', 'url', 'revision', 'license', 'retrieved_at'].every((key) => typeof source[key] === 'string')
+        || !Array.isArray(source.limitations)
+        || !source.limitations.every((item) => typeof item === 'string')) {
+        throw new Error('invalid static snapshot source');
+    }
+    if (!Array.isArray(parsed.routes) || !parsed.routes.every(isStaticFlightRoute)) {
+        throw new Error('invalid static snapshot routes');
+    }
+    return parsed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStaticFlightRoute(value) {
+    if (!isRecord(value)
+        || typeof value.query_id !== 'string'
+        || typeof value.from_city !== 'string'
+        || typeof value.to_city !== 'string'
+        || (value.route_kind !== 'direct' && value.route_kind !== 'transfer')
+        || !Array.isArray(value.legs)
+        || value.legs.length === 0)
+        return false;
+    return value.legs.every((leg) => isRecord(leg)
+        && typeof leg.from_iata === 'string'
+        && typeof leg.to_iata === 'string'
+        && Array.isArray(leg.carrier_codes)
+        && leg.carrier_codes.every((carrier) => typeof carrier === 'string'));
+}
+function provenance(snapshot) {
+    return {
+        route_source: snapshot?.source.url ?? '',
+        route_revision: snapshot?.source.revision ?? '',
+        route_license: snapshot?.source.license ?? '',
+        band_source: 'sf-golden-manifest.json',
+    };
+}
+function formatWithOffset(timestampMs, offset) {
+    const sign = offset.startsWith('-') ? -1 : 1;
+    const [hours, minutes] = offset.slice(1).split(':').map(Number);
+    const offsetMinutes = sign * ((hours ?? 0) * 60 + (minutes ?? 0));
+    const local = new Date(timestampMs + offsetMinutes * 60_000).toISOString().slice(0, 19);
+    return `${local}${offset}`;
+}
+function buildSegments(query, route, manualSegment) {
+    if (route.route_kind === 'direct' && route.legs.length === 1) {
+        return [{
+                from: query.from,
+                to: query.to,
+                departure_at: manualSegment.departure_at,
+                arrival_at: manualSegment.arrival_at,
+                transport_number: `${route.legs[0].carrier_codes[0]}-STATIC`,
+            }];
+    }
+    if (route.route_kind !== 'transfer' || route.legs.length !== 2)
+        return null;
+    const departureMs = Date.parse(manualSegment.departure_at);
+    const arrivalMs = Date.parse(manualSegment.arrival_at);
+    if (!Number.isFinite(departureMs) || !Number.isFinite(arrivalMs) || arrivalMs <= departureMs)
+        return null;
+    const offset = manualSegment.departure_at.match(/([+-]\d{2}:\d{2})$/)?.[1] ?? '+08:00';
+    const totalMinutes = Math.floor((arrivalMs - departureMs) / 60_000);
+    if (totalMinutes < 90)
+        return null;
+    const layoverMinutes = Math.min(60, Math.floor(totalMinutes / 3));
+    const travelMinutes = totalMinutes - layoverMinutes;
+    const firstTravelMinutes = Math.floor(travelMinutes / 2);
+    const secondDepartureMs = arrivalMs - (travelMinutes - firstTravelMinutes) * 60_000;
+    const middle = route.legs[0].to_iata;
+    return [
+        {
+            from: query.from,
+            to: middle,
+            departure_at: manualSegment.departure_at,
+            arrival_at: formatWithOffset(departureMs + firstTravelMinutes * 60_000, offset),
+            transport_number: `${route.legs[0].carrier_codes[0]}-STATIC`,
+        },
+        {
+            from: middle,
+            to: query.to,
+            departure_at: formatWithOffset(secondDepartureMs, offset),
+            arrival_at: manualSegment.arrival_at,
+            transport_number: `${route.legs[1].carrier_codes[0]}-STATIC`,
+        },
+    ];
+}
+export function resolveStaticGolden(input) {
+    const route = input.snapshot?.routes.find((candidate) => candidate.query_id === input.query.id);
+    let fallbackReason;
+    if (input.snapshotError) {
+        fallbackReason = `static snapshot unavailable: ${input.snapshotError}`;
+    }
+    else if (!route) {
+        fallbackReason = `static route missing for ${input.query.id}`;
+    }
+    else if (route.from_city !== input.query.from || route.to_city !== input.query.to) {
+        fallbackReason = `static route mismatch for ${input.query.id}`;
+    }
+    else if (route.legs.some((leg) => leg.carrier_codes.length === 0)) {
+        fallbackReason = `static carrier coverage missing for ${input.query.id}`;
+    }
+    const manualSegment = input.manualRecord.route_segments[0];
+    const segments = !fallbackReason && route && manualSegment
+        ? buildSegments(input.query, route, manualSegment)
+        : null;
+    if (!fallbackReason && !segments)
+        fallbackReason = `static route cannot form comparable record for ${input.query.id}`;
+    if (fallbackReason) {
+        input.warn?.(`[sf-live-benchmark] static vendor failed for ${input.query.id}: ${fallbackReason}; fallback=manual-golden`);
+        return {
+            requested_source: 'static',
+            effective_source: 'manual-golden',
+            record: input.manualRecord,
+            fallback_reason: fallbackReason,
+            estimated_fields: [],
+            provenance: provenance(input.snapshot),
+        };
+    }
+    return {
+        requested_source: 'static',
+        effective_source: 'static-openflights+manual-band',
+        record: {
+            ...input.manualRecord,
+            route_segments: segments,
+            journey_type: route.route_kind,
+            source: 'static-openflights+manual-band',
+        },
+        estimated_fields: [
+            'route_segments[].departure_at',
+            'route_segments[].arrival_at',
+            'route_segments[].transport_number',
+            'price',
+        ],
+        provenance: provenance(input.snapshot),
+    };
+}

package/dist/capabilities/session/transport.js

@@ -0,0 +1,109 @@
+/**
+ * SessionTransport(会话检索传输层,RFC §3.2;2026-08-28 定案 puppeteer-core):
+ * - mode=cdp(默认):attach 用户日常 Chrome——Chrome 144+ 调试服务(chrome://inspect 开关)
+ *   与 playwright 不兼容(握手后 CDP 初始化悬挂,实测三轮),与 puppeteer 完全兼容(实测 2256 cookies)。
+ *   发现走 user-data-dir 的 DevToolsActivePort 文件(HTTP 发现面已硬化 404;Origin 头=403,安全设计)。
+ *   close() 只 disconnect,绝不关用户浏览器。
+ * - mode=persistent(测试/后备):puppeteer.launch 专用 profile(测试用 mktemp 隔离匿名态)。
+ * fail-closed(RFC §3.3-④):guard 装不上 = 整个会话打不开——不存在「无守卫的会话」这一形态。
+ * 永不抛错:任何启动失败降级为 TransportFailure,由 session-search 编排层消费。
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { attachReadGuardPuppeteer } from './read-guard.js';
+/**
+ * puppeteer-core 为可选依赖(D-14:产品运行时零硬依赖,缺则优雅降级)。
+ * 顶层动态 import——npm 形态若未装 puppeteer-core,openSession 返回 TransportFailure
+ * 而非在模块加载期炸掉整个插件(2026-08-28 发布面实测:静态 import 会拖垮 index.ts 加载链)。
+ */
+async function loadPuppeteer() {
+    try {
+        return await import('puppeteer-core');
+    }
+    catch {
+        return { missing: true };
+    }
+}
+function devtoolsWsEndpoint() {
+    try {
+        const udd = process.env.CHROME_USER_DATA_DIR ?? `${homedir()}/Library/Application Support/Google/Chrome`;
+        const [port, wsPath] = readFileSync(`${udd}/DevToolsActivePort`, 'utf8').trim().split('\n');
+        if (!port || !wsPath?.startsWith('/devtools/browser/')) {
+            return { err: `DevToolsActivePort 内容异常: ${String(port)}/${String(wsPath)}` };
+        }
+        return { ws: `ws://127.0.0.1:${port.trim()}${wsPath.trim()}` };
+    }
+    catch {
+        return { err: '日常 Chrome 未开调试端口。开启方法:Chrome 打开 chrome://inspect/#remote-debugging → 打开开关(Chrome 144+)' };
+    }
+}
+export async function openSession(opts = {}) {
+    const pp = await loadPuppeteer();
+    if ('missing' in pp) {
+        return { ok: false, summary: 'puppeteer-core 未安装(可选依赖):会话检索不可用,官方通道 gotry_flyai_search 仍可用。安装:npm i -D puppeteer-core' };
+    }
+    const puppeteer = pp.default;
+    const useCdp = opts.mode === 'cdp' || (opts.mode !== 'persistent' && !opts.profileDir);
+    let browser;
+    let isCdp = false;
+    if (useCdp) {
+        const d = devtoolsWsEndpoint();
+        if ('err' in d)
+            return { ok: false, summary: d.err };
+        try {
+            browser = await puppeteer.connect({ browserWSEndpoint: d.ws, defaultViewport: null });
+            isCdp = true;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : e?.message ?? JSON.stringify(e).slice(0, 200);
+            return { ok: false, summary: `cdp attach 失败:${String(msg).split('\n')[0]}` };
+        }
+    }
+    else {
+        const { tmpdir } = await import('node:os');
+        const profileDir = opts.profileDir ?? `${tmpdir()}/gotry-session-profile`;
+        try {
+            browser = await puppeteer.launch({ channel: 'chrome', headless: opts.headless ?? true, userDataDir: profileDir });
+        }
+        catch (e) {
+            return { ok: false, summary: `chrome launch failed: ${e instanceof Error ? e.message.split('\n')[0] : String(e)}` };
+        }
+    }
+    // fail-closed:guard 装不上即断开返回失败——不给无守卫的检索会话形态
+    // (唯一豁免:登录 bootstrap 显式 guard:false,见 TransportOptions 注释)
+    let guard;
+    if (opts.guard !== false) {
+        try {
+            guard = await attachReadGuardPuppeteer(browser, opts.auditPath);
+        }
+        catch (e) {
+            await (isCdp ? browser.disconnect() : browser.close()).catch(() => { });
+            return { ok: false, summary: `read-guard attach failed: ${e instanceof Error ? e.message.split('\n')[0] : String(e)}` };
+        }
+    }
+    // 标签页纪律:ownPage=自己开的新页(newPage:true)——用它,收尾按 closeOwnPage 关;
+    // 否则沿用既有首页(仅 persistent 兼容形态;cdp 检索/登录一律 newPage)
+    let ownPage = false;
+    let page;
+    if (opts.newPage) {
+        page = await browser.newPage();
+        ownPage = true;
+    }
+    else {
+        page = (await browser.pages())[0] ?? await browser.newPage();
+    }
+    return {
+        ok: true,
+        browser,
+        page,
+        guard: guard ?? { blockedCount: () => 0, requestCount: () => 0 },
+        close: async () => {
+            // 自己开的标签页按 closeOwnPage 收尾(登录引导保持 false——登录页留给用户);
+            // cdp:只断开连接,绝不关用户浏览器;persistent:关自己拉起的实例
+            if (ownPage && (opts.closeOwnPage ?? true)) {
+                await page.close().catch(() => { });
+            }
+            await (isCdp ? browser.disconnect() : browser.close()).catch(() => { });
+        },
+    };
+}