@danceiny/gotry 0.0.1-rc.5

package/ts/capabilities/hbcli.ts

@@ -0,0 +1,152 @@
+/**
+ * hotelbyte-cli(hbcli)能力层封装:进程内 spawn bun + hbcli --json。
+ *
+ * 拿到外部资源信息能力的三条路径:
+ *   1. 实时 hbcli 调用(能力强,延迟 1-3s,需凭证 + 证书有效)
+ *   2. 静态数据包(data/hotels_2026.json)——证据标注 [静态包:估算]
+ *   3. 简易降级返回(什么都不查得到时,提供"工具暂不可用"而不是抛错)
+ *
+ * 证书/凭证/网络问题一律降级,不抛到调用方——能力层契约:永远返回一种结果。
+ *
+ * §7-1/§7-2 L4 不变量:证据链标注([实时API:hbcli@<ts>] / [静态包:估算]);
+ * 估算必须显式标记。这是 L4 与 L1 透明卡片的接缝。
+ */
+
+import { spawn } from 'node:child_process'
+
+export interface HbcliCallOptions {
+  /** hbcli 二进制路径(默认 'hbcli',依赖 PATH) */
+  hbcliBin?: string
+  /** 超时(ms) */
+  timeoutMs?: number
+  /** 凭证(token)——空时不传,hbcli 用本地默认 */
+  token?: string
+  /** 环境(uat/prod/dev);默认 uat */
+  env?: 'uat' | 'prod' | 'dev'
+}
+
+export interface HbcliCallResult {
+  /** 是否走了实时 hbcli */
+  via: 'hbcli-realtime' | 'hbcli-cache' | 'hbcli-error'
+  /** hbcli 退码 0=成功 */
+  exitCode: number
+  /** 解析后的 JSON(若 --json 模式输出可解析;否则为空) */
+  result: unknown
+  /** 证据链标注(L4 契约;无论成功失败都填) */
+  evidence: string
+  /** hbcli 原始 stdout/stderr(供调试,2000 字符上限) */
+  stdout?: string
+  stderr?: string
+  /** 经过的时长 */
+  latencyMs: number
+  /** 错误时降级原因 */
+  error?: string
+}
+
+/** 通用 hbcli JSON 调用封装:失败不抛,而是返回降级结果 */
+export async function callHbcliJson(
+  args: string[],
+  opts: HbcliCallOptions = {},
+): Promise<HbcliCallResult> {
+  const started = Date.now()
+  const bin = opts.hbcliBin ?? 'hbcli'
+  const timeoutMs = opts.timeoutMs ?? 15_000
+  const env = opts.env ?? 'uat'
+  const envVars: Record<string, string> = { HOTELBYTE_ENV: env }
+  if (opts.token) envVars['HOTELBYTE_TOKEN'] = opts.token
+
+  return new Promise((resolve) => {
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const child = spawn(bin, args, { env: { ...process.env, ...envVars } })
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true
+        child.kill('SIGKILL')
+        resolve({
+          via: 'hbcli-error', exitCode: -1, result: null,
+          evidence: `[实时API:hbcli@timeout@${new Date().toISOString()}]`,
+          latencyMs: Date.now() - started, error: `timeout after ${timeoutMs}ms`,
+        })
+      }
+    }, timeoutMs)
+    child.stdout.on('data', (d: Buffer) => { stdout += d.toString() })
+    child.stderr.on('data', (d: Buffer) => { stderr += d.toString() })
+    child.on('close', (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      const latencyMs = Date.now() - started
+      if (code !== 0) {
+        // 不抛错,降级返回。证据链显式标注:实时 API 调用失败+原因+时间戳。
+        resolve({
+          via: 'hbcli-error', exitCode: code ?? -1, result: null,
+          evidence: `[实时API:hbcli@error@${new Date().toISOString()}]`,
+          stderr: stderr.slice(0, 2000),
+          latencyMs, error: stderr.trim().slice(0, 200) || `exit ${code}`,
+        })
+        return
+      }
+      // 尝试 JSON 解析
+      const jStart = stdout.search(/[\{\[]/)
+      const jsonStr = jStart >= 0 ? stdout.slice(jStart) : ''
+      let result: unknown = null
+      if (jsonStr) {
+        try { result = JSON.parse(jsonStr) } catch { /* 非 JSON 输出,留给调用方处理 */ }
+      }
+      resolve({
+        via: 'hbcli-realtime', exitCode: 0, result,
+        evidence: `[实时API:hbcli@${new Date().toISOString()}]`,
+        stdout: stdout.slice(0, 2000), latencyMs,
+      })
+    })
+    child.on('error', (e) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      // ENOENT (二进制不存在) 等也走降级路径
+      resolve({
+        via: 'hbcli-error', exitCode: -1, result: null,
+        evidence: `[实时API:hbcli@spawn_error@${new Date().toISOString()}]`,
+        latencyMs: Date.now() - started, error: (e as Error).message,
+      })
+    })
+  })
+}
+
+/** 高层语义化封装:酒店列表查询(down-tier to 静态包 + 证据链标注) */
+export async function searchHotels(
+  query: { destination: string; checkIn?: string; checkOut?: string; adults?: number },
+  opts: HbcliCallOptions & { fallbackPath?: string } = {},
+): Promise<HbcliCallResult & { hotels?: unknown; summary: string }> {
+  const hbArgs = ['search', 'hotel-list', '--json']
+  if (query.destination) hbArgs.push('--destination', query.destination)
+  if (query.checkIn) hbArgs.push('--check-in', query.checkIn)
+  if (query.checkOut) hbArgs.push('--check-out', query.checkOut)
+  if (query.adults) hbArgs.push('--adults', String(query.adults))
+  const live = await callHbcliJson(hbArgs, opts)
+  if (live.via === 'hbcli-realtime') {
+    return { ...live, hotels: live.result, summary: `${query.destination}:hbcli 实时返回` }
+  }
+  // 降级:读静态包
+  const fallback = opts.fallbackPath
+  if (fallback) {
+    try {
+      const { readFile } = await import('node:fs/promises')
+      const pack = JSON.parse(await readFile(fallback, 'utf-8')) as Record<string, unknown>
+      return {
+        ...live,
+        hotels: pack,
+        summary: `${query.destination}:hbcli 不可用(${live.error ?? live.via}),降级到静态包`,
+      }
+    } catch { /* 静态包读不到也优雅降级 */ }
+  }
+  return { ...live, summary: `${query.destination}:hbcli 不可用且无静态包(仅返回错误)` }
+}
+
+/** 高层语义化封装:目的地列表(无数据依赖,通常 hbcli dest 命令可独立调通) */
+export async function listDestinations(opts: HbcliCallOptions = {}): Promise<HbcliCallResult & { destinations?: unknown }> {
+  const r = await callHbcliJson(['search', 'destinations', '--json'], opts)
+  return { ...r, destinations: r.result }
+}

