@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/ts/src/dsh-llm.ts

@@ -1,7 +1,8 @@
 /**
  * 真 LlmPort:OpenAI 兼容接口的 provider 中立适配器(DeepSeek/MiniMax-M2 实测)。
  * 零新依赖(node 内建 fetch)。环境变量:LLM_API_KEY/LLM_BASE_URL/LLM_MODEL
- * (兼容旧 DEEPSEEK_* 别名)。MiniMax-M2 是推理模型:输出带 <think> 块,
+ * (兼容旧 DEEPSEEK_* 别名);GOTRY_LLM_TIMEOUT_MS = 单次请求总预算(默认 300000ms,
+ * 非正整数忽略)。MiniMax-M2 是推理模型:输出带 <think> 块,
  * 必须先剥离再解析——JSON 藏在 think 里是常见失败模式。
  * 无 key 时抛出明确错误,replay-real 自动回退 mock(ADR-8)。
  * 责任铁律不变:本适配器只做翻译/润色/解释,判定与算术在确定性组件。
@@ -12,17 +13,125 @@ import type { InterviewQuestion, TravelerProfile, TripState, Turn, CalendarState
 import { parseFlightPackToSpec, type JourneySpecTS } from './unified.ts'
 import { buildTimeAnchor } from './time-anchor.ts'
 import { buildSlotSystem, flagExpiredSlots, normalizeExtraction, type TravelSlotExtraction } from './travel-slots.ts'
+import { mergeProfileWorkWindow } from './flight-pack-adapter.ts'
 
 // 惰性读取(env 在调用时取值):模块顶常量会在 .env 加载前冻结(ESM import 提升),
 // 脚本先 loadEnv 再 import 也救不了——401 错配(key 发往默认端点)的存量隐患由此根除。
 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 }
+}
+
+/** 单次请求(连接→响应头→正文读完)的默认总预算:对推理模型足够宽松,只兜「连上了却永不应答」的卡死。 */
+export const DEFAULT_LLM_TIMEOUT_MS = 300_000
+/**
+ * 超时上限 = 2^31-1 ms(≈24.8 天)。Node 对更大的延迟会溢出并**悄悄改成 1ms**
+ * (TimeoutOverflowWarning),即「配得越大越立刻超时」——所以必须夹住,绝不原样透传。
+ */
+const MAX_LLM_TIMEOUT_MS = 2_147_483_647
+
+/**
+ * chat() 的请求级选项。timeoutMs 压过环境变量 GOTRY_LLM_TIMEOUT_MS;signal 由调用方持有并与
+ * 超时合并(AbortSignal.any)——任一先触发就终止本次请求,落成 LlmRequestError。
+ */
+export interface LlmRequestOptions {
+  timeoutMs?: number
+  signal?: AbortSignal
+}
+
+/** 只认十进制正整数(数值或纯数字串);其余(0/负数/小数/NaN/带单位/空串)一律 undefined——绝不退化成「无超时」。 */
+function parseTimeoutMs(raw: unknown): number | undefined {
+  const n = typeof raw === 'string' ? (/^\d+$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN) : raw
+  return typeof n === 'number' && Number.isSafeInteger(n) && n > 0 ? Math.min(n, MAX_LLM_TIMEOUT_MS) : undefined
+}
+
+/** 解析顺序:本次调用显式值 > 环境变量 GOTRY_LLM_TIMEOUT_MS(调用时取值,同 base()/model())> 默认值。 */
+export function resolveLlmTimeoutMs(callMs?: number): number {
+  return parseTimeoutMs(callMs) ?? parseTimeoutMs(process.env['GOTRY_LLM_TIMEOUT_MS']) ?? DEFAULT_LLM_TIMEOUT_MS
+}
+
+export type LlmRequestFailureCode = 'timeout' | 'aborted'
+
+/**
+ * chat() 请求被截断(超时 / 调用方取消)的类型化失败——不是挂起,也不会被吞。
+ * 与既有错误形态一致,而非另起一套:
+ *  - message 沿用本模块 `llm <kind>: <detail>` 约定(同 `llm 429: …`),只读 .message 的调用方
+ *    (nightly-evidence / persona-sim / time-eval --real)原样可用;
+ *  - name 取平台既有名 TimeoutError / AbortError(AbortSignal.timeout 与手动 abort 抛的同名),
+ *    persona-sim、channel-probe 等按 name 分类的代码零改动即可识别;
+ *  - cause 保留 fetch 抛出的原始错误(调用方自定义的 abort reason 也在其中)。
+ * HTTP 非 2xx(`llm <status>`)、DNS/连接重置、坏 JSON 仍是原样的普通 Error——只改写「被我们的 signal 终止」的失败。
+ */
+export class LlmRequestError extends Error {
+  readonly code: LlmRequestFailureCode
+  /** 本次生效的超时预算;仅 code === 'timeout' 有值 */
+  readonly timeoutMs: number | undefined
+
+  constructor(code: LlmRequestFailureCode, detail: string, options: { cause?: unknown; timeoutMs?: number } = {}) {
+    super(`llm ${code}: ${detail}`, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = code === 'timeout' ? 'TimeoutError' : 'AbortError'
+    this.code = code
+    this.timeoutMs = options.timeoutMs
+  }
+}
+
+interface ChatCompletion {
+  choices: Array<{ message: { content: string } }>
+  usage?: { prompt_tokens?: number; completion_tokens?: number; prompt_cache_hit_tokens?: number; prompt_cache_miss_tokens?: number }
+}
+
+/**
+ * 发一次请求并读完正文。**同一个 signal 贯穿 fetch 与 res.json()/res.text()**,所以超时覆盖整个请求
+ * (含「响应头已到、正文卡住」与「非 2xx 的错误正文卡住」),调用方取消同理。
+ * 只有「被我们的 signal 终止」才改写成 LlmRequestError;其余错误原样上抛。
+ */
+async function requestCompletion(
+  url: string,
+  init: { headers: Record<string, string>; body: string },
+  request: LlmRequestOptions,
+): Promise<{ ok: true; data: ChatCompletion } | { ok: false; status: number; text: string }> {
+  const timeoutMs = resolveLlmTimeoutMs(request.timeoutMs)
+  const timeout = AbortSignal.timeout(timeoutMs)
+  const signal = request.signal ? AbortSignal.any([request.signal, timeout]) : timeout
+  try {
+    const res = await fetch(url, { method: 'POST', headers: init.headers, body: init.body, signal })
+    if (!res.ok) return { ok: false, status: res.status, text: await res.text() }
+    return { ok: true, data: await res.json() as ChatCompletion }
+  } catch (error) {
+    if (!signal.aborted) throw error
+    // AbortSignal.any 的 reason 是最先触发的那个源的 reason:等于超时信号的 reason 即超时先到,否则是调用方取消
+    if (timeout.aborted && signal.reason === timeout.reason) {
+      throw new LlmRequestError('timeout', `no complete response within ${timeoutMs}ms (GOTRY_LLM_TIMEOUT_MS)`, { cause: error, timeoutMs })
+    }
+    throw new LlmRequestError('aborted', "request cancelled by the caller's AbortSignal", { cause: error })
+  }
+}
+
+async function chat(
+  messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>,
+  json: boolean,
+  usage?: LlmUsageTracker,
+  request: LlmRequestOptions = {},
+): 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`, {
-    method: 'POST',
+  const reply = await requestCompletion(`${base()}/chat/completions`, {
     headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
     body: JSON.stringify({
       model: model(),
@@ -30,9 +139,22 @@ async function chat(messages: Array<{ role: 'system' | 'user' | 'assistant'; con
       ...(json ? { response_format: { type: 'json_object' } } : {}),
       temperature: json ? 0 : 0.7,
     }),
-  })
-  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 } }> }
+  }, request)
+  if (!reply.ok) throw new Error(`llm ${reply.status}: ${reply.text.slice(0, 300)}`)
+  const data = reply.data
+  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
@@ -51,10 +173,10 @@ function parseJsonBlock(text: string): Record<string, unknown> | null {
 
 const FACTS_SYSTEM = `你是旅行规划的事实抽取器。从对话中抽取两类事实并以 JSON 返回:
 {"calendar": {"year": 数字, "assertedWeekdays": {"YYYY-MM-DD": "mon|tue|wed|thu|fri|sat|sun"}},
- "profile": {"workWindow": {"homeTzOffsetMin": 数字, "startMin": 数字, "endMin": 数字, "workdays": [0,1,2,3,4], "evidence": "用户原话"},
+ "profile": {"workWindow": {"homeTzOffsetMin": 数字(仅 legacy v1;用户未明确时可省略), "startMin": 数字, "endMin": 数字, "workdays": [0,1,2,3,4], "evidence": "用户原话"},
               "companions": ["..."], "budgetTier": "economy|comfort|convenience",
               "bookedResources": [{"kind": "flight|hotel", "ref": "...", "window": "..."}]}}
-只放用户明确说过的事实;没有的字段省略。分钟数从 HH:MM 换算;UTC+4 → homeTzOffsetMin=240。
+只放用户明确说过的事实;没有的字段省略。分钟数从 HH:MM 换算;用户未明确说 numeric offset 时不要猜、不要输出 homeTzOffsetMin;v2 pack 的 IANA home zone 属于数据层权威。
 **休假语义(关键)**:用户说「请假/年假/不用办公/休假」→ workWindow 输出 {"vacation": true}(不是省略!省略会触发重复追问);只有用户明确给了工作时间才输出完整 workWindow 对象。只输出 JSON。`
 
 const SKELETON_SYSTEM = `你是行程骨架抽取器。从对话中抽取行程的**骨架**——段(移动)与锚点,不包含任何班次数据(班次来自数据层,你不要编造时刻/价格/航班号)。
@@ -62,8 +184,13 @@ const SKELETON_SYSTEM = `你是行程骨架抽取器。从对话中抽取行程
 规则:每个跨城移动一段;锚点只放用户明说或必然的(如"当天到"→arriveByMin 23:59=1439);时刻用当日分钟。
 scenario 判定:「洱海/大理/千岛湖/太湖+选目的地」→erhai(候选集);「普吉/workation/远程办公+多城链」→workation(五段链);「云南/大理丽江」→yunnan;不确定→generic。只输出 JSON。`
 
-export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date = () => new Date()): LlmPort {
+/**
+ * request:本端口每次 chat() 共用的请求级选项(timeoutMs / signal)。signal 是端口级取消——
+ * 调用方可借它在会话/批次截止时真正掐断在途请求,而不是放着它继续挂在 provider 上。
+ */
+export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date = () => new Date(), request: LlmRequestOptions = {}): 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 +200,8 @@ 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,
+        request,
       )
       const obj = parseJsonBlock(out)
       if (!obj) return { assumptions: [] }
