@danceiny/gotry 0.0.1-rc.13 → 0.0.1-rc.15

package/ts/src/booking-saga.ts

@@ -0,0 +1,133 @@
+/**
+ * 预订 saga 状态机(booking_saga_fsm.v1)——issue #17 采纳三点的具名化落点。
+ *
+ * 立场(docs/booking-saga-fsm.md / ADR-17):不引入编排框架;预订 saga 的状态字母表与边表
+ * 就是账本 pending_writes(status CHECK:pending|confirmed|compensated)的显式化。
+ * 本模块是纯函数词汇层,零依赖、零行为、不接线任何 seam——M5 拍板 WriteGate 生产化时
+ * 以此为唯一状态推进词汇(具名化 = 状态与边不再散落在 SQL 字符串里)。
+ *
+ * 物理对账目标(state-ledger.ts,TS-4 基座):
+ *  - propose  = requestPendingWrite(∅ → pending,L2 只登记不执行;idem_key UNIQUE,重复提议 no-op)
+ *  - confirm  = confirmPendingWrite(pending → confirmed,L3 具名 seam 确认,携 receipt;无 receipt 则视为缺省空串)
+ *  - compensate = compensatePendingWrite(pending|confirmed → compensated,吸收态,无出边)
+ *  - 审计事件 kind:write.pending / write.confirmed / write.compensated
+ */
+
+export const BOOKING_SAGA_SCHEMA = 'booking_saga_fsm.v1'
+
+export type SagaStatus = 'pending' | 'confirmed' | 'compensated'
+export type SagaOrigin = 'none' | SagaStatus
+export type SagaTrigger = 'propose' | 'confirm' | 'compensate'
+export type SagaLedgerEvent = 'write.pending' | 'write.confirmed' | 'write.compensated'
+
+/** 状态字母表(与 pending_writes.status CHECK 约束逐字一致) */
+export const SAGA_STATUSES = ['pending', 'confirmed', 'compensated'] as const satisfies readonly SagaStatus[]
+
+export interface SagaEdge {
+  from: SagaOrigin
+  trigger: SagaTrigger
+  to: SagaStatus
+  event: SagaLedgerEvent
+  /** 边的守卫说明;物理执行在账本事务内(UNIQUE 守卫/CHECK),此处为语义面 */
+  guard: string
+}
+
+/**
+ * 边表(预订流程 FSM 的全部合法转移):
+ *  ∅ --propose--> pending --confirm--> confirmed
+ *        │             │
+ *        └---(任何状态) --compensate--> compensated(吸收态,无出边)
+ */
+export const SAGA_EDGES: ReadonlyArray<SagaEdge> = [
+  { from: 'none', trigger: 'propose', to: 'pending', event: 'write.pending', guard: 'L2 只登记不执行;idem_key UNIQUE(重复提议 no-op)' },
+  { from: 'pending', trigger: 'confirm', to: 'confirmed', event: 'write.confirmed', guard: 'L3 具名 seam 确认,必携 receipt;已确认不可再确认' },
+  { from: 'pending', trigger: 'compensate', to: 'compensated', event: 'write.compensated', guard: '外部写未发生,取消即终态(无补偿动作)' },
+  { from: 'confirmed', trigger: 'compensate', to: 'compensated', event: 'write.compensated', guard: '已发生副作用的 saga 补偿(退改),receipt 保留(COALESCE)' },
+]
+
+export type SagaRejection =
+  | 'missing-subject'
+  | 'idem-exists'
+  | 'already-confirmed'
+  | 'absorbed-compensated'
+  | 'already-compensated'
+
+/** 非边组合的拒绝理由(结构化,拒绝即不动——与账本 changes=0 同义) */
+export const SAGA_REJECTIONS: ReadonlyArray<{ from: SagaOrigin; trigger: SagaTrigger; reason: SagaRejection }> = [
+  { from: 'none', trigger: 'confirm', reason: 'missing-subject' },
+  { from: 'none', trigger: 'compensate', reason: 'missing-subject' },
+  { from: 'pending', trigger: 'propose', reason: 'idem-exists' },
+  { from: 'confirmed', trigger: 'propose', reason: 'idem-exists' },
+  { from: 'confirmed', trigger: 'confirm', reason: 'already-confirmed' },
+  { from: 'compensated', trigger: 'propose', reason: 'idem-exists' },
+  { from: 'compensated', trigger: 'confirm', reason: 'absorbed-compensated' },
+  { from: 'compensated', trigger: 'compensate', reason: 'already-compensated' },
+]
+
+export type SagaVerdict =
+  | { ok: true; from: SagaOrigin; trigger: SagaTrigger; to: SagaStatus; event: SagaLedgerEvent; guard: string; reason: null }
+  | { ok: false; from: SagaOrigin; trigger: SagaTrigger; to: null; event: null; guard: null; reason: SagaRejection }
+
+/** 触发解析:唯一归宿或结构化拒绝(预订 seam 的状态推进只许走这张表的边) */
+export function resolveSagaTrigger(origin: SagaOrigin, trigger: SagaTrigger): SagaVerdict {
+  const edge = SAGA_EDGES.find(e => e.from === origin && e.trigger === trigger)
+  if (edge) return { ok: true, from: origin, trigger, to: edge.to, event: edge.event, guard: edge.guard, reason: null }
+  const rejection = SAGA_REJECTIONS.find(e => e.from === origin && e.trigger === trigger)
+  return { ok: false, from: origin, trigger, to: null, event: null, guard: null, reason: rejection!.reason }
+}
+
+/** 触发器 → 账本事件 kind 的唯一映射(写入侧命名不再各处硬编码) */
+export const SAGA_TRIGGER_EVENT: Record<SagaTrigger, SagaLedgerEvent> = {
+  propose: 'write.pending',
+  confirm: 'write.confirmed',
+  compensate: 'write.compensated',
+}
+
+/** 账本事件 kind → 触发器(读取/审计侧);非 saga 事件返回 null */
+export function triggerOfEventKind(kind: string): SagaTrigger | null {
+  if (kind === 'write.pending') return 'propose'
+  if (kind === 'write.confirmed') return 'confirm'
+  if (kind === 'write.compensated') return 'compensate'
+  return null
+}
+
+export interface SagaAuditEvent {
+  seq?: number
+  kind: string
+  /** write.confirmed 携带的外部回执(payload.receipt) */
+  receipt?: string | null
+}
+
+/**
+ * 审计链校验(单 idem_key 的 write.* 事件序列):必须恰好走出边表的一条合法路径。
+ *  - 链以 write.pending 开头;
+ *  - confirm/compensate 至多各一次;
+ *  - compensated 之后不允许任何 saga 事件(吸收态);
+ *  - write.confirmed 的 receipt 为空(缺省/空串)即违例——L3 具名确认必携外部回执;
+ *  - 非 write.* 事件(其他域审计)穿插不计。
+ * 返回违例清单(空数组 = 链合法)。
+ */
+export function sagaTraceViolations(events: ReadonlyArray<SagaAuditEvent>): string[] {
+  const violations: string[] = []
+  let stage: SagaOrigin = 'none'
+  for (const ev of events) {
+    const trigger = triggerOfEventKind(ev.kind)
+    if (!trigger) continue
+    const verdict = resolveSagaTrigger(stage, trigger)
+    const at = `seq=${ev.seq ?? '?'} ${ev.kind}`
+    if (!verdict.ok) {
+      violations.push(`${at}: 非法(${stage} --${trigger}--> 拒绝 ${verdict.reason})`)
+      continue
+    }
+    stage = verdict.to
+    if (trigger === 'confirm' && (ev.receipt === undefined || ev.receipt === null || ev.receipt === '')) {
+      violations.push(`${at}: receipt 为空(L3 具名确认必携外部回执)`)
+    }
+  }
+  return violations
+}
+
+/** 完整合法路径集合(文档/测试共用):∅→pending→confirmed→compensated 与其前缀 */
+export function sagaLegalPaths(): ReadonlyArray<ReadonlyArray<SagaTrigger>> {
+  return [['propose'], ['propose', 'compensate'], ['propose', 'confirm'], ['propose', 'confirm', 'compensate']]
+}