package/ts/capabilities/incident-log.ts

@@ -0,0 +1,145 @@
+/**
+ * 进程级事故日志(D-NEW 护栏):fsync append-only JSONL。
+ *
+ * 目的: dsh 0.1.1-rc.1 只接 SIGINT/SIGTERM,缺 uncaughtException/unhandledRejection——
+ * 任一插件 wasm/runtime 异常穿透到 node 层都会让整个 web UI 进程死亡,
+ * 现场不存。这次(Z3 WASM mk_bool_var 崩溃)教训:连个取证都没有。
+ *
+ * 设计: 进程级 handler 同步写盘(fsync),尽量在进程被杀前留下事故证据。
+ * handler 自身不再抛——再次抛出会绕过 handler,变成无声死亡。
+ *
+ * §11 状态面同步:事故日志是 gotry-state/incidents.jsonl,
+ * 用户可见(README 第 x 节),可清理。
+ */
+
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export type IncidentKind = 'uncaughtException' | 'unhandledRejection' | 'plugin_error' | 'tool_execute_error'
+
+export interface Incident {
+  ts: string
+  kind: IncidentKind
+  message: string
+  stack?: string
+  /** 来自哪个来源(plugin_name / service url 等) */
+  source?: string
+}
+
+/** 解析 gotry-state 绝对路径(stateRoot 可相对也可绝对) */
+export function resolveIncidentsPath(stateRoot: string, filename = 'incidents.jsonl'): string {
+  const root = isAbsolute(stateRoot)
+    ? stateRoot
+    : join(process.cwd(), stateRoot)
+  return join(root, 'gotry-state', filename)
+}
+
+function ensureDir(path: string): void {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+let installed = false
+let logPath: string | null = null
+
+/**
+ * 写入一条事故并 fsync。同步执行——handler 内异步无效。
+ * 自身 try/catch 自保,不让写入失败再抛一次把进程杀掉。
+ */
+export function recordIncident(inc: Incident, stateRoot?: string): boolean {
+  const target = stateRoot ? resolveIncidentsPath(stateRoot) : (logPath ?? resolveIncidentsPath('.'))
+  try {
+    ensureDir(target)
+    appendFileSync(target, JSON.stringify(inc) + '\n', { flag: 'a' })
+    // fsync: 让盘数据落定,免得被杀时缓冲丢
+    const fd = require('node:fs').openSync(target, 'a')
+    require('node:fs').fsyncSync(fd)
+    require('node:fs').closeSync(fd)
+    return true
+  } catch {
+    // 绝对不能在这里抛——我们正在处理已经抛过一次的进程级错误
+    return false
+  }
+}
+
+/**
+ * 安装进程级护栏:进程整个生命周期仅生效一次(重复调用安全)。
+ * 必须同步执行——异步发生在事件循环下一次,而 wasm 崩溃后已无下一轮。
+ *
+ * @returns 一个 disposer,卸载所有监听(测试场景使用)
+ */
+export function installProcessGuards(stateRoot: string, labels?: { uncaughtException?: string; unhandledRejection?: string }): () => void {
+  if (installed) return () => { /* 已装,no-op */ }
+  installed = true
+  logPath = resolveIncidentsPath(stateRoot)
+
+  const uncaughtHandler = (err: Error, origin: NodeJS.UncaughtExceptionOriginTypes | 'uncaughtException') => {
+    recordIncident({
+      ts: new Date().toISOString(),
+      kind: 'uncaughtException',
+      message: (err?.message ?? String(err)).slice(0, 2000),
+      stack: (err?.stack ?? '').slice(0, 4000),
+      source: labels?.uncaughtException ?? String(origin),
+    }, stateRoot)
+    // 不调用 process.exit——让 dsh/上级容器的重启策略负责;
+    // 如果 dsh 不接住,我们至少留下事故记录。
+  }
+
+  const rejectionHandler = (reason: unknown, promise: Promise<unknown>) => {
+    const msg = reason instanceof Error ? reason.message : String(reason)
+    const stack = reason instanceof Error ? (reason.stack ?? '') : ''
+    recordIncident({
+      ts: new Date().toISOString(),
+      kind: 'unhandledRejection',
+      message: msg.slice(0, 2000),
+      stack: stack.slice(0, 4000),
+      source: labels?.unhandledRejection ?? 'promise',
+    }, stateRoot)
+  }
+
+  process.on('uncaughtException', uncaughtHandler)
+  process.on('unhandledRejection', rejectionHandler)
+  return () => {
+    process.off('uncaughtException', uncaughtHandler)
+    process.off('unhandledRejection', rejectionHandler)
+    installed = false
+  }
+}
+
+/**
+ * 工具执行面异常隔离(D-NEW gotry 侧收尾):dsh 的一个工具 execute 抛错/拒绝
+ * 会沿 cordis 传到主循环,拖垮整个会话。包装后:降级为结构化错误返回给 LLM、
+ * 事故落盘,永不向上抛。落盘失败也不抛(双保险,仍返回结构化错误)。
+ */
+export function guardToolExecute<A, R>(name: string, stateRoot: string, execute: (args: A, exec: unknown) => R | Promise<R>): (args: A, exec: unknown) => Promise<R> {
+  return async (args: A, exec: unknown): Promise<R> => {
+    try {
+      return await execute(args, exec)
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e))
+      recordIncident({
+        ts: new Date().toISOString(),
+        kind: 'tool_execute_error',
+        message: `${name}: ${err.message}`.slice(0, 2000),
+        stack: (err.stack ?? '').slice(0, 4000),
+        source: name,
+      }, stateRoot)
+      return {
+        ok: false,
+        summary: `gotry_${name} 内部错误(已隔离,会话继续): ${err.message.slice(0, 300)}`,
+        evidence: `[incident:tool_execute_error@${new Date().toISOString()}]`,
+      } as R
+    }
+  }
+}
+
+/** CLI 调试:从命令行单独跑查看当前进程是否已挂护栏 */
+if (import.meta.url === `file://${fileURLToPath(import.meta.url)}` && process.argv[2] === '--smoke') {
+  const stateRoot = process.argv[3] ?? '.'
+  installProcessGuards(stateRoot, { uncaughtException: 'smoke', unhandledRejection: 'smoke' })
+  writeFileSync(resolveIncidentsPath(stateRoot) + '.smoke', 'ok')
+  // 触发一次未捕获,应被写盘(不真正杀进程——进程继续跑完)
+  setTimeout(() => Promise.reject(new Error('intentional smoke-rejection')), 50)
+  setTimeout(() => { console.log('SMOKE OK'); process.exit(0) }, 500)
+}

