dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/intent/README.md

@@ -0,0 +1,63 @@
+# dsh-data-domain-knowledge/intent
+
+> 本模块原为独立插件 `@tita-data-agent/data-domain-intent`，于 0020 并入本插件，
+> 因为「意图」Tab 早已长在 `KnowledgePanel` 里。对外契约（三个 `intent_*` 工具名、
+> `/intent/*` 路由、`tita-data-agent-intent` 设置命名空间、`titaDataAgentIntent` 服务）
+> 一个都没变。
+
+Tita Data Agent 的意图**记录器**。Host 侧注册 `intent_record`、
+`intent_store_view`、`intent_registry_list` 三个工具。
+
+判断完全交给大模型：`intent_record` 只把模型给出的结论落成一条审计记录，不做
+关键词匹配、不做状态机、不反问、不阻断当前请求，也不返回失败。模型漏调时，Host
+在轮次结束（`turn/end`）补一条 `source: 'fallback'` 的 `unknown` 记录。
+
+分类规则（两段式判定 + 预置分类 + act 词表）**就是 `intent_record` 的工具描述**，
+0023 起不再单独注入 system prompt 段。工具描述是静态字符串，所以设置一变宿主就
+dispose 旧的、按新文本重新注册（`ensureRecordTool`）；没有开关，它始终在场。
+
+## 记录与 ID
+
+- 按 `session + turn` upsert：同一轮重复调用只留一条记录。
+- 每个 actionable 轮次由 Host 在 `turn/start` 预分配 `subtaskId`，模型用
+  `relation` 决定这轮是新任务（`new_task`）还是已有任务的子任务
+  （`subtask_of` + `task_id`）。引用不存在的 task 会降级为 `new_task` 并给出
+  warning。
+- `task_id` / `run_id` 可显式传入以续接链路或重试；`parentSubtaskId` 指向同一
+  task 下最近一条 subtask。
+
+## 配置
+
+分类、act、predicate 由 settings namespace `tita-data-agent-intent` 提供，`intent_registry_list`
+与 `intent_record` 的工具描述都读同一份配置。
+
+「意图」页分三个 tab：**意图记录**（只读审计流）/ **意图配置**（可写）/ **意图的逻辑**
+（说明：什么是意图、为什么要配置、字段 schema、引用文献）。
+
+**分类与 act 都可配置**（0023）：卡片可以增删改停用、一键恢复出厂预置，写入走
+`settings.<field>`；宿主在 `onChange` 里立刻把新配置灌回引擎并重挂工具描述，所以保存后
+**下一轮就生效**，不需要重启。predicate 是真实工具名，保持只读。
+
+每个分类带 `description`（这一类"是什么"）与 `examples`（用户可能怎么说）；每个 act 带
+`label` 与 `description`（"这一轮在做什么"）。它们都进工具描述，判定因此是**两段式**的：
+
+1. 先逐条比对预置分类，命中就**直接用该分类 id**；
+2. 全不命中才自行判断——新起一个 id 或落 `unknown`。
+
+预置项是模型的先验，不是"仅供参考的清单"；模型不必每轮从零分类。停用的分类不出现在可用
+清单里（只报数量），历史记录仍按原 id 解析。
+
+## 下游 ID 透传
+
+`tools/pre-execute` 明确禁止改写调用入参，因此 Host 不能在派发前注入 ID。透传
+由消费方在解析 lineage 时回退读取：intent 插件通过 cordis 服务
+`titaDataAgentIntent.activeLineage(sessionId)` 暴露当前任务 ID，data-table 的
+`lineageOfArgs` 已在缺省时合并该值（显式传参优先）。data-notebook 与
+data-domain-knowledge 的同类回退待接入。
+
+## 已知限制
+
+- 记录保存在进程内 `IntentStore`，按 TTL（默认 600 秒）过期，重启即丢；按
+  `taskId` 的历史反查与持久化尚未实现。
+- 派发竞态：与 `intent_record` 并行的业务调用可能先于记录提交，此时回退到
+  「活跃 taskId + 本轮占位 subtaskId」，不保证完全精确。

package/src/intent/engine.ts

