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

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

@@ -0,0 +1,636 @@
+/**
+ * 会话扩展桥(extension-bridge,RFC docs/rfc/user-session-data-rfc.md §2.2 通道 C——2026-08-29 founder 定案为 PRIMARY 传输)。
+ *
+ * 形态:Node http 服务,懒启动单例,只绑 127.0.0.1,端口池 8791-8795(与 extension/manifest.json
+ * host_permissions 一一对应,防漂移测试守住);**零新依赖**(node:http 手写,对齐已退役 shell 薄壳
+ * 的回环纪律;不引 ws——MV3 Service Worker 靠 ≤20s 的长轮询节奏维持 30s 存活窗口,HTTP 够用)。
+ *
+ * 授权模型:扩展经「一次性安装」获得信任,每请求校验 Origin ∈ 双通道扩展源白名单
+ * (网页发起的跨域请求必带邪恶 Origin,直接 403;POST 端点强制;GET /health /status 是本机
+ * 诊断面放行)。不做 CORS——有 host_permissions 的扩展 fetch 天然免预检,网页过不来。
+ * 双通道 ID 实录(2026-09-02):unpacked 通道(bundled/GitHub Releases)由 manifest 固定 key
+ * 派生 EXTENSION_ID;Chrome Web Store 用商店自己的签名 key 重签(不认 manifest key),
+ * 商店版 ID = EXTENSION_ID_STORE。两个 ID 都是 founder 控制的同一扩展,白名单双收。
+ *
+ * 协议(长轮询):
+ *   GET  /health           → lastSeen 刷新(扩展每 ≤30s 一次 + 每次断线重连)
+ *   GET  /status           → 诊断面 {port, extensionConnected, lastSeenMsAgo, queued, inFlight, parked}
+ *   POST /jobs             → 长轮询取活(hold ≤20s 返 {job:null});扩展单客户端
+ *   POST /results/:jobId   → 善果/失败回传(≤8MB;batchSearch ~550KB)
+ * 语义:桥不存在即整个扩展车道不存在——fail-closed 不变量在调用方(session-search 的 needs-extension)。
+ * 审计:job 提交/回传写 GuardAuditEntry 同款 JSONL(kind:'extension-session-job',channel 层负责)。
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createServer } from 'node:http';
+/** 桥端口池(extension/manifest.json host_permissions 必须同面;§38 断言) */
+export const BRIDGE_PORTS = [8791, 8792, 8793, 8794, 8795];
+export const BRIDGE_PROTOCOL = 'session-bridge.v1';
+/** 扩展固定 ID(unpacked 通道:manifest key 派生;bundled/GitHub Releases 均此 ID。变更即失配,Node 侧拒绝) */
+export const EXTENSION_ID = 'olpgkofjhhiiiahdkkbcninhjmegghfe';
+export const EXTENSION_ORIGIN = `chrome-extension://${EXTENSION_ID}`;
+/**
+ * Chrome Web Store 版扩展 ID(2026-09-02 上架):商店用自己生成的签名 key 重签,
+ * **不认 manifest 里的固定 key**——商店版 ID 与 unpacked 版不同(上架材料文档的
+ * 「若商店不认 key」预案坐实)。item ID 即商店详情页 URL 末段。
+ */
+export const EXTENSION_ID_STORE = 'oeajpiccmonococjcegddlooeeohlbgd';
+export const EXTENSION_ORIGIN_STORE = `chrome-extension://${EXTENSION_ID_STORE}`;
+/** 商店详情页(一键安装 + 自动更新通道;推荐安装方式) */
+export const EXTENSION_STORE_URL = `https://chromewebstore.google.com/detail/gotry-session-bridge/${EXTENSION_ID_STORE}`;
+/** 桥信任的扩展 Origin 白名单:unpacked(固定 key)+ 商店版,双通道同一扩展同源信任 */
+export const EXTENSION_ORIGINS = [EXTENSION_ORIGIN, EXTENSION_ORIGIN_STORE];
+/**
+ * 本地 unpacked 通道是否已落位(~/.gotry/extension/manifest.json)。
+ * 商店版没有本地文件面(装在 Chrome 里),离线不可探测——本函数只回答「本地通道在不在」,
+ * 商店版用户在这里恒 false,这正是 D-24 自适应文案的判定输入。
+ */
+export function localExtensionInstalled(home = homedir()) {
+    return existsSync(join(home, '.gotry', 'extension', 'manifest.json'));
+}
+/**
+ * needs-extension 自适应摘要(issue #117,D-24 残量):
+ * - 本地 unpacked 已落位 → 完整双通道指引(商店 + GitHub/开发者模式本地通道);
+ * - 未落位(商店版用户,或完全未装)→ 只推商店一键装,并给「已装商店版?打开 Chrome 即可」
+ *   提示——**不再出现开发者模式/本地通道文案**(已装商店版的用户不该再被指导 load unpacked)。
+ * 影响面统一行:账号会话通道断 → 列表底部工具不提供;其余工具不受影响。
+ * 纯函数(默认 HOME 可注入)。
+ *
+ * 双语对照:CN=本函数返回值;EN 权威见 docs/capability-onboarding.md「Session Bridge 安装」段。
+ */
+const EXTENSION_IMPACT_LINE = '影响面:gotry_session_search / gotry_session_login(账号会话通道)不可用;携程机票/酒店实时检索、12306 余票、Dida 实时报价都依赖此通道。其它工具(机票 FlyAI、酒店 hbcli、地图、天气等)不受影响。';
+export function needsExtensionSummary(opts = {}) {
+    const local = opts.localInstalled ?? localExtensionInstalled(opts.home);
+    if (local) {
+        return 'GoTry Session Bridge 扩展未连接(未安装或已停用)。推荐 Chrome 应用商店一键装(自动更新) '
+            + `${EXTENSION_STORE_URL} ;或 npx @danceiny/gotry setup 落位后 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension。`
+            + EXTENSION_IMPACT_LINE;
+    }
+    return 'GoTry Session Bridge 扩展未连接。若你已从 Chrome 商店安装(自动更新):打开 Chrome 并确认扩展已启用即可自动连接,无需再装。'
+        + `若尚未安装:应用商店一键装 ${EXTENSION_STORE_URL} (装完零弹窗,浏览器自己当安装器)。`
+        + EXTENSION_IMPACT_LINE;
+}
+/** 扩展在线判定:/health 心跳 ≤30s 一次 + 轮询重连,1.5 倍容差 */
+export const EXTENSION_CONNECTED_WINDOW_MS = 45_000;
+/** /jobs 长轮询 hold 上限(必须 < MV3 SW 30s 存活窗口) */
+export const JOBS_LONG_POLL_MS = 20_000;
+/** 提交 job 时扩展尚未上线,等它连上桥的宽限(首次调用后桥才拉起,扩展 5s 内即回连) */
+export const DEFAULT_EXTENSION_WAIT_MS = 6_000;
+/** /results 回包上限(batchSearch ~550KB,余量给未来酒店/多航段) */
+export const MAX_RESULT_BODY_BYTES = 8 * 1024 * 1024;
+/** 扩展客户端标识形状(每 SW 生命周期一个 crypto.randomUUID);导出供事件上行端点(批次 B)同链校验 */
+export const CLIENT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function jobMatches(entry, capabilities, origin, clientId) {
+    if (entry.preferredOrigin && entry.preferredOrigin !== origin)
+        return false;
+    if (entry.preferredClientId && entry.preferredClientId !== clientId)
+        return false;
+    return capabilities == null || capabilities.size === 0 || capabilities.has(entry.job.site);
+}
+function readBody(req, cap) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let size = 0;
+        let done = false;
+        req.on('data', (c) => {
+            if (done)
+                return;
+            size += c.length;
+            if (size > cap) {
+                done = true;
+                req.removeAllListeners('data');
+                resolve({ err: `body 超 ${cap} 字节上限(防失控回包)` });
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => { if (!done) {
+            done = true;
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        } });
+        req.on('error', () => { if (!done) {
+            done = true;
+            resolve({ err: 'body 读取失败' });
+        } });
+    });
+}
+/** 站点导航类作业(会真实打开供应商页面的 kind;cookie-names 只读不导航) */
+const NAVIGATION_JOB_KINDS = new Set(['search', 'open-login']);
+export function isNavigationJobKind(kind) {
+    return NAVIGATION_JOB_KINDS.has(kind);
+}
+export function createBridgeJobQueue(opts = {}) {
+    const extensionOrigins = new Set(opts.extensionOrigins ?? EXTENSION_ORIGINS);
+    const now = opts.now ?? Date.now;
+    const store = opts.store;
+    const queue = [];
+    const inFlight = new Map();
+    const parked = [];
+    let lastSeenAt = 0;
+    let closed = false;
+    const extensionConnected = () => lastSeenAt > 0 && now() - lastSeenAt < EXTENSION_CONNECTED_WINDOW_MS;
+    /**
+     * 账本写兜底:持久面故障不得打断桥协议主路径(write-before-submit 的 INSERT 除外,
+     * 它在 submit 里直接决定提交成败)。stderr 留痕,作业照常流转。
+     */
+    const record = (label, write) => {
+        if (!store)
+            return;
+        try {
+            write();
+        }
+        catch (e) {
+            process.stderr.write(`[bridge] 账本写入失败(${label}): ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    };
+    /** 领走首个 capability 匹配的 job(移入 inFlight——回包按 jobId 路由,两处都可找到) */
+    function takeMatching(capabilities, origin, clientId) {
+        const idx = queue.findIndex((q) => jobMatches(q, capabilities, origin, clientId));
+        if (idx < 0)
+            return null;
+        const [next] = queue.splice(idx, 1);
+        next.claimedOrigin = origin;
+        next.claimedClientId = clientId;
+        inFlight.set(next.job.jobId, next);
+        record('markClaimed', () => store.markClaimed(next.job.jobId, { origin, clientId }));
+        if (isNavigationJobKind(next.job.kind))
+            record('noteSiteHit', () => store.noteSiteHit(next.job.site));
+        return next;
+    }
+    /** 扩展回包:queued 与 inFlight 两处都可寻址(job 执行失败 = result.ok:false,桥自身不吞) */
+    function resolveJob(jobId, parsed) {
+        const inFlightHit = inFlight.get(jobId);
+        if (inFlightHit) {
+            inFlight.delete(jobId);
+            if (inFlightHit.timer)
+                clearTimeout(inFlightHit.timer);
+            record('markResolved', () => store.markResolved(jobId, parsed));
+            record('client-login-site', () => {
+                const names = Array.isArray(parsed.names) ? parsed.names : [];
+                if (parsed.ok === true && inFlightHit.job.kind === 'cookie-names' && names.length > 0 && inFlightHit.claimedClientId) {
+                    store.recordClientLoginSite(inFlightHit.claimedClientId, inFlightHit.job.site);
+                }
+            });
+            inFlightHit.resolve({ ok: true, result: parsed, origin: inFlightHit.claimedOrigin, clientId: inFlightHit.claimedClientId });
+            return;
+        }
+        const idx = queue.findIndex((q) => q.job.jobId === jobId);
+        if (idx < 0)
+            return;
+        const [entry] = queue.splice(idx, 1);
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        record('markResolved', () => store.markResolved(jobId, parsed));
+        entry.resolve({ ok: true, result: parsed });
+    }
+    /** 新 job 入队时即时派发给 capability 匹配的 parked 取活者(否则要白等一个 20s 长轮询周期) */
+    function dispatchToParked(entry) {
+        const i = parked.findIndex((p) => jobMatches(entry, p.capabilities, p.origin, p.clientId));
+        if (i < 0)
+            return false;
+        const [p] = parked.splice(i, 1);
+        clearTimeout(p.timer);
+        entry.claimedOrigin = p.origin;
+        entry.claimedClientId = p.clientId;
+        inFlight.set(entry.job.jobId, entry);
+        record('markClaimed', () => store.markClaimed(entry.job.jobId, { origin: p.origin, clientId: p.clientId }));
+        if (isNavigationJobKind(entry.job.kind))
+            record('noteSiteHit', () => store.noteSiteHit(entry.job.site));
+        p.res.statusCode = 200;
+        p.res.setHeader('content-type', 'application/json');
+        p.res.end(JSON.stringify({ job: entry.job }));
+        return true;
+    }
+    const stats = () => ({
+        queued: queue.length,
+        inFlight: inFlight.size,
+        parked: parked.length,
+        lastSeenMsAgo: lastSeenAt > 0 ? now() - lastSeenAt : null,
+    });
+    /**
+     * 结算器(submit 与 recoverOnBoot 复活条目共用):内存三态清理 + 账本终态落笔。
+     * 幂等护栏(settled 标记)防 waitTimer 兜底在 resolved 之后二次结算把账本写花。
+     * 超时结算规则(批次 A):曾被领取→unresolved+导航类记节律冷却(站点可能已被打);
+     * 从未被领取→void(零花费)。extension-not-connected 同为零花费 void;
+     * close 作废时已领取条目**留在 claimed**——持久记录交给下一轮 recoverOnBoot 收敛
+     * (扩展迟到回包仍可经 recordOrphanResult 对账,不虚构终态)。
+     */
+    function armSettle(entry, deliver) {
+        let settled = false;
+        return (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            const i = queue.findIndex((q) => q.job.jobId === entry.job.jobId);
+            if (i >= 0)
+                queue.splice(i, 1);
+            const wasClaimed = inFlight.delete(entry.job.jobId) || entry.claimedOrigin !== undefined;
+            // outcome.ok 的 resolved 已在 resolveJob 落账;这里只结算失败终态
+            if (store && !outcome.ok) {
+                if (outcome.reason === 'timeout') {
+                    if (wasClaimed) {
+                        record('markUnresolved', () => store.markUnresolved(entry.job.jobId, { reason: 'timeout' }));
+                        if (isNavigationJobKind(entry.job.kind))
+                            record('applyCooldown', () => store.applyCooldown(entry.job.site));
+                    }
+                    else {
+                        record('markVoid', () => store.markVoid(entry.job.jobId));
+                    }
+                }
+                else if (outcome.reason === 'extension-not-connected') {
+                    record('markVoid', () => store.markVoid(entry.job.jobId));
+                }
+                else if (!wasClaimed) {
+                    record('markVoid', () => store.markVoid(entry.job.jobId));
+                }
+            }
+            deliver?.(outcome);
+        };
+    }
+    /**
+     * 开机恢复(仅 store 形态;纯内存 no-op):
+     *   queued 未过期 → 重新入队(可被派发,迟到善果仍 resolved 落账);
+     *   queued 已过期 → void(未被领取即过期,零花费不再派发);
+     *   claimed 未超时 → 复活进 inFlight(重启丢在飞作业的修复面:扩展若已领取,回包直达);
+     *   claimed 已超时 → unresolved + 导航类记节律冷却(该站点可能已被打)。
+     * payload 损坏(id 不匹配/非 JSON)按不可对账处理:queued→void / claimed→unresolved。
+     */
+    function recoverOnBoot() {
+        const summary = { requeued: 0, rehydratedInFlight: 0, settledUnresolved: 0, voidedStale: 0 };
+        if (!store || closed)
+            return summary;
+        let pending = [];
+        try {
+            pending = store.listPendingJobs();
+        }
+        catch (e) {
+            process.stderr.write(`[bridge] 账本恢复读取失败:${e instanceof Error ? e.message : String(e)}\n`);
+            return summary;
+        }
+        for (const row of pending) {
+            const expired = row.timeout_at !== null && row.timeout_at <= now();
+            let job = null;
+            try {
+                const parsed = JSON.parse(row.payload_json);
+                if (parsed && typeof parsed.jobId === 'string' && parsed.jobId === row.id)
+                    job = parsed;
+            }
+            catch { /* 损坏 payload 按不可对账处理 */ }
+            if (row.status === 'claimed') {
+                if (!expired && job) {
+                    const entry = {
+                        job,
+                        resolve: null,
+                        timer: null,
+                        claimedOrigin: row.claimed_origin ?? undefined,
+                        claimedClientId: row.claimed_by_client ?? undefined,
+                    };
+                    const settle = armSettle(entry);
+                    entry.resolve = settle;
+                    const remaining = row.timeout_at !== null ? Math.max(row.timeout_at - now(), 1) : 30_000;
+                    entry.timer = setTimeout(() => settle({ ok: false, reason: 'timeout', summary: `恢复作业 ${row.id} 超时未回包` }), remaining);
+                    inFlight.set(row.id, entry);
+                    summary.rehydratedInFlight++;
+                }
+                else {
+                    record('markUnresolved', () => store.markUnresolved(row.id, { reason: 'timeout' }));
+                    if (isNavigationJobKind(row.kind))
+                        record('applyCooldown', () => store.applyCooldown(row.site));
+                    summary.settledUnresolved++;
+                }
+            }
+            else {
+                if (!expired && job) {
+                    const entry = {
+                        job,
+                        resolve: null,
+                        timer: null,
+                    };
+                    const settle = armSettle(entry);
+                    entry.resolve = settle;
+                    const remaining = row.timeout_at !== null ? Math.max(row.timeout_at - now(), 1) : 30_000;
+                    entry.timer = setTimeout(() => settle({ ok: false, reason: 'timeout', summary: `恢复作业 ${row.id} 超时未回包` }), remaining);
+                    if (!dispatchToParked(entry))
+                        queue.push(entry);
+                    summary.requeued++;
+                }
+                else {
+                    record('markVoid', () => store.markVoid(row.id));
+                    summary.voidedStale++;
+                }
+            }
+        }
+        return summary;
+    }
+    /**
+     * 协议处理器工厂:prefix='' 为独立桥形态(路径式 results);prefix='/v1/session/bridge'
+     * 为挂载形态(查询式 results——gotry-backend 内核只支持精确路由,jobId 走 query)。
+     * Origin 白名单校验内置于两种形态(远程形态同样强制:网页跨域请求必带邪恶 Origin)。
+     */
+    function makeHandler(prefix, resultsViaQuery, statusExtra) {
+        return (req, res) => {
+            if (closed) {
+                res.statusCode = 503;
+                res.end();
+                return;
+            }
+            const urlPath = (req.url ?? '').split('?')[0];
+            const path = prefix && urlPath.startsWith(prefix) ? urlPath.slice(prefix.length) : urlPath;
+            const origin = req.headers.origin;
+            const isPost = req.method === 'POST';
+            const originTrusted = typeof origin === 'string' && extensionOrigins.has(origin);
+            // 网页侧请求必带 Origin;桥端点只信任白名单内的 chrome-extension:// 源(诊断 GET 面放行)
+            if (isPost && !originTrusted) {
+                res.statusCode = 403;
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify({ ok: false, error: 'origin 不在桥白名单' }));
+                return;
+            }
+            // 心跳:扩展平时只走 /jobs 长轮询(健康只在启动探测时 ping 一次)——
+            // 一切携带白名单扩展 Origin 的请求都刷新 lastSeen,否则 45s 后误判扩展掉线;
+            // 无 Origin 的诊断 GET(/health /status)不记心跳,curl 探活不能伪造「扩展在线」
+            if (originTrusted) {
+                lastSeenAt = now();
+            }
+            const finish = (code, body) => {
+                res.statusCode = code;
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify(body));
+            };
+            if (req.method === 'GET' && path === '/health') {
+                finish(200, { ok: true, service: 'gotry-session-bridge', protocol: BRIDGE_PROTOCOL });
+                return;
+            }
+            if (req.method === 'GET' && path === '/status') {
+                finish(200, {
+                    ok: true, protocol: BRIDGE_PROTOCOL, ...stats(),
+                    extensionConnected: extensionConnected(),
+                    ...(statusExtra ? statusExtra() : {}),
+                });
+                return;
+            }
+            if (isPost && path === '/jobs') {
+                // 轮询体携带 {extensionVersion, capabilities: SITES 键清单}——按站点 capability
+                // 路由(见 ParkedPoller 注);体缺失/非 JSON 视为 match-all,向前兼容旧扩展。
+                void readBody(req, 64 * 1024).then((body) => {
+                    const pollerInfo = (() => {
+                        if (typeof body !== 'string')
+                            return { capabilities: null };
+                        try {
+                            const parsed = JSON.parse(body);
+                            return {
+                                capabilities: Array.isArray(parsed.capabilities) ? new Set(parsed.capabilities.filter((c) => typeof c === 'string')) : null,
+                                ...(typeof parsed.clientId === 'string' && CLIENT_ID_RE.test(parsed.clientId) ? { clientId: parsed.clientId } : {}),
+                            };
+                        }
+                        catch {
+                            return { capabilities: null };
+                        }
+                    })();
+                    // 客户端注册落账(store 形态):轮询即刷新 origin/capabilities/last_seen(bridge_clients upsert)
+                    if (pollerInfo.clientId) {
+                        record('upsertClient', () => store.upsertClient(pollerInfo.clientId, origin, [...(pollerInfo.capabilities ?? [])]));
+                    }
+                    const next = takeMatching(pollerInfo.capabilities, origin, pollerInfo.clientId);
+                    if (next) {
+                        finish(200, { job: next.job });
+                        return;
+                    }
+                    // 长轮询:hold ≤ JOBS_LONG_POLL_MS(必须 < MV3 SW 30s 存活窗口,每次响应都续命);
+                    // 新 job 提交时即时唤醒 parked 取活者(见 dispatchToParked)
+                    const poller = { res, timer: null, capabilities: pollerInfo.capabilities, origin: origin, clientId: pollerInfo.clientId };
+                    const parkTimer = setTimeout(() => {
+                        const i = parked.findIndex((p) => p.res === res);
+                        if (i >= 0)
+                            parked.splice(i, 1);
+                        finish(200, { job: null });
+                    }, JOBS_LONG_POLL_MS);
+                    poller.timer = parkTimer;
+                    // 默认桥是惰性能力:外部扩展的 parked 轮询不得在主流程结束后钉住 CLI。
+                    // keepBridge wizard 反过来要靠它守住进程,因此只对默认形态 unref。
+                    if (!opts.keepBridge)
+                        parkTimer.unref();
+                    parked.push(poller);
+                    res.on('close', () => {
+                        const i = parked.findIndex((p) => p.res === res);
+                        if (i >= 0)
+                            parked.splice(i, 1);
+                        clearTimeout(parkTimer);
+                    });
+                });
+                return;
+            }
+            const isResults = isPost && (resultsViaQuery ? path === '/results' : path.startsWith('/results/'));
+            if (isResults) {
+                const jobId = resultsViaQuery
+                    ? new URL(req.url ?? '', 'http://bridge.local').searchParams.get('jobId') ?? ''
+                    : decodeURIComponent(path.slice('/results/'.length));
+                if (!jobId) {
+                    finish(400, { ok: false, error: '缺 jobId' });
+                    return;
+                }
+                void readBody(req, MAX_RESULT_BODY_BYTES).then((body) => {
+                    if (typeof body !== 'string') {
+                        finish(400, { ok: false, error: body.err });
+                        return;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(body);
+                    }
+                    catch {
+                        finish(400, { ok: false, error: '回包不是 JSON' });
+                        return;
+                    }
+                    const assigned = inFlight.get(jobId);
+                    if (assigned?.claimedOrigin && assigned.claimedOrigin !== origin) {
+                        finish(403, { ok: false, error: '作业由另一扩展 Origin 领取' });
+                        return;
+                    }
+                    if (assigned?.claimedClientId && assigned.claimedClientId !== req.headers['x-gotry-client-id']) {
+                        finish(403, { ok: false, error: '作业由另一扩展客户端领取' });
+                        return;
+                    }
+                    // 未知 jobId(批次 A):不再 200 静默丢弃——404 明示,孤儿回包内容落账
+                    // (status='unresolved',result_json 保留)供对账。扩展 postResult 本就有
+                    // catch 且不检查状态码(extension/background.js),协议兼容零改动。
+                    const known = assigned !== undefined || queue.some((q) => q.job.jobId === jobId);
+                    if (!known) {
+                        record('orphan-result', () => store.recordOrphanResult(jobId, parsed));
+                        finish(404, { ok: false, error: 'unknown-job' });
+                        return;
+                    }
+                    finish(200, { ok: true });
+                    resolveJob(jobId, parsed);
+                });
+                return;
+            }
+            finish(404, { ok: false, error: 'unknown endpoint' });
+        };
+    }
+    const queueHandle = {
+        port: 0,
+        extensionConnected,
+        stats,
+        handleRequest: makeHandler('', false),
+        handleMountedRequest: makeHandler('/v1/session/bridge', true),
+        ...(store ? { recoverOnBoot } : {}),
+        submit(job, submitOpts = {}) {
+            const extensionWaitMs = submitOpts.extensionWaitMs ?? DEFAULT_EXTENSION_WAIT_MS;
+            const timeoutMs = submitOpts.timeoutMs ?? job.timeoutMs ?? 30_000;
+            const full = { jobId: randomUUID(), ...job };
+            return new Promise((resolve) => {
+                if (closed) {
+                    resolve({ ok: false, reason: 'bridge-unavailable', summary: '扩展桥已关闭' });
+                    return;
+                }
+                if (submitOpts.preferredOrigin && !extensionOrigins.has(submitOpts.preferredOrigin)) {
+                    resolve({ ok: false, reason: 'bridge-unavailable', summary: '指定扩展 Origin 不在桥白名单' });
+                    return;
+                }
+                if (submitOpts.preferredClientId && !CLIENT_ID_RE.test(submitOpts.preferredClientId)) {
+                    resolve({ ok: false, reason: 'bridge-unavailable', summary: '指定扩展客户端标识无效' });
+                    return;
+                }
+                // write-before-submit(store 形态):先落 queued 再入队/派发——持久面失败即提交失败,
+                // 绝不派发无账作业。桌面纯内存形态此步整体跳过,行为零变化。
+                if (store) {
+                    try {
+                        store.insertQueuedJob(full, now() + timeoutMs);
+                    }
+                    catch (e) {
+                        resolve({ ok: false, reason: 'bridge-unavailable', summary: `桥账本写入失败,作业不入队:${e instanceof Error ? e.message : String(e)}` });
+                        return;
+                    }
+                    if (isNavigationJobKind(full.kind))
+                        record('noteSiteHit', () => store.noteSiteHit(full.site));
+                }
+                const entry = { job: full, resolve: null, timer: null, preferredOrigin: submitOpts.preferredOrigin, preferredClientId: submitOpts.preferredClientId };
+                const settle = armSettle(entry, resolve);
+                entry.resolve = settle;
+                entry.timer = setTimeout(() => {
+                    settle({ ok: false, reason: 'timeout', summary: `扩展未在 ${timeoutMs}ms 内回包(标签页无嗅探命中或扩展已停用)` });
+                }, timeoutMs);
+                if (!dispatchToParked(entry))
+                    queue.push(entry);
+                // 扩展未上线:有界等待(桥刚拉起时扩展 ≤5s 即连上);宽限过仍无 → 立即 no-spend 失败,不空耗
+                let waited = 0;
+                const waitTimer = setInterval(() => {
+                    waited += 250;
+                    if (queueHandle.extensionConnected()) {
+                        clearInterval(waitTimer);
+                        return;
+                    }
+                    if (waited >= extensionWaitMs) {
+                        clearInterval(waitTimer);
+                        settle({
+                            ok: false,
+                            reason: 'extension-not-connected',
+                            // D-24 自适应文案(issue #117):按本地通道是否落位决定是否提及开发者模式
+                            summary: needsExtensionSummary(),
+                        });
+                    }
+                }, 250);
+            });
+        },
+        close: () => new Promise((resolve) => {
+            closed = true;
+            const voided = { ok: false, reason: 'bridge-unavailable', summary: '扩展桥关闭,任务作废(零花费)' };
+            for (const q of queue.splice(0)) {
+                if (q.timer)
+                    clearTimeout(q.timer);
+                q.resolve(voided);
+            }
+            for (const [, q] of inFlight) {
+                if (q.timer)
+                    clearTimeout(q.timer);
+                q.resolve(voided);
+            }
+            inFlight.clear();
+            for (const p of parked.splice(0)) {
+                clearTimeout(p.timer);
+                p.res.destroy();
+            }
+            resolve();
+        }),
+    };
+    return queueHandle;
+}
+/** 创 Bridge 服务(测试可直接调;生产走 getOrCreateSessionBridge 懒单例) */
+export async function createSessionBridge(opts = {}) {
+    const ports = opts.ports ?? [...BRIDGE_PORTS];
+    const queueHandle = createBridgeJobQueue(opts);
+    let port = 0;
+    const server = createServer((req, res) => queueHandle.handleRequest(req, res));
+    server.on('connection', (socket) => {
+        // server.unref() 只解开监听器;已接受的扩展长轮询 socket 仍会引用事件循环。
+        if (!opts.keepBridge)
+            socket.unref();
+    });
+    const bridge = {
+        port: 0,
+        extensionConnected: queueHandle.extensionConnected,
+        submit: (job, submitOpts) => queueHandle.submit(job, submitOpts),
+        close: () => new Promise((resolve) => {
+            void queueHandle.close().then(() => {
+                server.close(() => resolve());
+                server.closeAllConnections?.();
+            });
+        }),
+    };
+    const listenAt = (p) => new Promise((resolve, reject) => {
+        const onError = (e) => { server.off('listening', onListening); reject(e); };
+        const onListening = () => { server.off('error', onError); resolve(); };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(p, '127.0.0.1');
+    });
+    for (const p of ports) {
+        try {
+            await listenAt(p);
+            if (!opts.keepBridge) {
+                // 桥是后台服务:不得钉住事件循环——否则任何跑完主流程的宿主进程(如 smoke/CI)无法退出
+                server.unref();
+            }
+            // keepBridge 模式下:wizard 期间要持续监听扩展心跳(30s 周期),
+            // 不 unref 让 server 钉事件循环,wizard main 退时再显式 close 释放。
+            port = server.address().port;
+            bridge.port = port;
+            return { ok: true, bridge };
+        }
+        catch {
+            // 端口被占(如另一个 gotry 实例)——试端口池下一个
+        }
+    }
+    await queueHandle.close().catch(() => { });
+    return {
+        ok: false,
+        summary: `扩展桥端口池 ${ports.join('/')} 全部被占(多为并行 gotry 实例);不影响官方通道 gotry_flyai_search。关闭多余实例后重试。`,
+    };
+}
+/* ---------- 生产懒单例(进程内随 dsh 存活;失败可重试) ---------- */
+let singleton = null;
+export async function getOrCreateSessionBridge(opts = {}) {
+    if (singleton)
+        return singleton;
+    const created = await createSessionBridge(opts);
+    const result = created.ok
+        ? { ok: true, bridge: created.bridge }
+        : { ok: false, summary: created.summary };
+    singleton = result;
+    return result;
+}
+/** 测试隔离:丢弃单例(端口是进程内资源,close 后端口池立即可复用) */
+export async function __resetSessionBridgeForTest() {
+    if (singleton?.ok)
+        await singleton.bridge.close().catch(() => { });
+    singleton = null;
+}
+/** 测试注入:以临时端口的桥替换单例(channel 层测试不碰真实端口池) */
+export function __setSessionBridgeForTest(bridge) {
+    singleton = bridge ? { ok: true, bridge } : null;
+}