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

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

@@ -2,7 +2,7 @@
  * Seed 的**原始材料**：一份排查手册 + 三篇复盘。
  *
  * 这一层存在的理由，正是 v0.7 修掉的那处架构缺口：排查思路如果只以 TypeScript 字面量存在，
- * 它就**不是 wiki 内容** —— 不会进 `01_source_truth`、不会被编译、永远召不回来。
+ * 它就**不是 wiki 内容** —— 不会进 `01_source_raw`、不会被编译、永远召不回来。
  * 所以 seed 也走完整条动线：
  *
  * ```
@@ -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(),
   ]
 }