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

package/ts/capabilities/session/extension-channel.ts

@@ -0,0 +1,144 @@
+/**
+ * 扩展车道客户端(RFC §2.2 通道 C,2026-08-29 PRIMARY;issue #21 传输层方案 B)。
+ *
+ * 三种 job 封装:search(被动嗅探 batchSearch)/ open-login(登录入口置前台)/
+ * cookie-names(票据 cookie **名字**,协议面不存在值字段)。verdict 映射纯函数
+ * `classifyBridgeFailure` 供回归覆盖:
+ *   - extension-not-connected → 'needs-extension'(waiting no-spend,一次性安装指引;
+ *     **不静默回退 CDP**——回退即重新引入逐连接权限框,正是本通道要消灭的摩擦);
+ *   - bridge-unavailable(端口池全占等环境故障)→ 'error'(非用户门)。
+ * 检索页无回包不是车道失败:调用侧判为 sniff_timeout/error,页标题命挑战则判 challenged。
+ */
+
+import { getOrCreateSessionBridge, needsExtensionSummary, type ExtensionJobResult, type SessionJobHandle, type SniffBodies } from './extension-bridge.ts'
+
+/**
+ * needs-extension 用户门文案(D-24 自适应,issue #117):按本地通道是否落位自动跳过
+ * 开发者模式/本地通道指引——商店版用户只看到商店一键装与「已装即可」提示。
+ * 旧静态常量已退役:静态文案无法感知安装状态,正是 D-24 残量的病灶。
+ */
+export function needsExtensionHint(): string {
+  return needsExtensionSummary()
+}
+
+export type BridgeFailureKind = 'bridge-unavailable' | 'extension-not-connected' | 'timeout' | 'job-error'
+
+export interface BridgeFailure {
+  ok: false
+  kind: BridgeFailureKind
+  summary: string
+}
+
+/** 桥故障 → 用户门 verdict 纯函数(测试锚点):只有「扩展未连接」是用户门(waiting),其余降级 error */
+export function classifyBridgeFailure(kind: BridgeFailureKind): 'needs-extension' | 'error' {
+  return kind === 'extension-not-connected' ? 'needs-extension' : 'error'
+}
+
+export interface SessionJobHandleRef {
+  ok: true
+  bridge: SessionJobHandle
+}
+
+function bridgeReady(b: { ok: true; bridge: SessionJobHandle } | { ok: false; summary: string }): b is SessionJobHandleRef {
+  return b.ok === true
+}
+
+function failedJob(result: ExtensionJobResult): BridgeFailure | null {
+  if (result.ok === true) return null
+  return {
+    ok: false,
+    kind: 'job-error',
+    summary: typeof result.error === 'string' && result.error.length > 0
+      ? result.error.slice(0, 200)
+      : '扩展作业失败且未提供原因',
+  }
+}
+
+/** 桥解析(2026-09-11):gotry-backend 服务形态注入进程内队列;桌面形态缺省走 loopback 懒单例 */
+async function resolveBridge(injected?: SessionJobHandle): Promise<SessionJobHandleRef | { ok: false; summary: string }> {
+  if (injected) return { ok: true, bridge: injected }
+  return getOrCreateSessionBridge()
+}
+
+/** cookie-names job:票据 cookie 名存在性(名字级;协议不含值) */
+export async function extensionCookieNames(q: { site: string; domain: string; ticketNames: string[]; timeoutMs?: number }, bridgeHandle?: SessionJobHandle): Promise<{ ok: true; tickets: string[]; origin?: string; clientId?: string } | BridgeFailure> {
+  const bridge = await resolveBridge(bridgeHandle)
+  if (!bridgeReady(bridge)) return { ok: false, kind: 'bridge-unavailable', summary: bridge.summary }
+  const outcome = await bridge.bridge.submit(
+    { kind: 'cookie-names', site: q.site, timeoutMs: q.timeoutMs ?? 8_000 },
+    { timeoutMs: q.timeoutMs ?? 8_000 },
+  )
+  if (!outcome.ok) return { ok: false, kind: outcome.reason, summary: outcome.summary }
+  const failure = failedJob(outcome.result)
+  if (failure) return failure
+  const names = Array.isArray(outcome.result.names) ? outcome.result.names.filter((n): n is string => typeof n === 'string') : []
+  // 红线自证:隧道面只有名字(extension-tests §红线断言协议面无值字段)
+  return { ok: true, tickets: names, ...(outcome.origin ? { origin: outcome.origin } : {}), ...(outcome.clientId ? { clientId: outcome.clientId } : {}) }
+}
+
+/** 登录入口置前台打开(#34 纪律:标签留给用户,扩展侧不 close) */
+export async function extensionOpenLogin(q: { site: string; url: string; timeoutMs?: number }, bridgeHandle?: SessionJobHandle): Promise<{ ok: true; opened: boolean } | BridgeFailure> {
+  const bridge = await resolveBridge(bridgeHandle)
+  if (!bridgeReady(bridge)) return { ok: false, kind: 'bridge-unavailable', summary: bridge.summary }
+  const outcome = await bridge.bridge.submit({ kind: 'open-login', site: q.site, url: q.url }, { timeoutMs: q.timeoutMs ?? 15_000 })
+  if (!outcome.ok) return { ok: false, kind: outcome.reason, summary: outcome.summary }
+  const failure = failedJob(outcome.result)
+  if (failure) return failure
+  if (!outcome.result.opened) return { ok: false, kind: 'job-error', summary: outcome.result.error ?? '登录入口打开失败' }
+  return { ok: true, opened: true }
+}
+
+export interface ExtensionSearchOutcome {
+  ok: true
+  /** NETWORK_HINTS 命中的响应原文;未命中/超时为空 */
+  body: string
+  /** Exact NETWORK_HINTS response URL selected for body;未命中/超时为空 */
+  url: string
+  /** 页标题(challenged 判定素材) */
+  title: string
+  /** 到点未见 hints 命中(站点无回包/风控拦截页) */
+  timedOut: boolean
+  /** multiCollect(dida 推荐流):分桶回包体;旧扩展/非 multiCollect 缺省 */
+  bodies?: SniffBodies
+  /** 页面级挑战标记(content-bridge 按 DOM 判定;网关侧不得用供应商响应体扫「验证」——会把酒店名误判成风控) */
+  challenge?: boolean
+}
+
+/** 检索 job:后台标签打开 entry,等 content hook 的嗅探回包;页无响应=timedOut(非车道失败) */
+export async function extensionSearchJob(
+  q: { site: string; url: string; timeoutMs?: number; multiCollect?: boolean; query?: Record<string, unknown>; preferredOrigin?: string; preferredClientId?: string },
+  bridgeHandle?: SessionJobHandle,
+): Promise<ExtensionSearchOutcome | BridgeFailure> {
+  const bridge = await resolveBridge(bridgeHandle)
+  if (!bridgeReady(bridge)) return { ok: false, kind: 'bridge-unavailable', summary: bridge.summary }
+  const timeoutMs = q.timeoutMs ?? 30_000
+  const outcome = await bridge.bridge.submit(
+    { kind: 'search', site: q.site, url: q.url, timeoutMs, ...(q.multiCollect ? { multiCollect: true } : {}), ...(q.query ? { query: q.query } : {}) },
+    { timeoutMs: timeoutMs + 10_000, ...(q.preferredOrigin ? { preferredOrigin: q.preferredOrigin } : {}), ...(q.preferredClientId ? { preferredClientId: q.preferredClientId } : {}) },
+  )
+  if (!outcome.ok) return { ok: false, kind: outcome.reason, summary: outcome.summary }
+  // An exhausted page sniff still carries the page title and challenge hint.
+  // Let the caller inspect them before classifying the empty body.
+  if (outcome.result.ok === false && outcome.result.timeout === true) {
+    return {
+      ok: true,
+      body: '',
+      url: '',
+      title: typeof outcome.result.title === 'string' ? outcome.result.title : '',
+      timedOut: true,
+      ...(outcome.result.challenge === true ? { challenge: true } : {}),
+    }
+  }
+  const failure = failedJob(outcome.result)
+  if (failure) return failure
+  const bodies = outcome.result.bodies
+  return {
+    ok: true,
+    ...(outcome.result.challenge === true ? { challenge: true } : {}),
+    body: typeof outcome.result.body === 'string' ? outcome.result.body : '',
+    url: typeof outcome.result.url === 'string' ? outcome.result.url : '',
+    title: typeof outcome.result.title === 'string' ? outcome.result.title : '',
+    timedOut: outcome.result.timeout === true,
+    ...(bodies && typeof bodies === 'object' ? { bodies } : {}),
+  }
+}

