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

package/src/diagnosis/types.ts

@@ -1,7 +1,7 @@
 /**
  * 归因图谱的**领域模型**：节点 / 边 / 图 的形状与枚举。
  *
- * 为什么它不在 client 里：宿主也要读写同一套结构（`05_diagnosis/*.jsonl`、
+ * 为什么它不在 client 里：宿主也要读写同一套结构（`01_source_truth/agent_diagnosis_case/`、
  * `/diagnosis/graph`）。视图是消费者，不是所有者 —— 模型放在领域层，客户端和宿主
  * 各自 import，谁都不能私自改形状。
  *
@@ -14,26 +14,55 @@ import type { ProblemClassId } from './problem-classes.js'
 /** 类型层 / 引用层 / 实例层。轴不同，不能合成一种节点。 */
 export type NodeLayer = 'type' | 'reference' | 'instance'
 
-/** 九类归因节点。与 wiki 卡片的 `entity_type` 一一对应。 */
+/**
+ * 九类归因节点。与 wiki 卡片的 `entity_type` 一一对应（`asset` 与三类执行产物除外）。
+ *
+ * **两个名字用的是下划线**（`check_point` / `failure_reason`），卡片类型用连字符
+ * （`diagnosis/check-point` / `diagnosis/failure-reason`）：kind 是代码里的标识符，
+ * 卡片类型是 `entity_type`，后者沿用 `diagnosis/*` 已有的连字符习惯。
+ */
 export type AttributionNodeKind =
   | 'symptom'
   | 'hypothesis'
-  | 'check'
-  | 'failure-mode'
+  | 'check_point'
+  | 'failure_reason'
   | 'asset'
   | 'case'
   | 'evidence'
   | 'cause'
   | 'unknown'
 
-/** 失败模式切面。分类只影响排序与分组，不影响「能查到什么」。 */
-export type FailureMode = 'upstream-missing' | 'spec-change' | 'data-processing' | 'consumption' | 'permission'
+/**
+ * 失败原因切面 —— **原因出在链路的哪一环**（五个取值之一）。
+ *
+ * 原名叫 `FailureMode`（失败模式）。改名的理由：「failure mode」是可靠性工程（FMEA）
+ * 里的术语，指**故障长什么样**（「间歇性失效」「启动即失败」）；而这一类装的是
+ * **原因出在链路的哪一环**。沿用旧名会让人往里塞「数据质量差」这种既不是形态、
+ * 也不是环节的东西 —— 而那正是 schema 校验要拦的东西。
+ */
+export type FailureReason = 'upstream-missing' | 'spec-change' | 'data-processing' | 'consumption' | 'permission'
+
+/** 一次查询的结论。`inconclusive` 是**一等取值**：便宜检查给不出结论，这本身就是知识。 */
+export type EvidenceVerdict = 'supports' | 'refutes' | 'inconclusive'
+
+/**
+ * 资产的种类（表 / 指标 / 任务 / 链路）。
+ *
+ * 它由**卡片声明**，不由代码从 id 猜：`assets[]` 的每一项可以写成 `"dwd_ord_di"`，
+ * 也可以写成 `{ id: "dwd_ord_di", type: "table" }`。猜前缀（`dwd_` 是表、`metric_` 是指标）
+ * 看着方便，但它会在有人给表起名 `t_xxx` 的那天静默失效 —— 而失效的表现是
+ * 「查询依据那一段的排序莫名其妙地变了」，没人会想到去查一个前缀规则。
+ *
+ * 声明了类型时，「查询依据」那一段按它分组（§7.7 ④）；没声明就退回 id 序，
+ * 两种都稳定、可复现。
+ */
+export type AssetType = 'table' | 'metric' | 'job' | 'linkage'
 
 /**
  * 问题侧的分类字段（只出现在 symptom 节点上）。
  *
- * 与 `FailureMode` 是**两根不同的轴，不能合并**：这一对说的是「问题是什么样」，
- * `failureMode` 说的是「原因出在哪一环」。前者挂在现象上、值班同学看到异常就能填；
+ * 与 `FailureReason` 是**两根不同的轴，不能合并**：这一对说的是「问题是什么样」，
+ * `failureReason` 说的是「原因出在哪一环」。前者挂在现象上、值班同学看到异常就能填；
  * 后者挂在假设上、要等排查有结论。合成一根轴，就会出现「异常波动归因属于哪个问题大类」
  * 这种没有答案的问题（0021 §4.5 与本文件顶部的分层原则）。
  */
@@ -44,11 +73,12 @@ export interface ProblemTaxonomy {
   problemSubclass?: string
 }
 
