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

package/src/runtime.ts

@@ -3,36 +3,59 @@ import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { appendFile, mkdir, readFile, readdir, rename, rm, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import {
   buildSourceTypeCatalog, defaultSourceTypes, DEFAULT_KNOWLEDGE_CONFIG, deriveSourceExt,
   FALLBACK_EMBEDDING_MODEL, FALLBACK_RERANK_MODEL, legacyResourceHome, SOURCE_TYPE_ID_PATTERN,
   LOCAL_EMBEDDING_MODEL_DIR, LOCAL_RERANK_MODEL_DIR,
-  type CardSchemaIssue, type ContextGraph, type ContextItem, type DocumentVersion, type Envelope,
+  ANOMALY_SCORE, CARD_REVIEW_BASE_SCORE, REVIEWED_SCORE_FLOOR,
+  type CardAnnotation, type CardReview, type CardSchemaIssue, type ContextGraph, type ContextItem, type DocumentVersion, type Envelope,
   type KnowledgeAssetRef, type KnowledgeCard, type KnowledgeConfig, type KnowledgeDocument,
   type KnowledgeDocumentDetail, type KnowledgeError, type KnowledgeStatus, type KnowledgeUnit,
-  type RecallDiagnostics, type RecallEvidence, type RecallHit, type RecallMode, type RecallResult, type RecallRoute, type RecallRouteDiagnostic, type RebuildReport,
-  type RerankResult, type RuntimeKnowledgeConfig, type SchemaType, type SearchHit, type SourceRaw, type SourceRawRead, type SourceType,
+  type ContextBudgetReport, type RecallDiagnostics, type RecallEvidence, type RecallExpansion, type RecallHit, type RecallLedger, type RecallLedgerRow, type RecallMode, type RecallResult, type RecallTimings, type RecallRoute, type RecallRouteDiagnostic, type RebuildReport,
+  type RerankResult, type RuntimeKnowledgeConfig, type SchemaType, type SearchHit, type SourceMetadataField, type SourceOriginRef, type SourceProvenance, type SourceRaw, type SourceRawRead, type SourceType,
   type SourceTypeCatalog, type SourceTypeDef, type WikiCardVersion, type WikiNote,
-  type WikiSchemaMode, type WikiTypeCatalog, type WikiTypeDef,
+  type WikiTypeCatalog, type WikiTypeDef,
 } from './types.js'
 import { defaultWikiTypes, validateCardAgainstType, WIKI_TYPE_RULES } from './wiki-types.js'
+import { LEGACY_ENTITY_TYPES } from './diagnosis/schema.js'
+import { DiagnosisStore } from './diagnosis/store.js'
 import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandidates, RELATES_TO, type NormalizedCandidates } from './extract.js'
-import { extractWithModel, type ModelCall } from './extract-model.js'
+import { extractWithModel, skeletonBody, type ModelCall } from './extract-model.js'
 import { FTS_FILE, FtsIndex, loadSqlite, segment } from './fts.js'
-import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, rrfFuse, selectContext, tokenSet, type RouteRanking } from './recall-rank.js'
+import { insertImage, planSourceImages, type SourceImage } from './source-images.js'
+import {
+  applyRelatedSection, buildWikiIndex, cardKey, deadLinkIssue, deadLinksOf, planRelated, stripRelatedSection,
+  type DeadLink, type RelatedEntry,
+} from './wiki-finalize.js'
+import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, reviewWeight, rrfFuse, tokenSet, type RouteRanking } from './recall-rank.js'
 import { legacyKnowledgeRoot } from './layout.js'
+import { unlinkIfExists, writeBufferAtomic, writeTextAtomic } from './fs-atomic.js'
 import { envelopeFailure, envelopeSuccess } from 'dsh-data-contracts/envelope'
 import type { LineageContext, LineageRef } from 'dsh-data-contracts/refs'
 
-// 05_diagnosis 是派生层（智能归因图谱）：内容可由 02_wiki + 03_compiled 重建，
-// 和 03_compiled 同性质，所以给独立编号段而不是塞进源头目录。
+// **知识树只有三段**（v1.1 起）：`01_source_raw` / `02_wiki` / `03_compiled`。
+//
+// 撤掉的两段，理由都写在这里，避免下一个人重新加回来：
 //
-// `00_schema` 在 0030 被撤掉了：它从建出来那天起就是一个**空目录**。分类注册表
-// 与 Wiki 类型注册表一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是
-// 配置，跟着根路径走，见 `knowledge-bases.ts`），而这个段里没有一行代码写过东西。
-// 「磁盘上有一个文件夹」本身是一种承诺，承诺了却空着就是误导。
-const LAYOUT = ['01_source_truth', '02_wiki', '03_compiled', '05_diagnosis'] as const
+// - `00_schema`（0030 撤）：它从建出来那天起就是一个**空目录**。分类注册表与 Wiki 类型
+//   注册表一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是**配置**，跟着根路径
+//   走，见 `knowledge-bases.ts`），而这个段里没有一行代码写过东西。「磁盘上有一个文件夹」
+//   本身是一种承诺，承诺了却空着就是误导。**一句话：schema 在设置里编辑，不在磁盘上。**
+// - `05_diagnosis`（v1.1 撤）：它同时装着两类东西 —— 「一次排查的产物」（源头）与
+//   「五类模板卡」（配置）—— 一个编号段混装两种性质，`rebuild --only` 的语义立刻含糊。
+//   现在：一次排查的产物是一条 `agent_diagnosis_case` 的 SourceRaw（落 `01_source_raw/`），
+//   模板卡由类型定义派生（不落盘）。旧目录里的 `*.jsonl` 降为**只读的迁移输入与历史快照**。
+const LAYOUT = ['01_source_raw', '02_wiki', '03_compiled'] as const
+/**
+ * 卡片正文里那个机器可读块的围栏标记。
+ *
+ * 与 `diagnosis/cards.ts` 的 `BLOCK_FENCE` 是同一个字符串，但这里不能 import 它 ——
+ * 迁移要在**不解析卡片**的前提下改块里的一个字段名（旧块的 `failure_mode`），
+ * 而 `cards.ts` 的 `parseCard` 已经把旧字段名归一化了，读回来的对象里根本没有它。
+ */
+const DIAGNOSIS_BLOCK_FENCE = 'json diagnosis'
 /**
  * SourceRaw 段。段内**按来源分类再分一层**：`<段>/<source_type>/<docSlug>.md`。
  *
@@ -43,10 +66,27 @@ const LAYOUT = ['01_source_truth', '02_wiki', '03_compiled', '05_diagnosis'] as
  * 读路径不依赖这个层级：`sourceIndex()` 递归扫全段建 slug → path 索引，所以旧
  * 平铺布局与迁移中间态都照常可读（见 `migrateSourceTruthLayout`）。
  */
-const SOURCE_TRUTH = '01_source_truth'
+const SOURCE_TRUTH = '01_source_raw'
+/**
+ * 0051 之前的段名。**只留这一处**，两个用途：
+ * 1. **兼容解析**：存量正文里的图片引用写的是 `../../01_source_truth/_assets/…`
+ *    （0047 的三种历史写法之一），改段名不改文件内容，所以解析器要同时认两个名字；
+ * 2. **迁移**：把整棵树搬过来（`migrateSourceTree`）。
+ *
+ * 卡片正文里的老引用**不改写**：改正文会造内容版本、让卡片重编重编码，而代价只是为了
+ * 让一个字符串好看一点。解析器认两个名字，读得到就行。
+ */
+const LEGACY_SOURCE_TRUTH = '01_source_truth'
 /** Wiki 段；段内按 `entity_type` 分目录（与 SourceRaw 的分类分层同一个思路）。 */
 const WIKI = '02_wiki'
 const STATUS: KnowledgeStatus[] = ['unreviewed', 'draft', 'reviewed', 'active', 'deprecated', 'problem']
+/**
+ * 一次 `import_sources` 能带多少份来源（0045）。
+ *
+ * 这不是产品配额，是**一次调用能被按住的时长**：编译逐份来源串行抽实体，50 份已经要跑
+ * 很久。超了就分批，每批各自编译 —— 而不是让一次调用变成没人知道什么时候结束的东西。
+ */
+export const MAX_IMPORT_SOURCES = 50
 const SAFE_ID = /^[a-zA-Z0-9._:-]{1,160}$/
 const VECTOR_MANIFEST = 'vector-manifest.json'
 const VECTOR_BINARY = 'vectors.binary'
@@ -68,6 +108,16 @@ const VECTOR_QUANTIZATION = 'binary+hamming+int8' as const
 const ENCODER_FINGERPRINT = 'wemm-official-processor-v1'
 /** Stage 2 output consumed by stage 3 recall. */
 const WIKI_NOTES = 'wiki_notes.json'
+/**
+ * 归因图谱的编译产物（0021 §14.3）。
+ *
+ * 在这之前 `cardsToGraph()` 是**读的时候现算**的，归因图不落 `03_compiled` —— 于是
+ * `build-manifest.json` 不知道它存在（回答不了「这张图是哪个版本编出来的」），
+ * 而图召回也读不到它。现在它和 `knowledge_graph.json` 一起由同一次 `rebuild` 产出，
+ * **但保留两种粒度**：卡片级回答「知识长什么样」，字段级回答「这条路怎么走」。
+ * 合成一张会让图谱 Tab 看到一张卡片散成七个点（§14.4 的三条理由）。
+ */
+const DIAGNOSIS_GRAPH = 'diagnosis_graph.json'
 /** Pre-0014 artifact name; kept readable so an upgrade does not force a rebuild. */
 const LEGACY_UNITS = 'knowledge_units.json'
 /**
@@ -102,6 +152,14 @@ const CARD_VERSIONS = 'card-versions'
  * 只会让下一次重建把关系重新抽一遍。
  */
 const EXTRACTED_RELATIONS = 'extracted_relations.json'
+/**
+ * 索引页（0049）：**不打开界面也能知道这个库里有什么**。
+ *
+ * 落在 `03_compiled/` 而不是 `02_wiki/`：后者的每一份 `.md` 都会被 `loadCards`
+ * 当成一张卡片读进卡片清单，索引页放进去就会变成一张标题叫「知识库索引」的卡片，
+ * 而且每次编译都变一次。它是派生产物，所以归派生目录。
+ */
+const WIKI_INDEX = 'wiki-index.md'
 /** Sections shorter than this stay in a single note; longer cards split by heading. */
 const NOTE_SPLIT_MIN_CHARS = 800
 /**
@@ -114,6 +172,20 @@ const NOTE_SPLIT_MIN_CHARS = 800
 const RELATION_QUERY_WORDS: Record<string, string> = {
   supported_by: 'supported by source 来源 出处 依据 支撑',
   [RELATES_TO]: 'relates to related 相关 关联 关系 有关',
+  // 归因图谱的十种边（0021 §4.2）。它们住在 `diagnosis_graph.json` 里，
+  // 但**按关系词命中**这条读法是同一套：中文提问不会写 `may_be_caused_by`。
+  // 少了这十行，图召回对 `refutes` / `verified_by` 这些语义完全不可见 ——
+  // 而「上次这条假设是被什么否定的」正是最该被召回到的东西。
+  may_be_caused_by: 'may be caused by 可能是原因 可能原因 候选原因 怀疑',
+  verified_by: 'verified by 由…验证 怎么验证 用哪个检查 检查点',
+  categorized_as: 'categorized as 归类为 属于哪一类 失败原因 切面',
+  queries: 'queries 查询依据 要去查 查哪些表 影响面',
+  produces: 'produces 产出 产出了什么 跑出了什么',
+  supports: 'supports 支持 印证 算数',
+  refutes: 'refutes 否定 排除 不成立 反例',
+  confirmed_as: 'confirmed as 确认为根因 确认根因 定位到',
+  instance_of: 'instance of 实例属于 哪次排查 案例',
+  indexed_from: 'indexed from 反查索引 落在哪个对象上 相关资产',
 }
 /**
  * 融合与阈值的常数（0031）。
@@ -146,8 +218,21 @@ const ENCODER_SELF_SIMILARITY_MAX = 0.99
 const MIN_QUERY_COVERAGE = 0.25
 /** 每条命中最多带几段证据原文。 */
 const EVIDENCE_PER_HIT = 3