package/ts/cordis.gotry-patch.yml

@@ -0,0 +1,36 @@
+# GoTry × dsh 成品组合(DeepSeek 原生——创始人官方 key)
+# 用法(在 ts/dsh-runtime 下):
+#   DEEPSEEK_API_KEY=<key> node node_modules/@deepseek-ai/dsh/lib/bin.js \
+#     --profile headless --patch ../cordis.gotry-patch.yml "<任务>"
+#   (web 界面: 把 --profile headless 换成 web)
+- insert:
+    - id: gotry-tools
+      name: '/Users/bytedance/work/gotry/ts/src/index.ts'
+      config:
+        pythonBin: '../../.venv/bin/python'
+        pythonPath: '../../py'
+        stateRoot: '.'
+        timeoutMs: 30000
+        preferInProcess: true
+        hbcliBin: 'hbcli'
+
+# GoTry 成品人格:行为契约=产品语义
+- id: system-prompt
+  config:
+    persona: >-
+      你是 GoTry——从出发到下一次出发的 AI 旅行伙伴(中国出境首发,workation 场景)。
+      今天是 {{current_date}}。行为契约:
+      (1)动机先行:首轮必问工作窗口(几点到几点/什么时区)与已订资源(航班/酒店);
+      (2)日历一次断言:日期换算 2026 年星期并记住,冲突让用户裁决,永不重算;
+      (3)翻译不造数:班次/价格只来自工具(gotry_feasibility_check/gotry_skeleton_check/gotry_hotel_search);
+      (4)判定归引擎:可行性/全成本由工具计算,你只解释;
+      (5)待决=选择题:2-3 个带 trade-off 选项;
+      (6)憧憬不被拒绝:不可行进 gotry_wish_pool_add(带条件);
+      (7)证据链:引用工具返回的标注([骨架:openflights]/[实时API:hbcli]/[静态包:估算])。
+      (8)时间感知:推荐季节/月份选项时,以今天为锚点——已过的月份不说「将」,
+      当下所在的季节直接点明(如「现在正是雨季」而非把当前月份当成远期选项)。
+      (9)兜底链:自身工具(可行性/酒店/天气/航班/Anything)答不上来时,用
+      gotry_agent_reach(100% follow Panniantong/Agent-Reach 路由表):web 读任意网页(r.jina.ai)/
+      rss/v2ex/youtube 字幕(yt-dlp)/github 搜索(gh)/bilibili/exa 语义搜索;需登录态的渠道
+      (twitter/reddit/xhs 等)会返回配置指引——如实转告用户,不编造。action=status 可跑
+      上游 `agent-reach doctor` 体检。答案标 [agent-reach:<渠道>@<ts>]。

