@danceiny/gotry 0.0.1-rc.18 → 0.0.1-rc.19

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

@@ -1,5 +1,5 @@
 /**
- * 会话扩展桥(extension-bridge,RFC user-session-data-rfc.md §2.2 通道 C——2026-08-29 founder 定案为 PRIMARY 传输)。
+ * 会话扩展桥(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 薄壳
@@ -22,6 +22,9 @@
  */
 
 import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
 
 /** 桥端口池(extension/manifest.json host_permissions 必须同面;§38 断言) */
@@ -41,6 +44,32 @@ 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: readonly string[] = [EXTENSION_ORIGIN, EXTENSION_ORIGIN_STORE]
+
+/**
+ * 本地 unpacked 通道是否已落位(~/.gotry/extension/manifest.json)。
+ * 商店版没有本地文件面(装在 Chrome 里),离线不可探测——本函数只回答「本地通道在不在」,
+ * 商店版用户在这里恒 false,这正是 D-24 自适应文案的判定输入。
+ */
+export function localExtensionInstalled(home = homedir()): boolean {
+  return existsSync(join(home, '.gotry', 'extension', 'manifest.json'))
+}
+
+/**
+ * needs-extension 自适应摘要(issue #117,D-24 残量):
+ * - 本地 unpacked 已落位 → 完整双通道指引(商店 + GitHub/开发者模式本地通道);
+ * - 未落位(商店版用户,或完全未装)→ 只推商店一键装,并给「已装商店版?打开 Chrome 即可」
+ *   提示——**不再出现开发者模式/本地通道文案**(已装商店版的用户不该再被指导 load unpacked)。
+ * 纯函数(默认 HOME 可注入)。
+ */
+export function needsExtensionSummary(opts: { localInstalled?: boolean; home?: string } = {}): string {
+  const local = opts.localInstalled ?? localExtensionInstalled(opts.home)
+  if (local) {
+    return 'GoTry Session Bridge 扩展未连接(未安装或已停用)。推荐 Chrome 应用商店一键装(自动更新) '
+      + `${EXTENSION_STORE_URL} ;或 npx gotry setup 落位后 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension`
+  }
+  return 'GoTry Session Bridge 扩展未连接。若你已从 Chrome 商店安装(自动更新):打开 Chrome 并确认扩展已启用即可自动连接,无需再装。'
+    + `若尚未安装:应用商店一键装 ${EXTENSION_STORE_URL} (装完零弹窗,浏览器自己当安装器)`
+}
 /** 扩展在线判定:/health 心跳 ≤30s 一次 + 轮询重连,1.5 倍容差 */
 export const EXTENSION_CONNECTED_WINDOW_MS = 45_000
 /** /jobs 长轮询 hold 上限(必须 < MV3 SW 30s 存活窗口) */
@@ -292,7 +321,8 @@ export async function createSessionBridge(opts: SessionBridgeOptions = {}): Prom
             settle({
               ok: false,
               reason: 'extension-not-connected',
-              summary: `GoTry Session Bridge 扩展未连接(未安装或已停用)。一次性安装(装完零弹窗):推荐 Chrome 应用商店一键装(自动更新) ${EXTENSION_STORE_URL} ;或 npx gotry setup 落位后 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension`,
+              // D-24 自适应文案(issue #117):按本地通道是否落位决定是否提及开发者模式
+              summary: needsExtensionSummary(),
             })
           }
         }, 250)

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

@@ -10,15 +10,16 @@
  * 检索页无回包不是车道失败:与 CDP 车道同语义(到点无 hints 命中 ⇒ miss,页标题命挑战 ⇒ challenged)。
  */
 
-import { getOrCreateSessionBridge, EXTENSION_STORE_URL, type SessionJobHandle } from './extension-bridge.ts'
+import { getOrCreateSessionBridge, needsExtensionSummary, type SessionJobHandle } from './extension-bridge.ts'
 
