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

package/ts/capabilities/session-consent.ts

@@ -16,9 +16,15 @@
  *   - 授权状态存 Weak<agent>——会话结束即遗忘,绝不跨会话持久化(明示授权不默认延续)。
  * 审计:批准/拒绝事件由 dsh ApprovalService 落 session log(approval/asked + decided),
  * 本模块不重复建账。站点白名单 = ACCOUNT_TOOLS 注册表(新会话适配器接入时登记)。
+ *
+ * site 绑定(2026-09-10 #308):同一工具多个 kind(例如 gotry_session_search → flight/hotel/dida/train)
+ * 必须按与 execute 同源的 interpretArgs 选 site(包装 query 优先);授权与拒绝均按 site
+ * 分桶。缺省 kind 保持工具合同的 flight 默认值;unknown/malformed kind 失败关闭(deny,
+ * 不扩权),防止新站点未登记就放行。train 虽是 12306 公开查询面,仍经过本闸的 off/ask/allow。
  */
 
 import type { Context } from '@deepseek-ai/cordis'
+import { interpretArgs } from '../src/tool-packet.ts'
 
 export type SessionAccess = 'ask' | 'allow' | 'off'
 export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
@@ -33,13 +39,33 @@ export interface ApprovalSeam {
   request(r: { agent?: unknown; toolName: string; callId?: string; reason?: string; signal?: AbortSignal }): Promise<ApprovalOutcome>
 }
 
-/** 账号面工具 → 站点(白名单登记处;新会话适配器接入时在此登记) */
+/**
+ * 工具级 site 表(无 kind 维度时使用):key=工具名,value=站点。
+ * 复合工具(同一名字下多 kind)在 SITE_FOR_KIND 中显式登记。
+ */
 export const ACCOUNT_TOOLS: Record<string, string> = {
   gotry_session_search: 'ctrip-flight',
 }
 
 const SITE_LABEL: Record<string, string> = {
   'ctrip-flight': '携程机票',
+  'ctrip-hotel': '携程酒店',
+  'dida-portal': 'Dida 供应商门户',
+  'train-12306': '12306 余票(公开查询面)',
+}
+
+/**
+ * 复合工具 × kind → site(#308:site 绑定)。
+ * 仅对显式登记的 kind 放行,未知 kind → 失败关闭(防止未登记站点扩权)。
+ * 12306 公开查询面(kind=train)仍受本工具的会话授权总闸约束,不因公开查询而绕过 off/ask/allow。
+ */
+export const SITE_FOR_KIND: Record<string, Record<string, string>> = {
+  gotry_session_search: {
+    flight: 'ctrip-flight',
+    hotel: 'ctrip-hotel',
+    dida: 'dida-portal',
+    train: 'train-12306',
+  },
 }
 
 interface AuthState {
@@ -56,12 +82,67 @@ export interface ConsentGateOptions {
   store?: WeakMap<object, AuthState>
 }
 
-export type ConsentExec = { name?: string; agent?: object; callId?: string }
+export type ConsentExec = { name?: string; agent?: object; callId?: string; arguments?: unknown }
 export type ConsentGate = (exec: ConsentExec, next: () => Promise<ConsentDecision>) => Promise<ConsentDecision>
 
+/** 会话检索工具支持的 kind;gate 与 execute 共用此选择结果。 */
+export const SESSION_SEARCH_KINDS = ['flight', 'hotel', 'train', 'dida'] as const
+export type SessionSearchKind = typeof SESSION_SEARCH_KINDS[number]
+
+export type SessionSearchKindSelection =
+  | { ok: true; kind: SessionSearchKind }
+  | { ok: false; reason: string }
+
+/**
+ * Select the kind exactly as the session tool execute path does.
+ * `interpretArgs` is intentionally the only query-wrapper normalizer: a
+ * wrapped query wins over conflicting flat fields, and omitted kind keeps the
+ * documented flight default. Explicit malformed/unknown kinds fail closed.
+ */
+export function resolveSessionSearchKind(args: unknown): SessionSearchKindSelection {
+  if (args === undefined) return { ok: true, kind: 'flight' }
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, reason: 'gotry_session_search 参数必须是对象;无法安全选择 kind,已失败关闭' }
+  }
+  const selected = interpretArgs<{ kind?: unknown }>(args as { query?: unknown } & Record<string, unknown>)
+  if (!selected || typeof selected !== 'object' || Array.isArray(selected)) {
+    return { ok: false, reason: 'gotry_session_search 参数包装形态无效;无法安全选择 kind,已失败关闭' }
+  }
+  if (!Object.prototype.hasOwnProperty.call(selected, 'kind')) return { ok: true, kind: 'flight' }
+  const kind = (selected as { kind?: unknown }).kind
+  if (typeof kind !== 'string' || kind.length === 0) {
+    return { ok: false, reason: 'gotry_session_search 收到 malformed kind;无法安全选择站点,已失败关闭' }
+  }
+  if (!(SESSION_SEARCH_KINDS as readonly string[]).includes(kind)) {
+    return { ok: false, reason: `gotry_session_search 收到未知 kind=${kind};只支持 ${SESSION_SEARCH_KINDS.join('/')},未知 kind 失败关闭` }
+  }
+  return { ok: true, kind: kind as SessionSearchKind }
+}
+
+/**
+ * 解析 site(#308):对复合工具(缺省 kind=flight,未知/malformed kind → fail-closed);对未在
+ * SITE_FOR_KIND 登记的工具走原 ACCOUNT_TOOLS 表保持兼容。无 site → 放行(非账号面工具)。
+ */
+export function resolveSiteForExec(exec: ConsentExec): { site: string } | { failClosed: true; reason: string } | null {
+  const name = exec.name
+  if (!name) return null
+  const map = SITE_FOR_KIND[name]
+  if (map) {
+    const selected = resolveSessionSearchKind(exec.arguments)
+    if (!selected.ok) return { failClosed: true, reason: selected.reason }
+    const site = map[selected.kind]
+    if (!site) return { failClosed: true, reason: `工具 ${name} 的 kind=${selected.kind} 未登记站点;失败关闭` }
+    return { site }
+  }
+  const site = ACCOUNT_TOOLS[name]
+  if (!site) return null
+  return { site }
+}
+
 function reasonFor(toolName: string, site: string): string {
-  return `${toolName} 将使用你本人已登录的浏览器会话做「${SITE_LABEL[site] ?? site}」只读检索`
-    + '(ReadGuard 物理只读:写请求网络层中止,agent 永不碰凭证与验证码);本次批准在你本会话内有效'
+  return `工具 ${toolName} 将使用你本人已登录的浏览器会话，在「${SITE_LABEL[site] ?? site}」进行只读检索`
+    + '（ReadGuard 物理只读：写请求在网络层即中止，agent 永不接触凭证与验证码）；'
+    + '本次批准仅在本会话内有效，会话结束即失效，不会跨会话延续。'
 }
 
 /**
@@ -69,24 +150,27 @@ function reasonFor(toolName: string, site: string): string {
  * 契约:
  *   - 非账号面工具 → next() 放行(零开销);
  *   - off → 拒绝(随时可关);
- *   - 会话内已拒绝 → 拒绝且不弹卡(拒绝=本会话吊销);
+ *   - 会话内已拒绝 → 拒绝且不弹卡(拒绝=本会话吊销;按 site 分桶,跨站不互授);
  *   - 会话内已批准 / allow 预授权 → 放行;
- *   - 其余 → ApprovalService.request();allowed-once 记入会话 granted;
- *     rejected/cancelled 记入会话 denied(本会话不在请求);
+ *   - 复合工具未知/malformed kind → fail-closed deny(不扩权),缺省 kind=flight;
+ *   - 其余 → ApprovalService.request();allowed-once 按 site 入会话 granted;
+ *     rejected/cancelled 按 site 入会话 denied(本会话不在请求);
  *     无审批通道 → deny(fail-closed,headless 无用户 = 无授权)。
  */
 export function createConsentGate(opts: ConsentGateOptions): ConsentGate {
   const store = opts.store ?? new WeakMap<object, AuthState>()
   const approvalOf = opts.approval ?? (() => undefined)
   return async (exec, next) => {
-    const site = exec.name && ACCOUNT_TOOLS[exec.name]
-    if (!site) return next()
+    const resolved = resolveSiteForExec(exec)
+    if (!resolved) return next()
+    if ('failClosed' in resolved) return { kind: 'deny', reason: resolved.reason }
+    const { site } = resolved
     if ((opts.access() ?? 'ask') === 'off') {
-      return { kind: 'deny', reason: `${exec.name} 已被配置关闭(sessionAccess=off);需要账号会话检索时由用户开启` }
+      return { kind: 'deny', reason: `工具 ${exec.name} 已被配置关闭（sessionAccess=off）。如需重新启用账号会话检索，请到配置中重新开启 sessionAccess。` }
     }
     const state = (exec.agent && store.get(exec.agent)) || undefined
     if (state?.denied.has(site)) {
-      return { kind: 'deny', reason: `你在本会话已拒绝过「${SITE_LABEL[site] ?? site}」的账号会话检索——本会话不再请求授权,请改走其他工具推进` }
+      return { kind: 'deny', reason: `你已在本会话拒绝过「${SITE_LABEL[site] ?? site}」的账号会话检索。为避免反复打扰，本会话不再请求授权，请改用其他工具继续推进。` }
     }
     if (state?.granted.has(site) || (opts.access() === 'allow' && exec.agent)) return next()
     const approval = opts.approval?.()
@@ -103,9 +187,9 @@ export function createConsentGate(opts: ConsentGateOptions): ConsentGate {
     }
     if (outcome === 'rejected' || outcome === 'cancelled') {
       remember(store, exec.agent, site, 'deny')
-      return { kind: 'deny', reason: `你拒绝了 ${exec.name} 的账号会话授权(本会话内生效);不再重复请求,请改走其他工具推进` }
+      return { kind: 'deny', reason: `你刚刚拒绝了工具 ${exec.name} 的账号会话授权（本次拒绝仅在本会话内生效）。为避免反复打扰，本会话不再重复请求授权，请改用其他工具继续推进。` }
     }
-    return { kind: 'deny', reason: `${exec.name} 需要你授权,但当前没有可用的审批通道(headless 一问一答无审批界面;请在 web 会话中使用账号会话检索)` }
+    return { kind: 'deny', reason: `工具 ${exec.name} 需要你授权，但当前没有可用的审批通道。在 headless 一问一答场景下没有审批界面，请改用 web 会话来使用账号会话检索。` }
   }
 }
 
