@danceiny/gotry 0.2.0-rc.30 → 0.2.0-rc.31

package/README.md

@@ -153,7 +153,7 @@ Trust is structural, not promised:
 ## Project Status and Roadmap
 Current boundary: deterministic planning and evidence-bound read capabilities are available; booking and real-user acceptance remain outside the shipped claim. See the [architecture](docs/architecture.md) and [roadmap](docs/roadmap.md).
 
-**v0.2.0-rc.29** on npm (`latest`). Pre-1.0: the core loop works end to end; evaluation is still at deterministic contracts and validators, with no external scores or uplift claims. External W2A events are contract-only and inert; no real sensor bridge or consumer is active yet.
+**v0.2.0-rc.30** on npm (`latest`). Pre-1.0: the core loop works end to end; evaluation is still at deterministic contracts and validators, with no external scores or uplift claims. External W2A events are contract-only and inert; no real sensor bridge or consumer is active yet.
 
 **Working today**
 
@@ -209,7 +209,7 @@ Documents ship as bilingual pairs (`x.md` English + `x.zh-CN.md` 中文); diverg
 
 **Built with**: DeepSeek Harness 0.2.0-rc.2 (root-pinned) · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 · OpenFlights · TypeScript
 
-**Version baseline: `v0.2.0-rc.29` (npm `latest`).** Verification gates: `scripts/run-all-tests.sh`; release flow: `scripts/publish-npm.sh`.
+**Version baseline: `v0.2.0-rc.30` (npm `latest`).** Verification gates: `scripts/run-all-tests.sh`; release flow: `scripts/publish-npm.sh`.
 
 <a href="https://www.star-history.com/?repos=danceiny%2Fgotry&type=date&legend=top-left">
  <picture>

package/README.zh-CN.md

@@ -155,7 +155,7 @@ npx @danceiny/gotry "我想从深圳休整两天,预算 3000"   # headless 一
 ## 状态与路线图
 当前边界：确定性规划与有证据边界的只读能力已经可用；预订与真实用户验收仍不属于当前交付声明。见[架构权威文档](docs/architecture.zh-CN.md)与[路线图](docs/roadmap.zh-CN.md)。
 
-npm `latest`：**v0.2.0-rc.29**。未到 1.0：核心链路已端到端可用；评测仍停留在确定性合同与校验器阶段，无外部分数、无 uplift 声明。外部 W2A 事件仍是合同层、默认 inert；尚无真实 sensor 桥或 consumer 激活。
+npm `latest`：**v0.2.0-rc.30**。未到 1.0：核心链路已端到端可用；评测仍停留在确定性合同与校验器阶段，无外部分数、无 uplift 声明。外部 W2A 事件仍是合同层、默认 inert；尚无真实 sensor 桥或 consumer 激活。
 
 **今天可用**
 
@@ -211,7 +211,7 @@ AI agent：[`AGENTS.md`](AGENTS.zh-CN.md) 是绑定契约——入场先清扫
 
 **Built with**: DeepSeek Harness 0.2.0-rc.2 (root-pinned) · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 · OpenFlights · TypeScript
 
-**版本基线：`v0.2.0-rc.29`（npm `latest`）。** 验证闸：`scripts/run-all-tests.sh`；发布流程：`scripts/publish-npm.sh`。
+**版本基线：`v0.2.0-rc.30`（npm `latest`）。** 验证闸：`scripts/run-all-tests.sh`；发布流程：`scripts/publish-npm.sh`。
 
 <a href="https://www.star-history.com/?repos=danceiny%2Fgotry&type=date&legend=top-left">
  <picture>

package/bin/gotry-bootstrap.js

@@ -53,6 +53,7 @@
  * 自渲。wizard 子命令退化为「离线健康探活等待」,只输出 stdout,不挡用户。
  */
 
+import { verifyFlyaiCandidate } from './gotry-flyai-verification.js'
 import { spawn } from 'node:child_process'
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
@@ -60,6 +61,7 @@ import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
 import { createHash } from 'node:crypto'
+import { checkExtensionStatus } from './gotry-extension-status.js'
 
 // ── FlyAI 凭据面(纯 JS 内联;与 ts/capabilities/flyai-config.ts 成对维护,
 // 口径以官方 @fly-ai/flyai-cli 1.0.16 解包事实为准。bootstrap 由 inner 以
