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

package/bin/gotry-bootstrap.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * gotry 外部依赖自举(founder 2026-08-29 指令:安装 gotry 时按上游本身的方式装好外部依赖):
+ *   hbcli(hotelbyte-cli)  → 官方 install.sh(原生二进制,~/.local/bin/hbcli)
+ *   agent-reach            → 官方 pip 安装 git+ upstream(包内 .venv,与 z3-solver 同址原则)
+ *   flyai                  → 无需安装(npx 每次自拉 @fly-ai/flyai-cli)
+ *   dsh-better-sidebar     → dsh 宿主层插件市场组件(dshmarket.com #1 UI,18.9 万周装):
+ *                           dsh web 侧栏工作台(文件浏览/Markdown/Mermaid/PDF 预览)——
+ *                           gotry 产物(工单交付 md/行程 md)的成熟查看面(issue #25)。
+ *                           宿主层安装(dsh plugin → ~/.dsh/profiles/web),不进 gotry 依赖。
+ *
+ * 用法:
+ *   node bin/gotry-bootstrap.js              # 显式安装(缺啥装啥;失败 exit 1)
+ *   node bin/gotry-bootstrap.js --auto       # postinstall 模式:CI/跳过开关检测,任何失败不挡安装(exit 0)
+ *   node bin/gotry-bootstrap.js --check-only # 只探测报告,不安装(测试钩子)
+ *
+ * 环境开关:
+ *   GOTRY_SETUP_SKIP=1            全部跳过
+ *   GOTRY_SETUP_HBCLI=0           跳过 hbcli
+ *   GOTRY_SETUP_REACH=0           跳过 agent-reach
+ *   GOTRY_SETUP_SIDEBAR=0         跳过 dsh-better-sidebar
+ *
+ * 契约:安装外部依赖永远不挡 gotry 本体——能力层各有降级路径(静态包/not-installed
+ * verdict),自举失败只降级体验,不产生故障。凭证(hbcli auth / agent-reach 渠道
+ * cookie)属用户资产,不自动配置,装完二进制后给指引。
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+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 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'
+
+/** 带超时的子进程(inherit stdio 让用户看见上游安装进度) */
+function run(cmd, args, { timeoutMs, cwd } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', cwd, env: process.env })
+    let done = false
+    const timer = setTimeout(() => {
+      if (!done) { done = true; try { child.kill('SIGKILL') } catch { /* ignore */ } }
+    }, timeoutMs)
+    child.on('error', (e) => { if (!done) { done = true; clearTimeout(timer); resolve({ ok: false, error: e.message }) } })
+    child.on('exit', (code) => { if (!done) { done = true; clearTimeout(timer); resolve({ ok: code === 0, error: code === 0 ? undefined : `exit ${code}` }) } })
+  })
+}
+
+/** 静默探测命令是否可执行(带超时) */
+function probe(cmd, args, timeoutMs = 10_000) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: 'ignore' })
+    let done = false
+    const timer = setTimeout(() => { if (!done) { done = true; try { child.kill('SIGKILL') } catch { /* ignore */ } resolve(false) } }, timeoutMs)
+    child.on('error', () => { if (!done) { done = true; clearTimeout(timer); resolve(false) } })
+    child.on('exit', (code) => { if (!done) { done = true; clearTimeout(timer); resolve(code === 0) } })
+  })
+}
+
+const say = (s) => console.log(s)
+
+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 } }
+  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 })
+  if (!r.ok) { say(`  ✗ 安装失败(${r.error})——不影响 gotry,酒店检索将用内置静态包;可稍后重试: npx gotry setup`); return { ok: false } }
+  const binDir = join(homedir(), '.local/bin')
+  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;未配时酒店检索自动用静态包)')
+  return { ok: true }
+}
+
+async function setupReach() {
+  say('[gotry-setup] agent-reach(可选网页/社媒读取源,pip 装入包内 .venv)')
+  const venvBin = join(repoRoot, '.venv/bin/agent-reach')
+  if (existsSync(venvBin)) { say('  ✓ 已安装(.venv)'); return { ok: true } }
+  if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
+  const hasPy = await probe('python3', ['--version'], 10_000)
+  if (!hasPy) { say('  ✗ 跳过:未找到 python3(agent-reach 需 Python 3;装好后重跑 npx gotry setup)'); return { ok: false } }
+  say(`  创建 .venv 并安装上游(${REACH_INSTALL_URL})`)
+  const venv = await run('python3', ['-m', 'venv', join(repoRoot, '.venv')], { timeoutMs: 120_000 })
+  if (!venv.ok) { say(`  ✗ venv 创建失败(${venv.error})——不影响 gotry,gotry_agent_reach 将返回 not-installed 指引`); return { ok: false } }
+  const pip = join(repoRoot, '.venv/bin/pip')
+  const inst = await run(pip, ['install', '-q', REACH_INSTALL_URL], { timeoutMs: 300_000 })
+  if (!inst.ok) { say(`  ✗ pip 安装失败(${inst.error})——可稍后重试: npx gotry setup`); return { ok: false } }
+  say('  ✓ 安装完成(渠道凭证选配见 docs/tokens.md: .venv/bin/agent-reach configure --from-browser chrome --platform <渠道>)')
+  return { ok: true }
+}
+
+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 } }
+  const SIDEBAR_PKG = 'dsh-better-sidebar@latest'
+  // dsh CLI:本包依赖里的 @deepseek-ai/dsh 优先;解析不到走 npx 自拉(官方安装途径同款)
+  const { createRequire } = await import('node:module')
+  const require_ = createRequire(join(repoRoot, 'package.json'))
+  let launched = false
+  try {
+    const dshBin = require_.resolve('@deepseek-ai/dsh/lib/bin.js')
+    say(`  安装中(dsh plugin → web profile): ${SIDEBAR_PKG}`)
+    const r = await run(process.execPath, [dshBin, 'plugin', '--profile', 'web', 'add', SIDEBAR_PKG], { timeoutMs: 300_000 })
+    launched = true
+    if (r.ok) {
+      say('  ✓ 安装完成(gotry web 刷新浏览器即见右侧工作台;工作区里的产物 md 可直接预览)')
+      return { ok: true }
+    }
+    say(`  ✗ dsh plugin 安装失败(${r.error})——尝试 npx 途径`)
+  } catch { /* 本包未携带 @deepseek-ai/dsh */ }
+  if (!launched) say('  本包未携带 @deepseek-ai/dsh,走 npx 途径安装')
+  const r2 = await run('npx', ['-y', '--package', '@deepseek-ai/dsh', 'dsh', 'plugin', '--profile', 'web', 'add', SIDEBAR_PKG], { timeoutMs: 300_000 })
+  if (!r2.ok) {
+    say('  ✗ 安装失败——不影响 gotry:产物仍可在对话里说「看看我生成的行程」经 gotry_artifacts_list/read 查看;可稍后重试: npx gotry setup')
+    return { ok: false }
+  }
+  say('  ✓ 安装完成(gotry web 刷新浏览器即见右侧工作台)')
+  return { ok: true }
+}
+
+async function main() {
+  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')
+    process.exit(AUTO ? 0 : 1)
+  }
+  if (AUTO && (process.env.CI || process.env.GOTRY_SETUP_SKIP === '1')) {
+    say('[gotry-setup] CI/GOTRY_SETUP_SKIP 检测——跳过外部依赖自举(可随时手动: npx gotry setup)')
+    say('GoTry installed. Run: npx gotry web   (dsh Web UI on :3080)')
+    process.exit(0)
+  }
+  if (!AUTO && process.env.GOTRY_SETUP_SKIP === '1') { say('[gotry-setup] GOTRY_SETUP_SKIP=1——跳过'); process.exit(0) }
+  const results = []
+  if (process.env.GOTRY_SETUP_HBCLI !== '0') results.push(await setupHbcli())
+  else say('[gotry-setup] hbcli:GOTRY_SETUP_HBCLI=0 跳过')
+  if (process.env.GOTRY_SETUP_REACH !== '0') results.push(await setupReach())
+  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 跳过')
+  say('[gotry-setup] flyai:无需安装(npx 每次自拉 @fly-ai/flyai-cli,免 key)')
+  const failed = results.filter((r) => !r.ok).length
+  if (failed > 0) {
+    say(`[gotry-setup] ${failed} 项未就绪——gotry 本体不受影响(各能力均有降级路径);可稍后重跑: npx gotry setup`)
+    process.exit(AUTO ? 0 : 1)
+  }
+  say('[gotry-setup] 全部就绪。Run: npx gotry web')
+  process.exit(0)
+}
+
+main().catch((e) => {
+  say(`[gotry-setup] 异常:${e.message}(不影响 gotry 本体;可重试 npx gotry setup)`)
+  process.exit(AUTO ? 0 : 1)
+})