-/** 一次性用户门文案(needs-extension 统一指引,与 bootstrap setupExtension 输出同口径) */
-export const NEEDS_EXTENSION_HINT =
-  '需要一次性安装 GoTry Session Bridge 浏览器扩展(装完零弹窗):'
-  + `推荐 Chrome 应用商店一键安装(自动更新) ${EXTENSION_STORE_URL} ;`
-  + '免审核、版本更新更快的 GitHub 通道:npx gotry setup --extension-from=github(自动下载落位 ~/.gotry/extension;'
-  + '手动下载 github.com/Danceiny/gotry/releases 标签 ext-* 的 gotry-session-bridge.tar.gz),'
-  + '再在 chrome://extensions 开发者模式「加载已解压的扩展程序」指向解压目录'
+/**
+ * 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'
 

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

@@ -104,7 +104,9 @@ export function parseDistManifest(raw: string): ExtensionDistManifest {
   const tarballSha256 = obj.tarballSha256
   const zip = obj.zip
   const zipSha256 = obj.zipSha256
-  if (typeof version !== 'string' || !/^\d+\.\d+\.\d+$/.test(version)) throw new Error('dist-manifest.version 缺失或非 x.y.z')
+  // 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')

package/ts/capabilities/session/health-watch.ts

@@ -1,6 +1,6 @@
 /**
  * 扩展健康检查 + 自动重放(issue #21 onboarding UX,P3.6 gotry-session-onboarding-goal,
- * RFC user-session-data-rfc.md §3.3)。
+ * RFC docs/rfc/user-session-data-rfc.md §3.3)。
  *
  * 动机:首次 `sessionFlightSearch` 遇 `needs-extension` 时,旧版要求用户装完扩展后**自己重跑命令**;
  * 本模块把「用户手工重跑」改成「后台有界轮询 + 扩展一就位自动重放同一 query_id」——

package/ts/capabilities/session/read-guard.ts

@@ -1,5 +1,5 @@
 /**
- * ReadGuard:会话检索面的只读物理隔离(RFC user-session-data-rfc.md §3.3)。
+ * ReadGuard:会话检索面的只读物理隔离(RFC docs/rfc/user-session-data-rfc.md §3.3)。
  *
  * 写不是「被禁止的行为」,是「不存在的原语」——WriteGate(L0-L4)的检索态前置:
  *   ① 网络层:route 拦截——命中硬支付模式(任意方法)或写方法+写URL模式 → abort + 审计落盘;

package/ts/capabilities/session/wizard.ts

@@ -1,5 +1,5 @@
 /**
- * 会话扩展 onboarding wizard(RFC user-session-data-rfc.md §3.3,ADR-21 上架后重设)。
+ * 会话扩展 onboarding wizard(RFC docs/rfc/user-session-data-rfc.md §3.3,ADR-21 上架后重设)。
  *
  * 单一职责(2026-09-02 重设):**只做 Node 端两件事**——
  *   ① 扩展文件从源落位到 `~/.gotry/extension`(幂等)

package/ts/capabilities/session-search.ts

@@ -6,7 +6,7 @@
  *  cdp(attach 日常 Chrome,Chrome 144+ 每连接弹权限框)降为显式后备
  * (`GOTRY_SESSION_TRANSPORT=cdp` opt-in,诊断/测试用);persistent 仅测试。
  *
- * 证据链(L4 增补):[会话:ctrip-flight@ts] = 用户本人会话内实时检索,非官方 API;
+ * 证据链(L4 增补):[会话:ctrip-flight@ts] / [会话:ctrip-hotel@ts] = 用户本人会话内实时检索,非官方 API;
  * 风控命中(verdict='challenged')= degraded,绝不重试、绝不绕过(合规支柱②)。
  * 节律(§3.4):同站点 ≥30s 间隔 + 单调冷却;超间隔返回 verdict='cooldown'。
  * 永不抛错;扩展车道 fail-closed(桥/扩展不可用即 verdict,零花费);测试/巡检用隔离 profile 与 stateRoot。
@@ -17,6 +17,8 @@ import { extensionCookieNames, extensionSearchJob, classifyBridgeFailure } from
 import { appendFileSync, mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
 import { buildEntryUrl, NETWORK_HINTS, parseBatchSearch, LOGIN_COOKIE_NAMES, SITE_DOMAIN, type SessionFlightOption } from './session/adapters/ctrip-flight.ts'
+import { buildHotelEntryUrl, parseCtripHotelList, HOTEL_SITE_HOST, type SessionHotelOption } from './session/adapters/ctrip-hotel.ts'
+import { buildTrainEntryUrl, parseLeftTicketQuery, TRAIN_SITE_HOST, type SessionTrainOption } from './session/adapters/rail-12306.ts'
 import { EXTENSION_STORE_URL } from './session/extension-bridge.ts'
 
 export type SessionVerdict = 'hit' | 'miss' | 'error' | 'challenged' | 'cooldown' | 'needs-login' | 'needs-attach' | 'needs-extension'
@@ -109,6 +111,326 @@ export function appendExtensionAudit(auditPath: string | undefined, entry: { kin
   } catch { /* 审计失败不阻塞检索 */ }
 }
 
