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

package/dist/src/index.js

@@ -23,6 +23,7 @@ import { flyaiSearch } from '../capabilities/flyai.js';
 import { sessionFlightSearch } from '../capabilities/session-search.js';
 import { sessionLogin } from '../capabilities/session-login.js';
 import { createConsentGate, approvalFromContext } from '../capabilities/session-consent.js';
+import { listArtifacts, readArtifact } from '../capabilities/artifacts.js';
 export const name = 'gotry-tools';
 export const inject = [
     'tools',
@@ -585,10 +586,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 +880,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,
@@ -1352,6 +1358,138 @@ export function apply(ctx, config) {
             };
         }
     }));
+    registerGuarded(defineTool({
+        name: 'gotry_artifacts_list',
+        description: 'List GoTry artifacts — deep-planning deliverables (async runs from the state ledger) plus agent-written markdown files ' + 'in the working directory (trip plans etc.). READ-ONLY discovery. ' + 'Use when the user asks to see/open/revisit a previously generated artifact ' + '(「看看刚才生成的行程」「上次的规划在哪」「打开那个 md」) — list first, then read with gotry_artifacts_read.',
+        parameters: {
+            query: {
+                type: 'json',
+                required: true,
+                description: '{ limit?: 20 }'
+            }
+        },
+        output: {
+            schema: {
+                type: 'json'
+            },
+            render: (_args, value)=>[
+                    {
+                        type: 'text',
+                        text: String(value.summary ?? JSON.stringify(value).slice(0, 600))
+                    }
+                ]
+        },
+        async execute (args, _exec) {
+            const q = unwrapQuery(args, 'limit');
+            const r = await listArtifacts({
+                stateRoot: config.stateRoot ?? '.',
+                limit: q.limit
+            });
+            const lines = r.artifacts.map((a)=>`- [${a.source}] ${a.title}${a.status ? `(${a.status})` : ''} — ${a.path}${a.updated ? ` @ ${a.updated.slice(0, 16).replace('T', ' ')}` : ''}`);
+            const summary = r.artifacts.length ? `在册产物 ${r.artifacts.length}/${r.total} 项${r.truncated ? '(截断,可加 limit)' : ''}:\n${lines.join('\n')}` : '无在册产物(异步深度规划交付与工作目录 md 文件都会出现在这里)';
+            return JSON.parse(JSON.stringify({
+                ok: true,
+                artifacts: r.artifacts,
+                total: r.total,
+                truncated: r.truncated,
+                summary
+            }));
+        },
+        presentCall: ()=>({
+                card: 'generic',
+                title: '列出产物',
+                kind: 'search'
+            }),
+        presentResult: (_args, value)=>{
+            const r = value;
+            return {
+                card: 'generic',
+                title: `产物:${r.total ?? 0} 项在册`,
+                content: [
+                    {
+                        type: 'text',
+                        text: String(r.summary ?? '')
+                    }
+                ]
+            };
+        }
+    }));
+    registerGuarded(defineTool({
+        name: 'gotry_artifacts_read',
+        description: 'Read one GoTry artifact as a line-numbered file view rendered directly in the chat UI. ' + 'Input: the path from gotry_artifacts_list, or a bare async ticket id (e.g. dp-xxxx). ' + 'Optional offset (1-based) / limit window for paging large files. ' + 'READ-ONLY; text artifacts only (md/txt/json/jsonl/csv/log/yaml).',
+        parameters: {
+            query: {
+                type: 'json',
+                required: true,
+                description: '{ path: "<list 返回的路径或工单 id>", offset?: 1, limit?: 400 }'
+            }
+        },
+        output: {
+            schema: {
+                type: 'json'
+            },
+            render: (_args, value)=>[
+                    {
+                        type: 'text',
+                        text: String(value.content ?? JSON.stringify(value).slice(0, 600))
+                    }
+                ]
+        },
+        async execute (args, _exec) {
+            const q = unwrapQuery(args, 'path');
+            if (!q.path) return JSON.parse(JSON.stringify({
+                ok: false,
+                error: 'path 必填(来自 gotry_artifacts_list)'
+            }));
+            const r = await readArtifact({
+                stateRoot: config.stateRoot ?? '.',
+                path: q.path,
+                offset: q.offset,
+                limit: q.limit
+            });
+            if (!r.ok) return JSON.parse(JSON.stringify(r));
+            return JSON.parse(JSON.stringify({
+                ...r,
+                summary: `${r.path}(${r.totalLines} 行)第 ${r.offset}-${r.offset + r.lines.length - 1} 行${r.windowed ? `(共 ${r.totalLines} 行,可翻页)` : ''}`
+            }));
+        },
+        presentCall: (args)=>({
+                card: 'generic',
+                title: `读产物:${String(args.query?.path ?? '')}`,
+                kind: 'read',
+                rawInput: args.query
+            }),
+        presentResult: (_args, value)=>{
+            const r = value;
+            if (!r.ok) {
+                return {
+                    card: 'generic',
+                    title: '读产物失败',
+                    content: [
+                        {
+                            type: 'text',
+                            text: String(r.error ?? '')
+                        }
+                    ]
+                };
+            }
+            return {
+                card: 'read',
+                title: r.path?.split('/').pop() ?? r.path ?? '',
+                path: r.path ?? '',
+                offset: r.offset ?? 1,
+                lines: r.lines ?? [],
+                totalLines: r.totalLines ?? 0,
+                lang: r.lang,
+                content: [
+                    {
+                        type: 'text',
+                        text: r.content ?? ''
+                    }
+                ]
+            };
+        }
+    }));
 }
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danceiny/gotry",
-  "version": "0.0.1-rc.13",
+  "version": "0.0.1-rc.15",
   "description": "GoTry — 从出发到下一次出发的 AI 旅行 Agent(dsh 插件)。npm 包入口 + vendored dsh runtime + 5 行 README 安装路径。",
   "type": "module",
   "main": "ts/src/index.ts",