-/** 同一张 wiki 最多几条进上下文：否则 5 条上下文可能全是同一张卡的不同小节。 */
-const CONTEXT_PER_WIKI_CAP = 2
+/*
+ * 0050 删掉了 `CONTEXT_PER_WIKI_CAP`（同一张 wiki 最多几条进上下文）。
+ * 它是「按 note 组装上下文」时代的补丁：那时同一张卡的多个小节能占满名额。
+ * 现在上下文**按卡片去重**，一张卡只有一个条目 —— 上限这个概念不再需要，
+ * 取而代之的是卡片级的 1 跳扩展上限（`MAX_EXPANSION_CARDS`）。
+ */
+/**
+ * 1 跳扩展最多拉几张卡片（0050）。
+ *
+ * 上限是**有意的**：一张卡片在图上的邻居可以很多（一份来源编出的卡片彼此都是邻居），
+ * 不设限时「1 跳」会把整个连通分量拖进上下文。宁可少拉，也不要让扩展压过命中。
+ */
+const MAX_EXPANSION_CARDS = 20
+/** 溢出文件的保留时长：超过它的旧文件在下次召回时清掉（0050）。 */
+const RECALL_OVERFLOW_TTL_MS = 24 * 60 * 60 * 1000
 const BIT_COUNTS = Array.from({ length: 256 }, (_, value) => {
   let count = 0
   for (let bit = value; bit !== 0; bit &= bit - 1) count += 1
@@ -207,8 +292,16 @@ interface ExtractionOutcome {
   extractionHashes: Record<string, string>
   candidatesExtracted: number
   candidatesRejected: number
+  /**
+   * 这一轮**新建**的 wiki 卡片数。
+   *
+   * 名字从 `proposalsCreated` 改回来（0044）：Pass 0 重新直接落卡。0040 v1.5 那道
+   * 「人确认之后才入库」的门撤掉了 —— 入库在前、review 在后，所以计数必须如实说
+   * 「新建了 N 张卡片」，而磁盘上真的有 N 张。
+   */
   cardsCreated: number
-  cardsMerged: number
+  /** 这一轮**更新**（把新抽到的正文追加进去、或补上来源）的已有卡片数。 */
+  cardsUpdated: number
   sourcesExtracted: number
   sourcesSkipped: number
   relations: Array<{ fromKey: string; toKey: string; relation: string; sourceId: string }>
@@ -220,6 +313,29 @@ interface ExtractionOutcome {
   warnings: string[]
 }
 
+/**
+ * Finalize（收尾段）一次运行的结果（0049）。
+ *
+ * `related` 与 `deadLinks` 要**继续往下传**：正文层算出来的计划，产物层（索引页）
+ * 与接口层（卡片抽屉的相关分块）读的是同一份 —— 三处各算一遍就会漂移。
+ */
+interface FinalizeOutcome {
+  related: Map<string, RelatedEntry[]>
+  /** 相关链接总条数（含双向），报告里显示的就是它。 */
+  relatedLinks: number
+  /** 有几张卡片至少有了一条相关。 */
+  relatedCards: number
+  deadLinks: DeadLink[]
+  /** 这一轮因为相关块或断链问题而重写的卡片数。 */
+  rewritten: number
+}
+
+/** 卡片上的待补项（`metadata.schema_issues`），形状不对时当空。 */
+function cardIssuesOf(card: KnowledgeCard): CardSchemaIssue[] {
+  const raw = card.metadata.schema_issues
+  return Array.isArray(raw) ? raw as CardSchemaIssue[] : []
+}
+
 /**
  * Both helpers delegate to the shared envelope constructors: the five-key shape
  * and the "warnings ⇒ partial" rule live in `dsh-data-contracts`,
@@ -252,16 +368,332 @@ function contentHashOf(content: string): string { return hash(content) }
  * 已经在正文里出现过的那一段不再追加：同一份来源重建、或同一段被两个候选命中时，
  * 卡片不该越编译越长。判重按整段文本，所以它是幂等的。
  */
+/** 批量导入里成功写入的一条来源（0045）。`index` 回指输入数组，调用方能对上号。 */
+export interface ImportedSourceReport {
+  index: number
+  sourceId: string
+  title?: string
+  path: string
+  bytes: number
+}
+
+/** 批量导入里失败的一条。**带着原因回来**，因为局部失败要求调用方能只重试那几条。 */
+export interface ImportFailure {
+  index: number
+  title?: string
+  code: string
+  message: string
+}
+
+/**
+ * 批量导入顺带那次编译的结果。
+ *
+ * 只带**能被人读懂**的几个数：新建 / 并入 / 复用 / 重编 / 重抽 / 跳过 / 移除、索引版本、
+ * 向量那一段的状态。整份 `RebuildReport` 有三十多个字段（指纹、计数、诊断），
+ * 而这里要回答的是「刚才那一下让库里多了什么」。
+ */
+export interface ImportCompileReport {
+  cardsCreated: number
+  cardsUpdated: number
+  cardsReused?: number
+  notesReused?: number
+  notesRecompiled?: number
+  sourcesExtracted?: number
+  sourcesSkipped?: number
+  cardsRemoved?: number
+  embedding?: string
+  version?: number
+}
+
+/** 一次 `import_sources` 的账本：写了哪些、哪些没写成、顺带编译出了什么。 */
+export interface ImportSourcesResult {
+  written: ImportedSourceReport[]
+  failed: ImportFailure[]
+  /** 输入里一共有几份 —— 成功数 + 失败数 = 它，除非整批在写入前就被拒了。 */
+  attempted: number
+  /** `compile: false` 时是 `null`：明确表示「这次没编译」，而不是「编译了但没数字」。 */
+  compile: ImportCompileReport | null
+}
+
+/**
+ * Pass 0 收集到的一条**待落卡片**。
+ *
+ * 它存在的原因是**整轮结束才落盘**：一份来源里同一个实体可能被抽到两次，两份来源也
+ * 可能抽到同一个实体 —— 逐次写会得到 N 次覆盖，而增量指纹要的是「这一轮这张卡片
+ * 最终长什么样」。
+ *
+ * `card` 是**已有卡片**（更新时），带着它的状态、备注、评分与 metadata —— 更新一张
+ * 卡片不该把人写过的备注、review 结论、以及别处来源的字段一起抹掉。
+ */
+interface PendingCard {
+  action: 'create' | 'update'
+  entityType: SchemaType
+  entityId: string
+  title: string
+  content: string
+  sourceRefs: string[]
+  metadata: Record<string, unknown>
+  summary?: string
+  /**
+   * 更新的是哪张已有卡片。
+   *
+   * 带着它是为了**保住正文之外的一切**：状态、人工备注（`annotations`）、review 评分
+   * （`review`）、别处来源留下的字段。只凭 `type:id` 重新拼一张卡片，会把这些悄悄抹掉 ——
+   * 而「备注不会被编译覆盖」正是 0044 承诺的东西。
+   */
+  existing?: KnowledgeCard
+  /** 这一轮判重命中过它的来源与候选键，写进 `metadata.extraction_merges`。 */
+  merges: Array<{ sourceId: string; keys: string[]; at: string }>
+  /**
+   * 这一轮有没有**改到卡片的字段值**（类型定义里的 `formula` / `owner` 之类，或摘要）。
+   *
+   * 单独记一个布尔而不是去比整个 `metadata`：`metadata` 里还有 `evidence`、`confidence`、
+   * `extraction_merges` 这些每次都不同的东西，整体比较只会永远为真，于是「没变的卡片不重写」
+   * 这条增量承诺就悄悄失效了。这里只回答那个真正要紧的问题 —— 字段值变了没有。
+   */
+  fieldChanged?: boolean
+}
+
+/** 候选的别名集合：判重认的是名字，不是卡片 id（中文名会退化成哈希 id）。 */
+function aliasesOf(candidate: { name: string; aliases?: string[] }): string[] {
+  return [...new Set([candidate.name, ...(candidate.aliases ?? [])].map(value => value.trim()).filter(Boolean))]
+}
+
+/** 累积一次「并入已有卡片」。同一条 pending 被追加两次时 `appendExtracted` 自带判重。 */
+function mergeIntoPending(
+  pending: Map<string, PendingCard>,
+  card: KnowledgeCard,
+  sourceId: string,
+  bodies: string[],
+  keys: string[],
+  at: string,
+  /**
+   * 这次新抽到的**字段值**（类型定义里的 `formula` / `owner` 等）与摘要。
+   *
+   * 它们必须跟着走完整条路径。0044 的实现里漏过一次：模型在第二份文档里给出了更完整的
+   * `formula`，卡片只追加了正文，字段值停在第一份文档的版本上 —— 而正文里写着新的公式。
+   * 这种「正文与字段互相矛盾」比缺字段更难发现。
+   */
+  fields?: Record<string, string>,
+  summary?: string,
+): void {
+  const key = `${card.entityType}:${card.entityId}`
+  const previous = pending.get(key)
+  // 字段值真的变了才算「改到」：同一段公式被两份文档重复写下是很常见的，
+  // 那种情况下这一轮没有任何新东西，不该把卡片重写一遍。
+  const changed = Object.entries(fields ?? {}).some(([name, value]) => String(card.metadata[name] ?? '') !== value)
+    || Boolean(summary && summary !== (card.summary ?? ''))
+  if (previous) {
+    previous.content = appendExtracted(previous.content, bodies)
+    if (!previous.sourceRefs.includes(sourceId)) previous.sourceRefs.push(sourceId)
+    previous.metadata = { ...previous.metadata, ...(fields ?? {}) }
+    if (!previous.summary && summary) previous.summary = summary
+    if (changed) previous.fieldChanged = true
+    previous.merges.push({ sourceId, keys, at })
+    return
+  }
+  pending.set(key, {
+    action: 'update',
+    entityType: card.entityType,
+    entityId: card.entityId,
+    title: card.title,
+    // **追加**而不是覆盖，也不是丢弃：实体已存在时，这次新抽到的正文并进原卡片，
+    // 于是知识是累积的，来源改写了也不会停在旧版本上。
+    content: appendExtracted(card.content, bodies),
+    sourceRefs: card.sourceRefs.includes(sourceId) ? [...card.sourceRefs] : [...card.sourceRefs, sourceId],
+    metadata: { ...card.metadata, ...(fields ?? {}) },
+    ...(summary ?? card.summary ? { summary: summary ?? card.summary } : {}),
+    existing: card,
+    merges: [{ sourceId, keys, at }],
+    ...(changed ? { fieldChanged: true } : {}),
+  })
+}
+
+/** 来源的判重留痕：只留最近 20 条，它是「这张卡被哪些来源命中过」的痕迹，不是审计日志。 */
+function mergeHistoryOf(metadata: Record<string, unknown>, additions: PendingCard['merges']): Array<Record<string, unknown>> {
+  const history = Array.isArray(metadata.extraction_merges) ? metadata.extraction_merges : []
+  return [...history, ...additions].slice(-20) as Array<Record<string, unknown>>
+}
+
+/**
+ * 从 frontmatter 里读人工备注。
+ *
+ * 形状不对的一条**丢掉，而不是让整张卡片读不出来**：备注是附加信息，为了一条写坏的
+ * 备注把一张知识卡片变成「读不到」，代价方向错了。
+ */
+function parseAnnotations(value: unknown): CardAnnotation[] {
+  if (!Array.isArray(value)) return []
+  const result: CardAnnotation[] = []
+  for (const item of value) {
+    if (item === null || typeof item !== 'object') continue
+    const record = item as Record<string, unknown>
+    const note = typeof record.note === 'string' ? record.note.trim() : ''
+    if (!note) continue
+    result.push({
+      id: typeof record.id === 'string' && record.id.trim() ? record.id.trim() : `a-${hash(note).slice(0, 12)}`,
+      kind: record.kind === 'anomaly' ? 'anomaly' : 'note',
+      note,
+      ...(typeof record.author === 'string' && record.author.trim() ? { author: record.author.trim() } : {}),
+      createdAt: typeof record.createdAt === 'string' && record.createdAt.trim() ? record.createdAt.trim() : '',
+      ...(typeof record.sourceRef === 'string' && record.sourceRef.trim() ? { sourceRef: record.sourceRef.trim() } : {}),
+    })
+  }
+  return result
+}
+
+/** 从 frontmatter 里读 review 结论。缺省 = 还没人看过（调用方按 `CARD_REVIEW_BASE_SCORE` 处理）。 */
+function parseReview(value: unknown): CardReview | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = value as Record<string, unknown>
+  const score = Number(record.score)
+  const state = record.state === 'reviewed' ? 'reviewed' : 'unreviewed'
+  return {
+    state,
+    score: Number.isFinite(score) ? Math.min(1, Math.max(0, score)) : state === 'reviewed' ? REVIEWED_SCORE_FLOOR : CARD_REVIEW_BASE_SCORE,
+    ...(typeof record.reviewedAt === 'string' && record.reviewedAt.trim() ? { reviewedAt: record.reviewedAt.trim() } : {}),
+    ...(typeof record.reviewedBy === 'string' && record.reviewedBy.trim() ? { reviewedBy: record.reviewedBy.trim() } : {}),
+  }
+}
+
+/**
+ * 一张卡片的**有效评分**（0044）：有异常点备注时封顶。
+ *
+ * 为什么不把「异常」直接写进 `review.score`：异常是**关于证据的判断**（这段内容和原始
+ * 文档对不上），review 是**关于覆盖度的判断**（这张卡该有的小节都有了）。两者会同时成立 ——
+ * 一张 review 通过的卡片里照样可能被标出一个数字对不上。分成两个字段之后，
+ * 撤掉异常备注，review 的结论原样回来；写成一个数就再也分不开了。
+ */
+function effectiveReviewScore(card: Pick<KnowledgeCard, 'review' | 'annotations'>): number {
+  const base = card.review?.score ?? CARD_REVIEW_BASE_SCORE
+  const hasAnomaly = (card.annotations ?? []).some(item => item.kind === 'anomaly')
+  return hasAnomaly ? Math.min(base, ANOMALY_SCORE) : base
+}
+
+function annotationId(note: string, at: string): string {
+  return `a-${hash(`${at}|${note}`).slice(0, 16)}`
+}
+
+/**
+ * 一份正文的小节结构：`## 标签` + 它下面的内容。
+ *
+ * `heading` 保留原始那一行（`## 定义`），重建时逐字写回去，所以合并不会顺手把
+ * 「## 定义」改成别的写法。首个标题之前的内容收进 `label: ''` 的那一格 ——
+ * 模型偶尔会先写一句总述，丢掉它比多一格更糟。
+ */
+interface BodySection {
+  heading: string
+  label: string
+  body: string
+}
+
+/**
+ * 按 `## 小节` 切开正文。没有任何标题时返回 `null`，调用方据此退回「整段拼接」。
+ */
+function splitSections(markdown: string): BodySection[] | null {
+  const sections: Array<{ heading: string; label: string; lines: string[] }> = []
+  let current: { heading: string; label: string; lines: string[] } | undefined
+  let seenHeading = false
+  for (const line of markdown.split('\n')) {
+    const match = /^##\s+(.+?)\s*$/.exec(line)
+    if (match) {
+      seenHeading = true
+      current = { heading: line.trim(), label: match[1].trim(), lines: [] }
+      sections.push(current)
+      continue
+    }
+    if (!current) {
+      // 第一个标题出现之前的行（含前导空行）归入前言。
+      current = { heading: '', label: '', lines: [] }
+      sections.push(current)
+    }
+    current.lines.push(line)
+  }
+  if (!seenHeading) return null
+  return sections.map(section => ({ heading: section.heading, label: section.label, body: section.lines.join('\n').trim() }))
+}
+
+/**
+ * 一整节只是**一句括号里的占位**吗（`（文档未说明）` / `（本文档未说明适用场景。）`）？
+ *
+ * 占位是编译器的约定（`skeletonBody` 写「（文档未说明）」），模型会照着模仿。
+ * 判断成占位之后，后来的真实内容**替换**它而不是追加在它后面 —— 否则卡片会长成
+ * 「（文档未说明）」+ 具体内容，读起来像两句话，而第一句已经过期了。
+ */
+function isPlaceholderSection(text: string): boolean {
+  const trimmed = text.trim()
+  return /^[（(][^（()）]*[）)]$/.test(trimmed)
+}
+
+/** 把一节的新内容并进旧内容：占位替换、重复跳过、其余追加。 */
+function mergeSectionText(current: string, addition: string): string {
+  const next = addition.trim()
+  if (!next) return current.trim()
+  const previous = current.trim()
+  if (!previous) return next
+  if (previous.includes(next)) return previous
+  if (isPlaceholderSection(previous)) return next
+  return `${previous}\n\n${next}`
+}
+
+/**
+ * 把一次新抽到的正文并进已有正文（0044）。
+ *
+ * ## 为什么不是简单的字符串拼接
+ *
+ * 实机验证抓到的形状：同一实体被第二份文档命中时，卡片变成
+ * `## 适用场景 / ## 步骤 / ## 验收与失败处理 / ## 适用场景 / ## 步骤 / …` ——
+ * 每一节都出现两次。正文是**按类型 schema 分节**的，重复标题意味着这张卡片不再
+ * 符合它的类型，读的人还得自己把两段同一节的内容在脑子里合起来。
+ *
+ * 所以按小节折进去：**每个标签只出现一次**，新内容并进同一节里；旧内容还是占位
+ * （「（文档未说明）」）时被新内容替换。两份正文里只要有一份没有 `##` 结构
+ * （规则路径切出来的原文就是这样），就退回整段拼接 —— 那种情况下没有可靠的
+ * 对齐依据，硬折会把内容塞错节。
+ *
+ * ## 为什么改在这里
+ *
+ * 所有「并入已有卡片」的路径都走这个函数（编译、`writeCards`、诊断卡片），
+ * 在上层各自折一次，必然有一处漏掉。
+ */
 function appendExtracted(existing: string, additions: string[]): string {
   let content = existing
   for (const addition of additions) {
     const body = addition.trim()
     if (!body || content.includes(body)) continue
-    content = content ? `${content}\n\n${body}` : body
+    content = foldBody(content.trim(), body)
   }
   return content
 }
 
+/** 把 `incoming` 按小节折进 `existing`；结构对不上时整段追加。 */
+function foldBody(existing: string, incoming: string): string {
+  if (!existing) return incoming
+  const base = splitSections(existing)
+  const extra = splitSections(incoming)
+  if (!base || !extra) return `${existing}\n\n${incoming}`
+
+  const byLabel = new Map(base.map(section => [section.label, section]))
+  const appended: BodySection[] = []
+  for (const section of extra) {
+    const target = byLabel.get(section.label)
+    if (target) {
+      target.body = mergeSectionText(target.body, section.body)
+      continue
+    }
+    // 新标签：整节接在最后，标题逐字保留。
+    const fresh = { heading: section.heading, label: section.label, body: section.body }
+    byLabel.set(section.label, fresh)
+    appended.push(fresh)
+  }
+
+  const ordered = [...base, ...appended]
+  const rendered = ordered
+    .map(section => (section.heading ? `${section.heading}\n\n${section.body}`.trimEnd() : section.body))
+    .filter(part => part.trim().length > 0)
+    .join('\n\n')
+  return rendered
+}
+
 /**
  * `2026-01-02T03:04:05.123Z` → `20260102T030405123Z`. Millisecond precision keeps
  * two overwrites inside the same second from colliding on the same version id.
@@ -288,15 +720,31 @@ function plainRecord(value: unknown): Record<string, unknown> {
  * `metadata.source_path`; otherwise the upstream `source_format` label
  * (`markdown` / `office` / …); otherwise `markdown`, the store's default shape.
  */
+/**
+ * 这份来源**是什么格式**（`web_page` / `office` / `pdf` / `markdown`…）。
+ *
+ * `source_format` 是转换内核报出来的**格式类**，有就以它为准 —— 按扩展名去猜会把
+ * 「网页」显示成「html」（0048 之前就是这样：`类型: .html · html`，而 manifest 里
+ * 明明写着 `web_page`）。没有 `source_format` 的手写来源才退回扩展名那条链。
+ */
 function sourceFormatOf(metadata: Record<string, unknown>): string {
-  const sourcePath = typeof metadata.source_path === 'string' ? metadata.source_path.trim() : ''
-  if (sourcePath) {
-    const base = sourcePath.split(/[\\/]/).pop() ?? ''
+  const format = typeof metadata.source_format === 'string' ? metadata.source_format.trim().toLowerCase() : ''
+  if (format) return format
+  const ext = sourceExtOf(metadata)
+  return ext ? ext.replace(/^\./, '') : 'markdown'
+}
+
+/** 底稿文件名 → 扩展名。`original.rel` 是 0048 起的持久位置，`source_path` 是旧形状。 */
+function sourceExtOf(metadata: Record<string, unknown>): string {
+  const original = plainRecord(metadata.original)
+  const candidates = [original.rel, metadata.source_path]
+  for (const value of candidates) {
+    if (typeof value !== 'string' || !value.trim()) continue
+    const base = value.trim().split(/[\\/]/).pop() ?? ''
     const dot = base.lastIndexOf('.')
-    if (dot > 0 && dot < base.length - 1) return base.slice(dot + 1).toLowerCase()
+    if (dot > 0 && dot < base.length - 1) return base.slice(dot).toLowerCase()
   }
-  const format = typeof metadata.source_format === 'string' ? metadata.source_format.trim().toLowerCase() : ''
-  return format || 'markdown'
+  return ''
 }
 
 /** Failure payload for a document lookup that could not produce a detail. */
@@ -304,10 +752,25 @@ function emptyDocumentDetail(docId: string): KnowledgeDocumentDetail {
   return {
     docId, title: docId, sourceType: '', sourceTypeKnown: false, sourceFormat: '', parser: '', externalId: '', contentHash: '',
     bytes: 0, assetCount: 0, createdAt: '', updatedAt: '', versionCount: 0,
-    relativePath: '', ext: '', content: '', frontmatter: {}, assets: [],
+    relativePath: '', ext: '', content: '', contentChars: 0, contentTruncated: false, frontmatter: {}, assets: [],
   }
 }
 
+/**
+ * 抽屉里的原文预览**只发**正文的前这么多字符。
+ *
+ * 依据是实跑反馈：一份几十万字的转换文档，抽屉只渲染前 4000 字符（更长的在
+ * 380px 宽的抽屉里没有阅读意义），而接口原来把**整份正文**发过去 —— 传输、JSON 解析、
+ * 塞进 React state 全按全文的量级付费，于是「打开弹层要等半天」。上面那段封顶之后，
+ * 弹层的耗时与文档大小**脱钩**；要读全文走独立整页（分页取，见 `documentContentPage`）。
+ *
+ * 4000 是用户明确要的阈值，所以它是一个具名常量而不是散在各处的字面量。
+ */
+export const SOURCE_PREVIEW_CHARS = 4000
+
+/** 耗时统一保留一位小数：界面上不需要微秒，而 0.0 与 0 的读法不一样。 */
+function round1(value: number): number { return Math.round(value * 10) / 10 }
+
 function generatedId(prefix: string): string { return `${prefix}_${hash(`${Date.now()}:${Math.random()}`)}` }
 
 function parseLineage(value: unknown): LineageContext | undefined {
@@ -362,42 +825,24 @@ export function parseMarkdown(source: string): { frontmatter: Record<string, unk
   return { frontmatter, content: source.slice(end + 4).trim() }
 }
 
+/**
+ * 把旧卡片结构化块里的 `failure_mode` 改成 `failure_reason`（0040 的第二次改名）。
+ *
+ * 只动那个围栏块里的键名，不动正文 —— 正文里出现「failure_mode」这个词完全可能是
+ * 有意写的（比如一张讲 FMEA 的卡片）。做字符串级替换而不是解析再序列化，是因为
+ * 解析会**丢掉格式**（缩进、键序），而迁移的第一条纪律是不制造无谓的 diff。
+ */
+function rewriteLegacyBlockFields(content: string): string {
+  const pattern = new RegExp('(```' + DIAGNOSIS_BLOCK_FENCE + '\\s*\\n)([\\s\\S]*?)(```)')
+  return content.replace(pattern, (_all, head: string, body: string, tail: string) =>
+    head + body.replace(/"failure_mode"(\s*:)/g, '"failure_reason"$1') + tail)
+}
+
 function markdown(frontmatter: Record<string, unknown>, content: string): string {
   const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`)
   return `---\n${lines.join('\n')}\n---\n\n${content.trim()}\n`
 }
 
-async function writeTextAtomic(path: string, content: string): Promise<void> {
-  // 原子写需要一个与目标同目录的临时文件，所以目标目录必须先存在。0030 起
-  // SourceRaw 落在 `<段>/<source_type>/` 下，而 `ensureLayout` 只建段目录 —— 少了
-  // 这一行，第一次写某一种分类就会 ENOENT（实测）。
-  await mkdir(dirname(path), { recursive: true })
-  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
-  try {
-    await writeFile(temporary, content, 'utf8')
-    await rename(temporary, path)
-  } finally {
-    await unlinkIfExists(temporary)
-  }
-}
-
-async function writeBufferAtomic(path: string, content: Buffer): Promise<void> {
-  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
-  try {
-    await writeFile(temporary, content)
-    await rename(temporary, path)
-  } finally {
-    await unlinkIfExists(temporary)
-  }
-}
-
-async function unlinkIfExists(path: string): Promise<void> {
-  try {
-    const { unlink } = await import('node:fs/promises')
-    await unlink(path)
-  } catch { /* rename already consumed the temp file */ }
-}
-
 async function filesUnder(root: string): Promise<string[]> {
   try {
     const entries = await readdir(root, { withFileTypes: true })
@@ -458,8 +903,198 @@ function markdownImageRefs(content: string): string[] {
   return [...new Set(refs)]
 }
 
-function markdownImagePaths(content: string, baseDir: string): string[] {
-  return markdownImageRefs(content).map(value => isAbsolute(value) ? resolve(value) : resolve(baseDir, value))
+/**
+ * 一份 SourceRaw 的 front matter（0048）。
+ *
+ * 键分成两类，**顺序与来源**都是刻意的：
+ *
+ * 1. **OKF v0.2 的顶层键**：`type` / `title` / `description` / `resource` /
+ *    `tags` / `generated` / `sources`。它们是真 YAML 键，人能读、`grep` 得到、
+ *    外部工具能按公开规范读走。`generated.at` 就是**采集时间**（OKF 里没有「抓取
+ *    时间」这个概念，本文件何时被谁写出来就是它）。
+ * 2. **我们自己的运行键**：`source_id` / `external_id` / `created_at` / `updated_at` /
+ *    `metadata` / `lineage`。OKF 明确允许自定义键，且要求消费者不得因为未知键拒收，
+ *    所以这两类可以同处一个 front matter。
+ *
+ * `metadata` 只剩**类型专属的扩展键**（转换任务 id、内容哈希、资产清单、格式…）：
+ * 那些东西 OKF 没有对应概念，但也不该混进上面那组公开字段里。
+ *
+ * `type` 是 OKF 唯一必填键，值就是我们自己的来源分类（它本来就是「这个概念是什么」）。
+ * 旧文件里的 `source_type` 仍然读得到（见 `sourceTypeOf`），迁移只写新键。
+ */
+function sourceFrontMatter(record: SourceRaw, provenance?: SourceProvenance): Record<string, unknown> {
+  const frontMatter: Record<string, unknown> = {
+    type: record.sourceType,
+    title: record.title,
+  }
+  if (provenance?.description?.trim()) frontMatter.description = provenance.description.trim()
+  if (provenance?.resource?.trim()) frontMatter.resource = provenance.resource.trim()
+  if (provenance?.tags && provenance.tags.length > 0) frontMatter.tags = provenance.tags
+  const generated = {
+    ...(provenance?.generatedBy?.trim() ? { by: provenance.generatedBy.trim() } : {}),
+    ...(provenance?.generatedAt?.trim() ? { at: provenance.generatedAt.trim() } : {}),
+  }
+  if (Object.keys(generated).length > 0) frontMatter.generated = generated
+  const sources = (provenance?.sources ?? []).filter(origin => origin.resource.trim())
+  if (sources.length > 0) {
+    frontMatter.sources = sources.map((origin: SourceOriginRef) => ({
+      id: origin.id,
+      resource: origin.resource,
+      ...(origin.title?.trim() ? { title: origin.title.trim() } : {}),
+      ...(origin.author?.trim() ? { author: origin.author.trim() } : {}),
+      ...(origin.lastModified?.trim() ? { last_modified: origin.lastModified.trim() } : {}),
+    }))
+  }
+  frontMatter.source_id = record.sourceId
+  frontMatter.external_id = record.externalId ?? ''
+  frontMatter.created_at = record.createdAt
+  frontMatter.updated_at = record.updatedAt
+  frontMatter.metadata = record.metadata
+  if (record.lineage) frontMatter.lineage = record.lineage
+  return frontMatter
+}
+
+/** 把 `sources[0].author` 拆成 `['sources', 0, 'author']`。 */
+function metadataPath(key: string): Array<string | number> {
+  const tokens: Array<string | number> = []
+  for (const part of key.split('.')) {
+    const name = part.replace(/\[\d+\]/g, '').trim()
+    if (name) tokens.push(name)
+    for (const index of part.matchAll(/\[(\d+)\]/g)) tokens.push(Number(index[1]))
+  }
+  return tokens
+}
+
+/** 这份 front matter 里，分类声明的元数据字段缺了哪些（缺 = 没有值，不是「值为空串」）。 */
+function missingMetadataFields(fields: SourceMetadataField[] | undefined, frontMatter: Record<string, unknown>): SourceMetadataField[] {
+  if (!fields || fields.length === 0) return []
+  const present = (key: string): boolean => {
+    let current: unknown = frontMatter
+    for (const token of metadataPath(key)) {
+      if (typeof token === 'number') {
+        if (!Array.isArray(current)) return false
+        current = current[token]
+      } else {
+        if (current === null || typeof current !== 'object') return false
+        current = (current as Record<string, unknown>)[token]
+      }
+    }
+    if (current === undefined || current === null) return false
+    if (typeof current === 'string') return current.trim().length > 0
+    if (Array.isArray(current)) return current.length > 0
+    return true
+  }
+  return fields.filter(field => field.required === true && !present(field.key))
+}
+
+/**
+ * 读一份 front matter 里的来源分类。
+ *
+ * 两个键都认：`type` 是 0048 起的规范键（OKF 必填），`source_type` 是旧文件里的键。
+ * 迁移会把存量文件改写成 `type`，但**读**这一侧永远两个都认 —— 别的库、别人手写的
+ * 文件、备份里翻出来的文件都可能还是旧形状，读不了就等于数据丢失。
+ */
+function sourceTypeOf(frontmatter: Record<string, unknown>): string {
+  const canonical = frontmatter.type
+  if (typeof canonical === 'string' && canonical.trim()) return canonical.trim()
+  const legacy = frontmatter.source_type
+  if (typeof legacy === 'string' && legacy.trim()) return legacy.trim()
+  return ''
+}
+
+/**
+ * 一个图片引用可能指向哪些磁盘路径，按优先级排。
+ *
+ * 知识库里同时存在三种写法，都是历史产物，谁也没错，所以解析要认全：
+ *
+ * | 写法 | 谁写的 | 从哪解析 |
+ * | --- | --- | --- |
+ * | `01_source_raw/_assets/<bucket>/<file>` | **规范形**：知识库根相对 | 根目录 |
+ * | `_assets/<bucket>/<file>` | 转换内核早期写进 SourceRaw 的形式（相对 `01_source_raw/`） | 根目录 + `01_source_raw/` |
+ * | `../../01_source_raw/_assets/…` | `cardHints` 给手工建卡用的形式 | 文件自己所在目录 |
+ *
+ * 顺序就是「先根目录、再 `01_source_raw/`、最后文件自己的目录」，而且只认**真实存在**
+ * 的那个（{@link markdownImagePaths} 用 `existsSync` 挑）。这条规则与 `assetsOf` 共用，
+ * 因为「文档里有几张图」和「卡片正文里的图在哪」必须是同一个答案。
+ */
+function assetRefCandidates(ref: string, baseDir: string, rootDir: string): string[] {
+  if (isAbsolute(ref)) return [resolve(ref)]
+  return [
+    resolve(rootDir, ref),
+    resolve(rootDir, SOURCE_TRUTH, ref),
+    // 老段名的引用（0051 之前写进正文的那些）：换一个名字再试一遍，别让存量卡片丢图。
+    ...(ref.includes(LEGACY_SOURCE_TRUTH) ? [resolve(rootDir, ref.replace(LEGACY_SOURCE_TRUTH, SOURCE_TRUTH))] : []),
+    ...(ref.includes(SOURCE_TRUTH) ? [resolve(rootDir, ref.replace(SOURCE_TRUTH, LEGACY_SOURCE_TRUTH))] : []),
+    resolve(baseDir, ref),
+  ]
+}
+
+/**
+ * 把 `from` 里的每一项并进 `to`（0051 的迁移中间态用）。
+ *
+ * 目标里已有的**不覆盖**：迁移只负责「把还没过来的搬过来」，冲突留给下一次启动或
+ * 人来处理。两边都是目录就递归 —— `_assets/<bucket>/` 是两层，一层不够。
+ */
+async function mergeDir(from: string, to: string): Promise<void> {
+  await mkdir(to, { recursive: true })
+  for (const entry of await readdir(from, { withFileTypes: true })) {
+    const source = join(from, entry.name)
+    const target = join(to, entry.name)
+    if (existsSync(target)) {
+      if (entry.isDirectory()) await mergeDir(source, target)
+      continue
+    }
+    await rename(source, target)
+  }
+}
+
+/**
+ * 文件名（不含扩展名）：**用标题**（0051）。
+ *
+ * 三条规则，都是为了让它在任何文件系统上都落得下去：
+ * 1. 路径不安全字符与不可见字符换成 `-`（`/` `\` `:` `*` `?` `"` `<` `>` `|` 与控制字符）；
+ * 2. 首尾的点与空格去掉（Windows 与 macOS 都不喜欢，且会让 `ls` 看起来少一个字符）；
+ * 3. 截断到 120 字符；标题为空（或全是非法字符）时**退回 `source_id` 的 slug** ——
+ *    宁可文件名不好看，也不要没有文件名。
+ *
+ * 它不负责查重：目标路径上已经有人占了，由 `addSource` 按 `SOURCE_TITLE_DUPLICATED` 拒收。
+ */
+function sourceFileBase(title: string, sourceId: string): string {
+  const cleaned = title
+    .replace(/[/\\:*?"<>|\u0000-\u001f]/g, '-')
+    .replace(/\s+/g, ' ')
+    .replace(/^[.\s]+|[.\s]+$/g, '')
+    .slice(0, 120)
+    .trim()
+  // 只剩替换字符（`///` → `---`）等于没有名字：一个叫 `---.md` 的文件比 id 更难认。
+  return /^[-\s]*$/.test(cleaned) ? slug(sourceId) : cleaned
+}
+
+/**
+ * 正文里的图片引用 → 绝对路径。
+ *
+ * 卡片这条路上原先少了这一步：`markdownImagePaths(content, dirname(path))` 只按文件
+ * 自己的目录解析。于是卡片正文里那张从来源**原样搬过来**的图，被解析成
+ * `02_wiki/<type>/_assets/…` —— 一个不存在的路径。0047 实机就是这么炸的：向量编码器
+ * 报 `FileNotFoundError: …/02_wiki/concept/_assets/…/img-2d1e420e82a8.png`，
+ * 整个 embedding 那一档直接降级成 unavailable。
+ */
+function markdownImagePaths(content: string, baseDir: string, rootDir?: string): string[] {
+  return markdownImageRefs(content).map(value => {
+    if (isAbsolute(value)) return resolve(value)
+    if (rootDir) {
+      const found = assetRefCandidates(value, baseDir, rootDir).find(candidate => existsSync(candidate))
+      if (found) return found
+    }
+    return resolve(baseDir, value)
+  })
+}
+
+/** 按来源数一数「有多少张图没落位」，用来生成一条人能照着查的 warning。 */
+function countBySource(images: SourceImage[]): Map<string, number> {
+  const result = new Map<string, number>()
+  for (const image of images) result.set(image.sourceId, (result.get(image.sourceId) ?? 0) + 1)
+  return result
 }
 
 async function imageFingerprints(paths: string[]): Promise<string[]> {
@@ -604,7 +1239,6 @@ export type SourceTypeProvider = () => SourceTypeDef[]
 /** Wiki 卡片类型注册表的读取入口（0024）：类型定义 + schema 生效方式。 */
 export interface WikiSchemaSnapshot {
   types: WikiTypeDef[]
-  mode: WikiSchemaMode
 }
 export type WikiSchemaProvider = () => WikiSchemaSnapshot
 
@@ -688,6 +1322,30 @@ export interface KnowledgeRuntimeOptions {
    * 不能让「没有模型就跑不动」成为新的前提。
    */
   modelCall?: ModelCall
+  /**
+   * **按需解析**模型接缝（0044）。
+   *
+   * 为什么不能只用上面那个 `modelCall`：它是**构造时读一次**的值，而插件 apply 的
+   * 时刻早于 `agent-default-model` 那个 bundle 挂载 —— profile 的组合顺序是
+   * 「package.json 的 bundles → cordis.patch.yml」，而 `agent-default-model` 在 patch 层。
+   * 于是那一次读到的永远是 undefined，而它**再也不会变**，模型抽取一次都不跑。
+   *
+   * 实跑证据（2026-09-27）：默认模型配的是 `opencode-go / deepseek-v4.1-flash`，而编译出来的
+   * 卡片 `metadata.extraction` 是 `pass0`（规则路径），正文是整篇文章 —— 也就是用户报的
+   * 「编译只是按目录截取」。静默降级了很久，因为没有任何一处说「模型抽取没生效」。
+   *
+   * 所以两者都给：`modelCall` 供测试注入固定值，`modelSeam` 供插件层延迟解析，
+   * **并且必须能说出拿不到的原因** —— `why` 会原样进 `rebuild` 的 warnings。
+   * 一个说不出理由的降级，等于没有降级信息。
+   */
+  modelSeam?: () => ModelSeam
+}
+
+/** 一次模型接缝解析的结果。两件东西都要有交代：能不能用，以及不能用时为什么。 */
+export interface ModelSeam {
+  call?: ModelCall
+  /** 拿不到 `call` 的原因，人话。会被原样写进 `rebuild` 的 warnings。 */
+  why?: string
 }
 
 export class KnowledgeRuntime {
@@ -720,8 +1378,16 @@ export class KnowledgeRuntime {
    * 写入与删除后必须失效（见 `addSource` / `deleteDocument`）。
    */
   private sourceIndex: Map<string, string> | undefined
+  /** `path → sourceId`：目标路径被谁占着（0051 的重名判定）。与 `sourceIndex` 同一次遍历建。 */
+  private sourcePathOwner: Map<string, string> | undefined
   /** 段内布局整理是否已经跑过（每个 runtime 一次）。 */
   private segmentsOrganized = false
+  /**
+   * 一次性迁移里**没有静默处理掉**的事（改名冲突、迁移后比对不一致）。
+   *
+   * 它必须能被界面读到：迁移失败而没人知道，等价于数据已经丢了。
+   */
+  private migrationProblems: string[] = []
   private vectorIndex: LoadedVectorIndex | null = null
   private vectorError: string | undefined
   private embeddingWorker: JsonLineWorker | null = null
@@ -751,8 +1417,10 @@ export class KnowledgeRuntime {
    * `memoryPath`，守卫换成「不许跑出 memoryDir」。
    */
   private readonly memoryDir: string
-  /** #3b 的模型调用接缝；undefined = 退回纯规则抽取。 */
-  private readonly modelCall: ModelCall | undefined
+  /** #3b 的模型调用接缝；undefined = 退回纯规则抽取。测试注入的固定值。 */
+  private readonly staticModelCall: ModelCall | undefined
+  /** 每次真正要用模型时问一遍的那个接缝 provider（0044）。为空则退回 `staticModelCall`。 */
+  private readonly modelSeamProvider?: () => ModelSeam
 
   constructor(rootDir: string, config: Partial<RuntimeKnowledgeConfig> = {}, options: KnowledgeRuntimeOptions = {}) {
     this.rootDir = resolve(rootDir)
@@ -763,7 +1431,8 @@ export class KnowledgeRuntime {
     this.sourceTypeProvider = options.sourceTypes
     this.wikiSchemaProvider = options.wikiSchema
     this.memoryDir = options.memoryRoot ? resolve(options.memoryRoot) : join(this.rootDir, '04_memory')
-    this.modelCall = options.modelCall
+    this.staticModelCall = options.modelCall
+    this.modelSeamProvider = options.modelSeam
     const resources = resolveResources(options.resourceRoot)
     this.pythonPath = config.python?.trim() || resources.python
     this.embeddingModelPath = config.embeddingModel?.trim() || resources.embeddingModel
@@ -771,6 +1440,17 @@ export class KnowledgeRuntime {
     this.embeddingModelId = resources.modelId(this.embeddingModelPath)
   }
 
+  /**
+   * 现在能不能用模型抽实体。
+   *
+   * **每次现问**，不是在构造时定死：插件 apply 的时刻早于 `agent-default-model` 挂载，
+   * 那时问一次只会得到 undefined，而定死之后就再也不会变（见 `modelCallProvider`）。
+   */
+  private modelSeamNow(): ModelSeam {
+    if (this.modelSeamProvider) return this.modelSeamProvider()
+    return this.staticModelCall ? { call: this.staticModelCall } : { why: '运行时没有注入模型接缝' }
+  }
+
   /**
    * 就地应用一份新的运行时配置（0.1.7 的 volatile 改动走这条路）。
    *
@@ -823,45 +1503,288 @@ export class KnowledgeRuntime {
 
   /** 当前生效的卡片 schema：类型定义 + 生效方式。 */
   wikiSchema(): WikiSchemaSnapshot {
-    return this.wikiSchemaProvider?.() ?? { types: defaultWikiTypes(), mode: 'report' }
+    return this.wikiSchemaProvider?.() ?? { types: defaultWikiTypes() }
   }
 
   /**
-   * Agent 与设置面板共用的类型目录：注册表 + 生效方式 + 内置只读判定规则 +
-   * 现有卡片的三层校验结果（`report` 模式下这是"待补"清单）。
+   * Agent 与设置面板共用的类型目录：注册表 + 内置只读判定规则 +
+   * 现有卡片的三层校验结果（`report` 模式下这是"待补"清单）+ **review 进度**。
+   *
+   * review 计数挂在这里而不是另开一路，是因为 review 就发生在这一屏（「知识库 → Wiki」）——
+   * 与 lint 待补清单是同一处，不新造第二套界面。
+   *
+   * 0044：`proposals`（待审提议条数）改成 `reviews`。队列退役之后「还有几条等人确认」
+   * 这个问题不再有意义 —— 卡片一编译就入库了，剩下的问题是「入库的这些里，我看过几条」。
    */
   async wikiTypeCatalog(): Promise<Envelope<WikiTypeCatalog>> {
     const schema = this.wikiSchema()
     const issues = await this.lintCards()
+    const cards = await this.loadCards()
     return success({
       types: schema.types,
-      mode: schema.mode,
       rules: WIKI_TYPE_RULES,
       issues: issues.slice(0, 50),
       issueCount: issues.length,
+      reviews: {
+        total: cards.length,
+        unreviewed: cards.filter(card => card.review?.state !== 'reviewed').length,
+        reviewed: cards.filter(card => card.review?.state === 'reviewed').length,
+        anomalies: cards.filter(card => (card.annotations ?? []).some(item => item.kind === 'anomaly')).length,
+      },
     })
   }
 
-  /** 对已落库的卡片跑三层校验。不写盘，只报告。 */
+  /**
+   * 智能归因图谱的存储句柄。
+   *
+   * 它由 runtime 自己构造（而不是由 index.ts 注入），因为 `rebuild` 要产出
+   * `03_compiled/diagnosis_graph.json` —— 那次产出必须和 `knowledge_graph.json`
+   * 在同一次卡片遍历的语义下发生，否则两份产物会来自两个不同版本的卡片。
+   */
+  private diagnosis?: DiagnosisStore
+
+  diagnosisStore(): DiagnosisStore {
+    if (!this.diagnosis) this.diagnosis = new DiagnosisStore(this)
+    return this.diagnosis
+  }
+
+  /* ────────────────────────────────────── 卡片入库：直接写，不排队 ── */
+
+  /**
+   * 把一批卡片**直接写进 `02_wiki`**（0044）。
+   *
+   * 0040 v1.5 的这道门原来是「提一条提议 → 人在面板确认 → 才落卡」，理由是类型层是收敛的
+   * 那一层，错一条所有现象的排序一起错。0044 把方向反过来：**入库在前、review 在后**。
+   * 判据是实践中的两个事实：
+   *
+   * 1. **确认门把知识挡在了门外。** 抽到的东西停在 `memory/card-proposals/` 里等人点，
+   *    而人不会一条条点。用户看到的现象就是「编译没生效」——文档导进去了，wiki 是空的。
+   * 2. **review 的价值不需要排队来实现。** 「这张卡片对不对」可以在它已经可召回之后回答；
+   *    而「未 review 就不许进来」等于把「暂时没人看的正确知识」和「错误知识」一起丢掉。
+   *
+   * 于是现在的形状是：入库 → 召回得到（评分稍低）→ 人 review → 评分抬高 / 备注异常点。
+   * 拒绝某条知识的正确做法是 `set_knowledge_status(deprecated|problem)`，它会留痕，
+   * 也能被撤回 —— 比「从来没见过它」更容易纠正。
+   *
+   * 与编译路径的差别只有一条：这里允许调用方指定 `entityId` 与正文，编译路径由候选推导。
+   * 两者共用 `writeCard`，所以校验、版本快照、备注保留的行为完全一致。
+   */
+  async writeCards(input: {
+    sourceId: string
+    cards: Array<{
+      action?: 'create' | 'update' | 'merge'
+      entityType: string
+      entityId: string
+      title: string
+      summary?: string
+      content: string
+      sourceRefs?: string[]
+      metadata?: Record<string, unknown>
+    }>
+    lineage?: LineageContext
+  }): Promise<Envelope<{ written: number; ids: string[]; rejected: string[]; warnings: string[] }>> {
+    const empty = { written: 0, ids: [] as string[], rejected: [] as string[], warnings: [] as string[] }
+    if (!input.sourceId?.trim()) return failure(empty, 'SOURCE_REF_REQUIRED', '卡片必须挂在一条来源上', false, '先调 add_source 落一条来源，再用它的 source_id 写入卡片。')
+    const sources = new Set((await this.loadSources()).map(source => source.sourceId))
+    if (!sources.has(input.sourceId)) {
+      return failure(empty, 'SOURCE_REF_NOT_FOUND', `source_refs 引用不存在: ${input.sourceId}`, false, '先调用 add_source 写入对应的 SourceTruth')
+    }
+    if (!Array.isArray(input.cards) || input.cards.length === 0) {
+      return failure(empty, 'CARD_EMPTY', '至少要写一张卡片', true)
+    }
+    const schema = this.wikiSchema()
+    const rejected: string[] = []
+    const warnings: string[] = []
+    const ids: string[] = []
+    /**
+     * 判重索引只读一次。**批量里的后一张要能看到前一张刚写的卡片** —— 同一个实体在
+     * 一批里出现两次时，第二次必须走并入而不是再写一遍，所以写成功后要回填这张表。
+     */
+    const byKey = new Map((await this.loadCards()).map(card => [`${card.entityType}:${card.entityId}`, card]))
+    for (const item of input.cards) {
+      const type = schema.types.find(def => def.id === item.entityType)
+      if (!type) { rejected.push(`${item.entityId}：未知卡片类型 ${item.entityType}`); continue }
+      if (!type.enabled) { rejected.push(`${item.entityId}：类型 ${item.entityType} 已停用`); continue }
+      /**
+       * **已有卡片时走「并入」而不是覆盖。**
+       *
+       * 这一步是必需的，不是优化：Agent 按「同一实体跨两份文档」调用两次时，覆盖式写入会让
+       * 第一份来源与它的正文**静默消失**（实测：先 doc:a 再 doc:b，卡片只剩 `["doc:b"]`）。
+       * 退役的提议存储天然按身份去重并累积 `source_refs`，所以少了这一步就是相对旧链路的一处退化。
+       *
+       * 三条合并规则与编译路径完全相同，两处共用 `appendExtracted`：
+       * 正文追加（自带文本判重）、`source_refs` 取并集、`metadata` 合并。
+       * `status` 与人工备注 / review 由 `writeCard` 自己保留，不在这里重复照顾。
+       */
+      const existing = byKey.get(`${item.entityType}:${item.entityId}`)
+      const requestedRefs = item.sourceRefs ?? [input.sourceId]
+      const sourceRefs = existing ? [...new Set([...existing.sourceRefs, ...requestedRefs])] : requestedRefs
+      const content = existing ? appendExtracted(existing.content, [item.content]) : item.content
+      const written = await this.writeCard({
+        entityType: item.entityType as SchemaType,
+        entityId: item.entityId,
+        title: item.title,
+        content,
+        sourceRefs,
+        ...(item.summary ?? existing?.summary ? { summary: item.summary ?? existing?.summary } : {}),
+        ...(item.metadata || existing?.metadata ? { metadata: { ...(existing?.metadata ?? {}), ...(item.metadata ?? {}) } } : {}),
+        ...(existing ? { status: existing.status } : {}),
+        ...(existing?.owner ? { owner: existing.owner } : {}),
+        ...(existing?.provenance ? { provenance: existing.provenance } : {}),
+        origin: 'compile',
+        ...(input.lineage ? { lineage: input.lineage } : {}),
+      })
+      if (written.ok === false) {
+        rejected.push(`${item.entityId}：${written.error.code} ${written.error.message}`)
+        continue
+      }
+      ids.push(item.entityId)
+      // 回填：这一批里后面那张卡片要按**刚写下的**样子判重，而不是按开批之前的磁盘快照。
+      byKey.set(`${item.entityType}:${item.entityId}`, {
+        entityId: item.entityId, entityType: item.entityType as SchemaType, title: item.title,
+        status: existing?.status ?? 'unreviewed', content, sourceRefs,
+        ...(item.summary ?? existing?.summary ? { summary: item.summary ?? existing?.summary } : {}),
+        metadata: { ...(existing?.metadata ?? {}), ...(item.metadata ?? {}) }, updatedAt: new Date().toISOString(),
+      })
+      for (const warning of written.warnings ?? []) warnings.push(`${item.entityId}：${warning}`)
+    }
+    return success(
+      { written: ids.length, ids, rejected, warnings },
+      rejected.length > 0 ? [`${rejected.length} 张卡片被拒：${rejected.join('；')}`] : [],
+    )
+  }
+
+  /* ────────────────────────────────────── 入库之后：备注与 review ── */
+
+  /**
+   * 给一张卡片加一条**人工备注**，或撤掉一条（0044）。
+   *
+   * 这是「wiki 不可修改」的对偶：正文改不了，但**判断改得了**。「这份文档的数字和卡片
+   * 对不上」「这个口径在另一份文档里是反的」——这些都是关于卡片的判断，不是卡片的内容，
+   * 所以它们落在 frontmatter 的 `annotations` 里，编译永远不碰。
+   *
+   * `kind: 'anomaly'` 会把卡片的有效评分压到 `ANOMALY_SCORE`（见 `effectiveReviewScore`）：
+   * 异常卡片照样召回得到，只是排在后面 —— 而不是被藏起来。藏起来的问题在于没人会再看到它，
+   * 于是也就没人会去修。
+   */
+  async annotateCard(input: {
+    entityId: string
+    entityType?: SchemaType
+    /** 不传 `note` 时必须是「撤销一条」：给出 `removeId`。 */
+    kind?: 'note' | 'anomaly'
+    note?: string
+    author?: string
+    sourceRef?: string
+    removeId?: string
+    lineage?: LineageContext
+  }): Promise<Envelope<{ entityId: string; annotations: CardAnnotation[]; reviewScore: number }>> {
+    const card = await this.readCard(input.entityId, input.entityType)
+    if (!card) return failure({ entityId: input.entityId, annotations: [], reviewScore: 0 }, 'CARD_NOT_FOUND', `知识卡片不存在: ${input.entityId}`, true)
+    const current = card.annotations ?? []
+    let next: CardAnnotation[]
+    if (input.removeId?.trim()) {
+      next = current.filter(item => item.id !== input.removeId!.trim())
+      if (next.length === current.length) {
+        return failure({ entityId: input.entityId, annotations: current, reviewScore: effectiveReviewScore(card) }, 'ANNOTATION_NOT_FOUND', `备注不存在: ${input.removeId}`, true)
+      }
+    } else {
+      const note = input.note?.trim() ?? ''
+      if (!note) return failure({ entityId: input.entityId, annotations: current, reviewScore: effectiveReviewScore(card) }, 'ANNOTATION_NOTE_REQUIRED', 'note 不能为空', true)
+      const at = new Date().toISOString()
+      next = [...current, {
+        id: annotationId(note, at),
+        kind: input.kind === 'anomaly' ? 'anomaly' : 'note',
+        note,
+        ...(input.author?.trim() ? { author: input.author.trim() } : {}),
+        createdAt: at,
+        ...(input.sourceRef?.trim() ? { sourceRef: input.sourceRef.trim() } : {}),
+      }]
+    }
+    const written = await this.writeCard({ ...card, sourceRefs: card.sourceRefs, annotations: next, origin: 'internal' as const })
+    if (written.ok === false) return failure({ entityId: input.entityId, annotations: current, reviewScore: effectiveReviewScore(card) }, written.error.code, written.error.message, written.error.retryable, written.error.suggestion)
+    await this.audit('wiki.annotate', { entityId: input.entityId, added: input.removeId ? 0 : 1, removed: input.removeId ? 1 : 0, count: next.length })
+    const score = effectiveReviewScore({ annotations: next, ...(card.review ? { review: card.review } : {}) })
+    return success({ entityId: input.entityId, annotations: next, reviewScore: score })
+  }
+
+  /**
+   * review 一张卡片（0044）。**它不是准入闸门** —— 卡片在 review 之前就已经入库、可召回了。
+   *
+   * `review` 把评分抬到 `REVIEWED_SCORE_FLOOR`，`unreview` 放回出厂分。两个动作都可逆：
+   * review 是一个可以被推翻的判断，不是一次性的凭证。
+   */
+  async reviewCard(input: {
+    entityId: string
+    entityType?: SchemaType
+    action: 'review' | 'unreview'
+    reviewer?: string
+    lineage?: LineageContext
+  }): Promise<Envelope<{ entityId: string; review: CardReview; reviewScore: number; status: KnowledgeStatus }>> {
+    const card = await this.readCard(input.entityId, input.entityType)
+    if (!card) return failure({ entityId: input.entityId, review: { state: 'unreviewed', score: CARD_REVIEW_BASE_SCORE }, reviewScore: CARD_REVIEW_BASE_SCORE, status: 'unreviewed' as KnowledgeStatus }, 'CARD_NOT_FOUND', `知识卡片不存在: ${input.entityId}`, true)
+    const at = new Date().toISOString()
+    const reviewer = input.reviewer?.trim() || 'user:panel'
+    const review: CardReview = input.action === 'review'
+      ? { state: 'reviewed', score: Math.max(card.review?.score ?? 0, REVIEWED_SCORE_FLOOR), reviewedAt: at, reviewedBy: reviewer }
+      : { state: 'unreviewed', score: CARD_REVIEW_BASE_SCORE }
+    /**
+     * 状态跟着一起走（0044 实机验证第七批）。
+     *
+     * 卡片有两个字段：`status` 是**生命周期**（编译器写它，人在 `set_knowledge_status`
+     * 里改），`review` 是**人的判断 + 评分**。它们本来描述不同的事，但「已经 review 过」
+     * 的卡片在预览里显示 `状态 unreviewed` 会让人以为刚才那一下没生效 —— 实机验证时
+     * 看到的就是这个组合。
+     *
+     * 所以：
+     * - `review` 通过时，`unreviewed` / `draft` 推进到 `reviewed`（这个词本来就在
+     *   状态词表里，含义就是这个）；
+     * - 撤销 review 时只把 `reviewed` 退回 `unreviewed`，**不动** `active` / `deprecated` /
+     *   `problem` —— 那些是人另外做过的决定，不该被一次撤销顺手抹掉。
+     */
+    const nextStatus: KnowledgeStatus = input.action === 'review'
+      ? (card.status === 'unreviewed' || card.status === 'draft' ? 'reviewed' : card.status)
+      : (card.status === 'reviewed' ? 'unreviewed' : card.status)
+    const written = await this.writeCard({ ...card, status: nextStatus, sourceRefs: card.sourceRefs, review, origin: 'review' as const })
+    if (written.ok === false) {
+      const current: CardReview = card.review ?? { state: 'unreviewed', score: CARD_REVIEW_BASE_SCORE }
+      return failure({ entityId: input.entityId, review: current, reviewScore: effectiveReviewScore(card), status: card.status }, written.error.code, written.error.message, written.error.retryable, written.error.suggestion)
+    }
+    await this.audit('wiki.review', { entityId: input.entityId, action: input.action, reviewer, score: review.score })
+    return success({ entityId: input.entityId, review, reviewScore: effectiveReviewScore({ ...card, review }), status: nextStatus })
+  }
+
+  /**
+   * 对已落库的卡片跑三层校验。不写盘，只报告。
+   *
+   * 0049 补齐了 `reference` 那一层：正文里的 `[[类型/名称]]` 指向一张不存在的卡片，
+   * 就是一条断链。此前这一层只有类型定义里的名字，没有任何产生者 —— 而「引用错说明
+   * 图断了」正是它要回答的问题（format 错说明没填完，语义错说明这条知识没用）。
+   */
   async lintCards(): Promise<Array<CardSchemaIssue & { entityId: string; entityType: string }>> {
     const schema = this.wikiSchema()
     const byId = new Map(schema.types.map(def => [def.id, def]))
     const result: Array<CardSchemaIssue & { entityId: string; entityType: string }> = []
-    for (const card of await this.loadCards()) {
+    const cards = await this.loadCards()
+    for (const card of cards) {
       const type = byId.get(card.entityType)
       if (!type) continue
       for (const issue of validateCardAgainstType(type, card)) {
         result.push({ ...issue, entityId: card.entityId, entityType: card.entityType })
       }
     }
+    // 断链与类型无关（一张类型没登记的卡片照样能有链接），所以单独扫一遍全部卡片。
+    for (const link of deadLinksOf(cards)) {
+      result.push({ ...deadLinkIssue(link.target), entityId: link.entityId, entityType: link.entityType })
+    }
     return result
   }
 
   /**
-   * `write_knowledge_card` 的类型闸门 + 三层校验。
+   * 类型闸门 + 三层校验。
    *
-   * 返回 `{ type, issues }` 或一个失败信封。是否因 issues 拒绝写入由 `mode` 决定：
-   * `strict` 直接拒绝，`report` 把问题写进卡片并回报——存量卡片因此不会被升级挡在门外。
+   * 返回 `{ type, issues }` 或一个失败信封（只可能因为**未知类型** —— 没有类型定义就连
+   * 「缺什么」都说不出来）。issues **不决定写不写**：0044 起卡片一律直接入库，问题写进
+   * `metadata.schema_issues` 由面板显示成「待补」。原来的 `strict` / `report` 开关一并撤掉了。
    */
   private cardSchemaGate(input: { entityType: string; title: string; content: string; sourceRefs: string[]; metadata: Record<string, unknown>; owner?: string; summary?: string }):
   { type: WikiTypeDef; issues: CardSchemaIssue[] } | { error: KnowledgeError } {
@@ -933,6 +1856,13 @@ export class KnowledgeRuntime {
   }
 
   directory(name: typeof LAYOUT[number]): string { return join(this.rootDir, name) }
+  /**
+   * 0051 之前的段目录路径。
+   *
+   * 它**不在 `LAYOUT` 里**：`LAYOUT` 是「应该建出来的目录」清单，而老段名只是要读、
+   * 要搬走的东西 —— 把它加进 `LAYOUT`，`ensureLayout` 每次启动都会把那个空目录建回来。
+   */
+  private legacySourceDir(): string { return join(this.rootDir, LEGACY_SOURCE_TRUTH) }
   async ensureLayout(): Promise<void> {
     await Promise.all(LAYOUT.map(name => mkdir(this.directory(name), { recursive: true })))
     // 记忆段在知识树**外面**（0032），所以要单独建。它与 LAYOUT 一起建的理由相同：
@@ -943,11 +1873,109 @@ export class KnowledgeRuntime {
     // 写入与统计的入口。实例级标志保证每个 runtime 只扫一次。
     if (!this.segmentsOrganized) {
       this.segmentsOrganized = true
+      // 0051 的改名排在最前：后面几个迁移都按 `SOURCE_TRUTH` 扫目录，先把树搬过来，
+      // 它们就只需要认一个名字（而老段名只留兼容解析那一处）。
+      await this.migrateSourceTree()
       await this.migrateSourceTruthLayout()
-      await this.dropLegacySchemaSegment()
+      await this.dropRetiredSegments()
+      await this.migrateLegacySourceTypeRename()
+      await this.migrateLegacyDiagnosisCards()
+      await this.migrateSourceFrontMatter()
+      await this.migrateSourceFileNames()
     }
   }
 
+  /**
+   * 0051：`01_source_truth/` → `01_source_raw/`。
+   *
+   * **整棵树一次 `rename`**，不逐文件搬：`_assets/` 就在那个目录里，逐文件搬会把
+   * 图片落下的概率变成「每个文件各一次」。一次 rename 是原子的，要么全过来要么全没动。
+   *
+   * 两种中间态都要处理：
+   * - 目标不存在 → 直接 rename；
+   * - 两个目录都在（上一次搬到一半）→ 逐项合并：目标里没有的搬过去，两边都有的
+   *   （`_assets` 与分类目录）递归合并，最后删掉空壳。
+   *
+   * 失败不回滚、不抛：`loadSources` 两个段名都扫，搬到一半的库照常可读，
+   * 下一次启动接着搬。
+   */
+  private async migrateSourceTree(): Promise<void> {
+    const from = this.legacySourceDir()
+    const to = this.directory(SOURCE_TRUTH)
+    if (!existsSync(from)) return
+    try {
+      if (!existsSync(to)) {
+        await rename(from, to)
+      } else {
+        await mergeDir(from, to)
+        await rmdir(from).catch(() => { /* 还有搬不动的，下次再来 */ })
+      }
+      this.sourceIndex = undefined
+      this.sourcePathOwner = undefined
+      this.migrationProblems.push('段目录已改名为 01_source_raw（原 01_source_truth）')
+    } catch (cause) {
+      this.migrationProblems.push(`段目录改名未完成，下次启动继续：${cause instanceof Error ? cause.message : String(cause)}`)
+    }
+  }
+
+  /**
+   * 0051：文件名改成标题。
+   *
+   * 只动**名字不对**的那些（可重入），而且**只 rename，不改内容** —— 正文里那些
+   * `../../01_source_truth/_assets/…` 的老引用一个字节都不动，解析器认两个段名
+   * （见 `assetRefCandidates`）。改内容会造内容版本、让卡片重编重编码，代价远大于
+   * 一个字符串好不好看。
+   *
+   * 目标路径被别的来源占着时**不覆盖**：加内容哈希后缀并记一条，让人去改标题
+   * （与 `addSource` 的默认拒收同一条纪律，只是这里不能拒 —— 那是历史数据）。
+   */
+  private async migrateSourceFileNames(): Promise<void> {
+    const sources = await this.loadSources()
+    const index = await this.sourceIndexMap()
+    const taken = new Map<string, string>()
+    for (const source of sources) {
+      const path = index.get(slug(source.sourceId))
+      if (path === undefined) continue
+      taken.set(path, source.sourceId)
+    }
+    for (const source of sources) {
+      const path = index.get(slug(source.sourceId))
+      if (path === undefined) continue
+      /**
+       * 没有合法 `type` 的文件**留在原地**（与 0030 同一条纪律：宁可少搬，不可搬错）。
+       *
+       * `loadSources` 把读不出分类的来源当成 `document`（读得到总比丢掉好），所以
+       * 「默认成了 document」与「真的写着 document」在这里长得一样 —— 必须回文件里
+       * 看那一行，否则一个没有 front matter 的散文件会被搬进 `document/`。
+       */
+      if (!(await this.hasDeclaredSourceType(path))) continue
+      let target = this.sourcePath(source.sourceId, source.sourceType, source.title)
+      if (target === path) continue
+      const occupant = taken.get(target)
+      if (occupant !== undefined && occupant !== source.sourceId) {
+        target = this.safePath(SOURCE_TRUTH, source.sourceType, `${sourceFileBase(source.title, source.sourceId)}-${hash(source.sourceId).slice(0, 6)}.md`)
+        this.migrationProblems.push(`来源 ${source.sourceId} 与 ${occupant} 标题相同（「${source.title}」），已落成 ${basename(target)}；建议改标题`)
+      }
+      try {
+        await mkdir(dirname(target), { recursive: true })
+        await rename(path, target)
+        taken.delete(path)
+        taken.set(target, source.sourceId)
+      } catch (cause) {
+        this.migrationProblems.push(`来源 ${source.sourceId} 改名失败，保持原名：${cause instanceof Error ? cause.message : String(cause)}`)
+      }
+    }
+    this.sourceIndex = undefined
+    this.sourcePathOwner = undefined
+  }
+
+  /** 这份文件自己声明了合法分类吗（`migrateSourceFileNames` 只搬声明过的）。 */
+  private async hasDeclaredSourceType(path: string): Promise<boolean> {
+    try {
+      return SOURCE_TYPE_ID_PATTERN.test(sourceTypeOf(parseMarkdown(await readFile(path, 'utf8')).frontmatter))
+    } catch { return false }
+  }
+
   /**
    * 0030：把平铺的 `<段>/*.md` 搬进 `<段>/<source_type>/*.md`。
    *
@@ -965,7 +1993,7 @@ export class KnowledgeRuntime {
       const from = join(root, entry.name)
       let sourceType = ''
       try {
-        sourceType = String(parseMarkdown(await readFile(from, 'utf8')).frontmatter.source_type ?? '')
+        sourceType = sourceTypeOf(parseMarkdown(await readFile(from, 'utf8')).frontmatter)
       } catch { continue }
       if (!SOURCE_TYPE_ID_PATTERN.test(sourceType)) continue
       const target = join(root, sourceType, entry.name)
@@ -978,6 +2006,64 @@ export class KnowledgeRuntime {
     this.sourceIndex = undefined
   }
 
+  /**
+   * 0048：把存量 SourceRaw 的 front matter 改成 OKF v0.2 的形状。
+   *
+   * 改三件事，都只搬**已经存在**的值，不猜、不造：
+   *
+   * 1. `source_type` → `type`（OKF 唯一必填键）。旧键删掉 —— 同一个事实留两份，
+   *    迟早会出现「改了这份、那份没改」。读取侧两个键都认（见 `sourceTypeOf`），
+   *    所以迁移没跑到、或别的库还是旧形状，都不影响可用性。
+   * 2. `metadata.source_url` → 顶层 `resource`（OKF 的「底层资产地址」）。
+   * 3. 补 `generated{by,at}` 与 `sources[]`：`by` 取自 `metadata.parser`（谁解析的），
+   *    `at` 取自 `created_at`（这份文件什么时候写出来的）。**作者与发布时间补不出来**
+   *    —— 0048 之前适配器把它们抽出来就扔了，这里如实留空，不编一个。
+   *
+   * 正文一个字节都不动，也不制造内容版本（版本只认正文变化）。整个迁移可重入：
+   * 已经有 `type` 的文件直接跳过。
+   */
+  private async migrateSourceFrontMatter(): Promise<void> {
+    for (const path of await filesUnder(this.directory(SOURCE_TRUTH))) {
+      let parsed
+      try { parsed = parseMarkdown(await readFile(path, 'utf8')) } catch { continue }
+      const frontmatter = parsed.frontmatter
+      if (typeof frontmatter.type === 'string' && frontmatter.type.trim()) continue
+      const sourceType = sourceTypeOf(frontmatter) || 'document'
+      const metadata = plainRecord(frontmatter.metadata)
+      const resource = typeof metadata.source_url === 'string' && metadata.source_url.trim() ? metadata.source_url.trim() : undefined
+      const parser = typeof metadata.parser === 'string' && metadata.parser.trim() ? metadata.parser.trim() : undefined
+      const createdAt = typeof frontmatter.created_at === 'string' ? frontmatter.created_at : undefined
+      const title = typeof frontmatter.title === 'string' ? frontmatter.title : undefined
+      /**
+       * `metadata.source_url` 与顶层 `resource` 是同一个事实：搬上去之后就把旧的删掉
+       * —— 两份键迟早出现「改了这份、那份没改」。`source_path` 同理：它指的是暂存目录里
+       * 那个**已经被删掉**的文件，留着它只会让人以为还能找回来（底稿现在由交付目录的
+       * `source/` 承担，0048 起才有）。
+       */
+      const { source_url: _promoted, source_path: _stale, ...restMetadata } = metadata
+      const { source_type: _legacy, ...rest } = frontmatter
+      const nextMetadata = Object.keys(restMetadata).length > 0 ? restMetadata : undefined
+      const next: Record<string, unknown> = {
+        type: sourceType,
+        ...(title !== undefined ? { title } : {}),
+        ...(resource !== undefined ? { resource } : {}),
+        ...(parser !== undefined || createdAt !== undefined
+          ? { generated: { ...(parser !== undefined ? { by: `convert/${parser}` } : {}), ...(createdAt !== undefined ? { at: createdAt } : {}) } }
+          : {}),
+        ...(resource !== undefined ? { sources: [{ id: 'origin', resource, ...(title !== undefined ? { title } : {}) }] } : {}),
+        ...rest,
+        ...(nextMetadata !== undefined ? { metadata: nextMetadata } : {}),
+      }
+      try {
+        await writeTextAtomic(path, markdown(next, parsed.content))
+      } catch (cause) {
+        this.migrationProblems.push(`来源 ${basename(path)} 的 front matter 迁移失败：${cause instanceof Error ? cause.message : String(cause)}`)
+      }
+    }
+    this.sourceIndex = undefined
+    this.sourceCorpusCache = undefined
+  }
+
   /**
    * 0030：删掉已经被撤掉的 `00_schema` 段。
    *
@@ -985,8 +2071,35 @@ export class KnowledgeRuntime {
    * 有人放了文件，那就不属于「没用的空文件夹」了 —— 那种情况下留着并让人自己判断，
    * 比替他们删掉安全。
    */
-  private async dropLegacySchemaSegment(): Promise<void> {
-    const path = this.safePath('00_schema')
+  /**
+   * 清掉**只装了旧版本自己生成的东西**的退役段。
+   *
+   * `00_schema` 从来没有一行代码写过东西，所以「空」就是它的全部历史形态 —— 空就删。
+   *
+   * `05_diagnosis` 不一样：旧版本在里面铺过 `templates/*.md` 与一份 README，那两样是
+   * 可以重建的（模板由类型定义派生、README 是说明），删掉不丢知识。但同一个目录里
+   * 可能躺着**真正的历史快照**（`*.jsonl` / `cases.json`），那是只读的迁移输入，
+   * 一个字节都不能动。所以判据是**文件清单**而不是「空不空」：只认得旧版本自己写的
+   * 那些名字时，才删；出现任何别的东西就整个留着。
+   */
+  private async dropRetiredSegments(): Promise<void> {
+    await this.dropSegmentIfEmpty('00_schema')
+    const legacy = this.safePath('05_diagnosis')
+    try {
+      const entries = await readdir(legacy, { withFileTypes: true })
+      const owned = entries.every(entry =>
+        entry.isDirectory()
+          ? entry.name === 'templates'
+          : entry.name === 'README.md' || entry.name.endsWith('.jsonl') || entry.name === 'cases.json')
+      if (!owned) return
+      // 有 jsonl / cases.json 就是历史快照，留着（`DiagnosisStore` 还要读它做迁移）。
+      if (entries.some(entry => entry.isFile() && (entry.name.endsWith('.jsonl') || entry.name === 'cases.json'))) return
+      await rm(legacy, { recursive: true, force: true })
+    } catch { /* 不存在或删不掉都不是错误 */ }
+  }
+
+  private async dropSegmentIfEmpty(name: string): Promise<void> {
+    const path = this.safePath(name)
     try {
       const entries = await readdir(path)
       if (entries.length > 0) return
@@ -997,6 +2110,137 @@ export class KnowledgeRuntime {
     } catch { /* 不存在、非空、或删不掉都不是错误 */ }
   }
 
+  /**
+   * 0040 §3.2 的一次性迁移：`01_source_raw/ai_chat_message/` → `agent_chat_message/`。
+   *
+   * 改名不能只改注册表：`01_source_raw/` 是**按分类分目录**的，存量来源的
+   * frontmatter 里写着 `source_type: ai_chat_message`。只改注册表会有两个后果 ——
+   * 旧目录里那些来源变成一个「注册表里没有的分类」（界面上显示成未知分类），
+   * 而旧分类因为还有来源在，永远删不掉。
+   *
+   * 三条纪律：
+   * 1. **逐份搬，不整体 rename 目录。** 目标里可能已经有同名文件（用户在新版本里
+   *    重新录过同一份来源），整体搬会覆盖它。
+   * 2. **同名时比对正文**：一致就删掉旧的那份（同一份东西，只是目录名变了）；
+   *    不一致就**两边都留**，并把冲突报给界面 —— 静默覆盖等于丢数据。
+   * 3. **迁移无损才认**：写完读回来比对 frontmatter 与正文，不一致就放弃这一份。
+   */
+  private async migrateLegacySourceTypeRename(): Promise<void> {
+    const from = this.safePath(SOURCE_TRUTH, 'ai_chat_message')
+    const to = this.safePath(SOURCE_TRUTH, 'agent_chat_message')
+    let names: string[]
+    try { names = await readdir(from) } catch { return }
+    const conflicts: string[] = []
+    for (const name of names) {
+      if (extname(name).toLowerCase() !== '.md') continue
+      const source = join(from, name)
+      let raw: string
+      try { raw = await readFile(source, 'utf8') } catch { continue }
+      const parsed = parseMarkdown(raw)
+      const sourceId = String(parsed.frontmatter.source_id ?? basename(name, '.md'))
+      const target = join(to, name)
+      let existing: string | undefined
+      try { existing = await readFile(target, 'utf8') } catch { /* 目标里还没有 */ }
+      if (existing !== undefined) {
+        const previous = parseMarkdown(existing)
+        if (previous.content.trim() !== parsed.content.trim()) conflicts.push(sourceId)
+        await unlinkIfExists(source)
+        continue
+      }
+      await writeTextAtomic(target, markdown({ ...parsed.frontmatter, type: 'agent_chat_message', source_type: 'agent_chat_message' }, parsed.content))
+      const roundTrip = parseMarkdown(await readFile(target, 'utf8'))
+      if (roundTrip.content.trim() !== parsed.content.trim() || sourceTypeOf(roundTrip.frontmatter) !== 'agent_chat_message') {
+        // 读回来对不上：把目标撤掉，旧的那份留着 —— 宁可迁移没生效，也不要留半份。
+        await unlinkIfExists(target)
+        conflicts.push(`${sourceId}（迁移后比对不一致，已放弃）`)
+        continue
+      }
+      await unlinkIfExists(source)
+    }
+    try { await rmdir(from) } catch { /* 还有别的东西在里面 */ }
+    if (conflicts.length > 0) {
+      this.migrationProblems.push(`来源分类改名迁移有 ${conflicts.length} 处冲突，旧文件保留在 01_source_raw/ai_chat_message/：${conflicts.join('、')}`)
+    }
+  }
+
+  /**
+   * 0040 §4 的一次性迁移：两次改名（`check` → `check_point`、`failure-mode` →
+   * `failure_reason`）的存量卡片。
+   *
+   * 两件事一起做，因为它们是同一次改名的两个面：
+   * 1. **卡片类型**：`02_wiki/diagnosis/check/` → `check-point/`，
+   *    frontmatter 的 `entity_type` 一起改；
+   * 2. **结构化块里的字段名**：`failure_mode` → `failure_reason`。这一条与卡片类型
+   *    无关 —— `diagnosis/hypothesis` 卡片的类型没变，但它块里那个字段变了。
+   *    只按目录过滤的话，假设卡片上的旧字段名会永远留在磁盘上，而读回来是「少一个
+   *    必填字段」，正文里却明明写着它。
+   *
+   * 读取端本来也认别名（`cards.parseCard`），但**只在内存里认是不够的**：`writeCard`
+   * 按 `entity_type` 决定写哪个目录，改一张旧卡片就会在 `check-point/` 下多写一份，
+   * 而旧目录里那份还在 —— 同一张卡片变成两张，读图时看谁先被遍历到。
+   *
+   * 用 `writeCard` 而不是自己拼 frontmatter：它是唯一知道卡片信封长什么样、并且会
+   * 顺手做版本快照与三层校验的地方。
+   */
+  private async migrateLegacyDiagnosisCards(): Promise<void> {
+    const root = this.safePath(WIKI, 'diagnosis')
+    let kinds: string[]
+    try { kinds = await readdir(root) } catch { return }
+    /**
+     * 目录名是 `entity_type` 的**命名空间之后那一段**（`02_wiki/diagnosis/check/` 对应
+     * `diagnosis/check`）。用后缀匹配而不是拿 `entity_type` 直接比目录名 —— 直接比的话
+     * 一个都匹配不上，而失败方式是静默的：迁移什么都没做，卡片仍按旧类型读。
+     */
+    const legacyByDir = new Map<string, string>()
+    for (const [legacy, next] of Object.entries(LEGACY_ENTITY_TYPES)) {
+      legacyByDir.set(legacy.slice(legacy.indexOf('/') + 1), next)
+    }
+    const problems: string[] = []
+    for (const dir of kinds) {
+      const legacyDir = join(root, dir)
+      const renamedType = legacyByDir.get(dir)
+      // 类型没改名、也不在旧目录里的子树也要扫一遍：块字段名的改名与类型无关。
+      for (const file of await filesUnder(legacyDir)) {
+        let raw: string
+        try { raw = await readFile(file, 'utf8') } catch { continue }
+        const parsed = parseMarkdown(raw)
+        const entityId = String(parsed.frontmatter.entity_id ?? basename(file, '.md'))
+        const currentType = String(parsed.frontmatter.entity_type ?? '')
+        const nextType = renamedType ?? LEGACY_ENTITY_TYPES[currentType] ?? currentType
+        if (!nextType) continue
+        const body = rewriteLegacyBlockFields(parsed.content)
+        const typeChanged = nextType !== currentType
+        const bodyChanged = body !== parsed.content
+        // 两样都没变就什么都不做 —— 每次启动都重写一遍所有卡片会把版本历史灌满。
+        if (!typeChanged && !bodyChanged) continue
+        const written = await this.writeCard({
+          entityType: nextType as SchemaType,
+          entityId,
+          title: String(parsed.frontmatter.title ?? entityId),
+          content: body,
+          sourceRefs: Array.isArray(parsed.frontmatter.source_refs) ? parsed.frontmatter.source_refs.map(String) : [],
+          status: (STATUS.includes(String(parsed.frontmatter.status) as KnowledgeStatus) ? String(parsed.frontmatter.status) : 'unreviewed') as KnowledgeStatus,
+          ...(typeof parsed.frontmatter.summary === 'string' && parsed.frontmatter.summary ? { summary: parsed.frontmatter.summary } : {}),
+          ...(typeof parsed.frontmatter.owner === 'string' && parsed.frontmatter.owner ? { owner: parsed.frontmatter.owner } : {}),
+          metadata: typeof parsed.frontmatter.metadata === 'object' && parsed.frontmatter.metadata ? parsed.frontmatter.metadata as Record<string, unknown> : {},
+        })
+        if (written.ok === false) {
+          problems.push(`卡片 ${entityId} 从 ${currentType || dir} 迁到 ${nextType} 失败（${written.error.code}），旧文件保留`)
+          continue
+        }
+        // 读回来确认它真的落在新目录、而且认得出新类型，再删旧的。
+        const readBack = await this.readCard(entityId, nextType as SchemaType)
+        if (!readBack) {
+          problems.push(`卡片 ${entityId} 迁移后读不回来，旧文件保留`)
+          continue
+        }
+        // 正文没变、类型也没变时，`writeCard` 写的是同一个路径 —— 这时**不要**删它。
+        if (written.data.path !== file) await unlinkIfExists(file)
+      }
+      try { await rmdir(legacyDir) } catch { /* 还有别的东西在里面 */ }
+    }
+    if (problems.length > 0) this.migrationProblems.push(...problems)
+  }
   private async loadVectorIndex(): Promise<LoadedVectorIndex | null> {
     if (this.vectorIndex) return this.vectorIndex
     try {
@@ -1228,6 +2472,10 @@ export class KnowledgeRuntime {
       const graph = JSON.parse(await readFile(this.safePath('03_compiled', 'knowledge_graph.json'), 'utf8'))
       if (graph && Array.isArray(graph.nodes) && Array.isArray(graph.edges)) this.graph = graph as typeof this.graph
     } catch { /* the first build has not happened yet */ }
+    try {
+      const diagnosis = JSON.parse(await readFile(this.safePath('03_compiled', DIAGNOSIS_GRAPH), 'utf8'))
+      if (diagnosis && Array.isArray(diagnosis.nodes) && Array.isArray(diagnosis.edges)) this.diagnosisGraph = diagnosis as typeof this.diagnosisGraph
+    } catch { /* 归因图还没编过（这个库没做过排查），或者旧版本没有这个产物 */ }
   }
 
   private safePath(...parts: string[]): string {
@@ -1270,9 +2518,9 @@ export class KnowledgeRuntime {
         only?: string; incremental?: boolean; skipped?: boolean
         cardsReused?: number; cardsRecompiled?: number; cardsAdded?: number; cardsRemoved?: number
         notesReused?: number; notesRecompiled?: number
-        // Pass 0 的计数：面板据此显示「这一轮抽了几个候选、建了几张卡」。
+        // Pass 0 的计数：面板据此显示「这一轮抽了几个候选、新建/更新了几张卡片」。
         candidatesExtracted?: number; candidatesRejected?: number
-        cardsCreated?: number; cardsMerged?: number
+        cardsCreated?: number; cardsUpdated?: number
         relationsExtracted?: number; relationsDropped?: number
         sourcesExtracted?: number; sourcesSkipped?: number
       }
@@ -1293,7 +2541,7 @@ export class KnowledgeRuntime {
       memoryFiles: await fileCount(this.memoryDir),
       /**
        * 按**段名**取，不按位置取。这里原先是 `counts[1]`，而它之所以曾经是对的，
-       * 只是因为 `LAYOUT[1]` 恰好是 `01_source_truth` —— 0030 撤掉 `00_schema`
+       * 只是因为 `LAYOUT[1]` 恰好是 `01_source_raw` —— 0030 撤掉 `00_schema`
        * 之后同一条表达式就静默变成了「wiki 卡片数」，界面上的来源数直接归零。
        * 布局的索引是实现的偶然，段名才是契约。
        */
@@ -1303,6 +2551,12 @@ export class KnowledgeRuntime {
       notes: this.units.length,
       graphNodes: this.graph.nodes.length,
       graphEdges: this.graph.edges.length,
+      /**
+       * 一次性迁移里没有静默处理掉的事（来源分类改名冲突、卡片改名迁移失败）。
+       *
+       * 它必须能被界面读到：迁移失败而没人知道，等价于数据已经丢了。
+       */
+      migrationProblems: this.migrationProblems,
       buildVersion: Number(buildManifest.version ?? 0),
       builtAt: buildManifest.builtAt,
       trackedCards: Object.keys(buildManifest.cardHashes ?? {}).length,
@@ -1326,7 +2580,133 @@ export class KnowledgeRuntime {
     }
   }
 
-  async addSource(input: { sourceType: SourceType; title?: string; content: string; externalId?: string; metadata?: Record<string, unknown>; sourceId?: string; lineage?: LineageContext }): Promise<Envelope<{ sourceId: string; path: string; lineage?: LineageContext }>> {
+  /**
+   * 批量写入来源 + **一次**编译（0045）。
+   *
+   * ## 为什么值得单独一个方法，而不是让调用方循环 `add_source` + `rebuild_knowledge`
+   *
+   * 三件事只有放在一起才对：
+   *
+   * 1. **一次审批。** Agent 侧写入都要过 DSH 的审批闸门（`tools/pre-execute` 里那几个
+   *    写工具）。十份文档 = 十次弹窗，而人真正要同意的是「把这十份导进去」这一件事。
+   * 2. **编译只跑一次。** 每写一份就 `rebuild` 一次，第 10 份文档要付 10 次抽取的钱，
+   *    而前 9 次的结果当场就被下一次覆盖。
+   * 3. **失败要局部化。** 第 7 份文档格式不对，不该让前 6 份白写、后 3 份不写。
+   *    所以逐条记录成败，最后一次性汇报 —— 成功的已经在库里，失败的带着原因回来，
+   *    调用方可以只重试那几条。
+   *
+   * ## 为什么全部失败时返回 failure 而不是带 warning 的 success
+   *
+   * 「10 份全没进去」与「10 份都进去了，其中 1 份顺带报了个警告」是两件完全不同的事，
+   * 用同一种信封表达，模型会把前一种当成后一种继续往下走。所以一份都没写成时如实失败，
+   * 每条的原因仍然在 `sources[].message` 里。
+   */
+  async importSources(input: {
+    sources: Array<{ sourceType: SourceType; title?: string; content: string; externalId?: string; metadata?: Record<string, unknown>; allowDuplicateTitle?: boolean }>
+    /** 默认编译（`only: 'wiki'`）。关掉它就只做写入，留给调用方自己决定何时编译。 */
+    compile?: boolean
+    lineage?: LineageContext
+  }): Promise<Envelope<ImportSourcesResult>> {
+    const empty: ImportSourcesResult = { written: [], failed: [], attempted: 0, compile: null }
+    const items = Array.isArray(input.sources) ? input.sources : []
+    if (items.length === 0) return failure(empty, 'SOURCES_REQUIRED', 'sources 不能为空：至少要给一份来源', true)
+    /**
+     * 上限只防「一次调用把整台机器按住」：编译是逐份来源串行抽实体的，50 份已经要跑很久。
+     * 它**不是**产品配额 —— 超过就分批调，每批各自编译。
+     */
+    if (items.length > MAX_IMPORT_SOURCES) {
+      return failure(empty, 'IMPORT_TOO_MANY', `一次最多导入 ${MAX_IMPORT_SOURCES} 份来源，收到 ${items.length} 份；请分批调用`, true)
+    }
+
+    const written: ImportedSourceReport[] = []
+    const failed: ImportFailure[] = []
+    const warnings: string[] = []
+    for (const [index, item] of items.entries()) {
+      const title = item?.title?.trim() || undefined
+      const result = await this.addSource({
+        sourceType: item?.sourceType,
+        ...(title ? { title } : {}),
+        content: item?.content,
+        ...(item?.externalId ? { externalId: item.externalId } : {}),
+        ...(item?.metadata ? { metadata: item.metadata } : {}),
+        ...(item?.allowDuplicateTitle === true ? { allowDuplicateTitle: true } : {}),
+        ...(input.lineage ? { lineage: input.lineage } : {}),
+      })
+      if (result.ok === false) {
+        const message = result.error?.message ?? '写入失败'
+        failed.push({ index, ...(title ? { title } : {}), code: result.error?.code ?? 'SOURCE_WRITE_FAILED', message })
+        // 逐条失败也要出现在 warnings 里：`ImportSourcesResult.failed` 是结构化账本，
+        // 而 warnings 是不管谁在读都必须看见的那一句。
+        warnings.push(`第 ${index + 1} 份来源${title ? `「${title}」` : ''}没有写入：${message}`)
+        continue
+      }
+      written.push({
+        index,
+        sourceId: result.data.sourceId,
+        ...(title ? { title } : {}),
+        path: result.data.path,
+        bytes: typeof item?.content === 'string' ? item.content.length : 0,
+      })
+    }
+
+    if (written.length === 0) {
+      return failure({ ...empty, failed, attempted: items.length }, 'IMPORT_ALL_FAILED', `${items.length} 份来源全部写入失败，没有任何东西进入知识库`, true,
+        failed[0] ? `第一份的原因：${failed[0].message}` : undefined)
+    }
+
+    /**
+     * 编译。**只要有一份写成就编**：成功的那几份已经是库里的知识，
+     * 「因为同批里有一份失败就不编」等于把已经进来的知识又挡在门外一次。
+     */
+    let compile: ImportCompileReport | null = null
+    if (input.compile !== false) {
+      const rebuilt = await this.rebuild('wiki', input.lineage)
+      if (rebuilt.ok === false) {
+        warnings.push(`来源已写入，但编译失败：${rebuilt.error?.message ?? '未知原因'}`)
+      } else {
+        const data = rebuilt.data
+        compile = {
+          cardsCreated: data.cardsCreated,
+          cardsUpdated: data.cardsUpdated,
+          cardsReused: data.cardsReused,
+          notesReused: data.notesReused,
+          notesRecompiled: data.notesRecompiled,
+          sourcesExtracted: data.sourcesExtracted,
+          sourcesSkipped: data.sourcesSkipped,
+          cardsRemoved: data.cardsRemoved,
+          embedding: data.embedding,
+          version: data.version,
+        }
+        warnings.push(...(rebuilt.warnings ?? []))
+      }
+    }
+
+    return success({ written, failed, attempted: items.length, compile }, warnings)
+  }
+
+  /**
+   * 写入一份 SourceRaw。
+   *
+   * `provenance` 是 OKF v0.2 那一组（`description` / `resource` / `generated` /
+   * `sources[]` / `tags`），它们**写成真正的顶层键**而不是塞进 `metadata` 那个 JSON
+   * 字符串里（0048）：元数据要能被人读、被 `grep` 到、被外部工具按公开规范读走。
+   * `metadata` 只留类型专属的扩展键。
+   */
+  async addSource(input: {
+    sourceType: SourceType
+    title?: string
+    content: string
+    externalId?: string
+    metadata?: Record<string, unknown>
+    sourceId?: string
+    lineage?: LineageContext
+    provenance?: SourceProvenance
+    /**
+     * 允许与已有的来源同标题（0051）。默认 `false`：重名是错误，拒收并要求改标题。
+     * 传 `true` 时落成 `<标题>-<内容哈希前 6 位>.md`，并回一条 warning。
+     */
+    allowDuplicateTitle?: boolean
+  }): Promise<Envelope<{ sourceId: string; path: string; lineage?: LineageContext }>> {
     if (!this.config.allowSourceTruth) return failure({ sourceId: '', path: '' }, 'SOURCE_TRUTH_DISABLED', '当前配置禁止写入 SourceTruth', false)
     // 分类闸门走注册表（0013），不再是硬编码枚举：自定义分类建完即可用。
     const gate = this.sourceTypeGate(input.sourceType)
@@ -1347,7 +2727,39 @@ export class KnowledgeRuntime {
     await this.ensureLayout()
     const sourceId = input.sourceId?.trim() || `${input.sourceType}:${hash(input.externalId ?? input.content)}`
     if (!SAFE_ID.test(sourceId)) return failure({ sourceId: '', path: '' }, 'SOURCE_ID_INVALID', 'source_id 含有非法字符', false)
-    const path = this.sourcePath(sourceId, input.sourceType)
+    const title = input.title?.trim() || sourceId
+    /**
+     * 重名（0051）：**默认拒收**。
+     *
+     * 文件名就是标题，所以「两份来源同一个标题」不再是看不见的事 —— 它们会争同一个
+     * 路径。判据落在**目标路径**上而不是标题字符串上：标题里被换掉的非法字符
+     * （`A/B` 与 `A-B`）也会撞路径，按字符串比会漏。
+     *
+     * 三条出路，覆盖三种真实情形：
+     * 1. 同一个 `sourceId`（同一份东西重复导入）→ 目标是它自己现在的位置，不冲突；
+     * 2. 另一个 `sourceId` 占着这个路径 → **拒收**，报错里带上「被谁占着」，让人改标题；
+     * 3. 调用方明确要留两份同标题材料 → 传 `allowDuplicateTitle`，落成
+     *    `<标题>-<内容哈希前 6 位>.md`，并回一条 warning。
+     *
+     * 为什么不静默加后缀：那样人永远不知道库里有两份「复盘」—— 而「有两份」这件事本身
+     * 就是要人处理的信号。也不静默覆盖：那等于直接丢一份知识。
+     */
+    let path = this.sourcePath(sourceId, input.sourceType, title)
+    let duplicateNote: string | undefined
+    const owner = await this.sourceIdAtPath(path)
+    if (owner !== undefined && owner !== sourceId) {
+      if (input.allowDuplicateTitle !== true) {
+        return failure(
+          { sourceId: '', path },
+          'SOURCE_TITLE_DUPLICATED',
+          `标题「${title}」已被来源 ${owner} 占用（它写在这个路径上），改一个标题再来`,
+          true,
+          '换一个有区分度的标题（例如带上日期或版本），或显式传 allow_duplicate_title: true 让两份并存。',
+        )
+      }
+      path = this.safePath(SOURCE_TRUTH, input.sourceType, `${sourceFileBase(title, sourceId)}-${hash(sourceId).slice(0, 6)}.md`)
+      duplicateNote = `标题「${title}」与来源 ${owner} 重复，已按 allow_duplicate_title 落成 ${basename(path)}；建议改成有区分度的标题。`
+    }
     /**
      * 这一份文档**可能已经以另一个分类存在**。0030 起分类是目录名，所以
      * 「改一个来源的分类」不再是原地覆盖，而是换目录 —— 必须先解析它现在落在哪，
@@ -1372,17 +2784,46 @@ export class KnowledgeRuntime {
         await this.snapshotSource(sourceId, previousRaw, previous.content)
       }
     }
-    const record: SourceRaw = { sourceId, sourceType: input.sourceType, title: input.title?.trim() || sourceId, content: input.content, ...(input.externalId ? { externalId: input.externalId } : {}), metadata: input.metadata ?? {}, ...(input.lineage ? { lineage: input.lineage } : {}), createdAt, updatedAt: new Date().toISOString() }
-    await writeTextAtomic(path, markdown({ source_id: sourceId, source_type: input.sourceType, title: record.title, created_at: record.createdAt, updated_at: record.updatedAt, external_id: input.externalId ?? '', metadata: record.metadata, ...(record.lineage ? { lineage: record.lineage } : {}) }, record.content))
+    const record: SourceRaw = { sourceId, sourceType: input.sourceType, title, content: input.content, ...(input.externalId ? { externalId: input.externalId } : {}), metadata: input.metadata ?? {}, ...(input.lineage ? { lineage: input.lineage } : {}), createdAt, updatedAt: new Date().toISOString() }
+    const frontMatter = sourceFrontMatter(record, input.provenance)
+    await writeTextAtomic(path, markdown(frontMatter, record.content))
+    /**
+     * 分类声明的必填元数据缺了就**如实报出来**，不拒收（0048）。
+     *
+     * 与「缺必填小节的卡片照常入库」同一条纪律：元数据缺失是**信息不全**，不是
+     * 「这份知识不存在」。拒收的代价是知识直接丢了，而报出来的代价只是界面上多一句
+     * 提示 —— 后者可以补，前者补不回来。
+     */
+    const declared = this.sourceTypes().find(def => def.id === record.sourceType)?.metadataFields
+    const missing = missingMetadataFields(declared, frontMatter)
     // 换了分类的那一次：新文件已经落好，旧目录里那份才删 —— 顺序反过来的话，写入
     // 失败就同时丢了旧的那一份。
     if (previousPath !== undefined && previousPath !== path) {
       try { await unlink(previousPath) } catch { /* already moved or removed */ }
     }
-    this.sourceIndex?.set(slug(sourceId), path)
+    /**
+     * 索引与归属表都要跟着**新路径**走（0051）。
+     *
+     * 归属表（`path → sourceId`）是重名判定的依据，漏更新会留下一个幽灵归属：改了标题
+     * 之后，旧路径上明明没有文件，另一个来源想用那个标题却会被判成「重名」而拒收。
+     */
+    if (this.sourceIndex) {
+      if (previousPath !== undefined && previousPath !== path) {
+        this.sourceIndex.delete(previousPath)
+        this.sourcePathOwner?.delete(previousPath)
+      }
+      this.sourceIndex.set(slug(sourceId), path)
+      this.sourcePathOwner?.set(path, sourceId)
+    }
     // 证据片段取自 SourceRaw 正文，写入后那份缓存必须失效（否则上下文会引用旧原文）。
     this.sourceCorpusCache = undefined
-    return success({ sourceId, path, ...(record.lineage ? { lineage: record.lineage } : {}) })
+    return success(
+      { sourceId, path, ...(record.lineage ? { lineage: record.lineage } : {}) },
+      [
+        ...(duplicateNote ? [duplicateNote] : []),
+        ...missing.map(field => `来源缺少「${field.label}」（${field.key}）：分类「${record.sourceType}」声明它是必填的。`),
+      ],
+    )
   }
 
   /** Directory holding one document's version snapshots. */
@@ -1408,14 +2849,30 @@ export class KnowledgeRuntime {
 
   async loadSources(): Promise<SourceRaw[]> {
     const result: SourceRaw[] = []
+    /**
+     * 索引在**同一次遍历**里建起来（0051）。
+     *
+     * 文件名从 `source_id` 改成标题之后，「按 id 找文件」不再能从文件名推出来 ——
+     * 权威身份在 front matter 里。与其再扫一遍磁盘、再读一遍文件，不如在唯一一次
+     * 遍历里同时建两张表：`sourceId → path`（`sourcePathOf` 用）与 `path → sourceId`
+     * （`addSource` 判断目标路径被谁占着）。
+     */
+    const byId = new Map<string, string>()
+    const byPath = new Map<string, string>()
     for (const path of await filesUnder(this.directory(SOURCE_TRUTH))) {
       const parsed = parseMarkdown(await readFile(path, 'utf8'))
       const sourceId = String(parsed.frontmatter.source_id ?? basename(path, '.md'))
-      const sourceType = String(parsed.frontmatter.source_type ?? 'document') as SourceType
+      byId.set(slug(sourceId), path)
+      // 文件名也可能是旧布局的 id（迁移中间态）：两个键都登记，谁在都不算丢。
+      byId.set(basename(path, '.md'), path)
+      byPath.set(path, sourceId)
+      const sourceType = (sourceTypeOf(parsed.frontmatter) || 'document') as SourceType
       // 0013：未知分类**不再静默丢弃**。分类只是元数据，内容仍然可召回；
       // 丢掉文档才是真正的数据损失。未知分类在列表里以「未知分类」呈现。
       result.push({ sourceId, sourceType, title: String(parsed.frontmatter.title ?? sourceId), content: parsed.content, externalId: typeof parsed.frontmatter.external_id === 'string' && parsed.frontmatter.external_id ? parsed.frontmatter.external_id : undefined, metadata: typeof parsed.frontmatter.metadata === 'object' && parsed.frontmatter.metadata ? parsed.frontmatter.metadata as Record<string, unknown> : {}, ...(parseLineage(parsed.frontmatter.lineage) ? { lineage: parseLineage(parsed.frontmatter.lineage) } : {}), createdAt: String(parsed.frontmatter.created_at ?? ''), updatedAt: String(parsed.frontmatter.updated_at ?? '') })
     }
+    this.sourceIndex = byId
+    this.sourcePathOwner = byPath
     return result
   }
 
@@ -1428,17 +2885,26 @@ export class KnowledgeRuntime {
    * （`addSource` 的 `sourceTypeGate`），所以它一定匹配 `SOURCE_TYPE_ID_PATTERN`，
    * 不会引入路径穿越。
    */
-  private sourcePath(sourceId: string, sourceType: string): string {
-    return this.safePath(SOURCE_TRUTH, sourceType, `${slug(sourceId)}.md`)
+  private sourcePath(sourceId: string, sourceType: string, title: string): string {
+    return this.safePath(SOURCE_TRUTH, sourceType, `${sourceFileBase(title, sourceId)}.md`)
   }
 
-  /** 递归扫 SourceRaw 段，建 `docSlug → path` 索引；两种布局都覆盖。 */
+  /**
+   * `docSlug → path` 索引；两种布局都覆盖。
+   *
+   * 0051 起它**由 `loadSources` 建**（那一次遍历本来就要读每个文件的 front matter，
+   * 而文件名不再是身份，只能从 front matter 里拿）。这里只是把「还没建」补上。
+   */
   private async sourceIndexMap(): Promise<Map<string, string>> {
     if (this.sourceIndex) return this.sourceIndex
-    const index = new Map<string, string>()
-    for (const path of await filesUnder(this.directory(SOURCE_TRUTH))) index.set(basename(path, '.md'), path)
-    this.sourceIndex = index
-    return index
+    await this.loadSources()
+    return this.sourceIndex ?? new Map()
+  }
+
+  /** 这个路径现在被哪一份来源占着（0051：重名判定的依据）。 */
+  private async sourceIdAtPath(path: string): Promise<string | undefined> {
+    if (!this.sourcePathOwner) await this.loadSources()
+    return this.sourcePathOwner?.get(path)
   }
 
   /** 已知文档 id 的落盘位置；不存在时 `undefined`（调用方各自决定怎么报错）。 */
@@ -1449,13 +2915,12 @@ export class KnowledgeRuntime {
   /**
    * Assets a document really has on disk.
    *
-   * Preferred source of truth is `metadata.assets` (knowledge-root-relative
-   * paths written by `convert/ingest.ts`). Documents written by hand fall back
-   * to parsing local markdown image links. A link is resolved **knowledge-root
-   * first, then relative to the document's own directory**: the convert ingest
-   * seam re-bases assets to `_assets/<bucket>/<name>` (root-relative), while
-   * hand-written docs typically use a sibling path. Only existing files are
-   * returned, so `assetCount` is never an over-count.
+   * Preferred source of truth is `metadata.assets` (paths written by
+   * `convert/ingest.ts`). Documents written by hand fall back to parsing local
+   * markdown image links. Both go through {@link assetRefCandidates}, so a
+   * document's asset list and a card's `imagePaths` answer the same question the
+   * same way. Only existing files are returned, so `assetCount` is never an
+   * over-count.
    */
   private async assetsOf(path: string, content: string, metadata: Record<string, unknown>): Promise<KnowledgeAssetRef[]> {
     const refs = new Set<string>()
@@ -1466,7 +2931,7 @@ export class KnowledgeRuntime {
     const assets: KnowledgeAssetRef[] = []
     const seen = new Set<string>()
     for (const ref of refs) {
-      const candidates = isAbsolute(ref) ? [resolve(ref)] : [resolve(root, ref), resolve(dirname(path), ref)]
+      const candidates = assetRefCandidates(ref, dirname(path), root)
       for (const absolute of candidates) {
         if (!insideRoot(absolute)) continue
         let details
@@ -1475,21 +2940,64 @@ export class KnowledgeRuntime {
         const rel = relative(root, absolute).split(sep).join('/')
         if (seen.has(rel)) break
         seen.add(rel)
-        const encoded = rel.split('/').map(segment => encodeURIComponent(segment)).join('/')
-        assets.push({ rel, bytes: details.size, url: `/knowledge/assets/${encodeURIComponent(this.baseId)}/${encoded}` })
+        assets.push({ rel, bytes: details.size, url: this.assetUrlOf(rel) })
         break
       }
     }
     return assets.sort((left, right) => left.rel.localeCompare(right.rel))
   }
 
-  /** Parse one on-disk SourceRaw file into the detail projection. */
-  private async readDocumentFile(path: string): Promise<KnowledgeDocumentDetail | undefined> {
+  /**
+   * 图片素材的浏览器地址。面板与整页都用它加载图，所以只能有一个拼法。
+   */
+  private assetUrlOf(rel: string): string {
+    const encoded = rel.split('/').map(segment => encodeURIComponent(segment)).join('/')
+    return `/knowledge/assets/${encodeURIComponent(this.baseId)}/${encoded}`
+  }
+
+  /**
+   * 一张 wiki 卡片的图片素材（0047）。
+   *
+   * 卡片详情原先只回 `imagePaths` —— **磁盘绝对路径**。客户端拿它加载不了图（浏览器
+   * 只认 URL），所以预览抽屉里卡片的图一直不显示；而 SourceRaw 那边早就有 `assets`
+   * （`rel` + `url` + `bytes`）。这里把同一种东西补齐，两个预览走同一条路。
+   *
+   * 只认知识库根目录以内的文件：卡片正文里可能留着别的绝对路径（人手工写的），
+   * 那种不该变成一个可下载的 URL。
+   */
+  async assetsOfCard(card: KnowledgeCard): Promise<KnowledgeAssetRef[]> {
+    const root = this.rootDir
+    const insideRoot = (value: string): boolean => value === root || value.startsWith(root.endsWith(sep) ? root : `${root}${sep}`)
+    const assets: KnowledgeAssetRef[] = []
+    const seen = new Set<string>()
+    for (const absolute of card.imagePaths ?? []) {
+      if (!isAbsolute(absolute) || !insideRoot(absolute)) continue
+      let details
+      try { details = await stat(absolute) } catch { continue }
+      if (!details.isFile()) continue
+      const rel = relative(root, absolute).split(sep).join('/')
+      if (seen.has(rel)) continue
+      seen.add(rel)
+      assets.push({ rel, bytes: details.size, url: this.assetUrlOf(rel) })
+    }
+    return assets.sort((left, right) => left.rel.localeCompare(right.rel))
+  }
+
+  /**
+   * Parse one on-disk SourceRaw file into the detail projection.
+   *
+   * `previewChars` 给了就把正文截到那么长，并把**总长度**如实放进 `contentChars`
+   * （见 `SOURCE_PREVIEW_CHARS` 的理由）。不给就是不截断 —— 那是「我确实要全文」的
+   * 调用方，目前只有 `readDocumentBody()` 之外的内部路径会这么用。
+   */
+  private async readDocumentFile(path: string, previewChars?: number): Promise<KnowledgeDocumentDetail | undefined> {
     let raw: string
     try { raw = await readFile(path, 'utf8') } catch { return undefined }
     const parsed = parseMarkdown(raw)
+    const contentChars = parsed.content.length
+    const content = previewChars !== undefined && previewChars < contentChars ? parsed.content.slice(0, previewChars) : parsed.content
     const sourceId = String(parsed.frontmatter.source_id ?? basename(path, '.md'))
-    const sourceType = String(parsed.frontmatter.source_type ?? 'document')
+    const sourceType = sourceTypeOf(parsed.frontmatter) || 'document'
     // 未知分类照样投影出来（0013）；前端按 sourceTypeKnown 渲染「未知分类」徽标。
     const sourceTypeKnown = this.sourceTypes().some(def => def.id === sourceType)
     const metadata = plainRecord(parsed.frontmatter.metadata)
@@ -1523,7 +3031,9 @@ export class KnowledgeRuntime {
       versionCount: (await this.versionIds(sourceId)).length + 1,
       relativePath: relative(this.rootDir, path).split(sep).join('/'),
       ext,
-      content: parsed.content,
+      content,
+      contentChars,
+      contentTruncated: content.length < contentChars,
       frontmatter: parsed.frontmatter,
       assets,
       ...(lineage ? { lineage: lineage as Record<string, string> } : {}),
@@ -1548,9 +3058,27 @@ export class KnowledgeRuntime {
   }
 
   /** 文档详情：正文、frontmatter、资产与 lineage。 */
-  async readDocument(docId: string): Promise<KnowledgeDocumentDetail | undefined> {
+  /**
+   * 一份文档的详情投影，**正文默认按 `SOURCE_PREVIEW_CHARS` 封顶**。
+   *
+   * 这是明细接口（抽屉里的预览）读的那一份，所以默认就是「够预览」而不是「全文」：
+   * 全文由 `readDocumentBody()` 提供服务，而它只服务独立整页的分页读取。
+   */
+  async readDocument(docId: string, previewChars: number = SOURCE_PREVIEW_CHARS): Promise<KnowledgeDocumentDetail | undefined> {
     const path = await this.sourcePathOf(docId)
-    return path ? this.readDocumentFile(path) : undefined
+    return path ? this.readDocumentFile(path, previewChars) : undefined
+  }
+
+  /**
+   * 一份文档的**完整正文**（不含 frontmatter），给独立整页分页取用。
+   *
+   * 每次调用都重读一遍盘：独立整页是「用户滚到哪儿取哪一页」，一次请求一段文本，
+   * 谁都不该拿到整份文档 —— 这正是抽屉那一版的问题。缓存留到真的量出来是瓶颈再加。
+   */
+  async readDocumentBody(docId: string): Promise<string | undefined> {
+    const path = await this.sourcePathOf(docId)
+    if (path === undefined) return undefined
+    try { return parseMarkdown(await readFile(path, 'utf8')).content } catch { return undefined }
   }
 
   /**
@@ -1605,7 +3133,7 @@ export class KnowledgeRuntime {
   async revertDocument(docId: string, versionId: string): Promise<Envelope<KnowledgeDocumentDetail>> {
     const path = await this.sourcePathOf(docId)
     if (path === undefined) return failure(emptyDocumentDetail(docId), 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true)
-    const head = await this.readDocumentFile(path)
+    const head = await this.readDocumentFile(path, SOURCE_PREVIEW_CHARS)
     if (!head) return failure(emptyDocumentDetail(docId), 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true)
     const target = typeof versionId === 'string' ? versionId.trim() : ''
     if (!target) return failure(head, 'VERSION_ID_REQUIRED', 'versionId 不能为空', false, '用 list_versions / GET /knowledge/documents/:docId/versions 先取版本列表。')
@@ -1614,7 +3142,7 @@ export class KnowledgeRuntime {
     if (!existsSync(snapshotPath)) return failure(head, 'VERSION_NOT_FOUND', `版本不存在: ${target}`, true)
     const parsed = parseMarkdown(await readFile(snapshotPath, 'utf8'))
     const restored = await this.addSource({
-      sourceType: (String(parsed.frontmatter.source_type ?? 'document')) as SourceType,
+      sourceType: (sourceTypeOf(parsed.frontmatter) || 'document') as SourceType,
       title: typeof parsed.frontmatter.title === 'string' ? parsed.frontmatter.title : undefined,
       content: parsed.content,
       externalId: typeof parsed.frontmatter.external_id === 'string' && parsed.frontmatter.external_id ? parsed.frontmatter.external_id : undefined,
@@ -1623,7 +3151,13 @@ export class KnowledgeRuntime {
       lineage: parseLineage(parsed.frontmatter.lineage),
     })
     if (!restored.ok) return failure(head, restored.error?.code ?? 'REVERT_FAILED', restored.error?.message ?? '回滚写入失败', restored.error?.retryable ?? false, restored.error?.suggestion)
-    const document = await this.readDocumentFile(path)
+    /**
+     * 读的是**回滚写完之后**的路径，不是开头那个。
+     *
+     * 0051 起文件名跟着标题走：回滚到一版标题不同的历史，文件会被改名 —— 开头取到的
+     * 路径当场过期，再按它读就是「回滚后文档不可读」，而文件其实好好的。
+     */
+    const document = await this.readDocumentFile(restored.data.path, SOURCE_PREVIEW_CHARS)
     if (!document) return failure(head, 'DOCUMENT_NOT_FOUND', `回滚后文档不可读: ${docId}`, true)
     await this.audit('source_truth.revert', { docId, versionId: target })
     return success(document)
@@ -1645,7 +3179,24 @@ export class KnowledgeRuntime {
    * 负责人。它属于 0021 §6.4 的卡片信封（智能归因的五类卡片里 `check.owner` 是必填 ——
    * 「这一步该找谁」和成本、判定阈值一样是执行信息）；其余 entity_type 不使用它。
    */
-  owner?: string; metadata?: Record<string, unknown>; lineage?: LineageContext; provenance?: LineageRef[] }): Promise<Envelope<{ entityId: string; path: string; lineage?: LineageContext }>> {
+  owner?: string; metadata?: Record<string, unknown>; lineage?: LineageContext; provenance?: LineageRef[]; /**
+   * 额外的校验问题（0049）。编译收尾段算出「正文里的 wiki 链接指向不存在的卡片」，
+   * 它是 `reference` 那一层的问题 —— 与 format / semantic 一起写进 `metadata.schema_issues`，
+   * 卡片抽屉上就会出现一枚「引用」徽标。收尾段不能自己拼 metadata：那样会把写入时
+   * 重算的 format / semantic 覆盖掉。
+   */
+  extraIssues?: CardSchemaIssue[]; /**
+   * 人工备注（0044）。**不传 = 保留磁盘上已有的那些**，不是清空 —— 编译路径不传它，
+   * 所以「重新编译一次不会抹掉备注」是结构上的保证，而不是靠每个调用方记得带上。
+   */
+  annotations?: CardAnnotation[]; /** review 结论与评分（0044）。同样：不传 = 保留已有的。 */ review?: CardReview; /**
+   * 谁在写这张卡片。
+   *
+   * `'manual'` 是**唯一会被正文不可变规则拦下**的来源：已有卡片的正文字节不同 →
+   * `WIKI_CARD_IMMUTABLE`。编译（`'compile'`）追加正文、review 与备注写信封字段，
+   * 两者都不受这条规则约束 —— 把它们也拦掉，卡片就再也不会长了。
+   */
+  origin?: 'compile' | 'review' | 'manual' | 'internal' }): Promise<Envelope<{ entityId: string; path: string; lineage?: LineageContext }>> {
     if (!SAFE_ID.test(input.entityId)) return failure({ entityId: input.entityId, path: '' }, 'ENTITY_ID_INVALID', 'entity_id 必须是稳定且安全的标识符', false)
     if (!input.title?.trim() || !input.content?.trim()) return failure({ entityId: input.entityId, path: '' }, 'CARD_CONTENT_REQUIRED', 'title 和 content 不能为空', true)
     if (!Array.isArray(input.sourceRefs) || input.sourceRefs.length === 0) return failure({ entityId: input.entityId, path: '' }, 'SOURCE_REFS_REQUIRED', '知识卡片必须引用 SourceTruth', false)
@@ -1654,7 +3205,18 @@ export class KnowledgeRuntime {
     if (missingRefs.length > 0) return failure({ entityId: input.entityId, path: '' }, 'SOURCE_REF_NOT_FOUND', `source_refs 引用不存在: ${missingRefs.join(', ')}`, false, '先调用 add_source 写入对应的 SourceTruth')
     const status = input.status ?? 'unreviewed'
     if (!STATUS.includes(status)) return failure({ entityId: input.entityId, path: '' }, 'STATUS_INVALID', 'status 不合法', false)
-    // 0024：类型闸门 + 三层校验（format / reference / semantic）。
+    /**
+     * 0044：缺信息的卡片**照常入库**。
+     *
+     * 0040 时期这里有两道拒绝：类型不在注册表里直接拒、三层校验不通过时 `strict` 模式拒。
+     * 两条都撤掉了 —— 编译的价值在于「记下来，后面有涉及到的文档再慢慢补」，而拒绝
+     * 恰好把这个机会丢掉了。缺什么由 `schema_issues` 如实标出，人在 review 时补。
+     *
+     * 唯一保留的拦截是**未知类型**：没有类型定义就没有小节骨架，连「缺什么」都说不出来。
+     * 编译侧在调用这里之前已经把未登记的类型**退回兜底类型**（`compileSource`），
+     * 所以这条路只在别的调用方拿着一个没登记的类型直接写盘时才会走到 —— 那时拒绝是对的，
+     * 而提示会给出可用类型的清单。
+     */
     const gate = this.cardSchemaGate({
       entityType: input.entityType, title: input.title.trim(), content: input.content,
       sourceRefs: input.sourceRefs, metadata: input.metadata ?? {}, ...(input.owner ? { owner: input.owner } : {}), ...(input.summary ? { summary: input.summary } : {}),
@@ -1662,15 +3224,6 @@ export class KnowledgeRuntime {
     if ('error' in gate) return failure({ entityId: input.entityId, path: '' }, gate.error.code, gate.error.message, gate.error.retryable, gate.error.suggestion)
     const { issues } = gate
     const warnings = issues.map(issue => `${issue.level}: ${issue.message}`)
-    if (issues.length > 0 && this.wikiSchema().mode === 'strict') {
-      return failure(
-        { entityId: input.entityId, path: '' },
-        'CARD_SCHEMA_INVALID',
-        `卡片不符合「${gate.type.label}」的 schema：${issues.map(issue => issue.message).join('；')}`,
-        false,
-        '补齐必填小节 / 字段后重试；或在「知识库设置 → Wiki 类型」里把生效方式改为 report（只标记不拦截）。',
-      )
-    }
     await this.ensureLayout()
     const path = this.safePath(WIKI, input.entityType, `${slug(input.entityId)}.md`)
     await mkdir(dirname(path), { recursive: true })
@@ -1680,18 +3233,72 @@ export class KnowledgeRuntime {
     // 「审核一次 = 多一个版本」，版本列表会被状态流转灌满。
     let createdAt = updatedAt
     let previousRaw: string | undefined
+    let previousAnnotations: CardAnnotation[] | undefined
+    let previousReview: CardReview | undefined
     try { previousRaw = await readFile(path, 'utf8') } catch { /* 首次写入这张卡片 */ }
     if (previousRaw !== undefined) {
       const previous = parseMarkdown(previousRaw)
       createdAt = String(previous.frontmatter.created_at ?? createdAt)
+      previousAnnotations = parseAnnotations(previous.frontmatter.annotations)
+      previousReview = parseReview(previous.frontmatter.review)
       if (previous.content.trim() !== input.content.trim()) {
+        if (input.origin === 'manual') {
+          return failure(
+            { entityId: input.entityId, path },
+            'WIKI_CARD_IMMUTABLE',
+            `wiki 正文不可手工修改: ${input.entityId}`,
+            false,
+            '正文由编译产出（新文档会追加进来）。要指出问题请加备注：annotate_wiki_card 或面板上的「备注 / 异常点」。',
+          )
+        }
         await this.snapshotCard(input.entityType, input.entityId, previousRaw, previous.content)
       }
     }
     const provenance = [...(input.provenance ?? []), ...(input.lineage ? [{ ...input.lineage, role: 'created' as const, refType: 'knowledge_card', refId: input.entityId }] : [])]
-    // report 模式：把问题留在卡片上，界面据此显示"待补"，而不是静默通过。
-    const metadata = { ...(input.metadata ?? {}), ...(issues.length > 0 ? { schema_issues: issues } : {}) }
-    await writeTextAtomic(path, markdown({ entity_id: input.entityId, entity_type: input.entityType, title: input.title.trim(), status, summary: input.summary ?? '', ...(input.owner ? { owner: input.owner } : {}), source_refs: input.sourceRefs, created_at: createdAt, updated_at: updatedAt, metadata, ...(provenance.length > 0 ? { provenance } : {}) }, input.content))
+    /**
+     * report 模式：把问题留在卡片上，界面据此显示"待补"，而不是静默通过。
+     *
+     * `schema_issues` **一律由这里重算**（先摘掉入参里可能带着的旧值）。入参 metadata
+     * 常常是「从磁盘上读回来的那一份」，里面就有上一次的 `schema_issues` —— 只做覆盖
+     * 不摘旧值，一张补好了的卡片会一直挂着旧问题；而问题清空时那个键根本没被覆盖，
+     * 于是「补好了」这件事在界面上永远不生效。
+     */
+    const { schema_issues: _staleIssues, ...inputMetadata } = input.metadata ?? {}
+    void _staleIssues
+    const allIssues = [...issues, ...(input.extraIssues ?? [])]
+    const metadata = { ...inputMetadata, ...(allIssues.length > 0 ? { schema_issues: allIssues } : {}) }
+    // 备注与 review **默认继承磁盘上已有的**：不传不等于清空。见入参注释。
+    const annotations = input.annotations ?? previousAnnotations ?? []
+    const review = input.review ?? previousReview
+    await writeTextAtomic(path, markdown({
+      entity_id: input.entityId, entity_type: input.entityType, title: input.title.trim(), status, summary: input.summary ?? '',
+      ...(input.owner ? { owner: input.owner } : {}), source_refs: input.sourceRefs, created_at: createdAt, updated_at: updatedAt, metadata,
+      ...(annotations.length > 0 ? { annotations } : {}),
+      ...(review ? { review } : {}),
+      ...(provenance.length > 0 ? { provenance } : {}),
+    }, input.content))
+    /**
+     * 同步内存里的卡片清单。
+     *
+     * `this.cards` 是召回组装 `context[].wiki` 时读的那一份。写盘不同步它，会出现
+     * 「刚加的备注，在召回结果里看不到」—— 而人正是在召回结果里核对备注的。
+     *
+     * 重新 `loadCards()` 一遍是 O(整个 wiki)，而一次编译会连着写几十张卡；所以这里
+     * 就地替换那一条。缓存为空时什么都不做：那表示还没人读过卡片清单，下次读会拿到全量。
+     */
+    if (this.cards.length > 0) {
+      const next: KnowledgeCard = {
+        entityId: input.entityId, entityType: input.entityType, title: input.title.trim(), status,
+        ...(input.summary ? { summary: input.summary } : {}),
+        content: input.content, sourceRefs: input.sourceRefs, metadata, updatedAt,
+        ...(annotations.length > 0 ? { annotations } : {}),
+        ...(review ? { review } : {}),
+        ...(provenance.length > 0 ? { provenance } : {}),
+      }
+      const index = this.cards.findIndex(card => card.entityId === input.entityId && card.entityType === input.entityType)
+      if (index >= 0) this.cards[index] = next
+      else this.cards.push(next)
+    }
     return success({ entityId: input.entityId, path, ...(input.lineage ? { lineage: input.lineage } : {}) }, warnings)
   }
 
@@ -1804,7 +3411,21 @@ export class KnowledgeRuntime {
       // 0024：未知类型**不再静默丢弃**。类型只是元数据，丢掉卡片才是真正的数据损失；
       // 未知类型在界面上显示成「未登记类型」，由人决定是补登记还是改卡片。
       const refs = Array.isArray(parsed.frontmatter.source_refs) ? parsed.frontmatter.source_refs.map(String) : []
-      result.push({ entityId, entityType, title: String(parsed.frontmatter.title ?? entityId), status: STATUS.includes(String(parsed.frontmatter.status) as KnowledgeStatus) ? String(parsed.frontmatter.status) as KnowledgeStatus : 'draft', summary: typeof parsed.frontmatter.summary === 'string' ? parsed.frontmatter.summary : undefined, content: parsed.content, sourceRefs: refs, ...(parseProvenance(parsed.frontmatter.provenance) ? { provenance: parseProvenance(parsed.frontmatter.provenance) } : {}), metadata: typeof parsed.frontmatter.metadata === 'object' && parsed.frontmatter.metadata ? parsed.frontmatter.metadata as Record<string, unknown> : {}, updatedAt: String(parsed.frontmatter.updated_at ?? ''), imagePaths: markdownImagePaths(parsed.content, dirname(path)) })
+      const annotations = parseAnnotations(parsed.frontmatter.annotations)
+      const review = parseReview(parsed.frontmatter.review)
+      result.push({
+        entityId, entityType, title: String(parsed.frontmatter.title ?? entityId),
+        status: STATUS.includes(String(parsed.frontmatter.status) as KnowledgeStatus) ? String(parsed.frontmatter.status) as KnowledgeStatus : 'draft',
+        summary: typeof parsed.frontmatter.summary === 'string' ? parsed.frontmatter.summary : undefined,
+        content: parsed.content, sourceRefs: refs,
+        ...(typeof parsed.frontmatter.owner === 'string' && parsed.frontmatter.owner ? { owner: parsed.frontmatter.owner } : {}),
+        ...(parseProvenance(parsed.frontmatter.provenance) ? { provenance: parseProvenance(parsed.frontmatter.provenance) } : {}),
+        metadata: typeof parsed.frontmatter.metadata === 'object' && parsed.frontmatter.metadata ? parsed.frontmatter.metadata as Record<string, unknown> : {},
+        updatedAt: String(parsed.frontmatter.updated_at ?? ''),
+        imagePaths: markdownImagePaths(parsed.content, dirname(path), this.rootDir),
+        ...(annotations.length > 0 ? { annotations } : {}),
+        ...(review ? { review } : {}),
+      })
     }
     return result
   }
@@ -1841,9 +3462,34 @@ export class KnowledgeRuntime {
     if (card.status === 'problem') return []
     const notes: WikiNote[] = []
     const sourceTypesFor = card.sourceRefs.flatMap(ref => { const sourceType = sourceTypes.get(ref); return sourceType ? [sourceType] : [] })
-    for (const [index, chunk] of splitWikiNotes(card).entries()) {
+    /**
+     * 卡片文件所在目录：正文里的图片引用是相对它写的（`../../01_source_raw/_assets/…`），
+     * 和 `loadCards` 用的是同一个基准。
+     */
+    const cardDir = join(this.directory(WIKI), card.entityType)
+    // 0044：note 带上父级 wiki 的**有效评分**。它不进正文、不参与向量指纹，所以
+    // review 一下不会让整个语料重新编码，只会改变召回时的加权。
+    const reviewScore = effectiveReviewScore(card)
+    /**
+     * 召回单元里**不带相关块**（0049）。
+     *
+     * 相关块是导航，不是知识：它写的是别的卡片的名字。切进 wikiNotes 之后，一句
+     * 「毛利率怎么算」会同时命中真正讲毛利率的那张卡和所有**提到**它的卡 —— 而后者
+     * 除了一个标题什么都没有。文件里留着它（人 grep 得到、编辑器里点得开），
+     * 召回不吃它。
+     */
+    const recallBody = stripRelatedSection(card.content)
+    for (const [index, chunk] of splitWikiNotes({ ...card, content: recallBody }).entries()) {
       const baseId = `${card.entityType}:${card.entityId}`
       const unitId = index === 0 ? baseId : `${baseId}#${index}`
+      /**
+       * 图按**这一节自己**的引用算，不是把整张卡片的图摊给每一节（0046）。
+       *
+       * 多模态编码只吃每张 note 的**第一张**图，所以「这一节的第一张图」必须是这一节
+       * 自己的图 —— 否则「景气投资」那一节编码时会拿到「低估值」那节的图，而卡片
+       * 正文里图片的落点本来就是按节算好的。
+       */
+      const chunkImages = markdownImagePaths(chunk.content, cardDir, this.rootDir)
       notes.push({
         unitId,
         noteId: unitId,
@@ -1857,7 +3503,8 @@ export class KnowledgeRuntime {
         sourceTypes: sourceTypesFor,
         ...(card.provenance ? { provenance: card.provenance } : {}),
         status: card.status,
-        ...(card.imagePaths?.length ? { imagePaths: card.imagePaths } : {}),
+        ...(chunkImages.length > 0 ? { imagePaths: chunkImages } : {}),
+        reviewScore,
       })
     }
     return notes
@@ -1893,7 +3540,7 @@ export class KnowledgeRuntime {
    * sigmoid 之后的展示值，两者单调等价，排序不受影响。刻度换算集中在
    * `applyRerank`（纯函数，有测试），这里不再自己乘除。
    */
-  private async rerankNotes(query: string, hits: RecallHit[], threshold: number): Promise<{ hits: RecallHit[]; result: RerankResult; warning?: string }> {
+  private async rerankNotes(query: string, hits: RecallHit[], threshold: number): Promise<{ hits: RecallHit[]; result: RerankResult; scored?: Array<{ unitId: string; logit: number; rerankScore: number; kept: boolean }>; warning?: string }> {
     const provider = this.config.rerankProvider
     if (provider === 'none') return { hits, result: { status: 'skipped', provider, threshold } }
     if (hits.length < 2) return { hits, result: { status: 'skipped', provider, model: this.rerankModelPath, scored: hits.length, threshold } }
@@ -1912,6 +3559,7 @@ export class KnowledgeRuntime {
       const vocabSize = Number(response?.vocabSize)
       return {
         hits: outcome.kept,
+        scored: outcome.scored,
         result: {
           status: 'ready', provider, model: this.rerankModelPath,
           scored: outcome.kept.length, threshold, dropped: outcome.dropped,
@@ -1934,13 +3582,28 @@ export class KnowledgeRuntime {
    * Fingerprint of everything a wikiNote is compiled *from*.
    *
    * Deliberately excludes the fields that are cheap to refresh on a reused note
-   * (`provenance`, `imagePaths`, `metadata`) and includes the ones that change
-   * what the note says (`title`, `status`, `content`, `sourceRefs`). A card whose
-   * fingerprint is unchanged produces byte-identical notes, so reusing them is
-   * not a shortcut — it is the same answer without the churn.
+   * (`provenance`, `imagePaths`, `metadata`, `annotations`) and includes the ones
+   * that change what the note says (`title`, `status`, `content`, `sourceRefs`,
+   * `review`). A card whose fingerprint is unchanged produces byte-identical
+   * notes, so reusing them is not a shortcut — it is the same answer without the
+   * churn.
+   *
+   * 0044 把**有效评分**算进来，因为 note 上确实带着它。少了这一条会踩一个很隐蔽的坑：
+   * review 不改 `title` / `content` / `sourceRefs`，于是增量编译判定「语料没变」直接
+   * 跳过，`wiki_notes.json` 停在旧评分上 —— 表现就是「review 了，但召回排序一动不动」。
+   *
+   * 代价可控：评分变了会重编这条 note，但**不会重新编码**。向量指纹（`vectorInputs`）
+   * 只哈希 `unitId + text + sourceRefs + images`，而 review 一个字都不改这些 ——
+   * 所以重编拿到的还是同一条文本、同一个向量。
+   *
+   * `annotations` 刻意不进指纹：备注只出现在召回结果附带的 wiki 卡片上，不进 note。
+   * 把它算进来会让「加一条备注」触发一次没必要的版本升级。
    */
   private cardHashOf(card: KnowledgeCard): string {
-    return contentHashOf(JSON.stringify({ title: card.title, status: card.status, content: card.content, sourceRefs: card.sourceRefs }))
+    return contentHashOf(JSON.stringify({
+      title: card.title, status: card.status, content: card.content, sourceRefs: card.sourceRefs,
+      review: effectiveReviewScore(card),
+    }))
   }
 
   /** Previous `wiki_notes.json` (or the pre-0014 mirror), without touching `this.units`. */
@@ -1982,19 +3645,19 @@ export class KnowledgeRuntime {
   private emptyExtractionOutcome(extractionHashes: Record<string, string>): ExtractionOutcome {
     return {
       extractionHashes,
-      candidatesExtracted: 0, candidatesRejected: 0, cardsCreated: 0, cardsMerged: 0,
+      candidatesExtracted: 0, candidatesRejected: 0, cardsCreated: 0, cardsUpdated: 0,
       sourcesExtracted: 0, sourcesSkipped: 0, relations: [], relationsBySource: {}, warnings: [],
     }
   }
 
   /**
-   * Pass 0：对指纹变了的来源做候选抽取 + 归一，并把结果落成 wiki 卡片。
+   * Pass 0：对指纹变了的来源做候选抽取 + 归一，并把结果**直接落成 wiki 卡片**。
    *
    * 三条硬约束：
    * 1. **增量**：指纹没变的来源一次都不抽（这是 0025 增量承诺的一部分）；
    * 2. **不重写没变的卡片**：合并只追加 `source_refs`，正文不动，所以不会凭空造
    *    版本快照（`snapshotCard` 只认正文变化）；
-   * 3. **fail-soft**：一个候选被闸门拒绝、甚至一份来源整个抛错，都只记一笔，
+   * 3. **fail-soft**：一个候选写不进去、甚至一份来源整个抛错，都只记一笔，
    *    绝不带走整次重建 —— 重建失败比少一张卡片严重得多。
    */
   private async runExtractionStage(sources: SourceRaw[], previousHashes: Record<string, string>): Promise<ExtractionOutcome> {
@@ -2002,6 +3665,21 @@ export class KnowledgeRuntime {
     const enabledTypes = schema.types.filter(def => def.enabled)
     const registryHash = contentHashOf(JSON.stringify(enabledTypes.map(def => ({ id: def.id, description: def.description, examples: def.examples }))))
     const outcome = this.emptyExtractionOutcome({})
+    /**
+     * 模型调用**每轮解析一次**，而且解析不到时**如实报出来**（0044）。
+     *
+     * 静默降级的代价实测过：默认模型明明配着，接缝却永远是空的，于是编译一路按
+     * `##` 小节切了好几个月，而界面上没有任何一处说「模型抽取没生效」。人只会得出
+     * 一个结论 ——「这个编译没用」。降级可以是诚实的，前提是它说话。
+     */
+    const seam = this.config.extractWithModel ? this.modelSeamNow() : {}
+    const call = seam.call
+    if (this.config.extractWithModel && !call) {
+      outcome.warnings.push(
+        `模型抽取已开启，但取不到可用的模型调用：${seam.why ?? '原因未知'} —— 本次退回规则抽取：`
+        + '卡片正文是按 `##` 小节切下来的原文，判重也只能比字面，同一实体换个标题写法会落成两张卡。',
+      )
+    }
     /**
      * 上一轮落下的关系产物。**跳过的来源从这里读回自己的关系** —— 没有这一步，
      * 一次全量重编就会把图上所有 `relates_to` 边抹掉（见 `EXTRACTED_RELATIONS`）。
@@ -2009,7 +3687,13 @@ export class KnowledgeRuntime {
     const persisted = await this.readExtractedRelations()
     // 计数器与产物不能由 readdir 的顺序决定，所以先按 sourceId 排序。
     const ordered = [...sources].sort((left, right) => left.sourceId.localeCompare(right.sourceId))
-    let cards = await this.loadCards()
+    /**
+     * 库里的卡片是判重的参照物。整轮结束才一次性落盘 —— 同一张卡片被多份来源命中时
+     * 只写一次，正文在这一轮内累积（而不是产生 N 次互相覆盖的写入）。
+     */
+    const cards = await this.loadCards()
+    const byKey = new Map(cards.map(card => [`${card.entityType}:${card.entityId}`, card]))
+    const pending = new Map<string, PendingCard>()
     for (const source of ordered) {
       const fingerprint = this.extractionFingerprint(source, registryHash)
       outcome.extractionHashes[source.sourceId] = fingerprint
@@ -2024,11 +3708,121 @@ export class KnowledgeRuntime {
       }
       outcome.sourcesExtracted += 1
       try {
-        cards = await this.extractFromSource(source, cards, enabledTypes, outcome)
+        // 同一轮里后一份来源应当能看到前一份来源刚抽出来的实体，所以判重索引
+        // 每份来源都用「磁盘上的卡片 + 这一轮 pending 的卡片」重建。
+        await this.compileSource(source, byKey, pending, enabledTypes, outcome, call)
       } catch (cause) {
         outcome.warnings.push(`来源 ${source.sourceId} 的候选抽取失败，已跳过该来源：${cause instanceof Error ? cause.message : String(cause)}`)
       }
     }
+    /**
+     * 落**卡片**，不是提议（0044）。
+     *
+     * 每个计数都对应一次真实的 `writeCard`：只有真的写成功了才算「新建 / 更新」。
+     * 写失败的进 `warnings` 而不是静默消失 —— 少一张卡片是一个需要被看见的事件。
+     */
+    /**
+     * 图落位（0046）。
+     *
+     * 抽取那一段交给模型的是文字，模型给回来的正文里没有图，于是来源里 22 张图表
+     * 一张也进不了卡片 —— 而多模态编码读的正是 `imagePaths[0]`。图是**确定性**的
+     * （来源里有哪张图、它跟在哪段话后面，都不需要模型判断），所以在落盘前单独算一遍。
+     *
+     * 跨卡片一起算：一篇方法论文章编出 8 张卡，同一张图必须只落一张。已经引用过这张图
+     * 的卡片不算「变了」，所以重复编译不会反复写盘。
+     */
+    const folded = new Map<string, string>()
+    for (const [key, item] of pending) folded.set(key, appendExtracted(item.existing?.content ?? '', [item.content]))
+    const view: Array<{ key: string; content: string; sourceRefs: string[] }> = []
+    for (const [key, card] of byKey) view.push({ key, content: card.content, sourceRefs: card.sourceRefs })
+    for (const [key, item] of pending) view.push({ key, content: folded.get(key) ?? '', sourceRefs: item.sourceRefs })
+    const imagePlan = planSourceImages({ cards: view, sources: ordered.map(source => ({ sourceId: source.sourceId, content: source.content })) })
+    for (const [key, item] of pending) {
+      let content = folded.get(key) ?? ''
+      for (const image of imagePlan.byCard.get(key) ?? []) content = insertImage(content, image)
+      folded.set(key, content)
+    }
+    for (const [sourceId, count] of countBySource(imagePlan.unplaced)) {
+      outcome.warnings.push(`来源 ${sourceId} 有 ${count} 张图没找到落点（既不在任何卡片正文里，也不属于图所在的来源小节），仍留在来源里`)
+    }
+    const writtenKeys = new Set<string>()
+    for (const item of pending.values()) {
+      const key = `${item.entityType}:${item.entityId}`
+      const existing = item.existing
+      const metadata = { ...item.metadata, ...(item.merges.length > 0 ? { extraction_merges: mergeHistoryOf(item.metadata, item.merges) } : {}) }
+      /**
+       * 已经一模一样的卡片不重写。
+       *
+       * 判据只有两条：**正文没有新增内容**，而且**所有来源都已在 `source_refs` 里**。
+       * 少了这条，重建一次就会把每张卡片重写一遍 —— 而增量编译的意义正在于
+       * 「重编一次，没变的卡片不该产生任何写入」。
+       *
+       * 比较的是「追加之后是否还是原样」，而不是逐字比较：`item.content` 是从已有正文
+       * 出发追加出来的，两者相等就说明这次抽到的东西一个字都不新。图也算在内：
+       * 计划里带图而正文里没有，就是「变了」。
+       */
+      const content = folded.get(key) ?? item.content
+      writtenKeys.add(key)
+      const unchanged = existing !== undefined
+        && !item.fieldChanged
+        && content === existing.content
+        && item.sourceRefs.every(ref => existing.sourceRefs.includes(ref))
+      if (unchanged) continue
+      const written = await this.writeCard({
+        entityType: item.entityType,
+        entityId: item.entityId,
+        title: item.title,
+        content,
+        sourceRefs: item.sourceRefs,
+        ...(item.summary ? { summary: item.summary } : {}),
+        status: existing?.status ?? 'unreviewed',
+        ...(existing?.owner ? { owner: existing.owner } : {}),
+        ...(existing?.provenance ? { provenance: existing.provenance } : {}),
+        metadata,
+        origin: 'compile',
+      })
+      if (written.ok === false) {
+        outcome.warnings.push(`卡片 ${item.entityId} 写入失败（${written.error.code}）：${written.error.message}`)
+        continue
+      }
+      if (item.action === 'create') outcome.cardsCreated += 1
+      else outcome.cardsUpdated += 1
+      for (const warning of written.warnings ?? []) outcome.warnings.push(`卡片 ${item.entityId}：${warning}`)
+    }
+    /**
+     * 只补图的卡片：指纹没变的来源这一轮**不重抽**（`sourcesSkipped`），所以它的卡片
+     * 压根不在 `pending` 里 —— 而「卡片正文里有没有图」不影响抽取指纹。
+     *
+     * 少了这一段，0046 之前编好的库永远拿不到图：重编一次，来源被跳过，图还是不在。
+     * 这段只做一件事：把算好的图插进去，正文别的部分一个字都不动。
+     */
+    for (const [key, images] of imagePlan.byCard) {
+      if (writtenKeys.has(key)) continue
+      const card = byKey.get(key)
+      if (!card) continue
+      let content = card.content
+      for (const image of images) content = insertImage(content, image)
+      if (content === card.content) continue
+      const written = await this.writeCard({
+        entityType: card.entityType,
+        entityId: card.entityId,
+        title: card.title,
+        content,
+        sourceRefs: card.sourceRefs,
+        ...(card.summary ? { summary: card.summary } : {}),
+        status: card.status,
+        ...(card.owner ? { owner: card.owner } : {}),
+        ...(card.provenance ? { provenance: card.provenance } : {}),
+        metadata: card.metadata,
+        origin: 'compile',
+      })
+      if (written.ok === false) {
+        outcome.warnings.push(`卡片 ${card.entityId} 补图失败（${written.error.code}）：${written.error.message}`)
+        continue
+      }
+      outcome.cardsUpdated += 1
+      for (const warning of written.warnings ?? []) outcome.warnings.push(`卡片 ${card.entityId}：${warning}`)
+    }
     // 只留这一轮真实存在的来源：删掉的文档不该在图上留下幽灵关系。
     const alive = new Set(ordered.map(source => source.sourceId))
     const next: Record<string, ExtractionOutcome['relations']> = {}
@@ -2070,138 +3864,193 @@ export class KnowledgeRuntime {
     } catch { /* 写不进去就当这一轮没有产物，下一次重建会重新抽 */ }
   }
 
-  /** 一份来源的抽取结果：新建候选卡片、把证据来源并进已有卡片、收集关系候选。 */
-  private async extractFromSource(source: SourceRaw, cards: KnowledgeCard[], enabledTypes: WikiTypeDef[], outcome: ExtractionOutcome): Promise<KnowledgeCard[]> {
-    /**
-     * #3b：**模型先抽实体，规则补关系。**
-     *
-     * 规则抽取把「小节标题」当实体身份，实测下来的后果是同一件东西横跨两份文档就
-     * 变成两张卡片（`新建 2 / 并入 0`）—— 追加分支永远不触发。所以实体这一层交给
-     * 模型（它能判断「毛利率变动及其驱动因素」与「毛利率（口径补充）」是同一个东西）。
-     *
-     * 但仍然**照跑一遍规则抽取**，理由有两个：关系候选只有规则会抽（模型这一层不产
-     * 关系），而且模型不可用时它就是那条降级路径。两者不是二选一。
-     */
+  /**
+   * 一份来源的编译结果：**按 wiki schema 抽实体**（新建 / 更新），并收集关系候选。
+   *
+   * ## 模型先抽实体，规则补关系
+   *
+   * 规则抽取把「小节标题」当实体身份，实测下来的后果是同一件东西横跨两份文档就
+   * 变成两张卡片（`新建 2 / 并入 0`），而且卡片正文是按 `##` 切下来的原文片段 ——
+   * 也就是「编译只是按目录截取」。所以实体这一层交给模型：它按类型的必填小节与字段
+   * 写正文，并回答「这个实体是不是已经在下表里了」。
+   *
+   * 但仍然**照跑一遍规则抽取**，理由有两个：关系候选只有规则会抽（模型这一层不产
+   * 关系），而且模型不可用时它就是那条降级路径。两者不是二选一。
+   *
+   * ## 缺信息也抽
+   *
+   * 0040 那一版在这里拒绝「没有正文」的候选、拒绝「类型未登记」的候选。两条都撤掉了：
+   * 编译的价值在于**记下来，后面有涉及到的文档再慢慢补**，而拒绝恰好把这个机会丢掉。
+   * 只剩一条硬要求 —— 正文不能是空的（一条什么都说不出的卡片没有东西可召回）；
+   * 模型路径已经保证只要给了 summary 就有骨架，规则路径的候选天然带正文。
+   */
+  private async compileSource(
+    source: SourceRaw,
+    byKey: Map<string, KnowledgeCard>,
+    pending: Map<string, PendingCard>,
+    enabledTypes: WikiTypeDef[],
+    outcome: ExtractionOutcome,
+    /** 这一轮可用的模型调用；由 `runExtractionStage` 解析一次后传进来。 */
+    call: ModelCall | undefined,
+  ): Promise<void> {
+    // 判重索引要看到「这一轮前面几份来源刚抽出来的卡片」，否则同一实体跨两份文档
+    // 会各建一张 —— 而那正是这次改造要修掉的那个 bug。
+    const cards = [...byKey.values()]
+    // 同一份来源里的两个候选指向同一张卡片时，只该合并一次。
+    const merges = new Map<string, NormalizedCandidates['merges'][number]>()
+
     const ruleCandidates = extractCandidates(source, enabledTypes)
     outcome.candidatesExtracted += ruleCandidates.length
     const ruleNormalized = normalizeCandidates(ruleCandidates, buildAliasIndex(cards))
 
-    let normalized: NormalizedCandidates = ruleNormalized
-    if (this.modelCall && this.config.extractWithModel) {
-      const modelled = await extractWithModel({ source, wikiTypes: enabledTypes, existing: cards, call: this.modelCall })
+    let fresh = ruleNormalized.fresh
+    for (const merge of ruleNormalized.merges) if (!merges.has(merge.key)) merges.set(merge.key, merge)
+
+    /**
+     * 这一份来源**实际用了哪条路**（0044 实机验证修的第二个诚实问题）。
+     *
+     * 原来这里写的是 `extraction: call ? 'model' : 'pass0'` —— 判据是「有没有接缝」，
+     * 不是「模型给的东西有没有被用上」。实机上模型确实被调用了，但输出不是 JSON，
+     * 于是候选整批来自规则路径，卡片却标着 `extraction: model`：**脏的是标签，不是数据**。
+     * 下一次有人排查「为什么正文还是按 `##` 切的」，会盯着这个字段得出相反结论。
+     *
+     * 现在的判据是产物：模型给出至少一条实体（新建或并入）才算 `model`。
+     */
+    let extractionPath: 'model' | 'pass0' = 'pass0'
+    if (call) {
+      const modelled = await extractWithModel({
+        source,
+        wikiTypes: enabledTypes,
+        existing: cards,
+        call,
+        /**
+         * 路由与缓存亲和的会话身份，**按知识库稳定**（0044 实机验证第五批）。
+         *
+         * 没有它，OpenCode 系路由直接回 400 `MissingSessionID` —— 那件事在界面上长得
+         * 像「模型抽取不可用」。用 `knowledge:<库 id>` 而不是随机 UUID：同一个库反复
+         * 编译时提示词高度重复（类型定义 + 已有卡片清单），稳定的值把请求钉在同一个
+         * 上游后端，命中缓存的概率才成立。
+         */
+        sessionId: `knowledge:${this.baseId || 'default'}`,
+      })
       for (const warning of modelled.warnings) outcome.warnings.push(warning)
       // 模型一条实体都没给（或者不可用）时，完整退回规则结果，而不是丢掉整轮抽取。
       if (modelled.fresh.length > 0 || modelled.merges.length > 0) {
-        normalized = { fresh: modelled.fresh, merges: modelled.merges, relations: ruleNormalized.relations }
+        extractionPath = 'model'
+        fresh = modelled.fresh
+        merges.clear()
+        for (const merge of modelled.merges) if (!merges.has(merge.key)) merges.set(merge.key, merge)
+      } else if (modelled.warnings.length === 0) {
+        // 模型正常回答、只是没给实体 —— 这也是一次实际的降级，不该只体现在卡片标签上。
+        outcome.warnings.push('模型没有给出任何实体，本次退回规则抽取（正文按 `##` 小节切）。')
       }
     }
-    const candidates = normalized.fresh
-    if (candidates.length === 0 && normalized.merges.length === 0) return cards
-    const next = [...cards]
 
-    // 先建后并：同一轮里新建的卡片也可能被别名指回，先建才能让后面的合并找得到对象。
-    for (const candidate of normalized.fresh) {
+    const at = new Date().toISOString()
+    for (const candidate of fresh) {
+      /**
+       * 类型：未登记就**退回一个已启用的兜底类型**，而不是丢掉这条候选。
+       *
+       * 0040 时期这里是 `candidatesRejected += 1` 然后 continue。那条规则与
+       * 「缺信息也编译进去」直接冲突：类型没登记是**配置问题**，不是「这条知识不存在」——
+       * 而配置问题该由配置界面回答，不该让文档里的知识消失。退回时记一条 warning，
+       * 把原始类型名带上，人是能顺藤摸瓜去登记它的。
+       *
+       * 模型路径（`extract-model.ts`）早就是这么做的，这里补齐规则路径 —— 两条路径对
+       * 同一种情况给出不同结论，比任选一种都糟。
+       */
+      const wanted = enabledTypes.find(def => def.id === candidate.type)
+      const resolvedType = wanted ?? enabledTypes.find(def => def.id === 'concept') ?? enabledTypes[0]
+      if (!resolvedType) {
+        outcome.candidatesRejected += 1
+        outcome.warnings.push(`候选「${candidate.name}」未入库：没有任何已启用的 wiki 类型可落（先在「知识库设置 → Wiki 类型」里登记一个）`)
+        continue
+      }
+      if (!wanted) {
+        outcome.warnings.push(`候选「${candidate.name}」的类型 ${candidate.type} 未登记或已停用，已按「${resolvedType.id}」入库`)
+      }
       /**
-       * 候选**必须带正文**才落卡。
+       * 正文：候选自带的正文优先，没有就用 summary 撑一个带必填小节骨架的最小正文。
        *
-       * 0029 实跑发现：这里原来在候选没有正文时拿 `type.template` 顶上，于是
-       * `[[链接]]` 指到、但还没人写过的实体（那时链接候选确实没有正文）会落成一张
-       * **正文是模板**的卡片，而模板里的「（必填：写什么）」会被编进 wikiNotes、
-       * 被召回、被塞进模型的上下文包 —— 管线写出了一张它自己的校验器判为不合格的
-       * 卡片。链接候选现在会带上它所在小节的正文（`extract.ts`），所以这条回退基本
-       * 不会被走到；真走到了就**不落卡**，并如实计数：没有正文 = 没有可说的。
+       * 两条路径（模型 / 规则）走同一个 `skeletonBody`，所以「只说了半句」的候选在两处
+       * 得到同一种对待。撑完还是空 → 这是**唯一保留的拒绝**：一条什么都不说的卡片没有
+       * 东西可召回，而它占的 id 会让下一份真正说了点什么的文档并进这张空卡里。
        */
-      const body = candidate.body?.trim() ?? ''
+      const body = candidate.body?.trim() || skeletonBody(resolvedType, candidate.summary?.trim() ?? '')
       if (!body) {
         outcome.candidatesRejected += 1
-        outcome.warnings.push(`候选「${candidate.name}」没有任何正文（只在别处被提到，所在小节也没取到），不落卡`)
+        outcome.warnings.push(`候选「${candidate.name}」没有任何正文与摘要（只在别处被提到，所在小节也没取到），未入库`)
         continue
       }
-      // 重复的写法都进 aliases：判重认的是名字，不是卡片 id（中文名会退化成哈希 id）。
-      const aliases = [...new Set([candidate.name, ...(candidate.aliases ?? [])].map(value => value.trim()).filter(Boolean))]
+      const entityId = candidateEntityId(candidate.name)
+      const key = `${resolvedType.id}:${entityId}`
       const metadata: Record<string, unknown> = {
-        extraction: 'pass0',
+        extraction: extractionPath,
         candidate_kind: candidate.kind,
         confidence: candidate.confidence,
         evidence: {
           sourceId: candidate.evidence.sourceId,
           ...(candidate.evidence.heading ? { heading: candidate.evidence.heading } : {}),
         },
-        ...(aliases.length > 0 ? { aliases } : {}),
+        // 重复的写法都进 aliases：判重认的是名字，不是卡片 id（中文名会退化成哈希 id）。
+        ...(aliasesOf(candidate).length > 0 ? { aliases: aliasesOf(candidate) } : {}),
+        // 类型定义里的字段（`metric.formula` 之类）落在 metadata 上，不占正文。
+        ...(candidate.fields ?? {}),
       }
-      const written = await this.writeCard({
-        entityType: candidate.type,
-        entityId: candidateEntityId(candidate.name),
-        title: candidate.name,
-        content: body,
-        sourceRefs: [candidate.evidence.sourceId],
-        status: 'unreviewed',
-        metadata,
-      })
-      if (!written.ok) {
-        outcome.candidatesRejected += 1
-        outcome.warnings.push(`候选「${candidate.name}」未写入（${written.error?.code ?? 'UNKNOWN'}）：${written.error?.message ?? ''}`)
+      // 库里已经有这张卡片 → 不是新建，而是「把这次抽到的正文并进去」。
+      const existing = byKey.get(key)
+      if (existing) {
+        mergeIntoPending(pending, existing, candidate.evidence.sourceId, [body], [candidate.name], at, candidate.fields, candidate.summary)
+        continue
+      }
+      const previous = pending.get(key)
+      if (previous) {
+        previous.content = appendExtracted(previous.content, [body])
+        if (!previous.sourceRefs.includes(candidate.evidence.sourceId)) previous.sourceRefs.push(candidate.evidence.sourceId)
+        if (!previous.summary && candidate.summary) previous.summary = candidate.summary
+        previous.metadata = { ...previous.metadata, ...(candidate.fields ?? {}) }
+        previous.merges.push({ sourceId: candidate.evidence.sourceId, keys: [candidate.name], at })
         continue
       }
-      outcome.cardsCreated += 1
-      next.push({
-        entityId: written.data.entityId,
-        entityType: candidate.type,
+      pending.set(key, {
+        action: 'create',
+        entityType: resolvedType.id as SchemaType,
+        entityId,
         title: candidate.name,
-        status: 'unreviewed',
         content: body,
         sourceRefs: [candidate.evidence.sourceId],
         metadata,
-        updatedAt: '',
+        ...(candidate.summary ? { summary: candidate.summary } : {}),
+        merges: [{ sourceId: candidate.evidence.sourceId, keys: [candidate.name], at }],
       })
     }
 
-    // 归一：命中的候选把证据来源并进已有卡片。同一张卡片在这一轮里的多次命中合并且只写一次。
-    const targets = new Map<string, { card: KnowledgeCard; keys: string[]; sourceId: string; bodies: string[] }>()
-    for (const merge of normalized.merges) {
-      const card = next.find(item => item.entityId === merge.entityId && item.entityType === merge.entityType)
-      if (!card) continue
-      // 「只在没有的时候追加」：来源已在 source_refs 里就什么都不做 —— 空写也会
-      // 刷新 updated_at，并让「并入了多少张卡」这个计数变成谎话。
-      if (card.sourceRefs.includes(merge.sourceId)) continue
-      const id = `${merge.entityType}:${merge.entityId}`
-      const entry = targets.get(id)
-      if (entry) {
-        if (!entry.keys.includes(merge.key)) entry.keys.push(merge.key)
-        entry.bodies.push(merge.body)
-      } else targets.set(id, { card, keys: [merge.key], sourceId: merge.sourceId, bodies: [merge.body] })
-    }
-    for (const { card, keys, sourceId, bodies } of targets.values()) {
-      const history = Array.isArray(card.metadata.extraction_merges) ? card.metadata.extraction_merges : []
-      // 只留最近 20 条：这是「这张卡被哪些来源判重命中过」的可见痕迹，不是审计日志。
-      const extraction_merges = [...history, { sourceId, keys, at: new Date().toISOString() }].slice(-20)
-      // **追加**而不是覆盖，也不是丢弃：实体已存在时，这次新抽到的正文并进原卡片，
-      // 于是知识是累积的，来源改写了也不会停在旧版本上。
-      const content = appendExtracted(card.content, bodies)
-      const written = await this.writeCard({
-        ...card,
-        content,
-        sourceRefs: [...card.sourceRefs, sourceId],
-        metadata: { ...card.metadata, extraction_merges },
-      })
-      if (!written.ok) {
-        outcome.candidatesRejected += 1
-        outcome.warnings.push(`候选并入卡片「${card.entityId}」失败（${written.error?.code ?? 'UNKNOWN'}）：${written.error?.message ?? ''}`)
+    // 归一：命中的候选把证据来源并进已有卡片。同一张卡片在这一轮里的多次命中合并成一条。
+    for (const merge of merges.values()) {
+      const key = `${merge.entityType}:${merge.entityId}`
+      // 这一轮刚新建的卡片也要认：它此刻还在 `pending` 里，不在磁盘上。
+      const existing = byKey.get(key)
+      if (existing) {
+        // 「只在没有的时候追加」：来源已在 source_refs 里、正文也已在卡片里时什么都不做 ——
+        // 空写一次也会让「更新了几张卡」这个计数变成谎话。
+        if (existing.sourceRefs.includes(merge.sourceId) && appendExtracted(existing.content, [merge.body]) === existing.content) continue
+        mergeIntoPending(pending, existing, merge.sourceId, [merge.body], [merge.key], at, merge.fields, merge.summary)
         continue
       }
-      outcome.cardsMerged += 1
-      // 让后面的来源看到已经追加过的正文与 source_refs，避免重复写入。
-      const index = next.findIndex(item => item.entityId === card.entityId && item.entityType === card.entityType)
-      if (index >= 0) next[index] = { ...card, content, sourceRefs: [...card.sourceRefs, sourceId], metadata: { ...card.metadata, extraction_merges } }
+      const previous = pending.get(key)
+      if (!previous) continue
+      previous.content = appendExtracted(previous.content, [merge.body])
+      if (!previous.sourceRefs.includes(merge.sourceId)) previous.sourceRefs.push(merge.sourceId)
+      previous.metadata = { ...previous.metadata, ...(merge.fields ?? {}) }
+      previous.merges.push({ sourceId: merge.sourceId, keys: [merge.key], at })
     }
 
-    outcome.relations.push(...normalized.relations)
+    outcome.relations.push(...ruleNormalized.relations)
     // 按来源存一份：跳过的来源下次重建要靠它把关系读回来（见 EXTRACTED_RELATIONS）。
     outcome.relationsBySource[source.sourceId] = [
       ...(outcome.relationsBySource[source.sourceId] ?? []),
-      ...normalized.relations,
+      ...ruleNormalized.relations,
     ]
-    return next
   }
 
   /**
@@ -2232,6 +4081,326 @@ export class KnowledgeRuntime {
     return { extracted, dropped }
   }
 
+  // ------------------------------------------- Finalize · 索引 / 断链 / 相关（0049）
+
+  /**
+   * 收尾段的**正文层**：给卡片补相关块、把断链写成 `reference` 问题。
+   *
+   * 它必须在 stage 2（切 wikiNotes）**之前**跑：相关块是正文的一部分，晚于切分写进去，
+   * 这一轮编出来的召回单元就与卡片正文对不上，而下次重建又会因为正文变了重切一遍 ——
+   * 每次编译都白编一次。
+   *
+   * 三段都是确定性的，所以这个函数可以重复跑：没变化的卡片一次都不写盘（判据是
+   * 「正文 + 问题清单逐字相同」）。这也让「重编一次，卡片不该有任何写入」这条承诺
+   * 在收尾段照样成立。
+   */
+  private async runFinalizeStage(
+    cards: KnowledgeCard[],
+    relations: Array<{ fromKey: string; toKey: string }>,
+    warnings: string[],
+  ): Promise<FinalizeOutcome> {
+    const related = planRelated(cards, relations)
+    /**
+     * 断链扫的是**写完相关块之后的正文**，不是读进来的那一份。
+     *
+     * 相关块自己就是一堆 `[[类型/标题]]`：扫旧正文等于这一轮看不见它们，而它们马上
+     * 要写进文件 —— 于是「引用是否成立」这件事被推迟到下一轮，而下一轮又会因为
+     * 问题清单变了再写一遍。扫新正文，一轮就说清楚。
+     */
+    const nextContent = new Map(cards.map(card => [cardKey(card), applyRelatedSection(card.content, related.get(cardKey(card)) ?? [])]))
+    const deadLinks = deadLinksOf(cards.map(card => ({ ...card, content: nextContent.get(cardKey(card)) ?? card.content })))
+    const deadByKey = new Map<string, string[]>()
+    for (const link of deadLinks) {
+      const bucket = deadByKey.get(link.key) ?? []
+      bucket.push(link.target)
+      deadByKey.set(link.key, bucket)
+    }
+    let rewritten = 0
+    for (const card of cards) {
+      const key = cardKey(card)
+      const content = nextContent.get(key) ?? card.content
+      // 旧的问题清单里 `reference` 那几条是上一轮算的，先摘掉再按这一轮重算 ——
+      // 断链修好之后那条问题必须消失，否则「待补」清单会越用越长。
+      const kept = cardIssuesOf(card).filter(issue => issue.level !== 'reference')
+      const reference = (deadByKey.get(key) ?? []).map(deadLinkIssue)
+      const issues = [...kept, ...reference]
+      if (content === card.content && JSON.stringify(issues) === JSON.stringify(cardIssuesOf(card))) continue
+      /**
+       * 没有来源的卡片写不进去（`writeCard` 要求 `source_refs` 非空），而这是**唯一**
+       * 一种收尾段碰不到的卡片：它已经是一张不合法的卡片了。如实报出来，不静默跳过 ——
+       * 这种卡片只能由人补来源，或者删掉。
+       */
+      if (card.sourceRefs.length === 0) {
+        warnings.push(`卡片 ${card.entityId} 没有来源，无法补相关块：正文只读，来源只能由编译或人工重新写入`)
+        continue
+      }
+      const written = await this.writeCard({
+        entityType: card.entityType,
+        entityId: card.entityId,
+        title: card.title,
+        content,
+        sourceRefs: card.sourceRefs,
+        ...(card.summary ? { summary: card.summary } : {}),
+        status: card.status,
+        ...(card.owner ? { owner: card.owner } : {}),
+        ...(card.provenance ? { provenance: card.provenance } : {}),
+        metadata: card.metadata,
+        extraIssues: reference,
+        origin: 'compile',
+      })
+      if (written.ok === false) {
+        warnings.push(`卡片 ${card.entityId} 的相关块 / 断链未写入（${written.error.code}）：${written.error.message}`)
+        continue
+      }
+      rewritten += 1
+    }
+    return {
+      related, deadLinks, rewritten,
+      relatedLinks: [...related.values()].reduce((sum, entries) => sum + entries.length, 0),
+      relatedCards: [...related.keys()].length,
+    }
+  }
+
+  /** 收尾段的**产物层**：写索引页。它读的是正文层算完之后的卡片清单。 */
+  private async writeWikiIndex(input: {
+    cards: KnowledgeCard[]
+    related: Map<string, RelatedEntry[]>
+    deadLinks: DeadLink[]
+  }): Promise<void> {
+    await writeTextAtomic(this.safePath('03_compiled', WIKI_INDEX), buildWikiIndex(input))
+  }
+
+  /** 一条路的候选 → 账本行（0050）。名次按这一路自己的顺序，没过阈值的也在。 */
+  private ledgerRows(rows: Array<RouteRanking & { kept: boolean }> | undefined, unitById: Map<string, WikiNote>): RecallLedgerRow[] {
+    return (rows ?? []).flatMap((row, index) => {
+      const note = unitById.get(row.unitId)
+      if (note === undefined) return []
+      return [{
+        unitId: row.unitId,
+        title: note.title,
+        entityType: note.entityType,
+        entityId: note.entityId,
+        score: row.score,
+        rank: index + 1,
+        kept: row.kept,
+      }]
+    })
+  }
+
+  // ------------------------------------------- 召回组装：去重 / 扩展 / 预算（0050）
+
+  /**
+   * **1 跳扩展**：从命中的卡片出发，按图上的边拉邻居。
+   *
+   * 两个来源，优先级相同（都记进 `via`，一条邻居可以有多条来路）：
+   * 1. **图上的边**（`relates_to` 这类卡片之间的关系）—— `supported_by` 不算：
+   *    它连的是「卡片 → 来源」，而来源不是 wiki 卡片，进不了上下文；
+   * 2. **共同来源**：同一份 SourceRaw 编译出来的卡片也是邻居（这是最实用的一类，
+   *    新库里往往一条 `relates_to` 都没有）。
+   *
+   * 调用点必须在**按卡片去重之后**：先扩展再去重会把邻居与命中混在一起，
+   * 而上下文里必须分得清「这是召回来的」还是「这是延伸出来的」。
+   */
+  private expandWiki(seedKeys: string[], cardByKey: Map<string, KnowledgeCard>, includeProblems: boolean): RecallExpansion {
+    const seeds = new Set(seedKeys)
+    const visible = (card: KnowledgeCard): boolean => includeProblems || card.status !== 'problem'
+    const via = new Map<string, string[]>()
+    const remember = (key: string, from: string): void => {
+      const bucket = via.get(key) ?? []
+      if (!bucket.includes(from)) bucket.push(from)
+      via.set(key, bucket)
+    }
+    const edges: Array<Record<string, unknown>> = []
+    for (const edge of this.graph.edges) {
+      const type = String(edge.type)
+      if (type === 'supported_by') continue
+      const from = String(edge.from)
+      const to = String(edge.to)
+      const fromSeed = seeds.has(from)
+      const toSeed = seeds.has(to)
+      // 两端都在种子里（种子里的一条内部边）或都不在（与这次召回无关）：不是扩展。
+      if (fromSeed === toSeed) continue
+      const neighbor = fromSeed ? to : from
+      const card = cardByKey.get(neighbor)
+      if (card === undefined || !visible(card)) continue
+      remember(neighbor, `${fromSeed ? from : to}|${type}`)
+      edges.push(edge)
+    }
+    // 共同来源：反向走 `supported_by`（来源 → 它编译出的卡片）。
+    const bySource = new Map<string, string[]>()
+    for (const key of seeds) {
+      for (const ref of cardByKey.get(key)?.sourceRefs ?? []) {
+        const bucket = bySource.get(ref) ?? []
+        bucket.push(key)
+        bySource.set(ref, bucket)
+      }
+    }
+    for (const card of cardByKey.values()) {
+      const key = cardKey(card)
+      if (seeds.has(key) || !visible(card)) continue
+      for (const ref of card.sourceRefs) {
+        const owners = bySource.get(ref)
+        if (owners === undefined || owners.length === 0) continue
+        remember(key, `${owners[0]}|shared_source`)
+      }
+    }
+    const nodes: RecallExpansion['nodes'] = []
+    for (const [key, sources] of via) {
+      const card = cardByKey.get(key)
+      if (card === undefined) continue
+      nodes.push({ entityType: card.entityType, entityId: card.entityId, title: card.title, via: sources })
+    }
+    // 排序：来路多的在前（更可能是真的相关），同数按身份，保证确定性。
+    nodes.sort((left, right) => right.via.length - left.via.length || `${left.entityType}:${left.entityId}`.localeCompare(`${right.entityType}:${right.entityId}`))
+    const capped = nodes.slice(0, MAX_EXPANSION_CARDS)
+    const kept = new Set(capped.map(node => `${node.entityType}:${node.entityId}`))
+    return {
+      nodes: capped,
+      // 只留两端都在扩展集里的边：一端是命中卡片的边已经写在命中卡片自己的子图里了。
+      edges: edges.filter(edge => kept.has(String(edge.from)) && kept.has(String(edge.to))),
+      included: [],
+    }
+  }
+
+  /** 一条上下文条目「值多少字符」：命中条目算它那些 note 的正文，扩展条目算标题 + 摘要（+ 正文）。 */
+  private contextCost(item: ContextItem, full: boolean): number {
+    if (item.reason === 'hit') return item.notes.reduce((sum, note) => sum + note.title.length + note.content.length, 0)
+    const card = item.wiki
+    if (card === null) return 0
+    const shallow = card.title.length + (card.summary?.length ?? 0)
+    return full ? shallow + card.content.length : shallow
+  }
+
+  /** 溢出目录：**系统临时目录**，不随知识库走（0050 的取舍，见 issue）。 */
+  private recallOverflowDir(): string {
+    return join(tmpdir(), 'dsh-knowledge-recall', this.baseId || 'default')
+  }
+
+  /**
+   * 上下文预算：装箱 + 溢出（0050）。
+   *
+   * 让位顺序（写死在这里，不是启发式）：
+   * 1. **命中的 note 正文优先**：它是证据，装不下就该少给几张卡片，而不是把证据截断；
+   * 2. 扩展卡片先给**标题 + 摘要 + 来路**（便宜，且足以让模型知道「还有这么一张卡」）；
+   * 3. 还有余量才给扩展卡片的正文。
+   *
+   * 溢出的内容落**系统临时目录**（`<os.tmpdir()>/dsh-knowledge-recall/<库>/<recallId>.md`），
+   * 不随库走：它是一次召回的临时产物，下一次召回就是另一份。代价是系统会清它 ——
+   * 所以指路行必须说清「本次会话内有效」，并给出「读不到就重新召回」这条出路。
+   */
+  private async packContext(input: { items: ContextItem[]; maxChars: number; recallId: string }): Promise<{
+    items: ContextItem[]
+    report: ContextBudgetReport
+    notice?: string
+  }> {
+    const { items, maxChars, recallId } = input
+    const hitCards = items.filter(item => item.reason === 'hit').length
+    const expandedCards = items.length - hitCards
+    const totalChars = items.reduce((sum, item) => sum + this.contextCost(item, true), 0)
+    if (!Number.isFinite(maxChars) || maxChars <= 0) {
+      return { items, report: { maxChars: 0, usedChars: totalChars, omittedCards: 0, omittedChars: 0, hitCards, expandedCards } }
+    }
+    const keptItems: ContextItem[] = []
+    let used = 0
+    for (const item of items) {
+      const full = this.contextCost(item, true)
+      const shallow = this.contextCost(item, false)
+      // 命中条目按整条算（它的正文就是证据）；扩展条目可以先按「浅」那一档进。
+      const cost = item.reason === 'hit' ? full : shallow
+      if (used + cost > maxChars) continue
+      used += cost
+      keptItems.push(item)
+    }
+    const keptKeys = new Set(keptItems.map(item => item.wiki === null ? '' : `${item.wiki.entityType}:${item.wiki.entityId}`))
+    const omitted = items.filter(item => !keptKeys.has(item.wiki === null ? '' : `${item.wiki.entityType}:${item.wiki.entityId}`))
+    const report: ContextBudgetReport = {
+      maxChars,
+      usedChars: used,
+      omittedCards: omitted.length,
+      omittedChars: omitted.reduce((sum, item) => sum + this.contextCost(item, true), 0),
+      hitCards: keptItems.filter(item => item.reason === 'hit').length,
+      expandedCards: keptItems.filter(item => item.reason === 'expansion').length,
+    }
+    if (omitted.length === 0) return { items: keptItems, report }
+    const overflowPath = await this.writeRecallOverflow({ items, recallId, usedChars: used, maxChars })
+    report.overflowPath = overflowPath
+    return {
+      items: keptItems,
+      report,
+      notice: `还有 ${report.omittedCards} 张卡片共 ${report.omittedChars} 字符没有放进上下文，完整内容在 ${overflowPath}；需要更多信息时直接读这个文件（它是本次召回的临时产物，不保证长期存在）。`,
+    }
+  }
+
+  /** 把**完整**的上下文写进溢出文件（含被预算挡在外面的那些）。 */
+  private async writeRecallOverflow(input: { items: ContextItem[]; recallId: string; usedChars: number; maxChars: number }): Promise<string> {
+    const dir = this.recallOverflowDir()
+    await mkdir(dir, { recursive: true })
+    await this.pruneRecallOverflow(dir)
+    const path = join(dir, `${input.recallId}.md`)
+    const lines: string[] = [
+      '# 这次召回的完整上下文',
+      '',
+      `上限 ${input.maxChars} 字符，上下文里装了 ${input.usedChars} 字符；这里是**全部**内容。`,
+      '它是临时产物，读不到时重新召回一次即可。',
+      '',
+    ]
+    for (const item of input.items) {
+      const card = item.wiki
+      lines.push(`## ${card?.title ?? '(未找到卡片)'} · ${card?.entityType ?? ''}/${card?.entityId ?? ''}${item.reason === 'expansion' ? '（1 跳扩展）' : ''}`, '')
+      if (item.via) lines.push(`来路：${item.via.entityType}/${item.via.entityId}（${item.via.relation}）`, '')
+      if (card?.summary) lines.push(`> ${card.summary}`, '')
+      for (const note of item.notes) lines.push(`### ${note.title}`, '', note.content, '')
+      if (item.reason === 'expansion' && card) lines.push(card.content, '')
+    }
+    await writeTextAtomic(path, `${lines.join('\n').replace(/\n+$/, '')}\n`)
+    return path
+  }
+
+  /** 清掉本库前缀下超过保留时长的溢出文件（自清理，不依赖系统清 tmp）。 */
+  private async pruneRecallOverflow(dir: string): Promise<void> {
+    try {
+      const cutoff = Date.now() - RECALL_OVERFLOW_TTL_MS
+      for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+        const path = join(dir, entry.name)
+        try {
+          const info = await stat(path)
+          if (info.mtimeMs < cutoff) await unlink(path)
+        } catch { /* 并发删掉了就算了 */ }
+      }
+    } catch { /* 目录还不存在：没有什么要清 */ }
+  }
+
+  /**
+   * 一张卡片的出链与入链（面板抽屉里的「相关」分块）。
+   *
+   * 与写进正文的那一块**同一份计划**：两处都调 `planRelated`，所以界面上看到的关系
+   * 与文件里写的不会漂移。入链要单独算 —— 关系是双向记的，但同源那一类是「谁和我
+   * 同源」，只能扫一遍别人的出链。
+   */
+  async relatedOfCard(card: KnowledgeCard): Promise<{ outgoing: RelatedEntry[]; incoming: RelatedEntry[] }> {
+    /**
+     * 图上那几条关系边住在 `knowledge_graph.json`，进程刚起来时内存里是空的。
+     * 少了这一次读取，「关系」那一类相关会**静默缺失**（只剩同源那几条），而界面上
+     * 看不出少了什么 —— 卡片抽屉是本插件里第一个在召回之外读图的地方。
+     */
+    if (this.graph.edges.length === 0) await this.loadCompiledState()
+    const cards = await this.loadCards()
+    const graphRelations = this.graph.edges
+      .filter(edge => String(edge.type) !== 'supported_by')
+      .map(edge => ({ fromKey: String(edge.from), toKey: String(edge.to) }))
+    const related = planRelated(cards, graphRelations)
+    const key = cardKey(card)
+    const outgoing = related.get(key) ?? []
+    const incoming: RelatedEntry[] = []
+    for (const [fromKey, entries] of related) {
+      if (fromKey === key) continue
+      const entry = entries.find(item => item.key === key)
+      if (entry) incoming.push({ ...entry, key: fromKey })
+    }
+    return { outgoing, incoming }
+  }
+
   async rebuild(only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean } = {}): Promise<Envelope<RebuildReport>> {
     await this.ensureLayout()
     const startedAt = new Date().toISOString()
@@ -2240,7 +4409,7 @@ export class KnowledgeRuntime {
     const sourceTypes = new Map(sources.map(source => [source.sourceId, source.sourceType]))
 
     // ------------------------------------------------ previous build state
-    let previousManifest: { version?: number; builtAt?: string; cardHashes?: Record<string, string>; extractionHashes?: Record<string, string>; embedding?: unknown } = {}
+    let previousManifest: { version?: number; builtAt?: string; cardHashes?: Record<string, string>; extractionHashes?: Record<string, string>; embedding?: unknown; diagnosisHash?: string; indexHash?: string } = {}
     try {
       previousManifest = JSON.parse(await readFile(this.safePath('03_compiled', 'build-manifest.json'), 'utf8')) as typeof previousManifest
     } catch { /* first build */ }
@@ -2258,14 +4427,20 @@ export class KnowledgeRuntime {
     const extraction = extractEnabled
       ? await this.runExtractionStage(sources, previousExtractionHashes)
       : this.emptyExtractionOutcome(previousExtractionHashes)
-    // 抽取刚落过盘：stage 2 必须看到新的卡片清单，否则这一轮建的卡片要等下一次
-    // 重建才进 wikiNotes，用户点了编译却召不回刚抽出来的东西。
-    if (extraction.cardsCreated > 0 || extraction.cardsMerged > 0) this.cards = await this.loadCards()
+    /**
+     * 抽取刚落过盘：stage 2 必须看到新的卡片清单，否则这一轮建的卡片要等下一次
+     * 重建才进 wikiNotes，用户点了编译却召不回刚抽出来的东西。
+     *
+     * 0044 之前这一行是多余的（Pass 0 只写提议，卡片清单根本不会变），所以它一直是
+     * 一个**没被触发过的**承诺；现在 Pass 0 直接落卡，漏掉它就会表现成「第一次编译
+     * 什么都没建出来，第二次才有」—— 一个看起来像缓存没刷新的 bug。
+     */
+    if (extractEnabled) this.cards = await this.loadCards()
     const extractionCounts = {
       candidatesExtracted: extraction.candidatesExtracted,
       candidatesRejected: extraction.candidatesRejected,
       cardsCreated: extraction.cardsCreated,
-      cardsMerged: extraction.cardsMerged,
+      cardsUpdated: extraction.cardsUpdated,
       sourcesExtracted: extraction.sourcesExtracted,
       sourcesSkipped: extraction.sourcesSkipped,
     }
@@ -2273,11 +4448,54 @@ export class KnowledgeRuntime {
     let relationsExtracted = 0
     let relationsDropped = 0
 
+    // --------------------------------- Finalize · 相关块与断链（正文层，先于切分）
+    /**
+     * 收尾段在 stage 2 **之前**跑，理由有两条，都不是风格问题：
+     *
+     * 1. 相关块是正文的一部分。晚于切分写进去，这一轮编出的召回单元就与卡片正文对不上，
+     *    而下一轮又会因为正文变了重切一遍 —— 每次编译都白编一次；
+     * 2. 它必须参与「语料变了没有」的判定。0047 的图片那次踩过同一个坑：派生内容写盘
+     *    晚于判定，增量编译判定「没有变化」，刚写进去的东西连同整个产物一起被丢掉。
+     *
+     * `extractEnabled` 为假（`only: 'embeddings'`）时整段不跑：它不碰 wiki 层。
+     */
+    const finalize: FinalizeOutcome = extractEnabled
+      ? await this.runFinalizeStage(this.cards, extraction.relations, warnings)
+      : { related: new Map(), relatedLinks: 0, relatedCards: 0, deadLinks: [], rewritten: 0 }
+    // 正文层刚落过盘：stage 2 必须看到写完相关块之后的卡片。
+    if (finalize.rewritten > 0) this.cards = await this.loadCards()
+    /**
+     * 索引页也是这次编译的产物，所以它变了也算「语料变了」。
+     *
+     * 少了这一条会踩一个很隐蔽的坑：一个**本来就没有任何关系**的知识库，收尾段一条
+     * 卡片都不改，增量编译于是判定「没有变化」直接跳过 —— 索引页永远不会被写出来，
+     * 而界面上没有任何一处说「这个文件没有生成」。
+     */
+    const indexText = buildWikiIndex({ cards: this.cards, related: finalize.related, deadLinks: finalize.deadLinks })
+    const indexHash = contentHashOf(indexText)
+    // 文件被手工删掉时也算「变了」：它是产物，不该因为「内容没变」就永远回不来。
+    const indexChanged = indexHash !== previousManifest.indexHash || !existsSync(this.safePath('03_compiled', WIKI_INDEX))
+    const finalizeCounts = {
+      relatedLinks: finalize.relatedLinks,
+      relatedCards: finalize.relatedCards,
+      deadLinks: finalize.deadLinks.length,
+      finalizeRewritten: finalize.rewritten,
+    }
+
     // ------------------------------------------------ stage 2 · compile notes
     let cardsReused = 0
     let cardsRecompiled = 0
     let cardsAdded = 0
     let notesReused = 0
+    /**
+     * 复用 note 时**派生字段**（图片路径、来源分类、溯源链）被刷新过。
+     *
+     * 它必须参与「语料变了没有」的判定：这些字段不在 `cardHashOf` 里（它们能从正文
+     * 重算出来），所以一张卡片可以「一个字都没变」而编译产物确实不同 —— 0047 实机
+     * 踩到的就是这个：解析规则修好了，增量编译却判定「没有变化」，直接走空操作返回，
+     * 刷新过的路径连同整个 `wiki_notes.json` 一起被丢掉。
+     */
+    let derivedRefreshed = false
     let notesRecompiled = 0
     const cardHashes: Record<string, string> = {}
     /**
@@ -2308,16 +4526,33 @@ export class KnowledgeRuntime {
         if (!previousHashes[key]) cardsAdded += 1
         const kept = incremental && previousHashes[key] === fingerprint ? previousByWiki.get(key) : undefined
         if (kept && kept.length > 0) {
-          // Reuse the notes verbatim, but refresh the two derived fields that can
-          // change *without* the card changing: a SourceRaw's business type and
-          // the card's provenance chain. Keeping a stale `sourceTypes` would make
-          // a source_type-filtered recall silently miss this card.
+          // Reuse the notes verbatim, but refresh the derived fields that can
+          // change *without* the card changing: a SourceRaw's business type, the
+          // card's provenance chain, and the image paths. Keeping a stale
+          // `sourceTypes` would make a source_type-filtered recall silently miss
+          // this card; keeping stale `imagePaths` would keep the multimodal
+          // encoder pointed at a path that no longer resolves (0047: the first
+          // live rebuild reused notes whose paths were resolved by the old rule,
+          // so the encoder still got `02_wiki/concept/_assets/…`).
+          //
+          // 评分不在这里刷新：它已经是 `cardHashOf` 的一部分，所以「评分变了」走的是
+          // 重编那条分支，不会走到这里。
           const sourceTypesFor = card.sourceRefs.flatMap(ref => { const sourceType = sourceTypes.get(ref); return sourceType ? [sourceType] : [] })
-          notes.push(...kept.map(note => ({
-            ...note,
-            sourceTypes: sourceTypesFor,
-            ...(card.provenance ? { provenance: card.provenance } : {}),
-          })))
+          const cardDir = join(this.directory(WIKI), card.entityType)
+          notes.push(...kept.map(note => {
+            // 图按 note **自己那一节**的引用算 —— 与 `compileCardNotes` 同一条规则，
+            // 否则复用与重编会给出两套答案。
+            const images = markdownImagePaths(note.content, cardDir, this.rootDir)
+            if (JSON.stringify(note.imagePaths ?? []) !== JSON.stringify(images)) derivedRefreshed = true
+            if (JSON.stringify(note.sourceTypes ?? []) !== JSON.stringify(sourceTypesFor)) derivedRefreshed = true
+            const { imagePaths: _stale, ...rest } = note
+            return {
+              ...rest,
+              ...(images.length > 0 ? { imagePaths: images } : {}),
+              sourceTypes: sourceTypesFor,
+              ...(card.provenance ? { provenance: card.provenance } : {}),
+            }
+          }))
           cardsReused += 1
           notesReused += kept.length
         } else {
@@ -2335,7 +4570,19 @@ export class KnowledgeRuntime {
       // bumping the version there would invalidate the vector cache and every
       // qrels pointing at it for nothing. `all` never takes this path (see
       // `incremental` above).
-      const corpusChanged = !incremental || previousVersion === 0 || cardsRecompiled > 0 || cardsRemoved > 0
+      /**
+       * 归因图（字段级）也是这次编译的产物之一，所以它变了也算「语料变了」。
+       *
+       * 少了这一条会踩一个很隐蔽的坑：**记一次排查不改任何卡片**（它写的是一条
+       * `agent_diagnosis_case` 的 SourceRaw），于是增量编译判定「没变化」直接跳过 ——
+       * 而 `03_compiled/diagnosis_graph.json` 停在上一轮，图召回因此看不到这次排查
+       * 新增的 `produces` / `supports` / `refutes` 边。它读的是**编译产物**，
+       * 不是 `02_wiki` 的实时投影（§14.3）。
+       */
+      const diagnosis = await this.diagnosisStore().readGraph()
+      const diagnosisHash = contentHashOf(JSON.stringify({ nodes: diagnosis.nodes, edges: diagnosis.edges }))
+      const diagnosisChanged = diagnosisHash !== previousManifest.diagnosisHash
+      const corpusChanged = !incremental || previousVersion === 0 || cardsRecompiled > 0 || cardsRemoved > 0 || diagnosisChanged || derivedRefreshed || indexChanged
       if (!corpusChanged) {
         const compileRunId = `rebuild_${hash(`${startedAt}:${this.cards.length}`)}`
         const report: RebuildReport = {
@@ -2346,7 +4593,7 @@ export class KnowledgeRuntime {
           cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0,
           notesReused, notesRecompiled: 0,
           incremental: true, skipped: true,
-          ...extractionCounts,
+          ...extractionCounts, ...finalizeCounts,
           // 这一轮没有重装图，所以没有一条边是「这次连上的」或「这次丢掉的」。
           // 报 0 而不是把图里已有的边算进来：那会把历史成果记到这次空操作头上。
           relationsExtracted: 0, relationsDropped: 0,
@@ -2356,7 +4603,7 @@ export class KnowledgeRuntime {
         // 用户刚点了编译却看到上次的统计，会以为按钮没生效。version 不变，所以
         // 这个写入既不改索引也不让向量缓存失效。extractionHashes 必须跟着更新：
         // 来源变了但没抽出卡片时，不落新指纹会让下一次又把它重抽一遍。
-        await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version: previousVersion, builtAt: previousManifest.builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: previousManifest.embedding, compileRunId, lastBuild: { only, incremental: true, skipped: true, cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0, notesReused, notesRecompiled: 0, ...extractionCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2))
+        await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version: previousVersion, builtAt: previousManifest.builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: previousManifest.embedding, diagnosisHash, indexHash, compileRunId, lastBuild: { only, incremental: true, skipped: true, cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0, notesReused, notesRecompiled: 0, ...extractionCounts, ...finalizeCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2))
         return success(report, ['知识库没有变化：已复用全部 wikiNotes，未生成新的索引版本。', ...extraction.warnings])
       }
 
@@ -2381,6 +4628,23 @@ export class KnowledgeRuntime {
       // Compatibility mirror for tooling that predates wiki_notes.json.
       await writeTextAtomic(this.safePath('03_compiled', LEGACY_UNITS), JSON.stringify(this.units, null, 2))
       await writeTextAtomic(this.safePath('03_compiled', 'knowledge_graph.json'), JSON.stringify(this.graph, null, 2))
+      /**
+       * 字段级的归因图（0021 §14.3）。**同一次编译产出两份投影，各自由它的消费者读**：
+       * `knowledge_graph.json` 是卡片级（图谱 Tab、图召回），这里是字段级
+       * （智能归因三视图）。不合成一张 —— 消费者不同、`supported_by` 只对卡片成立、
+       * 而召回权重的基准不该被顺手改掉（§14.4）。
+       */
+      this.diagnosisGraph = { nodes: diagnosis.nodes as unknown as Array<Record<string, unknown>>, edges: diagnosis.edges as unknown as Array<Record<string, unknown>> }
+      await writeTextAtomic(this.safePath('03_compiled', DIAGNOSIS_GRAPH), JSON.stringify({ version, builtAt, nodes: diagnosis.nodes, edges: diagnosis.edges }, null, 2))
+      /**
+       * 收尾段的**产物层**：索引页（0049）。
+       *
+       * 放在图装配之后：索引页里那几条「相关」是**图上的边**，先写索引再装图，写出来的
+       * 就会是上一轮的图。`indexText` 在正文层那一段已经算过一次（为了判断「这一轮到底
+       * 有没有变化」），这里重算一遍是因为卡片清单可能被 stage 2 之后的写入改过 ——
+       * 两处调的是同一个纯函数，所以不可能给出两种格式。
+       */
+      await this.writeWikiIndex({ cards: this.cards, related: finalize.related, deadLinks: finalize.deadLinks })
       // 关键词索引跟着 notes 一起落盘（0031）：它的输入就是 notes，两者必须同时有效，
       // 否则会出现「卡片改了、关键词路还按旧词表召回」。它不依赖编码器，所以 wiki-only
       // 重建也要重建它 —— 而向量是 stage 3，仍然只在 `embeddings`/`all` 时重算。
@@ -2390,7 +4654,7 @@ export class KnowledgeRuntime {
       // re-encode of the whole corpus.
       const embeddingResult = only === 'all' ? await this.buildVectorIndex(this.units, version) : { status: 'skipped' as const, count: 0, reused: 0 }
       const compileRunId = `rebuild_${hash(`${startedAt}:${this.cards.length}`)}`
-      await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version, builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: embeddingResult, fts: ftsResult, compileRunId, lastBuild: { only, incremental: cardsReused > 0, skipped: false, cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount, notesReused, notesRecompiled, ...extractionCounts, relationsExtracted, relationsDropped }, ...(lineage ? { lineage } : {}) }, null, 2))
+      await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version, builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: embeddingResult, fts: ftsResult, compileRunId, diagnosisHash, indexHash, diagnosisGraph: { nodes: diagnosis.nodes.length, edges: diagnosis.edges.length }, lastBuild: { only, incremental: cardsReused > 0, skipped: false, cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount, notesReused, notesRecompiled, ...extractionCounts, ...finalizeCounts, relationsExtracted, relationsDropped }, ...(lineage ? { lineage } : {}) }, null, 2))
       const report: RebuildReport = {
         runId: compileRunId, compileRunId, version, only,
         cards: this.cards.length, units: this.units.length, notes: this.units.length,
@@ -2404,7 +4668,7 @@ export class KnowledgeRuntime {
         notesReused, notesRecompiled,
         incremental: cardsReused > 0 || notesReused > 0,
         skipped: false,
-        ...extractionCounts, relationsExtracted, relationsDropped,
+        ...extractionCounts, ...finalizeCounts, relationsExtracted, relationsDropped,
         ...(lineage ? { lineage } : {}), startedAt, finishedAt: new Date().toISOString(),
       }
       if (embeddingResult.status === 'unavailable') warnings.push(`embedding 不可用，已保留 FTS fallback：${embeddingResult.error ?? 'unknown error'}`)
@@ -2428,8 +4692,8 @@ export class KnowledgeRuntime {
       vectorQuantization: embeddingResult.status === 'ready' ? VECTOR_QUANTIZATION : undefined,
       embeddingError: embeddingResult.error,
       incremental: embeddingResult.reused > 0, skipped: false,
-      // `embeddings` 不跑 Pass 0，所以这些计数是真的 0，不是省略。
-      ...extractionCounts, relationsExtracted: 0, relationsDropped: 0,
+      // `embeddings` 不跑 Pass 0，也不跑收尾段，所以这些计数是真的 0，不是省略。
+      ...extractionCounts, ...finalizeCounts, relationsExtracted: 0, relationsDropped: 0,
       ...(lineage ? { lineage } : {}), startedAt, finishedAt: new Date().toISOString(),
     }
     if (embeddingResult.status === 'unavailable') warnings.push(`embedding 不可用，已保留 FTS fallback：${embeddingResult.error ?? 'unknown error'}`)
@@ -2499,12 +4763,12 @@ export class KnowledgeRuntime {
   }
 
   /** 关键词路：FTS5 + BM25（0031）。索引不在时如实降级，不退回旧的计数打分。 */
-  private async ftsRoute(query: string, eligible: WikiNote[], pool: number, threshold: number, titleOf: (sourceId: string) => string | undefined): Promise<{ ranking: RouteRanking[]; diagnostic: RecallRouteDiagnostic }> {
+  private async ftsRoute(query: string, eligible: WikiNote[], pool: number, threshold: number, titleOf: (sourceId: string) => string | undefined): Promise<{ ranking: RouteRanking[]; rows: Array<RouteRanking & { kept: boolean }>; diagnostic: RecallRouteDiagnostic }> {
     const eligibleIds = new Set(eligible.map(note => note.unitId))
     const sqlite = await loadSqlite()
-    if (!sqlite) return { ranking: [], diagnostic: { route: 'fts', status: 'degraded', reason: '当前 Node 没有 node:sqlite（需要 22.5+），关键词路已降级' } }
+    if (!sqlite) return { ranking: [], rows: [], diagnostic: { route: 'fts', status: 'degraded', reason: '当前 Node 没有 node:sqlite（需要 22.5+），关键词路已降级' } }
     const index = await FtsIndex.open(this.safePath('03_compiled', FTS_FILE), sqlite.DatabaseSync)
-    if (!index) return { ranking: [], diagnostic: { route: 'fts', status: 'degraded', reason: `关键词索引不存在（03_compiled/${FTS_FILE}），先编译一次` } }
+    if (!index) return { ranking: [], rows: [], diagnostic: { route: 'fts', status: 'degraded', reason: `关键词索引不存在（03_compiled/${FTS_FILE}），先编译一次` } }
     try {
       const found = index.search(query, pool).filter(hit => eligibleIds.has(hit.unitId))
       /**
@@ -2527,9 +4791,10 @@ export class KnowledgeRuntime {
         // 单字查询（如 `表`）是刻意收窄的问法，没有「多字词覆盖率」可言：不拦它，
         // 交给阈值。这里如实返回空排名之外的结果需要另走一条路，所以直接用全部命中。
         const ranking = found.map(hit => ({ unitId: hit.unitId, score: hit.score }))
-        const { kept, dropped, topScore } = applyThreshold(ranking, threshold)
+        const { kept, dropped, topScore, rows } = applyThreshold(ranking, threshold)
         return {
           ranking: kept,
+          rows,
           diagnostic: {
             route: 'fts', status: 'ran', candidates: ranking.length, kept: kept.length, topScore, threshold,
             ...(dropped > 0 ? { reason: `${dropped} 条低于关键词阈值 ${threshold} 被丢弃` } : {}),
@@ -2546,13 +4811,14 @@ export class KnowledgeRuntime {
       })
       const covered = scored.filter(hit => hit.coverage >= MIN_QUERY_COVERAGE)
       const ranking = covered.map(hit => ({ unitId: hit.unitId, score: hit.score }))
-      const { kept, dropped, topScore } = applyThreshold(ranking, threshold)
+      const { kept, dropped, topScore, rows } = applyThreshold(ranking, threshold)
       const lowCoverage = scored.length - covered.length
       const reasons: string[] = []
       if (lowCoverage > 0) reasons.push(`${lowCoverage} 条查询词覆盖率低于 ${MIN_QUERY_COVERAGE} 被丢弃`)
       if (dropped > 0) reasons.push(`${dropped} 条低于关键词阈值 ${threshold} 被丢弃`)
       return {
         ranking: kept,
+        rows,
         diagnostic: {
           route: 'fts', status: 'ran', candidates: ranking.length, kept: kept.length, topScore, threshold,
           ...(reasons.length > 0 ? { reason: reasons.join('；') } : {}),
@@ -2570,16 +4836,18 @@ export class KnowledgeRuntime {
    * 阈值就完全失去意义（余弦 0 会被映射成 0.5，轻松过线）。原始余弦是绝对量，可以直接
    * 用来判「这段内容和问题到底像不像」—— 弃答主要靠它和重排阈值。
    */
-  private async vectorRoute(query: string, eligibleIds: Set<string>, pool: number, threshold: number): Promise<{ ranking: RouteRanking[]; diagnostic: RecallRouteDiagnostic; health: { ok: boolean; reason?: string } }> {
+  private async vectorRoute(query: string, eligibleIds: Set<string>, pool: number, threshold: number): Promise<{ ranking: RouteRanking[]; rows: Array<RouteRanking & { kept: boolean }>; diagnostic: RecallRouteDiagnostic; health: { ok: boolean; reason?: string }; timings?: { embedMs: number; scanMs: number } }> {
     const health = await this.checkEncoder()
-    if (!health.ok) return { ranking: [], diagnostic: { route: 'vector', status: 'degraded', reason: health.reason }, health }
+    if (!health.ok) return { ranking: [], rows: [], diagnostic: { route: 'vector', status: 'degraded', reason: health.reason }, health }
     try {
-      const scores = await this.vectorRecall(query, eligibleIds, pool)
+      const { scores, embedMs, scanMs } = await this.vectorRecall(query, eligibleIds, pool)
       const ranking = [...scores.entries()].map(([unitId, score]) => ({ unitId, score })).sort((left, right) => right.score - left.score || left.unitId.localeCompare(right.unitId))
-      const { kept, dropped, topScore } = applyThreshold(ranking, threshold)
+      const { kept, dropped, topScore, rows } = applyThreshold(ranking, threshold)
       return {
         ranking: kept,
+        rows,
         health,
+        timings: { embedMs, scanMs },
         diagnostic: {
           route: 'vector', status: 'ran', candidates: ranking.length, kept: kept.length, topScore, threshold,
           ...(dropped > 0 ? { reason: `${dropped} 条低于向量阈值 ${threshold} 被丢弃` } : {}),
@@ -2588,7 +4856,7 @@ export class KnowledgeRuntime {
     } catch (cause) {
       const error = cause instanceof Error ? cause.message : String(cause)
       this.vectorError = error
-      return { ranking: [], diagnostic: { route: 'vector', status: 'degraded', reason: `向量召回不可用：${error}` }, health }
+      return { ranking: [], rows: [], diagnostic: { route: 'vector', status: 'degraded', reason: `向量召回不可用：${error}` }, health }
     }
   }
 
@@ -2598,7 +4866,60 @@ export class KnowledgeRuntime {
    * 匹配逻辑与 0030 相同（词面匹配节点 title / id 与关系词，命中节点带出 1 跳邻居并衰减），
    * 但返回值只用于给**已经在候选池里**的条目加权 —— 它自己不能制造候选。
    */
-  private graphBoostRanking(query: string, eligible: WikiNote[], includeProblems: boolean): RouteRanking[] {
+  /**
+   * 字段级的归因图（`03_compiled/diagnosis_graph.json`）。
+   *
+   * 它只用于**给已经在候选池里的条目加权**（和卡片级图一样，不能自己制造候选）。
+   * 用途是把「假设 → 检查点」「证据 → 假设」这两类卡片级图看不见的语义带进召回。
+   */
+  private diagnosisGraph: { nodes: Array<Record<string, unknown>>; edges: Array<Record<string, unknown>> } = { nodes: [], edges: [] }
+
+  /**
+   * 归因图上按词面命中的节点 → 分数，含 1 跳衰减。
+   *
+   * 与卡片级那一段是**同一条算法、两份数据**：卡片级图里只有 `supported_by` /
+   * `relates_to`，而字段级图里是十种语义边。分开算再按 `entityId` 合流，
+   * 是因为两张图的节点含义不同（一个是卡片，一个是字段级节点），合成一张会让
+   * 图谱 Tab 看到一张卡片散成七个点。
+   */
+  private diagnosisHits(queryTokens: string[]): Map<string, number> {
+    const seed = new Map<string, number>()
+    if (this.diagnosisGraph.nodes.length === 0) return seed
+    for (const node of this.diagnosisGraph.nodes) {
+      const title = String(node.title ?? '').toLocaleLowerCase()
+      const id = String(node.id ?? '').toLocaleLowerCase()
+      let score = 0
+      for (const token of queryTokens) {
+        if (title.includes(token)) score += 3
+        else if (id.includes(token)) score += 2
+      }
+      if (score > 0) seed.set(String(node.id), score)
+    }
+    // 关系词命中：两端各得 1 分。中文提问不会写 `refutes`，所以走 RELATION_QUERY_WORDS。
+    for (const edge of this.diagnosisGraph.edges) {
+      const type = String(edge.kind ?? '')
+      const relation = (RELATION_QUERY_WORDS[type] ?? type.toLocaleLowerCase().replace(/_/g, ' ')).toLocaleLowerCase()
+      let score = 0
+      for (const token of queryTokens) if (relation.includes(token)) score += 1
+      if (score > 0) {
+        seed.set(String(edge.source), Math.max(seed.get(String(edge.source)) ?? 0, score))
+        seed.set(String(edge.target), Math.max(seed.get(String(edge.target)) ?? 0, score))
+      }
+    }
+    if (seed.size === 0) return seed
+    const expanded = new Map<string, number>(seed)
+    for (const [id, score] of seed) {
+      for (const edge of this.diagnosisGraph.edges) {
+        const from = String(edge.source)
+        const to = String(edge.target)
+        if (from === id) expanded.set(to, Math.max(expanded.get(to) ?? 0, score * 0.5))
+        else if (to === id) expanded.set(from, Math.max(expanded.get(from) ?? 0, score * 0.5))
+      }
+    }
+    return expanded
+  }
+
+  private async graphBoostRanking(query: string, eligible: WikiNote[], includeProblems: boolean): Promise<RouteRanking[]> {
     if (this.graph.nodes.length === 0) return []
     const queryTokens = segment(query)
     if (queryTokens.length === 0) return []
@@ -2606,6 +4927,9 @@ export class KnowledgeRuntime {
     const boost = (key: string, score: number): void => { byNodeKey.set(key, Math.max(byNodeKey.get(key) ?? 0, score)) }
     const visible = (node: Record<string, unknown>): boolean => includeProblems || node.status !== 'problem'
     const nodeKey = (node: Record<string, unknown>): string => `${String(node.type)}:${String(node.id)}`
+    /** 卡片级节点 id → 它的 `entity_type`。归因图的节点 id 与卡片 id 相等（§14.1）。 */
+    const typeByEntityId = new Map<string, string>()
+    for (const node of this.graph.nodes) typeByEntityId.set(String(node.id), String(node.type))
 
     for (const node of this.graph.nodes) {
       if (!visible(node)) continue
@@ -2625,6 +4949,18 @@ export class KnowledgeRuntime {
       for (const token of queryTokens) if (relation.includes(token)) score += 1
       if (score > 0) { boost(String(edge.from), score); boost(String(edge.to), score) }
     }
+    /**
+     * **字段级的归因图**（0021 §14.4 的第二条最小路径）。
+     *
+     * 卡片级的图只认 `supported_by` 与 `relates_to` 两种关系词，所以「假设 → 检查点」
+     * 与「证据 → 假设」这两类语义对召回完全不可见。这里按 `entityId` 把两张图接起来：
+     * 归因图上命中的节点，映射回同 id 的卡片级节点加权 —— **不需要合图**，
+     * 因为两张图的节点 id 本来就相等（§14.1）。
+     */
+    for (const [id, score] of this.diagnosisHits(queryTokens)) {
+      const type = typeByEntityId.get(id)
+      if (type) boost(`${type}:${id}`, score)
+    }
     if (byNodeKey.size === 0) return []
     const expanded = new Map<string, number>(byNodeKey)
     for (const [key, score] of byNodeKey) {
@@ -2691,9 +5027,14 @@ export class KnowledgeRuntime {
     includeProblems = false,
     mode?: RecallMode,
     lineage?: LineageContext,
-    options: { contextTopN?: number; rerank?: boolean } = {},
+    options: { contextTopN?: number; rerank?: boolean; contextMaxChars?: number; detail?: boolean } = {},
   ): Promise<Envelope<RecallResult>> {
     const recallId = generatedId('recall')
+    /**
+     * 各阶段耗时（0050 第二版）。用 `performance.now()` 而不是 `Date.now()`：
+     * 向量扫描这一段本身就在毫秒以下，用墙钟分辨率量不出东西来。
+     */
+    const startedAt = performance.now()
     const recallMode = mode ?? this.config.recallMode
     const recallTopK = limit ?? this.config.recallTopK
     const requestedTopN = options.contextTopN ?? this.config.contextTopN
@@ -2749,37 +5090,70 @@ export class KnowledgeRuntime {
     const useVector = recallMode !== 'fts'
     const useGraphBoost = recallMode === 'hybrid' || recallMode === 'graph'
 
+    const ftsStarted = performance.now()
     const ftsOutcome = useFts
       ? await this.ftsRoute(query, eligible, candidatePool, this.config.keywordThreshold, titleOf)
-      : { ranking: [] as RouteRanking[], diagnostic: { route: 'fts' as const, status: 'skipped' as const, reason: '当前模式未启用关键词路' } }
+      : { ranking: [] as RouteRanking[], rows: [] as Array<RouteRanking & { kept: boolean }>, diagnostic: { route: 'fts' as const, status: 'skipped' as const, reason: '当前模式未启用关键词路' } }
+    const ftsMs = performance.now() - ftsStarted
+    const vectorStarted = performance.now()
     const vectorOutcome = useVector
       ? await this.vectorRoute(query, eligibleIds, candidatePool, this.config.vectorThreshold)
-      : { ranking: [] as RouteRanking[], diagnostic: { route: 'vector' as const, status: 'skipped' as const, reason: '当前模式未启用向量路' }, health: { ok: false, reason: '当前模式未启用向量路' } }
-    const graphRanking = useGraphBoost ? this.graphBoostRanking(query, eligible, includeProblems) : []
+      : { ranking: [] as RouteRanking[], rows: [] as Array<RouteRanking & { kept: boolean }>, diagnostic: { route: 'vector' as const, status: 'skipped' as const, reason: '当前模式未启用向量路' }, health: { ok: false, reason: '当前模式未启用向量路' } }
+    const vectorMs = performance.now() - vectorStarted
+    const graphStarted = performance.now()
+    const graphRanking = useGraphBoost ? await this.graphBoostRanking(query, eligible, includeProblems) : []
+    const graphMs = performance.now() - graphStarted
 
     if (ftsOutcome.diagnostic.status === 'degraded' && ftsOutcome.diagnostic.reason) warnings.push(ftsOutcome.diagnostic.reason)
     if (vectorOutcome.diagnostic.status === 'degraded' && vectorOutcome.diagnostic.reason) warnings.push(vectorOutcome.diagnostic.reason)
 
     // --- R2 · 名次级融合（RRF）+ 图谱 boost ---------------------------------
+    const fuseStarted = performance.now()
     const fused = rrfFuse({ fts: ftsOutcome.ranking, vector: vectorOutcome.ranking }, { k: RRF_K, weights: RRF_WEIGHTS })
     const boosted = graphBoost(fused, graphRanking, { k: RRF_K, weights: RRF_WEIGHTS })
 
     const unitById = new Map(eligible.map(unit => [unit.unitId, unit]))
+    /**
+     * 0044：review 评分在这里接进排序。
+     *
+     * 它**只改排序键，不改 `score` 字段本身** —— 命中里那个 `score` 仍然是融合分/重排分，
+     * 是「这一路觉得它多相关」的原始答案。把评分乘进去再写回 `score`，会让读的人以为
+     * 相关性变了；而它变的只是「同类命中里先看谁」。
+     *
+     * 生效点有两处，缺一处就会出现「review 了但排序没动」：
+     * 1. 重排前的候选顺序（决定哪些条目进入重排的视线）；
+     * 2. 重排后的截断顺序（`recallTopK`）。
+     *
+     * 0050 之前还有第三处（上下文选择的 MMR 相关性函数）。现在上下文按**卡片**去重、
+     * 顺序直接沿用 `hits`（`notesByWiki` 的顺序就是它），所以那第三处自然消失了 ——
+     * 不是被删掉，而是不再需要单独算一遍。
+     */
+    const rankKey = (hit: RecallHit): number => (hit.rerankScore ?? hit.score) * reviewWeight(hit.reviewScore)
     let hits: RecallHit[] = boosted.hits
       .filter(hit => unitById.has(hit.unitId))
       .map(hit => ({ ...unitById.get(hit.unitId)!, score: hit.score, match: matchOf(hit.ranks), ranks: hit.ranks }))
+      .sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId))
+
+    const fuseMs = performance.now() - fuseStarted
 
     // --- R3 · 对**候选池**重排，再过阈值 ------------------------------------
     let rerank: RerankResult
+    const rerankStarted = performance.now()
+    /** 逐条模型分（0050 的面板账本用）：`kept` 只给活下来的，账本要全部。 */
+    let rerankScored: Array<{ unitId: string; logit: number; rerankScore: number; kept: boolean }> = []
     if (options.rerank === false || this.config.rerankProvider === 'none') {
       rerank = { status: 'skipped', provider: this.config.rerankProvider }
       hits = hits.slice(0, recallTopK)
     } else {
       const reranked = await this.rerankNotes(query, hits, this.config.rerankThreshold)
+      rerankScored = reranked.scored ?? []
       hits = reranked.hits.slice(0, recallTopK)
       rerank = reranked.result
       if (reranked.warning) warnings.push(reranked.warning)
     }
+    // 重排换的是相关性顺序，评分加权仍然要压在最上面 —— 否则「review 过的排前面一点」
+    // 只在关掉重排时成立，而重排默认是开着的。
+    hits = [...hits].sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId))
 
     // --- R4 · 证据片段 -----------------------------------------------------
     await this.attachEvidence(hits, queryTerms, corpus)
@@ -2822,36 +5196,149 @@ export class KnowledgeRuntime {
     }
 
     // --- 组装：片段 → 整篇 → 证据 -------------------------------------------
+    const assembleStarted = performance.now()
     const cards = this.cards.length > 0 ? this.cards : await this.loadCards()
     const cardByKey = new Map(cards.map(card => [`${card.entityType}:${card.entityId}`, card]))
     const wikiKey = (note: Pick<RecallHit, 'entityType' | 'entityId'>) => `${note.entityType}:${note.entityId}`
-    const wiki = [...new Set(hits.map(wikiKey))].map(key => cardByKey.get(key)).filter((card): card is KnowledgeCard => card !== undefined)
-    const graph = this.oneHopGraph(new Set(hits.map(wikiKey)), includeProblems)
-    // 上下文条目的选择**不是**简单切片：每张 wiki 封顶 + MMR 去冗余，否则 5 条上下文
-    // 可能全是同一张卡的不同小节（一屏塞满、信息量为 1）。
-    const contextHits = selectContext(hits, {
-      relevance: hit => hit.rerankScore ?? hit.score,
-      tokens: hit => tokenSet(`${hit.title}\n${hit.content}`),
-      wikiKey: hit => hit.entityId,
-      limit: contextTopN,
-      perWikiCap: CONTEXT_PER_WIKI_CAP,
-    })
-    const context: ContextItem[] = contextHits.map(note => ({
-      note,
-      wiki: cardByKey.get(wikiKey(note)) ?? null,
-      graph: this.oneHopGraph(new Set([wikiKey(note)]), includeProblems),
-      ...(note.evidence ? { evidence: note.evidence } : {}),
-    }))
+
+    /**
+     * 按 **wiki 卡片**去重（0050 的第一半）。
+     *
+     * `hits` 已经按排序键降序，所以每张卡片第一次出现的那条就是它**最好的一条 note**
+     * —— 那就是这张卡片的等级。同一张卡的其余小节挂在它下面（`notes`），
+     * 不再各自占一个上下文名额。
+     */
+    const notesByWiki = new Map<string, RecallHit[]>()
+    for (const hit of hits) {
+      const key = wikiKey(hit)
+      const bucket = notesByWiki.get(key)
+      if (bucket) bucket.push(hit)
+      else notesByWiki.set(key, [hit])
+    }
+    /**
+     * 命中的卡片，顺序 = 各自最好那条 note 的顺序。
+     *
+     * `contextTopN` 约束的是**这里**：进上下文的命中卡片数。1 跳扩展来的卡片另算
+     * （它们受上下文预算与 `MAX_EXPANSION_CARDS` 约束）—— 扩展是「延伸」，
+     * 不该挤掉「证据」的名额，也不该被 top_n 卡死。
+     */
+    const hitCards = [...notesByWiki.entries()]
+      .map(([key, notes]) => ({ key, notes, card: cardByKey.get(key) }))
+      .slice(0, contextTopN)
+    const wiki = hitCards.map(item => item.card).filter((card): card is KnowledgeCard => card !== undefined)
+    const graph = this.oneHopGraph(new Set(hitCards.map(item => item.key)), includeProblems)
+
+    /**
+     * **在去重之后**做 1 跳扩展（0050 的第二半）。
+     *
+     * 反过来（先扩展再去重）会把邻居与被命中的卡片混在一起，分不清「这是召回来的」
+     * 还是「这是邻居」—— 而这两件事在上下文里必须能分开，前者是证据，后者是延伸。
+     */
+    const expansion = this.expandWiki(hitCards.map(item => item.key), cardByKey, includeProblems)
+
+    /** 上下文条目：先命中的卡片（带它们的 note），再扩展来的卡片。 */
+    const items: ContextItem[] = [
+      ...hitCards.map(item => ({
+        wiki: item.card ?? null,
+        notes: item.notes,
+        note: item.notes[0]!,
+        graph: this.oneHopGraph(new Set([item.key]), includeProblems),
+        reason: 'hit' as const,
+        ...(item.notes[0]!.evidence ? { evidence: item.notes[0]!.evidence } : {}),
+      })),
+      ...expansion.nodes.map(node => {
+        const key = `${node.entityType}:${node.entityId}`
+        const card = cardByKey.get(key) ?? null
+        const [fromKey, relation] = (node.via[0] ?? '').split('|')
+        const from = fromKey === undefined ? undefined : cardByKey.get(fromKey)
+        return {
+          wiki: card,
+          notes: [],
+          graph: this.oneHopGraph(new Set([key]), includeProblems),
+          reason: 'expansion' as const,
+          ...(from === undefined ? {} : { via: { entityType: from.entityType, entityId: from.entityId, title: from.title, relation: relation ?? '' } }),
+        }
+      }),
+    ]
+
+    /**
+     * 上下文预算（0050）：装箱 + 溢出。
+     *
+     * 让位顺序写死在 `packContext` 里：先保证命中 note 的正文完整（它是证据），
+     * 再给扩展卡片的标题 + 摘要 + 关系，最后才给扩展卡片的正文。
+     */
+    /**
+     * 每次调用可以覆盖预算（0050）：指路行里就写着「读不到就调大预算重新召回」，
+     * 所以那条出路必须真的存在 —— 只给一个设置项的话，Agent 改不了它。
+     */
+    const maxChars = options.contextMaxChars ?? this.config.contextMaxChars
+    const packed = await this.packContext({ items, maxChars, recallId })
+    /** 哪些扩展卡片真的进了上下文（被预算挡住的也如实报出来）。 */
+    expansion.included = packed.items
+      .filter(item => item.reason === 'expansion' && item.wiki !== null)
+      .map(item => `${item.wiki!.entityType}:${item.wiki!.entityId}`)
+    if (packed.notice) warnings.push(packed.notice)
+
+    /**
+     * 面板账本（0050）：`detail: true` 才建。
+     *
+     * 它回答的是「这一条是怎么进来的、算了几分、有没有被丢」—— 而这三问分别对应
+     * 关键词路 / 向量路 / 重排。工具调用不带它：几十行候选分数进模型上下文是纯噪声。
+     */
+    const ledger: RecallLedger | undefined = options.detail === true
+      ? {
+        fts: this.ledgerRows(ftsOutcome.rows, unitById),
+        vector: this.ledgerRows(vectorOutcome.rows, unitById),
+        rerank: (() => {
+          const byUnit = new Map(rerankScored.map(row => [row.unitId, row]))
+          const fusedByUnit = new Map(boosted.hits.map(hit => [hit.unitId, hit.score]))
+          const order = rerankScored.length > 0 ? rerankScored.map(row => row.unitId) : hits.map(hit => hit.unitId)
+          return order.flatMap((unitId, index) => {
+            const note = unitById.get(unitId)
+            if (note === undefined) return []
+            const model = byUnit.get(unitId)
+            return [{
+              unitId,
+              title: note.title,
+              entityType: note.entityType,
+              entityId: note.entityId,
+              score: model?.rerankScore ?? fusedByUnit.get(unitId) ?? 0,
+              rank: index + 1,
+              kept: model?.kept ?? true,
+              fused: fusedByUnit.get(unitId) ?? 0,
+              ...(model === undefined ? {} : { logit: model.logit, rerankScore: model.rerankScore }),
+              // 没有模型分就是「重排没跑」或「这条没进重排」；有模型分而没 kept 就是被阈值丢了。
+              dropped: model !== undefined && !model.kept,
+            }]
+          })
+        })(),
+      }
+      : undefined
+
+    /** 每个数都是**这一段自己**的耗时（不是累计），量级差得远时一眼能看出是谁慢。 */
+    const timings: RecallTimings = {
+      ftsMs: round1(ftsMs),
+      vectorMs: round1(vectorMs),
+      ...(vectorOutcome.timings === undefined ? {} : { embedMs: round1(vectorOutcome.timings.embedMs), scanMs: round1(vectorOutcome.timings.scanMs) }),
+      graphMs: round1(graphMs),
+      fuseMs: round1(fuseMs),
+      ...(rerank.status === 'ready' ? { rerankMs: round1(performance.now() - rerankStarted) } : {}),
+      // 组装从「按卡片去重」算起（重排之后），所以它不含重排自己的时间。
+      assembleMs: round1(performance.now() - assembleStarted),
+      totalMs: round1(performance.now() - startedAt),
+    }
 
     const data: RecallResult = {
-      hits, context, wiki, graph, backend, routes: ranRoutes, recallMode, rerank, recallTopK, candidatePool, contextTopN,
-      insufficientEvidence, diagnostics, recallId,
+      hits, context: packed.items, wiki, graph, backend, routes: ranRoutes, recallMode, rerank, recallTopK, candidatePool, contextTopN,
+      insufficientEvidence, diagnostics, recallId, timings,
+      expansion, budget: packed.report,
+      ...(ledger === undefined ? {} : { ledger }),
       ...(indexVersion === undefined ? {} : { indexVersion }),
       ...(compileRunId === undefined ? {} : { compileRunId }),
       ...(eventLineage ? { lineage: eventLineage } : {}),
     }
     await this.audit('knowledge.recall', {
-      query: query.slice(0, 4000), count: hits.length, context: context.length, backend, routes: ranRoutes,
+      query: query.slice(0, 4000), count: hits.length, context: packed.items.length, backend, routes: ranRoutes,
       rerank: rerank.status, rerankThreshold: this.config.rerankThreshold, candidatePool,
       ...(rerank.dropped === undefined ? {} : { rerankDropped: rerank.dropped }),
       ...(rerank.topLogit === undefined ? {} : { rerankTopLogit: Number(rerank.topLogit.toFixed(4)) }),
@@ -2873,11 +5360,16 @@ export class KnowledgeRuntime {
    * 2. **量纲**：返回**原始余弦**，不再做 `(cos+1)/2` 的映射 —— 那个映射让 `0.15` 这类阈值
    *    失去意义（余弦 0 → 0.5，轻松过线）。原始余弦是绝对量，可以直接用于弃答。
    */
-  private async vectorRecall(query: string, eligibleIds: Set<string>, candidateLimit: number): Promise<Map<string, number>> {
+  private async vectorRecall(query: string, eligibleIds: Set<string>, candidateLimit: number): Promise<{ scores: Map<string, number>; embedMs: number; scanMs: number }> {
     const index = await this.loadVectorIndex()
     if (!index || index.manifest.itemCount === 0) throw new Error('VECTOR_INDEX_NOT_READY')
     if (index.manifest.provider !== this.config.embeddingProvider || index.manifest.model !== this.embeddingModelId || index.manifest.dimension !== this.config.embeddingDimension) throw new Error('VECTOR_INDEX_CONFIG_MISMATCH')
+    // 查询编码单独计时：模型没加载时这一段是 8 秒，加载之后是 0.3 秒 —— 这一段的
+    // 数字就是「测试为什么慢」的答案本身，混进扫描时间里就看不出来了。
+    const embedStarted = performance.now()
     const encoded = await this.encodeEmbeddings([{ text: query }])
+    const embedMs = performance.now() - embedStarted
+    const scanStarted = performance.now()
     const queryBinary = binaryVector(encoded.vectors[0]!, index.manifest.dimension)
     const queryInt8 = int8Vector(encoded.vectors[0]!, index.manifest.dimension)
     const binaryWidth = Math.ceil(index.manifest.dimension / 8)
@@ -2902,7 +5394,7 @@ export class KnowledgeRuntime {
       for (let dimension = 0; dimension < index.manifest.dimension; dimension += 1) dot += signedByte(queryInt8[dimension]!) * signedByte(index.int8[offset + dimension]!)
       scores.set(item.unitId, Math.max(-1, Math.min(1, dot / (127 * 127))))
     }
-    return scores
+    return { scores, embedMs, scanMs: performance.now() - scanStarted }
   }
 
   /**
@@ -2972,7 +5464,7 @@ export class KnowledgeRuntime {
         content,
         // 索引命中不了时退回按 id + 分类算出来的路径：那条路径**就是**写入时用的，
         // 所以它仍然指向真实文件（索引缺失只可能是并发写入还没失效缓存）。
-        path: index.get(slug(source.sourceId)) ?? this.sourcePath(source.sourceId, source.sourceType),
+        path: index.get(slug(source.sourceId)) ?? this.sourcePath(source.sourceId, source.sourceType, source.title),
         returnedChars: content.length,
         totalChars: source.content.length,
       })
@@ -2984,8 +5476,25 @@ export class KnowledgeRuntime {
 
   async graphQuery(action: 'entity' | 'neighbors' | 'path' | 'list' | 'types', entityId?: string, entityType?: string, depth = 1, options: { fromId?: string; toId?: string; status?: string; includeProblem?: boolean; limit?: number } = {}, lineage?: LineageContext): Promise<Envelope<Record<string, unknown>>> {
     const eventLineage = withRun(lineage, 'graph-query')
-    if (this.units.length === 0) await this.rebuild('all', eventLineage)
+    /**
+     * **读盘，不编译。**
+     *
+     * `units` 为空只说明这个 runtime 还没读过 `03_compiled/`，**不等于**盘上没有编译
+     * 产物：runtime 是按库缓存的，设置一变就被丢掉（`KnowledgeBases.invalidate()`），
+     * 下一次读图时内存里又是空的。原来的写法把这两种情况当成同一件事，在这里直接
+     * `rebuild('all')` —— 于是一次**读**变成一次全量编译：面板刷新时那个
+     * `GET /knowledge/graph` 在几百篇文档的库上要等 3~5 秒，而这段时间整个知识库面板
+     * 连同「类型定义」都是不可操作的。
+     *
+     * 编译是**写**动作，归「编译」按钮与 `POST /knowledge/rebuild`。读路径只如实报告
+     * 「盘上还没有编译产物」（`needsBuild`），要不要编由界面和 Agent 自己决定 ——
+     * 与 `recall` 同一条规矩：先读盘，读不到再说。
+     */
+    if (this.units.length === 0 && this.graph.nodes.length === 0) await this.loadCompiledState()
+    const needsBuild = this.units.length === 0 && this.graph.nodes.length === 0
     const attachLineage = (data: Record<string, unknown>): Record<string, unknown> => eventLineage ? { ...data, lineage: eventLineage } : data
+    /** 空图 + 一句为什么空：调用方（尤其是 Agent）不能把「还没编译」读成「这个库没有知识」。 */
+    const attachBuild = (data: Record<string, unknown>): Record<string, unknown> => needsBuild ? { ...data, needsBuild: true } : data
     if (depth < 1 || depth > 3) return failure({}, 'DEPTH_INVALID', 'depth 必须在 1 到 3 之间', false)
     const limit = options.limit ?? 50
     if (!Number.isInteger(limit) || limit < 1 || limit > 50) return failure({}, 'LIMIT_INVALID', 'limit 必须在 1 到 50 之间', false)
@@ -2998,7 +5507,7 @@ export class KnowledgeRuntime {
       .filter(node => !options.status || node.status === options.status)
     const nodes = allNodes.filter(node => !entityType || node.type === entityType)
     const edges = this.graph.edges.filter(edge => allNodes.some(node => `${node.type}:${node.id}` === String(edge.from)) && allNodes.some(node => `${node.type}:${node.id}` === String(edge.to)))
-    if (action === 'list') return success(attachLineage({ nodes: nodes.slice(0, limit), edges: edges.slice(0, limit) }))
+    if (action === 'list') return success(attachLineage(attachBuild({ nodes: nodes.slice(0, limit), edges: edges.slice(0, limit) })))
 
     const nodeKey = (rawId: string | undefined, rawType?: string): string | undefined => {
       if (!rawId) return undefined
@@ -3024,20 +5533,20 @@ export class KnowledgeRuntime {
         })
         for (const next of nextKeys) if (!visited.has(next)) { visited.add(next); queue.push({ key: next, path: [...current.path, next] }) }
       }
-      if (!found) return success(attachLineage({ path: [], nodes: [], edges: [] }))
+      if (!found) return success(attachLineage(attachBuild({ path: [], nodes: [], edges: [] })))
       return success(attachLineage({ path: found, nodes: allNodes.filter(node => found!.includes(`${node.type}:${node.id}`)), edges: edges.filter(edge => found!.includes(String(edge.from)) && found!.includes(String(edge.to))) }))
     }
 
     const id = nodeKey(entityId, entityType)
     if (!id) return failure({}, 'ENTITY_REQUIRED', '该 graph action 需要 entity_id', true)
-    if (action === 'entity') return success(attachLineage({ nodes: nodes.filter(node => `${node.type}:${node.id}` === id).slice(0, limit) }))
+    if (action === 'entity') return success(attachLineage(attachBuild({ nodes: nodes.filter(node => `${node.type}:${node.id}` === id).slice(0, limit) })))
     if (action === 'neighbors') {
       const ids = new Set([id])
       for (let index = 0; index < depth; index++) for (const edge of edges) {
         if (ids.has(String(edge.from))) ids.add(String(edge.to))
         if (ids.has(String(edge.to))) ids.add(String(edge.from))
       }
-      return success(attachLineage({ nodes: allNodes.filter(node => ids.has(`${node.type}:${node.id}`)).slice(0, limit), edges: edges.filter(edge => ids.has(String(edge.from)) || ids.has(String(edge.to))).slice(0, limit) }))
+      return success(attachLineage(attachBuild({ nodes: allNodes.filter(node => ids.has(`${node.type}:${node.id}`)).slice(0, limit), edges: edges.filter(edge => ids.has(String(edge.from)) || ids.has(String(edge.to))).slice(0, limit) })))
     }
     return failure({}, 'ACTION_INVALID', `不支持的 graph action: ${action}`, false)
   }