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

package/src/wiki-types.ts

@@ -0,0 +1,357 @@
+import { DIAGNOSIS_ENTITIES } from './diagnosis/schema.js'
+import type { CardSchemaIssue, WikiFieldSpec, WikiSectionSpec, WikiTypeDef } from './types.js'
+
+/**
+ * Wiki 卡片类型的出厂定义与校验（issue 0024）。
+ *
+ * 这一层回答的是"**SourceRaw → Wiki** 能生成什么、每类长什么样"。它不是生成器：
+ * 生成仍由模型完成（`write_knowledge_card`），这里提供的是**判据 + 骨架 + 校验**。
+ *
+ * 三个设计判断：
+ *
+ * 1. **schema 就是提示词。** 类型定义、示例、必填小节都随 `write_knowledge_card` 的工具
+ *    描述下发（与 0023 同一机制），所以用户改完类型下一轮模型就看到新规则。
+ * 2. **模板决定这套 schema 能不能被用起来**（0021 的判断）。`template` 由 `sections` 派生，
+ *    不手写第二份，否则又是一处"校验通过但人照着抄还是错"。
+ * 3. **校验分三层**：格式 / 引用 / 语义。混成同一个"校验失败"，人就学不会怎么写卡片。
+ */
+
+/** 出厂 wiki 类型：6 个通用类型 + diagnosis 的 5 个类型族。 */
+const GENERIC_TYPES: Array<Omit<WikiTypeDef, 'template' | 'enabled' | 'builtin' | 'cardCount'>> = [
+  {
+    id: 'concept',
+    label: '概念',
+    description: '一个业务或技术概念的定义与边界，回答「这个词在我們这儿指什么」。',
+    layer: 'type',
+    sections: [
+      { label: '定义', required: true },
+      { label: '边界与反例', required: true },
+      { label: '关联', required: false },
+    ],
+    fields: [{ name: 'owner', required: false, note: '谁维护这个概念的定义' }],
+    sourceTypes: [],
+    examples: ['什么是活跃用户', '「有效订单」的口径是什么', '这个指标和那个指标什么关系'],
+  },
+  {
+    id: 'metric',
+    label: '指标',
+    description: '一个可计算、可归属的量化口径，回答「这个数是怎么算出来的」。',
+    layer: 'type',
+    sections: [
+      { label: '口径定义', required: true },
+      { label: '计算逻辑', required: true },
+      { label: '负责人', required: false },
+    ],
+    fields: [
+      { name: 'formula', required: true, note: '可执行的表达式或伪代码' },
+      { name: 'owner', required: true, note: '谁对这个口径负责' },
+    ],
+    sourceTypes: ['document', 'prd'],
+    examples: ['上个月的 GMV 怎么算', '转化率的口径是什么', '这个指标怎么拆'],
+  },
+  {
+    id: 'table',
+    label: '数据表',
+    description: '一张有明确语义、粒度和归属的数据表。',
+    layer: 'type',
+    sections: [
+      { label: '用途', required: true },
+      { label: '字段与口径', required: true },
+      { label: '更新与负责人', required: false },
+    ],
+    fields: [
+      { name: 'owner', required: true, note: '表责任人' },
+      { name: 'grain', required: true, note: '一行代表什么（粒度）' },
+    ],
+    sourceTypes: ['document'],
+    examples: ['订单表有哪些字段', '这张表的粒度是什么', '这张表多久更新一次'],
+  },
+  {
+    id: 'event',
+    label: '事件',
+    description: '一个会改变业务状态、需要被记录和响应的事实。',
+    layer: 'instance',
+    sections: [
+      { label: '触发条件', required: true },
+      { label: '影响', required: true },
+      { label: '处理方式', required: true },
+    ],
+    fields: [{ name: 'severity', required: true, note: '影响级别' }],
+    sourceTypes: ['chat_message', 'question'],
+    examples: ['上游延迟告警怎么处理', '这次大促爆单是怎么回事'],
+  },
+  {
+    id: 'playbook',
+    label: '手册',
+    description: '一类问题的标准做法，回答「该怎么做」而不是「做过什么」。',
+    layer: 'type',
+    sections: [
+      { label: '适用场景', required: true },
+      { label: '步骤', required: true },
+      { label: '验收与失败处理', required: false },
+    ],
+    fields: [{ name: 'owner', required: true, note: '手册维护人' }],
+    sourceTypes: ['document', 'prd'],
+    examples: ['新人怎么接入一张表', '发布前要检查什么'],
+  },
+  {
+    id: 'case',
+    label: '案例',
+    description: '一件真实发生过的事：背景、经过、结果与教训。',
+    layer: 'instance',
+    sections: [
+      { label: '背景', required: true },
+      { label: '经过', required: true },
+      { label: '结果与教训', required: true },
+    ],
+    fields: [{ name: 'occurred_at', required: true, note: '发生时间' }],
+    sourceTypes: ['chat_message', 'question'],
+    examples: ['上次数据延迟是怎么定位的', '那次口径改动的来龙去脉'],
+  },
+]
+
+/** diagnosis 五类的说明；字段与小节直接取自 0021 的 schema，不复制第二份。 */
+const DIAGNOSIS_DESCRIPTIONS: Record<string, string> = {
+  'diagnosis/symptom': '一类可复用的现象：可观测口径 + 进入条件，是排查的入口。',
+  'diagnosis/hypothesis': '一条可判真假的假设，带反例边界，是排查的中间层。',
+  'diagnosis/check': '一步可执行的检查，回答「怎么验证一个假设」。',
+  'diagnosis/failure-mode': '失败模式切面：把假设按根因类别分组，用于排序与查重。',
+  'diagnosis/case': '一次真实排查的完整路径，是实例层的记录而不是可复用知识。',
+}
+
+const DIAGNOSIS_EXAMPLES: Record<string, string[]> = {
+  'diagnosis/symptom': ['销售额突然掉了', '今天报表数对不上'],
+  'diagnosis/hypothesis': ['上游同步漏了', '口径被人改过'],
+  'diagnosis/check': ['查一下上游任务状态', '比对两天的分区行数'],
+  'diagnosis/failure-mode': ['上游缺失', '口径变更', '数据处理'],
+  'diagnosis/case': ['上次大促数据延迟的排查过程'],
+}
+
+/** 由小节派生模板卡。**没有第二份手写模板**：改了 sections，模板跟着变。 */
+export function templateCardFor(sections: WikiSectionSpec[], fields: WikiFieldSpec[] = []): string {
+  const required = sections.filter(section => section.required).map(section => section.label)
+  const head = fields.filter(field => field.required).map(field => `> 必填字段：\`${field.name}\`（${field.note}）`)
+  const body = sections.map(section => `## ${section.label}\n\n（${section.required ? '必填' : '可选'}：写什么）\n`).join('\n')
+  const summary = required.length > 0 ? `<!-- 必填小节：${required.join(' / ')} -->` : ''
+  return [summary, ...head, '', body].filter(Boolean).join('\n')
+}
+
+function make(def: Omit<WikiTypeDef, 'template' | 'enabled' | 'builtin' | 'cardCount'>): WikiTypeDef {
+  const sections: WikiSectionSpec[] = def.sections.map(section => ({ ...section }))
+  const fields: WikiFieldSpec[] = def.fields.map(field => ({ ...field }))
+  return { ...def, sections, fields, sourceTypes: [...def.sourceTypes], examples: [...def.examples], template: templateCardFor(sections, fields), enabled: true, builtin: true, cardCount: 0 }
+}
+
+/**
+ * 出厂注册表：6 个通用类型 + diagnosis 的 5 个类型族。
+ *
+ * diagnosis 的部分**从 `diagnosis/schema.ts` 取**——0021 明确要求那张清单只有一个定义处，
+ * 抄第二份的下场是"校验通过了但编译器不认"。
+ */
+export const DEFAULT_WIKI_TYPES: WikiTypeDef[] = [
+  ...GENERIC_TYPES.map(make),
+  ...DIAGNOSIS_ENTITIES.map(spec => make({
+    id: spec.entityType,
+    label: spec.label,
+    description: DIAGNOSIS_DESCRIPTIONS[spec.entityType] ?? spec.label,
+    layer: spec.layer === 'instance' ? 'instance' : 'type',
+    sections: spec.sections.map(label => ({ label, required: true })),
+    fields: spec.fields.map(field => ({ name: field.name, required: field.system !== true, note: field.note })),
+    sourceTypes: [],
+    examples: DIAGNOSIS_EXAMPLES[spec.entityType] ?? [],
+  })),
+]
+
+const BUILTIN_IDS: ReadonlySet<string> = new Set(DEFAULT_WIKI_TYPES.map(def => def.id))
+
+export function isBuiltinWikiType(id: string): boolean {
+  return BUILTIN_IDS.has(id)
+}
+
+/** 出厂注册表副本（全部启用，`cardCount` 待算）。 */
+export function defaultWikiTypes(): WikiTypeDef[] {
+  return DEFAULT_WIKI_TYPES.map(def => ({
+    ...def,
+    sections: def.sections.map(section => ({ ...section })),
+    fields: def.fields.map(field => ({ ...field })),
+    sourceTypes: [...def.sourceTypes],
+    examples: [...def.examples],
+    cardCount: 0,
+  }))
+}
+
+/**
+ * 内置只读的判定规则：模型该按什么顺序挑类型。
+ *
+ * 与 0013 的 `classifierPrompt` 同构——**不允许修改，但必须暴露**。
+ */
+export const WIKI_TYPE_RULES = [
+  '先按每个类型的「定义」与「例如」判断这张卡片属于哪一类；命中就直接用它，不要新起一个近义的类型。',
+  '所有类型都不命中时，才按语义新起一个类型 id（小写英文，可带 `命名空间/名字`），并在知识库设置里把它登记成正式类型。',
+  '一张卡片只讲一件事：概念讲定义、指标讲口径、手册讲做法、案例讲发生过的事。混在一起时要拆成多张卡片。',
+  '卡片必须引用真实存在的 SourceRaw：`source_refs` 写了不存在的来源会被直接拒绝。',
+  '必填小节与必填字段来自类型定义；缺了它们卡片仍然可写（report 模式），但会被标成待补。',
+].join('\n')
+
+/** 新增 / 编辑类型时提交的草稿。 */
+export interface WikiTypeDraft {
+  id?: string
+  label?: string
+  description?: string
+  layer?: string
+  sections?: unknown
+  fields?: unknown
+  sourceTypes?: unknown
+  examples?: unknown
+}
+
+export interface WikiTypeDraftProblem {
+  ok: false
+  code: string
+  message: string
+  suggestion?: string
+  field: 'id' | 'label' | 'description' | 'sections' | 'fields'
+}
+
+/** 解析「每行一条」的小节草稿：`名称` 或 `名称*`（`*` = 必填）。 */
+export function parseSectionLines(value: unknown): WikiSectionSpec[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((item): WikiSectionSpec[] => {
+    if (typeof item === 'object' && item !== null) {
+      const record = item as Record<string, unknown>
+      const label = typeof record.label === 'string' ? record.label.trim() : ''
+      return label ? [{ label, required: record.required !== false }] : []
+    }
+    const text = String(item).trim()
+    if (!text) return []
+    const required = !text.endsWith('?')
+    return [{ label: required ? text : text.slice(0, -1).trim(), required }]
+  })
+}
+
+/** 解析字段草稿：`name` / `name|说明` / `name|说明|可选`。 */
+export function parseFieldLines(value: unknown): WikiFieldSpec[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((item): WikiFieldSpec[] => {
+    // 已经是对象形态（整表 round-trip / 编辑已有类型）时按字段取，不要再 stringify 成 [object Object]。
+    if (typeof item === 'object' && item !== null) {
+      const record = item as Record<string, unknown>
+      const name = typeof record.name === 'string' ? record.name.trim() : ''
+      if (!name) return []
+      return [{ name, note: typeof record.note === 'string' ? record.note : '', required: record.required !== false }]
+    }
+    const text = String(item).trim()
+    if (!text) return []
+    const [rawName, rawNote = '', rawOptional = ''] = text.split('|').map(part => part.trim())
+    if (!rawName) return []
+    return [{ name: rawName, note: rawNote, required: rawOptional !== '可选' && rawOptional !== 'optional' }]
+  })
+}
+
+/**
+ * 校验一份类型草稿。
+ *
+ * 与 0013 的 source type 一样：光给个名字不让入库——入库的 `sections` / `fields` 会直接
+ * 变成"卡片该怎么写"的约束。
+ */
+export function validateWikiTypeDraft(draft: WikiTypeDraft, knownIds: ReadonlySet<string>): { ok: true } | WikiTypeDraftProblem {
+  const id = typeof draft.id === 'string' ? draft.id.trim() : ''
+  if (!/^[a-z][a-z0-9_/-]{1,60}$/.test(id)) {
+    return { ok: false, code: 'WIKI_TYPE_ID_INVALID', field: 'id', message: '类型 id 必须是小写字母开头的 2–61 位小写字母 / 数字 / 下划线 / 连字符 / 斜杠', suggestion: '例如 metric、diagnosis/symptom；id 创建后不可修改。' }
+  }
+  if (isBuiltinWikiType(id)) {
+    return { ok: false, code: 'WIKI_TYPE_BUILTIN_LOCKED', field: 'id', message: `内置类型 id 不可占用: ${id}`, suggestion: '内置类型可以改文案、停用，但不能删；新场景请另起 id。' }
+  }
+  void knownIds
+  return validateWikiTypeText(draft)
+}
+
+/** 只校验文案与小节 / 字段，不碰 id（内置类型改内容走这里）。 */
+export function validateWikiTypeText(draft: WikiTypeDraft): { ok: true } | WikiTypeDraftProblem {
+  const label = typeof draft.label === 'string' ? draft.label.trim() : ''
+  if (!label) return { ok: false, code: 'WIKI_TYPE_LABEL_REQUIRED', field: 'label', message: 'label 不能为空' }
+  const description = typeof draft.description === 'string' ? draft.description.trim() : ''
+  if (description.length < 8) {
+    return { ok: false, code: 'WIKI_TYPE_DESCRIPTION_REQUIRED', field: 'description', message: 'description 必填，且要写清这个类型「是什么」', suggestion: '一句话定义，至少 8 个字；它是模型判断卡片类型的主要依据。' }
+  }
+  const sections = parseSectionLines(draft.sections)
+  if (sections.length === 0) {
+    return { ok: false, code: 'WIKI_TYPE_SECTIONS_REQUIRED', field: 'sections', message: '至少写一个小节', suggestion: '小节是卡片的骨架，也是模板卡与校验的依据；一行一个，例如「口径定义」。' }
+  }
+  if (!sections.some(section => section.required)) {
+    return { ok: false, code: 'WIKI_TYPE_SECTION_REQUIRED_MISSING', field: 'sections', message: '至少要有一个必填小节', suggestion: '没有必填小节，这张卡片就没有可校验的骨架。' }
+  }
+  const fields = parseFieldLines(draft.fields)
+  const seenNames = new Set<string>()
+  for (const field of fields) {
+    if (seenNames.has(field.name)) return { ok: false, code: 'WIKI_TYPE_FIELD_DUPLICATE', field: 'fields', message: `字段名重复: ${field.name}` }
+    seenNames.add(field.name)
+  }
+  return { ok: true }
+}
+
+const PLACEHOLDER = /(TODO|待补充|待填|xxx|XXX|写什么)/
+
+/** 卡片正文里找小节标题：`## 小节名` 或 `### 小节名`（标题后可有补充文字）。 */
+function hasSection(content: string, label: string): boolean {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`^#{2,4}\\s*${escaped}`, 'm').test(content)
+}
+
+/**
+ * 三层校验：format / reference / semantic。
+ *
+ * 只报问题，不决定是否写入——是否拦截由 `wikiSchemaMode` 决定（strict 拒绝 / report 标记）。
+ */
+export function validateCardAgainstType(
+  type: WikiTypeDef,
+  card: { title: string; content: string; sourceRefs: string[]; metadata: Record<string, unknown>; owner?: string; summary?: string },
+): CardSchemaIssue[] {
+  const issues: CardSchemaIssue[] = []
+
+  // ---- format：必填小节与必填字段
+  for (const section of type.sections) {
+    if (!section.required) continue
+    if (!hasSection(card.content, section.label)) {
+      issues.push({ level: 'format', field: section.label, message: `缺少必填小节「${section.label}」` })
+    }
+  }
+  for (const field of type.fields) {
+    if (!field.required) continue
+    const topLevel = field.name === 'owner' ? card.owner : field.name === 'summary' ? card.summary : undefined
+    const inMetadata = card.metadata[field.name]
+    if (!topLevel?.toString().trim() && (inMetadata === undefined || inMetadata === null || String(inMetadata).trim() === '')) {
+      issues.push({ level: 'format', field: field.name, message: `缺少必填字段 ${field.name}（${field.note}）` })
+    }
+  }
+
+  // ---- reference：来源分类是否符合该类型的期望（只提示，不阻断）
+  if (type.sourceTypes.length > 0) {
+    const mismatched = card.metadata.source_types
+    if (Array.isArray(mismatched) && mismatched.length > 0) {
+      const allowed = new Set(type.sourceTypes)
+      const outside = mismatched.map(String).filter(id => !allowed.has(id))
+      if (outside.length > 0) {
+        issues.push({ level: 'reference', field: 'source_types', message: `来源分类 ${outside.join(' / ')} 不在该类型的期望范围（${type.sourceTypes.join(' / ')}）内` })
+      }
+    }
+  }
+
+  // ---- semantic：正文不能只有标题，也不能留着占位符
+  const body = card.content
+    .split('\n')
+    .filter(line => !/^\s*#{1,6}\s/.test(line))
+    .join('')
+    .replace(/\s+/g, '')
+  if (body.length < 20) {
+    issues.push({ level: 'semantic', message: `正文实质内容过少（去掉标题后 ${body.length} 字），像是只搭了骨架` })
+  }
+  if (PLACEHOLDER.test(card.content)) {
+    issues.push({ level: 'semantic', message: '正文里还留着占位符（TODO / 待补充 / 写什么）' })
+  }
+  if (type.layer === 'instance' && !card.metadata.occurred_at && type.id === 'case') {
+    issues.push({ level: 'semantic', field: 'occurred_at', message: '案例类卡片应写明发生时间' })
+  }
+
+  return issues
+}