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

package/lib/types/diagnosis/store.js

@@ -1,37 +1,38 @@
-import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { SEED_CASES, SEED_GRAPH } from './seed.js';
 import { seedSources } from './seed-source.js';
-import { DIAGNOSIS_ENTITIES, templateCard, validateDiagnosis } from './schema.js';
-import { cardsToGraph, cardPathOf, graphToCards, parseCard, serializeCard, RUN_EDGE_KINDS, } from './cards.js';
+import { validateDiagnosis } from './schema.js';
+import { cardsToGraph, CARD_EDGE_KINDS, graphToCards, parseCard, serializeCard, RUN_EDGE_KINDS, } from './cards.js';
+import { caseCardOf, parseRunSource, renderRunSource, runReferenceProblems, runToGraph } from './run.js';
 /**
- * `05_diagnosis/` 的落盘与读取（v0.7 起：**卡片才是真相，这里只放一次排查的产物**）。
+ * 排查知识的读取与写入（v1.1 起：**没有 `05_diagnosis/` 了**）。
  *
- * ## 为什么要改
- *
- * 改版前这里同时扮演两个角色：既是 seed 写出来的 jsonl 数据集，又被当成图的唯一来源。
- * 后果是排查思路**从来没进过 wiki** —— 不在 `01_source_truth`、不是 `02_wiki` 的卡片、
- * 编译器不认它的 entity_type，于是不会被 wikiNote 化、不会进向量索引，**永远召不回来**。
- * 而 `store.ts` 顶上那句「全部内容都能从 wiki 卡片确定性重建」描述的其实是目标状态，
- * 代码走的是相反的路径。
- *
- * ## 现在的分工
+ * ## 三段，各一个答案
  *
  * | 目录 | 内容 | 谁是真相 |
  * | --- | --- | --- |
- * | `01_source_truth/` | 手册与复盘原文（`sourceType=question`） | 人写的原始材料 |
- * | `02_wiki/diagnosis/` | 五类卡片（三段式） | **知识侧的唯一真相** |
- * | `05_diagnosis/` | `evidence` / `cause` / 执行边（`produces` `supports` `refutes` `confirmed_as`）与模板卡 | 一次排查的产物 |
+ * | `01_source_raw/question/` | 手册与复盘原文 | 人写的原始材料 |
+ * | `01_source_raw/agent_diagnosis_case/` | 一次排查的过程记录（一条 SourceRaw） | Agent 跑出来的原始记录 |
+ * | `02_wiki/diagnosis/` | 五类卡片（三段式） | **知识侧的唯一真相**，由一次排查 / 载入示例 / 迁移直接写入（0044 起不经人确认） |
+ *
+ * `05_diagnosis/` 在 v1.1 撤销了（0021 §0.3）。它同时装着两类东西 —— 「一次排查的产物」
+ * （源头）与「五类模板卡」（配置）—— 一个编号段混装两种性质，`rebuild --only` 的语义
+ * 立刻含糊。而且它自造的 jsonl 过不了 `source_refs` 那道门：卡片要求引用**真实存在的
+ * SourceRaw**，jsonl 不是。
+ *
+ * 旧的 `05_diagnosis/*.jsonl` 因此降为**只读的迁移输入与历史快照**：还在，还能读，
+ * 但不再被写、也不再是任何东西的真相。
+ *
+ * ## 读取顺序是显式的（`snapshot().source` 会把它报给界面）
  *
- * 读取顺序是显式的：**有卡片就编译卡片；没有卡片但有旧 jsonl 就按旧格式读出来（并尝试
- * 前向迁移）；两者都没有才灌 seed**。老知识根不会因为这次改动而读不出内容。
+ * 1. 有卡片 → 卡片 + 一次排查的 SourceRaw；
+ * 2. 没有卡片但有旧 jsonl → 按旧格式读出来（并尝试**无损**前向迁移）；
+ * 3. 两者都没有 → **什么都不写**：空态 + 「载入内置示例」按钮。
  */
