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

package/src/index.ts

@@ -0,0 +1,1091 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { createReadStream, existsSync } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { extname, isAbsolute, join, resolve, sep } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool, type PreToolDecision, type ToolRunContext } from '@deepseek-ai/dsh-tools'
+import type { LineageContext } from 'dsh-data-contracts/refs'
+import {
+  DEFAULT_KNOWLEDGE_CONFIG, type Envelope, type KnowledgeBase, type KnowledgeConfig,
+  type KnowledgeStatus, type RecallMode, type SchemaType, type SourceType, type SourceTypeDef, type SourceTypeDraft,
+  type WikiSchemaMode, type WikiTypeDef,
+} from './types.js'
+import { defaultKnowledgeRoot, KnowledgeRuntime, success, failure, type KnowledgeRuntimeOptions, type WikiSchemaProvider } from './runtime.js'
+import { unwrapGroup } from './settings-volatile.js'
+import type { ModelCall } from './extract-model.js'
+import {
+  agentLayout, defaultAgentRoot, ensureAgentLayout, intentRoot, knowledgeBaseRoot, legacyDefaultKnowledgeRoot,
+  memoryRoot, presetSourceDir, resourceRegistry, resourceRoot, type AgentLayout,
+} from './layout.js'
+import { migrateLegacyKnowledgeTree, migrateLegacyMemory, migrateLegacyResources, type MigrationOutcome } from './migrate.js'
+import { legacyResourceHome } from './types.js'
+import {
+  PickerError, createDirectory, listDirectory, pickDirectory, pickerKind, pickerOf,
+} from './directory-picker.js'
+import { DiagnosisStore } from './diagnosis/store.js'
+import { KNOWLEDGE_SETTINGS_SCHEMA, SETTINGS_NAMESPACE } from './settings-schema.js'
+import { DEFAULT_KB_ID, KnowledgeBases } from './knowledge-bases.js'
+import {
+  applyConvert, CONVERT_SETTINGS_NAMESPACE, CONVERT_SETTINGS_SCHEMA, MOUNT_PATH as CONVERT_MOUNT_PATH,
+  type ConvertHost,
+} from './convert/host.js'
+import type { ConvertPluginConfig } from './convert/types.js'
+import {
+  applyIntent, INTENT_MOUNT_PATH, INTENT_SERVICE, INTENT_SETTINGS_SCHEMA,
+  SETTINGS_NAMESPACE as INTENT_SETTINGS_NAMESPACE,
+  type IntentHost,
+  type IntentLineageService,
+} from './intent/host.js'
+import type { IntentSettings } from './intent/types.js'
+
+export * from './types.js'
+export * from './runtime.js'
+export * from './knowledge-bases.js'
+export * from './intent/types.js'
+export * from './intent/engine.js'
+export { applyConvert as applyConvertHost, CONVERT_SETTINGS_NAMESPACE, CONVERT_MOUNT_PATH, type ConvertHost }
+export { applyIntent as applyIntentHost, INTENT_MOUNT_PATH, INTENT_SERVICE, INTENT_SETTINGS_NAMESPACE, type IntentHost, type IntentLineageService }
+
+export const name = 'dsh-data-domain-knowledge'
+/**
+ * `systemPrompt` is here because the 意图 module injects the category-routing
+ * section; the intent Host used to declare it in its own `inject` list before
+ * 0020 merged the two mount units.
+ *
+ * `settings` 在 0.1.7 之后**不再需要**：设置已经是本 entry 的 config
+ * （见下面的 `Config`），`settings.installSection` 那条路已经整个删除。
+ */
+export const inject = ['tools', 'webServer', 'systemPrompt'] as const
+// schema 与命名空间搬到了 `settings-schema.ts`（可测）。这里再导出一次，保持
+// `dsh-data-domain-knowledge` 的既有出口不变。
+export { KNOWLEDGE_SETTINGS_SCHEMA, SETTINGS_NAMESPACE }
+export { CONVERT_SETTINGS_SCHEMA, INTENT_SETTINGS_SCHEMA }
+/**
+ * 组合 schema 与它的取值形态住在 `./config-schema.js`：那里**没有工具层依赖**，
+ * 所以 `tests/settings-schema.test.mjs` 能 import 它并把三组设置解析一遍（装载器
+ * 仍然要从**本模块**读到 `Config`，所以这里 import 之后再 re-export）。
+ *
+ * 0.1.7 删掉了「设置命名空间 + `settings.installSection`」这一整套 API，改成
+ * **设置就是插件自己 entry 的 config**：schema 在 `config-schema.js` 里声明，初值由
+ * profile patch 的 `config:` 提供，设置页里的改动由 `configEditor` 写回同一处，
+ * 客户端按**路径**寻址（`{op:'set', path:['intent','categories']}`）。
+ */
+import { Config, type KnowledgePluginConfig } from './config-schema.js'
+export { Config, type KnowledgePluginConfig }
+
+/**
+ * The live multi-knowledge-base registry, set by `apply()`.
+ *
+ * The convert host (owned by another module) needs to resolve a knowledge base
+ * by id without importing this plugin's `apply` scope, so the instance is
+ * published here. `undefined` before `apply()` runs (or in unit tests that only
+ * import the runtime).
+ */
+let activeKnowledgeBases: KnowledgeBases | undefined
+export function currentKnowledgeBases(): KnowledgeBases | undefined { return activeKnowledgeBases }
+
+type Args = Record<string, any>
+type WebServerLike = { register(route: { kind: 'exact' | 'prefix'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> }): () => unknown }
+
+function output() { return { schema: { type: 'json' } as const, render: (_args: unknown, value: unknown) => [{ type: 'text' as const, text: JSON.stringify(value) }] } }
+function tool(name: string, description: string, parameters: Record<string, unknown>, execute: (args: Args, exec: ToolRunContext) => Promise<unknown>) {
+  return defineTool({ name, description, parameters: parameters as any, output: output(), execute: execute as any } as any)
+}
+function envelopeError(code: string, message: string, suggestion?: string) { return failure({}, code, message, false, suggestion) }
+
+/**
+ * 目录选择的失败码。`PickerError` 自带业务码就直接用，别的异常归到
+ * `PICKER_UNAVAILABLE` —— 不是目录选择器的问题，就是它没挂上。
+ */
+function pickerCode(cause: unknown): string {
+  return cause instanceof PickerError ? cause.code : 'PICKER_UNAVAILABLE'
+}
+
+/**
+ * 家当有没有真的落在 `resource/` 下（0029 的目标）。
+ *
+ * 三种情况要分开说，因为处理方式完全不同：
+ * - 在 `resource/` 里 → 什么都不用做（不在返回值里）；
+ * - `outside`：是绝对路径但在别处（典型是旧家当目录 `~/.tita-data-agent`）——
+ *   迁移就是为它写的，重启后会被搬进来；
+ * - `bare`：根本不是一个路径（`python3`、`BAAI/bge-reranker-base`）—— 迁移搬不了它，
+ *   因为它从来不是一份「家当」，得先把它放成 `resource/models/<名字>`，或显式配一个路径。
+ *
+ * 面板靠它说人话：**「模型不在家当目录里」比「语义检索可能不可用」可操作得多。**
+ */
+function outsideResource(resources: { python: string; embeddingModel: string; rerankModel: string }, resourceDir: string): Array<{ key: string; value: string; kind: 'outside' | 'bare' }> {
+  const prefix = resourceDir.endsWith(sep) ? resourceDir : `${resourceDir}${sep}`
+  const outside: Array<{ key: string; value: string; kind: 'outside' | 'bare' }> = []
+  for (const key of ['python', 'embeddingModel', 'rerankModel'] as const) {
+    const value = resources[key]
+    if (!value || value === resourceDir || value.startsWith(prefix)) continue
+    outside.push({ key, value, kind: isAbsolute(value) ? 'outside' : 'bare' })
+  }
+  return outside
+}
+
+function lineageOf(args: Args, exec?: ToolRunContext): LineageContext | undefined {
+  const lineage: 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'], ['intentId', 'intent_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().slice(0, 160)
+  return Object.keys(lineage).length > 0 ? lineage : undefined
+}
+
+function lineageFromUrl(url: URL): LineageContext | undefined {
+  return lineageOf({
+    session_key: url.searchParams.get('session_key') ?? undefined,
+    turn_id: url.searchParams.get('turn_id') ?? undefined,
+    intent_id: url.searchParams.get('intent_id') ?? undefined,
+    task_id: url.searchParams.get('task_id') ?? undefined,
+    subtask_id: url.searchParams.get('subtask_id') ?? undefined,
+    parent_subtask_id: url.searchParams.get('parent_subtask_id') ?? undefined,
+    run_id: url.searchParams.get('run_id') ?? undefined,
+    trace_id: url.searchParams.get('trace_id') ?? undefined,
+    domain: url.searchParams.get('domain') ?? undefined,
+  })
+}
+
+async function readBody(req: IncomingMessage, maxBytes = 256 * 1024): Promise<any> {
+  const chunks: Buffer[] = []
+  let bytes = 0
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))
+    bytes += buffer.length
+    if (bytes > maxBytes) throw new Error('REQUEST_TOO_LARGE')
+    chunks.push(buffer)
+  }
+  if (!chunks.length) return {}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+function 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)) }
+function query(req: IncomingMessage): URL { return new URL(req.url ?? '/', 'http://127.0.0.1') }
+
+/** URL-decoded path segments. `docId` contains `:`, so decoding is mandatory. */
+function pathSegments(pathname: string): string[] {
+  return pathname.split('/').filter(Boolean).map(segment => {
+    try { return decodeURIComponent(segment) } catch { return segment }
+  })
+}
+
+function clampInt(raw: string | null, fallback: number, min: number, max: number): number {
+  if (raw === null || raw.trim() === '') return fallback
+  const value = Number(raw)
+  if (!Number.isInteger(value)) return fallback
+  return Math.min(max, Math.max(min, value))
+}
+
+/** 删除守卫的 HTTP 状态：这三类冲突必须是 409，前端据此提示用户。 */
+const CONFLICT_CODES = new Set([
+  'FILE_TYPE_IN_USE', 'BASE_IS_DEFAULT', 'BASE_IN_USE',
+  'SOURCE_TYPE_IN_USE', 'SOURCE_TYPE_EXISTS', 'SOURCE_TYPE_BUILTIN_LOCKED',
+  // 0024 卡片类型注册表
+  'WIKI_TYPE_IN_USE', 'WIKI_TYPE_EXISTS', 'WIKI_TYPE_BUILTIN_LOCKED',
+])
+const BAD_REQUEST_CODES = new Set([
+  'REQUEST_INVALID', 'NAME_REQUIRED', 'FILE_TYPES_INVALID', 'VERSION_ID_REQUIRED', 'PAYLOAD_INVALID',
+  // 0013 注册表：分类草稿不合规一律 400；「在用 / 内置 / 兜底」这类不可变更状态走 409。
+  'SOURCE_TYPES_INVALID', 'SOURCE_TYPE_ID_INVALID', 'SOURCE_TYPE_LABEL_REQUIRED', 'SOURCE_TYPE_DESCRIPTION_REQUIRED',
+  'SOURCE_TYPE_DESCRIPTION_BY_FORMAT', 'SOURCE_TYPE_SIGNALS_REQUIRED', 'SOURCE_TYPE_EXCLUDES_REQUIRED',
+  'SOURCE_TYPE_EXCLUDE_DANGLING', 'SOURCE_TYPE_LIMIT', 'SOURCE_TYPE_FALLBACK_REQUIRED',
+  // 0024 卡片类型注册表：草稿不合规一律 400
+  'WIKI_TYPES_INVALID', 'WIKI_TYPE_ID_INVALID', 'WIKI_TYPE_LABEL_REQUIRED', 'WIKI_TYPE_DESCRIPTION_REQUIRED',
+  'WIKI_TYPE_SECTIONS_REQUIRED', 'WIKI_TYPE_SECTION_REQUIRED_MISSING', 'WIKI_TYPE_FIELD_DUPLICATE',
+  'CARD_SCHEMA_INVALID',
+])
+
+function envelopeStatus(envelope: Envelope<unknown>): number {
+  const code = envelope?.error?.code
+  if (!code) return 200
+  if (CONFLICT_CODES.has(code)) return 409
+  if (code === 'METHOD_NOT_ALLOWED') return 405
+  if (BAD_REQUEST_CODES.has(code)) return 400
+  if (code === 'NOT_FOUND' || code.endsWith('_NOT_FOUND')) return 404
+  return 200
+}
+
+/**
+ * 只给**新增**的 base / document 路由用：按错误码给出真实的 HTTP 状态
+ * （409 / 404 / 400），并在守卫冲突时把 `code`/`message` 同时提到顶层，
+ * 前端既能读 envelope 也能直接读冲突码。既有路由仍保持 200 + envelope。
+ */
+function sendEnvelope(res: ServerResponse, envelope: Envelope<unknown>): void {
+  const status = envelopeStatus(envelope)
+  if (status === 200 || !envelope?.error) { send(res, status, envelope); return }
+  send(res, status, { ...envelope, code: envelope.error.code, message: envelope.error.message })
+}
+
+const ASSET_CONTENT_TYPES: Record<string, string> = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.svg': 'image/svg+xml', '.bmp': 'image/bmp', '.avif': 'image/avif',
+  '.pdf': 'application/pdf', '.json': 'application/json; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8', '.md': 'text/markdown; charset=utf-8',
+}
+
+/**
+ * 把 entry config 里的 `knowledge` 组补成**完整且合法**的配置。
+ *
+ * 组合层正常情况下会把 schema 默认值合进来，但这个函数也会被单元测试和别的装配
+ * 方式调用，那时给回来的可能是缺字段的对象（甚至 `undefined`）。而这两个路径字段
+ * 一旦是 `undefined`，`layout.ts` 里的 `resolve()` 会直接抛 —— 一个配置疏漏不该把
+ * 整个插件打挂，所以在这里补，而不是在每个用它的地方都判一次。
+ *
+ * `unwrapGroup` 那一层是 0.1.7 的 volatile 契约：schema 解析出来的字段是引用
+ * （`{get, write}`），不是值。见 `settings-volatile.ts`。
+ */
+function normalizeKnowledge(next: Partial<KnowledgeConfig> | undefined): KnowledgeConfig {
+  const plain = unwrapGroup<KnowledgeConfig>(next)
+  return {
+    ...DEFAULT_KNOWLEDGE_CONFIG,
+    ...plain,
+    agentRoot: typeof plain.agentRoot === 'string' && plain.agentRoot.trim() ? plain.agentRoot : defaultAgentRoot(),
+    rootDir: typeof plain.rootDir === 'string' ? plain.rootDir : '',
+  }
+}
+
+
+export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): void {
+  /**
+   * 0029：配置里现在有两个路径字段，但只有 `agentRoot` 是「设置」。
+   *
+   * `rootDir` 是旧布局的知识树根，只作为迁移来源存在。初始值给空串而不是旧默认值
+   * ——迁移的来源由下面的 `legacySource()` 决定，它还要考虑「没设过 rootDir 的
+   * 用户，旧树在旧默认位置」这一种情况。
+   *
+   * 0.1.7：值来自本 entry 的 `config`（`apply` 的第二个参数），不再是
+   * `settings.installSection` 推回来的命名空间。这里先 `normalizeKnowledge` 补齐，
+   * 之后的迁移与 runtime 都只认这一份配置。
+   */
+  let config: KnowledgeConfig = normalizeKnowledge(pluginConfig.knowledge)
+  /**
+   * entry config 的另外两组，**按需求值**。
+   *
+   * 为什么是函数而不是先解包成一个值：0.1.7 的设置字段全标了 volatile，schema
+   * 解析出来是引用；解包一次就是一张快照，而 volatile 改动**不会重载插件**
+   * （loader 只就地改引用、再发一个 `loader/volatile-update`）。函数让下游每次
+   * 「重灌」都从同一个引用重新读值，改设置才真的会生效。
+   *
+   * `knowledge` 那组不需要函数：`normalizeKnowledge` 本来就在 volatile 事件里重跑一遍。
+   */
+  const intentGroup = (): Partial<IntentSettings> => unwrapGroup<IntentSettings>(pluginConfig.intent)
+  const convertGroup = (): Partial<ConvertPluginConfig> => unwrapGroup<ConvertPluginConfig>(pluginConfig.convert)
+  /**
+   * 这两组的把手，`loader/volatile-update` 时调 `reprocess()` 按新值重灌。
+   *
+   * 先声明后赋值：事件只在运行时触发，而两组的装配在下面（`applyConvert` /
+   * `applyIntent`）。
+   */
+  let intentHost: IntentHost | undefined
+  let convertHost: ConvertHost | undefined
+  /** 知识树迁移的结论。`/knowledge/layout` 会带上它，界面据此如实交代数据搬没搬。 */
+  let migration: MigrationOutcome = { status: 'skipped', reason: '尚未解析设置' }
+  /** 家当（模型 / Python 环境 / 注册表）迁移的结论。 */
+  let resourceMigration: MigrationOutcome = { status: 'skipped', reason: '尚未解析设置' }
+  /** 记忆段（知识树 → `<agentRoot>/memory/<库 id>`）迁移的结论（0032）。 */
+  let memoryMigration: MigrationOutcome = { status: 'skipped', reason: '尚未解析设置' }
+  /**
+   * 初始化失败的原因（如果有）。字段名保持 `settingsError`：`/knowledge/layout`
+   * 与面板上的告警都按这个名字读，改名的收益不如改语义的成本高。
+   *
+   * 旧的理由是「设置分区注册失败会被静默吞掉」（v0.7.5 的
+   * `z.string().min(1).default('')` 让整个命名空间注册不上）。0.1.7 之后 schema
+   * 错误会在装载 entry 时就抛、插件直接加载失败，不再是静默的；但**迁移**仍可能
+   * 因为一个权限问题失败，而那条失败不该让插件起不来，所以这里依旧接住并上报。
+   */
+  let settingsError: string | undefined
+  /**
+   * 迁移只该发生一次 —— 实际含义是「每次 apply 最多一次」。
+   *
+   * 0.1.7 下改设置会让插件**整个重载**，apply 因此会再跑一遍。用「已经跑过」而不是
+   * 「结果如何」做闸门，是为了不让一个失败的迁移在重载时被反复重试。
+   */
+  let migrationDone = false
+
+  /**
+   * 迁移的旧位置来源。
+   *
+   * 显式设过 `rootDir` 就用它；否则退回旧默认位置（`DSH_KNOWLEDGE_ROOT` 或
+   * `~/Desktop/titaagent/domain_knowledge`）。判据交给 `migrateLegacyKnowledgeTree`，
+   * 这里只负责「谁可能是旧树」。
+   */
+  const legacySource = (): string => config.rootDir.trim() || legacyDefaultKnowledgeRoot()
+
+  /**
+   * 默认库的来源分类注册表提供者（0013）。
+   *
+   * `bases` 在下面几行之后才创建，所以先用一个可变槽位接住；真正读取发生在
+   * 调用时（`add_source` / `list_source_types`），那时 `bases` 一定已就绪。
+   * 用 provider 而不是快照，是为了让用户改完分类**立刻**对 Agent 生效。
+   */
+  let defaultBaseSourceTypes: (() => SourceTypeDef[]) | undefined
+  let defaultBaseWikiSchema: WikiSchemaProvider | undefined
+  /**
+   * #3b：把 **DSH 的默认模型**包成运行时认识的纯文本调用。
+   *
+   * 这里刻意**不复制一份模型选择**。`provider` / `model` / `reasoningEffort` 的真源是
+   * DSH 自己的 `agentDefaultModel`（设置里那一项）。插件再存一份，就会出现「设置里显示
+   * A、实际调的是 B」—— 0029 想收拢的正是这类两处说法。
+   *
+   * 取不到 `llm` 或默认模型时返回 undefined，链路**退回纯规则抽取**：模型是增强，
+   * 不是前提。
+   */
+  const modelCallFor = (): ModelCall | undefined => {
+    const llm = ctx.get('llm') as { stream(options: Record<string, unknown>): AsyncIterable<{ type?: string; text?: string }> } | undefined
+    /**
+     * `agentDefaultModel` 是一个**服务实例**（`dsh-agent-default-model` 的
+     * `AgentDefaultModelConfig extends Service`），默认模型要从它的
+     * `currentSelection()` 拿。
+     *
+     * 直接读 `.provider` 是取不到的：它的 Config 字段标了 volatile，解析出来是引用，
+     * 所以那个类自己也是用 `this.config.provider.get()` 读的。第一版就是按普通属性读的，
+     * 结果是永远拿到 undefined —— 模型接缝静默失效。
+     */
+    const service = ctx.get('agentDefaultModel') as { currentSelection?: () => { provider?: string; model?: string; reasoningEffort?: string } } | undefined
+    const route = service?.currentSelection?.()
+    if (!llm || !route?.provider || !route?.model) return undefined
+    const { provider, model, reasoningEffort } = route
+    return async ({ system, prompt }) => {
+      let text = ''
+      const request = { provider, model, ...(reasoningEffort ? { reasoningEffort } : {}), system, messages: [{ role: 'user', content: prompt }] }
+      for await (const chunk of llm.stream(request)) {
+        if (chunk?.type === 'text-delta' && typeof chunk.text === 'string') text += chunk.text
+      }
+      return text
+    }
+  }
+  const runtimeOptions = (): KnowledgeRuntimeOptions => {
+    const modelCall = modelCallFor()
+    return {
+      ...(defaultBaseSourceTypes ? { sourceTypes: defaultBaseSourceTypes } : {}),
+      ...(defaultBaseWikiSchema ? { wikiSchema: defaultBaseWikiSchema } : {}),
+      // 0029：家当目录。配置里三个路径为空时，运行时从这里解析模型与解释器。
+      resourceRoot: resourceRoot(config.agentRoot),
+      // 0032：记忆段。默认库的记忆落在 `<agentRoot>/memory/default`，与知识树平级。
+      memoryRoot: memoryRoot(config.agentRoot, DEFAULT_KB_ID),
+      // #3b：模型接缝（实体抽取与归并）。没有默认模型时不提供，链路自动退回规则抽取。
+      ...(modelCall ? { modelCall } : {}),
+    }
+  }
+  /** 默认知识库的根：`<agentRoot>/domain_knowledge/default`。 */
+  const defaultBaseRoot = (): string => knowledgeBaseRoot(config.agentRoot, 'default')
+  let runtime = new KnowledgeRuntime(defaultBaseRoot(), config, runtimeOptions())
+  ensureAgentLayout(config.agentRoot)
+
+  // Multi-knowledge-base registry (0021). The default base reuses the
+  // settings-driven runtime above, so `runtimeOf('default')` — and therefore
+  // every legacy route/tool that omits `kb` — stays byte-identical to before.
+  // 0029: 新建的库落在 `<agentRoot>/domain_knowledge/<id>`，不再是各写各的自由路径。
+  const bases = new KnowledgeBases({
+    defaultRootDir: defaultBaseRoot,
+    agentRoot: () => config.agentRoot,
+    // 0029：注册表也进根路径 —— 「这个 Agent 的全部磁盘足迹」应该是一个目录。
+    registryFile: () => resourceRegistry(config.agentRoot),
+    defaultRuntime: () => runtime,
+    config: () => config,
+  })
+  runtime.baseId = bases.defaultId
+  defaultBaseSourceTypes = () => bases.sourceTypesOf(bases.defaultId)
+  defaultBaseWikiSchema = () => ({ types: bases.wikiTypesOf(bases.defaultId), mode: bases.wikiSchemaModeOf(bases.defaultId) })
+  activeKnowledgeBases = bases
+
+  const kbIdOf = (value: unknown): string => {
+    if (value === undefined || value === null) return bases.defaultId
+    const id = String(value).trim()
+    return id || bases.defaultId
+  }
+
+  /**
+   * 0.1.7 的 volatile 配置改动：**宿主不重载插件，插件必须自己用上去。**
+   *
+   * `Entry._commitVolatile()` 只调 `updateVolatile()` 就地改引用，再发一个
+   * `loader/volatile-update` 事件。所以「设置存下了但没生效」这件事只能在这里兜住 ——
+   * 设置 schema 里的字段全部标了 volatile（见 `settings-volatile.ts`），这两件事必须成对。
+   *
+   * 就地更新之所以够用，是因为 `pluginConfig` 就是宿主那份被改过的对象：重新
+   * `normalizeKnowledge` 一下就能拿到新值。
+   *
+   * 分两种改动处理：
+   *
+   * - **非结构性**（阈值、topK、provider、开关……）：这些字段运行时是**每次调用现读**
+   *   `this.config` 的，合并进去就生效。
+   * - **`agentRoot` 是结构性的**：它决定知识树在磁盘的哪里。根一变，已经建好的 runtime
+   *   和注册表缓存都还指着旧目录 —— 只合并配置会得到最坏的结果「设置显示新路径、实际
+   *   还在读写旧路径」。所以这里重建默认 runtime、重指注册表、重新铺一次布局。
+   */
+  // `loader/volatile-update` 是 loader 运行时真实发出的事件，但没进 cordis 的 `Events`
+  // 类型表（它是 loader 内部约定），所以这里显式放宽一次。
+  const volatileCtx = ctx as unknown as { on(name: string, listener: () => void): () => void }
+  ctx.effect(() => volatileCtx.on('loader/volatile-update', () => {
+    const previousAgentRoot = config.agentRoot
+    config = normalizeKnowledge(pluginConfig.knowledge)
+    runtime.updateConfig(config)
+    /**
+     * 意图与转换两组挂在**同一个 entry** 上（`config-schema.ts` 里那三组），所以
+     * volatile 事件也会带着它们的改动。它们不会因此被重载，只能自己就地重灌 ——
+     * 漏掉这一步的后果是「设置页保存了、界面显示新值、Agent 还在用旧值」。
+     *
+     * 放在 `agentRoot` 那条提前返回**之前**：根没变不代表另外两组没变。
+     */
+    intentHost?.reprocess()
+    convertHost?.reprocess()
+    if (config.agentRoot === previousAgentRoot) return
+    runtime.close()
+    runtime = new KnowledgeRuntime(defaultBaseRoot(), config, runtimeOptions())
+    runtime.baseId = bases.defaultId
+    ensureAgentLayout(config.agentRoot)
+    bases.invalidate()
+    void bases.repoint()
+  }), 'tita knowledge: apply volatile config')
+
+  /** Runtime behind an optional `kb`; `undefined` when the id is unknown. */
+  const runtimeOf = (id: string): KnowledgeRuntime | undefined => {
+    if (id === bases.defaultId) return runtime
+    return bases.get(id) ? bases.runtimeOf(id) : undefined
+  }
+
+  /** Tool-facing wrapper: an unknown `kb` becomes a BASE_NOT_FOUND envelope. */
+  const withRuntime = async <T>(kb: unknown, run: (target: KnowledgeRuntime) => Promise<Envelope<T>>): Promise<Envelope<T>> => {
+    const id = kbIdOf(kb)
+    const target = runtimeOf(id)
+    if (!target) {
+      // 与 `SOURCE_TYPE_UNKNOWN` 同一条纪律：把可用值直接写进自愈建议，调用方不必再跑
+      // 一趟才发现自己拿的是错 id。这里原先是「先列出 /knowledge/bases」——那是给浏览器
+      // 面板读的 HTTP 路由，模型照着做不了。
+      const available = bases.list().map(base => base.id).join(' / ')
+      return failure({} as T, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true, `先调 list_knowledge_bases 确认 id；当前可用: ${available}（不传 kb 表示默认库 ${bases.defaultId}）。`)
+    }
+    return run(target)
+  }
+
+  /**
+   * 给每个知识库搬记忆段（0032）。
+   *
+   * 结论只保留**最后一个非 skipped 的**：默认库才是用户实际在用的那个，而面板上
+   * 一行位置有限。真有多个库搬失败时，`/knowledge/layout` 的 `resourceMigration`
+   * 与知识库列表里的路径仍然能对上账。
+   */
+  const migrateAllMemory = (): MigrationOutcome => {
+    const bases = activeKnowledgeBases
+    if (!bases) return { status: 'skipped', reason: '知识库注册表尚未就绪' }
+    let outcome: MigrationOutcome = { status: 'skipped', reason: '每个知识库的记忆都在新位置' }
+    const roots = bases.list()
+    const defaultBase = roots.find(item => item.id === bases.defaultId)
+    // 默认库的根由配置推出来，可能还没出现在注册表里（首启）；补上它。
+    const plan = defaultBase ? roots : [{ id: bases.defaultId, rootDir: defaultBaseRoot() }, ...roots]
+    for (const base of plan) {
+      try {
+        const moved = migrateLegacyMemory({ agentRoot: config.agentRoot, kbRoot: base.rootDir, kbId: base.id })
+        if (moved.status !== 'skipped') outcome = moved
+      } catch (cause) {
+        outcome = {
+          status: 'failed',
+          from: join(base.rootDir, '04_memory'),
+          to: memoryRoot(config.agentRoot, base.id),
+          reason: cause instanceof Error ? cause.message : String(cause),
+        }
+      }
+    }
+    return outcome
+  }
+
+  /**
+   * 初始化：迁移 → 布局 → 构造 runtime。
+   *
+   * 顺序是**硬要求**：配置已由外层的 `normalizeKnowledge` 补齐，这里先迁移（迁移要读
+   * 新的 `agentRoot` 与旧的 `rootDir`），最后才构造 runtime。反过来的话，runtime 会在
+   * 数据搬完之前就指着新路径，于是「刚启动时知识库是空的」——而那正是最容易让人以为
+   * 数据丢了的时刻。
+   *
+   * 0.1.7：这段以前挂在 `settings.installSection` 的 `setSource`/`onChange` 回调里，
+   * 因为配置要等设置层推回来。现在配置是 `apply` 的入参，所以直接在 apply 时跑一次；
+   * 改设置会让插件**整个重载**，于是它会随重载再跑，由 `migrationDone` 挡住重复迁移。
+   */
+  const initialize = (): void => {
+    if (!migrationDone) {
+      migrationDone = true
+      // 顺序：先把知识树搬进新根路径，再把家当搬进来。家当要在 runtime 构造**之前**
+      // 到位 —— 否则模型与解释器会先按旧位置解析一次，那一轮跑的是旧环境。
+      migration = migrateLegacyKnowledgeTree({ agentRoot: config.agentRoot, legacyRoot: legacySource() })
+      resourceMigration = migrateLegacyResources({ agentRoot: config.agentRoot, legacyHome: legacyResourceHome() })
+      /**
+       * 0032：记忆段从知识树搬出去。**每个知识库各搬一次** —— 它按库分叉，而
+       * 非默认库的 runtime 是懒建的（`runtimeOf`），懒建里做迁移会把「打开一个库」
+       * 变成一次可能的搬盘。放在这里，顺序与另外两个迁移一致：搬完才构造 runtime。
+       *
+       * 逐个 try：一个库搬不动不该让其余的也不搬，更不该让插件起不来。
+       */
+      memoryMigration = migrateAllMemory()
+      // 注册表可能刚被搬进来：让它按新位置重新读一遍。
+      void bases.repoint()
+    }
+    ensureAgentLayout(config.agentRoot)
+    runtime.close()
+    runtime = new KnowledgeRuntime(defaultBaseRoot(), config, runtimeOptions())
+    runtime.baseId = bases.defaultId
+    // 非默认库的 runtime 用新配置重建；默认 runtime 已由上一行替换。
+    bases.invalidate()
+  }
+
+  /**
+   * 初始化失败必须留下痕迹。
+   *
+   * 迁移会因为权限、占用、半个快照这类原因失败；而它抛出的异常如果没人接，就只是
+   * 一次没人看见的失败 —— 面板照常显示，数据却没搬。抓住它、记下来、让
+   * `/knowledge/layout` 报出去，界面于是能说「为什么不对」，而不是只显示症状。
+   *
+   * 注意这里**不吞配置错误**：schema 不合法的 config 在装载 entry 时就已经让插件
+   * 加载失败了（那是响亮的）。这里接住的只是初始化期的数据问题。
+   */
+  try {
+    initialize()
+    settingsError = undefined
+  } catch (cause) {
+    settingsError = cause instanceof Error ? cause.message : String(cause)
+  }
+
+  // Conversion host (issue 0018). It shares this plugin's runtime so ingestion is
+  // an in-process `addSource` call, and it owns the `convert` config group, the
+  // `/convert/**` route and the `convert_*` tools.
+  // The kernel behind it stays an optional dependency, loaded lazily.
+  convertHost = applyConvert(ctx, {
+    runtime: () => runtime,
+    knowledgeRoot: () => runtime.rootDir,
+    /**
+     * 0029：转换内核的目录也从同一个根路径推出来 —— 交付物落
+     * `<agentRoot>/output/<日期>/`，工作区与任务状态落 `<agentRoot>/tmp/`。
+     * 转换因此**不再有自己的路径设置**：一个 Agent 只有一个根路径。
+     */
+    agentRoot: () => config.agentRoot,
+    /**
+     * 交付物落在**工作项目**下：`<工作区>/output/<日期>/`，不是 Agent 根路径。
+     *
+     * 根路径下的四段（知识 / 记忆 / 意图 / 家当）是**这个 Agent 自己的东西**，跨项目
+     * 累积；交付物是**某个项目的产物**，换一个项目打开就不该再看见。两者判据不同，
+     * 所以落点也不同。
+     *
+     * 这里给的是宿主进程的工作目录：转换内核是宿主级单例，拿不到会话，也就拿不到
+     * 「这个会话的工作项目」。单项目部署下两者一致；多项目共用宿主时交付物会集中到
+     * 宿主启动目录 —— 见 `ConvertHostDeps.workspace` 的说明。
+     */
+    workspace: () => process.cwd(),
+    // 0.1.7：转换的设置不再走命名空间，随本 entry 的 config 一起下来。
+    // 给函数而不是值：字段是 volatile 引用，解包一次就是快照（见 `convertGroup`）。
+    config: convertGroup,
+    // 0019: a delivery can target one knowledge base (the panel imports into the
+    // base the user selected). Unknown/absent id falls back to the default base
+    // instead of failing the ingest.
+    resolveTarget: (kbId?: string) => {
+      const target = kbId ? runtimeOf(kbId) : undefined
+      return target ? { runtime: target, knowledgeRoot: target.rootDir } : { runtime, knowledgeRoot: runtime.rootDir }
+    },
+  })
+
+  // 意图记录模块 (issue 0020). The 意图 view was already one of this plugin's
+  // five panel tabs, but its Host lived in a second mount unit; 0020 folds it in
+  // so the declared information architecture and the code layout agree again.
+  // It keeps the three `intent_*` tool names, the `/intent/**` read-only surface,
+  // and — critically — the `titaDataAgentIntent` Cordis service that `data-table`
+  // resolves by name.
+  // 0032/0033：意图的配置与留痕落进 `<agentRoot>/intent`（与知识、记忆平级）。
+  // 0.1.7：意图的设置不再走命名空间，随本 entry 的 config 一起下来。
+  intentHost = applyIntent(ctx, { intentRoot: () => intentRoot(config.agentRoot), config: intentGroup })
+
+  const writeTools = new Set(['add_source', 'write_knowledge_card', 'set_knowledge_status', 'rebuild_knowledge', 'record_feedback'])
+  ctx.on('tools/pre-execute', (exec, next): Promise<PreToolDecision> => {
+    if (writeTools.has(exec.name)) return Promise.resolve({ kind: 'ask', reason: '该操作会写入 Tita Knowledge Store，需要本轮用户审批。' })
+    return next()
+  })
+  ctx.tools.register(tool('recall_knowledge', 'Recall compiled knowledge: multi-route recall over wikiNotes (top_k, default from settings), resolve each hit to its wiki and 1-hop graph, BERT-rerank, then return the top_n context pack.', { query: { type: 'string', required: true }, scope: { type: 'string' }, limit: { type: 'integer' }, top_k: { type: 'integer' }, top_n: { type: 'integer' }, rerank: { type: 'boolean' }, source_types: { type: 'array' }, include_problems: { type: 'boolean' }, mode: { type: 'string', enum: ['fts', 'vector', 'graph', 'hybrid'] }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, parent_subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.recall(args.query, args.top_k ?? args.limit, args.source_types ?? [], args.include_problems ?? false, args.mode as RecallMode | undefined, lineageOf(args, exec), { contextTopN: args.top_n, rerank: args.rerank }))))
+  ctx.tools.register(tool('check_knowledge_embeddings', 'Inspect the local embedding provider and binary/int8 vector index without loading the model.', { kb: { type: 'string' }, session_key: { type: 'string' } }, async args => withRuntime(args.kb, target => target.embeddingHealth())))
+  ctx.tools.register(tool('query_knowledge_graph', 'Query entities, neighbors, paths, lists and relation types in the compiled knowledge graph.', { action: { type: 'string', enum: ['entity', 'neighbors', 'path', 'list', 'types'], required: true }, entity_id: { type: 'string' }, id: { type: 'string' }, entity_type: { type: 'string' }, from_id: { type: 'string' }, to_id: { type: 'string' }, type: { type: 'string' }, status: { type: 'string' }, include_problem: { type: 'boolean' }, limit: { type: 'integer' }, depth: { type: 'integer' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, parent_subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.graphQuery(args.action, args.entity_id ?? args.id, args.entity_type ?? args.type, args.depth ?? 1, { fromId: args.from_id, toId: args.to_id, status: args.status, includeProblem: args.include_problem ?? false, limit: args.limit ?? 50 }, lineageOf(args, exec)))))
+  ctx.tools.register(tool('query_source_truth', 'Read SourceRaw (原始可追溯文档) with access audit. Returns the top max_chars characters (default and hard max 40000) shared across the matched sources. Each source carries its absolute file `path`, `returnedChars` and `totalChars`, and the envelope carries `truncated`. When truncated is true (or returnedChars < totalChars) the content is INCOMPLETE — read that `path` directly to get the rest rather than answering from a partial document.', { query: { type: 'string', required: true }, source_types: { type: 'array' }, limit: { type: 'integer' }, max_chars: { type: 'integer' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.sourceTruth(args.query, args.source_types ?? [], args.limit ?? 20, args.max_chars ?? 40000, lineageOf(args, exec)))))
+  /**
+   * 知识库 id 的**发现入口**。
+   *
+   * 在这之前，「有哪些库」对模型是一个答不出来的问题：`/knowledge/bases` 是给浏览器
+   * 面板读的 HTTP 路由，而 `withRuntime` 在 id 未知时的自愈建议正是让调用方「先列出
+   * /knowledge/bases」。于是非默认库只能靠猜，猜错得到一句它无法执行的建议。这个工具
+   * 补上那一跳，`withRuntime` 的建议也改成指向它。
+   *
+   * 返回的是**投影**而不是 `KnowledgeBase` 整体：`sourceTypes` 与 `wikiTypes` 两张
+   * 注册表各有几十条，而这里要回答的是「有哪些库、哪个是默认、各有多少东西」；注册表
+   * 本身由 `list_source_types` / `list_wiki_types` 按需读，不在这里重复下发。
+   *
+   * 也**不调 `refresh()`**：它要遍历整棵树重算统计并落盘，而这个工具是只读的发现入口，
+   * 读落盘缓存就够，代价是一次同步的 `list()`。
+   */
+  ctx.tools.register(tool('list_knowledge_bases', 'List the knowledge bases on this deployment: id, name, description, which one is the default, and how much each holds. Read-only. Call this before passing a `kb` you have not seen this session, and never invent a base id.', {}, async () => success({
+    defaultBaseId: bases.defaultId,
+    bases: bases.list().map(base => ({
+      id: base.id,
+      name: base.name,
+      description: base.description,
+      isDefault: base.isDefault,
+      sourceCount: base.sourceCount,
+      cardCount: base.cardCount,
+      noteCount: base.noteCount,
+      buildVersion: base.buildVersion,
+    })),
+  })))
+  ctx.tools.register(tool('list_source_types', 'List the SourceRaw business classifications (the per-knowledge-base source_type registry) together with the built-in read-only classifier prompt. Call this before add_source whenever the classification is not obvious; the registry is editable per knowledge base, so custom ids such as test_unit may exist.', { kb: { type: 'string', description: '目标知识库 id；省略则用默认库' }, session_key: { type: 'string' } }, async args => withRuntime(args.kb, target => Promise.resolve(target.sourceTypeCatalog()))))
+  ctx.tools.register(tool('list_wiki_types', 'List the Wiki card types (the per-knowledge-base card schema) with their required sections, required fields, expected source types and template card. Call this before write_knowledge_card: entity_type must be one of these ids, and the required sections/fields are what makes the card usable.', { kb: { type: 'string', description: '目标知识库 id；省略则用默认库' }, session_key: { type: 'string' } }, async args => withRuntime(args.kb, target => target.wikiTypeCatalog())))
+  ctx.tools.register(tool('add_source', 'Add or update a SourceRaw document (原始可追溯文档). source_type is a per-knowledge-base business classification: call list_source_types first when unsure, and never guess silently. DSH requests one user approval before execution.', { source_type: { type: 'string', required: true, description: '来源业务分类 id（按业务场景，不是文件格式）。先调 list_source_types 拿注册表；拿不准就返回候选问用户，不要默认 document。' }, title: { type: 'string' }, content: { type: 'string', required: true }, external_id: { type: 'string' }, metadata: { type: 'json' }, source_id: { type: 'string' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.addSource({ sourceType: args.source_type, title: args.title, content: args.content, externalId: args.external_id, metadata: args.metadata, sourceId: args.source_id, lineage: lineageOf(args, exec) }))))
+  ctx.tools.register(tool('write_knowledge_card', 'Write a Wiki knowledge card with mandatory source_refs. New cards default to unreviewed. DSH requests one user approval before execution.', { entity_type: { type: 'string', required: true, description: 'Wiki 卡片类型 id：先按 list_wiki_types 的类型定义与「例如」判断，命中就直接用它；必填小节与必填字段见该类型的 schema' }, entity_id: { type: 'string', required: true }, title: { type: 'string', required: true }, content: { type: 'string', required: true }, source_refs: { type: 'array', required: true }, status: { type: 'string', enum: ['unreviewed', 'draft', 'reviewed', 'active', 'deprecated', 'problem'] }, summary: { type: 'string' }, metadata: { type: 'json' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.writeCard({ entityType: args.entity_type, entityId: args.entity_id, title: args.title, content: args.content, sourceRefs: args.source_refs, status: args.status, summary: args.summary, metadata: args.metadata, lineage: lineageOf(args, exec) }))))
+  ctx.tools.register(tool('set_knowledge_status', 'Change a Wiki card status. problem requires problem_note and recovery must pass through unreviewed. DSH requests one user approval before execution.', { entity_id: { type: 'string', required: true }, status: { type: 'string', enum: ['unreviewed', 'draft', 'reviewed', 'active', 'deprecated', 'problem'], required: true }, problem_note: { type: 'string' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.setStatus(args.entity_id, args.status as KnowledgeStatus, args.problem_note, lineageOf(args, exec)))))
+  ctx.tools.register(tool('rebuild_knowledge', 'Rebuild schema/wiki/compiled knowledge indexes. DSH requests one user approval before execution.', { only: { type: 'string', enum: ['all', 'schema', 'wiki', 'embeddings'] }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.rebuild(args.only ?? 'all', lineageOf(args, exec)))))
+  ctx.tools.register(tool('record_feedback', 'Record bounded feedback for a knowledge result. DSH requests one user approval before execution.', { feedback_id: { type: 'string' }, unit_id: { type: 'string' }, rating: { type: 'integer', required: true }, comment: { type: 'string' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.recordFeedback({ feedbackId: args.feedback_id, unitId: args.unit_id, rating: args.rating, comment: args.comment, sessionKey: args.session_key, lineage: lineageOf(args, exec) }))))
+
+  ctx.inject(['webServer'], webCtx => {
+    const web = webCtx as unknown as Context & { webServer: WebServerLike }
+    const register = (route: { kind: 'exact' | 'prefix'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> }) => web.webServer.register(route)
+
+    /**
+     * Resolve the knowledge base behind an optional `kb` query/body field.
+     * Older routes stay byte-compatible: an absent `kb` is the default base.
+     */
+    const resolveBase = (kb: unknown): { runtime: KnowledgeRuntime; base: KnowledgeBase } | { failure: Envelope<Record<string, unknown>> } => {
+      const id = kbIdOf(kb)
+      const base = bases.get(id)
+      if (!base) return { failure: failure({}, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true, '先 GET /knowledge/bases 拿到可用 id；不传 kb 表示默认库。') }
+      const target = runtimeOf(id)
+      if (!target) return { failure: failure({}, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true) }
+      return { runtime: target, base }
+    }
+
+    /**
+     * 智能归因图谱的存储句柄，按 rootDir 缓存。
+     *
+     * 每个知识库有自己的 `05_diagnosis/`，和它的 wiki / 编译产物同源；缓存键用
+     * rootDir 而不是 baseId，因为独立 runtime（未挂到知识库列表上的）也要能读写。
+     */
+    const diagnosisStores = new Map<string, DiagnosisStore>()
+    const storeOf = (target: KnowledgeRuntime): DiagnosisStore => {
+      const cached = diagnosisStores.get(target.rootDir)
+      if (cached) return cached
+      // 卡片要经运行时的 writeCard 落盘（它同时校验 schema 与「出处必须真实存在」），
+      // 所以 store 拿的是运行时本身，不只是 rootDir。
+      const created = new DiagnosisStore(target)
+      diagnosisStores.set(target.rootDir, created)
+      return created
+    }
+
+    const routes = [
+      { kind: 'exact' as const, path: '/knowledge/stats', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const resolved = resolveBase(query(req).searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        return send(res, 200, success(await resolved.runtime.stats()))
+      } },
+      { kind: 'exact' as const, path: '/knowledge/search', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const url = query(req)
+        const resolved = resolveBase(url.searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        const sourceTypes = (url.searchParams.get('source_types') ?? '').split(',').map(value => value.trim()).filter(Boolean)
+        const topK = url.searchParams.get('top_k') ?? url.searchParams.get('limit')
+        const topN = url.searchParams.get('top_n')
+        const rerankParam = url.searchParams.get('rerank')
+        // 响应里始终带 routes + backend，前端据此显示「关键词 / 向量 / 知识图谱」三路状态。
+        return send(res, 200, await resolved.runtime.recall(
+          url.searchParams.get('query') ?? '',
+          topK === null ? undefined : Number(topK),
+          sourceTypes,
+          url.searchParams.get('include_problems') === 'true',
+          (url.searchParams.get('mode') ?? undefined) as RecallMode | undefined,
+          lineageFromUrl(url),
+          { ...(topN === null ? {} : { contextTopN: Number(topN) }), ...(rerankParam === null ? {} : { rerank: rerankParam !== 'false' && rerankParam !== '0' }) },
+        ))
+      } },
+      { kind: 'exact' as const, path: '/knowledge/embedding/health', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const resolved = resolveBase(query(req).searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        return send(res, 200, await resolved.runtime.embeddingHealth())
+      } },
+      { kind: 'exact' as const, path: '/knowledge/graph', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const url = query(req)
+        const resolved = resolveBase(url.searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        send(res, 200, await resolved.runtime.graphQuery((url.searchParams.get('action') ?? 'list') as any, url.searchParams.get('entity_id') ?? undefined, url.searchParams.get('entity_type') ?? undefined, Number(url.searchParams.get('depth') ?? 1), { fromId: url.searchParams.get('from_id') ?? undefined, toId: url.searchParams.get('to_id') ?? undefined, status: url.searchParams.get('status') ?? undefined, includeProblem: url.searchParams.get('include_problem') === 'true', limit: Number(url.searchParams.get('limit') ?? 50) }, lineageFromUrl(url)))
+      } },
+      { kind: 'exact' as const, path: '/knowledge/cards', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const resolved = resolveBase(query(req).searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        return send(res, 200, success({ cards: await resolved.runtime.loadCards() }))
+      } },
+      { kind: 'exact' as const, path: '/knowledge/rebuild', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        try {
+          if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'))
+          const body = await readBody(req)
+          const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'))
+          if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+          return send(res, 200, await resolved.runtime.rebuild(body.only ?? 'all', lineageOf(body)))
+        } catch (cause) {
+          return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)))
+        }
+      } },
+      { kind: 'exact' as const, path: '/knowledge/sources', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        try {
+          if (req.method === 'POST') {
+            const body = await readBody(req, 1_200_000)
+            const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'))
+            if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+            return send(res, 200, await resolved.runtime.addSource({ sourceType: body.source_type ?? 'document', title: body.title, content: body.content, externalId: body.external_id, metadata: body.metadata, sourceId: body.source_id, lineage: lineageOf(body) }))
+          }
+          if (req.method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET 或 POST'))
+          const url = query(req)
+          const resolved = resolveBase(url.searchParams.get('kb'))
+          if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+          return send(res, 200, await resolved.runtime.sourceTruth(url.searchParams.get('query') ?? '', [], 20, 40000, lineageFromUrl(url)))
+        } catch (cause) {
+          return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)))
+        }
+      } },
+      // ---------------------------------------------------------- 目录选择（0029）
+      /**
+       * 根路径的**只读**视图：四段布局、两次迁移的结论、家当解析结果、宿主提供的是哪种选择交互。
+       *
+       * 设置面板要显示「你这个根路径下会长出哪几段」，而那是服务端算出来的
+       * （`layout.ts` 是唯一真源），所以不能让前端自己拼字符串。
+       */
+      { kind: 'exact' as const, path: '/knowledge/layout', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const dirs = agentLayout(config.agentRoot)
+        const resources = runtime.resourcePaths()
+        // preset 的真源目录。它随插件分发，所以路径由插件自己算 —— 客户端不该拼这个
+        // 字符串，也不该猜包装在哪。`exists` 是给界面用的：路径不在时如实说「这个安装
+        // 里没有 preset 真源」，而不是给一个点了弹空目录的按钮。
+        const presetDir = presetSourceDir()
+        return send(res, 200, success({
+          ...dirs,
+          presetDir,
+          presetDirExists: existsSync(presetDir),
+          migration,
+          resourceMigration,
+          memoryMigration,
+          // 三个「家当」路径**解析后**的值。设置面板用它显示「自动」到底指向哪里 ——
+          // 配置里是空串（= 自动），但用户要看到的是真实路径。
+          resources,
+          // 家当有没有真的落在 `resource/` 下（0029 的目标）。`resource` 是家当目录本身，
+          // 用它做前缀判断：不在里面的就是「还在旧位置」或「是一个裸的 HuggingFace 仓库名」。
+          resourcesOutsideResource: outsideResource(resources, dirs.resource),
+          // 设置分区没注册上时的原因。有它，「设置服务不可用」才不是一句空话。
+          ...(settingsError ? { settingsError } : {}),
+          pickerKind: pickerKind(pickerOf(ctx)),
+        }))
+      } },
+      /**
+       * 开一次目录选择。
+       *
+       * native 形态下这个请求会一直挂到用户关掉系统对话框（关掉 = `path: null`）。
+       * 不用超时打断它：对话框是**用户在看**的，任何超时都会变成「我还没选完，
+       * 页面就说失败了」。
+       */
+      { kind: 'exact' as const, path: '/knowledge/pick-directory', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 endpoint 只接受 POST'))
+        const controller = new AbortController()
+        // 客户端断开（关页面/刷新）时终止对话框，别让一个没人要的对话框留在屏幕上。
+        req.on('close', () => controller.abort())
+        try {
+          return send(res, 200, success(await pickDirectory(pickerOf(ctx), controller.signal)))
+        } catch (cause) {
+          return send(res, 200, failure({ kind: null }, pickerCode(cause), cause instanceof Error ? cause.message : String(cause), true, '检查 DSH 是否挂载了目录选择后端（dsh-host-directory-picker-*）。'))
+        }
+      } },
+      /** 列一层目录。只在 browse 形态下有内容。 */
+      { kind: 'exact' as const, path: '/knowledge/browse-directory', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const url = query(req)
+        const target = url.searchParams.get('path') ?? undefined
+        try {
+          return send(res, 200, success(await listDirectory(pickerOf(ctx), target, new AbortController().signal)))
+        } catch (cause) {
+          return send(res, 200, failure({ path: target ?? '' }, pickerCode(cause), cause instanceof Error ? cause.message : String(cause), true))
+        }
+      } },
+      /** 在某个目录下建一个子目录。只在 browse 形态下有内容。 */
+      { kind: 'exact' as const, path: '/knowledge/create-directory', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 endpoint 只接受 POST'))
+        try {
+          const body = await readBody(req)
+          return send(res, 200, success({ path: await createDirectory(pickerOf(ctx), String(body.path ?? ''), String(body.name ?? '')) }))
+        } catch (cause) {
+          return send(res, 200, failure({ path: '' }, pickerCode(cause), cause instanceof Error ? cause.message : String(cause), true))
+        }
+      } },
+      // 智能归因：与 /knowledge/* 平级而不是挂在其下 —— 它读的是 05_diagnosis，
+      // 不是知识库本身的编译产物，路径上不该假装是 knowledge 的子资源。
+      { kind: 'exact' as const, path: '/diagnosis/graph', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const resolved = resolveBase(query(req).searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        const snapshot = await storeOf(resolved.runtime).snapshot()
+        // issues 一并返回：三层校验的结果要能直接显示在界面上，而不是只写进日志。
+        // source / migrated / problems 一并返回：界面必须能说清「现在读的是卡片还是旧 jsonl」，
+        // 以及迁移有没有生效 —— 这类状态靠猜就会变成一句含糊的「05_diagnosis」。
+        return send(res, 200, success({
+          graph: snapshot.graph, cases: snapshot.cases, issues: snapshot.issues,
+          seeded: snapshot.seeded, migrated: snapshot.migrated, source: snapshot.source, problems: snapshot.problems,
+        }))
+      } },
+      { kind: 'exact' as const, path: '/diagnosis/cases', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const resolved = resolveBase(query(req).searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        return send(res, 200, success({ cases: (await storeOf(resolved.runtime).snapshot()).cases }))
+      } },
+      { kind: 'prefix' as const, path: '/knowledge', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        const method = req.method ?? 'GET'
+        try {
+          const url = query(req)
+          const segments = pathSegments(url.pathname)
+          const rest = segments[0] === 'knowledge' ? segments.slice(1) : []
+          if (rest.length === 0) return send(res, 404, envelopeError('NOT_FOUND', 'knowledge endpoint 不存在'))
+
+          // 兼容旧路径：POST /knowledge/feedback、/knowledge/rebuild
+          if (rest.length === 1 && rest[0] === 'feedback') {
+            if (method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'))
+            const body = await readBody(req)
+            return sendEnvelope(res, await withRuntime(body.kb, target => target.recordFeedback(body)))
+          }
+          if (rest.length === 1 && rest[0] === 'rebuild') {
+            if (method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'))
+            const body = await readBody(req)
+            return sendEnvelope(res, await withRuntime(body.kb, target => target.rebuild(body.only ?? 'all', lineageOf(body))))
+          }
+
+          // ---------------------------------------------- /knowledge/bases
+          if (rest[0] === 'bases') {
+            if (rest.length === 1) {
+              if (method === 'GET') {
+                await bases.refresh()
+                return send(res, 200, success({ bases: bases.list(), defaultBaseId: bases.defaultId }))
+              }
+              if (method === 'POST') {
+                const body = await readBody(req)
+                try {
+                  const base = await bases.create({ name: body.name, description: body.description, rootDir: body.rootDir })
+                  await bases.refresh(base.id)
+                  return send(res, 200, success({ base: bases.get(base.id) ?? base }))
+                } catch (cause) {
+                  const code = cause instanceof Error ? cause.message : String(cause)
+                  if (code === 'NAME_REQUIRED') return sendEnvelope(res, failure({}, 'NAME_REQUIRED', 'name 不能为空', false))
+                  return send(res, 400, envelopeError('REQUEST_INVALID', code))
+                }
+              }
+              return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 支持 GET 或 POST'))
+            }
+            const baseId = rest[1]!
+            if (rest.length === 2) {
+              if (method === 'PATCH') {
+                const body = await readBody(req)
+                const updated = await bases.update(baseId, { name: body.name, description: body.description, sourceTypes: body.sourceTypes as SourceTypeDef[] | undefined, wikiTypes: body.wikiTypes as WikiTypeDef[] | undefined, wikiSchemaMode: body.wikiSchemaMode as WikiSchemaMode | undefined, resetWikiTypes: body.resetWikiTypes === true })
+                if (!updated.ok) return sendEnvelope(res, updated)
+                return send(res, 200, success({ base: updated.data }, updated.warnings))
+              }
+              if (method === 'DELETE') {
+                const removed = await bases.remove(baseId)
+                if (!removed.ok) return sendEnvelope(res, removed)
+                return send(res, 200, success({ deleted: true as const }))
+              }
+              return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 支持 PATCH 或 DELETE'))
+            }
+            if (rest.length === 4 && rest[2] === 'source-types') {
+              if (method !== 'DELETE') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 DELETE'))
+              const removed = await bases.removeSourceType(baseId, rest[3]!)
+              if (!removed.ok) return sendEnvelope(res, removed)
+              return send(res, 200, success({ deleted: true as const }))
+            }
+            return send(res, 404, envelopeError('NOT_FOUND', 'knowledge endpoint 不存在'))
+          }
+
+          // ----------------------------------------- /knowledge/source-types
+          // 来源业务分类注册表（0013）。读接口给设置面板和 Agent 共用：返回注册表
+          // 加上那段**内置只读**的判定提示词；写接口只动当前知识库的注册表。
+          if (rest[0] === 'source-types') {
+            const kbParam = url.searchParams.get('kb')
+            if (rest.length === 1) {
+              if (method === 'GET') {
+                const resolved = resolveBase(kbParam)
+                if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+                return send(res, 200, resolved.runtime.sourceTypeCatalog())
+              }
+              if (method === 'POST') {
+                const body = await readBody(req)
+                const id = kbIdOf(body.kb ?? kbParam)
+                const created = await bases.addSourceType(id, body as SourceTypeDraft)
+                if (!created.ok) return sendEnvelope(res, created)
+                return send(res, 200, success({ type: created.data }))
+              }
+              return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 支持 GET 或 POST'))
+            }
+            const typeId = rest[1]!
+            if (method === 'PATCH') {
+              const body = await readBody(req)
+              const id = kbIdOf(body.kb ?? kbParam)
+              const updated = await bases.updateSourceType(id, typeId, body as SourceTypeDraft)
+              if (!updated.ok) return sendEnvelope(res, updated)
+              return send(res, 200, success({ type: updated.data }))
+            }
+            if (method === 'DELETE') {
+              const id = kbIdOf(kbParam)
+              const removed = await bases.removeSourceType(id, typeId)
+              if (!removed.ok) return sendEnvelope(res, removed)
+              return send(res, 200, success({ deleted: true as const }))
+            }
+            return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 支持 PATCH 或 DELETE'))
+          }
+
+          // -------------------------------------------- /knowledge/wiki-types
+          // Wiki 卡片类型注册表（0024）。读接口给设置面板和 Agent 共用：返回类型定义、
+          // 模板卡、内置只读判定规则，以及现有卡片的三层校验结果。
+          if (rest[0] === 'wiki-types') {
+            const kbParam = url.searchParams.get('kb')
+            if (rest.length === 1) {
+              if (method === 'GET') {
+                const resolved = resolveBase(kbParam)
+                if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+                return send(res, 200, await resolved.runtime.wikiTypeCatalog())
+              }
+              if (method === 'POST') {
+                const body = await readBody(req)
+                const id = kbIdOf(body.kb ?? kbParam)
+                const created = await bases.addWikiType(id, body)
+                if (!created.ok) return sendEnvelope(res, created)
+                return send(res, 200, success({ type: created.data }))
+              }
+              return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 支持 GET 或 POST'))
+            }
+            const typeId = rest[1]!
+            if (method === 'PATCH') {
+              const body = await readBody(req)
+              const id = kbIdOf(body.kb ?? kbParam)
+              const updated = await bases.updateWikiType(id, typeId, body)
+              if (!updated.ok) return sendEnvelope(res, updated)
+              return send(res, 200, success({ type: updated.data }))
+            }
+            if (method === 'DELETE') {
+              const id = kbIdOf(kbParam)
+              const removed = await bases.removeWikiType(id, typeId)
+              if (!removed.ok) return sendEnvelope(res, removed)
+              return send(res, 200, success({ deleted: true as const }))
+            }
+            return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 支持 PATCH 或 DELETE'))
+          }
+
+          // ----------------------------------------------- /knowledge/cards
+          // wiki 卡片详情与版本（0025）。列表走上面的 exact 路由；这里只处理
+          // `/cards/:entityId` 及其 `/versions`、`/revert` 子路径 —— 卡片和
+          // SourceRaw 一样有历史，用户点开一张卡片要能看到它被改过几次。
+          if (rest[0] === 'cards' && rest.length >= 2) {
+            const kbParam = url.searchParams.get('kb')
+            const resolved = resolveBase(kbParam)
+            if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+            const entityId = decodeURIComponent(rest[1]!)
+            const entityType = (url.searchParams.get('entity_type') ?? undefined) as SchemaType | undefined
+            if (rest.length === 2) {
+              if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
+              const card = await resolved.runtime.readCard(entityId, entityType)
+              if (!card) return sendEnvelope(res, failure({}, 'CARD_NOT_FOUND', `知识卡片不存在: ${entityId}`, true))
+              return send(res, 200, success({ card }))
+            }
+            if (rest.length === 3 && rest[2] === 'versions') {
+              if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
+              const versions = await resolved.runtime.listCardVersions(entityId, entityType)
+              if (versions.length === 0) return sendEnvelope(res, failure({}, 'CARD_NOT_FOUND', `知识卡片不存在: ${entityId}`, true))
+              return send(res, 200, success({ versions }))
+            }
+            if (rest.length === 3 && rest[2] === 'revert') {
+              if (method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'))
+              const body = await readBody(req)
+              const reverted = await resolved.runtime.revertCard(entityId, String(body.versionId ?? ''), entityType)
+              if (!reverted.ok) return sendEnvelope(res, reverted)
+              return send(res, 200, success({ card: reverted.data }))
+            }
+            return send(res, 404, envelopeError('NOT_FOUND', 'knowledge endpoint 不存在'))
+          }
+
+          // ------------------------------------------- /knowledge/documents
+          if (rest[0] === 'documents') {
+            const kbParam = url.searchParams.get('kb')
+            if (rest.length === 1) {
+              if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
+              const resolved = resolveBase(kbParam)
+              if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+              let documents = await resolved.runtime.listDocuments()
+              const sourceType = url.searchParams.get('source_type')
+              if (sourceType) documents = documents.filter(item => item.sourceType === sourceType)
+              const search = (url.searchParams.get('query') ?? '').trim().toLocaleLowerCase()
+              if (search) documents = documents.filter(item => `${item.docId}\n${item.title}\n${item.externalId}`.toLocaleLowerCase().includes(search))
+              const total = documents.length
+              const offset = clampInt(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER)
+              const limit = clampInt(url.searchParams.get('limit'), 50, 1, 500)
+              return send(res, 200, success({ documents: documents.slice(offset, offset + limit), total }))
+            }
+            const docId = rest[1]!
+            const resolved = resolveBase(kbParam)
+            if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+            if (rest.length === 2) {
+              if (method === 'GET') {
+                const document = await resolved.runtime.readDocument(docId)
+                if (!document) return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true))
+                return send(res, 200, success({ document }))
+              }
+              if (method === 'DELETE') {
+                const deleted = await resolved.runtime.deleteDocument(docId)
+                if (!deleted.ok) return sendEnvelope(res, deleted)
+                return send(res, 200, success({ deleted: true as const }))
+              }
+              return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 支持 GET 或 DELETE'))
+            }
+            if (rest.length === 3 && rest[2] === 'versions') {
+              if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
+              const versions = await resolved.runtime.listVersions(docId)
+              if (versions.length === 0) return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true))
+              return send(res, 200, success({ versions }))
+            }
+            if (rest.length === 3 && rest[2] === 'revert') {
+              if (method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'))
+              const body = await readBody(req)
+              const reverted = await resolved.runtime.revertDocument(docId, String(body.versionId ?? ''))
+              if (!reverted.ok) return sendEnvelope(res, reverted)
+              return send(res, 200, success({ document: reverted.data }))
+            }
+            return send(res, 404, envelopeError('NOT_FOUND', 'knowledge endpoint 不存在'))
+          }
+
+          // ---------------------------------------------- /knowledge/assets
+          if (rest[0] === 'assets') {
+            if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
+            if (rest.length < 3) return send(res, 404, envelopeError('NOT_FOUND', 'asset 路径不完整'))
+            const base = bases.get(rest[1]!)
+            if (!base) return sendEnvelope(res, failure({}, 'BASE_NOT_FOUND', `知识库不存在: ${rest[1]}`, true))
+            const rootDir = resolve(base.rootDir)
+            const absolute = resolve(rootDir, ...rest.slice(2))
+            const withinRoot = absolute === rootDir || absolute.startsWith(rootDir.endsWith(sep) ? rootDir : `${rootDir}${sep}`)
+            if (!withinRoot) return sendEnvelope(res, failure({}, 'ASSET_NOT_FOUND', 'asset 路径越界', false))
+            try {
+              const details = await stat(absolute)
+              if (!details.isFile()) throw new Error('NOT_A_FILE')
+              res.statusCode = 200
+              res.setHeader('content-type', ASSET_CONTENT_TYPES[extname(absolute).toLowerCase()] ?? 'application/octet-stream')
+              res.setHeader('content-length', String(details.size))
+              res.setHeader('cache-control', 'private, max-age=60')
+              await new Promise<void>(resolvePromise => {
+                const stream = createReadStream(absolute)
+                stream.on('error', () => { res.destroy(); resolvePromise() })
+                stream.on('close', () => resolvePromise())
+                stream.pipe(res)
+              })
+              return
+            } catch {
+              return sendEnvelope(res, failure({}, 'ASSET_NOT_FOUND', `asset 不存在: ${rest.slice(2).join('/')}`, true))
+            }
+          }
+
+          return send(res, 404, envelopeError('NOT_FOUND', 'knowledge endpoint 不存在'))
+        } catch (cause) { return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause))) }
+      } },
+    ]
+    const disposers = routes.map(register)
+    return () => { runtime.close(); for (const dispose of disposers) void dispose() }
+  })
+}