dsh-data-domain-knowledge 0.1.0-alpha.9 → 0.1.1-alpha.2

package/src/diagnosis/schema.ts

@@ -247,8 +247,8 @@ export function validateDiagnosis(graph: AttributionGraphData): DiagnosisIssue[]
       if (!node.verdict) issues.push(fieldIssue(node, 'verdict', '证据必须给出结论：supports / refutes / inconclusive'))
       if (!node.why?.trim()) issues.push(fieldIssue(node, 'why', '证据必须说明「为什么这个结果算数或不算数」—— 采信与剔除都得能说理由'))
     }
-    // `case` 节点只是图上的桩：案例的正文与路径住在案例卡片里，由
-    // DiagnosisSnapshot.cases 校验，不在节点上重复要求。
+    // `case` 节点只是兼容旧图的桩；当前排查视图由 SourceRaw 记录派生，
+    // 新排查不会再写 diagnosis/case WikiCard。
   }
 
   // ── 第二层：引用完整性 ────────────────────────────────────────────────────

package/src/diagnosis/seed-source.ts

@@ -6,11 +6,12 @@
  * 所以 seed 也走完整条动线：
  *
  * ```
- * 这些文本（SourceRaw） → 五类卡片 → 编译 → 图
+ * 原文（SourceRaw） → 抽取 Knowledge / Event → 归一
+ * 排查运行记录（SourceRaw） → 只读 Case 视图
  * ```
  *
- * 手册与复盘是**人写的散文**（就是下面这些字面量），卡片是从它们编译出来的结构化提取。
- * 两者内容会有重叠 —— 那是正常的：卡片是散文的投影，不是它的替代品。
+ * 手册与复盘是**人写的散文**（就是下面这些字面量）。载入示例只保存来源与可复用诊断卡；
+ * Case 从独立的排查运行记录派生，不生成第二张诊断卡。
  */
 import { SEED_CASES, SEED_RUNS } from './seed.js'
 import { renderRunSource } from './run.js'
@@ -83,7 +84,7 @@ export const SEED_HANDBOOK = `# 日报指标异常排查手册（内部版）
 同一批假设被反复验证，而永远不会被剪掉 —— 图上会长出一堆僵尸边。
 `
 