package/ts/src/dsh-llm.ts

@@ -18,7 +18,25 @@ import { buildSlotSystem, flagExpiredSlots, normalizeExtraction, type TravelSlot
 const model = () => process.env['LLM_MODEL'] ?? process.env['DEEPSEEK_MODEL'] ?? 'MiniMax-M2'
 const base = () => (process.env['LLM_BASE_URL'] ?? process.env['DEEPSEEK_BASE_URL'] ?? 'https://api.minimax.io/v1').replace(/\/$/, '')
 
-async function chat(messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>, json: boolean): Promise<string> {
+/**
+ * Token 用量累计器(OpenAI 兼容 usage 映射)。nightly real-LLM 成本证据(Issue #22
+ * `gotry_m3_nightly_run_v1.cost_usd`)的唯一测量来源——成本不允许凭空断言,只允许
+ * 这里实测出的 tokens × 封存价表换算;responsesMissingUsage > 0 时成本不可证,调用方必须 fail-closed。
+ */
+export interface LlmUsageTracker {
+  calls: number
+  inputTokens: number
+  outputTokens: number
+  inputCacheHitTokens: number
+  inputCacheMissTokens: number
+  responsesMissingUsage: number
+}
+
+function emptyUsage(): LlmUsageTracker {
+  return { calls: 0, inputTokens: 0, outputTokens: 0, inputCacheHitTokens: 0, inputCacheMissTokens: 0, responsesMissingUsage: 0 }
+}
+
+async function chat(messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>, json: boolean, usage?: LlmUsageTracker): Promise<string> {
   const key = process.env['LLM_API_KEY'] ?? process.env['DEEPSEEK_API_KEY']
   if (!key) throw new Error('LLM_API_KEY 未设置(兼容 DEEPSEEK_API_KEY 别名)——真 LLM 路径不可用,请回退 mock(ADR-8)')
   const res = await fetch(`${base()}/chat/completions`, {
@@ -32,7 +50,20 @@ async function chat(messages: Array<{ role: 'system' | 'user' | 'assistant'; con
     }),
   })
   if (!res.ok) throw new Error(`llm ${res.status}: ${(await res.text()).slice(0, 300)}`)
-  const data = await res.json() as { choices: Array<{ message: { content: string } }> }
+  const data = await res.json() as { choices: Array<{ message: { content: string } }>; usage?: { prompt_tokens?: number; completion_tokens?: number; prompt_cache_hit_tokens?: number; prompt_cache_miss_tokens?: number } }
+  if (usage) {
+    usage.calls += 1
+    const u = data.usage
+    if (u && Number.isFinite(u.prompt_tokens) && Number.isFinite(u.completion_tokens)) {
+      usage.inputTokens += u.prompt_tokens ?? 0
+      usage.outputTokens += u.completion_tokens ?? 0
+      usage.inputCacheHitTokens += u.prompt_cache_hit_tokens ?? 0
+      // 无缓存明细的 provider:全部输入按 miss 记(随后按 peak miss 价换算,只高不低)
+      usage.inputCacheMissTokens += u.prompt_cache_miss_tokens ?? (u.prompt_tokens ?? 0)
+    } else {
+      usage.responsesMissingUsage += 1
+    }
+  }
   const raw = data.choices[0]?.message?.content ?? ''
   // 推理模型(MiniMax-M2 等):剥 <think> 块,只留正文;未闭合时留全文由上层容错
   return raw.replace(/<think>[\s\S]*?<\/think>/g, '').trim() || raw
@@ -62,8 +93,9 @@ const SKELETON_SYSTEM = `你是行程骨架抽取器。从对话中抽取行程
 规则:每个跨城移动一段;锚点只放用户明说或必然的(如"当天到"→arriveByMin 23:59=1439);时刻用当日分钟。
 scenario 判定:「洱海/大理/千岛湖/太湖+选目的地」→erhai(候选集);「普吉/workation/远程办公+多城链」→workation(五段链);「云南/大理丽江」→yunnan;不确定→generic。只输出 JSON。`
 
-export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date = () => new Date()): LlmPort {
+export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date = () => new Date()): LlmPort & { usage: LlmUsageTracker } {
   const pack = flightPackPath
+  const usage = emptyUsage()
   const historyText = (h: Turn[]) => h.map(t => `${t.role === 'user' ? '用户' : '助手'}: ${t.text}`).join('\n')
   // 时间锚点卡:每条抽取链路都带上「今天」——legacy 路径此前无时间注入,
   // 过期/相对日期语义全靠它(算术在 time-anchor 层,LLM 只查卡)。
@@ -73,6 +105,7 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
       const out = await chat(
         [{ role: 'system', content: FACTS_SYSTEM }, { role: 'user', content: `${anchorContext()}\n\n${historyText(history)}` }],
         true,
+        usage,
       )
       const obj = parseJsonBlock(out)
       if (!obj) return { assumptions: [] }
@@ -87,6 +120,7 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
       const out = await chat(
         [{ role: 'system', content: SKELETON_SYSTEM }, { role: 'user', content: `${context}\n\n${historyText(history)}` }],
         true,
+        usage,
       )
       const skeleton = parseJsonBlock(out)
       if (!skeleton || !Array.isArray(skeleton['segments']) || (skeleton['segments'] as unknown[]).length === 0) return null
@@ -136,6 +170,7 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
       const out = await chat(
         [{ role: 'system', content: buildSlotSystem(anchor) }, { role: 'user', content: historyText(history) }],
         true,
+        usage,
       )
       const obj = parseJsonBlock(out)
       if (!obj) return null
@@ -148,8 +183,10 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
         [{ role: 'system', content: '把旅行规划的追问润色得更自然,保留全部信息(含为什么问),一两句话,不要加表情。' },
          { role: 'user', content: `【${q.key}】${q.text}(为什么问:${q.why})` }],
         false,
+        usage,
       )
       return out.trim() || `【${q.key}】${q.text}`
     },
+    usage,
   }
 }