package/ts/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@gotry/plugin",
+  "version": "0.0.1-rc.2",
+  "private": true,
+  "description": "GoTry dsh plugin: motivation profile, feasibility (door-to-door true cost via unified segment model), skeleton connectivity, hotel search, wish pool — all pure TS, no Python runtime required",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "smoke": "tsx scripts/smoke.ts"
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/schemastery": "*",
+    "z3-solver": "^5.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/ts/scripts/skeleton-check.ts

@@ -0,0 +1,45 @@
+/**
+ * OpenFlights 骨架校验(M2 段 3,§7-1 骨架层):引擎候选集的通航性合法性校验。
+ * 数据源:data/openflights-skeleton.json(OpenFlights ODbL,枢纽间 168 对)。
+ * 语义:「查不到≠不可达」(骨架只含枢纽间),但「查到」= 候选集强证据。
+ * 运行:cd ts && npx tsx scripts/skeleton-check.ts HKG HKT
+ */
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+interface Skeleton {
+  meta: { source: string; note: string; hub_filter: string[] }
+  pairs: Record<string, string[]>
+}
+
+let cached: Skeleton | null = null
+
+async function load(): Promise<Skeleton> {
+  if (!cached) {
+    cached = JSON.parse(await readFile(join(import.meta.dirname, '..', '..', 'data', 'openflights-skeleton.json'), 'utf-8')) as Skeleton
+  }
+  return cached
+}
+
+export async function checkConnectivity(a: string, b: string): Promise<{ connected: boolean; airlines?: string[]; evidence: string }> {
+  const skeleton = await load()
+  const key = [a.toUpperCase(), b.toUpperCase()].sort().join('-')
+  const airlines = skeleton.pairs[key]
+  if (airlines) {
+    return { connected: true, airlines, evidence: `[骨架:openflights] ✅ ${a}↔${b} 直飞(${airlines.length}+ 航司:${airlines.join(',')})` }
+  }
+  const inHub = (skeleton.meta.hub_filter as string[]).includes(a.toUpperCase())
+    && (skeleton.meta.hub_filter as string[]).includes(b.toUpperCase())
+  return {
+    connected: false,
+    evidence: inHub
+      ? `[骨架:openflights] ❌ ${a}↔${b} 枢纽间无直飞记录——引擎应将此候选降权或要求中转`
+      : `[骨架:openflights] ○ ${a}或${b}不在枢纽集,骨架不覆盖(不作否定结论)`,
+  }
+}
+
+// CLI 直跑
+if (process.argv[2] && process.argv[3]) {
+  console.log((await checkConnectivity(process.argv[2], process.argv[3])).evidence)
+}

