@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/ts/capabilities/agent-reach-deep.ts

@@ -0,0 +1,114 @@
+/**
+ * agent-reach 深度能力层:yt-dlp 字幕提取 + gh 仓库搜索(可选工具,系统有就调,没有降级)。
+ *
+ * 与 agent-reach.ts(r.jina.ai 读网页)互补——dsh LLM 的 3 个 agent-reach 工具:
+ *   - gotry_web_search      → r.jina.ai(已落,零配置)
+ *   - gotry_video_subtitle  → yt-dlp(本文件;系统装了就调,没装降级提示安装方式)
+ *   - gotry_github_search   → gh(本文件;系统装了就调,没装降级提示安装方式)
+ *
+ * 契约(与 anything/weather/opensky/agent-reach 同构,L4 不变量):
+ *   - 永不抛错:spawn 失败/超时/工具未装一律降级返回;
+ *   - 证据链标注:[agent-reach:yt-dlp@ts] / [agent-reach:gh@ts] / [@error@ts] / [@not-installed@ts];
+ *   - 零强制依赖:不 npm install 任何东西,用系统 PATH 里的二进制。
+ */
+
+import { spawn } from 'node:child_process'
+
+export interface SpawnQuery {
+  /** 完整命令参数(不含 bin) */
+  args: string[]
+  /** 二进制名;默认按能力层定 */
+  bin?: string
+  /** 超时(ms);默认 30_000 */
+  timeoutMs?: number
+}
+
+export interface SpawnResult {
+  ok: boolean
+  /** found / not-installed / error / timeout */
+  verdict: 'found' | 'not-installed' | 'error' | 'timeout'
+  evidence: string
+  latencyMs: number
+  stdout?: string
+  stderr?: string
+}
+
+function run(bin: string, args: string[], timeoutMs: number): Promise<{ code: number | null; stdout: string; stderr: string; err?: string; timedOut: boolean }> {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { env: process.env })
+    let stdout = ''
+    let stderr = ''
+    let err: string | undefined
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      try { child.kill('SIGKILL') } catch { /* ignore */ }
+    }, timeoutMs)
+    child.stdout.on('data', (d: Buffer) => { stdout += d.toString() })
+    child.stderr.on('data', (d: Buffer) => { stderr += d.toString() })
+    child.on('error', (e) => { err = (e as Error).message })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      resolve({ code, stdout, stderr, err, timedOut })
+    })
+  })
+}
+
+const ts = () => new Date().toISOString()
+
+/** yt-dlp 提取视频字幕(YouTube/B站;系统需已装 yt-dlp) */
+export async function videoSubtitle(q: { url: string; lang?: string; timeoutMs?: number }): Promise<SpawnResult & { subtitles?: string }> {
+  const started = Date.now()
+  const lang = q.lang ?? 'zh-Hans,zh,en'
+  const args = ['--write-sub', '--write-auto-sub', '--sub-langs', lang, '--skip-download', '--sub-format', 'vtt', '-o', '/tmp/gotry-sub-%(id)s', q.url]
+  const r = await run('yt-dlp', args, q.timeoutMs ?? 60_000)
+  const latencyMs = Date.now() - started
+  // not-installed: ENOENT
+  if (r.err?.includes('ENOENT')) {
+    return { ok: false, verdict: 'not-installed', evidence: `[agent-reach:yt-dlp@not-installed@${ts()}]`, latencyMs, stderr: 'yt-dlp 未安装;装法: brew install yt-dlp 或 pip install yt-dlp' }
+  }
+  if (r.timedOut) {
+    return { ok: false, verdict: 'timeout', evidence: `[agent-reach:yt-dlp@error@${ts()}] timeout`, latencyMs }
+  }
+  if (r.code !== 0) {
+    return { ok: false, verdict: 'error', evidence: `[agent-reach:yt-dlp@error@${ts()}] exit ${r.code}`, latencyMs, stderr: r.stderr.slice(0, 400) }
+  }
+  // 从 stdout 抓写入的字幕文件名
+  const m = r.stdout.match(/Writing subtitles to:\s*(\S+)/)
+  if (!m) {
+    return { ok: false, verdict: 'error', evidence: `[agent-reach:yt-dlp@error@${ts()}] no subtitle file in output`, latencyMs, stderr: r.stdout.slice(0, 300) }
+  }
+  const { readFile } = await import('node:fs/promises')
+  let subtitles: string | undefined
+  try {
+    subtitles = (await readFile(m[1]!, 'utf-8')).slice(0, 8000)
+  } catch { /* 字幕文件读失败保留 undefined */ }
+  return { ok: true, verdict: 'found', evidence: `[agent-reach:yt-dlp@${ts()}]`, latencyMs, stdout: r.stdout.slice(0, 400), subtitles }
+}
+
+/** gh 搜索 GitHub 仓库(系统需已装 gh 并登录) */
+export async function githubSearch(q: { query: string; limit?: number; timeoutMs?: number }): Promise<SpawnResult & { repos?: Array<{ name: string; description?: string; stars?: number; url?: string }> }> {
+  const started = Date.now()
+  const limit = q.limit ?? 5
+  const args = ['search', 'repos', q.query, '--json', 'fullName,description,stargazersCount,url', '--limit', String(limit)]
+  const r = await run('gh', args, q.timeoutMs ?? 30_000)
+  const latencyMs = Date.now() - started
+  if (r.err?.includes('ENOENT')) {
+    return { ok: false, verdict: 'not-installed', evidence: `[agent-reach:gh@not-installed@${ts()}]`, latencyMs, stderr: 'gh 未安装;装法: brew install gh && gh auth login' }
+  }
+  if (r.timedOut) {
+    return { ok: false, verdict: 'timeout', evidence: `[agent-reach:gh@error@${ts()}] timeout`, latencyMs }
+  }
+  if (r.code !== 0) {
+    return { ok: false, verdict: 'error', evidence: `[agent-reach:gh@error@${ts()}] exit ${r.code}`, latencyMs, stderr: r.stderr.slice(0, 300) }
+  }
+  try {
+    const repos = JSON.parse(r.stdout) as Array<{ fullName: string; description?: string; stargazersCount?: number; url?: string }>
+    return {
+      ok: true, verdict: 'found', evidence: `[agent-reach:gh@${ts()}]`, latencyMs,
+      repos: repos.map(x => ({ name: x.fullName, description: x.description, stars: x.stargazersCount, url: x.url })),
+    }
+  } catch {
+    return { ok: false, verdict: 'error', evidence: `[agent-reach:gh@error@${ts()}] parse fail`, latencyMs, stderr: r.stdout.slice(0, 300) }
+  }
+}

