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

package/src/extract.ts

@@ -0,0 +1,632 @@
+import type { KnowledgeCard, SchemaType, SourceRaw, WikiTypeDef } from './types.js'
+
+/**
+ * Pass 0 · 候选抽取 + 归一（与库内判重）。
+ *
+ * 这一层是「SourceRaw → Wiki」的第一个编译阶段，也是唯一一个**不调用模型**的阶段：
+ * 它只做「文档里明明白白写着什么」这件事。三个设计判断：
+ *
+ * 1. **纯函数。** 不碰磁盘、不碰模型、不碰网络，所以它可以被直接单测，
+ *    也可以在重建之外被复用（Agent 想先看看会抽出什么）。真正落盘的是 `rebuild()`。
+ * 2. **只认有据可查的候选。** 每个候选都必须带着 `evidence`（来源 id + 小节 / 原文片段）；
+ *    抽不出证据的位置宁可不出候选，也不编一个名字出来。
+ * 3. **related ≠ same。** `relation` 候选永远只变成图的边，绝不参与卡片合并 ——
+ *    「A 和 B 有关系」和「A 就是 B」是两件事，混起来会把两张卡片糊成一张，
+ *    而且糊掉之后没有任何痕迹能还原。
+ */
+
+export interface CandidateEvidence {
+  sourceId: string
+  /** 候选来自哪个 `##`/`###` 小节（声明式候选可自带）。 */
+  heading?: string
+  /** 支撑这个候选的原文片段；只作证据展示，不参与判重。 */
+  quote?: string
+}
+
+export interface ExtractionCandidate {
+  kind: 'entity' | 'concept' | 'relation'
+  /** Display name, e.g. 「销售口径」. */
+  name: string
+  /** The wiki card type this candidate should become. Must be an enabled WikiTypeDef id. */
+  type: SchemaType
+  evidence: CandidateEvidence
+  /** Other spellings that mean the same thing (from `[[Name|alias]]` and frontmatter). */
+  aliases?: string[]
+  /** Markdown body that backs this candidate (used as the card body). */
+  body?: string
+  /** For kind === 'relation': the other end. */
+  target?: { name: string; type?: SchemaType }
+  /** For kind === 'relation': the relation id, e.g. 'relates_to'. */
+  relation?: string
+  confidence: number
+}
+
+/** 抽取关系候选时使用的默认关系 id；图里也只认这个 id（见 `rebuild()` 的边装配）。 */
+export const RELATES_TO = 'relates_to'
+
+/**
+ * 每份来源最多抽多少张卡片候选。
+ *
+ * 这是**有意为之的上限**，不是省略号：一份长文档的小节可以有几十个，放开就会把
+ * 一个知识库灌成「一篇文档 = 几十张未审核卡片」，人再也不会去看它们。宁可少抽，
+ * 剩下的由 Agent 用声明式候选主动补。
+ */
+export const MAX_CANDIDATES_PER_SOURCE = 12
+
+/** `##`/`###` 小节正文短于此长度就不成候选：那更像标签而不是一个可定义的对象。 */
+const SECTION_MIN_CHARS = 120
+
+/** 这些小节名是结构性噪音，抽成卡片只会污染 wiki。 */
+const GENERIC_HEADINGS = new Set([
+  '参考', '参考资料', '参考文献', '参考链接', '附录', '目录', '变更记录', '更新记录',
+  '版本历史', '修订记录', '相关文档', '相关链接', '致谢', '脚注', '备注', '索引', '术语表',
+])
+
+/** 兜底类型：所有已知类型都不命中时落它（见 `pickType`）。 */
+const FALLBACK_TYPE: SchemaType = 'concept'
+
+/** 与 `runtime.ts` 的 `SAFE_ID` 同形：卡片 id 只允许 ASCII 安全字符。 */
+const SAFE_ENTITY_ID = /^[a-zA-Z0-9._:-]{1,160}$/
+
+/**
+ * 名字归一：小写 + 把非字母数字的连续段折成 `-`。
+ *
+ * **必须与 `candidateKey` / `buildAliasIndex` 用同一套归一**，否则「GMV 口径」和
+ * 「gmv-口径」在索引里是两个键，判重就会漏。这里刻意用小写化而不是运行时 slug 的
+ * 原样保留，因为判重是「同一个指称」的问题，大小写不构成区别。
+ */
+export function normalizeCandidateName(value: string): string {
+  return value.trim().toLowerCase().replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^-+|-+$/g, '').slice(0, 120)
+}
+
+export function candidateKey(candidate: { type: string; name: string }): string {
+  return `${candidate.type}:${normalizeCandidateName(candidate.name)}`
+}
+
+/**
+ * 候选落到磁盘时用的 `entity_id`。
+ *
+ * 卡片 id 必须过 `SAFE_ID`（ASCII），而候选名常常是中文，所以中文名不能直接当 id：
+ * 这里退化成 `candidate-<fnv1a>` 的稳定哈希。名字本身仍然完整地写进卡片 title，
+ * 并作为 alias 进索引，所以下一次判重照样能按名字找到它 —— 判重认的是名字，不是 id。
+ */
+export function candidateEntityId(name: string): string {
+  const normalized = normalizeCandidateName(name)
+  if (SAFE_ENTITY_ID.test(normalized)) return normalized
+  return `candidate-${fnv1a(normalized)}`
+}
+
+/** FNV-1a（32 位）：只用来生成稳定短 id，不用于任何安全目的。 */
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(36)
+}
+
+function stringList(value: unknown): string[] {
+  if (typeof value === 'string') return value.trim() ? [value.trim()] : []
+  if (!Array.isArray(value)) return []
+  return value.map(item => (typeof item === 'string' ? item.trim() : '')).filter(Boolean)
+}
+
+function plainRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+// ------------------------------------------------------------ 类型判定
+
+/**
+ * 用类型注册表的 `examples` / `description` 做**关键词重合**判型。
+ *
+ * 刻意不用模型：这一步只要「像指标就落指标，什么都不像就落概念」，判错了人还能改
+ * （卡片是 unreviewed）。要的是**确定性** —— 同一份文档两次抽取必须得到同一个类型，
+ * 否则增量指纹会永远在变。
+ */
+function typeCorpus(def: WikiTypeDef): string {
+  return [def.id, def.label, def.description, ...def.examples].join('\n').toLowerCase()
+}
+
+/**
+ * 名称的匹配片段。
+ *
+ * 中文没有词边界，只按空格切词的话「销售口径」永远匹配不上任何例子，所以额外补
+ * 2-gram（`销售` / `售口` / `口径`）。片段只用于打分，不用于生成任何 id。
+ */
+function nameFragments(name: string): string[] {
+  const lower = name.trim().toLowerCase()
+  const fragments = new Set<string>()
+  if (lower.length >= 2) fragments.add(lower)
+  for (const token of lower.split(/[^\p{L}\p{N}]+/u)) if (token.length >= 2) fragments.add(token)
+  const compact = [...lower.replace(/[^\p{L}\p{N}]+/gu, '')]
+  for (let index = 0; index + 1 < compact.length; index += 1) fragments.add(`${compact[index]}${compact[index + 1]}`)
+  return [...fragments]
+}
+
+function scoreType(def: WikiTypeDef, name: string): number {
+  const corpus = typeCorpus(def)
+  const full = name.trim().toLowerCase()
+  let score = full.length >= 2 && corpus.includes(full) ? 3 : 0
+  for (const fragment of nameFragments(name)) if (corpus.includes(fragment)) score += 1
+  return score
+}
+
+/** 在**启用的**类型里挑一个；全不命中时落 `concept`（不在注册表里就落第一个启用的）。 */
+function pickType(name: string, enabled: WikiTypeDef[]): SchemaType {
+  let best: WikiTypeDef | undefined
+  let bestScore = 0
+  for (const def of enabled) {
+    const score = scoreType(def, name)
+    // 只有严格更高才替换：同分保持注册表顺序，抽取结果因此是确定的。
+    if (score > bestScore) { best = def; bestScore = score }
+  }
+  if (best) return best.id as SchemaType
+  if (enabled.some(def => def.id === FALLBACK_TYPE)) return FALLBACK_TYPE
+  return (enabled[0]?.id ?? FALLBACK_TYPE) as SchemaType
+}
+
+// ------------------------------------------------------------ 小节切分
+
+interface Section { heading: string; content: string; markdown: string }
+
+/** 按 `##`/`###` 切小节；`#` 与 `####` 不参与（前者是文档标题，后者太细）。 */
+function sectionsOf(content: string): Section[] {
+  const sections: Section[] = []
+  let current: { heading: string; lines: string[] } | undefined
+  const flush = (): void => {
+    if (!current) return
+    const markdown = current.lines.join('\n').trim()
+    const body = current.lines.slice(1).join('\n').trim()
+    sections.push({ heading: current.heading, content: body, markdown })
+    current = undefined
+  }
+  for (const line of content.split(/\r?\n/)) {
+    const match = /^(#{1,4})\s+(.+?)\s*$/.exec(line)
+    if (match) {
+      flush()
+      if (match[1] === '##' || match[1] === '###') current = { heading: match[2]!.replace(/[：:]\s*$/, '').trim(), lines: [line] }
+      continue
+    }
+    if (current) current.lines.push(line)
+  }
+  flush()
+  return sections
+}
+
+function isGenericHeading(heading: string): boolean {
+  const normalized = heading.replace(/[\s：:。.、]+$/g, '').trim()
+  if (GENERIC_HEADINGS.has(normalized)) return true
+  // 纯序号 / 纯数字小节（`1.`、`（二）`、`3`）不构成一个可定义的对象。
+  return /^[（(]?[0-9一二三四五六七八九十]+[)）.、]?$/.test(normalized)
+}
+
+function sectionForName(sections: Section[], name: string): Section | undefined {
+  const normalized = normalizeCandidateName(name)
+  if (!normalized) return undefined
+  return sections.find(section => {
+    const heading = normalizeCandidateName(section.heading)
+    return heading === normalized || (heading.length >= 2 && normalized.includes(heading)) || (normalized.length >= 2 && heading.includes(normalized))
+  })
+}
+
+// ------------------------------------------------------------ 声明式候选
+
+/**
+ * 文档frontmatter / metadata 里可以直接声明候选，这是 Agent 的**逃生通道**：
+ * 自动抽取判断不了的时候，由调用方明确写出「这里有一个 X」。
+ *
+ * `SourceRaw` 只带 `metadata:` 这一块（`loadSources` 只投影它），所以声明写在
+ * `metadata` 里。接受四种形态，按出现顺序合并：
+ *
+ * ```yaml
+ * metadata:
+ *   candidates:                      # ① 分桶
+ *     entities:   [{ name: 订单表, type: table }]
+ *     concepts:   [{ name: 销售口径, aliases: [GMV 口径], body: "…" }]
+ *     relations:  [{ from: 销售口径, to: GMV, relation: relates_to }]
+ *   candidates:                      # ② 扁平数组（每条自带 kind）
+ *     - { kind: entity,  name: 订单表, type: table }
+ *     - { kind: concept, name: 销售口径 }
+ *     - { kind: relation, name: 销售口径, target: { name: GMV } }
+ *     - 纯字符串                       # 等价于 { kind: concept, name: 字符串 }
+ *   entities:  [ … ]                 # ③ 直接挂 entities / concepts / relations
+ *   concepts:  [ … ]
+ *   relations: [ … ]
+ * ```
+ *
+ * 单条候选可带：`name`（或 `title`；关系也可用 `from`）、`type` / `entity_type`、
+ * `aliases`、`body`、`heading`、`confidence`。关系还可带 `to` / `target`、
+ * `relation`（默认 `relates_to`）、`to_type`。
+ */
+interface DeclaredEntry { kind: 'entity' | 'concept' | 'relation'; entry: unknown }
+
+function declaredEntries(metadata: Record<string, unknown>): DeclaredEntry[] {
+  const result: DeclaredEntry[] = []
+  const pushList = (kind: DeclaredEntry['kind'], value: unknown): void => {
+    if (!Array.isArray(value)) return
+    for (const entry of value) result.push({ kind, entry })
+  }
+  const bag = metadata.candidates
+  if (Array.isArray(bag)) {
+    for (const entry of bag) {
+      const record = typeof entry === 'string' ? undefined : plainRecord(entry)
+      const declared = record && typeof record.kind === 'string' ? record.kind.trim().toLowerCase() : ''
+      const kind: DeclaredEntry['kind'] = declared === 'relation' ? 'relation' : declared === 'entity' ? 'entity' : 'concept'
+      result.push({ kind, entry })
+    }
+  } else if (bag !== null && typeof bag === 'object') {
+    const bucket = plainRecord(bag)
+    pushList('entity', bucket.entities)
+    pushList('concept', bucket.concepts)
+    pushList('relation', bucket.relations)
+  }
+  pushList('entity', metadata.entities)
+  pushList('concept', metadata.concepts)
+  pushList('relation', metadata.relations)
+  return result
+}
+
+function entryName(entry: unknown): string {
+  if (typeof entry === 'string') return entry.trim()
+  const record = plainRecord(entry)
+  for (const key of ['name', 'title', 'from'] as const) {
+    const value = record[key]
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+  return ''
+}
+
+/** 显式声明的类型 id：原样带出去，交给 `writeCard` 的类型闸门裁决（不在这里改判）。 */
+function entryTypeId(entry: unknown): string | undefined {
+  const record = plainRecord(entry)
+  for (const key of ['type', 'entity_type'] as const) {
+    const value = record[key]
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+  return undefined
+}
+
+function entryTargetName(entry: unknown): string {
+  const record = plainRecord(entry)
+  const target = record.target
+  if (typeof record.to === 'string' && record.to.trim()) return record.to.trim()
+  if (typeof target === 'string' && target.trim()) return target.trim()
+  const nested = plainRecord(target)
+  return typeof nested.name === 'string' ? nested.name.trim() : ''
+}
+
+function entryTargetTypeId(entry: unknown): string | undefined {
+  const record = plainRecord(entry)
+  const direct = record.to_type
+  if (typeof direct === 'string' && direct.trim()) return direct.trim()
+  const nested = plainRecord(record.target)
+  return typeof nested.type === 'string' && nested.type.trim() ? nested.type.trim() : undefined
+}
+
+function entryRelation(entry: unknown): string {
+  const value = plainRecord(entry).relation
+  return typeof value === 'string' && value.trim() ? value.trim() : RELATES_TO
+}
+
+function entryConfidence(entry: unknown, fallback: number): number {
+  const value = Number(plainRecord(entry).confidence)
+  return Number.isFinite(value) && value > 0 && value <= 1 ? value : fallback
+}
+
+function entryBody(entry: unknown): string | undefined {
+  const value = plainRecord(entry).body
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function entryHeading(entry: unknown): string | undefined {
+  const value = plainRecord(entry).heading
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function entryQuote(entry: unknown): string {
+  const text = typeof entry === 'string' ? entry : JSON.stringify(entry)
+  return text.replace(/\s+/g, ' ').trim().slice(0, 240)
+}
+
+// ------------------------------------------------------------ 抽取入口
+
+/** 文档自己的主候选：声明式优先，其次第一个像样的小节（`[[链接]]` 关系的起点）。 */
+function kindFor(type: SchemaType): 'entity' | 'concept' {
+  return type === FALLBACK_TYPE ? 'concept' : 'entity'
+}
+
+export function extractCandidates(source: SourceRaw, wikiTypes: WikiTypeDef[]): ExtractionCandidate[] {
+  const metadata = plainRecord(source.metadata)
+  const enabled = wikiTypes.filter(def => def.enabled)
+  const sections = sectionsOf(source.content)
+  const evidence = (heading?: string, quote?: string): CandidateEvidence => ({
+    sourceId: source.sourceId,
+    ...(heading ? { heading } : {}),
+    ...(quote ? { quote } : {}),
+  })
+  // 显式声明的类型原样采信：抽取器不替 Agent 改判类型。写不进去（id 未登记 / 已停用）
+  // 是 `writeCard` 的闸门该说的话，那时它会被计入 candidatesRejected 而不是被静默换型。
+  const declaredType = (raw: string | undefined, name: string): SchemaType => (raw ?? pickType(name, enabled)) as SchemaType
+
+  // ---- ① / ② 声明式候选（最高置信）
+  const declaredEntities: ExtractionCandidate[] = []
+  const declaredRelations: ExtractionCandidate[] = []
+  for (const { kind, entry } of declaredEntries(metadata)) {
+    const name = entryName(entry)
+    if (!name) continue
+    const type = declaredType(entryTypeId(entry), name)
+    if (kind === 'relation') {
+      const to = entryTargetName(entry)
+      if (!to) continue
+      declaredRelations.push({
+        kind: 'relation', name, type,
+        evidence: evidence(entryHeading(entry), entryQuote(entry)),
+        target: { name: to, ...(entryTargetTypeId(entry) ? { type: declaredType(entryTargetTypeId(entry), to) } : {}) },
+        relation: entryRelation(entry),
+        confidence: entryConfidence(entry, 0.95),
+      })
+      continue
+    }
+    const aliases = stringList(plainRecord(entry).aliases)
+    const heading = entryHeading(entry) ?? sectionForName(sections, name)?.heading
+    const body = entryBody(entry) ?? sectionForName(sections, name)?.markdown
+    declaredEntities.push({
+      kind: kind === 'entity' ? 'entity' : kindFor(type), name, type,
+      evidence: evidence(heading, entryQuote(entry)),
+      ...(aliases.length > 0 ? { aliases } : {}),
+      ...(body ? { body } : {}),
+      confidence: entryConfidence(entry, 0.95),
+    })
+  }
+
+  // ---- ④ 小节候选（先算：`[[链接]]` 的关系起点可能就是第一个小节）
+  const headingCandidates: ExtractionCandidate[] = []
+  for (const section of sections) {
+    if (isGenericHeading(section.heading)) continue
+    if (section.content.length < SECTION_MIN_CHARS) continue
+    const type = pickType(section.heading, enabled)
+    headingCandidates.push({
+      kind: kindFor(type), name: section.heading, type,
+      evidence: evidence(section.heading, section.content.slice(0, 240)),
+      body: section.markdown,
+      confidence: 0.5,
+    })
+  }
+
+  // ---- ③ wikilink 候选 + 从主候选指向它的 relates_to
+  const linkCandidates: ExtractionCandidate[] = []
+  const linkSeen = new Set<string>()
+  /**
+   * 每个 `[[链接]]` 落在哪个小节里。
+   *
+   * 0029 实跑发现的召回污染就是这里造成的：链接候选原来只带 `evidence(undefined, …)`，
+   * 于是它**没有正文**，落卡时只能拿 wiki 类型的模板顶上 —— 模型召回到的是
+   * 「（必填：写什么）」。而链接所在的那一小节就是关于它的现成说明，本来就在手边。
+   */
+  const sectionByHeading = new Map(sections.map(section => [section.heading, section]))
+  const linkSection = new Map<string, Section>()
+  {
+    let current: Section | undefined
+    for (const line of source.content.split(/\r?\n/)) {
+      const heading = /^#{2,6}\s+(.+?)\s*$/.exec(line)
+      if (heading) { current = sectionByHeading.get(heading[1]!.trim()); continue }
+      if (!current) continue
+      for (const match of line.matchAll(/\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g)) {
+        const name = (match[1] ?? '').trim()
+        if (name && !linkSection.has(name)) linkSection.set(name, current)
+      }
+    }
+  }
+  for (const match of source.content.matchAll(/\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g)) {
+    const name = (match[1] ?? '').trim()
+    if (!name) continue
+    const alias = (match[2] ?? '').trim()
+    const type = pickType(name, enabled)
+    const key = candidateKey({ type, name })
+    if (linkSeen.has(key)) continue
+    linkSeen.add(key)
+    const section = linkSection.get(name)
+    linkCandidates.push({
+      kind: kindFor(type), name, type,
+      evidence: evidence(section?.heading, match[0].slice(0, 240)),
+      ...(alias ? { aliases: [alias] } : {}),
+      ...(section ? { body: section.markdown } : {}),
+      confidence: 0.6,
+    })
+  }
+  const primary = declaredEntities[0] ?? headingCandidates[0]
+  const linkRelations: ExtractionCandidate[] = []
+  if (primary) {
+    for (const link of linkCandidates) {
+      // 主候选指向自己不算关系。
+      if (candidateKey(primary) === candidateKey(link)) continue
+      linkRelations.push({
+        kind: 'relation', name: primary.name, type: primary.type,
+        evidence: link.evidence,
+        target: { name: link.name, type: link.type },
+        relation: RELATES_TO,
+        confidence: 0.55,
+      })
+    }
+  }
+
+  // ---- ⑤ 什么都没抽到时，文档标题本身就是一个候选（有标题就有据）
+  const titleCandidates: ExtractionCandidate[] = []
+  const title = (source.title ?? '').trim()
+  if (declaredEntities.length + linkCandidates.length + headingCandidates.length === 0 && title) {
+    const type = pickType(title, enabled)
+    titleCandidates.push({
+      kind: kindFor(type), name: title, type,
+      // 整篇正文就是「这篇文档在讲什么」的正文 —— 没有小节可切时，它就是唯一的内容。
+      evidence: evidence(undefined, title),
+      ...(source.content.trim() ? { body: source.content.trim() } : {}),
+      confidence: 0.35,
+    })
+  }
+
+  // 顺序 = 优先级（声明式 → 链接 → 小节 → 标题），同类内保持文档出现顺序；
+  // 上限只砍尾部的低置信候选，不会把声明式候选挤掉。
+  const entities: ExtractionCandidate[] = []
+  const entitySeen = new Set<string>()
+  for (const candidate of [...declaredEntities, ...linkCandidates, ...headingCandidates, ...titleCandidates]) {
+    if (!candidate.name.trim()) continue
+    const key = candidateKey(candidate)
+    if (entitySeen.has(key)) continue
+    entitySeen.add(key)
+    entities.push(candidate)
+    if (entities.length >= MAX_CANDIDATES_PER_SOURCE) break
+  }
+  const relations: ExtractionCandidate[] = []
+  const relationSeen = new Set<string>()
+  for (const candidate of [...declaredRelations, ...linkRelations]) {
+    const to = candidate.target?.name?.trim()
+    if (!candidate.name.trim() || !to) continue
+    const key = `${normalizeCandidateName(candidate.name)}->${normalizeCandidateName(to)}:${candidate.relation ?? RELATES_TO}`
+    if (relationSeen.has(key)) continue
+    relationSeen.add(key)
+    relations.push(candidate)
+    if (relations.length >= MAX_CANDIDATES_PER_SOURCE) break
+  }
+  return [...entities, ...relations]
+}
+
+// ------------------------------------------------------------ 归一 · 与库内判重
+
+/**
+ * 现有卡片的判重索引。
+ *
+ * 三处都登记：`entityType + entityId`（技术 id）、`entityType + title`（人写的中文名）、
+ * `metadata.aliases` 里的每个写法。**别名是关键字**：Agent 写卡片时把「GMV 口径」登记
+ * 成 `gmv-kpi` 的别名，抽取器下一次就认得这两者是同一个指称，不会再造第二张卡。
+ */
+export function buildAliasIndex(cards: KnowledgeCard[]): Map<string, KnowledgeCard> {
+  const index = new Map<string, KnowledgeCard>()
+  const put = (type: string, name: unknown, card: KnowledgeCard): void => {
+    if (typeof name !== 'string' || !name.trim()) return
+    const key = candidateKey({ type, name })
+    // 先到先得：同一 slug 撞车时保持确定性，不让文件系统顺序决定谁赢。
+    if (!index.has(key)) index.set(key, card)
+  }
+  for (const card of cards) {
+    put(card.entityType, card.entityId, card)
+    put(card.entityType, card.title, card)
+    for (const alias of stringList(plainRecord(card.metadata).aliases)) put(card.entityType, alias, card)
+  }
+  return index
+}
+
+export interface NormalizedCandidates {
+  fresh: ExtractionCandidate[]
+  /**
+   * Candidates whose referent already exists: merge into that card.
+   *
+   * `body` 是**这次新抽到的正文**，必须一起带出去。只带 `sourceId` 的话，调用方
+   * 除了「记一笔来源」什么也做不了 —— 新写进来源里的内容会**静默消失**，卡片永远
+   * 停在第一次抽取时的样子（落点是 `runtime.ts` 的 `appendExtracted`）。
+   */
+  merges: Array<{ key: string; entityId: string; entityType: SchemaType; sourceId: string; body: string }>
+  /**
+   * Relation candidates are never merged — they become graph edges.
+   *
+   * `fromKey` / `toKey` 是**图上的节点键**（`<entityType>:<entityId>`），不是候选键
+   * （`<type>:<归一化名字>`）。两者在名字是 ASCII 时长得一样，在中文名上完全不同 ——
+   * 中文名的卡片 id 会退化成 `candidate-<hash>`。这里必须先解析成真正的节点键，
+   * 否则装配图时按候选键去找节点，**所有中文名之间的关系都会被当成「端点不存在」丢掉**。
+   */
+  relations: Array<{ fromKey: string; toKey: string; relation: string; sourceId: string }>
+}
+
+/**
+ * 归一：把候选分成「新建」「并入已有卡片」「关系」三类。
+ *
+ * 关系两端也走同一套判重，所以边只可能连到**真实存在的 wiki 节点**上；解析不出来的
+ * 端点会带着一个稳定 key 出去，由 `rebuild()` 在装配图时丢弃并计数，而不是在这里
+ * 凭空造一个节点。
+ */
+export function normalizeCandidates(candidates: ExtractionCandidate[], index: Map<string, KnowledgeCard>): NormalizedCandidates {
+  const resolved = new Map(index)
+  const byName = new Map<string, string[]>()
+  const remember = (key: string): void => {
+    const separator = key.indexOf(':')
+    const name = separator >= 0 ? key.slice(separator + 1) : key
+    const bucket = byName.get(name)
+    if (bucket) { if (!bucket.includes(key)) bucket.push(key) }
+    else byName.set(name, [key])
+  }
+  for (const key of resolved.keys()) remember(key)
+
+  const lookup = (name: string, type?: string): string | undefined => {
+    const normalized = normalizeCandidateName(name)
+    if (!normalized) return undefined
+    if (type) {
+      const exact = `${type}:${normalized}`
+      if (resolved.has(exact)) return exact
+    }
+    // 没给类型（或给的类型对不上）时按名字找：判重认的是指称，不是类型。
+    return byName.get(normalized)?.[0]
+  }
+
+  /** 候选键 → 图上的节点键。找不到对应卡片时返回 undefined，由调用方决定怎么兜底。 */
+  const nodeKey = (name: string, type?: string): string | undefined => {
+    const key = lookup(name, type)
+    if (!key) return undefined
+    const card = resolved.get(key)
+    return card ? `${card.entityType}:${card.entityId}` : key
+  }
+
+  const fresh: ExtractionCandidate[] = []
+  const merges: NormalizedCandidates['merges'] = []
+  const relations: NormalizedCandidates['relations'] = []
+  /** 本次已判为「新建」的 key（含别名）：同一份文档里的重复写法不再各建一张。 */
+  const freshKeys = new Set<string>()
+
+  const register = (key: string, card: KnowledgeCard): void => {
+    if (!resolved.has(key)) resolved.set(key, card)
+    remember(key)
+  }
+
+  for (const candidate of candidates) {
+    if (candidate.kind === 'relation') {
+      const targetName = candidate.target?.name ?? ''
+      if (!candidate.name.trim() || !targetName.trim()) continue
+      const targetType = candidate.target?.type
+      relations.push({
+        // 解析不出来时退回候选键：它一定不在 nodeMap 里，装配阶段会把它计入
+        // relationsDropped —— 这比在这里凭空造一个节点诚实。
+        fromKey: nodeKey(candidate.name, candidate.type) ?? candidateKey({ type: candidate.type, name: candidate.name }),
+        toKey: nodeKey(targetName, targetType) ?? candidateKey({ type: targetType ?? candidate.type, name: targetName }),
+        relation: candidate.relation ?? RELATES_TO,
+        sourceId: candidate.evidence.sourceId,
+      })
+      continue
+    }
+    const key = candidateKey(candidate)
+    if (freshKeys.has(key)) continue
+    const existing = resolved.get(key)
+    if (existing) {
+      merges.push({ key, entityId: existing.entityId, entityType: existing.entityType, sourceId: candidate.evidence.sourceId, body: candidate.body ?? '' })
+      continue
+    }
+    fresh.push(candidate)
+    const projected: KnowledgeCard = {
+      entityId: candidateEntityId(candidate.name),
+      entityType: candidate.type,
+      title: candidate.name,
+      status: 'unreviewed',
+      content: candidate.body ?? '',
+      sourceRefs: [candidate.evidence.sourceId],
+      metadata: {},
+      updatedAt: '',
+    }
+    freshKeys.add(key)
+    register(key, projected)
+    for (const alias of candidate.aliases ?? []) {
+      const aliasKey = candidateKey({ type: candidate.type, name: alias })
+      freshKeys.add(aliasKey)
+      register(aliasKey, projected)
+    }
+  }
+  return { fresh, merges, relations }
+}