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

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,
+  }
+}

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

@@ -20,7 +20,7 @@
  * - 重放上限(防止 watch 反复 ready/抖动导致无限重放;maxRetries 默认 1)。
  *
  * 纪律:
- * - 不引 GUI 依赖;只 spawn `node:http` 探活(已经在扩展桥验证过,§38 23 断言覆盖);
+ * - 不引 GUI 依赖;只 spawn `node:http` 探活(已经在扩展桥验证过,§38 24 断言覆盖);
  * - 不持锁、不轮询文件、不读 dsh-runtime 共享状态;
  * - 不污染扩展桥 single-instance;probe 走独立短连接。
  */

package/ts/capabilities/session/static-flight-golden.ts

@@ -0,0 +1,209 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { SessionComparableRecord, SessionComparableSegment } from './benchmark.ts'
+
+export type GoldenSource = 'manual' | 'flyai' | 'static'
+
+export interface StaticFlightRouteLeg {
+  from_iata: string
+  to_iata: string
+  carrier_codes: string[]
+}
+
+export interface StaticFlightRoute {
+  query_id: string
+  from_city: string
+  to_city: string
+  route_kind: 'direct' | 'transfer'
+  legs: StaticFlightRouteLeg[]
+}
+
+export interface StaticFlightSnapshot {
+  schema_version: 'sf-static-routes.v1'
+  source: {
+    name: string
+    url: string
+    revision: string
+    license: string
+    retrieved_at: string
+    limitations: string[]
+  }
+  routes: StaticFlightRoute[]
+}
+
+export interface StaticGoldenResolution {
+  requested_source: 'static'
+  effective_source: 'static-openflights+manual-band' | 'manual-golden'
+  record: SessionComparableRecord
+  fallback_reason?: string
+  estimated_fields: string[]
+  provenance: {
+    route_source: string
+    route_revision: string
+    route_license: string
+    band_source: 'sf-golden-manifest.json'
+  }
+}
+
+export function parseGoldenSource(args: string[]): GoldenSource {
+  const raw = args.find((arg) => arg.startsWith('--golden='))?.slice('--golden='.length) ?? 'manual'
+  if (raw === 'manual' || raw === 'flyai' || raw === 'static') return raw
+  throw new Error(`不支持的 golden vendor: ${raw}`)
+}
+
+export function loadStaticFlightSnapshot(
+  path = join(import.meta.dirname, '..', '..', 'data', 'sf-static-routes.json'),
+): StaticFlightSnapshot {
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+  if (!isRecord(parsed) || parsed.schema_version !== 'sf-static-routes.v1') {
+    throw new Error(`invalid static snapshot schema_version: ${String(isRecord(parsed) ? parsed.schema_version : undefined)}`)
+  }
+  const source = parsed.source
+  if (!isRecord(source)
+    || !['name', 'url', 'revision', 'license', 'retrieved_at'].every((key) => typeof source[key] === 'string')
+    || !Array.isArray(source.limitations)
+    || !source.limitations.every((item) => typeof item === 'string')) {
+    throw new Error('invalid static snapshot source')
+  }
+  if (!Array.isArray(parsed.routes) || !parsed.routes.every(isStaticFlightRoute)) {
+    throw new Error('invalid static snapshot routes')
+  }
+  return parsed as unknown as StaticFlightSnapshot
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isStaticFlightRoute(value: unknown): boolean {
+  if (!isRecord(value)
+    || typeof value.query_id !== 'string'
+    || typeof value.from_city !== 'string'
+    || typeof value.to_city !== 'string'
+    || (value.route_kind !== 'direct' && value.route_kind !== 'transfer')
+    || !Array.isArray(value.legs)
+    || value.legs.length === 0) return false
+  return value.legs.every((leg) => isRecord(leg)
+    && typeof leg.from_iata === 'string'
+    && typeof leg.to_iata === 'string'
+    && Array.isArray(leg.carrier_codes)
+    && leg.carrier_codes.every((carrier) => typeof carrier === 'string'))
+}
+
+function provenance(snapshot?: StaticFlightSnapshot): StaticGoldenResolution['provenance'] {
+  return {
+    route_source: snapshot?.source.url ?? '',
+    route_revision: snapshot?.source.revision ?? '',
+    route_license: snapshot?.source.license ?? '',
+    band_source: 'sf-golden-manifest.json',
+  }
+}
+
+function formatWithOffset(timestampMs: number, offset: string): string {
+  const sign = offset.startsWith('-') ? -1 : 1
+  const [hours, minutes] = offset.slice(1).split(':').map(Number)
+  const offsetMinutes = sign * ((hours ?? 0) * 60 + (minutes ?? 0))
+  const local = new Date(timestampMs + offsetMinutes * 60_000).toISOString().slice(0, 19)
+  return `${local}${offset}`
+}
+
+function buildSegments(
+  query: { from: string; to: string },
+  route: StaticFlightRoute,
+  manualSegment: SessionComparableSegment,
+): SessionComparableSegment[] | null {
+  if (route.route_kind === 'direct' && route.legs.length === 1) {
+    return [{
+      from: query.from,
+      to: query.to,
+      departure_at: manualSegment.departure_at,
+      arrival_at: manualSegment.arrival_at,
+      transport_number: `${route.legs[0]!.carrier_codes[0]}-STATIC`,
+    }]
+  }
+  if (route.route_kind !== 'transfer' || route.legs.length !== 2) return null
+  const departureMs = Date.parse(manualSegment.departure_at)
+  const arrivalMs = Date.parse(manualSegment.arrival_at)
+  if (!Number.isFinite(departureMs) || !Number.isFinite(arrivalMs) || arrivalMs <= departureMs) return null
+  const offset = manualSegment.departure_at.match(/([+-]\d{2}:\d{2})$/)?.[1] ?? '+08:00'
+  const totalMinutes = Math.floor((arrivalMs - departureMs) / 60_000)
+  if (totalMinutes < 90) return null
+  const layoverMinutes = Math.min(60, Math.floor(totalMinutes / 3))
+  const travelMinutes = totalMinutes - layoverMinutes
+  const firstTravelMinutes = Math.floor(travelMinutes / 2)
+  const secondDepartureMs = arrivalMs - (travelMinutes - firstTravelMinutes) * 60_000
+  const middle = route.legs[0]!.to_iata
+  return [
+    {
+      from: query.from,
+      to: middle,
+      departure_at: manualSegment.departure_at,
+      arrival_at: formatWithOffset(departureMs + firstTravelMinutes * 60_000, offset),
+      transport_number: `${route.legs[0]!.carrier_codes[0]}-STATIC`,
+    },
+    {
+      from: middle,
+      to: query.to,
+      departure_at: formatWithOffset(secondDepartureMs, offset),
+      arrival_at: manualSegment.arrival_at,
+      transport_number: `${route.legs[1]!.carrier_codes[0]}-STATIC`,
+    },
+  ]
+}
+
+export function resolveStaticGolden(input: {
+  query: { id: string; from: string; to: string; date: string }
+  manualRecord: SessionComparableRecord
+  snapshot?: StaticFlightSnapshot
+  snapshotError?: string
+  warn?: (message: string) => void
+}): StaticGoldenResolution {
+  const route = input.snapshot?.routes.find((candidate) => candidate.query_id === input.query.id)
+  let fallbackReason: string | undefined
+  if (input.snapshotError) {
+    fallbackReason = `static snapshot unavailable: ${input.snapshotError}`
+  } else if (!route) {
+    fallbackReason = `static route missing for ${input.query.id}`
+  } else if (route.from_city !== input.query.from || route.to_city !== input.query.to) {
+    fallbackReason = `static route mismatch for ${input.query.id}`
+  } else if (route.legs.some((leg) => leg.carrier_codes.length === 0)) {
+    fallbackReason = `static carrier coverage missing for ${input.query.id}`
+  }
+
+  const manualSegment = input.manualRecord.route_segments[0]
+  const segments = !fallbackReason && route && manualSegment
+    ? buildSegments(input.query, route, manualSegment)
+    : null
+  if (!fallbackReason && !segments) fallbackReason = `static route cannot form comparable record for ${input.query.id}`
+
+  if (fallbackReason) {
+    input.warn?.(`[sf-live-benchmark] static vendor failed for ${input.query.id}: ${fallbackReason}; fallback=manual-golden`)
+    return {
+      requested_source: 'static',
+      effective_source: 'manual-golden',
+      record: input.manualRecord,
+      fallback_reason: fallbackReason,
+      estimated_fields: [],
+      provenance: provenance(input.snapshot),
+    }
+  }
+
+  return {
+    requested_source: 'static',
+    effective_source: 'static-openflights+manual-band',
+    record: {
+      ...input.manualRecord,
+      route_segments: segments!,
+      journey_type: route!.route_kind,
+      source: 'static-openflights+manual-band',
+    },
+    estimated_fields: [
+      'route_segments[].departure_at',
+      'route_segments[].arrival_at',
+      'route_segments[].transport_number',
+      'price',
+    ],
+    provenance: provenance(input.snapshot),
+  }
+}

package/ts/capabilities/session/wizard.ts

@@ -1,39 +1,29 @@
 /**
- * 会话扩展 onboarding wizard(issue #21 onboarding UX,P3.6 gotry-session-onboarding-goal,
- * RFC user-session-data-rfc.md §3.3)。
+ * 会话扩展 onboarding wizard(RFC user-session-data-rfc.md §3.3,ADR-21 上架后重设)。
  *
- * 单一职责:**编排** 4 步闭环(扩展落位→打开 chrome://extensions→剪贴板复制→后台 health-watch) +
- * 跨平台降级(macOS osascript / Linux zenity / Windows msg / headless 终端)。
- * 不实现任何 cookie 值读取、不发起任何写入操作、不引 GUI 包。
+ * 单一职责(2026-09-02 重设):**只做 Node 端两件事**——
+ *   ① 扩展文件从源落位到 `~/.gotry/extension`(幂等)
+ *   ② source/dest 静态预检 + manifest.key 校验(给 health-watch 前的快照)
  *
- * 形态:
- * - `runOnboardingWizard({ dryRun, openBrowser, clipboard, panel })` 返回步骤结果数组;
- * - 每步 `{step, status: 'ok'|'skip'|'fail', summary}`;终端 stdout 顺序打印;
- * - 失败步不挡退出(exit 0;失败信息人话化,不抛栈)。
+ * 浏览器商店安装是浏览器的事,dsh 渲染 verdict.installUrl 是 dsh UI 的事;
+ * gotry **不再**弹 GUI 面板(pbcopy/osascript/zenity/msg)、不再 open 浏览器、
+ * 不再写一墙文字 CLI 指引。任何"装到能用"的 UX 都由浏览器商店 + dsh UI 分担。
  *
- * 跨平台策略:
- * - 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 调用。
+ * 历史形态回顾:
+ * - 2026-08-30 初版:5 步编排 + 剪贴板 + GUI 面板 + 健康探活(全栈闭环初衷好,但越界管了浏览器)
+ * - 2026-09-02 上架后:缩为 2 步(ensure + watch precheck),纯 Node 职责
  *
- * 不引入 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 真的就绪」。
+ * 接口契约:
+ * - `runOnboardingWizard({ dryRun, extensionDir?, sourceDir? })` 返回 2 步 OnboardingResult
+ * - `defaultExtensionDir()` / `describeExtensionDir()` 留作公开工具
  */
 
-import { spawn } from 'node:child_process'
 import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
-import { homedir, platform } from 'node:os'
+import { homedir } 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'
+  step: 'ensure-extension-files' | 'watch-extension-ready'
   status: 'ok' | 'skip' | 'fail'
   summary: string
 }