package/ts/capabilities/session/extension-distribution.ts

@@ -0,0 +1,266 @@
+/**
+ * 扩展产物分发(issue #21 分发通道,ADR-21;founder 2026-08-30「产物下载和安装也得做成更好的
+ * 用户体验,可以用 github 作为分发渠道」)。
+ *
+ * 平台硬约束(诚实前置):Chrome 禁止普通用户从任意 URL 安装打包 CRX——GitHub 只能改善
+ * 「下载」(版本化/回滚/与 npm 发版节奏解耦),改善不了「安装」;「开发者模式加载已解压」
+ * 那 3 次点击只有上架 Chrome Web Store 才能消掉(商店版自动更新,见 extension-webstore-submission.md)。
+ * manifest 固定 key ⇒ 双通道是同一个扩展 ID(olpgkofjhhiiiahdkkbcninhjmegghfe),端口池/
+ * host_permissions 不随通道漂移——本模块用 key 钉住这一不变量。
+ *
+ * 单一职责:① 产物源解析(bundled 默认离线确定性 | github 显式 opt-in);
+ * ② GitHub Releases 下载链:dist-manifest → tar.gz → SHA256 校验 → tar 解压 → key 钉扎校验
+ *    → 版本比较 → 原子交换 ~/.gotry/extension;
+ * ③ 失败语义:github 源任何失败(无网/404/校验不过/key 漂移)→ 结构化 fallback bundled,
+ *    绝不挡 setup(安装外部产物永远不挡 gotry 本体——bootstrap 契约)。
+ *
+ * 信任边界(诚实声明):TLS 传输 + 同源 dist-manifest 哈希完整性——防截断/损坏/误传资产,
+ * 不防仓库本身被攻陷(无独立 pinning;独立 pin 需把哈希烘进 npm 包,与「扩展更新与 npm
+ * 发版解耦」目标冲突,明确不做)。
+ *
+ * 零新 npm 依赖:fetch 走 Node ≥22 全局;解压走平台原生 `tar -xzf`(macOS/Linux/Windows10+
+ * 自带);SHA256 走 node:crypto。spawn/fetch 可注入(离线测试)。
+ */
+
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Releases 稳定资产名(每版覆盖同名上传;latest/download 永久链只认稳定名)。
+ *  与 scripts/package-extension.mjs 的资产名必须逐字一致——extension-distribution-tests 防漂移。 */
+export const DIST_ASSET_TARBALL = 'gotry-session-bridge.tar.gz'
+export const DIST_ASSET_STORE_ZIP = 'gotry-session-bridge-store.zip'
+export const DIST_ASSET_MANIFEST = 'extension-dist-manifest.json'
+
+export const DEFAULT_RELEASE_BASE = 'https://github.com/Danceiny/gotry/releases'
+
+export interface ExtensionDistManifest {
+  version: string
+  tarball: string
+  tarballSha256: string
+  zip: string
+  zipSha256: string
+  builtFromCommit?: string
+}
+
+export interface GithubSourceOptions {
+  /** Releases 基址(测试/镜像可指回环);默认 GitHub 官方 */
+  releaseBase?: string
+  /** 注入 fetch(离线测试);默认全局 fetch */
+  fetch?: typeof fetch
+  /** 注入 spawn(离线测试拦截 tar);默认 child_process.spawn */
+  spawnFn?: typeof spawn
+  /** 下载/解压超时(默认 60s,有界) */
+  timeoutMs?: number
+}
+
+export type ExtensionInstallAction = 'installed' | 'up-to-date' | 'fallback-bundled'
+
+export interface ExtensionInstallResult {
+  ok: boolean
+  action: ExtensionInstallAction
+  /** 远端 dist-manifest 声明的版本(action=up-to-date 时也带回,供比较报告) */
+  version?: string
+  /** 交换前 dest 里已就位的版本(无则 undefined) */
+  previousVersion?: string
+  error?: string
+}
+
+/** 纯函数:三段数字版本比较(a<b 负 / 相等 0 / a>b 正;非数字段按 0 处理,长度差补 0) */
+export function compareVersions(a: string, b: string): number {
+  const pa = String(a).split('.').map((s) => Number.parseInt(s, 10) || 0)
+  const pb = String(b).split('.').map((s) => Number.parseInt(s, 10) || 0)
+  const n = Math.max(pa.length, pb.length)
+  for (let i = 0; i < n; i += 1) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
+/** 纯函数:Releases latest/download 永久链(稳定资产名) */
+export function distAssetUrls(releaseBase: string = DEFAULT_RELEASE_BASE): { tarball: string; storeZip: string; manifest: string } {
+  const base = releaseBase.replace(/\/+$/, '')
+  return {
+    tarball: `${base}/latest/download/${DIST_ASSET_TARBALL}`,
+    storeZip: `${base}/latest/download/${DIST_ASSET_STORE_ZIP}`,
+    manifest: `${base}/latest/download/${DIST_ASSET_MANIFEST}`,
+  }
+}
+
+const SHA256_RE = /^[0-9a-f]{64}$/
+
+/** 纯函数:dist-manifest 解析,fail-closed(坏 JSON/缺字段/资产名漂移/哈希非 64-hex 一律拒绝) */
+export function parseDistManifest(raw: string): ExtensionDistManifest {
+  let obj: Record<string, unknown>
+  try {
+    obj = JSON.parse(raw) as Record<string, unknown>
+  } catch {
+    throw new Error('dist-manifest 不是合法 JSON')
+  }
+  const version = obj.version
+  const tarball = obj.tarball
+  const tarballSha256 = obj.tarballSha256
+  const zip = obj.zip
+  const zipSha256 = obj.zipSha256
+  // Chrome manifest version 形态:1-4 段点分整数(扩展版本跟随 gotry 主版本
+  // 0.0.1-rc.N → 四段投影 0.0.1.N,展示名走 version_name 原样)
+  if (typeof version !== 'string' || !/^\d+(\.\d+){1,3}$/.test(version)) throw new Error('dist-manifest.version 缺失或非 1-4 段点分整数')
+  if (tarball !== DIST_ASSET_TARBALL) throw new Error(`dist-manifest.tarball 资产名漂移(期望 ${DIST_ASSET_TARBALL})`)
+  if (zip !== DIST_ASSET_STORE_ZIP) throw new Error(`dist-manifest.zip 资产名漂移(期望 ${DIST_ASSET_STORE_ZIP})`)
+  if (typeof tarballSha256 !== 'string' || !SHA256_RE.test(tarballSha256)) throw new Error('dist-manifest.tarballSha256 非 64-hex')
+  if (typeof zipSha256 !== 'string' || !SHA256_RE.test(zipSha256)) throw new Error('dist-manifest.zipSha256 非 64-hex')
+  return {
+    version,
+    tarball,
+    tarballSha256,
+    zip,
+    zipSha256,
+    builtFromCommit: typeof obj.builtFromCommit === 'string' ? obj.builtFromCommit : undefined,
+  }
+}
+
+export function sha256Hex(bytes: Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+/** 读取扩展 manifest 的 key(固定 key ⇒ 固定扩展 ID;分发通道 ID 不变量的锚点) */
+export function readExtensionKey(extensionDir: string): string | undefined {
+  const p = join(extensionDir, 'manifest.json')
+  if (!existsSync(p)) return undefined
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf8')) as { key?: unknown }
+    return typeof m.key === 'string' ? m.key : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function readExtensionVersion(extensionDir: string): string | undefined {
+  const p = join(extensionDir, 'manifest.json')
+  if (!existsSync(p)) return undefined
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf8')) as { version?: unknown }
+    return typeof m.version === 'string' ? m.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function runTar(args: string[], spawnFn: typeof spawn, timeoutMs: number): Promise<{ ok: boolean; error?: string }> {
+  return new Promise((resolve) => {
+    const child = spawnFn('tar', args, { stdio: 'ignore' })
+    let done = false
+    const timer = setTimeout(() => {
+      if (!done) {
+        done = true
+        try {
+          child.kill('SIGKILL')
+        } catch {
+          /* ignore */
+        }
+        resolve({ ok: false, error: `tar 超时(>${timeoutMs}ms)` })
+      }
+    }, timeoutMs)
+    child.on('error', (e) => {
+      if (!done) {
+        done = true
+        clearTimeout(timer)
+        resolve({ ok: false, error: `tar 不可用:${e.message}` })
+      }
+    })
+    child.on('close', (code) => {
+      if (!done) {
+        done = true
+        clearTimeout(timer)
+        resolve(code === 0 ? { ok: true } : { ok: false, error: `tar exit ${code}` })
+      }
+    })
+  })
+}
+
+async function fetchBytes(url: string, fetchFn: typeof fetch, timeoutMs: number): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; error: string }> {
+  try {
+    const res = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) })
+    if (!res.ok) return { ok: false, error: `HTTP ${res.status} ${url}` }
+    const buf = new Uint8Array(await res.arrayBuffer())
+    return { ok: true, bytes: buf }
+  } catch (e) {
+    return { ok: false, error: `下载失败 ${(e as Error).message}` }
+  }
+}
+
+export interface InstallFromGithubOptions extends GithubSourceOptions {
+  /** 落位目录(默认 ~/.gotry/extension 由调用方决定,本层不猜) */
+  destDir: string
+  /** 钉扎参照:bundled extension/ 目录(其 manifest key 是 ID 不变量的基准;缺省只做版本校验) */
+  pinnedSourceDir?: string
+  /** 只报告不落盘(up-to-date/将安装哪个版本;不下载 tarball 之外的任何东西) */
+  checkOnly?: boolean
+}
+
+/**
+ * GitHub Releases → ~/.gotry/extension 安装链。
+ * 任何失败都返回 { ok:false, action:'fallback-bundled' }——调用方显式降级 bundled,
+ * 本函数不抛出(bootstrap 契约:安装外部产物永远不挡 gotry 本体)。
+ */
+export async function installExtensionFromGithub(opts: InstallFromGithubOptions): Promise<ExtensionInstallResult> {
+  const timeoutMs = opts.timeoutMs ?? 60_000
+  const fetchFn = opts.fetch ?? fetch
+  const spawnFn = opts.spawnFn ?? spawn
+  const urls = distAssetUrls(opts.releaseBase)
+  const fail = (error: string): ExtensionInstallResult => ({ ok: false, action: 'fallback-bundled', error })
+
+  const mRes = await fetchBytes(urls.manifest, fetchFn, timeoutMs)
+  if (!mRes.ok) return fail(mRes.error)
+  let manifest: ExtensionDistManifest
+  try {
+    manifest = parseDistManifest(new TextDecoder().decode(mRes.bytes))
+  } catch (e) {
+    return fail(`dist-manifest 校验失败:${(e as Error).message}`)
+  }
+
+  const previousVersion = readExtensionVersion(opts.destDir)
+  if (previousVersion != null && compareVersions(manifest.version, previousVersion) <= 0) {
+    return { ok: true, action: 'up-to-date', version: manifest.version, previousVersion }
+  }
+  if (opts.checkOnly) {
+    return { ok: true, action: 'up-to-date', version: manifest.version, previousVersion } // check-only 语义:报告远端版本,不落盘
+  }
+
+  const tRes = await fetchBytes(urls.tarball, fetchFn, timeoutMs)
+  if (!tRes.ok) return fail(tRes.error)
+  const actual = sha256Hex(tRes.bytes)
+  if (actual !== manifest.tarballSha256) return fail(`SHA256 不符(期望 ${manifest.tarballSha256.slice(0, 12)}… 实得 ${actual.slice(0, 12)}…)`)
+
+  // 落盘 → tar 解压 → key 钉扎 → 原子交换;incoming 目录同盘保证 rename 原子性
+  const incoming = `${opts.destDir}.incoming-${process.pid}-${Date.now()}`
+  const tarPath = `${incoming}.tar.gz`
+  try {
+    rmSync(incoming, { recursive: true, force: true })
+    mkdirSync(incoming, { recursive: true })
+    writeFileSync(tarPath, tRes.bytes)
+    // 包内含顶层目录 gotry-session-bridge/;--strip-components 落到 incoming 根
+    const ext = await runTar(['-xzf', tarPath, '-C', incoming, '--strip-components', '1'], spawnFn, timeoutMs)
+    if (!ext.ok) return fail(ext.error!)
+
+    const incomingKey = readExtensionKey(incoming)
+    if (incomingKey == null) return fail('解压产物缺 manifest.json/key(非法包)')
+    if (opts.pinnedSourceDir) {
+      const pinnedKey = readExtensionKey(opts.pinnedSourceDir)
+      if (pinnedKey != null && incomingKey !== pinnedKey) return fail('扩展 key 漂移(通道产物与 bundled 不同 ID——拒绝安装,防端口池/host 权限漂移)')
+    }
+    const incomingVersion = readExtensionVersion(incoming)
+    if (incomingVersion !== manifest.version) return fail(`解压产物版本(${incomingVersion})与 dist-manifest(${manifest.version})不符`)
+
+    rmSync(opts.destDir, { recursive: true, force: true })
+    cpSync(incoming, opts.destDir, { recursive: true })
+    return { ok: true, action: 'installed', version: manifest.version, previousVersion }
+  } catch (e) {
+    return fail(`落位失败 ${(e as Error).message}`)
+  } finally {
+    rmSync(incoming, { recursive: true, force: true })
+    rmSync(tarPath, { force: true })
+  }
+}