package/bin/gotry-inner.js

@@ -16,7 +16,7 @@
  *      占位(本机绝对路径),随 tarball 分发后对其他机器必错。
  */
 
-import { spawn } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
@@ -56,6 +56,7 @@ if (help) {
 
 Usage:
   gotry web                          # dsh Web UI on http://127.0.0.1:3080
+  gotry setup                        # 安装可选外部依赖(hbcli 官方脚本 / agent-reach pip;装时已自动跑过)
   gotry "一段完整任务..."            # headless 一问一答
   gotry help                         # this help
 
@@ -68,12 +69,18 @@ Detail: https://github.com/Danceiny/gotry — README
   process.exit(0)
 }
 
-// mode 决定路径: 'web'/'help'/'help' 是字面命令;否则第一段 args[0] 是任务本身的一部分
-const literal = new Set(['web', 'help', '-h', '--help'])
+// mode 决定路径: 'web'/'setup'/'help' 是字面命令;否则第一段 args[0] 是任务本身的一部分
+const literal = new Set(['web', 'setup', 'help', '-h', '--help'])
 const isLiteral = literal.has(args[0])
 const mode = isLiteral ? args[0] : 'headless'
 const rest = isLiteral ? args.slice(1) : args
 
+// setup:外部依赖自举(hbcli/agent-reach),不需要 dsh runtime 与 LLM key,同步分发后即退
+if (mode === 'setup') {
+  const r = spawnSync(process.execPath, [join(here, 'gotry-bootstrap.js'), ...rest], { stdio: 'inherit' })
+  process.exit(r.status ?? (r.error ? 1 : 0))
+}
+
 // --- dsh runtime 定位:repo checkout(vendored)优先,npm 安装走依赖解析 ---
 const vendoredDsh = join(repoRoot, 'ts/dsh-runtime/node_modules/@deepseek-ai/dsh/lib/bin.js')
 let dshBin = ''

