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

package/src/intent/host.ts

@@ -0,0 +1,462 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-settings'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { envelopeSuccess } from 'dsh-data-contracts/envelope'
+import type { LineageContext } from 'dsh-data-contracts/refs'
+import { DEFAULT_ACTS, DEFAULT_CATEGORIES, DEFAULT_INTENT_SETTINGS, DEFAULT_PREDICATES, type IntentActDef, type IntentSettings } from './types.js'
+import { IntentEngine } from './engine.js'
+import { appendIntentRecord, INTENT_REGISTRY_FILE, readIntentRecords, readIntentRegistry, writeIntentRegistry, type IntentRegistryFile } from './store.js'
+import type { IntentToolHost } from './tools.js'
+import { lineageOf, sessionKeyOf } from './tools.js'
+
+export * from './types.js'
+export * from './engine.js'
+export * from './tools.js'
+
+export const SETTINGS_NAMESPACE = 'tita-data-agent-intent'
+/** Read-only HTTP surface the 意图 panel reads: `/intent/overview`, `/intent/store`, `/intent/registry`. */
+export const INTENT_MOUNT_PATH = '/intent'
+/** Cordis service name consumers read to inherit the session's active task ids. */
+export const INTENT_SERVICE = 'titaDataAgentIntent'
+
+/**
+ * 意图引擎的对外操作面。
+ *
+ * 两类消费者，一个服务：
+ * - `activeLineage` —— 其它插件（`data-table`）读本轮活动血缘。
+ * - 其余成员 —— agent 平面的挂载行（`./preset-tools.ts`）按它注册 `intent_*` 工具。
+ *
+ * 0029 之前这三个工具由本模块直接全局注册；现在注册搬到了 agent 平面，这里只留
+ * 「引擎能做什么」。引擎只有一份，工具定义也只有一份（`./tools.ts`）。
+ */
+export interface IntentService extends IntentToolHost {
+  /**
+   * Ids a downstream tool call in `sessionKey` should carry. `committed` is
+   * false while the current turn has not recorded yet, so callers can tell a
+   * provisional subtask id from an authoritative record.
+   * @param sessionKey - session whose lineage is requested.
+   * @returns lineage plus whether a record already committed it, or undefined when nothing is known.
+   */
+  activeLineage(sessionKey: string): { lineage: Partial<LineageContext>; committed: boolean } | undefined
+}
+
+/** @deprecated 0029：改用 `IntentService`。保留别名只为不动既有 import。 */
+export type IntentLineageService = IntentService
+
+// 三个 schema 搬到了 `./settings-schema.js`（纯数据、可在 node --test 里独立解析）。
+// `CATEGORY_SCHEMA` / `ACT_SCHEMA` 在下面的注册表写入校验里还要用，所以先 import
+// 再 re-export —— 单独一条 `export … from` 不会把它们带进本文件的作用域。
+import { ACT_SCHEMA, CATEGORY_SCHEMA } from './settings-schema.js'
+export { ACT_SCHEMA, CATEGORY_SCHEMA, INTENT_SETTINGS_SCHEMA } from './settings-schema.js'
+
+/** Concatenate the text of one user message, whichever content form it carries. */
+function userText(message: unknown): string {
+  const content = (message as { content?: unknown } | undefined)?.content
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map(block => typeof block === 'string' ? block : (block as { text?: unknown } | undefined)?.text)
+    .filter((text): text is string => typeof text === 'string')
+    .join('\n')
+}
+
+/**
+ * 意图记录模块（原 `@tita-data-agent/data-domain-intent`，0020 并入本插件）。
+ *
+ * 它是 `KnowledgePanel` 五个视图之一「意图」的宿主实现。0029 起它**只负责引擎**：
+ * 设置、轮次记账、`/intent/**` 只读面，以及通过 `INTENT_SERVICE` 暴露操作面。
+ *
+ * 三个 `intent_*` 工具**不再在这里注册** —— 它们搬到了 agent 平面的
+ * `./preset-tools.ts`，只被自定义 preset 的 `agent.cordis.yml` 挂载，于是只有跑
+ * TitaAgent 那套组合的会话才看得到它们。理由见那个文件的模块注释。
+ *
+ * 本模块由 `src/index.ts` 组合根调用，不自己导出 `name` / `inject`。
+ * @module dsh-data-domain-knowledge/intent
+ */
+/**
+ * 组合根交给意图模块的东西。
+ *
+ * `intentRoot` 是**函数**而不是字符串：根路径由设置决定，可以在运行时改，而
+ * 模块加载时还不知道。每次读写都重新问一次，于是「改了根路径」立刻生效，
+ * 不存在「配置说 A、实际写 B」。
+ */
+export interface IntentHostDeps {
+  /** `<agentRoot>/intent`。省略时退回内存态（只测引擎的单元测试用这个形态）。 */
+  intentRoot?: () => string
+  /**
+   * 已解析的 `intent` 设置组（来自插件 entry 的 config）。
+   *
+   * 0.1.7 起设置不再是命名空间 —— 它随 `apply(ctx, config)` 进来。省略时用
+   * `DEFAULT_INTENT_SETTINGS`，这样只测引擎的装配方式仍然能跑。
+   *
+   * 允许给**函数**：设置字段全是 volatile，schema 解析出来是引用，而「解包成普通值」
+   * 是一次快照 —— 快照会漏掉「用户在设置页改了值」（loader 只就地改引用、不重载插件）。
+   * 给函数则每次读都重新解包，`reprocess()` 才真的拿得到新值。
+   */
+  config?: Partial<IntentSettings> | (() => Partial<IntentSettings>)
+}
+
+/**
+ * `applyIntent` 交给组合根的那一个把手。
+ *
+ * volatile 改动不会重载插件（`Entry._commitVolatile()` 只就地改引用再发一个
+ * `loader/volatile-update`），所以「设置存下了但没生效」只能由插件自己兜住 ——
+ * 见 `settings-volatile.ts` 末尾那段。重灌设置之后还要 `notify()`：agent 平面的行
+ * 挂在那个订阅上，而 `intent_record` 的**工具描述就是路由提示词**，词表一变描述就
+ * 必须变。
+ */
+export interface IntentHost {
+  /** 按**当前**的 entry config 重灌一次引擎设置，并通知订阅者。 */
+  reprocess(): void
+}
+
+export function applyIntent(ctx: Context, deps: IntentHostDeps = {}): IntentHost {
+  const engine = new IntentEngine(DEFAULT_INTENT_SETTINGS)
+  const root = (): string | undefined => deps.intentRoot?.()
+  /**
+   * 注册表的**真源**（0033）。
+   *
+   * `undefined` = 文件还不存在（首启）。这时按 settings 里解析出来的值启动，
+   * 并在第一次读到时把它**播种**成文件 —— 这样老用户已经改过的分类不会因为
+   * 「真源搬家」而悄悄回到出厂预置。
+   */
+  let fileRegistry: IntentRegistryFile | undefined
+  /**
+   * 每个知识库…不，意图不分库（见 `layout.ts` 原理 6），所以这里只有一个根。
+   * 但**记录是会话级的**，读的时候要按 sessionKey 过滤。
+   */
+  /**
+   * 读注册表；文件不存在时**按设置里解析出来的值播种**。
+   *
+   * 播种的输入必须是 `seedFrom`（刚解析出来的设置），**不能**读 `engine.registry()`
+   * —— 那一刻引擎里还是出厂预置（`apply()` 还没跑），于是「老用户在 settings 里改过
+   * 的分类」会在真源搬家的瞬间被悄悄换回出厂值。这条路径只在文件不存在时走一次，
+   * 而它承载的正是「搬家不丢用户的编辑」。
+   */
+  const loadRegistry = (seedFrom: IntentSettings): void => {
+    const base = root()
+    if (!base) return
+    const fromFile = readIntentRegistry(base)
+    if (fromFile) { fileRegistry = fromFile; return }
+    // **同步**，因为它在设置解析的回调里 —— 见 store.ts 的 writeAtomicSync 注释。
+    try {
+      fileRegistry = writeIntentRegistry(base, {
+        acts: seedFrom.acts,
+        // `examples` 在 settings 那侧是可选的（0012 时代的配置没有这个字段），
+        // 落成文件时补成空数组 —— 文件是要被人读的，缺字段比空数组更难懂。
+        categories: seedFrom.categories.map(category => ({
+          id: category.id,
+          label: category.label,
+          route: category.route,
+          description: category.description ?? '',
+          examples: [...(category.examples ?? [])],
+          enabled: category.enabled,
+        })),
+      })
+    } catch { /* 目录不可写：按出厂预置跑，不留痕也不该让插件起不来 */ }
+  }
+  /** 把「文件（若有）+ settings 里的标量」合成一份引擎设置。 */
+  const merged = (settings: IntentSettings): IntentSettings => fileRegistry
+    ? { ...settings, acts: fileRegistry.acts, categories: fileRegistry.categories }
+    : settings
+  /**
+   * 引擎变化（设置改了、词表改了）的订阅者。
+   *
+   * 唯一消费者是 agent 平面的注册行：`intent_record` 的**工具描述就是路由提示词**
+   * （0023），而工具描述是静态字符串 —— 词表一变必须重新注册那个工具，下一轮模型
+   * 看到的规则才是新的。宿主平面只负责**通知**，重挂由知道工具在哪的那个平面做。
+   */
+  const listeners = new Set<() => void>()
+  const notify = (): void => { for (const listener of [...listeners]) { try { listener() } catch { /* 一个坏订阅者不该打断设置生效 */ } } }
+  /**
+   * 当前生效的设置来源。
+   *
+   * 放在 `applyIntent` 作用域而不是 settings 回调里：注册表的写路径（`/intent/registry`
+   * 的 POST）也要用它把新词表灌回引擎，而那条路径在 webServer 回调里。
+   */
+  /**
+   * 设置来源。0.1.7 起**设置就是插件自己 entry 的 config**（`apply(ctx, config)`
+   * 的第二个参数），`settings.installSection` 那套命名空间注册已经整个删除了。
+   *
+   * 组合层会把 schema 默认值合进来；这里再 `merged()` 一次是为了兼容直接调用
+   * `applyIntent` 的装配方式（那时可能只给一个片段，甚至什么都不给）。
+   */
+  /**
+   * 读取当前设置组。
+   *
+   * 组合根给的是**函数**时（真实装配方式，见 `IntentHostDeps.config`）每次都重新解包，
+   * 于是「改设置 → `reprocess()`」这条路拿到的是新值；给普通对象时（单元测试、直接
+   * 调用）原样用。
+   */
+  const readConfig = (): Partial<IntentSettings> =>
+    (typeof deps.config === 'function' ? deps.config() : deps.config) ?? {}
+  /**
+   * 生效的设置 = 出厂默认 ← entry config ← 文件真源（`merged`）。
+   *
+   * 铺一层 `DEFAULT_INTENT_SETTINGS` 是为了让「直接调用 `applyIntent` 且只给一个
+   * 片段」也成立：缺的字段落下就是 `undefined`，而 `{...settings, ...next}` 的合并
+   * 会让 `undefined` **覆盖**掉引擎里已有的默认值。
+   */
+  const source = (): IntentSettings => merged({ ...DEFAULT_INTENT_SETTINGS, ...readConfig() })
+
+  /**
+   * 初始灌入：先按**文件真源**读一次注册表，再把结果灌进引擎，最后通知订阅者。
+   *
+   * 旧实现把这条路径拆成两个回调（`setSource` 在 install 时 `loadRegistry` + `apply`，
+   * `onChange` 只 `apply`）。新模型下改设置会让插件**整个重载**，所以只需在 apply
+   * 时跑一次 install 那条路径 —— 顺序也保持不变，否则「先 apply 后 loadRegistry」
+   * 会让第一轮工具描述用出厂词表。
+   */
+  loadRegistry(source())
+  engine.setSettings(merged(source() as IntentSettings))
+  notify()
+
+  /**
+   * 留痕出口（0033）：每条记录追加进 `intent/records.ndjson`。
+   *
+   * 装的是**同步**闭包，内部 fire-and-forget 一个 Promise：`save()` 在记录路径上，
+   * 让它 await 磁盘等于把「记录不拦截请求」这条契约交给磁盘可用性。写失败由
+   * `appendIntentRecord` 自己吞掉 —— 丢一条留痕比让这一轮回答失败轻得多。
+   */
+  if (deps.intentRoot) {
+    engine.store.setSink(record => { void appendIntentRecord(root() as string, record) })
+    /**
+     * 把留痕读回工作集。放在这里而不是 `apply()` 里：`apply` 每次改设置都会跑，
+     * 而 hydrate 只该在启动时发生一次（重复 hydrate 只是重复覆盖同样的记录，
+     * 但没必要每次都读一遍磁盘）。
+     */
+    void readIntentRecords(root() as string).then(records => {
+      const loaded = engine.store.hydrate(records)
+      if (loaded > 0) notify()
+    })
+  }
+
+  ctx.provide(INTENT_SERVICE, {
+    activeLineage: (sessionKey: string) => engine.activeLineage(sessionKey),
+    routingPrompt: () => engine.routingPrompt(),
+    /**
+     * `intent_record` 的参数落进引擎。放在这里而不是工具定义里：工具定义要与平面
+     * 无关（`./tools.ts`），而「参数怎么变成一条记录」是引擎的事。
+     */
+    record: (args, exec) => {
+      const lineage = lineageOf(args, exec)
+      return engine.record({
+        userInput: typeof args.user_input === 'string' ? args.user_input : '',
+        ...(typeof args.act === 'string' ? { act: args.act } : {}),
+        ...(typeof args.category === 'string' ? { category: args.category } : {}),
+        ...(typeof args.predicate === 'string' ? { predicate: args.predicate } : {}),
+        ...(args.slots !== undefined ? { slots: args.slots as Record<string, unknown> } : {}),
+        ...(typeof args.confidence === 'number' ? { confidence: args.confidence } : {}),
+        ...(Array.isArray(args.refs) ? { refs: args.refs as Array<{ id: string }> } : {}),
+        ...(args.relation === 'new_task' || args.relation === 'subtask_of' ? { relation: args.relation } : {}),
+        sessionKey: sessionKeyOf(args, exec),
+        ...(lineage ? { lineage } : {}),
+      })
+    },
+    view: (sessionKey, includePrompt) => engine.view(sessionKey, includePrompt),
+    registry: () => envelopeSuccess({ registry: engine.registry(), prompt: engine.routingPrompt() }),
+    subscribe: (listener: () => void) => { listeners.add(listener); return () => { listeners.delete(listener) } },
+  } satisfies IntentService)
+
+  // 0023：路由提示词不再单独注入 system prompt 段，它现在是 `intent_record` 的工具
+  // 描述（见 `./tools.ts` 的 `registerIntentTools`）。两处都放会重复占用上下文，
+  // 而且会漂移。
+
+  // Turn bookkeeping: allocate provisional ids per turn and backfill one record
+  // if the turn ends without one (issue 0012 decision B).
+  const pendingInput = new Map<string, string>()
+  ctx.on('session/event', (session, event) => {
+    const sessionKey = session.header.id as unknown as string
+    if (event.type === 'user/message') {
+      pendingInput.set(sessionKey, userText(event.data))
+      return
+    }
+    if (event.type === 'turn/start') {
+      engine.beginTurn(sessionKey, event.data.turn, pendingInput.get(sessionKey) ?? '')
+      return
+    }
+    if (event.type === 'turn/end') {
+      engine.fallbackWhenMissing(sessionKey, event.data.turn)
+      pendingInput.delete(sessionKey)
+    }
+  })
+
+  // Read-only HTTP surface for the 意图 panel. The intent store is in-memory and
+  // session-scoped, so the panel reads it over HTTP instead of duplicating the
+  // engine in the browser.
+  ctx.inject(['webServer'], webCtx => {
+    const web = webCtx as unknown as {
+      webServer: {
+        register(route: { kind: 'exact' | 'prefix'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> | void }): () => unknown
+      }
+    }
+    const send = (res: ServerResponse, status: number, body: unknown): void => {
+      res.statusCode = status
+      res.setHeader('content-type', 'application/json; charset=utf-8')
+      res.setHeader('cache-control', 'no-store')
+      res.end(JSON.stringify(body))
+    }
+    const readJsonBody = async (req: IncomingMessage): Promise<Record<string, unknown>> => {
+      const chunks: Buffer[] = []
+      for await (const chunk of req) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)))
+      if (!chunks.length) return {}
+      const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new Error('请求体必须是一个 JSON 对象')
+      return parsed as Record<string, unknown>
+    }
+    /** 文件里的词表与出厂预置是否不同 —— 面板据此显示「已自定义」并放开「恢复出厂」。 */
+    const customized = (): { categories: boolean; acts: boolean } => {
+      const same = (left: unknown, right: unknown): boolean => JSON.stringify(left) === JSON.stringify(right)
+      return {
+        categories: !same(fileRegistry?.categories ?? DEFAULT_CATEGORIES, DEFAULT_CATEGORIES),
+        acts: !same(fileRegistry?.acts ?? DEFAULT_ACTS, DEFAULT_ACTS),
+      }
+    }
+    /** 写一份新词表：落盘 → 灌回引擎 → 通知重挂工具描述。 */
+    const saveRegistry = (next: { acts?: IntentRegistryFile['acts']; categories?: IntentRegistryFile['categories'] }): void => {
+      const base = root()
+      if (!base) throw new Error('意图目录尚未就绪（agentRoot 还没解析出来）')
+      const current = engine.registry()
+      fileRegistry = writeIntentRegistry(base, {
+        acts: next.acts ?? fileRegistry?.acts ?? current.acts,
+        categories: next.categories ?? fileRegistry?.categories ?? current.categories,
+      })
+      // 词表变了 = 工具描述变了 = 下一轮模型看到的规则要变。
+      engine.setSettings(merged(source()) as Partial<IntentSettings>)
+      notify()
+    }
+    const routes = [
+      {
+        kind: 'exact' as const,
+        path: `${INTENT_MOUNT_PATH}/overview`,
+        handler: async (_req: IncomingMessage, res: ServerResponse) => {
+          const overview = engine.overview()
+          const base = root()
+          if (base) {
+            /**
+             * 用**留痕**补齐工作集里已经没有的会话（0033）。
+             *
+             * 工作集有 600 秒 TTL，所以重启或隔一段时间回来，面板上的会话列表会
+             * 空掉 —— 而磁盘上明明留着。这里把文件里出现过、工作集里没有的会话补上，
+             * 数字与最后一条分类都从留痕读。工作集里已有的不覆盖：那一条带着活的
+             * `tasks`（血缘），比从文件重算的更准。
+             */
+            const all = await readIntentRecords(base, undefined, 500)
+            const seen = new Set(overview.sessions.map(session => String(session.sessionKey)))
+            const bySession = new Map<string, typeof all>()
+            for (const record of all) {
+              const list = bySession.get(record.sessionKey) ?? []
+              list.push(record)
+              bySession.set(record.sessionKey, list)
+            }
+            for (const [sessionKey, records] of bySession) {
+              if (seen.has(sessionKey)) continue
+              const last = records[records.length - 1]
+              if (!last) continue
+              overview.sessions.push({
+                sessionKey,
+                recordCount: records.length,
+                lastAt: last.updatedAt ?? last.createdAt,
+                activeIntentId: last.id,
+                lastAct: last.act,
+                ...(last.category ? { lastCategory: last.category } : {}),
+                lastRelation: last.relation,
+                ...(last.lineage.taskId ? { activeTaskId: last.lineage.taskId } : {}),
+                ...(last.confidence !== undefined ? { lastConfidence: last.confidence } : {}),
+                durable: true,
+              })
+            }
+            overview.sessions.sort((left, right) => String(right.lastAt ?? '').localeCompare(String(left.lastAt ?? '')))
+          }
+          send(res, 200, envelopeSuccess(overview))
+        },
+      },
+      {
+        kind: 'exact' as const,
+        path: `${INTENT_MOUNT_PATH}/store`,
+        handler: async (req: IncomingMessage, res: ServerResponse) => {
+          const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+          const sessionKey = url.searchParams.get('session_key')?.trim() || 'default'
+          const includePrompt = url.searchParams.get('include_prompt') === 'true'
+          const view = engine.view(sessionKey, includePrompt)
+          const base = root()
+          if (base) {
+            /**
+             * `recent` 读**留痕**而不是工作集（0033）。
+             *
+             * 工作集有 TTL：600 秒之后同一个会话的 `records()` 就是空数组，面板上
+             * 「意图记录」会莫名其妙变空，而文件里明明一条不少。`tasks` /
+             * `activeTaskId` 仍来自工作集 —— 那是**活的血缘**，不是历史。
+             */
+            const durable = await readIntentRecords(base, sessionKey, 50)
+            const store = (view.data as { store?: { recent?: unknown[] } }).store
+            if (store) store.recent = durable.slice(-10).reverse()
+          }
+          send(res, 200, view)
+        },
+      },
+      {
+        kind: 'exact' as const,
+        path: `${INTENT_MOUNT_PATH}/registry`,
+        handler: async (req: IncomingMessage, res: ServerResponse) => {
+          /**
+           * 注册表**可写**（0033）：真源是 `intent/registry.json`，不再是宿主的
+           * settings 文档。写在这里而不是走设置作用域，是因为设置作用域改的是
+           * 「宿主的配置」，而分类词表是这个 Agent 自己的文件 —— 它要能跟着
+           * `agentRoot` 一起被备份、被 diff。
+           */
+          if (req.method === 'POST') {
+            try {
+              const body = await readJsonBody(req)
+              const reset = typeof body.reset === 'string' ? body.reset : undefined
+              if (reset) {
+                saveRegistry({
+                  ...(reset === 'acts' || reset === 'all' ? { acts: DEFAULT_ACTS } : {}),
+                  ...(reset === 'categories' || reset === 'all' ? { categories: DEFAULT_CATEGORIES } : {}),
+                })
+              } else {
+                // 请求体是 `unknown`，schema 的入参类型是「已解析过的形状」；这里的窄化
+                // 正是校验本身要做的事 —— 校验不过会抛，抛了就走下面的 400。
+                const acts = body.acts === undefined ? undefined : z.array(ACT_SCHEMA)(body.acts as never) as IntentActDef[]
+                const categories = body.categories === undefined ? undefined : z.array(CATEGORY_SCHEMA)(body.categories as never) as IntentRegistryFile['categories']
+                if (!acts && !categories) throw new Error('请求体里既没有 categories 也没有 acts')
+                saveRegistry({
+                  ...(acts ? { acts } : {}),
+                  ...(categories ? { categories } : {}),
+                })
+              }
+            } catch (cause) {
+              const message = cause instanceof Error ? cause.message : String(cause)
+              return send(res, 400, envelopeSuccess({
+                registry: engine.registry(),
+                prompt: engine.routingPrompt(),
+                customized: customized(),
+                source: fileRegistry ? 'file' : 'factory',
+                error: message,
+              }))
+            }
+          }
+          send(res, 200, envelopeSuccess({
+            registry: engine.registry(),
+            prompt: engine.routingPrompt(),
+            customized: customized(),
+            source: fileRegistry ? 'file' : 'factory',
+            ...(root() ? { path: `${root() as string}/${INTENT_REGISTRY_FILE}` } : {}),
+          }))
+        },
+      },
+    ]
+    const disposers = routes.map(route => web.webServer.register(route))
+    return () => { for (const dispose of disposers) void dispose() }
+  })
+
+  return {
+    reprocess: () => {
+      engine.setSettings(merged(source()))
+      notify()
+    },
+  }
+}