package/ts/src/index.ts

@@ -22,7 +22,6 @@ 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'
@@ -31,15 +30,14 @@ 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 { wmoLabel } from '../capabilities/weather.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'
 import { sessionLogin } from '../capabilities/session-login.ts'
 import { createConsentGate, approvalFromContext } from '../capabilities/session-consent.ts'
+import { listArtifacts, readArtifact } from '../capabilities/artifacts.ts'
+import { interpretEffect, declinedObservation } from '../capabilities/effect.ts'
 
 export const name = 'gotry-tools'
 export const inject = ['tools', 'systemPrompt']
@@ -493,10 +491,14 @@ export function apply(ctx: Context, config: Config): void {
         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 },
-      )
+      // 效应解译层(ADR-18):渠道选择/韧性(重试/熔断)在解译器,result 原样透传——
+      // 断路拒绝时返回平铺失败面(不发起查询,不伪装成 miss)
+      const itp = await interpretEffect({
+        effect: 'HBCLI_HOTEL_SEARCH',
+        params: { destination: q.destination, checkIn: resolveDate(q.checkIn), checkOut: resolveDate(q.checkOut), adults: q.adults, hbcliBin: config.hbcliBin, timeoutMs: config.timeoutMs, fallbackPath },
+      })
+      if (!itp.result) return declinedObservation('HBCLI_HOTEL_SEARCH', itp.trace)
+      const resp = itp.result
       const dir = await ensureStateDir(config.stateRoot)
       const isLive = resp.via === 'hbcli-realtime'
       const evidence = isLive ? resp.evidence : '[静态包:估算]'
