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

package/src/knowledge-bases.ts

@@ -0,0 +1,1160 @@
+/**
+ * 多知识库注册表（0021）。
+ *
+ * 产品参照 WeKnora：**一个知识库 = 独立配置 + 独立内容**。每个库有自己的
+ * `rootDir`（沿用既有的 `01_source_truth` / `02_wiki` / `03_compiled` /
+ * `04_memory` 布局）和一套「文件类型 → 解析引擎」规则；库下面挂文档列表、
+ * 文档详情与版本历史。
+ *
+ * 0029：库的 `rootDir` 不再是各写各的自由路径，而是**从 Tita Agent 根路径推出来的
+ * 一格**：`<agentRoot>/domain_knowledge/<库 id>`。注册表因此不再需要用户为每个库
+ * 挑一个目录 —— 见 `layout.ts` 的三条原理。
+ *
+ * 注册表本身只持久化**配置**（id / name / description / rootDir / sourceTypes / wikiTypes），
+ * 落到 `<dataHome>/knowledge-bases.json`，`dataHome =
+ * process.env.TITA_DATA_AGENT_HOME || ~/.tita-data-agent`。
+ * `sourceCount` / `cardCount` / `noteCount` / `buildVersion` 和每条分类/类型的
+ * 计数都是**计算字段**，缓存在同一个 JSON 里，由 `refresh()` 从真实
+ * runtime 重新统计；这样 `list()` / `get()` 保持同步签名（前端首屏直接用），
+ * 路由在返回前 `await refresh()` 拿到准确值。
+ *
+ * 默认库 id 固定为 `default`，其 `rootDir` 始终来自 `defaultRootDir()`
+ * （即插件设置里的 `agentRoot` 推出来的那一格），因此旧接口 / 旧工具不传 `kb`
+ * 时行为完全不变。
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import {
+  BUILTIN_SOURCE_TYPES, defaultSourceTypes, FALLBACK_SOURCE_TYPE, isBuiltinSourceType,
+  MAX_SOURCE_TYPES, SOURCE_TYPE_ID_PATTERN, validateSourceTypeDraft, validateSourceTypeText, WIKI_TYPE_ID_PATTERN,
+  type Envelope, type KnowledgeBase, type KnowledgeConfig,
+  type SourceTypeDef, type SourceTypeDraft, type WikiSchemaMode, type WikiTypeDef,
+} from './types.js'
+import {
+  defaultWikiTypes, isBuiltinWikiType, parseFieldLines, parseSectionLines, templateCardFor,
+  validateWikiTypeDraft, validateWikiTypeText, type WikiTypeDraft,
+} from './wiki-types.js'
+import { defaultKnowledgeRoot, failure, KnowledgeRuntime, success } from './runtime.js'
+import { knowledgeBaseRoot, memoryRoot } from './layout.js'
+
+/** 持久化形态：配置 + 计算字段缓存分区。 */
+interface KnowledgeBaseRecord {
+  id: string
+  name: string
+  description: string
+  rootDir: string
+  isDefault: boolean
+  sourceTypes: SourceTypeDef[]
+  /** Wiki 卡片类型注册表（0024）。 */
+  wikiTypes: WikiTypeDef[]
+  /** `report` 只标记问题，`strict` 拒绝不合规的写入。 */
+  wikiSchemaMode: WikiSchemaMode
+  createdAt: string
+  updatedAt: string
+}
+
+interface BaseStats {
+  sourceCount: number
+  cardCount: number
+  noteCount: number
+  buildVersion: number
+  /** typeId → 该库中引用该来源分类的文档数。 */
+  sourceTypes: Record<string, number>
+  /** wikiTypeId → 该库中该类型的卡片数。 */
+  wikiTypes: Record<string, number>
+}
+
+/**
+ * 默认知识库的 id。
+ *
+ * 导出成常量而不是只放在类字段上：`index.ts` 里 `runtimeOptions()` 会被
+ * **`bases` 构造之前**调用一次（默认库的 runtime 要先于注册表存在，因为注册表要
+ * 复用它），那时读 `bases.defaultId` 会撞上 TDZ。id 本身是契约的一部分，本来就
+ * 不该只挂在一个实例上。
+ */
+export const DEFAULT_KB_ID = 'default'
+
+export interface KnowledgeBasesOptions {
+  /** 覆盖 `~/.tita-data-agent`；测试用临时目录，避免写用户主目录。 */
+  dataHome?: string
+  /** 默认库的根目录来源；插件传入由 `agentRoot` 推出来的那一格。 */
+  defaultRootDir?: () => string
+  /**
+   * Tita Agent 根路径来源（0029）。给了它，**新建**的知识库就落在
+   * `<agentRoot>/domain_knowledge/<id>`；不给则退回旧行为
+   * （`<dataHome>/knowledge-bases/<id>`），这样只关心注册表逻辑的单元测试
+   * 不必先造一个根路径。
+   */
+  agentRoot?: () => string
+  /**
+   * 默认库已由宿主（settings 驱动）持有 runtime 时，复用它而不是另建一个，
+   * 否则同一个 rootDir 会被两个 runtime 同时写。
+   */
+  defaultRuntime?: () => KnowledgeRuntime
+  /** 非默认库的 runtime 配置来源（embedding / rerank / topK 等跟随插件设置）。 */
+  config?: () => Partial<Omit<KnowledgeConfig, 'rootDir' | 'agentRoot'>>
+  /**
+   * 覆盖注册表文件位置（默认 `<dataHome>/knowledge-bases.json`）。
+   *
+   * 可以是函数：0029 起它跟着 `agentRoot` 走（`<agentRoot>/resource/knowledge-bases.json`），
+   * 而 agentRoot 由设置决定、构造时还不知道。
+   */
+  registryFile?: string | (() => string)
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+/** 只接受"非空字符串"，其余一律回退。注册表里有大量 `unknown` 字段要走这里。 */
+function textOr(input: unknown, fallback: string): string {
+  return typeof input === 'string' && input.trim() ? input.trim() : fallback
+}
+
+function normalizeExt(value: unknown, fallback: string): string {
+  const text = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  const ext = text || fallback
+  return ext.startsWith('.') ? ext : `.${ext}`
+}
+
+/** 空的失败载荷：删除守卫失败时前端仍需一个可渲染的 base 形状。 */
+function emptyBase(id: string): KnowledgeBase {
+  return {
+    id, name: id, description: '', rootDir: '', isDefault: false, sourceTypes: [],
+    wikiTypes: [], wikiSchemaMode: 'report', wikiTypesCustomized: false,
+    createdAt: '', updatedAt: '', sourceCount: 0, cardCount: 0, noteCount: 0, buildVersion: 0,
+  }
+}
+
+async function writeTextAtomic(path: string, content: string): Promise<void> {
+  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
+  try {
+    await writeFile(temporary, content, 'utf8')
+    await rename(temporary, path)
+  } finally {
+    try { await unlink(temporary) } catch { /* rename already consumed it */ }
+  }
+}
+
+export function defaultDataHome(): string {
+  return resolve(process.env.TITA_DATA_AGENT_HOME || join(homedir(), '.tita-data-agent'))
+}
+
+export class KnowledgeBases {
+  readonly defaultId = DEFAULT_KB_ID
+  private readonly dataHome: string
+  /** 路径来源可以是函数（跟着 agentRoot 走），所以现算。 */
+  private resolveRegistry(): string {
+    const configured = this.options.registryFile
+    const value = typeof configured === 'function' ? configured() : configured
+    return resolve(value || join(this.dataHome, 'knowledge-bases.json'))
+  }
+  /**
+   * **实际在用**的注册表文件。
+   *
+   * 由 `repoint()` 决定，`ensureLoaded()` 与 `persist()` 都读它。之所以不能每次都现算：
+   * 家当搬迁失败时（跨卷等）我们要**留在旧位置**，而「留在哪」必须是一个被记住的
+   * 决定，不能每次重新推导 —— 否则读在旧位置、写在新的，两边就分叉了。
+   */
+  private activeRegistry = ''
+  /** 实际在用的注册表文件；`repoint()` 还没跑过时就是配置算出来的那个。 */
+  private get registryPath(): string { return this.activeRegistry || this.resolveRegistry() }
+  private readonly options: KnowledgeBasesOptions
+  private records: KnowledgeBaseRecord[] = []
+  private stats = new Map<string, BaseStats>()
+  /** runtime 缓存按 rootDir 建键，两个库共用目录时也就共用 runtime。 */
+  private readonly runtimes = new Map<string, KnowledgeRuntime>()
+  private loaded = false
+
+  constructor(options: KnowledgeBasesOptions = {}) {
+    this.options = options
+    this.dataHome = resolve(options.dataHome || defaultDataHome())
+  }
+
+  /**
+   * 注册表位置变了就重新读一遍（0029：它跟着 `agentRoot` 走）。
+   *
+   * 位置没变时是空操作。变了的场景只有一个：用户改了根路径，于是注册表要跟着
+   * 搬过去 —— 那时旧位置的记录必须丢掉，否则会出现「两个库列表叠在一起」。
+   * 缓存的 runtime 一并关掉：它们的 `rootDir` 是按旧 agentRoot 算的。
+   */
+  async repoint(): Promise<void> {
+    const next = this.resolveRegistry()
+    // 只在**已经决定过**的前提下才早退：`activeRegistry` 还是空的时候，「当前路径」
+    // 就是配置算出来的 `next`，拿它做相等判断会让第一次 repoint 直接返回 ——
+    // 于是下面的回退分支永远走不到，注册表也就永远切不过去。
+    if (this.activeRegistry && this.activeRegistry === next) return
+    /**
+     * 新位置还没有注册表、旧位置有 → **留在旧位置**。
+     *
+     * 这正是「家当搬迁失败」的样子（跨卷时我们刻意不自动复制几个 GB）。这时如果
+     * 一头扎到新路径，用户会看到一个**空的知识库列表** —— 数据没丢，但界面说丢了，
+     * 这是最糟的失败方式。留在旧位置至少是可用的。
+     */
+    const legacy = resolve(join(this.dataHome, 'knowledge-bases.json'))
+    if (!existsSync(next) && existsSync(legacy)) {
+      this.activeRegistry = legacy
+    } else {
+      this.activeRegistry = next
+    }
+    for (const runtime of this.runtimes.values()) runtime.close()
+    this.runtimes.clear()
+    this.records = []
+    this.stats.clear()
+    this.loaded = false
+    this.ensureLoaded()
+  }
+
+  // ------------------------------------------------------------- 读路径（同步）
+
+  list(): KnowledgeBase[] {
+    this.ensureLoaded()
+    return this.records.map(item => this.view(item))
+  }
+
+  get(id: string): KnowledgeBase | undefined {
+    this.ensureLoaded()
+    const found = this.records.find(item => item.id === id)
+    return found ? this.view(found) : undefined
+  }
+
+  /**
+   * 某个知识库的 runtime（按 rootDir 缓存）。
+   *
+   * 未知 id 抛 `BASE_NOT_FOUND`（契约签名是同步返回 runtime，没有 Envelope
+   * 可承载错误）；路由先用 `get()` 做 404 判定。
+   */
+  runtimeOf(id: string): KnowledgeRuntime {
+    const base = this.requireRecord(id)
+    const key = base.rootDir
+    const cached = this.runtimes.get(key)
+    if (cached) return cached
+    const runtime = base.isDefault && this.options.defaultRuntime
+      ? this.options.defaultRuntime()
+      : new KnowledgeRuntime(base.rootDir, this.options.config?.() ?? {}, {
+        sourceTypes: () => this.sourceTypesOf(base.id),
+        wikiSchema: () => ({ types: this.wikiTypesOf(base.id), mode: base.wikiSchemaMode }),
+        // 0032：记忆段跟着**这个库**走，二级用 id。`agentRoot` 没给时（只测注册表
+        // 逻辑的单元测试）留空，runtime 会退回知识树里的 `04_memory`。
+        ...(this.options.agentRoot ? { memoryRoot: memoryRoot(this.options.agentRoot(), base.id) } : {}),
+      })
+    runtime.baseId = base.id
+    this.runtimes.set(key, runtime)
+    return runtime
+  }
+
+  /**
+   * 设置变化后调用：关掉并丢弃非默认库的 runtime，下次 `runtimeOf` 会用新的
+   * embedding / rerank 配置重建。默认库由宿主自己重建，这里不动。
+   */
+  invalidate(): void {
+    const keep = resolve(this.defaultRootDir())
+    for (const [key, runtime] of this.runtimes) {
+      if (key === keep) continue
+      runtime.close()
+      this.runtimes.delete(key)
+    }
+  }
+
+  closeAll(): void {
+    for (const runtime of this.runtimes.values()) runtime.close()
+    this.runtimes.clear()
+  }
+
+  // ------------------------------------------------------------- 统计刷新
+
+  /**
+   * 从真实 runtime 重新统计一个（或全部）知识库的 sourceCount / cardCount /
+   * noteCount / buildVersion 与每条规则的 fileCount，并落盘缓存。
+   * 目录不可读时保留上一次统计，不抛错、不谎报 0。
+   */
+  async refresh(id?: string): Promise<void> {
+    this.ensureLoaded()
+    for (const item of this.records) {
+      if (id !== undefined && item.id !== id) continue
+      await this.refreshOne(item)
+    }
+    await this.persist()
+  }
+
+  private async refreshOne(base: KnowledgeBaseRecord): Promise<void> {
+    const runtime = this.runtimeOf(base.id)
+    try {
+      const [summary, documents, cards] = await Promise.all([runtime.stats(), runtime.listDocuments(), runtime.loadCards()])
+      // sourceCount 同理：按文档**实际**写在 frontmatter 里的分类计数，而不是按
+      // 注册表里还剩下的分类计数。否则手工改坏的分类会被统计成 0，删除守卫就形同虚设。
+      const sourceTypes: Record<string, number> = {}
+      for (const def of base.sourceTypes) sourceTypes[def.id] = 0
+      for (const document of documents) sourceTypes[document.sourceType] = (sourceTypes[document.sourceType] ?? 0) + 1
+      // wikiType 的 cardCount 同理：按卡片**实际**写的 entity_type 计数，未知类型也算，
+      // 否则"未登记类型"的卡片会在界面上凭空消失。
+      const wikiTypes: Record<string, number> = {}
+      for (const def of base.wikiTypes) wikiTypes[def.id] = 0
+      for (const card of cards) wikiTypes[card.entityType] = (wikiTypes[card.entityType] ?? 0) + 1
+      this.stats.set(base.id, {
+        sourceCount: Number(summary.sourceCount ?? documents.length),
+        cardCount: Number(summary.cards ?? 0),
+        noteCount: Number(summary.notes ?? 0),
+        buildVersion: Number(summary.buildVersion ?? 0),
+        sourceTypes,
+        wikiTypes,
+      })
+    } catch { /* 保留上一次统计 */ }
+  }
+
+  // ------------------------------------------------------------- 写路径
+
+  /**
+   * 新建知识库。名字为空时抛 `NAME_REQUIRED`（契约签名返回裸
+   * `KnowledgeBase`，没有 Envelope 可承载错误，路由捕获后转 400）。
+   * `rootDir` 缺省为 `<agentRoot>/domain_knowledge/<id>`（0029）；没接根路径时
+   * 退回 `<dataHome>/knowledge-bases/<id>`。
+   */
+  async create(input: { name: string; description?: string; rootDir?: string }): Promise<KnowledgeBase> {
+    this.ensureLoaded()
+    const name = typeof input?.name === 'string' ? input.name.trim() : ''
+    if (!name) throw new Error('NAME_REQUIRED')
+    const id = this.nextId(name)
+    const agentRoot = this.options.agentRoot?.()
+    const rootDir = typeof input.rootDir === 'string' && input.rootDir.trim()
+      ? resolve(input.rootDir.trim())
+      : agentRoot
+        ? knowledgeBaseRoot(agentRoot, id)
+        : join(this.dataHome, 'knowledge-bases', id)
+    const now = new Date().toISOString()
+    const base: KnowledgeBaseRecord = {
+      id,
+      name,
+      description: typeof input.description === 'string' ? input.description.trim() : '',
+      rootDir,
+      isDefault: false,
+      sourceTypes: defaultSourceTypes(),
+      wikiTypes: defaultWikiTypes(),
+      wikiSchemaMode: 'report',
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.records.push(base)
+    await mkdir(rootDir, { recursive: true })
+    await this.persist()
+    return this.view(base)
+  }
+
+  /**
+   * 更新名称 / 描述 / 来源类型注册表 / Wiki 类型注册表。
+   *
+   * `patch.fileTypes` 与 `patch.sourceTypes` 都是**完整的期望列表**：凡是提供了
+   * 列表却丢掉了某个「在用」的条目，就返回 `*_IN_USE` 并且**整体不写入**（不做
+   * 部分更新），这样前端不会出现「名称改了、规则没删掉」的半成品状态。
+   *
+   * `sourceTypes` 另有三条注册表专属守卫（0013）：内置分类不允许删除（缺失即
+   * 恢复，并给出 warning）、兜底分类 `document` 不允许停用、新建自定义分类必须
+   * 提交完整判定文案。
+   */
+  async update(id: string, patch: { name?: string; description?: string; sourceTypes?: SourceTypeDef[]; wikiTypes?: WikiTypeDef[]; wikiSchemaMode?: WikiSchemaMode; resetWikiTypes?: boolean }): Promise<Envelope<KnowledgeBase>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure(emptyBase(id), 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    // 守卫必须基于精确的实时计数，不能用可能过期的缓存。
+    await this.refreshOne(base)
+    let sourceTypes: SourceTypeDef[] | undefined
+    let sourceWarnings: string[] = []
+    if (patch.sourceTypes !== undefined) {
+      if (!Array.isArray(patch.sourceTypes)) return failure(this.view(base), 'SOURCE_TYPES_INVALID', 'sourceTypes 必须是 SourceTypeDef 数组', false)
+      const merged = this.mergeSourceTypes(base, patch.sourceTypes)
+      if ('error' in merged) return failure(this.view(base), merged.error.code, merged.error.message, false, merged.error.suggestion)
+      sourceTypes = merged.types
+      sourceWarnings = merged.warnings
+    }
+    if (patch.name !== undefined) {
+      const name = String(patch.name).trim()
+      if (!name) return failure(this.view(base), 'NAME_REQUIRED', 'name 不能为空', false)
+      base.name = name
+    }
+    let wikiTypes: WikiTypeDef[] | undefined
+    let wikiWarnings: string[] = []
+    if (patch.wikiTypes !== undefined) {
+      if (!Array.isArray(patch.wikiTypes)) return failure(this.view(base), 'WIKI_TYPES_INVALID', 'wikiTypes 必须是 WikiTypeDef 数组', false)
+      const merged = this.mergeWikiTypes(base, patch.wikiTypes)
+      if ('error' in merged) return failure(this.view(base), merged.error.code, merged.error.message, false, merged.error.suggestion)
+      wikiTypes = merged.types
+      wikiWarnings = merged.warnings
+    }
+    if (patch.resetWikiTypes === true) base.wikiTypes = defaultWikiTypes()
+    if (patch.description !== undefined) base.description = String(patch.description)
+    if (sourceTypes !== undefined) base.sourceTypes = sourceTypes
+    if (wikiTypes !== undefined) base.wikiTypes = wikiTypes
+    if (patch.wikiSchemaMode !== undefined) base.wikiSchemaMode = patch.wikiSchemaMode === 'strict' ? 'strict' : 'report'
+    base.updatedAt = new Date().toISOString()
+    await this.refreshOne(base)
+    await this.persist()
+    return success(this.view(base), [...sourceWarnings, ...wikiWarnings])
+  }
+
+  // ------------------------------------------------- 来源分类注册表（0013）
+
+  /** 某个知识库当前生效的分类注册表（含 `sourceCount`）。供 runtime provider 使用。 */
+  sourceTypesOf(id: string): SourceTypeDef[] {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return defaultSourceTypes()
+    const counts = this.stats.get(base.id)?.sourceTypes ?? {}
+    return base.sourceTypes.map(def => ({ ...def, sourceCount: counts[def.id] ?? 0 }))
+  }
+
+  /**
+   * 新增一个自定义分类。
+   *
+   * 必须先满足判定文案要求（`validateSourceTypeDraft`）——0013 的「用户追加新
+   * 类型时要用文字标明怎么判断」在这里落成硬校验：没有 `description` /
+   * 至少 2 条 `signals` / 至少 1 条指向已知分类的 `excludes`，一律不进注册表。
+   */
+  async addSourceType(id: string, draft: SourceTypeDraft): Promise<Envelope<SourceTypeDef>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure({} as SourceTypeDef, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    const typeId = typeof draft?.id === 'string' ? draft.id.trim() : ''
+    if (base.sourceTypes.some(def => def.id === typeId)) {
+      return failure({} as SourceTypeDef, 'SOURCE_TYPE_EXISTS', `分类已存在: ${typeId}`, false, '改语义请编辑现有分类，或换一个 id。')
+    }
+    const customs = base.sourceTypes.filter(def => !def.builtin)
+    if (customs.length >= MAX_SOURCE_TYPES - BUILTIN_SOURCE_TYPES.length) {
+      return failure({} as SourceTypeDef, 'SOURCE_TYPE_LIMIT', `自定义分类最多 ${MAX_SOURCE_TYPES - BUILTIN_SOURCE_TYPES.length} 个`, false)
+    }
+    const known = new Set(base.sourceTypes.map(def => def.id))
+    const problem = validateSourceTypeDraft(draft, known)
+    if (!problem.ok) return failure({} as SourceTypeDef, problem.code, problem.message, false, problem.suggestion)
+    const created: SourceTypeDef = {
+      id: typeId,
+      label: String(draft.label).trim(),
+      description: String(draft.description).trim(),
+      signals: (draft.signals as unknown[]).map(item => String(item).trim()).filter(Boolean),
+      excludes: (draft.excludes as unknown[]).map(item => String(item).trim()).filter(Boolean),
+      enabled: draft.enabled !== false,
+      builtin: false,
+      fallback: false,
+      sourceCount: 0,
+    }
+    base.sourceTypes = [...base.sourceTypes, created]
+    base.updatedAt = new Date().toISOString()
+    await this.persist()
+    return success({ ...created, sourceCount: 0 })
+  }
+
+  /**
+   * 编辑一个分类的文案 / 启用状态。
+   *
+   * - 内置分类：可以改 `label` / `description` / `signals` / `excludes` / `enabled`；
+   * - 兜底分类 `document`：**不允许停用**（判定链最后一步落在它上）；
+   * - 自定义分类：同样可以改，`id` 永远锁定。
+   */
+  async updateSourceType(id: string, typeId: string, patch: SourceTypeDraft): Promise<Envelope<SourceTypeDef>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure({} as SourceTypeDef, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    const existing = base.sourceTypes.find(def => def.id === typeId)
+    if (!existing) return failure({} as SourceTypeDef, 'SOURCE_TYPE_NOT_FOUND', `来源分类不存在: ${typeId}`, true)
+    if (patch.enabled === false && existing.fallback) {
+      return failure({} as SourceTypeDef, 'SOURCE_TYPE_FALLBACK_REQUIRED', `兜底分类 ${existing.label}（${existing.id}）不能停用`, false, '判定链全不命中时必须有一个归属；请改用其他分类的启用状态。')
+    }
+    const merged: SourceTypeDraft = {
+      id: existing.id,
+      label: patch.label ?? existing.label,
+      description: patch.description ?? existing.description,
+      signals: patch.signals ?? existing.signals,
+      excludes: patch.excludes ?? existing.excludes,
+      enabled: patch.enabled === undefined ? existing.enabled : patch.enabled !== false,
+    }
+    const known = new Set(base.sourceTypes.map(def => def.id))
+    const problem = validateSourceTypeText(merged, known)
+    if (!problem.ok) return failure({} as SourceTypeDef, problem.code, problem.message, false, problem.suggestion)
+    const next: SourceTypeDef = {
+      ...existing,
+      label: String(merged.label).trim(),
+      description: String(merged.description).trim(),
+      signals: (merged.signals as unknown[]).map(item => String(item).trim()).filter(Boolean),
+      excludes: (merged.excludes as unknown[]).map(item => String(item).trim()).filter(Boolean),
+      enabled: merged.enabled === true,
+    }
+    base.sourceTypes = base.sourceTypes.map(def => def.id === typeId ? next : def)
+    base.updatedAt = new Date().toISOString()
+    await this.persist()
+    return success(next)
+  }
+
+  /**
+   * 删除知识库。
+   *
+   * 只删注册表条目，**不动磁盘内容**（删用户文档是不可逆的，必须先显式清空文档，
+   * 这也是 `BASE_IN_USE` 守卫的另一半含义）。默认库拒绝删除。
+   */
+  async remove(id: string): Promise<Envelope<{ deleted: true }>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure({ deleted: true }, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    if (base.isDefault || base.id === this.defaultId) return failure({ deleted: true }, 'BASE_IS_DEFAULT', '默认知识库不能删除', false)
+    let documentCount = 0
+    try { documentCount = (await this.runtimeOf(base.id).listDocuments()).length } catch { /* 目录不可读则按空处理 */ }
+    if (documentCount > 0) return failure({ deleted: true }, 'BASE_IN_USE', `知识库下还有 ${documentCount} 个文档，先清空再删除`, false, '文档接口 DELETE /knowledge/documents/:docId 可逐个删除。')
+    this.records = this.records.filter(item => item.id !== id)
+    this.runtimes.get(base.rootDir)?.close()
+    this.runtimes.delete(base.rootDir)
+    this.stats.delete(id)
+    await this.persist()
+    return success({ deleted: true })
+  }
+
+  /**
+   * 删除一个来源分类（0013）。
+   *
+   * 三层守卫，顺序即优先级：
+   * 1. 内置分类**不允许删除**（只能停用）；
+   * 2. 兜底分类**不允许删除**（它必须永远存在）；
+   * 3. 该分类下还有来源（`sourceCount > 0`）→ `SOURCE_TYPE_IN_USE`，先迁移再删。
+   */
+  async removeSourceType(id: string, typeId: string): Promise<Envelope<{ deleted: true }>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure({ deleted: true }, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    const def = base.sourceTypes.find(item => item.id === typeId)
+    if (!def) return failure({ deleted: true }, 'SOURCE_TYPE_NOT_FOUND', `来源分类不存在: ${typeId}`, true)
+    if (def.builtin) {
+      return failure({ deleted: true }, 'SOURCE_TYPE_BUILTIN_LOCKED', `内置分类不可删除: ${def.label}（${def.id}）`, false, '内置分类只允许停用；确要换语义请新建一个自定义分类。')
+    }
+    if (def.fallback) {
+      return failure({ deleted: true }, 'SOURCE_TYPE_FALLBACK_REQUIRED', `兜底分类不可删除: ${def.label}（${def.id}）`, false)
+    }
+    await this.refreshOne(base)
+    const count = this.stats.get(base.id)?.sourceTypes?.[typeId] ?? 0
+    if (count > 0) {
+      return failure({ deleted: true }, 'SOURCE_TYPE_IN_USE', `该分类下还有 ${count} 个来源，先迁移再删除`, false, `把 /knowledge/documents?source_type=${typeId} 下的来源改到别的分类，或保留该分类。`)
+    }
+    base.sourceTypes = base.sourceTypes.filter(item => item.id !== typeId)
+    base.updatedAt = new Date().toISOString()
+    await this.persist()
+    return success({ deleted: true })
+  }
+
+  // ------------------------------------------------- Wiki 卡片类型注册表（0024）
+
+  /** 某个知识库当前生效的卡片类型（含 `cardCount`）。供 runtime provider 使用。 */
+  wikiTypesOf(id: string): WikiTypeDef[] {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return defaultWikiTypes()
+    const counts = this.stats.get(base.id)?.wikiTypes ?? {}
+    return base.wikiTypes.map(def => ({ ...def, cardCount: counts[def.id] ?? 0 }))
+  }
+
+  /** 卡片 schema 生效方式；未知 id 回退出厂值。 */
+  wikiSchemaModeOf(id: string): WikiSchemaMode {
+    this.ensureLoaded()
+    return this.records.find(item => item.id === id)?.wikiSchemaMode ?? 'report'
+  }
+
+  /**
+   * 新增一个卡片类型。
+   *
+   * 与 0013 的 source type 同一条要求：光给名字不让入库——`sections` / `fields` 会直接
+   * 变成"卡片该怎么写"的约束，也是模板卡的来源。
+   */
+  async addWikiType(id: string, draft: WikiTypeDraft): Promise<Envelope<WikiTypeDef>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure({} as WikiTypeDef, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    const typeId = typeof draft?.id === 'string' ? draft.id.trim() : ''
+    if (base.wikiTypes.some(def => def.id === typeId)) {
+      return failure({} as WikiTypeDef, 'WIKI_TYPE_EXISTS', `卡片类型已存在: ${typeId}`, false, '改语义请编辑现有类型，或换一个 id。')
+    }
+    const problem = validateWikiTypeDraft(draft, new Set(base.wikiTypes.map(def => def.id)))
+    if (!problem.ok) return failure({} as WikiTypeDef, problem.code, problem.message, false, problem.suggestion)
+    const created = this.wikiTypeFromDraft(typeId, draft)
+    base.wikiTypes = [...base.wikiTypes, created]
+    base.updatedAt = new Date().toISOString()
+    await this.persist()
+    return success({ ...created, cardCount: 0 })
+  }
+
+  /** 编辑一个卡片类型的文案 / 小节 / 字段 / 启停。内置类型也可以改，但 id 与 `builtin` 锁定。 */
+  async updateWikiType(id: string, typeId: string, patch: WikiTypeDraft & { enabled?: boolean }): Promise<Envelope<WikiTypeDef>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure({} as WikiTypeDef, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    const existing = base.wikiTypes.find(def => def.id === typeId)
+    if (!existing) return failure({} as WikiTypeDef, 'WIKI_TYPE_NOT_FOUND', `卡片类型不存在: ${typeId}`, true)
+    const merged: WikiTypeDraft = {
+      id: existing.id,
+      label: patch.label ?? existing.label,
+      description: patch.description ?? existing.description,
+      layer: patch.layer ?? existing.layer,
+      sections: patch.sections ?? existing.sections,
+      fields: patch.fields ?? existing.fields,
+      sourceTypes: patch.sourceTypes ?? existing.sourceTypes,
+      examples: patch.examples ?? existing.examples,
+    }
+    const problem = validateWikiTypeText(merged)
+    if (!problem.ok) return failure({} as WikiTypeDef, problem.code, problem.message, false, problem.suggestion)
+    const sections = parseSectionLines(merged.sections)
+    const fields = parseFieldLines(merged.fields)
+    const next: WikiTypeDef = {
+      ...existing,
+      label: String(merged.label).trim(),
+      description: String(merged.description).trim(),
+      layer: merged.layer === 'instance' ? 'instance' : 'type',
+      sections,
+      fields,
+      sourceTypes: this.stringList(merged.sourceTypes),
+      examples: this.stringList(merged.examples),
+      template: templateCardFor(sections, fields),
+      enabled: patch.enabled === undefined ? existing.enabled : patch.enabled !== false,
+    }
+    base.wikiTypes = base.wikiTypes.map(def => def.id === typeId ? next : def)
+    base.updatedAt = new Date().toISOString()
+    await this.persist()
+    return success(next)
+  }
+
+  /**
+   * 删除一个卡片类型。
+   *
+   * 两层守卫：内置类型不可删（只能停用）；该类型下还有卡片时不可删（先改卡片类型）。
+   */
+  async removeWikiType(id: string, typeId: string): Promise<Envelope<{ deleted: true }>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure({ deleted: true }, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    const def = base.wikiTypes.find(item => item.id === typeId)
+    if (!def) return failure({ deleted: true }, 'WIKI_TYPE_NOT_FOUND', `卡片类型不存在: ${typeId}`, true)
+    if (def.builtin) {
+      return failure({ deleted: true }, 'WIKI_TYPE_BUILTIN_LOCKED', `内置类型不可删除: ${def.label}（${def.id}）`, false, '内置类型只允许停用；确要换语义请新建一个自定义类型。')
+    }
+    await this.refreshOne(base)
+    const count = this.stats.get(base.id)?.wikiTypes?.[typeId] ?? 0
+    if (count > 0) {
+      return failure({ deleted: true }, 'WIKI_TYPE_IN_USE', `该类型下还有 ${count} 张卡片，先改类型再删除`, false, `把 entity_type=${typeId} 的卡片改成别的类型，或在 wikiTypes 里保留该类型。`)
+    }
+    base.wikiTypes = base.wikiTypes.filter(item => item.id !== typeId)
+    base.updatedAt = new Date().toISOString()
+    await this.persist()
+    return success({ deleted: true })
+  }
+
+  /** 切换卡片 schema 的生效方式（`report` 只标记，`strict` 拒绝不合规的写入）。 */
+  async setWikiSchemaMode(id: string, mode: WikiSchemaMode): Promise<Envelope<{ mode: WikiSchemaMode }>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure({ mode }, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    base.wikiSchemaMode = mode === 'strict' ? 'strict' : 'report'
+    base.updatedAt = new Date().toISOString()
+    await this.persist()
+    return success({ mode: base.wikiSchemaMode })
+  }
+
+  /** 把一条 draft 转成完整类型（模板卡由小节派生，不手写第二份）。 */
+  private wikiTypeFromDraft(typeId: string, draft: WikiTypeDraft): WikiTypeDef {
+    const sections = parseSectionLines(draft.sections)
+    const fields = parseFieldLines(draft.fields)
+    return {
+      id: typeId,
+      label: String(draft.label ?? typeId).trim(),
+      description: String(draft.description ?? '').trim(),
+      layer: draft.layer === 'instance' ? 'instance' : 'type',
+      sections,
+      fields,
+      sourceTypes: this.stringList(draft.sourceTypes),
+      examples: this.stringList(draft.examples),
+      template: templateCardFor(sections, fields),
+      enabled: true,
+      builtin: false,
+      cardCount: 0,
+    }
+  }
+
+  private stringList(value: unknown): string[] {
+    if (!Array.isArray(value)) return []
+    return [...new Set(value.map(item => (typeof item === 'string' ? item.trim() : '')).filter(Boolean))]
+  }
+
+  /**
+   * 把磁盘上的 `wikiTypes` 规整成**必定包含全部内置类型**的合法注册表。
+   *
+   * 与 `normalizeSourceTypes` 同一套语义：老配置（没有 `wikiTypes` 字段）升级时补齐内置，
+   * 缺失的内置类型被恢复（内置只允许停用，不允许删除）。
+   */
+  private normalizeWikiTypes(raw: unknown): WikiTypeDef[] {
+    const persisted = Array.isArray(raw) ? raw : []
+    const byId = new Map<string, Record<string, unknown>>()
+    for (const item of persisted) {
+      const value = record(item)
+      const id = typeof value.id === 'string' ? value.id.trim() : ''
+      if (!id || !WIKI_TYPE_ID_PATTERN.test(id) || byId.has(id)) continue
+      byId.set(id, value)
+    }
+    const defaults = defaultWikiTypes()
+    const builtins = defaults.map(def => {
+      const value = byId.get(def.id)
+      if (!value) return def
+      byId.delete(def.id)
+      return this.wikiTypeFromRecord(def, value)
+    })
+    const customs: WikiTypeDef[] = []
+    for (const [id, value] of byId) {
+      if (isBuiltinWikiType(id)) continue
+      const base: WikiTypeDef = { id, label: id, description: '', layer: 'type', sections: [], fields: [], sourceTypes: [], examples: [], template: '', enabled: true, builtin: false, cardCount: 0 }
+      const draft = this.wikiTypeFromRecord(base, value)
+      // 只有能写出骨架的自定义类型才值得留下；否则它既没有模板也校验不了。
+      if (validateWikiTypeText(draft).ok) customs.push(draft)
+    }
+    return [...builtins, ...customs]
+  }
+
+  /** 用一条持久化记录覆盖默认值；`builtin` / `id` 只信服务端。 */
+  private wikiTypeFromRecord(base: WikiTypeDef, value: Record<string, unknown>): WikiTypeDef {
+    const sections = parseSectionLines(value.sections)
+    const fields = parseFieldLines(value.fields)
+    return {
+      id: base.id,
+      label: textOr(value.label, base.label),
+      description: textOr(value.description, base.description),
+      layer: value.layer === 'instance' ? 'instance' : base.layer,
+      sections: sections.length > 0 ? sections : base.sections.map(section => ({ ...section })),
+      fields: Array.isArray(value.fields) ? fields : base.fields.map(field => ({ ...field })),
+      sourceTypes: Array.isArray(value.sourceTypes) ? this.stringList(value.sourceTypes) : [...base.sourceTypes],
+      examples: this.stringList(value.examples).length > 0 ? this.stringList(value.examples) : [...base.examples],
+      template: textOr(value.template, base.template),
+      enabled: value.enabled !== false,
+      builtin: base.builtin,
+      cardCount: 0,
+    }
+  }
+
+  /** `wikiTypes` 是否已偏离出厂定义（只看语义字段，不看计算字段）。 */
+  private wikiTypesDifferFromDefaults(types: WikiTypeDef[]): boolean {
+    const signature = (list: WikiTypeDef[]): string => JSON.stringify(list.map(def => ({
+      id: def.id, label: def.label, description: def.description, layer: def.layer, enabled: def.enabled,
+      sections: def.sections, fields: def.fields, sourceTypes: def.sourceTypes, examples: def.examples,
+    })))
+    const defaults = defaultWikiTypes()
+    if (types.length !== defaults.length) return true
+    return signature(types) !== signature(defaults)
+  }
+
+  /**
+   * 把 `wikiTypes` 恢复成出厂定义（模式一并回到 `report`）。
+   *
+   * 与"整表提交里缺了某个内置类型"不同：那条路径只是**恢复缺失项**，保留了用户改过的内容；
+   * 这里是货真价实的重置，所以单独一个开关，语义不含糊。
+   */
+  async resetWikiTypes(id: string): Promise<Envelope<KnowledgeBase>> {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) return failure(emptyBase(id), 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
+    base.wikiTypes = defaultWikiTypes()
+    base.wikiSchemaMode = 'report'
+    base.updatedAt = new Date().toISOString()
+    await this.refreshOne(base)
+    await this.persist()
+    return success(this.view(base))
+  }
+
+  // ------------------------------------------------------------- 内部
+
+  private defaultRootDir(): string {
+    return resolve(this.options.defaultRootDir?.() || defaultKnowledgeRoot())
+  }
+
+  private requireRecord(id: string): KnowledgeBaseRecord {
+    this.ensureLoaded()
+    const base = this.records.find(item => item.id === id)
+    if (!base) throw new Error(`BASE_NOT_FOUND: ${id}`)
+    return base
+  }
+
+  private view(base: KnowledgeBaseRecord): KnowledgeBase {
+    const stats = this.stats.get(base.id)
+    return {
+      id: base.id,
+      name: base.name,
+      description: base.description,
+      rootDir: base.isDefault ? this.defaultRootDir() : base.rootDir,
+      isDefault: base.isDefault,
+      sourceTypes: base.sourceTypes.map(def => ({ ...def, sourceCount: stats?.sourceTypes?.[def.id] ?? 0 })),
+      wikiTypes: base.wikiTypes.map(def => ({ ...def, cardCount: stats?.wikiTypes?.[def.id] ?? 0 })),
+      wikiSchemaMode: base.wikiSchemaMode,
+      wikiTypesCustomized: this.wikiTypesDifferFromDefaults(base.wikiTypes),
+      createdAt: base.createdAt,
+      updatedAt: base.updatedAt,
+      sourceCount: stats?.sourceCount ?? 0,
+      cardCount: stats?.cardCount ?? 0,
+      noteCount: stats?.noteCount ?? 0,
+      buildVersion: stats?.buildVersion ?? 0,
+    }
+  }
+
+  private seedDefault(): KnowledgeBaseRecord {
+    const now = new Date().toISOString()
+    return {
+      id: this.defaultId,
+      name: '默认知识库',
+      description: '插件设置 rootDir 指向的知识库，旧接口与旧工具默认作用于它。',
+      rootDir: this.defaultRootDir(),
+      isDefault: true,
+      sourceTypes: defaultSourceTypes(),
+      wikiTypes: defaultWikiTypes(),
+      wikiSchemaMode: 'report',
+      createdAt: now,
+      updatedAt: now,
+    }
+  }
+
+  private ensureLoaded(): void {
+    if (this.loaded) return
+    this.loaded = true
+    try {
+      const parsed = JSON.parse(readFileSync(this.registryPath, 'utf8')) as { bases?: unknown; stats?: unknown }
+      if (Array.isArray(parsed.bases)) {
+        for (const item of parsed.bases) {
+          const base = this.normalize(item)
+          if (base && !this.records.some(existing => existing.id === base.id)) this.records.push(base)
+        }
+      }
+      const cached = record(parsed.stats)
+      for (const [id, value] of Object.entries(cached)) {
+        const stats = record(value)
+        this.stats.set(id, {
+          sourceCount: Number(stats.sourceCount ?? 0),
+          cardCount: Number(stats.cardCount ?? 0),
+          noteCount: Number(stats.noteCount ?? 0),
+          buildVersion: Number(stats.buildVersion ?? 0),
+          sourceTypes: Object.fromEntries(Object.entries(record(stats.sourceTypes)).map(([key, count]) => [key, Number(count) || 0])),
+          wikiTypes: Object.fromEntries(Object.entries(record(stats.wikiTypes)).map(([key, count]) => [key, Number(count) || 0])),
+        })
+      }
+    } catch { /* 首次运行或文件损坏：从默认库重新开始 */ }
+
+    // 默认库永远存在，且 rootDir 以插件设置（defaultRootDir）为准。
+    const index = this.records.findIndex(item => item.isDefault || item.id === this.defaultId)
+    const seed = this.seedDefault()
+    if (index < 0) this.records.unshift(seed)
+    else {
+      const existing = this.records[index]!
+      this.records[index] = {
+        ...existing,
+        id: this.defaultId,
+        isDefault: true,
+        rootDir: seed.rootDir,
+        name: existing.name || seed.name,
+        sourceTypes: existing.sourceTypes.length > 0 ? existing.sourceTypes : seed.sourceTypes,
+        wikiTypes: existing.wikiTypes.length > 0 ? existing.wikiTypes : seed.wikiTypes,
+      }
+    }
+  }
+
+  private normalize(raw: unknown): KnowledgeBaseRecord | undefined {
+    const value = record(raw)
+    const id = typeof value.id === 'string' ? value.id.trim() : ''
+    if (!id) return undefined
+    const now = new Date().toISOString()
+    const rootDir = typeof value.rootDir === 'string' && value.rootDir.trim()
+      ? resolve(value.rootDir.trim())
+      : join(this.dataHome, 'knowledge-bases', id)
+    return {
+      id,
+      name: typeof value.name === 'string' && value.name.trim() ? value.name.trim() : id,
+      description: typeof value.description === 'string' ? value.description : '',
+      rootDir,
+      isDefault: value.isDefault === true || id === this.defaultId,
+      sourceTypes: this.normalizeSourceTypes(value.sourceTypes),
+      wikiTypes: this.normalizeWikiTypes(value.wikiTypes),
+      wikiSchemaMode: value.wikiSchemaMode === 'strict' ? 'strict' : 'report',
+      createdAt: typeof value.createdAt === 'string' && value.createdAt ? value.createdAt : now,
+      updatedAt: typeof value.updatedAt === 'string' && value.updatedAt ? value.updatedAt : now,
+    }
+  }
+
+  // --------------------------------------------- 来源分类注册表的规整与合并（0013）
+
+  /**
+   * 把磁盘上的 `sourceTypes` 规整成一个**必定包含全部内置分类**的合法注册表。
+   *
+   * 两个关键行为：
+   * 1. 老注册表（没有 `sourceTypes` 字段）升级时自动补上全部内置分类；
+   * 2. 任何缺失的内置分类都会被补回来——内置分类只允许停用，不允许删除。
+   */
+  private normalizeSourceTypes(raw: unknown): SourceTypeDef[] {
+    const persisted = Array.isArray(raw) ? raw : []
+    const byId = new Map<string, Record<string, unknown>>()
+    for (const item of persisted) {
+      const value = record(item)
+      const id = typeof value.id === 'string' ? value.id.trim() : ''
+      if (!id || !SOURCE_TYPE_ID_PATTERN.test(id) || byId.has(id)) continue
+      byId.set(id, value)
+    }
+    const defaults = defaultSourceTypes()
+    const builtins = defaults.map(def => {
+      const value = byId.get(def.id)
+      if (!value) return def
+      byId.delete(def.id)
+      return this.sourceTypeFromRecord(def, value)
+    })
+    const customs: SourceTypeDef[] = []
+    for (const [id, value] of byId) {
+      if (isBuiltinSourceType(id)) continue
+      customs.push(this.sourceTypeFromRecord({ id, label: id, description: '', signals: [], excludes: [], enabled: true, builtin: false, fallback: false, sourceCount: 0 }, value))
+    }
+    const kept = customs
+      .filter(def => validateSourceTypeDraft(def, new Set([...builtins.map(item => item.id), ...customs.map(item => item.id)])).ok)
+      .slice(0, Math.max(0, MAX_SOURCE_TYPES - builtins.length))
+    return [...builtins, ...kept]
+  }
+
+  /** 用一条持久化记录覆盖默认值；`builtin` / `fallback` / `id` 只信服务端。 */
+  private sourceTypeFromRecord(base: SourceTypeDef, value: Record<string, unknown>): SourceTypeDef {
+    const list = (input: unknown, fallback: string[]): string[] => {
+      if (!Array.isArray(input)) return [...fallback]
+      const items = input.map(item => (typeof item === 'string' ? item.trim() : '')).filter(Boolean)
+      return items.length > 0 ? items : [...fallback]
+    }
+    return {
+      id: base.id,
+      label: textOr(value.label, base.label),
+      description: textOr(value.description, base.description),
+      signals: list(value.signals, base.signals),
+      excludes: list(value.excludes, base.excludes),
+      // 兜底分类永远启用：判定链最后一步必须有归属。
+      enabled: base.fallback ? true : value.enabled !== false,
+      builtin: base.builtin,
+      fallback: base.fallback,
+      sourceCount: 0,
+    }
+  }
+
+  /**
+   * 合并前端提交的**完整**注册表列表。
+   *
+   * 返回 `error` 表示整体拒绝（不做部分写入）；返回 `warnings` 表示有内容被
+   * 静默纠正（目前只有"试图删除内置分类"这一种），前端据此提示用户。
+   */
+  private mergeSourceTypes(
+    base: KnowledgeBaseRecord,
+    patch: SourceTypeDef[],
+  ): { types: SourceTypeDef[]; warnings: string[] } | { error: { code: string; message: string; suggestion?: string } } {
+    const existing = base.sourceTypes
+    const requested = new Map<string, Record<string, unknown>>()
+    for (const item of patch) {
+      const value = record(item)
+      const id = typeof value.id === 'string' ? value.id.trim() : ''
+      if (!id || requested.has(id)) continue
+      requested.set(id, value)
+    }
+    const warnings: string[] = []
+    const next: SourceTypeDef[] = []
+
+    // 1) 内置分类：顺序固定、不可删除（缺失即恢复），可改文案、可停用（兜底除外）。
+    for (const seed of defaultSourceTypes()) {
+      const previous = existing.find(def => def.id === seed.id) ?? seed
+      const value = requested.get(seed.id)
+      if (value === undefined) {
+        if (existing.some(def => def.id === seed.id)) warnings.push(`内置分类 ${seed.label}（${seed.id}）不可删除，已保留。`)
+        next.push(previous)
+        continue
+      }
+      requested.delete(seed.id)
+      const draft: SourceTypeDraft = {
+        id: seed.id,
+        label: textOr(value.label, previous.label),
+        description: textOr(value.description, previous.description),
+        signals: value.signals ?? previous.signals,
+        excludes: value.excludes ?? previous.excludes,
+        enabled: value.enabled === undefined ? previous.enabled : value.enabled !== false,
+      }
+      if (seed.fallback && draft.enabled === false) {
+        return { error: { code: 'SOURCE_TYPE_FALLBACK_REQUIRED', message: `兜底分类 ${seed.label}（${seed.id}）不能停用`, suggestion: '判定链全不命中时必须有一个归属；请改为停用其他分类。' } }
+      }
+      const problem = validateSourceTypeText(draft, new Set([...existing.map(def => def.id), ...requested.keys()]))
+      if (!problem.ok) return { error: { code: problem.code, message: `${seed.label}: ${problem.message}`, suggestion: problem.suggestion } }
+      next.push({
+        ...seed,
+        label: String(draft.label).trim(),
+        description: String(draft.description).trim(),
+        signals: (draft.signals as unknown[]).map(item => String(item).trim()).filter(Boolean),
+        excludes: (draft.excludes as unknown[]).map(item => String(item).trim()).filter(Boolean),
+        enabled: seed.fallback ? true : draft.enabled !== false,
+        sourceCount: 0,
+      })
+    }
+
+    // 2) 自定义分类：可增可删，但新增/编辑都必须带上能判的文案。
+    const keptCustoms: SourceTypeDef[] = []
+    const known = new Set([...next.map(def => def.id), ...requested.keys()])
+    for (const [id, value] of requested) {
+      const previous = existing.find(def => def.id === id)
+      const draft: SourceTypeDraft = {
+        id,
+        label: textOr(value.label, previous?.label ?? id),
+        description: textOr(value.description, previous?.description ?? ''),
+        signals: value.signals ?? previous?.signals,
+        excludes: value.excludes ?? previous?.excludes,
+        enabled: value.enabled === undefined ? previous?.enabled ?? true : value.enabled !== false,
+      }
+      const problem = validateSourceTypeDraft(draft, known)
+      if (!problem.ok) return { error: { code: problem.code, message: `${id}: ${problem.message}`, suggestion: problem.suggestion } }
+      keptCustoms.push({
+        id, label: String(draft.label).trim(), description: String(draft.description).trim(),
+        signals: (draft.signals as unknown[]).map(item => String(item).trim()).filter(Boolean),
+        excludes: (draft.excludes as unknown[]).map(item => String(item).trim()).filter(Boolean),
+        enabled: draft.enabled !== false, builtin: false, fallback: false, sourceCount: 0,
+      })
+    }
+    if (keptCustoms.length > Math.max(0, MAX_SOURCE_TYPES - BUILTIN_SOURCE_TYPES.length)) {
+      return { error: { code: 'SOURCE_TYPE_LIMIT', message: `自定义分类最多 ${MAX_SOURCE_TYPES - BUILTIN_SOURCE_TYPES.length} 个` } }
+    }
+
+    // 3) 被删掉的自定义分类：在用就不许删（整体拒绝）。
+    const counts = this.stats.get(base.id)?.sourceTypes ?? {}
+    const keptIds = new Set([...next.map(def => def.id), ...keptCustoms.map(def => def.id)])
+    for (const def of existing) {
+      if (def.builtin || keptIds.has(def.id)) continue
+      const count = counts[def.id] ?? 0
+      if (count > 0) {
+        return { error: { code: 'SOURCE_TYPE_IN_USE', message: `分类 ${def.label}（${def.id}）下还有 ${count} 个来源，先迁移再删除`, suggestion: `把 /knowledge/documents?source_type=${def.id} 下的来源改到别的分类，或保留该分类。` } }
+      }
+    }
+
+    return { types: [...next, ...keptCustoms], warnings }
+  }
+
+  /**
+   * 合并前端提交的**完整**卡片类型列表。
+   *
+   * 与 `mergeSourceTypes` 同一套语义：内置类型不可删除（缺失即恢复 + warning），
+   * 在用类型不可删除（整体拒绝，不做部分写入），自定义类型必须能写出骨架。
+   */
+  private mergeWikiTypes(
+    base: KnowledgeBaseRecord,
+    patch: WikiTypeDef[],
+  ): { types: WikiTypeDef[]; warnings: string[] } | { error: { code: string; message: string; suggestion?: string } } {
+    const existing = base.wikiTypes
+    const requested = new Map<string, Record<string, unknown>>()
+    for (const item of patch) {
+      const value = record(item)
+      const typeId = typeof value.id === 'string' ? value.id.trim() : ''
+      if (!typeId || requested.has(typeId)) continue
+      requested.set(typeId, value)
+    }
+    const warnings: string[] = []
+    const next: WikiTypeDef[] = []
+
+    // 1) 内置类型：顺序固定、不可删除（缺失即恢复），可改文案与小节。
+    for (const seed of defaultWikiTypes()) {
+      const previous = existing.find(def => def.id === seed.id) ?? seed
+      const value = requested.get(seed.id)
+      if (value === undefined) {
+        if (existing.some(def => def.id === seed.id)) warnings.push(`内置类型 ${seed.label}（${seed.id}）不可删除，已保留。`)
+        next.push(previous)
+        continue
+      }
+      requested.delete(seed.id)
+      const draft: WikiTypeDraft = {
+        id: seed.id,
+        label: textOr(value.label, previous.label),
+        description: textOr(value.description, previous.description),
+        layer: value.layer === 'instance' ? 'instance' : previous.layer,
+        sections: Array.isArray(value.sections) ? value.sections : previous.sections,
+        fields: Array.isArray(value.fields) ? value.fields : previous.fields,
+        sourceTypes: Array.isArray(value.sourceTypes) ? value.sourceTypes : previous.sourceTypes,
+        examples: Array.isArray(value.examples) ? value.examples : previous.examples,
+      }
+      const problem = validateWikiTypeText(draft)
+      if (!problem.ok) return { error: { code: problem.code, message: `${seed.label}: ${problem.message}`, suggestion: problem.suggestion } }
+      const sections = parseSectionLines(draft.sections)
+      const fields = parseFieldLines(draft.fields)
+      next.push({
+        ...seed,
+        label: String(draft.label).trim(),
+        description: String(draft.description).trim(),
+        layer: draft.layer === 'instance' ? 'instance' : 'type',
+        sections,
+        fields,
+        sourceTypes: this.stringList(draft.sourceTypes),
+        examples: this.stringList(draft.examples),
+        template: templateCardFor(sections, fields),
+        enabled: value.enabled === undefined ? previous.enabled : value.enabled !== false,
+      })
+    }
+
+    // 2) 自定义类型：可增可删，但必须能写出骨架（小节 + 必填小节）。
+    const keptCustoms: WikiTypeDef[] = []
+    for (const [typeId, value] of requested) {
+      if (isBuiltinWikiType(typeId)) continue
+      const previous = existing.find(def => def.id === typeId)
+      const draft: WikiTypeDraft = {
+        id: typeId,
+        label: textOr(value.label, previous?.label ?? typeId),
+        description: textOr(value.description, previous?.description ?? ''),
+        layer: value.layer === 'instance' ? 'instance' : previous?.layer ?? 'type',
+        sections: Array.isArray(value.sections) ? value.sections : previous?.sections ?? [],
+        fields: Array.isArray(value.fields) ? value.fields : previous?.fields ?? [],
+        sourceTypes: Array.isArray(value.sourceTypes) ? value.sourceTypes : previous?.sourceTypes ?? [],
+        examples: Array.isArray(value.examples) ? value.examples : previous?.examples ?? [],
+      }
+      const problem = previous ? validateWikiTypeText(draft) : validateWikiTypeDraft(draft, new Set(existing.map(def => def.id)))
+      if (!problem.ok) return { error: { code: problem.code, message: `${typeId}: ${problem.message}`, suggestion: problem.suggestion } }
+      const sections = parseSectionLines(draft.sections)
+      const fields = parseFieldLines(draft.fields)
+      keptCustoms.push({
+        id: typeId,
+        label: String(draft.label).trim(),
+        description: String(draft.description).trim(),
+        layer: draft.layer === 'instance' ? 'instance' : 'type',
+        sections,
+        fields,
+        sourceTypes: this.stringList(draft.sourceTypes),
+        examples: this.stringList(draft.examples),
+        template: templateCardFor(sections, fields),
+        enabled: value.enabled === undefined ? previous?.enabled ?? true : value.enabled !== false,
+        builtin: false,
+        cardCount: 0,
+      })
+    }
+
+    // 3) 被删掉的自定义类型：在用就不许删（整体拒绝）。
+    const counts = this.stats.get(base.id)?.wikiTypes ?? {}
+    const keptIds = new Set([...next.map(def => def.id), ...keptCustoms.map(def => def.id)])
+    for (const def of existing) {
+      if (def.builtin || keptIds.has(def.id)) continue
+      const count = counts[def.id] ?? 0
+      if (count > 0) {
+        return { error: { code: 'WIKI_TYPE_IN_USE', message: `类型 ${def.label}（${def.id}）下还有 ${count} 张卡片，先改类型再删除`, suggestion: `把 entity_type=${def.id} 的卡片改成别的类型，或保留该类型。` } }
+      }
+    }
+
+    return { types: [...next, ...keptCustoms], warnings }
+  }
+
+  private nextId(name: string): string {
+    const slugged = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48)
+    // 中文等非 ASCII 名字 slug 后会为空，用 base64url 前 10 位兜底，保证 URL 安全。
+    const fingerprint = Buffer.from(name, 'utf8').toString('base64url').replace(/[^a-zA-Z0-9]/g, '').slice(0, 10).toLowerCase()
+    const stem = slugged || `kb-${fingerprint || 'base'}`
+    const base = stem === this.defaultId ? `${stem}-base` : stem
+    let candidate = base
+    let suffix = 2
+    while (this.records.some(item => item.id === candidate)) candidate = `${base}-${suffix++}`
+    return candidate
+  }
+
+  private async persist(): Promise<void> {
+    const payload = {
+      version: 1,
+      bases: this.records.map(base => ({ ...base, rootDir: base.isDefault ? this.defaultRootDir() : base.rootDir })),
+      stats: Object.fromEntries(this.stats),
+    }
+    const path = this.registryPath
+    await mkdir(dirname(path), { recursive: true })
+    await writeTextAtomic(path, JSON.stringify(payload, null, 2))
+  }
+}