dsh-data-domain-knowledge 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/types.ts

@@ -7,7 +7,12 @@ export type KnowledgeStatus = 'unreviewed' | 'draft' | 'reviewed' | 'active' | '
  * 注册表允许用户追加自定义分类，所以**运行时一律按 `string` 处理**
  * （见 `SourceType`）；这个字面量联合只用来标记哪些 id 是内置的。
  */
-export type BuiltinSourceType = 'chat_message' | 'ai_chat_message' | 'document' | 'book' | 'article' | 'prd' | 'question'
+export type BuiltinSourceType =
+  | 'chat_message'
+  | 'agent_chat_message'
+  | 'agent_diagnosis_case'
+  | 'document' | 'book' | 'article' | 'prd' | 'question'
+  | 'table' | 'metric' | 'data_dev_script' | 'query_case'
 /** 来源业务分类 id。自定义分类是开放集合，所以不是字面量联合。 */
 export type SourceType = string
 /**
@@ -20,8 +25,8 @@ export type SourceType = string
  */
 export type SchemaType =
   | 'concept' | 'metric' | 'table' | 'event' | 'playbook' | 'case'
-  | 'diagnosis/symptom' | 'diagnosis/hypothesis' | 'diagnosis/check'
-  | 'diagnosis/failure-mode' | 'diagnosis/case'
+  | 'diagnosis/symptom' | 'diagnosis/hypothesis' | 'diagnosis/check-point'
+  | 'diagnosis/failure-reason' | 'diagnosis/case'
 export type EmbeddingProvider = 'wemm-python' | 'ollama' | 'none'
 export type EmbeddingDevice = 'auto' | 'mps' | 'cpu'
 export type RerankProvider = 'bert-python' | 'none'
