dsh-data-domain-knowledge 0.1.1-alpha.2 → 0.1.1-alpha.3

package/src/intent/engine.ts

@@ -1,515 +0,0 @@
-import {
-  DEFAULT_ACTS,
-  DEFAULT_CATEGORIES,
-  DEFAULT_INTENT_SETTINGS,
-  DEFAULT_PREDICATES,
-  type IntentRecord,
-  type IntentRecordInput,
-  type IntentRef,
-  type IntentRelation,
-  type IntentResult,
-  type IntentSettings,
-  type IntentSlotMap,
-  type IntentSource,
-  type IntentStoreView,
-  type IntentTaskSummary,
-  type IntentTurnState,
-} from './types.js'
-import { envelopeSuccess } from '#contracts'
-import type { LineageContext } from '#contracts'
-
-function id(prefix = 'intent'): string {
-  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
-}
-
-function clamp01(value: unknown): number | undefined {
-  if (typeof value !== 'number' || !Number.isFinite(value)) return undefined
-  return Math.max(0, Math.min(1, value))
-}
-
-function slotsOf(value: unknown): IntentSlotMap {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
-  return Object.fromEntries(Object.entries(value as Record<string, unknown>).filter(([, item]) => item !== null && item !== undefined))
-}
-
-function refsOf(value: unknown): IntentRef[] {
-  if (!Array.isArray(value)) return []
-  return value.flatMap((ref): IntentRef[] => {
-    if (typeof ref === 'string' && ref.trim()) return [{ id: ref.trim() }]
-    if (ref && typeof ref === 'object' && typeof (ref as { id?: unknown }).id === 'string') {
-      const item = ref as { id: string; kind?: unknown; label?: unknown }
-      return [{ id: item.id, ...(typeof item.kind === 'string' ? { kind: item.kind } : {}), ...(typeof item.label === 'string' ? { label: item.label } : {}) }]
-    }
-    return []
-  })
-}
-
-function safeLineage(value: unknown): Partial<LineageContext> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
-  const record = value as Record<string, unknown>
-  const result: Partial<LineageContext> = {}
-  for (const key of ['sessionId', 'turnId', 'intentId', 'taskId', 'subtaskId', 'parentSubtaskId', 'runId', 'traceId', 'domain'] as const) {
-    if (typeof record[key] === 'string' && record[key].trim()) result[key] = record[key].trim().slice(0, 160)
-  }
-  return result
-}
-
-/** 标量字段的同类兜底：类型不对就退回默认值（引用对象、`undefined`、字符串都算不对）。 */
-function numberOr(value: unknown, fallback: number): number {
-  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
-}
-
-function booleanOr(value: unknown, fallback: boolean): boolean {
-  return typeof value === 'boolean' ? value : fallback
-}
-
-function normalizeSettings(settings: IntentSettings): IntentSettings {
-  return {
-    ...settings,
-    clarifyThreshold: numberOr(settings.clarifyThreshold, DEFAULT_INTENT_SETTINGS.clarifyThreshold),
-    ttlSeconds: numberOr(settings.ttlSeconds, DEFAULT_INTENT_SETTINGS.ttlSeconds),
-    fallbackEnabled: booleanOr(settings.fallbackEnabled, DEFAULT_INTENT_SETTINGS.fallbackEnabled),
-  }
-}
-
-/**
- * Bounded audit store: one record per session turn, expiring after the configured TTL.
- *
- * 0033 起它同时是**工作集**与**留痕的入口**，两者的分工要说清：
- *
- * - 内存里这份是有 TTL 的**工作集**（默认 600 秒）：血缘判定只关心最近的轮次，
- *   一个十轮之前就结束的会话不该让新的一轮接到它的 task 上。
- * - 磁盘上那份（`intent/intent.db`）是**留痕**，当前版本便于读取，历史版本只追加、不随 TTL 消失。
- *   `sink` 在每次 `save` 时被调用，`hydrate` 在启动时把留痕读回工作集 ——
- *   重启之后同一个会话的血缘因此还在（在 TTL 窗口内）。
- *
- * 为什么不干脆让 `records()` 直接读文件：那会让 TTL 名存实亡（文件永远有），
- * 于是「工作集」这个概念消失，血缘会接到很久以前的 task 上。两件事分开，
- * 各自的契约才都成立。
- */
-export class IntentStore {
-  private readonly sessions = new Map<string, { records: IntentRecord[]; touched: number }>()
-  /**
-   * 每条被保存的记录都会经过它（落盘留痕）。
-   *
-   * 同步签名、由调用方自己吞异常：`save` 在记录路径的关键路径上，而留痕失败
-   * 不该让这一轮的意图记录失败 —— 「记录不拦截请求」这条契约对留痕也成立。
-   */
-  private sink?: (record: IntentRecord) => void
-  constructor(private ttlSeconds = DEFAULT_INTENT_SETTINGS.ttlSeconds, private readonly now = () => Date.now()) {}
-
-  /** 装上一个留痕出口。多次调用以最后一次为准。 */
-  setSink(sink: (record: IntentRecord) => void): void {
-    this.sink = sink
-  }
-
-  /**
-   * 把留痕读回工作集（启动时调用一次）。
-   *
-   * `touched` 用记录自己的 `updatedAt`，于是「重启」不会把 TTL 归零：一份十小时
-   * 前的记录在 TTL 600 秒下本来就该过期，重启不该让它复活。
-   */
-  hydrate(records: IntentRecord[]): number {
-    let loaded = 0
-    for (const record of records) {
-      const item = this.sessions.get(record.sessionKey) ?? { records: [], touched: 0 }
-      const index = item.records.findIndex(existing => existing.turnKey === record.turnKey)
-      if (index >= 0) item.records[index] = record
-      else item.records.push(record)
-      item.records = item.records.slice(-100)
-      const at = Date.parse(String(record.updatedAt ?? record.createdAt))
-      item.touched = Math.max(item.touched, Number.isFinite(at) ? at : this.now())
-      this.sessions.set(record.sessionKey, item)
-      loaded += 1
-    }
-    return loaded
-  }
-
-  setTtl(seconds: number): void {
-    this.ttlSeconds = Math.max(1, Math.min(86400, Math.round(seconds)))
-  }
-
-  private entry(sessionKey: string) {
-    const current = this.sessions.get(sessionKey)
-    if (!current || this.now() - current.touched > this.ttlSeconds * 1000) {
-      const fresh: { records: IntentRecord[]; touched: number } = { records: [], touched: this.now() }
-      this.sessions.set(sessionKey, fresh)
-      return fresh
-    }
-    current.touched = this.now()
-    return current
-  }
-
-  /** Upsert by turn key so repeated records within one turn stay a single fact. */
-  save(record: IntentRecord): IntentRecord {
-    const item = this.entry(record.sessionKey)
-    const index = item.records.findIndex(existing => existing.turnKey === record.turnKey)
-    if (index >= 0) item.records[index] = record
-    else item.records.push(record)
-    item.records = item.records.slice(-100)
-    try { this.sink?.(record) } catch { /* 留痕失败不影响这一轮 */ }
-    return record
-  }
-
-  records(sessionKey: string): IntentRecord[] {
-    return this.entry(sessionKey).records
-  }
-
-  last(sessionKey: string): IntentRecord | undefined {
-    return this.entry(sessionKey).records.at(-1)
-  }
-
-  findByTurn(sessionKey: string, turnKey: string): IntentRecord | undefined {
-    return this.entry(sessionKey).records.find(record => record.turnKey === turnKey)
-  }
-
-  taskExists(sessionKey: string, taskId: string): boolean {
-    return this.entry(sessionKey).records.some(record => record.lineage.taskId === taskId)
-  }
-
-  lastSubtaskOf(sessionKey: string, taskId: string): string | undefined {
-    return this.entry(sessionKey).records.filter(record => record.lineage.taskId === taskId).at(-1)?.lineage.subtaskId
-  }
-
-  expiresAt(sessionKey: string): string | undefined {
-    const item = this.entry(sessionKey)
-    return item.records.length > 0 ? new Date(item.touched + this.ttlSeconds * 1000).toISOString() : undefined
-  }
-
-  clear(sessionKey: string): void {
-    this.sessions.delete(sessionKey)
-  }
-
-  /** When the session was last touched (ms since epoch); 0 when unknown. */
-  touchedAt(sessionKey: string): number {
-    return this.sessions.get(sessionKey)?.touched ?? 0
-  }
-
-  /** Live session keys, most recently touched first. Expired sessions are skipped. */
-  sessionKeys(): string[] {
-    const now = this.now()
-    const live: Array<{ key: string; touched: number }> = []
-    for (const [key, item] of this.sessions) {
-      if (now - item.touched > this.ttlSeconds * 1000) continue
-      live.push({ key, touched: item.touched })
-    }
-    return live.sort((left, right) => right.touched - left.touched).map(item => item.key)
-  }
-}
-
-/**
- * Intent recorder. Every entry point is total: an unrecognized act, an unknown
- * task reference, or a missing classification degrade into warnings on a stored
- * record. Nothing here blocks, confirms, or rewrites the user's request.
- */
-export class IntentEngine {
-  readonly store: IntentStore
-  private settings: IntentSettings
-  private readonly turns = new Map<string, IntentTurnState>()
-
-  constructor(settings: Partial<IntentSettings> = {}, store?: IntentStore) {
-    this.settings = normalizeSettings({ ...DEFAULT_INTENT_SETTINGS, ...settings })
-    this.store = store ?? new IntentStore(this.settings.ttlSeconds)
-  }
-
-  setSettings(settings: Partial<IntentSettings>): void {
-    this.settings = normalizeSettings({ ...this.settings, ...settings })
-    this.store.setTtl(this.settings.ttlSeconds)
-  }
-
-  getSettings(): IntentSettings {
-    return this.settings
-  }
-
-  /**
-   * Open a turn and allocate its provisional ids before the model records.
-   * Downstream calls dispatched in parallel with the record can already carry
-   * an id; the record later commits the authoritative task binding.
-   */
-  beginTurn(sessionKey: string, turn: number, userInput: string, eligible = true): IntentTurnState {
-    const state: IntentTurnState = {
-      turn,
-      userInput: userInput.slice(0, 2000),
-      subtaskId: id('subtask'),
-      taskId: this.store.last(sessionKey)?.lineage.taskId,
-      eligible,
-      dataToolUsed: false,
-      committed: false,
-    }
-    this.turns.set(sessionKey, state)
-    return state
-  }
-
-  /**
-   * 用户消息可能在 `turn/start` 之后才到达。
-   *
-   * 宿主事件顺序不是固定的：有些会话先发 `turn/start`，再发 `user/message`。如果只在
-   * `beginTurn` 读取一次原文，就会把整轮意图永久记录成空字符串。收到真实用户消息后，
-   * 只更新尚未提交的当前轮次；已经记录的判断不再被后来事件改写。
-   */
-  updateTurnInput(sessionKey: string, userInput: string): boolean {
-    const state = this.turns.get(sessionKey)
-    if (!state || state.committed || !userInput.trim()) return false
-    state.userInput = userInput.slice(0, 2000)
-    return true
-  }
-
-  /** Mark the current turn as a data turn without classifying it. */
-  markDataIntent(sessionKey: string, turn?: number): boolean {
-    const state = this.turns.get(sessionKey)
-    if (!state || state.committed || (turn !== undefined && state.turn !== turn)) return false
-    state.eligible = true
-    return true
-  }
-
-  /** Mark the current turn as a data turn based on actual data-tool use. */
-  markDataToolUse(sessionKey: string, turn?: number): boolean {
-    const state = this.turns.get(sessionKey)
-    if (!state || state.committed || (turn !== undefined && state.turn !== turn)) return false
-    state.eligible = true
-    state.dataToolUsed = true
-    return true
-  }
-
-  /** Clear a text-only gate when the model explicitly identifies a non-data turn. */
-  clearDataIntent(sessionKey: string, turn?: number): boolean {
-    const state = this.turns.get(sessionKey)
-    if (!state || state.committed || (turn !== undefined && state.turn !== turn)) return false
-    if (!state.dataToolUsed) state.eligible = false
-    return true
-  }
-
-  /** Whether the current turn is eligible for data intent recording. */
-  isDataIntentTurn(sessionKey: string, turn?: number): boolean {
-    const state = this.turns.get(sessionKey)
-    return Boolean(state && !state.committed && state.eligible && (turn === undefined || state.turn === turn))
-  }
-
-  /** Backfill one `unknown` record only when an eligible data turn has no model record. */
-  fallbackWhenMissing(sessionKey: string, turn: number): IntentResult | undefined {
-    if (!this.settings.fallbackEnabled) return undefined
-    const state = this.turns.get(sessionKey)
-    if (!state || state.turn !== turn || state.committed) return undefined
-    if (!state.eligible) {
-      this.turns.delete(sessionKey)
-      return undefined
-    }
-    const result = this.record({
-      userInput: state.userInput,
-      act: 'unknown',
-      category: 'unknown',
-      relation: 'unknown',
-      sessionKey,
-    }, 'fallback')
-    if (result.ok) {
-      state.committed = true
-      this.turns.delete(sessionKey)
-    }
-    return result
-  }
-
-  /** Record the model's intent judgement. The host applies scope before calling this method. */
-  record(input: IntentRecordInput, source: IntentSource = 'model'): IntentResult {
-    const sessionKey = input.sessionKey?.trim() || 'default'
-    const timestamp = new Date(input.now ?? Date.now()).toISOString()
-    const warnings: string[] = []
-    const state = this.turns.get(sessionKey)
-    const turnKey = state ? `${sessionKey}#${state.turn}` : `${sessionKey}#${input.turnId?.trim() || 'manual'}`
-    const existing = this.store.findByTurn(sessionKey, turnKey)
-    const lineageInput = safeLineage(input.lineage)
-
-    const userInput = input.userInput?.trim() ? input.userInput : state?.userInput ?? ''
-    const act = input.act?.trim() || 'unknown'
-    const category = input.category?.trim() || undefined
-    const confidence = clamp01(input.confidence)
-    if (!userInput.trim()) warnings.push('user_input 为空，仅记录了一条空意图')
-    if (act !== 'unknown' && !DEFAULT_ACTS.some(item => item.id === act && item.enabled)) warnings.push(`act "${act}" 不在内置 act 列表中，已按原样记录`)
-    if (category && !DEFAULT_CATEGORIES.some(item => item.id === category && item.enabled)) warnings.push(`category "${category}" 不是内置分类，已按原样记录`)
-    const lowConfidence = confidence !== undefined && confidence < this.settings.clarifyThreshold
-    if (lowConfidence) warnings.push(`confidence ${confidence.toFixed(2)} 低于阈值 ${this.settings.clarifyThreshold.toFixed(2)}，已标记 lowConfidence`)
-
-    const requestedTaskId = lineageInput.taskId
-    let relation: IntentRelation = input.relation ?? (requestedTaskId ? 'subtask_of' : 'new_task')
-    let taskId: string | undefined
-    let parentSubtaskId: string | undefined
-    if (relation === 'subtask_of') {
-      if (requestedTaskId && this.store.taskExists(sessionKey, requestedTaskId)) {
-        taskId = requestedTaskId
-        parentSubtaskId = this.store.lastSubtaskOf(sessionKey, requestedTaskId)
-      } else {
-        warnings.push(requestedTaskId
-          ? `task_id "${requestedTaskId}" 在本会话不存在，本轮已按 new_task 记录`
-          : 'relation=subtask_of 缺少 task_id，本轮已按 new_task 记录')
-        relation = 'new_task'
-      }
-    }
-    if (!taskId) {
-      taskId = relation === 'new_task'
-        ? id('task')
-        : existing?.lineage.taskId ?? state?.taskId ?? id('task')
-    }
-    const subtaskId = existing?.lineage.subtaskId ?? state?.subtaskId ?? id('subtask')
-    const runId = lineageInput.runId ?? existing?.lineage.runId ?? id('run')
-    const intentId = existing?.id ?? id('intent')
-    const turnId = input.turnId?.trim() || existing?.turnId || (state ? `turn-${state.turn}` : id('turn'))
-
-    const record: IntentRecord = {
-      id: intentId,
-      sessionKey,
-      turnKey,
-      turnId,
-      userInput,
-      act,
-      ...(category ? { category } : {}),
-      ...(input.predicate?.trim() ? { predicate: input.predicate.trim() } : {}),
-      slots: slotsOf(input.slots),
-      ...(confidence !== undefined ? { confidence } : {}),
-      ...(lowConfidence ? { lowConfidence: true } : {}),
-      refs: refsOf(input.refs),
-      relation,
-      source,
-      createdAt: existing?.createdAt ?? timestamp,
-      updatedAt: timestamp,
-      lineage: {
-        ...lineageInput,
-        sessionId: lineageInput.sessionId ?? sessionKey,
-        turnId,
-        intentId,
-        taskId,
-        subtaskId,
-        ...(parentSubtaskId ? { parentSubtaskId } : {}),
-        runId,
-      },
-      meta: {},
-    }
-    this.store.save(record)
-    if (state) {
-      state.committed = true
-      state.taskId = taskId
-      state.subtaskId = subtaskId
-    }
-
-    // Built through the shared constructor. This literal used to omit
-    // `error: null`, which made an intent result the one envelope in the repo
-    // that did not satisfy spec/contracts/envelope.json.
-    return envelopeSuccess({
-      intentId,
-      taskId,
-      subtaskId,
-      ...(parentSubtaskId ? { parentSubtaskId } : {}),
-      runId,
-      turnId,
-      act,
-      ...(category ? { category } : {}),
-      relation,
-      source,
-      lowConfidence,
-      activeTasks: this.tasks(sessionKey),
-    }, warnings)
-  }
-
-  /** Ids a downstream tool call in this session should carry. */
-  activeLineage(sessionKey: string): { lineage: Partial<LineageContext>; committed: boolean } | undefined {
-    const last = this.store.last(sessionKey)
-    if (last) return { lineage: { ...last.lineage }, committed: this.turns.get(sessionKey)?.committed ?? true }
-    const state = this.turns.get(sessionKey)
-    if (!state) return undefined
-    return { lineage: { sessionId: sessionKey, ...(state.taskId ? { taskId: state.taskId } : {}), subtaskId: state.subtaskId }, committed: false }
-  }
-
-  tasks(sessionKey: string): IntentTaskSummary[] {
-    const now = Date.now()
-    const seen = new Map<string, IntentTaskSummary>()
-    for (const record of this.store.records(sessionKey)) {
-      const taskId = record.lineage.taskId
-      if (!taskId) continue
-      seen.set(taskId, {
-        taskId,
-        ...(record.lineage.subtaskId ? { lastSubtaskId: record.lineage.subtaskId } : {}),
-        ...(record.category ? { category: record.category } : {}),
-        ageSeconds: Math.max(0, Math.round((now - Date.parse(record.updatedAt)) / 1000)),
-      })
-    }
-    return [...seen.values()].slice(-3).reverse()
-  }
-
-  view(sessionKey = 'default', includePrompt = false): IntentResult {
-    const last = this.store.last(sessionKey)
-    const view: IntentStoreView = {
-      sessionKey,
-      ...(last?.lineage.taskId ? { activeTaskId: last.lineage.taskId } : {}),
-      ...(last ? { activeIntentId: last.id } : {}),
-      tasks: this.tasks(sessionKey),
-      recent: this.store.records(sessionKey).slice(-10).reverse(),
-      ...(this.store.expiresAt(sessionKey) ? { expiresAt: this.store.expiresAt(sessionKey) } : {}),
-    }
-    return envelopeSuccess({ store: view, ...(includePrompt ? { prompt: this.routingPrompt() } : {}) })
-  }
-
-  /**
-   * Session-level index for the 意图 panel: every live session with its last
-   * classification and active task ids. Records themselves stay per-session.
-   */
-  overview(): { sessions: Array<Record<string, unknown>> } {
-    const sessions = this.store.sessionKeys().map(sessionKey => {
-      const last = this.store.last(sessionKey)
-      return {
-        sessionKey,
-        recordCount: this.store.records(sessionKey).length,
-        lastAt: new Date(this.store.touchedAt(sessionKey)).toISOString(),
-        tasks: this.tasks(sessionKey),
-        ...(last ? { activeIntentId: last.id } : {}),
-        ...(last?.act ? { lastAct: last.act } : {}),
-        ...(last?.category ? { lastCategory: last.category } : {}),
-        ...(last?.relation ? { lastRelation: last.relation } : {}),
-        ...(last?.lineage.taskId ? { activeTaskId: last.lineage.taskId } : {}),
-        ...(last && last.confidence !== undefined ? { lastConfidence: last.confidence } : {}),
-      }
-    })
-    return { sessions }
-  }
-
-  /**
-   * Model-facing contract: record first, then continue; the record never gates the request.
-   *
-   * 这段文本就是 `intent_record` 的**工具描述**（0023 起不再单独注入 system prompt 段），
-   * 分类规则固定随工具在场，不再通过设置或注册表变更。
-   *
-   * 分类判定是**两段式**的（issue 0023）：
-   * 1. 先拿用户意思去比对预置分类的 `description` / `examples`，命中就**直接用该 id**；
-   * 2. 全不命中才允许自行判断（新起一个 id 或落 `unknown`）。
-   *
-   * 这样预置项就是"先验"，而不是一份仅供参考的清单——模型不必每轮从零分类。
-   */
-  routingPrompt(): string {
-    const routes = DEFAULT_CATEGORIES
-      .map(category => {
-        const head = `- ${category.id}（${category.label}）→ ${category.route}${category.description ? `：${category.description}` : ''}`
-        const examples = (category.examples ?? []).filter(Boolean)
-        return examples.length > 0 ? `${head}\n  例如：${examples.join(' / ')}` : head
-      })
-      .join('\n')
-    return [
-      '本工具支持 standard preset 的顶层会话。先判断本轮是否属于数据 / 知识域；只有属于数据域时，才调用 intent_record 落一条数据意图审计；寒暄、闲聊、Agent 自身说明、纯写作、代码和一般运维请求不要调用，也不要补 unknown。记录不改变、不阻塞、也不需要用户确认。',
-      '如果当前请求会使用数据、知识库、表格、报告、SourceRaw、WikiCard、查询、分析、导入、编译或召回工具，它属于数据域；否则按普通对话处理。',
-      '当前轮是新的任务用 relation=new_task；如果是在延续某个已有任务（追问、补充、纠正），用 relation=subtask_of 并带上该任务的 task_id；无法判断时省略 relation。',
-      '',
-      '分类判定分两步，必须先匹配预置、再自行判断：',
-      '1) 先把用户的意思和下面的「预置分类」逐条比对——看定义，也看"例如"里的说法。命中就直接用该分类的 id，不要另起一个近义的新 id，也不要因为措辞不同就换一个分类。',
-      '2) 所有预置分类都不命中时，才自行判断：可以按语义新起一个短语作为分类 id，或落 unknown。新起的 id 用英文小写下划线，并在 slots 里带上关键参数。',
-      '',
-      '预置分类（category 参数传 id）：',
-      routes,
-      '',
-      'act 回答"这一轮用户在做什么"，挑最贴近的一个：',
-      DEFAULT_ACTS
-        .map(def => `- ${def.id}${def.label && def.label !== def.id ? `（${def.label}）` : ''}${def.description ? `：${def.description}` : ''}`)
-        .join('\n'),
-      `可用 predicate：${DEFAULT_PREDICATES.join('、')}`,
-    ].join('\n')
-  }
-}
-
-export function createIntentEngine(settings?: Partial<IntentSettings>): IntentEngine {
-  return new IntentEngine(settings)
-}