@danceiny/gotry 0.0.1-rc.14 → 0.0.1-rc.16

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

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

package/ts/capabilities/session/wizard.ts

@@ -0,0 +1,282 @@
+/**
+ * 会话扩展 onboarding wizard(issue #21 onboarding UX,P3.6 gotry-session-onboarding-goal,
+ * RFC user-session-data-rfc.md §3.3)。
+ *
+ * 单一职责:**编排** 4 步闭环(扩展落位→打开 chrome://extensions→剪贴板复制→后台 health-watch) +
+ * 跨平台降级(macOS osascript / Linux zenity / Windows msg / headless 终端)。
+ * 不实现任何 cookie 值读取、不发起任何写入操作、不引 GUI 包。
+ *
+ * 形态:
+ * - `runOnboardingWizard({ dryRun, openBrowser, clipboard, panel })` 返回步骤结果数组;
+ * - 每步 `{step, status: 'ok'|'skip'|'fail', summary}`;终端 stdout 顺序打印;
+ * - 失败步不挡退出(exit 0;失败信息人话化,不抛栈)。
+ *
+ * 跨平台策略:
+ * - macOS:`osascript -e 'tell application "Google Chrome" to open location "chrome://extensions"'`
+ *   + `pbcopy <path>`;有 Cocoa 引导面板(`osascript -e 'display dialog ...'`)。
+ * - Linux:`xdg-open chrome://extensions`(浏览器由系统默认) + `xclip -selection clipboard`;
+ *   有 `zenity --info --text=...` 面板(无 zenity 降 terminal)。
+ * - Windows:`start chrome chrome://extensions` + `clip`;无 panel,降 terminal。
+ * - Headless(SSH / CI):terminal 面板 + 跳过所有 GUI 调用。
+ *
+ * 不引入 npm 包:osascript/zenity/pbcopy/xclip/clip/start/xdg-open 走 child_process.spawn,
+ * 失败降级 stdout,不挡主流程(run-all §40 onboarding-tests 4 断言覆盖跨平台降级)。
+ *
+ * 输出形态:`runOnboardingWizard` 是纯编排,**不直接抓 Chrome 状态**——
+ * 健康检查由 health-watch.ts 接管(单独测试覆盖)。Wizard 只负责「把人引到 Chrome 前」,
+ * watch 负责「等 Chrome 真的就绪」。
+ */
+
+import { spawn } from 'node:child_process'
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
+import { homedir, platform } from 'node:os'
+import { join } from 'node:path'
+
+export interface OnboardingStep {
+  step: 'ensure-extension-files' | 'open-chrome-extensions' | 'clipboard-extension-path' | 'watch-extension-ready' | 'panel-guide'
+  status: 'ok' | 'skip' | 'fail'
+  summary: string
+}
+
+export interface OnboardingOptions {
+  /** 零网络零浏览器;只校验命令编排与输出形态;run-all §40 必走 */
+  dryRun?: boolean
+  /** 扩展落位目录(默认 ~/.gotry/extension) */
+  extensionDir?: string
+  /** 源扩展目录(默认仓库 ./extension/,随 npm 装入 dist/extension) */
+  sourceDir?: string
+  /** 覆盖平台探测(headless 测试) */
+  forcePlatform?: 'darwin' | 'linux' | 'win32' | 'headless'
+  /** 注入 spawn(测试可拦截命令执行);签名同 child_process.spawn,默认 spawn */
+  spawn?: typeof spawn
+}
+
+export interface OnboardingResult {
+  ok: boolean
+  steps: OnboardingStep[]
+  platform: 'darwin' | 'linux' | 'win32' | 'headless'
+  extensionDir: string
+}
+
+const DEFAULT_SOURCE_DIR_CANDIDATES = [
+  join(process.cwd(), 'extension'),
+  join(process.cwd(), 'dist', 'extension'),
+  join(process.cwd(), 'ts', '..', 'extension'),
+]
+
+function resolveExtensionSourceDir(): string {
+  for (const candidate of DEFAULT_SOURCE_DIR_CANDIDATES) {
+    if (existsSync(join(candidate, 'manifest.json'))) return candidate
+  }
+  return DEFAULT_SOURCE_DIR_CANDIDATES[0]!
+}
+
+export function defaultExtensionDir(): string {
+  return join(homedir(), '.gotry', 'extension')
+}
+
+function detectPlatform(force?: OnboardingOptions['forcePlatform']): 'darwin' | 'linux' | 'win32' | 'headless' {
+  if (force) return force
+  if (process.env.GOTRY_ONBOARDING_HEADLESS === '1') return 'headless'
+  const p = platform()
+  if (p === 'darwin' || p === 'linux' || p === 'win32') {
+    if (p !== 'darwin' && !process.env.DISPLAY) return 'headless'
+    return p
+  }
+  return 'headless'
+}
+
+/** 落位扩展文件(幂等);缺源/源不全会 fail-soft,提示用户重跑 `gotry setup` */
+function ensureExtensionFiles(source: string, target: string, dryRun: boolean): OnboardingStep {
+  if (dryRun) return { step: 'ensure-extension-files', status: 'skip', summary: '[dry-run] skip 扩展落位' }
+  try {
+    if (!existsSync(source) || !existsSync(join(source, 'manifest.json'))) {
+      return { step: 'ensure-extension-files', status: 'fail', summary: `源扩展目录缺失 manifest.json: ${source}(先跑 npx gotry setup 落位)` }
+    }
+    mkdirSync(target, { recursive: true })
+    const required = ['manifest.json', 'background.js', 'content-main.js', 'content-bridge.js']
+    for (const f of required) {
+      const src = join(source, f)
+      if (!existsSync(src)) return { step: 'ensure-extension-files', status: 'fail', summary: `源扩展缺 ${f}(重新 npm install 或 gotry setup)` }
+      copyFileSync(src, join(target, f))
+    }
+    return { step: 'ensure-extension-files', status: 'ok', summary: `扩展已落位 ${target}(manifest+3 文件)` }
+  } catch (e) {
+    return { step: 'ensure-extension-files', status: 'fail', summary: `扩展落位失败: ${e instanceof Error ? e.message.slice(0, 120) : String(e)}` }
+  }
+}
+
+/** 打开 chrome://extensions;失败降级提示用户手开 */
+function openChromeExtensions(sp: typeof spawn, plat: 'darwin' | 'linux' | 'win32' | 'headless', dryRun: boolean): OnboardingStep {
+  if (dryRun) return { step: 'open-chrome-extensions', status: 'skip', summary: '[dry-run] skip 打开 chrome://extensions' }
+  if (plat === 'headless') return { step: 'open-chrome-extensions', status: 'skip', summary: 'headless 环境跳过 GUI;请在你桌面 Chrome 手动打开 chrome://extensions' }
+  const cmd = (() => {
+    if (plat === 'darwin') return { bin: 'open', args: ['-a', 'Google Chrome', 'chrome://extensions'] }
+    if (plat === 'linux') return { bin: 'xdg-open', args: ['chrome://extensions'] }
+    return { bin: 'cmd', args: ['/c', 'start', 'chrome', 'chrome://extensions'] }
+  })()
+  try {
+    const child = sp(cmd.bin, cmd.args, { detached: true, stdio: 'ignore' })
+    child.unref?.()
+    return { step: 'open-chrome-extensions', status: 'ok', summary: `已打开 chrome://extensions(${plat})` }
+  } catch (e) {
+    return { step: 'open-chrome-extensions', status: 'fail', summary: `自动打开失败: ${e instanceof Error ? e.message.slice(0, 80) : String(e)};请手开 chrome://extensions` }
+  }
+}
+
+/** 复制扩展目录路径到剪贴板;失败降级 stdout */
+async function clipboardExtensionPath(sp: typeof spawn, plat: 'darwin' | 'linux' | 'win32' | 'headless', path: string, dryRun: boolean): Promise<OnboardingStep> {
+  if (dryRun) return { step: 'clipboard-extension-path', status: 'skip', summary: '[dry-run] skip 剪贴板复制' }
+  if (plat === 'headless') return { step: 'clipboard-extension-path', status: 'skip', summary: `headless 无剪贴板;扩展目录路径:${path}` }
+  const cmd = (() => {
+    if (plat === 'darwin') return { bin: 'pbcopy', args: [] as string[] }
+    if (plat === 'linux') return { bin: 'xclip', args: ['-selection', 'clipboard'] }
+    return { bin: 'clip', args: [] as string[] }
+  })()
+  // 关键:pbcopy/xclip/clip 都在 stdin EOF 之后才提交内容,stdin 必须 pipe,
+  // 且必须 await exit(否则 end() 还在 buffer 里就被当作「完成」)。
+  // 之前用 stdio: 'inherit' → stdin 是 null → write 没生效 → 用户剪贴板没被覆盖。
+  return new Promise<OnboardingStep>((resolveStep) => {
+    let child: ReturnType<typeof spawn>
+    try {
+      child = sp(cmd.bin, cmd.args, { stdio: ['pipe', 'ignore', 'ignore'] }) as unknown as ReturnType<typeof spawn>
+    } catch {
+      resolveStep({ step: 'clipboard-extension-path', status: 'skip', summary: `剪贴板工具不可用(${cmd.bin});扩展目录路径手动复制: ${path}` })
+      return
+    }
+    let settled = false
+    const settle = (s: OnboardingStep): void => {
+      if (settled) return
+      settled = true
+      resolveStep(s)
+    }
+    child.on('error', () => settle({ step: 'clipboard-extension-path', status: 'skip', summary: `剪贴板工具启动失败(${cmd.bin});扩展目录路径手动复制: ${path}` }))
+    child.on('exit', (code) => {
+      if (code === 0) settle({ step: 'clipboard-extension-path', status: 'ok', summary: `已复制扩展目录到剪贴板: ${path}` })
+      else settle({ step: 'clipboard-extension-path', status: 'fail', summary: `剪贴板工具退出码 ${code}(${cmd.bin});扩展目录路径手动复制: ${path}` })
+    })
+    try {
+      child.stdin?.write(path)
+      child.stdin?.end()
+    } catch {
+      settle({ step: 'clipboard-extension-path', status: 'skip', summary: `剪贴板工具 stdin 不可写(${cmd.bin});扩展目录路径手动复制: ${path}` })
+    }
+  })
+}
+
+/** 终端面板 stdout(无 GUI 时唯一形态);headless / GUI 不可用时使用 */
+function panelGuideTerminal(plat: 'darwin' | 'linux' | 'win32' | 'headless', extensionDir: string, watchMs: number): OnboardingStep {
+  const lines = [
+    '┌─ GoTry 扩展安装 ─────────────────────────────────┐',
+    '│  共 3 步,约 30 秒,装完零弹窗                     │',
+    '│                                                   │',
+    '│  ① 在 Chrome 右上角开启「开发者模式」             │',
+    `│  ② 点「加载已解压的扩展程序」选这个目录(已复制):  │`,
+    `│     ${extensionDir}`,
+    '│  ③ 弹窗「添加扩展」点「添加」                    │',
+    `│                                                   │`,
+    `│  后台探活中(最长 ${Math.round(watchMs / 1000)}s)…         │`,
+    '└───────────────────────────────────────────────────┘',
+  ]
+  // headless = 纯文本面板;darwin/linux/win32 在 GUI 面板不可用时也走这路
+  if (plat === 'headless') {
+    process.stdout.write(lines.join('\n') + '\n')
+    return { step: 'panel-guide', status: 'skip', summary: 'headless 终端面板已打印' }
+  }
+  process.stdout.write(lines.join('\n') + '\n')
+  return { step: 'panel-guide', status: 'skip', summary: '终端面板已打印(GUI 面板降级)' }
+}
+
+/** GUI 面板(Cocoa / zenity / msg);失败降 terminal */
+function panelGuideGui(sp: typeof spawn, plat: 'darwin' | 'linux' | 'win32' | 'headless', extensionDir: string, dryRun: boolean): OnboardingStep {
+  if (dryRun) return { step: 'panel-guide', status: 'skip', summary: '[dry-run] skip GUI 面板' }
+  if (plat === 'headless') return panelGuideTerminal(plat, extensionDir, 120_000)
+  const message = `在 Chrome 右上角开启「开发者模式」 → 点「加载已解压的扩展程序」 → 选择(已复制):${extensionDir} → 弹窗点「添加扩展」`
+  try {
+    if (plat === 'darwin') {
+      const script = `display dialog "${message.replace(/"/g, '\\"')}" with title "GoTry 扩展安装" buttons {"我装好了"} default button 1`
+      sp('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref?.()
+      return { step: 'panel-guide', status: 'ok', summary: '已弹 macOS Cocoa 引导面板' }
+    }
+    if (plat === 'linux') {
+      const child = sp('zenity', ['--info', '--title=GoTry 扩展安装', `--text=${message}`], { stdio: 'ignore', detached: true })
+      child.unref?.()
+      child.on('error', () => {
+        process.stdout.write(`(zenity 不可用,走终端面板)扩展目录: ${extensionDir}\n`)
+      })
+      return { step: 'panel-guide', status: 'ok', summary: '已弹 zenity 引导面板' }
+    }
+    // Windows:无原生 msg 面板,降终端
+    return panelGuideTerminal(plat, extensionDir, 120_000)
+  } catch (e) {
+    return panelGuideTerminal(plat, extensionDir, 120_000)
+  }
+}
+
+/** 探活:留给 health-watch.ts,这里只打日志;集成在 main runner 时再调 */
+async function watchExtensionReady(dryRun: boolean, sourceDir: string, extensionDir: string): Promise<OnboardingStep> {
+  if (dryRun) return { step: 'watch-extension-ready', status: 'skip', summary: '[dry-run] skip health-watch' }
+  // 真实集成由 cli/wizard runner 接管(避免 wizard 模块 import health-watch 形成环);
+  // 这里只校验源文件齐全 + 落位目录可见
+  if (!existsSync(extensionDir) || !existsSync(join(extensionDir, 'manifest.json'))) {
+    return { step: 'watch-extension-ready', status: 'fail', summary: `落位缺失 manifest.json:${extensionDir}` }
+  }
+  const srcStat = statSync(sourceDir)
+  const dstStat = statSync(extensionDir)
+  if (srcStat.mtimeMs > dstStat.mtimeMs) {
+    return { step: 'watch-extension-ready', status: 'fail', summary: `扩展文件可能过期(源比落位新);重跑 npx gotry setup` }
+  }
+  // 读 manifest 校验 key 存在(=扩展 ID 稳定)
+  const manifest = JSON.parse(await (await import('node:fs/promises')).readFile(join(extensionDir, 'manifest.json'), 'utf8'))
+  if (typeof manifest.key !== 'string' || manifest.key.length < 100) {
+    return { step: 'watch-extension-ready', status: 'fail', summary: 'manifest.key 缺失或过短,扩展 ID 不能稳定' }
+  }
+  return { step: 'watch-extension-ready', status: 'ok', summary: '扩展文件就绪(manifest.key 校验通过,后台轮询就绪态由 health-watch 接管)' }
+}
+
+/**
+ * 主入口:wizard 编排 5 步闭环(ensure→open→clipboard→panel→watch-precheck)。
+ * 真实 health-watch 由 cli runner 在面板按下「我装好了」后启,本函数只做静态预检。
+ */
+export async function runOnboardingWizard(opts: OnboardingOptions = {}): Promise<OnboardingResult> {
+  const sp = opts.spawn ?? spawn
+  const dryRun = opts.dryRun ?? false
+  const plat = detectPlatform(opts.forcePlatform)
+  const extensionDir = opts.extensionDir ?? defaultExtensionDir()
+  const sourceDir = opts.sourceDir ?? resolveExtensionSourceDir()
+
+  const steps: OnboardingStep[] = []
+  steps.push(ensureExtensionFiles(sourceDir, extensionDir, dryRun))
+  steps.push(openChromeExtensions(sp, plat, dryRun))
+  if (plat !== 'headless') {
+    steps.push(await clipboardExtensionPath(sp, plat, extensionDir, dryRun))
+    steps.push(panelGuideGui(sp, plat, extensionDir, dryRun))
+  } else {
+    steps.push({ step: 'clipboard-extension-path', status: 'skip', summary: 'headless 跳过剪贴板' })
+    steps.push(panelGuideTerminal(plat, extensionDir, 120_000))
+  }
+  steps.push(await watchExtensionReady(dryRun, sourceDir, extensionDir))
+
+  const ok = steps.every((s) => s.status !== 'fail')
+  return { ok, steps, platform: plat, extensionDir }
+}
+
+/** stdout 人话化打印(默认终端面板形态);测试可禁用 */
+export function printWizardResult(result: OnboardingResult, destination: NodeJS.WritableStream = process.stdout): void {
+  const tag = (s: OnboardingStep): string => {
+    if (s.status === 'ok') return '✅'
+    if (s.status === 'skip') return '⏭ '
+    return '❌'
+  }
+  for (const s of result.steps) {
+    destination.write(`${tag(s)} ${s.step}: ${s.summary}\n`)
+  }
+  destination.write(`platform=${result.platform}; extensionDir=${result.extensionDir}; overall=${result.ok ? 'ok' : 'has-failures'}\n`)
+}
+
+/** 留作 onboard final summary 的只读探针(便于 cli 输出「已就绪 / 待装」) */
+export function describeExtensionDir(extensionDir: string): { exists: boolean; fileCount: number; hasManifest: boolean } {
+  if (!existsSync(extensionDir)) return { exists: false, fileCount: 0, hasManifest: false }
+  const files = readdirSync(extensionDir)
+  return { exists: true, fileCount: files.length, hasManifest: files.includes('manifest.json') }
+}

package/ts/capabilities/session-login.ts

@@ -14,6 +14,8 @@
  */
 
 import { openSession } from './session/transport.ts'
+import { extensionCookieNames, extensionOpenLogin, classifyBridgeFailure, NEEDS_EXTENSION_HINT } from './session/extension-channel.ts'
+import { resolveTransportMode } from './session-search.ts'
 
 export interface LoginTarget {
   domain: string
@@ -48,7 +50,7 @@ export interface SessionLoginResult {
   via: 'session-login' | 'session-login-error'
   evidence: string
   latencyMs: number
-  verdict: 'logged-in' | 'pending' | 'needs-attach' | 'error'
+  verdict: 'logged-in' | 'pending' | 'needs-attach' | 'needs-extension' | 'error'
   site: string
   /** 已检出的登录票据 cookie 名(名字,非值——本模块永不读取/存储/回传任何 cookie 值) */
   tickets?: string[]
@@ -74,7 +76,7 @@ export async function pollTicketNames(browser: { cookies(): Promise<CookieLike[]
 /**
  * 产品化登录引导(永不抛错;登录由用户在携程官网完成,gotry 只做名称级存在性检查)。
  * verdict:logged-in=已检出票据;pending=登录入口已打开、用户尚未完成(不阻塞,可稍后再查);
- * needs-attach=用户 Chrome 未开调试端口(一次性开关指引);error=其余降级。
+ * needs-extension=扩展桥未连接(一次性安装指引,默认车道);needs-attach=cdp 车道下用户 Chrome 未开调试端口;error=其余降级。
  */
 export async function sessionLogin(q: SessionLoginQuery = {}): Promise<SessionLoginResult> {
   const started = Date.now()
@@ -84,6 +86,10 @@ export async function sessionLogin(q: SessionLoginQuery = {}): Promise<SessionLo
   if (!target) {
     return err(site, 'error', `未知站点 ${site}(可选 ${Object.keys(LOGIN_TARGETS).join('/')})`, started, ts)
   }
+  // 扩展车道(默认):零 CDP、零系统弹窗——cookie 名快查 + 登录入口 job
+  if (resolveTransportMode() === 'extension') {
+    return sessionLoginViaExtension(site, target, q, started, ts)
+  }
   // 人机共治纪律:开自己的新标签页并置前台——用户必须看见登录页(2026-08-29 founder:
   // 「我根本就看不到登录页面」,此前误劫持用户既有标签页);closeOwnPage=false 把登录页留给用户
   const t = await openSession({ mode: 'cdp', guard: false })
@@ -143,4 +149,49 @@ export async function sessionLogin(q: SessionLoginQuery = {}): Promise<SessionLo
     await t.close().catch(() => { /* ignore */ })
     return err(site, 'error', e instanceof Error ? e.message : String(e), started, ts)
   }
+}
+
+/**
+ * 扩展车道登录引导(2026-08-29 传输层方案 C):语义与 cdp 车道一致——
+ * 自动检测优先(票据名在 = 零弹窗直接确认);未检出才开登录入口 job(置前台,标签留给用户);
+ * 只读轮询票据名,永不接触 cookie 值。verdict:logged-in | pending | needs-extension | error。
+ */
+async function sessionLoginViaExtension(site: string, target: LoginTarget, q: SessionLoginQuery, started: number, ts: string): Promise<SessionLoginResult> {
+  const evidenceTag = `[会话:${site}-login@${ts}]`
+  const quick = (verdict: SessionLoginResult['verdict'], error: string): SessionLoginResult => ({
+    ok: false, via: 'session-login-error', evidence: `[会话:login-error@${ts}] ${error.slice(0, 200)}`,
+    latencyMs: Date.now() - started, verdict, site, error: verdict === 'needs-extension' ? `${error};${NEEDS_EXTENSION_HINT}`.slice(0, 400) : error.slice(0, 400),
+  })
+  // 自动检测优先:先只读票据名——已登录则零交互直接确认(与 cdp 车道同一语义,founder「UI 里有自动检测吗」)
+  const pre = await extensionCookieNames({ site, domain: target.domain, ticketNames: target.names, timeoutMs: 8_000 })
+  if (!pre.ok) return quick(classifyBridgeFailure(pre.kind) === 'needs-extension' ? 'needs-extension' : 'error', pre.summary)
+  if (pre.tickets.length > 0) {
+    return {
+      ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'logged-in', site, tickets: pre.tickets,
+      evidence: `${evidenceTag} 自动检测:票据 cookie 已在(先前登录已生效)——[${pre.tickets.join(', ')}](只读名字,0 网页交互,零弹窗)`,
+    }
+  }
+  // 未检出 → 开登录入口标签(置前台,绝不劫持用户已有页面;登录在携程官网完成)
+  const opened = await extensionOpenLogin({ site, url: target.entryUrl, timeoutMs: 15_000 })
+  if (!opened.ok) return quick(classifyBridgeFailure(opened.kind) === 'needs-extension' ? 'needs-extension' : 'error', opened.summary)
+  const waitMs = Math.min(Math.max(q.waitMs ?? 90_000, 0), 300_000)
+  const pollMs = Math.min(Math.max(q.pollMs ?? 3_000, 500), 10_000)
+  const deadline = Date.now() + waitMs
+  let tickets: string[] = []
+  while (Date.now() < deadline) {
+    await new Promise<void>((resolve) => setTimeout(resolve, pollMs))
+    const poll = await extensionCookieNames({ site, domain: target.domain, ticketNames: target.names, timeoutMs: 8_000 })
+    if (poll.ok) tickets = poll.tickets
+    if (tickets.length > 0) break
+  }
+  if (tickets.length > 0) {
+    return {
+      ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'logged-in', site, tickets,
+      evidence: `${evidenceTag} 票据 cookie 已检出 [${tickets.join(', ')}](只读名字;登录在你自己的浏览器里完成,gotry 全程未接触任何密码/验证码/cookie 值)`,
+    }
+  }
+  return {
+    ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'pending', site, tickets: [],
+    evidence: `${evidenceTag} 登录入口已在你的 Chrome 置前打开(${target.label});在标签页里正常登录完成后再说一声「继续查」即可——gotry 只检查"是否已登录",永不收集你的账号信息`,
+  }
 }