package/src/intent/preset-tools.ts

@@ -0,0 +1,48 @@
+/**
+ * `intent_*` 工具的 **agent 平面**挂载行（0029）。
+ *
+ * ## 为什么这三个工具要单独一个挂载行
+ *
+ * 意图记录是这个方案自己的东西：只有跑 TitaAgent 那套组合的会话才该在提示词里看到
+ * `intent_record`。而 DSH 里「只有某个 preset 能用」唯一支持的形态就是**注册作用域** ——
+ * 注册在哪个作用域，就只在哪个作用域可见。宿主平面注册 = 全局工具，每个 agent 都会
+ * 看到它；`ctx.tools.restrict()` 只能做减法、且宿主平面调它会直接抛，没有「只给某一个
+ * 作用域」的正向开关。
+ *
+ * 所以这三个工具的注册搬到这里：这个模块**只被自定义 preset 的 `agent.cordis.yml`
+ * 挂载**，它 `apply` 时拿到的 ctx 是那个 preset 的 standing mount 作用域，于是注册出来
+ * 的工具只覆盖加入该 preset 的会话。别的 preset、临时会话都看不到它们 —— 而「看不到」
+ * 与「调不了」在 `dsh-tools` 里是同一件事（不可见的工具会以 `UNKNOWN_TOOL` 拒掉）。
+ *
+ * ## 两条约束
+ *
+ * 1. **它不 provide 任何服务。** preset 的挂载审计拒绝在根 realm 发布服务；这个行只往
+ *    `tools` 注册表里塞定义，和随包的 `tool-fs` / `tool-bash` 是同一类行。
+ * 2. **它不自己造引擎。** 引擎（设置、轮次记账、HTTP 只读面）住在宿主平面，通过
+ *    `INTENT_SERVICE` 暴露操作面；这一行只按那个面注册工具。引擎因此只有一份。
+ *
+ * @module
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { INTENT_SERVICE, type IntentService } from './host.js'
+import { registerIntentTools } from './tools.js'
+
+/** 与 `package.json` 的 `exports["./intent-tools"]` 对应。 */
+export const name = 'dsh-data-domain-knowledge/intent-tools'
+
+/**
+ * `tools` 是注册目标；`INTENT_SERVICE` 是引擎操作面。
+ *
+ * 把服务写进 `inject` 而不是在 `apply` 里判空：宿主平面还没就绪时这一行应该**等**，
+ * 而不是挂上一个没有引擎可用的空壳 —— 后者会让模型看到一个必然报错的工具。
+ */
+export const inject = ['tools', INTENT_SERVICE] as const
+
+export function apply(ctx: Context): void {
+  const service = ctx.get(INTENT_SERVICE) as IntentService | undefined
+  if (!service) return
+  // `effect` 把 disposer 绑到这个 fiber 上：卸载时三个工具一起撤掉，不留下悬空的
+  // 注册。preset 换掉或进程退出都走这条路径。
+  ctx.effect(() => registerIntentTools(ctx as unknown as { tools: { register(definition: unknown): unknown } }, service), 'tita intent tools')
+}

