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

package/bin/gotry-bootstrap.js

@@ -0,0 +1,126 @@
+#!/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)
+ *
+ * 用法:
+ *   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 本体——能力层各有降级路径(静态包/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 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}`)
+    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 跳过')
+  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/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 = {}) {

package/dist/scripts/bootstrap-tests.js

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+const repoRoot = join(import.meta.dirname, '..', '..');
+const bootstrap = join(repoRoot, 'bin', 'gotry-bootstrap.js');
+function runBootstrap(extraArgs, extraEnv) {
+    try {
+        const out = execFileSync('node', [
+            bootstrap,
+            ...extraArgs
+        ], {
+            encoding: 'utf-8',
+            timeout: 60_000,
+            env: {
+                ...process.env,
+                ...extraEnv
+            }
+        });
+        return {
+            code: 0,
+            out
+        };
+    } catch (e) {
+        const err = e;
+        return {
+            code: err.status ?? 1,
+            out: err.stdout ?? ''
+        };
+    }
+}
+const c1 = runBootstrap([
+    '--check-only'
+], {});
+assert.equal(c1.code, 0, `--check-only 应 exit 0,实际 ${c1.code}\n${c1.out}`);
+assert.ok(c1.out.includes('hbcli'), '报告应含 hbcli 节');
+assert.ok(c1.out.includes('agent-reach'), '报告应含 agent-reach 节');
+assert.ok(c1.out.includes('flyai'), '报告应含 flyai(无需安装)节');
+console.log('1. --check-only 探测报告 exit 0(hbcli/agent-reach/flyai 三节齐)OK');
+const c2 = runBootstrap([
+    '--auto'
+], {
+    GOTRY_SETUP_SKIP: '1'
+});
+assert.equal(c2.code, 0, '--auto 跳过态应 exit 0(永不挡 npm install)');
+assert.ok(c2.out.includes('跳过'), '应输出跳过说明');
+console.log('2. --auto + GOTRY_SETUP_SKIP=1 → exit 0(安装永不失败)OK');
+const c3 = runBootstrap([], {
+    GOTRY_SETUP_SKIP: '1'
+});
+assert.equal(c3.code, 0, '显式模式跳过态应 exit 0');
+assert.ok(c3.out.includes('跳过'), '应输出跳过说明');
+console.log('3. 显式模式 + GOTRY_SETUP_SKIP=1 → exit 0 OK');
+console.log('BOOTSTRAP TESTS: 3/3 OK(探测报告/跳过开关/postinstall 非致命)');
+
+
+//# sourceURL=/Users/bytedance/work/gotry/ts/scripts/bootstrap-tests.ts

package/dist/scripts/flyai-tests.js

@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import { writeFile, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { flyaiSearch } from '../capabilities/flyai.js';
+const tmp = await mkdtemp(join(tmpdir(), 'flyai-test-'));
+async function fakeCli(name, code, payload) {
+    const p = join(tmp, name);
+    await writeFile(p, `#!/bin/sh\necho '${payload}'\nexit ${code}\n`, {
+        mode: 0o755
+    });
+    return p;
+}
+const base = {
+    kind: 'flight',
+    origin: '上海',
+    destination: '丽江',
+    depDate: '2026-10-01'
+};
+const sentinelBin = await fakeCli('flyai-sentinel', 0, '{"message":"SentinelBlockException: flow control"}');
+const s = await flyaiSearch({
+    ...base,
+    cliBin: sentinelBin,
+    timeoutMs: 5000
+});
+assert.equal(s.ok, false, 'Sentinel 形状应 ok=false');
+assert.equal(s.verdict, 'error', `Sentinel 形状应判 error,实际 ${s.verdict}`);
+assert.match(s.error ?? '', /sentinel/i, `error 应保留 sentinel 字样(供上层限流识别),实际 ${s.error}`);
+assert.match(s.evidence, /\[实时API:flyai@error@/, 'error 证据链标注');
+console.log('1. Sentinel 非业务形状 → error(非静默 miss)OK');
+const missBin = await fakeCli('flyai-miss', 0, '{"data":{"itemList":[]}}');
+const m = await flyaiSearch({
+    ...base,
+    cliBin: missBin,
+    timeoutMs: 5000
+});
+assert.equal(m.ok, true, '业务空形状 ok=true');
+assert.equal(m.verdict, 'miss', `空 itemList 应判 miss,实际 ${m.verdict}`);
+assert.match(m.evidence, /0\/0 flight options/, 'miss 证据链 0/0');
+console.log('2. 业务空形状 → miss(0/0)OK');
+const hitPayload = JSON.stringify({
+    data: {
+        itemList: [
+            {
+                journeys: [
+                    {
+                        segments: [
+                            {
+                                marketingTransportNo: '9C6617',
+                                marketingTransportName: '吉祥航空',
+                                depDateTime: '2026-10-01 07:55',
+                                arrDateTime: '2026-10-01 11:20',
+                                depStationName: '浦东T2',
+                                arrStationName: '丽江三义',
+                                duration: 205
+                            }
+                        ]
+                    }
+                ],
+                ticketPrice: '580',
+                jumpUrl: 'https://www.fliggy.com/demo'
+            }
+        ]
+    }
+});
+const hitBin = await fakeCli('flyai-hit', 0, hitPayload);
+const h = await flyaiSearch({
+    ...base,
+    cliBin: hitBin,
+    timeoutMs: 5000
+});
+assert.equal(h.verdict, 'hit', `业务条目应判 hit,实际 ${h.verdict}`);
+assert.equal(h.options?.length, 1, '1 个选项');
+assert.equal(h.options[0].no, '9C6617');
+assert.equal(h.options[0].price, 580, '价格数值解析');
+assert.equal(h.options[0].depStation, '浦东T2');
+assert.match(h.evidence, /1\/1 flight options/, 'hit 证据链 1/1');
+console.log('3. 业务命中 → hit(9C6617 ¥580)OK');
+const failBin = await fakeCli('flyai-fail', 1, '');
+const f = await flyaiSearch({
+    ...base,
+    cliBin: failBin,
+    timeoutMs: 5000
+});
+assert.equal(f.ok, false);
+assert.equal(f.verdict, 'error', '非零退出应判 error');
+console.log('4. 非零退出 → error OK');
+await rm(tmp, {
+    recursive: true,
+    force: true
+});
+console.log('FLYAI TESTS: 4/4 OK(离线假 CLI:Sentinel→error / 空 itemList→miss / 命中→hit / exit≠0→error)');
+
+
+//# sourceURL=/Users/bytedance/work/gotry/ts/scripts/flyai-tests.ts

package/dist/scripts/hbcli-tests.js

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
 import { writeFile, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { callHbcliJson, searchHotels } from '../capabilities/hbcli.js';
+import { callHbcliJson, searchHotels, hbcliBinCandidates } from '../capabilities/hbcli.js';
 const tmp = await mkdtemp(join(tmpdir(), 'hbcli-test-'));
 async function fakeBin(name, code, payload) {
     const p = join(tmp, name);
@@ -112,11 +112,36 @@ const r5 = await searchHotels({
 });
 assert.equal(r5.hotels ?? null, null, '无目的地命中时 hotels 为 null(不整包倾倒)');
 assert.match(r5.summary, /无「巴黎」住宿数据/, 'summary 明示静态包无该目的地');
-await rm(tmp, {
+const r6 = await searchHotels({
+    destination: '普吉'
+}, {
+    hbcliBin: '/nope/hbcli',
+    fallbackPath: fallback
+});
+assert.equal(r6.via, 'hbcli-error', 'no-binary path');
+assert.ok(r6.summary.includes('未安装 hbcli'), `summary 应人话化 ENOENT,实际 ${r6.summary}`);
+assert.ok(r6.summary.includes('gotry setup'), '应带 gotry setup 安装指引');
+assert.ok(r6.summary.includes('降级到静态包'), '人话化后仍指明降级到静态包');
+console.log(`6. ENOENT 人话化 OK:${r6.summary}`);
+{
+    const home = '/home/t';
+    assert.deepEqual(hbcliBinCandidates('hbcli', home), [
+        'hbcli',
+        '/home/t/.local/bin/hbcli',
+        '/home/t/.staicli/current/hbcli'
+    ], '默认名应带安装位候选');
+    assert.deepEqual(hbcliBinCandidates('hbcli-not-on-path', home), [
+        'hbcli-not-on-path'
+    ], '自定义名单候选(测试确定性)');
+    assert.deepEqual(hbcliBinCandidates('/nope/hbcli', home), [
+        '/nope/hbcli'
+    ], '绝对路径单候选');
+    console.log('7. hbcliBinCandidates(~/.local/bin + ~/.staicli/current 回退)OK');
+}await rm(tmp, {
     recursive: true,
     force: true
 });
-console.log('HBCLI TESTS: 6/6 OK (happy / error / no-binary / fallback-filter / fallback-no-match / v0.3.0 旗标回归)');
+console.log('HBCLI TESTS: 8/8 OK (happy / error / no-binary / fallback-filter / fallback-no-match / v0.3.0 旗标回归 / ENOENT 人话化 / 候选路径)');
 
 
 //# sourceURL=/Users/bytedance/work/gotry/ts/scripts/hbcli-tests.ts

package/dist/src/index.js

@@ -585,10 +585,14 @@ export function apply(ctx, config) {
             }),
         presentResult: (_args, value)=>{
             const r = value;
-            const n = Array.isArray(r.hotels) ? r.hotels.length : 0;
+            const h = r.hotels;
+            const liveCount = Array.isArray(h) ? h.length : 0;
+            const stays = !Array.isArray(h) && h && typeof h === 'object' ? h.stays : undefined;
+            const staticCount = Array.isArray(stays) ? stays.length : 0;
+            const tag = r.via === 'hbcli-realtime' ? liveCount ? `实时 ${liveCount} 家` : '实时' : staticCount ? `静态包 ${staticCount} 块` : liveCount ? `${liveCount} 家` : '无结果';
             return {
                 card: 'generic',
-                title: `酒店:${r.destination ?? ''} ${n ? `${n} 家(${r.via === 'hbcli-realtime' ? '实时' : '静态包'})` : '无结果'}`,
+                title: `酒店:${r.destination ?? ''} ${tag}`,
                 content: [
                     {
                         type: 'text',
@@ -875,7 +879,8 @@ export function apply(ctx, config) {
                 depDate: q.date
             });
             const top = (r.options ?? []).slice(0, 8).map((o)=>`${o.no} ${o.name} ${o.depDateTime.slice(11, 16)}→${o.arrDateTime.slice(11, 16)} ¥${o.price}`);
-            const summary = r.verdict === 'hit' ? `${q.from}→${q.to} ${q.date} ${kind === 'flight' ? '机票' : '火车票'}(飞猪官方只读)前 ${top.length} 条:\n${top.join('\n')}\n${r.evidence}` : `${q.from}→${q.to} ${q.date} 无结果或失败:${r.error ?? 'miss'} ${r.evidence}`;
+            const label = kind === 'flight' ? '机票' : '火车票';
+            const summary = r.verdict === 'hit' ? `${q.from}→${q.to} ${q.date} ${label}(飞猪官方只读)前 ${top.length} 条:\n${top.join('\n')}\n${r.evidence}` : r.verdict === 'miss' ? `${q.from}→${q.to} ${q.date} ${label}官方通道正常返回 0 条(常见原因:航线未开放/当日售罄)。${r.evidence}` : `${q.from}→${q.to} ${q.date} ${label}检索失败(可能限流/网络):${r.error ?? ''} ${r.evidence}`;
             return JSON.parse(JSON.stringify({
                 ...r,
                 kind,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danceiny/gotry",
-  "version": "0.0.1-rc.13",
+  "version": "0.0.1-rc.14",
   "description": "GoTry — 从出发到下一次出发的 AI 旅行 Agent(dsh 插件)。npm 包入口 + vendored dsh runtime + 5 行 README 安装路径。",
   "type": "module",
   "main": "ts/src/index.ts",
@@ -47,6 +47,7 @@
     "ts/package.json",
     "cordis.gotry-patch.yml",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE",
     "ts/capabilities/session-consent.ts",
     "ts/capabilities/session-login.ts"

package/ts/capabilities/hbcli.ts

@@ -13,9 +13,11 @@
  */
 
 import { spawn } from 'node:child_process'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 
 export interface HbcliCallOptions {
-  /** hbcli 二进制路径(默认 'hbcli',依赖 PATH) */
+  /** hbcli 二进制路径(默认 'hbcli',依赖 PATH;~/.local/bin 等已知安装位自动回退) */
   hbcliBin?: string
   /** 超时(ms) */
   timeoutMs?: number
@@ -43,23 +45,29 @@ export interface HbcliCallResult {
   error?: string
 }
 
-/** 通用 hbcli JSON 调用封装:失败不抛,而是返回降级结果 */
-export async function callHbcliJson(
+/**
+ * hbcli 二进制候选路径(gotry setup 按官方脚本装到 ~/.local/bin/hbcli,
+ * symlink 指向 ~/.staicli/current/hbcli——当 PATH 不含 ~/.local/bin 时裸名
+ * spawn 仍 ENOENT,按已知安装位回退)。仅对默认名 'hbcli' 扩展;显式自定义
+ * 名(如测试注入的不存在路径)不扩展,保持配置即所用的可测性。
+ */
+export function hbcliBinCandidates(bin: string, homeDir: string = homedir()): string[] {
+  if (bin !== 'hbcli') return [bin]
+  return [bin, join(homeDir, '.local/bin/hbcli'), join(homeDir, '.staicli/current/hbcli')]
+}
+
+/** 单个候选的一次 spawn 封装:失败不抛,返回降级结果(spawnError 标记 ENOENT 类失败供上层换候选) */
+function attemptHbcli(
+  bin: string,
   args: string[],
-  opts: HbcliCallOptions = {},
-): Promise<HbcliCallResult> {
+  opts: Required<Pick<HbcliCallOptions, 'timeoutMs' | 'env'>> & { envVars: Record<string, string> },
+): Promise<HbcliCallResult & { spawnError?: boolean }> {
   const started = Date.now()
-  const bin = opts.hbcliBin ?? 'hbcli'
-  const timeoutMs = opts.timeoutMs ?? 15_000
-  const env = opts.env ?? 'uat'
-  const envVars: Record<string, string> = { HOTELBYTE_ENV: env }
-  if (opts.token) envVars['HOTELBYTE_TOKEN'] = opts.token
-
   return new Promise((resolve) => {
     let stdout = ''
     let stderr = ''
     let settled = false
-    const child = spawn(bin, args, { env: { ...process.env, ...envVars } })
+    const child = spawn(bin, args, { env: { ...process.env, ...opts.envVars } })
     const timer = setTimeout(() => {
       if (!settled) {
         settled = true
@@ -67,10 +75,10 @@ export async function callHbcliJson(
         resolve({
           via: 'hbcli-error', exitCode: -1, result: null,
           evidence: `[实时API:hbcli@timeout@${new Date().toISOString()}]`,
-          latencyMs: Date.now() - started, error: `timeout after ${timeoutMs}ms`,
+          latencyMs: Date.now() - started, error: `timeout after ${opts.timeoutMs}ms`,
         })
       }
-    }, timeoutMs)
+    }, opts.timeoutMs)
     child.stdout.on('data', (d: Buffer) => { stdout += d.toString() })
     child.stderr.on('data', (d: Buffer) => { stderr += d.toString() })
     child.on('close', (code) => {
@@ -105,16 +113,35 @@ export async function callHbcliJson(
       if (settled) return
       settled = true
       clearTimeout(timer)
-      // ENOENT (二进制不存在) 等也走降级路径
+      // ENOENT (二进制不存在) 等也走降级路径;spawnError 供上层按候选路径重试
       resolve({
         via: 'hbcli-error', exitCode: -1, result: null,
         evidence: `[实时API:hbcli@spawn_error@${new Date().toISOString()}]`,
-        latencyMs: Date.now() - started, error: (e as Error).message,
+        latencyMs: Date.now() - started, error: (e as Error).message, spawnError: true,
       })
     })
   })
 }
 
+/** 通用 hbcli JSON 调用封装:失败不抛,而是返回降级结果 */
+export async function callHbcliJson(
+  args: string[],
+  opts: HbcliCallOptions = {},
+): Promise<HbcliCallResult> {
+  const env = opts.env ?? 'uat'
+  const envVars: Record<string, string> = { 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: HbcliCallResult & { spawnError?: boolean } | undefined
+  for (const bin of candidates) {
+    last = await attemptHbcli(bin, args, callOpts)
+    // spawn 级失败(ENOENT 等)且还有候选 → 换下一个已知安装位;其余失败(退码/超时)无重试意义
+    if (!(last.spawnError && candidates.indexOf(bin) < candidates.length - 1)) return last
+  }
+  return last!
+}
+
 /** 高层语义化封装:酒店列表查询(down-tier to 静态包 + 证据链标注) */
 export async function searchHotels(
   query: { destination: string; checkIn?: string; checkOut?: string; adults?: number },
@@ -129,6 +156,11 @@ export async function searchHotels(
   if (live.via === 'hbcli-realtime') {
     return { ...live, hotels: live.result, summary: `${query.destination}:hbcli 实时返回${query.checkIn || query.checkOut ? '(日期不传上游 list,以当前窗口房价返回)' : ''}` }
   }
+  // 降级原因人话化(issue #24):hbcli 未安装时按 gotry setup 指引(npm 安装期已
+  // 自动跑过官方脚本;PATH 未含 ~/.local/bin 时上方候选路径也已兜住),
+  // 裸 "spawn hbcli ENOENT" 读起来像工具坏了——实际静态包降级是设计行为
+  const rawReason = live.error ?? live.via
+  const reason = /ENOENT/i.test(rawReason) ? '未安装 hbcli(可选实时源;npx gotry setup 可按官方脚本安装)' : rawReason
   // 降级:读静态包,按目的地过滤命中的住宿块(issue #24)——整包倾倒会把无关场景
   // (深圳/普吉/曼谷/云南/大理混装)灌给模型且不指明哪块相关;包内无该目的地时明示
   // 「无数据」而不是伪装成可用结果。
@@ -144,17 +176,17 @@ export async function searchHotels(
         return {
           ...live,
           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 不可用且无静态包(仅返回错误)` }
+  return { ...live, summary: `${query.destination}:hbcli 实时源不可用(${reason})且无静态包(仅返回错误)` }
 }
 
 /** 高层语义化封装:目的地列表(无数据依赖,通常 hbcli dest 命令可独立调通) */