@@ -0,0 +1,527 @@
+import {
+  DEFAULT_ACTS,
+  DEFAULT_INTENT_SETTINGS,
+  type IntentActDef,
+  type IntentRecord,
+  type IntentRecordInput,
+  type IntentRef,
+  type IntentRegistry,
+  type IntentRelation,
+  type IntentResult,
+  type IntentSettings,
+  type IntentSlotMap,
+  type IntentSource,
+  type IntentStoreView,
+  type IntentTaskSummary,
+  type IntentTurnState,
+} from './types.js'
+import { envelopeSuccess } from 'dsh-data-contracts/envelope'
+import type { LineageContext } from 'dsh-data-contracts/refs'
+
+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
+}
+
+/**
+ * 规整 act 词表。
+ *
+ * 兼容两种形态：0023 之前的持久化配置是 `string[]`，现在是带 label 的对象数组。
+ * 老配置读回来只会缺 label / description，不会丢动作。
+ */
+function actsOf(value: unknown): IntentActDef[] {
+  if (!Array.isArray(value)) return DEFAULT_ACTS.map(def => ({ ...def }))
+  return value.flatMap((item): IntentActDef[] => {
+    if (typeof item === 'string' && item.trim()) {
+      const id = item.trim()
+      return [{ id, label: id, description: '', enabled: true }]
+    }
+    if (!item || typeof item !== 'object') return []
+    const record = item as Record<string, unknown>
+    const id = typeof record.id === 'string' ? record.id.trim() : ''
+    if (!id) return []
+    return [{
+      id,
+      label: typeof record.label === 'string' && record.label.trim() ? record.label.trim() : id,
+      description: typeof record.description === 'string' ? record.description : '',
+      enabled: record.enabled !== false,
+    }]
+  })
+}
+
+/**
+ * 谓词词表。
+ *
+ * 与 `categories` / `acts` 同一个理由：`predicates` 是 schema 里唯一一个「数组 +
+ * volatile」的标量字段，而 0.1.7 解析出来的 volatile 字段是引用、不是值 —— 一个
+ * 漏解包的引用在这里会变成 `predicates.join('、')` 抛
+ * `join is not a function`（0029 实测，抛出点在 preset 的挂载行上，整个 preset
+ * 组合不出会话）。所以这里也兜一层：不是字符串数组就退回出厂谓词，而不是让整个
+ * preset 挂掉 —— 与 `normalizeKnowledge` 的取舍一致（一个配置疏漏不该把插件打挂）。
+ */
+function predicatesOf(value: unknown): string[] {
+  if (!Array.isArray(value)) return DEFAULT_INTENT_SETTINGS.predicates
+  const items = value.filter((item): item is string => typeof item === 'string')
+  return items.length ? items : DEFAULT_INTENT_SETTINGS.predicates
+}
+
+/** 标量字段的同类兜底：类型不对就退回默认值（引用对象、`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),
+    categories: Array.isArray(settings.categories) ? settings.categories : DEFAULT_INTENT_SETTINGS.categories,
+    acts: actsOf(settings.acts),
+    predicates: predicatesOf(settings.predicates),
+  }
+}
+
+/**
+ * Bounded audit store: one record per session turn, expiring after the configured TTL.
+ *
+ * 0033 起它同时是**工作集**与**留痕的入口**，两者的分工要说清：
+ *
+ * - 内存里这份是有 TTL 的**工作集**（默认 600 秒）：血缘判定只关心最近的轮次，
+ *   一个十轮之前就结束的会话不该让新的一轮接到它的 task 上。
+ * - 磁盘上那份（`intent/records.ndjson`）是**留痕**，只追加、不随 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): IntentTurnState {
+    const state: IntentTurnState = {
+      turn,
+      userInput: userInput.slice(0, 2000),
+      subtaskId: id('subtask'),
+      taskId: this.store.last(sessionKey)?.lineage.taskId,
+      committed: false,
+    }
+    this.turns.set(sessionKey, state)
+    return state
+  }
+
+  /** Backfill one `unknown` record when a turn ends without a 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
+    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. Always stores a record. */
+  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 act = input.act?.trim() || 'unknown'
+    const category = input.category?.trim() || undefined
+    const confidence = clamp01(input.confidence)
+    if (!input.userInput?.trim()) warnings.push('user_input 为空，仅记录了一条空意图')
+    if (act !== 'unknown' && !this.settings.acts.some(item => item.id === act && item.enabled)) warnings.push(`act "${act}" 不在已启用的 act 列表中，已按原样记录`)
+    if (category && !this.settings.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: input.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 }
+  }
+
+  registry(): IntentRegistry {
+    return {
+      acts: this.settings.acts.map(def => ({ ...def })),
+      categories: this.settings.categories.map(category => ({
+        id: category.id,
+        label: category.label,
+        route: category.route,
+        description: category.description ?? '',
+        examples: [...(category.examples ?? [])],
+        enabled: category.enabled,
+      })),
+      predicates: [...this.settings.predicates],
+    }
+  }
+
+  /**
+   * 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 enabled = this.settings.categories.filter(category => category.enabled)
+    const disabledCount = this.settings.categories.length - enabled.length
+    const routes = enabled
+      .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')
+    const acts = this.settings.acts.filter(def => def.enabled)
+      .map(def => `- ${def.id}${def.label && def.label !== def.id ? `（${def.label}）` : ''}${def.description ? `：${def.description}` : ''}`)
+      .join('\n')
+    return [
+      '记录本轮用户意图：先判断，再调用 intent_record 落一条审计记录，然后继续完成请求——记录不改变、不阻塞、也不需要用户确认。',
+      '当前轮是新的任务用 relation=new_task；如果是在延续某个已有任务（追问、补充、纠正），用 relation=subtask_of 并带上该任务的 task_id；无法判断时省略 relation。',
+      '',
+      '分类判定分两步，必须先匹配预置、再自行判断：',
+      '1) 先把用户的意思和下面的「预置分类」逐条比对——看定义，也看"例如"里的说法。命中就直接用该分类的 id，不要另起一个近义的新 id，也不要因为措辞不同就换一个分类。',
+      '2) 所有预置分类都不命中时，才自行判断：可以按语义新起一个短语作为分类 id，或落 unknown。新起的 id 用英文小写下划线，并在 slots 里带上关键参数。',
+      '',
+      '预置分类（category 参数传 id）：',
+      routes,
+      ...(disabledCount > 0 ? [`（另有 ${disabledCount} 个分类已停用，不要使用。）`] : []),
+      '',
+      'act 回答"这一轮用户在做什么"，挑最贴近的一个：',
+      acts,
+      `可用 predicate：${this.settings.predicates.join('、')}`,
+    ].join('\n')
+  }
+}
+
+export function createIntentEngine(settings?: Partial<IntentSettings>): IntentEngine {
+  return new IntentEngine(settings)
+}