-/** 三篇复盘：案例卡片的出处。正文就是案例的散文段（现象 / 影响面 / 排查过程 / 根因 / 修复）。 */
+/** 三篇复盘：供后续抽取 Knowledge / Event 的来源文档。 */
 export function seedCaseSources(): SeedSource[] {
   return SEED_CASES.map(item => ({
     id: item.id,

package/src/diagnosis/seed.ts

@@ -19,7 +19,7 @@ import type { AttributionCase, AttributionGraphData, DiagnosisRunRecord } from '
  * | `question` | 人 | 手册与复盘 —— 卡片 `source_refs` 指向这里 |
  * | `agent_diagnosis_case` | Agent | 一次排查的过程记录（`SEED_RUNS`） |
  *
- * `SEED_GRAPH` 里**只有卡片定义得了的东西**：类型层、引用层资产、案例桩，以及六种卡片边。
+ * `SEED_GRAPH` 里有可复用诊断 Knowledge 与引用层资产；历史案例桩只用于旧格式兼容夹具。
  * `evidence` / `cause` 与四条执行边由 `SEED_RUNS` 读时解析出来 —— 把「上次查到什么」
  * 写进卡片，等于让一份可复用的知识绑死在一次执行上。
  */
@@ -122,10 +122,8 @@ export const SEED_GRAPH: AttributionGraphData = {
     { id: 'metric_daily_gmv', kind: 'asset', layer: 'reference', title: 'metric_daily_gmv', assetType: 'metric' },
     { id: 'bi_daily_dashboard', kind: 'asset', layer: 'reference', title: 'bi_daily_dashboard', assetType: 'linkage' },
 
-    // ── 实例层：案例节点是**图上的桩**（正文与有序路径住在案例卡片里） ──────
-    // 标题必须与 `SEED_CASES[].title` 是同一个字符串，否则同一份知识会有两份标题
-    // （而且还真的不一致过：「只剩」vs「只有」）。画布要在标签前显示案例 id，
-    // 那是渲染层的事（见 `nodeStyleFor` 的 labelText）。
+    // ── 兼容层：旧格式里的案例节点桩。新样例的排查记录由 SEED_RUNS 派生为只读视图。 ──
+    // 保留稳定 ID，供旧卡片编解码与历史图迁移夹具使用。
     { id: 'CASE-001', kind: 'case', layer: 'instance', title: '日报 GMV 为 0' },
     { id: 'CASE-002', kind: 'case', layer: 'instance', title: '订单数只有昨日 12%' },
     { id: 'CASE-003', kind: 'case', layer: 'instance', title: 'DAU 突增 3.1 倍' },
@@ -197,7 +195,7 @@ export const SEED_GRAPH: AttributionGraphData = {
   ],
 }
 
-/** 三个 seed 案例卡片，与上面图谱里的节点 id 对齐（0021 §11）。 */
+/** 旧版示例 Case 投影夹具；仅供历史卡片编解码与来源文案使用，当前载入流程不落盘。 */
 export const SEED_CASES: AttributionCase[] = [
   {
     id: 'CASE-001',
@@ -280,8 +278,8 @@ export const SEED_CASES: AttributionCase[] = [
  * 三次排查的**过程记录**（`agent_diagnosis_case`）。
  *
  * 它们与 `SEED_CASES` 一一对应，但**不是同一份东西**：这里是 Agent 跑出来的原始记录
- * （每条检查点真跑了什么、看到什么、这个结果算不算数），`SEED_CASES` 是之后归纳出来的
- * 案例卡片（要经人确认才生效）。一个回答「当时怎么走的」，一个回答「结论是什么」。
+ * （每条检查点真跑了什么、看到什么、这个结果算不算数）；当前 Case 视图从运行记录派生，
+ * `SEED_CASES` 仅保留作旧卡片格式夹具。
  *
  * `E7` 是 CASE-001 里那次**贵的否定**：T7.2 直连明细对账推翻了 H7。它不在案例的
  * 主路径上（主路径早就确认了 H1），但它是这次排查最贵的一条知识 —— 40 分钟的误导段

package/src/diagnosis/store.ts

@@ -7,9 +7,9 @@ import {
   cardFromRecord, cardsToGraph, CARD_EDGE_KINDS, graphToCards, parseCard, serializeCard,
   RUN_EDGE_KINDS, type DiagnosisCard,
 } from './cards.js'
-import { caseCardOf, parseRunSource, renderRunSource, runReferenceProblems, runToGraph } from './run.js'
+import { caseViewOfRun, parseRunSource, renderRunSource, runReferenceProblems, runToGraph } from './run.js'
 import type {
-  AttributionCase, AttributionEdge, AttributionGraphData, AttributionNode, AttributionNodeKind, DiagnosisRunRecord,
+  AttributionCase, AttributionEdge, AttributionEvent, AttributionGraphData, AttributionNode, AttributionNodeKind, DiagnosisRunRecord,
 } from './types.js'
 import type { KnowledgeRuntime } from '../runtime.js'
 import type { SchemaType } from '../types.js'
@@ -22,7 +22,7 @@ import type { SchemaType } from '../types.js'
  * | 目录 | 内容 | 谁是真相 |
  * | --- | --- | --- |
  * | `01_source_raw/` | 手册、复盘与排查原文 | SourceRaw 的唯一真相 |
- * | `02_wiki/diagnosis/` | 五类卡片（三段式） | **知识侧的唯一真相**，由一次排查 / 载入示例 / 迁移直接写入（0044 起不经人确认） |
+ * | `02_wiki/diagnosis/` | 历史诊断卡片 | 仅为旧数据兼容读取；新排查不再写 diagnosis/case 卡片 |
  *
  * `05_diagnosis/` 在 v1.1 撤销了（0021 §0.3）。它同时装着两类东西 —— 「一次排查的产物」
  * （源头）与「五类模板卡」（配置）—— 一个编号段混装两种性质，`rebuild --only` 的语义
@@ -58,12 +58,13 @@ const LEGACY_RUN_SHARDS: Record<string, AttributionNodeKind> = {
   'causes.jsonl': 'cause',
 }
 
-/** 读取顺序的显式来源，界面据此说明「现在看到的是哪一份」。 */
-export type DiagnosisSource = 'cards' | 'jsonl' | 'empty'
+/** 读取来源，界面据此说明当前展示的是卡片、记录、旧快照还是空库。 */
+export type DiagnosisSource = 'cards' | 'records' | 'jsonl' | 'empty'
 
 export interface DiagnosisSnapshot {
   graph: AttributionGraphData
   cases: AttributionCase[]
+  events: AttributionEvent[]
   issues: DiagnosisIssue[]
   /** 数据是不是本次调用从内置示例写进去的（只有 `loadSample()` 会把它变成 true）。 */
   seeded: boolean
@@ -86,7 +87,7 @@ export interface DiagnosisSnapshot {
  * `loadSources` 是 v1.1 新增的：一次排查的产物现在是一条 `agent_diagnosis_case`
  * 的 SourceRaw，归因图读的是它，而不是自造的 jsonl。
  */
-type DiagnosisHost = Pick<KnowledgeRuntime, 'rootDir' | 'addSource' | 'writeCard' | 'loadSources' | 'loadCards' | 'readCard'>
+type DiagnosisHost = Pick<KnowledgeRuntime, 'rootDir' | 'addSource' | 'writeCard' | 'loadSources' | 'loadCards' | 'loadEvents' | 'readCard' | 'knowledgeStoreAvailable'>
 
 export class DiagnosisStore {
   constructor(private readonly host: DiagnosisHost) {}
@@ -112,65 +113,111 @@ export class DiagnosisStore {
    * 造出「设置里改了、磁盘上那份没改」的第二真源。
    */
   async ensure(): Promise<{ seeded: boolean; migrated: boolean; problems: string[] }> {
+    /**
+     * **「读不到」不等于「空」**（0070）。
+     *
+     * `readCards()` 在存储不可用时返回空数组，于是「node:sqlite 连不上 / 属主标记不符 /
+     * 权限不对」会被读成「这个库什么都还没有」，接着走下面的旧格式迁移 —— 那是一次
+     * **写**（会写入内置种子来源与几十张卡）。一次可恢复的读故障就这样变成不可逆的污染。
+     * 所以先问一句存储到底在不在，不在就什么都不做，并如实报出来。
+     */
+    if (!await this.host.knowledgeStoreAvailable()) {
+      return { seeded: false, migrated: false, problems: ['知识存储当前不可用，已跳过内置示例与旧格式迁移；请先解决存储问题再打开本页。'] }
+    }
     if ((await this.readCards()).length > 0) return { seeded: false, migrated: false, problems: [] }
     if ((await this.legacyShardFiles()).length > 0) return await this.migrate()
     return { seeded: false, migrated: false, problems: [] }
   }
 
   /**
-   * 载入**内置示例**：一份排查手册 + 三篇复盘 + 三次排查日志 → SourceRaw → 卡片 → 图。
+   * 载入**内置示例**：一份排查手册 + 三篇复盘 + 三次排查日志 → SourceRaw、可复用诊断卡与只读排查视图。
    *
    * 只有用户明确点了「载入内置示例」才走这里（`ensure()` 不再自动调用）。幂等：
    * `addSource` 按 `externalId`、`writeCard` 按 entityId，点两次不会写出第二份。
    *
-   * **它走的是「提议 → 确认」那条门，不是绕过它**（0021 §6.1）。区别只在确认者是谁：
-   * 用户点「载入内置示例」这个动作本身就是**对整批示例的确认**，所以这里给每条提议记下
-   * `confirmedBy = user:load-sample`，然后照常走 `writeCard`。这样做的两个好处：
-   * 待办区里能看到这批卡片是怎么来的；而「未确认不落 `02_wiki/`」这条规则没有被开一个
-   * 后门 —— 例外是**确认者的身份**，不是门的缺失。
+   * 示例里的可复用诊断 Knowledge 是预先整理好的演示数据，直接写入当前知识库。
+   * 三条排查记录作为 SourceRaw 写入，并由读取层派生只读 Case 视图；不创建 `diagnosis/case` WikiCard。
    */
   async loadSample(): Promise<{ seeded: boolean; migrated: boolean; problems: string[] }> {
+    /**
+     * 载入示例是一次**写**，所以门要在服务端，不能只在界面上。
+     *
+     * `canLoadSample` 原来只出现在 `snapshot()` 的返回值里，用来决定那枚按钮显不显示 ——
+     * 而 `POST /diagnosis/sample` 直接调这里。任何非界面的调用方（脚本、旧标签页、
+     * 以后的 runbook）打一次，就能在一个已经有真实知识的库上注入一整套演示数据，
+     * 库里于是有两份互相矛盾的知识，而这正是本文件开头要防的事。
+     *
+     * **不给覆盖开关**：曾经加过一个 `force`，但它没有任何调用方（路由按无参调用），
+     * 而且「往有真实知识的库里再塞一套演示」本来就不该是一个可选项 —— 那正是这条门要防的。
+     */
+    const allowed = await this.sampleAllowed()
+    if (!allowed.ok) {
+      return { seeded: false, migrated: false, problems: [`这个知识库里已经有内容（${allowed.reason}），不再载入内置示例。`] }
+    }
     const { problems: sourceProblems, refs } = await this.writeSources(seedSources())
-    const cards = withSourceRefs(graphToCards(SEED_GRAPH, SEED_CASES), refs, SEED_CASES)
+    const cards = withSourceRefs(
+      graphToCards(SEED_GRAPH),
+      refs,
+      SEED_CASES,
+    )
     const problems = [...sourceProblems, ...await this.writeCards(cards, 'user:load-sample')]
     return { seeded: true, migrated: false, problems }
   }
 
+  /** Read Event entities for the Knowledge & Event view without building the diagnosis graph. */
+  async listEvents(): Promise<AttributionEvent[]> {
+    return this.readEvents()
+  }
+
+  /**
+   * 「能不能载入内置示例」的**唯一**判据 —— 只看四个计数。
+   *
+   * 抽出来是因为它有两个消费者（`snapshot()` 的 `canLoadSample` 与 `loadSample()` 的门），
+   * 各写一份的话，界面说「可以」而服务端说「不行」只是时间问题。判据与**读取**分开：
+   * 两边各自的读取是必要的（一个已经拿到了卡片/Event，一个还没读），规则不必要各写一遍。
+   */
+  private static sampleGate(state: { cards: number; events: number; runs: number; shards: number }): { ok: boolean; reason?: string } {
+    if (state.cards > 0) return { ok: false, reason: '已经有卡片' }
+    if (state.events > 0) return { ok: false, reason: '已经有 Event' }
+    if (state.runs > 0) return { ok: false, reason: '已经有排查记录' }
+    if (state.shards > 0) return { ok: false, reason: '还有旧格式的 05_diagnosis 分片等待迁移' }
+    return { ok: true }
+  }
+
+  private async sampleAllowed(): Promise<{ ok: boolean; reason?: string }> {
+    return DiagnosisStore.sampleGate({
+      cards: (await this.readCards()).length,
+      events: (await this.readEvents()).length,
+      runs: (await this.readRuns()).records.length,
+      shards: (await this.legacyShardFiles()).length,
+    })
+  }
+
   async snapshot(): Promise<DiagnosisSnapshot> {
     const { seeded, migrated, problems } = await this.ensure()
     const cards = await this.readCards()
+    const events = await this.readEvents()
+    const baseGraph = cards.length > 0 ? { nodes: [], edges: [] } : await this.readLegacyGraph()
+    const baseCases = cards.length > 0 ? [] : await this.readLegacyCases()
+    const built = await this.buildGraph(cards, baseGraph, baseCases)
+    const runRecords = (await this.readRuns()).records
     /**
-     * 「什么都没有」= 没有卡片、也没有旧 jsonl。它是**可以载入内置示例**的唯一条件：
+     * 「什么都没有」= 没有卡片、Event、排查日志和旧 jsonl。它是**可以载入内置示例**的唯一条件：
      * 已经有知识（不管哪一代形态）时不该再往里塞示例 —— 那会变成第二份互相矛盾的知识。
      */
-    const canLoadSample = cards.length === 0 && (await this.legacyShardFiles()).length === 0
-
-    if (cards.length > 0) {
-      const built = await this.buildGraph(cards)
-      return {
-        graph: built.graph,
-        cases: built.cases,
-        issues: validateDiagnosis(built.graph),
-        seeded,
-        migrated,
-        source: 'cards',
-        canLoadSample: false,
-        problems: [...problems, ...built.problems],
-      }
-    }
-
-    // 还没有卡片：旧 jsonl 就是当前可读的来源；两份都没有就是一个空库。
-    const graph = await this.readLegacyGraph()
-    const cases = await this.readLegacyCases()
+    const canLoadSample = DiagnosisStore.sampleGate({
+      cards: cards.length, events: events.length, runs: runRecords.length, shards: (await this.legacyShardFiles()).length,
+    }).ok
     return {
-      graph,
-      cases,
-      issues: validateDiagnosis(graph),
+      graph: built.graph,
+      cases: built.cases,
+      events,
+      issues: validateDiagnosis(built.graph),
       seeded,
       migrated,
-      source: canLoadSample ? 'empty' : 'jsonl',
+      source: canLoadSample ? 'empty' : cards.length > 0 ? 'cards' : events.length > 0 || runRecords.length > 0 ? 'records' : 'jsonl',
       canLoadSample,
-      problems,
+      problems: [...problems, ...built.problems],
     }
   }
 
@@ -181,21 +228,27 @@ export class DiagnosisStore {
    * 与四条执行边全部来自 `agent_diagnosis_case` 的 SourceRaw。合成一张图是**读**的时候
    * 做的，不是写的时候 —— 写的时候合成，等于让一次执行的结果变成可复用的知识。
    */
-  private async buildGraph(cards: DiagnosisCard[]): Promise<{ graph: AttributionGraphData; cases: AttributionCase[]; problems: string[] }> {
+  private async buildGraph(cards: DiagnosisCard[], baseGraph: AttributionGraphData = { nodes: [], edges: [] }, baseCases: AttributionCase[] = []): 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 nodes: AttributionNode[] = [...baseGraph.nodes, ...compiled.graph.nodes]
+    const edges: AttributionEdge[] = [...baseGraph.edges, ...compiled.graph.edges]
+    const knownCardNodes = [...baseGraph.nodes, ...compiled.graph.nodes]
+    const cases = new Map<string, AttributionCase>()
+    for (const item of [...baseCases, ...compiled.cases]) cases.set(item.id, item)
 
     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)])
+      const known = new Set([...knownCardNodes.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)
+      const symptomTitle = knownCardNodes.find(node => node.id === record.symptomId)?.title ?? record.symptomId
+      const view = caseViewOfRun(record, symptomTitle)
+      cases.set(view.id, view)
     }
 
     /**
@@ -210,7 +263,7 @@ export class DiagnosisStore {
     nodes.push(...legacyRun.nodes)
     edges.push(...legacyRun.edges)
 
-    return { graph: dedupe({ nodes, edges }, problems), cases: compiled.cases, problems }
+    return { graph: dedupe({ nodes, edges }, problems), cases: [...cases.values()], problems }
   }
 
   /**
@@ -238,14 +291,15 @@ export class DiagnosisStore {
 
   async readGraph(): Promise<AttributionGraphData> {
     const cards = await this.readCards()
-    if (cards.length > 0) return (await this.buildGraph(cards)).graph
-    return await this.readLegacyGraph()
+    const baseGraph = cards.length > 0 ? { nodes: [], edges: [] } : await this.readLegacyGraph()
+    return (await this.buildGraph(cards, baseGraph)).graph
   }
 
   async readCases(): Promise<AttributionCase[]> {
     const cards = await this.readCards()
-    if (cards.length > 0) return cardsToGraph(cards).cases
-    return await this.readLegacyCases()
+    const baseGraph = cards.length > 0 ? { nodes: [], edges: [] } : await this.readLegacyGraph()
+    const baseCases = cards.length > 0 ? [] : await this.readLegacyCases()
+    return (await this.buildGraph(cards, baseGraph, baseCases)).cases
   }
 
   /* ────────────────────────────────────────────── 卡片：读写 ── */
@@ -267,6 +321,35 @@ export class DiagnosisStore {
     return cards
   }
 
+  /** Event 与 Knowledge 同层，读取独立的 event 实体表。 */
+  private async readEvents(): Promise<AttributionEvent[]> {
+    const events = await this.host.loadEvents()
+    return events.map(event => ({
+      id: event.id,
+      title: event.title,
+      summary: event.summary,
+      identityType: event.identityType,
+      ...(event.externalId ? { externalId: event.externalId } : {}),
+      ...(event.occurredAt ? { occurredAt: event.occurredAt } : {}),
+      ...(event.symptom ? { symptom: event.symptom } : {}),
+      coordinate: event.coordinate,
+      timeline: event.timeline.map((step, index) => ({
+        id: step.id || `timeline-${index + 1}`,
+        type: step.type,
+        description: step.description,
+        ...(step.result ? { result: step.result } : {}),
+        ...(step.at ? { at: step.at } : {}),
+        sourceId: step.sourceId,
+      })),
+      rootCauses: event.rootCauses,
+      outcomes: event.outcomes,
+      missing: event.missing,
+      sources: event.sources.filter(source => source.found && source.documentId && source.quote)
+        .map(source => ({ documentId: source.documentId, quote: source.quote })),
+      recordCount: event.records.length,
+    })).sort((left, right) => (right.occurredAt ?? '').localeCompare(left.occurredAt ?? '') || left.title.localeCompare(right.title))
+  }
+
   /* ────────────────────────────────────────────── 一次排查的记录 ── */
 
   /**
@@ -279,6 +362,7 @@ export class DiagnosisStore {
     const records: DiagnosisRunRecord[] = []
     const problems: string[] = []
     for (const source of await this.host.loadSources()) {
+      if (!source.sourceId.startsWith('diagnosis:') && !source.content.includes('```json diagnosis-run')) continue
       const record = parseRunSource(source.content)
       if (record) records.push(record)
       else problems.push(`诊断日志 ${source.sourceId} 里没有可解析的 \`json diagnosis-run\` 块，已跳过`)
@@ -287,15 +371,11 @@ export class DiagnosisStore {
   }
 
   /**
-   * 一次排查结束：写一条 SourceRaw，并**直接写入**一张案例卡片。
-   *
-   * 0044：案例卡片原来只提议、等人确认。与编译那条链路一样改成直接入库 ——
-   * 一次排查的价值就在于「当时是怎么走的」，让它停在待办队列里等于把经验丢掉。
-   * 卡片会被标成 `unreviewed`，人在「知识库 → Wiki」里 review 它。
-   *
-   * 幂等：`externalId` = runId，同一次排查重跑不会写出第二条来源；卡片按 entityId 写入。
+   * 一次排查结束只写一条 SourceRaw。案例视图从这条记录派生；Knowledge / Event 的抽取与归一
+   * 仍由知识处理阶段执行，避免把同一份排查过程再写成另一张 WikiCard。
+   * 幂等：`externalId` = runId，同一次排查重跑不会写出第二条来源。
    */
-  async recordRun(record: DiagnosisRunRecord): Promise<{ sourceId?: string; entityId?: string; problems: string[] }> {
+  async recordRun(record: DiagnosisRunRecord): Promise<{ sourceId?: string; problems: string[] }> {
     const problems: string[] = []
     const added = await this.host.addSource({
       title: `AI 诊断日志 · ${record.symptomId} · ${record.runId}`,
@@ -306,18 +386,7 @@ export class DiagnosisStore {
     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 }
+    return { sourceId, problems }
   }
 
   /* ────────────────────────────────────────────── 旧知识根迁移 ── */
@@ -460,8 +529,8 @@ export function renderCardBody(card: DiagnosisCard): string {
 /**
  * 给卡片挂出处。
  *
- * 规则是**数据驱动的**，不是凭印象分的：案例卡片与它自己的复盘原文一一对应；
- * 其它卡片取「第一篇走过它的复盘」，没有走过它的就挂那本手册。
+ * 规则是**数据驱动的**，不是凭印象分的：可复用诊断卡优先引用第一篇走过该节点的复盘；
+ * 没有经过复盘的节点引用手册。历史 Case 卡仍由旧数据读取，不在新示例里生成。
  */
 function withSourceRefs(
   cards: DiagnosisCard[],

package/src/diagnosis/types.ts

@@ -15,7 +15,8 @@ import type { ProblemClassId } from './problem-classes.js'
 export type NodeLayer = 'type' | 'reference' | 'instance'
 
 /**
- * 九类归因节点。与 wiki 卡片的 `entity_type` 一一对应（`asset` 与三类执行产物除外）。
+ * 九类归因图节点。当前 Knowledge 节点可对应 WikiCard；`case` 是排查记录视图，
+ * `asset` 与执行产物也不对应 WikiCard。历史 Case WikiCard 仅为兼容数据。
  *
  * **两个名字用的是下划线**（`check_point` / `failure_reason`），卡片类型用连字符
  * （`diagnosis/check-point` / `diagnosis/failure-reason`）：kind 是代码里的标识符，
@@ -187,18 +188,9 @@ export interface AttributionGraphData {
 }
 
 /**
- * 案例 = **一篇 wiki 定义 + 一条有序排查路径**。
- *
- * 它住在领域层而不是示例里（原来是 `seed.ts`）：案例是编译产物的一种
- * （`cardsToGraph()` 从卡片把它算出来，`/diagnosis/graph` 把它发给界面），
- * 而示例只是**一份**案例的取值来源。视图要渲染「服务端给的案例」，
- * 那它 import 的形状就不该从示例模块里拿。
- *
- * 两段各有明确消费者，不能合并：
- * - `sections` 是给人读、给向量召回的散文（可 diff、可评审、可追溯）；
- * - `path` 是给图和剪枝用的结构（有序、可判真假、带被否定的分支）。
- *
- * 序和枚举一旦写进散文，归并算法就再也读不到它们了 —— 所以路径单独成段。
+ * Case 是一次排查记录的只读展示投影，不是持久化实体。
+ * `sections` 供人阅读，`path` 保留检查顺序与被否定的分支；来源是 SourceRaw 运行记录。
+ * 历史 `diagnosis/case` WikiCard 仍可读取，但新的运行与示例载入不再生成它。
  */
 export interface CaseSection {
   heading: string
@@ -223,6 +215,33 @@ export interface AttributionCase {
   /** 误导段：最贵的那条知识。没有它，下次还会有人在同一个假设上烧掉四十分钟。 */
   misleading?: { nodeId: string; label: string; wastedMinutes: number; why: string }
   rootCause: string
+  /** 排查记录里的根因确认状态；旧案例卡片缺省时按已有内容展示。 */
+  rootCauseStatus?: 'confirmed' | 'unconfirmed'
+}
+
+/** 从独立 Event 实体读取的一次具体发生，供智能归因的事件视图展示。 */
+export interface AttributionEvent {
+  id: string
+  title: string
+  summary: string
+  identityType: 'external_id' | 'composite' | 'source'
+  externalId?: string
+  occurredAt?: string
+  symptom?: string
+  coordinate: { object: string | null; action: string | null; scene: string | null }
+  timeline: Array<{
+    id: string
+    type: string
+    description: string
+    result?: string
+    at?: string
+    sourceId: string
+  }>
+  rootCauses: Array<{ text: string; status: 'confirmed' | 'suspected' | null; sourceId: string }>
+  outcomes: Array<{ text: string; sourceId: string }>
+  missing: string[]
+  sources: Array<{ documentId: string; quote: string }>
+  recordCount: number
 }
 
 export interface AttributionStats {
@@ -298,8 +317,8 @@ export interface DiagnosisRunCause {
 /**
  * 一次排查的完整记录。落到 SourceRaw 正文里的 ```json diagnosis-run 块。
  *
- * 它与案例卡片的区别是**谁写的、有没有被归纳过**：这里是 Agent 跑完一圈留下的
- * 原始记录，案例卡片是**之后**归纳出来的知识（而且必须经人确认才生效）。
+ * 它是 Agent 跑完一圈留下的原始记录。Case 视图从这条记录派生；可复用 Knowledge 与 Event
+ * 由独立抽取和归一阶段生成，不在这条记录写成第二张卡片。
  */
 export interface DiagnosisRunRecord {
   /** 本次排查的 runId。同时用作 SourceRaw 的 `externalId`，重跑不产生第二条记录。 */

package/src/environment/dsh-python.ts

@@ -0,0 +1,156 @@
+/**
+ * DSH 自带 Python 的落点（2026-10-18）。
+ *
+ * 桌面端把 Python 3.12 **打在自己的运行时里**：
+ * `<App>/Contents/Resources/runtime/primary-runtime/dependencies/python`（清单见同目录
+ * `runtime.json` 的 `python` 字段）。但这一层没把位置告诉插件 —— 宿主不导出 `DSH_PYTHON`，
+ * 于是「一键准备」的默认值 `python3` 落到了系统那个 3.9（macOS 命令行工具自带的正是 3.9），
+ * 第一步就报「Python 版本不受支持」，而机器上明明有 3.12。
+ *
+ * 所以这里自己找，顺序是：
+ *
+ * 1. **`DSH_PYTHON`** —— 显式覆盖永远是第一位的（文档里承诺的自定义入口）。
+ * 2. **DSH 自带的那一个** —— 从宿主告诉我们的两个锚点推：Electron 的 `resourcesPath`，
+ *    以及 `process.execPath`（桌面端是 `Contents/MacOS/<App>`，`ELECTRON_RUN_AS_NODE` 下
+ *    它就是运行时用的那个可执行文件）。两者都会向上找几级，因为包装脚本与真实二进制的
+ *    层级不一定一样。
+ * 3. **PATH 上的 `python3`** —— 都没有才退回。
+ *
+ * ## 这里只回答「哪个路径最可能是它」，不回答「它是哪个版本」
+ *
+ * 版本判断必须由准备阶段做（它要跑一次 `sys.version_info`，并把结论写进安装日志）。
+ * 在这里再探测一遍等于把同步可判的事情做成两次异步调用，而且拿到版本也不知道该报给谁。
+ */
+
+import { existsSync } from 'node:fs'
+import { posix, win32 } from 'node:path'
+import { runProcess } from './process.js'
+
+/**
+ * 按**目标平台**拼路径，不按跑这段代码的机器。
+ *
+ * 生产里两者永远一致（Windows 上 `process.platform` 就是 `win32`），但这里允许注入平台 ——
+ * 而 POSIX 上的 `dirname('C:\\x\\node.exe')` 会给出 `'.'`，于是那条 Windows 断言在 mac 上
+ * 跑不通。用平台自己的路径工具，注入才是真的能测。
+ */
+const pathsFor = (platform: NodeJS.Platform): typeof posix => platform === 'win32' ? win32 : posix
+
+/** 相对 App 资源根的落点。`runtime.json` 就在它的上一级。 */
+const BUNDLE_RELATIVE = ['runtime/primary-runtime/dependencies/python']
+
+/** 一个解释器可能叫的几个名字。Windows 的独立发行版把 `python.exe` 放在根上。 */
+function interpreterNames(root: string, platform: NodeJS.Platform): string[] {
+  const { join } = pathsFor(platform)
+  return platform === 'win32'
+    ? [join(root, 'python.exe'), join(root, 'python3.exe')]
+    : [join(root, 'bin', 'python3'), join(root, 'bin', 'python')]
+}
+
+/** 从锚点向上走几级，每一级都试「本体」和「本体/Resources」两种排法。 */
+function bundleCandidates(anchor: string, platform: NodeJS.Platform): string[] {
+  const { dirname, join } = pathsFor(platform)
+  const found: string[] = []
+  let dir = anchor
+  for (let depth = 0; depth < 6; depth += 1) {
+    for (const relative of BUNDLE_RELATIVE) {
+      for (const name of interpreterNames(join(dir, relative), platform)) found.push(name)
+      // macOS / Windows 的 `.app`：真实资源在 `Contents/Resources`，而锚点是 `Contents/MacOS`。
+      for (const name of interpreterNames(join(dir, 'Resources', relative), platform)) found.push(name)
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return found
+}
+
+export interface PythonPick {
+  /** 要拿去建虚拟环境的解释器。 */
+  path: string
+  /** 它从哪来 —— 报错时要能说清「我没找到自带的那个」。 */
+  source: 'override' | 'bundled' | 'path'
+}
+
+export interface PythonProbe {
+  env?: Record<string, string | undefined>
+  /** Electron 的 `process.resourcesPath`；不在 Electron 里时省略。 */
+  resourcesPath?: string
+  /** 宿主的可执行文件路径；默认取 `process.execPath`。 */
+  execPath?: string
+  platform?: NodeJS.Platform
+  /** 存在性判断，测试里换成假的。 */
+  exists?: (path: string) => boolean
+}
+
+/**
+ * 挑一个基础解释器。**纯函数**（存在性判断可注入），所以「自带优先于 PATH」这条能被单独断言。
+ */
+export function pickBasePython(probe: PythonProbe = {}): PythonPick {
+  const env = probe.env ?? process.env
+  const override = env.DSH_PYTHON?.trim()
+  if (override) return { path: override, source: 'override' }
+  const platform = probe.platform ?? process.platform
+  const exists = probe.exists ?? existsSync
+  const anchors: string[] = []
+  if (probe.resourcesPath) anchors.push(probe.resourcesPath)
+  const { dirname } = pathsFor(platform)
+  const executables = [env.DSH_DESKTOP_NODE_EXECUTABLE, probe.execPath ?? process.execPath]
+  for (const executable of executables) {
+    const value = executable?.trim()
+    if (value) anchors.push(dirname(value))
+  }
+  for (const anchor of anchors) {
+    for (const candidate of bundleCandidates(anchor, platform)) {
+      if (exists(candidate)) return { path: candidate, source: 'bundled' }
+    }
+  }
+  return { path: 'python3', source: 'path' }
+}
+
+/** 报错里那句「没找到自带的那一个」用得上。 */
+export function pythonSourceLabel(source: PythonPick['source']): string {
+  return source === 'override' ? 'DSH_PYTHON' : source === 'bundled' ? 'DSH 自带运行时' : 'PATH 上的 python3'
+}
+
+/**
+ * 这个解释器能不能加载**第三方原生扩展**（torch 这类 pip 装的 dylib）。
+ *
+ * macOS 上不行的一种情况是真实存在过的（2026-10-18 实测）：DSH 桌面端把 Python 3.12
+ * 打在自己的运行时里，并给它签了 Developer ID + **hardened runtime**
+ * （`flags=0x10000(runtime)`），又没有 `com.apple.security.cs.disable-library-validation`。
+ * 库校验因此生效 —— 它只肯加载**同一 Team ID** 签的 dylib。pip 上的 torch 是 ad-hoc 签名
+ * （Team ID 为空），于是：
+ *
+ * ```
+ * OSError: dlopen(.../libtorch_global_deps.dylib, 0x000A):
+ *   code signature ... not valid for use in process:
+ *   mapping process and mapped file (non-platform) have different Team IDs
+ * ```
+ *
+ * 同一个 dylib 换成 uv 管的独立 CPython（`adhoc, linker-signed`，没有 runtime 标记）
+ * 就能加载 —— 这一条在同一台机器上验过。
+ *
+ * 判据读的是 `codesign` 的 flags，不看路径：运行时目录在某些安装形态下不在 `.app` 里，
+ * 而「带不带 hardened runtime」才是真正决定库校验的那件事。没有 `codesign`（Linux/Windows）
+ * 或读不到（没签名）时一律当「能加载」—— 不因为探测失败就改道去下载解释器。
+ */
+export async function hasHardenedRuntime(path: string, run: typeof runProcess = runProcess): Promise<boolean> {
+  if (process.platform !== 'darwin') return false
+  try {
+    const output = await run('/usr/bin/codesign', ['-dv', '--verbose=2', path], { timeoutMs: 10_000 })
+    const flags = /flags=0x[0-9a-f]+\(([^)]*)\)/i.exec(output)?.[1] ?? ''
+    return flags.split(',').some(flag => flag.trim() === 'runtime')
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 这个解释器要不要换成 uv 管的那一个。
+ *
+ * 判据只有一条：**带 hardened runtime 就用不了第三方原生扩展**（见 `hasHardenedRuntime`）。
+ * `DSH_PYTHON` 显式给的不改道 —— 那是用户的选择；插件只把风险写进日志。
+ */
+export function needsManagedInterpreter(pick: PythonPick, hardened: boolean): boolean {
+  return hardened && pick.source !== 'override'
+}