package/dist/capabilities/artifacts.js

@@ -0,0 +1,217 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { openLedgerIfExists } from '../src/state-ledger.js';
+const MAX_LIST = 50;
+const MAX_WINDOW = 400;
+const MAX_BYTES = 2 * 1024 * 1024;
+const TEXT_EXT_LANG = {
+    md: 'markdown',
+    txt: 'text',
+    json: 'json',
+    jsonl: 'json',
+    csv: 'csv',
+    log: 'text',
+    yaml: 'yaml',
+    yml: 'yaml'
+};
+const DIR_DENY = [
+    'node_modules',
+    '.git'
+];
+function rootOf(stateRoot) {
+    return stateRoot === '.' ? process.cwd() : resolve(stateRoot);
+}
+function underRoot(p, root) {
+    const r = resolve(root);
+    return p === r || p.startsWith(r + sep);
+}
+function hasDeniedSegment(p) {
+    return p.split(sep).some((seg)=>DIR_DENY.includes(seg));
+}
+function asyncDeliverablePath(root, id) {
+    return join(root, 'gotry-state', 'async', `${id}.deliverable.md`);
+}
+function listRunsFromLedger(root, tenant, limit) {
+    const ledger = openLedgerIfExists(root, tenant);
+    if (!ledger) return [];
+    const rows = ledger.db.prepare('SELECT id, goal, status, deliverable, updated FROM workflow_runs WHERE tenant_id = ? ORDER BY updated DESC LIMIT ?').all(ledger.tenant, limit);
+    return rows.map((r)=>{
+        const file = asyncDeliverablePath(root, r.id);
+        return {
+            source: 'async-run',
+            id: r.id,
+            title: r.goal,
+            path: file,
+            status: r.status,
+            updated: r.updated,
+            bytes: r.deliverable?.length
+        };
+    });
+}
+async function listDeliverableFiles(root, limit) {
+    const dir = join(root, 'gotry-state', 'async');
+    let names = [];
+    try {
+        names = (await readdir(dir)).filter((n)=>n.endsWith('.deliverable.md'));
+    } catch  {
+        return [];
+    }
+    const entries = [];
+    for (const n of names.slice(0, limit * 2)){
+        const p = join(dir, n);
+        const st = await stat(p).catch(()=>null);
+        if (!st?.isFile()) continue;
+        entries.push({
+            source: 'async-run',
+            id: n.replace(/\.deliverable\.md$/, ''),
+            title: n.replace(/\.deliverable\.md$/, ''),
+            path: p,
+            status: existsSync(p.replace(/\.deliverable\.md$/, '.json')) ? 'pending-view' : 'legacy',
+            updated: new Date(st.mtimeMs).toISOString(),
+            bytes: st.size
+        });
+    }
+    return entries.sort((a, b)=>String(b.updated).localeCompare(String(a.updated)));
+}
+async function listCwdMarkdown(cwd, limit) {
+    let dirents;
+    try {
+        dirents = await readdir(cwd, {
+            withFileTypes: true
+        });
+    } catch  {
+        return [];
+    }
+    const entries = [];
+    for (const d of dirents){
+        if (!d.isFile() || !/\.md$/i.test(d.name) || d.name.startsWith('.')) continue;
+        const p = join(cwd, d.name);
+        const st = await stat(p).catch(()=>null);
+        if (!st) continue;
+        entries.push({
+            source: 'cwd-file',
+            id: d.name,
+            title: d.name.replace(/\.md$/i, ''),
+            path: p,
+            updated: new Date(st.mtimeMs).toISOString(),
+            bytes: st.size
+        });
+    }
+    return entries.sort((a, b)=>String(b.updated).localeCompare(String(a.updated))).slice(0, limit);
+}
+export async function listArtifacts(opts) {
+    const limit = Math.max(1, Math.min(opts.limit ?? 20, MAX_LIST));
+    const root = rootOf(opts.stateRoot);
+    const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+    const seenPath = new Set();
+    const merged = [];
+    for (const e of [
+        ...listRunsFromLedger(root, 'local', limit),
+        ...await listDeliverableFiles(root, limit),
+        ...await listCwdMarkdown(cwd, limit)
+    ]){
+        if (seenPath.has(e.path)) continue;
+        seenPath.add(e.path);
+        merged.push(e);
+    }
+    merged.sort((a, b)=>String(b.updated ?? '').localeCompare(String(a.updated ?? '')));
+    const total = merged.length;
+    return {
+        artifacts: merged.slice(0, limit),
+        total,
+        truncated: total > limit,
+        roots: [
+            root,
+            cwd
+        ]
+    };
+}
+export async function readArtifact(opts) {
+    const root = rootOf(opts.stateRoot);
+    const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+    const raw = String(opts.path ?? '').trim();
+    if (!raw) return {
+        ok: false,
+        error: 'path 必填(来自 gotry_artifacts_list 的 path,或异步工单 id)'
+    };
+    let text = null;
+    let filePath = '';
+    if (!raw.includes('/') && !raw.includes('\\') && !raw.includes('.')) {
+        const ledger = openLedgerIfExists(root, 'local');
+        const run = ledger?.db.prepare('SELECT id, goal, status, deliverable FROM workflow_runs WHERE id = ? AND tenant_id = ?').get(raw, ledger.tenant);
+        if (run?.deliverable) {
+            text = run.deliverable;
+            filePath = asyncDeliverablePath(root, raw);
+        } else {
+            const p = asyncDeliverablePath(root, raw);
+            if (existsSync(p)) {
+                filePath = p;
+                text = await readFile(p, 'utf-8');
+            }
+        }
+        if (text === null) return {
+            ok: false,
+            error: `工单 ${raw} 无 deliverable(未交付或不存在)`,
+            hint: '先 gotry_artifacts_list 看在册产物'
+        };
+    }
+    if (text === null) {
+        const candidates = isAbsolute(raw) ? [
+            resolve(raw)
+        ] : [
+            resolve(cwd, raw),
+            resolve(root, raw),
+            resolve(root, 'gotry-state', 'async', raw)
+        ];
+        const allowed = candidates.find((p)=>(underRoot(p, cwd) || underRoot(p, root)) && !hasDeniedSegment(p));
+        if (!allowed) {
+            return {
+                ok: false,
+                error: `路径越界:${raw}`,
+                hint: `只读 ${root} 与 dsh 工作目录内的文本产物`
+            };
+        }
+        const ext = allowed.slice(allowed.lastIndexOf('.') + 1).toLowerCase();
+        if (!TEXT_EXT_LANG[ext]) {
+            return {
+                ok: false,
+                error: `不支持的文件类型 .${ext}`,
+                hint: `白名单:${Object.keys(TEXT_EXT_LANG).join('/')}`
+            };
+        }
+        const st = await stat(allowed).catch(()=>null);
+        if (!st?.isFile()) return {
+            ok: false,
+            error: `文件不存在:${raw}`,
+            hint: '先 gotry_artifacts_list 看在册产物'
+        };
+        if (st.size > MAX_BYTES) return {
+            ok: false,
+            error: `文件过大(${st.size} bytes > ${MAX_BYTES})`
+        };
+        filePath = allowed;
+        text = await readFile(allowed, 'utf-8');
+    }
+    const allLines = text.split('\n');
+    const offset = Math.max(1, Math.min(opts.offset ?? 1, allLines.length));
+    const limit = Math.max(1, Math.min(opts.limit ?? MAX_WINDOW, MAX_WINDOW));
+    const slice = allLines.slice(offset - 1, offset - 1 + limit);
+    const ext = filePath.slice(filePath.lastIndexOf('.') + 1).toLowerCase();
+    return {
+        ok: true,
+        path: filePath,
+        offset,
+        lines: slice.map((t, i)=>({
+                number: offset + i,
+                text: t
+            })),
+        totalLines: allLines.length,
+        lang: TEXT_EXT_LANG[ext] ?? 'text',
+        content: slice.join('\n'),
+        windowed: allLines.length > offset - 1 + slice.length
+    };
+}
+
+
+//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/artifacts.ts