package/ts/scripts/skeleton-integration-test.ts

@@ -0,0 +1,23 @@
+/**
+ * 骨架层集成验证(§7-1 消费面):开 skeletonHub + 带 route 的段 → 结果带三值标注;
+ * 枢纽间否定只标注不排除——EK329(数据集滞后的新航线)必须存活。
+ * 运行(在 ts/ 下):npx tsx scripts/skeleton-integration-test.ts
+ */
+
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parseFlightPackToSpec, solveUnified } from '../src/unified.ts'
+
+const pack = JSON.parse(await readFile(join('..', 'data', 'flights_2026.json'), 'utf-8'))
+const spec = parseFlightPackToSpec(pack)
+spec.budgetCny = 9000
+spec.skeletonHub = true
+spec.segments.forEach(s => { if (s.id === 'f5') s.route = 'SZX->DXB'; if (s.id === 'f1') s.route = 'HKG->HKT' })
+const r = await solveUnified(spec)
+assert.equal(r.feasible, true, '骨架否定不排除——EK329 必须仍在')
+const f5 = r.legs!.find(l => l.leg === 'f5')
+assert.equal(f5?.service, 'EK329', 'EK329 存活(骨架滞后容错)')
+assert.ok((r.skeleton_notes ?? []).some(n => n.includes('SZX') && n.includes('❌')), `枢纽否定标注在: ${r.skeleton_notes}`)
+assert.ok((r.skeleton_notes ?? []).some(n => n.includes('HKG') && n.includes('✅')), '正向标注在')
+console.log(`骨架集成 OK:EK329 在枢纽否定下存活,标注=[${r.skeleton_notes?.join(' | ')}]`)

