@danceiny/gotry 0.0.1-rc.10

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,158 @@
+/**
+ * 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]
+ */
+
+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 }> {
+  return new Promise((resolveRun) => {
+    const child = spawn(bin, args, { env: process.env })
+    let stdout = ''
+    let stderr = ''
+    let err: string | undefined
+    const timer = setTimeout(() => { 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 }) })
+  })
+}
+
+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>
+}
+
+/** 通用入口:反射调上游任意渠道方法;永不抛错 */
+export async function reach(q: { channel: string; method: string; args?: string[] | string; timeoutMs?: number }): 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 = venvPython()
+  if (!existsSync(py)) {
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs: 0, setup: 'gotry .venv 缺 python — 见 docs/tokens.md(agent-reach 安装)' }
+  }
+  const args = Array.isArray(q.args) ? q.args : (q.args ? q.args.split(/\s+/).filter(Boolean) : [])
+  const r = await run(py, [bridgeScript(), q.channel, q.method, ...args], q.timeoutMs ?? 30_000)
+  const latencyMs = Date.now() - started
+
+  let parsed: BridgeOut = {}
+  try {
+    parsed = JSON.parse((r.stdout || '').trim().split('\n').filter(Boolean).pop() ?? '{}') as BridgeOut
+  } catch { /* 走下面的兜底 */ }
+
+  if (r.err?.includes('ENOENT')) {
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv/bin/python 不可执行(装 agent-reach: 见 docs/tokens.md)' }
+  }
+  if (parsed.ok === true) {
+    return { ...base, ok: true, verdict: 'found', evidence: evidence('found'), latencyMs, data: parsed.data }
+  }
+  // 上游 agent_reach 包未装(bridge 自己的 exit 3 输出)
+  if (parsed.error?.includes('agent_reach 未安装')) {
+    return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv 缺 agent-reach(pip install agent-reach,见 docs/tokens.md)' }
+  }
+  // 未知渠道/方法:自描述,附上游清单(不拦 LLM,让它看清单自纠)
+  if (r.code === 2) {
+    return {
+      ...base, ok: false, verdict: 'error', evidence: evidence('error'), latencyMs,
+      error: parsed.error,
+      inventory: parsed.channels ? { channels: parsed.channels } : { channel: parsed.channel, methods: parsed.methods },
+    }
+  }
+  // 调用抛错:若上游 check() 给出 warn/off,把上游原话作为 setup 透传
+  const checkStatus = parsed.check?.status
+  if (checkStatus === 'warn' || checkStatus === 'off') {
+    return { ...base, ok: false, verdict: 'needs-setup', evidence: evidence('needs-setup'), latencyMs, error: parsed.error, setup: parsed.check?.message }
+  }
+  return { ...base, ok: false, verdict: 'error', evidence: evidence('error'), latencyMs, error: parsed.error ?? r.stderr.slice(0, 200) }
+}
+
+/** 读网页:委托上游 WebChannel.read(Jina Reader 后端);供 gotry web 读取工具使用 */
+export async function readUrl(q: { url: string; timeoutMs?: number }): 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 })
+  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,
+    error: 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: 'pip install agent-reach 于 .venv(见 docs/tokens.md)' }
+  }
+  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,201 @@
+/**
+ * Anything 通用搜索能力层:hbcli → hotel-be Anything 函数。
+ *
+ * 链路(同构 hbcli.ts):
+ *   gotry capabilities/anything.ts
+ *     → spawn hbcli search anything [keywords...] --json <opts>
+ *       → hotel-be /api/search/anything
+ *         → search/service/geography.go func Anything (mixed 城市+酒店搜索)
+ *
+ * 三值语义:
+ *   - hit:  命中候选(混合 city/hotel,maybe-coords)
+ *   - miss: hbcli exit 0,但 candidates 为空(查无结果)
+ *   - err:  hbcli exit ≠ 0 或超时(降级,降级产物 标 [实时API:hbcli-anything@error@ts])
+ *
+ * 契约(与 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 { spawn } from 'node:child_process'
+
+export interface AnythingQuery {
+  /** 多词以空格 join,与 hbcli argument-parser 一致;前后 trim。空则报错(unless contentType 强限定) */
+  keyword: string
+  /** 'city' | 'hotel' | undefined(混合) */
+  contentType?: 'city' | 'hotel'
+  /** 限定子区域 ID(可选) */
+  parentDestinationId?: string | number
+  /** 默认 12_000 ms */
+  timeoutMs?: number
+  /** 显式 hbcli 路径(默认 'hbcli',从 $PATH 找) */
+  hbcliBin?: string
+}
+
+export interface AnythingHit {
+  type: 'city' | 'hotel' | 'place'
+  /** FuzzySearchItem name(or hotel name);fallback 为 region.Name */
+  name: string
+  /** score / 0..1(若返回) */
+  score?: number
+  /** lat/lng(若 region 给出) */
+  latitude?: number
+  longitude?: number
+  /** city id(若有) */
+  destinationId?: string
+  /** hotel id(若有) */
+  hotelId?: string
+}
+
+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
+}
+
+interface RawSearchResp {
+  candidates?: RawSearchItem[]
+}
+interface RawSearchItem {
+  type?: string
+  name?: string
+  label?: string
+  region?: { id?: string; name?: string; latitude?: number; longitude?: number; typeScore?: number; name_en?: string; name_zh?: string }
+  hotel?: { id?: string; name?: string; latitude?: number; longitude?: number }
+  score?: number
+}
+
+function sh(cmd: string, args: string[], opts: { timeoutMs: number; env: NodeJS.ProcessEnv }) {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => {
+    ctrl.abort()
+    // AbortSignal on spawn 会发 SIGTERM;对于不响应 SIGTERM 的子进程,需要在外部再发一次 SIGKILL。
+    // Node 不能直接通过 AbortController 拿 child pid,所以需要借助外部变量保存 child。
+  }, opts.timeoutMs)
+  let child: ReturnType<typeof spawn> | null = null
+  let killTimer: NodeJS.Timeout | null = null
+  return new Promise<{ code: number; stdout: string; stderr: string; error?: string }>((resolve) => {
+    child = spawn(cmd, args, {
+      env: opts.env,
+      cwd: process.cwd(),
+      signal: ctrl.signal,
+    })
+    let stdout = ''
+    let stderr = ''
+    let error: string | undefined
+    let killed = false
+    child.stdout?.on('data', (d: Buffer) => { stdout += d.toString() })
+    child.stderr?.on('data', (d: Buffer) => { stderr += d.toString() })
+    child.on('error', (e) => { error = (e as Error).message.slice(0, 200) })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      if (killTimer) clearTimeout(killTimer)
+      resolve({ code: killed ? -2 : (code ?? -1), stdout, stderr, error })
+    })
+    // Abort 后 500ms 内若子进程仍活,发 SIGKILL 强杀。
+    ctrl.signal.addEventListener('abort', () => {
+      if (!child) return
+      try {
+        child.kill('SIGTERM')
+      } catch { /* ignore */ }
+      killTimer = setTimeout(() => {
+        try { child?.kill('SIGKILL') } catch { /* ignore */ }
+      }, 500)
+    })
+  })
+}
+
+const upperFirst = (s: string): string => (s ? s[0]!.toUpperCase() + s.slice(1) : s)
+const lowerFirst = (s: string): string => (s ? s[0]!.toLowerCase() + s.slice(1) : s)
+
+/** 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 bin = q.hbcliBin ?? 'hbcli'
+  const args = [bin, 'search', 'anything', kw]
+  if (q.contentType) args.push('--content-type', q.contentType)
+  if (q.parentDestinationId !== undefined) {
+    args.push('--parent-destination-id', String(q.parentDestinationId))
+  }
+
+  const r = await sh(bin, args.slice(1), {
+    timeoutMs: q.timeoutMs ?? 12_000,
+    env: process.env,
+  })
+  const latencyMs = Date.now() - started
+
+  if (r.error || r.code !== 0) {
+    return {
+      ok: false,
+      via: 'hbcli-anything-error',
+      evidence: `[实时API:hbcli-anything@error@${ts}] ${r.error ?? `exit ${r.code}`}`,
+      latencyMs,
+      verdict: 'error',
+      error: r.error ?? `${r.stderr.slice(0, 200)} (exit ${r.code})`,
+    }
+  }
+
+  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' || it.type === 'SupplierHotelList' || Boolean(hotel.id)
+    return {
+      type: (isHotel ? 'hotel' : (it.type === 'place' || it.type === 'City' ? lowerFirst(it.type) : 'city')) as AnythingHit['type'],
+      name: it.name ?? region.name_en ?? region.name ?? hotel.name ?? '?',
+      score: it.score ?? region.typeScore,
+      latitude: hotel.latitude ?? region.latitude,
+      longitude: hotel.longitude ?? region.longitude,
+      destinationId: region.id,
+      hotelId: hotel.id,
+    }
+  })
+
+  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,
+  }
+}
+
+// noop exports to keep file shape consistent with hbcli.ts
+export const _ = { upperFirst }

package/ts/capabilities/flyai.ts

@@ -0,0 +1,151 @@
+/**
+ * FlyAI 官方通道能力层(飞猪开放平台,data-sources.md §8 / RFC user-session-data-rfc.md P0):
+ *
+ * 链路(同构 anything.ts 的 CLI spawn 模式):
+ *   gotry capabilities/flyai.ts
+ *     → spawn `npx -y @fly-ai/flyai-cli search-flight|search-train --origin X --destination Y --dep-date D`
+ *       → 飞猪 MCP API(实时直连官方商品库)
+ *
+ * 契约(与 hbcli/weather/opensky/anything 同构,L4 不变量):
+ *   - 只读:8 工具全只读,交易经 jumpUrl 由人完成(与 WriteGate 哲学同构);
+ *   - 永不抛错:网络/超时/解析失败一律降级返回 verdict='error';
+ *   - 证据链:成功 [实时API:flyai@ts];失败 [实时API:flyai@error@ts];
+ *   - 无 key 可用;FLYAI_API_KEY 为可选增强(env 透传)。
+ */
+
+import { spawn } from 'node:child_process'
+
+export type FlyaiKind = 'flight' | 'train'
+
+export interface FlyaiQuery {
+  kind: FlyaiKind
+  /** 城市名(中文),如 上海 / 丽江 */
+  origin: string
+  destination: string
+  /** YYYY-MM-DD */
+  depDate: string
+  /** 默认 30_000 ms(npx 冷启动 + 远端检索) */
+  timeoutMs?: number
+  /** 显式 CLI bin(默认 npx -y @fly-ai/flyai-cli) */
+  cliBin?: string
+}
+
+export interface FlyaiOption {
+  /** 航班号/车次,如 9C6617 / G201 */
+  no: string
+  /** 承运:吉祥航空 / 高铁 */
+  name: string
+  depDateTime: string
+  arrDateTime: string
+  depStation: string
+  arrStation: string
+  durationMin: number
+  price: number
+  seatClass?: string
+  /** 飞猪侧预订跳转(由人完成,agent 不碰) */
+  jumpUrl?: string
+  /** 打码价格原值(如 "1xxx"——未鉴权态火车价被模糊化,真实价以 jumpUrl 落地页为准) */
+  priceRaw?: string
+}
+
+export interface FlyaiResult {
+  ok: boolean
+  via: 'flyai' | 'flyai-error'
+  evidence: string
+  latencyMs: number
+  verdict: 'hit' | 'miss' | 'error'
+  kind: FlyaiKind
+  options?: FlyaiOption[]
+  error?: string
+}
+
+interface RawItem {
+  journeys?: Array<{
+    journeyType?: string
+    segments?: Array<{
+      marketingTransportName?: string
+      marketingTransportNo?: string
+      depDateTime?: string
+      arrDateTime?: string
+      depStationName?: string
+      arrStationName?: string
+      duration?: string | number
+      seatClassName?: string
+    }>
+  }>
+  ticketPrice?: string
+  /** 火车条目用顶层 price(且未鉴权态为打码串如 "1xxx") */
+  price?: string
+  jumpUrl?: string
+}
+
+function sh(cmd: string, args: string[], opts: { timeoutMs: number }) {
+  const child = spawn(cmd, args, { env: process.env, cwd: process.cwd() })
+  let stdout = ''
+  let stderr = ''
+  let error: string | undefined
+  const timer = setTimeout(() => {
+    try { child.kill('SIGKILL') } catch { /* ignore */ }
+  }, opts.timeoutMs)
+  return new Promise<{ code: number; stdout: string; stderr: string; error?: string; timedOut?: boolean }>((resolve) => {
+    child.stdout?.on('data', (d: Buffer) => { stdout += d.toString() })
+    child.stderr?.on('data', (d: Buffer) => { stderr += d.toString() })
+    child.on('error', (e) => { error = (e as Error).message.slice(0, 200) })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      resolve({ code: code ?? -1, stdout, stderr, error })
+    })
+  }).finally(() => clearTimeout(timer))
+}
+
+/** FlyAI 官方只读检索(机/火车票) — 任何失败走降级;不抛错 */
+export async function flyaiSearch(q: FlyaiQuery): Promise<FlyaiResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const base = { kind: q.kind, latencyMs: 0 }
+  const origin = (q.origin ?? '').trim()
+  const destination = (q.destination ?? '').trim()
+  if (!origin || !destination || !/^\d{4}-\d{2}-\d{2}$/.test(q.depDate ?? '')) {
+    return { ...base, ok: false, via: 'flyai-error', verdict: 'error', evidence: `[实时API:flyai@error@${ts}] bad args`, error: 'origin/destination/depDate(YYYY-MM-DD) required' }
+  }
+  const sub = q.kind === 'flight' ? 'search-flight' : 'search-train'
+  const r = await sh(q.cliBin ?? 'npx', ['-y', '@fly-ai/flyai-cli', sub, '--origin', origin, '--destination', destination, '--dep-date', q.depDate], {
+    timeoutMs: q.timeoutMs ?? 30_000,
+  })
+  const latencyMs = Date.now() - started
+  if (r.error || r.code !== 0) {
+    return { ...base, latencyMs, ok: false, via: 'flyai-error', verdict: 'error', evidence: `[实时API:flyai@error@${ts}] ${r.error ?? `exit ${r.code}`}`, error: r.error ?? r.stderr.replace(/\s+/g, ' ').slice(0, 200) }
+  }
+  let items: RawItem[]
+  try {
+    const jStart = r.stdout.indexOf('{')
+    const parsed = JSON.parse(jStart >= 0 ? r.stdout.slice(jStart) : r.stdout) as { data?: { itemList?: RawItem[] } }
+    items = parsed.data?.itemList ?? []
+  } catch {
+    // 实测(2026-08-28):Sentinel 限流时 CLI exit=0 但 stdout 是 {"message":"SentinelBlockException..."}
+    const raw = r.stdout.replace(/\s+/g, ' ').slice(0, 160)
+    return { ...base, latencyMs, ok: false, via: 'flyai-error', verdict: 'error', evidence: `[实时API:flyai@error@${ts}] parse failed: ${raw}`, error: `failed to parse flyai output as JSON: ${raw}` }
+  }
+  const options: FlyaiOption[] = []
+  for (const it of items) {
+    const seg = it.journeys?.[0]?.segments?.[0]
+    if (!seg?.marketingTransportNo || !seg.depDateTime) continue
+    const rawPrice = it.ticketPrice ?? it.price ?? ''
+    const numericPrice = Number(rawPrice)
+    options.push({
+      no: seg.marketingTransportNo,
+      name: seg.marketingTransportName ?? '',
+      depDateTime: seg.depDateTime ?? '',
+      arrDateTime: seg.arrDateTime ?? '',
+      depStation: seg.depStationName ?? '',
+      arrStation: seg.arrStationName ?? '',
+      durationMin: Number(seg.duration ?? 0) || 0,
+      price: Number.isFinite(numericPrice) && numericPrice > 0 ? numericPrice : 0,
+      priceRaw: /^\d+$/.test(rawPrice) ? undefined : rawPrice || undefined,
+      seatClass: seg.seatClassName,
+      jumpUrl: it.jumpUrl,
+    })
+  }
+  const verdict: FlyaiResult['verdict'] = options.length > 0 ? 'hit' : 'miss'
+  return { kind: q.kind, latencyMs, ok: true, via: 'flyai', verdict, evidence: `[实时API:flyai@${ts}] ${options.length}/${items.length} ${q.kind} options`, options }
+}