-const DIR = '05_diagnosis';
-/** 一次排查写下的节点：它们不是知识，所以留在这里，不进卡片。 */
-const RUN_NODE_SHARDS = {
-    'evidence.jsonl': 'evidence',
-    'causes.jsonl': 'cause',
-};
+const LEGACY_DIR = '05_diagnosis';
+/** 一次排查的产物：`01_source_raw/<这个分类>/`。 */
+const RUN_SOURCE_TYPE = 'agent_diagnosis_case';
 /**
  * 旧版的类型层分片。**只读，不再写**：v0.7 之前它们就是真相，现在它们的角色是
  * 「迁移输入 + 历史快照」。迁移成功后内容已经在卡片里，这些文件保持原样以便追溯。
@@ -39,28 +40,22 @@ const RUN_NODE_SHARDS = {
 const LEGACY_SHARDS = {
     'symptoms.jsonl': 'symptom',
     'hypotheses.jsonl': 'hypothesis',
-    'checks.jsonl': 'check',
-    'failure-modes.jsonl': 'failure-mode',
+    'checks.jsonl': 'check_point',
+    'failure-modes.jsonl': 'failure_reason',
     'assets.jsonl': 'asset',
     'cases.jsonl': 'case',
 };
-const README = `# 05_diagnosis
-
-这个目录**只放一次排查的产物**（\`evidence\` / \`cause\` / 执行边），以及新人照抄的模板卡。
-
-排查思路本身（现象 / 假设 / 检查 / 失败模式 / 案例）现在是 **wiki 卡片**，住在
-\`02_wiki/diagnosis/\`，出处是 \`01_source_truth/\` 里的手册与复盘。图由卡片编译而来 ——
-所以改知识要改卡片（或改它的来源文档再重新编译），不要改这里。
-
-\`*.jsonl\` 里若出现 \`symptoms\` / \`hypotheses\` / \`checks\` / \`failure-modes\` / \`assets\`
-等分片，那是 v0.7 之前的历史快照：版本升级时被读出来迁移成了卡片，之后不再更新。
-`;
+/** 一次排查写下的节点（旧格式）。同样只读。 */
+const LEGACY_RUN_SHARDS = {
+    'evidence.jsonl': 'evidence',
+    'causes.jsonl': 'cause',
+};
 export class DiagnosisStore {
     host;
     constructor(host) {
         this.host = host;
     }
-    get dir() { return join(this.host.rootDir, DIR); }
+    get legacyDir() { return join(this.host.rootDir, LEGACY_DIR); }
     get cardsDir() { return join(this.host.rootDir, '02_wiki', 'diagnosis'); }
     /**
      * 幂等初始化。三种状态各自处理，互不覆盖：
@@ -69,84 +64,149 @@ export class DiagnosisStore {
      * 2. 没有卡片但有旧 jsonl → **前向迁移**：把旧图反推成卡片写出去，并**校验迁移无损**
      *    （重新编译一遍与旧图比对，不一致就不认这次迁移，继续按 jsonl 读 —— 宁可留在旧形态，
      *    也不要静默丢知识）；
-     * 3. 两者都没有 → 首次启动：先落手册与复盘的 SourceRaw，再把 seed 编译成卡片。
+     * 3. 两者都没有 → **什么都不写**。这个库还没开始做排查。
+     *
+     * 第 3 条原来是自动写入内置示例。实跑反馈把它改掉了：那份示例长得像真的业务文档，
+     * 而它落在用户自己的 `01_source_raw/` 与 `02_wiki/` 里 —— 新装一台机器，一打开
+     * 「智能归因」就凭空多出几份来源和几十张卡片。示例还在（`loadSample()`），
+     * 但改成**用户点一下才载入**。
+     *
+     * **v1.1 起连模板文件也不铺了**：模板卡由类型定义派生（0021 §6.6），落成磁盘文件会
+     * 造出「设置里改了、磁盘上那份没改」的第二真源。
      */
     async ensure() {
-        await mkdir(this.dir, { recursive: true });
-        const templates = join(this.dir, 'templates');
-        await mkdir(templates, { recursive: true });
-        await Promise.all(DIAGNOSIS_ENTITIES.map(spec => this.writeIfAbsent(join(templates, `${spec.entityType.replace(/\//g, '-')}.md`), templateCard(spec))));
-        // 目录角色的说明也要落盘：下一个人只打开 05_diagnosis 时，得知道知识已经搬走了。
-        await this.writeIfAbsent(join(this.dir, 'README.md'), README);
-        // 注意：**不要**在这里为一次排查的产物建空占位文件。它们走 `writeIfAbsent`，
-        // 而「占位」会在首次 seed 之前就把文件创建出来，于是 seed 的真实内容被判为「已存在」
-        // 而写不进去 —— 结果是图上少了 evidence / cause 五个节点，且没有任何报错。
         if ((await this.readCards()).length > 0)
             return { seeded: false, migrated: false, problems: [] };
         if ((await this.legacyShardFiles()).length > 0)
             return await this.migrate();
-        return await this.seed();
+        return { seeded: false, migrated: false, problems: [] };
+    }
+    /**
+     * 载入**内置示例**：一份排查手册 + 三篇复盘 + 三次排查日志 → SourceRaw → 卡片 → 图。
+     *
+     * 只有用户明确点了「载入内置示例」才走这里（`ensure()` 不再自动调用）。幂等：
+     * `addSource` 按 `externalId`、`writeCard` 按 entityId，点两次不会写出第二份。
+     *
+     * **它走的是「提议 → 确认」那条门，不是绕过它**（0021 §6.1）。区别只在确认者是谁：
+     * 用户点「载入内置示例」这个动作本身就是**对整批示例的确认**，所以这里给每条提议记下
+     * `confirmedBy = user:load-sample`，然后照常走 `writeCard`。这样做的两个好处：
+     * 待办区里能看到这批卡片是怎么来的；而「未确认不落 `02_wiki/`」这条规则没有被开一个
+     * 后门 —— 例外是**确认者的身份**，不是门的缺失。
+     */
+    async loadSample() {
+        const { problems: sourceProblems, refs } = await this.writeSources(seedSources());
+        const cards = withSourceRefs(graphToCards(SEED_GRAPH, SEED_CASES), refs, SEED_CASES);
+        const problems = [...sourceProblems, ...await this.writeCards(cards, 'user:load-sample')];
+        return { seeded: true, migrated: false, problems };
     }
     async snapshot() {
         const { seeded, migrated, problems } = await this.ensure();
         const cards = await this.readCards();
-        const run = await this.readRunArtifacts();
+        /**
+         * 「什么都没有」= 没有卡片、也没有旧 jsonl。它是**可以载入内置示例**的唯一条件：
+         * 已经有知识（不管哪一代形态）时不该再往里塞示例 —— 那会变成第二份互相矛盾的知识。
+         */
+        const canLoadSample = cards.length === 0 && (await this.legacyShardFiles()).length === 0;
         if (cards.length > 0) {
-            const compiled = cardsToGraph(cards);
-            const graph = {
-                nodes: [...compiled.graph.nodes, ...run.nodes],
-                edges: [...compiled.graph.edges, ...run.edges],
-            };
+            const built = await this.buildGraph(cards);
             return {
-                graph,
-                cases: compiled.cases,
-                issues: validateDiagnosis(graph),
+                graph: built.graph,
+                cases: built.cases,
+                issues: validateDiagnosis(built.graph),
                 seeded,
                 migrated,
                 source: 'cards',
-                problems: [...problems, ...compiled.problems],
+                canLoadSample: false,
+                problems: [...problems, ...built.problems],
             };
         }
-        // 还没有卡片：旧 jsonl（或 seed 刚写下的那份）就是当前可读的来源。
-        const graph = await this.readGraph();
-        const cases = await this.readCases();
+        // 还没有卡片：旧 jsonl 就是当前可读的来源；两份都没有就是一个空库。
+        const graph = await this.readLegacyGraph();
+        const cases = await this.readLegacyCases();
         return {
             graph,
             cases,
             issues: validateDiagnosis(graph),
             seeded,
             migrated,
-            source: (await this.legacyShardFiles()).length > 0 ? 'jsonl' : 'seed',
+            source: canLoadSample ? 'empty' : 'jsonl',
+            canLoadSample,
             problems,
         };
     }
     /**
-     * 图。
+     * 图 = **卡片那张图** + **一次排查的产物**。
+     *
+     * 两条来源严格分工：类型层与引用层（以及六种卡片边）全部来自卡片；`evidence` / `cause`
+     * 与四条执行边全部来自 `agent_diagnosis_case` 的 SourceRaw。合成一张图是**读**的时候
+     * 做的，不是写的时候 —— 写的时候合成，等于让一次执行的结果变成可复用的知识。
+     */
+    async buildGraph(cards) {
+        const compiled = cardsToGraph(cards);
+        const problems = [...compiled.problems];
+        const nodes = [...compiled.graph.nodes];
+        const edges = [...compiled.graph.edges];
+        const runs = await this.readRuns();
+        problems.push(...runs.problems);
+        for (const record of runs.records) {
+            const run = runToGraph(record);
+            // 引用完整性要**连这次排查自己产出的 id 一起算**：路径里的 `E1` / `C1` 正是它写下的。
+            const known = new Set([...compiled.graph.nodes.map(node => node.id), ...run.nodes.map(node => node.id)]);
+            problems.push(...run.problems, ...runReferenceProblems(record, known));
+            nodes.push(...run.nodes);
+            edges.push(...run.edges);
+        }
+        /**
+         * **旧 jsonl 里的执行产物继续可读。**
+         *
+         * 它们是只读的历史快照（v0.7 之前一次排查的产物就写在那里），而卡片表达不了它们
+         * —— `evidence` / `cause` 与四条执行边不属于任何卡片。所以迁移只搬「卡片能表达的那
+         * 部分」，这一部分留在原处继续供读。少了这一段，一次旧知识根迁移之后图会静默地
+         * 少掉全部证据与根因，而迁移还报成功。
+         */
+        const legacyRun = await this.readLegacyRunArtifacts();
+        nodes.push(...legacyRun.nodes);
+        edges.push(...legacyRun.edges);
+        return { graph: dedupe({ nodes, edges }, problems), cases: compiled.cases, problems };
+    }
+    /**
+     * 旧 `05_diagnosis/` 里的执行产物：`evidence.jsonl` / `causes.jsonl` / `edges.jsonl`。
      *
-     * 有卡片：`cardsToGraph(卡片)` + 一次排查的产物；没有卡片：按旧 jsonl 读。
-     * 两条路径都返回同一种形状，调用方不需要知道现在是哪一代。
+     * 只取**执行边**：卡片边由卡片投影出来，这里再读一遍就会出现重复边。同时按 id 去重
+     * —— 已经由 `agent_diagnosis_case` 解析出来的节点不重复加（新旧两代可能描述同一次排查）。
      */
+    async readLegacyRunArtifacts() {
+        const nodes = [];
+        for (const file of Object.keys(LEGACY_RUN_SHARDS)) {
+            for (const row of await this.readLines(join(this.legacyDir, file))) {
+                try {
+                    nodes.push(JSON.parse(row));
+                }
+                catch { /* 跳过损坏行 */ }
+            }
+        }
+        const edges = [];
+        for (const row of await this.readLines(join(this.legacyDir, 'edges.jsonl'))) {
+            try {
+                const edge = JSON.parse(row);
+                if (RUN_EDGE_KINDS.includes(edge.kind))
+                    edges.push(edge);
+            }
+            catch { /* 同上 */ }
+        }
+        return { nodes, edges };
+    }
     async readGraph() {
         const cards = await this.readCards();
-        if (cards.length > 0) {
-            const compiled = cardsToGraph(cards);
-            const run = await this.readRunArtifacts();
-            return { nodes: [...compiled.graph.nodes, ...run.nodes], edges: [...compiled.graph.edges, ...run.edges] };
-        }
+        if (cards.length > 0)
+            return (await this.buildGraph(cards)).graph;
         return await this.readLegacyGraph();
     }
     async readCases() {
         const cards = await this.readCards();
         if (cards.length > 0)
             return cardsToGraph(cards).cases;
-        try {
-            const raw = await readFile(join(this.dir, 'cases.json'), 'utf8');
-            const parsed = JSON.parse(raw);
-            return Array.isArray(parsed) ? parsed : [];
-        }
-        catch {
-            return [];
-        }
+        return await this.readLegacyCases();
     }
     /* ────────────────────────────────────────────── 卡片：读写 ── */
     /** 读 `02_wiki/diagnosis/**` 下的全部卡片。解析不出来的文件按「不是卡片」跳过。 */
@@ -159,57 +219,88 @@ export class DiagnosisStore {
         }
         return cards;
     }