@@ -69,7 +74,7 @@ export interface KnowledgeConfig {
    */
   agentRoot: string
   /**
-   * @deprecated 0029：这是**旧布局**的知识树根（`01_source_truth` 直接躺在它
+   * @deprecated 0029：这是**旧布局**的知识树根（`01_source_raw` 直接躺在它
    * 下面）。它不再可设置，也不再决定任何路径 —— 只作为一次性的迁移来源存在：
    * 值非空且新位置还是空的时，把旧树搬进 `<agentRoot>/domain_knowledge/default`。
    * 搬完（或本来就没有）它就不再有意义。
@@ -88,17 +93,23 @@ export interface KnowledgeConfig {
    * Pass 0（候选抽取 + 归一）的总开关。
    *
    * 默认**开**：它是「SourceRaw → Wiki」这条链上唯一不依赖模型的一步，关掉之后
-   * 知识库就只能靠 Agent 逐张 `write_knowledge_card` 长大。关掉的场景是真实存在的
-   * （批量导入时不想让每份文档都自动长出一张未审核卡片），所以它必须可关，
+   * 知识库就只能靠人一次次手工补卡片。关掉的场景是真实存在的
+   * （批量导入时不想让每份文档都自动长出一张卡片），所以它必须可关，
    * 但关掉不等于删除：计数器会如实回 0，而不是假装抽过了。
    */
   extractCandidates: boolean
   /**
-   * #3b：用模型做**实体抽取与归并**（`extract-model.ts`）。
+   * #3b：用模型做**按 schema 的实体抽取与归并**（`extract-model.ts`）。
    *
-   * 开着时，`rebuild` 把「这份来源里有哪些实体、其中哪些 wiki 里已经有了」交给模型；
-   * 关系候选仍由规则抽取补上，模型不可用则整轮退回规则。所以它是**增强**而不是依赖 ——
-   * 关掉它链路照跑，只是同一实体横跨两份文档时可能落成两张卡（实测过）。
+   * 开着时，`rebuild` 把「这份来源里有哪些实体、每个实体该写成什么样的小节、
+   * 其中哪些 wiki 里已经有了」交给模型；关系候选仍由规则抽取补上，模型不可用则整轮
+   * 退回规则。所以它是**增强**而不是依赖 —— 关掉它链路照跑，只是同一实体横跨两份
+   * 文档时可能落成两张卡（实测过），而且卡片正文会退回成按小节切下来的原文片段。
+   *
+   * **0044 起默认开。** 编译的全部价值就是「按 wiki schema 提取实体」，而这件事只有
+   * 模型做得了：规则路径拿 `##` 小节标题当实体名，切出来的就是目录，不是知识。
+   * 0040 时期默认关，是因为那时候抽出来的东西要人逐条确认、成本要省着花；
+   * 现在入库在前、review 在后，默认关等于默认不编译。
    *
    * 触发时机跟着来源走：只有**变化的来源**才进这一轮（增量复用没变的不重跑），
    * 所以成本与「改了多少来源」成正比，而不是与库的大小成正比。
@@ -137,6 +148,14 @@ export interface KnowledgeConfig {
   vectorThreshold: number
   /** Stage 4 rerank: how many reranked wikiNotes enter the model context. */
   contextTopN: number
+  /**
+   * 上下文最大字符数（0050）。默认 20000，`0` = 不限。
+   *
+   * 它约束的是**组装后的上下文字符数**（命中的 note 正文 + 扩展卡片的标题/摘要/正文），
+   * 不是 `hits` 的长度：5 条 note 可能是一千字，也可能是十万字（一条 note 就是卡片的一整节）。
+   * 超出的部分落系统临时目录，上下文里留一行绝对路径，Agent 用自己的文件读取能力去取。
+   */
+  contextMaxChars: number
   /**
    * Stage 4 重排后的最低分（0..1，sigmoid 之后的 cross-encoder 分）。
    *
@@ -184,7 +203,7 @@ export type RuntimeKnowledgeConfig = Omit<KnowledgeConfig, 'rootDir' | 'agentRoo
 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'],
+  sourceAppendTypes: ['chat_message', 'agent_chat_message', 'document'],
   allowSourceTruth: true,
   // 0029 撤掉了 `maxSourceBytes`：单条来源**没有**字符数上限。见
   // `runtime.ts` 的 `addSource` —— 真正的边界是转换内核的 `maxInputBytes`
@@ -192,9 +211,9 @@ export const DEFAULT_KNOWLEDGE_CONFIG: RuntimeKnowledgeConfig = {
   // 只有显式写 `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()),
+  // 0044：模型抽取默认**开**，因为「按 schema 提取实体」就是编译本身。只有在
+  // env 里显式写 `false` / `0` 才关（关掉后退回纯规则 Pass 0：按小节切，正文是原文片段）。
+  extractWithModel: !['false', '0'].includes((process.env.DSH_KNOWLEDGE_EXTRACT_WITH_MODEL ?? '').trim().toLowerCase()),
   // 0029：三个「家当」路径的默认值是**空串 = 自动**。它们跟着 `<agentRoot>/resource/`
   // 走，而 agentRoot 由设置决定、模块加载时还不知道 —— 所以在运行时解析
   // （`runtime.ts` 的 `resolveResources`）。环境变量仍然优先。
@@ -229,13 +248,14 @@ export const DEFAULT_KNOWLEDGE_CONFIG: RuntimeKnowledgeConfig = {
    */
   vectorThreshold: Number(process.env.DSH_KNOWLEDGE_VECTOR_THRESHOLD || 0.5),
   contextTopN: Number(process.env.DSH_KNOWLEDGE_CONTEXT_TOP_N || 5),
+  contextMaxChars: Number(process.env.DSH_KNOWLEDGE_CONTEXT_MAX_CHARS || 20_000),
   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`。 */
+/** 一条原始可追溯文档（SourceRaw）。磁盘布局沿用 `01_source_raw`。 */
 export interface SourceRaw {
   sourceId: string
   sourceType: SourceType
@@ -270,6 +290,42 @@ export interface SourceRawRead extends SourceRaw {
   totalChars: number
 }
 
+/**
+ * 一条**人工备注**（0044）。
+ *
+ * 它永远不进 `content`。理由只有一个：wiki 正文由编译产出，人往正文里写字就等于让
+ * 「这一段是谁写的」失去答案 —— 下一次编译追加内容时，人写的那段该保留还是该被覆盖，
+ * 没有任何判据。备注单独存，两个问题一起消失：编译只管自己的正文，人只管自己的判断。
+ *
+ * `kind: 'anomaly'` 是「这里有异常点」的显式标记 —— 例如卡片里的数字与原始文档对不上、
+ * 两处口径互相矛盾。它比一条普通备注更需要被召回时看见，所以在上下文包里单独标出。
+ */
+export interface CardAnnotation {
+  id: string
+  kind: 'note' | 'anomaly'
+  note: string
+  author?: string
+  createdAt: string
+  /** 这条备注针对哪一份来源（可选）；异常点常常能指到具体文档。 */
+  sourceRef?: string
+}
+
+/**
+ * 一张卡片的 review 结论与评分（0044）。
+ *
+ * **入库在前、review 在后。** 卡片一编译出来就落盘、就进召回，`state` 是
+ * `unreviewed`；人看过了把它标成 `reviewed`，`score` 随之抬到
+ * `REVIEWED_SCORE_FLOOR`。评分的作用是**召回排序里的一个有界加权**，不是准入闸门 ——
+ * 没 review 过的卡片照样召回得到，只是排得稍后一点。
+ */
+export interface CardReview {
+  state: 'unreviewed' | 'reviewed'
+  /** 0..1。新卡是 `CARD_REVIEW_BASE_SCORE`，reviewed 之后不低于 `REVIEWED_SCORE_FLOOR`。 */
+  score: number
+  reviewedAt?: string
+  reviewedBy?: string
+}
+
 export interface KnowledgeCard {
   entityId: string
   entityType: SchemaType
@@ -279,12 +335,32 @@ export interface KnowledgeCard {
   content: string
   sourceRefs: string[]
   provenance?: LineageRef[]
+  /**
+   * 负责人（0021 §6.4 的卡片信封）。
+   *
+   * 0049 之前 `loadCards` 不读它，于是**编译路径看不见这个字段**：任何一次
+   * 「重写这张卡片」（补图、补相关块）都会把它从文件里抹掉，而 `check.owner` 是
+   * 那个 schema 的必填字段 —— 一次与它无关的编译就能让卡片变成待补。现在读进内存，
+   * 重写时原样带回去。
+   */
+  owner?: string
   metadata: Record<string, unknown>
   updatedAt: string
   /** Resolved local markdown image references used by the multimodal embedder. */
   imagePaths?: string[]
+  /** 人工备注（0044）。正文之外的东西，编译不碰它。 */
+  annotations?: CardAnnotation[]
+  /** review 结论与评分（0044）。缺省 = 还没人看过。 */
+  review?: CardReview
 }
 
+/** 新卡片的出厂评分：入库即生效，review 不是前提。 */
+export const CARD_REVIEW_BASE_SCORE = 0.35
+/** review 通过之后的评分下限。 */
+export const REVIEWED_SCORE_FLOOR = 0.8
+/** 标记为异常点时，评分降到这个值 —— 它仍然召回得到，只是排在后面。 */
+export const ANOMALY_SCORE = 0.15
+
 /**
  * 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
@@ -312,6 +388,11 @@ export interface WikiNote {
   status: KnowledgeStatus
   /** Local markdown image references are embedded with the text when possible. */
   imagePaths?: string[]
+  /**
+   * 父级 wiki 的 review 评分（0044）。**不进 note 的正文，也不参与向量指纹** ——
+   * 它只影响融合分的加权，所以 review 一下不会让整个语料重新编码。
+   */
+  reviewScore?: number
 }
 
 /** Backwards-compatible alias: compiled retrieval units are now wikiNotes. */
@@ -451,11 +532,27 @@ export interface ContextGraph {
   edges: Array<Record<string, unknown>>
 }
 
+/**
+ * 上下文里的一条：**一张 wiki 卡片**，不是一条 note（0050）。
+ *
+ * 0050 之前一条上下文对应一条 note，于是同一张卡片的多个小节能吃掉 `context_top_n`
+ * 的全部名额。现在按卡片去重：命中的那几张卡片各带**它命中的那些 note**（按重排分降序），
+ * 再按「该卡片最好那条 note 的重排分」排序 —— 卡片级顺序仍然由片段级重排决定。
+ *
+ * 顺序是硬约束：**先去重，再扩展**。反过来就分不清哪张是召回来的、哪张是邻居。
+ */
 export interface ContextItem {
-  note: RecallHit
   wiki: KnowledgeCard | null
-  /** 1-hop subgraph around the hit's wiki card. */
+  /** 命中的 note（按重排分降序）。`reason === 'expansion'` 时为空。 */
+  notes: RecallHit[]
+  /** `notes[0]` 的别名：只要「最好那一片」的消费方用它。扩展条目没有它。 */
+  note?: RecallHit
+  /** 这张卡片自己的一跳子图。 */
   graph: ContextGraph
+  /** 这张卡片为什么在上下文里：命中，还是 1 跳扩展。 */
+  reason: 'hit' | 'expansion'
+  /** 扩展条目：它是从哪张命中的卡片、沿哪条边连过来的。 */
+  via?: { entityType: string; entityId: string; title: string; relation: string }
   /**
    * 这条命中引用的 SourceRaw 证据片段（0031）。
    *
@@ -465,12 +562,101 @@ export interface ContextItem {
   evidence?: RecallEvidence[]
 }
 
+/**
+ * 召回各阶段的耗时（毫秒）——「为什么慢」的答案必须能在界面上看见（0050 第二版）。
+ *
+ * 拆得比「总耗时」细，是因为这几个数**量级差得很远**：查询编码在模型已加载时约 270ms，
+ * 首次（含加载 2B 模型）约 8s；重排同理（首次含加载 BERT）。只给一个总数时，人只会觉得
+ * 「这个测试很慢」，而看不出慢在加载模型还是慢在算法。
+ *
+ * 每个字段都是**这一段自己的**耗时，不是累计值。
+ */
+export interface RecallTimings {
+  /** 关键词路：FTS5 查询 + 多字词覆盖率算分。 */
+  ftsMs: number
+  /** 向量路整体（= `embedMs` + `scanMs` + 阈值与排序）。 */
+  vectorMs: number
+  /** 其中：查询编码。**首次含模型加载**，所以它可能是 8000ms 而不是 270ms。 */
+  embedMs?: number
+  /** 其中：索引扫描（汉明预筛 + int8 精算）。 */
+  scanMs?: number
+  /** 图谱 boost 的名次表。 */
+  graphMs: number
+  /** RRF 融合 + 图谱加权 + 排序。 */
+  fuseMs: number
+  /** cross-encoder 重排。**首次含模型加载**；跳过重排时没有这个字段。 */
+  rerankMs?: number
+  /** 组装：按卡片去重 + 1 跳扩展 + 上下文预算装箱。 */
+  assembleMs: number
+  /** 这一整次召回（从进入到返回）。 */
+  totalMs: number
+}
+
+/**
+ * 面板账本的一行（0050）：**这一路**对这个候选算出的分数与它的名次。
+ *
+ * 它只在 HTTP 的 `detail=true` 上返回，工具调用不带 —— 账本是给人看的（哪条被丢了、
+ * 各自多少分），进模型上下文只会变成几十行噪声。
+ */
+export interface RecallLedgerRow {
+  unitId: string
+  title: string
+  entityType: string
+  entityId: string
+  /** 这一路自己的分数（关键词 BM25 / 向量余弦 / 融合分）。 */
+  score: number
+  /** 这一路内部的名次（1 起）。 */
+  rank: number
+  /** 过没过这一路的阈值。 */
+  kept: boolean
+}
+
+/** 面板账本：每一路的全部候选 + 重排的全部候选（含被丢弃的）。 */
+export interface RecallLedger {
+  /** 关键词路：`rows` 含没过阈值的那些。 */
+  fts: RecallLedgerRow[]
+  /** 向量路：同上。 */
+  vector: RecallLedgerRow[]
+  /** 融合后进入重排的候选。`logit` 是模型原始分（跨查询可比的那个刻度）。 */
+  rerank: Array<RecallLedgerRow & { fused: number; logit?: number; rerankScore?: number; dropped: boolean }>
+}
+
+/** 1 跳扩展的结果（0050）：命中卡片之外，按图上的边拉进来的邻居。 */
+export interface RecallExpansion {
+  /** 邻居卡片。`via` 是「从哪张卡、沿哪条边」—— 一条邻居可能有多条来路。 */
+  nodes: Array<{ entityType: string; entityId: string; title: string; via: string[] }>
+  /** 这些邻居之间的边（只含两端都在扩展集里的）。 */
+  edges: Array<Record<string, unknown>>
+  /** 其中真的进了上下文的（其余被预算挡在外面）。 */
+  included: string[]
+}
+
+/**
+ * 上下文预算（0050）的真实账：装进去多少、挤掉多少、溢出文件在哪。
+ *
+ * 每个数都来自一次真实的拼接，没有估算 —— 面板据此显示「还有 N 张卡片没进上下文」。
+ */
+export interface ContextBudgetReport {
+  /** 这次生效的上限（`0` = 不限）。 */
+  maxChars: number
+  /** 装进上下文的字符数。 */
+  usedChars: number
+  /** 因为预算没进上下文的卡片数与字符数。 */
+  omittedCards: number
+  omittedChars: number
+  /** 命中的卡片数（去重后）与扩展进来的卡片数。 */
+  hitCards: number
+  expandedCards: number
+  /** 溢出文件的绝对路径（有溢出时才有；它在系统临时目录里，不随库走）。 */
+  overflowPath?: string
+}
+
 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. */
+  /** Distinct wiki cards hit by the recalled notes（去重后，按各自最好那条 note 排序）。 */
   wiki: KnowledgeCard[]
   /** Union of the 1-hop subgraphs of the recalled wiki cards. */
   graph: ContextGraph
@@ -493,6 +679,14 @@ export interface RecallResult {
   insufficientEvidence: boolean
   /** 每一路在这一轮里发生了什么（阈值、候选数、最高分、降级原因）。 */
   diagnostics: RecallDiagnostics
+  /** 1 跳扩展的结果（0050）。没有邻居时是空集，不是缺字段。 */
+  expansion?: RecallExpansion
+  /** 上下文预算的真实账（0050）。 */
+  budget?: ContextBudgetReport
+  /** 面板账本（0050）：只在 `detail: true` 时返回。 */
+  ledger?: RecallLedger
+  /** 各阶段耗时（毫秒）。它很小，所以不藏在 `detail` 后面 —— Agent 也会问「为什么慢」。 */
+  timings?: RecallTimings
   recallId: string
   indexVersion?: number
   compileRunId?: string
@@ -519,10 +713,13 @@ export interface KnowledgeBase {
    */
   wikiTypes: WikiTypeDef[]
   /**
-   * 卡片 schema 的生效方式：`report` 只把问题写进卡片并回报，`strict` 直接拒绝不合规的写入。
-   * 默认 `report`，避免存量卡片在升级后被挡在门外。
+   * 0044 撤掉了 `wikiSchemaMode`（`strict` 拒绝不合规写入 / `report` 只标记）。
+   *
+   * 两个理由：**缺信息也入库**是这一版的核心决定（卡片记下来，后面有涉及到的文档再补），
+   * 而一个「拒绝写入」的开关与它直接冲突；而且校验本身已经不再决定写不写 —— 它只把问题
+   * 写进 `metadata.schema_issues`，由面板显示成「待补」。留一个什么都不拦的开关，
+   * 比没有更糟：界面上摆着它，人就会以为它在起作用。
    */
-  wikiSchemaMode: WikiSchemaMode
   /**
    * 计算字段：当前 `wikiTypes` 是否已偏离出厂定义。界面据此决定「恢复默认」是否可点，
    * 也让人一眼看出这套 schema 是本库自己调过的。
@@ -558,7 +755,7 @@ export interface KnowledgeDocument {
   createdAt: string
   updatedAt: string
   versionCount: number
-  /** 相对知识库根目录，如 `01_source_truth/<slug>.md`。 */
+  /** 相对知识库根目录，如 `01_source_raw/<slug>.md`。 */
   relativePath: string
   ext: string
 }
@@ -570,8 +767,21 @@ export interface KnowledgeAssetRef {
   url: string
 }
 
+/**
+ * 文档详情。
+ *
+ * `content` **可能只是正文的前一段**：明细接口按 `SOURCE_PREVIEW_CHARS` 封顶，
+ * 因为抽屉里的预览读不完一份几十万字文档，而把它整份发过来正是「打开弹层要等半天」
+ * 的原因。要全文走独立整页的分页接口（`GET /knowledge/documents/:docId/content`）。
+ * 两件事分开之后，`contentChars` / `contentTruncated` 就是界面必须读的那两个字段 ——
+ * 「这里显示了多少、全文有多少」不能靠猜。
+ */
 export interface KnowledgeDocumentDetail extends KnowledgeDocument {
   content: string
+  /** 正文总字符数（不是 `content.length`）。 */
+  contentChars: number
+  /** `content` 是否被截断过。为真时界面要给「新页面打开」。 */
+  contentTruncated: boolean
   frontmatter: Record<string, unknown>
   assets: KnowledgeAssetRef[]
   lineage?: Record<string, string>
@@ -613,10 +823,27 @@ export function deriveSourceExt(metadata: Record<string, unknown> | undefined):
     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'
+  return FORMAT_EXTENSION[format] ?? (format ? `.${format}` : '.md')
+}
+
+/**
+ * 格式类 → 扩展名。
+ *
+ * 为什么需要这张表：扩展名与格式类**不是一回事**（`web_page` 的底稿是 `.html`，
+ * `office` 可能是 `.docx` / `.xlsx` / `.pptx`），而 0048 之后 front matter 里只有格式类
+ * 和底稿文件名，没有那个已经失效的暂存路径可查。表里没有的格式退回 `.${format}`：
+ * 一个看得出是推导出来的扩展名，好过假装知道。
+ */
+const FORMAT_EXTENSION: Record<string, string> = {
+  markdown: '.md',
+  text: '.txt',
+  html: '.html',
+  pdf: '.pdf',
+  office: '.docx',
+  web_page: '.html',
+  video: '.mp4',
+  audio: '.mp3',
+  image: '.png',
 }
 
 export interface RebuildReport {
@@ -668,19 +895,40 @@ export interface RebuildReport {
    * 「SourceRaw → Wiki」第一段的诚实计数。
    *
    * 这八个数**每一个都来自真实发生过的事件**，没有一个是估算出来的：抽取了几个
-   * 候选、其中几个被类型闸门拒了、建了几张卡、并进几张卡、几条关系真的连上了、
+   * 候选、其中几个被类型闸门拒了、新建了几张卡、更新了几张卡、几条关系真的连上了、
    * 几条因为端点不存在被丢掉、几份来源这次被重抽、几份因为指纹没变被跳过。
    * `extractCandidates` 关掉时它们全部回 0，而不是从响应里消失 —— 「跳过」和
    * 「没有这个能力」是两件事，用缺字段表达会让人分不清。
    */
   candidatesExtracted: number
   candidatesRejected: number
+  /**
+   * 这一轮**新建**的 wiki 卡片数。
+   *
+   * 名字从 `proposalsCreated` 改回来（0044）：Pass 0 重新直接落卡，不再只提议。
+   * 0040 v1.5 那道「人确认之后才入库」的门在 0044 撤掉了 —— 入库在前，review 在后，
+   * 所以计数必须如实说「新建了 N 张卡片」，而磁盘上真的有 N 张。
+   */
   cardsCreated: number
-  cardsMerged: number
+  /** 这一轮**更新**（把新抽到的正文追加进去、或补上来源）的已有卡片数。 */
+  cardsUpdated: number
   relationsExtracted: number
   relationsDropped: number
   sourcesExtracted: number
   sourcesSkipped: number
+  // ------------------------------------------------ Finalize · 索引 / 断链 / 相关
+  /**
+   * 收尾段（0049）的真实计数。三段都不调模型，全是规则与图算法。
+   *
+   * `relatedLinks` 是**相关链接条数**（一张卡片指向另一张算一条，双向各算一条），
+   * `relatedCards` 是有至少一条相关的卡片数，`deadLinks` 是正文里指向不存在卡片的
+   * `[[…]]` 条数 —— 它是三层校验里 `reference` 那一层。
+   */
+  relatedLinks?: number
+  relatedCards?: number
+  deadLinks?: number
+  /** 这一轮因为补相关块或改写断链问题而重写的卡片数。 */
+  finalizeRewritten?: number
 }
 
 // ------------------------------------------------- 来源业务分类注册表（0013）
@@ -712,10 +960,96 @@ export interface SourceTypeDef {
   builtin: boolean
   /** 兜底分类（`document`）：必须存在且不可停用，判定链最后一步落在它上。 */
   fallback: boolean
+  /**
+   * 这个分类的来源**该带哪些元数据字段**（0048）。
+   *
+   * 为什么放在类型定义里而不是写死一份全局清单：一张指标表的元数据和一篇公众号
+   * 文章需要的完全不是同一批东西 —— 指标要口径与负责人，文章要作者与发布时间。
+   * 声明在分类上，面板才能在「录入向导 / 来源详情」里说清**这一类**缺了什么，
+   * 而不是对所有来源提同一份要求。
+   *
+   * `required: true` 的字段缺失时**不拒收**（缺信息也编译进去），只如实报出来。
+   */
+  metadataFields?: SourceMetadataField[]
   /** 计算字段：该库中引用该分类的来源数，由 `refresh` 实时算出，不参与持久化。 */
   sourceCount: number
 }
 
+/**
+ * 一个来源分类声明的元数据字段（0048）。
+ *
+ * `key` 用 front matter 里的**顶层键名**（OKF v0.2 的词汇：`resource` / `description` /
+ * `sources[].author` / `generated.at` …），这样面板能直接拿它去 front matter 里取值，
+ * 不需要第二张映射表。
+ */
+export interface SourceMetadataField {
+  /** front matter 顶层键，或 `sources[0].author` 这种点路径。 */
+  key: string
+  label: string
+  /** 一句话说明这个字段是什么，面板上作为提示。 */
+  description?: string
+  /** 缺失时提示「这一类来源通常要带它」，但**不拒收**。 */
+  required?: boolean
+}
+
+/**
+ * 一份来源的 OKF v0.2 溯源信息（0048）。
+ *
+ * 字段名直接取自 OKF v0.2（<https://github.com/GoogleCloudPlatform/open-knowledge-format>）：
+ * `description` / `resource` / `generated{by,at}` / `sources[]`。规范里没有「采集时间」
+ * 这个概念，所以采集时间写在 `generated.at`（本文件是什么时候、被谁写出来的）。
+ */
+export interface SourceProvenance {
+  /** 一句话摘要（OKF `description`）。 */
+  description?: string
+  /** 底层资产的规范地址（OKF `resource`）：原始网页地址，或库内相对路径。 */
+  resource?: string
+  /** 谁把这份文件写出来的（OKF `generated.by`），如 `convert/web@1/wx_article`。 */
+  generatedBy?: string
+  /** 什么时候写出来的（OKF `generated.at`），即采集/转换时间。 */
+  generatedAt?: string
+  /** 这份文件的来源清单（OKF `sources[]`）。 */
+  sources?: SourceOriginRef[]
+  /** 标签（OKF `tags`）。 */
+  tags?: string[]
+}
+
+/**
+ * 元数据字段声明的规范化。
+ *
+ * 只做「去掉空值、去重、trim」这类整理，不做严格校验：字段清单是**提示性**的
+ * （缺失只报不拒），为它设一道硬闸门只会让人没法保存一个还在想字段名的草稿。
+ * `key` 必须非空且不含空白 —— 它要被当成 front matter 的路径去取值。
+ */
+export function normalizeMetadataFields(input: unknown): SourceMetadataField[] {
+  if (!Array.isArray(input)) return []
+  const seen = new Set<string>()
+  const fields: SourceMetadataField[] = []
+  for (const item of input) {
+    if (item === null || typeof item !== 'object') continue
+    const record = item as Record<string, unknown>
+    const key = typeof record.key === 'string' ? record.key.trim() : ''
+    if (!key || /\s/.test(key) || seen.has(key)) continue
+    seen.add(key)
+    const label = typeof record.label === 'string' && record.label.trim() ? record.label.trim() : key
+    const description = typeof record.description === 'string' && record.description.trim() ? record.description.trim() : undefined
+    fields.push({ key, label, ...(description ? { description } : {}), ...(record.required === true ? { required: true } : {}) })
+  }
+  return fields
+}
+
+/** OKF `sources[]` 里的一条。`resource` 是条目内唯一必填。 */
+export interface SourceOriginRef {
+  /** 稳定键，正文引用与逐条归属都用它。 */
+  id: string
+  resource: string
+  title?: string
+  /** 来源的产出者（作者 / 账号 / 团队）。 */
+  author?: string
+  /** 来源自身最后变更时间（ISO 8601），对网页就是发布时间。 */
+  lastModified?: string
+}
+
 /** 分类 id 的形状约束；与 0013 规范第 1 节一致。 */
 export const SOURCE_TYPE_ID_PATTERN = /^[a-z][a-z0-9_]{1,40}$/
 /** 兜底分类 id；判定链全不命中时落它，因此它不可停用、不可删除。 */
@@ -735,14 +1069,23 @@ export const BUILTIN_SOURCE_TYPES: ReadonlyArray<Omit<SourceTypeDef, 'sourceCoun
     label: '聊天日志',
     description: '人与人之间在日常沟通中产生的消息记录，以对话往返为主要形态。',
     signals: ['有发言人与时间戳的短消息流', '多话题跳转、口语化、缩写多', '常见 @提及、表情、附件'],
-    excludes: ['与 AI 的对话归 ai_chat_message', '整理后的会议纪要归 document', '已成问题—根因—方案的记录归 question'],
+    excludes: ['与 AI 的对话归 agent_chat_message', '整理后的会议纪要归 document', '已成问题—根因—方案的记录归 question'],
     enabled: true,
     builtin: true,
     fallback: false,
   },
   {
-    id: 'ai_chat_message',
-    label: 'AI 对话日志',
+    /**
+     * `ai_chat_message` 在 0040 改名为 `agent_chat_message`（**只改名，不改语义**）。
+     *
+     * 理由：原有八个内置分类里只有它带 `ai_` 前缀，而链路里其他地方一律用 `agent`
+     * （`agent_diagnosis_case`、Agent 工具、`agentRoot`）。统一词根，避免同一份设计里
+     * 出现两套命名。存量来源靠一次性迁移换目录 + 改 frontmatter（见
+     * `runtime.migrateLegacySourceTypeRename`），注册表侧的旧 id 在
+     * `normalizeSourceTypes` 里按别名认。
+     */
+    id: 'agent_chat_message',
+    label: '用户与 AI 的对话日志',
     description: '用户与 AI 助手之间的完整对话记录，包含双方往返消息。',
     signals: ['user / assistant 角色交替', '提示词与回答成对出现', '代码块密集、常与会话 id 或模型名同现'],
     excludes: ['人在群里转贴 AI 回答归 chat_message', '由 AI 对话整理出的方法论文档归 document 或 article'],
@@ -750,6 +1093,28 @@ export const BUILTIN_SOURCE_TYPES: ReadonlyArray<Omit<SourceTypeDef, 'sourceCoun
     builtin: true,
     fallback: false,
   },
+  {
+    /**
+     * `agent_diagnosis_case`（0040 §3.1）—— **AI 诊断日志**。
+     *
+     * 它装的是**一次排查的过程记录**：现象、走过的路径（有序）、每个检查点的产出
+     * （含被否定与给不出结论的）、确认的根因、耗时、误导段。作者是 Agent，
+     * 每次排查结束自动写一条（`externalId` = runId，重跑不产生重复记录）。
+     *
+     * **与 `question` 的边界是「谁写的、是不是已经归纳过」**：
+     * 人写的结论（手册、人工复盘）→ `question`；Agent 自动记录的过程 → 这里。
+     * 同一件事可以有两条来源，它们不是重复 —— 一个回答「结论是什么」，
+     * 一个回答「当时怎么走的」。
+     */
+    id: 'agent_diagnosis_case',
+    label: 'AI 诊断日志',
+    description: 'Agent 跑完一次问题排查后留下的过程记录：现象、路径、各检查点的产出、确认的根因、耗时与误导段。',
+    signals: ['带 runId / 现象 id / 耗时与有序路径的结构化记录', '每个检查点有成对的「实际查询 + 结果 + 这个结果算不算数」', '含被否定的假设与「给不出结论」的检查'],
+    excludes: ['人写的手册与人工复盘归 question', '由这次排查归纳出的卡片是 wiki 卡片而不是来源，那类内容归 document', '日常取数问答归 query_case'],
+    enabled: true,
+    builtin: true,
+    fallback: false,
+  },
   {
     id: 'document',
     label: '企业内部文档',
@@ -795,7 +1160,7 @@ export const BUILTIN_SOURCE_TYPES: ReadonlyArray<Omit<SourceTypeDef, 'sourceCoun
     label: '问题排查文档',
     description: '以某个具体问题或故障为中心的记录：现象、影响、排查过程、根因、解决方案与后续动作。',
     signals: ['错误码、堆栈或日志片段', '复现步骤、临时规避、根因、修复版本', '时间线、一问一答或一问题多方案'],
-    excludes: ['一般性经验总结归 document', '产品需求归 prd', '外部作者的公开分析归 article'],
+    excludes: ['一般性经验总结归 document', '产品需求归 prd', '外部作者的公开分析归 article', 'Agent 跑出来的一次排查过程记录归 agent_diagnosis_case'],
     enabled: true,
     builtin: true,
     fallback: false,
@@ -862,6 +1227,20 @@ export const BUILTIN_SOURCE_TYPES: ReadonlyArray<Omit<SourceTypeDef, 'sourceCoun
 
 const BUILTIN_SOURCE_TYPE_IDS: ReadonlySet<string> = new Set(BUILTIN_SOURCE_TYPES.map(def => def.id))
 
+/**
+ * 改名之前的来源分类 id → 新 id（0040 §3.2）。
+ *
+ * 它有两个消费者，缺一个就会静默丢东西：
+ * 1. **注册表**（`normalizeSourceTypes`）—— 存量 `knowledge-bases.json` 里那一项写着
+ *    旧 id，不认别名的话它会被当成一个**自定义分类**留下来，于是「注册表里到底有什么」
+ *    永远说不清（内置项和它并存）。
+ * 2. **磁盘**（`runtime.migrateLegacySourceTypeRename`）—— `01_source_raw/` 是按分类
+ *    分目录的，存量来源的 frontmatter 里写着 `source_type: ai_chat_message`。
+ */
+export const LEGACY_SOURCE_TYPE_IDS: Record<string, string> = {
+  ai_chat_message: 'agent_chat_message',
+}
+
 export function isBuiltinSourceType(id: string): boolean {
   return BUILTIN_SOURCE_TYPE_IDS.has(id)
 }
@@ -919,12 +1298,16 @@ function deepFreeze<T>(value: T): T {
 
 export const SOURCE_CLASSIFIER_PROMPT: SourceClassifierPrompt = deepFreeze({
   readonly: true,
-  version: 2,
+  version: 3,
   title: '来源业务分类判定规则',
   priority: [
     { type: 'user', rule: '用户显式指定分类 → 直接用，记 source_type_source: user。' },
-    { type: 'ai_chat_message', rule: '内容是人与 AI 的对话记录（含 AI 回复）→ ai_chat_message。' },
+    { type: 'agent_chat_message', rule: '内容是人与 AI 的对话记录（含 AI 回复）→ agent_chat_message。' },
     { type: 'chat_message', rule: '内容是人与人之间的消息流（IM / 会议聊天 / 客服会话）→ chat_message。' },
+    // `agent_diagnosis_case` 紧跟对话类、排在通用文档之前：它的形状最特征化
+    // （runId + 有序路径 + 每个检查点的「实际查询 / 结果 / 算不算数」），而它和
+    // `question` 最容易混 —— 落到 question 之后再想捞回来就晚了。
+    { type: 'agent_diagnosis_case', rule: '内容是 Agent 跑完一次排查留下的过程记录（runId + 有序路径 + 每个检查点的实际查询与结果 + 确认的根因 + 耗时）→ agent_diagnosis_case。' },
     // 数据域四类排在通用文档之前：它们的形状（DDL、公式、SQL、问答）比
     // 「像不像一篇内部文档」更特征化，落到 document 之后再想捞回来就晚了。
     // 四类之间的次序按「定义的确定性」排：口径与表结构有明确文本特征，脚本次之，
@@ -932,7 +1315,7 @@ export const SOURCE_CLASSIFIER_PROMPT: SourceClassifierPrompt = deepFreeze({
     { type: 'metric', rule: '内容在定义一个可计算的量化口径（指标名 + 公式 + 维度 / 粒度 / 负责人）→ metric。' },
     { type: 'table', rule: '内容在描述一张表或数据集本身（字段清单、类型、分区、主键、更新频率）→ table。' },
     { type: 'data_dev_script', rule: '内容是生产数据的加工逻辑（SQL / PySpark / Shell / 调度定义，读什么写什么）→ data_dev_script。' },
-    { type: 'question', rule: '内容以某个具体问题或故障为中心（现象 → 排查 → 根因 → 措施）→ question。' },
+    { type: 'question', rule: '内容是**人写**的、以某个具体问题或故障为中心的结论（现象 → 排查 → 根因 → 措施）→ question。' },
     { type: 'query_case', rule: '内容是一次取数问答的完整记录（问题 → 口径 → SQL → 结果）→ query_case。' },
     { type: 'prd', rule: '内容面向「要做什么功能、给谁用、怎么算做完」→ prd。' },
     { type: 'book', rule: '内容是正式出版物或成体系的整书 → book。' },
@@ -993,6 +1376,8 @@ export interface SourceTypeDraft {
   signals?: unknown
   excludes?: unknown
   enabled?: boolean
+  /** 这一类来源该带哪些元数据字段（0048）。缺省 = 不改动磁盘上已有的声明。 */
+  metadataFields?: unknown
 }
 
 export interface SourceTypeDraftProblem {
@@ -1076,7 +1461,8 @@ export interface WikiSectionSpec {
 /**
  * 一条 front matter / metadata 字段要求（机器读的部分）。
  *
- * `name` 对应 `write_knowledge_card` 的顶层字段（`owner` / `summary`）或 `metadata` 里的键。
+ * `name` 对应卡片的顶层字段（`owner` / `summary`）或 `metadata` 里的键 ——
+ * 编译器的抽取提示词会把这些字段名直接下发（0044），所以它同时是「机器读的部分」的契约。
  */
 export interface WikiFieldSpec {
   name: string
@@ -1088,7 +1474,14 @@ export interface WikiFieldSpec {
  * 一个 wiki 卡片类型（0024）。
  *
  * 它是"SourceRaw → Wiki"这一段的**约束**：哪些类型能生成、每类必须有哪些小节与字段、
- * 期望来自哪些来源分类、模板长什么样。判定与生成仍交给模型，这里给的是**判据与骨架**。
+ * 模板长什么样。判定与生成仍交给模型，这里给的是**判据与骨架**。
+ *
+ * **「期望来源分类」（`sourceTypes`）在 0040 删掉了。** 它当时的实际作用只有一条：
+ * reference 层校验时，卡片引用的来源分类不在列表里就提示一下、不阻断 —— 既不参与拦截，
+ * 也不参与生成，只是让人手填一份「我猜这类卡片大概会引用哪些来源」的静态清单。
+ * 三条撤销理由（详见 prd/0040 §4.2）：它是一份会漂移的猜测；「这类卡片该引用什么来源」
+ * 需要读卡片内容与历史引用分布，那是 Agent 在一次生成里顺手就能判断的事；而留着一个
+ * 不拦截的必填感字段，会教坏写定义的人。
  */
 export interface WikiTypeDef {
   /** 稳定 id，`^[a-z][a-z0-9_/-]{1,60}$`（允许 `diagnosis/symptom` 这类命名空间）。 */
@@ -1099,11 +1492,9 @@ export interface WikiTypeDef {
   layer: 'type' | 'instance'
   sections: WikiSectionSpec[]
   fields: WikiFieldSpec[]
-  /** 期望的来源业务分类 id（0013 的 `source_type`）；空数组表示不限制。 */
-  sourceTypes: string[]
   /** few-shot：用户会怎么提到这种卡片。随工具描述下发。 */
   examples: string[]
-  /** 模板卡（Markdown 骨架），新建卡片时照抄。 */
+  /** 模板卡（Markdown 骨架），新建卡片时照抄。由 `sections` / `fields` **派生**。 */
   template: string
   enabled: boolean
   /** 内置类型只允许停用，不允许删除。 */
@@ -1112,9 +1503,6 @@ export interface WikiTypeDef {
   cardCount: number
 }
 
-/** 卡片 schema 的生效方式。 */
-export type WikiSchemaMode = 'strict' | 'report'
-
 /** 卡片校验问题的一层。混成同一个「校验失败」，人就学不会怎么写卡片（0021 §1）。 */
 export type CardIssueLevel = 'format' | 'reference' | 'semantic'
 
@@ -1125,15 +1513,28 @@ export interface CardSchemaIssue {
   message: string
 }
 
-/** 卡片类型目录：注册表 + 生效方式 + 内置只读判定规则 + 当前卡片的问题清单。 */
+/** 卡片类型目录：注册表 + 内置只读判定规则 + 当前卡片的问题清单 + review 进度。 */
 export interface WikiTypeCatalog {
   types: WikiTypeDef[]
-  mode: WikiSchemaMode
   /** 内置只读的判定规则：模型该按什么顺序挑类型。 */
   rules: string
   /** 已落库卡片的三层校验结果（前 N 条）。 */
   issues: Array<CardSchemaIssue & { entityId: string; entityType: string }>
   issueCount: number
+  /**
+   * review 进度（0044）。
+   *
+   * 它取代了原来的 `proposals`（待审提议条数）。队列退役之后「还有几条等人确认」不再
+   * 是一个有意义的问题 —— 卡片一编译就入库了，剩下的问题是「入库的这些里我看过几条、
+   * 有几条被标了异常」。这三个数就回答它。
+   */
+  reviews: {
+    total: number
+    unreviewed: number
+    reviewed: number
+    /** 带 `kind: 'anomaly'` 备注的卡片数 —— 它们被评分压制，需要有人处理。 */
+    anomalies: number
+  }
 }
 
 /** 卡片类型 id 的形状；允许 `diagnosis/symptom` 这类带命名空间的 id。 */