@@ -45,16 +35,11 @@ export interface OnboardingOptions {
   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
 }
 
@@ -75,17 +60,6 @@ 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 扩展落位' }
@@ -106,162 +80,46 @@ function ensureExtensionFiles(source: string, target: string, dryRun: boolean):
   }
 }
 
-/** 打开 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 终端面板已打印' }
+/** 静态预检:落位目录可见 + manifest.key 存在(扩展 ID 稳定)+ 源未新于 dest */
+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 precheck' }
+  if (!existsSync(extensionDir) || !existsSync(join(extensionDir, 'manifest.json'))) {
+    return { step: 'watch-extension-ready', status: 'fail', summary: `落位缺失 manifest.json:${extensionDir}` }
   }
-  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 引导面板' }
+    const srcStat = statSync(sourceDir)
+    const dstStat = statSync(extensionDir)
+    if (srcStat.mtimeMs > dstStat.mtimeMs) {
+      return { step: 'watch-extension-ready', status: 'fail', summary: `扩展文件可能过期(源比落位新);重跑 npx gotry setup` }
     }
-    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 引导面板' }
+    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 不能稳定' }
     }
-    // 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: 'fail', summary: `静态预检失败: ${e instanceof Error ? e.message.slice(0, 120) : String(e)}` }
   }
   return { step: 'watch-extension-ready', status: 'ok', summary: '扩展文件就绪(manifest.key 校验通过,后台轮询就绪态由 health-watch 接管)' }
 }
 
 /**
- * 主入口:wizard 编排 5 步闭环(ensure→open→clipboard→panel→watch-precheck)。
- * 真实 health-watch 由 cli runner 在面板按下「我装好了」后启,本函数只做静态预检。
+ * 主入口(2 步):①扩展落位 ②watch precheck 静态预检。
+ * 真 health-watch 由 health-watch.ts 单独负责,不并入 wizard。
  */
 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 }
+  return { ok, steps, extensionDir }
 }
 
-/** stdout 人话化打印(默认终端面板形态);测试可禁用 */
+/** stdout 人话化打印(给 bootstrap 子进程单行 JSON 输出之外的兜底形态) */
 export function printWizardResult(result: OnboardingResult, destination: NodeJS.WritableStream = process.stdout): void {
   const tag = (s: OnboardingStep): string => {
     if (s.status === 'ok') return '✅'
@@ -271,10 +129,10 @@ export function printWizardResult(result: OnboardingResult, destination: NodeJS.
   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`)
+  destination.write(`extensionDir=${result.extensionDir}; overall=${result.ok ? 'ok' : 'has-failures'}\n`)
 }
 
-/** 留作 onboard final summary 的只读探针(便于 cli 输出「已就绪 / 待装」) */
+/** 公开诊断探针(bootstrap 报告用) */
 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)