-    /** 写一批卡片。返回写失败的原因（schema 不认、出处不存在等），由调用方决定怎么显示。 */
-    async writeCards(cards) {
+    /* ────────────────────────────────────────────── 一次排查的记录 ── */
+    /**
+     * 读全部 `agent_diagnosis_case` 来源，解析出排查记录。
+     *
+     * 块坏了、`runId` 缺了、`symptomId` 缺了就**跳过并如实报问题** —— 不猜。
+     * 一条坏日志不该让整张图读不出来，但它也不能被静默吞掉。
+     */
+    async readRuns() {
+        const records = [];
         const problems = [];
-        for (const card of cards) {
-            const written = await this.host.writeCard({
-                entityType: card.entityType,
-                entityId: card.entityId,
-                title: card.title,
-                content: renderBody(card),
-                sourceRefs: card.sourceRefs,
-                status: card.status,
-                ...(card.summary ? { summary: card.summary } : {}),
-                ...(card.owner ? { owner: card.owner } : {}),
-            });
-            if (written.ok === false)
-                problems.push(`卡片 ${card.entityId} 写入失败：${written.error.code} ${written.error.message}`);
+        for (const source of await this.host.loadSources()) {
+            if (source.sourceType !== RUN_SOURCE_TYPE)
+                continue;
+            const record = parseRunSource(source.content);
+            if (record)
+                records.push(record);
+            else
+                problems.push(`诊断日志 ${source.sourceId} 里没有可解析的 \`json diagnosis-run\` 块，已跳过`);
         }
-        return problems;
+        return { records, problems };
     }
-    /* ────────────────────────────────────────────── 首次 seed ── */
-    async seed() {
-        const { problems: sourceProblems, refs } = await this.writeSources(seedSources());
-        const cards = withSourceRefs(graphToCards(SEED_GRAPH, SEED_CASES), refs, SEED_GRAPH, SEED_CASES);
-        const problems = [...sourceProblems, ...await this.writeCards(cards)];
-        // 一次排查的产物照旧落在这里 —— seed 本来就等于「已经发生过的那三次排查」。
-        await this.writeRunArtifacts(SEED_GRAPH);
-        await this.writeLegacySnapshot();
-        return { seeded: true, migrated: false, problems };
+    /**
+     * 一次排查结束：写一条 `agent_diagnosis_case` 的 SourceRaw，并**直接写入**一张案例卡片。
+     *
+     * 0044：案例卡片原来只提议、等人确认。与编译那条链路一样改成直接入库 ——
+     * 一次排查的价值就在于「当时是怎么走的」，让它停在待办队列里等于把经验丢掉。
+     * 卡片会被标成 `unreviewed`，人在「知识库 → Wiki」里 review 它。
+     *
+     * 幂等：`externalId` = runId，同一次排查重跑不会写出第二条来源；卡片按 entityId 写入。
+     */
+    async recordRun(record) {
+        const problems = [];
+        const added = await this.host.addSource({
+            sourceType: RUN_SOURCE_TYPE,
+            title: `AI 诊断日志 · ${record.symptomId} · ${record.runId}`,
+            content: renderRunSource(record),
+            externalId: record.runId,
+            sourceId: `${RUN_SOURCE_TYPE}:${record.runId}`,
+        });
+        if (added.ok === false)
+            return { problems: [`诊断日志 ${record.runId} 写入失败：${added.error.code} ${added.error.message}`] };
+        const sourceId = added.data.sourceId;
+        const symptomTitle = (await this.readCards()).find(card => card.entityId === record.symptomId)?.title ?? record.symptomId;
+        const draft = caseCardOf(record, symptomTitle);
+        const written = await this.host.writeCard({
+            entityType: draft.entityType,
+            entityId: draft.entityId,
+            title: draft.title,
+            content: renderCardBody(draft),
+            sourceRefs: [sourceId],
+            status: 'unreviewed',
+        });
+        if (written.ok === false)
+            problems.push(`案例卡片 ${draft.entityId} 写入失败：${written.error.code} ${written.error.message}`);
+        return { sourceId, ...(written.ok === false ? {} : { entityId: draft.entityId }), problems };
     }
     /* ────────────────────────────────────────────── 旧知识根迁移 ── */
     async migrate() {
         const legacy = await this.readLegacyGraph();
-        const cases = await this.readCases();
+        const cases = await this.readLegacyCases();
         // **先在内存里验证，通过才写盘。**
         //
         // 卡片表达不了的东西确实存在：手工加的边、没有任何假设引用的资产节点……一旦迁移会丢，
         // 就宁可留在旧形态，也不要静默丢知识。而「先写再验、失败回滚」会留一个更糟的中间态：
         // 卡片已经落盘，下一次读就成了卡片来源 —— 于是分歧只在第一次读时被报出来，
         // 之后再也看不见。所以顺序是：编译 → 比对 → 才写。
-        const run = await this.readRunArtifacts();
         const draft = graphToCards(legacy, cases);
         const compiled = cardsToGraph(draft);
-        const divergence = compareGraphs(legacy, {
-            nodes: [...compiled.graph.nodes, ...run.nodes],
-            edges: [...compiled.graph.edges, ...run.edges],
-        });
+        /**
+         * 比对的是**卡片能表达的那部分**。
+         *
+         * `evidence` / `cause` 与四条执行边不在卡片里（§6.7 的边界表），它们留在
+         * `05_diagnosis/` 里继续供读（见 `readLegacyRunArtifacts`）。把它们算进比对，
+         * 结果是**任何带排查产物的旧知识根都迁不动** —— 而失败方式是静默的：图少了一半，
+         * 迁移还报成功。
+         */
+        const divergence = compareGraphs(cardExpressible(legacy), compiled.graph);
         if (divergence) {
             return { seeded: false, migrated: false, problems: [`迁移未生效（仍按 05_diagnosis/*.jsonl 读）：${divergence}`] };
         }
         const { problems: sourceProblems, refs } = await this.writeSources(seedSources());
-        const problems = [...sourceProblems, ...await this.writeCards(withSourceRefs(draft, refs, legacy, cases))];
+        const problems = [...sourceProblems, ...await this.writeCards(withSourceRefs(draft, refs, cases), 'migration:05_diagnosis')];
         return { seeded: false, migrated: problems.length === 0, problems };
     }
     /* ────────────────────────────────────────────── SourceRaw ── */
@@ -236,58 +327,60 @@ export class DiagnosisStore {
         }
         return { problems, refs };
     }
-    /* ────────────────────────────────────────────── 一次排查的产物 ── */
-    async readRunArtifacts() {
-        const nodes = [];
-        for (const file of Object.keys(RUN_NODE_SHARDS)) {
-            for (const row of await this.readLines(join(this.dir, file))) {
-                try {
-                    nodes.push(JSON.parse(row));
-                }
-                catch { /* 跳过损坏行，不让一行毁掉整张图 */ }
-            }
-        }
-        const edges = [];
-        for (const row of await this.readLines(join(this.dir, 'edges.jsonl'))) {
-            try {
-                const edge = JSON.parse(row);
-                // 只认执行边：五种卡片边由卡片投影出来，这里再读一遍就会出现重复边。
-                if (RUN_EDGE_KINDS.includes(edge.kind))
-                    edges.push(edge);
-            }
-            catch { /* 同上 */ }
+    /* ────────────────────────────────────────────── 写卡片 ── */
+    /**
+     * 写一批卡片。返回写失败的原因（类型不认、出处不存在等），由调用方决定怎么显示。
+     *
+     * 0044：**直接写**，不再先提一条提议再确认再落卡。`confirmedBy` 现在只是一个
+     * 归因用的标签（载入示例时是 `user:load-sample`，迁移时是迁移逻辑），不再是准入凭证 ——
+     * 凭证这道门已经不存在了。留它是因为它进 `writeCard` 的 lineage 留痕，
+     * 而「这张卡片是哪一次动作产生的」仍然值得回答。
+     */
+    async writeCards(cards, confirmedBy) {
+        const problems = [];
+        for (const card of cards) {
+            const written = await this.host.writeCard({
+                entityType: card.entityType,
+                entityId: card.entityId,
+                title: card.title,
+                content: renderCardBody(card),
+                sourceRefs: card.sourceRefs,
+                status: card.status,
+                ...(card.summary ? { summary: card.summary } : {}),
+                ...(card.owner ? { owner: card.owner } : {}),
+            });
+            if (written.ok === false)
+                problems.push(`卡片 ${card.entityId} 写入失败：${written.error.code} ${written.error.message}`);
         }
-        return { nodes, edges };
+        if (problems.length > 0)
+            problems.push(`（这一批卡片由 ${confirmedBy} 写入）`);
+        return problems;
     }
-    async writeRunArtifacts(graph) {
-        for (const [file, kind] of Object.entries(RUN_NODE_SHARDS)) {
-            const rows = graph.nodes.filter(node => node.kind === kind);
-            await this.writeIfAbsent(join(this.dir, file), rows.map(row => JSON.stringify(row)).join('\n'));
+    /* ────────────────────────────────────────────── 旧读法（只读） ── */
+    async readLegacyCases() {
+        try {
+            const raw = await readFile(join(this.legacyDir, 'cases.json'), 'utf8');
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
         }
-        await this.writeIfAbsent(join(this.dir, 'edges.jsonl'), graph.edges.filter(edge => RUN_EDGE_KINDS.includes(edge.kind)).map(edge => JSON.stringify(edge)).join('\n'));
-    }
-    /** 旧版的类型层快照。首次 seed 时也写一份：它让 `05_diagnosis/` 仍是一份可读的完整快照。 */
-    async writeLegacySnapshot() {
-        for (const [file, kind] of Object.entries(LEGACY_SHARDS)) {
-            const rows = SEED_GRAPH.nodes.filter(node => node.kind === kind);
-            await this.writeIfAbsent(join(this.dir, file), rows.map(row => JSON.stringify(row)).join('\n'));
+        catch {
+            return [];
         }
-        await this.writeIfAbsent(join(this.dir, 'cases.json'), JSON.stringify(SEED_CASES, null, 2));
     }
-    /* ────────────────────────────────────────────── 旧读法 ── */
     async readLegacyGraph() {
         const nodes = [];
-        for (const [file, kind] of Object.entries({ ...LEGACY_SHARDS, ...RUN_NODE_SHARDS })) {
-            for (const row of await this.readLines(join(this.dir, file))) {
+        for (const file of Object.keys({ ...LEGACY_SHARDS, ...LEGACY_RUN_SHARDS })) {
+            for (const row of await this.readLines(join(this.legacyDir, file))) {
                 try {
                     nodes.push(JSON.parse(row));
                 }
                 catch { /* 跳过损坏行 */ }
             }
-            void kind;
         }
         const edges = [];
-        for (const row of await this.readLines(join(this.dir, 'edges.jsonl'))) {
+        for (const row of await this.readLines(join(this.legacyDir, 'edges.jsonl'))) {
+            // **全部边都读**，不筛：旧文件是**迁移输入**，六种卡片边正是要从这里反推成
+            // 卡片字段的。只在读「当前图」时才筛执行边（`readLegacyRunArtifacts`）。
             try {
                 edges.push(JSON.parse(row));
             }
@@ -298,14 +391,13 @@ export class DiagnosisStore {
     /**
      * 是否存在**值得迁移的旧知识根**。
      *
-     * 只看旧版的**类型层**分片，而且要求它真的有内容：`ensure()` 自己会为一次排查的产物
-     * （`evidence.jsonl` 等）建空占位文件 —— 若把空文件也算成「旧知识根」，首次启动会走进
-     * 迁移分支，然后在空图上白跑一趟。
+     * 只看旧版的**类型层**分片，而且要求它真的有内容：空文件不算「旧知识根」，
+     * 否则首次启动会走进迁移分支，然后在空图上白跑一趟。
      */
     async legacyShardFiles() {
         const found = [];
         for (const file of Object.keys(LEGACY_SHARDS)) {
-            if ((await this.readLines(join(this.dir, file))).length > 0)
+            if ((await this.readLines(join(this.legacyDir, file))).length > 0)
                 found.push(file);
         }
         return found;
@@ -318,18 +410,9 @@ export class DiagnosisStore {
             return [];
         }
     }
-    async writeIfAbsent(path, content) {
-        try {
-            await readFile(path);
-            return;
-        }
-        catch {
-            await writeFile(path, content, 'utf8');
-        }
-    }
 }
 /** 卡片正文：小节 + 结构化块。复用编解码里的同一套序列化，避免两处格式漂移。 */
-function renderBody(card) {
+export function renderCardBody(card) {
     const text = serializeCard(card);
     return text.slice(text.indexOf('\n---\n', 3) + 5).trim();
 }
@@ -339,7 +422,7 @@ function renderBody(card) {
  * 规则是**数据驱动的**，不是凭印象分的：案例卡片与它自己的复盘原文一一对应；
  * 其它卡片取「第一篇走过它的复盘」，没有走过它的就挂那本手册。
  */
-function withSourceRefs(cards, refs, graph, cases) {
+function withSourceRefs(cards, refs, cases) {
     const handbook = refs.get('handbook');
     /** 节点 id → 它出现在哪篇复盘里（取第一篇）。 */
     const caseOf = new Map();
@@ -352,13 +435,62 @@ function withSourceRefs(cards, refs, graph, cases) {
             if (!caseOf.has(step.nodeId))
                 caseOf.set(step.nodeId, ref);
     }
-    void graph;
     return cards.map(card => {
         const own = card.entityType === 'diagnosis/case' ? refs.get(card.entityId) : undefined;
         const ref = own ?? caseOf.get(card.entityId) ?? handbook;
         return { ...card, sourceRefs: ref ? [ref] : [] };
     });
 }
+/**
+ * 按 id 去重。
+ *
+ * 新旧两代可能描述**同一次排查**：一条 `agent_diagnosis_case` 的 SourceRaw（v1.1 起）
+ * 与 `05_diagnosis/evidence.jsonl`（历史快照）里会有同一个 `E1`。不去重的后果是图上
+ * 出现两个 `E1` —— 而画布按 id 建节点，第二个会静默覆盖第一个的位置与样式，
+ * 读起来像「这次排查跑了两遍」。
+ *
+ * 同 id 但 kind 不同是真冲突（同一份知识被两处定义成两样东西），报出来而不是静默取第一个。
+ */
+function dedupe(graph, problems) {
+    const nodes = [];
+    const byId = new Map();
+    for (const node of graph.nodes) {
+        const previous = byId.get(node.id);
+        if (previous) {
+            if (previous.kind !== node.kind)
+                problems.push(`节点 ${node.id} 被定义成了两种类型（${previous.kind} / ${node.kind}）—— 只保留第一个`);
+            continue;
+        }
+        byId.set(node.id, node);
+        nodes.push(node);
+    }
+    const edges = [];
+    const seen = new Set();
+    for (const edge of graph.edges) {
+        const key = `${edge.kind}:${edge.source}->${edge.target}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        edges.push(edge);
+    }
+    return { nodes, edges };
+}
+/** 只能由一次排查产出的节点类型。它们不属于任何卡片（§6.7 的边界表）。 */
+const RUN_ONLY_KINDS = ['evidence', 'cause', 'unknown'];
+/**
+ * 旧图里**卡片能表达的那部分**：类型层、引用层的资产、案例桩，以及六种卡片边。
+ *
+ * 执行产物（`evidence` / `cause` / `unknown` 与四条执行边）不在其中 —— 它们的归宿是
+ * `agent_diagnosis_case` 的 SourceRaw，而不是卡片。
+ */
+function cardExpressible(graph) {
+    const nodes = graph.nodes.filter(node => !RUN_ONLY_KINDS.includes(node.kind));
+    const ids = new Set(nodes.map(node => node.id));
+    return {
+        nodes,
+        edges: graph.edges.filter(edge => CARD_EDGE_KINDS.includes(edge.kind) && ids.has(edge.source) && ids.has(edge.target)),
+    };
+}
 /**
  * 两张图是否一致。返回 `undefined` 表示一致，否则返回第一条差异的人话描述。
  *
@@ -405,5 +537,4 @@ async function walkMarkdown(dir) {
     }
     return found;
 }
-export { cardPathOf };
 //# sourceMappingURL=store.js.map