@@ -516,11 +518,18 @@ export function apply(ctx: Context, config: Config): void {
     },
     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
+      const r = value as { hotels?: unknown; via?: string; destination?: string; summary?: string }
+      const h = r.hotels
+      const liveCount = Array.isArray(h) ? h.length : 0
+      // 静态包是 {meta, stays} 对象而非数组(issue #24:此前计数恒 0 → UI 显示「无结果」)
+      const stays = !Array.isArray(h) && h && typeof h === 'object' ? (h as { stays?: unknown[] }).stays : undefined
+      const staticCount = Array.isArray(stays) ? stays.length : 0
+      const tag = r.via === 'hbcli-realtime'
+        ? (liveCount ? `实时 ${liveCount} 家` : '实时')
+        : staticCount ? `静态包 ${staticCount} 块` : (liveCount ? `${liveCount} 家` : '无结果')
       return {
         card: 'generic',
-        title: `酒店:${r.destination ?? ''} ${n ? `${n} 家(${r.via === 'hbcli-realtime' ? '实时' : '静态包'})` : '无结果'}`,
+        title: `酒店:${r.destination ?? ''} ${tag}`,
         content: [{ type: 'text', text: String(r.summary ?? '') }],
       }
     },
@@ -576,7 +585,9 @@ export function apply(ctx: Context, config: Config): void {
       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)
+        const geoItp = await interpretEffect({ effect: 'WEATHER_GEOCODE', params: { name: q.place } })
+        if (!geoItp.result) return declinedObservation('WEATHER_GEOCODE', geoItp.trace)
+        const geo = geoItp.result
         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>
         }
