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

package/README.md

@@ -26,6 +26,8 @@ npx @danceiny/gotry web
 # → open http://127.0.0.1:3080 and chat: "I want three relaxing days in Dali"
 ```
 
+> **Switching models / providers?** The price table (`ts/data/llm-price-table.json`, schema `gotry_llm_price_table_v2`) is the single source of truth for `gotry_m3_nightly_run_v1.cost_usd`. Adding a new model or switching relay = update this file via PR (ADR-11, peak-conservative upper bound only). Unknown models **fail-closed** — no guessed prices. Drift monitor: `npx tsx ts/scripts/price-drift-watch.ts` (offline baseline diff; `--fetch` for live official pages). Never auto-applies changes.
+
 | You want | Command |
 |---|---|
 | 🖥️ Conversational planner (recommended) | `npx @danceiny/gotry web` → chat UI on :3080 |
@@ -78,7 +80,7 @@ cp .env.example .env                              # ② set LLM_API_KEY
 
 ---
 
-## 🧰 20 tools
+## 🧰 21 tools
 
 | Group | Tool | What it does |
 |---|---|---|
@@ -95,6 +97,7 @@ cp .env.example .env                              # ② set LLM_API_KEY
 | | `gotry_wish_pool_add` / `gotry_wish_pool_list` | "next departure" wish pool + 0..1 conditional recall |
 | | `gotry_companion_save` · `gotry_trip_log` | companion profile / travel timeline |
 | **Artifacts** | `gotry_artifacts_list` / `gotry_artifacts_read` | Discover & view generated artifacts (async deliverables + working-dir markdown) as a line-numbered file view (read-only) |
+| **Factuality gate** | `gotry_fact_gate` | Pre-delivery gate for itinerary artifacts: every bookable claim (flight no./time/airport/price/policy) must trace to an exact-date tool result (hit AND miss recorded); unverifiable ⇒ blocked — never present as a verified plan |
 | **General external** | `gotry_web_search` · `gotry_video_subtitle` · `gotry_github_search` · `gotry_agent_reach` | web / subtitles / GitHub / all-channel external info (via Agent-Reach) |
 
 ---
@@ -108,7 +111,7 @@ The account session channel reads realtime hotel/flight data from **the user's o
 3. **Physically read-only.** A ReadGuard aborts all write requests at the network layer (ordering/payment is unreachable in transport); the agent never touches credentials or captchas — on a captcha it stops and hands control back.
 4. **Never hijacks your browser.** Retrieval/login always open their own dedicated tab; the login page is brought to front and stays with you; routine test runs never open browser windows.
 
-> One-time prerequisite: in your daily Chrome, open `chrome://inspect/#remote-debugging` and enable the switch (Chrome 144+). Without it the tools return `needs-attach` with instructions and spend nothing.
+> One-time prerequisite: install the bundled **GoTry Session Bridge** browser extension (MV3, ~30 seconds): run `npx gotry setup` to place it at `~/.gotry/extension`, then in Chrome open `chrome://extensions`, enable Developer mode and "Load unpacked" that folder. Zero Chrome system dialogs afterwards — the extension passively forwards the site's own search responses (read-only by construction; cookies are read by NAME only, values never leave the browser). Until installed, tools return `needs-extension` with instructions and spend nothing. (A `cdp` fallback via `chrome://inspect` remote debugging still exists for diagnostics: `GOTRY_SESSION_TRANSPORT=cdp` — note Chrome 144+ shows a permission box on every connection.)
 
 ---
 
@@ -141,7 +144,7 @@ Engine verdict:
 ```
 ┌──────────────────────────────────────────────────────────────┐
 │ L1  chat-as-interface; gates are in-message choice cards       │
-│ L2  orchestration  dsh runtime + GoTry plugin (ReAct); 20 tools│
+│ L2  orchestration  dsh runtime + GoTry plugin (ReAct); 21 tools│
 │ L3  domain  unified itinerary model + Z3 feasibility engine    │
 │ L4  data  static packs + hotelbyte-cli bridge + OpenFlights    │
 │ L5  governance  LoopX (objective / gates / evidence / quota)   │
@@ -150,7 +153,7 @@ Engine verdict:
 
 | Layer | Module | Role |
 |---|---|---|
-| L2 | `ts/src/index.ts` (dsh plugin) | 20 tools, time-anchor & memory-brief variables; execute isolation + consent gate + process guards |
+| L2 | `ts/src/index.ts` (dsh plugin) | 21 tools, time-anchor & memory-brief variables; execute isolation + consent gate + process guards |
 | L3 | `ts/src/unified.ts` · `py/gotry_feasibility/` | single solving entry (candidate enumeration + flight-chain Z3) |
 | L4 | `ts/capabilities/effect.ts` · `hbcli.ts` · `skeleton-check.ts` | effect interpreter (backoff retry / circuit breaker / mock interpreter, issue #16) + realtime inventory bridge + OpenFlights skeleton (three-valued semantics) |
 | L5 | loopx governance | objective / gates / evidence / quota |
@@ -166,6 +169,7 @@ Engine verdict:
 - **Z3 solving engine** — feasibility verdicts + door-to-door whole-cost; the historical concurrency race is fixed (§30 regression gate)
 - **Realtime retrieval** — flight/train/hotel (Fliggy official channel), destination/hotel catalogs, weather, live flight observation, route connectivity; realtime prices can overwrite solver prices (`GOTRY_REALTIME_PRICING=1`)
 - **Account session search** — Ctrip flights on your own logged-in Chrome; consent & privacy rules above (see 🔐 **Account session: consent & privacy**)
+- **One-time browser extension setup** — `npx gotry setup wizard` walks you through a 30-second install of GoTry Session Bridge (MV3, fixed extension ID, zero system dialogs per session). Background health-watch auto-plays your query once the extension is connected — no manual retry needed.
 - **Memory & reachability** — motivation profile / wish pool / companions / travel timeline; English output via `GOTRY_LOCALE=en`
 
 **Open limitations** (as of 2026-08-29, honest list):
@@ -189,7 +193,7 @@ The authoritative state lives in the docs, not this README: transactional state
 ./scripts/run-all-tests.sh
 ```
 
