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

package/src/diagnosis/store.ts

@@ -1,45 +1,47 @@
-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, type AttributionCase } from './seed.js'
+import { SEED_CASES, SEED_GRAPH } from './seed.js'
 import { seedSources, type SeedSource } from './seed-source.js'
-import { DIAGNOSIS_ENTITIES, templateCard, validateDiagnosis, type DiagnosisIssue } from './schema.js'
+import { validateDiagnosis, type DiagnosisIssue } from './schema.js'
 import {
-  cardsToGraph, cardPathOf, graphToCards, parseCard, serializeCard,
+  cardsToGraph, CARD_EDGE_KINDS, graphToCards, parseCard, serializeCard,
   RUN_EDGE_KINDS, type DiagnosisCard,
 } from './cards.js'
-import type { AttributionEdge, AttributionGraphData, AttributionNode, AttributionNodeKind } from './types.js'
+import { caseCardOf, parseRunSource, renderRunSource, runReferenceProblems, runToGraph } from './run.js'
+import type {
+  AttributionCase, AttributionEdge, AttributionGraphData, AttributionNode, AttributionNodeKind, DiagnosisRunRecord,
+} from './types.js'
 import type { KnowledgeRuntime } from '../runtime.js'
 import type { SchemaType } from '../types.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: Record<string, AttributionNodeKind> = {
-  'evidence.jsonl': 'evidence',
-  'causes.jsonl': 'cause',
-}
+const LEGACY_DIR = '05_diagnosis'
+/** 一次排查的产物：`01_source_raw/<这个分类>/`。 */
+const RUN_SOURCE_TYPE = 'agent_diagnosis_case'
 
 /**
  * 旧版的类型层分片。**只读，不再写**：v0.7 之前它们就是真相，现在它们的角色是
@@ -48,48 +50,52 @@ const RUN_NODE_SHARDS: Record<string, AttributionNodeKind> = {
 const LEGACY_SHARDS: Record<string, AttributionNodeKind> = {
   '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: Record<string, AttributionNodeKind> = {
+  'evidence.jsonl': 'evidence',
+  'causes.jsonl': 'cause',
+}
 
 /** 读取顺序的显式来源，界面据此说明「现在看到的是哪一份」。 */
-export type DiagnosisSource = 'cards' | 'jsonl' | 'seed'
+export type DiagnosisSource = 'cards' | 'jsonl' | 'empty'
 
 export interface DiagnosisSnapshot {
   graph: AttributionGraphData
   cases: AttributionCase[]
   issues: DiagnosisIssue[]
-  /** 数据是不是本次 ensure() 从 seed 写进去的。界面据此说明来源。 */
+  /** 数据是不是本次调用从内置示例写进去的（只有 `loadSample()` 会把它变成 true）。 */
   seeded: boolean
   /** 旧知识根是否在本次被前向迁移成卡片。 */
   migrated: boolean
   /** 读的是哪一份真相。 */
   source: DiagnosisSource
-  /** 写卡片 / 迁移过程中发现的问题（写失败、迁移分歧）。必须能显示出来，不能只进日志。 */
+  /**
+   * 这个库还什么都没有 —— 界面据此显示空态（说什么会有、怎么开始），
+   * 而不是画一张空图。
+   */
+  canLoadSample: boolean
+  /** 写卡片 / 迁移 / 读诊断日志过程中发现的问题。必须能显示出来，不能只进日志。 */
   problems: string[]
 }
 