package/ts/capabilities/agent-reach.ts

@@ -0,0 +1,198 @@
+/**
+ * agent-reach wrapper —— 上游 Panniantong/Agent-Reach 的薄壳(零渠道知识)。
+ *
+ * 分工(2026-08-22 founder 纠偏「wrapper 不是 router」):
+ *   - 知识(渠道清单/方法签名/setup 指引)→ 上游:agent_reach.channels 注册表 + Channel.check() + guides/
+ *   - 决策(该调哪个渠道哪个方法)      → dsh 里的 LLM(靠本 wrapper 的自描述错误拿清单)
+ *   - 管道(spawn/超时/永不抛错/证据链) → 本文件 + agent-reach-bridge.py,上游加渠道零改动
+ *
+ * 上游设计意图(Channel 基类原话):"After installation, agents call upstream tools directly."
+ *   - python-API 渠道(web.read / v2ex.get_hot_topics / xueqiu.get_stock_quote / youtube.transcribe ...)
+ *     走本文件 reach() 的反射桥
+ *   - 外部 CLI 工具渠道(github→gh / youtube 字幕→yt-dlp 等)由专用 dsh 工具(gotry_github_search /
+ *     gotry_video_subtitle,见 agent-reach-deep.ts)充当执行面;上游无 python API 的不再自行拼命令
+ *
+ * 契约(L4 不变量,与 anything/weather/opensky 同构):
+ *   - 永不抛错;verdict: found / not-installed / needs-setup / error
+ *   - needs-setup 的 setup 文案 = 上游 check() 原话透传,不转述
+ *   - 证据链 [agent-reach:<channel>.<method>@ts]
+ *   - 失败人话化（#559）：进程级失败与桥结构化错误均走分类文案，不漏 traceback、stderr、凭证样原话；setup（上游 check() 原话）与 inventory（上游注册表）透传契约不变
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+export interface ReachResult {
+  channel: string
+  method: string
+  ok: boolean
+  verdict: 'found' | 'not-installed' | 'needs-setup' | 'error'
+  evidence: string
+  latencyMs: number
+  data?: unknown
+  /** 上游清单(未知渠道→渠道表;未知方法→方法签名表),LLM 据此自纠 */
+  inventory?: Record<string, unknown>
+  /** 上游 check() 原话(仅 needs-setup 时) */
+  setup?: string
+  error?: string
+}
+
+const ts = () => new Date().toISOString()
+const repoRoot = () => resolve(import.meta.dirname, '..', '..')
+const venvPython = () => resolve(repoRoot(), '.venv/bin/python')
+const bridgeScript = () => resolve(import.meta.dirname, 'agent-reach-bridge.py')
+
+function run(bin: string, args: string[], timeoutMs: number): Promise<{ code: number | null; stdout: string; stderr: string; err?: string; timedOut: boolean }> {
+  return new Promise((resolveRun) => {
+    const child = spawn(bin, args, { env: process.env })
+    let stdout = ''
+    let stderr = ''
+    let err: string | undefined
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      try { child.kill('SIGKILL') } catch { /* ignore */ }
+    }, timeoutMs)
+    child.stdout.on('data', (d: Buffer) => { stdout += d.toString() })
+    child.stderr.on('data', (d: Buffer) => { stderr += d.toString() })
+    child.on('error', (e) => { err = (e as Error).message })
+    child.on('close', (code) => { clearTimeout(timer); resolveRun({ code, stdout, stderr, err, timedOut }) })
+  })
+}
+
+interface BridgeOut {
+  ok?: boolean
+  data?: unknown
+  error?: string
+  check?: { status?: string; message?: string }
+  channels?: Record<string, string>
+  methods?: Record<string, string>
+  channel?: Record<string, unknown>
+}
+
+/**
+ * 桥进程级失败人话化(对齐 anything.ts failureReason 口径;issue #559 第五缺口)。
+ *
+ * 这条消息会直接渲染进用户回复(gotry_agent_reach 的 error 分支、gotry_web_search 的
+ * unavailable 括号),所以 Python traceback、上游凭证片段这类桥进程 stderr 原文不能出现——
+ * 桥进程失败是可选实时源的降级设计行为,不是工具坏了;无法归类时也要说清发生了什么。
+ */
+function bridgeFailureReason(r: { code: number | null; stdout: string; timedOut: boolean }, timeoutMs: number): string {
+  if (r.timedOut) return `agent-reach 反射桥超时（>${timeoutMs}ms，本轮按降级处理；可调大 timeoutMs 或稍后再试）`
+  if (!r.stdout.trim()) {
+    const why = r.code == null ? '进程异常结束' : `退出码 ${r.code}`
+    return `agent-reach 反射桥未返回可判定结果（${why}，本轮按降级处理）；整体装配状态可用 gotry_doctor 查看`
+  }
+  return `agent-reach 反射桥输出无法解析（退出码 ${r.code ?? '未知'}，本轮按降级处理）；整体装配状态可用 gotry_doctor 查看`
+}
+
+/** 通用入口:反射调上游任意渠道方法;永不抛错 */
+export async function reach(q: { channel: string; method: string; args?: string[] | string; timeoutMs?: number; /** 测试注入:替换 .venv/bin/python(确定性失败面;与 anything.ts hbcliBin 同构) */ pythonBin?: string }): Promise<ReachResult> {
+  const started = Date.now()
+  const evidence = (state: string) => `[agent-reach:${q.channel}.${q.method}@${state === 'found' ? ts() : `${state}@${ts()}`}]`
+  const base = { channel: q.channel, method: q.method }
+
+  if (!q.channel || !q.method) {
+    return { ...base, ok: false, verdict: 'error', evidence: evidence('error'), latencyMs: 0, error: 'channel 与 method 必填(渠道/方法清单:先随便调一次,inventory 会带回上游清单)' }
+  }
+  const py = q.pythonBin ?? venvPython()
+  if (!existsSync(py)) {
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs: 0, setup: 'gotry .venv 缺 python——可选依赖未装配。补装:终端跑 npx @danceiny/gotry doctor --fix,或让用户看体检报告 npx @danceiny/gotry doctor' }
+  }
+  const args = Array.isArray(q.args) ? q.args : (q.args ? q.args.split(/\s+/).filter(Boolean) : [])
+  const timeoutMs = q.timeoutMs ?? 30_000
+  const r = await run(py, [bridgeScript(), q.channel, q.method, ...args], timeoutMs)
+  const latencyMs = Date.now() - started
+
+  let parsedRaw: unknown
+  try {
+    parsedRaw = JSON.parse((r.stdout || '').trim().split('\n').filter(Boolean).pop() ?? '{}')
+  } catch { /* 走下面的兜底 */ }
+  // 形状闸:JSON 合法但不是对象(null/数组/标量)同不可解析处理,永不抛错(#559)
+  const parsed: BridgeOut = typeof parsedRaw === 'object' && parsedRaw !== null && !Array.isArray(parsedRaw) ? parsedRaw as BridgeOut : {}
+  // 桥结构化 error 是任意上游异常原话(可含凭证 URL/traceback),只在判定分支用,不透传用户面(#559)
+  const bridgeError = typeof parsed.error === 'string' && parsed.error.length > 0 ? parsed.error : undefined
+
+  if (r.err?.includes('ENOENT')) {
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv/bin/python 不可执行——补装:终端跑 npx @danceiny/gotry doctor --fix' }
+  }
+  if (parsed.ok === true) {
+    return { ...base, ok: true, verdict: 'found', evidence: evidence('found'), latencyMs, data: parsed.data }
+  }
+  // 上游 agent_reach 包未装(bridge 自己的 exit 3 输出)
+  if (bridgeError?.includes('agent_reach 未安装')) {
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv 缺 agent-reach 包——补装:终端跑 npx @danceiny/gotry doctor --fix' }
+  }
+  // 未知渠道/方法:自描述,附上游清单(不拦 LLM,让它看清单自纠);error 用自身查询值给安全
+  // 描述——桥报错文案是任意上游文本不透传,清单本体不受影响(#559)
+  if (r.code === 2) {
+    return {
+      ...base, ok: false, verdict: 'error', evidence: evidence('error'), latencyMs,
+      error: `${q.channel}.${q.method} 不在上游 agent-reach 渠道/方法清单内——按返回 inventory 清单改正渠道名/方法名后重调`,
+      inventory: parsed.channels ? { channels: parsed.channels } : { channel: parsed.channel, methods: parsed.methods },
+    }
+  }
+  // 调用抛错:若上游 check() 给出 warn/off,把上游原话作为 setup 透传;error 走分类安全文案
+  const checkStatus = parsed.check?.status
+  if (checkStatus === 'warn' || checkStatus === 'off') {
+    return {
+      ...base, ok: false, verdict: 'needs-setup', evidence: evidence('needs-setup'), latencyMs,
+      error: `${q.channel}.${q.method} 调用失败：上游体检结论为 ${checkStatus}（渠道未就绪），本轮按降级处理；按 setup 指引配置后重试`,
+      setup: typeof parsed.check?.message === 'string' ? parsed.check.message : undefined,
+    }
+  }
+  // 桥报 ok:false(不论 error 字段可读与否)都按渠道调用失败分类;桥结构化 error 原话与
+  // 进程级失败(stdout 空/半截 JSON/形状不对/超时)都走人话——raw 原话可能带 traceback/
+  // 凭证片段,不进用户面;透传契约只剩 setup 与 inventory(#559)
+  return {
+    ...base, ok: false, verdict: 'error', evidence: evidence('error'), latencyMs,
+    error: parsed.ok === false
+      ? `${q.channel}.${q.method} 调用失败：桥报告渠道调用出错但未附可读体检指引，本轮按降级处理；可调同渠道 check() 体检或用 gotry_doctor 查装配状态`
+      : bridgeFailureReason(r, timeoutMs),
+  }
+}
+
+/** 读网页:委托上游 WebChannel.read(Jina Reader 后端);供 gotry web 读取工具使用 */
+export async function readUrl(q: { url: string; timeoutMs?: number; /** 测试注入:替换 .venv/bin/python(与 reach.pythonBin 同构) */ pythonBin?: string }): Promise<{ ok: boolean; via: string; title?: string; content?: string; evidence: string; latencyMs: number; error?: string }> {
+  if (!/^https?:\/\//.test(q.url.trim())) {
+    return { ok: false, via: 'r.jina.ai-error', evidence: `[agent-reach:web.read@error@${ts()}] 非法 URL(需 http(s)://)`, latencyMs: 0, error: 'url 必须以 http(s):// 开头' }
+  }
+  const r = await reach({ channel: 'web', method: 'read', args: [q.url.trim()], timeoutMs: q.timeoutMs, pythonBin: q.pythonBin })
+  const content = typeof r.data === 'string' ? r.data.slice(0, 8000) : undefined
+  // 上游 Jina Reader 输出首行 "Title: ...",提取为标题(展示层逻辑,非渠道知识)
+  const title = content?.match(/^Title: (.+)$/m)?.[1]
+  return {
+    ok: r.ok, via: r.ok ? 'r.jina.ai' : 'r.jina.ai-error',
+    title, content, evidence: r.evidence, latencyMs: r.latencyMs,
+    // not-installed/needs-setup 的补装/配置指引住在 setup,不穿过来 gotry_web_search 会渲染 unavailable (undefined)(#559)
+    error: r.setup ? [r.error, r.setup].filter(Boolean).join('；') : r.error,
+  }
+}
+
+export interface ReachStatus {
+  ok: boolean
+  via: 'agent-reach-cli' | 'not-installed'
+  evidence: string
+  latencyMs: number
+  /** 上游 doctor 原始输出(渠道状态以上游为准,gotry 不自探测) */
+  output: string
+}
+
+/** 渠道体检:spawn 真 agent-reach doctor,输出原样透传 */
+export async function reachStatus(timeoutMs = 90_000): Promise<ReachStatus> {
+  const started = Date.now()
+  const bin = resolve(repoRoot(), '.venv/bin/agent-reach')
+  if (!existsSync(bin)) {
+    return { ok: false, via: 'not-installed', evidence: `[agent-reach:doctor@not-installed@${ts()}]`, latencyMs: 0, output: 'Agent Reach 未装配(.venv 缺失)——可选依赖,补装:终端跑 npx @danceiny/gotry doctor --fix;或让助手调 gotry_doctor 看整体体检报告' }
+  }
+  const r = await run(bin, ['doctor'], timeoutMs)
+  const output = (r.stdout || r.stderr).trim()
+  return {
+    ok: !r.err?.includes('ENOENT') && r.code === 0,
+    via: 'agent-reach-cli',
+    evidence: `[agent-reach:doctor@${ts()}] via .venv/bin/agent-reach`,
+    latencyMs: Date.now() - started,
+    output: output.slice(0, 4000),
+  }
+}