package/dist/capabilities/hbcli.js

@@ -1,13 +1,18 @@
 import { spawn } from 'node:child_process';
-export async function callHbcliJson(args, opts = {}) {
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function hbcliBinCandidates(bin, homeDir = homedir()) {
+    if (bin !== 'hbcli') return [
+        bin
+    ];
+    return [
+        bin,
+        join(homeDir, '.local/bin/hbcli'),
+        join(homeDir, '.staicli/current/hbcli')
+    ];
+}
+function attemptHbcli(bin, args, opts) {
     const started = Date.now();
-    const bin = opts.hbcliBin ?? 'hbcli';
-    const timeoutMs = opts.timeoutMs ?? 15_000;
-    const env = opts.env ?? 'uat';
-    const envVars = {
-        HOTELBYTE_ENV: env
-    };
-    if (opts.token) envVars['HOTELBYTE_TOKEN'] = opts.token;
     return new Promise((resolve)=>{
         let stdout = '';
         let stderr = '';
@@ -15,7 +20,7 @@ export async function callHbcliJson(args, opts = {}) {
         const child = spawn(bin, args, {
             env: {
                 ...process.env,
-                ...envVars
+                ...opts.envVars
             }
         });
         const timer = setTimeout(()=>{
@@ -28,10 +33,10 @@ export async function callHbcliJson(args, opts = {}) {
                     result: null,
                     evidence: `[实时API:hbcli@timeout@${new Date().toISOString()}]`,
                     latencyMs: Date.now() - started,
-                    error: `timeout after ${timeoutMs}ms`
+                    error: `timeout after ${opts.timeoutMs}ms`
                 });
             }
-        }, timeoutMs);
+        }, opts.timeoutMs);
         child.stdout.on('data', (d)=>{
             stdout += d.toString();
         });
@@ -82,11 +87,31 @@ export async function callHbcliJson(args, opts = {}) {
                 result: null,
                 evidence: `[实时API:hbcli@spawn_error@${new Date().toISOString()}]`,
                 latencyMs: Date.now() - started,
-                error: e.message
+                error: e.message,
+                spawnError: true
             });
         });
     });
 }
