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

package/lib/types/runtime.js

@@ -1,25 +1,42 @@
 import { createHash } from 'node:crypto';
 import { spawn } 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 { appendFile, mkdir, readFile, readdir, rename, rm, rmdir, stat, unlink } from 'node:fs/promises';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 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, } from './types.js';
 import { defaultWikiTypes, validateCardAgainstType, WIKI_TYPE_RULES } from './wiki-types.js';
+import { LEGACY_ENTITY_TYPES } from './diagnosis/schema.js';
+import { CardProposalStore } from './proposals.js';
+import { DiagnosisStore } from './diagnosis/store.js';
 import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandidates, RELATES_TO } from './extract.js';
 import { extractWithModel } from './extract-model.js';
 import { FTS_FILE, FtsIndex, loadSqlite, segment } from './fts.js';
 import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, rrfFuse, selectContext, tokenSet } 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';
-// 05_diagnosis 是派生层（智能归因图谱）：内容可由 02_wiki + 03_compiled 重建，
-// 和 03_compiled 同性质，所以给独立编号段而不是塞进源头目录。
+// **知识树只有三段**（v1.1 起）：`01_source_truth` / `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'];
+// 撤掉的两段，理由都写在这里，避免下一个人重新加回来：
+//
+// - `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_truth/`），
+//   模板卡由类型定义派生（不落盘）。旧目录里的 `*.jsonl` 降为**只读的迁移输入与历史快照**。
+const LAYOUT = ['01_source_truth', '02_wiki', '03_compiled'];
+/**
+ * 卡片正文里那个机器可读块的围栏标记。
+ *
+ * 与 `diagnosis/cards.ts` 的 `BLOCK_FENCE` 是同一个字符串，但这里不能 import 它 ——
+ * 迁移要在**不解析卡片**的前提下改块里的一个字段名（旧块的 `failure_mode`），
+ * 而 `cards.ts` 的 `parseCard` 已经把旧字段名归一化了，读回来的对象里根本没有它。
+ */
+const DIAGNOSIS_BLOCK_FENCE = 'json diagnosis';
 /**
  * SourceRaw 段。段内**按来源分类再分一层**：`<段>/<source_type>/<docSlug>.md`。
  *
@@ -55,6 +72,16 @@ const VECTOR_QUANTIZATION = 'binary+hamming+int8';
 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';
 /**
@@ -101,6 +128,20 @@ const NOTE_SPLIT_MIN_CHARS = 800;
 const RELATION_QUERY_WORDS = {
     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）。
@@ -159,16 +200,43 @@ function slug(value) {
 function hash(value) { return createHash('sha256').update(value).digest('hex').slice(0, 24); }
 /** The content hash used for `KnowledgeDocument.contentHash` and version ids. */
 function contentHashOf(content) { return hash(content); }
+/** 候选的别名集合：判重认的是名字，不是卡片 id（中文名会退化成哈希 id）。 */
+function aliasesOf(candidate) {
+    return [...new Set([candidate.name, ...(candidate.aliases ?? [])].map(value => value.trim()).filter(Boolean))];
+}
 /**
- * 把这次新抽到的正文**追加**进已有卡片的正文。
+ * 把一次「并入已有卡片」累积进 `pending`。
  *
- * 这是「wiki 编译第二条链路」的落点：实体已经在 wiki 里 → 在原卡片上追加；不在 →
- * 新建一张。追加而不是覆盖，是因为覆盖会把别的来源贡献的内容删掉；而**丢弃**
- * （第一版的行为）更糟 —— 来源改写了，卡片却永远停在第一次抽取的样子。
- *
- * 已经在正文里出现过的那一段不再追加：同一份来源重建、或同一段被两个候选命中时，
- * 卡片不该越编译越长。判重按整段文本，所以它是幂等的。
+ * 已有卡片只读，所以累积的是**提议的正文**：`appendExtracted` 从卡片当时的正文出发，
+ * 把这一轮所有命中的正文依次追加进去。同一条提议被追加两次正文时不会重复
+ * （`appendExtracted` 自带 `includes` 判重）。
  */