@@ -87,6 +216,8 @@ 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,
+        request,
       )
       const skeleton = parseJsonBlock(out)
       if (!skeleton || !Array.isArray(skeleton['segments']) || (skeleton['segments'] as unknown[]).length === 0) return null
@@ -112,7 +243,11 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
           return { segments: [], note: 'erhai-candidates', budgetCny: 3000 } as unknown as JourneySpecTS
         }
         packSpec = parseFlightPackToSpec(JSON.parse(await readFile(packPath, 'utf-8')))
-      } catch {
+      } catch (e) {
+        // issue #620:数据包被 parse 边界拒收时,原因必须留痕——否则用户只看到
+        // 「骨架还不完整」,运维看不到是哪个包的哪个字段把求解面挡住了。
+        const err = e as Error & { code?: string }
+        console.error(`[gotry] extractSpec: 数据包不可用 ${packPath}(${err.code ?? 'parse_failed'}):`, (err.message ?? '').slice(0, 200))
         return null
       }
       const anchorsById = new Map<string, Record<string, unknown>>(
@@ -121,12 +256,7 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
         const a = anchorsById.get(seg.id) as { arriveByMin?: number } | undefined
         if (a?.arriveByMin !== undefined) seg.anchors = { arriveByMin: a.arriveByMin }
       }