+export async function callHbcliJson(args, opts = {}) {
+    const env = opts.env ?? 'uat';
+    const envVars = {
+        HOTELBYTE_ENV: env
+    };
+    if (opts.token) envVars['HOTELBYTE_TOKEN'] = opts.token;
+    const callOpts = {
+        timeoutMs: opts.timeoutMs ?? 15_000,
+        env,
+        envVars
+    };
+    const candidates = hbcliBinCandidates(opts.hbcliBin ?? 'hbcli');
+    let last;
+    for (const bin of candidates){
+        last = await attemptHbcli(bin, args, callOpts);
+        if (!(last.spawnError && candidates.indexOf(bin) < candidates.length - 1)) return last;
+    }
+    return last;
+}
 export async function searchHotels(query, opts = {}) {
     const hbArgs = [
         'search',
@@ -110,6 +135,8 @@ export async function searchHotels(query, opts = {}) {
             summary: `${query.destination}:hbcli 实时返回${query.checkIn || query.checkOut ? '(日期不传上游 list,以当前窗口房价返回)' : ''}`
         };
     }
+    const rawReason = live.error ?? live.via;
+    const reason = /ENOENT/i.test(rawReason) ? '未安装 hbcli(可选实时源;npx gotry setup 可按官方脚本安装)' : rawReason;
     const fallback = opts.fallbackPath;
     if (fallback) {
         try {
@@ -124,19 +151,19 @@ export async function searchHotels(query, opts = {}) {
                     hotels: {
                         stays: matched
                     },
-                    summary: `${query.destination}:hbcli 不可用(${live.error ?? live.via}),降级到静态包,命中 ${matched.length} 个住宿块`
+                    summary: `${query.destination}:hbcli 实时源不可用(${reason}),已降级到静态包(公开渠道估算,非实时),命中 ${matched.length} 个住宿块`
                 };
             }
             return {
                 ...live,
                 hotels: null,
-                summary: `${query.destination}:hbcli 不可用(${live.error ?? live.via}),且静态包无「${query.destination}」住宿数据(静态包仅覆盖内置场景)`
+                summary: `${query.destination}:hbcli 实时源不可用(${reason}),且静态包无「${query.destination}」住宿数据(静态包仅覆盖内置场景)`
             };
         } catch  {}
     }
     return {
         ...live,
-        summary: `${query.destination}:hbcli 不可用且无静态包(仅返回错误)`
+        summary: `${query.destination}:hbcli 实时源不可用(${reason})且无静态包(仅返回错误)`
     };
 }
 export async function listDestinations(opts = {}) {