package/ts/capabilities/session/extract.ts

@@ -0,0 +1,54 @@
+/**
+ * a11y 快照兜底抽取器(RFC §2.3 第②层:站点无干净 XHR JSON 时,从可访问性树快照抽结构化条目)。
+ * 纯函数:输入 Playwright ariaSnapshot/domSnapshot 文本,输出归一化条目(role/name/ref),
+ * 供确定性规则或 LLM 按 schema 消费;不做任何页面交互。
+ *
+ * 辑律(ADR-12 同款边界):抽取只认结构(行首 role 与缩进),不做开放式语义猜测;
+ * 页面文本是不可信输入(RFC §3.5)——本层只归形状,语义判定在上游 schema 处。
+ */
+
+export interface A11yEntry {
+  /** 行首 role,如 button / textbox / link / heading / listitem */
+  role: string
+  /** 括号内 accessible name(去引号,截断 200) */
+  name: string
+  /** 快照行号(0 基,回指原快照) */
+  line: number
+}
+
+/**
+ * Playwright aria snapshot 行形如:
+ *   `- button "搜索" [ref=s1e5]`
+ *   `- heading "上海到丽江" [level=1]`
+ * 提取 role/name;无 name 的行(name='')保留占位(计数/结构比对仍可用)。
+ */
+export function extractA11yEntries(snapshotText: string, opts: { maxEntries?: number } = {}): A11yEntry[] {
+  const cap = opts.maxEntries ?? 500
+  const out: A11yEntry[] = []
+  const lines = snapshotText.split('\n')
+  for (let i = 0; i < lines.length && out.length < cap; i++) {
+    const m = /^[\s*-]*\s*([a-zA-Z][\w-]*)(?:\s+"((?:[^"\\]|\\.)*)")?/.exec(lines[i] ?? '')
+    if (!m) continue
+    const name = (m[2] ?? '').replace(/\\"/g, '"').slice(0, 200)
+    out.push({ role: m[1]!.toLowerCase(), name, line: i })
+  }
+  return out
+}
+
+/** DOM 提交件过滤入口(RFC §3.3-②):从条目集中剔除命中提交黑名单的可交互件,返回保留集 */
+export function filterSubmitEntries<T extends { role: string; name: string }>(entries: T[], isSubmit: (name: string) => boolean): T[] {
+  const interactive = new Set(['button', 'link', 'menuitem', 'option'])
+  return entries.filter((e) => !(interactive.has(e.role) && isSubmit(e.name)))
+}
+
+/** 名称相似度粗筛(自愈定位的候选排序底座;0=不同串,1=包含) */
+export function nameAffinity(a: string, b: string): number {
+  const x = a.trim(); const y = b.trim()
+  if (!x || !y) return 0
+  if (x === y) return 1
+  if (x.includes(y) || y.includes(x)) return 0.8
+  const sa = new Set(x); const sb = new Set(y)
+  let common = 0
+  for (const ch of sa) if (sb.has(ch)) common += 1
+  return common / Math.max(sa.size, sb.size)
+}

