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

package/src/intent/store.ts

@@ -0,0 +1,143 @@
+/**
+ * 意图的**落盘**（0033）。
+ *
+ * ## 为什么需要它
+ *
+ * 0033 之前，意图的两半都不在磁盘上属于这个 Agent 的地方：
+ *
+ * - **分类 / act 注册表**住在宿主的 settings 文档（`settings.yaml`）里。它确实落盘了，
+ *   但那是**宿主的配置**，不是这个 Agent 的文件 —— 备份知识库不会带上它，换一台机器
+ *   也不跟着走，而它恰恰决定了「同一句话被理解成什么」。
+ * - **每轮记录**只在内存里（`IntentStore` 的 Map，TTL 600 秒）。重启即丢。而架构图上
+ *   写着「意图记录…都已落盘」——**那句话当时是假的**。
+ *
+ * 现在两份东西都在 `<agentRoot>/intent/`：
+ *
+ * ```
+ * <agentRoot>/intent/
+ *   registry.json      分类 / act 词表（可编辑，面板就地改）
+ *   records.ndjson     每轮一条记录，append-only
+ * ```
+ *
+ * ## 为什么记录是 append-only 而不是「覆盖写」
+ *
+ * 记录本身按 `sessionKey#turn` upsert（同一轮重复调用只算一条事实），但**文件是审计
+ * 留痕**：追加每一版比原地覆盖更能回答「这一轮改过什么」。读的时候按同一个 key 取
+ * 最后一条，于是内存里那份「一轮一条」的语义不变，而磁盘上留下了完整过程。
+ *
+ * 代价是文件会随使用增长。这是审计流的固有代价，且它是纯追加、没有读放大 ——
+ * 真到需要清理时应该按时间归档，而不是在这里改成覆盖写。
+ *
+ * @module
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { appendFile, mkdir, readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { IntentActDef, IntentRecord } from './types.js'
+
+/** 注册表文件名。分类与 act 住一起：它们是一份词表的两半，分开存只会漂移。 */
+export const INTENT_REGISTRY_FILE = 'registry.json'
+/** 记录文件名。NDJSON 而不是 JSON 数组：追加是 O(1)，且半行坏数据只坏一行。 */
+export const INTENT_RECORDS_FILE = 'records.ndjson'
+
+export interface IntentRegistryFile {
+  version: 1
+  acts: IntentActDef[]
+  categories: Array<{ id: string; label: string; route: string; description: string; examples: string[]; enabled: boolean }>
+  updatedAt?: string
+}
+
+/**
+ * 原子写：先写 `.tmp` 再 rename。半截的 registry.json 会让引擎按出厂预置启动。
+ *
+ * **同步**，与 `migrate.ts` 同一个理由：注册表的读发生在**设置解析的回调里**
+ * （`setSource` → `apply()` → 灌进引擎），而那条路径必须同步完成 —— 异步化会让
+ * 「设置改了，引擎还是旧的」重新出现，而且窗口期随磁盘快慢变化。文件只有几 KB，
+ * 一次启动读一次。
+ */
+function writeAtomicSync(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const temp = `${path}.tmp`
+  writeFileSync(temp, content, 'utf8')
+  renameSync(temp, path)
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * 读注册表文件。
+ *
+ * **不抛异常**：文件坏了、被手改坏了、写了一半 —— 都返回 `undefined`，调用方按
+ * 出厂预置启动。注册表读不出来不该让整个意图引擎起不来，更不该让插件起不来。
+ */
+export function readIntentRegistry(root: string): IntentRegistryFile | undefined {
+  const path = join(root, INTENT_REGISTRY_FILE)
+  if (!existsSync(path)) return undefined
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    if (!isPlainObject(parsed)) return undefined
+    if (!Array.isArray(parsed.acts) || !Array.isArray(parsed.categories)) return undefined
+    return {
+      version: 1,
+      acts: parsed.acts as IntentActDef[],
+      categories: parsed.categories as IntentRegistryFile['categories'],
+      ...(typeof parsed.updatedAt === 'string' ? { updatedAt: parsed.updatedAt } : {}),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/** 写注册表文件。`updatedAt` 由调用方给，便于测试与审计对齐。 */
+export function writeIntentRegistry(root: string, registry: { acts: IntentActDef[]; categories: IntentRegistryFile['categories'] }, updatedAt = new Date().toISOString()): IntentRegistryFile {
+  const payload: IntentRegistryFile = { version: 1, acts: registry.acts, categories: registry.categories, updatedAt }
+  writeAtomicSync(join(root, INTENT_REGISTRY_FILE), `${JSON.stringify(payload, null, 2)}\n`)
+  return payload
+}
+
+/** 追加一条记录。失败不抛：留痕写不进去不该影响这一轮的回答。 */
+export async function appendIntentRecord(root: string, record: IntentRecord): Promise<void> {
+  try {
+    await mkdir(root, { recursive: true })
+    await appendFile(join(root, INTENT_RECORDS_FILE), `${JSON.stringify(record)}\n`, 'utf8')
+  } catch { /* 磁盘满 / 只读卷：这一轮照常回答，留痕缺失 */ }
+}
+
+/**
+ * 读记录（新→旧按时间，返回时升序）。
+ *
+ * 三条纪律：
+ * 1. **坏行只丢它自己。** 追加写天然会留下「最后一行写了一半」的可能（进程被杀），
+ *    一行 JSON.parse 失败不该让整份历史读不出来。
+ * 2. **按 `sessionKey#turnKey` 取最后一条。** 与内存里那份 upsert 语义一致。
+ * 3. `limit` 是**每个会话**的上限，不是总数：面板一次只显示一个会话。
+ */
+export async function readIntentRecords(root: string, sessionKey?: string, limit = 200): Promise<IntentRecord[]> {
+  const path = join(root, INTENT_RECORDS_FILE)
+  if (!existsSync(path)) return []
+  let text: string
+  try {
+    text = await readFile(path, 'utf8')
+  } catch {
+    return []
+  }
+  const latest = new Map<string, IntentRecord>()
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue
+    let record: IntentRecord
+    try {
+      record = JSON.parse(line) as IntentRecord
+    } catch {
+      continue
+    }
+    if (!isPlainObject(record) || typeof record.sessionKey !== 'string' || typeof record.turnKey !== 'string') continue
+    if (sessionKey !== undefined && record.sessionKey !== sessionKey) continue
+    latest.set(`${record.sessionKey}#${record.turnKey}`, record)
+  }
+  return [...latest.values()]
+    .sort((left, right) => String(left.updatedAt ?? left.createdAt).localeCompare(String(right.updatedAt ?? right.createdAt)))
+    .slice(-limit)
+}

package/src/intent/tools.ts

@@ -0,0 +1,139 @@
+/**
+ * 三个 `intent_*` 工具的**注册器**：与「引擎住在哪个平面」解耦。
+ *
+ * ## 为什么要单独一个文件
+ *
+ * 0029 之前这三个工具由宿主平面的 `applyIntent` 直接 `ctx.tools.register(...)`，
+ * 于是它们是**全局工具**：任何 agent、任何 preset 的会话都会在提示词里看到
+ * `intent_record`，也都能调它。而意图记录是这个方案自己的东西 —— 只有跑
+ * TitaAgent 那套组合的会话才该有它，别的 agent 场景（别的 preset、临时会话）
+ * 不该被塞一个用不上的工具。
+ *
+ * DSH 里「只有某个 preset 能用」的**唯一**支持形态是**注册作用域**：注册在哪个
+ * 作用域，就只在哪个作用域可见（`dsh-tools` 的 `register` 是 scope-layered）。
+ * `ctx.tools.restrict()` 只能做减法（从继承来的工具里减掉），宿主平面调它还会
+ * 直接抛 —— 没有「只给某一个作用域」的正向开关。所以正确的做法是把注册搬到
+ * **agent 平面**：一个只被自定义 preset 的 `agent.cordis.yml` 挂载的行
+ * （`./preset-tools.ts`），它注册的工具只覆盖那个 preset 的会话。
+ *
+ * 注册逻辑本身与平面无关，所以它留在这里：宿主平面负责「引擎怎么跑」（设置、
+ * 轮次记账、HTTP 只读面），agent 平面负责「模型看到什么工具」。两边共用这一份，
+ * 不各写一套工具定义。
+ *
+ * @module
+ */
+
+import { defineTool, type ToolRunContext } from '@deepseek-ai/dsh-tools'
+import type { LineageContext } from 'dsh-data-contracts/refs'
+
+/**
+ * 注册这三个工具需要引擎提供的能力。
+ *
+ * 刻意是**结构化的最小面**而不是 `IntentEngine` 本身：宿主平面通过
+ * `INTENT_SERVICE` 提供它，agent 平面的行只按这个形状取用。这样 preset 行不必
+ * import 引擎、也不必知道引擎住在哪个模块里。
+ */
+export interface IntentToolHost {
+  /** `intent_record` 的**工具描述就是路由提示词**（0023）。 */
+  routingPrompt(): string
+  record(args: Record<string, unknown>, exec?: ToolRunContext): unknown
+  view(sessionKey: string, includePrompt?: boolean): unknown
+  registry(): unknown
+  /** 提示词 / 词表变化时通知，返回取消订阅。 */
+  subscribe(listener: () => void): () => void
+}
+
+/** `intent_record` 的参数表。描述是路由提示词（工具级），所以这里只声明字段。 */
+const INTENT_RECORD_PARAMS: Record<string, unknown> = {
+  user_input: { type: 'string', required: true, description: '本轮用户原文' },
+  act: { type: 'string', description: '本轮动作 id，取自工具描述里的 act 词表' },
+  category: { type: 'string', description: '意图分类 id：先按预置分类匹配，命中就直接用它的 id；全不命中才自行新起一个 id 或落 unknown' },
+  predicate: { type: 'string', description: '要执行的动作，例如 query_babel_data' },
+  slots: { type: 'json', description: '从用户输入抽取的关键参数' },
+  confidence: { type: 'number', description: '0-1，用于标注 lowConfidence' },
+  refs: { type: 'array', description: '引用对象，例如 { id, kind, label }' },
+  relation: { type: 'string', enum: ['new_task', 'subtask_of'], description: '本轮是新任务还是已有任务的子任务' },
+  session_key: { type: 'string' },
+  turn_id: { type: 'string', description: '当前对话轮次 id；不传则由 Host 生成' },
+  task_id: { type: 'string', description: 'relation=subtask_of 时指向的已有业务任务 id；新任务不传' },
+  subtask_id: { type: 'string', description: '已有子任务 id；新子任务不传，由 Host 生成' },
+  parent_subtask_id: { type: 'string', description: '父任务节点 id；通常由 Host 生成' },
+  run_id: { type: 'string', description: '已有执行尝试 id；重试时传新值' },
+  trace_id: { type: 'string' },
+  domain: { type: 'string' },
+}
+
+/** 工具的最小注册面。测试替身与真实 `ctx` 都满足它。 */
+export interface ToolRegistryLike {
+  register(definition: unknown): unknown
+}
+
+export function jsonTool(name: string, description: string, parameters: Record<string, unknown>, execute: (args: any, exec?: ToolRunContext) => unknown) {
+  return defineTool({
+    name, description, parameters: parameters as any,
+    output: { schema: { type: 'json' }, render: (_args: unknown, value: unknown) => [{ type: 'text' as const, text: JSON.stringify(value) }] },
+    execute: async (args: any, exec: ToolRunContext) => execute(args, exec),
+  } as any)
+}
+
+export function lineageOf(args: Record<string, unknown>, exec?: ToolRunContext): Partial<LineageContext> | undefined {
+  const lineage: Partial<LineageContext> = {}
+  const sessionId = typeof args.session_key === 'string' && args.session_key.trim() ? args.session_key.trim() : exec?.agent?.session.header.id
+  if (sessionId) lineage.sessionId = sessionId
+  const fields: Array<[keyof LineageContext, string]> = [
+    ['turnId', 'turn_id'], ['taskId', 'task_id'], ['subtaskId', 'subtask_id'],
+    ['parentSubtaskId', 'parent_subtask_id'], ['runId', 'run_id'], ['traceId', 'trace_id'], ['domain', 'domain'],
+  ]
+  for (const [target, source] of fields) if (typeof args[source] === 'string' && args[source].trim()) lineage[target] = args[source].trim()
+  return Object.keys(lineage).length > 0 ? lineage : undefined
+}
+
+export function sessionKeyOf(args: Record<string, unknown>, exec?: ToolRunContext): string {
+  const explicit = typeof args.session_key === 'string' ? args.session_key.trim() : ''
+  return explicit || exec?.agent?.session.header.id || 'default'
+}
+
+/**
+ * 注册三个 `intent_*` 工具，返回一个把三者一起撤掉的 disposer。
+ *
+ * `intent_record` 的描述是**动态**的：分类 / act 词表可以在设置里改，而工具描述
+ * 是静态字符串。所以设置一变就 dispose 旧的、按新文本重新注册 —— 下一轮模型看到
+ * 的规则就是新的。这是「保存后下一轮生效」在工具这一侧的实现。
+ *
+ * 类型守卫（`typeof disposer === 'function'`）是因为测试替身的 `register` 不一定
+ * 返回 disposer。
+ */
+export function registerIntentTools(ctx: { tools: ToolRegistryLike }, host: IntentToolHost): () => void {
+  let disposeRecord: (() => void) | undefined
+  let registeredDescription = ''
+  const ensureRecordTool = (): void => {
+    const description = host.routingPrompt()
+    if (registeredDescription === description && disposeRecord) return
+    disposeRecord?.()
+    disposeRecord = undefined
+    registeredDescription = description
+    const disposer: unknown = ctx.tools.register(jsonTool('intent_record', description, INTENT_RECORD_PARAMS, (args, exec) => host.record(args, exec)))
+    if (typeof disposer === 'function') disposeRecord = disposer as () => void
+  }
+
+  ensureRecordTool()
+  const disposeView: unknown = ctx.tools.register(jsonTool(
+    'intent_store_view', 'View recent intent records and the active task ids for the current session.',
+    { session_key: { type: 'string' }, include_prompt: { type: 'boolean' } },
+    (args: { session_key?: string; include_prompt?: boolean }, exec) => host.view(sessionKeyOf(args, exec), args.include_prompt),
+  ))
+  const disposeRegistry: unknown = ctx.tools.register(jsonTool(
+    'intent_registry_list', 'List the configured intent acts, categories and predicates together with the routing prompt that ships as the intent_record tool description.',
+    {},
+    () => host.registry(),
+  ))
+
+  const unsubscribe = host.subscribe(ensureRecordTool)
+  return () => {
+    unsubscribe()
+    disposeRecord?.()
+    disposeRecord = undefined
+    if (typeof disposeView === 'function') (disposeView as () => void)()
+    if (typeof disposeRegistry === 'function') (disposeRegistry as () => void)()
+  }
+}

package/src/intent/types.ts

@@ -0,0 +1,245 @@
+import type { ToolStatus } from 'dsh-data-contracts/envelope'
+import type { LineageContext } from 'dsh-data-contracts/refs'
+
+export type { ToolStatus }
+
+/**
+ * 一个动作类型（act）。
+ *
+ * act 回答"这一轮用户在**做什么**"，与 category（做什么**业务**）正交：同一句
+ * "帮我看下上个月的 GMV" 是 `query` × `data_analysis`。光有 id 时模型只能猜
+ * `query` 和 `request` 的区别，所以每一类都带 label 与 description。
+ */
+export interface IntentActDef {
+  id: string
+  label: string
+  description: string
+  enabled: boolean
+}
+
+/**
+ * 出厂 act 词表。16 个动作覆盖"提问 / 让做 / 补充 / 反馈 / 终止 / 闲聊"六种交互。
+ *
+ * 记录仍是自由文本（模型可以写没配置过的 act，只给 warning），这份词表是**先验**：
+ * 它进 routing prompt，也进设置页与 `intent_registry_list`。
+ */
+export const DEFAULT_ACTS: IntentActDef[] = [
+  { id: 'query', label: '查询', description: '向数据或知识提问，要一个答案或一批结果。', enabled: true },
+  { id: 'request', label: '执行请求', description: '让 Agent 做一件事并产生副作用：写入、发送、导出、修改。', enabled: true },
+  { id: 'inform', label: '补充信息', description: '用户提供事实、参数或上下文，本身不要求动作。', enabled: true },
+  { id: 'confirm', label: '确认', description: '用户认可某个提议或方案，允许继续。', enabled: true },
+  { id: 'select', label: '选择', description: '在多个候选中指定一个。', enabled: true },
+  { id: 'correct', label: '纠正', description: '指出前面的理解或结果不对，要求改。', enabled: true },
+  { id: 'cancel', label: '取消', description: '终止或撤回正在进行的任务。', enabled: true },
+  { id: 'review', label: '审阅', description: '对已产出的内容做检查、评估与把关。', enabled: true },
+  { id: 'explain', label: '解释', description: '要求讲清原理、口径或原因，而不是要新数据。', enabled: true },
+  { id: 'compare', label: '对比', description: '把两个及以上对象放在一起比较差异。', enabled: true },
+  { id: 'recommend', label: '推荐', description: '要建议与取舍意见。', enabled: true },
+  { id: 'resume', label: '继续', description: '回到之前中断的任务继续做。', enabled: true },
+  { id: 'reject', label: '拒绝', description: '不接受某个提议或结果。', enabled: true },
+  { id: 'greet', label: '问候', description: '打招呼、开场。', enabled: true },
+  { id: 'chat', label: '闲聊', description: '非任务性的对话。', enabled: true },
+  { id: 'unknown', label: '未判定', description: '无法归入以上任何一类，或本轮信息不足以判断。', enabled: true },
+]
+
+/** Free-form act id; configured in `IntentSettings.acts`. */
+export type IntentAct = string
+
+/** How one turn relates to the session's existing tasks. */
+export type IntentRelation = 'new_task' | 'subtask_of' | 'unknown'
+
+/** `model` is a model-authored record; `fallback` is the Host's turn-end backfill. */
+export type IntentSource = 'model' | 'fallback'
+
+export interface IntentSlotMap {
+  [name: string]: unknown
+}
+
+export interface IntentRef {
+  id: string
+  kind?: string
+  label?: string
+}
+
+/**
+ * One configurable intent category; `route` names the act it usually maps to.
+ *
+ * 预置分类的作用是**把模型的自由判断收窄成一次匹配**：
+ * {@link description} 说明这一类"是什么"，{@link examples} 给出用户可能怎么说。
+ * 两者都会被拼进 routing prompt，模型先按它们匹配，命中就直接用该 id。
+ */
+export interface IntentCategory {
+  id: string
+  label: string
+  route: string
+  description: string
+  /**
+   * 预置说法（few-shot）：用户可能怎么表达这一类意图，每行一条。
+   *
+   * 可选——0012 时代的持久化配置没有这个字段，缺省按空数组处理，注册表 schema
+   * 也会补默认值。
+   */
+  examples?: string[]
+  enabled: boolean
+}
+
+/**
+ * Recorder settings. The classification vocabulary is user-editable: nothing
+ * here constrains what a model may record, it only describes the options the
+ * routing prompt offers and what `intent_registry_list` reports.
+ */
+export interface IntentSettings {
+  /** Below this confidence a record is annotated lowConfidence; the model decides whether to clarify. */
+  clarifyThreshold: number
+  ttlSeconds: number
+  /**
+   * 0023：路由提示词**没有开关**。它随 `intent_record` 的工具描述一起下发，
+   * 分类规则必须始终在场——否则模型退化成每轮从零判断。
+   */
+  /** Backfill one `unknown` record when a turn ends without a model record. */
+  fallbackEnabled: boolean
+  categories: IntentCategory[]
+  acts: IntentActDef[]
+  predicates: string[]
+}
+
+function category(id: string, label: string, route: string, description: string, examples: string[]): IntentCategory & { examples: string[] } {
+  return { id, label, route, description, examples, enabled: true }
+}
+
+/**
+ * 出厂预置的意图分类。
+ *
+ * 每一项都**必须**带 `description` 与 `examples`：只给标签（"数据分析"）时模型
+ * 只能靠猜，同一句话在不同轮次会被分到不同类。这些文案是模型的匹配依据，全部
+ * 可以在「意图」页里改。
+ */
+export const DEFAULT_CATEGORIES: Array<IntentCategory & { examples: string[] }> = [
+  category('data_analysis', '数据分析', 'query', '取数、算指标、拆口径的请求：给一个数或一段分析结论。', ['帮我算一下上个月的 GMV', '这个指标怎么拆', '跑个数看看环比']),
+  category('metadata_exploration', '元数据探索', 'query', '问"有哪些表/字段/口径"本身，要的是结构而不是数字。', ['这张表有哪些字段', '库里有几张订单表', '这些指标的口径是怎么定义的']),
+  category('data_validation', '数据校验', 'query', '核对数据是否可信：对不上、空值、重复、异常波动。', ['这两个数对不上，查一下', '帮我看下这列有没有重复', '空值率是不是偏高了']),
+  category('knowledge_consultation', '知识咨询', 'query', '问组织既有的结论、规则、流程或负责人，答案在知识库里。', ['我们去年是怎么定这个口径的', '知识库里有没有相关文档', '这个流程找谁确认']),
+  category('knowledge_building', '知识构建', 'request', '把材料沉淀进知识库：录入来源、写卡片、重建索引。', ['把这份文档存进知识库', '记一条：这个口径改成…', '帮我整理成一张知识卡片']),
+  category('document_research', '文档研究', 'query', '对一份或多份长文档做通读、归纳、对比、找证据。', ['把这份 PRD 读一遍，总结需求点', '这几篇文档有没有冲突', '从报告里找出支持这个结论的证据']),
+  category('message_collaboration', '消息协作', 'request', '替用户发消息、同步进度、在群里通知或拉人。', ['发条消息给张三', '在群里同步一下进度', '@一下负责人催确认']),
+  category('artifact_delivery', '产物交付', 'request', '要一个可交付的文件：表格、报告、周报、导出件。', ['导出一份 Excel', '生成这周的周报', '把结果做成表格发我']),
+  category('agent_engineering', 'Agent 工程', 'request', '改 Agent 自身：加工具、调提示词、改 skill、查它为什么这么答。', ['加一个工具', '这个 skill 怎么改', '它刚才为什么没调那个工具']),
+  category('tooling_operations', '工具运维', 'request', '运维动作：重启、看队列、清缓存、处理环境报错。', ['重启一下服务', '看看任务队列', '这个报错怎么修']),
+  category('personal_assistant', '个人助理', 'request', '个人日程与提醒类事务。', ['明天提醒我开会', '帮我约个会', '看下我今天的日程']),
+  category('conversation', '普通对话', 'chat', '寒暄、闲聊、对 Agent 本身的提问，没有数据或交付目标。', ['你好', '你是谁', '谢谢，先这样']),
+]
+
+export const DEFAULT_PREDICATES: string[] = [
+  'query_babel_data', 'query_knowledge', 'query_source_truth', 'query_metadata',
+  'query_graph', 'add_source', 'write_knowledge_card', 'rebuild_knowledge',
+  'send_message', 'export_artifact', 'unknown',
+]
+
+export const DEFAULT_INTENT_SETTINGS: IntentSettings = {
+  clarifyThreshold: 0.65,
+  ttlSeconds: 600,
+  fallbackEnabled: true,
+  categories: DEFAULT_CATEGORIES,
+  acts: DEFAULT_ACTS,
+  predicates: DEFAULT_PREDICATES,
+}
+
+/** One recorded intent. The record is an audit fact; it never drives control flow. */
+export interface IntentRecord {
+  id: string
+  sessionKey: string
+  /** `sessionKey#turn` — the upsert key that keeps one record per turn. */
+  turnKey: string
+  turnId: string
+  userInput: string
+  act: IntentAct
+  category?: string
+  predicate?: string
+  slots: IntentSlotMap
+  confidence?: number
+  lowConfidence?: boolean
+  refs: IntentRef[]
+  relation: IntentRelation
+  source: IntentSource
+  createdAt: string
+  updatedAt: string
+  lineage: LineageContext
+  meta: Record<string, unknown>
+}
+
+export interface IntentRecordInput {
+  userInput: string
+  act?: string
+  category?: string
+  predicate?: string
+  slots?: IntentSlotMap
+  confidence?: number
+  refs?: IntentRef[]
+  relation?: IntentRelation
+  sessionKey: string
+  turnId?: string
+  lineage?: Partial<LineageContext>
+  now?: number
+}
+
+/** Compact task context returned to the model so it can pick the next relation. */
+export interface IntentTaskSummary {
+  taskId: string
+  lastSubtaskId?: string
+  category?: string
+  ageSeconds: number
+}
+
+export interface IntentRegistry {
+  /** 可编辑的 act 词表（带 label / description），面板就地增删改。 */
+  acts: IntentActDef[]
+  /**
+   * 可用的意图分类。带 `description` / `examples`，因为「意图」页要就地编辑它们，
+   * 而不是只渲染成一组只读徽标。
+   */
+  categories: Array<{ id: string; label: string; route: string; description: string; examples: string[]; enabled: boolean }>
+  predicates: string[]
+}
+
+export interface IntentStoreView {
+  sessionKey: string
+  activeTaskId?: string
+  activeIntentId?: string
+  tasks: IntentTaskSummary[]
+  recent: IntentRecord[]
+  expiresAt?: string
+}
+
+export interface IntentResultData {
+  intentId?: string
+  taskId?: string
+  subtaskId?: string
+  parentSubtaskId?: string
+  runId?: string
+  turnId?: string
+  act?: string
+  category?: string
+  relation?: IntentRelation
+  source?: IntentSource
+  lowConfidence?: boolean
+  activeTasks?: IntentTaskSummary[]
+  store?: IntentStoreView
+  registry?: IntentRegistry
+  prompt?: string
+}
+
+export interface IntentResult {
+  ok: boolean
+  status: ToolStatus
+  data: IntentResultData
+  warnings: string[]
+}
+
+/** Live turn state: the provisional ids allocated before the model records. */
+export interface IntentTurnState {
+  turn: number
+  userInput: string
+  subtaskId: string
+  taskId?: string
+  committed: boolean
+}