-/** 九种边。层内定义可能性与顺序，跨层定义证据与复用。 */
+/** 十种边。层内定义可能性与顺序，跨层定义证据与复用。 */
 export type AttributionEdgeKind =
   | 'may_be_caused_by'
   | 'verified_by'
   | 'categorized_as'
+  | 'queries'
   | 'produces'
   | 'supports'
   | 'refutes'
@@ -63,7 +93,7 @@ export interface AttributionNode extends ProblemTaxonomy {
   title: string
   /** 一句话判据。图谱视图在 tooltip 与侧栏里用它，而不是靠标题猜。 */
   summary?: string
-  failureMode?: FailureMode
+  failureReason?: FailureReason
   /** 被复用次数：节点大小由它决定，这是「图有没有在被用」最直接的读数。 */
   reuseCount?: number
   /** 最低成本检查的耗时（分钟），单位与 0021 §4.4 一致。 */
@@ -84,19 +114,50 @@ export interface AttributionNode extends ProblemTaxonomy {
    * 没有它，查重会把所有相似情形并进一条假设，图会慢慢失去分辨力。
    */
   notWhen?: string
-  /** 检查的判定阈值：看到什么算真 / 算假。缺了它，这一步就无法被自动化或复核。 */
+  /** 检查点的判定阈值：看到什么算真 / 算假。缺了它，这一步就无法被自动化或复核。 */
   verdictTrue?: string
   verdictFalse?: string
   /**
-   * 失败模式节点的稳定编码（= `FailureMode`）。只出现在 `failure-mode` 节点上。
+   * 检查点的**查询依据**：这条检查要去查哪些对象（表 / 指标 / 任务 / 链路）。
    *
-   * 假设卡片里写的是 `failure_mode: data-processing`（编码），而边要连到**节点**，
+   * 与假设上的 `assets` 是两件事，落在两种边上：这里是 `queries`（这条检查要去查什么），
+   * 那里是 `indexed_from`（这条假设落在哪个对象上）。
+   */
+  assets?: string[]
+  /**
+   * 资产的种类。**只出现在 `asset` 节点上**，且只有卡片声明过才有值。
+   *
+   * 它读起来像是「节点的一个属性」，其实来源是**别的卡片**：资产节点由引用反推，
+   * 而种类写在引用它的那对 `assets[]` 里（`{ id, type }` 形态）。
+   */
+  assetType?: AssetType
+  /**
+   * 失败原因节点的稳定编码（= `FailureReason`）。只出现在 `failure_reason` 节点上。
+   *
+   * 假设卡片里写的是 `failure_reason: data-processing`（编码），而边要连到**节点**，
    * 所以需要一条「编码 → 节点 id」的可逆映射。少了它，`categorized_as` 边就只能靠
-   * 「F1 恰好是第一个失败模式」这种位置约定去猜 —— 那是会在某次重排后静默出错的东西。
+   * 「F1 恰好是第一个失败原因」这种位置约定去猜 —— 那是会在某次重排后静默出错的东西。
    */
-  code?: FailureMode
+  code?: FailureReason
   /** 边或节点是否已被判定失效（原因已修好 / 90 天未走）。 */
   stale?: boolean
+
+  /* ── 以下是**实例层执行产物**（evidence）专属字段：一次查询的输入与输出 ── */
+
+  /** 这次实际跑的查询语句。可复用的查询模板归 `check_point.runbook`，不是这里。 */
+  query?: string
+  /** 看到什么。 */
+  result?: string
+  /** 这个结果算不算数：支持 / 否定 / 给不出结论。 */
+  verdict?: EvidenceVerdict
+  /** **为什么**算数或不算数。评估要有对称性：采信与剔除都得能说理由。 */
+  why?: string
+  /** 什么时候跑的。 */
+  at?: string
+  /** 谁跑的。 */
+  by?: string
+  /** 原始输出指向哪里（日志 / 结果集 / 附件）。 */
+  rawRef?: string
 }
 
 export interface AttributionEdge {
@@ -125,6 +186,45 @@ export interface AttributionGraphData {
   stats?: Partial<AttributionStats>
 }
 
+/**
+ * 案例 = **一篇 wiki 定义 + 一条有序排查路径**。
+ *
+ * 它住在领域层而不是示例里（原来是 `seed.ts`）：案例是编译产物的一种
+ * （`cardsToGraph()` 从卡片把它算出来，`/diagnosis/graph` 把它发给界面），
+ * 而示例只是**一份**案例的取值来源。视图要渲染「服务端给的案例」，
+ * 那它 import 的形状就不该从示例模块里拿。
+ *
+ * 两段各有明确消费者，不能合并：
+ * - `sections` 是给人读、给向量召回的散文（可 diff、可评审、可追溯）；
+ * - `path` 是给图和剪枝用的结构（有序、可判真假、带被否定的分支）。
+ *
+ * 序和枚举一旦写进散文，归并算法就再也读不到它们了 —— 所以路径单独成段。
+ */
+export interface CaseSection {
+  heading: string
+  body: string
+}
+
+export interface CasePathStep {
+  nodeId: string
+  label: string
+  note: string
+  /** 这一步的结论是「否定」：它把某个假设置于死地，而不是坐实。 */
+  refuted?: boolean
+}
+
+export interface AttributionCase {
+  id: string
+  title: string
+  symptomId: string
+  sections: CaseSection[]
+  path: CasePathStep[]
+  durationMinutes: number
+  /** 误导段：最贵的那条知识。没有它，下次还会有人在同一个假设上烧掉四十分钟。 */
+  misleading?: { nodeId: string; label: string; wastedMinutes: number; why: string }
+  rootCause: string
+}
+
 export interface AttributionStats {
   typeNodes: number
   referenceNodes: number
@@ -134,7 +234,7 @@ export interface AttributionStats {
    * 现象（问题侧）节点数。
    *
    * 单独数出来，是因为它和图例的关系最容易被看错：图例里的五种颜色**全是原因侧**
-   * （失败模式），而问题侧有几个节点、有没有分类，必须能一眼读到 —— 否则「图上那些
+   * （失败原因），而问题侧有几个节点、有没有分类，必须能一眼读到 —— 否则「图上那些
    * 颜色在说问题还是说原因」就只能靠猜。
    */
   symptoms: number
@@ -150,3 +250,68 @@ export interface AttributionStats {
   /** 僵尸边：90 天未被走过的 `may_be_caused_by`。 */
   zombies: number
 }
+
+/* ────────────────────────────────────────────────────────────────────────────
+ * 一次排查的记录（`01_source_truth/agent_diagnosis_case/`）
+ *
+ * 它**不是卡片**：读图时才被解析成 `evidence` / `cause` 节点与
+ * `produces` / `supports` / `refutes` / `confirmed_as` 四条执行边。
+ *
+ * 为什么要有它，而不是继续用 jsonl：排查产物要能被 `query_source_truth` 读到、
+ * 被卡片引用、被 SourceRaw 已有的治理覆盖（分类、版本、检索），就得是一条 SourceRaw。
+ * 自造一个 jsonl 格式，等于在知识库旁边再养一套只读不进链路的数据。
+ * ──────────────────────────────────────────────────────────────────────────── */
+
+/** 一次查询的产出。**含被否定与给不出结论的那些** —— 它们才是最贵的知识。 */
+export interface DiagnosisRunEvidence {
+  /** 证据 id，如 `E1`。同一次排查内唯一。 */
+  id: string
+  /** 跑的是哪个检查点。`produces` 边的起点。 */
+  checkPointId: string
+  /** 这次实际跑的查询语句（不是可复用的模板）。 */
+  query: string
+  /** 看到什么。 */
+  result: string
+  /** 这个结果算不算数。 */
+  verdict: EvidenceVerdict
+  /** 为什么算数 / 不算数。`supports` 与 `refutes` 两条边共用它。 */
+  why: string
+  /** 支持或否定的假设 id。`inconclusive` 时可以缺省。 */
+  hypothesisId?: string
+  at: string
+  by: string
+  rawRef?: string
+}
+
+/** 确认下来的根因。 */
+export interface DiagnosisRunCause {
+  /** 被确认的假设。`confirmed_as` 边的起点。 */
+  hypothesisId: string
+  /** 根因节点 id，如 `C1`。缺省时按 `C-<hypothesisId>` 生成。 */
+  id?: string
+  /** 根因一句话。 */
+  text: string
+  fixAction?: string
+  confirmedAt: string
+}
+
+/**
+ * 一次排查的完整记录。落到 SourceRaw 正文里的 ```json diagnosis-run 块。
+ *
+ * 它与案例卡片的区别是**谁写的、有没有被归纳过**：这里是 Agent 跑完一圈留下的
+ * 原始记录，案例卡片是**之后**归纳出来的知识（而且必须经人确认才生效）。
+ */
+export interface DiagnosisRunRecord {
+  /** 本次排查的 runId。同时用作 SourceRaw 的 `externalId`，重跑不产生第二条记录。 */
+  runId: string
+  /** 入口现象 id。 */
+  symptomId: string
+  startedAt: string
+  durationMinutes: number
+  /** 走过的路径（有序）。含被否定的分支 —— 那是这次排查最值钱的部分。 */
+  path: CasePathStep[]
+  evidence: DiagnosisRunEvidence[]
+  rootCause?: DiagnosisRunCause
+  /** 误导段：哪个假设把这次排查带偏了、浪费了多少分钟、为什么。 */
+  misleading?: Array<{ nodeId: string; label: string; wastedMinutes: number; why: string }>
+}

package/src/document-page.ts

@@ -0,0 +1,51 @@
+/**
+ * 独立整页（`/knowledge/documents/:docId/view`）的**分页规则**。
+ *
+ * 它单独一个模块而不是写在 `index.ts` 的路由里，理由是这个函数值得被直接测：
+ * 「一页一段、段与段首尾相接、一个字都不丢」是那条路由唯一的硬约束，而它藏在
+ * HTTP 处理里就只能靠起服务来验。纯函数搬出来之后 `tests/document-page.test.mjs`
+ * 可以直接对着它断言（含「所有页拼起来逐字等于原文」这条）。
+ *
+ * @module dsh-data-domain-knowledge/document-page
+ */
+
+/**
+ * 一次取多少字符、一次最多能取多少。
+ *
+ * 「打开要等半天」的成因就是把整份正文一次发过来。这两个数就是那条规矩的落点：
+ * 任何一次响应都只是**一段**，要看全文就一页一页地要。上限也刻意压着 ——
+ * 20 万字符已经能把一份普通文档读完，再大就回到了「一次发全文」。
+ */
+export const DOC_PAGE_CHARS = 20000
+export const DOC_PAGE_CHARS_MAX = 200000
+
+export interface DocumentContentPage {
+  text: string
+  offset: number
+  nextOffset: number
+  totalChars: number
+  eof: boolean
+}
+
+/**
+ * 取正文的一页，切点**对齐到空行**。
+ *
+ * 为什么非要对齐：Markdown 的块（表格、代码块、列表）从中间断开会被渲染成两个残缺的块，
+ * 而整页是**每页各自渲染**的（见 `doc-page.tsx` 第 2 条）。一段表格被切成两半，读者看到的
+ * 就是两张破表。空行是块边界，所以往回找最近的空行。
+ *
+ * 只在后半段找：从前半段找会把页面缩得太短（一次只发几百字符，翻页翻到手软）。
+ * 找不到（比如一个超长代码块）就硬切 —— 页大小上限比块的完整性更要紧，那是这个页面
+ * 唯一不能失控的量。
+ */
+export function documentContentPage(body: string, offset: number, limit: number): DocumentContentPage {
+  const totalChars = body.length
+  const start = Math.min(Math.max(offset, 0), totalChars)
+  let end = Math.min(start + limit, totalChars)
+  if (end < totalChars) {
+    const floor = start + Math.floor(limit / 2)
+    const boundary = body.slice(floor, end).lastIndexOf('\n\n')
+    if (boundary >= 0) end = floor + boundary + 2
+  }
+  return { text: body.slice(start, end), offset: start, nextOffset: end, totalChars, eof: end >= totalChars }
+}

package/src/fs-atomic.ts

@@ -0,0 +1,42 @@
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/**
+ * 原子写：先写同目录的临时文件，再 `rename` 覆盖目标。
+ *
+ * 抽成独立模块的理由是**它有两个消费者**：宿主运行时（SourceRaw / 卡片 / 编译产物）
+ * 与提议存储（`proposals.ts`）。提议是「关于 Agent 动作的待办留痕」，不属于知识树，
+ * 所以它不能反过来依赖 runtime —— 那会把分层倒过来（`diagnosis/` 与 `proposals.ts`
+ * 都是被 runtime 消费的领域模块）。
+ */
+
+export async function writeTextAtomic(path: string, content: string): Promise<void> {
+  // 原子写需要一个与目标同目录的临时文件，所以目标目录必须先存在。0030 起
+  // SourceRaw 落在 `<段>/<source_type>/` 下，而 `ensureLayout` 只建段目录 —— 少了
+  // 这一行，第一次写某一种分类就会 ENOENT（实测）。
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
+  try {
+    await writeFile(temporary, content, 'utf8')
+    await rename(temporary, path)
+  } finally {
+    await unlinkIfExists(temporary)
+  }
+}
+
+export async function writeBufferAtomic(path: string, content: Buffer): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
+  try {
+    await writeFile(temporary, content)
+    await rename(temporary, path)
+  } finally {
+    await unlinkIfExists(temporary)
+  }
+}
+
+export async function unlinkIfExists(path: string): Promise<void> {
+  try {
+    await unlink(path)
+  } catch { /* rename already consumed the temp file */ }
+}