+// ---------------------------------------------------------------------------
+// 酒店会话检索(2026-09-03 实装;与机票同构:节律闸/登录闸/needs-extension 映射/
+// 挑战红线/证据链。酒店页与机票页同属 ctrip.com 风控域,但通道键独立——
+// 各自 30s 预算已足够礼貌,跨通道合并预算留首个真会话风控观测后校准)
+// ---------------------------------------------------------------------------
+
+export interface SessionHotelQuery {
+  /** 目的地(中文);城市码表未收录时须带 cityId */
+  to: string
+  /** 显式城市 id(携程/trip.com 酒店 list 页 URL 的 city= 数字;覆盖码表) */
+  cityId?: number | string
+  /** YYYY-MM-DD */
+  checkIn?: string
+  /** YYYY-MM-DD(与 checkIn 成对) */
+  checkOut?: string
+  adults?: number
+  /** 隔离 profile 目录(测试必传;默认 /tmp 专用目录) */
+  profileDir?: string
+  headless?: boolean
+  /** ReadGuard 审计路径(测试传隔离 stateRoot 下) */
+  auditPath?: string
+  /** 等嗅探回包的上限,默认 30_000(酒店列表接口比机票慢) */
+  timeoutMs?: number
+  /** 允许匿名实例(默认 false);true 仅适配器链路自检,证据链标 anonymous */
+  allowAnonymous?: boolean
+}
+
+export interface SessionHotelResult {
+  ok: boolean
+  via: 'session-ctrip-hotel' | 'session-ctrip-hotel-error'
+  evidence: string
+  latencyMs: number
+  verdict: SessionVerdict
+  hotels?: SessionHotelOption[]
+  error?: string
+  /** needs-extension 时给出 Chrome Web Store URL(dsh UI 渲成可点链接) */
+  installUrl?: string
+  installAction?: 'add-to-chrome'
+}
+
+/** 酒店城市码表未收录时的人话指引(纯函数,测试锚点) */
+export function hotelCityUnresolvedHint(cities: string[]): string {
+  return `城市 ${cities.join('/')} 不在携程酒店城市码表——先 web 搜「hotels.ctrip.com ${cities[0] ?? ''} 酒店」拿到 list 页 URL 里的 city= 数字,带 cityId 重试`
+}
+
+export async function sessionHotelSearch(q: SessionHotelQuery): Promise<SessionHotelResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const site = 'ctrip-hotel'
+  const err = (verdict: SessionVerdict, error: string): SessionHotelResult => ({
+    ok: false, via: 'session-ctrip-hotel-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict, error,
+  })
+
+  // 日期对闸(与 flyai hotel 同口径):成对且 YYYY-MM-DD;过去日期不发上游
+  if ((q.checkIn ? 1 : 0) !== (q.checkOut ? 1 : 0) || (q.checkIn && !/^\d{4}-\d{2}-\d{2}$/.test(q.checkIn))) {
+    return err('error', 'checkIn/checkOut 须成对且为 YYYY-MM-DD(未定档期可不带日期)')
+  }
+  if (q.checkIn) {
+    const now = new Date()
+    const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+    if (q.checkIn < today || (q.checkOut ?? '') < q.checkIn) {
+      return err('error', `入住 ${q.checkIn}/退房 ${q.checkOut ?? ''} 不是未来合法区间(今天 ${today})——向用户确认日期后再查`)
+    }
+  }
+
+  // 节律闸:超间隔即拒,不发起导航
+  const last = lastCallAt.get(site) ?? 0
+  if (Date.now() - last < MIN_INTERVAL_MS) {
+    return err('cooldown', `rate limit: last call ${Date.now() - last}ms ago, min ${MIN_INTERVAL_MS}ms`)
+  }
+  lastCallAt.set(site, Date.now())
+
+  const entry = buildHotelEntryUrl({ to: q.to, cityId: q.cityId, checkIn: q.checkIn, checkOut: q.checkOut, adults: q.adults })
+  if (!entry.ok || !entry.url) {
+    return err('error', hotelCityUnresolvedHint(entry.unresolved ?? [q.to]))
+  }
+
+  const mode = resolveTransportMode(q.profileDir)
+
+  if (mode === 'extension') {
+    // ① 登录态快查(与机票同账号体系,票据 cookie 名一致)
+    const login = await extensionCookieNames({ site, domain: SITE_DOMAIN.replace(/^\./, ''), ticketNames: LOGIN_COOKIE_NAMES })
+    if (!login.ok) {
+      const verdict = classifyBridgeFailure(login.kind)
+      if (verdict === 'needs-extension') {
+        return { ok: false, via: 'session-ctrip-hotel-error', evidence: '[会话:ctrip-hotel-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: login.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' as const }
+      }
+      return err(verdict, login.summary)
+    }
+    if (login.tickets.length === 0 && !q.allowAnonymous) {
+      return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)')
+    }
+    // ② 检索 job:后台标签 + 被动嗅探(URL hint + 形状兜底;扩展零写行为)
+    const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs })
+    appendExtensionAudit(q.auditPath, {
+      kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+      result: r.ok ? (r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"`) : `${r.kind}:${r.summary.slice(0, 120)}`,
+    })
+    if (!r.ok) {
+      const verdict = classifyBridgeFailure(r.kind)
+      if (verdict === 'needs-extension') {
+        return { ok: false, via: 'session-ctrip-hotel-error', evidence: '[会话:ctrip-hotel-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' as const }
+      }
+      return err(verdict, r.summary)
+    }
+    const title = r.title
+    const head = r.body.slice(0, 5000)
+    if (CHALLENGE_RE.test(title + head)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    const hotels = parseCtripHotelList(r.body)
+    const verdict: SessionVerdict = hotels.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-ctrip-hotel',
+      evidence: `[会话:${site}@${ts}] ${hotels.length} hotels;transport=extension(被动嗅探,零系统弹窗;扩展零写行为=物理只读)${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+      latencyMs: Date.now() - started,
+      verdict,
+      hotels,
+    }
+  }
+
+  // cdp/persistent 车道:与机票同构——挂监听等 NETWORK hint 回包(酒店用 HOTEL hints + 形状兜底)
+  const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true })
+  if (!t.ok) {
+    return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary)
+  }
+  try {
+    const loggedIn = async (): Promise<boolean> => {
+      const cookies = await t.browser.cookies().catch(() => [])
+      return cookies.some((c) => c.domain.includes(SITE_DOMAIN.replace(/^\./, '')) && LOGIN_COOKIE_NAMES.includes(c.name))
+    }
+    if (!(await loggedIn()) && !q.allowAnonymous) {
+      return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)')
+    }
+    let settled = false
+    let body = ''
+    const heard = new Promise<void>((resolve) => {
+      t.page.on('response', async (res) => {
+        if (settled) return
+        const u = res.url()
+        const hostHit = u.includes(HOTEL_SITE_HOST)
+        if (!hostHit) return
+        try {
+          const text = await res.text()
+          if (text && (hostHit && /hotels\.ctrip\.com\/(hotels\/api|domestic\/pc\/api)|GetHotelListBySOA|GetHotelListByCity|HotelSearch|hotelsearch/i.test(u) || text.length <= 2_000_000 && /"hotelList"|"hotelMatchInfos"|"hotelName"/.test(text))) {
+            body = text
+            settled = true
+            resolve()
+          }
+        } catch { /* 流式/竞态不可读则继续等下一个 */ }
+      })
+      setTimeout(() => resolve(), q.timeoutMs ?? 30_000)
+    })
+    await t.page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 30_000 })
+    await heard
+    const title = await t.page.title().catch(() => '')
+    const headHtml = (await t.page.content().catch(() => '')).slice(0, 5000)
+    if (CHALLENGE_RE.test(title + headHtml)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    const hotels = parseCtripHotelList(body)
+    const verdict: SessionVerdict = hotels.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-ctrip-hotel',
+      evidence: `[会话:${site}@${ts}] ${hotels.length} hotels;guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+      latencyMs: Date.now() - started,
+      verdict,
+      hotels,
+    }
+  } catch (e) {
+    return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e))
+  } finally {
+    await t.close()
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// 火车会话检索(2026-09-03 实装;12306 余票查询是公开面——登录只关系下单,
+// 无账号数据过手,故无登录闸;扩展照样只读被动嗅探,证据链标注「公开查询面」)
+// ---------------------------------------------------------------------------
+
+export interface SessionTrainQuery {
+  from: string
+  to: string
+  /** YYYY-MM-DD */
+  date: string
+  /** 显式城市电报码(覆盖码表;kyfw 查询页 URL fs=城市,XXX 的三位码) */
+  fromStationTelecode?: string
+  toStationTelecode?: string
+  /** 隔离 profile 目录(测试必传;默认 /tmp 专用目录) */
+  profileDir?: string
+  headless?: boolean
+  /** ReadGuard 审计路径(测试传隔离 stateRoot 下) */
+  auditPath?: string
+  /** 等嗅探回包的上限,默认 25_000 */
+  timeoutMs?: number
+}
+
+export interface SessionTrainResult {
+  ok: boolean
+  via: 'session-train-12306' | 'session-train-12306-error'
+  evidence: string
+  latencyMs: number
+  verdict: SessionVerdict
+  trains?: SessionTrainOption[]
+  error?: string
+  /** needs-extension 时给出 Chrome Web Store URL(dsh UI 渲成可点链接) */
+  installUrl?: string
+  installAction?: 'add-to-chrome'
+}
+
+/** 车站电报码表未收录时的人话指引(纯函数,测试锚点) */
+export function trainStationUnresolvedHint(cities: string[]): string {
+  return `城市 ${cities.join('/')} 不在 12306 城市电报码表——web 搜「12306 ${cities[0] ?? ''} 余票」拿到 kyfw 查询页 URL 里的 fs=城市,XXX 三位码,带 fromStationTelecode/toStationTelecode 重试`
+}
+
+export async function sessionTrainSearch(q: SessionTrainQuery): Promise<SessionTrainResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const site = 'train-12306'
+  const err = (verdict: SessionVerdict, error: string): SessionTrainResult => ({
+    ok: false, via: 'session-train-12306-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict, error,
+  })
+
+  // 节律闸:超间隔即拒,不发起导航
+  const last = lastCallAt.get(site) ?? 0
+  if (Date.now() - last < MIN_INTERVAL_MS) {
+    return err('cooldown', `rate limit: last call ${Date.now() - last}ms ago, min ${MIN_INTERVAL_MS}ms`)
+  }
+  lastCallAt.set(site, Date.now())
+
+  const entry = buildTrainEntryUrl({ from: q.from, to: q.to, date: q.date, fromStationTelecode: q.fromStationTelecode, toStationTelecode: q.toStationTelecode })
+  if (!entry.ok || !entry.url) {
+    return err('error', trainStationUnresolvedHint(entry.unresolved ?? [q.from, q.to]))
+  }
+
+  const mode = resolveTransportMode(q.profileDir)
+
+  if (mode === 'extension') {
+    // 无登录闸(公开查询面):直接发起检索 job
+    const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs })
+    appendExtensionAudit(q.auditPath, {
+      kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+      result: r.ok ? (r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"`) : `${r.kind}:${r.summary.slice(0, 120)}`,
+    })
+    if (!r.ok) {
+      const verdict = classifyBridgeFailure(r.kind)
+      if (verdict === 'needs-extension') {
+        return { ok: false, via: 'session-train-12306-error', evidence: '[会话:train-12306-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' as const }
+      }
+      return err(verdict, r.summary)
+    }
+    const title = r.title
+    const head = r.body.slice(0, 5000)
+    if (CHALLENGE_RE.test(title + head)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    const trains = parseLeftTicketQuery(r.body, entry.url)
+    const verdict: SessionVerdict = trains.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-train-12306',
+      evidence: `[会话:${site}@${ts}] ${trains.length} trains;transport=extension(公开查询面,被动嗅探,零系统弹窗;扩展零写行为=物理只读)`,
+      latencyMs: Date.now() - started,
+      verdict,
+      trains,
+    }
+  }
+
+  // cdp/persistent 车道:与机/酒同构
+  const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true })
+  if (!t.ok) {
+    return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary)
+  }
+  try {
+    let settled = false
+    let body = ''
+    const heard = new Promise<void>((resolve) => {
+      t.page.on('response', async (res) => {
+        if (settled) return
+        const u = res.url()
+        if (!/leftTicket\/query/i.test(u)) return
+        try {
+          const text = await res.text()
+          if (text) {
+            body = text
+            settled = true
+            resolve()
+          }
+        } catch { /* 流式/竞态不可读则继续等下一个 */ }
+      })
+      setTimeout(() => resolve(), q.timeoutMs ?? 25_000)
+    })
+    await t.page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 30_000 })
+    await heard
+    const title = await t.page.title().catch(() => '')
+    const headHtml = (await t.page.content().catch(() => '')).slice(0, 5000)
+    if (CHALLENGE_RE.test(title + headHtml)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    const trains = parseLeftTicketQuery(body, entry.url)
+    const verdict: SessionVerdict = trains.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-train-12306',
+      evidence: `[会话:${site}@${ts}] ${trains.length} trains(公开查询面);guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}`,
+      latencyMs: Date.now() - started,
+      verdict,
+      trains,
+    }
+  } catch (e) {
+    return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e))
+  } finally {
+    await t.close()
+  }
+}
+
 export async function sessionFlightSearch(q: SessionFlightQuery): Promise<SessionSearchResult> {
   const started = Date.now()
   const ts = new Date().toISOString()

package/ts/package.json

@@ -15,6 +15,7 @@
     "@deepseek-ai/schemastery": "^3.18.2",
     "@types/better-sqlite3": "^9.6.0",
     "better-sqlite3": "^13.0.3",
+    "dsh-map-tools": "0.5.1",
     "z3-solver": "^5.2.0"
   },
   "devDependencies": {

package/ts/scripts/turn-handoff-collect.ts

@@ -0,0 +1,178 @@
+/**
+ * 后台深度规划工单收集器(ADR-24 v2 收集闭环;async-collect 的 turn-handoff 对位)。
+ *
+ * 「一小时后回来看看」的后台半段:加载 open 工单 → 以 GOTRY_HANDOFF_CHILD=1
+ * 派生 headless 规划会话(唯一出口 converge,不回递归)→ 捕获最终答复为
+ * 交付物 → settleTurnHandoffTicket 结算(交付物 .deliverable.md + 工单状态
+ * 原子更新)。终态幂等:已 settled/failed 的工单复诵交付物与终态 JSON,零
+ * 重算、零再花。最后一行固定输出 gotry_turn_handoff_terminal.v1 JSON;
+ * succeeded exit 0,failed exit 2。
+ *
+ * 运行(在 ts/ 下):
+ *   npx tsx scripts/turn-handoff-collect.ts <ticketId> [stateRoot]
+ *   npx tsx scripts/turn-handoff-collect.ts --all [stateRoot]
+ * 环境变量:
+ *   GOTRY_HANDOFF_PLANNER_BIN      规划器二进制(默认 <repo>/bin/gotry-inner.js)
+ *   GOTRY_HANDOFF_PLANNER_TIMEOUT_MS 规划器硬上限(默认 900_000)
+ *
+ * v1 诚实边界:工单只携带用户原文,规划会话是全新上下文(fresh cwd/DSH_HOME)
+ * ——原会话中已读的工作区文件/日历结论不随单迁移,由规划器按需重取。
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  listTurnHandoffTickets,
+  settleTurnHandoffTicket,
+  TURN_HANDOFF_SCHEMA,
+  type TurnHandoffTicket,
+} from '../src/turn-deadline.ts'
+
+const TURN_HANDOFF_TERMINAL_SCHEMA = 'gotry_turn_handoff_terminal.v1' as const
+const ROOT = join(import.meta.dirname, '..', '..')
+
+interface TerminalOutcome {
+  schema: typeof TURN_HANDOFF_TERMINAL_SCHEMA
+  ticket_id: string
+  status: 'succeeded' | 'failed'
+  deliverable_path?: string
+  error?: string
+}
+
+function emitTerminal(outcome: TerminalOutcome): never {
+  console.log(JSON.stringify(outcome))
+  process.exit(outcome.status === 'succeeded' ? 0 : 2)
+}
+
+function loadTicket(stateRoot: string, ticketId: string): TurnHandoffTicket | null {
+  try {
+    const path = join(stateRoot === '.' ? process.cwd() : stateRoot, 'gotry-state', 'turn-handoffs', `${ticketId}.json`)
+    const ticket = JSON.parse(readFileSync(path, 'utf-8')) as TurnHandoffTicket
+    return ticket?.schema === TURN_HANDOFF_SCHEMA ? ticket : null
+  } catch {
+    return null
+  }
+}
+
+function replay(ticket: TurnHandoffTicket, stateRoot: string): never {
+  const dir = join(stateRoot === '.' ? process.cwd() : stateRoot, 'gotry-state', 'turn-handoffs')
+  emitTerminal({
+    schema: TURN_HANDOFF_TERMINAL_SCHEMA,
+    ticket_id: ticket.id,
+    status: ticket.status === 'settled' ? 'succeeded' : 'failed',
+    ...(ticket.deliverableFile ? { deliverable_path: join(dir, ticket.deliverableFile) } : {}),
+    ...(ticket.error ? { error: ticket.error } : {}),
+  })
+}
+
+async function runPlanner(ticket: TurnHandoffTicket): Promise<{ ok: boolean; output: string; error?: string }> {
+  const plannerBin = process.env.GOTRY_HANDOFF_PLANNER_BIN ?? join(ROOT, 'bin', 'gotry-inner.js')
+  if (!existsSync(plannerBin)) {
+    return { ok: false, output: '', error: `planner binary unavailable: ${plannerBin}` }
+  }
+  const timeoutMs = Number.parseInt(process.env.GOTRY_HANDOFF_PLANNER_TIMEOUT_MS ?? '', 10) || 900_000
+  const dshHome = mkdtempSync(join(tmpdir(), 'gotry-handoff-child-dsh-'))
+  const childCwd = mkdtempSync(join(tmpdir(), 'gotry-handoff-child-cwd-'))
+  try {
+    const childEnv: NodeJS.ProcessEnv = { ...process.env }
+    childEnv.DSH_HOME = dshHome
+    // 递归防护(核心):子会话唯一出口 converge + 长 leash;同时清掉父进程的
+    // 数值 pin 与工单根,子会话不得再 handoff、也不受测试阈值影响。
+    childEnv.GOTRY_HANDOFF_CHILD = '1'
+    delete childEnv.GOTRY_TURN_DEADLINE_SOFT_MS
+    delete childEnv.GOTRY_TURN_DEADLINE_HARD_MS
+    delete childEnv.GOTRY_TURN_HANDOFF_ROOT
+    // .js/.mjs/.cjs 经当前 node 派生(测试假 planner 无执行位也成立);
+    // 其余(gotry-inner.js 之外的 .bin shim、全局命令)直接执行。
+    const isJsScript = /\.(js|mjs|cjs)$/.test(plannerBin)
+    const child = isJsScript
+      ? spawn(process.execPath, [plannerBin, ticket.userMessage], { cwd: childCwd, env: childEnv, stdio: ['ignore', 'pipe', 'pipe'] })
+      : spawn(plannerBin, [ticket.userMessage], { cwd: childCwd, env: childEnv, stdio: ['ignore', 'pipe', 'pipe'] })
+    let output = ''
+    child.stdout.on('data', chunk => { output += chunk.toString() })
+    child.stderr.on('data', chunk => { output += chunk.toString() })
+    const code = await new Promise<number | null>(resolve => {
+      const timer = setTimeout(() => { child.kill('SIGKILL'); resolve(null) }, timeoutMs)
+      child.once('exit', c => { clearTimeout(timer); resolve(c) })
+    })
+    if (code === null) return { ok: false, output: '', error: `planner timed out after ${timeoutMs}ms` }
+    if (code !== 0) return { ok: false, output: '', error: `planner exited ${code}: ${output.trim().slice(-300)}` }
+    const deliverable = output.trim()
+    if (!deliverable) return { ok: false, output: '', error: 'planner produced empty output' }
+    return { ok: true, output: deliverable }
+  } finally {
+    await new Promise<void>(resolve => setTimeout(resolve, 200))
+    rmSync(dshHome, { recursive: true, force: true })
+    rmSync(childCwd, { recursive: true, force: true })
+  }
+}
+
+async function collectOne(stateRoot: string, ticketId: string): Promise<void> {
+  const ticket = loadTicket(stateRoot, ticketId)
+  if (!ticket) {
+    console.error(`工单 ${ticketId} 不存在(${stateRoot}/gotry-state/turn-handoffs/)`)
+    process.exit(1)
+  }
+  if (ticket.status !== 'open') {
+    console.error(`工单 ${ticketId} 已是终态 ${ticket.status},复诵不重算:`)
+    replay(ticket, stateRoot)
+  }
+  const result = await runPlanner(ticket)
+  const deliverable = result.ok
+    ? `# 后台深度规划交付:${ticket.objective.slice(0, 60)}\n(工单 ${ticket.id},原请求 ${ticket.requestedAt})\n\n${result.output}`
+    : `# 后台深度规划失败:${ticket.objective.slice(0, 60)}\n(工单 ${ticket.id},原请求 ${ticket.requestedAt})\n\n未产出交付物:${result.error ?? '未知原因'}。这趟规划没有完成——请重新发起,失败原因如上,无部分结果可交付。`
+  const { deliverablePath } = await settleTurnHandoffTicket(
+    stateRoot, ticket, result.ok ? 'settled' : 'failed', deliverable, result.ok ? undefined : result.error,
+  )
+  console.error(`工单 ${ticket.id} ${result.ok ? '已交付' : '失败'}:${deliverablePath}`)
+  emitTerminal({
+    schema: TURN_HANDOFF_TERMINAL_SCHEMA,
+    ticket_id: ticket.id,
+    status: result.ok ? 'succeeded' : 'failed',
+    ...(result.ok
+      ? { deliverable_path: deliverablePath }
+      : { error: result.error ?? 'unknown' }),
+  })
+}
+
+async function collectAll(stateRoot: string): Promise<void> {
+  const open = (await listTurnHandoffTickets(stateRoot)).filter(t => t.status === 'open')
+  if (open.length === 0) {
+    console.error('无待回收的后台规划工单(open=0)')
+    process.exit(0)
+  }
+  let failed = 0
+  for (const view of open) {
+    const ticket = loadTicket(stateRoot, view.id)
+    if (!ticket || ticket.status !== 'open') continue
+    const result = await runPlanner(ticket)
+    const deliverable = result.ok
+      ? `# 后台深度规划交付:${ticket.objective.slice(0, 60)}\n(工单 ${ticket.id},原请求 ${ticket.requestedAt})\n\n${result.output}`
+      : `# 后台深度规划失败:${ticket.objective.slice(0, 60)}\n(工单 ${ticket.id},原请求 ${ticket.requestedAt})\n\n未产出交付物:${result.error ?? '未知原因'}。这趟规划没有完成——请重新发起,失败原因如上,无部分结果可交付。`
+    const { deliverablePath } = await settleTurnHandoffTicket(
+      stateRoot, ticket, result.ok ? 'settled' : 'failed', deliverable, result.ok ? undefined : result.error,
+    )
+    console.error(`工单 ${ticket.id} ${result.ok ? '已交付' : '失败'}:${deliverablePath}`)
+    if (!result.ok) failed += 1
+  }
+  console.log(JSON.stringify({
+    schema: TURN_HANDOFF_TERMINAL_SCHEMA,
+    ticket_id: `--all(${open.length})`,
+    status: failed === 0 ? 'succeeded' : 'failed',
+    error: failed === 0 ? undefined : `${failed}/${open.length} 张工单回收失败`,
+  }))
+  process.exit(failed === 0 ? 0 : 2)
+}
+
+const [target, stateRootArg] = process.argv.slice(2)
+const stateRoot = stateRootArg ?? '.'
+if (target === '--all') {
+  await collectAll(stateRoot)
+} else if (target) {
+  await collectOne(stateRoot, target)
+} else {
+  console.error('用法:npx tsx scripts/turn-handoff-collect.ts <ticketId|--all> [stateRoot]')
+  process.exit(1)
+}