-/** 只取运行时里真正要用的三件事：读根目录、落 SourceRaw、写卡片。 */
-type DiagnosisHost = Pick<KnowledgeRuntime, 'rootDir' | 'addSource' | 'writeCard'>
+/**
+ * 只取运行时里真正要用的那几件事：读根目录、落 SourceRaw、写卡片、列来源。
+ *
+ * `loadSources` 是 v1.1 新增的：一次排查的产物现在是一条 `agent_diagnosis_case`
+ * 的 SourceRaw，归因图读的是它，而不是自造的 jsonl。
+ */
+type DiagnosisHost = Pick<KnowledgeRuntime, 'rootDir' | 'addSource' | 'writeCard' | 'loadSources'>
 
 export class DiagnosisStore {
   constructor(private readonly host: DiagnosisHost) {}
 
-  private get dir(): string { return join(this.host.rootDir, DIR) }
+  private get legacyDir(): string { return join(this.host.rootDir, LEGACY_DIR) }
   private get cardsDir(): string { return join(this.host.rootDir, '02_wiki', 'diagnosis') }
 
   /**
@@ -99,85 +105,151 @@ export class DiagnosisStore {
    * 2. 没有卡片但有旧 jsonl → **前向迁移**：把旧图反推成卡片写出去，并**校验迁移无损**
    *    （重新编译一遍与旧图比对，不一致就不认这次迁移，继续按 jsonl 读 —— 宁可留在旧形态，
    *    也不要静默丢知识）；
-   * 3. 两者都没有 → 首次启动：先落手册与复盘的 SourceRaw，再把 seed 编译成卡片。
+   * 3. 两者都没有 → **什么都不写**。这个库还没开始做排查。
+   *
+   * 第 3 条原来是自动写入内置示例。实跑反馈把它改掉了：那份示例长得像真的业务文档，
+   * 而它落在用户自己的 `01_source_raw/` 与 `02_wiki/` 里 —— 新装一台机器，一打开
+   * 「智能归因」就凭空多出几份来源和几十张卡片。示例还在（`loadSample()`），
+   * 但改成**用户点一下才载入**。
+   *
+   * **v1.1 起连模板文件也不铺了**：模板卡由类型定义派生（0021 §6.6），落成磁盘文件会
+   * 造出「设置里改了、磁盘上那份没改」的第二真源。
    */
   async ensure(): Promise<{ seeded: boolean; migrated: boolean; problems: string[] }> {
-    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(): Promise<{ seeded: boolean; migrated: boolean; problems: string[] }> {
+    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(): Promise<DiagnosisSnapshot> {
     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: AttributionGraphData = {
-        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,
     }
   }
 
   /**
-   * 图。
+   * 图 = **卡片那张图** + **一次排查的产物**。
    *
-   * 有卡片：`cardsToGraph(卡片)` + 一次排查的产物；没有卡片：按旧 jsonl 读。
-   * 两条路径都返回同一种形状，调用方不需要知道现在是哪一代。
+   * 两条来源严格分工：类型层与引用层（以及六种卡片边）全部来自卡片；`evidence` / `cause`
+   * 与四条执行边全部来自 `agent_diagnosis_case` 的 SourceRaw。合成一张图是**读**的时候
+   * 做的，不是写的时候 —— 写的时候合成，等于让一次执行的结果变成可复用的知识。
    */
+  private async buildGraph(cards: DiagnosisCard[]): Promise<{ graph: AttributionGraphData; cases: AttributionCase[]; problems: string[] }> {
+    const compiled = cardsToGraph(cards)
+    const problems = [...compiled.problems]
+    const nodes: AttributionNode[] = [...compiled.graph.nodes]
+    const edges: AttributionEdge[] = [...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`。
+   *
+   * 只取**执行边**：卡片边由卡片投影出来，这里再读一遍就会出现重复边。同时按 id 去重
+   * —— 已经由 `agent_diagnosis_case` 解析出来的节点不重复加（新旧两代可能描述同一次排查）。
+   */
+  private async readLegacyRunArtifacts(): Promise<{ nodes: AttributionNode[]; edges: AttributionEdge[] }> {
+    const nodes: AttributionNode[] = []
+    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) as AttributionNode) } catch { /* 跳过损坏行 */ }
+      }
+    }
+    const edges: AttributionEdge[] = []
+    for (const row of await this.readLines(join(this.legacyDir, 'edges.jsonl'))) {
+      try {
+        const edge = JSON.parse(row) as AttributionEdge
+        if (RUN_EDGE_KINDS.includes(edge.kind)) edges.push(edge)
+      } catch { /* 同上 */ }
+    }
+    return { nodes, edges }
+  }
+
   async readGraph(): Promise<AttributionGraphData> {
     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(): Promise<AttributionCase[]> {
     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) as AttributionCase[]
-      return Array.isArray(parsed) ? parsed : []
-    } catch { return [] }
+    return await this.readLegacyCases()
   }
 
   /* ────────────────────────────────────────────── 卡片：读写 ── */
@@ -192,42 +264,66 @@ export class DiagnosisStore {
     return cards
   }
 
-  /** 写一批卡片。返回写失败的原因（schema 不认、出处不存在等），由调用方决定怎么显示。 */
-  private async writeCards(cards: DiagnosisCard[]): Promise<string[]> {
+  /* ────────────────────────────────────────────── 一次排查的记录 ── */
+
+  /**
+   * 读全部 `agent_diagnosis_case` 来源，解析出排查记录。
+   *
+   * 块坏了、`runId` 缺了、`symptomId` 缺了就**跳过并如实报问题** —— 不猜。
+   * 一条坏日志不该让整张图读不出来，但它也不能被静默吞掉。
+   */
+  async readRuns(): Promise<{ records: DiagnosisRunRecord[]; problems: string[] }> {
+    const records: DiagnosisRunRecord[] = []
     const problems: string[] = []
-    for (const card of cards) {
-      const written = await this.host.writeCard({
-        entityType: card.entityType as SchemaType,
-        entityId: card.entityId,
-        title: card.title,
-        content: renderBody(card),
-        sourceRefs: card.sourceRefs,
-        status: card.status as never,
-        ...(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 ── */
-
-  private async seed(): Promise<{ seeded: boolean; migrated: boolean; problems: string[] }> {
-    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: DiagnosisRunRecord): Promise<{ sourceId?: string; entityId?: string; problems: string[] }> {
+    const problems: string[] = []
+    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 as SchemaType,
+      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 }
   }
 
   /* ────────────────────────────────────────────── 旧知识根迁移 ── */
 
   private async migrate(): Promise<{ seeded: boolean; migrated: boolean; problems: string[] }> {
     const legacy = await this.readLegacyGraph()
-    const cases = await this.readCases()
+    const cases = await this.readLegacyCases()
 
     // **先在内存里验证，通过才写盘。**
     //
@@ -235,19 +331,23 @@ export class DiagnosisStore {
     // 就宁可留在旧形态，也不要静默丢知识。而「先写再验、失败回滚」会留一个更糟的中间态：
     // 卡片已经落盘，下一次读就成了卡片来源 —— 于是分歧只在第一次读时被报出来，
     // 之后再也看不见。所以顺序是：编译 → 比对 → 才写。
-    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 }
   }
 
@@ -275,58 +375,56 @@ export class DiagnosisStore {
     return { problems, refs }
   }
 
-  /* ────────────────────────────────────────────── 一次排查的产物 ── */
+  /* ────────────────────────────────────────────── 写卡片 ── */
 
-  private async readRunArtifacts(): Promise<{ nodes: AttributionNode[]; edges: AttributionEdge[] }> {
-    const nodes: AttributionNode[] = []
-    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) as AttributionNode) } catch { /* 跳过损坏行，不让一行毁掉整张图 */ }
-      }
-    }
-    const edges: AttributionEdge[] = []
-    for (const row of await this.readLines(join(this.dir, 'edges.jsonl'))) {
-      try {
-        const edge = JSON.parse(row) as AttributionEdge
-        // 只认执行边：五种卡片边由卡片投影出来，这里再读一遍就会出现重复边。
-        if (RUN_EDGE_KINDS.includes(edge.kind)) edges.push(edge)
-      } catch { /* 同上 */ }
+  /**
+   * 写一批卡片。返回写失败的原因（类型不认、出处不存在等），由调用方决定怎么显示。
+   *
+   * 0044：**直接写**，不再先提一条提议再确认再落卡。`confirmedBy` 现在只是一个
+   * 归因用的标签（载入示例时是 `user:load-sample`，迁移时是迁移逻辑），不再是准入凭证 ——
+   * 凭证这道门已经不存在了。留它是因为它进 `writeCard` 的 lineage 留痕，
+   * 而「这张卡片是哪一次动作产生的」仍然值得回答。
+   */
+  private async writeCards(cards: DiagnosisCard[], confirmedBy: string): Promise<string[]> {
+    const problems: string[] = []
+    for (const card of cards) {
+      const written = await this.host.writeCard({
+        entityType: card.entityType as SchemaType,
+        entityId: card.entityId,
+        title: card.title,
+        content: renderCardBody(card),
+        sourceRefs: card.sourceRefs,
+        status: card.status as never,
+        ...(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
   }
 
-  private async writeRunArtifacts(graph: AttributionGraphData): Promise<void> {
-    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'))
-    }
-    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/` 仍是一份可读的完整快照。 */
-  private async writeLegacySnapshot(): Promise<void> {
-    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'))
-    }
-    await this.writeIfAbsent(join(this.dir, 'cases.json'), JSON.stringify(SEED_CASES, null, 2))
+  private async readLegacyCases(): Promise<AttributionCase[]> {
+    try {
+      const raw = await readFile(join(this.legacyDir, 'cases.json'), 'utf8')
+      const parsed = JSON.parse(raw) as AttributionCase[]
+      return Array.isArray(parsed) ? parsed : []
+    } catch { return [] }
   }
 
-  /* ────────────────────────────────────────────── 旧读法 ── */
-
   private async readLegacyGraph(): Promise<AttributionGraphData> {
     const nodes: AttributionNode[] = []
-    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) as AttributionNode) } catch { /* 跳过损坏行 */ }
       }
-      void kind
     }
     const edges: AttributionEdge[] = []
-    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) as AttributionEdge) } catch { /* 同上 */ }
     }
     return { nodes, edges }