@@ -267,7 +269,7 @@ async function runSetupFlyai() {
       say('  验证: 未配置——可直接匿名试用(共享额度易达限),或粘贴正式 key 验证后保存')
     }
     if (extra) say(extra)
-    say('  凭据修改仅本机命令可达: `gotry setup flyai`(隐藏输入)/ `--stdin` / `--clear`;模型工具不能传 key')
+    say('  本机配置：`npx @danceiny/gotry setup flyai`（隐藏输入）；`--status` 查看；`--clear` 清除；模型工具不能传 key')
   }
 
   if (STATUS) {
@@ -315,8 +317,10 @@ async function runSetupFlyai() {
       // 非 TTY 且未显式 --stdin:仍接受管道输入,但不进入交互隐藏模式。
     }
   } else {
-    say('[gotry-setup] FlyAI API key 设置(输入隐藏,不回显;粘贴后回车)')
-    say('  打开 https://flyai.open.fliggy.com/console，登录后复制 API Key。直接回车取消。')
+    say('[gotry-setup] FlyAI 配置向导（无需设置环境变量或手工编辑文件）')
+    say('  1. 打开 https://flyai.open.fliggy.com/console，登录后复制 API Key。')
+    say('  2. 在下面粘贴并回车（输入隐藏，不回显）；直接回车取消。请勿把 key 发到聊天里。')
+    say('  3. 自动做只读验证，通过后保存到本机；失败保留原配置。')
     candidate = await hiddenInput('  key: ')
   }
   candidate = (candidate ?? '').trim()