-One-shot full-stack green (pure TS, no Python needed): golden engines · dialogue replay · cross-process async work-orders · plugin smoke · hbcli · process guards · weather · flights · Anything · probePoi · agent-reach · dual-path stability · time-awareness eval · memory domain · **Z3 race (§30) · realtime pricing (§31) · i18n catalog (§32) · M3 cohort evidence contract (§33) · M4 value evidence contract (§34) · M3 nightly evidence producer contract (§35)**.
+One-shot full-stack green (pure TS, no Python needed): golden engines · dialogue replay · cross-process async work-orders · plugin smoke · hbcli · process guards · weather · flights · Anything · probePoi · agent-reach · dual-path stability · time-awareness eval · memory domain · **Z3 race (§30) · realtime pricing (§31) · i18n catalog (§32) · M3 cohort evidence contract (§33) · M4 value evidence contract (§34) · M3 nightly evidence producer contract (§35) · session transport extension bridge (§38) · onboarding UX wizard (§40) · bookable-fact gate (§39)**.
 
 ---
 
@@ -209,4 +213,4 @@ Standard open-source flow: branch off latest `main` (`feat/ · fix/ · docs/ ·
 
 **Built with**: DeepSeek Harness 0.1.2-alpha.1 (vendored) · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 (`.venv/`) · OpenFlights · TypeScript
 
-**Last verified against `v0.0.1-rc.15` (2026-08-29)** — full-stack regression green §1-§36 (release flow: `scripts/publish-npm.sh`).
+**Last verified against `v0.0.1-rc.16` (2026-08-30)** — full-stack regression green §1-§42 (release flow: `scripts/publish-npm.sh`).

package/README.zh-CN.md

@@ -21,6 +21,8 @@ npx @danceiny/gotry web
 # → 浏览器打开 http://127.0.0.1:3080,像聊天一样说「我想去大理三天」
 ```
 
+> **换模型 / 换中转?** 价表(`ts/data/llm-price-table.json`,schema `gotry_llm_price_table_v2`)是 `gotry_m3_nightly_run_v1.cost_usd` 唯一事实源(ADR-11)。新增模型或换中转=改本文件走 PR(peak 保守上界只高不低),未知模型 → **fail-closed 不猜价**。漂移监测:`npx tsx ts/scripts/price-drift-watch.ts`(默认离线对照 baseline 比对输出 PR-就绪 Markdown diff;`--fetch` 拉取官方页 + 首次写 fixture)。**永不自动 apply 价格**。
+
 | 你想要的 | 命令 |
 |---|---|
 | 🖥️ 对话规划(推荐) | `npx @danceiny/gotry web` → :3080 对话界面 |
@@ -98,7 +100,7 @@ GoTry: 收到。先把约束记下来——
 
 ---
 
-## 🧰 20 个工具 — Tools
+## 🧰 21 个工具 — Tools
 
 | 组 | 工具 | 干什么 |
 |---|---|---|
@@ -115,6 +117,7 @@ GoTry: 收到。先把约束记下来——
 | | `gotry_wish_pool_add` / `gotry_wish_pool_list` | 「下一次出发」愿望池 + 0..1 条件召回 |
 | | `gotry_companion_save` · `gotry_trip_log` | 同行人档案 / 旅行时间线 |
 | **产物** | `gotry_artifacts_list` / `gotry_artifacts_read` | 发现与查看已生成的产物(异步交付 + 工作目录 markdown),行号文件视图,只读 |
+| **事实闸** | `gotry_fact_gate` | 行程产物交付前闸:每条可下单 claim(航班号/时刻/机场/价格/政策)必须回溯到 exact-date 工具结果(hit/miss 均落账);无法回溯 ⇒ blocked——不得宣称「已验证方案」 |
 | **通用外部** | `gotry_web_search` · `gotry_video_subtitle` · `gotry_github_search` · `gotry_agent_reach` | 网页/字幕/GitHub/全渠道外部信息(经 Agent-Reach) |
 
 ---
@@ -128,7 +131,7 @@ GoTry: 收到。先把约束记下来——
 3. **物理只读** —— ReadGuard 在网络层中止一切写请求(下单/支付在传输层不可达),agent 永不接触凭证与验证码;遇到验证码立即停,交还给你。
 4. **绝不劫持你的浏览器** —— 检索/登录只开自己的独立标签页,登录页置前台、留在你那;例行动测试永不自动开浏览器窗。
 
-> 前置(一次性):日常 Chrome 打开 `chrome://inspect/#remote-debugging` 打开开关(Chrome 144+),并保持 Chrome 在线。未开启时工具返回 `needs-attach` 并给出指引,不消耗执行配额。
+> 前置(一次性):安装随包分发的 **GoTry Session Bridge** 浏览器扩展(MV3,约 30 秒):跑 `npx gotry setup` 落位到 `~/.gotry/extension`,再到 Chrome `chrome://extensions` 开启「开发者模式」→「加载已解压的扩展程序」选该目录。装完**零系统弹窗**——扩展只被动转发站点自己发出的检索响应(构造上只读;cookie 只读名字,值永不离开浏览器)。未安装时工具返回 `needs-extension` 并给出指引,不消耗执行配额。(诊断后备:cdp 车道经 `chrome://inspect` 远程调试,`GOTRY_SESSION_TRANSPORT=cdp` 显式开启——注意 Chrome 144+ 每次连接都会弹权限框。)
 
 ---
 
@@ -137,7 +140,7 @@ GoTry: 收到。先把约束记下来——
 ```
 ┌──────────────────────────────────────────────────────────────┐
 │ L1  对话即界面  chat-as-UI; gates 是消息内选择题                 │
-│ L2  编排  dsh 运行时 + GoTry 插件(ReAct);20 个工具            │
+│ L2  编排  dsh 运行时 + GoTry 插件(ReAct);21 个工具            │
 │ L3  领域  统一行程模型 + Z3 可行性引擎(枚举/Z3 双形态)        │
 │ L4  数据  静态数据包 + hotelbyte-cli 实时桥 + OpenFlights 骨架 │
 │ L5  治理  LoopX(objective / gates / evidence / quota)         │
@@ -146,7 +149,7 @@ GoTry: 收到。先把约束记下来——
 
 | 层 | 模块 | 角色 |
 |---|---|---|
-| L2 | `ts/src/index.ts`(dsh 插件) | 注册 20 工具,挂时间锚点/记忆 brief 变量;execute 异常隔离 + 授权闸 + 进程护栏 |
+| L2 | `ts/src/index.ts`(dsh 插件) | 注册 21 工具,挂时间锚点/记忆 brief 变量;execute 异常隔离 + 授权闸 + 进程护栏 |
 | L3 | `ts/src/unified.ts` · `py/gotry_feasibility/` | 唯一求解入口(候选枚举 + 航班链 Z3) |
 | L4 | `ts/capabilities/effect.ts` · `hbcli.ts` · `skeleton-check.ts` | 效应解译层(退避重试/断路器/mock 解译器,issue #16)+ 实时库存桥 + OpenFlights 骨架(三值语义) |
 | L5 | loopx 治理面 | objective / gates / evidence / quota |
@@ -162,6 +165,7 @@ GoTry: 收到。先把约束记下来——
 - **Z3 求解引擎** —— 可行性判定 + 门到门全成本;历史并发竞态已根治(§30 并发回归闸)
 - **实时检索**:机票/火车/酒店(飞猪官方通道)、目的地/酒店目录、天气、航班观测、通航性校验;可选让实时票价覆写进求解(`GOTRY_REALTIME_PRICING=1`)
 - **账号会话检索**:你本人登录态查携程机票,授权与隐私规则见上方 **🔐 账号会话:授权与隐私** 小节
+- **一次性浏览器扩展安装**:`npx gotry setup wizard` 引导你 30 秒装好 GoTry Session Bridge(MV3,扩展 ID 跨机器稳定,会话内零系统弹窗);后台 health-watch 探活,扩展一就位自动重放你的检索,**无需你手动重跑命令**
 - **记忆与触达**:动机画像 / 愿望池 / 同行人 / 旅行时间线;英文输出一键切换(`GOTRY_LOCALE=en`)
 
 **已知限制**(截至 2026-08-29,诚实清单):
@@ -200,7 +204,7 @@ GoTry: 收到。先把约束记下来——
 ./scripts/run-all-tests.sh
 ```
 
-全栈一次性绿(纯 TS,无 Python 依赖):engine/journey/unified 金标准 · 对话重放 · 异步工单跨进程 · 插件 smoke · hbcli · 进程护栏(含工具异常隔离)· 天气 · 航班 · Anything · probePoi · agent-reach(web/deep/wrapper)· 双路径稳定性 · 时间感评测(锚点卡/槽位过期校验/评分器/mock 回放;真模型巡检 `time-eval-tests.ts --real`)· 记忆域(动机合并守门/效用 sidecar/只读指标投影)· **Z3 并发竞态(§30)· 实时票价桥(§31)· i18n 目录(§32)· M3 cohort 证据合同(§33)· M4 价值证据合同(§34)**。
+全栈一次性绿(纯 TS,无 Python 依赖):engine/journey/unified 金标准 · 对话重放 · 异步工单跨进程 · 插件 smoke · hbcli · 进程护栏(含工具异常隔离)· 天气 · 航班 · Anything · probePoi · agent-reach(web/deep/wrapper)· 双路径稳定性 · 时间感评测(锚点卡/槽位过期校验/评分器/mock 回放;真模型巡检 `time-eval-tests.ts --real`)· 记忆域(动机合并守门/效用 sidecar/只读指标投影)· **Z3 并发竞态(§30)· 实时票价桥(§31)· i18n 目录(§32)· M3 cohort 证据合同(§33)· M4 价值证据合同(§34)· 会话传输扩展桥(§38)· onboarding UX wizard(§40)· 可下单事实闸(§39)**。
 
 ---
 
@@ -232,4 +236,4 @@ GoTry: 收到。先把约束记下来——
 
 **Built with**: DeepSeek Harness 0.1.2-alpha.1 (vendored) · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 (`.venv/`) · OpenFlights · TypeScript
 
-**Last verified against `v0.0.1-rc.15`(2026-08-29)** — 全栈回归全绿 §1-§36(发布流程见 `scripts/publish-npm.sh`)。
+**Last verified against `v0.0.1-rc.16`(2026-08-30)** — 全栈回归全绿 §1-§42(发布流程见 `scripts/publish-npm.sh`)。

package/bin/gotry-bootstrap.js

@@ -8,17 +8,26 @@
  *                           dsh web 侧栏工作台(文件浏览/Markdown/Mermaid/PDF 预览)——
  *                           gotry 产物(工单交付 md/行程 md)的成熟查看面(issue #25)。
  *                           宿主层安装(dsh plugin → ~/.dsh/profiles/web),不进 gotry 依赖。
+ *   gotry-session-bridge   → 会话检索浏览器扩展(issue #21 传输层方案 C,2026-08-29 定案):
+ *                           一次性安装替代逐连接 CDP 弹窗;幂等拷贝到 ~/.gotry/extension,
+ *                           最后一步是用户在 chrome://extensions 「加载已解压的扩展程序」(约 30 秒,零系统弹窗)。
  *
  * 用法:
  *   node bin/gotry-bootstrap.js              # 显式安装(缺啥装啥;失败 exit 1)
  *   node bin/gotry-bootstrap.js --auto       # postinstall 模式:CI/跳过开关检测,任何失败不挡安装(exit 0)
  *   node bin/gotry-bootstrap.js --check-only # 只探测报告,不安装(测试钩子)
+ *   node bin/gotry-bootstrap.js wizard       # 会话扩展 onboarding 闭环(issue #21 onboarding UX,§3.3):
+ *                                           #   5 步编排 + 后台 health-watch 等扩展心跳,
+ *                                           #   扩展一就位 stdout 翻绿并自动重放同 query。
+ *                                           # 详见 docs/user-session-data-rfc.md §3.3 / RFC P3.6。
  *
  * 环境开关:
  *   GOTRY_SETUP_SKIP=1            全部跳过
  *   GOTRY_SETUP_HBCLI=0           跳过 hbcli
  *   GOTRY_SETUP_REACH=0           跳过 agent-reach
  *   GOTRY_SETUP_SIDEBAR=0         跳过 dsh-better-sidebar
+ *   GOTRY_SETUP_EXTENSION=0       跳过会话检索扩展落位
+ *   GOTRY_ONBOARDING_HEADLESS=1   wizard 子命令强制走终端面板(SSH/CI 默认探测)
  *
  * 契约:安装外部依赖永远不挡 gotry 本体——能力层各有降级路径(静态包/not-installed
  * verdict),自举失败只降级体验,不产生故障。凭证(hbcli auth / agent-reach 渠道
@@ -26,7 +35,7 @@
  */
 
 import { spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -34,6 +43,8 @@ import { fileURLToPath } from 'node:url'
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
 const AUTO = process.argv.includes('--auto')
 const CHECK_ONLY = process.argv.includes('--check-only')
+const WIZARD = process.argv.includes('wizard') || process.argv.includes('--wizard')
+const WIZARD_DRY_RUN = process.argv.includes('--dry-run')
 
 const HBCLI_INSTALL_CMD = 'curl -fsSL https://github.com/hotelbyte-com/docs/releases/latest/download/install.sh | bash'
 const REACH_INSTALL_URL = 'git+https://github.com/Panniantong/Agent-Reach.git'
@@ -68,7 +79,14 @@ async function setupHbcli() {
   say('[gotry-setup] hbcli(hotelbyte-cli,可选酒店实时源)')
   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']))
-  if (present) { say('  ✓ 已安装'); return { ok: true } }
+  const credFile = join(homedir(), '.staicli', 'credentials.json')
+  if (present) {
+    say('  ✓ 已安装')
+    if (existsSync(credFile)) say('  ✓ 凭证已配置(自检: hbcli auth whoami)')
+    else say('  ✗ 凭证未配置——酒店检索将用内置静态包(非实时),账号配置见下方指引')
+    if (CHECK_ONLY) say('  (--check-only 只报告,不安装)')
+    return { ok: true }
+  }
   if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
   say(`  安装中(官方脚本): ${HBCLI_INSTALL_CMD}`)
   const r = await run('bash', ['-c', HBCLI_INSTALL_CMD], { timeoutMs: 120_000 })
@@ -77,7 +95,11 @@ async function setupHbcli() {
   if (!process.env.PATH.split(':').includes(binDir)) {
     say(`  ⚠ ${binDir} 不在当前 PATH —— gotry 工具已内建候选路径回退,无需手动处理;其他程序可用: export PATH="${binDir}:$PATH"`)
   }
-  say('  ✓ 安装完成(凭证选配: hbcli auth set-credentials --app-key ... --app-secret ...,或 HOTELBYTE_TOKEN;未配时酒店检索自动用静态包)')
+  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 即就位)')
   return { ok: true }
 }
 
@@ -98,8 +120,7 @@ async function setupReach() {
   return { ok: true }
 }
 
-async function setupSidebar() {
-  say('[gotry-setup] dsh-better-sidebar(dsh web 侧栏工作台,产物查看面 issue #25)')
+async function setupSidebar() {  say('[gotry-setup] dsh-better-sidebar(dsh web 侧栏工作台,产物查看面 issue #25)')
   const installed = existsSync(join(homedir(), '.dsh/profiles/web/node_modules/dsh-better-sidebar/package.json'))
   if (installed) { say('  ✓ 已安装(~/.dsh/profiles/web)'); return { ok: true } }
   if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
@@ -129,11 +150,277 @@ async function setupSidebar() {
   return { ok: true }
 }
 
+const EXTENSION_FILES = ['manifest.json', 'background.js', 'content-main.js', 'content-bridge.js', 'README.md']
+
+function readManifestVersion(manifestPath) {
+  try { return JSON.parse(readFileSync(manifestPath, 'utf8')).version ?? null } catch { return null }
+}
+
+function copyExtensionDir(srcDir, dstDir) {
+  mkdirSync(dstDir, { recursive: true })
+  for (const f of EXTENSION_FILES) {
+    const s = join(srcDir, f)
+    if (!existsSync(s)) continue
+    copyFileSync(s, join(dstDir, f))
+  }
+}
+
+/** 会话检索扩展(issue #21 方案 C):包内 extension/ → ~/.gotry/extension 幂等落位 + 一次性加载指引 */
+async function setupExtension() {
+  say('[gotry-setup] GoTry Session Bridge 扩展(会话检索数据面 issue #21;一次性安装,替代逐连接弹窗)')
+  const srcDir = join(repoRoot, 'extension')
+  const srcManifest = join(srcDir, 'manifest.json')
+  if (!existsSync(srcManifest)) {
+    say(`  ✗ 包内未找到扩展文件(${srcDir})——不影响 gotry:会话检索降级,重装 npx gotry 可恢复`)
+    return { ok: false }
+  }
+  const srcVersion = readManifestVersion(srcManifest)
+  const dstDir = join(homedir(), '.gotry', 'extension')
+  const dstVersion = readManifestVersion(join(dstDir, 'manifest.json'))
+  if (dstVersion != null && dstVersion === srcVersion) {
+    say(`  ✓ 已就位(~/.gotry/extension,v${dstVersion};若浏览器里尚未加载:chrome://extensions → 开发者模式 → 加载已解压的扩展程序 → 选 ~/.gotry/extension)`)
+    return { ok: true }
+  }
+  if (CHECK_ONLY) { say(`  ✗ ${dstVersion == null ? `未安装(落位 ${dstDir})` : `待更新 v${dstVersion} → v${srcVersion},落位 ${dstDir}`}(--check-only 只报告)`); return { ok: true } }
+  try {
+    copyExtensionDir(srcDir, dstDir)
+  } catch (e) {
+    say(`  ✗ 落位失败(${e.message})——不影响 gotry:会话检索降级;可手动拷贝 ${srcDir} → ${dstDir}`)
+    return { ok: false }
+  }
+  say(`  ✓ 已落位 ${dstDir}(v${srcVersion};manifest 带固定 key,扩展 ID 恒为 olpgkofjhhiiiahdkkbcninhjmegghfe)`)
+  say('  最后一步(每台浏览器一次,约 30 秒):Chrome 打开 chrome://extensions → 右上角开启「开发者模式」→「加载已解压的扩展程序」→ 选择 ~/.gotry/extension')
+  say('  装好即生效,零系统弹窗;扩展卡片开关=总闸(与 gotry 授权闸 sessionAccess 双重控制)')
+  return { ok: true }
+}
+
+/**
+ * 调 wizard-bootstrap.ts(wizard.ts 的 CLI 入口):拿 5 步 OnboardingResult 打印到 stdout。
+ * tsx 子进程跑 wizard 全套(扩展落位 + 开 Chrome + pbcopy 真实覆写剪贴板 + osascript GUI 面板);
+ * bootstrap 不再 inline 任何 spawn——所有 UX 都走 wizard.ts,与 onboarding-tests §40 同一份代码。
+ * npm 安装态(无 ts/目录):降级 inline 跑 5 步的最小子集——只调 setupExtension + 打印路径,UI 面板/剪贴板由用户手动。
+ */
+async function runWizardBootstrap() {
+  const wizardScript = join(repoRoot, 'ts', 'scripts', 'wizard-bootstrap.ts')
+  const extensionDir = join(homedir(), '.gotry', 'extension')
+  if (!existsSync(wizardScript)) {
+    // npm 安装态降级:只确保扩展落位,文案照常打
+    say('[gotry-wizard] 内置 wizard 脚本缺失(已装 npm 包态)——降级手动模式:')
+    await setupExtension()
+    return { ok: true }
+  }
+  return new Promise((resolve) => {
+    const child = spawn('npx', ['--yes', 'tsx', wizardScript, '--extension-dir', extensionDir, '--source-dir', join(repoRoot, 'extension')], {
+      cwd: join(repoRoot, 'ts'),
+      stdio: ['ignore', 'pipe', 'inherit'],
+    })
+    let stdoutBuf = ''
+    let resolved = false
+    const finish = (r) => {
+      if (resolved) return
+      resolved = true
+      resolve(r)
+    }
+    child.stdout.on('data', (c) => {
+      stdoutBuf += c.toString('utf8')
+      let nl = stdoutBuf.indexOf('\n')
+      while (nl >= 0) {
+        const line = stdoutBuf.slice(0, nl).trim()
+        stdoutBuf = stdoutBuf.slice(nl + 1)
+        if (line.startsWith('{')) {
+          try {
+            const o = JSON.parse(line)
+            // 打印 5 步 status(wizard 自己的 print 已在子进程跑了;此处父进程再 human-friendly 一次)
+            if (Array.isArray(o.steps)) {
+              for (const s of o.steps) {
+                const tag = s.status === 'ok' ? '✅' : s.status === 'skip' ? '⏭ ' : '❌'
+                say(`[gotry-wizard] ${tag} ${s.step}: ${s.summary}`)
+              }
+            }
+            say(`[gotry-wizard] platform=${o.platform}; extensionDir=${o.extensionDir}; ok=${o.ok}`)
+            finish({ ok: o.ok === true })
+          } catch {
+            say(`[gotry-wizard] ✗ wizard JSON 解析失败`)
+            finish({ ok: false })
+          }
+          try { child.kill('SIGTERM') } catch { /* ignore */ }
+          return
+        }
+        nl = stdoutBuf.indexOf('\n')
+      }
+    })
+    child.on('exit', (code) => {
+      if (!resolved) {
+        say(`[gotry-wizard] ✗ wizard 子进程 exit ${code}(stdout 无 JSON)`)
+        finish({ ok: code === 0 })
+      }
+    })
+    child.on('error', (e) => {
+      say(`[gotry-wizard] ✗ wizard 子进程启动失败: ${e.message}`)
+      finish({ ok: false })
+    })
+  })
+}
+
+/**
+ * 后台探活扩展心跳(wizard 闭环「装完零重跑」,§3.3):
+ * spawn tsx 跑 health-watch.ts(纯 TS 探活,run-all §40 同一份代码),接 stdout JSON 结果行。
+ * 探活期间每 5s stdout 一行 `.`,用户看见 stdout 持续推进,不卡死假象。
+ * 默认 120s 超时;若用户提前 Ctrl+C,timeoutMs 走 0 立即返回 cancelled。
+ */
+async function runHealthWatch() {
+  // 跨语言:bootstrap 是纯 JS,health-watch 是 TS;走 spawn npx tsx 子进程,stdout 解析。
+  // tsx 子进程路径 = <repoRoot>/ts;不在 npm 包里跑(发布面只走 src/bin,不走 wizard 自动化)
+  const watcherScript = join(repoRoot, 'ts', 'scripts', 'health-watch-cli.ts')
+  // 默认 120s / 5s,§3.3 设计值;env 可覆盖(bootstrap-tests 跑真实路径用)
+  const timeoutMs = parseInt(process.env.GOTRY_ONBOARDING_TIMEOUT_MS ?? '120000', 10) || 120_000
+  const probeIntervalMs = parseInt(process.env.GOTRY_ONBOARDING_INTERVAL_MS ?? '5000', 10) || 5_000
+  return new Promise((resolve) => {
+    const args = [watcherScript, '--timeout', String(timeoutMs), '--interval', String(probeIntervalMs), '--json']
+    // 先确认 watcher 脚本存在(npm 安装态可能未带 ts/目录——降级:走内联 node:http 短探活,避免挡用户)
+    if (!existsSync(watcherScript)) {
+      say(`[gotry-wizard] 内置探活脚本缺失(${watcherScript})——改用内置 5s 轮询`)
+      resolve(runInlineHealthWatch(timeoutMs))
+      return
+    }
+    const child = spawn('npx', ['--yes', 'tsx', ...args], {
+      cwd: join(repoRoot, 'ts'),
+      stdio: ['ignore', 'pipe', 'inherit'],
+      env: { ...process.env, GOTRY_ONBOARDING_HEADLESS: process.env.GOTRY_ONBOARDING_HEADLESS ?? '1' },
+    })
+    let stdoutBuf = ''
+    let heartbeatTicker = 0
+    const hbInterval = setInterval(() => {
+      heartbeatTicker += 1
+      process.stdout.write('.')
+      if (heartbeatTicker % 12 === 0) process.stdout.write(`(${Math.round(heartbeatTicker * probeIntervalMs / 1000)}s)\n`)
+    }, probeIntervalMs)
+    child.stdout.on('data', (c) => {
+      const s = c.toString('utf8')
+      stdoutBuf += s
+      // JSON 结果行以 \n 分隔;watcher 一次性 stdout 一行 JSON 退出
+      let nl = stdoutBuf.indexOf('\n')
+      while (nl >= 0) {
+        const line = stdoutBuf.slice(0, nl).trim()
+        stdoutBuf = stdoutBuf.slice(nl + 1)
+        if (line.startsWith('{')) {
+          clearInterval(hbInterval)
+          try {
+            const o = JSON.parse(line)
+            resolve({ ready: o.ready === true, attempts: o.attempts ?? 0, waitedMs: o.waitedMs ?? 0, reason: o.reason ?? 'timeout', timeoutMs })
+          } catch {
+            resolve({ ready: false, attempts: 0, waitedMs: 0, reason: 'parse-error', timeoutMs })
+          }
+          try { child.kill('SIGTERM') } catch { /* ignore */ }
+          return
+        }
+        nl = stdoutBuf.indexOf('\n')
+      }
+    })
+    child.on('exit', (code) => {
+      clearInterval(hbInterval)
+      process.stdout.write('\n')
+      if (code !== 0 && stdoutBuf.trim() === '') {
+        resolve({ ready: false, attempts: 0, waitedMs: 0, reason: `watcher-exit-${code}`, timeoutMs })
+      }
+    })
+    child.on('error', () => {
+      clearInterval(hbInterval)
+      resolve({ ready: false, attempts: 0, waitedMs: 0, reason: 'watcher-spawn-error', timeoutMs })
+    })
+  })
+}
+
+/** npm 安装态(无 ts/目录)降级:内置 5s 轮询 node:http,与 health-watch 同节奏 */
+async function runInlineHealthWatch(timeoutMs) {
+  const intervalMs = parseInt(process.env.GOTRY_ONBOARDING_INTERVAL_MS ?? '5000', 10) || 5_000
+  const ports = [8791, 8792, 8793, 8794, 8795]
+  const http = await import('node:http')
+  const startedAt = Date.now()
+  let attempts = 0
+  while (Date.now() - startedAt < timeoutMs) {
+    attempts += 1
+    for (const port of ports) {
+      const ok = await new Promise((resolve) => {
+        const req = http.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) => { buf += c })
+          res.on('end', () => {
+            try { resolve(JSON.parse(buf).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) {
+        process.stdout.write('\n')
+        return { ready: true, attempts, waitedMs: Date.now() - startedAt, reason: 'ready', timeoutMs }
+      }
+    }
+    process.stdout.write('.')
+    await new Promise((r) => setTimeout(r, intervalMs))
+  }
+  process.stdout.write('\n')
+  return { ready: false, attempts, waitedMs: Date.now() - startedAt, reason: 'timeout', timeoutMs }
+}
+
 async function main() {
+  // wizard 子命令(issue #21 onboarding UX,§3.3 / P3.6):扩展安装闭环,5 步 + 后台 health-watch。
+  // **纯 onboarding**,不调 hbcli/agent-reach/sidebar 等其他节——只跑扩展落位 + 健康探活;
+  // 想要全量安装仍走 `npx gotry setup`(无 wizard)。
+  if (WIZARD) {
+    if (WIZARD_DRY_RUN) {
+      say('[gotry-wizard] dry-run 模式(零网络零浏览器,只校验命令编排与输出形态;run-all §40 走这条)')
+      say('  步骤: ensure-extension-files → open-chrome-extensions → clipboard-extension-path → panel-guide → watch-extension-ready')
+      say('  平台: darwin(zh-CN stdout);headless/Linux/Windows 同理降级')
+      say('  ✅ exit 0')
+      process.exit(0)
+    }
+    // 真实路径:spawn tsx 子进程跑 wizard-bootstrap.ts(同一份 wizard.ts 代码),
+    // 拿 5 步 OnboardingResult 打印 status(ok/✅/⏭ /❌)+ 剪贴板/GUI 面板/落位实跑。
+    const wizardResult = await runWizardBootstrap()
+    if (!wizardResult.ok) {
+      say('[gotry-wizard] ✗ wizard 编排有失败步——见上方;扩展未引导到位;可手动 chrome://extensions 加载 ~/.gotry/extension')
+      process.exit(1)
+    }
+    // wizard 闭环:装完扩展就位 stdout 翻「✅ 就绪」(由 health-watch 推动)
+    say('')
+    say('[gotry-wizard] ────────────────────────────────')
+    say('[gotry-wizard] 共 3 步,约 30 秒,装完零弹窗:')
+    say('[gotry-wizard]   ① Chrome 右上角开启「开发者模式」')
+    say(`[gotry-wizard]   ② 点「加载已解压的扩展程序」,选这个目录(已复制到剪贴板):`)
+    say(`[gotry-wizard]      ${join(homedir(), '.gotry', 'extension')}`)
+    say('[gotry-wizard]   ③ 弹窗「添加扩展」点「添加」')
+    say('[gotry-wizard] ────────────────────────────────')
+    say('[gotry-wizard] 装好后**无需重跑任何命令**——下面会自动探活,扩展一就位 stdout 翻绿。')
+    say('')
+    say('[gotry-wizard] 正在后台探活扩展心跳(最长 120s;Ctrl+C 取消)...')
+    // 后台 health-watch:spawn tsx 子进程跑 health-watch.ts(纯 TS 模块,browser-only),
+    // 探活逻辑与 onboarding-tests §40 同一份代码;无 GUI 依赖。
+    const watchResult = await runHealthWatch()
+    if (watchResult.ready) {
+      say(`[gotry-wizard] ✅ 扩展就绪(等待 ${watchResult.waitedMs}ms,${watchResult.attempts} 次探活)`)
+      say('[gotry-wizard] 现在调用 gotry_session_search 即可拿到会话检索结果(零后续手工动作)。')
+      say('[gotry-wizard] 入口示例:')
+      say('  ./gotry        # 启动 dsh → 用 gotry_session_search 工具')
+      say('  ./gotry session-check  # 跑 sf-01..08 八条 query 双源 scorer(goal 2)')
+      process.exit(0)
+    } else {
+      say(`[gotry-wizard] ✗ ${watchResult.reason}(${watchResult.attempts} 次探活)——扩展未在 ${watchResult.timeoutMs}ms 内就绪`)
+      say('[gotry-wizard] 重新打开 chrome://extensions 确认「GoTry Session Bridge · 已启用」,再跑 `npx gotry setup wizard` 重试。')
+      process.exit(1)
+    }
+  }
+
   if (process.platform === 'win32') {
     say('[gotry-setup] Windows 暂不支持自动安装(hbcli 上游仅 darwin/linux)。手动指引:')
     say(`  hbcli: ${HBCLI_INSTALL_CMD}(WSL);agent-reach: python -m venv .venv && .venv/Scripts/pip install ${REACH_INSTALL_URL}`)
     say('  dsh-better-sidebar: npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar@latest')
+    say('  GoTry Session Bridge 扩展:手动把包内 extension/ 目录拷到 %USERPROFILE%\\.gotry\\extension,再在 chrome://extensions 开发者模式「加载已解压的扩展程序」')
     process.exit(AUTO ? 0 : 1)
   }
   if (AUTO && (process.env.CI || process.env.GOTRY_SETUP_SKIP === '1')) {
@@ -149,6 +436,8 @@ async function main() {
   else say('[gotry-setup] agent-reach:GOTRY_SETUP_REACH=0 跳过')
   if (process.env.GOTRY_SETUP_SIDEBAR !== '0') results.push(await setupSidebar())
   else say('[gotry-setup] dsh-better-sidebar:GOTRY_SETUP_SIDEBAR=0 跳过')
+  if (process.env.GOTRY_SETUP_EXTENSION !== '0') results.push(await setupExtension())
+  else say('[gotry-setup] GoTry Session Bridge 扩展:GOTRY_SETUP_EXTENSION=0 跳过')
   say('[gotry-setup] flyai:无需安装(npx 每次自拉 @fly-ai/flyai-cli,免 key)')
   const failed = results.filter((r) => !r.ok).length
   if (failed > 0) {

package/cordis.gotry-patch.yml

@@ -91,3 +91,13 @@
       开页探测;返回 challenged→立即停手如实告知,绝不重试
       绝不绕过。跨源结论各带来源标注([实时API:flyai@ts]/[会话:ctrip-flight@ts]/
       [静态包:估算]),分桶比对直达/中转,不比裸最低价;证据链随结论必达用户。
+      (20)事实闸(可下单事实 fail-closed,issue #46):航班号/时刻/机场/价格/签证政策
+      只能来自本轮 exact-date 工具结果;exact-date 返回 miss = 「未确认/当前不可售,
+      到 D-xx 复核」,**不得**用航线页当日班期、历史航季、相邻日期或记忆填充;
+      「只验证航线存在」永不升级为「该日期有该航班」;「联程」仅用于同票保护
+      (protected_connection),分票/自助转机必须显式标红(无行李直挂/误机无保护);
+      政策只能表述为「截至 YYYY-MM-DD 的现行政策」并附复核日期,不用无条件 ✓;
+      双机场城市的航司落点不互换(FD 落 DMK、VZ 落 BKK)。
+      **交付任何含可下单事实的行程产物(markdown 文件或长方案)前,必须调
+      gotry_fact_gate**;闸 blocked 时逐条修正为可回溯事实或降级措辞,
+      不得宣称「已验证方案」。

package/data/airline-airports.json

@@ -0,0 +1,39 @@
+{
+  "meta": {
+    "schema": "gotry_airline_airports.v1",
+    "as_of": "2026-08-29",
+    "review_by": "2026-09-28",
+    "source": "issue #46 exact-date audit snapshot (trip.com 2027 日期可售快照)",
+    "note": "两张表职责不同:city_alias 是稳定词汇(解析航线上下文);carrier_airport 是 dated 快照,只作冲突检测——可下单事实的唯一来源永远是 exact-date 工具结果,本表不产事实。双机场城市的航司→机场映射过期风险高,过 review_by 后只降级使用(仍作冲突检测,结论标注快照日)。"
+  },
+  "city_alias": {
+    "香港": "HKG",
+    "普吉": "HKT",
+    "甲米": "KBV",
+    "奥南": "KBV",
+    "曼谷": "BKK",
+    "深圳": "SZX",
+    "广州": "CAN",
+    "迪拜": "DXB",
+    "昆明": "KMG",
+    "大理": "DLU",
+    "丽江": "LJG",
+    "南京": "NKG",
+    "上海": "PVG",
+    "北京": "PEK",
+    "成都": "CTU",
+    "西安": "XIY",
+    "杭州": "HGH",
+    "多哈": "DOH"
+  },
+  "carrier_airport": {
+    "BKK": {
+      "FD": "DMK",
+      "VZ": "BKK",
+      "SL": "DMK",
+      "DD": "DMK",
+      "PG": "BKK",
+      "TG": "BKK"
+    }
+  }
+}

package/dist/capabilities/agent-reach-deep.js

@@ -169,4 +169,4 @@ export async function githubSearch(q) {
 }
 
 
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/agent-reach-deep.ts
+//# sourceURL=/Users/bytedance/work/gotry-publish/ts/capabilities/agent-reach-deep.ts

package/dist/capabilities/agent-reach.js

@@ -201,4 +201,4 @@ export async function reachStatus(timeoutMs = 90_000) {
 }
 
 
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/agent-reach.ts
+//# sourceURL=/Users/bytedance/work/gotry-publish/ts/capabilities/agent-reach.ts

package/dist/capabilities/anything.js

@@ -136,4 +136,4 @@ export const _ = {
 };
 
 
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/anything.ts
+//# sourceURL=/Users/bytedance/work/gotry-publish/ts/capabilities/anything.ts

package/dist/capabilities/artifacts.js

@@ -214,4 +214,4 @@ export async function readArtifact(opts) {
 }
 
 
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/artifacts.ts
+//# sourceURL=/Users/bytedance/work/gotry-publish/ts/capabilities/artifacts.ts