+function mergeProposal(pending, card, sourceId, bodies, keys) {
+    const key = `${card.entityType}:${card.entityId}`;
+    const previous = pending.get(key);
+    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);
+    if (previous) {
+        previous.content = appendExtracted(previous.content, bodies);
+        if (!previous.sourceRefs.includes(sourceId))
+            previous.sourceRefs.push(sourceId);
+        previous.metadata = { ...previous.metadata, extraction_merges };
+        return;
+    }
+    pending.set(key, {
+        action: 'update',
+        entityType: card.entityType,
+        entityId: card.entityId,
+        title: card.title,
+        // **追加**而不是覆盖，也不是丢弃：实体已存在时，这次新抽到的正文并进原卡片，
+        // 于是知识是累积的，来源改写了也不会停在旧版本上。
+        content: appendExtracted(card.content, bodies),
+        sourceRefs: [...card.sourceRefs, sourceId],
+        metadata: { ...card.metadata, extraction_merges },
+        baseHash: contentHashOf(card.content),
+    });
+}
 function appendExtracted(existing, additions) {
     let content = existing;
     for (const addition of additions) {
@@ -218,9 +286,20 @@ function emptyDocumentDetail(docId) {
     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;
 function generatedId(prefix) { return `${prefix}_${hash(`${Date.now()}:${Math.random()}`)}`; }
 function parseLineage(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -285,41 +364,21 @@ export function parseMarkdown(source) {
     }
     return { frontmatter, content: source.slice(end + 4).trim() };
 }
+/**
+ * 把旧卡片结构化块里的 `failure_mode` 改成 `failure_reason`（0040 的第二次改名）。
+ *
+ * 只动那个围栏块里的键名，不动正文 —— 正文里出现「failure_mode」这个词完全可能是
+ * 有意写的（比如一张讲 FMEA 的卡片）。做字符串级替换而不是解析再序列化，是因为
+ * 解析会**丢掉格式**（缩进、键序），而迁移的第一条纪律是不制造无谓的 diff。
+ */
+function rewriteLegacyBlockFields(content) {
+    const pattern = new RegExp('(```' + DIAGNOSIS_BLOCK_FENCE + '\\s*\\n)([\\s\\S]*?)(```)');
+    return content.replace(pattern, (_all, head, body, tail) => head + body.replace(/"failure_mode"(\s*:)/g, '"failure_reason"$1') + tail);
+}
 function markdown(frontmatter, content) {
     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, content) {
-    // 原子写需要一个与目标同目录的临时文件，所以目标目录必须先存在。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, content) {
-    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) {
-    try {
-        const { unlink } = await import('node:fs/promises');
-        await unlink(path);
-    }
-    catch { /* rename already consumed the temp file */ }
-}
 async function filesUnder(root) {
     try {
         const entries = await readdir(root, { withFileTypes: true });
@@ -615,6 +674,12 @@ export class KnowledgeRuntime {
     sourceIndex;
     /** 段内布局整理是否已经跑过（每个 runtime 一次）。 */
     segmentsOrganized = false;
+    /**
+     * 一次性迁移里**没有静默处理掉**的事（改名冲突、迁移后比对不一致）。
+     *
+     * 它必须能被界面读到：迁移失败而没人知道，等价于数据已经丢了。
+     */
+    migrationProblems = [];
     vectorIndex = null;
     vectorError;
     embeddingWorker = null;
@@ -715,19 +780,179 @@ export class KnowledgeRuntime {
     }
     /**
      * Agent 与设置面板共用的类型目录：注册表 + 生效方式 + 内置只读判定规则 +
-     * 现有卡片的三层校验结果（`report` 模式下这是"待补"清单）。
+     * 现有卡片的三层校验结果（`report` 模式下这是"待补"清单）+ **待审提议的条数**。
+     *
+     * 提议计数挂在这里而不是另开一路，是因为 review 就发生在这一屏（「知识库 → Wiki」的
+     * 待办区）—— 与 Pass 0 的候选草案、lint 待补清单是同一处，不新造第二套 review 界面。
      */
     async wikiTypeCatalog() {
         const schema = this.wikiSchema();
         const issues = await this.lintCards();
+        const all = await this.cardProposals().list();
         return success({
             types: schema.types,
             mode: schema.mode,
             rules: WIKI_TYPE_RULES,
             issues: issues.slice(0, 50),
             issueCount: issues.length,
+            proposals: {
+                pending: all.filter(item => item.status === 'pending').length,
+                rejected: all.filter(item => item.status === 'rejected').length,
+                confirmed: all.filter(item => item.status === 'confirmed' && !item.writtenAt).length,
+            },
         });
     }
+    /**
+     * 智能归因图谱的存储句柄。
+     *
+     * 它由 runtime 自己构造（而不是由 index.ts 注入），因为 `rebuild` 要产出
+     * `03_compiled/diagnosis_graph.json` —— 那次产出必须和 `knowledge_graph.json`
+     * 在同一次卡片遍历的语义下发生，否则两份产物会来自两个不同版本的卡片。
+     */
+    diagnosis;
+    diagnosisStore() {
+        if (!this.diagnosis)
+            this.diagnosis = new DiagnosisStore(this, this.cardProposals());
+        return this.diagnosis;
+    }
+    /**
+     * 卡片提议的存储（0021 §6.1 的那道门）。
+     *
+     * 它按**记忆段**（`<agentRoot>/memory/<库 id>`）落，不在知识树里 —— 理由写在
+     * `proposals.ts` 顶上：提议是「关于 Agent 动作的待办留痕」，删掉只丢待办、
+     * 重跑一次提议就能回来，所以它既不属于「源头」（删了就丢数据的那一段），
+     * 更不能落 `02_wiki/`（那正是这道门要拦的事）。
+     */
+    proposalStore;
+    cardProposals() {
+        if (!this.proposalStore) {
+            this.proposalStore = new CardProposalStore({
+                memoryRoot: this.memoryDir,
+                schema: () => ({ types: this.wikiSchema().types }),
+            });
+        }
+        return this.proposalStore;
+    }
+    /* ────────────────────────────────────── 卡片提议：提议 → 确认 ── */
+    /**
+     * 提一批卡片提议。**它不写任何卡片**（0021 §6.1）。
+     *
+     * 这是 Agent 唯一能碰类型层的入口：把草案挂到触发它的那条 SourceRaw 上，
+     * 由人在面板上确认之后才落卡。未确认的提议不落 `02_wiki/`、不进编译、
+     * 不参与召回、不在图上出现。
+     */
+    async proposeCards(input) {
+        const empty = { proposed: 0, ids: [], rejected: [] };
+        if (!input.sourceId?.trim())
+            return failure(empty, 'SOURCE_REF_REQUIRED', '提议必须挂在一条触发它的 SourceRaw 上', 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.proposals) || input.proposals.length === 0) {
+            return failure(empty, 'PROPOSAL_EMPTY', '至少要提一条提议', true);
+        }
+        const schema = this.wikiSchema();
+        const rejected = [];
+        const accepted = input.proposals.filter(item => {
+            const type = schema.types.find(def => def.id === item.entityType);
+            if (!type) {
+                rejected.push(`${item.entityId}：未知卡片类型 ${item.entityType}`);
+                return false;
+            }
+            if (!type.enabled) {
+                rejected.push(`${item.entityId}：类型 ${item.entityType} 已停用`);
+                return false;
+            }
+            if (!SAFE_ID.test(item.entityId)) {
+                rejected.push(`${item.entityId}：entity_id 形状不合法`);
+                return false;
+            }
+            if (!item.title?.trim() || !item.content?.trim()) {
+                rejected.push(`${item.entityId}：title 与 content 都不能为空`);
+                return false;
+            }
+            return true;
+        });
+        const touched = await this.cardProposals().upsert(accepted.map(item => ({
+            sourceRef: input.sourceId,
+            trigger: 'agent',
+            action: item.action ?? 'create',
+            entityType: item.entityType,
+            entityId: item.entityId,
+            title: item.title.trim(),
+            ...(item.summary ? { summary: item.summary } : {}),
+            content: item.content,
+            sourceRefs: item.sourceRefs ?? [input.sourceId],
+            ...(item.metadata ? { metadata: item.metadata } : {}),
+        })));
+        return success({ proposed: touched.length, ids: touched.map(item => item.id), rejected }, rejected.length > 0 ? [`${rejected.length} 条提议被拒：${rejected.join('；')}`] : []);
+    }
+    /**
+     * 把一条**已确认**的提议落成卡片。
+     *
+     * 三道检查，缺一条这道门就有缝：
+     * 1. 提议存在，且状态是 `confirmed`（人点过「通过」）；
+     * 2. **还没落过卡**（`writtenAt` 为空）—— 确认凭证是**一次性**的；
+     * 3. 再跑一遍三层校验（0021 §6.5）：提议阶段那一遍是 Agent 自己补的，
+     *    这一遍的修改可能来自人，两道都跑才拦得住「改完又破了约束」。
+     */
+    async applyProposal(proposalId, lineage) {
+        const store = this.cardProposals();
+        const empty = { entityId: '', path: '', proposalId };
+        const proposal = await store.get(proposalId);
+        if (!proposal)
+            return failure(empty, 'CARD_PROPOSAL_NOT_FOUND', `提议不存在: ${proposalId}`, true);
+        if (proposal.status === 'pending') {
+            return failure(empty, 'CARD_PROPOSAL_NOT_CONFIRMED', `提议尚未经人确认: ${proposalId}`, false, '未确认的提议不落卡片 —— 这正是这道门的意义。请在「知识库 → Wiki」的待办区确认它。');
+        }
+        if (proposal.status === 'rejected') {
+            return failure(empty, 'CARD_PROPOSAL_REJECTED', `提议已被拒绝: ${proposalId}`, false, proposal.reason ? `拒绝原因：${proposal.reason}` : '被拒绝的提议不会再落卡；内容变了才会重新提。');
+        }
+        if (proposal.writtenAt) {
+            return failure(empty, 'CARD_PROPOSAL_ALREADY_WRITTEN', `提议已经落过卡: ${proposalId}`, false, '确认凭证是一次性的；要改卡片请直接改卡片，或重新提一条提议。');
+        }
+        const written = await this.writeCard({
+            entityType: proposal.entityType,
+            entityId: proposal.entityId,
+            title: proposal.title,
+            content: proposal.content,
+            sourceRefs: proposal.sourceRefs,
+            ...(proposal.summary ? { summary: proposal.summary } : {}),
+            ...(proposal.metadata ? { metadata: proposal.metadata } : {}),
+            ...(lineage ? { lineage } : {}),
+        });
+        if (written.ok === false)
+            return failure(empty, written.error.code, written.error.message, written.error.retryable, written.error.suggestion);
+        await store.markWritten(proposalId);
+        return success({ entityId: proposal.entityId, path: written.data.path, proposalId });
+    }
+    /**
+     * 人的 review 动作（面板调用，**不是工具**）。
+     *
+     * Agent 拿不到这个入口 —— 它只能 `proposeCards` 与 `applyProposal`，而后者要求
+     * 一条已经被人确认过的提议。确认权收在人手里，这是 §6.1 那条硬规则的结构保证。
+     */
+    async reviewProposal(input) {
+        const store = this.cardProposals();
+        const reviewer = input.reviewer?.trim() || 'user:panel';
+        const empty = { proposalId: input.proposalId, status: '', written: false };
+        if (input.action === 'reject') {
+            const rejected = await store.reject(input.proposalId, input.reason ?? '', reviewer);
+            if (!rejected)
+                return failure(empty, 'CARD_PROPOSAL_NOT_FOUND', `提议不存在或已不在待审状态: ${input.proposalId}`, true);
+            return success({ proposalId: rejected.id, status: rejected.status, written: false });
+        }
+        const confirmed = await store.confirm(input.proposalId, reviewer, input.patch);
+        if (!confirmed)
+            return failure(empty, 'CARD_PROPOSAL_NOT_FOUND', `提议不存在或已不在待审状态: ${input.proposalId}`, true);
+        if (input.action === 'confirm')
+            return success({ proposalId: confirmed.id, status: confirmed.status, written: false });
+        const applied = await this.applyProposal(confirmed.id, input.lineage);
+        if (applied.ok === false)
+            return failure(empty, applied.error.code, applied.error.message, applied.error.retryable, applied.error.suggestion);
+        return success({ proposalId: confirmed.id, status: 'confirmed', written: true });
+    }
     /** 对已落库的卡片跑三层校验。不写盘，只报告。 */
     async lintCards() {
         const schema = this.wikiSchema();
@@ -824,7 +1049,9 @@ export class KnowledgeRuntime {
         if (!this.segmentsOrganized) {
             this.segmentsOrganized = true;
             await this.migrateSourceTruthLayout();
-            await this.dropLegacySchemaSegment();
+            await this.dropRetiredSegments();
+            await this.migrateLegacySourceTypeRename();
+            await this.migrateLegacyDiagnosisCards();
         }
     }
     /**
@@ -874,8 +1101,36 @@ export class KnowledgeRuntime {
      * 有人放了文件，那就不属于「没用的空文件夹」了 —— 那种情况下留着并让人自己判断，
      * 比替他们删掉安全。
      */
-    async dropLegacySchemaSegment() {
-        const path = this.safePath('00_schema');
+    /**
+     * 清掉**只装了旧版本自己生成的东西**的退役段。
+     *
+     * `00_schema` 从来没有一行代码写过东西，所以「空」就是它的全部历史形态 —— 空就删。
+     *
+     * `05_diagnosis` 不一样：旧版本在里面铺过 `templates/*.md` 与一份 README，那两样是
+     * 可以重建的（模板由类型定义派生、README 是说明），删掉不丢知识。但同一个目录里
+     * 可能躺着**真正的历史快照**（`*.jsonl` / `cases.json`），那是只读的迁移输入，
+     * 一个字节都不能动。所以判据是**文件清单**而不是「空不空」：只认得旧版本自己写的
+     * 那些名字时，才删；出现任何别的东西就整个留着。
+     */
+    async dropRetiredSegments() {
+        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 { /* 不存在或删不掉都不是错误 */ }
+    }
+    async dropSegmentIfEmpty(name) {
+        const path = this.safePath(name);
         try {
             const entries = await readdir(path);
             if (entries.length > 0)
@@ -887,6 +1142,171 @@ export class KnowledgeRuntime {
         }
         catch { /* 不存在、非空、或删不掉都不是错误 */ }
     }
+    /**
+     * 0040 §3.2 的一次性迁移：`01_source_truth/ai_chat_message/` → `agent_chat_message/`。
+     *
+     * 改名不能只改注册表：`01_source_truth/` 是**按分类分目录**的，存量来源的
+     * frontmatter 里写着 `source_type: ai_chat_message`。只改注册表会有两个后果 ——
+     * 旧目录里那些来源变成一个「注册表里没有的分类」（界面上显示成未知分类），
+     * 而旧分类因为还有来源在，永远删不掉。
+     *
+     * 三条纪律：
+     * 1. **逐份搬，不整体 rename 目录。** 目标里可能已经有同名文件（用户在新版本里
+     *    重新录过同一份来源），整体搬会覆盖它。
+     * 2. **同名时比对正文**：一致就删掉旧的那份（同一份东西，只是目录名变了）；
+     *    不一致就**两边都留**，并把冲突报给界面 —— 静默覆盖等于丢数据。
+     * 3. **迁移无损才认**：写完读回来比对 frontmatter 与正文，不一致就放弃这一份。
+     */
+    async migrateLegacySourceTypeRename() {
+        const from = this.safePath(SOURCE_TRUTH, 'ai_chat_message');
+        const to = this.safePath(SOURCE_TRUTH, 'agent_chat_message');
+        let names;
+        try {
+            names = await readdir(from);
+        }
+        catch {
+            return;
+        }
+        const conflicts = [];
+        for (const name of names) {
+            if (extname(name).toLowerCase() !== '.md')
+                continue;
+            const source = join(from, name);
+            let raw;
+            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;
+            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, source_type: 'agent_chat_message' }, parsed.content));
+            const roundTrip = parseMarkdown(await readFile(target, 'utf8'));
+            if (roundTrip.content.trim() !== parsed.content.trim() || roundTrip.frontmatter.source_type !== '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_truth/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：它是唯一知道卡片信封长什么样、并且会
+     * 顺手做版本快照与三层校验的地方。
+     */
+    async migrateLegacyDiagnosisCards() {
+        const root = this.safePath(WIKI, 'diagnosis');
+        let kinds;
+        try {
+            kinds = await readdir(root);
+        }
+        catch {
+            return;
+        }
+        /**
+         * 目录名是 `entity_type` 的**命名空间之后那一段**（`02_wiki/diagnosis/check/` 对应
+         * `diagnosis/check`）。用后缀匹配而不是拿 `entity_type` 直接比目录名 —— 直接比的话
+         * 一个都匹配不上，而失败方式是静默的：迁移什么都没做，卡片仍按旧类型读。
+         */
+        const legacyByDir = new Map();
+        for (const [legacy, next] of Object.entries(LEGACY_ENTITY_TYPES)) {
+            legacyByDir.set(legacy.slice(legacy.indexOf('/') + 1), next);
+        }
+        const problems = [];
+        for (const dir of kinds) {
+            const legacyDir = join(root, dir);
+            const renamedType = legacyByDir.get(dir);
+            // 类型没改名、也不在旧目录里的子树也要扫一遍：块字段名的改名与类型无关。
+            for (const file of await filesUnder(legacyDir)) {
+                let raw;
+                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,
+                    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)) ? String(parsed.frontmatter.status) : 'unreviewed'),
+                    ...(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 : {},
+                });
+                if (written.ok === false) {
+                    problems.push(`卡片 ${entityId} 从 ${currentType || dir} 迁到 ${nextType} 失败（${written.error.code}），旧文件保留`);
+                    continue;
+                }
+                // 读回来确认它真的落在新目录、而且认得出新类型，再删旧的。
+                const readBack = await this.readCard(entityId, nextType);
+                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);
+    }
     async loadVectorIndex() {
         if (this.vectorIndex)
             return this.vectorIndex;
@@ -1129,6 +1549,12 @@ export class KnowledgeRuntime {
                 this.graph = 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;
+        }
+        catch { /* 归因图还没编过（这个库没做过排查），或者旧版本没有这个产物 */ }
     }
     safePath(...parts) {
         const path = resolve(this.rootDir, ...parts);
@@ -1189,6 +1615,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,
@@ -1388,8 +1820,14 @@ export class KnowledgeRuntime {
         }
         return assets.sort((left, right) => left.rel.localeCompare(right.rel));
     }
-    /** Parse one on-disk SourceRaw file into the detail projection. */
-    async readDocumentFile(path) {
+    /**
+     * Parse one on-disk SourceRaw file into the detail projection.
+     *
+     * `previewChars` 给了就把正文截到那么长，并把**总长度**如实放进 `contentChars`
+     * （见 `SOURCE_PREVIEW_CHARS` 的理由）。不给就是不截断 —— 那是「我确实要全文」的
+     * 调用方，目前只有 `readDocumentBody()` 之外的内部路径会这么用。
+     */
+    async readDocumentFile(path, previewChars) {
         let raw;
         try {
             raw = await readFile(path, 'utf8');
@@ -1398,6 +1836,8 @@ export class KnowledgeRuntime {
             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');
         // 未知分类照样投影出来（0013）；前端按 sourceTypeKnown 渲染「未知分类」徽标。
@@ -1433,7 +1873,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 } : {}),
@@ -1457,9 +1899,32 @@ export class KnowledgeRuntime {
         return documents.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.docId.localeCompare(right.docId));
     }
     /** 文档详情：正文、frontmatter、资产与 lineage。 */
-    async readDocument(docId) {
+    /**
+     * 一份文档的详情投影，**正文默认按 `SOURCE_PREVIEW_CHARS` 封顶**。
+     *
+     * 这是明细接口（抽屉里的预览）读的那一份，所以默认就是「够预览」而不是「全文」：
+     * 全文由 `readDocumentBody()` 提供服务，而它只服务独立整页的分页读取。
+     */
+    async readDocument(docId, previewChars = SOURCE_PREVIEW_CHARS) {
+        const path = await this.sourcePathOf(docId);
+        return path ? this.readDocumentFile(path, previewChars) : undefined;
+    }
+    /**
+     * 一份文档的**完整正文**（不含 frontmatter），给独立整页分页取用。
+     *
+     * 每次调用都重读一遍盘：独立整页是「用户滚到哪儿取哪一页」，一次请求一段文本，
+     * 谁都不该拿到整份文档 —— 这正是抽屉那一版的问题。缓存留到真的量出来是瓶颈再加。
+     */
+    async readDocumentBody(docId) {
         const path = await this.sourcePathOf(docId);
-        return path ? this.readDocumentFile(path) : undefined;
+        if (path === undefined)
+            return undefined;
+        try {
+            return parseMarkdown(await readFile(path, 'utf8')).content;
+        }
+        catch {
+            return undefined;
+        }
     }
     /**
      * 版本历史，新→旧。
@@ -1520,7 +1985,7 @@ export class KnowledgeRuntime {
         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() : '';
@@ -1543,7 +2008,7 @@ export class KnowledgeRuntime {
         });
         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);
+        const document = await this.readDocumentFile(path, SOURCE_PREVIEW_CHARS);
         if (!document)
             return failure(head, 'DOCUMENT_NOT_FOUND', `回滚后文档不可读: ${docId}`, true);
         await this.audit('source_truth.revert', { docId, versionId: target });
@@ -1910,7 +2375,7 @@ export class KnowledgeRuntime {
     emptyExtractionOutcome(extractionHashes) {
         return {
             extractionHashes,
-            candidatesExtracted: 0, candidatesRejected: 0, cardsCreated: 0, cardsMerged: 0,
+            candidatesExtracted: 0, candidatesRejected: 0, proposalsCreated: 0, proposalsMerged: 0,
             sourcesExtracted: 0, sourcesSkipped: 0, relations: [], relationsBySource: {}, warnings: [],
         };
     }
@@ -1936,7 +2401,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();
+        /**
+         * 库里的卡片是**只读的参照物**：这一轮不再往里加东西，抽到的一切都进 `pending`。
+         * 整轮结束才一次性 upsert —— 同一张卡片被多份来源命中时只有一条提议，
+         * 正文累积（而不是产生 N 条互相打架的提议）。
+         */
+        const cards = await this.loadCards();
+        const pending = new Map();
         for (const source of ordered) {
             const fingerprint = this.extractionFingerprint(source, registryHash);
             outcome.extractionHashes[source.sourceId] = fingerprint;
@@ -1951,12 +2422,35 @@ export class KnowledgeRuntime {
             }
             outcome.sourcesExtracted += 1;
             try {
-                cards = await this.extractFromSource(source, cards, enabledTypes, outcome);
+                await this.proposeFromSource(source, cards, enabledTypes, outcome, pending);
             }
             catch (cause) {
                 outcome.warnings.push(`来源 ${source.sourceId} 的候选抽取失败，已跳过该来源：${cause instanceof Error ? cause.message : String(cause)}`);
             }
         }
+        /**
+         * 落**提议**，不是卡片。
+         *
+         * `upsert` 会按内容指纹判重：人已经拒绝过、而且内容没变的那一条不会再冒出来；
+         * 人已经确认过、而且内容没变的那一条也不会再问一遍。计数取自它真正写下的那些，
+         * 而不是 `pending` 的大小 —— 报告里的数字必须是「这次真的发生了什么」。
+         */
+        if (pending.size > 0) {
+            const touched = await this.cardProposals().upsert([...pending.values()].map(item => ({
+                sourceRef: item.sourceRefs[0] ?? `kb:${item.entityType}`,
+                trigger: 'extraction',
+                action: item.action,
+                entityType: item.entityType,
+                entityId: item.entityId,
+                title: item.title,
+                content: item.content,
+                sourceRefs: item.sourceRefs,
+                ...(item.metadata ? { metadata: item.metadata } : {}),
+                ...(item.baseHash ? { baseHash: item.baseHash } : {}),
+            })));
+            outcome.proposalsCreated = touched.filter(item => item.action === 'create').length;
+            outcome.proposalsMerged = touched.filter(item => item.action === 'update').length;
+        }
         // 只留这一轮真实存在的来源：删掉的文档不该在图上留下幽灵关系。
         const alive = new Set(ordered.map(source => source.sourceId));
         const next = {};
@@ -2003,8 +2497,16 @@ export class KnowledgeRuntime {
         }
         catch { /* 写不进去就当这一轮没有产物，下一次重建会重新抽 */ }
     }
-    /** 一份来源的抽取结果：新建候选卡片、把证据来源并进已有卡片、收集关系候选。 */
-    async extractFromSource(source, cards, enabledTypes, outcome) {
+    /**
+     * 一份来源的抽取结果：**产出提议**（新建 / 更新），并收集关系候选。
+     *
+     * 它**不再写卡片**。这是 v1.5 那道门最容易被绕开的地方：Pass 0 是一次自动流程，
+     * 它写进 `02_wiki/` 的东西会立刻参与编译、进图、被召回 —— 而类型层是收敛的那一层，
+     * 它错一条，所有现象的排序一起错。所以这里只往 `pending` 里放提议，
+     * 由 `runExtractionStage` 在整轮结束时一次性 upsert（同一张卡片被多份来源命中时，
+     * 只有一条提议，正文累积）。
+     */
+    async proposeFromSource(source, cards, enabledTypes, outcome, pending) {
         /**
          * #3b：**模型先抽实体，规则补关系。**
          *
@@ -2028,30 +2530,35 @@ export class KnowledgeRuntime {
                 normalized = { fresh: modelled.fresh, merges: modelled.merges, relations: ruleNormalized.relations };
             }
         }
-        const candidates = normalized.fresh;
-        if (candidates.length === 0 && normalized.merges.length === 0)
-            return cards;
-        const next = [...cards];
-        // 先建后并：同一轮里新建的卡片也可能被别名指回，先建才能让后面的合并找得到对象。
         for (const candidate of normalized.fresh) {
             /**
-             * 候选**必须带正文**才落卡。
+             * 候选**必须带正文**才提提议。
              *
              * 0029 实跑发现：这里原来在候选没有正文时拿 `type.template` 顶上，于是
              * `[[链接]]` 指到、但还没人写过的实体（那时链接候选确实没有正文）会落成一张
              * **正文是模板**的卡片，而模板里的「（必填：写什么）」会被编进 wikiNotes、
              * 被召回、被塞进模型的上下文包 —— 管线写出了一张它自己的校验器判为不合格的
              * 卡片。链接候选现在会带上它所在小节的正文（`extract.ts`），所以这条回退基本
-             * 不会被走到；真走到了就**不落卡**，并如实计数：没有正文 = 没有可说的。
+             * 不会被走到；真走到了就**不提**，并如实计数：没有正文 = 没有可说的。
              */
             const body = candidate.body?.trim() ?? '';
             if (!body) {
                 outcome.candidatesRejected += 1;
-                outcome.warnings.push(`候选「${candidate.name}」没有任何正文（只在别处被提到，所在小节也没取到），不落卡`);
+                outcome.warnings.push(`候选「${candidate.name}」没有任何正文（只在别处被提到，所在小节也没取到），不提提议`);
+                continue;
+            }
+            /**
+             * 类型必须来自注册表。抽到一个没登记的类型时**不提这条提议** —— 提议的正文与
+             * 小节骨架都按类型的 schema 校验，而未知类型没有 schema，人 review 时只能拒掉它。
+             * 与其往待办队列里塞一条注定被拒的东西，不如当场记一笔并说清原因。
+             */
+            if (!enabledTypes.some(def => def.id === candidate.type)) {
+                outcome.candidatesRejected += 1;
+                outcome.warnings.push(`候选「${candidate.name}」未提议（SCHEMA_TYPE_INVALID）：类型 ${candidate.type} 未登记或已停用`);
                 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 = `${candidate.type}:${entityId}`;
             const metadata = {
                 extraction: 'pass0',
                 candidate_kind: candidate.kind,
@@ -2060,77 +2567,42 @@ export class KnowledgeRuntime {
                     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) } : {}),
             };
-            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 = cards.find(card => card.entityId === entityId && card.entityType === candidate.type);
+            if (existing) {
+                mergeProposal(pending, existing, candidate.evidence.sourceId, [body], [candidate.name]);
+                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);
                 continue;
             }
-            outcome.cardsCreated += 1;
-            next.push({
-                entityId: written.data.entityId,
+            pending.set(key, {
+                action: 'create',
                 entityType: candidate.type,
+                entityId,
                 title: candidate.name,
-                status: 'unreviewed',
                 content: body,
                 sourceRefs: [candidate.evidence.sourceId],
                 metadata,
-                updatedAt: '',
             });
         }
-        // 归一：命中的候选把证据来源并进已有卡片。同一张卡片在这一轮里的多次命中合并且只写一次。
-        const targets = new Map();
+        // 归一：命中的候选把证据来源并进已有卡片。同一张卡片在这一轮里的多次命中合并成一条提议。
         for (const merge of normalized.merges) {
-            const card = next.find(item => item.entityId === merge.entityId && item.entityType === merge.entityType);
+            const card = cards.find(item => item.entityId === merge.entityId && item.entityType === merge.entityType);
             if (!card)
                 continue;
-            // 「只在没有的时候追加」：来源已在 source_refs 里就什么都不做 —— 空写也会
-            // 刷新 updated_at，并让「并入了多少张卡」这个计数变成谎话。
+            // 「只在没有的时候追加」：来源已在 source_refs 里就什么都不做 —— 空提一条提议
+            // 也会让「并入了多少张卡」这个计数变成谎话。
             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 ?? ''}`);
-                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 } };
+            mergeProposal(pending, card, merge.sourceId, [merge.body], [merge.key]);
         }
         outcome.relations.push(...normalized.relations);
         // 按来源存一份：跳过的来源下次重建要靠它把关系读回来（见 EXTRACTED_RELATIONS）。
@@ -2138,7 +2610,6 @@ export class KnowledgeRuntime {
             ...(outcome.relationsBySource[source.sourceId] ?? []),
             ...normalized.relations,
         ];
-        return next;
     }
     /**
      * 把关系候选装配成 wiki↔wiki 的边。
@@ -2196,13 +2667,11 @@ export class KnowledgeRuntime {
             : this.emptyExtractionOutcome(previousExtractionHashes);
         // 抽取刚落过盘：stage 2 必须看到新的卡片清单，否则这一轮建的卡片要等下一次
         // 重建才进 wikiNotes，用户点了编译却召不回刚抽出来的东西。
-        if (extraction.cardsCreated > 0 || extraction.cardsMerged > 0)
-            this.cards = await this.loadCards();
         const extractionCounts = {
             candidatesExtracted: extraction.candidatesExtracted,
             candidatesRejected: extraction.candidatesRejected,
-            cardsCreated: extraction.cardsCreated,
-            cardsMerged: extraction.cardsMerged,
+            proposalsCreated: extraction.proposalsCreated,
+            proposalsMerged: extraction.proposalsMerged,
             sourcesExtracted: extraction.sourcesExtracted,
             sourcesSkipped: extraction.sourcesSkipped,
         };
@@ -2276,7 +2745,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;
             if (!corpusChanged) {
                 const compileRunId = `rebuild_${hash(`${startedAt}:${this.cards.length}`)}`;
                 const report = {
@@ -2297,7 +2778,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, 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));
                 return success(report, ['知识库没有变化：已复用全部 wikiNotes，未生成新的索引版本。', ...extraction.warnings]);
             }
             const nodeMap = new Map();
@@ -2321,6 +2802,14 @@ 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, edges: diagnosis.edges };
+            await writeTextAtomic(this.safePath('03_compiled', DIAGNOSIS_GRAPH), JSON.stringify({ version, builtAt, nodes: diagnosis.nodes, edges: diagnosis.edges }, null, 2));
             // 关键词索引跟着 notes 一起落盘（0031）：它的输入就是 notes，两者必须同时有效，
             // 否则会出现「卡片改了、关键词路还按旧词表召回」。它不依赖编码器，所以 wiki-only
             // 重建也要重建它 —— 而向量是 stage 3，仍然只在 `embeddings`/`all` 时重算。
@@ -2330,7 +2819,7 @@ export class KnowledgeRuntime {
             // re-encode of the whole corpus.
             const embeddingResult = only === 'all' ? await this.buildVectorIndex(this.units, version) : { status: 'skipped', 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, diagnosisGraph: { nodes: diagnosis.nodes.length, edges: diagnosis.edges.length }, lastBuild: { only, incremental: cardsReused > 0, skipped: false, cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount, notesReused, notesRecompiled, ...extractionCounts, relationsExtracted, relationsDropped }, ...(lineage ? { lineage } : {}) }, null, 2));
             const report = {
                 runId: compileRunId, compileRunId, version, only,
                 cards: this.cards.length, units: this.units.length, notes: this.units.length,
@@ -2545,7 +3034,67 @@ export class KnowledgeRuntime {
      * 匹配逻辑与 0030 相同（词面匹配节点 title / id 与关系词，命中节点带出 1 跳邻居并衰减），
      * 但返回值只用于给**已经在候选池里**的条目加权 —— 它自己不能制造候选。
      */
-    graphBoostRanking(query, eligible, includeProblems) {
+    /**
+     * 字段级的归因图（`03_compiled/diagnosis_graph.json`）。
+     *
+     * 它只用于**给已经在候选池里的条目加权**（和卡片级图一样，不能自己制造候选）。
+     * 用途是把「假设 → 检查点」「证据 → 假设」这两类卡片级图看不见的语义带进召回。
+     */
+    diagnosisGraph = { nodes: [], edges: [] };
+    /**
+     * 归因图上按词面命中的节点 → 分数，含 1 跳衰减。
+     *
+     * 与卡片级那一段是**同一条算法、两份数据**：卡片级图里只有 `supported_by` /
+     * `relates_to`，而字段级图里是十种语义边。分开算再按 `entityId` 合流，
+     * 是因为两张图的节点含义不同（一个是卡片，一个是字段级节点），合成一张会让
+     * 图谱 Tab 看到一张卡片散成七个点。
+     */
+    diagnosisHits(queryTokens) {
+        const seed = new Map();
+        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(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;
+    }
+    async graphBoostRanking(query, eligible, includeProblems) {
         if (this.graph.nodes.length === 0)
             return [];
         const queryTokens = segment(query);
@@ -2555,6 +3104,10 @@ export class KnowledgeRuntime {
         const boost = (key, score) => { byNodeKey.set(key, Math.max(byNodeKey.get(key) ?? 0, score)); };
         const visible = (node) => includeProblems || node.status !== 'problem';
         const nodeKey = (node) => `${String(node.type)}:${String(node.id)}`;
+        /** 卡片级节点 id → 它的 `entity_type`。归因图的节点 id 与卡片 id 相等（§14.1）。 */
+        const typeByEntityId = new Map();
+        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;
@@ -2582,6 +3135,19 @@ export class KnowledgeRuntime {
                 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(byNodeKey);
@@ -2711,7 +3277,7 @@ export class KnowledgeRuntime {
         const vectorOutcome = useVector
             ? await this.vectorRoute(query, eligibleIds, candidatePool, this.config.vectorThreshold)
             : { ranking: [], diagnostic: { route: 'vector', status: 'skipped', reason: '当前模式未启用向量路' }, health: { ok: false, reason: '当前模式未启用向量路' } };
-        const graphRanking = useGraphBoost ? this.graphBoostRanking(query, eligible, includeProblems) : [];
+        const graphRanking = useGraphBoost ? await this.graphBoostRanking(query, eligible, includeProblems) : [];
         if (ftsOutcome.diagnostic.status === 'degraded' && ftsOutcome.diagnostic.reason)
             warnings.push(ftsOutcome.diagnostic.reason);
         if (vectorOutcome.diagnostic.status === 'degraded' && vectorOutcome.diagnostic.reason)
@@ -2941,9 +3507,26 @@ export class KnowledgeRuntime {
     }
     async graphQuery(action, entityId, entityType, depth = 1, options = {}, lineage) {
         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) => eventLineage ? { ...data, lineage: eventLineage } : data;
+        /** 空图 + 一句为什么空：调用方（尤其是 Agent）不能把「还没编译」读成「这个库没有知识」。 */
+        const attachBuild = (data) => needsBuild ? { ...data, needsBuild: true } : data;
         if (depth < 1 || depth > 3)
             return failure({}, 'DEPTH_INVALID', 'depth 必须在 1 到 3 之间', false);
         const limit = options.limit ?? 50;
@@ -2959,7 +3542,7 @@ export class KnowledgeRuntime {
         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) }));
+            return success(attachLineage(attachBuild({ nodes: nodes.slice(0, limit), edges: edges.slice(0, limit) })));
         const nodeKey = (rawId, rawType) => {
             if (!rawId)
                 return undefined;
@@ -2998,14 +3581,14 @@ export class KnowledgeRuntime {
                     }
             }
             if (!found)
-                return success(attachLineage({ path: [], nodes: [], edges: [] }));
+                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) }));
+            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++)
@@ -3015,7 +3598,7 @@ export class KnowledgeRuntime {
                     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);
     }