@danceiny/gotry 0.0.1-rc.10

package/ts/src/index.ts

@@ -0,0 +1,968 @@
+/**
+ * GoTry dsh 插件(gotry-tools):把 GoTry 的领域能力注册为 dsh 工具。
+ *
+ * 对应总纲 3.2 插件清单中的三个最小集:
+ *   - gotry_feasibility_check   可行性引擎(门到门全成本,bridge → Python Z3)
+ *   - gotry_motivation_save     动机画像落盘(为什么出发;B2B 接缝的契约对象)
+ *   - gotry_wish_pool_add       「下一次出发」清单(憧憬不被拒绝)
+ *
+ * 插件形态遵循 dsh 约定(name/inject/Config/apply + ctx.tools.register(defineTool(...))),
+ * 对齐已发布 @deepseek-ai/dsh-tools@0.0.1-rc.1 的契约:
+ * render 位于 output 对象内,参数属性是 ValueSchemaSpec(支持 type:'json')。
+ *
+ * @module @gotry/plugin
+ */
+
+import { join } from 'node:path'
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { ensureStateDir, recordLatency } from './bridge.ts'
+import { segmentsFromCandidate, solveChoiceSegment } from './unified.ts'
+import { checkConnectivity } from '../scripts/skeleton-check.ts'
+import { parseCandidate, parseRequest } from './model.ts'
+import { searchHotels as hbcliSearchHotels } from '../capabilities/hbcli.ts'
+import { installProcessGuards, guardToolExecute } from '../capabilities/incident-log.ts'
+import { interpretArgs, type GotryObservation } from './tool-packet.ts'
+import { projectUtility } from './memory-utility.ts'
+import { pickNudgeWish, type WishPoolEntry } from './wish-pool.ts'
+import { resolveTimelineDate } from './travel-timeline.ts'
+import { ensureLedger, readCompanionsWithFallback, readMotivationWithFallback, readTripsWithFallback, readWishPoolWithFallback } from './state-ledger.ts'
+import { buildTimeAnchor } from './time-anchor.ts'
+import { resolveSlotDate } from './slot-spec.ts'
+import { geocodePlace, getForecast, getClimate, wmoLabel } from '../capabilities/weather.ts'
+import { verifyFlight } from '../capabilities/opensky.ts'
+import { anythingSearch } from '../capabilities/anything.ts'
+import { readUrl, reach, reachStatus } from '../capabilities/agent-reach.ts'
+import { videoSubtitle, githubSearch } from '../capabilities/agent-reach-deep.ts'
+import { flyaiSearch } from '../capabilities/flyai.ts'
+import { sessionFlightSearch } from '../capabilities/session-search.ts'
+
+export const name = 'gotry-tools'
+export const inject = ['tools', 'systemPrompt']
+
+export interface Config {
+  /** 状态根目录(动机画像、wish pool、延迟日志) */
+  stateRoot: string
+  /** 引擎调用超时(ms) */
+  timeoutMs: number
+  /** hbcli 二进制路径(hotelbyte-cli;空=禁用实时酒店,回退数据包) */
+  hbcliBin: string
+}
+
+export const Config: z<Config> = z.object({
+  stateRoot: z.string().default('.'),
+  timeoutMs: z.number().default(30_000),
+  hbcliBin: z.string().default('hbcli'),
+})
+
+interface FeasibilityResult {
+  answer_md?: string
+  recommended?: string | null
+  verdicts?: Array<Record<string, unknown>>
+}
+
+interface MotivationProfileInput {
+  weights?: Record<string, number>
+  evidence?: string[]
+  hard?: Record<string, unknown>
+}
+
+interface WishPoolEntryInput {
+  name?: string
+  reason?: string
+  conditions?: Record<string, unknown>
+}
+
+
+/**
+ * query 包装参数的三形态归一(#12/#13):实现移居 tool-packet.ts(interpretArgs,
+ * RFC S1 interpretation 层语义归位),此处按旧名引 handy 别名,调用点零漂移。
+ */
+const unwrapQuery = interpretArgs
+
+/**
+ * 动机画像 → persona 紧凑 brief(M4 T1 读回路径):空画像返回 ''(首访),
+ * persona 据此决定是否访谈。只读,不猜——画像里没有的字段不编。
+ * ADR-15:读经账本(未迁移 root 回退旧文件,只读)。
+ */
+function renderMotivationBrief(stateRoot: string): string {
+  const p = readMotivationWithFallback(stateRoot)
+  if (!p) return '' // 首访:无画像
+  const lines: string[] = ['## 用户记忆(跨会话画像;与用户当轮说法冲突时以用户为准,更新经 gotry_motivation_save)']
+  const weights = Object.entries(p.weights ?? {})
+  if (weights.length) lines.push(`- 动机权重: ${weights.map(([k, v]) => `${k}=${v}`).join(', ')}(证据 ${p.evidence?.length ?? 0} 条)`)
+  const hard = Object.entries(p.hard ?? {})
+  if (hard.length) lines.push(`- 硬约束: ${hard.map(([k, v]) => `${k}=${String(v)}`).join(', ')}`)
+  // 旅行时间线(memory-design P1):去过的地方不再主动推荐,除非用户点名
+  const trips = readTimelineTrips(stateRoot)
+  if (trips.length) {
+    lines.push(`- 去过: ${trips.map(t => `${t.destination}(${t.start.slice(0, 7)})`).join('、')}——去过的地方不再主动推荐,除非用户点名`)
+  }
+  // 同行人档案(memory-design P2):约束只进排序与行程结构建议,永不硬过滤
+  const companions = readCompanions(stateRoot)
+  if (companions.length) {
+    lines.push(`- 同行人: ${companions.map(c => `${c.label}(${c.brief})`).join('、')}——约束进结构与排序建议,不硬过滤;引用时带当初的原话依据`)
+  }
+  lines.push(`- 愿望池: 用 gotry_wish_pool_list 按条件召回(0..1),勿直接堆砌`)
+  if (p.updated_at) lines.push(`- 更新于: ${p.updated_at}`)
+  return weights.length || hard.length ? lines.join('\n') : ''
+}
+
+/** 时间线摘要(brief 用):最近 3 次行程(目的地+年月);账本优先,未迁移回退文件 */
+/** 同行人摘要(brief 用):label + 约束串 */
+function readCompanions(stateRoot: string): Array<{ label: string; brief: string }> {
+  return readCompanionsWithFallback(stateRoot)
+    .map(c => {
+      const bits = [c.constraints.mobility, ...(c.constraints.health ?? []), ...(c.constraints.prefs ?? [])].filter(Boolean)
+      return { label: c.label, brief: bits.join('/') }
+    })
+}
+
+function readTimelineTrips(stateRoot: string): Array<{ destination: string; start: string }> {
+  return readTripsWithFallback(stateRoot)
+    .map(t => ({ destination: t.destination, start: t.start }))
+    .sort((a, b) => (a.start < b.start ? 1 : -1))
+    .slice(0, 3)
+}
+
+type Json = string | number | boolean | null | Json[] | { [k: string]: Json }
+type JsonObject = { [k: string]: Json }
+
+export function apply(ctx: Context, config: Config): void {
+  // 时间感知:注册动态变量,persona 里用 {{current_date}} 引用。
+  // 每次 assemble 时取系统时钟——LLM 始终知道「今天是几号」。
+  const sp = (ctx as unknown as Record<string, unknown>)['systemPrompt'] as {
+    variable?: (name: string, provider: () => string) => void
+  } | undefined
+  sp?.variable?.('current_date', () => {
+    const d = new Date()
+    const ymd = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+    const weekdays = ['日', '一', '二', '三', '四', '五', '六']
+    return `${ymd} 周${weekdays[d.getDay()]}`
+  })
+  // 时间锚点卡(time-anchor 层,确定性):相对日期换算的唯一依据——
+  // 明天/下周X/下个月中旬/节日都查卡,LLM 不自算(算术只在代码层)。
+  sp?.variable?.('time_anchor_card', () => buildTimeAnchor(new Date()).card)
+
+  // M4 记忆读回(T1 闭环的另一半):motivation-profile 此前只写不读,每个新会话
+  // 模型都是盲的、重新访谈——「回访规划时长降 ≥50%」不可能成立。这里把画像
+  // 渲染成紧凑 brief 注入 persona;为空 = 首访。与当轮说法冲突时以用户为准。
+  sp?.variable?.('motivation_brief', () => renderMotivationBrief(config.stateRoot ?? '.'))
+
+  // D-NEW 进程护栏(Z3 WASM crash 教训):dsh 0.1.1-rc.1 缺 uncaughtException
+  // handler,插件异常穿透即杀进程。我们在 gotry 侧挂护栏:同步 fsync 写事故证据
+  // (gotry-state/incidents.jsonl),handler 自身不再抛,不阻塞后续控制流。
+  // 不调 process.exit——让 dsh/上级容器决定生死,我们只留现场。
+  installProcessGuards(config.stateRoot ?? '.', { uncaughtException: 'gotry-tools', unhandledRejection: 'gotry-tools' })
+
+  // D-NEW 收尾:全部工具 execute 统一异常隔离——单个工具抛错/拒绝不再沿 cordis
+  // 传到 dsh 主循环,降级为结构化错误返回给 LLM + incident 落盘(incident-log.ts)。
+  const registerGuarded = (tool: ReturnType<typeof defineTool>): void => {
+    const t = { ...(tool as unknown as Record<string, unknown>) }
+    if (typeof t.execute === 'function') {
+      t.execute = guardToolExecute(String(t.name), config.stateRoot ?? '.', t.execute as (args: never, exec: unknown) => never)
+    }
+    ctx.tools.register(t as unknown as ReturnType<typeof defineTool>)
+  }
+
+  registerGuarded(defineTool({
+    name: 'gotry_feasibility_check',
+    description:
+      'Check travel candidates against the user\'s motivation and hard constraints using the '
+      + 'door-to-door true-cost engine (wake time, arrival state, energy, usable hours, money). '
+      + 'Input is the structured request (motivation weights + hard constraints + window + budget + home hubs) '
+      + 'and the candidate list (services/transfers/stay costs/min days): '
+      + 'structure { request: { motivation weights, hard constraints, window, budget, home hubs }, candidates: [ { id, label, services, transfers, stay, minDays } ] }. '
+      + 'Returns per-candidate verdicts, unsat cores with minimal-modification suggestions, '
+      + 'a wish-pool entry for infeasible aspirations, and a ready-to-show markdown answer.',
+    parameters: {
+      payload: {
+        type: 'json',
+        required: true,
+        description: 'The full engine payload: { request, candidates }.',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{
+        type: 'text',
+        text: String((value as FeasibilityResult).answer_md ?? JSON.stringify(value)),
+      }],
+    },
+    async execute(args: { payload: unknown }, _exec: unknown) {
+      // 纯 TS 路径:D-7 后 unified solveChoiceSegment 是唯一求解入口(无 Python 桥、无 z3 WASM
+      // 路径——候选形态枚举求解,~6ms/次)。unified 内部有 try-catch 护栏覆盖 wasm 异常。
+      const started = Date.now()
+      const payload = args.payload as Record<string, unknown>
+      const req = parseRequest(payload['request'] as Record<string, unknown>)
+      const cands = (payload['candidates'] as Record<string, unknown>[]).map(parseCandidate)
+      const spec = segmentsFromCandidate(req, cands)
+      const result = solveChoiceSegment(spec, req) as Record<string, unknown>
+      const dir = await ensureStateDir(config.stateRoot)
+      await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, 'feasibility_check:in-process-unified').catch(() => {})
+      return { ok: true, ...result, latency_ms: Date.now() - started, via: 'in-process-unified' }
+    },
+    presentCall: args => ({ card: 'generic', title: 'GoTry 可行性检查(门到门全成本)', kind: 'execute', rawInput: args.payload }),
+    presentResult: (args, value) => {
+      // D-4 卡片赎回:结果卡不再是裸 JSON —— 逐候选判定 + 全成本 vs 预算紧凑行 + 人话答案
+      const r = value as FeasibilityResult
+      const budget = ((args.payload as { request?: { budget_cny?: number } })?.request)?.budget_cny
+      const lines = (r.verdicts ?? []).map(v => {
+        const tc = (v.true_cost ?? {}) as { money_cny?: number }
+        const money = typeof tc.money_cny === 'number'
+          ? ` ¥${tc.money_cny}/人` + (typeof budget === 'number' ? `(预算 ¥${budget},${tc.money_cny <= budget ? '余' : '超'} ¥${Math.abs(budget - tc.money_cny)})` : '')
+          : ''
+        return v.feasible
+          ? `✅ ${String(v.name ?? v.candidate_id)}${money}${v.candidate_id === r.recommended ? ' ← 推荐' : ''}`
+          : `❌ ${String(v.name ?? v.candidate_id)} — ${(Array.isArray(v.unsat_core) ? v.unsat_core.join(',') : '不可行')}`
+      })
+      return {
+        card: 'generic',
+        title: `可行性:${r.recommended ? `推荐 ${r.recommended}` : '全部不可行'}`,
+        content: [{ type: 'text', text: (lines.length ? lines.join('\n') + '\n\n' : '') + String(r.answer_md ?? '').slice(0, 1500) }],
+      }
+    },
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_motivation_save',
+    description:
+      'Persist the traveler\'s motivation profile (the "why depart" contract object). '
+      + 'This is the B2B reuse seam: downstream plugins consume only MotivationProfile + constraints, '
+      + 'never the principal/sponsor distinction. MERGE semantics (T1): call again with just the NEW '
+      + 'facts learned this turn (weights delta optional but MUST bring fresh evidence; evidence = user quotes); '
+      + 'existing history is never deleted. Requires evidence on every call (P0 anti-fabrication rule).',
+    parameters: {
+      profile: {
+        type: 'json',
+        required: true,
+        description: '{ weights: {escape_rest: 0.7, ...}, evidence: [user quotes...], hard: {wake_not_before, min_arrival_energy_pct} }',
+      },
+    },
+    output: {
+      // loose json:guard 兜底字段(ok/summary)不被 strict schema 拒(骨架事故同款)
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: `动机画像已保存:${String((value as { path?: string }).path ?? '')}` }],
+    },
+    async execute(args: { profile: unknown }, _exec: unknown) {
+      // T1 接线:本工具是增量补丁语义(契约 18——模型每轮把对话新事实带进来),
+      // 经 mergeProfile 守门合并进既有画像(追加不删史/幂等/权重变更须伴新证据),
+      // 不再整档覆盖。首次调用(无档案)= 全量建立。
+      // ADR-15:守门+事件+投影在账本单事务内完成,evidence 红线拒绝即回滚,账本无痕。
+      const incoming = (args.profile ?? {}) as { weights?: Record<string, number>; evidence?: string[]; hard?: Record<string, unknown> }
+      if (!incoming.evidence?.length) {
+        throw new Error('refusing to save a motivation profile without evidence (P0 anti-fabrication rule)')
+      }
+      const ledger = ensureLedger(config.stateRoot)
+      const res = ledger.appendMotivationPatch({ weights: incoming.weights, evidence: incoming.evidence, hard: incoming.hard })
+      const profileJson = JSON.parse(JSON.stringify(res.profile)) as JsonObject
+      return res.saved
+        ? { ok: true, saved: true, path: ledger.dbPath, profile: profileJson, summary: '画像已合并入账本(单事务)' }
+        : { ok: true, saved: false, path: ledger.dbPath, profile: profileJson, summary: '无新内容(幂等跳过)' }
+    },
+    presentCall: args => ({ card: 'generic', title: '保存动机画像', kind: 'edit', rawInput: args.profile }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_wish_pool_add',
+    description:
+      'Add an aspiration to the "next departure" wish pool — the graceful home for infeasible dreams. '
+      + 'An entry carries its fulfilment conditions (days needed, budget, best months) so a future '
+      + '"next departure" nudge can fire when the window matches. Each entry gets a stable wish_id '
+      + '(the memory-utility sidecar keys on it); muted:true puts a wish dormant (永不删除,只是不再召回). 憧憬不被拒绝。',
+    parameters: {
+      entry: {
+        type: 'json',
+        required: true,
+        description: '{ name, reason?, conditions: { days, budget_cny, best_months }, muted?: boolean }',
+      },
+    },
+    output: {
+      // loose json:guard 兜底字段(ok/summary)不被 strict schema 拒(骨架事故同款)
+      schema: { type: 'json' },
+      render: (_args, value) => {
+        const v = value as { total?: number; path?: string }
+        return [{ type: 'text', text: `已加入「下一次出发」清单(共 ${v.total ?? '?'} 项):${v.path ?? ''}` }]
+      },
+    },
+    async execute(args: { entry: unknown }, _exec: unknown) {
+      const entry = (args.entry ?? {}) as WishPoolEntryInput & { muted?: boolean }
+      // 同名憧憬幂等更新(刷新理由与成行条件),不重复入池;wish_id 语义派生自名称,稳定可重放。
+      // ADR-15:conditions 红线在账本事务内校验拒绝。
+      const ledger = ensureLedger(config.stateRoot)
+      const r = ledger.appendWish({ name: entry.name, reason: entry.reason, conditions: entry.conditions, muted: entry.muted })
+      return { ok: true, added: r.added, wish_id: r.wish_id, total: r.total, path: ledger.dbPath }
+    },
+    presentCall: args => ({ card: 'generic', title: '加入「下一次出发」清单', kind: 'edit', rawInput: args.entry }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_wish_pool_list',
+    description:
+      'Surface AT MOST ONE "next departure" wish whose fulfilment conditions match the user\'s current window '
+      + '(0..1 rule: never more than one nudge per turn, never push when nothing matches — 憧憬不被拒绝,也不被硬推). '
+      + 'Muted wishes never surface. Surfacing records a recalled event in the memory-utility sidecar. '
+      + 'action="confirm-outcome" records the user-confirmed real-world outcome (attribution helpful/harmful/neutral) — '
+      + 'ONLY pass attribution the user explicitly stated; the agent must never self-attribute usefulness.',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ action?: "recall"|"confirm-outcome", days?, budgetCny?, month?, wishId?, attribution?: "helpful"|"harmful"|"neutral", detail?, tripStart?: "行程起始(确认成行时挂时间线)" }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ action?: string; days?: number; budgetCny?: number; month?: number; wishId?: string; attribution?: 'helpful' | 'harmful' | 'neutral'; detail?: string; tripStart?: string }>(args, 'action')
+      const ledger = ensureLedger(config.stateRoot)
+      const now = new Date().toISOString()
+      if (q.action === 'confirm-outcome') {
+        if (!q.wishId || !q.attribution) {
+          return { ok: false, summary: 'confirm-outcome 需要 wishId + attribution(helpful|harmful|neutral)' } as never
+        }
+        // 成行确认 = 效用事件 + 可选时间线行程,账本单事务(ADR-15:原两文件写在崩溃时分叉)
+        let tripInput: { destination: string; start: string; end?: string; companions?: string[]; source: 'wish-confirmed'; evidence: string } | undefined
+        const wish = ledger.readWishPool().find(e => String(e.wish_id) === q.wishId) as { name?: unknown } | undefined
+        if (q.tripStart && wish?.name) {
+          const anchor = buildTimeAnchor(new Date())
+          const start = resolveTimelineDate(q.tripStart, anchor) ?? (/^\d{4}-\d{2}-\d{2}$/.test(q.tripStart) ? q.tripStart : undefined)
+          if (start) {
+            tripInput = {
+              destination: String(wish.name), start, companions: undefined,
+              source: 'wish-confirmed', evidence: `wish ${q.wishId} confirm-outcome(${q.attribution})`,
+            }
+          }
+        }
+        const r = ledger.confirmOutcome({ wishId: q.wishId, attribution: q.attribution, detail: q.detail, trip: tripInput })
+        return { ok: true, recorded: r.recorded, wish_id: q.wishId, status: q.attribution, ...(r.trip ? { trip: r.trip } : {}) } as never
+      }
+      // recall:0..1 条件匹配(判定归 wish-pool 纯函数),muted 永不召回,无命中不硬推
+      const pool = ledger.readWishPool()
+      const candidates = pool.filter(e => !e.muted && typeof e.wish_id === 'string')
+      const month = q.month ?? new Date().getMonth() + 1
+      const match = pickNudgeWish(candidates as WishPoolEntry[], { days: q.days, budgetCny: q.budgetCny, month })
+      if (!match) {
+        return { ok: true, suggestion: null, summary: `无可成行的憧憬匹配当前窗口(${candidates.length} 条在册,0..1 纪律:不硬推)` } as never
+      }
+      const { events: next } = ledger.appendUtilityEvent({
+        wish_id: match.wishId, kind: 'recalled', ts: now, ctx: 'gotry_wish_pool_list.recall',
+      })
+      const utility = projectUtility(next)[match.wishId]
+      return {
+        ok: true,
+        suggestion: { wish_id: match.entry['wish_id'], name: match.entry['name'], reason: match.entry['reason'], conditions: match.entry['conditions'], match_score: match.score, hits: match.hits },
+        utility: { status: utility?.status ?? 'unknown', recalled: utility?.recalled ?? 1 },
+        summary: `「下一次出发」候选(0..1):${String(match.entry['name'])}——成行条件 ${JSON.stringify(match.entry['conditions'])},本次窗口命中 ${match.score}/3 项(${match.hits.join('+')});效用状态 ${utility?.status ?? 'unknown'}`,
+      } as never
+    },
+    presentCall: args => ({ card: 'generic', title: '「下一次出发」召回', kind: 'search', rawInput: args.query }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_companion_save',
+    description:
+      'Save/update a travel companion profile (memory-design M5 layer): constraints that shape itinerary STRUCTURE and ranking — '
+      + 'never a hard filter (「爸爸65轻度高血压」→ 不排高海拔/控制步行量;「晕车」→ 优先火车/备提示). '
+      + 'evidence MUST be the user\'s verbatim words (append-only, traceable). '
+      + 'NEGATIVE LIST: passport/ID/phone numbers are rejected on sight — such fields never enter storage.',
+    parameters: {
+      companion: {
+        type: 'json',
+        required: true,
+        description: '{ label: "爸爸", constraints: { mobility?: "步行≤4h", health?: ["轻度高血压"], prefs?: ["怕吵"] }, evidence: "<用户原话>" }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }],
+    },
+    async execute(args: { companion: unknown }, _exec: unknown) {
+      const c = (args.companion ?? {}) as { label?: string; constraints?: { mobility?: string; health?: string[]; prefs?: string[] }; evidence?: string }
+      if (!c.evidence) return { ok: false, summary: 'evidence 必填(用户原话,溯源 P0)' } as never
+      // ADR-15:负面清单守卫(upsertCompanion)在账本事务内执行,拒收即回滚
+      const ledger = ensureLedger(config.stateRoot)
+      const res = ledger.appendCompanion({
+        label: String(c.label ?? ''),
+        constraints: { mobility: c.constraints?.mobility, health: c.constraints?.health, prefs: c.constraints?.prefs },
+        evidence: c.evidence,
+      })
+      if (!res.appended && res.reason) return { ok: false, summary: res.reason } as never
+      return { ok: true, appended: res.appended, companion_id: res.companionId, total: res.total, summary: res.appended ? `同行人已保存:${res.companionId}` : `无新内容(幂等跳过):${res.companionId}` } as never
+    },
+    presentCall: args => ({ card: 'generic', title: '保存同行人', kind: 'edit', rawInput: args.companion }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_trip_log',
+    description:
+      'Record a PAST trip into the travel timeline (memory-design M4 layer). Use when the user mentions a trip they already took '
+      + '(「去年国庆去了大理」) — dates resolve via the time anchor (词表外日期会拒绝,请用户给绝对日期), evidence MUST be the user\'s verbatim words. '
+      + 'Append-only and idempotent (same destination+start+source = same trip); overlapping same-destination trips are rejected for human adjudication. '
+      + 'Past trips power origin resolution and 「去过不再推」 ranking — never a hard filter.',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ destination: "大理", start: "2025-10-01 或绝对日期表达", end?: 同上, companions?: ["爸爸"], evidence: "<用户原话>" }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ destination?: string; start?: string; end?: string; companions?: string[]; evidence?: string }>(args, 'destination')
+      if (!q.destination) return { ok: false, summary: 'destination 必填' } as never
+      if (!q.evidence) return { ok: false, summary: 'evidence 必填(用户原话,溯源 P0)' } as never
+      const anchor = buildTimeAnchor(new Date())
+      const start = resolveTimelineDate(q.start ?? '', anchor) ?? (/^\d{4}-\d{2}-\d{2}$/.test(q.start ?? '') ? q.start : undefined)
+      if (!start) return { ok: false, summary: `start 无法解析为绝对日期(${q.start ?? '缺'})——请向用户要具体日期,不猜` } as never
+      const end = q.end ? (resolveTimelineDate(q.end, anchor) ?? (/^\d{4}-\d{2}-\d{2}$/.test(q.end) ? q.end : undefined)) : undefined
+      // ADR-15:appendTrip 守门(必填/绝对日期/重叠冲突即停)在账本事务内执行
+      const ledger = ensureLedger(config.stateRoot)
+      const res = ledger.appendTripEvent({
+        destination: q.destination.trim(), start, end, companions: q.companions,
+        source: 'user-verbatim', evidence: q.evidence,
+      })
+      if (!res.appended && res.reason) return { ok: false, summary: res.reason } as never
+      return { ok: true, appended: res.appended, trip_id: res.tripId, total: res.total, summary: res.appended ? `已入时间线:${q.destination} @ ${start}` : `已存在(幂等跳过):${res.tripId}` } as never
+    },
+    presentCall: args => ({ card: 'generic', title: '记录旅行', kind: 'edit', rawInput: args.query }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_hotel_search',
+    description:
+      'Search hotels via hotelbyte-cli (real-time when hbcli credentials exist, falls back to the static pack with explicit evidence tagging). '
+      + 'Input: destination city name + optional dates/occupancy. Dates accept verbatim natural expressions (下周五 / 8.20 / 下周五+3) — '
+      + 'the code layer resolves them against the time anchor; unresolved expressions degrade to an undated search with an explicit '
+      + 'date_notes entry instead of guessing. Output: hotel list with evidence chain ([realtime-API:hbcli] + fetch timestamp, '
+      + 'or [static-pack:estimate]) per the L4 invariant.',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ destination: "<目的地城市>", checkIn?: "YYYY-MM-DD 或自然表达(下周五/8.20)", checkOut?: 同上, occupancy?: { adults: 2 } }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 400)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ destination?: string; checkIn?: string; checkOut?: string; adults?: number }>(args, 'destination')
+      if (!q.destination) throw new Error('gotry_hotel_search requires destination')
+      const started = Date.now()
+      const fallbackPath = join(import.meta.dirname, '..', '..', 'data', 'hotels_2026.json')
+      // D-10 切片 B:日期槽位接受逐字自然表达(下周五/8.20/+N),代码层换算(slot-spec);
+      // unresolved 不猜——降级为无日期搜索并显式记 note,由模型向用户追问
+      const anchor = buildTimeAnchor(new Date())
+      const dateNotes: string[] = []
+      const resolveDate = (expr?: string): string | undefined => {
+        if (!expr) return undefined
+        const r = resolveSlotDate(expr, anchor)
+        if (!r.date) {
+          dateNotes.push(`日期未解析:${r.raw}——请向用户确认具体日期`)
+          return undefined
+        }
+        if (r.raw !== r.date) dateNotes.push(`slot-resolved: ${r.raw} → ${r.date}`)
+        return r.date
+      }
+      const resp = await hbcliSearchHotels(
+        { destination: q.destination, checkIn: resolveDate(q.checkIn), checkOut: resolveDate(q.checkOut), adults: q.adults },
+        { hbcliBin: config.hbcliBin, timeoutMs: config.timeoutMs, fallbackPath },
+      )
+      const dir = await ensureStateDir(config.stateRoot)
+      const isLive = resp.via === 'hbcli-realtime'
+      const evidence = isLive ? resp.evidence : '[静态包:估算]'
+      await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `hotel_search:${resp.via}`).catch(() => {})
+      const payload = {
+        ok: true,
+        hotels: resp.hotels ?? null,
+        evidence,
+        destination: q.destination,
+        via: resp.via,
+        latency_ms: Date.now() - started,
+        summary: resp.summary,
+        error: resp.error,
+        ...(dateNotes.length ? { date_notes: dateNotes } : {}),
+      } as never
+      return JSON.parse(JSON.stringify(payload)) as never
+    },
+    presentCall: args => ({ card: 'generic', title: `酒店搜索:${String((args.query as { destination?: string })?.destination ?? '')}`, kind: 'search', rawInput: args.query }),
+    presentResult: (_args, value) => {
+      const r = value as { hotels?: unknown[]; via?: string; destination?: string; summary?: string }
+      const n = Array.isArray(r.hotels) ? r.hotels.length : 0
+      return {
+        card: 'generic',
+        title: `酒店:${r.destination ?? ''} ${n ? `${n} 家(${r.via === 'hbcli-realtime' ? '实时' : '静态包'})` : '无结果'}`,
+        content: [{ type: 'text', text: String(r.summary ?? '') }],
+      }
+    },
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_skeleton_check',
+    description:
+      'Check flight connectivity between two airports against the OpenFlights skeleton (free tier). '
+      + 'Three-valued: found = strong positive (airlines returned); hub-to-hub absence = downgrade signal, NEVER disproof '
+      + '(skeleton lags reality); outside hub set = no conclusion. Use BEFORE recommending a route.',
+    parameters: {
+      from: { type: 'string', required: true, description: 'IATA, e.g. HKG' },
+      to: { type: 'string', required: true, description: 'IATA, e.g. HKT' },
+    },
+    output: {
+      // loose json(与兄弟工具一致):strict additionalProperties:false 会拒 guard 的
+      // 错误兜底字段(ok/summary),校验错掩盖真实错误
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { evidence?: string }).evidence ?? JSON.stringify(value)) }],
+    },
+    async execute(args: { from?: string; to?: string; query?: unknown } & Record<string, unknown>, _exec: unknown) {
+      // 平铺参数的工具也会被 LLM 包进 query(#12/#13 同款形态),unwrapQuery 兜住
+      const q = unwrapQuery<{ from?: string; to?: string }>(args)
+      const verdict = await checkConnectivity(String(q.from ?? ''), String(q.to ?? ''))
+      return JSON.parse(JSON.stringify({ ok: true, ...verdict })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `骨架校验:${args.from}-${args.to}`, kind: 'execute', rawInput: args }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_weather_check',
+    description:
+      'Check weather for a destination: forecast (≤16 days) or historical climate (seasonality baseline). '
+      + 'Free Open-Meteo API, no key required. Input: place name (Chinese ok) or lat/lng. '
+      + 'Returns daily temp range, precipitation probability, weather code — with evidence chain tagging '
+      + '[实时API:open-meteo@ts]. Use to ground seasonal advice in real data instead of LLM guessing.',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ place: "<城市名>", month?: 8, mode?: "forecast"|"climate", days?: 7 }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 600)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ place?: string; lat?: number; lng?: number; month?: number; mode?: string; days?: number }>(args, 'place')
+      const started = Date.now()
+      let lat: number | undefined = q.lat, lng: number | undefined = q.lng
+      let placeLabel = q.place ?? `${q.lat},${q.lng}`
+      if (lat === undefined || lng === undefined) {
+        if (!q.place) throw new Error('gotry_weather_check requires place name or lat/lng')
+        const geo = await geocodePlace(q.place)
+        if (!geo.ok || geo.results.length === 0) {
+          return JSON.parse(JSON.stringify({ ok: false, summary: `地点「${q.place}」地理编码失败:${geo.error ?? '无结果'}`, evidence: geo.evidence })) as Record<string, never>
+        }
+        const hit = geo.results[0]
+        lat = hit.latitude; lng = hit.longitude
+        placeLabel = `${hit.name}(${hit.admin1 ?? hit.country ?? ''})`
+      }
+      const isClimate = q.mode === 'climate' || (q.month !== undefined && q.mode !== 'forecast')
+      const r = isClimate
+        ? await getClimate({ latitude: lat, longitude: lng }, q.month ?? new Date().getMonth() + 1)
+        : await getForecast({ latitude: lat, longitude: lng }, { days: q.days })
+      const dir = await ensureStateDir(config.stateRoot)
+      await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `weather:${r.via}`).catch(() => {})
+      const dailyLines = (r.daily ?? []).slice(0, 7).map(d =>
+        `${d.date} ${d.tempMinC.toFixed(0)}–${d.tempMaxC.toFixed(0)}°C ${wmoLabel(d.weatherCode)}${d.precipProbMaxPct !== null ? ` 降水概率${d.precipProbMaxPct}%` : ''}`)
+      const summary = r.ok
+        ? `${placeLabel}:${isClimate ? '历史气候' : `${q.days ?? 7} 天预报`}\n${dailyLines.join('\n')}\n${r.evidence}`
+        : `${placeLabel}:天气查询失败(${r.error})${r.evidence}`
+      return JSON.parse(JSON.stringify({
+        ok: r.ok, place: placeLabel, mode: isClimate ? 'climate' : 'forecast',
+        daily: r.daily, evidence: r.evidence, summary,
+        latency_ms: Date.now() - started,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `天气:${String((args.query as { place?: string })?.place ?? '')}`, kind: 'fetch', rawInput: args.query }),
+    presentResult: (args, value) => {
+      const r = value as { summary?: string }
+      const place = String((args.query as { place?: string })?.place ?? '')
+      const failed = String(r.summary ?? '').includes('降级') || String(r.summary ?? '').includes('unavailable')
+      return {
+        card: 'generic',
+        title: `天气:${place} ${failed ? '降级' : 'ok'}`,
+        content: [{ type: 'text', text: String(r.summary ?? '') }],
+      }
+    },
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_flight_verify',
+    description:
+      'Verify whether a flight callsign is currently observable on the OpenSky ADS-B network. '
+      + 'Free anonymous API (~400 credits/day, 4 req/s burst). Three-valued semantics: '
+      + 'observed = strong positive (the aircraft is currently being broadcast); '
+      + 'not_observed = no conclusion (ADS-B coverage is limited by geography/altitude — '
+      + 'a missing signal does NOT disprove the flight); '
+      + 'unavailable = API failure, gracefully degraded. '
+      + 'Use to ground "is this flight actually flying right now?" in real data, complementing '
+      + 'the OpenFlights skeleton (historical connectivity) and the static flight pack (planned schedule).',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ callsign: "EK329", airport?: "OMDB", timeoutMs?: 10000 }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 500)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ callsign: string; airport?: string; timeoutMs?: number }>(args, 'callsign')
+      const started = Date.now()
+      if (!q.callsign) {
+        return JSON.parse(JSON.stringify({ verdict: 'unavailable', evidence: '[校验不可用:无 callsign]', summary: 'callsign 必填' })) as Record<string, never>
+      }
+      const r = await verifyFlight({ callsign: q.callsign, airport: q.airport, timeoutMs: q.timeoutMs })
+      const dir = await ensureStateDir(config.stateRoot)
+      await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `flight_verify:${r.via}`).catch(() => {})
+      const summary = r.verdict === 'observed'
+        ? `${r.callsign} 当前 ADS-B 观测命中 (${r.hits?.length ?? 0} 架)${r.airport ? ` 在 ${r.airport}` : ''}\n${r.evidence}`
+        : r.verdict === 'not_observed'
+          ? `${r.callsign} 当前观测列表未见(ADS-B 覆盖有限,不否定该航班存在)\n${r.evidence}`
+          : `${r.callsign} OpenSky 不可用:${r.error}\n${r.evidence}`
+      return JSON.parse(JSON.stringify({
+        ok: true,
+        verdict: r.verdict, callsign: r.callsign, airport: r.airport,
+        sample_size: r.sampleSize, hits: r.hits, evidence: r.evidence, summary,
+        latency_ms: Date.now() - started,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `飞行校验:${String((args.query as { callsign?: string })?.callsign ?? '')}`, kind: 'fetch', rawInput: args.query }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_flyai_search',
+    description:
+      'Live flight/train search via Fliggy official FlyAI channel (read-only, no key, booking only via jumpUrl by the human). '
+      + 'PRIMARY source for real schedules & prices (RFC user-session-data-rfc). Input: kind=flight|train, from/to city names (Chinese), date YYYY-MM-DD. '
+      + 'Evidence [实时API:flyai@ts]. Cross-validate expensive claims against gotry_session_search when it matters.',
+    parameters: {
+      query: { type: 'json', required: true, description: '{ kind: "flight"|"train", from: "上海", to: "丽江", date: "2026-10-01" }' },
+    },
+    output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String((v as { summary?: string }).summary ?? JSON.stringify(v).slice(0, 600)) }] },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ kind?: string; from?: string; to?: string; date?: string }>(args, 'from')
+      const kind = q.kind === 'train' ? 'train' : 'flight'
+      if (!q.from || !q.to || !q.date) {
+        return { ok: false, summary: '需要 from/to(中文城市名)与 date(YYYY-MM-DD)' } as const
+      }
+      const r = await flyaiSearch({ kind, origin: q.from, destination: q.to, 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}`
+      return JSON.parse(JSON.stringify({ ...r, kind, summary })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `官方检索:${String((args.query as { kind?: string })?.kind ?? 'flight')}`, kind: 'fetch', rawInput: args.query }),
+    presentResult: (args, value) => {
+      const r = value as { ok?: boolean; options?: unknown[] }
+      return { card: 'generic', title: `飞猪检索:${r.ok && (r.options?.length ?? 0) > 0 ? `${r.options!.length} 条` : '降级'}`, content: [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }] }
+    },
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_session_search',
+    description:
+      'Cross-validation search on the user\'s OWN logged-in browser session (dedicated persistent profile, ReadGuard = physically read-only: '
+      + 'write requests are aborted at network layer; agent NEVER touches credentials/captcha; on captcha it stops and returns challenged). '
+      + 'Currently ctrip-flight: sniffs the site search API for structured options. Evidence [会话:ctrip-flight@ts]. '
+      + 'verdict needs-login = run scripts/session-login.ts once with the human logging in. Rate-limited (≥30s between same-site calls). '
+      + 'Use to verify/double-check prices from gotry_flyai_search on the same itinerary (split by 直达/中转).',
+    parameters: {
+      query: { type: 'json', required: true, description: '{ from: "上海", to: "丽江", date: "2026-10-01" }' },
+    },
+    output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String((v as { summary?: string }).summary ?? JSON.stringify(v).slice(0, 600)) }] },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ from?: string; to?: string; date?: string }>(args, 'from')
+      if (!q.from || !q.to || !q.date) {
+        return { ok: false, summary: '需要 from/to(中文城市名,词表内)与 date(YYYY-MM-DD)' } as const
+      }
+      const r = await sessionFlightSearch({
+        from: q.from, to: q.to, date: q.date,
+        // ADR-15 收尾:ReadGuard 审计在生产工具路径同样落盘(此前仅测试传隔离 stateRoot 才有 JSONL)
+        auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
+      })
+      const top = (r.options ?? []).slice(0, 8).map(o => `${o.flightNo} ${o.airline} ${o.depDateTime.slice(11, 16)}→${o.arrDateTime.slice(11, 16)} ¥${o.price}`)
+      const summary = r.verdict === 'hit'
+        ? `${q.from}→${q.to} ${q.date} 会话检索(携程,用户本人登录态)前 ${top.length} 条:\n${top.join('\n')}\n${r.evidence}`
+        : `会话检索未取回(${r.verdict}):${r.error ?? ''} ${r.evidence}`
+      return JSON.parse(JSON.stringify({ ...r, summary })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `会话检索:${String((args.query as { from?: string })?.from ?? '')}`, kind: 'fetch', rawInput: args.query }),
+    presentResult: (_args, value) => {
+      const r = value as { verdict?: string; options?: unknown[] }
+      const label = r.verdict === 'hit' ? `会话 ${r.options!.length} 条` : (r.verdict === 'needs-login' ? '需登录' : r.verdict ?? '降级')
+      return { card: 'generic', title: `会话检索:${label}`, content: [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }] }
+    },
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_anything_search',
+    description:
+      'Travel-domain search via hotel-byte CLI → hotel-be Anything (cities/hotels/destinations) — NOT general web search; for general internet facts use gotry_agent_reach. ' +
+      'Mixed destinations (cities / metropolitan areas / high-level regions) + hotels in one call. ' +
+      'Returns candidates with type, name, optional coordinates and hotel-id. ' +
+      'Three-valued semantics: hit = ≥1 candidate; miss = 0 candidates (try synonyms or contentType=city/hotel); ' +
+      'unavailable = hbcli failed (degraded, never blocks). ' +
+      'Use as the first stop when the user mentions a place/city/hotel name and you need to ground it in real catalog data ' +
+      '(OpenFlights skeleton tells you connectivity; Anything tells you what EXISTS at a city/region).',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ keyword: "<搜索关键词>", contentType?: "city"|"hotel", parentDestinationId?: "?", timeoutMs?: 12000 }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 800)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ keyword: string; contentType?: 'city' | 'hotel'; parentDestinationId?: string | number; timeoutMs?: number }>(args, 'keyword')
+      const started = Date.now()
+      if (!q.keyword) {
+        return JSON.parse(JSON.stringify({ ok: false, verdict: 'error', summary: 'keyword 必填', evidence: '[hbcli-anything@error] empty' })) as Record<string, never>
+      }
+      const r = await anythingSearch(q)
+      const dir = await ensureStateDir(config.stateRoot)
+      await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `anything:${r.via}`).catch(() => {})
+      const top5 = (r.hits ?? []).slice(0, 5)
+      const summary = r.verdict === 'hit'
+        ? `${q.keyword} → hit (${r.hits?.length ?? 0} 候选项)\n${top5.map((h, i) => `  ${i + 1}. [${h.type}] ${h.name}${h.latitude !== undefined && h.longitude !== undefined ? ` @ (${h.latitude.toFixed(3)},${h.longitude.toFixed(3)})` : ''}`).join('\n')}\n${r.evidence}`
+        : r.verdict === 'miss'
+          ? `${q.keyword} → miss (酒店-be 一切正常但无候选)\n${r.evidence}`
+          : `${q.keyword} → unavailable (${r.error})\n${r.evidence}`
+      return JSON.parse(JSON.stringify({
+        ok: r.ok, verdict: r.verdict, keyword: q.keyword,
+        content_type: q.contentType ?? null,
+        total_candidates: r.totalCandidates, hits: r.hits, evidence: r.evidence, summary,
+        latency_ms: Date.now() - started,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `Anything search:${String((args.query as { keyword?: string })?.keyword ?? '')}`, kind: 'search', rawInput: args.query }),
+    presentResult: (_args, value) => {
+      const r = value as { hits?: unknown[]; total_candidates?: number; verdict?: string; keyword?: string; summary?: string }
+      const n = Array.isArray(r.hits) ? r.hits.length : (r.total_candidates ?? 0)
+      return {
+        card: 'generic',
+        title: `Anything:${r.keyword ?? ''} ${r.verdict === 'hit' ? `${n} hits` : (r.verdict ?? 'no-result')}`,
+        content: [{ type: 'text', text: String(r.summary ?? '') }],
+      }
+    },
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_web_search',
+    description:
+      'Read any public URL as markdown (Jina Reader, free, no key). ' +
+      'Use as the "last mile" web reader when hotel-be Anything or gotry tools lack the answer. ' +
+      'NOT a general-purpose search engine — only fetches a URL you already know. ' +
+      'Three-valued: ok / error(非法 URL/超时)/not-reachable(r.jina.ai 不可用).' +
+      'Contract with gotry capabilities/anything.ts: 同构(L4 证据链 + 降级不阻塞 + 三值)。',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ url: "https://example.com", timeoutMs?: 20000 }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { content?: string }).content?.slice(0, 800) ?? JSON.stringify(value).slice(0, 800)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ url?: string; timeoutMs?: number }>(args, 'url')
+      const started = Date.now()
+      if (!q.url) {
+        return JSON.parse(JSON.stringify({ ok: false, summary: 'url 必填', evidence: '[agent-reach:error] empty url' })) as Record<string, never>
+      }
+      const r = await readUrl({ url: q.url, timeoutMs: q.timeoutMs })
+      const dir = await ensureStateDir(config.stateRoot)
+      await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `agent-reach:${r.via}`).catch(() => {})
+      const summary = r.ok
+        ? `${q.url} → ${r.title ?? '(no title)'} (${r.latencyMs}ms)\n${r.evidence}\n---\n${r.content?.slice(0, 600) ?? ''}`
+        : `${q.url} → unavailable (${r.error})\n${r.evidence}`
+      return JSON.parse(JSON.stringify({
+        ok: r.ok, url: q.url, via: r.via, title: r.title,
+        content: r.content, evidence: r.evidence, summary,
+        latency_ms: Date.now() - started,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `读网页:${String((args.query as { url?: string })?.url ?? '')}`, kind: 'fetch', rawInput: args.query }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_video_subtitle',
+    description:
+      'Extract subtitles from a YouTube/Bilibili video (yt-dlp, optional tool). ' +
+      'If yt-dlp is installed on this machine, returns the subtitle text (vtt, zh-Hans/zh/en preference). ' +
+      'If NOT installed, degrades gracefully with install instructions — never blocks. ' +
+      'Evidence chain: [agent-reach:yt-dlp@ts] / [@not-installed@ts].',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ url: "https://www.youtube.com/watch?v=...", lang?: "zh-Hans,zh,en" }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 600)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ url?: string; lang?: string }>(args, 'url')
+      if (!q.url) {
+        return JSON.parse(JSON.stringify({ ok: false, summary: 'url 必填' })) as Record<string, never>
+      }
+      const r = await videoSubtitle({ url: q.url, lang: q.lang })
+      const summary = r.verdict === 'found'
+        ? `${q.url} 字幕提取成功 (${r.latencyMs}ms)\n${r.evidence}\n---\n${(r.subtitles ?? '').slice(0, 800)}`
+        : r.verdict === 'not-installed'
+          ? `yt-dlp 未安装。${r.stderr}\n${r.evidence}`
+          : `${q.url} 字幕提取失败(${r.verdict})\n${r.evidence}`
+      return JSON.parse(JSON.stringify({
+        ok: r.ok, verdict: r.verdict, url: q.url,
+        subtitles: r.subtitles?.slice(0, 4000), evidence: r.evidence, summary,
+        latency_ms: r.latencyMs,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `视频字幕:${String((args.query as { url?: string })?.url ?? '')}`, kind: 'fetch', rawInput: args.query }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_github_search',
+    description:
+      'Search GitHub repositories (gh CLI, optional tool). ' +
+      'If gh is installed and authenticated, returns repos with name/description/stars/url. ' +
+      'If NOT installed, degrades with install instructions — never blocks. ' +
+      'Evidence chain: [agent-reach:gh@ts] / [@not-installed@ts].',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ query: "agent-reach", limit?: 5 }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 600)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ query?: string; limit?: number }>(args, 'query')
+      if (!q.query) {
+        return JSON.parse(JSON.stringify({ ok: false, summary: 'query 必填' })) as Record<string, never>
+      }
+      const r = await githubSearch({ query: q.query, limit: q.limit })
+      const summary = r.verdict === 'found'
+        ? `${q.query} → ${r.repos?.length ?? 0} repos\n${(r.repos ?? []).map((x, i) => `  ${i + 1}. ${x.name} ★${x.stars ?? '?'} — ${(x.description ?? '').slice(0, 60)}`).join('\n')}\n${r.evidence}`
+        : r.verdict === 'not-installed'
+          ? `gh 未安装。${r.stderr}\n${r.evidence}`
+          : `${q.query} 搜索失败(${r.verdict})\n${r.evidence}`
+      return JSON.parse(JSON.stringify({
+        ok: r.ok, verdict: r.verdict, query: q.query,
+        repos: r.repos, evidence: r.evidence, summary,
+        latency_ms: r.latencyMs,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `GitHub 搜索:${String((args.query as { query?: string })?.query ?? '')}`, kind: 'search', rawInput: args.query }),
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_agent_reach',
+    description:
+      'Agent Reach — the PRIMARY external-data gateway (thin wrapper over Panniantong/Agent-Reach upstream registry, zero channel knowledge here). ' +
+      'Prefer this for ANY external/internet fact beyond weather/flights/hotels. ' +
+      'Call ANY upstream channel method by reflection: web.read(url) / v2ex.get_hot_topics() / v2ex.search(query) / ' +
+      'xueqiu.get_stock_quote(symbol) / xueqiu.search_stock(query) / youtube.transcribe(url) / <channel>.check() ... ' +
+      'Unknown channel or method? Just call it — the error returns the upstream inventory (channel list or method signatures) so you can self-correct. ' +
+      'Action "status" runs the real `agent-reach doctor` (.venv/bin/agent-reach). ' +
+      'Channels needing cookies/setup return the upstream check() guidance verbatim — do NOT give up there: hand the user the exact configure command, then offer to re-check. ' +
+      'Evidence chain: [agent-reach:<channel>.<method>@ts].',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ action: "status" } 或 { action: "reach", channel: "<上游渠道名,如 web/v2ex/xueqiu>", method: "<上游方法名,如 read/get_hot_topics/get_stock_quote>", args?: "<空格分隔参数>" }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 800)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ action?: string; channel?: string; method?: string; args?: string; timeoutMs?: number }>(args, 'channel')
+      const started = Date.now()
+      const dir = await ensureStateDir(config.stateRoot)
+
+      if (q.action === 'status' || (!q.action && !q.channel)) {
+        const st = await reachStatus(q.timeoutMs)
+        await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, 'agent-reach:doctor').catch(() => {})
+        const summary = st.via === 'agent-reach-cli'
+          ? `Agent Reach doctor(上游 CLI,原样透传):\n${st.output}\n${st.evidence}`
+          : `Agent Reach 未装:\n${st.output}\n${st.evidence}`
+        return JSON.parse(JSON.stringify({
+          ok: st.ok, via: st.via, output: st.output, evidence: st.evidence, summary,
+          latency_ms: Date.now() - started,
+        })) as Record<string, never>
+      }
+
+      if (!q.channel || !q.method) {
+        return JSON.parse(JSON.stringify({ ok: false, summary: 'channel 与 method 必填(或 action=status);清单可先随便调一次,inventory 会带回上游渠道/方法表' })) as Record<string, never>
+      }
+      const r = await reach({ channel: q.channel, method: q.method, args: q.args, timeoutMs: q.timeoutMs })
+      // 长结果干净截断:数组按条目边界保留(dsh 工具上限会拦腰断 JSON,模型只能看到半条)
+      const dataStr = (v: unknown): unknown => {
+        if (Array.isArray(v)) {
+          const kept: unknown[] = []
+          let budget = 3500
+          for (const item of v) {
+            const s = JSON.stringify(item)
+            if (budget - s.length < 0) break
+            budget -= s.length + 1
+            kept.push(item)
+          }
+          if (kept.length < v.length) kept.push(`…(截断:保留 ${kept.length}/${v.length} 条;可用上游方法带 limit 参数取更少)`)
+          return kept
+        }
+        if (typeof v === 'string') return v.length > 4000 ? v.slice(0, 4000) + '…(截断)' : v
+        return v
+      }
+      if (r.ok) r.data = dataStr(r.data)
+      await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `agent-reach:${q.channel}.${q.method}:${r.verdict}`).catch(() => {})
+      const summary = r.verdict === 'found'
+        ? `${q.channel}.${q.method} → found (${r.latencyMs}ms)\n${r.evidence}\n${typeof r.data === 'string' ? r.data.slice(0, 600) : JSON.stringify(r.data ?? null).slice(0, 600)}`
+        : r.verdict === 'needs-setup'
+          ? `${q.channel}.${q.method} → 需配置(上游 check() 原话): ${r.setup ?? ''}\n${r.evidence}`
+          : r.verdict === 'not-installed'
+            ? `${q.channel}.${q.method} → 上游未装: ${r.setup ?? ''}\n${r.evidence}`
+            : `${q.channel}.${q.method} → ${r.error ?? 'error'}${r.inventory ? `\n上游清单: ${JSON.stringify(r.inventory).slice(0, 1200)}` : ''}\n${r.evidence}`
+      return JSON.parse(JSON.stringify({
+        ok: r.ok, channel: r.channel, method: q.method, verdict: r.verdict,
+        data: typeof r.data === 'string' ? r.data.slice(0, 4000) : r.data,
+        inventory: r.inventory, setup: r.setup, evidence: r.evidence, summary,
+        latency_ms: Date.now() - started,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `Agent Reach:${String((args.query as { channel?: string; method?: string })?.channel ?? '')}.${String((args.query as { method?: string })?.method ?? 'status')}`, kind: 'fetch', rawInput: args.query }),
+    presentResult: (args, value) => {
+      const r = value as { verdict?: string; summary?: string }
+      const q = (args.query as { channel?: string; method?: string }) ?? {}
+      const icon = r.verdict === 'found' ? '✅' : r.verdict === 'needs-setup' ? '🔧' : r.verdict === 'not-installed' ? '📦' : '❌'
+      return {
+        card: 'generic',
+        title: `AgentReach ${icon} ${q.channel ?? ''}.${q.method ?? 'status'} ${r.verdict ?? ''}`,
+        content: [{ type: 'text', text: String(r.summary ?? '') }],
+      }
+    },
+  }))
+}