package/src/intent/settings-schema.ts

@@ -0,0 +1,63 @@
+/**
+ * 意图设置的 schema（纯数据，单独一个模块）。
+ *
+ * ## 为什么从 `host.ts` 搬出来
+ *
+ * 0.1.7 之后设置是一个 entry 的 **config schema**，而 `Config` 要在
+ * `tests/settings-schema.test.mjs` 里能被**独立解析一遍** —— 那正是一个「写错一个
+ * 默认值、整个 entry 装载失败」的东西该有的守卫。但 `host.ts` 会 `import` 工具层
+ * （`@deepseek-ai/dsh-tools`），它在 `node --test` 里拉不起来：`dsh-tools` 的
+ * `@deepseek-ai/dsh-sandbox` 是 peer，而本仓库 `autoInstallPeers: false`。
+ *
+ * 于是「schema 住在哪个文件」不是风格问题，而是**这个测试能不能跑**的问题。
+ * 与 `src/settings-schema.ts` 同一个理由（那边的文件头写着同一件事）。
+ *
+ * @module
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { volatileFields } from '../settings-volatile.js'
+import {
+  DEFAULT_ACTS, DEFAULT_CATEGORIES, DEFAULT_INTENT_SETTINGS, DEFAULT_PREDICATES,
+  type IntentSettings,
+} from './types.js'
+
+/**
+ * 一条分类的 schema。`/intent/registry` 的写入校验也用它 —— 所以它和
+ * `INTENT_SETTINGS_SCHEMA` 一起住在这里，而不是留在 `host.ts`。
+ */
+export const CATEGORY_SCHEMA = z.object({
+  id: z.string().required(),
+  label: z.string().required(),
+  route: z.string().required(),
+  description: z.string(),
+  // 预置说法（few-shot）。老配置没有这个字段，缺省空数组。
+  examples: z.array(z.string()).default([]),
+  enabled: z.boolean().default(true),
+})
+
+/** 一个 act 的 schema。同样被注册表写入校验复用。 */
+export const ACT_SCHEMA = z.object({
+  id: z.string().required(),
+  label: z.string(),
+  description: z.string(),
+  enabled: z.boolean().default(true),
+})
+
+/**
+ * 意图设置 schema。
+ *
+ * 显式标注 `Schemastery<IntentSettings>` 不是为了文档 —— 而是**导出**它之后
+ * `tsc` 必须把这个类型写进 `.d.ts`，而纯推断出来的类型会引用 `@deepseek-ai/cosmokit`
+ * 的 `Dict`（`z.object` 的 `ObjectT` 用它），那是一条 `.pnpm/...` 里的不可移植路径，
+ * 于是报 TS2742。标注之后写出去的是这个名字，路径问题就没了。
+ */
+export const INTENT_SETTINGS_SCHEMA: Schemastery<IntentSettings> = z.object(volatileFields({
+  clarifyThreshold: z.number().min(0).max(1).default(DEFAULT_INTENT_SETTINGS.clarifyThreshold),
+  ttlSeconds: z.number().step(1).min(1).max(86400).default(DEFAULT_INTENT_SETTINGS.ttlSeconds),
+  // 0023：路由提示词没有开关。它随 `intent_record` 的工具描述下发，始终在场。
+  fallbackEnabled: z.boolean().default(DEFAULT_INTENT_SETTINGS.fallbackEnabled),
+  categories: z.array(CATEGORY_SCHEMA).default(DEFAULT_CATEGORIES),
+  acts: z.array(ACT_SCHEMA).default(DEFAULT_ACTS),
+  predicates: z.array(z.string()).default(DEFAULT_PREDICATES),
+}))