@@ -336,7 +340,7 @@ async function runSetupFlyai() {
   if (verify.verdict !== 'hit') {
     say(`[gotry-setup] ✗ 验证未通过(${verify.verdict}):${verify.error ?? ''}`)
     say('  配置未改动(失败不覆盖原有效设置)。核对 key 后重试,或 `--clear` 回退匿名。')
-    return 1
+    return verify.exitCode ?? 1
   }
 
   const before = readFlyaiConfigObject()
@@ -393,7 +397,6 @@ async function runSetupFlyai() {
 /** TTY 隐藏输入:raw mode,不回显;Enter 结束;Ctrl+C/Ctrl+D 取消 */
 function hiddenInput(prompt) {
   return new Promise((resolve) => {
-    process.stdout.write(prompt)
     let buf = ''
     const stdin = process.stdin
     stdin.setRawMode(true)
@@ -433,6 +436,9 @@ function hiddenInput(prompt) {
       }
     }
     stdin.on('data', onData)
+    // Disable terminal echo before advertising readiness: a fast paste can
+    // reach the PTY as soon as the prompt is written, even within this tick.
+    process.stdout.write(prompt)
   })
 }
 
@@ -441,73 +447,26 @@ function hiddenInput(prompt) {
  * 子进程 env scrub FLYAI_API_KEY/DEBUG_FLYAI_API_KEY 后注入候选。
  * 返回 {verdict,error}。
  */
-function verifyCandidateKeyInline(candidate) {
-  const GOTRY_FLYAI_CLI = process.env.GOTRY_FLYAI_CLI_BIN ?? ''
-  const cliBin = GOTRY_FLYAI_CLI || 'npx'
-  const prefix = GOTRY_FLYAI_CLI ? [] : ['-y', '@fly-ai/flyai-cli@1.0.16']
-  const env = { ...process.env }
-  delete env.FLYAI_API_KEY
-  delete env.DEBUG_FLYAI_API_KEY
-  env.FLYAI_API_KEY = candidate
-  const date = new Date(Date.now() + 7 * 86_400_000).toISOString().slice(0, 10)
-  const args = [...prefix, 'search-flight', '--origin', '上海', '--destination', '丽江', '--dep-date', date]
-  const configuredTimeout = Number(process.env.GOTRY_FLYAI_VERIFY_TIMEOUT_MS ?? 20_000)
-  const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? Math.min(configuredTimeout, 60_000) : 20_000
-  return new Promise((resolve) => {
-    let stdout = ''
-    let stderr = ''
-    let timedOut = false
-    let settled = false
-    const child = spawn(cliBin, args, {
-      env, stdio: ['ignore', 'pipe', 'pipe'],
-      detached: process.platform !== 'win32',
-    })
-    const finish = (v) => {
-      if (settled) return
-      settled = true
-      resolve(v)
-    }
-    const killGroup = (signal) => {
-      if (process.platform !== 'win32' && child.pid) {
-        try { process.kill(-child.pid, signal); return } catch { /* fall through */ }
-      }
-      try { child.kill(signal) } catch { /* ignore */ }
+async function verifyCandidateKeyInline(candidate) {
+  const controller = new AbortController()
+  let interrupted
+  const listeners = new Map()
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    const listener = () => {
+      interrupted ??= signal
+      controller.abort()
     }
-    const timer = setTimeout(() => { timedOut = true; killGroup('SIGKILL') }, timeoutMs)
-    child.stdout?.on('data', d => { stdout += d.toString() })
-    child.stderr?.on('data', d => { stderr += d.toString() })
-    child.on('error', (e) => { clearTimeout(timer); finish({ verdict: 'error', error: e.message }) })
-    child.on('close', (code) => {
-      clearTimeout(timer)
-      const combined = `${stderr}\n${stdout}`
-      if (timedOut) return finish({ verdict: 'timeout', error: `验证调用超时 ${timeoutMs}ms` })
-      if (/Invalid API key|HTTP\s*401|\b401\b/.test(combined)) {
-        return finish({ verdict: 'auth-error', error: '401 Invalid API key' })
-      }
-      if (/HTTP\s*403|\b403\b/.test(combined)) {
-        return finish({ verdict: 'forbidden', error: 'HTTP 403：无访问权限，请核对控制台权限。' })
-      }
-      if (/Trial limit reached/.test(combined)) {
-        return finish({ verdict: 'needs-setup', error: 'Trial limit reached(候选 key 未被识别为正式 key?)' })
-      }
-      if (/HTTP\s*429|\b429\b/.test(combined)) {
-        return finish({ verdict: 'rate-limited', error: '普通限流,稍后重试' })
-      }
-      if (code !== 0) {
-        // Upstream diagnostics can echo credentials or a private debug URL.
-        return finish({ verdict: 'error', error: `验证进程失败（exit ${code}）；请检查网络与服务状态。` })
-      }
-      try {
-        const envelope = JSON.parse(stdout)
-        if (Array.isArray(envelope?.data?.itemList)) {
-          return finish({ verdict: 'hit', count: envelope.data.itemList.length })
-        }
-        return finish({ verdict: 'error', error: '响应缺 data.itemList' })
-      } catch {
-        return finish({ verdict: 'error', error: '响应不是合法 JSON' })
-      }
-    })
-  })
+    listeners.set(signal, listener)
+    process.on(signal, listener)
+  }
+  try {
+    const result = await verifyFlyaiCandidate(candidate, { signal: controller.signal })
+    return interrupted
+      ? { ...result, verdict: 'cancelled', exitCode: 128 + (interrupted === 'SIGINT' ? 2 : 15) }
+      : result
+  } finally {
+    for (const [signal, listener] of listeners) process.off(signal, listener)
+  }
 }
 
 
@@ -889,9 +848,8 @@ async function doctorChecks() {
   const nodeFine = maj > 22 || (maj === 22 && min >= 15)
   items.push({ label: 'Node 运行时', ok: nodeFine, level: nodeFine ? 'ok' : 'missing', detail: `Node ${nv}(需 ≥22.15)`, fix: nodeFine ? undefined : '升级 Node.js 至 22.15+(https://nodejs.org)' })
   // 扩展
-  const extManifest = join(homedir(), '.gotry', 'extension', 'manifest.json')
-  const extOk = existsSync(extManifest)
-  items.push({ label: 'Stai Travel Bridge 扩展', ok: extOk, level: extOk ? 'ok' : 'missing', detail: extOk ? `已就位(${extManifest})` : '未安装——影响面:gotry_session_search / gotry_session_login(账号会话通道)不可用;携程机票/酒店实时检索、12306 余票、Dida 实时报价都依赖此通道。其它工具(机票 FlyAI、酒店 hbcli、地图、天气等)不受影响', fix: extOk ? undefined : '在 Chrome 应用商店一键安装(自动更新): https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd' })
+  const extension = await checkExtensionStatus()
+  items.push({ label: 'Stai Travel Bridge 扩展', ok: extension.status === 'ok', level: extension.status, detail: extension.detail, fix: extension.fix })
   // agent-reach(.venv 装在包内)
   const venvPython = join(repoRoot, '.venv/bin/python')
   const reachBin = join(repoRoot, '.venv/bin/agent-reach')
@@ -931,7 +889,7 @@ async function doctorChecks() {
   let flyaiFix
   if (!flyaiResolved.key) {
     flyaiDetail = '未配置 key——匿名试用中(共享额度易达限;达限报 Trial limit reached)。影响面:共享池额度小,频繁会话易触顶;达限本会话内 gotry_flyai_search(机票/酒店/票务/AI/万豪 8 类)失败,改走 gotry_session_search 账号会话通道。'
-    flyaiFix = '本机运行 `gotry setup flyai`(隐藏输入,先验证后保存 FLYAI_API_KEY);打开 https://flyai.open.fliggy.com/console，登录后复制 API Key'
+    flyaiFix = 'Web 打开「插件 → GoTry → FlyAI」验证并保存；或运行 `npx @danceiny/gotry setup flyai`：① 打开 https://flyai.open.fliggy.com/console 复制 API Key；② 在终端隐藏粘贴；③ 验证后保存。也可运行 `npx @danceiny/gotry doctor --fix` 按提示配置'
   } else {
     const keySha = sha256Inline(flyaiResolved.key)
     const receiptMatches = flyaiReceipt
@@ -946,16 +904,16 @@ async function doctorChecks() {
       flyaiDetail = `已验证 ${flyaiReceipt.at}(${sourceNote};endpoint ${displayEndpointInline(flyaiEndpoint.url)}${flyaiEndpoint.debug ? '(DEBUG)' : ''})`
     } else if (flyaiReceipt && flyaiReceipt.keySha256 === keySha && flyaiReceipt.verdict !== 'verified') {
       flyaiDetail = `已配置未通过验证(${flyaiReceipt.verdict}@ ${flyaiReceipt.at};${sourceNote};endpoint ${displayEndpointInline(flyaiEndpoint.url)}${flyaiEndpoint.debug ? '(DEBUG)' : ''})——非空不等于鉴权通过`
-      flyaiFix = '本机运行 `gotry setup flyai` 重新验证;`gotry setup flyai --clear` 回退匿名'
+      flyaiFix = 'Web 打开「插件 → GoTry → FlyAI」重新验证；或运行 `npx @danceiny/gotry setup flyai`；`npx @danceiny/gotry setup flyai --clear` 回退匿名'
     } else {
       flyaiDetail = `已配置,未验证(${sourceNote};endpoint ${displayEndpointInline(flyaiEndpoint.url)}${flyaiEndpoint.debug ? '(DEBUG)' : ''})`
-      flyaiFix = '本机运行 `gotry setup flyai`(候选 key scrub-env 验证后保存)'
+      flyaiFix = 'Web 打开「插件 → GoTry → FlyAI」验证并保存；或运行 `npx @danceiny/gotry setup flyai`，按提示隐藏粘贴 API Key'
     }
   }
   items.push({ label: 'FlyAI(飞猪官方检索:机/火/酒/景/关键词/AI/万豪 8 类)', ok: flyaiLevel === 'ok', level: flyaiLevel, detail: flyaiDetail, fix: flyaiFix })
   // sidebar(状态面与 setupSidebar 的落盘复核同一口径)
   const sbOk = sidebarInstalled()
-  items.push({ label: 'dsh-better-sidebar(侧栏工作台)', ok: sbOk, level: sbOk ? 'ok' : 'missing', detail: sbOk ? '已安装——web UI 右侧工作台可预览产物与 doctor 报告(gotry-state/doctor-report.md)' : '未安装——dsh web 无右侧工作台,产物与 doctor 报告只能在对话里看(gotry_artifacts_list)', fix: sbOk ? undefined : 'npx @danceiny/gotry doctor --fix' })
+  items.push({ label: 'dsh-better-sidebar(侧栏工作台)', ok: sbOk, level: sbOk ? 'ok' : 'missing', detail: sbOk ? '已安装——web UI 右侧工作台可预览产物与 doctor 报告(gotry-state/doctor-report.md)' : '未安装此增强组件——Web 自带 GoTry 产物页与原生预览；可选补装以增强文件浏览', fix: sbOk ? undefined : 'npx @danceiny/gotry doctor --fix' })
   // dsh-calendar(setup 状态面;默认不挂载=ok 是合法态,opt-in 未配置才 degraded)
   const calState = readCalendarState()
   const calOn = calState?.enabled === true
@@ -1018,8 +976,8 @@ const fixCell = (fix) => (!fix ? '—' : /^(npx|hbcli|curl|pip|python|\$)/.test(
 function startupDoctorLine(items) {
   const broken = (items ?? []).filter((i) => i.level && i.level !== 'ok')
   if (broken.length === 0) return null
-  const human = (lv) => (lv === 'missing' ? '缺' : '半可用')
-  return `[gotry] doctor: ${broken.length} 项待处理(${broken.map((i) => `${i.label}=${human(i.level)}`).join('、')})——对话里让助手调 gotry_doctor 看详情与指引,或终端跑 npx @danceiny/gotry doctor`
+  const human = i => i.level === 'missing' ? '缺' : i.label.startsWith('Stai Travel Bridge') ? '待确认' : '半可用'
+  return `[gotry] doctor: ${broken.length} 项待处理(${broken.map((i) => `${i.label}=${human(i)}`).join('、')})——对话里让助手调 gotry_doctor 看详情与指引,或终端跑 npx @danceiny/gotry doctor`
 }
 
 /** 体检报告 markdown(与 ts/capabilities/doctor.ts renderDoctorReportMd 同形) */
@@ -1073,11 +1031,26 @@ async function runDoctor() {
       if (process.env.GOTRY_SETUP_SIDEBAR !== '0') results.push(await setupSidebar())
       const failedFix = results.filter((r) => !r.ok).length
       say(failedFix === 0 ? '[gotry-doctor] 补装完成;下面是补装后复检。' : `[gotry-doctor] ${failedFix} 项补装失败——见上方安装器输出;可重跑 npx @danceiny/gotry doctor --fix`)
-      items = await doctorChecks()
-      for (const i of items) {
-        say(`  ${doctorIcon[i.level]} ${i.label}:${i.detail}`)
+    }
+    // Explicit --fix may offer local credential setup, but never consumes a
+    // secret from CI, a pipe, startup diagnostics or the model tool surface.
+    if (items.some(i => i.label.startsWith('FlyAI(') && i.level !== 'ok')
+        && process.platform !== 'win32' && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI) {
+      process.stdout.write('[gotry-doctor] 现在配置 FlyAI？控制台取 key → 隐藏粘贴 → 验证后保存（y/N）：')
+      const answer = await readOneLine(process.stdin)
+      if (/^y(?:es)?$/i.test(answer.trim())) {
+        const setupCode = await runSetupFlyai()
+        if (setupCode === 130 || setupCode === 143) return setupCode
+        if (setupCode !== 0) say('[gotry-doctor] FlyAI 配置未完成；可重跑 `npx @danceiny/gotry setup flyai`。')
+      } else {
+        say('[gotry-doctor] 已跳过 FlyAI 配置；稍后运行 `npx @danceiny/gotry setup flyai`。')
       }
     }
+    items = await doctorChecks()
+    for (const i of items) {
+      say(`  ${doctorIcon[i.level]} ${i.label}:${i.detail}`)
+      if (i.level !== 'ok' && i.fix) say(`      ↳ 修复: ${i.fix}`)
+    }
   }
   // 报告落盘(侧栏工作台预览面;写失败不挡体检结论)
   try {

package/bin/gotry-extension-status.d.ts

@@ -0,0 +1,12 @@
+export interface ExtensionStatusOptions {
+  homeDir?: string
+  platform?: NodeJS.Platform
+  env?: NodeJS.ProcessEnv
+  ports?: readonly number[]
+  timeoutMs?: number
+}
+export function checkExtensionStatus(opts?: ExtensionStatusOptions): Promise<{
+  status: 'ok' | 'degraded'
+  detail: string
+  fix?: string
+}>

package/bin/gotry-extension-status.js

@@ -0,0 +1,113 @@
+// Shared by the npm CLI and gotry_doctor. Disk presence proves installation,
+// while only a fresh, trusted-origin heartbeat on the existing bridge proves
+// connection. This diagnostic never starts a bridge or sends a heartbeat.
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { get } from 'node:http'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const IDS = ['oeajpiccmonococjcegddlooeeohlbgd', 'olpgkofjhhiiiahdkkbcninhjmegghfe']
+const PORTS = [8791, 8792, 8793, 8794, 8795]
+const STORE_URL = `https://chromewebstore.google.com/detail/gotry-session-bridge/${IDS[0]}`
+
+function json(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')) } catch { return null }
+}
+function directories(path) {
+  try { return readdirSync(path, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name) } catch { return [] }
+}
+
+function browserRoots(home, platform, env) {
+  if (platform === 'darwin') {
+    const base = join(home, 'Library', 'Application Support')
+    return ['Google/Chrome', 'Google/Chrome Beta', 'Google/Chrome Canary', 'Chromium', 'Microsoft Edge', 'BraveSoftware/Brave-Browser'].map(path => join(base, path))
+  }
+  if (platform === 'win32') {
+    const base = env.LOCALAPPDATA || join(home, 'AppData', 'Local')
+    return ['Google/Chrome/User Data', 'Google/Chrome Beta/User Data', 'Google/Chrome SxS/User Data', 'Chromium/User Data', 'Microsoft/Edge/User Data', 'BraveSoftware/Brave-Browser/User Data'].map(path => join(base, path))
+  }
+  const base = env.XDG_CONFIG_HOME || join(home, '.config')
+  return ['google-chrome', 'google-chrome-beta', 'google-chrome-unstable', 'chromium', 'microsoft-edge', 'BraveSoftware/Brave-Browser'].map(path => join(base, path))
+}
+
+function installedProfiles(home, platform, env) {
+  const found = []
+  for (const root of browserRoots(home, platform, env)) {
+    for (const name of directories(root)) {
+      const profile = join(root, name)
+      const matches = IDS.filter(id => directories(join(profile, 'Extensions', id)).some(version => {
+        const manifest = json(join(profile, 'Extensions', id, version, 'manifest.json'))
+        return manifest?.manifest_version === 3 && typeof manifest.version === 'string'
+      }))
+      if (!matches.length) continue
+      const secure = json(join(profile, 'Secure Preferences'))?.extensions?.settings
+      const preferences = json(join(profile, 'Preferences'))?.extensions?.settings
+      for (const id of matches) {
+        const settings = secure?.[id] ?? preferences?.[id]
+        // Uninstall/update may leave version directories behind. Require the
+        // browser's current registration as well as its on-disk manifest.
+        if (!settings || typeof settings !== 'object' || Array.isArray(settings)) continue
+        const disabled = (typeof settings?.state === 'number' && settings.state !== 1)
+          || (Array.isArray(settings?.disable_reasons) && settings.disable_reasons.length > 0)
+        found.push({ profile, disabled })
+      }
+    }
+  }
+  return found
+}
+
+function bridgeStatus(port, timeoutMs) {
+  return new Promise(resolve => {
+    let done = false
+    const finish = value => { if (!done) { done = true; clearTimeout(timer); resolve(value) } }
+    const req = get({ hostname: '127.0.0.1', port, path: '/status' }, res => {
+      let body = ''
+      res.setEncoding('utf8')
+      res.on('data', chunk => {
+        body += chunk
+        if (body.length > 16_384) { finish(null); req.destroy() }
+      })
+      res.on('error', () => finish(null))
+      res.on('end', () => {
+        try {
+          const status = JSON.parse(body)
+          if (res.statusCode !== 200 || status.ok !== true || status.protocol !== 'session-bridge.v1'
+              || typeof status.extensionConnected !== 'boolean') { finish(null); return }
+          finish({ port, connected: status.extensionConnected === true
+            && Number.isFinite(status.lastSeenMsAgo) && status.lastSeenMsAgo >= 0 && status.lastSeenMsAgo < 45_000 })
+        } catch { finish(null) }
+      })
+    })
+    const timer = setTimeout(() => { finish(null); req.destroy() }, timeoutMs)
+    req.on('error', () => finish(null))
+  })
+}
+
+export async function checkExtensionStatus(opts = {}) {
+  const home = opts.homeDir ?? homedir()
+  const platform = opts.platform ?? process.platform
+  const env = opts.env ?? process.env
+  const bridges = await Promise.all((opts.ports ?? PORTS).map(port => bridgeStatus(port, opts.timeoutMs ?? 400)))
+  const connected = bridges.find(status => status?.connected)
+  if (connected) return {
+    status: 'ok', detail: `已连接（本机桥端口 ${connected.port}，近期扩展心跳已确认）`,
+  }
+  const profiles = installedProfiles(home, platform, env)
+  if (profiles.length) {
+    const enabled = profiles.find(profile => !profile.disabled)
+    return {
+      status: 'degraded',
+      detail: enabled ? `已安装（浏览器配置：${enabled.profile}）；当前连接未确认，离线安装检查不代表会话检索已就绪`
+        : `已安装，但已停用（浏览器配置：${profiles[0].profile}）；当前连接未确认`,
+      fix: '打开安装扩展的浏览器，在 chrome://extensions 启用 Stai Travel Bridge；启动 `npx @danceiny/gotry web`，在对话中发起账号会话检索并按提示授权以启动连接；保持会话运行时重跑 doctor，检索以 gotry_session_search 的结果为准',
+    }
+  }
+  if (existsSync(join(home, '.gotry', 'extension', 'manifest.json'))) return {
+    status: 'degraded', detail: '本地扩展文件已就位，浏览器加载及当前连接未确认',
+    fix: '推荐从商店安装：' + STORE_URL + '；或在 chrome://extensions 加载 ~/.gotry/extension；启动 `npx @danceiny/gotry web`，在对话中发起账号会话检索并按提示授权以启动连接',
+  }
+  return {
+    status: 'degraded', detail: '未检测到浏览器安装记录，当前连接未确认（浏览器可能使用其他配置目录）；无法仅凭文件判断安装状态。影响面：账号会话检索需扩展在线，机票 FlyAI、酒店 hbcli、地图、天气等其它工具不受影响',
+    fix: '已安装时：打开对应浏览器，在 chrome://extensions 确认已启用；启动 `npx @danceiny/gotry web`，在对话中发起账号会话检索并按提示授权以启动连接；保持会话运行时复检。首次安装：' + STORE_URL,
+  }
+}

package/bin/gotry-flyai-verification.d.ts

@@ -0,0 +1,9 @@
+export interface FlyaiCandidateVerification {
+  verdict: 'hit' | 'auth-error' | 'forbidden' | 'needs-setup' | 'rate-limited' | 'timeout' | 'cancelled' | 'error'
+  count?: number
+  error?: string
+}
+export declare function verifyFlyaiCandidate(candidate: string, options?: {
+  env?: NodeJS.ProcessEnv
+  signal?: AbortSignal
+}): Promise<FlyaiCandidateVerification>

package/bin/gotry-flyai-verification.js

@@ -0,0 +1,63 @@
+/** Shared, bounded, read-only candidate verification for terminal and native Web setup. */
+import { spawnOwnedChild, terminateOwnedChild } from './gotry-process-liveness.js'
+
+export async function verifyFlyaiCandidate(candidate, options = {}) {
+  const configured = options.env ?? process.env
+  if (options.signal?.aborted) return { verdict: 'cancelled', error: '验证已取消。' }
+  const env = { ...configured, FLYAI_API_KEY: candidate }
+  delete env.DEBUG_FLYAI_API_KEY
+  const command = configured.GOTRY_FLYAI_CLI_BIN || 'npx'
+  const prefix = configured.GOTRY_FLYAI_CLI_BIN ? [] : ['-y', '@fly-ai/flyai-cli@1.0.16']
+  const date = new Date(Date.now() + 7 * 86_400_000).toISOString().slice(0, 10)
+  const args = [...prefix, 'search-flight', '--origin', '上海', '--destination', '丽江', '--dep-date', date]
+  const limit = Number(configured.GOTRY_FLYAI_VERIFY_TIMEOUT_MS ?? 20_000)
+  const timeoutMs = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 60_000) : 20_000
+  const owned = spawnOwnedChild(command, args, { env, stdio: ['ignore', 'pipe', 'pipe'] })
+  let stopReason, timer, stdout = '', stderr = '', bytes = 0
+  const stop = (reason) => {
+    stopReason ??= reason
+    void terminateOwnedChild({ ...owned, signal: 'SIGKILL', termGraceMs: 100, killWaitMs: 1000 })
+  }
+  const abort = () => stop('cancelled')
+  try {
+    const result = await new Promise(resolve => {
+      let settled = false
+      const finish = value => { if (!settled) { settled = true; resolve(value) } }
+      timer = setTimeout(() => stop('timeout'), timeoutMs)
+      options.signal?.addEventListener('abort', abort, { once: true })
+      if (options.signal?.aborted) abort()
+      owned.child.stdout?.on('data', chunk => {
+        bytes += chunk.length
+        if (bytes > 256 * 1024) return stop('output-limit')
+        stdout += chunk.toString()
+      })
+      owned.child.stderr?.on('data', chunk => {
+        bytes += chunk.length
+        if (bytes > 256 * 1024) return stop('output-limit')
+        stderr += chunk.toString()
+      })
+      owned.child.once('error', () => finish({ verdict: 'error', error: '无法启动验证进程。' }))
+      owned.child.once('close', code => {
+        if (stopReason) return finish({ verdict: stopReason === 'output-limit' ? 'error' : stopReason,
+          error: stopReason === 'cancelled' ? '验证已取消。' : stopReason === 'timeout' ? `验证调用超时 ${timeoutMs}ms。` : '验证响应过大。' })
+        const combined = `${stderr}\n${stdout}`
+        if (/Invalid API key|HTTP\s*401|\b401\b/.test(combined)) return finish({ verdict: 'auth-error', error: '401 Invalid API key' })
+        if (/HTTP\s*403|\b403\b/.test(combined)) return finish({ verdict: 'forbidden', error: 'HTTP 403：无访问权限，请核对控制台权限。' })
+        if (/Trial limit reached/.test(combined)) return finish({ verdict: 'needs-setup', error: '试用额度已用尽，请核对控制台 Key。' })
+        if (/HTTP\s*429|\b429\b/.test(combined)) return finish({ verdict: 'rate-limited', error: '普通限流，稍后重试。' })
+        if (code !== 0) return finish({ verdict: 'error', error: `验证进程失败（exit ${code}）；请检查网络与服务状态。` })
+        try {
+          const envelope = JSON.parse(stdout)
+          finish(Array.isArray(envelope?.data?.itemList)
+            ? { verdict: 'hit', count: envelope.data.itemList.length }
+            : { verdict: 'error', error: '响应缺 data.itemList。' })
+        } catch { finish({ verdict: 'error', error: '响应不是合法 JSON。' }) }
+      })
+    })
+    return result
+  } finally {
+    clearTimeout(timer)
+    options.signal?.removeEventListener('abort', abort)
+    await terminateOwnedChild({ ...owned, signal: 'SIGKILL', termGraceMs: 100, killWaitMs: 1000 })
+  }
+}

package/bin/gotry-inner.js

@@ -88,8 +88,9 @@ Usage:
     # 跳过该问: --no-onboarding 或 GOTRY_ONBOARDING_SKIP=1
   gotry setup                        # 扩展就位检查/指引(商店一键装)
   gotry setup calendar               # 可选日历(CalDAV 工作窗口)挂载开关:默认关;--off 关闭;--status 查看
+  gotry setup flyai                  # FlyAI 配置向导:控制台取 key → 隐藏粘贴 → 验证后保存;--status 查看;--clear 清除
   gotry doctor                       # 可选依赖体检:扩展/agent-reach/hbcli/flyai/sidebar 状态 + 补装指引
-  gotry doctor --fix                 # 体检 + 按报告补装(hbcli 官方脚本 / agent-reach pip / sidebar 插件)
+  gotry doctor --fix                 # 补装可选依赖;交互终端可选择接着配置 FlyAI
   gotry "一段完整任务..."            # headless 一问一答
   gotry help                         # this help
   gotry --version                    # 版本号(bug 报告必填项)