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

package/src/diagnosis/run.ts

@@ -0,0 +1,245 @@
+import type {
+  AttributionEdge, AttributionGraphData, AttributionNode, CasePathStep, DiagnosisRunEvidence, DiagnosisRunRecord,
+} from './types.js'
+import type { DiagnosisCard } from './cards.js'
+
+/**
+ * 一次排查的记录 —— `01_source_truth/agent_diagnosis_case/` 那条 SourceRaw 的编解码。
+ *
+ * ## 为什么它是一条 SourceRaw，而不是一个自造的 jsonl
+ *
+ * 排查产物要能被 `query_source_truth` 读到、被卡片引用、被 SourceRaw 已有的治理覆盖
+ * （分类、版本、检索），就得是一条 SourceRaw。自造一个 jsonl 格式，等于在知识库旁边
+ * 再养一套只读不进链路的数据 —— 这也是 0021 §0.3 撤销 `05_diagnosis/` 的直接原因。
+ *
+ * ## 它与案例卡片的区别
+ *
+ * | | 谁写 | 性质 |
+ * | --- | --- | --- |
+ * | 这条 SourceRaw（`agent_diagnosis_case`） | **Agent**，每次排查结束自动写 | 跑出来的**过程记录** |
+ * | 案例卡片（`diagnosis/case`） | Agent 提议 → **人确认** | 归纳出来的**结论** |
+ *
+ * 同一件事可以有两条记录，它们不是重复：一个回答「当时怎么走的」，一个回答「结论是什么」。
+ * 而案例卡片必须经人确认 —— 它落在类型层收敛的那一侧，见 0021 §6.1。
+ *
+ * ## 三段式
+ *
+ * 与卡片同构：正文小节给人读、` ```json diagnosis-run ` 块给机器读。序和枚举一进散文，
+ * 归并算法就再也读不到它了。
+ */
+
+/** 机器可读块的围栏标记。与卡片的 `json diagnosis` 分开，两种块不会互相误读。 */
+const RUN_FENCE = 'json diagnosis-run'
+
+/** 证据节点的标题取自 `result`；太长就截断，完整值仍在节点上。 */
+const EVIDENCE_TITLE_CHARS = 60
+
+export interface DiagnosisRunFile {
+  record: DiagnosisRunRecord
+  /** 正文小节（人读的部分）。由记录派生，不手写第二份。 */
+  sections: Array<{ heading: string; body: string }>
+}
+
+/**
+ * 一次排查的记录 → SourceRaw 正文。
+ *
+ * 正文按「现象 / 走过的路径 / 结论」三段组织：那是人打开这条来源时想看的三件事，
+ * 而机器要读的一切都在下面的块里。
+ */
+export function renderRunSource(record: DiagnosisRunRecord): string {
+  const path = record.path.length > 0
+    ? record.path.map(step => `- \`${step.label}\` ${step.note}${step.refuted ? '（否定）' : ''}`).join('\n')
+    : '（这次没有记录路径）'
+  const evidence = record.evidence.length > 0
+    ? record.evidence.map(item => `- \`${item.id}\` 跑 \`${item.checkPointId}\`：${item.result} —— ${verdictWord(item.verdict)}${item.why ? `，因为${item.why}` : ''}`).join('\n')
+    : '（这次没有产出证据）'
+  const conclusion = record.rootCause
+    ? [`**根因**：${record.rootCause.text}`, record.rootCause.fixAction ? `**修复**：${record.rootCause.fixAction}` : ''].filter(Boolean).join('\n\n')
+    : '（这次没有确认根因）'
+  const misleading = record.misleading && record.misleading.length > 0
+    ? `\n\n## 误导段\n\n${record.misleading.map(item => `- ${item.label}：浪费 ${item.wastedMinutes} 分钟。${item.why}`).join('\n')}`
+    : ''
+
+  return [
+    '## 现象',
+    '',
+    `入口现象 \`${record.symptomId}\`，开始于 ${record.startedAt}，总耗时 ${record.durationMinutes} 分钟。`,
+    '',
+    '## 走过的路径',
+    '',
+    path,
+    '',
+    '## 每个检查点的产出',
+    '',
+    evidence,
+    '',
+    '## 结论',
+    '',
+    conclusion,
+    misleading,
+    '',
+    '```' + RUN_FENCE,
+    JSON.stringify(record, null, 2),
+    '```',
+    '',
+  ].join('\n')
+}
+
+function verdictWord(verdict: DiagnosisRunEvidence['verdict']): string {
+  if (verdict === 'supports') return '支持'
+  if (verdict === 'refutes') return '否定'
+  return '给不出结论'
+}
+
+/** SourceRaw 正文 → 记录。块坏了或缺 runId 时返回 undefined（调用方如实报问题，不猜）。 */
+export function parseRunSource(content: string): DiagnosisRunRecord | undefined {
+  const match = content.match(new RegExp('```' + RUN_FENCE + '\\s*\\n([\\s\\S]*?)```'))
+  if (!match) return undefined
+  let value: unknown
+  try { value = JSON.parse(match[1]) } catch { return undefined }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = value as Partial<DiagnosisRunRecord>
+  if (typeof record.runId !== 'string' || !record.runId.trim()) return undefined
+  if (typeof record.symptomId !== 'string' || !record.symptomId.trim()) return undefined
+  return {
+    runId: record.runId,
+    symptomId: record.symptomId,
+    startedAt: typeof record.startedAt === 'string' ? record.startedAt : '',
+    durationMinutes: typeof record.durationMinutes === 'number' ? record.durationMinutes : 0,
+    path: Array.isArray(record.path) ? record.path as CasePathStep[] : [],
+    evidence: Array.isArray(record.evidence) ? record.evidence.filter(isEvidence) : [],
+    ...(record.rootCause && typeof record.rootCause === 'object' ? { rootCause: record.rootCause } : {}),
+    ...(Array.isArray(record.misleading) ? { misleading: record.misleading } : {}),
+  }
+}
+
+function isEvidence(value: unknown): value is DiagnosisRunEvidence {
+  if (!value || typeof value !== 'object') return false
+  const item = value as Partial<DiagnosisRunEvidence>
+  return typeof item.id === 'string' && typeof item.checkPointId === 'string'
+    && (item.verdict === 'supports' || item.verdict === 'refutes' || item.verdict === 'inconclusive')
+}
+
+/** 根因节点 id：记录里给了就用它，没给就按假设 id 生成一个稳定的。 */
+export function causeIdOf(record: DiagnosisRunRecord): string | undefined {
+  if (!record.rootCause) return undefined
+  return record.rootCause.id?.trim() || `C-${record.rootCause.hypothesisId}`
+}
+
+/**
+ * 记录 → 实例层节点与四条执行边。
+ *
+ * **它只产出执行产物**：`evidence` / `cause` 节点与 `produces` / `supports` / `refutes` /
+ * `confirmed_as`。类型层（现象、假设、检查点、失败原因）永远来自卡片 —— 把两者混在一起，
+ * 一次执行的结果就会被伪装成可复用的知识（§6.7 的边界表）。
+ */
+export function runToGraph(record: DiagnosisRunRecord): { nodes: AttributionNode[]; edges: AttributionEdge[]; problems: string[] } {
+  const nodes: AttributionNode[] = []
+  const edges: AttributionEdge[] = []
+  const problems: string[] = []
+  const seen = new Set<string>()
+
+  for (const item of record.evidence) {
+    if (seen.has(item.id)) problems.push(`证据 ${item.id} 在这次排查里出现了两次 —— 同一份产出只能有一个 id`)
+    seen.add(item.id)
+    const result = item.result ?? ''
+    nodes.push({
+      id: item.id,
+      kind: 'evidence',
+      layer: 'instance',
+      title: result.length > EVIDENCE_TITLE_CHARS ? `${result.slice(0, EVIDENCE_TITLE_CHARS)}…` : result || item.id,
+      summary: item.why,
+      query: item.query,
+      result,
+      verdict: item.verdict,
+      why: item.why,
+      at: item.at,
+      by: item.by,
+      ...(item.rawRef ? { rawRef: item.rawRef } : {}),
+    })
+    edges.push({ id: `run-${record.runId}-${item.checkPointId}-${item.id}`, source: item.checkPointId, target: item.id, kind: 'produces' })
+    // 给不出结论的证据**不挂支持 / 否定边**：它不是「弱支持」，它是没有结论。
+    // 把它挂成 supports 会让最贵的教训（便宜检查给不出结论）从模型里消失。
+    if (item.verdict !== 'inconclusive' && item.hypothesisId) {
+      edges.push({
+        id: `run-${record.runId}-${item.id}-${item.hypothesisId}`,
+        source: item.id,
+        target: item.hypothesisId,
+        kind: item.verdict === 'supports' ? 'supports' : 'refutes',
+      })
+    }
+  }
+
+  const causeId = causeIdOf(record)
+  if (record.rootCause && causeId) {
+    nodes.push({
+      id: causeId,
+      kind: 'cause',
+      layer: 'instance',
+      title: record.rootCause.text,
+      ...(record.rootCause.fixAction ? { summary: record.rootCause.fixAction } : {}),
+      ...(record.rootCause.confirmedAt ? { at: record.rootCause.confirmedAt } : {}),
+    })
+    edges.push({ id: `run-${record.runId}-${record.rootCause.hypothesisId}-${causeId}`, source: record.rootCause.hypothesisId, target: causeId, kind: 'confirmed_as' })
+  }
+
+  return { nodes, edges, problems }
+}
+
+/**
+ * 引用完整性：一次排查里的每个 id 都必须在图上真实存在。
+ *
+ * 缺了这条，一条写错 id 的诊断日志会在图上留下悬空的执行边 —— 而
+ * `validateDiagnosis` 只在读图之后才看得到，那时已经分不清是卡片错了还是日志错了。
+ *
+ * `knownIds` 要**同时包含卡片那部分与这次排查自己产出的那部分**：路径里的 `E1` / `C1`
+ * 正是这次排查自己写下的，只拿卡片图去比会把它们全判成悬空。
+ */
+export function runReferenceProblems(record: DiagnosisRunRecord, knownIds: ReadonlySet<string>): string[] {
+  const ids = knownIds
+  const problems: string[] = []
+  if (!ids.has(record.symptomId)) problems.push(`诊断日志 ${record.runId} 的入口现象 ${record.symptomId} 不存在`)
+  for (const item of record.evidence) {
+    if (!ids.has(item.checkPointId)) problems.push(`诊断日志 ${record.runId} 的证据 ${item.id} 指向不存在的检查点 ${item.checkPointId}`)
+    if (item.hypothesisId && !ids.has(item.hypothesisId)) problems.push(`诊断日志 ${record.runId} 的证据 ${item.id} 指向不存在的假设 ${item.hypothesisId}`)
+  }
+  if (record.rootCause && !ids.has(record.rootCause.hypothesisId)) {
+    problems.push(`诊断日志 ${record.runId} 的根因指向不存在的假设 ${record.rootCause.hypothesisId}`)
+  }
+  for (const step of record.path) {
+    if (!ids.has(step.nodeId)) problems.push(`诊断日志 ${record.runId} 的路径节点 ${step.nodeId} 不存在`)
+  }
+  return problems
+}
+
+/**
+ * 把一次排查归纳成一张**案例卡片**（还只是提议，要人确认才生效）。
+ *
+ * 归纳这一步是「过程记录 → 可复用知识」的那一跳，也是唯一需要人看的一跳：
+ * 路径里哪几步其实是误导、根因一句话怎么写，都是判断题。
+ */
+export function caseProposalOf(record: DiagnosisRunRecord, symptomTitle: string): DiagnosisCard {
+  const rootCause = record.rootCause?.text ?? '（这次没有确认根因）'
+  const firstMisleading = record.misleading?.[0]
+  return {
+    entityId: `CASE-${record.runId}`,
+    entityType: 'diagnosis/case',
+    title: symptomTitle,
+    status: 'unreviewed',
+    sourceRefs: [],
+    sections: [
+      { heading: '现象', body: `入口现象 \`${record.symptomId}\`（${symptomTitle}），开始于 ${record.startedAt}。` },
+      { heading: '影响面', body: '（待补：这次影响到了谁、范围多大）' },
+      { heading: '排查过程', body: record.path.map(step => `- \`${step.label}\` ${step.note}${step.refuted ? '（否定）' : ''}`).join('\n') || '（没有记录路径）' },
+      { heading: '根因', body: rootCause },
+      { heading: '修复与防复发', body: record.rootCause?.fixAction ?? '（待补：修复动作与防复发措施）' },
+    ],
+    block: {
+      symptom: record.symptomId,
+      path: record.path,
+      duration_minutes: record.durationMinutes,
+      ...(firstMisleading ? { misleading: firstMisleading } : {}),
+      root_cause: rootCause,
+    },
+  }
+}