@@ -20,6 +20,7 @@
     "ts/src/dsh-llm.ts",
     "ts/src/mock-llm.ts",
     "ts/src/state-ledger.ts",
+    "ts/src/booking-saga.ts",
     "ts/src/tool-packet.ts",
     "ts/src/memory-capture.ts",
     "ts/src/memory-utility.ts",
@@ -47,9 +48,11 @@
     "ts/package.json",
     "cordis.gotry-patch.yml",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE",
     "ts/capabilities/session-consent.ts",
-    "ts/capabilities/session-login.ts"
+    "ts/capabilities/session-login.ts",
+    "ts/capabilities/artifacts.ts"
   ],
   "engines": {
     "node": ">=22.0.0"

package/ts/capabilities/artifacts.ts

@@ -0,0 +1,235 @@
+/**
+ * 产物面(issue #25):agent 生成的文件不再只是「落在本地文件系统里的一个文件名」。
+ *
+ * 只读能力层,两个纯函数入口(dsh 工具 gotry_artifacts_list / gotry_artifacts_read 的实现):
+ *   - listArtifacts: 产物发现。权威源 = 账本 workflow_runs(ADR-15;无账本的旧 root 回退
+ *     扫描 gotry-state/async/*.deliverable.md 文件视图),外加 dsh 工作目录顶层 *.md
+ *     (agent 写出的行程/规划文件正落在这里——issue 截图里的 trip-2027-*.md 即此类)。
+ *   - readArtifact: 产物阅读。行窗口(offset/limit)+ 原始行号,输出 dsh read 卡所需的
+ *     全部字段({number,text}[] / totalLines / lang),UI 侧渲染为行号文件视图。
+ *
+ * 纪律:本层只读(不写任何文件;WriteGate 红线不涉及);读取范围白名单 =
+ * stateRoot 根 + dsh 工作目录(排除 node_modules/.git),扩展名白名单 =
+ * 文本类(md/txt/json/jsonl/csv/log/yaml/yml)——本工具是「产物查看」,不是通用文件浏览器。
+ */
+
+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.ts'
+
+export interface ArtifactEntry {
+  source: 'async-run' | 'cwd-file'
+  id: string
+  title: string
+  path: string
+  status?: string
+  updated?: string
+  bytes?: number
+}
+
+export interface ArtifactReadView {
+  ok: true
+  path: string
+  offset: number
+  lines: Array<{ number: number; text: string }>
+  totalLines: number
+  lang?: string
+  content: string
+  windowed: boolean
+}
+
+const MAX_LIST = 50
+const MAX_WINDOW = 400
+const MAX_BYTES = 2 * 1024 * 1024
+const TEXT_EXT_LANG: Record<string, string> = {
+  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: string): string {
+  return stateRoot === '.' ? process.cwd() : resolve(stateRoot)
+}
+
+function underRoot(p: string, root: string): boolean {
+  const r = resolve(root)
+  return p === r || p.startsWith(r + sep)
+}
+
+function hasDeniedSegment(p: string): boolean {
+  return p.split(sep).some(seg => DIR_DENY.includes(seg))
+}
+
+function asyncDeliverablePath(root: string, id: string): string {
+  return join(root, 'gotry-state', 'async', `${id}.deliverable.md`)
+}
+
+/** 账本 workflow_runs 是权威(listWorkflowRuns 只读 SELECT 直查,不为一个视图改 ledger 类)。 */
+function listRunsFromLedger(root: string, tenant: string, limit: number): ArtifactEntry[] {
+  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) as Array<{ id: string; goal: string; status: string; deliverable: string | null; updated: string }>
+  return rows.map(r => {
+    const file = asyncDeliverablePath(root, r.id)
+    return {
+      source: 'async-run' as const,
+      id: r.id,
+      title: r.goal,
+      path: file,
+      status: r.status,
+      updated: r.updated,
+      bytes: r.deliverable?.length,
+    }
+  })
+}
+
+/** 无账本旧 root 的兼容视图:直接扫 async 目录的 deliverable 文件(只读,与清扫合同同一目录)。 */
+async function listDeliverableFiles(root: string, limit: number): Promise<ArtifactEntry[]> {
+  const dir = join(root, 'gotry-state', 'async')
+  let names: string[] = []
+  try {
+    names = (await readdir(dir)).filter(n => n.endsWith('.deliverable.md'))
+  } catch {
+    return []
+  }
+  const entries: ArtifactEntry[] = []
+  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)))
+}
+
+/** dsh 工作目录顶层 *.md(agent 写出的行程规划等);非递归,排除 dotfiles。 */
+async function listCwdMarkdown(cwd: string, limit: number): Promise<ArtifactEntry[]> {
+  let dirents
+  try {
+    dirents = await readdir(cwd, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const entries: ArtifactEntry[] = []
+  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: {
+  stateRoot: string
+  cwd?: string
+  limit?: number
+}): Promise<{ artifacts: ArtifactEntry[]; total: number; truncated: boolean; roots: string[] }> {
+  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<string>()
+  const merged: ArtifactEntry[] = []
+  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] }
+}
+
+/**
+ * 读一个产物。path 三形态:
+ *   1. 裸工单 id(无 / 无 .)→ 账本 workflow_runs.deliverable(权威),文件视图缺失也能读;
+ *   2. list 返回的绝对/相对路径 → 限定在 stateRoot 根或 dsh 工作目录内(排除 node_modules/.git);
+ *   3. 相对文件名 → 先按 dsh 工作目录顶层,再按 gotry-state/async/ 找。
+ * 窗口:offset(1 起)/limit(≤400 行);超窗返回 windowed:true,UI 用 read 卡渲染行号视图。
+ */
+export async function readArtifact(opts: {
+  stateRoot: string
+  cwd?: string
+  path: string
+  offset?: number
+  limit?: number
+}): Promise<ArtifactReadView | { ok: false; error: string; hint?: string }> {
+  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: string | null = null
+  let filePath = ''
+
+  // 1) 裸工单 id:账本权威读(文件视图缺失不挡阅读)
+  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) as { deliverable: string | null } | undefined
+    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 看在册产物' }
+  }
+
+  // 2) 路径形态:目录白名单 + 扩展名白名单
+  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,
+  }
+}

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 命令可独立调通) */