package/ts/capabilities/session/golden-score.ts

@@ -0,0 +1,139 @@
+import {
+  SESSION_FIELD_ACCURACY_THRESHOLD,
+  type SessionComparableRecord,
+} from './benchmark.ts'
+
+export interface GoldenBand {
+  query_id: string
+  from: string
+  to: string
+  date: string
+  window_dep_local: { earliest: string; latest: string }
+  window_arr_local: { earliest: string; latest: string }
+  duration_min: { min: number; max: number }
+  price_cny: { min: number; max: number }
+  transport_hint: string
+  known_flights: string[]
+}
+
+export interface GoldenSoftScore {
+  pass: boolean
+  total: number
+  correct: number
+  accuracy: number
+  missing: string[]
+  incorrect: string[]
+  golden_source: string
+}
+
+function parseHHmm(value: string): number {
+  const [hours, minutes] = value.split(':')
+  return parseInt(hours!, 10) * 60 + parseInt(minutes!, 10)
+}
+
+function parseLocalMinutes(value: string): number | null {
+  const match = value.match(/(\d{2}):(\d{2})/)
+  if (!match) return null
+  return parseInt(match[1]!, 10) * 60 + parseInt(match[2]!, 10)
+}
+
+function parseLocalDate(value: string): string | null {
+  return value.match(/^(\d{4}-\d{2}-\d{2})[T ]/)?.[1] ?? null
+}
+
+export function scoreSessionAgainstGoldenBand(
+  session: SessionComparableRecord,
+  band: GoldenBand,
+  goldenSource: string,
+): GoldenSoftScore {
+  const missing: string[] = []
+  const hardIncorrect: string[] = []
+  const segment = session.route_segments[0]
+
+  if (!session.query_id) missing.push('query_id')
+  else if (session.query_id !== band.query_id) hardIncorrect.push('query_id')
+  if (!session.currency) missing.push('currency')
+  else if (session.currency !== 'CNY') hardIncorrect.push('currency')
+  if (!session.source) missing.push('source')
+  else if (session.source !== 'ctrip-flight') hardIncorrect.push('source')
+  if (!session.verdict) missing.push('verdict')
+  else if (session.verdict !== 'hit') hardIncorrect.push('verdict')
+
+  if (!segment) {
+    missing.push(
+      'route_segments[0].from',
+      'route_segments[0].to',
+      'route_segments[0].departure_at',
+      'route_segments[0].arrival_at',
+      'route_segments[0].transport_number',
+    )
+  } else {
+    if (!segment.from) missing.push('route_segments[0].from')
+    else if (segment.from !== band.from) hardIncorrect.push('route_segments[0].from')
+    if (!segment.to) missing.push('route_segments[0].to')
+    else if (segment.to !== band.to) hardIncorrect.push('route_segments[0].to')
+    if (!segment.departure_at) missing.push('route_segments[0].departure_at')
+    else if (parseLocalDate(segment.departure_at) !== band.date) {
+      hardIncorrect.push('route_segments[0].departure_at.date')
+    }
+    if (!segment.arrival_at) missing.push('route_segments[0].arrival_at')
+    else if (parseLocalDate(segment.arrival_at) !== band.date) {
+      hardIncorrect.push('route_segments[0].arrival_at.date')
+    }
+    if (!segment.transport_number) missing.push('route_segments[0].transport_number')
+  }
+
+  const softChecks: Array<{ path: string; ok: boolean }> = []
+  if (segment?.departure_at) {
+    const minutes = parseLocalMinutes(segment.departure_at)
+    softChecks.push({
+      path: 'route_segments[0].departure_at',
+      ok: minutes !== null
+        && minutes >= parseHHmm(band.window_dep_local.earliest)
+        && minutes <= parseHHmm(band.window_dep_local.latest),
+    })
+  }
+  if (segment?.arrival_at) {
+    const minutes = parseLocalMinutes(segment.arrival_at)
+    softChecks.push({
+      path: 'route_segments[0].arrival_at',
+      ok: minutes !== null
+        && minutes >= parseHHmm(band.window_arr_local.earliest)
+        && minutes <= parseHHmm(band.window_arr_local.latest),
+    })
+  }
+  if (segment?.transport_number) {
+    const actual = segment.transport_number.toUpperCase()
+    softChecks.push({
+      path: 'route_segments[0].transport_number',
+      ok: band.known_flights.some((flight) => actual.startsWith(flight.toUpperCase()))
+        || band.known_flights.some((flight) => actual.includes(flight.toUpperCase().slice(0, 2))),
+    })
+  }
+  if (Number.isFinite(session.price) && session.price > 0) {
+    const margin = band.price_cny.max * 0.15
+    softChecks.push({
+      path: 'price',
+      ok: session.price >= band.price_cny.min - margin
+        && session.price <= band.price_cny.max + margin,
+    })
+  } else missing.push('price')
+
+  const softIncorrect = softChecks.filter((check) => !check.ok).map((check) => check.path)
+  const incorrect = [...hardIncorrect, ...softIncorrect]
+  // 合同字段固定为 13，缺字段不能靠缩小分母抬高准确率。
+  const total = 13
+  const correct = Math.max(0, total - new Set(missing).size - incorrect.length)
+  const accuracy = total > 0 ? correct / total : 0
+  return {
+    pass: missing.length === 0
+      && hardIncorrect.length === 0
+      && accuracy >= SESSION_FIELD_ACCURACY_THRESHOLD,
+    total,
+    correct,
+    accuracy,
+    missing: Array.from(new Set(missing)),
+    incorrect,
+    golden_source: goldenSource,
+  }
+}