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

package/ts/src/index.ts

@@ -14,20 +14,30 @@
  */
 
 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, readJson, recordLatency, writeJson } from './bridge.ts'
+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']
@@ -49,6 +59,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 +75,58 @@ 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 据此决定是否访谈。只读,不猜——画像里没有的字段不编。
+ * 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 }
 
@@ -78,6 +142,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 +173,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 +202,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 +231,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 +242,27 @@ 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 守门合并进既有画像(追加不删史/幂等/权重变更须伴新证据),
+      // 不再整档覆盖。首次调用(无档案)= 全量建立。
+      // 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 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
-      await writeJson(path, saved)
-      return { saved: true, path, profile: saved }
-    },
-    presentCall: args => ({ card: 'generic', title: '保存动机画像', kind: 'other', rawInput: args.profile }),
+      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({
@@ -180,62 +270,184 @@ 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
-      if (!entry.name || !entry.conditions) {
-        throw new Error('wish pool entry requires name and conditions (fulfilment conditions are the whole point)')
+      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
       }
-      const dir = await ensureStateDir(config.stateRoot)
-      const path = join(dir, 'wish-pool.json')
-      const pool = (await readJson(path, [])) as Array<Record<string, unknown>>
-      // 同名憧憬幂等更新(刷新理由与成行条件),不重复落盘
-      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 }
-        await writeJson(path, pool)
-        return { added: false, total: pool.length, path }
+      // 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
       }
-      pool.push({ reason: '', ...entry, added_at: new Date().toISOString() })
-      await writeJson(path, pool)
-      return { added: true, total: pool.length, path }
+      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: "<用户原话>" }',
+      },
     },
-    presentCall: args => ({ card: 'generic', title: '加入「下一次出发」清单', kind: 'other', rawInput: args.entry }),
+    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. 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 +455,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 +482,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 +490,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 +517,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 +542,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 +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, 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 +581,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 +617,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 +631,85 @@ 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_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:
-      '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 +720,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 +728,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 +749,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 +781,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 +798,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 +820,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 +836,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 +858,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 +874,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 +900,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 +920,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 +953,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 ?? '') }],
+      }
+    },
   }))
 }