package/src/diagnosis/schema.ts

@@ -16,13 +16,16 @@ import { PROBLEM_CLASS_LABEL, problemClassIds, problemSubclassOf } from './probl
  *    序和枚举一旦写进散文，归并算法就再也读不到它们了。
  * 3. **校验必须分三层报错**：格式 / 引用完整性 / 语义。混成同一个「校验失败」，
  *    人就学不会怎么写卡片。
+ *
+ * 两处更名（0021 v1.1 / v1.2）：`check` → **`check_point`**（检查点）、
+ * `failure-mode` → **`failure_reason`**（失败原因）。kind 用下划线，卡片类型用连字符。
  */
 
 export type DiagnosisEntityType =
   | 'diagnosis/symptom'
   | 'diagnosis/hypothesis'
-  | 'diagnosis/check'
-  | 'diagnosis/failure-mode'
+  | 'diagnosis/check-point'
+  | 'diagnosis/failure-reason'
   | 'diagnosis/case'
 
 export interface DiagnosisFieldSpec {
@@ -53,11 +56,29 @@ export interface DiagnosisEntitySpec {
 export const DIAGNOSIS_ENTITY_TYPES: DiagnosisEntityType[] = [
   'diagnosis/symptom',
   'diagnosis/hypothesis',
-  'diagnosis/check',
-  'diagnosis/failure-mode',
+  'diagnosis/check-point',
+  'diagnosis/failure-reason',
   'diagnosis/case',
 ]
 
+/**
+ * 改名之前的两个 `entity_type`，以及它们对应的新名字。
+ *
+ * 留着这张表是为了**存量卡片不静默消失**：磁盘上还叫 `diagnosis/check` 的卡片，
+ * 如果读的时候直接判为「未知类型」，后果是这张卡片既不进 wikiNotes、也不上图，
+ * 而且没有任何报错。所以读取端按别名认，写入端做一次性迁移（见
+ * `runtime.migrateLegacyDiagnosisCards`）。
+ */
+export const LEGACY_ENTITY_TYPES: Record<string, DiagnosisEntityType> = {
+  'diagnosis/check': 'diagnosis/check-point',
+  'diagnosis/failure-mode': 'diagnosis/failure-reason',
+}
+
+/** 卡片里那个旧字段名 → 新字段名。`failure_mode` 改叫 `failure_reason`。 */
+export const LEGACY_BLOCK_FIELDS: Record<string, string> = {
+  failure_mode: 'failure_reason',
+}
+
 /** 不是 wiki 卡片、但仍属于同一张图的节点类型。校验不按卡片规则要求它们。 */
 export const NON_CARD_KINDS: AttributionNodeKind[] = ['asset', 'evidence', 'cause', 'unknown']
 
@@ -76,11 +97,11 @@ export const DIAGNOSIS_ENTITIES: DiagnosisEntitySpec[] = [
     entityType: 'diagnosis/symptom',
     kind: 'symptom',
     layer: 'type',
-    label: '现象类型',
+    label: '现象',
     fields: [
       { name: 'observable', note: '可观测口径：指标 + 维度 + 时间窗' },
       { name: 'entry_when', note: '什么条件下适用' },
-      { name: 'problem_class', note: '问题大类：mandatory，取值只能来自 §4.5 的四个大类' },
+      { name: 'problem_class', note: '问题大类：必填，取值只能来自 §4.5 的四个大类' },
       { name: 'problem_subclass', note: '问题子类：必须属于所选大类；它同时决定 §5.1 的 shape / time_pattern' },
     ],
     sections: ['观测口径', '典型信号', '不适用的情况', '关联假设'],
@@ -93,34 +114,35 @@ export const DIAGNOSIS_ENTITIES: DiagnosisEntitySpec[] = [
     fields: [
       { name: 'discriminator', note: '**一句可判真假的话** —— 它同时是查重的比对对象' },
       { name: 'not_when', note: '**反例边界**：什么情况下这个假设不成立。refutes 边在文档层的表达' },
-      { name: 'failure_mode', note: '切面：upstream-missing | spec-change | data-processing | consumption | permission' },
-      { name: 'verified_by', note: '引用的检查 id 列表' },
-      { name: 'assets', note: '关联资产（表 / 指标 / 任务）' },
+      { name: 'failure_reason', note: '切面：upstream-missing | spec-change | data-processing | consumption | permission' },
+      { name: 'verified_by', note: '引用的检查点 id 列表' },
+      { name: 'assets', note: '这条假设**落在**哪些对象上（反向索引入口）。可写成 `"dwd_ord_di"`，或 `{ id, type }` 顺带声明种类' },
       { name: 'stats', system: true, note: 'prior / last_hit_at / refutes_count / case_count' },
     ],
     sections: ['判据', '反例边界', '典型信号', '关联检查', '案例索引'],
   },
   {
-    entityType: 'diagnosis/check',
-    kind: 'check',
+    entityType: 'diagnosis/check-point',
+    kind: 'check_point',
     layer: 'type',
-    label: '检查',
+    label: '检查点',
     fields: [
       { name: 'cost_minutes', note: '耗时（分钟），优先分的分母' },
       { name: 'automation', note: 'auto | manual' },
       { name: 'owner', note: '执行人或角色' },
       { name: 'verdict_true', note: '**看到什么算真**' },
       { name: 'verdict_false', note: '**看到什么算假** —— 只写「算真」就无法否定假设' },
-      { name: 'runbook', note: '怎么跑：SQL / 工具 / 找谁' },
+      { name: 'runbook', note: '怎么跑：SQL / 工具 / 找谁。**可复用的查询模板**写这里' },
       { name: 'side_effect', note: '是否有副作用（只读 / 会写）' },
+      { name: 'assets', note: '**查询依据**：这条检查要去查哪些对象（表 / 指标 / 任务 / 链路）。可写成 `"dwd_ord_di"`，或 `{ id, type }` 顺带声明种类' },
     ],
     sections: ['怎么跑', '判定阈值', '有结论与无结论的区分'],
   },
   {
-    entityType: 'diagnosis/failure-mode',
-    kind: 'failure-mode',
+    entityType: 'diagnosis/failure-reason',
+    kind: 'failure_reason',
     layer: 'type',
-    label: '失败模式（切面）',
+    label: '失败原因',
     fields: [
       { name: 'code', note: '稳定编码' },
       { name: 'label', note: '界面词' },
@@ -135,7 +157,7 @@ export const DIAGNOSIS_ENTITIES: DiagnosisEntitySpec[] = [
     label: '案例',
     fields: [
       { name: 'symptom', note: '入口现象 id' },
-      { name: 'path', note: '**有序**节点序列：现象 → 假设 → 检查 → 证据 → 根因' },
+      { name: 'path', note: '**有序**节点序列：现象 → 假设 → 检查点 → 证据 → 根因' },
       { name: 'duration_minutes', note: '总耗时' },
       { name: 'misleading_edges', note: '误导边：节点 + 浪费的分钟数 + 为什么' },
       { name: 'root_cause', note: '根因一句话' },
@@ -146,7 +168,7 @@ export const DIAGNOSIS_ENTITIES: DiagnosisEntitySpec[] = [
   },
 ]
 
-/** 语义校验用的判据：check 的标题必须**可执行**。 */
+/** 语义校验用的判据：检查点的标题必须**可执行**。 */
 const VAGUE_CHECK_TITLES = /^(检查|看看|排查|确认)?\s*(一下)?\s*(数据质量|是不是|有没有问题|上游|下游)/
 
 export type DiagnosisIssueLevel = 'format' | 'reference' | 'semantic'
@@ -171,6 +193,9 @@ export function specOf(kind: AttributionNodeKind): DiagnosisEntitySpec | undefin
  *
  * 分开报错不是洁癖：**格式错说明卡片没填完，引用错说明图断了，语义错说明这条知识
  * 本身没用**。三者对应的动作完全不同（补字段 / 修边 / 重写），混在一起就只能靠猜。
+ *
+ * 它同时是**提议阶段与确认阶段的前置**（0021 §6.5）：两道都跑，是因为这两次修改
+ * 来自不同的人。
  */
 export function validateDiagnosis(graph: AttributionGraphData): DiagnosisIssue[] {
   const issues: DiagnosisIssue[] = []
@@ -185,7 +210,7 @@ export function validateDiagnosis(graph: AttributionGraphData): DiagnosisIssue[]
     if (node.kind === 'hypothesis') {
       if (!node.discriminator?.trim()) issues.push(fieldIssue(node, 'discriminator', '假设必须有一句可判真假的判据'))
       if (!node.notWhen?.trim()) issues.push(fieldIssue(node, 'notWhen', '假设必须写明反例边界 —— 否则查重会把相似情形并成一条'))
-      if (!node.failureMode) issues.push(fieldIssue(node, 'failureMode', '假设必须归属一个失败模式切面'))
+      if (!node.failureReason) issues.push(fieldIssue(node, 'failureReason', '假设必须归属一个失败原因切面'))
     }
     if (node.kind === 'symptom') {
       // 问题侧的分类是**必填**：留空的后果不是「少个字段」，而是这个现象在按问题筛选时
@@ -207,12 +232,22 @@ export function validateDiagnosis(graph: AttributionGraphData): DiagnosisIssue[]
       // 分类字段只属于现象。假设上挂问题大类，会把「问题」和「原因」两根轴搅在一起。
       issues.push(fieldIssue(node, 'problemClass', '问题分类只能写在现象（symptom）上，不能挂在原因侧'))
     }
-    if (node.kind === 'check') {
+    if (node.kind === 'check_point') {
       for (const [field, value] of [['costMinutes', node.costMinutes], ['automation', node.automation], ['owner', node.owner], ['verdictTrue', node.verdictTrue], ['verdictFalse', node.verdictFalse]] as const) {
-        if (value === undefined || value === '') issues.push(fieldIssue(node, field, `检查缺少 ${field} —— 缺了它这一步就无法被自动化或复核`))
+        if (value === undefined || value === '') issues.push(fieldIssue(node, field, `检查点缺少 ${field} —— 缺了它这一步就无法被自动化或复核`))
       }
+      // `assets[]` 是 v1.3 的必填：缺了它，这条检查**不知道去哪查**，
+      // 也就没法生成查询、判断影响面。
+      if (!node.assets || node.assets.length === 0) {
+        issues.push(fieldIssue(node, 'assets', '检查点必须写明查询依据（assets[]）—— 缺了它这条检查不知道去哪查'))
+      }
+    }
+    if (node.kind === 'evidence') {
+      if (!node.query?.trim()) issues.push(fieldIssue(node, 'query', '证据必须记下这次实际跑的查询'))
+      if (!node.verdict) issues.push(fieldIssue(node, 'verdict', '证据必须给出结论：supports / refutes / inconclusive'))
+      if (!node.why?.trim()) issues.push(fieldIssue(node, 'why', '证据必须说明「为什么这个结果算数或不算数」—— 采信与剔除都得能说理由'))
     }
-    // `case` 节点只是图上的桩：案例的正文与路径住在 `cases.json` 里，由
+    // `case` 节点只是图上的桩：案例的正文与路径住在案例卡片里，由
     // DiagnosisSnapshot.cases 校验，不在节点上重复要求。
   }
 
@@ -225,18 +260,18 @@ export function validateDiagnosis(graph: AttributionGraphData): DiagnosisIssue[]
     if (node.kind !== 'hypothesis') continue
     const hasCheck = graph.edges.some(edge => edge.kind === 'verified_by' && edge.source === node.id)
     // 空区不是错，是**待办**：它是一条信息（这张图哪里还没建完），所以只提示不报错。
-    if (!hasCheck) issues.push({ level: 'semantic', entityId: node.id, message: '空区：有假设但没有任何检查，拿不出成本，因此进不了排序' })
+    if (!hasCheck) issues.push({ level: 'semantic', entityId: node.id, message: '空区：有假设但没有任何检查点，拿不出成本，因此进不了排序' })
   }
 
   // ── 第三层：语义 ──────────────────────────────────────────────────────────
   for (const node of graph.nodes) {
-    if (node.kind !== 'check') continue
+    if (node.kind !== 'check_point') continue
     if (VAGUE_CHECK_TITLES.test(node.title.trim())) {
       issues.push({
         level: 'semantic',
         entityId: node.id,
         field: 'title',
-        message: `检查标题不可执行：「${node.title}」。必须能回答「谁、用什么、多久、看到什么算真、看到什么算假」`,
+        message: `检查点标题不可执行：「${node.title}」。必须能回答「谁、用什么、多久、看到什么算真、看到什么算假」`,
       })
     }
   }
@@ -244,7 +279,13 @@ export function validateDiagnosis(graph: AttributionGraphData): DiagnosisIssue[]
   return issues
 }
 
-/** 空的模板卡：新人写卡片时看的是它，不是 schema。 */
+/**
+ * 空的模板卡：新人写卡片时看的是它，不是 schema。
+ *
+ * 模板卡**由类型定义派生、不再落成磁盘文件**（0021 §6.6）：模板是类型定义的一种
+ * 呈现，定义搬进设置，模板跟着走 —— 否则会出现「设置里改了、磁盘上那份没改」的
+ * 第二真源。
+ */
 export function templateCard(spec: DiagnosisEntitySpec): string {
   const front = [
     `entity_type: ${spec.entityType}`,

package/src/diagnosis/seed-source.ts

@@ -12,14 +12,22 @@
  * 手册与复盘是**人写的散文**（就是下面这些字面量），卡片是从它们编译出来的结构化提取。
  * 两者内容会有重叠 —— 那是正常的：卡片是散文的投影，不是它的替代品。
  */
-import { SEED_CASES } from './seed.js'
+import { SEED_CASES, SEED_RUNS } from './seed.js'
+import { renderRunSource } from './run.js'
 
 export interface SeedSource {
   /** 稳定 id，用作 `external_id`，迁移与重跑都靠它幂等。 */
   id: string
   title: string
-  /** 来源分类。排查手册与复盘都属于既有的 `question`（「问题排查文档」）。 */
-  sourceType: 'question'
+  /**
+   * 来源分类。**两种**：
+   * - `question`：人写的手册与复盘（卡片 `source_refs` 指向这里）；
+   * - `agent_diagnosis_case`：Agent 跑出来的三次排查记录（v1.1 新增的来源分类）。
+   *
+   * 边界裁决是「谁写的、是不是已经归纳过」：同一件事可以有两条来源，
+   * 一个回答「结论是什么」，一个回答「当时怎么走的」。
+   */
+  sourceType: 'question' | 'agent_diagnosis_case'
   content: string
 }
 
@@ -99,9 +107,26 @@ export function seedCaseSources(): SeedSource[] {
   }))
 }
 
+/**
+ * 三次排查的**过程记录**。
+ *
+ * 它们不由散文手写，而是从 `SEED_RUNS` **渲染**出来（`renderRunSource`）——
+ * 这正是运行时那条路径：一次排查结束 → 一条 `agent_diagnosis_case` 的 SourceRaw。
+ * 示例走同一条路，所以它同时也是这条路的回归夹具。
+ */
+export function seedRunSources(): SeedSource[] {
+  return SEED_RUNS.map(record => ({
+    id: record.runId,
+    title: `AI 诊断日志 · ${record.symptomId} · ${record.runId}`,
+    sourceType: 'agent_diagnosis_case' as const,
+    content: renderRunSource(record),
+  }))
+}
+
 export function seedSources(): SeedSource[] {
   return [
     { id: 'handbook', title: '日报指标异常排查手册（内部版）', sourceType: 'question', content: SEED_HANDBOOK },
     ...seedCaseSources(),
+    ...seedRunSources(),
   ]
 }