@@ -124,4 +208,4 @@ export function approvalFromContext(ctx: Context): () => ApprovalSeam | undefine
     const approval = get.call(ctx, 'approval') as ApprovalSeam | undefined
     return approval && typeof approval.request === 'function' ? approval : undefined
   }
-}
+}

package/ts/capabilities/session-login.ts

@@ -30,6 +30,7 @@ export interface LoginTarget {
 export const LOGIN_TARGETS: Record<string, LoginTarget> = {
   'ctrip-flight': { domain: 'ctrip.com', names: ['cticket', 'uid', 'uname', 'passport'], label: '携程机票', entryUrl: 'https://flights.ctrip.com/' },
   'meituan-hotel': { domain: 'meituan.com', names: ['lt', 'u', 'token', 'n'], label: '美团酒店', entryUrl: 'https://hotel.meituan.com/' },
+  'dida-portal': { domain: 'dida.com', names: ['CN_M_DidaTravel'], label: 'Dida 供应商门户', entryUrl: 'https://portal.dida.com/login' },
 }
 
 interface CookieLike {

package/ts/capabilities/session-search.ts

@@ -12,14 +12,16 @@
  * 永不抛错;扩展车道 fail-closed(桥/扩展不可用即 verdict,零花费);测试/巡检用隔离 profile 与 stateRoot。
  */
 
-import { openSession } from './session/transport.ts'
+import { openSession, type SessionTransport, type TransportFailure } from './session/transport.ts'
 import { extensionCookieNames, extensionSearchJob, classifyBridgeFailure } from './session/extension-channel.ts'
 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 { randomUUID } from 'node:crypto'
+import { buildEntryUrl, NETWORK_HINTS, parseBatchSearchResult, 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'
+import { buildTrainEntryUrl, parseLeftTicketQueryResult, resolveTrainQueryTelecodes, validateTrainQueryResponseUrl, TRAIN_SITE_HOST, type SessionTrainOption, type TrainQueryParseOutcome, type TrainResponseBinding } from './session/adapters/rail-12306.ts'
+import { buildDidaEntryUrl, parseDidaRates, parseDidaRecommendHotels, parseDidaPrices, DIDA_NETWORK_HINTS, DIDA_SITE_HOST, DIDA_SITE_DOMAIN, DIDA_LOGIN_COOKIE_NAMES, type SessionDidaRateOption } from './session/adapters/dida-portal.ts'
+import { EXTENSION_STORE_URL, type SessionJobHandle, type SniffBodies } from './session/extension-bridge.ts'
 
 export type SessionVerdict = 'hit' | 'miss' | 'error' | 'challenged' | 'cooldown' | 'needs-login' | 'needs-attach' | 'needs-extension'
 
@@ -59,6 +61,12 @@ export function __resetRateLimiterForTest(): void {
   lastCallAt.clear()
 }
 
+let trainSessionTransportForTest: (() => Promise<SessionTransport | TransportFailure>) | undefined
+/** Isolated CDP collector seam; production uses openSession and never installs this. */
+export function __setTrainSessionTransportForTest(factory: (() => Promise<SessionTransport | TransportFailure>) | null): void {
+  trainSessionTransportForTest = factory ?? undefined
+}
+
 const CHALLENGE_RE = /验证|滑块|captcha|verify/i
 
 /** 把 transport 文案漂移收敛为稳定的产品 verdict；纯函数供回归覆盖。 */
@@ -290,6 +298,203 @@ export async function sessionHotelSearch(q: SessionHotelQuery): Promise<SessionH
 }
 
 
+// ---------------------------------------------------------------------------
+// Dida 供应商门户会话检索(2026-09-09 实装;hotel-be portal integration 迁移线:
+// 员工登录经 hotel-be portal 自动填充跳板在 dida 官网由人完成,gotry 只在用户
+// 本人 Chrome 登录态里被动嗅探 portal 自己的实时价回包。与机/酒/火同构:
+// 节律闸/登录闸(票据 cookie 名)/needs-extension 映射/挑战红线/证据链。
+// SPA 边界:find 页加载即自发的 SearchMonitor/SearchRealTime 才可嗅;页内点击
+// 触发的检索属用户本人的浏览行为,被动面只收页自发请求——零 DOM 交互不变量。
+// ---------------------------------------------------------------------------
+
+export interface SessionDidaQuery {
+  /** 显式覆盖入口 URL(深链参数校准后使用;须落在 portal.dida.com 域内) */
+  entryUrl?: string
+  /** 隔离 profile 目录(测试必传;默认 /tmp 专用目录) */
+  profileDir?: string
+  headless?: boolean
+  /** ReadGuard 审计路径(测试传隔离 stateRoot 下) */
+  auditPath?: string
+  /** 等嗅探回包的上限,默认 30_000(dida SPA 加载较慢) */
+  timeoutMs?: number
+  /** 允许匿名实例(默认 false——员工本人 dida 会话是本面的存在前提) */
+  allowAnonymous?: boolean
+  /**
+   * 扩展桥注入(2026-09-11,gotry-backend 服务形态):传进程内作业队列,
+   * 远程扩展经鉴权面连入;缺省走 loopback 懒单例(桌面形态)
+   */
+  bridge?: SessionJobHandle
+}
+
+export interface SessionDidaResult {
+  ok: boolean
+  via: 'session-dida-portal' | 'session-dida-portal-error'
+  evidence: string
+  latencyMs: number
+  verdict: SessionVerdict
+  rates?: SessionDidaRateOption[]
+  error?: string
+  /** needs-extension 时给出 Chrome Web Store URL(dsh UI 渲成可点链接) */
+  installUrl?: string
+  installAction?: 'add-to-chrome'
+}
+
+/** 员工侧登录指引(纯函数,测试锚点):账密永不经 gotry——酒店 platform
+ * 凭据在 hotel-be portal「自动登录」跳板完成,dida 侧人只补验证码 */
+export function didaLoginHint(): string {
+  return '未检出你的 dida 登录态——在 hotel-be portal「供应商门户」页对该凭据点「自动登录」完成跳板登录(账密自动填充,你只补验证码);或调用 gotry_session_login(site=dida-portal)打开 dida 登录入口。登录在 dida 官网完成;gotry 永不经手密码/验证码/cookie 值'
+}
+
+/** dida 三类回包合并解析(推荐酒店 + 推荐价格 + 实时价;CDP 窗口收集与扩展 multiCollect 双车道同一合并语义) */
+function mergeDidaRatesBodies(bodies: { hotels: string; recommendPrices: string; realtime: string }): SessionDidaRateOption[] {
+  const hotels = parseDidaRecommendHotels(bodies.hotels)
+  const recommendPrices = parseDidaPrices(bodies.recommendPrices)
+  const realtimeRates = parseDidaRates(bodies.realtime)
+  const pricesByHotel = new Map(recommendPrices.map((p) => [p.hotelId, p]))
+  const rates: SessionDidaRateOption[] = [...realtimeRates]
+  for (const h of hotels) {
+    const p = pricesByHotel.get(h.hotelId)
+    rates.push({
+      hotelId: h.hotelId,
+      hotelName: h.name,
+      price: p?.price ?? 0,
+      ...(p?.currency ? { currency: p.currency } : {}),
+      ...(p?.priceDate ? { priceDate: p.priceDate } : {}),
+    })
+  }
+  return rates
+}
+
+export async function sessionDidaSearch(q: SessionDidaQuery): Promise<SessionDidaResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const site = 'dida-portal'
+  const err = (verdict: SessionVerdict, error: string): SessionDidaResult => ({
+    ok: false, via: 'session-dida-portal-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 = buildDidaEntryUrl({ entryUrl: q.entryUrl })
+  if (!entry.ok || !entry.url) {
+    return err('error', 'entry URL 必须落在 https://portal.dida.com/ 域内')
+  }
+
+  const mode = resolveTransportMode(q.profileDir)
+
+  if (mode === 'extension') {
+    // ① 登录态快查:票据 cookie 名存在性(名字级;协议面不存在值字段)。
+    // 20s 窗口:桥常在本调用前才拉起,扩展 SW 可能已按 MV3 30s 节律休眠——
+    // job 在桥上按 capability 排队等轮询者,窗口覆盖一次 alarm 唤醒周期。
+    const login = await extensionCookieNames({ site, domain: DIDA_SITE_DOMAIN, ticketNames: DIDA_LOGIN_COOKIE_NAMES, timeoutMs: 20_000 }, q.bridge)
+    if (!login.ok) {
+      const verdict = classifyBridgeFailure(login.kind)
+      if (verdict === 'needs-extension') {
+        return { ok: false, via: 'session-dida-portal-error', evidence: '[会话:dida-portal-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', didaLoginHint())
+    }
+    // ② 检索 job:后台标签 + 被动嗅探(URL hint + 形状兜底;扩展零写行为)。
+    // multiCollect:find 页自发 hotels+recommendPrices 双流,单首包语义丢一半(2026-09-11)
+    const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs, multiCollect: true }, q.bridge)
+    appendExtensionAudit(q.auditPath, {
+      kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+      result: r.ok ? (r.timedOut ? 'timeout' : r.bodies ? `bodies hotels=${r.bodies.hotels?.length ?? 0}B prices=${r.bodies.recommendPrices?.length ?? 0}B` : `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-dida-portal-error', evidence: '[会话:dida-portal-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.bodies?.hotels ?? r.body).slice(0, 5000)
+    if (CHALLENGE_RE.test(title + head)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    // multiCollect 分桶回包 → 与 CDP 车道同语义合并;旧扩展单首包 → 退化 parseDidaRates 兜底
+    const rates = r.bodies
+      ? mergeDidaRatesBodies({ hotels: r.bodies.hotels ?? '', recommendPrices: r.bodies.recommendPrices ?? '', realtime: r.bodies.realtime ?? '' })
+      : parseDidaRates(r.body)
+    const verdict: SessionVerdict = rates.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-dida-portal',
+      evidence: `[会话:${site}@${ts}] ${rates.length} rates;transport=extension(被动嗅探,零系统弹窗;扩展零写行为=物理只读)${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+      latencyMs: Date.now() - started,
+      verdict,
+      rates,
+    }
+  }
+
+  // cdp/persistent 车道:与机/酒同构——挂监听等 DIDA 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(DIDA_SITE_DOMAIN) && DIDA_LOGIN_COOKIE_NAMES.includes(c.name))
+    }
+    if (!(await loggedIn()) && !q.allowAnonymous) {
+      return err('needs-login', didaLoginHint())
+    }
+    // 窗口式收集(2026-09-10 校准):find 页加载自发推荐流(酒店+价格两个接口)
+    // 与可能的实时价接口——按接口分类收 body,窗口结束统一合并解析。
+    const bodies = { hotels: '', recommendPrices: '', realtime: '' }
+    const collect = (text: string, url: string): void => {
+      if (/SearchHomepageRecommendHotels/i.test(url)) bodies.hotels = text
+      else if (/SearchHomepageRecommendPrices/i.test(url)) bodies.recommendPrices = text
+      else if (/HotelPriceAPI\/SearchRealTime/i.test(url)) bodies.realtime = text
+    }
+    const heard = new Promise<void>((resolve) => {
+      t.page.on('response', async (res) => {
+        const u = res.url()
+        if (!DIDA_NETWORK_HINTS.some((re) => re.test(u))) return
+        try {
+          const text = await res.text()
+          if (text) collect(text, u)
+        } 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 rates: SessionDidaRateOption[] = mergeDidaRatesBodies(bodies)
+    // 有推荐酒店或有实时价即视为通道产出;纯无价酒店如实标注价格待询
+    const priced = rates.filter((r) => r.price > 0).length
+    const verdict: SessionVerdict = rates.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-dida-portal',
+      evidence: `[会话:${site}@${ts}] ${rates.length} hotels(${priced} priced);guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+      latencyMs: Date.now() - started,
+      verdict,
+      rates,
+    }
+  } catch (e) {
+    return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e))
+  } finally {
+    await t.close()
+  }
+}
+
+
 // ---------------------------------------------------------------------------
 // 火车会话检索(2026-09-03 实装;12306 余票查询是公开面——登录只关系下单,
 // 无账号数据过手,故无登录闸;扩展照样只读被动嗅探,证据链标注「公开查询面」)
@@ -319,12 +524,34 @@ export interface SessionTrainResult {
   latencyMs: number
   verdict: SessionVerdict
   trains?: SessionTrainOption[]
+  /** Typed parser/runtime outcome. `trains` remains a compatibility projection. */
+  outcome: TrainSessionOutcome
+  /** Created by this search invocation; facts must use this binding, not caller metadata. */
+  collection?: TrainCollectionBinding
   error?: string
   /** needs-extension 时给出 Chrome Web Store URL(dsh UI 渲成可点链接) */
   installUrl?: string
   installAction?: 'add-to-chrome'
 }
 
+export type TrainSessionOutcome = TrainQueryParseOutcome | {
+  kind: 'transport-runtime-error'
+  reason: string
+}
+
+export interface TrainCollectionBinding {
+  /** Route/date captured by the actual session invocation. */
+  requested: { from: string; to: string; date: string }
+  /** Resolved telecodes/date used to build this invocation's query. */
+  request: { fromStationTelecode: string; toStationTelecode: string; date: string }
+  /** Provenance from the exact response whose body produced the typed outcome. */
+  response: TrainResponseBinding
+  /** Per-invocation identity; never derived by the fact converter. */
+  batchId: string
+  queryId: string
+  fetchedAt: string
+}
+
 /** 车站电报码表未收录时的人话指引(纯函数,测试锚点) */
 export function trainStationUnresolvedHint(cities: string[]): string {
   return `城市 ${cities.join('/')} 不在 12306 城市电报码表——web 搜「12306 ${cities[0] ?? ''} 余票」拿到 kyfw 查询页 URL 里的 fs=城市,XXX 三位码,带 fromStationTelecode/toStationTelecode 重试`
@@ -335,9 +562,72 @@ export async function sessionTrainSearch(q: SessionTrainQuery): Promise<SessionT
   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,
+    ok: false, via: 'session-train-12306-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict,
+    outcome: { kind: 'transport-runtime-error', reason: error }, error,
   })
 
+  const parsedResult = (body: string, responseUrl: string, evidence: string, guardSuffix = ''): SessionTrainResult => {
+    const outcome = parseLeftTicketQueryResult(body, entry.url!, { maxItems: 30 })
+    if (outcome.kind === 'malformed') {
+      return {
+        ok: false,
+        via: 'session-train-12306-error',
+        evidence: `${evidence} typed-parse=malformed`,
+        latencyMs: Date.now() - started,
+        verdict: 'error',
+        outcome,
+        error: `12306 leftTicket/query 响应未通过 typed contract:${outcome.reason}`,
+      }
+    }
+    const request = resolveTrainQueryTelecodes({ from: q.from, to: q.to, date: q.date, fromStationTelecode: q.fromStationTelecode, toStationTelecode: q.toStationTelecode })
+    if (!request.ok) {
+      return {
+        ok: false,
+        via: 'session-train-12306-error',
+        evidence: `${evidence} typed-response-binding=unresolved`,
+        latencyMs: Date.now() - started,
+        verdict: 'error',
+        outcome,
+        trains: outcome.trains,
+        error: `12306 查询请求电报码未解析:${request.unresolved.join(',')}`,
+      }
+    }
+    const response = validateTrainQueryResponseUrl(responseUrl, request.telecodes)
+    if (!response.ok) {
+      return {
+        ok: false,
+        via: 'session-train-12306-error',
+        evidence: `${evidence} typed-response-binding=invalid`,
+        latencyMs: Date.now() - started,
+        verdict: 'error',
+        outcome,
+        trains: outcome.trains,
+        error: `12306 leftTicket/query 响应未绑定本次请求:${response.reason}`,
+      }
+    }
+    const fetchedAt = new Date().toISOString()
+    const batchId = randomUUID()
+    const collection: TrainCollectionBinding = {
+      requested: { from: q.from, to: q.to, date: q.date },
+      request: request.telecodes,
+      response: response.binding,
+      batchId,
+      queryId: `session:12306-train:${batchId}`,
+      fetchedAt,
+    }
+    const trains = outcome.trains
+    return {
+      ok: true,
+      via: 'session-train-12306',
+      evidence: `${evidence} ${guardSuffix}`.trim(),
+      latencyMs: Date.now() - started,
+      verdict: outcome.kind === 'recognized-nonempty' ? 'hit' : 'miss',
+      outcome,
+      collection,
+      trains,
+    }
+  }
+
   // 节律闸:超间隔即拒,不发起导航
   const last = lastCallAt.get(site) ?? 0
   if (Date.now() - last < MIN_INTERVAL_MS) {
@@ -362,7 +652,7 @@ export async function sessionTrainSearch(q: SessionTrainQuery): Promise<SessionT
     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 { ok: false, via: 'session-train-12306-error', evidence: '[会话:train-12306-needs-extension@ts]', latencyMs: Date.now() - started, verdict, outcome: { kind: 'transport-runtime-error', reason: r.summary }, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' as const }
       }
       return err(verdict, r.summary)
     }
@@ -371,26 +661,20 @@ export async function sessionTrainSearch(q: SessionTrainQuery): Promise<SessionT
     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,
-    }
+    return parsedResult(r.body, r.url, `[会话:${site}@${ts}] transport=extension(公开查询面,被动嗅探,零系统弹窗;扩展零写行为=物理只读)`)
   }
 
   // cdp/persistent 车道:与机/酒同构
-  const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true })
+  const t = await (trainSessionTransportForTest
+    ? trainSessionTransportForTest()
+    : 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 = ''
+    let responseUrl = ''
     const heard = new Promise<void>((resolve) => {
       t.page.on('response', async (res) => {
         if (settled) return
@@ -400,6 +684,7 @@ export async function sessionTrainSearch(q: SessionTrainQuery): Promise<SessionT
           const text = await res.text()
           if (text) {
             body = text
+            responseUrl = u
             settled = true
             resolve()
           }
@@ -414,16 +699,7 @@ export async function sessionTrainSearch(q: SessionTrainQuery): Promise<SessionT
     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,
-    }
+    return parsedResult(body, responseUrl, `[会话:${site}@${ts}] 12306 公开查询面`, `guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}`)
   } catch (e) {
     return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e))
   } finally {
@@ -485,8 +761,12 @@ export async function sessionFlightSearch(q: SessionFlightQuery): Promise<Sessio
     if (CHALLENGE_RE.test(title + head)) {
       return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
     }
-    const options = parseBatchSearch(r.body)
-    const verdict: SessionVerdict = options.length > 0 ? 'hit' : 'miss'
+    const parsed = parseBatchSearchResult(r.body)
+    if (parsed.verdict === 'error') {
+      return err('error', `batchSearch 响应形状异常(非合法空响应;options=0 不视为 miss):body ${r.body.length}B 头 ${r.body.slice(0, 80)}`)
+    }
+    const options = parsed.options
+    const verdict: SessionVerdict = parsed.verdict === 'hit' ? 'hit' : 'miss'
     return {
       ok: true,
       via: 'session-ctrip-flight',
@@ -543,8 +823,12 @@ export async function sessionFlightSearch(q: SessionFlightQuery): Promise<Sessio
     if (CHALLENGE_RE.test(title + headHtml)) {
       return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
     }
-    const options = parseBatchSearch(body)
-    const verdict: SessionVerdict = options.length > 0 ? 'hit' : 'miss'
+    const parsed = parseBatchSearchResult(body)
+    if (parsed.verdict === 'error') {
+      return err('error', `batchSearch 响应形状异常(非合法空响应;options=0 不视为 miss):body ${body.length}B 头 ${body.slice(0, 80)}`)
+    }
+    const options = parsed.options
+    const verdict: SessionVerdict = parsed.verdict === 'hit' ? 'hit' : 'miss'
     return {
       ok: true,
       via: 'session-ctrip-flight',

package/ts/dsh-runtime/vendor/README.md

@@ -27,12 +27,16 @@ dsh 发布家族的全量 vendored 成员,pnpm workspace 方式参与安装
 
 `dsh-map-tools`(dshmarket 第三方宿主插件,地图/路线/POI,零 key 走
 OSM/OSRM)与 dsh 家族不同源,进本目录的原因是 **npm 依赖形态被上游
-peerDependencies 否决**:它要求 `dsh-settings`/`dsh-tools`
-`>=0.1.2-rc.1`,而 gotry 锁定的运行时家族是 `0.1.2-alpha.3`
+peerDependencies 否决**:历史上游要求 `dsh-settings`/`dsh-tools`
+`>=0.1.2-rc.1`,而 gotry 历史锁定的运行时家族是 `0.1.2-alpha.3`
 (semver 上 alpha < rc)——npm/npx 严格 peer 解析直接 ERESOLVE
 (optionalDependencies 也不豁免),硬依赖会弄坏 `npx @danceiny/gotry`
-主安装路径。故以 vendor 副本随 tarball 分发(root `package.json`
-`files[]` 含本目录),`bin/gotry-inner.js` 解析链 vendor 优先;
+主安装路径。当前锁定 `0.1.5-alpha.1` 家族后,`>=0.1.2-rc.1` 已被满足,
+但 vendored 副本 peerDependencies 已对齐 `0.1.5-alpha.1`,继续保持
+vendored 形态复用同一份适配补丁与七工具接线,避免在 npm 依赖面引入
+额外硬依赖而弄坏 `npx @danceiny/gotry` 主安装路径。故以 vendor
+副本随 tarball 分发(root `package.json` `files[]` 含本目录),
+`bin/gotry-inner.js` 解析链 vendor 优先;
 升级 = 从 npm 拉 `dsh-map-tools@<new>` 覆盖本目录(保留来源与
 license:MIT,上游 package.json 里无 devDependencies 需清理)。