@@ -335,14 +433,13 @@ export class DiagnosisStore {
   /**
    * 是否存在**值得迁移的旧知识根**。
    *
-   * 只看旧版的**类型层**分片，而且要求它真的有内容：`ensure()` 自己会为一次排查的产物
-   * （`evidence.jsonl` 等）建空占位文件 —— 若把空文件也算成「旧知识根」，首次启动会走进
-   * 迁移分支，然后在空图上白跑一趟。
+   * 只看旧版的**类型层**分片，而且要求它真的有内容：空文件不算「旧知识根」，
+   * 否则首次启动会走进迁移分支，然后在空图上白跑一趟。
    */
   private async legacyShardFiles(): Promise<string[]> {
     const found: string[] = []
     for (const file of Object.keys(LEGACY_SHARDS)) {
-      if ((await this.readLines(join(this.dir, file))).length > 0) found.push(file)
+      if ((await this.readLines(join(this.legacyDir, file))).length > 0) found.push(file)
     }
     return found
   }
@@ -352,17 +449,10 @@ export class DiagnosisStore {
       return (await readFile(path, 'utf8')).split('\n').map(line => line.trim()).filter(Boolean)
     } catch { return [] }
   }
-
-  private async writeIfAbsent(path: string, content: string): Promise<void> {
-    try {
-      await readFile(path)
-      return
-    } catch { await writeFile(path, content, 'utf8') }
-  }
 }
 
 /** 卡片正文：小节 + 结构化块。复用编解码里的同一套序列化，避免两处格式漂移。 */