@@ -585,9 +596,11 @@ export function apply(ctx: Context, config: Config): void {
         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 wxItp = isClimate
+        ? await interpretEffect({ effect: 'WEATHER_CLIMATE', params: { latitude: lat, longitude: lng, month: q.month ?? new Date().getMonth() + 1 } })
+        : await interpretEffect({ effect: 'WEATHER_FORECAST', params: { latitude: lat, longitude: lng, days: q.days } })
+      if (!wxItp.result) return declinedObservation(isClimate ? 'WEATHER_CLIMATE' : 'WEATHER_FORECAST', wxItp.trace)
+      const r = wxItp.result
       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 =>
@@ -642,7 +655,9 @@ export function apply(ctx: Context, config: Config): void {
       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 itp = await interpretEffect({ effect: 'OPENSKY_FLIGHT_VERIFY', params: { callsign: q.callsign, airport: q.airport, timeoutMs: q.timeoutMs } })
+      if (!itp.result) return declinedObservation('OPENSKY_FLIGHT_VERIFY', itp.trace)
+      const r = itp.result
       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'
@@ -694,7 +709,9 @@ export function apply(ctx: Context, config: Config): void {
             return { ok: false, summary: 'checkOut 需 YYYY-MM-DD(与 checkIn 成对)' } as const
           }
         }
-        const r = await flyaiSearch({ kind: 'hotel', destName: dest, checkInDate: q.checkIn, checkOutDate: q.checkOut, keyWords: q.keyWords })
+        const itp = await interpretEffect({ effect: 'FLYAI_SEARCH', params: { kind: 'hotel', destName: dest, checkInDate: q.checkIn, checkOutDate: q.checkOut, keyWords: q.keyWords } })
+        if (!itp.result) return declinedObservation('FLYAI_SEARCH', itp.trace)
+        const r = itp.result
         const top = (r.hotels ?? []).slice(0, 8).map(o => `${o.name}${o.star ? `(${o.star})` : ''} ${o.priceRaw ?? '价待询'}${o.poi ? ` · ${o.poi}` : ''}`)
         const summary = r.verdict === 'hit'
           ? `${dest} 酒店(飞猪官方只读)前 ${top.length} 家(价格多为打码,真实价以 jumpUrl 为准):\n${top.join('\n')}\n${r.evidence}`
@@ -717,11 +734,18 @@ export function apply(ctx: Context, config: Config): void {
             + `多为用户时间表达未带年份所致——向用户确认年份(或按未来最近的同月日修正)后再查。`,
         })) as Record<string, never>
       }
-      const r = await flyaiSearch({ kind, origin: q.from, destination: q.to, depDate: q.date })
+      const itp = await interpretEffect({ effect: 'FLYAI_SEARCH', params: { kind, origin: q.from, destination: q.to, depDate: q.date } })
+      if (!itp.result) return declinedObservation('FLYAI_SEARCH', itp.trace)
+      const r = itp.result
       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}`)
+      // issue #24:miss(上游正常返回 0 条)与 error(限流/网络)分开陈述,不再混写「无结果或失败」
+      // (过去日期已被上方预校验拦下,此处不会出现过期查询)
+      const label = kind === 'flight' ? '机票' : '火车票'
       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}`
+        ? `${q.from}→${q.to} ${q.date} ${label}(飞猪官方只读)前 ${top.length} 条:\n${top.join('\n')}\n${r.evidence}`
+        : r.verdict === 'miss'
+          ? `${q.from}→${q.to} ${q.date} ${label}官方通道正常返回 0 条(常见原因:航线未开放/当日售罄)。${r.evidence}`
+          : `${q.from}→${q.to} ${q.date} ${label}检索失败(可能限流/网络):${r.error ?? ''} ${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 }),
@@ -783,11 +807,18 @@ export function apply(ctx: Context, config: Config): void {
       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'),
+      // 效应解译层(ADR-18):SESSION 通道策略=永不重试/不熔断,节律闸在渠道内;
+      // 解译器只做分发与证据拼装,verdict 语义(risk 型 needs-login/challenged)原样透传
+      const itp = await interpretEffect({
+        effect: 'SESSION_FLIGHT_SEARCH',
+        params: {
+          from: q.from, to: q.to, date: q.date,
+          // ADR-15 收尾:ReadGuard 审计在生产工具路径同样落盘(此前仅测试传隔离 stateRoot 才有 JSONL)
+          auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
+        },
       })
+      if (!itp.result) return declinedObservation('SESSION_FLIGHT_SEARCH', itp.trace)
+      const r = itp.result
       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}`
