dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/diagnosis/cards.ts

@@ -0,0 +1,498 @@
+import { DIAGNOSIS_ENTITIES, type DiagnosisEntityType } from './schema.js'
+import type { AttributionCase } from './seed.js'
+import type {
+  AttributionEdge, AttributionEdgeKind, AttributionGraphData, AttributionNode, AttributionNodeKind,
+  FailureMode,
+} from './types.js'
+
+/**
+ * 诊断卡片的**编解码**：markdown 卡片 ⇄ 图上的节点与边（0021 §6.3）。
+ *
+ * ## 为什么这一层必须存在
+ *
+ * 在它之前，智能归因的图只有一条来源：`seed.ts` 里的 TypeScript 字面量，被
+ * `DiagnosisStore.ensure()` 直接写成 `05_diagnosis/*.jsonl`。那意味着**排查思路从来没有
+ * 进过 wiki**：它不在 `01_source_truth` 里、不是 `02_wiki` 的卡片、编译器连
+ * `diagnosis/hypothesis` 这个 entity_type 都不认 —— 于是它既不会被 wikiNote 化，
+ * 也不会进向量索引，**召回永远召不到它**。而「遇到类似问题先召回」正是这个产品的主张。
+ *
+ * 这一层把图变成卡片的**投影**：卡片是手写的（人写、Agent 写、从 SourceRaw 编译而来），
+ * 图是算出来的。§4「存图、显树」讲的是同一件事 —— 存的是知识，图是它的一种读法。
+ *
+ * ## 卡片三段式与「谁由卡片定义」的边界
+ *
+ * ```
+ * front matter ── 信封：id / entity_type / title / summary / status / owner / source_refs
+ * 正文小节 ────── 人读、给向量召回（可 diff、可评审）
+ * 结构化块 ────── 机器读：枚举、引用、**顺序**、逐边属性
+ * ```
+ *
+ * 边界要说清楚，否则「为什么这张图里有东西不在卡片里」会变成一个反复出现的疑问：
+ *
+ * | 图上的东西 | 谁定义 | 为什么 |
+ * | --- | --- | --- |
+ * | symptom / hypothesis / check / failure-mode / case 节点 | **卡片** | 这五类是人写的知识（§6.4） |
+ * | asset 节点 | 引用反推 | 它随数据目录同步，不手写；卡片里只留 id |
+ * | 现象→假设 / 假设→检查 / 假设→失败模式 / 资产→假设 / 案例→现象 边 | **卡片** | 都是卡片字段的确定性投影 |
+ * | evidence / cause 节点，produces / supports / refutes / confirmed_as 边 | **一次排查** | 它们是一次执行的结果，不是知识；由排查自动写入（§6.4） |
+ *
+ * 最后一行不是妥协，是分层：把「上次查到什么」写进卡片，等于让一份可复用的知识
+ * 绑死在一次具体的执行上。
+ */
+
+/** 卡片正文里那个机器可读块的围栏标记。用带名字的围栏，方便人和编辑器识别。 */
+const BLOCK_FENCE = 'json diagnosis'
+
+export interface DiagnosisCardSection {
+  heading: string
+  body: string
+}
+
+export interface DiagnosisCard {
+  entityId: string
+  entityType: DiagnosisEntityType
+  title: string
+  /** 一句话说明。落到节点上是 `summary`（现象上是 `observable`）。 */
+  summary?: string
+  status: string
+  owner?: string
+  sourceRefs: string[]
+  updatedAt?: string
+  /** 正文小节，顺序按 spec。 */
+  sections: DiagnosisCardSection[]
+  /** 结构化块。字段随 entity_type 而定，见 `CARD_LAYOUT`。 */
+  block: Record<string, unknown>
+}
+
+/** 卡片不声明状态时的默认值：它已经被人写过一遍，只是还没走评审流程。 */
+export const DEFAULT_CARD_STATUS = 'reviewed'
+
+/**
+ * 每种卡片：结构化块里放哪些字段，以及哪个字段是「节点的一句话说明」。
+ *
+ * 这张表是**唯一的映射声明**。校验、序列化、反序列化都读它 —— 三处各写一份字段清单，
+ * 迟早会出现「校验要求 A、写盘漏了 B、读回来又不认识 C」。
+ */
+const CARD_LAYOUT: Record<DiagnosisEntityType, { block: string[]; summaryFrom: string }> = {
+  'diagnosis/symptom': {
+    // 现象的「一句话说明」就是它的可观测口径 —— §6.4 把 observable 定成必填正因如此。
+    block: ['observable', 'entry_when', 'problem_class', 'problem_subclass', 'candidates'],
+    summaryFrom: 'observable',
+  },
+  'diagnosis/hypothesis': {
+    block: ['discriminator', 'not_when', 'failure_mode', 'verified_by', 'assets', 'reuse_count', 'stale'],
+    summaryFrom: 'summary',
+  },
+  'diagnosis/check': {
+    block: ['cost_minutes', 'automation', 'verdict_true', 'verdict_false', 'stale'],
+    summaryFrom: 'summary',
+  },
+  'diagnosis/failure-mode': {
+    block: ['code', 'label', 'boundary'],
+    summaryFrom: 'summary',
+  },
+  'diagnosis/case': {
+    block: ['symptom', 'path', 'duration_minutes', 'misleading', 'root_cause', 'impact', 'prevention'],
+    summaryFrom: 'summary',
+  },
+}
+
+/** 反向查表：节点 kind → 卡片 entity_type。`asset` 与执行产物没有卡片。 */
+export function entityTypeOf(kind: AttributionNodeKind): DiagnosisEntityType | undefined {
+  return DIAGNOSIS_ENTITIES.find(spec => spec.kind === kind)?.entityType
+}
+
+/** 卡片能定义的节点类型。其余（asset / evidence / cause / unknown）不走卡片。 */
+export const CARD_NODE_KINDS: AttributionNodeKind[] = DIAGNOSIS_ENTITIES.map(spec => spec.kind)
+
+/** 卡片能定义的边：全部是卡片字段的确定性投影。 */
+export const CARD_EDGE_KINDS: AttributionEdgeKind[] = [
+  'may_be_caused_by', 'verified_by', 'categorized_as', 'indexed_from', 'instance_of',
+]
+
+/** 一次排查写下的边。它们不属于任何卡片，见文件头的边界表。 */
+export const RUN_EDGE_KINDS: AttributionEdgeKind[] = ['produces', 'supports', 'refutes', 'confirmed_as']
+
+/* ─────────────────────────────────────────────── 序列化：卡片 → markdown ── */
+
+function frontMatterValue(value: unknown): string {
+  return typeof value === 'string' ? value : JSON.stringify(value)
+}
+
+/**
+ * 卡片 → markdown 文本。
+ *
+ * 结构化块放在**正文里**而不是 front matter 的 JSON 里：改一个字段就从「一个几百字符的
+ * 长行整体重写」变成「一行改动」，review 时才看得出改了哪条判据、哪一步顺序。
+ * 这正是 §6.3 把三段分开的理由。
+ */
+export function serializeCard(card: DiagnosisCard): string {
+  const front: Array<[string, unknown]> = [
+    ['entity_id', card.entityId],
+    ['entity_type', card.entityType],
+    ['title', card.title],
+    ...(card.summary ? [['summary', card.summary] as [string, string]] : []),
+    ['status', card.status],
+    ...(card.owner ? [['owner', card.owner] as [string, string]] : []),
+    ['source_refs', card.sourceRefs],
+    ...(card.updatedAt ? [['updated_at', card.updatedAt] as [string, string]] : []),
+  ]
+  const body = card.sections
+    .filter(section => section.body.trim() !== '')
+    .map(section => `## ${section.heading}\n\n${section.body.trim()}`)
+    .join('\n\n')
+  const block = JSON.stringify(card.block, null, 2)
+  return `---\n${front.map(([key, value]) => `${key}: ${frontMatterValue(value)}`).join('\n')}\n---\n\n${body}\n\n\`\`\`${BLOCK_FENCE}\n${block}\n\`\`\`\n`
+}
+
+/* ─────────────────────────────────────────────── 反序列化：markdown → 卡片 ── */
+
+export function parseCard(source: string): DiagnosisCard | undefined {
+  // 复用运行时的 front matter 解析（同一个 yaml 子集），不另写一套。
+  const parsed = parseFrontmatter(source)
+  const entityType = String(parsed.frontmatter.entity_type ?? '')
+  if (!isEntityType(entityType)) return undefined
+  const entityId = String(parsed.frontmatter.entity_id ?? '').trim()
+  if (!entityId) return undefined
+
+  const match = parsed.content.match(new RegExp('```' + BLOCK_FENCE + '\\s*\\n([\\s\\S]*?)```'))
+  let block: Record<string, unknown> = {}
+  if (match) {
+    try {
+      const value = JSON.parse(match[1])
+      if (value && typeof value === 'object' && !Array.isArray(value)) block = value as Record<string, unknown>
+    } catch { /* 块坏了不静默降级成空对象：留空之后由三层校验的「格式层」报缺字段。 */ }
+  }
+  const body = match ? parsed.content.replace(match[0], '') : parsed.content
+  const refs = parsed.frontmatter.source_refs
+
+  return {
+    entityId,
+    entityType,
+    title: String(parsed.frontmatter.title ?? entityId),
+    ...(parsed.frontmatter.summary ? { summary: String(parsed.frontmatter.summary) } : {}),
+    status: String(parsed.frontmatter.status ?? DEFAULT_CARD_STATUS),
+    ...(parsed.frontmatter.owner ? { owner: String(parsed.frontmatter.owner) } : {}),
+    sourceRefs: Array.isArray(refs) ? refs.map(String) : [],
+    ...(parsed.frontmatter.updated_at ? { updatedAt: String(parsed.frontmatter.updated_at) } : {}),
+    sections: splitSections(body),
+    block,
+  }
+}
+
+/**
+ * 只解析 front matter 与正文。
+ *
+ * 与 `runtime.ts` 里的 `parseMarkdown` 是同一条规则（同一个 yaml 子集），这里保留一份
+ * 只读副本是为了让 `diagnosis/` 不反向依赖宿主的运行时 —— 领域模块被 runtime 依赖，
+ * 不能形成环。
+ */
+function parseFrontmatter(source: string): { frontmatter: Record<string, unknown>; content: string } {
+  if (!source.startsWith('---')) return { frontmatter: {}, content: source.trim() }
+  const end = source.indexOf('\n---', 3)
+  if (end < 0) return { frontmatter: {}, content: source.trim() }
+  const frontmatter: Record<string, unknown> = {}
+  for (const line of source.slice(3, end).replace(/^\n/, '').split(/\r?\n/)) {
+    const separator = line.indexOf(':')
+    if (separator <= 0) continue
+    const key = line.slice(0, separator).trim()
+    const text = line.slice(separator + 1).trim()
+    if (text === 'true') frontmatter[key] = true
+    else if (text === 'false') frontmatter[key] = false
+    else if (text === 'null') frontmatter[key] = null
+    else if (/^-?\d+(\.\d+)?$/.test(text)) frontmatter[key] = Number(text)
+    else if ((text.startsWith('[') && text.endsWith(']')) || (text.startsWith('{') && text.endsWith('}'))) {
+      try { frontmatter[key] = JSON.parse(text) } catch { frontmatter[key] = text.replace(/^['"]|['"]$/g, '') }
+    } else frontmatter[key] = text.replace(/^['"]|['"]$/g, '')
+  }
+  return { frontmatter, content: source.slice(end + 4).trim() }
+}
+
+function splitSections(body: string): DiagnosisCardSection[] {
+  const sections: DiagnosisCardSection[] = []
+  let heading: string | undefined
+  let lines: string[] = []
+  const flush = (): void => {
+    if (heading !== undefined) sections.push({ heading, body: lines.join('\n').trim() })
+    lines = []
+  }
+  for (const line of body.split(/\r?\n/)) {
+    const match = /^##\s+(.+)$/.exec(line)
+    if (match) { flush(); heading = match[1].trim() } else if (heading !== undefined) lines.push(line)
+  }
+  flush()
+  return sections.filter(section => section.body !== '')
+}
+
+function isEntityType(value: string): value is DiagnosisEntityType {
+  return DIAGNOSIS_ENTITIES.some(spec => spec.entityType === value)
+}
+
+/* ─────────────────────────────────────────────── 图 → 卡片 ── */
+
+/**
+ * 类型层与案例 → 卡片。
+ *
+ * `asset` / `evidence` / `cause` 节点**不产出卡片**：它们不是手写的知识（§6.4）。
+ * 被假设引用的资产会在反序列化时按 id 补一个最小节点回来。
+ */
+export function graphToCards(graph: AttributionGraphData, cases: AttributionCase[] = []): DiagnosisCard[] {
+  const cards: DiagnosisCard[] = []
+
+  for (const node of graph.nodes) {
+    // 案例节点只是图上的**桩**：它的正文与有序路径住在 `cases` 里（§6.4）。图上的桩不单独成卡，
+    // 否则同一个 CASE-001 会有两张卡 —— 一张带路径、一张空壳，读图时看谁先被遍历到。
+    if (node.kind === 'case') continue
+    const entityType = entityTypeOf(node.kind)
+    if (!entityType) continue
+    const layout = CARD_LAYOUT[entityType]
+    const block: Record<string, unknown> = {}
+
+    if (node.kind === 'symptom') {
+      block.observable = node.summary ?? ''
+      block.entry_when = ''
+      block.problem_class = node.problemClass ?? null
+      block.problem_subclass = node.problemSubclass ?? null
+      // 现象 → 假设：**逐边属性必须落在边上**（stale_days 属于「这个现象 × 这个假设」这一对），
+      // 所以它跟着现象卡片走，而不是跟着假设卡片走。
+      block.candidates = graph.edges
+        .filter(edge => edge.kind === 'may_be_caused_by' && edge.source === node.id)
+        .map(edge => ({
+          id: edge.target,
+          ...(edge.staleDays === undefined ? {} : { stale_days: edge.staleDays }),
+        }))
+    } else if (node.kind === 'hypothesis') {
+      block.discriminator = node.discriminator ?? ''
+      block.not_when = node.notWhen ?? ''
+      block.failure_mode = node.failureMode ?? null
+      block.verified_by = graph.edges.filter(edge => edge.kind === 'verified_by' && edge.source === node.id).map(edge => edge.target)
+      block.assets = graph.edges.filter(edge => edge.kind === 'indexed_from' && edge.target === node.id).map(edge => edge.source)
+      block.reuse_count = node.reuseCount ?? 0
+      if (node.stale !== undefined) block.stale = node.stale
+    } else if (node.kind === 'check') {
+      block.cost_minutes = node.costMinutes ?? null
+      block.automation = node.automation ?? null
+      block.verdict_true = node.verdictTrue ?? ''
+      block.verdict_false = node.verdictFalse ?? ''
+      if (node.stale !== undefined) block.stale = node.stale
+    } else if (node.kind === 'failure-mode') {
+      block.code = node.code ?? null
+      block.label = node.title
+      block.boundary = ''
+    }
+
+    cards.push({
+      entityId: node.id,
+      entityType,
+      title: node.title,
+      ...(layout.summaryFrom === 'summary' && node.summary ? { summary: node.summary } : {}),
+      status: DEFAULT_CARD_STATUS,
+      ...(node.owner ? { owner: node.owner } : {}),
+      sourceRefs: [],
+      sections: [],
+      block,
+    })
+  }
+
+  for (const item of cases) {
+    cards.push({
+      entityId: item.id,
+      entityType: 'diagnosis/case',
+      title: item.title,
+      status: DEFAULT_CARD_STATUS,
+      sourceRefs: [],
+      sections: item.sections.map(section => ({ heading: section.heading, body: section.body })),
+      block: {
+        // 案例必须从一个现象进入 —— 这条信息在图上就是 `instance_of` 边，在卡片上是这一个字段。
+        symptom: item.symptomId,
+        path: item.path,
+        duration_minutes: item.durationMinutes,
+        ...(item.misleading ? { misleading: item.misleading } : {}),
+        root_cause: item.rootCause,
+      },
+    })
+  }
+
+  return cards
+}
+
+/* ─────────────────────────────────────────────── 卡片 → 图 ── */
+
+export interface CompiledDiagnosis {
+  graph: AttributionGraphData
+  cases: AttributionCase[]
+  /** 卡片之间的关系（引用完整性等）；节点字段校验仍走 `validateDiagnosis`。 */
+  problems: string[]
+}
+
+/**
+ * 卡片 → 图。
+ *
+ * 只产出「卡片定义得了」的那部分（类型层 + 引用层的资产 + 案例，以及五种卡片边）；
+ * `evidence` / `cause` 与四条执行边由一次排查写入，不在这里合成 —— 否则一次执行的结果
+ * 会被伪装成可复用的知识。
+ */
+export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
+  const nodes: AttributionNode[] = []
+  const edges: AttributionEdge[] = []
+  const cases: AttributionCase[] = []
+  const problems: string[] = []
+  const seen = new Set<string>()
+  for (const card of cards) {
+    if (seen.has(card.entityId)) problems.push(`卡片 ${card.entityId} 被定义了多次 —— 同一份知识只能有一张卡片`)
+    seen.add(card.entityId)
+  }
+
+  /** 资产节点按引用反推：引用层随数据目录同步，卡片里只留 id。 */
+  const assetIds = new Set<string>()
+  const modeIdByCode = new Map<FailureMode, string>()
+
+  for (const card of cards) {
+    if (card.entityType === 'diagnosis/failure-mode' && typeof card.block.code === 'string') {
+      modeIdByCode.set(card.block.code as FailureMode, card.entityId)
+    }
+    if (card.entityType === 'diagnosis/hypothesis' && Array.isArray(card.block.assets)) {
+      for (const id of card.block.assets) assetIds.add(String(id))
+    }
+  }
+
+  for (const card of cards) {
+    const spec = DIAGNOSIS_ENTITIES.find(candidate => candidate.entityType === card.entityType)
+    if (!spec) continue
+    const layout = CARD_LAYOUT[card.entityType]
+    const summary = layout.summaryFrom === 'observable' ? stringOf(card.block.observable) : card.summary
+    const node: AttributionNode = {
+      id: card.entityId,
+      kind: spec.kind,
+      layer: spec.layer,
+      title: card.title,
+      ...(summary ? { summary } : {}),
+      ...(card.owner ? { owner: card.owner } : {}),
+    }
+
+    if (card.entityType === 'diagnosis/symptom') {
+      const problemClass = stringOf(card.block.problem_class)
+      if (problemClass) node.problemClass = problemClass as AttributionNode['problemClass']
+      const subclass = stringOf(card.block.problem_subclass)
+      if (subclass) node.problemSubclass = subclass
+      const candidates = Array.isArray(card.block.candidates) ? card.block.candidates : []
+      candidates.forEach((entry, index) => {
+        const target = stringOf((entry as { id?: unknown })?.id)
+        if (!target) return
+        const staleDays = numberOf((entry as { stale_days?: unknown })?.stale_days)
+        edges.push({
+          id: `e-${card.entityId.toLowerCase()}-${target.toLowerCase()}-${index}`,
+          source: card.entityId,
+          target,
+          kind: 'may_be_caused_by',
+          ...(staleDays === undefined ? {} : { staleDays }),
+        })
+      })
+    } else if (card.entityType === 'diagnosis/hypothesis') {
+      const discriminator = stringOf(card.block.discriminator)
+      if (discriminator) node.discriminator = discriminator
+      const notWhen = stringOf(card.block.not_when)
+      if (notWhen) node.notWhen = notWhen
+      const failureMode = stringOf(card.block.failure_mode)
+      if (failureMode) node.failureMode = failureMode as FailureMode
+      const reuse = numberOf(card.block.reuse_count)
+      if (reuse !== undefined) node.reuseCount = reuse
+      if (typeof card.block.stale === 'boolean') node.stale = card.block.stale
+
+      for (const [index, target] of listOf(card.block.verified_by).entries()) {
+        edges.push({ id: `e-${card.entityId.toLowerCase()}-${String(target).toLowerCase()}-${index}`, source: card.entityId, target: String(target), kind: 'verified_by' })
+      }
+      for (const [index, asset] of listOf(card.block.assets).entries()) {
+        edges.push({ id: `e-${String(asset).toLowerCase()}-${card.entityId.toLowerCase()}-${index}`, source: String(asset), target: card.entityId, kind: 'indexed_from' })
+      }
+      if (failureMode) {
+        const modeNode = modeIdByCode.get(failureMode as FailureMode)
+        if (modeNode) edges.push({ id: `e-${card.entityId.toLowerCase()}-${modeNode.toLowerCase()}`, source: card.entityId, target: modeNode, kind: 'categorized_as' })
+        else problems.push(`${card.entityId} 的 failure_mode=${failureMode} 找不到对应的失败模式卡片 —— categorized_as 边无从建立`)
+      }
+    } else if (card.entityType === 'diagnosis/check') {
+      const cost = numberOf(card.block.cost_minutes)
+      if (cost !== undefined) node.costMinutes = cost
+      const automation = stringOf(card.block.automation)
+      if (automation === 'auto' || automation === 'manual') node.automation = automation
+      const verdictTrue = stringOf(card.block.verdict_true)
+      if (verdictTrue) node.verdictTrue = verdictTrue
+      const verdictFalse = stringOf(card.block.verdict_false)
+      if (verdictFalse) node.verdictFalse = verdictFalse
+      if (typeof card.block.stale === 'boolean') node.stale = card.block.stale
+    } else if (card.entityType === 'diagnosis/failure-mode') {
+      const code = stringOf(card.block.code)
+      if (code) node.code = code as FailureMode
+    } else if (card.entityType === 'diagnosis/case') {
+      const symptom = stringOf(card.block.symptom)
+      if (!symptom) problems.push(`${card.entityId} 没有 symptom —— 案例必须从一个现象进入`)
+      else {
+        edges.push({ id: `e-${card.entityId.toLowerCase()}-${symptom.toLowerCase()}`, source: card.entityId, target: symptom, kind: 'instance_of' })
+        const path = Array.isArray(card.block.path) ? card.block.path as AttributionCase['path'] : []
+        cases.push({
+          id: card.entityId,
+          title: card.title,
+          symptomId: symptom,
+          sections: card.sections.map(section => ({ heading: section.heading, body: section.body })),
+          path,
+          durationMinutes: numberOf(card.block.duration_minutes) ?? 0,
+          ...(card.block.misleading ? { misleading: card.block.misleading as AttributionCase['misleading'] } : {}),
+          rootCause: stringOf(card.block.root_cause) ?? '',
+        })
+      }
+    }
+
+    nodes.push(node)
+  }
+
+  for (const id of assetIds) {
+    if (nodes.some(node => node.id === id)) continue
+    nodes.push({ id, kind: 'asset', layer: 'reference', title: id })
+  }
+
+  // 引用完整性：卡片引用了不存在的卡片时，必须报出来（否则图上会出现悬空边，
+  // 而 `validateDiagnosis` 只在读图之后才看得到）。
+  const ids = new Set(nodes.map(node => node.id))
+  for (const edge of edges) {
+    if (!ids.has(edge.source)) problems.push(`边 ${edge.id} 的起点 ${edge.source} 没有对应卡片`)
+    if (!ids.has(edge.target)) problems.push(`边 ${edge.id} 的终点 ${edge.target} 没有对应卡片`)
+  }
+
+  return { graph: { nodes, edges }, cases, problems }
+}
+
+function stringOf(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined
+}
+
+function numberOf(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+function listOf(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+/**
+ * 路径片段规范化。**必须与 `KnowledgeRuntime` 里那份逐字相同** —— 差一个字符，
+ * 「写进去的卡片」和「编译器去读的路径」就永远对不上，而且失败方式是静默的（读不到 = 图上少几条边）。
+ *
+ * 之所以在这里重复三行而不是把它从 runtime 里 import 出来：`diagnosis/` 是领域子模块，
+ * 反向依赖宿主运行时会把分层倒过来。取而代之的是一条测试，拿同一批 id 比对两边的输出 ——
+ * 规则漂移时测试会失败，而不是靠人记得同时改两处。
+ */
+function slugSegment(value: string): string {
+  const normalized = value.trim().replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^-+|-+$/g, '')
+  return normalized.slice(0, 120) || 'item'
+}
+
+/**
+ * 卡片在磁盘上的相对路径：`02_wiki/<entity_type>/<slug(entity_id)>.md`。
+ *
+ * `entity_type` 里的斜杠是**目录层级**（五类排查卡片因此落在 `02_wiki/diagnosis/` 下，
+ * 与其它 wiki 子树分开），不是要压成横杠 —— 我一开始压了，结果写进去的卡片和编译器去读的
+ * 路径差一层目录，而失败是静默的：读不到，就只是图上少几条边。
+ */
+export function cardPathOf(card: DiagnosisCard): string {
+  return `02_wiki/${card.entityType}/${slugSegment(card.entityId)}.md`
+}

package/src/diagnosis/problem-classes.ts

@@ -0,0 +1,117 @@
+/**
+ * 问题侧的分类表（0021 §4.5）。
+ *
+ * **为什么是一张表，而不是让每个现象随手写一个字符串。** 分类的价值来自「同一批大类
+ * 被反复用」；一旦允许自由书写，两周后就会出现「上游未产出」「上游没产出」「上游未输出」
+ * 三个大类各挂一个现象 —— 那等于没分类，而且图上看不出来。所以大类只能从这张表里取。
+ *
+ * **两级就够了。** 第三层「详细问题」在图上是 symptom 节点本身（带它的资产、时间窗、
+ * 维度），不再是目录里的一层。理由见 §4.5：把实例塞进类型层，正是 §4.1 明令要分开的事。
+ *
+ * **子类同时是召回特征的来源。** §5.1 的 `shape` / `time_pattern` 由前端从告警载荷里
+ * 提取，这里把两者的对应关系**写死在数据里**：`deviation-drop-sharp` 就是「偏低 × 突降」。
+ * 这样「分类」与「召回权重」不可能各说各话 —— 它们读的是同一份表，而不是两份逐渐漂移的清单。
+ */
+export type ProblemClassId = 'missing' | 'deviation' | 'inconsistency' | 'granularity'
+
+/** 差异形态（§5.1 召回权重里的 .30 项）。 */
+export type SymptomShape = 'zero' | 'low' | 'high' | 'mismatch' | 'error' | 'granularity'
+
+/** 时间模式（§5.1 召回权重里的 .20 项）。缺席表示这条子类不携带时间语义。 */
+export type SymptomTimePattern = 'drop-sharp' | 'drop-slow' | 'rise-sharp' | 'rise-slow' | 'periodic' | 'single-day'
+
+export interface ProblemSubclassSpec {
+  /** 全局唯一，形如 `missing-zero`。落盘的是它，不是中文标签。 */
+  id: string
+  label: string
+  shape: SymptomShape
+  timePattern?: SymptomTimePattern
+}
+
+export interface ProblemClassSpec {
+  id: ProblemClassId
+  label: string
+  /** 「第一眼看到什么」—— 大类是按值班同学的判断顺序切的，这句话就是那个判断。 */
+  cue: string
+  subclasses: ProblemSubclassSpec[]
+}
+
+/**
+ * 四个大类，按「看到异常之后的第一眼判断」排序：
+ * 该有的有没有 → 有的话幅度对不对 → 对不对得上 → 粒度对不对。
+ */
+export const PROBLEM_CLASSES: ProblemClassSpec[] = [
+  {
+    id: 'missing',
+    label: '缺失',
+    cue: '该有的没有',
+    subclasses: [
+      { id: 'missing-zero', label: '全量为 0', shape: 'zero' },
+      { id: 'missing-no-partition', label: '分区 / 表未产出', shape: 'zero' },
+      { id: 'missing-job-failed', label: '任务报错未产出', shape: 'error' },
+    ],
+  },
+  {
+    id: 'deviation',
+    label: '偏差',
+    cue: '有，但幅度不对',
+    subclasses: [
+      { id: 'deviation-drop-sharp', label: '突降', shape: 'low', timePattern: 'drop-sharp' },
+      { id: 'deviation-drop-slow', label: '缓降', shape: 'low', timePattern: 'drop-slow' },
+      { id: 'deviation-rise-sharp', label: '突增', shape: 'high', timePattern: 'rise-sharp' },
+      { id: 'deviation-rise-slow', label: '缓升', shape: 'high', timePattern: 'rise-slow' },
+    ],
+  },
+  {
+    id: 'inconsistency',
+    label: '不一致',
+    cue: '有，但对不上',
+    subclasses: [
+      { id: 'inconsistency-vs-source', label: '与源系统对不上', shape: 'mismatch' },
+      { id: 'inconsistency-cross-report', label: '跨报表勾稽不平', shape: 'mismatch' },
+      { id: 'inconsistency-spec-change', label: '口径变更后不一致', shape: 'mismatch', timePattern: 'periodic' },
+      { id: 'inconsistency-tz-boundary', label: '跨天 / 时区边界', shape: 'mismatch', timePattern: 'single-day' },
+    ],
+  },
+  {
+    id: 'granularity',
+    label: '粒度',
+    cue: '有，但切分不对',
+    subclasses: [
+      { id: 'granularity-dim-missing', label: '维度值缺失', shape: 'granularity' },
+      { id: 'granularity-dim-empty', label: '部分维度为空', shape: 'granularity' },
+      { id: 'granularity-dup-count', label: '重复计数', shape: 'granularity', timePattern: 'rise-sharp' },
+      { id: 'granularity-mapping-shift', label: '映射错位', shape: 'granularity' },
+    ],
+  },
+]
+
+export const PROBLEM_CLASS_LABEL: Record<ProblemClassId, string> = Object.fromEntries(
+  PROBLEM_CLASSES.map(item => [item.id, item.label]),
+) as Record<ProblemClassId, string>
+
+/** 子类表项 + 它属于哪个大类 —— 有了它，界面和校验都不用再自己反查归属。 */
+export interface IndexedProblemSubclass extends ProblemSubclassSpec { classId: ProblemClassId }
+
+/** 子类 id → 表项。查一次就够，落盘的 jsonl 里只写 id。 */
+export const PROBLEM_SUBCLASS_INDEX: Record<string, IndexedProblemSubclass> =
+  Object.fromEntries(PROBLEM_CLASSES.flatMap(item =>
+    item.subclasses.map(subclass => [subclass.id, { ...subclass, classId: item.id }]),
+  ))
+
+export function problemClassOf(subclassId: string | undefined): ProblemClassId | undefined {
+  return subclassId === undefined ? undefined : PROBLEM_SUBCLASS_INDEX[subclassId]?.classId
+}
+
+export function problemSubclassOf(subclassId: string | undefined): IndexedProblemSubclass | undefined {
+  return subclassId === undefined ? undefined : PROBLEM_SUBCLASS_INDEX[subclassId]
+}
+
+/** 子类是否真的属于该大类 —— 校验和界面联动都用它，不再各写一遍包含判断。 */
+export function subclassBelongsTo(subclassId: string | undefined, classId: ProblemClassId): boolean {
+  return problemClassOf(subclassId) === classId
+}
+
+export function problemClassIds(): ProblemClassId[] {
+  return PROBLEM_CLASSES.map(item => item.id)
+}