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

package/src/extract-model.ts

@@ -1,47 +1,63 @@
 /**
- * 模型驱动的候选抽取与**实体归并**（#3b）。
+ * 模型驱动的**按 schema 实体抽取与归并**（#3b / 0044）。
  *
- * ## 为什么需要这一步，而不是继续改规则
+ * ## 它解决的问题
  *
- * Pass 0 的规则抽取用**小节标题**当实体身份（`candidateEntityId(candidate.name)`）。
- * 于是同一件东西只要换个标题写法，就是两个实体。这不是理论问题，是实测出来的：
+ * 规则路径（`extract.ts`）拿 `##` 小节标题当实体名。实测的后果有两个，都不是理论问题：
  *
- * - 年报里的小节叫「毛利率变动及其驱动因素」；
- * - 口径手册里的小节叫「毛利率（口径补充）」；
- * - 结果：`新建 2 / 并入 0`，两张互不相干的卡片，
- *   而「实体已存在就追加正文」那条分支**永远不会触发**。
+ * 1. **抽出来的是目录，不是知识。** 年报里的小节叫「毛利率变动及其驱动因素」，
+ *    口径手册里的小节叫「毛利率（口径补充）」，于是同一件东西落成两张互不相干的卡片
+ *    （`新建 2 / 并入 0`），而「实体已存在就追加正文」那条分支**永远不会触发**。
+ *    想去掉括号后缀、去掉「及其驱动因素」，是语义判断，阈值化的字符串规则在第二步
+ *    必然出错（`应收账款周转天数` 与 `库存周转天数` 字面都带「周转天数」）。
+ * 2. **卡片正文是切下来的原文。** 一张 `metric` 卡片应该有「口径定义 / 计算逻辑」两个
+ *    必填小节，而按标题切出来的正文与类型定义毫无关系 —— 它长得像一篇文章，
+ *    不像一张卡片。0044 之前用户在界面上看到的「编译只是按目录截取」说的就是这件事。
  *
- * 想去掉括号后缀、去掉「及其驱动因素」这类尾巴，是**语义判断**：`毛利率` 与
- * `毛利率变动及其驱动因素` 是同一个东西，而 `应收账款周转天数` 与 `库存周转天数`
- * 不是 —— 两者字面都带「周转天数」。阈值化的字符串规则在第二步上必然出错，
- * 所以这件事必须交给模型。
+ * 所以这一层让模型回答三件它擅长、而规则做不好的事：
  *
- * ## 这一层只问一个问题
+ * 1. 「这份来源里有哪些**实体**」；
+ * 2. 「每个实体按它所属类型的 schema **该写成什么样**」—— 必填小节当骨架、必填字段当值；
+ * 3. 「这个实体是不是已经在下表里了」（给出已有卡片的 `existing_id`）。
  *
- * 它**不**让模型自由编造卡片，也不让它决定正文：正文永远是来源里的原文片段，
- * 模型只回答两件它擅长、而规则做不好的事 ——
+ * 第 3 问的**判断权在模型，决定权在这里**：模型说「是同一个」，我们就走追加；
+ * 说「不是」，就新建。模型给出的 `existing_id` 必须能在已有卡片里找到，
+ * 找不到就退回新建 —— 不能让模型凭一个不存在的 id 把内容写丢。
  *
- * 1. 「这份来源里有哪些**实体**」（规则只会按小节切，切出来的是标题不是实体）；
- * 2. 「这个实体是不是已经在下表里了」（给出已有卡片的 `existing_id`）。
+ * ## 缺信息也抽（0044）
  *
- * 第 2 问是归并的关键：**判断权在模型，决定权在这里**。模型说「是同一个」，
- * 我们就走追加；说「不是」，就新建。模型给出的 `existing_id` 必须能在已有卡片里
- * 找到，找不到就退回新建 —— 不能让模型凭一个不存在的 id 把内容写丢。
+ * 0040 那一版要求每条候选「必须带正文」，「必须来自已登记类型」，否则整条丢掉。
+ * 结果是**知识进不来**：一份只写了半句口径的文档，抽出来的东西全被闸门拒了，
+ * 而「半句口径」本身正是最该记下来的东西 —— 后面再来一份文档就能补上。
+ *
+ * 现在只做两件事，不做拒绝：
+ * - 类型不在注册表里 → 退回一个已启用的兜底类型 + 一条 warning（**不丢**）；
+ * - 正文为空 → 用 `summary` 撑起一个带必填小节骨架的最小正文（**不丢**）。
+ * 缺什么，由 `schema_issues` 如实标出来，人在 review 时补。
  *
  * ## 为什么要注入 `call`
  *
  * 模型调用是这一层唯一的非纯部分。把它作为参数注入，这个模块就能在没有模型的环境里
- * 被完整测试（见 `tests/extract-model.test.mjs`）——否则「归并对不对」这件事只能靠
- * 真跑一次模型来验，而那是不可重复的。
+ * 被完整测试（见 `tests/extract-model.test.mjs`）——否则「schema 是否真的传给了模型」
+ * 这件事只能靠真跑一次模型来验，而那是不可重复的。
  *
  * @module
  */
 
 import { candidateEntityId, type ExtractionCandidate } from './extract.js'