@@ -1061,4 +1092,93 @@ export function apply(ctx: Context, config: Config): void {
       }
     },
   }))
+
+  // ---- 产物面(issue #25):agent 生成的文件可在 dsh 内发现与阅读,不再只是本地文件名 ----
+
+  registerGuarded(defineTool({
+    name: 'gotry_artifacts_list',
+    description:
+      'List GoTry artifacts — deep-planning deliverables (async runs from the state ledger) plus agent-written markdown files ' +
+      'in the working directory (trip plans etc.). READ-ONLY discovery. ' +
+      'Use when the user asks to see/open/revisit a previously generated artifact ' +
+      '(「看看刚才生成的行程」「上次的规划在哪」「打开那个 md」) — list first, then read with gotry_artifacts_read.',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ limit?: 20 }',
+      },
+    },
+    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<{ limit?: number }>(args, 'limit')
+      const r = await listArtifacts({ stateRoot: config.stateRoot ?? '.', limit: q.limit })
+      const lines = r.artifacts.map(a =>
+        `- [${a.source}] ${a.title}${a.status ? `(${a.status})` : ''} — ${a.path}${a.updated ? ` @ ${a.updated.slice(0, 16).replace('T', ' ')}` : ''}`)
+      const summary = r.artifacts.length
+        ? `在册产物 ${r.artifacts.length}/${r.total} 项${r.truncated ? '(截断,可加 limit)' : ''}:\n${lines.join('\n')}`
+        : '无在册产物(异步深度规划交付与工作目录 md 文件都会出现在这里)'
+      return JSON.parse(JSON.stringify({ ok: true, artifacts: r.artifacts, total: r.total, truncated: r.truncated, summary })) as Record<string, never>
+    },
+    presentCall: () => ({ card: 'generic', title: '列出产物', kind: 'search' }),
+    presentResult: (_args, value) => {
+      const r = value as { summary?: string; total?: number }
+      return {
+        card: 'generic',
+        title: `产物:${r.total ?? 0} 项在册`,
+        content: [{ type: 'text', text: String(r.summary ?? '') }],
+      }
+    },
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_artifacts_read',
+    description:
+      'Read one GoTry artifact as a line-numbered file view rendered directly in the chat UI. ' +
+      'Input: the path from gotry_artifacts_list, or a bare async ticket id (e.g. dp-xxxx). ' +
+      'Optional offset (1-based) / limit window for paging large files. ' +
+      'READ-ONLY; text artifacts only (md/txt/json/jsonl/csv/log/yaml).',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ path: "<list 返回的路径或工单 id>", offset?: 1, limit?: 400 }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { content?: string }).content ?? JSON.stringify(value).slice(0, 600)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ path?: string; offset?: number; limit?: number }>(args, 'path')
+      if (!q.path) return JSON.parse(JSON.stringify({ ok: false, error: 'path 必填(来自 gotry_artifacts_list)' })) as Record<string, never>
+      const r = await readArtifact({ stateRoot: config.stateRoot ?? '.', path: q.path, offset: q.offset, limit: q.limit })
+      if (!r.ok) return JSON.parse(JSON.stringify(r)) as Record<string, never>
+      return JSON.parse(JSON.stringify({
+        ...r,
+        summary: `${r.path}(${r.totalLines} 行)第 ${r.offset}-${r.offset + r.lines.length - 1} 行${r.windowed ? `(共 ${r.totalLines} 行,可翻页)` : ''}`,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `读产物:${String((args.query as { path?: string })?.path ?? '')}`, kind: 'read', rawInput: args.query }),
+    presentResult: (_args, value) => {
+      const r = value as unknown as { ok?: boolean; path?: string; offset?: number; lines?: Array<{ number: number; text: string }>; totalLines?: number; lang?: string; content?: string; error?: string }
+      if (!r.ok) {
+        return { card: 'generic', title: '读产物失败', content: [{ type: 'text', text: String(r.error ?? '') }] }
+      }
+      // dsh read 卡:UI 渲染为行号文件视图(issue #25 的「插件能力查看 artifacts」落点)
+      return {
+        card: 'read' as const,
+        title: r.path?.split('/').pop() ?? r.path ?? '',
+        path: r.path ?? '',
+        offset: r.offset ?? 1,
+        lines: r.lines ?? [],
+        totalLines: r.totalLines ?? 0,
+        lang: r.lang,
+        content: [{ type: 'text', text: r.content ?? '' }],
+      }
+    },
+  }))
 }