package/ts/src/bridge.ts

@@ -0,0 +1,44 @@
+/**
+ * GoTry 桥接工具集(纯 Node 版,无 Python 依赖):
+ *   - ensureStateDir: 状态目录创建
+ *   - recordLatency: 延迟日志追加
+ *   - readJson / writeJson: JSON 文件安全读写
+ *
+ * 历史:曾有 callFeasibilityEngine 用 spawn(.venv/bin/python) 起 Python CLI,
+ * 作为 TS 求解的回退路径。D-7 切轨后 unified solveChoiceSegment 是唯一求解入口,
+ * Python oracle 路径于 v0.0.1-rc.2 移除——npm 一键分发不再需要 Python 运行时依赖。
+ */
+
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** 状态目录:动机画像 / wish pool 的落盘位置(红线 6:用户数据可见、可编辑、可删除) */
+export async function ensureStateDir(root: string): Promise<string> {
+  const dir = join(root, 'gotry-state')
+  await mkdir(dir, { recursive: true })
+  return dir
+}
+
+/** JSON 安全读取:文件不存在返回 fallback,解析失败抛错 */
+export async function readJson<T>(path: string, fallback: T): Promise<T> {
+  try {
+    const text = await readFile(path, 'utf-8')
+    return JSON.parse(text) as T
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return fallback
+    throw e
+  }
+}
+
+/** JSON 原子写入 */
+export async function writeJson(path: string, value: unknown): Promise<void> {
+  const tmp = `${path}.tmp`
+  await writeFile(tmp, JSON.stringify(value, null, 2), 'utf-8')
+  const { rename } = await import('node:fs/promises')
+  await rename(tmp, path)
+}
+
+/** 桥接延迟日志(追加式;T5 成本工程的度量数据源之一) */
+export async function recordLatency(logPath: string, latencyMs: number, kind: string): Promise<void> {
+  await appendFile(logPath, JSON.stringify({ ts: new Date().toISOString(), kind, latencyMs }) + '\n')
+}

package/ts/src/contracts.ts

