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

package/src/runtime.ts

@@ -17,22 +17,39 @@ import {
   type WikiSchemaMode, type WikiTypeCatalog, type WikiTypeDef,
 } from './types.js'
 import { defaultWikiTypes, validateCardAgainstType, WIKI_TYPE_RULES } from './wiki-types.js'
+import { LEGACY_ENTITY_TYPES } from './diagnosis/schema.js'
+import { CardProposalStore } from './proposals.js'
+import { DiagnosisStore } from './diagnosis/store.js'
 import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandidates, RELATES_TO, type NormalizedCandidates } from './extract.js'
 import { extractWithModel, type ModelCall } from './extract-model.js'
 import { FTS_FILE, FtsIndex, loadSqlite, segment } from './fts.js'
 import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, rrfFuse, selectContext, tokenSet, type RouteRanking } from './recall-rank.js'
 import { legacyKnowledgeRoot } from './layout.js'
+import { unlinkIfExists, writeBufferAtomic, writeTextAtomic } from './fs-atomic.js'
 import { envelopeFailure, envelopeSuccess } from 'dsh-data-contracts/envelope'
 import type { LineageContext, LineageRef } from 'dsh-data-contracts/refs'
 
-// 05_diagnosis 是派生层（智能归因图谱）：内容可由 02_wiki + 03_compiled 重建，
-// 和 03_compiled 同性质，所以给独立编号段而不是塞进源头目录。
+// **知识树只有三段**（v1.1 起）：`01_source_truth` / `02_wiki` / `03_compiled`。
 //
-// `00_schema` 在 0030 被撤掉了：它从建出来那天起就是一个**空目录**。分类注册表
-// 与 Wiki 类型注册表一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是
-// 配置，跟着根路径走，见 `knowledge-bases.ts`），而这个段里没有一行代码写过东西。
-// 「磁盘上有一个文件夹」本身是一种承诺，承诺了却空着就是误导。
-const LAYOUT = ['01_source_truth', '02_wiki', '03_compiled', '05_diagnosis'] as const
+// 撤掉的两段，理由都写在这里，避免下一个人重新加回来：
+//
+// - `00_schema`（0030 撤）：它从建出来那天起就是一个**空目录**。分类注册表与 Wiki 类型
+//   注册表一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是**配置**，跟着根路径
+//   走，见 `knowledge-bases.ts`），而这个段里没有一行代码写过东西。「磁盘上有一个文件夹」
+//   本身是一种承诺，承诺了却空着就是误导。**一句话：schema 在设置里编辑，不在磁盘上。**
+// - `05_diagnosis`（v1.1 撤）：它同时装着两类东西 —— 「一次排查的产物」（源头）与
+//   「五类模板卡」（配置）—— 一个编号段混装两种性质，`rebuild --only` 的语义立刻含糊。
+//   现在：一次排查的产物是一条 `agent_diagnosis_case` 的 SourceRaw（落 `01_source_truth/`），
+//   模板卡由类型定义派生（不落盘）。旧目录里的 `*.jsonl` 降为**只读的迁移输入与历史快照**。
+const LAYOUT = ['01_source_truth', '02_wiki', '03_compiled'] as const
+/**
+ * 卡片正文里那个机器可读块的围栏标记。
+ *
+ * 与 `diagnosis/cards.ts` 的 `BLOCK_FENCE` 是同一个字符串，但这里不能 import 它 ——
+ * 迁移要在**不解析卡片**的前提下改块里的一个字段名（旧块的 `failure_mode`），
+ * 而 `cards.ts` 的 `parseCard` 已经把旧字段名归一化了，读回来的对象里根本没有它。
+ */
+const DIAGNOSIS_BLOCK_FENCE = 'json diagnosis'
 /**
  * SourceRaw 段。段内**按来源分类再分一层**：`<段>/<source_type>/<docSlug>.md`。
  *
@@ -68,6 +85,16 @@ const VECTOR_QUANTIZATION = 'binary+hamming+int8' as const
 const ENCODER_FINGERPRINT = 'wemm-official-processor-v1'
 /** Stage 2 output consumed by stage 3 recall. */
 const WIKI_NOTES = 'wiki_notes.json'
+/**
+ * 归因图谱的编译产物（0021 §14.3）。
+ *
+ * 在这之前 `cardsToGraph()` 是**读的时候现算**的，归因图不落 `03_compiled` —— 于是
+ * `build-manifest.json` 不知道它存在（回答不了「这张图是哪个版本编出来的」），
+ * 而图召回也读不到它。现在它和 `knowledge_graph.json` 一起由同一次 `rebuild` 产出，
+ * **但保留两种粒度**：卡片级回答「知识长什么样」，字段级回答「这条路怎么走」。
+ * 合成一张会让图谱 Tab 看到一张卡片散成七个点（§14.4 的三条理由）。
+ */
+const DIAGNOSIS_GRAPH = 'diagnosis_graph.json'
 /** Pre-0014 artifact name; kept readable so an upgrade does not force a rebuild. */
 const LEGACY_UNITS = 'knowledge_units.json'
 /**
@@ -114,6 +141,20 @@ const NOTE_SPLIT_MIN_CHARS = 800
 const RELATION_QUERY_WORDS: Record<string, string> = {
   supported_by: 'supported by source 来源 出处 依据 支撑',
   [RELATES_TO]: 'relates to related 相关 关联 关系 有关',
+  // 归因图谱的十种边（0021 §4.2）。它们住在 `diagnosis_graph.json` 里，
+  // 但**按关系词命中**这条读法是同一套：中文提问不会写 `may_be_caused_by`。
+  // 少了这十行，图召回对 `refutes` / `verified_by` 这些语义完全不可见 ——
+  // 而「上次这条假设是被什么否定的」正是最该被召回到的东西。
+  may_be_caused_by: 'may be caused by 可能是原因 可能原因 候选原因 怀疑',
+  verified_by: 'verified by 由…验证 怎么验证 用哪个检查 检查点',
+  categorized_as: 'categorized as 归类为 属于哪一类 失败原因 切面',
+  queries: 'queries 查询依据 要去查 查哪些表 影响面',
+  produces: 'produces 产出 产出了什么 跑出了什么',
+  supports: 'supports 支持 印证 算数',
+  refutes: 'refutes 否定 排除 不成立 反例',
+  confirmed_as: 'confirmed as 确认为根因 确认根因 定位到',
+  instance_of: 'instance of 实例属于 哪次排查 案例',
+  indexed_from: 'indexed from 反查索引 落在哪个对象上 相关资产',
 }
 /**
  * 融合与阈值的常数（0031）。
@@ -207,8 +248,16 @@ interface ExtractionOutcome {
   extractionHashes: Record<string, string>
   candidatesExtracted: number
   candidatesRejected: number
-  cardsCreated: number
-  cardsMerged: number
+  /**
+   * 这一轮**新提**的卡片提议条数。
+   *
+   * 名字从 `cardsCreated` 改过来（v1.5）：Pass 0 不再直接落卡了 —— 它只提议，
+   * 由人在「知识库 → Wiki」的待办区确认之后才走 `writeCard`（0021 §6.1）。
+   * 计数不改名的话，报告会持续说「新建了 N 张卡片」，而磁盘上一张都没有。
+   */
+  proposalsCreated: number
+  /** 这一轮**更新**已有卡片内容的提议条数（原来叫 `cardsMerged`）。 */
+  proposalsMerged: number
   sourcesExtracted: number
   sourcesSkipped: number
   relations: Array<{ fromKey: string; toKey: string; relation: string; sourceId: string }>
@@ -252,6 +301,69 @@ function contentHashOf(content: string): string { return hash(content) }
  * 已经在正文里出现过的那一段不再追加：同一份来源重建、或同一段被两个候选命中时，
  * 卡片不该越编译越长。判重按整段文本，所以它是幂等的。
  */