-      packSpec.workWindow = state.profile.workWindow ? {
-        homeTzOffsetMin: state.profile.workWindow.homeTzOffsetMin,
-        startMin: state.profile.workWindow.startMin,
-        endMin: state.profile.workWindow.endMin,
-        workdays: state.profile.workWindow.workdays,
-      } : undefined
+      packSpec = mergeProfileWorkWindow(packSpec, state.profile.workWindow)
       packSpec.budgetCny = 9000
       return packSpec
     },
@@ -136,6 +266,8 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
       const out = await chat(
         [{ role: 'system', content: buildSlotSystem(anchor) }, { role: 'user', content: historyText(history) }],
         true,
+        usage,
+        request,
       )
       const obj = parseJsonBlock(out)
       if (!obj) return null
@@ -148,8 +280,11 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
         [{ role: 'system', content: '把旅行规划的追问润色得更自然,保留全部信息(含为什么问),一两句话,不要加表情。' },
          { role: 'user', content: `【${q.key}】${q.text}(为什么问:${q.why})` }],
         false,
+        usage,
+        request,
       )
       return out.trim() || `【${q.key}】${q.text}`
     },
+    usage,
   }
 }

package/ts/src/flyai-setup-tool.ts

@@ -0,0 +1,77 @@
+/** Read-only model surface. Credentials are entered only through the local CLI. */
+import { homedir } from 'node:os'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { EffectInterpreter } from '../capabilities/effect.ts'
+import {
+  displayEndpoint, endpointFingerprint, readFlyaiVerification, resolveFlyaiEndpoint,
+  resolveFlyaiKey, sha256Hex, writeFlyaiVerification,
+} from '../capabilities/flyai-config.ts'
+import type { FlyaiResult } from '../capabilities/flyai.ts'
+import { readLatestChannelEvents } from '../capabilities/channel-health.ts'
+
+const guidance = '在本机运行 gotry setup flyai（隐藏输入），或 gotry setup flyai --stdin；清除文件配置用 --clear。不要在聊天中发送 API key。打开 https://flyai.open.fliggy.com/console，登录后复制 API Key。'
+const guidanceImpact = '影响面:未配置 key 时 gotry_flyai_search 走匿名共享额度池(易达 Trial limit reached,达限本会话该工具不可用);配置后额度走本机 key,失败时按 verdict 改道 gotry_session_search 账号会话通道。'
+
+export function createFlyaiSetupTool(runEffect: EffectInterpreter, stateRoot?: string) {
+  return defineTool({
+    name: 'gotry_flyai_setup',
+    description: 'Inspect FlyAI credential source and verification status, or check the current configuration with a read-only search. Never accepts, changes or returns credentials. Check updates only a verification receipt; setting or clearing credentials requires the local gotry setup flyai command.',
+    parameters: { action: { type: 'string', enum: ['status', 'check'], description: 'status (default): local status; check: read-only provider verification' } },
+    output: { schema: { type: 'json' }, render: (_a, value) => [{ type: 'text', text: JSON.stringify(value) }] },
+    async execute(args, exec) {
+      // Reject unknown arguments before any provider invocation or metadata write.
+      if (Object.keys(args).some(key => key !== 'action') || (args.action !== undefined && args.action !== 'status' && args.action !== 'check')) {
+        return { ok: false, summary: `仅支持 status/check；不接收凭据。${guidance} ${guidanceImpact}` }
+      }
+      const home = homedir()
+      const current = resolveFlyaiKey()
+      const endpoint = resolveFlyaiEndpoint()
+      const fingerprint = endpointFingerprint(endpoint.url)
+      let receipt = readFlyaiVerification(home)
+      let checkVerdict: string | undefined
+      let receiptSaved: boolean | undefined
+      if (args.action === 'check') {
+        const date = new Date(Date.now() + 7 * 86_400_000).toISOString().slice(0, 10)
+        const outcome = await runEffect({ effect: 'FLYAI_SEARCH', params: {
+          kind: 'flight', origin: '上海', destination: '北京', depDate: date,
+          timeoutMs: 20_000, signal: exec?.signal,
+        } })
+        const result = outcome.result as FlyaiResult | null
+        checkVerdict = outcome.trace.declined === 'aborted' ? 'cancelled' : result?.verdict ?? 'error'
+        // A concurrent local credential change invalidates this check's receipt.
+        const after = resolveFlyaiKey()
+        const unchanged = current.key === after.key && current.source === after.source
+          && fingerprint === endpointFingerprint(resolveFlyaiEndpoint().url)
+        if (current.key && fingerprint && unchanged && checkVerdict !== 'cancelled') {
+          const allowed = ['auth-error', 'forbidden', 'rate-limited', 'timeout', 'needs-setup', 'error'] as const
+          const verdict = checkVerdict === 'hit' || checkVerdict === 'miss' ? 'verified'
+            : allowed.find(value => value === checkVerdict) ?? 'error'
+          receipt = { schema: 'gotry.flyai-verification.v1', source: current.source,
+            keySha256: sha256Hex(current.key), maskedKey: current.maskedKey ?? '****',
+            endpointFingerprint: fingerprint, endpointDebug: endpoint.debug,
+            verdict, at: new Date().toISOString() }
+          receiptSaved = writeFlyaiVerification(receipt, home)
+        }
+      }
+      const matches = Boolean(current.key && receipt && receipt.keySha256 === sha256Hex(current.key)
+        && receipt.source === current.source && receipt.endpointFingerprint === fingerprint
+        && receipt.endpointDebug === endpoint.debug)
+      const verified = matches && receipt?.verdict === 'verified'
+      const event = stateRoot ? (await readLatestChannelEvents(stateRoot, { requireValidTimestamp: true })).get('flyai') : undefined
+      const lastTrialLimit = event?.state === 'down' && event.reason === 'needs-setup' ? event.at : undefined
+      const status = !current.key ? '匿名试用（共享额度）' : verified ? '已验证当前配置' : '已配置，未验证通过'
+      const summary = `${status}；来源 ${current.source}；endpoint ${displayEndpoint(endpoint.url)}${endpoint.debug ? '（DEBUG）' : ''}。`
+        + (checkVerdict ? `本次只读检查：${checkVerdict}。` : '')
+        + (lastTrialLimit ? `最近试用额度受限：${lastTrialLimit}。` : '')
+        + (receiptSaved === false ? '验证回执保存失败，doctor 状态尚未更新。' : '') + guidance
+        + ' ' + guidanceImpact
+      return JSON.parse(JSON.stringify({ ok: receiptSaved !== false && (!checkVerdict || checkVerdict === 'hit' || checkVerdict === 'miss'), action: args.action ?? 'status',
+        source: current.source, configured: Boolean(current.key), verified,
+        maskedKey: current.maskedKey, configPath: current.configPath,
+        endpoint: displayEndpoint(endpoint.url), endpointDebug: endpoint.debug,
+        checkVerdict, receiptSaved, lastTrialLimit, summary })) as Record<string, never>
+    },
+    // Do not retain unexpected arguments even when a host bypasses schema validation.
+    presentCall: args => ({ card: 'generic', title: 'FlyAI 配置检查', kind: 'fetch', rawInput: { action: args.action === 'check' ? 'check' : 'status' } }),
+  })
+}