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

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.31** 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.31` (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.31**。未到 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.31`（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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * gotry 外部依赖自举(founder 2026-08-29 指令:安装 gotry 时按上游本身的方式装好外部依赖):
- *   hbcli(hotelbyte-cli)  → npm 优先(staicli@npmjs;Node ≥ 20),原生二进制 install.sh 兜底
+ *   hbcli(hotelbyte-cli)  → 官方版本钉扎的原生 install.sh(npm 发布暂落后)
  *   agent-reach            → 官方 pip 安装 git+ upstream(包内 .venv,与 z3-solver 同址原则)
  *   flyai                  → 无需安装(npx 每次自拉 @fly-ai/flyai-cli)
  *   dsh-better-sidebar     → dsh 宿主层插件市场组件(dshmarket.com #1 UI,18.9 万周装):
@@ -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,8 @@ 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'
+import { HBCLI_RELEASE_VERSION, HBCLI_INSTALL_CMD } from './gotry-hbcli-release.js'
 
 // ── FlyAI 凭据面(纯 JS 内联;与 ts/capabilities/flyai-config.ts 成对维护,
 // 口径以官方 @fly-ai/flyai-cli 1.0.16 解包事实为准。bootstrap 由 inner 以
@@ -162,24 +165,24 @@ function verifySecureModeInline(dir, file) {
 
 /**
  * 官方 CLI 首次运行可能先创建 ~/.flyai 为 0755(并写入 0600 device-id)。
- * 仅对当前用户拥有、且本身不是 symlink 的 .flyai 目录收紧权限；.gotry
- * 仍由 atomicWriteJsonInline 严格要求预先存在时就是 0700，不走此兼容路径。
+ * 仅对当前用户拥有、且本身不是 symlink 的目录收紧权限。
+ * 回执所在 .gotry 同样兼容 doctor/runtime 创建的既有 0755 目录。
  */
-function prepareFlyaiConfigDirInline() {
-  const dir = dirname(flyaiConfigFile())
+function preparePrivateDirInline(file = flyaiConfigFile()) {
+  const dir = dirname(file)
   try {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
     const entry = lstatSync(dir)
-    if (entry.isSymbolicLink()) return { ok: false, error: '.flyai 目录是符号链接,拒绝写入' }
-    if (!entry.isDirectory()) return { ok: false, error: '.flyai 路径不是目录,拒绝写入' }
+    if (entry.isSymbolicLink()) return { ok: false, error: '配置目录是符号链接,拒绝写入' }
+    if (!entry.isDirectory()) return { ok: false, error: '配置路径不是目录,拒绝写入' }
     if (typeof process.getuid === 'function' && entry.uid !== process.getuid()) {
-      return { ok: false, error: '.flyai 目录不属于当前用户,拒绝写入' }
+      return { ok: false, error: '配置目录不属于当前用户,拒绝写入' }
     }
     if ((entry.mode & 0o777) !== 0o700) chmodSync(dir, 0o700)
     const after = lstatSync(dir)
-    if (after.isSymbolicLink() || !after.isDirectory()) return { ok: false, error: '.flyai 目录状态发生变化,拒绝写入' }
-    if (typeof process.getuid === 'function' && after.uid !== process.getuid()) return { ok: false, error: '.flyai 目录所有者发生变化,拒绝写入' }
-    return verifySecureModeInline(dir, flyaiConfigFile())
+    if (after.isSymbolicLink() || !after.isDirectory()) return { ok: false, error: '配置目录状态发生变化,拒绝写入' }
+    if (typeof process.getuid === 'function' && after.uid !== process.getuid()) return { ok: false, error: '配置目录所有者发生变化,拒绝写入' }
+    return verifySecureModeInline(dir, file)
   } catch (e) {
     return { ok: false, error: e.message }
   }
@@ -267,7 +270,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) {
@@ -289,7 +292,7 @@ async function runSetupFlyai() {
       if (Object.keys(next).length === 0) {
         rmSync(flyaiConfigFile(), { force: true })
       } else {
-        const configDir = prepareFlyaiConfigDirInline()
+        const configDir = preparePrivateDirInline()
         if (!configDir.ok) { say(`[gotry-setup] 清除写入失败,旧配置保留:${configDir.error}`); return 1 }
         const w = atomicWriteJsonInline(flyaiConfigFile(), next)
         if (!w.ok) { say(`[gotry-setup] 清除写入失败,旧配置保留:${w.error}`); return 1 }
@@ -315,8 +318,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 +341,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()
@@ -345,7 +350,7 @@ async function runSetupFlyai() {
     return 1
   }
   const hadConfigFile = existsSync(flyaiConfigFile())
-  const configDir = prepareFlyaiConfigDirInline()
+  const configDir = preparePrivateDirInline()
   if (!configDir.ok) {
     say(`[gotry-setup] ✗ 配置目录不安全,旧配置保留:${configDir.error}`)
     return 1
@@ -376,7 +381,8 @@ async function runSetupFlyai() {
     endpointDebug: epAfter.debug,
     at: new Date().toISOString(),
   }
-  const receiptWrite = atomicWriteJsonInline(flyaiVerificationFile(), receipt)
+  const receiptDir = preparePrivateDirInline(flyaiVerificationFile())
+  const receiptWrite = receiptDir.ok ? atomicWriteJsonInline(flyaiVerificationFile(), receipt) : receiptDir
   if (!receiptWrite.ok) {
     const rollback = hadConfigFile
       ? atomicWriteJsonInline(flyaiConfigFile(), before.data)
@@ -393,7 +399,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 +438,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 +449,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)
+  }
 }
 
 
@@ -521,9 +482,6 @@ const WIZARD_DRY_RUN = process.argv.includes('--dry-run')
 const EXT_FROM_ARG = (process.argv.find((a) => a.startsWith('--extension-from=')) ?? '').split('=')[1]
 const EXTENSION_FROM = EXT_FROM_ARG === 'github' || EXT_FROM_ARG === 'bundled' ? EXT_FROM_ARG : process.env.GOTRY_EXTENSION_SOURCE === 'github' ? 'github' : 'bundled'
 
-// hbcli 安装通道:npm 优先(staicli@npmjs 双轨;显式 registry 防 bnpm 404),install.sh 兜底
-const HBCLI_NPM_INSTALL_CMD = 'npm install -g staicli --registry=https://registry.npmjs.org/'
-const HBCLI_INSTALL_CMD = HBCLI_NPM_INSTALL_CMD
 const REACH_INSTALL_URL = 'git+https://github.com/Panniantong/Agent-Reach.git'
 
 let activeInstallerChild = null
@@ -672,11 +630,8 @@ function classifyHbcliWhoami(out) {
 
 const say = (s) => console.log(s)
 
-/** hbcli 最低版本(可用 GOTRY_MIN_HBCLI_VERSION 覆盖)。
- * 0.0.3 修了 portal-ticket fallback bug(issue #142):低于该版本的 hbcli
- * 会把 literal "stored-ticket" 当 bearer 发到 hotel-be,让 trade.* /
- * search/checkAvail 等 @permission: openapi 端点全部 401。 */
-const MIN_HBCLI_VERSION = process.env.GOTRY_MIN_HBCLI_VERSION ?? '0.0.3'
+/** hbcli 最低版本(可用 GOTRY_MIN_HBCLI_VERSION 覆盖)，与工具层 doctor 共用发布基线。 */
+const MIN_HBCLI_VERSION = process.env.GOTRY_MIN_HBCLI_VERSION ?? HBCLI_RELEASE_VERSION
 
 function parseVersion(v) {
   const m = String(v || '').match(/(\d+)\.(\d+)\.(\d+)/)
@@ -704,38 +659,53 @@ async function hbcliVersion(bin) {
   })
 }
 
-async function setupHbcli() {
-  say(`[gotry-setup] hbcli(hotelbyte-cli,可选酒店实时源;需 ≥ v${MIN_HBCLI_VERSION},低于会踩 issue #142 的 401)`)
-  const candidates = ['hbcli', join(homedir(), '.local/bin/hbcli'), join(homedir(), '.staicli/current/hbcli')]
-  const present = candidates.some((p) => existsSync(p)) && (await probe(candidates[0], ['version']) || await probe(candidates[1], ['version']) || await probe(candidates[2], ['version']))
-  const credFile = join(homedir(), '.staicli', 'credentials.json')
-  if (present) {
-    const hit = candidates.find((p) => existsSync(p)) || 'hbcli'
-    const v = await hbcliVersion(hit)
-    if (v && !versionAtLeast(v, MIN_HBCLI_VERSION)) {
-      say(`  ✗ 版本过旧(v${v.join('.')} < v${MIN_HBCLI_VERSION})——@permission: openapi 端点(trade.* / search/checkAvail)会 401(issue #142)`)
-      say(`    升级: npm install -g staicli --registry=https://registry.npmjs.org/`)
-      return { ok: CHECK_ONLY ? true : false }
+async function setupHbcli(opts = {}) {
+  const home = opts.homeDir ?? homedir()
+  const staicliHome = opts.homeDir ? join(home, '.staicli') : process.env.STAICLI_HOME ?? join(home, '.staicli')
+  const checkOnly = opts.checkOnly ?? CHECK_ONLY
+  say(`[gotry-setup] hbcli(hotelbyte-cli,可选酒店实时源;需 ≥ v${MIN_HBCLI_VERSION})`)
+  const candidates = ['hbcli', join(home, '.local/bin/hbcli'), join(home, '.staicli/current/hbcli')]
+  const findInstalled = async () => {
+    for (const bin of candidates) {
+      const version = await hbcliVersion(bin)
+      if (version) return { bin, version }
     }
-    say(`  ✓ 已安装(v${v ? v.join('.') : '?'})`)
+    return null
+  }
+  const present = await findInstalled()
+  const credFile = join(staicliHome, 'credentials.json')
+  if (present && versionAtLeast(present.version, MIN_HBCLI_VERSION)) {
+    say(`  ✓ 已安装(v${present.version.join('.')})`)
     if (existsSync(credFile)) say('  ✓ 凭证已配置(自检: hbcli auth whoami)')
     else say('  ✗ 凭证未配置——酒店检索将用内置静态包(非实时),账号配置见下方指引')
-    if (CHECK_ONLY) say('  (--check-only 只报告,不安装)')
+    if (checkOnly) say('  (--check-only 只报告,不安装)')
     return { ok: true }
   }
-  if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
-  say(`  安装中(npm,staicli@npmjs): ${HBCLI_INSTALL_CMD}`)
-  const r = await run('bash', ['-c', HBCLI_INSTALL_CMD], { timeoutMs: 120_000 })
-  if (!r.ok) { say(`  ✗ 安装失败(${r.error})——不影响 gotry,酒店检索将用内置静态包;可稍后重试: npx @danceiny/gotry setup`); return { ok: false } }
-  const binDir = join(homedir(), '.local/bin')
-  if (!process.env.PATH.split(':').includes(binDir)) {
+  if (present) say(`  ✗ 版本过旧(v${present.version.join('.')} < v${MIN_HBCLI_VERSION})`)
+  else say('  ✗ 未安装或无法读取版本')
+  if (checkOnly) { say('  (--check-only 只报告,不安装)'); return { ok: true } }
+  say(`  ${present ? '升级' : '安装'}中(官方 staicli v${HBCLI_RELEASE_VERSION}): ${HBCLI_INSTALL_CMD}`)
+  const attemptInstall = opts.attemptInstall ?? ((command) => run('bash', ['-o', 'pipefail', '-c', command], {
+    timeoutMs: 120_000,
+    env: { ...process.env, HOME: home, STAICLI_HOME: staicliHome },
+  }))
+  const r = await attemptInstall(HBCLI_INSTALL_CMD)
+  if (!r.ok) { say(`  ✗ 安装失败(${r.error})——不影响 gotry,酒店检索将用内置静态包;可稍后重试: npx @danceiny/gotry doctor --fix`); return { ok: false, error: r.error } }
+  const installed = await findInstalled()
+  if (!installed || !versionAtLeast(installed.version, MIN_HBCLI_VERSION)) {
+    const error = `安装后当前候选路径仍未找到 hbcli ≥ v${MIN_HBCLI_VERSION}；检查 PATH 是否优先命中了旧版，以及 ${join(home, '.local/bin/hbcli')}`
+    say(`  ✗ ${error}`)
+    return { ok: false, error }
+  }
+  const binDir = join(home, '.local/bin')
+  if (!(process.env.PATH ?? '').split(':').includes(binDir)) {
     say(`  ⚠ ${binDir} 不在当前 PATH —— gotry 工具已内建候选路径回退,无需手动处理;其他程序可用: export PATH="${binDir}:$PATH"`)
   }
-  say('  ✓ 安装完成——账号配置(未配时酒店检索自动用静态包,非实时):')
-  say('    · 快速试用(官方沙箱演示账号): hbcli auth set-credentials --app-key hotelbyte_api_demo --app-secret hotelbyte_api_demo')
-  say('    · 正式接入: 向 HotelByte 申请专属 appKey/appSecret 后用同一命令替换')
-  say('    · 门户账号(权限更大,酒店搜索无必要): hbcli auth login --username <email>')
-  say('  自检: hbcli auth whoami(api_key.configured=true 即就位)')
+  say(`  ✓ 安装完成(v${installed.version.join('.')})——已有凭证保留；账号配置:`)
+  say('    · 打开 插件 → GoTry → HotelByte，申请沙箱账号并验证保存 App Key/App Secret')
+  say('    · 申请入口: https://hotelbyte.com/zh/guides/sandbox-verification')
+  say('    · CLI 配置: hbcli auth set-credentials --app-key <appKey> --app-secret <appSecret>')
+  say('  自检: hbcli auth whoami；实际酒店搜索仍需账号开通可用供应商')
   return { ok: true }
 }
 
@@ -889,16 +859,15 @@ 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')
   const reachOk = existsSync(reachBin)
   const reachLevel = reachOk ? 'ok' : existsSync(venvPython) ? 'degraded' : 'missing'
   items.push({ label: 'Agent Reach(网页/社媒读取)', ok: reachOk, level: reachLevel, detail: reachOk ? `已安装(${reachBin})` : reachLevel === 'degraded' ? '.venv 在但缺 agent-reach 包——gotry_agent_reach / gotry_web_search 读页会失败' : '未装配——gotry_agent_reach / gotry_web_search(读网页)/ gotry_video_subtitle / gotry_github_search 全部不可用', fix: reachOk ? undefined : 'npx @danceiny/gotry doctor --fix' })
-  // hbcli(裸名靠 PATH 探测;绝对路径 existsSync;版本 < MIN_HBCLI_VERSION 视为 missing,见 issue #142)
+  // hbcli(裸名靠 PATH 探测;绝对路径 existsSync;版本 < MIN_HBCLI_VERSION 需要升级)
   let hbBin = ''
   for (const p of ['hbcli', join(homedir(), '.local/bin/hbcli'), join(homedir(), '.staicli/current/hbcli')]) {
     if (p === 'hbcli') { if (await probe(p, ['version'])) { hbBin = 'hbcli(PATH)'; break } } else if (existsSync(p)) { hbBin = p; break }
@@ -906,7 +875,7 @@ async function doctorChecks() {
   if (hbBin) {
     const v = await hbcliVersion(hbBin)
     if (v && !versionAtLeast(v, MIN_HBCLI_VERSION)) {
-      items.push({ label: 'hbcli(酒店实时源)', ok: false, level: 'missing', detail: `版本过旧(v${v.join('.')} < v${MIN_HBCLI_VERSION})——trade.* / search/checkAvail 会 401(issue #142)`, fix: 'npm install -g staicli --registry=https://registry.npmjs.org/' })
+      items.push({ label: 'hbcli(酒店实时源)', ok: false, level: 'missing', detail: `版本过旧(v${v.join('.')} < v${MIN_HBCLI_VERSION})——请升级到支持当前认证与酒店配置的版本`, fix: HBCLI_INSTALL_CMD })
     } else {
       // 凭证按 whoami 的 JSON 三档判定,不再看退出码(#623:whoami 无凭证也退 0,旧判法恒报「凭证有效」)
       const cred = classifyHbcliWhoami(await probeStdout(hbBin === 'hbcli(PATH)' ? 'hbcli' : hbBin, ['--json', 'auth', 'whoami']))
@@ -915,7 +884,7 @@ async function doctorChecks() {
         detail: cred.ok
           ? `已安装且凭证有效(${hbBin}, v${v ? v.join('.') : '?'}${cred.customer ? ',customer 档在用(客户邮箱验证码登录)' : ''})`
           : '二进制在,但凭证未配置/失效——酒店检索将降级静态包(非实时)',
-        fix: cred.ok ? undefined : 'hbcli auth customer-send-code --email you@mail.com 收码后 hbcli auth customer-login --email you@mail.com --code <收件码>(客户邮箱验证码登录,新邮箱即注册,需 npm staicli ≥ 0.0.4);B 端租户注册走 hbcli auth register(先 auth send-code);或 hbcli auth set-credentials --app-key hotelbyte_api_demo --app-secret hotelbyte_api_demo(快速试用沙箱;正式 key 向 HotelByte 申请)',
+        fix: cred.ok ? undefined : 'hbcli auth customer-send-code --email you@mail.com 收码后 hbcli auth customer-login --email you@mail.com --code <收件码>(客户邮箱验证码登录,新邮箱即注册);B 端租户注册走 hbcli auth register(先 auth send-code);或在 插件 → GoTry → HotelByte 配置沙箱 App Key/App Secret',
       })
     }
   } else {
@@ -931,7 +900,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 +915,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 +987,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 +1042,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 {
@@ -1157,8 +1141,7 @@ function classifyDoctorGap(item, opts = {}) {
   const autoSupported = doctorFixAutoSupported(platform)
   if (label.startsWith('Agent Reach')) return installerEnabled('reach', env) && autoSupported ? 'auto' : 'unavailable'
   // hbcli:二进制缺失(missing)= auto(setupHbcli 装;win32 → unavailable,上游无 win 安装面);
-  // 凭证未配(degraded)= user-action(平台无关);旧版本(missing,安装器不自动升级)= auto 分桶
-  // 但安装会失败 → 结果兜底 unavailable,诚实不冒充。
+  // 凭证未配(degraded)= user-action(平台无关);旧版本(missing)= auto，同安装器升级后复检。
   if (label.startsWith('hbcli')) {
     if (item.level === 'degraded') return 'user-action'
     return installerEnabled('hbcli', env) && autoSupported ? 'auto' : 'unavailable'
@@ -1780,7 +1763,7 @@ if (process.argv[1] && process.argv[1].endsWith('gotry-bootstrap.js')) {
 }
 
 export {
-  setupSidebar, sidebarInstalled,
+  setupHbcli, setupSidebar, sidebarInstalled,
   classifyDoctorGap, buildOnboardingPlan, onboardingSkipReason,
   runOnboardingFix, promptOnboarding, renderClassifiedPlan, runOnboarding, orchestrateWebLaunch,
   doctorFixAutoSupported, platformAutoUnavailableReason, installerEnabled,

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