+/**
+ * Pass 0 收集到的一条待落提议。
+ *
+ * 它存在的原因是**整轮结束才 upsert**：一份来源里同一个实体可能被抽到两次，
+ * 两份来源也可能抽到同一个实体 —— 逐次写会得到 N 条互相打架的提议，
+ * 而人 review 的时候只想知道「这张卡片该不该建、正文是什么」。
+ */
+interface PendingProposal {
+  action: 'create' | 'update'
+  entityType: SchemaType
+  entityId: string
+  title: string
+  content: string
+  sourceRefs: string[]
+  metadata?: Record<string, unknown>
+  /** `update` 时目标卡片当时的正文指纹 —— 提议之后卡片又被人改过时能发现。 */
+  baseHash?: string
+}
+
+/** 候选的别名集合：判重认的是名字，不是卡片 id（中文名会退化成哈希 id）。 */
+function aliasesOf(candidate: { name: string; aliases?: string[] }): string[] {
+  return [...new Set([candidate.name, ...(candidate.aliases ?? [])].map(value => value.trim()).filter(Boolean))]
+}
+
+/**
+ * 把一次「并入已有卡片」累积进 `pending`。
+ *
+ * 已有卡片只读，所以累积的是**提议的正文**：`appendExtracted` 从卡片当时的正文出发，
+ * 把这一轮所有命中的正文依次追加进去。同一条提议被追加两次正文时不会重复
+ * （`appendExtracted` 自带 `includes` 判重）。
+ */
+function mergeProposal(
+  pending: Map<string, PendingProposal>,
+  card: KnowledgeCard,
+  sourceId: string,
+  bodies: string[],
+  keys: string[],
+): void {
+  const key = `${card.entityType}:${card.entityId}`
+  const previous = pending.get(key)
+  const history = Array.isArray(card.metadata.extraction_merges) ? card.metadata.extraction_merges : []
+  // 只留最近 20 条：这是「这张卡被哪些来源判重命中过」的可见痕迹，不是审计日志。
+  const extraction_merges = [...history, { sourceId, keys, at: new Date().toISOString() }].slice(-20)
+  if (previous) {
+    previous.content = appendExtracted(previous.content, bodies)
+    if (!previous.sourceRefs.includes(sourceId)) previous.sourceRefs.push(sourceId)
+    previous.metadata = { ...previous.metadata, extraction_merges }
+    return
+  }
+  pending.set(key, {
+    action: 'update',
+    entityType: card.entityType,
+    entityId: card.entityId,
+    title: card.title,
+    // **追加**而不是覆盖，也不是丢弃：实体已存在时，这次新抽到的正文并进原卡片，
+    // 于是知识是累积的，来源改写了也不会停在旧版本上。
+    content: appendExtracted(card.content, bodies),
+    sourceRefs: [...card.sourceRefs, sourceId],
+    metadata: { ...card.metadata, extraction_merges },
+    baseHash: contentHashOf(card.content),
+  })
+}
+
 function appendExtracted(existing: string, additions: string[]): string {
   let content = existing
   for (const addition of additions) {
@@ -304,10 +416,22 @@ function emptyDocumentDetail(docId: string): KnowledgeDocumentDetail {
   return {
     docId, title: docId, sourceType: '', sourceTypeKnown: false, sourceFormat: '', parser: '', externalId: '', contentHash: '',
     bytes: 0, assetCount: 0, createdAt: '', updatedAt: '', versionCount: 0,
-    relativePath: '', ext: '', content: '', frontmatter: {}, assets: [],
+    relativePath: '', ext: '', content: '', contentChars: 0, contentTruncated: false, frontmatter: {}, assets: [],
   }
 }
 
+/**
+ * 抽屉里的原文预览**只发**正文的前这么多字符。
+ *
+ * 依据是实跑反馈：一份几十万字的转换文档，抽屉只渲染前 4000 字符（更长的在
+ * 380px 宽的抽屉里没有阅读意义），而接口原来把**整份正文**发过去 —— 传输、JSON 解析、
+ * 塞进 React state 全按全文的量级付费，于是「打开弹层要等半天」。上面那段封顶之后，
+ * 弹层的耗时与文档大小**脱钩**；要读全文走独立整页（分页取，见 `documentContentPage`）。
+ *
+ * 4000 是用户明确要的阈值，所以它是一个具名常量而不是散在各处的字面量。
+ */
+export const SOURCE_PREVIEW_CHARS = 4000
+
 function generatedId(prefix: string): string { return `${prefix}_${hash(`${Date.now()}:${Math.random()}`)}` }
 
 function parseLineage(value: unknown): LineageContext | undefined {
@@ -362,42 +486,24 @@ export function parseMarkdown(source: string): { frontmatter: Record<string, unk
   return { frontmatter, content: source.slice(end + 4).trim() }
 }
 
+/**
+ * 把旧卡片结构化块里的 `failure_mode` 改成 `failure_reason`（0040 的第二次改名）。
+ *
+ * 只动那个围栏块里的键名，不动正文 —— 正文里出现「failure_mode」这个词完全可能是
+ * 有意写的（比如一张讲 FMEA 的卡片）。做字符串级替换而不是解析再序列化，是因为
+ * 解析会**丢掉格式**（缩进、键序），而迁移的第一条纪律是不制造无谓的 diff。
+ */
+function rewriteLegacyBlockFields(content: string): string {
+  const pattern = new RegExp('(```' + DIAGNOSIS_BLOCK_FENCE + '\\s*\\n)([\\s\\S]*?)(```)')
+  return content.replace(pattern, (_all, head: string, body: string, tail: string) =>
+    head + body.replace(/"failure_mode"(\s*:)/g, '"failure_reason"$1') + tail)
+}
+
 function markdown(frontmatter: Record<string, unknown>, content: string): string {
   const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`)
   return `---\n${lines.join('\n')}\n---\n\n${content.trim()}\n`
 }
 
-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)
-  }
-}
-
-async function writeBufferAtomic(path: string, content: Buffer): Promise<void> {
-  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
-  try {
-    await writeFile(temporary, content)
-    await rename(temporary, path)
-  } finally {
-    await unlinkIfExists(temporary)
-  }
-}
-
-async function unlinkIfExists(path: string): Promise<void> {
-  try {
-    const { unlink } = await import('node:fs/promises')
-    await unlink(path)
-  } catch { /* rename already consumed the temp file */ }
-}
-
 async function filesUnder(root: string): Promise<string[]> {
   try {
     const entries = await readdir(root, { withFileTypes: true })
@@ -722,6 +828,12 @@ export class KnowledgeRuntime {
   private sourceIndex: Map<string, string> | undefined
   /** 段内布局整理是否已经跑过（每个 runtime 一次）。 */
   private segmentsOrganized = false
+  /**
+   * 一次性迁移里**没有静默处理掉**的事（改名冲突、迁移后比对不一致）。
+   *
+   * 它必须能被界面读到：迁移失败而没人知道，等价于数据已经丢了。
+   */
+  private migrationProblems: string[] = []
   private vectorIndex: LoadedVectorIndex | null = null
   private vectorError: string | undefined
   private embeddingWorker: JsonLineWorker | null = null
@@ -828,18 +940,188 @@ export class KnowledgeRuntime {
 
   /**
    * Agent 与设置面板共用的类型目录：注册表 + 生效方式 + 内置只读判定规则 +
-   * 现有卡片的三层校验结果（`report` 模式下这是"待补"清单）。
+   * 现有卡片的三层校验结果（`report` 模式下这是"待补"清单）+ **待审提议的条数**。
+   *
+   * 提议计数挂在这里而不是另开一路，是因为 review 就发生在这一屏（「知识库 → Wiki」的
+   * 待办区）—— 与 Pass 0 的候选草案、lint 待补清单是同一处，不新造第二套 review 界面。
    */
   async wikiTypeCatalog(): Promise<Envelope<WikiTypeCatalog>> {
     const schema = this.wikiSchema()
     const issues = await this.lintCards()
+    const all = await this.cardProposals().list()
     return success({
       types: schema.types,
       mode: schema.mode,
       rules: WIKI_TYPE_RULES,
       issues: issues.slice(0, 50),
       issueCount: issues.length,
+      proposals: {
+        pending: all.filter(item => item.status === 'pending').length,
+        rejected: all.filter(item => item.status === 'rejected').length,
+        confirmed: all.filter(item => item.status === 'confirmed' && !item.writtenAt).length,
+      },
+    })
+  }
+
+  /**
+   * 智能归因图谱的存储句柄。
+   *
+   * 它由 runtime 自己构造（而不是由 index.ts 注入），因为 `rebuild` 要产出
+   * `03_compiled/diagnosis_graph.json` —— 那次产出必须和 `knowledge_graph.json`
+   * 在同一次卡片遍历的语义下发生，否则两份产物会来自两个不同版本的卡片。
+   */
+  private diagnosis?: DiagnosisStore
+
+  diagnosisStore(): DiagnosisStore {
+    if (!this.diagnosis) this.diagnosis = new DiagnosisStore(this, this.cardProposals())
+    return this.diagnosis
+  }
+
+  /**
+   * 卡片提议的存储（0021 §6.1 的那道门）。
+   *
+   * 它按**记忆段**（`<agentRoot>/memory/<库 id>`）落，不在知识树里 —— 理由写在
+   * `proposals.ts` 顶上：提议是「关于 Agent 动作的待办留痕」，删掉只丢待办、
+   * 重跑一次提议就能回来，所以它既不属于「源头」（删了就丢数据的那一段），
+   * 更不能落 `02_wiki/`（那正是这道门要拦的事）。
+   */
+  private proposalStore?: CardProposalStore
+
+  cardProposals(): CardProposalStore {
+    if (!this.proposalStore) {
+      this.proposalStore = new CardProposalStore({
+        memoryRoot: this.memoryDir,
+        schema: () => ({ types: this.wikiSchema().types }),
+      })
+    }
+    return this.proposalStore
+  }
+
+  /* ────────────────────────────────────── 卡片提议：提议 → 确认 ── */
+
+  /**
+   * 提一批卡片提议。**它不写任何卡片**（0021 §6.1）。
+   *
+   * 这是 Agent 唯一能碰类型层的入口：把草案挂到触发它的那条 SourceRaw 上，
+   * 由人在面板上确认之后才落卡。未确认的提议不落 `02_wiki/`、不进编译、
+   * 不参与召回、不在图上出现。
+   */
+  async proposeCards(input: {
+    sourceId: string
+    proposals: Array<{
+      action?: 'create' | 'update' | 'merge'
+      entityType: string
+      entityId: string
+      title: string
+      summary?: string
+      content: string
+      sourceRefs?: string[]
+      metadata?: Record<string, unknown>
+    }>
+  }): Promise<Envelope<{ proposed: number; ids: string[]; rejected: string[] }>> {
+    const empty = { proposed: 0, ids: [] as string[], rejected: [] as string[] }
+    if (!input.sourceId?.trim()) return failure(empty, 'SOURCE_REF_REQUIRED', '提议必须挂在一条触发它的 SourceRaw 上', false, '先调 add_source 落一条来源，再用它的 source_id 提提议。')
+    const sources = new Set((await this.loadSources()).map(source => source.sourceId))
+    if (!sources.has(input.sourceId)) {
+      return failure(empty, 'SOURCE_REF_NOT_FOUND', `source_refs 引用不存在: ${input.sourceId}`, false, '先调用 add_source 写入对应的 SourceTruth')
+    }
+    if (!Array.isArray(input.proposals) || input.proposals.length === 0) {
+      return failure(empty, 'PROPOSAL_EMPTY', '至少要提一条提议', true)
+    }
+    const schema = this.wikiSchema()
+    const rejected: string[] = []
+    const accepted = input.proposals.filter(item => {
+      const type = schema.types.find(def => def.id === item.entityType)
+      if (!type) { rejected.push(`${item.entityId}：未知卡片类型 ${item.entityType}`); return false }
+      if (!type.enabled) { rejected.push(`${item.entityId}：类型 ${item.entityType} 已停用`); return false }
+      if (!SAFE_ID.test(item.entityId)) { rejected.push(`${item.entityId}：entity_id 形状不合法`); return false }
+      if (!item.title?.trim() || !item.content?.trim()) { rejected.push(`${item.entityId}：title 与 content 都不能为空`); return false }
+      return true
+    })
+    const touched = await this.cardProposals().upsert(accepted.map(item => ({
+      sourceRef: input.sourceId,
+      trigger: 'agent' as const,
+      action: item.action ?? 'create',
+      entityType: item.entityType,
+      entityId: item.entityId,
+      title: item.title.trim(),
+      ...(item.summary ? { summary: item.summary } : {}),
+      content: item.content,
+      sourceRefs: item.sourceRefs ?? [input.sourceId],
+      ...(item.metadata ? { metadata: item.metadata } : {}),
+    })))
+    return success(
+      { proposed: touched.length, ids: touched.map(item => item.id), rejected },
+      rejected.length > 0 ? [`${rejected.length} 条提议被拒：${rejected.join('；')}`] : [],
+    )
+  }
+
+  /**
+   * 把一条**已确认**的提议落成卡片。
+   *
+   * 三道检查，缺一条这道门就有缝：
+   * 1. 提议存在，且状态是 `confirmed`（人点过「通过」）；
+   * 2. **还没落过卡**（`writtenAt` 为空）—— 确认凭证是**一次性**的；
+   * 3. 再跑一遍三层校验（0021 §6.5）：提议阶段那一遍是 Agent 自己补的，
+   *    这一遍的修改可能来自人，两道都跑才拦得住「改完又破了约束」。
+   */
+  async applyProposal(proposalId: string, lineage?: LineageContext): Promise<Envelope<{ entityId: string; path: string; proposalId: string }>> {
+    const store = this.cardProposals()
+    const empty = { entityId: '', path: '', proposalId }
+    const proposal = await store.get(proposalId)
+    if (!proposal) return failure(empty, 'CARD_PROPOSAL_NOT_FOUND', `提议不存在: ${proposalId}`, true)
+    if (proposal.status === 'pending') {
+      return failure(empty, 'CARD_PROPOSAL_NOT_CONFIRMED', `提议尚未经人确认: ${proposalId}`, false, '未确认的提议不落卡片 —— 这正是这道门的意义。请在「知识库 → Wiki」的待办区确认它。')
+    }
+    if (proposal.status === 'rejected') {
+      return failure(empty, 'CARD_PROPOSAL_REJECTED', `提议已被拒绝: ${proposalId}`, false, proposal.reason ? `拒绝原因：${proposal.reason}` : '被拒绝的提议不会再落卡；内容变了才会重新提。')
+    }
+    if (proposal.writtenAt) {
+      return failure(empty, 'CARD_PROPOSAL_ALREADY_WRITTEN', `提议已经落过卡: ${proposalId}`, false, '确认凭证是一次性的；要改卡片请直接改卡片，或重新提一条提议。')
+    }
+    const written = await this.writeCard({
+      entityType: proposal.entityType as SchemaType,
+      entityId: proposal.entityId,
+      title: proposal.title,
+      content: proposal.content,
+      sourceRefs: proposal.sourceRefs,
+      ...(proposal.summary ? { summary: proposal.summary } : {}),
+      ...(proposal.metadata ? { metadata: proposal.metadata } : {}),
+      ...(lineage ? { lineage } : {}),
     })
+    if (written.ok === false) return failure(empty, written.error.code, written.error.message, written.error.retryable, written.error.suggestion)
+    await store.markWritten(proposalId)
+    return success({ entityId: proposal.entityId, path: written.data.path, proposalId })
+  }
+
+  /**
+   * 人的 review 动作（面板调用，**不是工具**）。
+   *
+   * Agent 拿不到这个入口 —— 它只能 `proposeCards` 与 `applyProposal`，而后者要求
+   * 一条已经被人确认过的提议。确认权收在人手里，这是 §6.1 那条硬规则的结构保证。
+   */
+  async reviewProposal(input: {
+    proposalId: string
+    action: 'confirm-and-write' | 'confirm' | 'reject'
+    reviewer?: string
+    reason?: string
+    patch?: { title?: string; summary?: string; content?: string }
+    lineage?: LineageContext
+  }): Promise<Envelope<{ proposalId: string; status: string; written: boolean }>> {
+    const store = this.cardProposals()
+    const reviewer = input.reviewer?.trim() || 'user:panel'
+    const empty = { proposalId: input.proposalId, status: '', written: false }
+    if (input.action === 'reject') {
+      const rejected = await store.reject(input.proposalId, input.reason ?? '', reviewer)
+      if (!rejected) return failure(empty, 'CARD_PROPOSAL_NOT_FOUND', `提议不存在或已不在待审状态: ${input.proposalId}`, true)
+      return success({ proposalId: rejected.id, status: rejected.status, written: false })
+    }
+    const confirmed = await store.confirm(input.proposalId, reviewer, input.patch)
+    if (!confirmed) return failure(empty, 'CARD_PROPOSAL_NOT_FOUND', `提议不存在或已不在待审状态: ${input.proposalId}`, true)
+    if (input.action === 'confirm') return success({ proposalId: confirmed.id, status: confirmed.status, written: false })
+    const applied = await this.applyProposal(confirmed.id, input.lineage)
+    if (applied.ok === false) return failure(empty, applied.error.code, applied.error.message, applied.error.retryable, applied.error.suggestion)
+    return success({ proposalId: confirmed.id, status: 'confirmed', written: true })
   }
 
   /** 对已落库的卡片跑三层校验。不写盘，只报告。 */
@@ -944,7 +1226,9 @@ export class KnowledgeRuntime {
     if (!this.segmentsOrganized) {
       this.segmentsOrganized = true
       await this.migrateSourceTruthLayout()
-      await this.dropLegacySchemaSegment()
+      await this.dropRetiredSegments()
+      await this.migrateLegacySourceTypeRename()
+      await this.migrateLegacyDiagnosisCards()
     }
   }
 
@@ -985,8 +1269,35 @@ export class KnowledgeRuntime {
    * 有人放了文件，那就不属于「没用的空文件夹」了 —— 那种情况下留着并让人自己判断，
    * 比替他们删掉安全。
    */
-  private async dropLegacySchemaSegment(): Promise<void> {
-    const path = this.safePath('00_schema')
+  /**
+   * 清掉**只装了旧版本自己生成的东西**的退役段。
+   *
+   * `00_schema` 从来没有一行代码写过东西，所以「空」就是它的全部历史形态 —— 空就删。
+   *
+   * `05_diagnosis` 不一样：旧版本在里面铺过 `templates/*.md` 与一份 README，那两样是
+   * 可以重建的（模板由类型定义派生、README 是说明），删掉不丢知识。但同一个目录里
+   * 可能躺着**真正的历史快照**（`*.jsonl` / `cases.json`），那是只读的迁移输入，
+   * 一个字节都不能动。所以判据是**文件清单**而不是「空不空」：只认得旧版本自己写的
+   * 那些名字时，才删；出现任何别的东西就整个留着。
+   */
+  private async dropRetiredSegments(): Promise<void> {
+    await this.dropSegmentIfEmpty('00_schema')
+    const legacy = this.safePath('05_diagnosis')
+    try {
+      const entries = await readdir(legacy, { withFileTypes: true })
+      const owned = entries.every(entry =>
+        entry.isDirectory()
+          ? entry.name === 'templates'
+          : entry.name === 'README.md' || entry.name.endsWith('.jsonl') || entry.name === 'cases.json')
+      if (!owned) return
+      // 有 jsonl / cases.json 就是历史快照，留着（`DiagnosisStore` 还要读它做迁移）。
+      if (entries.some(entry => entry.isFile() && (entry.name.endsWith('.jsonl') || entry.name === 'cases.json'))) return
+      await rm(legacy, { recursive: true, force: true })
+    } catch { /* 不存在或删不掉都不是错误 */ }
+  }
+
+  private async dropSegmentIfEmpty(name: string): Promise<void> {
+    const path = this.safePath(name)
     try {
       const entries = await readdir(path)
       if (entries.length > 0) return
@@ -997,6 +1308,137 @@ export class KnowledgeRuntime {
     } catch { /* 不存在、非空、或删不掉都不是错误 */ }
   }
 
+  /**
+   * 0040 §3.2 的一次性迁移：`01_source_truth/ai_chat_message/` → `agent_chat_message/`。
+   *
+   * 改名不能只改注册表：`01_source_truth/` 是**按分类分目录**的，存量来源的
+   * frontmatter 里写着 `source_type: ai_chat_message`。只改注册表会有两个后果 ——
+   * 旧目录里那些来源变成一个「注册表里没有的分类」（界面上显示成未知分类），
+   * 而旧分类因为还有来源在，永远删不掉。
+   *
+   * 三条纪律：
+   * 1. **逐份搬，不整体 rename 目录。** 目标里可能已经有同名文件（用户在新版本里
+   *    重新录过同一份来源），整体搬会覆盖它。
+   * 2. **同名时比对正文**：一致就删掉旧的那份（同一份东西，只是目录名变了）；
+   *    不一致就**两边都留**，并把冲突报给界面 —— 静默覆盖等于丢数据。
+   * 3. **迁移无损才认**：写完读回来比对 frontmatter 与正文，不一致就放弃这一份。
+   */
+  private async migrateLegacySourceTypeRename(): Promise<void> {
+    const from = this.safePath(SOURCE_TRUTH, 'ai_chat_message')
+    const to = this.safePath(SOURCE_TRUTH, 'agent_chat_message')
+    let names: string[]
+    try { names = await readdir(from) } catch { return }
+    const conflicts: string[] = []
+    for (const name of names) {
+      if (extname(name).toLowerCase() !== '.md') continue
+      const source = join(from, name)
+      let raw: string
+      try { raw = await readFile(source, 'utf8') } catch { continue }
+      const parsed = parseMarkdown(raw)
+      const sourceId = String(parsed.frontmatter.source_id ?? basename(name, '.md'))
+      const target = join(to, name)
+      let existing: string | undefined
+      try { existing = await readFile(target, 'utf8') } catch { /* 目标里还没有 */ }
+      if (existing !== undefined) {
+        const previous = parseMarkdown(existing)
+        if (previous.content.trim() !== parsed.content.trim()) conflicts.push(sourceId)
+        await unlinkIfExists(source)
+        continue
+      }
+      await writeTextAtomic(target, markdown({ ...parsed.frontmatter, source_type: 'agent_chat_message' }, parsed.content))
+      const roundTrip = parseMarkdown(await readFile(target, 'utf8'))
+      if (roundTrip.content.trim() !== parsed.content.trim() || roundTrip.frontmatter.source_type !== 'agent_chat_message') {
+        // 读回来对不上：把目标撤掉，旧的那份留着 —— 宁可迁移没生效，也不要留半份。
+        await unlinkIfExists(target)
+        conflicts.push(`${sourceId}（迁移后比对不一致，已放弃）`)
+        continue
+      }
+      await unlinkIfExists(source)
+    }
+    try { await rmdir(from) } catch { /* 还有别的东西在里面 */ }
+    if (conflicts.length > 0) {
+      this.migrationProblems.push(`来源分类改名迁移有 ${conflicts.length} 处冲突，旧文件保留在 01_source_truth/ai_chat_message/：${conflicts.join('、')}`)
+    }
+  }
+
+  /**
+   * 0040 §4 的一次性迁移：两次改名（`check` → `check_point`、`failure-mode` →
+   * `failure_reason`）的存量卡片。
+   *
+   * 两件事一起做，因为它们是同一次改名的两个面：
+   * 1. **卡片类型**：`02_wiki/diagnosis/check/` → `check-point/`，
+   *    frontmatter 的 `entity_type` 一起改；
+   * 2. **结构化块里的字段名**：`failure_mode` → `failure_reason`。这一条与卡片类型
+   *    无关 —— `diagnosis/hypothesis` 卡片的类型没变，但它块里那个字段变了。
+   *    只按目录过滤的话，假设卡片上的旧字段名会永远留在磁盘上，而读回来是「少一个
+   *    必填字段」，正文里却明明写着它。
+   *
+   * 读取端本来也认别名（`cards.parseCard`），但**只在内存里认是不够的**：`writeCard`
+   * 按 `entity_type` 决定写哪个目录，改一张旧卡片就会在 `check-point/` 下多写一份，
+   * 而旧目录里那份还在 —— 同一张卡片变成两张，读图时看谁先被遍历到。
+   *
+   * 用 `writeCard` 而不是自己拼 frontmatter：它是唯一知道卡片信封长什么样、并且会
+   * 顺手做版本快照与三层校验的地方。
+   */
+  private async migrateLegacyDiagnosisCards(): Promise<void> {
+    const root = this.safePath(WIKI, 'diagnosis')
+    let kinds: string[]
+    try { kinds = await readdir(root) } catch { return }
+    /**
+     * 目录名是 `entity_type` 的**命名空间之后那一段**（`02_wiki/diagnosis/check/` 对应
+     * `diagnosis/check`）。用后缀匹配而不是拿 `entity_type` 直接比目录名 —— 直接比的话
+     * 一个都匹配不上，而失败方式是静默的：迁移什么都没做，卡片仍按旧类型读。
+     */
+    const legacyByDir = new Map<string, string>()
+    for (const [legacy, next] of Object.entries(LEGACY_ENTITY_TYPES)) {
+      legacyByDir.set(legacy.slice(legacy.indexOf('/') + 1), next)
+    }
+    const problems: string[] = []
+    for (const dir of kinds) {
+      const legacyDir = join(root, dir)
+      const renamedType = legacyByDir.get(dir)
+      // 类型没改名、也不在旧目录里的子树也要扫一遍：块字段名的改名与类型无关。
+      for (const file of await filesUnder(legacyDir)) {
+        let raw: string
+        try { raw = await readFile(file, 'utf8') } catch { continue }
+        const parsed = parseMarkdown(raw)
+        const entityId = String(parsed.frontmatter.entity_id ?? basename(file, '.md'))
+        const currentType = String(parsed.frontmatter.entity_type ?? '')
+        const nextType = renamedType ?? LEGACY_ENTITY_TYPES[currentType] ?? currentType
+        if (!nextType) continue
+        const body = rewriteLegacyBlockFields(parsed.content)
+        const typeChanged = nextType !== currentType
+        const bodyChanged = body !== parsed.content
+        // 两样都没变就什么都不做 —— 每次启动都重写一遍所有卡片会把版本历史灌满。
+        if (!typeChanged && !bodyChanged) continue
+        const written = await this.writeCard({
+          entityType: nextType as SchemaType,
+          entityId,
+          title: String(parsed.frontmatter.title ?? entityId),
+          content: body,
+          sourceRefs: Array.isArray(parsed.frontmatter.source_refs) ? parsed.frontmatter.source_refs.map(String) : [],
+          status: (STATUS.includes(String(parsed.frontmatter.status) as KnowledgeStatus) ? String(parsed.frontmatter.status) : 'unreviewed') as KnowledgeStatus,
+          ...(typeof parsed.frontmatter.summary === 'string' && parsed.frontmatter.summary ? { summary: parsed.frontmatter.summary } : {}),
+          ...(typeof parsed.frontmatter.owner === 'string' && parsed.frontmatter.owner ? { owner: parsed.frontmatter.owner } : {}),
+          metadata: typeof parsed.frontmatter.metadata === 'object' && parsed.frontmatter.metadata ? parsed.frontmatter.metadata as Record<string, unknown> : {},
+        })
+        if (written.ok === false) {
+          problems.push(`卡片 ${entityId} 从 ${currentType || dir} 迁到 ${nextType} 失败（${written.error.code}），旧文件保留`)
+          continue
+        }
+        // 读回来确认它真的落在新目录、而且认得出新类型，再删旧的。
+        const readBack = await this.readCard(entityId, nextType as SchemaType)
+        if (!readBack) {
+          problems.push(`卡片 ${entityId} 迁移后读不回来，旧文件保留`)
+          continue
+        }
+        // 正文没变、类型也没变时，`writeCard` 写的是同一个路径 —— 这时**不要**删它。
+        if (written.data.path !== file) await unlinkIfExists(file)
+      }
+      try { await rmdir(legacyDir) } catch { /* 还有别的东西在里面 */ }
+    }
+    if (problems.length > 0) this.migrationProblems.push(...problems)
+  }
   private async loadVectorIndex(): Promise<LoadedVectorIndex | null> {
     if (this.vectorIndex) return this.vectorIndex
     try {
@@ -1228,6 +1670,10 @@ export class KnowledgeRuntime {
       const graph = JSON.parse(await readFile(this.safePath('03_compiled', 'knowledge_graph.json'), 'utf8'))
       if (graph && Array.isArray(graph.nodes) && Array.isArray(graph.edges)) this.graph = graph as typeof this.graph
     } catch { /* the first build has not happened yet */ }
+    try {
+      const diagnosis = JSON.parse(await readFile(this.safePath('03_compiled', DIAGNOSIS_GRAPH), 'utf8'))
+      if (diagnosis && Array.isArray(diagnosis.nodes) && Array.isArray(diagnosis.edges)) this.diagnosisGraph = diagnosis as typeof this.diagnosisGraph
+    } catch { /* 归因图还没编过（这个库没做过排查），或者旧版本没有这个产物 */ }
   }
 
   private safePath(...parts: string[]): string {
@@ -1270,9 +1716,10 @@ export class KnowledgeRuntime {
         only?: string; incremental?: boolean; skipped?: boolean
         cardsReused?: number; cardsRecompiled?: number; cardsAdded?: number; cardsRemoved?: number
         notesReused?: number; notesRecompiled?: number
-        // Pass 0 的计数：面板据此显示「这一轮抽了几个候选、建了几张卡」。
+        // Pass 0 的计数：面板据此显示「这一轮抽了几个候选、提了几条提议」。
+        // v1.5 把 `cardsCreated` / `cardsMerged` 改成提议计数 —— Pass 0 不再落卡。
         candidatesExtracted?: number; candidatesRejected?: number
-        cardsCreated?: number; cardsMerged?: number
+        proposalsCreated?: number; proposalsMerged?: number
         relationsExtracted?: number; relationsDropped?: number
         sourcesExtracted?: number; sourcesSkipped?: number
       }
@@ -1303,6 +1750,12 @@ export class KnowledgeRuntime {
       notes: this.units.length,
       graphNodes: this.graph.nodes.length,
       graphEdges: this.graph.edges.length,
+      /**
+       * 一次性迁移里没有静默处理掉的事（来源分类改名冲突、卡片改名迁移失败）。
+       *
+       * 它必须能被界面读到：迁移失败而没人知道，等价于数据已经丢了。
+       */
+      migrationProblems: this.migrationProblems,
       buildVersion: Number(buildManifest.version ?? 0),
       builtAt: buildManifest.builtAt,
       trackedCards: Object.keys(buildManifest.cardHashes ?? {}).length,
@@ -1483,11 +1936,19 @@ export class KnowledgeRuntime {
     return assets.sort((left, right) => left.rel.localeCompare(right.rel))
   }
 
-  /** Parse one on-disk SourceRaw file into the detail projection. */
-  private async readDocumentFile(path: string): Promise<KnowledgeDocumentDetail | undefined> {
+  /**
+   * Parse one on-disk SourceRaw file into the detail projection.
+   *
+   * `previewChars` 给了就把正文截到那么长，并把**总长度**如实放进 `contentChars`
+   * （见 `SOURCE_PREVIEW_CHARS` 的理由）。不给就是不截断 —— 那是「我确实要全文」的
+   * 调用方，目前只有 `readDocumentBody()` 之外的内部路径会这么用。
+   */
+  private async readDocumentFile(path: string, previewChars?: number): Promise<KnowledgeDocumentDetail | undefined> {
     let raw: string
     try { raw = await readFile(path, 'utf8') } catch { return undefined }
     const parsed = parseMarkdown(raw)
+    const contentChars = parsed.content.length
+    const content = previewChars !== undefined && previewChars < contentChars ? parsed.content.slice(0, previewChars) : parsed.content
     const sourceId = String(parsed.frontmatter.source_id ?? basename(path, '.md'))
     const sourceType = String(parsed.frontmatter.source_type ?? 'document')
     // 未知分类照样投影出来（0013）；前端按 sourceTypeKnown 渲染「未知分类」徽标。
@@ -1523,7 +1984,9 @@ export class KnowledgeRuntime {
       versionCount: (await this.versionIds(sourceId)).length + 1,
       relativePath: relative(this.rootDir, path).split(sep).join('/'),
       ext,
-      content: parsed.content,
+      content,
+      contentChars,
+      contentTruncated: content.length < contentChars,
       frontmatter: parsed.frontmatter,
       assets,
       ...(lineage ? { lineage: lineage as Record<string, string> } : {}),
@@ -1548,9 +2011,27 @@ export class KnowledgeRuntime {
   }
 
   /** 文档详情：正文、frontmatter、资产与 lineage。 */
-  async readDocument(docId: string): Promise<KnowledgeDocumentDetail | undefined> {
+  /**
+   * 一份文档的详情投影，**正文默认按 `SOURCE_PREVIEW_CHARS` 封顶**。
+   *
+   * 这是明细接口（抽屉里的预览）读的那一份，所以默认就是「够预览」而不是「全文」：
+   * 全文由 `readDocumentBody()` 提供服务，而它只服务独立整页的分页读取。
+   */
+  async readDocument(docId: string, previewChars: number = SOURCE_PREVIEW_CHARS): Promise<KnowledgeDocumentDetail | undefined> {
+    const path = await this.sourcePathOf(docId)
+    return path ? this.readDocumentFile(path, previewChars) : undefined
+  }
+
+  /**
+   * 一份文档的**完整正文**（不含 frontmatter），给独立整页分页取用。
+   *
+   * 每次调用都重读一遍盘：独立整页是「用户滚到哪儿取哪一页」，一次请求一段文本，
+   * 谁都不该拿到整份文档 —— 这正是抽屉那一版的问题。缓存留到真的量出来是瓶颈再加。
+   */
+  async readDocumentBody(docId: string): Promise<string | undefined> {
     const path = await this.sourcePathOf(docId)
-    return path ? this.readDocumentFile(path) : undefined
+    if (path === undefined) return undefined
+    try { return parseMarkdown(await readFile(path, 'utf8')).content } catch { return undefined }
   }
 
   /**
@@ -1605,7 +2086,7 @@ export class KnowledgeRuntime {
   async revertDocument(docId: string, versionId: string): Promise<Envelope<KnowledgeDocumentDetail>> {
     const path = await this.sourcePathOf(docId)
     if (path === undefined) return failure(emptyDocumentDetail(docId), 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true)
-    const head = await this.readDocumentFile(path)
+    const head = await this.readDocumentFile(path, SOURCE_PREVIEW_CHARS)
     if (!head) return failure(emptyDocumentDetail(docId), 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true)
     const target = typeof versionId === 'string' ? versionId.trim() : ''
     if (!target) return failure(head, 'VERSION_ID_REQUIRED', 'versionId 不能为空', false, '用 list_versions / GET /knowledge/documents/:docId/versions 先取版本列表。')
@@ -1623,7 +2104,7 @@ export class KnowledgeRuntime {
       lineage: parseLineage(parsed.frontmatter.lineage),
     })
     if (!restored.ok) return failure(head, restored.error?.code ?? 'REVERT_FAILED', restored.error?.message ?? '回滚写入失败', restored.error?.retryable ?? false, restored.error?.suggestion)
-    const document = await this.readDocumentFile(path)
+    const document = await this.readDocumentFile(path, SOURCE_PREVIEW_CHARS)
     if (!document) return failure(head, 'DOCUMENT_NOT_FOUND', `回滚后文档不可读: ${docId}`, true)
     await this.audit('source_truth.revert', { docId, versionId: target })
     return success(document)
@@ -1982,7 +2463,7 @@ export class KnowledgeRuntime {
   private emptyExtractionOutcome(extractionHashes: Record<string, string>): ExtractionOutcome {
     return {
       extractionHashes,
-      candidatesExtracted: 0, candidatesRejected: 0, cardsCreated: 0, cardsMerged: 0,
+      candidatesExtracted: 0, candidatesRejected: 0, proposalsCreated: 0, proposalsMerged: 0,
       sourcesExtracted: 0, sourcesSkipped: 0, relations: [], relationsBySource: {}, warnings: [],
     }
   }
@@ -2009,7 +2490,13 @@ export class KnowledgeRuntime {
     const persisted = await this.readExtractedRelations()
     // 计数器与产物不能由 readdir 的顺序决定，所以先按 sourceId 排序。
     const ordered = [...sources].sort((left, right) => left.sourceId.localeCompare(right.sourceId))
-    let cards = await this.loadCards()
+    /**
+     * 库里的卡片是**只读的参照物**：这一轮不再往里加东西，抽到的一切都进 `pending`。
+     * 整轮结束才一次性 upsert —— 同一张卡片被多份来源命中时只有一条提议，
+     * 正文累积（而不是产生 N 条互相打架的提议）。
+     */
+    const cards = await this.loadCards()
+    const pending = new Map<string, PendingProposal>()
     for (const source of ordered) {
       const fingerprint = this.extractionFingerprint(source, registryHash)
       outcome.extractionHashes[source.sourceId] = fingerprint
@@ -2024,11 +2511,34 @@ export class KnowledgeRuntime {
       }
       outcome.sourcesExtracted += 1
       try {
-        cards = await this.extractFromSource(source, cards, enabledTypes, outcome)
+        await this.proposeFromSource(source, cards, enabledTypes, outcome, pending)
       } catch (cause) {
         outcome.warnings.push(`来源 ${source.sourceId} 的候选抽取失败，已跳过该来源：${cause instanceof Error ? cause.message : String(cause)}`)
       }
     }
+    /**
+     * 落**提议**，不是卡片。
+     *
+     * `upsert` 会按内容指纹判重：人已经拒绝过、而且内容没变的那一条不会再冒出来；
+     * 人已经确认过、而且内容没变的那一条也不会再问一遍。计数取自它真正写下的那些，
+     * 而不是 `pending` 的大小 —— 报告里的数字必须是「这次真的发生了什么」。
+     */
+    if (pending.size > 0) {
+      const touched = await this.cardProposals().upsert([...pending.values()].map(item => ({
+        sourceRef: item.sourceRefs[0] ?? `kb:${item.entityType}`,
+        trigger: 'extraction' as const,
+        action: item.action,
+        entityType: item.entityType,
+        entityId: item.entityId,
+        title: item.title,
+        content: item.content,
+        sourceRefs: item.sourceRefs,
+        ...(item.metadata ? { metadata: item.metadata } : {}),
+        ...(item.baseHash ? { baseHash: item.baseHash } : {}),
+      })))
+      outcome.proposalsCreated = touched.filter(item => item.action === 'create').length
+      outcome.proposalsMerged = touched.filter(item => item.action === 'update').length
+    }
     // 只留这一轮真实存在的来源：删掉的文档不该在图上留下幽灵关系。
     const alive = new Set(ordered.map(source => source.sourceId))
     const next: Record<string, ExtractionOutcome['relations']> = {}
@@ -2070,8 +2580,22 @@ export class KnowledgeRuntime {
     } catch { /* 写不进去就当这一轮没有产物，下一次重建会重新抽 */ }
   }
 
-  /** 一份来源的抽取结果：新建候选卡片、把证据来源并进已有卡片、收集关系候选。 */
-  private async extractFromSource(source: SourceRaw, cards: KnowledgeCard[], enabledTypes: WikiTypeDef[], outcome: ExtractionOutcome): Promise<KnowledgeCard[]> {
+  /**
+   * 一份来源的抽取结果：**产出提议**（新建 / 更新），并收集关系候选。
+   *
+   * 它**不再写卡片**。这是 v1.5 那道门最容易被绕开的地方：Pass 0 是一次自动流程，
+   * 它写进 `02_wiki/` 的东西会立刻参与编译、进图、被召回 —— 而类型层是收敛的那一层，
+   * 它错一条，所有现象的排序一起错。所以这里只往 `pending` 里放提议，
+   * 由 `runExtractionStage` 在整轮结束时一次性 upsert（同一张卡片被多份来源命中时，
+   * 只有一条提议，正文累积）。
+   */
+  private async proposeFromSource(
+    source: SourceRaw,
+    cards: KnowledgeCard[],
+    enabledTypes: WikiTypeDef[],
+    outcome: ExtractionOutcome,
+    pending: Map<string, PendingProposal>,
+  ): Promise<void> {
     /**
      * #3b：**模型先抽实体，规则补关系。**
      *
@@ -2095,30 +2619,36 @@ export class KnowledgeRuntime {
         normalized = { fresh: modelled.fresh, merges: modelled.merges, relations: ruleNormalized.relations }
       }
     }
-    const candidates = normalized.fresh
-    if (candidates.length === 0 && normalized.merges.length === 0) return cards
-    const next = [...cards]
 
-    // 先建后并：同一轮里新建的卡片也可能被别名指回，先建才能让后面的合并找得到对象。
     for (const candidate of normalized.fresh) {
       /**
-       * 候选**必须带正文**才落卡。
+       * 候选**必须带正文**才提提议。
        *
        * 0029 实跑发现：这里原来在候选没有正文时拿 `type.template` 顶上，于是
        * `[[链接]]` 指到、但还没人写过的实体（那时链接候选确实没有正文）会落成一张
        * **正文是模板**的卡片，而模板里的「（必填：写什么）」会被编进 wikiNotes、
        * 被召回、被塞进模型的上下文包 —— 管线写出了一张它自己的校验器判为不合格的
        * 卡片。链接候选现在会带上它所在小节的正文（`extract.ts`），所以这条回退基本
-       * 不会被走到；真走到了就**不落卡**，并如实计数：没有正文 = 没有可说的。
+       * 不会被走到；真走到了就**不提**，并如实计数：没有正文 = 没有可说的。
        */
       const body = candidate.body?.trim() ?? ''
       if (!body) {
         outcome.candidatesRejected += 1
-        outcome.warnings.push(`候选「${candidate.name}」没有任何正文（只在别处被提到，所在小节也没取到），不落卡`)
+        outcome.warnings.push(`候选「${candidate.name}」没有任何正文（只在别处被提到，所在小节也没取到），不提提议`)
+        continue
+      }
+      /**
+       * 类型必须来自注册表。抽到一个没登记的类型时**不提这条提议** —— 提议的正文与
+       * 小节骨架都按类型的 schema 校验，而未知类型没有 schema，人 review 时只能拒掉它。
+       * 与其往待办队列里塞一条注定被拒的东西，不如当场记一笔并说清原因。
+       */
+      if (!enabledTypes.some(def => def.id === candidate.type)) {
+        outcome.candidatesRejected += 1
+        outcome.warnings.push(`候选「${candidate.name}」未提议（SCHEMA_TYPE_INVALID）：类型 ${candidate.type} 未登记或已停用`)
         continue
       }
-      // 重复的写法都进 aliases：判重认的是名字，不是卡片 id（中文名会退化成哈希 id）。
-      const aliases = [...new Set([candidate.name, ...(candidate.aliases ?? [])].map(value => value.trim()).filter(Boolean))]
+      const entityId = candidateEntityId(candidate.name)
+      const key = `${candidate.type}:${entityId}`
       const metadata: Record<string, unknown> = {
         extraction: 'pass0',
         candidate_kind: candidate.kind,
@@ -2127,72 +2657,40 @@ export class KnowledgeRuntime {
           sourceId: candidate.evidence.sourceId,
           ...(candidate.evidence.heading ? { heading: candidate.evidence.heading } : {}),
         },
-        ...(aliases.length > 0 ? { aliases } : {}),
+        // 重复的写法都进 aliases：判重认的是名字，不是卡片 id（中文名会退化成哈希 id）。
+        ...(aliasesOf(candidate).length > 0 ? { aliases: aliasesOf(candidate) } : {}),
       }
-      const written = await this.writeCard({
-        entityType: candidate.type,
-        entityId: candidateEntityId(candidate.name),
-        title: candidate.name,
-        content: body,
-        sourceRefs: [candidate.evidence.sourceId],
-        status: 'unreviewed',
-        metadata,
-      })
-      if (!written.ok) {
-        outcome.candidatesRejected += 1
-        outcome.warnings.push(`候选「${candidate.name}」未写入（${written.error?.code ?? 'UNKNOWN'}）：${written.error?.message ?? ''}`)
+      // 库里已经有这张卡片 → 不是新建，而是「把这次抽到的正文并进去」。
+      const existing = cards.find(card => card.entityId === entityId && card.entityType === candidate.type)
+      if (existing) {
+        mergeProposal(pending, existing, candidate.evidence.sourceId, [body], [candidate.name])
         continue
       }
-      outcome.cardsCreated += 1
-      next.push({
-        entityId: written.data.entityId,
+      const previous = pending.get(key)
+      if (previous) {
+        previous.content = appendExtracted(previous.content, [body])
+        if (!previous.sourceRefs.includes(candidate.evidence.sourceId)) previous.sourceRefs.push(candidate.evidence.sourceId)
+        continue
+      }
+      pending.set(key, {
+        action: 'create',
         entityType: candidate.type,
+        entityId,
         title: candidate.name,
-        status: 'unreviewed',
         content: body,
         sourceRefs: [candidate.evidence.sourceId],
         metadata,
-        updatedAt: '',
       })
     }
 
-    // 归一：命中的候选把证据来源并进已有卡片。同一张卡片在这一轮里的多次命中合并且只写一次。
-    const targets = new Map<string, { card: KnowledgeCard; keys: string[]; sourceId: string; bodies: string[] }>()
+    // 归一：命中的候选把证据来源并进已有卡片。同一张卡片在这一轮里的多次命中合并成一条提议。
     for (const merge of normalized.merges) {
-      const card = next.find(item => item.entityId === merge.entityId && item.entityType === merge.entityType)
+      const card = cards.find(item => item.entityId === merge.entityId && item.entityType === merge.entityType)
       if (!card) continue
-      // 「只在没有的时候追加」：来源已在 source_refs 里就什么都不做 —— 空写也会
-      // 刷新 updated_at，并让「并入了多少张卡」这个计数变成谎话。
+      // 「只在没有的时候追加」：来源已在 source_refs 里就什么都不做 —— 空提一条提议
+      // 也会让「并入了多少张卡」这个计数变成谎话。
       if (card.sourceRefs.includes(merge.sourceId)) continue
-      const id = `${merge.entityType}:${merge.entityId}`
-      const entry = targets.get(id)
-      if (entry) {
-        if (!entry.keys.includes(merge.key)) entry.keys.push(merge.key)
-        entry.bodies.push(merge.body)
-      } else targets.set(id, { card, keys: [merge.key], sourceId: merge.sourceId, bodies: [merge.body] })
-    }
-    for (const { card, keys, sourceId, bodies } of targets.values()) {
-      const history = Array.isArray(card.metadata.extraction_merges) ? card.metadata.extraction_merges : []
-      // 只留最近 20 条：这是「这张卡被哪些来源判重命中过」的可见痕迹，不是审计日志。
-      const extraction_merges = [...history, { sourceId, keys, at: new Date().toISOString() }].slice(-20)
-      // **追加**而不是覆盖，也不是丢弃：实体已存在时，这次新抽到的正文并进原卡片，
-      // 于是知识是累积的，来源改写了也不会停在旧版本上。
-      const content = appendExtracted(card.content, bodies)
-      const written = await this.writeCard({
-        ...card,
-        content,
-        sourceRefs: [...card.sourceRefs, sourceId],
-        metadata: { ...card.metadata, extraction_merges },
-      })
-      if (!written.ok) {
-        outcome.candidatesRejected += 1
-        outcome.warnings.push(`候选并入卡片「${card.entityId}」失败（${written.error?.code ?? 'UNKNOWN'}）：${written.error?.message ?? ''}`)
-        continue
-      }
-      outcome.cardsMerged += 1
-      // 让后面的来源看到已经追加过的正文与 source_refs，避免重复写入。
-      const index = next.findIndex(item => item.entityId === card.entityId && item.entityType === card.entityType)
-      if (index >= 0) next[index] = { ...card, content, sourceRefs: [...card.sourceRefs, sourceId], metadata: { ...card.metadata, extraction_merges } }
+      mergeProposal(pending, card, merge.sourceId, [merge.body], [merge.key])
     }
 
     outcome.relations.push(...normalized.relations)
@@ -2201,7 +2699,6 @@ export class KnowledgeRuntime {
       ...(outcome.relationsBySource[source.sourceId] ?? []),
       ...normalized.relations,
     ]
-    return next
   }
 
   /**
@@ -2240,7 +2737,7 @@ export class KnowledgeRuntime {
     const sourceTypes = new Map(sources.map(source => [source.sourceId, source.sourceType]))
 
     // ------------------------------------------------ previous build state
-    let previousManifest: { version?: number; builtAt?: string; cardHashes?: Record<string, string>; extractionHashes?: Record<string, string>; embedding?: unknown } = {}
+    let previousManifest: { version?: number; builtAt?: string; cardHashes?: Record<string, string>; extractionHashes?: Record<string, string>; embedding?: unknown; diagnosisHash?: string } = {}
     try {
       previousManifest = JSON.parse(await readFile(this.safePath('03_compiled', 'build-manifest.json'), 'utf8')) as typeof previousManifest
     } catch { /* first build */ }
@@ -2260,12 +2757,11 @@ export class KnowledgeRuntime {
       : this.emptyExtractionOutcome(previousExtractionHashes)
     // 抽取刚落过盘：stage 2 必须看到新的卡片清单，否则这一轮建的卡片要等下一次
     // 重建才进 wikiNotes，用户点了编译却召不回刚抽出来的东西。
-    if (extraction.cardsCreated > 0 || extraction.cardsMerged > 0) this.cards = await this.loadCards()
     const extractionCounts = {
       candidatesExtracted: extraction.candidatesExtracted,
       candidatesRejected: extraction.candidatesRejected,
-      cardsCreated: extraction.cardsCreated,
-      cardsMerged: extraction.cardsMerged,
+      proposalsCreated: extraction.proposalsCreated,
+      proposalsMerged: extraction.proposalsMerged,
       sourcesExtracted: extraction.sourcesExtracted,
       sourcesSkipped: extraction.sourcesSkipped,
     }
@@ -2335,7 +2831,19 @@ export class KnowledgeRuntime {
       // bumping the version there would invalidate the vector cache and every
       // qrels pointing at it for nothing. `all` never takes this path (see
       // `incremental` above).
-      const corpusChanged = !incremental || previousVersion === 0 || cardsRecompiled > 0 || cardsRemoved > 0
+      /**
+       * 归因图（字段级）也是这次编译的产物之一，所以它变了也算「语料变了」。
+       *
+       * 少了这一条会踩一个很隐蔽的坑：**记一次排查不改任何卡片**（它写的是一条
+       * `agent_diagnosis_case` 的 SourceRaw），于是增量编译判定「没变化」直接跳过 ——
+       * 而 `03_compiled/diagnosis_graph.json` 停在上一轮，图召回因此看不到这次排查
+       * 新增的 `produces` / `supports` / `refutes` 边。它读的是**编译产物**，
+       * 不是 `02_wiki` 的实时投影（§14.3）。
+       */
+      const diagnosis = await this.diagnosisStore().readGraph()
+      const diagnosisHash = contentHashOf(JSON.stringify({ nodes: diagnosis.nodes, edges: diagnosis.edges }))
+      const diagnosisChanged = diagnosisHash !== previousManifest.diagnosisHash
+      const corpusChanged = !incremental || previousVersion === 0 || cardsRecompiled > 0 || cardsRemoved > 0 || diagnosisChanged
       if (!corpusChanged) {
         const compileRunId = `rebuild_${hash(`${startedAt}:${this.cards.length}`)}`
         const report: RebuildReport = {
@@ -2356,7 +2864,7 @@ export class KnowledgeRuntime {
         // 用户刚点了编译却看到上次的统计，会以为按钮没生效。version 不变，所以
         // 这个写入既不改索引也不让向量缓存失效。extractionHashes 必须跟着更新：
         // 来源变了但没抽出卡片时，不落新指纹会让下一次又把它重抽一遍。
-        await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version: previousVersion, builtAt: previousManifest.builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: previousManifest.embedding, compileRunId, lastBuild: { only, incremental: true, skipped: true, cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0, notesReused, notesRecompiled: 0, ...extractionCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2))
+        await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version: previousVersion, builtAt: previousManifest.builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: previousManifest.embedding, diagnosisHash, compileRunId, lastBuild: { only, incremental: true, skipped: true, cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0, notesReused, notesRecompiled: 0, ...extractionCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2))
         return success(report, ['知识库没有变化：已复用全部 wikiNotes，未生成新的索引版本。', ...extraction.warnings])
       }
 
@@ -2381,6 +2889,14 @@ export class KnowledgeRuntime {
       // Compatibility mirror for tooling that predates wiki_notes.json.
       await writeTextAtomic(this.safePath('03_compiled', LEGACY_UNITS), JSON.stringify(this.units, null, 2))
       await writeTextAtomic(this.safePath('03_compiled', 'knowledge_graph.json'), JSON.stringify(this.graph, null, 2))
+      /**
+       * 字段级的归因图（0021 §14.3）。**同一次编译产出两份投影，各自由它的消费者读**：
+       * `knowledge_graph.json` 是卡片级（图谱 Tab、图召回），这里是字段级
+       * （智能归因三视图）。不合成一张 —— 消费者不同、`supported_by` 只对卡片成立、
+       * 而召回权重的基准不该被顺手改掉（§14.4）。
+       */
+      this.diagnosisGraph = { nodes: diagnosis.nodes as unknown as Array<Record<string, unknown>>, edges: diagnosis.edges as unknown as Array<Record<string, unknown>> }
+      await writeTextAtomic(this.safePath('03_compiled', DIAGNOSIS_GRAPH), JSON.stringify({ version, builtAt, nodes: diagnosis.nodes, edges: diagnosis.edges }, null, 2))
       // 关键词索引跟着 notes 一起落盘（0031）：它的输入就是 notes，两者必须同时有效，
       // 否则会出现「卡片改了、关键词路还按旧词表召回」。它不依赖编码器，所以 wiki-only
       // 重建也要重建它 —— 而向量是 stage 3，仍然只在 `embeddings`/`all` 时重算。
@@ -2390,7 +2906,7 @@ export class KnowledgeRuntime {
       // re-encode of the whole corpus.
       const embeddingResult = only === 'all' ? await this.buildVectorIndex(this.units, version) : { status: 'skipped' as const, count: 0, reused: 0 }
       const compileRunId = `rebuild_${hash(`${startedAt}:${this.cards.length}`)}`
-      await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version, builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: embeddingResult, fts: ftsResult, compileRunId, lastBuild: { only, incremental: cardsReused > 0, skipped: false, cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount, notesReused, notesRecompiled, ...extractionCounts, relationsExtracted, relationsDropped }, ...(lineage ? { lineage } : {}) }, null, 2))
+      await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version, builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: embeddingResult, fts: ftsResult, compileRunId, diagnosisHash, diagnosisGraph: { nodes: diagnosis.nodes.length, edges: diagnosis.edges.length }, lastBuild: { only, incremental: cardsReused > 0, skipped: false, cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount, notesReused, notesRecompiled, ...extractionCounts, relationsExtracted, relationsDropped }, ...(lineage ? { lineage } : {}) }, null, 2))
       const report: RebuildReport = {
         runId: compileRunId, compileRunId, version, only,
         cards: this.cards.length, units: this.units.length, notes: this.units.length,
@@ -2598,7 +3114,60 @@ export class KnowledgeRuntime {
    * 匹配逻辑与 0030 相同（词面匹配节点 title / id 与关系词，命中节点带出 1 跳邻居并衰减），
    * 但返回值只用于给**已经在候选池里**的条目加权 —— 它自己不能制造候选。
    */
-  private graphBoostRanking(query: string, eligible: WikiNote[], includeProblems: boolean): RouteRanking[] {
+  /**
+   * 字段级的归因图（`03_compiled/diagnosis_graph.json`）。
+   *
+   * 它只用于**给已经在候选池里的条目加权**（和卡片级图一样，不能自己制造候选）。
+   * 用途是把「假设 → 检查点」「证据 → 假设」这两类卡片级图看不见的语义带进召回。
+   */
+  private diagnosisGraph: { nodes: Array<Record<string, unknown>>; edges: Array<Record<string, unknown>> } = { nodes: [], edges: [] }
+
+  /**
+   * 归因图上按词面命中的节点 → 分数，含 1 跳衰减。
+   *
+   * 与卡片级那一段是**同一条算法、两份数据**：卡片级图里只有 `supported_by` /
+   * `relates_to`，而字段级图里是十种语义边。分开算再按 `entityId` 合流，
+   * 是因为两张图的节点含义不同（一个是卡片，一个是字段级节点），合成一张会让
+   * 图谱 Tab 看到一张卡片散成七个点。
+   */
+  private diagnosisHits(queryTokens: string[]): Map<string, number> {
+    const seed = new Map<string, number>()
+    if (this.diagnosisGraph.nodes.length === 0) return seed
+    for (const node of this.diagnosisGraph.nodes) {
+      const title = String(node.title ?? '').toLocaleLowerCase()
+      const id = String(node.id ?? '').toLocaleLowerCase()
+      let score = 0
+      for (const token of queryTokens) {
+        if (title.includes(token)) score += 3
+        else if (id.includes(token)) score += 2
+      }
+      if (score > 0) seed.set(String(node.id), score)
+    }
+    // 关系词命中：两端各得 1 分。中文提问不会写 `refutes`，所以走 RELATION_QUERY_WORDS。
+    for (const edge of this.diagnosisGraph.edges) {
+      const type = String(edge.kind ?? '')
+      const relation = (RELATION_QUERY_WORDS[type] ?? type.toLocaleLowerCase().replace(/_/g, ' ')).toLocaleLowerCase()
+      let score = 0
+      for (const token of queryTokens) if (relation.includes(token)) score += 1
+      if (score > 0) {
+        seed.set(String(edge.source), Math.max(seed.get(String(edge.source)) ?? 0, score))
+        seed.set(String(edge.target), Math.max(seed.get(String(edge.target)) ?? 0, score))
+      }
+    }
+    if (seed.size === 0) return seed
+    const expanded = new Map<string, number>(seed)
+    for (const [id, score] of seed) {
+      for (const edge of this.diagnosisGraph.edges) {
+        const from = String(edge.source)
+        const to = String(edge.target)
+        if (from === id) expanded.set(to, Math.max(expanded.get(to) ?? 0, score * 0.5))
+        else if (to === id) expanded.set(from, Math.max(expanded.get(from) ?? 0, score * 0.5))
+      }
+    }
+    return expanded
+  }
+
+  private async graphBoostRanking(query: string, eligible: WikiNote[], includeProblems: boolean): Promise<RouteRanking[]> {
     if (this.graph.nodes.length === 0) return []
     const queryTokens = segment(query)
     if (queryTokens.length === 0) return []
@@ -2606,6 +3175,9 @@ export class KnowledgeRuntime {
     const boost = (key: string, score: number): void => { byNodeKey.set(key, Math.max(byNodeKey.get(key) ?? 0, score)) }
     const visible = (node: Record<string, unknown>): boolean => includeProblems || node.status !== 'problem'
     const nodeKey = (node: Record<string, unknown>): string => `${String(node.type)}:${String(node.id)}`
+    /** 卡片级节点 id → 它的 `entity_type`。归因图的节点 id 与卡片 id 相等（§14.1）。 */
+    const typeByEntityId = new Map<string, string>()
+    for (const node of this.graph.nodes) typeByEntityId.set(String(node.id), String(node.type))
 
     for (const node of this.graph.nodes) {
       if (!visible(node)) continue
@@ -2625,6 +3197,18 @@ export class KnowledgeRuntime {
       for (const token of queryTokens) if (relation.includes(token)) score += 1
       if (score > 0) { boost(String(edge.from), score); boost(String(edge.to), score) }
     }
+    /**
+     * **字段级的归因图**（0021 §14.4 的第二条最小路径）。
+     *
+     * 卡片级的图只认 `supported_by` 与 `relates_to` 两种关系词，所以「假设 → 检查点」
+     * 与「证据 → 假设」这两类语义对召回完全不可见。这里按 `entityId` 把两张图接起来：
+     * 归因图上命中的节点，映射回同 id 的卡片级节点加权 —— **不需要合图**，
+     * 因为两张图的节点 id 本来就相等（§14.1）。
+     */
+    for (const [id, score] of this.diagnosisHits(queryTokens)) {
+      const type = typeByEntityId.get(id)
+      if (type) boost(`${type}:${id}`, score)
+    }
     if (byNodeKey.size === 0) return []
     const expanded = new Map<string, number>(byNodeKey)
     for (const [key, score] of byNodeKey) {
@@ -2755,7 +3339,7 @@ export class KnowledgeRuntime {
     const vectorOutcome = useVector
       ? await this.vectorRoute(query, eligibleIds, candidatePool, this.config.vectorThreshold)
       : { ranking: [] as RouteRanking[], diagnostic: { route: 'vector' as const, status: 'skipped' as const, reason: '当前模式未启用向量路' }, health: { ok: false, reason: '当前模式未启用向量路' } }
-    const graphRanking = useGraphBoost ? this.graphBoostRanking(query, eligible, includeProblems) : []
+    const graphRanking = useGraphBoost ? await this.graphBoostRanking(query, eligible, includeProblems) : []
 
     if (ftsOutcome.diagnostic.status === 'degraded' && ftsOutcome.diagnostic.reason) warnings.push(ftsOutcome.diagnostic.reason)
     if (vectorOutcome.diagnostic.status === 'degraded' && vectorOutcome.diagnostic.reason) warnings.push(vectorOutcome.diagnostic.reason)
@@ -2984,8 +3568,25 @@ export class KnowledgeRuntime {
 
   async graphQuery(action: 'entity' | 'neighbors' | 'path' | 'list' | 'types', entityId?: string, entityType?: string, depth = 1, options: { fromId?: string; toId?: string; status?: string; includeProblem?: boolean; limit?: number } = {}, lineage?: LineageContext): Promise<Envelope<Record<string, unknown>>> {
     const eventLineage = withRun(lineage, 'graph-query')
-    if (this.units.length === 0) await this.rebuild('all', eventLineage)
+    /**
+     * **读盘，不编译。**
+     *
+     * `units` 为空只说明这个 runtime 还没读过 `03_compiled/`，**不等于**盘上没有编译
+     * 产物：runtime 是按库缓存的，设置一变就被丢掉（`KnowledgeBases.invalidate()`），
+     * 下一次读图时内存里又是空的。原来的写法把这两种情况当成同一件事，在这里直接
+     * `rebuild('all')` —— 于是一次**读**变成一次全量编译：面板刷新时那个
+     * `GET /knowledge/graph` 在几百篇文档的库上要等 3~5 秒，而这段时间整个知识库面板
+     * 连同「类型定义」都是不可操作的。
+     *
+     * 编译是**写**动作，归「编译」按钮与 `POST /knowledge/rebuild`。读路径只如实报告
+     * 「盘上还没有编译产物」（`needsBuild`），要不要编由界面和 Agent 自己决定 ——
+     * 与 `recall` 同一条规矩：先读盘，读不到再说。
+     */
+    if (this.units.length === 0 && this.graph.nodes.length === 0) await this.loadCompiledState()
+    const needsBuild = this.units.length === 0 && this.graph.nodes.length === 0
     const attachLineage = (data: Record<string, unknown>): Record<string, unknown> => eventLineage ? { ...data, lineage: eventLineage } : data
+    /** 空图 + 一句为什么空：调用方（尤其是 Agent）不能把「还没编译」读成「这个库没有知识」。 */
+    const attachBuild = (data: Record<string, unknown>): Record<string, unknown> => needsBuild ? { ...data, needsBuild: true } : data
     if (depth < 1 || depth > 3) return failure({}, 'DEPTH_INVALID', 'depth 必须在 1 到 3 之间', false)
     const limit = options.limit ?? 50
     if (!Number.isInteger(limit) || limit < 1 || limit > 50) return failure({}, 'LIMIT_INVALID', 'limit 必须在 1 到 50 之间', false)
@@ -2998,7 +3599,7 @@ export class KnowledgeRuntime {
       .filter(node => !options.status || node.status === options.status)
     const nodes = allNodes.filter(node => !entityType || node.type === entityType)
     const edges = this.graph.edges.filter(edge => allNodes.some(node => `${node.type}:${node.id}` === String(edge.from)) && allNodes.some(node => `${node.type}:${node.id}` === String(edge.to)))
-    if (action === 'list') return success(attachLineage({ nodes: nodes.slice(0, limit), edges: edges.slice(0, limit) }))
+    if (action === 'list') return success(attachLineage(attachBuild({ nodes: nodes.slice(0, limit), edges: edges.slice(0, limit) })))
 
     const nodeKey = (rawId: string | undefined, rawType?: string): string | undefined => {
       if (!rawId) return undefined
@@ -3024,20 +3625,20 @@ export class KnowledgeRuntime {
         })
         for (const next of nextKeys) if (!visited.has(next)) { visited.add(next); queue.push({ key: next, path: [...current.path, next] }) }
       }
-      if (!found) return success(attachLineage({ path: [], nodes: [], edges: [] }))
+      if (!found) return success(attachLineage(attachBuild({ path: [], nodes: [], edges: [] })))
       return success(attachLineage({ path: found, nodes: allNodes.filter(node => found!.includes(`${node.type}:${node.id}`)), edges: edges.filter(edge => found!.includes(String(edge.from)) && found!.includes(String(edge.to))) }))
     }
 
     const id = nodeKey(entityId, entityType)
     if (!id) return failure({}, 'ENTITY_REQUIRED', '该 graph action 需要 entity_id', true)
-    if (action === 'entity') return success(attachLineage({ nodes: nodes.filter(node => `${node.type}:${node.id}` === id).slice(0, limit) }))
+    if (action === 'entity') return success(attachLineage(attachBuild({ nodes: nodes.filter(node => `${node.type}:${node.id}` === id).slice(0, limit) })))
     if (action === 'neighbors') {
       const ids = new Set([id])
       for (let index = 0; index < depth; index++) for (const edge of edges) {
         if (ids.has(String(edge.from))) ids.add(String(edge.to))
         if (ids.has(String(edge.to))) ids.add(String(edge.from))
       }
-      return success(attachLineage({ nodes: allNodes.filter(node => ids.has(`${node.type}:${node.id}`)).slice(0, limit), edges: edges.filter(edge => ids.has(String(edge.from)) || ids.has(String(edge.to))).slice(0, limit) }))
+      return success(attachLineage(attachBuild({ nodes: allNodes.filter(node => ids.has(`${node.type}:${node.id}`)).slice(0, limit), edges: edges.filter(edge => ids.has(String(edge.from)) || ids.has(String(edge.to))).slice(0, limit) })))
     }
     return failure({}, 'ACTION_INVALID', `不支持的 graph action: ${action}`, false)
   }