@danceiny/gotry 0.0.1-rc.7 → 0.0.1-rc.8

package/ts/src/index.ts

@@ -14,6 +14,8 @@
  */
 
 import { join } from 'node:path'
+import { readFile, writeFile } from 'node:fs/promises'
+import { readFileSync } from 'node:fs'
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
@@ -23,6 +25,12 @@ 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 { appendEvent, projectUtility, type MemoryUtilityEvent } from './memory-utility.ts'
+import { pickNudgeWish, type WishPoolEntry } from './wish-pool.ts'
+import { mergeProfile } from './memory-capture.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'
@@ -49,6 +57,8 @@ export const Config: z<Config> = z.object({
 
 interface FeasibilityResult {
   answer_md?: string
+  recommended?: string | null
+  verdicts?: Array<Record<string, unknown>>
 }
 
 interface MotivationProfileInput {
@@ -63,6 +73,34 @@ interface WishPoolEntryInput {
   conditions?: Record<string, unknown>
 }
 
+
+/**
+ * query 包装参数的三形态归一(#12/#13):实现移居 tool-packet.ts(interpretArgs,
+ * RFC S1 interpretation 层语义归位),此处按旧名引 handy 别名,调用点零漂移。
+ */
+const unwrapQuery = interpretArgs
+
+/**
+ * 动机画像 → persona 紧凑 brief(M4 T1 读回路径):空文件返回 ''(首访),
+ * persona 据此决定是否访谈。只读,不猜——画像里没有的字段不编。
+ */
+function renderMotivationBrief(stateRoot: string): string {
+  try {
+    const raw = readFileSync(join(stateRoot, 'gotry-state', 'motivation-profile.json'), 'utf-8')
+    const p = JSON.parse(raw) as { weights?: Record<string, number>; evidence?: string[]; hard?: Record<string, unknown>; updated_at?: string }
+    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(', ')}`)
+    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') : ''
+  } catch {
+    return '' // 首访:无画像
+  }
+}
+
 type Json = string | number | boolean | null | Json[] | { [k: string]: Json }
 type JsonObject = { [k: string]: Json }
 
@@ -78,6 +116,14 @@ export function apply(ctx: Context, config: Config): void {
     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 写事故证据
@@ -101,7 +147,8 @@ export function apply(ctx: Context, config: Config): void {
       '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), same shape as data/golden_erhai.json. '
+      + '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: {
@@ -129,9 +176,28 @@ export function apply(ctx: Context, config: Config): void {
       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 { ...result, latency_ms: Date.now() - started, via: 'in-process-unified' }
+      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) }],
+      }
     },
-    presentCall: args => ({ card: 'generic', title: 'GoTry 可行性检查(门到门全成本)', kind: 'other', rawInput: args.payload }),
   }))
 
   registerGuarded(defineTool({
@@ -139,8 +205,9 @@ export function apply(ctx: Context, config: Config): void {
     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. Requires an evidence field: every weight must trace '
-      + 'back to the user\'s own words (P0 anti-fabrication rule).',
+      + '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',
@@ -149,30 +216,35 @@ export function apply(ctx: Context, config: Config): void {
       },
     },
     output: {
-      schema: {
-        type: 'object',
-        additionalProperties: false,
-        properties: {
-          saved: { type: 'boolean' },
-          path: { type: 'string' },
-          profile: { type: 'json' },
-        },
-      },
+      // 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) {
-      const profile = (args.profile ?? {}) as MotivationProfileInput
-      if (!profile.evidence?.length) {
+      // T1 接线:本工具是增量补丁语义(契约 18——模型每轮把对话新事实带进来),
+      // 经 mergeProfile 守门合并进既有画像(追加不删史/幂等/权重变更须伴新证据),
+      // 不再整档覆盖。首次调用(无档案)= 全量建立。
+      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 dir = await ensureStateDir(config.stateRoot)
       const path = join(dir, 'motivation-profile.json')
-      // JSON 往返保证落盘值与输出值都是 JsonValue(输出 schema 的硬要求)
-      const saved = JSON.parse(JSON.stringify({ ...profile, updated_at: new Date().toISOString() })) as JsonObject
+      let existing: { weights?: Record<string, number>; evidence?: string[]; hard?: Record<string, unknown> } | null = null
+      try {
+        existing = await readJson<typeof existing>(path, null)
+      } catch { /* 首次保存:无档案 */ }
+      const merged = mergeProfile(existing, { weights: incoming.weights, evidence: incoming.evidence, hard: incoming.hard })
+      if (!merged) {
+        // 幂等:补丁与现有画像完全一致,不落盘
+        const currentJson = JSON.parse(JSON.stringify({ ...(existing ?? {}), updated_at: new Date().toISOString() })) as JsonObject
+        return { ok: true, saved: false, path, profile: currentJson, summary: '无新内容(幂等跳过)' }
+      }
+      const saved = JSON.parse(JSON.stringify({ ...merged, updated_at: new Date().toISOString() })) as JsonObject
       await writeJson(path, saved)
-      return { saved: true, path, profile: saved }
+      return { ok: true, saved: true, path, profile: saved, summary: '画像已合并落盘' }
     },
-    presentCall: args => ({ card: 'generic', title: '保存动机画像', kind: 'other', rawInput: args.profile }),
+    presentCall: args => ({ card: 'generic', title: '保存动机画像', kind: 'edit', rawInput: args.profile }),
   }))
 
   registerGuarded(defineTool({
@@ -180,62 +252,135 @@ export function apply(ctx: Context, config: Config): void {
     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. 憧憬不被拒绝。',
+      + '"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 } }',
+        description: '{ name, reason?, conditions: { days, budget_cny, best_months }, muted?: boolean }',
       },
     },
     output: {
-      schema: {
-        type: 'object',
-        additionalProperties: false,
-        properties: {
-          added: { type: 'boolean' },
-          total: { type: 'integer' },
-          path: { type: 'string' },
-        },
-      },
+      // 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
+      const entry = (args.entry ?? {}) as WishPoolEntryInput & { muted?: boolean }
       if (!entry.name || !entry.conditions) {
         throw new Error('wish pool entry requires name and conditions (fulfilment conditions are the whole point)')
       }
       const dir = await ensureStateDir(config.stateRoot)
       const path = join(dir, 'wish-pool.json')
       const pool = (await readJson(path, [])) as Array<Record<string, unknown>>
-      // 同名憧憬幂等更新(刷新理由与成行条件),不重复落盘
+      // 同名憧憬幂等更新(刷新理由与成行条件),不重复落盘;wish_id 稳定(存量补签)
       const existing = pool.findIndex(e => e['name'] === entry.name)
       if (existing >= 0) {
-        pool[existing] = { ...pool[existing], reason: entry.reason ?? pool[existing]?.['reason'], conditions: entry.conditions }
+        const prev = pool[existing] ?? {}
+        pool[existing] = {
+          ...prev,
+          wish_id: prev['wish_id'] ?? `w${Date.now().toString(36)}`,
+          reason: entry.reason ?? prev['reason'],
+          conditions: entry.conditions,
+          ...(entry.muted !== undefined ? { muted: entry.muted } : {}),
+        }
         await writeJson(path, pool)
-        return { added: false, total: pool.length, path }
+        return { ok: true, added: false, wish_id: String(pool[existing]?.['wish_id']), total: pool.length, path }
       }
-      pool.push({ reason: '', ...entry, added_at: new Date().toISOString() })
+      const created = { wish_id: `w${Date.now().toString(36)}`, reason: '', ...entry, added_at: new Date().toISOString() }
+      pool.push(created)
       await writeJson(path, pool)
-      return { added: true, total: pool.length, path }
+      return { ok: true, added: true, wish_id: created.wish_id, total: pool.length, path }
     },
-    presentCall: args => ({ card: 'generic', title: '加入「下一次出发」清单', kind: 'other', rawInput: args.entry }),
+    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?: number, budgetCny?: number, month?: number, wishId?: string, attribution?: "helpful"|"harmful"|"neutral", detail?: string }',
+      },
+    },
+    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 }>(args, 'action')
+      const dir = await ensureStateDir(config.stateRoot)
+      const pool = (await readJson(join(dir, 'wish-pool.json'), [])) as Array<Record<string, unknown>>
+      const sidecarPath = join(dir, 'memory-utility.jsonl')
+      const loadSidecar = async (): Promise<MemoryUtilityEvent[]> => {
+        try {
+          const raw = await readFile(sidecarPath, 'utf-8')
+          return raw.split('\n').filter(Boolean).map(l => JSON.parse(l) as MemoryUtilityEvent)
+        } catch { return [] } // fail-open:sidecar 缺失/损坏不阻塞召回
+      }
+      const saveSidecar = async (events: MemoryUtilityEvent[]) => {
+        await writeFile(sidecarPath, events.map(e => JSON.stringify(e)).join('\n') + '\n', 'utf-8')
+      }
+      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
+        }
+        const events = await loadSidecar()
+        const { events: next, appended } = appendEvent(events, {
+          wish_id: q.wishId, kind: 'verified_outcome', ts: now,
+          ctx: 'gotry_wish_pool_list.confirm', detail: q.detail, attribution: q.attribution,
+        })
+        if (appended) await saveSidecar(next)
+        return { ok: true, recorded: appended, wish_id: q.wishId, status: q.attribution } as never
+      }
+      // recall:0..1 条件匹配(判定归 wish-pool 纯函数),muted 永不召回,无命中不硬推
+      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 = await loadSidecar()
+      const { events: next, appended } = appendEvent(events, {
+        wish_id: match.wishId, kind: 'recalled', ts: now, ctx: 'gotry_wish_pool_list.recall',
+      })
+      if (appended) await saveSidecar(next)
+      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_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. Output: hotel list with evidence chain ([realtime-API:hbcli] + fetch timestamp, '
+      + '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?: "2026-07-18", checkOut?: "2026-07-23", occupancy?: { adults: 2 } }',
+        description: '{ destination: "<目的地城市>", checkIn?: "YYYY-MM-DD 或自然表达(下周五/8.20)", checkOut?: 同上, occupancy?: { adults: 2 } }',
       },
     },
     output: {
@@ -243,12 +388,26 @@ export function apply(ctx: Context, config: Config): void {
       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 = (args.query ?? {}) as { destination?: string; checkIn?: string; checkOut?: string; adults?: number }
+      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: q.checkIn, checkOut: q.checkOut, adults: q.adults },
+        { 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)
@@ -256,6 +415,7 @@ export function apply(ctx: Context, config: Config): void {
       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,
@@ -263,10 +423,20 @@ export function apply(ctx: Context, config: Config): void {
         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 ?? '') }],
       }
-      return JSON.parse(JSON.stringify(payload)) as Record<string, unknown>
     },
-    presentCall: args => ({ card: 'generic', title: `酒店搜索:${String((args.query as { destination?: string })?.destination ?? '')}`, kind: 'other', rawInput: args.query }),
   }))
 
   registerGuarded(defineTool({
@@ -280,22 +450,18 @@ export function apply(ctx: Context, config: Config): void {
       to: { type: 'string', required: true, description: 'IATA, e.g. HKT' },
     },
     output: {
-      schema: {
-        type: 'object',
-        additionalProperties: false,
-        properties: {
-          connected: { type: 'boolean' },
-          airlines: { type: 'array', items: { type: 'string' } },
-          evidence: { type: 'string' },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: String((value as { evidence?: string }).evidence ?? '') }],
+      // 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 }, _exec: unknown) {
-      const verdict = await checkConnectivity(args.from, args.to)
-      return JSON.parse(JSON.stringify(verdict)) as Record<string, never>
+    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: 'other', rawInput: args }),
+    presentCall: args => ({ card: 'generic', title: `骨架校验:${args.from}-${args.to}`, kind: 'execute', rawInput: args }),
   }))
 
   registerGuarded(defineTool({
@@ -309,7 +475,7 @@ export function apply(ctx: Context, config: Config): void {
       query: {
         type: 'json',
         required: true,
-        description: '{ place: "大理市", month?: 8, mode?: "forecast"|"climate", days?: 7 }',
+        description: '{ place: "<城市名>", month?: 8, mode?: "forecast"|"climate", days?: 7 }',
       },
     },
     output: {
@@ -317,7 +483,7 @@ export function apply(ctx: Context, config: Config): void {
       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 = (args.query ?? {}) as { place?: string; lat?: number; lng?: number; month?: number; mode?: string; days?: number }
+      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}`
@@ -348,7 +514,17 @@ export function apply(ctx: Context, config: Config): void {
         latency_ms: Date.now() - started,
       })) as Record<string, never>
     },
-    presentCall: args => ({ card: 'generic', title: `天气:${String((args.query as { place?: string })?.place ?? '')}`, kind: 'other', rawInput: args.query }),
+    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({
@@ -374,7 +550,7 @@ export function apply(ctx: Context, config: Config): void {
       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 = (args.query ?? {}) as { callsign: string; airport?: string; timeoutMs?: number }
+      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>
@@ -388,18 +564,19 @@ export function apply(ctx: Context, config: Config): void {
           ? `${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: 'other', rawInput: args.query }),
+    presentCall: args => ({ card: 'generic', title: `飞行校验:${String((args.query as { callsign?: string })?.callsign ?? '')}`, kind: 'fetch', rawInput: args.query }),
   }))
 
   registerGuarded(defineTool({
     name: 'gotry_anything_search',
     description:
-      'Universal Anything search via hotel-byte CLI → hotel-be Anything endpoint. ' +
+      '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); ' +
@@ -410,7 +587,7 @@ export function apply(ctx: Context, config: Config): void {
       query: {
         type: 'json',
         required: true,
-        description: '{ keyword: "大理", contentType?: "city"|"hotel", parentDestinationId?: "?", timeoutMs?: 12000 }',
+        description: '{ keyword: "<搜索关键词>", contentType?: "city"|"hotel", parentDestinationId?: "?", timeoutMs?: 12000 }',
       },
     },
     output: {
@@ -418,7 +595,7 @@ export function apply(ctx: Context, config: Config): void {
       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 = (args.query ?? {}) as { keyword: string; contentType?: 'city' | 'hotel'; parentDestinationId?: string | number; timeoutMs?: number }
+      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>
@@ -439,7 +616,16 @@ export function apply(ctx: Context, config: Config): void {
         latency_ms: Date.now() - started,
       })) as Record<string, never>
     },
-    presentCall: args => ({ card: 'generic', title: `Anything search:${String((args.query as { keyword?: string })?.keyword ?? '')}`, kind: 'other', rawInput: args.query }),
+    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({
@@ -462,7 +648,7 @@ export function apply(ctx: Context, config: Config): void {
       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 = (args.query ?? {}) as { url?: string; timeoutMs?: number }
+      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>
@@ -479,7 +665,7 @@ export function apply(ctx: Context, config: Config): void {
         latency_ms: Date.now() - started,
       })) as Record<string, never>
     },
-    presentCall: args => ({ card: 'generic', title: `读网页:${String((args.query as { url?: string })?.url ?? '')}`, kind: 'other', rawInput: args.query }),
+    presentCall: args => ({ card: 'generic', title: `读网页:${String((args.query as { url?: string })?.url ?? '')}`, kind: 'fetch', rawInput: args.query }),
   }))
 
   registerGuarded(defineTool({
@@ -501,7 +687,7 @@ export function apply(ctx: Context, config: Config): void {
       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 = (args.query ?? {}) as { url?: string; lang?: string }
+      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>
       }
@@ -517,7 +703,7 @@ export function apply(ctx: Context, config: Config): void {
         latency_ms: r.latencyMs,
       })) as Record<string, never>
     },
-    presentCall: args => ({ card: 'generic', title: `视频字幕:${String((args.query as { url?: string })?.url ?? '')}`, kind: 'other', rawInput: args.query }),
+    presentCall: args => ({ card: 'generic', title: `视频字幕:${String((args.query as { url?: string })?.url ?? '')}`, kind: 'fetch', rawInput: args.query }),
   }))
 
   registerGuarded(defineTool({
@@ -539,7 +725,7 @@ export function apply(ctx: Context, config: Config): void {
       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 = (args.query ?? {}) as { query?: string; limit?: number }
+      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>
       }
@@ -555,18 +741,19 @@ export function apply(ctx: Context, config: Config): void {
         latency_ms: r.latencyMs,
       })) as Record<string, never>
     },
-    presentCall: args => ({ card: 'generic', title: `GitHub 搜索:${String((args.query as { query?: string })?.query ?? '')}`, kind: 'other', rawInput: args.query }),
+    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 — thin wrapper over Panniantong/Agent-Reach upstream registry (zero channel knowledge here). ' +
+      '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 (never blocks). ' +
+      '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: {
@@ -580,7 +767,7 @@ export function apply(ctx: Context, config: Config): void {
       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 = (args.query ?? {}) as { action?: string; channel?: string; method?: string; args?: string; timeoutMs?: number }
+      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)
 
@@ -600,6 +787,24 @@ export function apply(ctx: Context, config: Config): void {
         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)}`
@@ -615,6 +820,16 @@ export function apply(ctx: Context, config: Config): void {
         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: 'other', rawInput: args.query }),
+    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 ?? '') }],
+      }
+    },
   }))
 }