+import { templateCardFor } from './wiki-types.js'
 import type { KnowledgeCard, SchemaType, SourceRaw, WikiTypeDef } from './types.js'
 
-/** 一次纯文本模型调用：给出 system 与 prompt，拿回模型的原始文本。 */
-export type ModelCall = (request: { system: string; prompt: string }) => Promise<string>
+/**
+ * 一次纯文本模型调用：给出 system 与 prompt，拿回模型的原始文本。
+ *
+ * `sessionId` 是**路由与缓存亲和**的身份，不是对话（0044 实机验证第五批）。
+ * OpenCode 系的路由要求请求带 `x-opencode-session`，而 `dsh-opencode-session` 插件
+ * 只在 `options.sessionId` 存在时才打那个头 —— 缺了它，400 `MissingSessionID`
+ * 会一路伪装成「模型抽取不可用」。这里把它做成可选字段：假模型不必关心，
+ * 真接缝按知识库给一个稳定值。
+ */
+export type ModelCall = (request: { system: string; prompt: string; sessionId?: string }) => Promise<string>
 
 /** 归并条目：与规则抽取的 `NormalizedCandidates['merges']` 保持同一形状。 */
 export interface ModelMerge {
@@ -50,6 +66,8 @@ export interface ModelMerge {
   entityType: SchemaType
   sourceId: string
   body: string
+  summary?: string
+  fields?: Record<string, string>
 }
 
 export interface ModelExtractionResult {
@@ -62,15 +80,28 @@ export interface ModelExtractionResult {
 
 export interface ModelExtractionInput {
   source: SourceRaw
-  /** 已启用的 wiki 类型：模型只能从这些 id 里选。 */
+  /** 已启用的 wiki 类型：模型只能从这些 id 里选，而且它们的 schema 就是卡片骨架。 */
   wikiTypes: WikiTypeDef[]
   /** 当前库里的卡片：既是「已存在」的候选集，也是给模型的上下文。 */
   existing: KnowledgeCard[]
   call: ModelCall
+  /**
+   * 路由与缓存亲和的身份，按知识库稳定（`knowledge:<库 id>`）。
+   *
+   * 由运行时给：**只有它知道自己在写哪个库**。接缝层拿到什么就传什么，
+   * 没有时退回 `knowledge:default`（假模型、独立 runtime 的测试都属于这一档）。
+   */
+  sessionId?: string
 }
 
-/** 单个实体最多给模型的正文长度：够判断语义，又不至于把上下文撑爆。 */
-const BODY_LIMIT = 1200
+/** 单个实体给模型的正文长度上限：够判断语义，又不至于把上下文撑爆。 */
+const BODY_LIMIT = 2000
+
+/** 文档给模型的长度上限。 */
+const DOCUMENT_LIMIT = BODY_LIMIT * 8
+
+/** 已有卡片目录给模型多少行。 */
+const CATALOG_LIMIT = 200
 
 /**
  * 系统提示。**刻意写死在这里**而不是做成设置项：它不是用户的偏好，是这个模块与模型
@@ -78,16 +109,21 @@ const BODY_LIMIT = 1200
  * 解析器改坏。
  */
 const SYSTEM = [
-  'You extract wiki entities from a business document and decide which of them already exist.',
+  'You turn one business document into wiki cards for a knowledge base.',
   'Answer with a single JSON object and nothing else. No prose, no code fence.',
-  'Shape: {"entities":[{"name":string,"type":string,"summary":string,"body":string,"existing_id":string|null}]}',
+  'Shape: {"entities":[{"name":string,"type":string,"summary":string,"content":string,"fields":{string:string},"existing_id":string|null}]}',
   'Rules:',
-  '- "name" is the entity name as a business person would say it (e.g. 毛利率). Not a section heading.',
+  '- "name" is the entity name as a business person would say it (e.g. 毛利率). Never a section heading.',
   '- "type" MUST be one of the allowed type ids given in the prompt.',
-  '- "body" must be verbatim text from the document that backs this entity. Never invent facts.',
+  '- "content" MUST be markdown for that type: use its required section labels as "## <label>" headings, in order.',
+  '  Fill each section with facts stated in the document. Copy wording, do not paraphrase loosely.',
+  '  If the document does not say enough for a section, still write the heading and put only what IS known.',
+  '  NEVER invent numbers, owners, formulas or dates. Missing information is acceptable; made-up information is not.',
+  '- "fields" holds the type\'s required fields whose values the document states. Omit a field the document does not answer.',
+  '- "summary" is one sentence saying what this entity is.',
   '- "existing_id" is the entityId of the existing card this entity is the SAME thing as, or null.',
   '  Same thing means the same business concept; a narrower or different concept is NOT the same.',
-  '- Prefer few, real entities over many headings.',
+  '- Prefer few, real entities over many sections. Extract an entity even when the document only covers part of it.',
 ].join('\n')
 
 /** 从一串可能带 ``` 围栏的文本里取出 JSON 对象并解析。 */
@@ -110,100 +146,227 @@ function parseJsonObject(raw: string): unknown {
   }
 }
 
-/** 把模型的回答收敛成「合法实体数组」；任何不合法的一条都丢掉并记一条 warning。 */
-function readEntities(raw: unknown, allowedTypes: Set<string>, warnings: string[]): Array<Record<string, unknown>> {
-  if (raw === null || typeof raw !== 'object') {
-    warnings.push('模型输出不是 JSON 对象，本次抽取按空处理')
-    return []
-  }
-  const list = (raw as { entities?: unknown }).entities
-  if (!Array.isArray(list)) {
-    warnings.push('模型输出里没有 entities 数组，本次抽取按空处理')
-    return []
-  }
-  const kept: Array<Record<string, unknown>> = []
-  for (const item of list) {
-    if (item === null || typeof item !== 'object') continue
-    const record = item as Record<string, unknown>
-    const name = typeof record.name === 'string' ? record.name.trim() : ''
-    const type = typeof record.type === 'string' ? record.type.trim() : ''
-    const body = typeof record.body === 'string' ? record.body.trim() : ''
-    if (!name) continue
-    if (!allowedTypes.has(type)) {
-      warnings.push(`模型给出的类型「${type}」不在已启用类型里，候选「${name}」被丢掉`)
-      continue
-    }
-    if (!body) {
-      warnings.push(`候选「${name}」没有正文，被丢掉（卡片不能没有正文）`)
-      continue
-    }
-    kept.push({ ...record, name, type, body })
-  }
-  return kept
-}
-
 /**
- * 用模型抽取实体，并把它们判归到「新建」或「追加到已有卡片」两条路上。
+ * 一个类型的 schema 怎么讲给模型听。
  *
- * 失败一律降级而不抛出：模型不可用时返回空结果 + 一条 warning，让上层继续跑规则抽取。
- * 「因为模型挂了所以整次编译失败」是不能接受的 —— 那条链路本来就不依赖模型。
+ * 这是 0044 的关键一步：**必填小节与必填字段必须出现在提示词里**，否则模型写出来的
+ * 「正文」只能是一段自由文本 —— 而卡片是按小节校验的。导出它，是为了让
+ * 「schema 到底有没有下发」这件事可以在测试里被断言，而不是只能靠读代码相信。
  */
-export async function extractWithModel(input: ModelExtractionInput): Promise<ModelExtractionResult> {
-  const { source, wikiTypes, existing, call } = input
-  const warnings: string[] = []
-  const enabled = wikiTypes.filter(def => def.enabled)
-  const allowedTypes = new Set(enabled.map(def => String(def.id)))
+export function renderTypeSpec(def: WikiTypeDef): string {
+  const sections = def.sections.map(section => `${section.label}${section.required ? '（必填）' : '（可选）'}`).join(' / ')
+  const fields = def.fields.filter(field => field.required).map(field => `${field.name}（${field.note}）`).join('；')
+  return [
+    `- ${def.id} :: ${def.label}${def.description ? ` — ${def.description}` : ''}`,
+    sections ? `  小节：${sections}` : '',
+    fields ? `  必填字段：${fields}` : '',
+    def.examples.length > 0 ? `  例如：${def.examples.join('；')}` : '',
+    `  模板：\n${indent(templateCardFor(def.sections, def.fields))}`,
+  ].filter(Boolean).join('\n')
+}
+
+function indent(value: string): string {
+  return value.split('\n').map(line => `    ${line}`).join('\n')
+}
 
+/** 抽取用的完整提示词。导出以便测试断言「schema 真的在里面」。 */
+export function buildExtractionPrompt(input: Pick<ModelExtractionInput, 'source' | 'wikiTypes' | 'existing'>): string {
+  const { source, wikiTypes, existing } = input
   const catalog = existing
-    .slice(0, 200)
+    .slice(0, CATALOG_LIMIT)
     .map(card => `- ${card.entityId} :: ${card.title}（${card.entityType}）`)
     .join('\n')
-  const types = enabled
-    .map(def => `- ${def.id} :: ${def.label}${def.description ? ` — ${def.description}` : ''}`)
-    .join('\n')
-
-  const prompt = [
+  return [
     '# Allowed wiki type ids',
-    types || '（没有任何已启用类型）',
+    wikiTypes.map(renderTypeSpec).join('\n') || '（没有任何已启用类型）',
     '',
-    '# Existing wiki cards (entityId :: title)',
+    '# Existing wiki cards (entityId :: title（type）)',
     catalog || '（这个库还是空的）',
     '',
     '# Document',
     `title: ${source.title}`,
     `source_id: ${source.sourceId}`,
     '',
-    source.content.slice(0, BODY_LIMIT * 8),
+    source.content.slice(0, DOCUMENT_LIMIT),
   ].join('\n')
+}
+
+/** 把模型的 `fields` 收敛成一个字符串到字符串的字典；非字符串值丢掉。 */
+function readFields(raw: unknown): Record<string, string> {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return {}
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    const name = key.trim()
+    if (!name) continue
+    if (typeof value === 'string' && value.trim()) result[name] = value.trim()
+    else if (typeof value === 'number' && Number.isFinite(value)) result[name] = String(value)
+  }
+  return result
+}
+
+/**
+ * 一个已启用的兜底类型。
+ *
+ * 「类型不认识」不该丢实体 —— 0040 那一版就是在这一步丢的。退回 `concept`，
+ * 它不在注册表里就退第一个启用的类型；一个都没有（注册表被清空）时返回 undefined，
+ * 那时调用方也没有别的选择。
+ */
+function fallbackType(enabled: WikiTypeDef[]): WikiTypeDef | undefined {
+  return enabled.find(def => def.id === 'concept') ?? enabled[0]
+}
+
+interface ReadEntityOptions {
+  enabled: WikiTypeDef[]
+  warnings: string[]
+}
+
+/**
+ * 把模型的一条输出收敛成候选；不合法的一条记 warning 而不是静默丢弃。
+ *
+ * 「缺信息也抽」在这里落成代码：**名字是唯一的硬要求**。类型不认识就退回兜底、
+ * 正文为空就用 summary 撑一个带必填小节骨架的最小正文。
+ */
+function readEntity(item: unknown, options: ReadEntityOptions): { candidate: ExtractionCandidate; existingId?: string } | undefined {
+  const { enabled, warnings } = options
+  if (item === null || typeof item !== 'object') return undefined
+  const record = item as Record<string, unknown>
+  const name = typeof record.name === 'string' ? record.name.trim() : ''
+  if (!name) return undefined
+
+  const wanted = typeof record.type === 'string' ? record.type.trim() : ''
+  const matched = enabled.find(def => def.id === wanted)
+  let type = matched?.id as SchemaType | undefined
+  if (!type) {
+    const fallback = fallbackType(enabled)
+    if (!fallback) {
+      warnings.push(`候选「${name}」没有任何已启用类型可用，被丢掉`)
+      return undefined
+    }
+    warnings.push(`候选「${name}」的类型「${wanted || '（未给）'}」不在已启用类型里，已按「${fallback.id}」入库`)
+    type = fallback.id as SchemaType
+  }
+  const def = enabled.find(candidate => candidate.id === type)!
+
+  // 正文：优先用模型写的 `content`，兼容旧字段名 `body`。
+  const rawBody = typeof record.content === 'string' ? record.content.trim() : typeof record.body === 'string' ? record.body.trim() : ''
+  const summary = typeof record.summary === 'string' ? record.summary.trim() : ''
+  const content = rawBody ? rawBody.slice(0, BODY_LIMIT) : skeletonBody(def, summary)
+
+  const existingId = typeof record.existing_id === 'string' ? record.existing_id.trim() : ''
+  const fields = readFields(record.fields)
+  return {
+    existingId: existingId || undefined,
+    candidate: {
+      kind: type === 'concept' ? 'concept' : 'entity',
+      name,
+      type,
+      body: content,
+      ...(summary ? { summary } : {}),
+      ...(Object.keys(fields).length > 0 ? { fields } : {}),
+      aliases: [],
+      evidence: { sourceId: '' },
+      confidence: existingId ? 0.75 : 0.7,
+    },
+  }
+}
+
+/**
+ * 正文为空时的最小骨架。
+ *
+ * 不是「占位符」：占位符（`（必填：写什么）`）会被编译进召回单元、塞进模型上下文，
+ * 等于管线自己造噪声。这里只放**真实存在的信息** —— 模型给的 summary。
+ *
+ * 连 summary 都没有时返回空串。**这一层不替编译侧做丢弃决定**：它照样把候选交出去，
+ * 由 `runtime.compileSource` 按「正文是不是真的空」统一裁决（那是唯一保留的拒绝）。
+ * 在这里悄悄丢掉一条候选，会让「为什么这份文档一张卡都没抽出来」变成一个查不到答案的问题。
+ */
+export function skeletonBody(def: WikiTypeDef, summary: string): string {
+  const first = def.sections[0]?.label ?? '定义'
+  return summary ? `## ${first}\n\n${summary}` : ''
+}
+
+/**
+ * 用模型抽取实体，并把它们判归到「新建」或「追加到已有卡片」两条路上。
+ *
+ * 失败一律降级而不抛出：模型不可用时返回空结果 + 一条 warning，让上层继续跑规则抽取。
+ * 「因为模型挂了所以整次编译失败」是不能接受的 —— 那条链路本来就不依赖模型。
+ */
+/**
+ * 模型实际回了什么 —— 只留开头一小段，把 warning 变成可排查的东西。
+ *
+ * 「模型输出不是 JSON 对象」这句话本身没有下一步：是模型在讲道理、是被截断，
+ * 还是接缝根本没取到文字？三种情况的处理完全不同，而在实机上它们长得一模一样。
+ * 贴上开头 160 字符，第一次就能分辨。
+ */
+function outputPreview(raw: string): string {
+  const flat = raw.replace(/\s+/g, ' ').trim()
+  if (flat.length === 0) return '（模型回了空字符串）'
+  return flat.length > 160 ? `${flat.slice(0, 160)}…` : flat
+}
+
+export async function extractWithModel(input: ModelExtractionInput): Promise<ModelExtractionResult> {
+  const { source, wikiTypes, existing, call, sessionId } = input
+  const warnings: string[] = []
+  const enabled = wikiTypes.filter(def => def.enabled)
+  if (enabled.length === 0) {
+    return { fresh: [], merges: [], warnings: ['没有任何已启用的 wiki 类型，模型抽取已跳过（先在设置里登记一个类型）'] }
+  }
 
   let raw: string
   try {
-    raw = await call({ system: SYSTEM, prompt })
+    raw = await call({
+      system: SYSTEM,
+      prompt: buildExtractionPrompt({ source, wikiTypes: enabled, existing }),
+      ...(sessionId ? { sessionId } : {}),
+    })
   } catch (cause) {
     warnings.push(`模型抽取不可用：${cause instanceof Error ? cause.message : String(cause)}`)
     return { fresh: [], merges: [], warnings }
   }
 
+  const parsed = parseJsonObject(raw)
+  if (parsed === null || typeof parsed !== 'object') {
+    warnings.push(`模型输出不是 JSON 对象，本次抽取按空处理。模型实际回了：${outputPreview(raw)}`)
+    return { fresh: [], merges: [], warnings }
+  }
+  const list = (parsed as { entities?: unknown }).entities
+  if (!Array.isArray(list)) {
+    warnings.push('模型输出里没有 entities 数组，本次抽取按空处理')
+    return { fresh: [], merges: [], warnings }
+  }
+
   const byId = new Map(existing.map(card => [`${card.entityType}:${card.entityId}`, card]))
   const byEntityId = new Map(existing.map(card => [card.entityId, card]))
   const fresh: ExtractionCandidate[] = []
   const merges: ModelMerge[] = []
   const claimed = new Set<string>()
 
-  for (const entity of readEntities(parseJsonObject(raw), allowedTypes, warnings)) {
-    const name = String(entity.name)
-    const type = String(entity.type) as SchemaType
-    const body = String(entity.body).slice(0, BODY_LIMIT)
-    const wantedId = typeof entity.existing_id === 'string' ? entity.existing_id.trim() : ''
+  for (const entity of list) {
+    const read = readEntity(entity, { enabled, warnings })
+    if (!read) continue
+    const { candidate, existingId } = read
+    candidate.evidence = { sourceId: source.sourceId }
+    const name = candidate.name
+    const type = candidate.type
+    const body = candidate.body ?? ''
     // 模型给的 id 必须真的存在：它指着不存在的卡片时退回新建，绝不能让正文丢在空中。
-    const target = (wantedId ? byEntityId.get(wantedId) : undefined) ?? byId.get(`${type}:${name}`)
+    const target = (existingId ? byEntityId.get(existingId) : undefined) ?? byId.get(`${type}:${name}`)
 
     if (target) {
       const key = `${target.entityType}:${target.entityId}`
       // 同一张卡在一次抽取里被多个候选指向时只并一次，正文在这里先合起来。
       const already = merges.find(entry => entry.key === key)
-      if (already) already.body = `${already.body}\n\n${body}`
-      else merges.push({ key, entityId: target.entityId, entityType: target.entityType, sourceId: source.sourceId, body })
+      if (already) {
+        already.body = `${already.body}\n\n${body}`
+        if (!already.summary && candidate.summary) already.summary = candidate.summary
+        already.fields = { ...(already.fields ?? {}), ...(candidate.fields ?? {}) }
+      } else {
+        merges.push({
+          key, entityId: target.entityId, entityType: target.entityType, sourceId: source.sourceId, body,
+          ...(candidate.summary ? { summary: candidate.summary } : {}),
+          ...(candidate.fields && Object.keys(candidate.fields).length > 0 ? { fields: candidate.fields } : {}),
+        })
+      }
       claimed.add(key)
       continue
     }
@@ -212,15 +375,7 @@ export async function extractWithModel(input: ModelExtractionInput): Promise<Mod
     const key = `${type}:${entityId}`
     if (claimed.has(key)) continue
     claimed.add(key)
-    fresh.push({
-      kind: 'entity',
-      name,
-      type,
-      body,
-      aliases: [],
-      evidence: { sourceId: source.sourceId },
-      confidence: 0.7,
-    })
+    fresh.push(candidate)
   }
 
   return { fresh, merges, warnings }

package/src/extract.ts

@@ -34,6 +34,20 @@ export interface ExtractionCandidate {
   aliases?: string[]
   /** Markdown body that backs this candidate (used as the card body). */
   body?: string
+  /**
+   * 一句话摘要（0044）。模型按 schema 抽取时会给出；规则路径不产它。
+   *
+   * 它有独立价值：正文还没写全时，摘要是这张卡片**唯一能说的那句话** —— 缺信息也入库
+   * 时，卡片至少还有它。
+   */
+  summary?: string
+  /**
+   * 类型定义里的字段值（0044），例如 `metric` 的 `formula` / `owner`。
+   *
+   * 落在卡片 front matter 的 `metadata` 里，不占正文。模型按 schema 抽取时填；
+   * 规则路径不产它，所以缺字段的卡片会在 `schema_issues` 里如实标出来等人补。
+   */
+  fields?: Record<string, string>
   /** For kind === 'relation': the other end. */
   target?: { name: string; type?: SchemaType }
   /** For kind === 'relation': the relation id, e.g. 'relates_to'. */
@@ -320,6 +334,18 @@ function entryBody(entry: unknown): string | undefined {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined
 }
 
+/**
+ * 声明的摘要（0044）。
+ *
+ * 有了它，一条「只知道叫什么、还写不全」的声明式候选也能落成卡片：正文由摘要撑成
+ * 一个带必填小节骨架的最小正文（`runtime.compileSource` 的 `skeletonBody`）。
+ * 没有它，声明式候选只能靠正文自重 —— 而那正是「缺信息就不入库」的老毛病。
+ */
+function entrySummary(entry: unknown): string | undefined {
+  const value = plainRecord(entry).summary
+  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
@@ -372,11 +398,13 @@ export function extractCandidates(source: SourceRaw, wikiTypes: WikiTypeDef[]):
     const aliases = stringList(plainRecord(entry).aliases)
     const heading = entryHeading(entry) ?? sectionForName(sections, name)?.heading
     const body = entryBody(entry) ?? sectionForName(sections, name)?.markdown
+    const summary = entrySummary(entry)
     declaredEntities.push({
       kind: kind === 'entity' ? 'entity' : kindFor(type), name, type,
       evidence: evidence(heading, entryQuote(entry)),
       ...(aliases.length > 0 ? { aliases } : {}),
       ...(body ? { body } : {}),
+      ...(summary ? { summary } : {}),
       confidence: entryConfidence(entry, 0.95),
     })
   }
@@ -526,7 +554,7 @@ export interface NormalizedCandidates {
    * 除了「记一笔来源」什么也做不了 —— 新写进来源里的内容会**静默消失**，卡片永远
    * 停在第一次抽取时的样子（落点是 `runtime.ts` 的 `appendExtracted`）。
    */
-  merges: Array<{ key: string; entityId: string; entityType: SchemaType; sourceId: string; body: string }>
+  merges: Array<{ key: string; entityId: string; entityType: SchemaType; sourceId: string; body: string; summary?: string; fields?: Record<string, string> }>
   /**
    * Relation candidates are never merged — they become graph edges.
    *
@@ -606,7 +634,11 @@ export function normalizeCandidates(candidates: ExtractionCandidate[], index: Ma
     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 ?? '' })
+      merges.push({
+        key, entityId: existing.entityId, entityType: existing.entityType, sourceId: candidate.evidence.sourceId, body: candidate.body ?? '',
+        ...(candidate.summary ? { summary: candidate.summary } : {}),
+        ...(candidate.fields && Object.keys(candidate.fields).length > 0 ? { fields: candidate.fields } : {}),
+      })
       continue
     }
     fresh.push(candidate)
@@ -617,7 +649,7 @@ export function normalizeCandidates(candidates: ExtractionCandidate[], index: Ma
       status: 'unreviewed',
       content: candidate.body ?? '',
       sourceRefs: [candidate.evidence.sourceId],
-      metadata: {},
+      metadata: { ...(candidate.fields ?? {}) },
       updatedAt: '',
     }
     freshKeys.add(key)

package/src/fs-atomic.ts

@@ -4,10 +4,9 @@ import { dirname } from 'node:path'
 /**
  * 原子写：先写同目录的临时文件，再 `rename` 覆盖目标。
  *
- * 抽成独立模块的理由是**它有两个消费者**：宿主运行时（SourceRaw / 卡片 / 编译产物）
- * 与提议存储（`proposals.ts`）。提议是「关于 Agent 动作的待办留痕」，不属于知识树，
- * 所以它不能反过来依赖 runtime —— 那会把分层倒过来（`diagnosis/` 与 `proposals.ts`
- * 都是被 runtime 消费的领域模块）。
+ * 抽成独立模块的理由是**宿主运行时与领域模块都要用它**：SourceRaw / 卡片 / 编译产物
+ * 由 runtime 写，一次排查的样本与迁移由 `diagnosis/` 写。把它放在 runtime 里会让
+ * `diagnosis/` 反过来依赖 runtime 的实现细节 —— 分层就倒过来了。
  */
 
 export async function writeTextAtomic(path: string, content: string): Promise<void> {