dsh-data-domain-knowledge 0.1.0-alpha.9 → 0.1.1-alpha.2

package/src/axis-registry.ts

@@ -34,17 +34,31 @@
  * ## 为什么存在记忆段
  *
  * 注册表**不可重建**：它是人确认过的命名决定（改 canonical name、并两个实体、加一个别名），
- * 重跑一次抽取不会得到同样的结果。所以它和操作日志、抽取轨迹一样落在
- * `<memoryDir>/knowledge.sqlite`，不在 `03_compiled/`。
+ * 重跑一次抽取不会得到同样的结果。所以它与 Knowledge 共享 `knowledge.db`，
+ * 经过同一个属主与 schema 版本入口校验。
  */
 
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
+import { createHash } from 'node:crypto'
 import { loadSqlite, type SqliteDatabase } from './fts.js'
+import { KnowledgeDb } from './store/knowledge-db.js'
 
 /** 三个轴。三者地位相同（§3.1）—— 没有哪个更特殊。 */
 export type AxisKind = 'object' | 'action' | 'scene'
 
+/** 当前参与关系扩展召回的轴关系。它连接相关对象，不表示父子层级。 */
+export const AXIS_RELATION_TYPES = ['related_to'] as const
+export type AxisRelationType = typeof AXIS_RELATION_TYPES[number]
+
+export interface AxisRelation {
+  id: string
+  fromId: string
+  toId: string
+  relationType: AxisRelationType
+  evidence: string
+  createdAt: string
+  updatedAt: string
+}
+
 /**
  * 一个轴实体的状态。
  *
@@ -215,6 +229,18 @@ CREATE TABLE IF NOT EXISTS entity_guidance (
   created_at TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_axis_guidance_entity ON entity_guidance(entity_id);
+CREATE TABLE IF NOT EXISTS axis_relations (
+  id TEXT PRIMARY KEY,
+  from_id TEXT NOT NULL,
+  to_id TEXT NOT NULL,
+  relation_type TEXT NOT NULL,
+  evidence TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE(from_id, to_id, relation_type)
+);
+CREATE INDEX IF NOT EXISTS idx_axis_relation_from ON axis_relations(from_id, relation_type);
+CREATE INDEX IF NOT EXISTS idx_axis_relation_to ON axis_relations(to_id, relation_type);
 `
 
 /**
@@ -225,20 +251,27 @@ CREATE INDEX IF NOT EXISTS idx_axis_guidance_entity ON entity_guidance(entity_id
  */
 export class AxisRegistry {
   private db: SqliteDatabase | null = null
+  private owner: KnowledgeDb | null = null
 
-  constructor(private readonly file: string) {}
+  constructor(private readonly file: string, private readonly shared?: SqliteDatabase) {}
 
   async open(): Promise<boolean> {
     if (this.db !== null) return true
     const sqlite = await loadSqlite()
     if (sqlite === null) return false
     try {
-      await mkdir(dirname(this.file), { recursive: true })
-      this.db = new sqlite.DatabaseSync(this.file)
+      if (this.shared) this.db = this.shared
+      else {
+        const opened = await KnowledgeDb.open(this.file, sqlite.DatabaseSync)
+        if (!opened.ok) return false
+        this.owner = opened.db
+        this.db = opened.db.connection()
+      }
       this.db.exec(SCHEMA)
+      this.db.exec('CREATE TABLE IF NOT EXISTS axis_input_revision (id INTEGER PRIMARY KEY CHECK(id = 1), revision INTEGER NOT NULL); INSERT OR IGNORE INTO axis_input_revision VALUES (1, 0)')
       /*
-       * 补列。这个库**没有 `user_version` 那一套**（它是记忆段里的一张注册表，不是知识本体），
-       * 所以判据落在列上：缺就补，补齐之后什么都不做。`CREATE TABLE IF NOT EXISTS` 对
+       * 主库已通过 `user_version` 校验，再幂等补齐存量注册表的扩展列。缺就补。
+       * `CREATE TABLE IF NOT EXISTS` 对
        * 已经存在的表一个字都不改 —— 少了这一段，0068 之前建的库会永远没有这两列，
        * 而症状是「定义存进去了，下次打开又没了」。
        */
@@ -250,11 +283,57 @@ export class AxisRegistry {
       }
       return true
     } catch {
+      this.owner?.close()
+      this.owner = null
       this.db = null
       return false
     }
   }
 
+  inputRevision(): number {
+    return Number((this.db?.prepare('SELECT revision FROM axis_input_revision WHERE id = 1').get() as { revision?: number } | undefined)?.revision ?? 0)
+  }
+
+  /** Resolve against an isolated copy; commit only if the live registry still matches. */
+  async draft(): Promise<{ registry: AxisRegistry; commit: () => void; close: () => void }> {
+    const sqlite = await loadSqlite()
+    if (!sqlite || !this.db) throw new Error('AXIS_REGISTRY_UNAVAILABLE')
+    const live = this.db
+    const tables = ['axis_entities', 'axis_aliases', 'entity_guidance', 'axis_relations', 'axis_input_revision']
+    const read = (db: SqliteDatabase): Array<Array<Record<string, unknown>>> => tables.map(table => db.prepare(`SELECT * FROM ${table} ORDER BY rowid`).all() as Array<Record<string, unknown>>)
+    const before = read(live)
+    const copy = new sqlite.DatabaseSync(':memory:')
+    const registry = new AxisRegistry(':memory:', copy)
+    try {
+      if (!await registry.open()) throw new Error('AXIS_DRAFT_UNAVAILABLE')
+      tables.forEach((table, index) => {
+        copy.exec(`DELETE FROM ${table}`)
+        for (const row of before[index]!) {
+          const columns = Object.keys(row)
+          copy.prepare(`INSERT INTO ${table} (${columns.join(',')}) VALUES (${columns.map(() => '?').join(',')})`).run(...Object.values(row))
+        }
+      })
+      return {
+        registry,
+        commit: () => {
+          if (JSON.stringify(read(live)) !== JSON.stringify(before)) throw new Error('归一期间实体注册表已变化，请重试归一')
+          // Resolution only adds entities/aliases and fills model definitions.
+          for (const table of ['axis_entities', 'axis_aliases']) {
+            for (const row of copy.prepare(`SELECT * FROM ${table}`).all() as Array<Record<string, unknown>>) {
+              const columns = Object.keys(row)
+              const keys = table === 'axis_entities' ? ['id'] : ['entity_id', 'normalized', 'scope_id']
+              const updates = columns.filter(column => !keys.includes(column)).map(column => `${column}=excluded.${column}`)
+              live.prepare(`INSERT INTO ${table} (${columns.join(',')}) VALUES (${columns.map(() => '?').join(',')}) ON CONFLICT (${keys.join(',')}) DO UPDATE SET ${updates.join(',')}`).run(...Object.values(row))
+            }
+          }
+        },
+        close: () => { registry.close(); copy.close() },
+      }
+    } catch (cause) { registry.close(); copy.close(); throw cause }
+  }
+
+  private changedInput(): void { this.db?.prepare('UPDATE axis_input_revision SET revision = revision + 1 WHERE id = 1').run() }
+
   available(): boolean {
     return this.db !== null
   }
@@ -316,10 +395,19 @@ export class AxisRegistry {
 
     // 2 · 作用域内 alias
     if (parentId) {
-      const aliased = this.findAlias(normalized, parentId)
-      if (aliased) {
-        this.learn(aliased, mention, normalized, parentId, input.description)
-        return { mention, normalized, outcome: 'matched', entity: aliased, how: 'scoped-alias' }
+      const aliased = this.findAliases(input.kind, normalized, parentId)
+      if (aliased.length === 1) {
+        this.learn(aliased[0]!, mention, normalized, parentId, input.description)
+        return { mention, normalized, outcome: 'matched', entity: aliased[0]!, how: 'scoped-alias' }
+      }
+      /**
+       * 同一作用域里两个实体可以合法地共有同一条别名（`axis_aliases` 的主键是
+       * `(entity_id, normalized, scope_id)`，不是 `(normalized, scope_id)`）。这时候
+       * **不能取第一个** —— 本文件的规矩是「不唯一就不猜」，猜错的代价是把一条知识挂到
+       * 错误的对象上并一路传到卡名。全局那条路（下面）一直是这么做的，只有这里漏了。
+       */
+      if (aliased.length > 1) {
+        return { mention, normalized, outcome: 'ambiguous', candidates: aliased.slice().sort((left, right) => left.name.localeCompare(right.name)) }
       }
     }
 
@@ -447,6 +535,61 @@ export class AxisRegistry {
     })
   }
 
+  /** 列出对象关系；传实体 id 时只返回它的邻接关系。 */
+  async listRelations(entityId?: string): Promise<AxisRelation[]> {
+    if (this.db === null) throw new Error('AXIS_REGISTRY_UNAVAILABLE')
+    const params: Record<string, unknown> = {}
+    const filter = entityId === undefined ? '' : 'AND (r.from_id = :entityId OR r.to_id = :entityId)'
+    if (entityId !== undefined) params.entityId = entityId
+    const rows = this.db.prepare(`
+      SELECT r.* FROM axis_relations r
+      JOIN axis_entities a ON a.id = r.from_id
+      JOIN axis_entities b ON b.id = r.to_id
+      WHERE r.relation_type = 'related_to'
+        AND a.kind = 'object' AND b.kind = 'object'
+        AND a.status <> 'merged' AND b.status <> 'merged'
+        ${filter}
+      ORDER BY r.from_id, r.to_id
+    `).all(params) as Array<Record<string, unknown>>
+    return rows.map(rowToRelation)
+  }
+
+  /** 建立无方向的 related_to 边；同一个对象不能关联自己。 */
+  async addRelation(fromId: string, toId: string, evidence = ''): Promise<AxisRelation | null> {
+    if (this.db === null) throw new Error('AXIS_REGISTRY_UNAVAILABLE')
+    if (!fromId || !toId || fromId === toId) return null
+    const [from, to] = await Promise.all([this.get(fromId), this.get(toId)])
+    if (from === null || to === null || from.kind !== 'object' || to.kind !== 'object' || from.status === 'merged' || to.status === 'merged') return null
+    const [left, right] = [fromId, toId].sort((a, b) => a.localeCompare(b))
+    const now = new Date().toISOString()
+    const relation: AxisRelation = {
+      id: axisRelationId(left, right, 'related_to'),
+      fromId: left,
+      toId: right,
+      relationType: 'related_to',
+      evidence: evidence.trim(),
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.db.prepare(`
+      INSERT INTO axis_relations (id, from_id, to_id, relation_type, evidence, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(from_id, to_id, relation_type) DO UPDATE SET
+        evidence = CASE WHEN excluded.evidence <> '' THEN excluded.evidence ELSE axis_relations.evidence END,
+        updated_at = excluded.updated_at
+    `).run(relation.id, relation.fromId, relation.toId, relation.relationType, relation.evidence, relation.createdAt, relation.updatedAt)
+    const row = this.db.prepare('SELECT * FROM axis_relations WHERE from_id = ? AND to_id = ? AND relation_type = ?')
+      .get(left, right, 'related_to') as Record<string, unknown> | undefined
+    return row === undefined ? null : rowToRelation(row)
+  }
+
+  /** 移除一条对象关系。 */
+  async removeRelation(id: string): Promise<boolean> {
+    if (this.db === null) throw new Error('AXIS_REGISTRY_UNAVAILABLE')
+    const result = this.db.prepare('DELETE FROM axis_relations WHERE id = ?').run(id) as { changes?: unknown }
+    return Number(result.changes) > 0
+  }
+
   /** 每个轴各有多少个实体、其中几个待人确认。类型定义那一屏的计数读它。 */
   async stats(): Promise<Record<AxisKind, { total: number; candidate: number }>> {
     const empty = { total: 0, candidate: 0 }
@@ -475,6 +618,7 @@ export class AxisRegistry {
     const now = new Date().toISOString()
     this.db.prepare('UPDATE axis_entities SET name = ?, updated_at = ? WHERE id = ?').run(next, now, id)
     this.insertAlias(id, current.name, normalizeAxisName(current.name), current.scopeId, now)
+    this.changedInput()
     return this.get(id)
   }
 
@@ -490,6 +634,7 @@ export class AxisRegistry {
     const normalized = normalizeAxisName(alias)
     if (!normalized) return false
     this.insertAlias(id, alias.trim(), normalized, scopeId.trim(), new Date().toISOString())
+    this.changedInput()
     return true
   }
 
@@ -501,6 +646,7 @@ export class AxisRegistry {
   async setStatus(id: string, status: AxisStatus): Promise<AxisEntity | null> {
     if (this.db === null) throw new Error('AXIS_REGISTRY_UNAVAILABLE')
     this.db.prepare('UPDATE axis_entities SET status = ?, updated_at = ? WHERE id = ?').run(status, new Date().toISOString(), id)
+    this.changedInput()
     return this.get(id)
   }
 
@@ -511,18 +657,58 @@ export class AxisRegistry {
    * 它转成 `merged`，`scopeId` 改存目标 id —— 复用这一列而不是新加一列，因为
    * 「它现在归谁」与「它在谁的下面」对解析来说问的是同一件事。
    */
-  async merge(fromId: string, intoId: string): Promise<boolean> {
+  async merge(fromId: string, intoId: string, redirect?: (kind: AxisKind) => void): Promise<boolean> {
     if (this.db === null) throw new Error('AXIS_REGISTRY_UNAVAILABLE')
     if (fromId === intoId) return false
     const [from, into] = [await this.get(fromId), await this.get(intoId)]
-    if (from === null || into === null || from.kind !== into.kind) return false
+    if (from === null || into === null || from.kind !== into.kind || from.status === 'merged' || into.status === 'merged') return false
     const now = new Date().toISOString()
-    this.db.prepare('UPDATE axis_entities SET status = ?, scope_id = ?, updated_at = ? WHERE id = ?').run('merged', intoId, now, fromId)
-    // 被并者的别名与名字一起搬过去：按旧名、旧别名都要搜得到。
-    this.insertAlias(intoId, from.name, normalizeAxisName(from.name), into.scopeId, now)
-    const aliases = this.db.prepare('SELECT alias, scope_id FROM axis_aliases WHERE entity_id = ?').all(fromId) as Array<Record<string, unknown>>
-    for (const row of aliases) this.insertAlias(intoId, String(row.alias), normalizeAxisName(String(row.alias)), String(row.scope_id ?? ''), now)
-    return true
+    this.db.exec('SAVEPOINT axis_merge')
+    try {
+      this.db.prepare('UPDATE axis_entities SET status = ?, scope_id = ?, updated_at = ? WHERE id = ?').run('merged', intoId, now, fromId)
+      // 被并者的别名与名字一起搬过去：按旧名、旧别名都要搜得到。
+      this.insertAlias(intoId, from.name, normalizeAxisName(from.name), into.scopeId, now)
+      const aliases = this.db.prepare('SELECT alias, scope_id FROM axis_aliases WHERE entity_id = ?').all(fromId) as Array<Record<string, unknown>>
+      for (const row of aliases) this.insertAlias(intoId, String(row.alias), normalizeAxisName(String(row.alias)), String(row.scope_id ?? ''), now)
+      this.redirectRelations(fromId, intoId, now)
+      redirect?.(from.kind)
+      // Scope references on both canonical names and aliases move together.
+      this.db.prepare("UPDATE axis_entities SET scope_id = ? WHERE scope_id = ? AND status <> 'merged'").run(intoId, fromId)
+      this.db.prepare(`INSERT OR IGNORE INTO axis_aliases (entity_id, alias, normalized, scope_id, created_at)
+        SELECT entity_id, alias, normalized, ?, created_at FROM axis_aliases WHERE scope_id = ?`).run(intoId, fromId)
+      this.db.prepare('DELETE FROM axis_aliases WHERE scope_id = ?').run(fromId)
+      this.db.prepare('UPDATE entity_guidance SET entity_id = ? WHERE entity_id = ?').run(intoId, fromId)
+      this.changedInput()
+      this.db.exec('RELEASE axis_merge')
+      return true
+    } catch (cause) {
+      this.db.exec('ROLLBACK TO axis_merge; RELEASE axis_merge')
+      throw cause
+    }
+  }
+
+  /** 合并轴实体时转移相关关系，并折叠重复边与自环。 */
+  private redirectRelations(fromId: string, intoId: string, now: string): void {
+    if (this.db === null) return
+    const rows = this.db.prepare('SELECT * FROM axis_relations WHERE from_id = ? OR to_id = ?').all(fromId, fromId) as Array<Record<string, unknown>>
+    if (rows.length === 0) return
+    this.db.prepare('DELETE FROM axis_relations WHERE from_id = ? OR to_id = ?').run(fromId, fromId)
+    const insert = this.db.prepare(`
+      INSERT INTO axis_relations (id, from_id, to_id, relation_type, evidence, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(from_id, to_id, relation_type) DO UPDATE SET
+        evidence = CASE WHEN excluded.evidence <> '' THEN excluded.evidence ELSE axis_relations.evidence END,
+        updated_at = excluded.updated_at
+    `)
+    for (const row of rows) {
+      const oldFrom = String(row.from_id)
+      const oldTo = String(row.to_id)
+      const pair = [oldFrom === fromId ? intoId : oldFrom, oldTo === fromId ? intoId : oldTo]
+      if (pair[0] === pair[1]) continue
+      const [left, right] = pair.sort((a, b) => a.localeCompare(b))
+      const type = String(row.relation_type) as AxisRelationType
+      insert.run(axisRelationId(left, right, type), left, right, type, String(row.evidence ?? ''), String(row.created_at ?? now), now)
+    }
   }
 
   /* ─────────────────────────────────────────── 定义（0068） ── */
@@ -535,6 +721,7 @@ export class AxisRegistry {
     const next = text.trim()
     this.db.prepare('UPDATE axis_entities SET description = ?, description_source = ?, updated_at = ? WHERE id = ?')
       .run(next, next ? 'human' : '', new Date().toISOString(), id)
+    this.changedInput()
     return this.get(id)
   }
 
@@ -625,6 +812,7 @@ export class AxisRegistry {
     }
     this.db.prepare('INSERT INTO entity_guidance (id, entity_id, kind, text, author, created_at) VALUES (?, ?, ?, ?, ?, ?)')
       .run(guidance.id, guidance.entityId, guidance.kind, guidance.text, guidance.author, guidance.createdAt)
+    this.changedInput()
     return guidance
   }
 
@@ -634,6 +822,7 @@ export class AxisRegistry {
     const before = this.db.prepare('SELECT id FROM entity_guidance WHERE id = ?').get(id) as { id?: unknown } | undefined
     if (before === undefined) return false
     this.db.prepare('DELETE FROM entity_guidance WHERE id = ?').run(id)
+    this.changedInput()
     return true
   }
 
@@ -722,7 +911,8 @@ export class AxisRegistry {
   }
 
   close(): void {
-    this.db?.close()
+    this.owner?.close()
+    this.owner = null
     this.db = null
   }
 
@@ -736,11 +926,12 @@ export class AxisRegistry {
     return hit === undefined ? undefined : rowToEntity(hit)
   }
 
-  private findAlias(normalized: string, scopeId: string): AxisEntity | undefined {
-    const row = this.db!.prepare(
-      "SELECT e.* FROM axis_aliases a JOIN axis_entities e ON e.id = a.entity_id WHERE a.normalized = ? AND a.scope_id = ? AND e.status <> 'merged' LIMIT 1",
-    ).get(normalized, scopeId) as Record<string, unknown> | undefined
-    return row === undefined ? undefined : rowToEntity(row)
+  /** 作用域内的别名命中。**可能不止一条** —— 调用方必须自己判唯一性。 */
+  private findAliases(kind: AxisKind, normalized: string, scopeId: string): AxisEntity[] {
+    const rows = this.db!.prepare(
+      "SELECT e.* FROM axis_aliases a JOIN axis_entities e ON e.id = a.entity_id WHERE a.normalized = ? AND a.scope_id = ? AND e.kind = ? AND e.status <> 'merged' ORDER BY e.id",
+    ).all(normalized, scopeId, kind) as Array<Record<string, unknown>>
+    return rows.map(rowToEntity)
   }
 
   /** 全局 canonical 名精确命中。它可能不止一个 —— 两个实体同名时就是歧义。 */
@@ -862,6 +1053,22 @@ function rowToEntity(row: Record<string, unknown>): AxisEntity {
   }
 }
 
+function axisRelationId(fromId: string, toId: string, relationType: AxisRelationType): string {
+  return `axis_rel_${createHash('sha256').update(`${relationType}:${fromId}:${toId}`).digest('hex').slice(0, 14)}`
+}
+
+function rowToRelation(row: Record<string, unknown>): AxisRelation {
+  return {
+    id: String(row.id),
+    fromId: String(row.from_id),
+    toId: String(row.to_id),
+    relationType: String(row.relation_type) as AxisRelationType,
+    evidence: String(row.evidence ?? ''),
+    createdAt: String(row.created_at),
+    updatedAt: String(row.updated_at),
+  }
+}
+
 function rowToGuidance(row: Record<string, unknown>): AxisGuidance {
   return {
     id: String(row.id),

package/src/card-organize.ts

@@ -63,10 +63,10 @@ import { createHash } from 'node:crypto'
 import type { CardKnowledgeRow } from './store/knowledge-db.js'
 
 /** 组织方案的版本。它进 `layout_hash` —— 改提示词就该让已有的方案失效重排。 */
-export const ORGANIZE_VERSION = 2
+export const ORGANIZE_VERSION = 4
 
-/** 小节数量的上限。不是省略号：超过这个数，卡片就不再是「一个坐标的说明书」。 */
-export const MAX_SECTIONS = 12
+/** 章节计划的资源上限，覆盖当前单次组织的 Knowledge 上限；不是预设目录数量。 */
+export const MAX_SECTIONS = 200
 
 /** 小节标题的字符上限。 */
 export const MAX_SECTION_TITLE = 60
@@ -112,6 +112,9 @@ export interface OrganizeBlock {
 }
 
 export interface OrganizeSection {
+  sectionId?: string
+  retrievalNeed?: string
+  knowledgeIds?: string[]
   title: string
   blocks: OrganizeBlock[]
 }
@@ -144,11 +147,12 @@ export interface OrganizeInput {
   cardTitle: string
   coordinate: { object: string; action: string; scene: string }
   /** 这个坐标下的**全部**知识（库里已有的 ∪ 本轮新增的）。 */
-  knowledge: Array<{ id: string; text: string }>
+  knowledge: Array<{ id: string; text: string; sourceHeadings?: string[] }>
   /**
    * 卡片骨架允许的小节（类型定义里那套）。**是建议，不是白名单** ——
    * 一个小节该不该存在，取决于这个坐标下真的有什么知识，而那是模型这一次才看到的。
    */
+  existingSections?: SectionRecord[]
   suggestedSections?: string[]
   /** 骨架里的建议小节。下发进提示词，好让模型优先用它们承载对应内容。 */
   requiredSections?: string[]
@@ -178,70 +182,9 @@ export interface OrganizeCheck {
   summaryCited: string[]
 }
 
-// ---------------------------------------------------------------- 提示词
 
-/**
- * 组织阶段的 system 提示词。
- *
- * 四条规则是这份提示词的全部：**只组织不创造**、**每条知识都要落地**、
- * **每句都要挂引用**。其余全是输出形状。
- */
-export function buildOrganizeSystem(): string {
-  return [
-    '你在把一批已经抽好的知识组织成一张 Wiki 卡片。',
-    '',
-    '这批知识属于同一个坐标（对象 × 动作 × 场景）。它们是**事实真源**，你不许新增、',
-    '删除或改动它们说的事实。你能做的是：分小节、定顺序、把它们改写成读得下去的',
-    '叙述、给卡片起一个自然的标题、写一句概述。',
-    '',
-    '## 三条规则',
-    '',
-    '1. **只组织，不创造。** 你写的每一句话，说的都必须是这批知识里已经有的事。',
-    '   你觉得「应该还有一步」而知识里没有 —— 那就不要写。',
-    '2. **每条知识都要落地。** 输入给了几条，正文里就必须用上几条，一条都不能丢。',
-    '   可以把两条合成一行表格、合成一个步骤 —— 但它们的 id 都要挂上。',
-    '3. **每句都要挂引用。** 陈述事实的句子末尾挂 `[^知识id]`，可以挂多个。',
-    '   只有很短的导语（「这一节讲取数流程」）可以不挂。长句子不挂引用 = 没有来源的',
-    '   断言，整份方案会被打回。',
-    '4. **标题只做归纳，不要机械拼接。** 标题要能让人一眼知道卡片讲什么；不要照抄候选卡名，',
-    '   不要写成「对象的动作」「动作的动作」这类重复结构，不要加入知识里没有的新事实。',
-    '',
-    '## 可以做的改写',
-    '',
-    '- 缩写、重排、把陈述句改成祈使句（「楼层 ID 会变」→「不要写死楼层 ID」）。',
-    '- 把两条同类的知识合成一张表或一个步骤。',
-    '- 把字段名、SQL、URL 放进反引号。',
-    '- 加很短的小节导语，把一节的内容串起来。',
-    '',
-    '## 输出形状',
-    '',
-    '只回一个 JSON 对象，不要散文，不要代码围栏。',
-    '',
-    '```json',
-    '{',
-    '  "title": "简洁、自然、可检索的卡片标题，不要机械拼接对象和动作",',
-    '  "summary": "一句话说清这张卡讲什么。挂引用，如 [^k_abc]。",',
-    '  "sections": [',
-    '    {',
-    '      "title": "一、这一节讲什么",',
-    '      "blocks": [',
-    '        { "kind": "prose", "text": "一段话。[^k_abc]" },',
-    '        { "kind": "steps", "items": ["第一步。[^k_def]", "第二步。[^k_ghi]"] },',
-    '        { "kind": "bullets", "items": ["一个要点。[^k_jkl]"] },',
-    '        { "kind": "table", "header": ["", "甲", "乙"], "rows": [["来源", "A[^k_mno]", "B[^k_pqr]"]] },',
-    '        { "kind": "note", "text": "一句提醒。[^k_stu]" }',
-    '      ]',
-    '    }',
-    '  ]',
-    '}',
-    '```',
-    '',
-    '`kind` 只能是这五个之一：`prose`（一段话）、`steps`（有序步骤）、`bullets`（无序要点）、',
-    '`table`（对比表）、`note`（提醒）。表格的每一行列数必须与表头一致。',
-    '',
-    '小节标题自己起，要具体（「二、取数流程」而不是「二、步骤」）。小节数量 1 到 12。',
-  ].join('\n')
-}
+/** 组织阶段的 system 段搬到了 `organize-contract.ts`（说明页要显示它，而这里带着 node:crypto）。 */
+export { buildOrganizeSystem } from './organize-contract.js'
 
 /** 组织阶段的 user 提示词。知识清单在这里下发。 */
 export function buildOrganizePrompt(input: OrganizeInput): string {
@@ -258,23 +201,25 @@ export function buildOrganizePrompt(input: OrganizeInput): string {
   lines.push('')
 
   if (input.suggestedSections !== undefined && input.suggestedSections.length > 0) {
-    lines.push('# 本库卡片骨架里的小节（建议）')
+    lines.push('# 历史章节参考（不是固定目录）')
     lines.push('')
     const required = new Set(input.requiredSections ?? [])
     for (const section of input.suggestedSections) {
       lines.push(`- ${section}${required.has(section) ? '（建议）' : ''}`)
     }
     lines.push('')
-    lines.push('能用它们承载内容就用；装不下这批知识时可以自己起更贴切的小节名。')
+    lines.push('不要为了复用旧标题而合并不同检索需求。请按本批内容决定章节。')
     lines.push('')
   }
 
+  if (input.existingSections?.length) lines.push('# 已有章节身份（相同检索需求保留 section_id）', JSON.stringify(input.existingSections), '')
   lines.push(`# 这批知识（${input.knowledge.length} 条）`)
   lines.push('')
   lines.push('每条形如 `id :: 原文`。正文里的引用必须用这些 id。')
   lines.push('')
   for (const item of input.knowledge) {
     lines.push(`- \`${item.id}\` :: ${item.text.replace(/\s+/g, ' ').trim()}`)
+    if (item.sourceHeadings?.length) lines.push(`  原文标题路径（定位线索）：${[...new Set(item.sourceHeadings)].join('；')}`)
   }
   lines.push('')
 
@@ -460,7 +405,7 @@ export function parseOrganize(raw: string): { plan?: OrganizePlan; problems: Org
       }
       problems.push({ code: 'ORGANIZE_BLOCK_KIND', message: `小节「${title}」里有一个认不出的块类型「${kind}」` })
     }
-    if (blocks.length > 0) sections.push({ title, blocks })
+    if (blocks.length > 0) sections.push({ title, blocks, ...(asString(section.section_id) ? { sectionId: asString(section.section_id) } : {}), ...(asString(section.retrieval_need) ? { retrievalNeed: asString(section.retrieval_need) } : {}), ...(asStringList(section.knowledge_ids) ? { knowledgeIds: asStringList(section.knowledge_ids)! } : {}) })
   }
 
   if (sections.length === 0) problems.push({ code: 'ORGANIZE_NO_USABLE_SECTION', message: '没有一个可用的小节' })
@@ -488,6 +433,8 @@ export function checkOrganize(
   plan: OrganizePlan,
   known: string[],
   options: {
+    /** Check literal changes; this does not prove semantic entailment. */
+    knowledge?: Array<{ id: string; text: string }>
     /**
      * 正文里**可以**指向的其他卡片（`buildOrganizePrompt` 下发的那一份）。
      *
@@ -499,14 +446,36 @@ export function checkOrganize(
   } = {},
 ): OrganizeCheck {
   const problems: OrganizeProblem[] = []
+  for (const section of plan.sections) {
+    if (/\n|^#/.test(section.title) || section.blocks.some(block => blockTexts(block).some(text => /^#{1,2} /m.test(text)))) problems.push({ code: 'ORGANIZE_NESTED_H2', message: '章节正文不能插入一级或二级标题' })
+  }
+  for (const section of plan.sections) {
+    if (section.knowledgeIds) {
+      const actual = [...new Set(section.blocks.flatMap(block => blockTexts(block).flatMap(citationsIn)))].sort()
+      if (JSON.stringify([...new Set(section.knowledgeIds)].sort()) !== JSON.stringify(actual)) problems.push({ code: 'ORGANIZE_PLACEMENT_MISMATCH', message: `章节「${section.title}」的 knowledge_ids 与正文引用不一致` })
+    }
+  }
   const knownSet = new Set(known)
   const cited: string[] = []
   const seen = new Set<string>()
+  const byId = new Map(options.knowledge?.map(item => [item.id, item.text]) ?? [])
+  const literals = (text: string): string[] => [...text.replace(/\[\^[^\]]+\]/g, '').matchAll(/(?<![A-Za-z0-9_])(?:[<>≤≥]=?\s*)?[+-]?\d+(?:\.\d+)?(?:%|％)?/g)].map(match => match[0].replace(/\s/g, '').replace('％', '%'))
+  if (options.knowledge) {
+    const supported = new Set(literals(citationsIn(plan.summary).map(id => byId.get(id) ?? '').join('\n')))
+    const unsupported = literals(plan.summary).filter(value => !supported.has(value))
+    if (unsupported.length > 0) problems.push({ code: 'ORGANIZE_UNSUPPORTED_LITERAL', message: `概述的数值或比较条件没有引用依据：${[...new Set(unsupported)].join('、')}` })
+  }
 
   // 1 + 2：正文里的引用必须都存在，且每条知识都要落地。
   for (const section of plan.sections) {
     for (const block of section.blocks) {
       for (const text of blockTexts(block)) {
+        if (options.knowledge) {
+          const citedText = citationsIn(text).map(id => byId.get(id) ?? '').join('\n')
+          const supported = new Set(literals(citedText))
+          const unsupported = literals(text).filter(value => !supported.has(value))
+          if (unsupported.length > 0) problems.push({ code: 'ORGANIZE_UNSUPPORTED_LITERAL', message: `小节「${section.title}」的数值或比较条件没有引用依据：${[...new Set(unsupported)].join('、')}` })
+        }
         for (const id of citationsIn(text)) {
           if (!knownSet.has(id)) {
             problems.push({ code: 'ORGANIZE_UNKNOWN_CITATION', message: `小节「${section.title}」引用了这批知识里没有的 id「${id}」` })
@@ -708,16 +677,17 @@ export function placementsOf(plan: OrganizePlan, cited: string[]): CardKnowledge
  *
  * 输入是「知识集合 + 骨架 + 提示词版本」—— 三者任一变了才重排。所以：
  *
- * - 同一批知识再编译一次 → 指纹相同 → **不调模型**，复用库里那份方案。
- * - 这个坐标新进来一条知识 → 指纹变了 → 重排这一张卡（也只重排这一张）。
+ * - 知识与来源标题路径都没变 → 指纹相同 → **不调模型**，复用库里那份方案。
+ * - 知识或来源标题路径改变 → 指纹变化 → 重排这一张卡（也只重排这一张）。
  *
  * 少了它，每次编译都会把每张卡重排一遍：模型会给出**不一样**的排版，于是「重编一次、
  * 没变的卡片不产生写入」这条增量承诺失效，而人看到的是卡片莫名其妙地换了样子。
  */
-export function layoutHash(input: { knowledgeIds: string[]; profileId: string; version?: number }): string {
+export function layoutHash(input: { knowledgeIds: string[]; profileId: string; knowledgeContext?: string[]; version?: number }): string {
   const ids = [...input.knowledgeIds].sort()
+  const context = [...(input.knowledgeContext ?? [])].sort()
   return createHash('sha256')
-    .update(`v${input.version ?? ORGANIZE_VERSION}\u0001${input.profileId}\u0001${ids.join('\u0001')}`, 'utf8')
+    .update(`v${input.version ?? ORGANIZE_VERSION}\u0001${input.profileId}\u0001${ids.join('\u0001')}\u0001${context.join('\u0001')}`, 'utf8')
     .digest('hex')
     .slice(0, 16)
 }
@@ -734,12 +704,36 @@ export function layoutHash(input: { knowledgeIds: string[]; profileId: string; v
  * `origin` 是 `'fallback'` 时**下次编译会重试**：模型不可用是暂时的，而一次失败不该
  * 把这张卡永久钉在确定性布局上。代价是失败会重复花钱 —— 所以只在真的调用过之后才写。
  */
+export interface SectionRecord {
+  id: string
+  title: string
+  retrievalNeed: string
+  knowledgeIds: string[]
+}
+
+/** Stable identity follows the retrieval need and supporting Knowledge, never section order. */
+export function sectionRecords(plan: OrganizePlan, previous: SectionRecord[] = []): SectionRecord[] {
+  const used = new Set<string>()
+  return plan.sections.map(section => {
+    const knowledgeIds = [...new Set(section.blocks.flatMap(block => blockTexts(block).flatMap(citationsIn)))].sort()
+    const candidates = previous.filter(old => !used.has(old.id)).map(old => ({ old,
+      overlap: old.knowledgeIds.filter(id => knowledgeIds.includes(id)).length,
+      sameTitle: old.title === section.title,
+    })).filter(item => item.sameTitle || item.overlap > 0).sort((a, b) => Number(b.sameTitle) - Number(a.sameTitle) || b.overlap - a.overlap)
+    const matched = candidates.find(item => item.old.id === section.sectionId) ?? candidates[0]
+    const id = matched?.old.id ?? `sec_${createHash('sha256').update(JSON.stringify([knowledgeIds, section.retrievalNeed ?? section.title])).digest('hex').slice(0, 16)}`
+    used.add(id)
+    return { id, title: section.title, retrievalNeed: section.retrievalNeed ?? section.title, knowledgeIds }
+  })
+}
+
 export interface CardLayoutRecord {
   /** 排序时用的骨架 id。骨架换了，小节名就该重排。 */
   profile: string
   /** `layoutHash()` 的结果。相同 = 知识集合没变 = 不重排。 */
   hash: string
   origin: 'model' | 'fallback'
+  sections?: SectionRecord[]
 }
 
 /**
@@ -776,7 +770,7 @@ export function layoutOf(metadata: Record<string, unknown> | undefined): CardLay
   const profile = typeof record.profile === 'string' ? record.profile : ''
   const origin = record.origin === 'model' || record.origin === 'fallback' ? record.origin : undefined
   if (hash === '' || origin === undefined) return undefined
-  return { hash, profile, origin }
+  return { hash, profile, origin, ...(Array.isArray(record.sections) ? { sections: record.sections as SectionRecord[] } : {}) }
 }
 
 /**