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

package/src/types.ts

@@ -0,0 +1,1140 @@
+import { DIAGNOSIS_ENTITY_TYPES } from './diagnosis/schema.js'
+
+export type KnowledgeStatus = 'unreviewed' | 'draft' | 'reviewed' | 'active' | 'deprecated' | 'problem'
+/**
+ * 内置来源业务分类的 id（0013 注册表）。
+ *
+ * 注册表允许用户追加自定义分类，所以**运行时一律按 `string` 处理**
+ * （见 `SourceType`）；这个字面量联合只用来标记哪些 id 是内置的。
+ */
+export type BuiltinSourceType = 'chat_message' | 'ai_chat_message' | 'document' | 'book' | 'article' | 'prd' | 'question'
+/** 来源业务分类 id。自定义分类是开放集合，所以不是字面量联合。 */
+export type SourceType = string
+/**
+ * 知识卡片的 entity_type 白名单。
+ *
+ * **智能归因的五类也在这里**，这不是放宽而是纠错：排查思路本来就应该是一张 wiki 卡片
+ * （0021 §6.4 定了五类实体与三段式卡片），但白名单里没有它们的时候，`writeCard` 会直接
+ * 返回 `SCHEMA_TYPE_INVALID`，`readCards` 也会跳过 —— 于是排查思路**永远进不了 wikiNotes，
+ * 也就永远召不回来**。列表本身在 `diagnosis/schema.ts` 里定义一次，这里只做联合。
+ */
+export type SchemaType =
+  | 'concept' | 'metric' | 'table' | 'event' | 'playbook' | 'case'
+  | 'diagnosis/symptom' | 'diagnosis/hypothesis' | 'diagnosis/check'
+  | 'diagnosis/failure-mode' | 'diagnosis/case'
+export type EmbeddingProvider = 'wemm-python' | 'ollama' | 'none'
+export type EmbeddingDevice = 'auto' | 'mps' | 'cpu'
+export type RerankProvider = 'bert-python' | 'none'
+/** 真正跑起来的召回路线。`graph` 是 0021 加入的知识图谱路。 */
+export type RecallRoute = 'fts' | 'vector' | 'graph'
+/**
+ * 召回路线选择（0031 起语义有变）。
+ *
+ * `graph` 与 `hybrid` **同义**：知识图谱从「第三路」降成了 boost，它不能凭自己制造
+ * 候选，只给已经在候选池里的条目加权（见 `recallBoost`/`graphBoost`）。所以「只靠图谱」
+ * 的召回在设计上不成立，保留这个取值只为兼容已存的设置与调用方。
+ */
+export type RecallMode = 'fts' | 'vector' | 'graph' | 'hybrid'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import type { DataError, Envelope as WireEnvelope } from 'dsh-data-contracts/envelope'
+import type { LineageContext, LineageRef } from 'dsh-data-contracts/refs'
+
+export interface KnowledgeError extends DataError {
+  code: string
+  message: string
+  retryable: boolean
+  suggestion?: string
+}
+
+/**
+ * This plugin's envelope: the shared five-key wire contract
+ * (`spec/contracts/envelope.json`) with the error narrowed to `KnowledgeError`,
+ * so `retryable` / `suggestion` stay visible to callers and the panel.
+ *
+ * The shape itself lives in `dsh-data-contracts` — the status rule
+ * "warnings make it partial" is defined once there, not re-spelled here.
+ */
+export type Envelope<T> = WireEnvelope<T, KnowledgeError>
+
+export interface KnowledgeConfig {
+  /**
+   * **Tita Agent 根路径** —— 用户唯一要设的那个路径（0029）。
+   *
+   * 根路径下固定四段：`domain_knowledge/`（知识树，按知识库 id 分叉）、
+   * `output/`（交付物，二级按日期）、`tmp/`（运行期临时文件，二级按日期）、
+   * `resource/`（模型、Python 环境、注册表）。
+   * 四段为什么这么分，见 `layout.ts` 顶部的四条原理。
+   */
+  agentRoot: string
+  /**
+   * @deprecated 0029：这是**旧布局**的知识树根（`01_source_truth` 直接躺在它
+   * 下面）。它不再可设置，也不再决定任何路径 —— 只作为一次性的迁移来源存在：
+   * 值非空且新位置还是空的时，把旧树搬进 `<agentRoot>/domain_knowledge/default`。
+   * 搬完（或本来就没有）它就不再有意义。
+   */
+  rootDir: string
+  schemaTypes: SchemaType[]
+  /**
+   * @deprecated 0013：来源分类改为**按知识库持久化的注册表**
+   * （`KnowledgeBase.sourceTypes` / `00_schema/source-types.json` 语义）。
+   * 这个字段只是历史 settings JSON 的兼容壳，既不参与 `addSource` 校验，
+   * 也不再暴露在设置面板里；判定与校验一律走注册表。
+   */
+  sourceAppendTypes: SourceType[]
+  allowSourceTruth: boolean
+  /**
+   * Pass 0（候选抽取 + 归一）的总开关。
+   *
+   * 默认**开**：它是「SourceRaw → Wiki」这条链上唯一不依赖模型的一步，关掉之后
+   * 知识库就只能靠 Agent 逐张 `write_knowledge_card` 长大。关掉的场景是真实存在的
+   * （批量导入时不想让每份文档都自动长出一张未审核卡片），所以它必须可关，
+   * 但关掉不等于删除：计数器会如实回 0，而不是假装抽过了。
+   */
+  extractCandidates: boolean
+  /**
+   * #3b：用模型做**实体抽取与归并**（`extract-model.ts`）。
+   *
+   * 开着时，`rebuild` 把「这份来源里有哪些实体、其中哪些 wiki 里已经有了」交给模型；
+   * 关系候选仍由规则抽取补上，模型不可用则整轮退回规则。所以它是**增强**而不是依赖 ——
+   * 关掉它链路照跑，只是同一实体横跨两份文档时可能落成两张卡（实测过）。
+   *
+   * 触发时机跟着来源走：只有**变化的来源**才进这一轮（增量复用没变的不重跑），
+   * 所以成本与「改了多少来源」成正比，而不是与库的大小成正比。
+   */
+  extractWithModel: boolean
+  /** Python 解释器。空串 = 自动（`<agentRoot>/resource/python/bin/python`，退回旧家当目录，再退回 `python3`）。 */
+  python: string
+  embeddingProvider: EmbeddingProvider
+  embeddingBaseUrl: string
+  /** 嵌入模型：一个本地目录或一个 HF 模型名。空串 = 自动（根路径下的本地模型，退回旧家当目录，再退回 HF 名）。 */
+  embeddingModel: string
+  embeddingDimension: number
+  embeddingBatchSize: number
+  embeddingTimeoutMs: number
+  embeddingDevice: EmbeddingDevice
+  /** Stage 3 recall: how many wikiNotes the multi-route recall may return. */
+  recallTopK: number
+  /**
+   * Stage 3 的**候选池**深度：融合之前每一路各自超采多少条（0031）。
+   *
+   * 它和 `recallTopK` 是两件事，0014 早就点明过：前者是「先粗召回多少」，
+   * 后者是「最终给模型多少」。两者共用一个数时，重排只能给已经截断的列表换顺序，
+   * 永远救不回被融合排到窗口外的那一条。默认 50（与 WeKnora 的 `EmbeddingTopK` 一致）。
+   */
+  recallCandidatePool: number
+  /** Stage 3 recall: default route when a caller does not pass `mode`. */
+  recallMode: RecallMode
+  /**
+   * 关键词路的最低分（归一化 BM25，0..1）。低于它不进候选池。
+   *
+   * 注意它是**相对**阈值（按本次查询的最高分归一），所以它挡得住「弱命中」，
+   * 挡不住「整批都弱」；真正的绝对闸门是 `rerankThreshold`。
+   */
+  keywordThreshold: number
+  /** 向量路的最低相似度（原始余弦，−1..1）。这是**绝对**阈值，可直接用于弃答。 */
+  vectorThreshold: number
+  /** Stage 4 rerank: how many reranked wikiNotes enter the model context. */
+  contextTopN: number
+  /**
+   * Stage 4 重排后的最低分（0..1，sigmoid 之后的 cross-encoder 分）。
+   *
+   * 它是整条链路里唯一**跨查询可比**的相关性判据，所以「弃答」主要靠它。
+   */
+  rerankThreshold: number
+  /** Stage 4 rerank: BERT cross-encoder provider, or `none` to skip reranking. */
+  rerankProvider: RerankProvider
+  /** 重排模型：同上。空串 = 自动。 */
+  rerankModel: string
+  rerankTimeoutMs: number
+}
+
+/**
+ * 旧的「家当」目录（0029 之前模型与虚拟环境住在这里）。
+ *
+ * 现在它们是**兜底**：路径解析优先看 `<agentRoot>/resource/`，找不到再回这里，
+ * 最后才退回裸的模型名（从 HuggingFace 拉）。这样搬完家当、或还没搬完家当，
+ * 行为都对；而 `TITA_DATA_AGENT_HOME` 仍然是覆盖它的入口。
+ */
+export const legacyResourceHome = (): string => resolve(process.env.TITA_DATA_AGENT_HOME || join(homedir(), '.tita-data-agent'))
+/** 本地模型目录名。与 `layout.ts` 的 `resourceModels()` 拼在一起就是主位置。 */
+export const LOCAL_EMBEDDING_MODEL_DIR = 'WeMM-Embedding-2B-Quantized'
+export const LOCAL_RERANK_MODEL_DIR = 'bge-reranker-base'
+/** 裸模型名：本地没有时从 HuggingFace 拉。 */
+export const FALLBACK_EMBEDDING_MODEL = 'ewin-reg/WeMM-Embedding-2B-Quantized'
+export const FALLBACK_RERANK_MODEL = 'BAAI/bge-reranker-base'
+
+/**
+ * 一个**知识库运行时**需要的那部分配置。
+ *
+ * 去掉的是两个**路径**字段：运行时是「一个知识库」的视角，它的根由构造参数单独
+ * 传入（`rootDir`），而 `agentRoot` 是整个部署的根路径 —— 运行时既不该拥有它，
+ * 也不该从它推自己的位置。两个字段留在 `KnowledgeConfig` 里，是因为设置面板要
+ * 编辑 `agentRoot`、迁移要读旧的 `rootDir`。
+ */
+export type RuntimeKnowledgeConfig = Omit<KnowledgeConfig, 'rootDir' | 'agentRoot'>
+
+/**
+ * 除两个路径字段以外的全部默认值。
+ *
+ * `agentRoot` / `rootDir` 由 `index.ts` 用 `layout.ts` 算出来再合进来 —— 它们是
+ * 环境与磁盘事实（桌面在哪、旧树在不在），不是这张常量表能自己回答的。
+ */
+export const DEFAULT_KNOWLEDGE_CONFIG: RuntimeKnowledgeConfig = {
+  // 智能归因的五类在这里一并默认开启：没有它们，排查思路写不进 wiki、召不回来（见 SchemaType）。
+  schemaTypes: ['concept', 'metric', 'table', 'event', 'playbook', 'case', ...DIAGNOSIS_ENTITY_TYPES],
+  sourceAppendTypes: ['chat_message', 'ai_chat_message', 'document'],
+  allowSourceTruth: true,
+  // 0029 撤掉了 `maxSourceBytes`：单条来源**没有**字符数上限。见
+  // `runtime.ts` 的 `addSource` —— 真正的边界是转换内核的 `maxInputBytes`
+  // 与嵌入分批，不是存储层的一个配额。
+  // 只有显式写 `false` / `0` 才关；空值、其他任何写法都按默认「开」处理，
+  // 免得一个打错的 env 值把整条 Pass 0 悄悄关掉。
+  extractCandidates: !['false', '0'].includes((process.env.DSH_KNOWLEDGE_EXTRACT_CANDIDATES ?? '').trim().toLowerCase()),
+  // #3b：模型抽取默认**关**。它会真花钱、也依赖模型可用，所以由用户显式打开；
+  // 关着时链路与以前完全一致（纯规则 Pass 0）。
+  extractWithModel: ['true', '1'].includes((process.env.DSH_KNOWLEDGE_EXTRACT_WITH_MODEL ?? '').trim().toLowerCase()),
+  // 0029：三个「家当」路径的默认值是**空串 = 自动**。它们跟着 `<agentRoot>/resource/`
+  // 走，而 agentRoot 由设置决定、模块加载时还不知道 —— 所以在运行时解析
+  // （`runtime.ts` 的 `resolveResources`）。环境变量仍然优先。
+  python: process.env.DSH_PYTHON || '',
+  embeddingProvider: 'wemm-python',
+  embeddingBaseUrl: process.env.DSH_EMBEDDING_BASE_URL || 'http://127.0.0.1:11434',
+  embeddingModel: process.env.DSH_EMBEDDING_MODEL || process.env.DSH_EMBEDDING_MODEL_PATH || '',
+  embeddingDimension: Number(process.env.DSH_EMBEDDING_DIM || 1024),
+  embeddingBatchSize: 8,
+  embeddingTimeoutMs: 120000,
+  embeddingDevice: (process.env.DSH_EMBEDDING_DEVICE as 'auto' | 'mps' | 'cpu' | undefined) || 'auto',
+  recallTopK: Number(process.env.DSH_KNOWLEDGE_RECALL_TOP_K || 10),
+  recallCandidatePool: Number(process.env.DSH_KNOWLEDGE_CANDIDATE_POOL || 50),
+  recallMode: (process.env.DSH_KNOWLEDGE_RECALL_MODE as RecallMode | undefined) || 'hybrid',
+  // 阈值初值：关键词与重排沿用 WeKnora 的出厂值（0.3 / 0.2），**向量阈值必须改** ——
+  // 见下。
+  keywordThreshold: Number(process.env.DSH_KNOWLEDGE_KEYWORD_THRESHOLD || 0.3),
+  /**
+   * 向量阈值：**0.5，不是 WeKnora 的 0.15**。
+   *
+   * WeKnora 的 0.15 是给它自己那个 embedding 模型的；照搬到 WeMM 上，阈值就形同虚设 ——
+   * 实测（真实知识库，44 条 note，默认 WeMM）：
+   * - 无关查询（`完全无关的词汇zzz` / `zzzzz`）的最高余弦：**0.42 / 0.32**
+   * - 相关查询（`怎么排查指标异常` / `DAU 突增的原因` / `日报 GMV 为 0` / `口径变更怎么处理` /
+   *   `订单数下降`）的最高余弦：**0.60 / 0.70 / 0.83 / 0.67 / 0.74**
+   *
+   * 两簇之间有一条 0.42–0.59 的空带，0.5 落在带内。用 0.15 时无关查询会召回 43/44 条、
+   * `insufficientEvidence` 永远是 false —— 「弃答」就是一句空话（实测过）。
+   *
+   * 这个值**必须按模型与语料校准**：`diagnostics.routes[vector].topScore` 就是每次召回
+   * 的真实最高余弦，用它看自己的分布，而不是照抄别人的常数。
+   */
+  vectorThreshold: Number(process.env.DSH_KNOWLEDGE_VECTOR_THRESHOLD || 0.5),
+  contextTopN: Number(process.env.DSH_KNOWLEDGE_CONTEXT_TOP_N || 5),
+  rerankThreshold: Number(process.env.DSH_KNOWLEDGE_RERANK_THRESHOLD || 0.2),
+  rerankProvider: (process.env.DSH_RERANK_PROVIDER as RerankProvider | undefined) || 'bert-python',
+  rerankModel: process.env.DSH_RERANK_MODEL || '',
+  rerankTimeoutMs: Number(process.env.DSH_RERANK_TIMEOUT_MS || 60000),
+}
+
+/** 一条原始可追溯文档（SourceRaw）。磁盘布局沿用 `01_source_truth`。 */
+export interface SourceRaw {
+  sourceId: string
+  sourceType: SourceType
+  title: string
+  content: string
+  externalId?: string
+  metadata: Record<string, unknown>
+  lineage?: LineageContext
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * `query_source_truth` 读回来的一条来源：`SourceRaw` + **它在磁盘上的位置**。
+ *
+ * ## 为什么必须带 `path`
+ *
+ * 读取有配额（一次最多 `max_chars`，上限 40000 字符），而且配额是**跨多条来源共享**
+ * 的 —— 一份长文档很容易只回来一个开头。被截断时 `content` 是**不完整**的，而「不完整」
+ * 如果只能靠调用方拿长度自己猜，就会出最坏的那种错：以为读到了全文，其实只有前 4 万字符。
+ *
+ * 所以每条都给出绝对路径与全长：Agent 看到 `returnedChars < totalChars` 就知道该去读
+ * 文件原文（它本来就有读文件的能力），而不是基于半份文档下结论。这个路径是知识库里的
+ * **真实文件**，读它与读这里的内容是同一份数据。
+ */
+export interface SourceRawRead extends SourceRaw {
+  /** 这份来源在磁盘上的绝对路径。 */
+  path: string
+  /** 本次实际返回的字符数。 */
+  returnedChars: number
+  /** 这份来源正文的完整字符数。`returnedChars < totalChars` 即被截断。 */
+  totalChars: number
+}
+
+export interface KnowledgeCard {
+  entityId: string
+  entityType: SchemaType
+  title: string
+  status: KnowledgeStatus
+  summary?: string
+  content: string
+  sourceRefs: string[]
+  provenance?: LineageRef[]
+  metadata: Record<string, unknown>
+  updatedAt: string
+  /** Resolved local markdown image references used by the multimodal embedder. */
+  imagePaths?: string[]
+}
+
+/**
+ * A compiled recall unit. Stage 2 turns every wiki card into one or more
+ * wikiNotes; stage 3 recalls wikiNotes (never the wiki directly) and resolves
+ * each hit back to its parent wiki.
+ */
+export interface WikiNote {
+  /**
+   * Stable recall id. The first note of a wiki reuses `<entityType>:<entityId>`
+   * so historical qrels keep working; later notes append `#<n>`.
+   */
+  unitId: string
+  /** Alias of `unitId`, in wikiNotes vocabulary. */
+  noteId: string
+  entityId: string
+  /** The wiki card this note was compiled from (alias of `entityId`). */
+  wikiId: string
+  entityType: SchemaType
+  title: string
+  /** Section heading when a long wiki card was split into several notes. */
+  heading?: string
+  content: string
+  sourceRefs: string[]
+  sourceTypes: SourceType[]
+  provenance?: LineageRef[]
+  status: KnowledgeStatus
+  /** Local markdown image references are embedded with the text when possible. */
+  imagePaths?: string[]
+}
+
+/** Backwards-compatible alias: compiled retrieval units are now wikiNotes. */
+export type KnowledgeUnit = WikiNote
+
+/**
+ * One historical revision of a wiki card.
+ *
+ * Mirrors `DocumentVersion` on purpose: SourceRaw and wiki are the two content
+ * layers in this plugin, and a user who can roll a document back must be able to
+ * roll the card compiled from it back too. Snapshots live under
+ * `04_memory/card-versions/<entityType>/<entityId>/`, hold the *original card
+ * markdown bytes*, and are append-only — reverting snapshots the pre-revert head
+ * as well, so a rollback is itself reversible.
+ */
+export interface WikiCardVersion {
+  versionId: string
+  createdAt: string
+  contentHash: string
+  bytes: number
+  title: string
+  status: string
+  label: string
+  isCurrent: boolean
+}
+
+export interface SearchHit extends WikiNote {
+  score: number
+  match: 'fts' | 'vector' | 'graph' | 'hybrid'
+  /**
+   * 这个命中在每一路里的**名次**（1 起，0031）。
+   *
+   * 融合改用 RRF 之后，名次是唯一进入融合的量 —— 所以它必须留痕：界面上的
+   * 「三路状态」、`match` 的推导、以及「为什么这条排第一」都读它。
+   * 缺失 = 那一路没有召回它。
+   */
+  ranks?: Partial<Record<RecallRoute, number>>
+  /** 该命中引用的 SourceRaw 证据片段（0031）。可追溯从卡片级下沉到段落级。 */
+  evidence?: RecallEvidence[]
+}
+
+/**
+ * 一条命中的**证据片段**：它引用的 SourceRaw 里，与查询最相关的那一段原文。
+ *
+ * 为什么要有它：`context` 原来只带 wiki 卡片，模型要核对原文还得自己再调一次工具。
+ * 把证据放进上下文，「每一个数字都能指回它的口径定义与原始文档」才在**上下文层面**
+ * 成立，而不是靠模型自觉。
+ */
+export interface RecallEvidence {
+  sourceId: string
+  title?: string
+  /** 覆盖查询词最多的那一段原文（已按上限截断）。 */
+  excerpt: string
+  /** 该段在原文正文里的字符偏移，便于回跳。 */
+  offset: number
+  /** 这一段覆盖了查询词的比例（0..1）。 */
+  coverage: number
+}
+
+export interface RecallHit extends SearchHit {
+  /** Cross-encoder score after stage 4 rerank; absent when rerank is skipped. */
+  rerankScore?: number
+}
+
+export interface RerankResult {
+  status: 'ready' | 'unavailable' | 'skipped'
+  provider: RerankProvider
+  model?: string
+  scored?: number
+  error?: string
+  /** 这一轮生效的最低分（0031）。**原始 logit 刻度**，低于它的一律不进上下文。 */
+  threshold?: number
+  /** 被阈值丢掉的条数 —— 「弃答」能不能发生，看的就是它。 */
+  dropped?: number
+  /**
+   * 候选池里最高的 logit（0031）。
+   *
+   * 与 `dropped` 一起回答「这一批到底有多相关」：`dropped: 0` 有两种可能 ——
+   * 全都相关（topLogit 高），或者阈值根本没在工作（topLogit 贴近阈值）。
+   * 只报 `dropped` 会把这两种情况混成一个。
+   */
+  topLogit?: number
+  /**
+   * cross-encoder 分词器的词表大小（0031）。
+   *
+   * 存在的理由是**回归可见性**：词表退化成 5 个特殊 token 时，模型照样返回分数、
+   * 照样 `status: ready`，只是所有输入都变成 `<unk>`（实测三条无关文本 0.998–0.9994）。
+   * 现在 worker 会在加载时直接报 `RERANK_TOKENIZER_DEGENERATE`，这个字段则让
+   * 「真的加载了 250002 条词表」在面板上看得见。
+   */
+  vocabSize?: number
+}
+
+/**
+ * 一路在**这一轮**里的真实状态（0031）。
+ *
+ * 「降级不谎报」原来只体现在 `routes` 数组里，但 `routes` 只回答「跑没跑」，
+ * 回答不了「为什么没结果」。诊断把阈值、候选数、最高分一起给出，于是弃答
+ * （`insufficientEvidence`）不再是黑箱。
+ */
+export interface RecallRouteDiagnostic {
+  route: RecallRoute
+  status: 'ran' | 'degraded' | 'skipped'
+  /** 过滤前该路超采到的候选数。 */
+  candidates?: number
+  /** 过阈值之后剩下的条数。 */
+  kept?: number
+  /** 该路的最高分（解释「为什么弃答」时最有用的一格）。 */
+  topScore?: number
+  threshold?: number
+  /** 降级 / 跳过的原因，直接给用户看。 */
+  reason?: string
+}
+
+export interface RecallDiagnostics {
+  routes: RecallRouteDiagnostic[]
+  fusion: { method: 'rrf'; k: number; weights: Partial<Record<RecallRoute, number>> }
+  /** 图谱 boost 命中了多少条、权重多少。 */
+  graphBoost: { applied: number; weight: number }
+  /**
+   * 弃答判据的强度，如实标注：
+   * - `rerank-threshold`：重排跑通且**真的丢了东西** —— 跨查询可比的绝对判据；
+   * - `vector-threshold`：向量余弦阈值丢的（原始余弦也是绝对量）；
+   * - `relative-only`：只剩「按本次最高分归一」的相对阈值 —— 挡得住弱命中，挡不住
+   *   「整批都弱」；
+   * - `not-needed`：有结果且不需要判弃答。
+   */
+  abstention: 'rerank-threshold' | 'vector-threshold' | 'relative-only' | 'not-needed'
+  /** 向量索引与编码器的健康检查结论（0031 的 P0 门）。 */
+  encoder?: { ok: boolean; reason?: string }
+  /** 弃答时的一句话原因。 */
+  reason?: string
+}
+
+export interface ContextGraph {
+  nodes: Array<Record<string, unknown>>
+  edges: Array<Record<string, unknown>>
+}
+
+export interface ContextItem {
+  note: RecallHit
+  wiki: KnowledgeCard | null
+  /** 1-hop subgraph around the hit's wiki card. */
+  graph: ContextGraph
+  /**
+   * 这条命中引用的 SourceRaw 证据片段（0031）。
+   *
+   * 与 `note.evidence` 同源，放在这里是为了让「上下文包」自包含：读到 `context`
+   * 就拿到了「片段（为什么召回）→ 卡片（结论）→ 原文（证据）」三层。
+   */
+  evidence?: RecallEvidence[]
+}
+
+export interface RecallResult {
+  /** Stage 3: 融合（+ 重排）之后的 wikiNotes，最多 `recallTopK`。 */
+  hits: RecallHit[]
+  /** Stage 4: the `contextTopN` notes expanded to their wiki + 1-hop graph. */
+  context: ContextItem[]
+  /** Distinct wiki cards hit by the recalled notes. */
+  wiki: KnowledgeCard[]
+  /** Union of the 1-hop subgraphs of the recalled wiki cards. */
+  graph: ContextGraph
+  backend: string
+  routes: RecallRoute[]
+  /** Route actually used (caller override or the configured default). */
+  recallMode: RecallMode
+  rerank: RerankResult
+  recallTopK: number
+  /** 融合之前每一路的超采深度（0031）。 */
+  candidatePool: number
+  contextTopN: number
+  /**
+   * 一路都没过阈值 = 这个知识库里没有能回答这个问题的东西（0031）。
+   *
+   * 它是产品诚实性的一部分：与其凑满 5 条噪声让模型编，不如明确说「没有」。
+   * 消费方（Agent 工具 / 面板）看到 true 就该如实转述，而不是把 `hits: []`
+   * 当成一次失败。
+   */
+  insufficientEvidence: boolean
+  /** 每一路在这一轮里发生了什么（阈值、候选数、最高分、降级原因）。 */
+  diagnostics: RecallDiagnostics
+  recallId: string
+  indexVersion?: number
+  compileRunId?: string
+  lineage?: LineageContext
+}
+
+// ---------------------------------------------------------------- 多知识库（0021）
+
+/** 一个知识库 = 独立配置 + 独立内容根目录。 */
+export interface KnowledgeBase {
+  id: string
+  name: string
+  description: string
+  rootDir: string
+  isDefault: boolean
+  /**
+   * 来源业务分类注册表（0013），与 `wikiTypes` 平级、同样按库持久化。
+   * `fileCount` / `sourceCount` 这类计算字段由 refresh 实时算出。
+   */
+  sourceTypes: SourceTypeDef[]
+  /**
+   * Wiki 卡片类型注册表（0024）：决定"SourceRaw → Wiki"这一段能生成哪些类型的卡片、
+   * 每类卡片必须有哪些小节与字段。与 `sourceTypes` 同处持久化，理由见 0013 §7.1。
+   */
+  wikiTypes: WikiTypeDef[]
+  /**
+   * 卡片 schema 的生效方式：`report` 只把问题写进卡片并回报，`strict` 直接拒绝不合规的写入。
+   * 默认 `report`，避免存量卡片在升级后被挡在门外。
+   */
+  wikiSchemaMode: WikiSchemaMode
+  /**
+   * 计算字段：当前 `wikiTypes` 是否已偏离出厂定义。界面据此决定「恢复默认」是否可点，
+   * 也让人一眼看出这套 schema 是本库自己调过的。
+   */
+  wikiTypesCustomized: boolean
+  createdAt: string
+  updatedAt: string
+  sourceCount: number
+  cardCount: number
+  noteCount: number
+  buildVersion: number
+}
+
+/** 文档列表项（SourceRaw 的对外投影，不含正文）。 */
+export interface KnowledgeDocument {
+  /** = SourceRaw.sourceId */
+  docId: string
+  title: string
+  sourceType: string
+  /**
+   * `sourceType` 是否仍在当前知识库的注册表里。
+   *
+   * 0013 之前 `loadSources()` 会把未知分类**静默丢弃**，文档凭空消失；
+   * 现在一律保留并把这个标记交给前端渲染成「未知分类」徽标。
+   */
+  sourceTypeKnown: boolean
+  sourceFormat: string
+  parser: string
+  externalId: string
+  contentHash: string
+  bytes: number
+  assetCount: number
+  createdAt: string
+  updatedAt: string
+  versionCount: number
+  /** 相对知识库根目录，如 `01_source_truth/<slug>.md`。 */
+  relativePath: string
+  ext: string
+}
+
+/** 详情页要展示的资产引用；`url` 直接指向 `/knowledge/assets/<kbId>/<rel>`。 */
+export interface KnowledgeAssetRef {
+  rel: string
+  bytes: number
+  url: string
+}
+
+export interface KnowledgeDocumentDetail extends KnowledgeDocument {
+  content: string
+  frontmatter: Record<string, unknown>
+  assets: KnowledgeAssetRef[]
+  lineage?: Record<string, string>
+}
+
+/** 文档版本：`isCurrent` 的那条是当前 head，其余是历史快照。 */
+export interface DocumentVersion {
+  versionId: string
+  createdAt: string
+  contentHash: string
+  bytes: number
+  sourceFormat: string
+  label: string
+  isCurrent: boolean
+}
+
+/** 默认「文件类型 → 解析引擎」规则的内容，不含 `fileCount`。 */
+/**
+ * 从 SourceRaw 的 `metadata` 推导文档扩展名。
+ *
+ * **这个推导是有损的。** SourceRaw 只保存正文与 metadata，并不保存原始文件名；
+ * 因此只有上游（`src/convert/ingest.ts`）显式写了 `metadata.source_path` 时才能拿到
+ * 真实扩展名。回退链是启发式的：
+ *
+ * 1. `metadata.source_path` 的 basename 扩展名（最可信）；
+ * 2. `metadata.source_format === 'markdown'` → `.md`；
+ * 3. `metadata.source_format === 'office'` → `.docx`（office 是容器格式的粗粒度标记，
+ *    真实的 .doc/.xls/.ppt 会被误报为 `.docx`）；
+ * 4. 其余 `source_format` → `.` + source_format（当它本身就是一个扩展名时才对）；
+ * 5. 都没有 → `.md`（知识库里最常见的形态）。
+ *
+ * 因此 `fileCount` 与按扩展名过滤都只是近似值；要精确统计需要在入库时写 `source_path`。
+ */
+export function deriveSourceExt(metadata: Record<string, unknown> | undefined): string {
+  const sourcePath = metadata && typeof metadata.source_path === 'string' ? metadata.source_path.trim() : ''
+  if (sourcePath) {
+    const base = sourcePath.split(/[\\/]/).pop() ?? ''
+    const dot = base.lastIndexOf('.')
+    if (dot > 0 && dot < base.length - 1) return base.slice(dot).toLowerCase()
+  }
+  const format = metadata && typeof metadata.source_format === 'string' ? metadata.source_format.trim().toLowerCase() : ''
+  if (format === 'markdown') return '.md'
+  if (format === 'office') return '.docx'
+  if (format) return `.${format}`
+  return '.md'
+}
+
+export interface RebuildReport {
+  runId: string
+  version: number
+  only: string
+  cards: number
+  units: number
+  /** Compiled wikiNotes count (stage 2 output). */
+  notes: number
+  graphNodes: number
+  graphEdges: number
+  embedding: 'ready' | 'unavailable' | 'skipped'
+  embeddingItems?: number
+  embeddingReused?: number
+  embeddingDimension?: number
+  vectorQuantization?: 'binary+hamming+int8'
+  embeddingError?: string
+  /**
+   * 关键词索引（FTS5）的构建结论（0031）。
+   *
+   * 与 `embedding` 并列而不是塞进它：两者可以一个成一个败（编码器坏了但关键词索引照样
+   * 能建），而「哪一路现在是活的」必须一眼看得出。
+   */
+  fts?: 'ready' | 'unavailable'
+  lineage?: LineageContext
+  compileRunId?: string
+  startedAt: string
+  finishedAt: string
+  // ------------------------------------------------ 增量编译（0025 §增量更新）
+  /**
+   * Stage-2 incrementality. `compileNotes` is deterministic, so recompiling is
+   * cheap — what is *not* cheap is invalidating a stable corpus: a rebuild that
+   * renumbers notes forces a full re-embedding and breaks existing qrels.
+   * These counters make the reuse visible instead of implicit.
+   */
+  cardsReused?: number
+  cardsRecompiled?: number
+  cardsAdded?: number
+  cardsRemoved?: number
+  notesReused?: number
+  notesRecompiled?: number
+  /** Nothing changed: knowledge artifacts were left byte-identical. */
+  incremental?: boolean
+  /** The run was a no-op (a `wiki`-only rebuild over an unchanged corpus). */
+  skipped?: boolean
+  // ------------------------------------------------ Pass 0 · 候选抽取 + 归一
+  /**
+   * 「SourceRaw → Wiki」第一段的诚实计数。
+   *
+   * 这八个数**每一个都来自真实发生过的事件**，没有一个是估算出来的：抽取了几个
+   * 候选、其中几个被类型闸门拒了、建了几张卡、并进几张卡、几条关系真的连上了、
+   * 几条因为端点不存在被丢掉、几份来源这次被重抽、几份因为指纹没变被跳过。
+   * `extractCandidates` 关掉时它们全部回 0，而不是从响应里消失 —— 「跳过」和
+   * 「没有这个能力」是两件事，用缺字段表达会让人分不清。
+   */
+  candidatesExtracted: number
+  candidatesRejected: number
+  cardsCreated: number
+  cardsMerged: number
+  relationsExtracted: number
+  relationsDropped: number
+  sourcesExtracted: number
+  sourcesSkipped: number
+}
+
+// ------------------------------------------------- 来源业务分类注册表（0013）
+
+/**
+ * 一条来源业务分类。
+ *
+ * 设计原则：`source_type` 描述**业务场景**，不描述载体格式；载体走
+ * `source_format` / `parser`（见 `deriveSourceExt`）。三个「判定档位」是刻意
+ * 分开的，UI 与 Agent 都按这个契约消费：
+ *
+ * - 必填且不可动（`fallback`）：兜底分类必须存在且始终启用；
+ * - 内置可调（`builtin && !fallback`）：可改文案、可停用，但不可删除、不可改 id；
+ * - 自定义（`!builtin`）：可增可删，但新建时必须提交完整判定文案。
+ */
+export interface SourceTypeDef {
+  /** 稳定 id，`^[a-z][a-z0-9_]{1,40}$`，创建后不可修改。 */
+  id: string
+  label: string
+  /** 一句话定义，同时是 Agent 的判定依据。 */
+  description: string
+  /** 典型信号，至少 2 条；与 `description` 一起拼进判定提示词。 */
+  signals: string[]
+  /** 明确排除项，至少 1 条，每条必须指向一个已存在的分类。 */
+  excludes: string[]
+  /** 停用后不再出现在选择器与判定提示词里，历史引用仍能解析。 */
+  enabled: boolean
+  /** 内置分类只允许停用，不允许删除。 */
+  builtin: boolean
+  /** 兜底分类（`document`）：必须存在且不可停用，判定链最后一步落在它上。 */
+  fallback: boolean
+  /** 计算字段：该库中引用该分类的来源数，由 `refresh` 实时算出，不参与持久化。 */
+  sourceCount: number
+}
+
+/** 分类 id 的形状约束；与 0013 规范第 1 节一致。 */
+export const SOURCE_TYPE_ID_PATTERN = /^[a-z][a-z0-9_]{1,40}$/
+/** 兜底分类 id；判定链全不命中时落它，因此它不可停用、不可删除。 */
+export const FALLBACK_SOURCE_TYPE = 'document'
+/** 单库自定义分类数量上限，防止注册表无界膨胀。 */
+export const MAX_SOURCE_TYPES = 50
+
+/**
+ * 内置分类的出厂默认值（0013 规范第 7 节的 `source-types.json` 内容）。
+ *
+ * 这些值**可以改**（label / description / signals / excludes / enabled），
+ * 但条目本身不可删除——`normalizeSourceTypes()` 会把缺失的内置条目补回来。
+ */
+export const BUILTIN_SOURCE_TYPES: ReadonlyArray<Omit<SourceTypeDef, 'sourceCount'>> = [
+  {
+    id: 'chat_message',
+    label: '聊天日志',
+    description: '人与人之间在日常沟通中产生的消息记录，以对话往返为主要形态。',
+    signals: ['有发言人与时间戳的短消息流', '多话题跳转、口语化、缩写多', '常见 @提及、表情、附件'],
+    excludes: ['与 AI 的对话归 ai_chat_message', '整理后的会议纪要归 document', '已成问题—根因—方案的记录归 question'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  {
+    id: 'ai_chat_message',
+    label: 'AI 对话日志',
+    description: '用户与 AI 助手之间的完整对话记录，包含双方往返消息。',
+    signals: ['user / assistant 角色交替', '提示词与回答成对出现', '代码块密集、常与会话 id 或模型名同现'],
+    excludes: ['人在群里转贴 AI 回答归 chat_message', '由 AI 对话整理出的方法论文档归 document 或 article'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  {
+    id: 'document',
+    label: '企业内部文档',
+    description: '组织内部产生、用于内部协作与沉淀的文档；也是全不命中时的兜底分类。',
+    signals: ['内部作者、团队或编号、密级', '提到内部系统与组织名', '结构完整但非出版形态'],
+    excludes: ['面向功能与验收的需求文档归 prd', '以排查具体问题为中心归 question', '组织外部产出归 article', '正式出版物归 book'],
+    enabled: true,
+    builtin: true,
+    fallback: true,
+  },
+  {
+    id: 'book',
+    label: '书籍',
+    description: '正式出版或成体系的整书内容。',
+    signals: ['ISBN、出版社、版次或丛书名', '目录、章节、页码、前言、参考文献齐备', '按章拆分为多份录入'],
+    excludes: ['单篇论文、博客、报告归 article', '内部系统性手册归 document'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  {
+    id: 'article',
+    label: '业界文章',
+    description: '来自组织外部或对外发布的单篇文献。',
+    signals: ['外链 URL、外部作者或媒体署名、发布时间', '面向公开读者', '带原文链接或转载字样'],
+    excludes: ['正式出版物整书归 book', '内部未对外发布的资料归 document', '排查本组织具体问题归 question'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  {
+    id: 'prd',
+    label: '产品需求文档',
+    description: '描述要做什么产品功能、为谁做、为什么做、怎么算做完的需求文档。',
+    signals: ['需求背景、目标用户、用户故事', '功能列表、验收标准、上线计划、优先级', '版本号与评审状态'],
+    excludes: ['技术实现方案归 document', '缺陷与线上问题排查归 question', '产品使用说明归 document 或 article'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  {
+    id: 'question',
+    label: '问题排查文档',
+    description: '以某个具体问题或故障为中心的记录：现象、影响、排查过程、根因、解决方案与后续动作。',
+    signals: ['错误码、堆栈或日志片段', '复现步骤、临时规避、根因、修复版本', '时间线、一问一答或一问题多方案'],
+    excludes: ['一般性经验总结归 document', '产品需求归 prd', '外部作者的公开分析归 article'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  /**
+   * 以下四类是**数据域**的分类（0030）。
+   *
+   * 前七类描述的是「文档长什么样」，而数据 Agent 的日常是另一套东西：表结构、
+   * 指标口径、跑批脚本、一次取数的问答。它们混进 `document` 的后果最实际 ——
+   * 「销售额怎么算」要靠 `metric` 的公式，而不是一篇内部文档的正文；没有这一层，
+   * 召回就只能靠词面。
+   *
+   * 四类的边界是**它们各自回答的问题**：
+   * - `table`：这份数据存在哪、长什么样（字段 / 类型 / 分区 / 更新频率）。
+   * - `metric`：这个数字怎么算（口径、公式、维度、粒度）。
+   * - `data_dev_script`：这张表/这个指标是怎么被生产出来的（SQL / 调度 / 依赖）。
+   * - `query_case`：有人问过什么问题、当时怎么取、结果是多少（可复用的问答）。
+   *
+   * `table` 与 `data_dev_script` 最容易混：判据是**主语**——在建表和描述字段的是
+   * `table`，在加工数据、产出某张表的是脚本。`metric` 与 `query_case` 同理：定义
+   * 口径的是前者，记录“这一问是怎么答的”是后者。
+   */
+  {
+    id: 'table',
+    label: '表',
+    description: '一张表或一个数据集的元数据：字段清单、类型、分区、主键、更新频率与负责人。',
+    signals: ['CREATE TABLE / DDL，或字段名与类型成列成行', '分区字段、主键、存储格式、生命周期', '常带库名.表名与上下游说明'],
+    excludes: ['加工或产出这张表的 SQL / 调度归 data_dev_script', '指标口径与计算公式归 metric', '针对这张表的一次取数问答归 query_case'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  {
+    id: 'metric',
+    label: '指标',
+    description: '一个可计算、可归属的量化口径：它是什么、怎么算、按什么维度和粒度统计、谁负责。',
+    signals: ['指标名 + 口径定义 + 计算公式', '统计周期、维度、粒度、负责人、目标值', '常与同比 / 环比、分层口径、口径变更历史同现'],
+    excludes: ['底层表的字段清单归 table', '指标异常的线上排查过程归 question', '一次具体的取数问答归 query_case'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  {
+    id: 'data_dev_script',
+    label: '数据开发脚本',
+    description: '生产数据用的加工逻辑：SQL、PySpark、Shell 或调度定义，说明它读什么、写什么、什么时候跑。',
+    signals: ['SELECT … FROM / INSERT OVERWRITE / DAG 定义等可执行代码块', '调度周期、依赖、参数模板、临时表', '注明产出表名与跑批窗口'],
+    excludes: ['在建表并描述字段的是 table', '定义指标口径的是 metric', '只讲怎么取一次数的是 query_case'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+  {
+    id: 'query_case',
+    label: '数据查询案例',
+    description: '一次取数问答的完整记录：被问的是什么、口径怎么理解、查了哪张表、用了什么 SQL、结果对不对。',
+    signals: ['「问题 → 口径 → SQL → 结果」的成对结构', '带样例输出、校验数字或与预期不符的说明', '常被当作同类问题的复用模板'],
+    excludes: ['指标本身的定义与公式归 metric', '线上指标异常的排查记录归 question', '底层表结构归 table'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
+]
+
+const BUILTIN_SOURCE_TYPE_IDS: ReadonlySet<string> = new Set(BUILTIN_SOURCE_TYPES.map(def => def.id))
+
+export function isBuiltinSourceType(id: string): boolean {
+  return BUILTIN_SOURCE_TYPE_IDS.has(id)
+}
+
+/** 出厂默认注册表（全部启用，`sourceCount` 待算）。 */
+export function defaultSourceTypes(): SourceTypeDef[] {
+  return BUILTIN_SOURCE_TYPES.map(def => ({
+    ...def,
+    signals: [...def.signals],
+    excludes: [...def.excludes],
+    sourceCount: 0,
+  }))
+}
+
+/**
+ * 内置只读判定提示词。
+ *
+ * **它不允许被用户修改**——注册表里没有任何字段能覆盖它；但它必须**被暴露
+ * 出来**：`list_source_types` 工具、`GET /knowledge/source-types` 与设置面板的
+ * 「判定规则（内置，只读）」都原样返回它，让用户看得见 Agent 到底按什么判。
+ * 用户能写的只有每个分类自己的 `description` / `signals` / `excludes`。
+ */
+export interface SourceClassifierStep {
+  /** 该步落到哪个分类；`user` 表示"用户显式指定"这个非分类入口。 */
+  type: string
+  rule: string
+}
+
+export interface SourceClassifierPrompt {
+  readonly: true
+  version: number
+  title: string
+  /** 从最特征化走到最泛化；全不命中落 `fallback.type`。 */
+  priority: SourceClassifierStep[]
+  confidenceRule: string
+  fallback: { type: string; note: string }
+  escalation: { code: string; note: string }
+  /** 自定义分类由用户撰写的判定文案如何参与判定。 */
+  extensionRule: string
+}
+
+/**
+ * 深冻结：把「内置、不允许修改」从口头约定变成运行时可验证的事实。
+ *
+ * 冻结失败不会让进程崩溃——ESM 是严格模式，任何写入尝试会抛 `TypeError`，
+ * 于是"有人偷偷改提示词"会在第一次写入时就炸掉，而不是静默漂移。
+ */
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value)
+    for (const nested of Object.values(value as Record<string, unknown>)) deepFreeze(nested)
+  }
+  return value
+}
+
+export const SOURCE_CLASSIFIER_PROMPT: SourceClassifierPrompt = deepFreeze({
+  readonly: true,
+  version: 2,
+  title: '来源业务分类判定规则',
+  priority: [
+    { type: 'user', rule: '用户显式指定分类 → 直接用，记 source_type_source: user。' },
+    { type: 'ai_chat_message', rule: '内容是人与 AI 的对话记录（含 AI 回复）→ ai_chat_message。' },
+    { type: 'chat_message', rule: '内容是人与人之间的消息流（IM / 会议聊天 / 客服会话）→ chat_message。' },
+    // 数据域四类排在通用文档之前：它们的形状（DDL、公式、SQL、问答）比
+    // 「像不像一篇内部文档」更特征化，落到 document 之后再想捞回来就晚了。
+    // 四类之间的次序按「定义的确定性」排：口径与表结构有明确文本特征，脚本次之，
+    // 取数问答最接近泛化的对话记录。
+    { type: 'metric', rule: '内容在定义一个可计算的量化口径（指标名 + 公式 + 维度 / 粒度 / 负责人）→ metric。' },
+    { type: 'table', rule: '内容在描述一张表或数据集本身（字段清单、类型、分区、主键、更新频率）→ table。' },
+    { type: 'data_dev_script', rule: '内容是生产数据的加工逻辑（SQL / PySpark / Shell / 调度定义，读什么写什么）→ data_dev_script。' },
+    { type: 'question', rule: '内容以某个具体问题或故障为中心（现象 → 排查 → 根因 → 措施）→ question。' },
+    { type: 'query_case', rule: '内容是一次取数问答的完整记录（问题 → 口径 → SQL → 结果）→ query_case。' },
+    { type: 'prd', rule: '内容面向「要做什么功能、给谁用、怎么算做完」→ prd。' },
+    { type: 'book', rule: '内容是正式出版物或成体系的整书 → book。' },
+    { type: 'article', rule: '内容是组织外部产出或对外发布的单篇文献 → article。' },
+    { type: 'document', rule: '以上都不是的企业内部协作文档 → document。' },
+  ],
+  confidenceRule: '每一步都要求高置信才落定；同时命中两类且无法用优先级化解时不得自行决断，也不允许静默落 document。',
+  fallback: { type: FALLBACK_SOURCE_TYPE, note: '全不命中时的唯一兜底分类；该分类必须存在且不可停用。' },
+  escalation: {
+    code: 'SOURCE_TYPE_REQUIRED',
+    note: '返回 SOURCE_TYPE_REQUIRED 并附 2–3 个候选（含理由）交给用户在录入向导里选；用户也判不了时要求其显式确认一个暂定分类，并标记 needs_review。',
+  },
+  extensionRule: '自定义分类的 description / signals / excludes 由用户撰写并拼进本提示词参与判定：description 必须写清「是什么」，signals 至少 2 条，excludes 至少 1 条且必须指向一个已存在的分类。',
+})
+
+/** 判定提示词 + 每个分类当前是否启用；停用的分类标注出来而不是从提示词里删掉。 */
+export interface SourceClassifierPromptView extends SourceClassifierPrompt {
+  steps: ReadonlyArray<Readonly<SourceClassifierStep & { label: string; enabled: boolean; exists: boolean }>>
+}
+
+/**
+ * 展开成"每步带 label / enabled / exists"的视图。
+ *
+ * `priority` 直接复用被冻结的原数组（不复制），所以视图也无法被就地改写；
+ * 每次调用只新建 `steps`，并把它一并冻结。注册表怎么改，提示词骨架都不变。
+ */
+export function classifierPromptView(defs: SourceTypeDef[]): SourceClassifierPromptView {
+  const byId = new Map(defs.map(def => [def.id, def]))
+  const steps = SOURCE_CLASSIFIER_PROMPT.priority.map(step => {
+    const def = byId.get(step.type)
+    return Object.freeze({ ...step, label: def?.label ?? step.type, enabled: def?.enabled ?? false, exists: def !== undefined })
+  })
+  return Object.freeze({ ...SOURCE_CLASSIFIER_PROMPT, steps: Object.freeze(steps) })
+}
+
+/** 一个知识库的完整分类目录：注册表 + 内置只读提示词。 */
+export interface SourceTypeCatalog {
+  types: SourceTypeDef[]
+  classifierPrompt: SourceClassifierPromptView
+  fallbackTypeId: string
+  builtinIds: string[]
+}
+
+export function buildSourceTypeCatalog(defs: SourceTypeDef[]): SourceTypeCatalog {
+  return {
+    types: defs,
+    classifierPrompt: classifierPromptView(defs),
+    fallbackTypeId: FALLBACK_SOURCE_TYPE,
+    builtinIds: BUILTIN_SOURCE_TYPES.map(def => def.id),
+  }
+}
+
+/** 新建 / 编辑分类时提交的草稿。 */
+export interface SourceTypeDraft {
+  id?: string
+  label?: string
+  description?: string
+  signals?: unknown
+  excludes?: unknown
+  enabled?: boolean
+}
+
+export interface SourceTypeDraftProblem {
+  ok: false
+  code: string
+  message: string
+  suggestion?: string
+  /** 出错的字段，供表单高亮。 */
+  field: 'id' | 'label' | 'description' | 'signals' | 'excludes' | 'enabled'
+}
+
+const EXTENSION_HINT = /\.(pdf|docx?|xlsx?|pptx?|md|markdown|txt|csv|json|tsv|html?|png|jpe?g|gif|webp|zip)\b/i
+
+/**
+ * 校验一份自定义分类草稿。
+ *
+ * 这是在守「用户追加新类型时，必须用文字标明怎么判断」这条要求：光给个名字
+ * 是不允许入库的——入库的 `description` 会直接变成 Agent 的判定依据。
+ */
+export function validateSourceTypeDraft(draft: SourceTypeDraft, knownIds: ReadonlySet<string>): { ok: true } | SourceTypeDraftProblem {
+  const id = typeof draft.id === 'string' ? draft.id.trim() : ''
+  if (!SOURCE_TYPE_ID_PATTERN.test(id)) {
+    return { ok: false, code: 'SOURCE_TYPE_ID_INVALID', field: 'id', message: '分类 id 必须是小写字母开头的 2–41 位小写字母 / 数字 / 下划线', suggestion: '例如 test_unit、design_review；id 创建后不可修改。' }
+  }
+  if (isBuiltinSourceType(id)) {
+    return { ok: false, code: 'SOURCE_TYPE_BUILTIN_LOCKED', field: 'id', message: `内置分类 id 不可占用或修改: ${id}`, suggestion: '内置分类只能改文案或停用；新场景请另起 id。' }
+  }
+  return validateSourceTypeText(draft, knownIds)
+}
+
+/**
+ * 只校验判定文案（label / description / signals / excludes），不碰 id。
+ *
+ * 内置分类改文案走这里：id 锁定，但「必须写得能判」的标准一样严。
+ */
+export function validateSourceTypeText(draft: SourceTypeDraft, knownIds: ReadonlySet<string>): { ok: true } | SourceTypeDraftProblem {
+  const label = typeof draft.label === 'string' ? draft.label.trim() : ''
+  if (!label) return { ok: false, code: 'SOURCE_TYPE_LABEL_REQUIRED', field: 'label', message: 'label 不能为空' }
+  const description = typeof draft.description === 'string' ? draft.description.trim() : ''
+  if (description.length < 8) {
+    return { ok: false, code: 'SOURCE_TYPE_DESCRIPTION_REQUIRED', field: 'description', message: 'description 必填，且要写清这个分类「是什么」', suggestion: '一句话定义，至少 8 个字；它是 Agent 判定该分类的主要依据。' }
+  }
+  if (EXTENSION_HINT.test(description)) {
+    return { ok: false, code: 'SOURCE_TYPE_DESCRIPTION_BY_FORMAT', field: 'description', message: 'description 描述的是业务场景，不能写成载体 / 文件格式', suggestion: '例如不要写「包含 .xlsx 和 .csv 文件」，要写「用于跟踪测试用例执行结果的记录」。载体请走 source_format。' }
+  }
+  const signals = Array.isArray(draft.signals) ? draft.signals.map(item => String(item).trim()).filter(Boolean) : []
+  if (signals.length < 2) {
+    return { ok: false, code: 'SOURCE_TYPE_SIGNALS_REQUIRED', field: 'signals', message: 'signals 至少 2 条', suggestion: '写清「看到什么就说明是这一类」，每条一个特征。' }
+  }
+  const excludes = Array.isArray(draft.excludes) ? draft.excludes.map(item => String(item).trim()).filter(Boolean) : []
+  if (excludes.length < 1) {
+    return { ok: false, code: 'SOURCE_TYPE_EXCLUDES_REQUIRED', field: 'excludes', message: 'excludes 至少 1 条', suggestion: '写清「看起来像但其实不是」的情况，并指明它该归到哪个分类。' }
+  }
+  // 每条排除项都必须指向一个已存在的分类，否则边界是悬空的。
+  const known = [...new Set([...knownIds, draft.id ?? ''])].filter(Boolean)
+  const dangling = excludes.filter(text => !known.some(knownId => text.includes(knownId)))
+  if (dangling.length > 0) {
+    return {
+      ok: false, code: 'SOURCE_TYPE_EXCLUDE_DANGLING', field: 'excludes',
+      message: `排除项没有指向任何已存在的分类: ${dangling[0]}`,
+      suggestion: `每条排除项都要写出「归到哪个分类」，用 id 或标签都行。可用分类: ${known.join(' / ')}`,
+    }
+  }
+  return { ok: true }
+}
+
+// ------------------------------------------------- Wiki 卡片类型注册表（0024）
+
+/**
+ * Wiki 卡片类型的一条正文小节要求。
+ *
+ * 「正文小节」是给人读的部分：0021 的判断是"序和枚举一旦写进散文，归并算法就再也读不到
+ * 它们了"，所以小节名要固定，模板卡照着它生成。
+ */
+export interface WikiSectionSpec {
+  /** 小节名，同时是模板卡里的 Markdown 标题。 */
+  label: string
+  required: boolean
+}
+
+/**
+ * 一条 front matter / metadata 字段要求（机器读的部分）。
+ *
+ * `name` 对应 `write_knowledge_card` 的顶层字段（`owner` / `summary`）或 `metadata` 里的键。
+ */
+export interface WikiFieldSpec {
+  name: string
+  required: boolean
+  note: string
+}
+
+/**
+ * 一个 wiki 卡片类型（0024）。
+ *
+ * 它是"SourceRaw → Wiki"这一段的**约束**：哪些类型能生成、每类必须有哪些小节与字段、
+ * 期望来自哪些来源分类、模板长什么样。判定与生成仍交给模型，这里给的是**判据与骨架**。
+ */
+export interface WikiTypeDef {
+  /** 稳定 id，`^[a-z][a-z0-9_/-]{1,60}$`（允许 `diagnosis/symptom` 这类命名空间）。 */
+  id: string
+  label: string
+  description: string
+  /** 借 0021 的分层：类型层可复用上千次（假设/口径），实例层只发生过一次（案例）。 */
+  layer: 'type' | 'instance'
+  sections: WikiSectionSpec[]
+  fields: WikiFieldSpec[]
+  /** 期望的来源业务分类 id（0013 的 `source_type`）；空数组表示不限制。 */
+  sourceTypes: string[]
+  /** few-shot：用户会怎么提到这种卡片。随工具描述下发。 */
+  examples: string[]
+  /** 模板卡（Markdown 骨架），新建卡片时照抄。 */
+  template: string
+  enabled: boolean
+  /** 内置类型只允许停用，不允许删除。 */
+  builtin: boolean
+  /** 计算字段：该库中该类型的卡片数，由 refresh 实时算出。 */
+  cardCount: number
+}
+
+/** 卡片 schema 的生效方式。 */
+export type WikiSchemaMode = 'strict' | 'report'
+
+/** 卡片校验问题的一层。混成同一个「校验失败」，人就学不会怎么写卡片（0021 §1）。 */
+export type CardIssueLevel = 'format' | 'reference' | 'semantic'
+
+export interface CardSchemaIssue {
+  level: CardIssueLevel
+  /** 出问题的小节名或字段名。 */
+  field?: string
+  message: string
+}
+
+/** 卡片类型目录：注册表 + 生效方式 + 内置只读判定规则 + 当前卡片的问题清单。 */
+export interface WikiTypeCatalog {
+  types: WikiTypeDef[]
+  mode: WikiSchemaMode
+  /** 内置只读的判定规则：模型该按什么顺序挑类型。 */
+  rules: string
+  /** 已落库卡片的三层校验结果（前 N 条）。 */
+  issues: Array<CardSchemaIssue & { entityId: string; entityType: string }>
+  issueCount: number
+}
+
+/** 卡片类型 id 的形状；允许 `diagnosis/symptom` 这类带命名空间的 id。 */
+export const WIKI_TYPE_ID_PATTERN = /^[a-z][a-z0-9_/-]{1,60}$/