-function renderBody(card: DiagnosisCard): string {
+export function renderCardBody(card: DiagnosisCard): string {
   const text = serializeCard(card)
   return text.slice(text.indexOf('\n---\n', 3) + 5).trim()
 }
@@ -376,7 +466,6 @@ function renderBody(card: DiagnosisCard): string {
 function withSourceRefs(
   cards: DiagnosisCard[],
   refs: Map<string, string>,
-  graph: AttributionGraphData,
   cases: AttributionCase[],
 ): DiagnosisCard[] {
   const handbook = refs.get('handbook')
@@ -388,7 +477,6 @@ function withSourceRefs(
     caseOf.set(item.symptomId, ref)
     for (const step of item.path) 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
@@ -396,6 +484,57 @@ function withSourceRefs(
   })
 }
 
+/**
+ * 按 id 去重。
+ *
+ * 新旧两代可能描述**同一次排查**：一条 `agent_diagnosis_case` 的 SourceRaw（v1.1 起）
+ * 与 `05_diagnosis/evidence.jsonl`（历史快照）里会有同一个 `E1`。不去重的后果是图上
+ * 出现两个 `E1` —— 而画布按 id 建节点，第二个会静默覆盖第一个的位置与样式，
+ * 读起来像「这次排查跑了两遍」。
+ *
+ * 同 id 但 kind 不同是真冲突（同一份知识被两处定义成两样东西），报出来而不是静默取第一个。
+ */
+function dedupe(graph: AttributionGraphData, problems: string[]): AttributionGraphData {
+  const nodes: AttributionNode[] = []
+  const byId = new Map<string, AttributionNode>()
+  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: AttributionEdge[] = []
+  const seen = new Set<string>()
+  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: AttributionNodeKind[] = ['evidence', 'cause', 'unknown']
+
+/**
+ * 旧图里**卡片能表达的那部分**：类型层、引用层的资产、案例桩，以及六种卡片边。
+ *
+ * 执行产物（`evidence` / `cause` / `unknown` 与四条执行边）不在其中 —— 它们的归宿是
+ * `agent_diagnosis_case` 的 SourceRaw，而不是卡片。
+ */
+function cardExpressible(graph: AttributionGraphData): AttributionGraphData {
+  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` 表示一致，否则返回第一条差异的人话描述。
  *
@@ -428,5 +567,3 @@ async function walkMarkdown(dir: string): Promise<string[]> {
   }
   return found
 }
-
-export { cardPathOf }