package/ts/capabilities/anything.ts

@@ -0,0 +1,282 @@
+/**
+ * Anything 通用搜索能力层:hbcli → hotel-be Anything 函数。
+ *
+ * 链路(同构 hbcli.ts):
+ *   gotry capabilities/anything.ts
+ *     → spawn hbcli --json search anything <kw> [opts]
+ *       → hotel-be /api/search/anything(httpdispatch 自动注册;httpdispatch 路由面)
+ *         → search/service/geography.go func Anything (mixed 城市+酒店搜索)
+ *
+ * wire 契约(2026-09-07 对齐上游源码;SearchItem = FuzzySearchItem + hotel):
+ *   req  { keyword, contentType?, context.destinationId?, minHotelCount? }
+ *   resp { candidates: [{ type: 'city'|'place'|'hotel',
+ *                         region?:  { id, name:{en,zh,ar}, coordinates:{centerLat,centerLng}, countryCode, … },
+ *                         place?:   { latlngCoordinator },
+ *                         matchScore?, hotel?: { id, name:{en,zh,ar}, star, latlngCoordinator:{google|gaode:{lat,lng} } } }] }
+ *
+ * 三值语义:
+ *   - hit:  命中候选(混合 city/hotel,maybe-coords)
+ *   - miss: hbcli exit 0,但 candidates 为空(查无结果)
+ *   - err:  hbcli exit ≠ 0 或超时(降级,降级产物 标 [实时API:hbcli-anything@error@ts])
+ *
+ * 离线开关(issue #617;与会话通道 GOTRY_SESSION_LIVE 同形,方向相反以保持产品默认不变):
+ *   GOTRY_HBCLI_LIVE=0|false|off(不分大小写)→ 零 spawn、不碰凭据与后端,走同一条降级面
+ *   (verdict=error,证据标 [实时API:hbcli-anything@offline@ts]);未设或任何其他取值 = 与此前
+ *   完全一致(hbcli 可用即 live)。判定见 hbcliLiveEnabled;mock/dry-run harness(nightly-evidence --dry-run、
+ *   persona-sim、replay*)缺省把它置 0,operator 显式设置的值不覆盖。
+ *
+ * 契约(与 hbcli/weather/opensky 同构,L4 不变量):
+ *   - 永不抛错:网络/超时/解析失败一律降级返回;
+ *   - 证据链标注:成功 [实时API:hbcli-anything@ts];失败 [实时API:hbcli-anything@error@ts];
+ *   - 永不阻塞调用方:周边有 12s 默认超时,LLM 不等。
+ *
+ * 第 7 个能力层(与 hbcli.ts / weather.ts / opensky.ts 平级),data-sources.md §4
+ * Google Place 链路的「酒店-be 中间层」入口。
+ */
+
+import { hbcliBinCandidates } from './hbcli.ts'
+import { spawnBounded } from './spawn-bounded.ts'
+
+export interface AnythingQuery {
+  /** 多词以空格 join,与 hbcli argument-parser 一致;前后 trim。空则报错(unless contentType 强限定) */
+  keyword: string
+  /** 'city' | 'hotel' | undefined(混合) */
+  contentType?: 'city' | 'hotel'
+  /** 限定子区域 ID(上游 SearchReq.context.destinationId) */
+  parentDestinationId?: string | number
+  /** 默认 12_000 ms */
+  timeoutMs?: number
+  /** 显式 hbcli 路径(默认 'hbcli',从 $PATH 找;默认名自动回退 ~/.local/bin 等已知安装位) */
+  hbcliBin?: string
+  /** 宿主取消信号(exec.signal) */
+  signal?: AbortSignal
+}
+
+export interface AnythingHit {
+  type: 'city' | 'hotel' | 'place'
+  /** i18n name 解析(zh 优先,产品中文优先;回退 en/ar) */
+  name: string
+  /** matchScore(文本相关度,越高越匹配) */
+  score?: number
+  /** lat/lng(region.center 或 hotel/place latlngCoordinator,若给出) */
+  latitude?: number
+  longitude?: number
+  /** city id(region.id;酒店候选为所属 destinationId) */
+  destinationId?: string
+  /** hotel id(若有) */
+  hotelId?: string
+  /** 星级(酒店候选,若返回) */
+  star?: number
+}
+
+export interface AnythingResult {
+  ok: boolean
+  via: 'hbcli-anything' | 'hbcli-anything-error'
+  evidence: string
+  latencyMs: number
+  /** 三值 */
+  verdict: 'hit' | 'miss' | 'error'
+  hits?: AnythingHit[]
+  totalCandidates?: number
+  error?: string
+}
+
+/** 上游 i18n.I18N {en,zh,ar};tolerant 读取(字段可能缺省,老字符串形态也兜住) */
+type I18N = { en?: string; zh?: string; ar?: string } | string | undefined
+
+function i18nText(v: I18N): string {
+  if (!v) return ''
+  if (typeof v === 'string') return v
+  return v.zh || v.en || v.ar || ''
+}
+
+/** hotel-be Latlng:{lat,lng};google/gaode 双源取先非零者 */
+function latlngOf(coord: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } } | undefined): { latitude?: number; longitude?: number } {
+  for (const src of [coord?.google, coord?.gaode]) {
+    const lat = typeof src?.lat === 'number' ? src.lat : undefined
+    const lng = typeof src?.lng === 'number' ? src.lng : undefined
+    if (lat !== undefined && lng !== undefined && (lat !== 0 || lng !== 0)) return { latitude: lat, longitude: lng }
+  }
+  return {}
+}
+
+interface RawSearchResp {
+  candidates?: RawSearchItem[]
+}
+/** hotel-be SearchItem wire 形状(FuzzySearchItem + hotel,2026-09-07 对齐源码) */
+interface RawSearchItem {
+  type?: string
+  matchScore?: number
+  region?: {
+    id?: string | number
+    name?: I18N
+    countryCode?: string
+    coordinates?: { centerLat?: number; centerLng?: number }
+  }
+  place?: { latlngCoordinator?: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } } }
+  hotel?: {
+    id?: string | number
+    name?: I18N
+    star?: number
+    destinationId?: string | number
+    latlngCoordinator?: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } }
+  }
+}
+
+function sh(cmd: string, args: string[], opts: { timeoutMs: number; env: NodeJS.ProcessEnv; signal?: AbortSignal }) {
+  return spawnBounded(cmd, args, { env: opts.env, cwd: process.cwd(), timeoutMs: opts.timeoutMs, signal: opts.signal })
+}
+
+/** --json 必须在子命令前(cli.ts 全局旗标预扫描只认子命令前位置;JSON 错误也走结构化 stderr) */
+function buildArgs(keyword: string, q: AnythingQuery): string[] {
+  const args = ['--json', 'search', 'anything', keyword]
+  if (q.contentType) args.push('--content-type', q.contentType)
+  if (q.parentDestinationId !== undefined) args.push('--destination-id', String(q.parentDestinationId))
+  return args
+}
+
+/** 旧版 CLI 无 search anything 子命令时的可行动升级指引(issue #195:裸 unknown command 读起来像工具坏了) */
+function upgradeHint(stderr: string): string | null {
+  return /unknown command/i.test(stderr)
+    ? 'hbcli 版本过旧(无 search anything 子命令)——请升级:hbcli update,或重跑 npx @danceiny/gotry setup'
+    : null
+}
+
+/**
+ * 失败人话化(对齐 hbcli.ts 的 issue #24 口径)。
+ *
+ * 这条消息会直接渲染进用户回复(loop.ts 的 D-7a PoI 探针)并进入模型面,所以
+ * `(exit null)`、`spawn hbcli ENOENT` 这类进程噪音不能出现——hbcli 未装配是
+ * 可选实时源的降级设计行为,不是工具坏了;无法归类时也要说清发生了什么。
+ */
+function failureReason(
+  r: { error?: string; code?: number | null; stderr?: string; timedOut?: boolean },
+  cleanupError: string | undefined,
+): string {
+  const suffix = cleanupError ? `;${cleanupError}` : ''
+  if (/ENOENT/i.test(r.error ?? '')) return `未安装 hbcli(可选实时源;npx @danceiny/gotry setup 可按官方脚本安装)${suffix}`
+  if (r.timedOut) return `hbcli 实时查询超时(本轮按降级处理)${suffix}`
+  const detail = (r.stderr ?? '').trim().slice(0, 200)
+  if (detail) return `hbcli 报错:${detail}${suffix}`
+  return (r.code == null
+    ? 'hbcli 未返回可判定结果(进程异常结束,本轮按降级处理)'
+    : `hbcli 退出码 ${r.code},未返回可判定结果(本轮按降级处理)`) + suffix
+}
+
+/**
+ * 实时 hbcli 通道是否开启(issue #617)。只有显式写 0 / false / off(不分大小写,忽略首尾空白)
+ * 才关闭;未设或任何其他取值都视为开启——终端用户依赖的实时源缺省不丢。调用时读取,
+ * 测试与 harness 可在进程内切换。
+ */
+export function hbcliLiveEnabled(env: Partial<Pick<NodeJS.ProcessEnv, 'GOTRY_HBCLI_LIVE'>> = process.env): boolean {
+  const v = (env.GOTRY_HBCLI_LIVE ?? '').trim().toLowerCase()
+  return v !== '0' && v !== 'false' && v !== 'off'
+}
+
+/** Anything 通用搜索 — 任何搜索失败走降级;不抛错 */
+export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const kw = (q.keyword ?? '').trim()
+  if (!kw) {
+    return {
+      ok: false, via: 'hbcli-anything-error',
+      evidence: `[实时API:hbcli-anything@error@${ts}] keyword empty`,
+      latencyMs: Date.now() - started, verdict: 'error',
+      error: 'keyword is required',
+    }
+  }
+  const args = buildArgs(kw, q)
+  // spawn 级失败(ENOENT)按已知安装位回退(hbcli.ts callHbcliJson 同款);abort/超时/退码无重试无候选
+  const candidates = hbcliBinCandidates(q.hbcliBin ?? 'hbcli')
+  if (q.signal?.aborted) {
+    return {
+      ok: false, via: 'hbcli-anything-error',
+      evidence: `[实时API:hbcli-anything@abort@${ts}] pre-aborted, zero spawn`,
+      latencyMs: 0, verdict: 'error', error: 'aborted by host signal',
+    }
+  }
+  // 离线开关:位置在入参校验与 pre-abort 之后,既有入参的既有结果/原因串逐字节不变;
+  // 关闭时与「未装配 hbcli」同形降级(ok:false / hbcli-anything-error / verdict:error + 人话原因,
+  // 无进程噪音,也不含 timeout 字样——效应层只重试 timeout 类),且不 spawn、不重试。
+  if (!hbcliLiveEnabled()) {
+    return {
+      ok: false, via: 'hbcli-anything-error',
+      evidence: `[实时API:hbcli-anything@offline@${ts}] GOTRY_HBCLI_LIVE switched off; live channel closed, zero spawn`,
+      latencyMs: Date.now() - started, verdict: 'error',
+      error: 'hbcli 实时通道已关闭(GOTRY_HBCLI_LIVE 离线开关;本轮按降级处理,未发起查询)',
+    }
+  }
+  let r: Awaited<ReturnType<typeof spawnBounded>> = { code: null, stdout: '', stderr: '', aborted: false, timedOut: false }
+  for (let i = 0; i < candidates.length; i++) {
+    r = await sh(candidates[i]!, args, { timeoutMs: q.timeoutMs ?? 12_000, env: process.env, signal: q.signal })
+    if (!(r.error && /ENOENT/.test(r.error) && !r.aborted && !r.timedOut && i < candidates.length - 1)) break
+  }
+  const latencyMs = Date.now() - started
+  const cleanupError = r.groupReaped === false ? 'process group cleanup incomplete' : undefined
+
+  if (r.aborted) {
+    return {
+      ok: false, via: 'hbcli-anything-error',
+      evidence: `[实时API:hbcli-anything@abort@${ts}]`,
+      latencyMs, verdict: 'error', error: ['aborted by host signal', cleanupError].filter(Boolean).join('; '),
+    }
+  }
+  if (r.error || r.groupReaped === false || r.code !== 0) {
+    const raw = [r.error, r.stderr.slice(0, 200), cleanupError].filter(Boolean).join('; ') || `(exit ${r.code})`
+    return {
+      ok: false,
+      via: 'hbcli-anything-error',
+      // evidence 保留上游原话(溯源契约,anything-tests 锁);error 走人话面
+      evidence: `[实时API:hbcli-anything@${r.timedOut ? 'timeout' : 'error'}@${ts}] ${raw}`,
+      latencyMs,
+      verdict: 'error',
+      error: upgradeHint(r.stderr) ?? failureReason(r, cleanupError),
+    }
+  }
+
+  let data: RawSearchResp
+  try {
+    const jStart = r.stdout.indexOf('{') >= 0 ? r.stdout.indexOf('{') : r.stdout.indexOf('[')
+    const json = jStart >= 0 ? r.stdout.slice(jStart) : r.stdout
+    data = JSON.parse(json) as RawSearchResp
+  } catch {
+    return {
+      ok: false, via: 'hbcli-anything-error',
+      evidence: `[实时API:hbcli-anything@error@${ts}] parse failed`,
+      latencyMs,
+      verdict: 'error',
+      error: 'failed to parse hbcli output as JSON',
+    }
+  }
+
+  const rawItems = data.candidates ?? []
+  const hits: AnythingHit[] = rawItems.map((it) => {
+    const region = it.region ?? {}
+    const hotel = it.hotel ?? {}
+    const isHotel = it.type === 'hotel' || Boolean(hotel.id)
+    const hotelCoords = latlngOf(hotel.latlngCoordinator)
+    const placeCoords = latlngOf(it.place?.latlngCoordinator)
+    const center = region.coordinates ?? {}
+    return {
+      type: (isHotel ? 'hotel' : (it.type === 'place' ? 'place' : 'city')) as AnythingHit['type'],
+      name: i18nText(hotel.name) || i18nText(region.name) || '?',
+      score: it.matchScore,
+      latitude: hotelCoords.latitude ?? placeCoords.latitude ?? (typeof center.centerLat === 'number' ? center.centerLat : undefined),
+      longitude: hotelCoords.longitude ?? placeCoords.longitude ?? (typeof center.centerLng === 'number' ? center.centerLng : undefined),
+      destinationId: hotel.destinationId !== undefined ? String(hotel.destinationId) : (region.id !== undefined ? String(region.id) : undefined),
+      hotelId: hotel.id !== undefined ? String(hotel.id) : undefined,
+      star: typeof hotel.star === 'number' && hotel.star > 0 ? hotel.star : undefined,
+    }
+  })
+
+  const verdict: AnythingResult['verdict'] = hits.length > 0 ? 'hit' : 'miss'
+  return {
+    ok: true, via: 'hbcli-anything',
+    evidence: `[实时API:hbcli-anything@${ts}] ${hits.length}/${rawItems.length} candidates`,
+    latencyMs,
+    verdict,
+    hits,
+    totalCandidates: rawItems.length,
+  }
+}