@@ -0,0 +1,165 @@
+/**
+ * Stage 1 契约层(S1,docs/stage1-top-down-design.md §2)——顶层数据与工具面契约。
+ *
+ * 自顶向下纪律:本文件是唯一权威契约。实现(mock 循环/求解器挂载/真 LLM)都向这里对齐;
+ * 契约变更需走设计文档升版,不随实现漂移。
+ * 责任铁律:LLM 只做问句组织/翻译/解释;判定与算术永远是确定性组件。
+ */
+
+import type { JourneySpecTS } from './unified.ts'
+
+// ---- TripState:会话状态契约(一切组件围绕它读写) --------------------------------
+
+export interface CalendarState {
+  year: number
+  /** 一次断言终身使用:{"2026-07-17": "fri"}——Kimi 三轮日历混乱的解药 */
+  assertedWeekdays: Record<string, 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun'>
+}
+
+export interface WorkWindowProfile {
+  homeTzOffsetMin: number
+  startMin: number
+  endMin: number
+  workdays: number[]
+  /** 证据:用户原话(P0 反幻觉,与动机画像同规) */
+  evidence: string
+}
+
+export interface TravelerProfile {
+  workWindow?: WorkWindowProfile
+  companions?: string[]
+  budgetTier?: 'economy' | 'comfort' | 'convenience'
+  /** 已订资源(航班/酒店)——Kimi 复盘:第 6 轮才被问出的关键事实 */
+  bookedResources?: Array<{ kind: 'flight' | 'hotel'; ref: string; window?: string }>
+  motivation?: { weights: Record<string, number>; evidence: string[] }
+}
+
+export interface GateOption {
+  label: string
+  tradeOff?: string
+}
+
+export interface Gate {
+  id: string
+  question: string
+  options: GateOption[]
+  /** 回答后回填 */
+  answer?: string
+}
+
+export interface WishEntry {
+  name: string
+  reason: string
+  conditions: Record<string, unknown>
+  addedAt?: string
+}
+
+export interface TripState {
+  calendar: CalendarState
+  profile: TravelerProfile
+  spec?: JourneySpecTS
+  solve?: SolveResult
+  gates: Gate[]
+  wishes: WishEntry[]
+}
+
+// ---- 求解结果(unified 求解器输出的契约化引用) ----------------------------------
+
+export interface SolveResult {
+  feasible: boolean
+  money_cny?: number
+  legs?: Array<Record<string, unknown> & { leg: string }>
+  red_flags?: string[]
+  unsat_core?: string[]
+  suggestions?: Array<{ relax: string; money_cny?: number }>
+  work_window_exclusions?: Array<{ segment: string; option: string; reason: string }>
+  skeleton_notes?: string[]
+  verdicts?: Array<Record<string, unknown>>
+  recommended?: string | null
+}
+
+// ---- 工具面契约(五个;dsh 插件按此注册) -----------------------------------------
+
+export interface Turn {
+  role: 'user' | 'assistant'
+  text: string
+}
+
+/** ADR-9:访谈由缺失字段驱动(确定性),LLM 只润色问句 */
+export interface InterviewQuestion {
+  key: string                    // 对应 profile 的缺失字段,如 "workWindow" / "bookedResources"
+  text: string
+  why: string                    // 为什么问(Kimi 复盘:不解释的追问=审讯)
+  options?: GateOption[]
+}
+
+export interface GotryInterviewNextIO {
+  input: { state: TripState; brief?: string }
+  output: { questions: InterviewQuestion[]; missing: string[] }
+}
+
+export interface SpecAssumption {
+  field: string
+  value: unknown
+  source: 'user-verbatim' | 'inferred' | 'default'   // inferred 必须在渲染时声明
+}
+
+export interface GotrySpecExtractIO {
+  input: { history: Turn[]; state: TripState }
+  output: { spec: JourneySpecTS; assumptions: SpecAssumption[]; calendarConflicts?: string[] }
+}
+
+export interface GotrySolveIO {
+  input: { spec: JourneySpecTS }
+  output: { result: SolveResult }
+}
+
+export interface GotryRenderIO {
+  input: { state: TripState }
+  output: { replyMd: string; cardsMd: string[]; gates: Gate[] }
+}
+
+export interface GotryWishPoolIO {
+  input: { entry: WishEntry }
+  output: { added: boolean; total: number }
+}
+
+/** 工具注册表:名字 → IO 类型(dsh 插件按此生成 parameters/output schema) */
+export const TOOL_CONTRACTS = {
+  'gotry_interview_next': {} as GotryInterviewNextIO,
+  'gotry_spec_extract': {} as GotrySpecExtractIO,
+  'gotry_solve': {} as GotrySolveIO,
+  'gotry_render': {} as GotryRenderIO,
+  'gotry_wish_pool_add': {} as GotryWishPoolIO,
+} as const
+
+export type ToolName = keyof typeof TOOL_CONTRACTS
+
+// ---- wire schema(dsh 注册用的 JSON Schema 面;type:'json' 根 + 关键字段文档) ----
+
+export const TRIP_STATE_JSON_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    calendar: {
+      type: 'object', additionalProperties: true,
+      description: '年份与已断言的星期映射;一次断言终身使用,冲突必须显式指出',
+    },
+    profile: {
+      type: 'object', additionalProperties: true,
+      description: 'workWindow(带 evidence)/companions/budgetTier/bookedResources/motivation',
+    },
+    spec: { type: 'json', description: '统一行程模型 JourneySpec(见 unified.ts)' },
+    solve: { type: 'json', description: '求解结果(锚点/排除/红旗/建议)' },
+    gates: {
+      type: 'array',
+      description: '待决问题,只能是选择题',
+      items: {
+        type: 'object', additionalProperties: true,
+        properties: { id: { type: 'string' }, question: { type: 'string' } },
+      },
+    },
+    wishes: { type: 'array', description: '「下一次出发」清单', items: { type: 'object', additionalProperties: true } },
+  },
+  required: ['calendar', 'profile', 'gates', 'wishes'],
+} as const