dsh-data-domain-knowledge 0.1.1-alpha.2 → 0.1.1-alpha.4

package/src/settings-volatile.ts

@@ -93,13 +93,6 @@ export function unwrapVolatile<T>(value: unknown): T | undefined {
  * `knowledge` / `convert` / `behaviorRules` 三组），而只解一层的结果是「组本身还是原始对象、
  * 组里的字段还是引用」。
  *
- * 0029 实测到的故障就是这样来的：`intent` 组被原样交给 `applyIntent`，于是
- * `engine.settings.predicates` 是一个 `{get, write}` 引用而不是字符串数组，
- * `routingPrompt()` 里那句 `predicates.join('、')` 抛
- * `this.settings.predicates.join is not a function`。抛出点在 **preset 的挂载行**上，
- * 所以整个 preset 组合不出会话 —— 宿主平面没事（它在 apply 时不读谓词），一个字段
- * 的类型错误把 preset 打挂。
- *
  * ## 为什么是两层而不是把 `unwrapVolatile` 写成递归
  *
  * 多出来的那一层是**已知的、唯一的一层**：组 → 字段。递归会把「数组里的对象恰好

package/src/source-identity.ts

@@ -0,0 +1,85 @@
+/** Source IDs are opaque, scoped by knowledge base, and independent of names, locations and content. */
+export function isSourceId(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-zA-Z0-9._:-]{1,160}$/.test(value)
+}
+
+/** Allocate once when an input joins the import queue; retries and conversions keep this ID. */
+export function newSourceId(): string {
+  return `src_${globalThis.crypto.randomUUID()}`
+}
+
+/** Explicit acquisition identity; never inferred from document body or an arbitrary external_id. */
+export interface SourceIdentityInput {
+  url?: string
+  system?: string
+  scope?: string
+  documentType?: string
+  documentId?: string
+  /** Snake-case names accepted by Agent/HTTP callers. */
+  document_id?: string
+  document_type?: string
+}
+export interface SourceIdentity {
+  system: string
+  scope: string
+  documentType: string
+  documentId: string
+  rule: 'native-v1' | 'google-docs-v1' | 'feishu-v1' | 'url-v1'
+  url?: string
+}
+export class SourceIdentityError extends Error {
+  constructor(readonly code: string, message: string, readonly candidates: string[] = []) { super(message) }
+}
+export function sourceIdentityKey(value: SourceIdentity): string {
+  return JSON.stringify([value.system, value.scope, value.documentType, value.documentId])
+}
+
+/** WHATWG URL only: preserve query order, fragments, trailing slashes and protocol. No network/redirect inference. */
+export function normalizeSourceUrl(value: string): URL {
+  let url: URL
+  try { url = new URL(value) } catch { throw new SourceIdentityError('SOURCE_IDENTITY_INVALID', '来源 URL 必须是完整的 HTTP(S) 地址。') }
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || value.length > 8192) throw new SourceIdentityError('SOURCE_IDENTITY_INVALID', '来源 URL 必须为 HTTP(S)，且不能包含用户名或密码。')
+  return url
+}
+
+/** Known document links only. Unknown query parameters / fragments fall back to exact URL identity. */
+function platformIdentity(url: URL, scope?: string): SourceIdentity | undefined {
+  if (url.hash || url.port) return undefined
+  // These explicit tracking parameters do not select a document or its version. All others are retained via URL fallback.
+  if ([...url.searchParams.keys()].some(key => !['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'].includes(key))) return undefined
+  if (url.hostname === 'docs.google.com') {
+    const match = /^\/document\/(?:u\/\d+\/)?d\/([a-zA-Z0-9_-]+)(?:\/(?:edit|view|preview))?\/?$/.exec(url.pathname)
+    if (match) return { system: 'google-docs', scope: scope ?? url.origin, documentType: 'document', documentId: match[1]!, rule: 'google-docs-v1', url: url.href }
+  }
+  if (url.hostname.endsWith('.feishu.cn') || url.hostname.endsWith('.larksuite.com')) {
+    const match = /^\/(docx|docs|wiki)\/([a-zA-Z0-9]+)\/?$/.exec(url.pathname)
+    if (match) return { system: url.hostname.endsWith('.feishu.cn') ? 'feishu' : 'lark', scope: scope ?? url.origin,
+      documentType: match[1] === 'wiki' ? 'wiki-node' : match[1] === 'docs' ? 'doc' : 'docx', documentId: match[2]!, rule: 'feishu-v1', url: url.href }
+  }
+  return undefined
+}
+
+/** First entry is the primary identity; additional entries are verified URL aliases of that same identity. */
+export function resolveSourceIdentities(input: SourceIdentityInput): SourceIdentity[] {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new SourceIdentityError('SOURCE_IDENTITY_INVALID', 'source_identity 必须为对象。')
+  if ((input.documentId !== undefined && input.document_id !== undefined && input.documentId !== input.document_id) || (input.documentType !== undefined && input.document_type !== undefined && input.documentType !== input.document_type)) throw new SourceIdentityError('SOURCE_IDENTITY_INVALID', '平台文档身份的同名参数不能冲突。')
+  input = { ...input, documentId: input.documentId ?? input.document_id, documentType: input.documentType ?? input.document_type }
+  for (const key of ['url', 'system', 'scope', 'documentType', 'documentId'] as const) {
+    const value = input[key]
+    if (value !== undefined && (typeof value !== 'string' || !value.trim() || value !== value.trim() || value.length > (key === 'url' ? 8192 : 2048))) throw new SourceIdentityError('SOURCE_IDENTITY_INVALID', `source_identity.${key} 必须为非空、无首尾空格的字符串。`)
+  }
+  const url = input.url ? normalizeSourceUrl(input.url) : undefined
+  const parsed = url ? platformIdentity(url, input.scope) : undefined
+  const native = input.documentId !== undefined || input.system !== undefined || input.documentType !== undefined
+  const urlIdentity = url ? { system: 'web', scope: input.scope ?? url.origin, documentType: 'url', documentId: url.href, rule: 'url-v1' as const, url: url.href } : undefined
+  if (native) {
+    if (!input.system || !input.scope || !input.documentId) throw new SourceIdentityError('SOURCE_IDENTITY_INVALID', '平台身份必须同时提供 system、scope 和 document_id。')
+    const identity: SourceIdentity = { system: input.system.toLowerCase(), scope: input.scope, documentType: input.documentType ?? 'document', documentId: input.documentId, rule: 'native-v1', ...(url ? { url: url.href } : {}) }
+    if (parsed && sourceIdentityKey(identity) !== sourceIdentityKey(parsed)) throw new SourceIdentityError('SOURCE_ORIGIN_CONFLICT', '平台文档 ID 与链接解析结果不一致。')
+    // An unknown URL is provenance only: it does not prove an alias for a native resource.
+    return parsed && urlIdentity ? [identity, urlIdentity] : [identity]
+  }
+  if (parsed && urlIdentity) return [parsed, urlIdentity]
+  if (urlIdentity) return [urlIdentity]
+  throw new SourceIdentityError('SOURCE_IDENTITY_INVALID', '请提供 url，或完整的平台文档身份。')
+}

package/src/source-read.ts

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto'
+import type { KnowledgeDb } from './store/knowledge-db.js'
+import { isSourceId } from './source-identity.js'
+import { locateQuote } from './wiki-trial.js'
+
+export interface SourceReadInput {
+  sourceId: string
+  version?: number
+  contentHash?: string
+  start?: number
+  end?: number
+  quote?: string
+  offset?: number
+  maxChars?: number
+}
+export class SourceReadError extends Error {
+  constructor(readonly code: string, message: string) { super(message) }
+}
+/** Source ID identifies the document; the integer version pins its body; ranges use UTF-16, end exclusive. */
+export function readSourceExact(db: KnowledgeDb, input: SourceReadInput): Record<string, unknown> {
+  const fail = (code: string, message: string): never => { throw new SourceReadError(code, message) }
+  if (!isSourceId(input.sourceId)) return fail('SOURCE_ID_INVALID', 'source_id 必须为已返回的完整合法 ID。')
+  const current = db.source(input.sourceId)
+  if (!current) return fail('SOURCE_NOT_FOUND', 'source_id 不存在或已删除；不会回退到标题或正文搜索。')
+  const version = input.version ?? current.version
+  if (!Number.isInteger(version) || version < 1) return fail('SOURCE_VERSION_INVALID', 'version 必须为正整数。')
+  const revision = db.revisionBody('source', input.sourceId, version)
+  if (!revision) return fail('SOURCE_VERSION_NOT_FOUND', '指定来源版本不可用；不会改读最新版。')
+  const text = revision.body
+  const contentHash = createHash('sha256').update(text).digest('hex')
+  if (input.contentHash !== undefined && input.contentHash !== contentHash && input.contentHash !== contentHash.slice(0, 24)) return fail('SOURCE_HASH_MISMATCH', '指定版本的正文哈希与引用不一致。')
+  if (input.quote !== undefined && (typeof input.quote !== 'string' || !input.quote.trim())) return fail('SOURCE_QUOTE_INVALID', 'quote 必须为非空原文引文。')
+  const located = input.quote === undefined ? undefined : locateQuote(text, input.quote)
+  if (located && !located.found) return fail('SOURCE_QUOTE_MISMATCH', '引文不在指定版本中。')
+  const start = input.start ?? (input.end === undefined ? located?.locator?.start : undefined) ?? 0
+  const end = input.end ?? (input.start === undefined ? located?.locator?.end : undefined) ?? text.length
+  const offset = input.offset ?? 0, maxChars = input.maxChars ?? 20000
+  if (![start, end, offset, maxChars].every(Number.isInteger) || start < 0 || end < start || end > text.length || offset < 0 || offset > end - start || maxChars < 1 || maxChars > 40000) return fail('SOURCE_RANGE_INVALID', '范围必须满足 0 ≤ start ≤ end ≤ 正文长度；offset 为范围内偏移，max_chars 为 1–40000。')
+  if (input.quote && !locateQuote(text.slice(start, end), input.quote).found) return fail('SOURCE_QUOTE_MISMATCH', '指定范围与引文不匹配。')
+  const from = start + offset, to = Math.min(end, from + maxChars), truncated = to < end
+  const readRef = { source_id: input.sourceId, version, content_hash: contentHash, start, end }
+  return { sourceId: input.sourceId, title: String(revision.frontmatter.title ?? current.record.title), version, currentVersion: current.version,
+    historical: version !== current.version, contentHash, content: text.slice(from, to), start: from, end: to, rangeStart: start, rangeEnd: end,
+    offset, returnedChars: to - from, totalChars: text.length, truncated, nextOffset: truncated ? offset + to - from : null, readRef,
+    ...(truncated ? { nextRead: { tool: 'query_source_truth', args: { ...readRef, offset: offset + to - from, max_chars: maxChars } } } : {}),
+  }
+}

package/src/store/axis-references.ts

@@ -15,13 +15,14 @@ export function redirectAxisReferences(db: KnowledgeDb, kind: AxisKind, fromId:
   if (hasKnowledge) db.raw(`UPDATE knowledge SET ${column} = ?, updated_at = ? WHERE ${column} = ?`).run(intoId, new Date().toISOString(), fromId)
   const placements = db.placements()
   const cards = db.cards()
-  const byCoordinate = new Map(cards.filter(row => row.card.coordinate).map(row => [cardCoordinateKey(row.card.coordinate!), row]))
+  const wikiKind = (card: typeof cards[number]['card']) => card.metadata.wiki_kind === 'fact' || card.metadata.wiki_kind === 'way' ? card.metadata.wiki_kind : undefined
+  const byCoordinate = new Map(cards.filter(row => row.card.coordinate).map(row => [cardCoordinateKey(row.card.coordinate!, wikiKind(row.card)), row]))
   db.transact({ opId: `axis-merge:${fromId}:${intoId}:${Date.now()}`, actor: 'user', summary: '合并轴实体并迁移知识、卡片与事件引用' }, tx => {
     for (const row of cards) {
       const coordinate = row.card.coordinate
       if (!coordinate || coordinate[field] !== fromId) continue
       const next = redirect(coordinate)
-      const key = cardCoordinateKey(next)
+      const key = cardCoordinateKey(next, wikiKind(row.card))
       const target = byCoordinate.get(key)
       const base = target && target.card.entityId !== row.card.entityId ? target : row
       const merged = base !== row
@@ -32,6 +33,7 @@ export function redirectAxisReferences(db: KnowledgeDb, kind: AxisKind, fromId:
         sourceRefs: [...new Set([...base.card.sourceRefs, ...row.card.sourceRefs])],
         annotations: [...new Map([...(base.card.annotations ?? []), ...(row.card.annotations ?? [])].map(annotation => [annotation.id, annotation])).values()],
         metadata: { ...base.card.metadata, layout: undefined, citations: undefined,
+          knowledge_versions: { ...(row.card.metadata.knowledge_versions as Record<string, number> ?? {}), ...(base.card.metadata.knowledge_versions as Record<string, number> ?? {}) },
           aliases: [...new Set([...(Array.isArray(base.card.metadata.aliases) ? base.card.metadata.aliases : []), ...(Array.isArray(row.card.metadata.aliases) ? row.card.metadata.aliases : []), base.card.title, row.card.title])],
           ...(eventRefs.length ? { event_refs: JSON.stringify(eventRefs) } : {}) },
       }
@@ -41,7 +43,7 @@ export function redirectAxisReferences(db: KnowledgeDb, kind: AxisKind, fromId:
       const frontmatter = { ...base.frontmatter, coordinate: { object: next.objectId, action: next.actionId, scene: next.sceneId }, source_refs: card.sourceRefs, metadata: card.metadata, annotations: card.annotations }
       tx.putCard(card, frontmatter, { actor: 'user', kind: 'named', summary: '轴合并后的卡片引用' }, combined, true)
       db.setCardEvents(card.entityId, eventRefs)
-      byCoordinate.delete(cardCoordinateKey(coordinate))
+      byCoordinate.delete(cardCoordinateKey(coordinate, wikiKind(row.card)))
       byCoordinate.set(key, { ...base, card, frontmatter })
       placements.set(card.entityId, combined)
     }

package/src/store/knowledge-db.ts

@@ -1,3 +1,4 @@
+import { SourceIdentityError, type SourceIdentity } from '../source-identity.js'
 /**
  * 知识库文件（`<库 id>/knowledge.db`）：**正文、版本、血缘的唯一存储**。
  *
@@ -54,7 +55,7 @@ export const KNOWLEDGE_DB_APPLICATION_ID = 0x544B4244
  * 旧库会在打开时做一次**事务化就地迁移**。知识库是用户数据，不能因为存储层增加了
  * 一列或调整了主键就要求用户重新导入；只有比当前版本更新的库才拒绝打开。
  */
-export const KNOWLEDGE_DB_SCHEMA = 7
+export const KNOWLEDGE_DB_SCHEMA = 9
 
 /** 实体种类。`knowledge` 与轴注册表不走这张表（它们各有自己的表，见 §3.2）。 */
 export type EntityKind = 'source' | 'card'
@@ -264,6 +265,16 @@ CREATE TABLE IF NOT EXISTS card_event (
 CREATE INDEX IF NOT EXISTS card_event_event_idx ON card_event(event_id);
 `
 
+const SOURCE_IDENTITY_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS source_identity (
+  system TEXT NOT NULL, scope TEXT NOT NULL, document_type TEXT NOT NULL, document_id TEXT NOT NULL,
+  source_id TEXT NOT NULL, rule TEXT NOT NULL, url TEXT,
+  PRIMARY KEY(system, scope, document_type, document_id)
+);
+CREATE INDEX IF NOT EXISTS source_identity_source ON source_identity(source_id);
+CREATE UNIQUE INDEX IF NOT EXISTS source_identity_primary ON source_identity(source_id) WHERE rule <> 'url-v1';
+`
+
 function schemaSql(): string {
   return `
 CREATE TABLE IF NOT EXISTS blob (
@@ -286,6 +297,8 @@ CREATE TABLE IF NOT EXISTS source (
   original_bytes  INTEGER
 );
 
+${SOURCE_IDENTITY_SCHEMA_SQL}
+
 CREATE TABLE IF NOT EXISTS card (
   -- 坐标是卡片身份。entity_id 是旧接口、版本和关联表继续使用的稳定别名。
   coordinate_key TEXT PRIMARY KEY NOT NULL,
@@ -566,6 +579,12 @@ function migrateSchema(db: SqliteDatabase, fromVersion: number): void {
 
   db.exec('BEGIN IMMEDIATE')
   try {
+    if (fromVersion === 8) {
+      db.exec(SOURCE_IDENTITY_SCHEMA_SQL)
+      db.exec(`PRAGMA user_version = ${KNOWLEDGE_DB_SCHEMA}`)
+      db.exec('COMMIT')
+      return
+    }
     addColumnIfMissing(db, 'blob', 'bytes', '"bytes" INTEGER NOT NULL DEFAULT 0')
     rebuildSourceTableForSchemaMigration(db)
     addColumnIfMissing(db, 'source', 'original_rel', '"original_rel" TEXT')
@@ -581,6 +600,18 @@ function migrateSchema(db: SqliteDatabase, fromVersion: number): void {
 
     // 其他模块可能已经先建了自己的表；schemaSql 使用 IF NOT EXISTS，可安全补齐剩余结构和索引。
     db.exec(schemaSql())
+    // Rekey typed Wiki rows without changing entity IDs, content, reviews or revisions.
+    const wikiRows = db.prepare('SELECT entity_id,coordinate_key,object_id,action_id,scene_id,frontmatter FROM card').all() as Array<Record<string, unknown>>
+    for (const row of wikiRows) {
+      const metadata = parseFrontmatter(String(row.frontmatter)).metadata as Record<string, unknown> | undefined
+      const kind = metadata?.wiki_kind
+      const coordinate = coordinateOfRow(row)
+      if (!coordinate || (kind !== 'fact' && kind !== 'way')) continue
+      const key = cardCoordinateKey(coordinate, kind)
+      const holder = db.prepare('SELECT entity_id FROM card WHERE coordinate_key=?').get(key) as { entity_id: string } | undefined
+      if (holder && holder.entity_id !== row.entity_id) continue
+      db.prepare('UPDATE card SET coordinate_key=? WHERE entity_id=?').run(key, String(row.entity_id))
+    }
     db.exec(`PRAGMA application_id = ${KNOWLEDGE_DB_APPLICATION_ID}`)
     db.exec(`PRAGMA user_version = ${KNOWLEDGE_DB_SCHEMA}`)
     db.exec('COMMIT')
@@ -719,6 +750,14 @@ export class KnowledgeTx {
     })
   }
 
+  bindSourceIdentity(identity: SourceIdentity, sourceId: string): void {
+    if (!this.db.source(sourceId)) throw new SourceIdentityError('SOURCE_ORIGIN_UNAVAILABLE', '身份绑定的来源必须存在。', [sourceId])
+    const owner = this.db.sourceIdByIdentity(identity)
+    if (owner && owner !== sourceId) throw new SourceIdentityError('SOURCE_ORIGIN_CONFLICT', '来源身份已绑定另一份文档。', [owner, sourceId])
+    this.raw('INSERT INTO source_identity(system,scope,document_type,document_id,source_id,rule,url) VALUES (?,?,?,?,?,?,?) ON CONFLICT(system,scope,document_type,document_id) DO NOTHING')
+      .run(identity.system, identity.scope, identity.documentType, identity.documentId, sourceId, identity.rule, identity.url ?? null)
+  }
+
   /**
    * 写一张卡片。判据同样是正文哈希。
    *
@@ -736,7 +775,7 @@ export class KnowledgeTx {
       const storedCoordinate = card.coordinate ?? (existing === undefined ? undefined : coordinateOfRow(existing))
       const coordinateKey = storedCoordinate === undefined
         ? legacyCardStorageKey(card.entityId)
-        : cardCoordinateKey(storedCoordinate)
+        : cardCoordinateKey(storedCoordinate, card.metadata.wiki_kind === 'fact' || card.metadata.wiki_kind === 'way' ? card.metadata.wiki_kind : undefined)
       const oldKey = typeof existing?.coordinate_key === 'string' ? existing.coordinate_key : undefined
       if (existing !== undefined) {
         if (!allowCoordinateMove && oldKey !== undefined && oldKey !== coordinateKey && !oldKey.startsWith('legacy:')) {
@@ -840,6 +879,8 @@ export class KnowledgeTx {
   /** 删实体本体。**`revision` 行与 `blob` 不动** —— 删除即灭史是 0062 之前的缺陷 5。 */
   removeEntity(kind: EntityKind, id: string): void {
     this.raw(`DELETE FROM ${kind === 'source' ? 'source' : 'card'} WHERE entity_id = ?`).run(id)
+    if (kind === 'source') this.raw('DELETE FROM source_identity WHERE source_id=?').run(id)
+    if (kind === 'source' && tableExists(this.db.connection(), 'pipeline_chunks')) this.raw('DELETE FROM pipeline_chunks WHERE source_id=?').run(id)
     this.raw('DELETE FROM entity_asset WHERE entity_kind = ? AND entity_id = ?').run(kind, id)
     /*
      * 卡片的知识落位跟着走（0069）。这里没有外键，所以它是**代码责任** —— 漏掉的话，
@@ -890,6 +931,7 @@ export class KnowledgeDb {
     let db: SqliteDatabase
     try {
       db = new DatabaseSync(file)
+      db.exec('PRAGMA busy_timeout = 5000')
     } catch (cause) {
       return { ok: false, code: 'OPEN_FAILED', message: `打开失败：${cause instanceof Error ? cause.message : String(cause)}` }
     }
@@ -1217,6 +1259,16 @@ export class KnowledgeDb {
     return typeof row?.entity_id === 'string' ? row.entity_id : undefined
   }
 
+  sourceIdByIdentity(identity: SourceIdentity): string | undefined {
+    const row = this.raw('SELECT source_id FROM source_identity WHERE system=? AND scope=? AND document_type=? AND document_id=?')
+      .get(identity.system, identity.scope, identity.documentType, identity.documentId) as { source_id: string } | undefined
+    return row?.source_id
+  }
+  sourceIdentities(sourceId: string): SourceIdentity[] {
+    const rows = this.raw('SELECT * FROM source_identity WHERE source_id=? ORDER BY system,scope,document_type,document_id').all(sourceId) as Array<Record<string, string>>
+    return rows.map(row => ({ system: row.system!, scope: row.scope!, documentType: row.document_type!, documentId: row.document_id!, rule: row.rule as SourceIdentity['rule'], ...(row.url ? { url: row.url } : {}) }))
+  }
+
   card(id: string): CardRecord | undefined {
     return (this.readEntities('card', id) as CardRecord[])[0]
   }

package/src/store/source-identity.ts

@@ -0,0 +1,42 @@
+import { SourceIdentityError, newSourceId, resolveSourceIdentities, sourceIdentityKey, type SourceIdentity } from '../source-identity.js'
+import type { KnowledgeDb } from './knowledge-db.js'
+
+/** Old conversion URLs may already be lossy canonical URLs; they are candidates, not automatic identity proof. */
+function legacyIdentities(db: KnowledgeDb, id: string): SourceIdentity[] {
+  const source = db.source(id)
+  if (!source) return []
+  const stored = source.frontmatter
+  const metadata = source.record.metadata
+  const generated = stored.generated as { by?: unknown } | undefined
+  if (metadata.source_format !== 'web_page' || typeof generated?.by !== 'string' || !generated.by.startsWith('convert/') || typeof stored.resource !== 'string') return []
+  try { return resolveSourceIdentities({ url: stored.resource }) } catch { return [] }
+}
+
+/** Called inside KnowledgeDb.transact, after its first write has acquired SQLite's writer lock. */
+export function chooseSourceId(db: KnowledgeDb, proposedId: string | undefined, incoming: SourceIdentity[]): { sourceId: string; reused: boolean } {
+  if (!incoming.length) return { sourceId: proposedId ?? newSourceId(), reused: proposedId !== undefined && !!db.source(proposedId) }
+  const primary = incoming[0]!, primaryKey = sourceIdentityKey(primary)
+  const owners = new Set(incoming.map(identity => db.sourceIdByIdentity(identity)).filter((id): id is string => !!id))
+  const proposed = proposedId === undefined ? undefined : db.source(proposedId)
+  if (owners.size > 1) throw new SourceIdentityError('SOURCE_ORIGIN_CONFLICT', '平台 ID 与 URL 映射到不同来源，未自动合并。', [...owners])
+  if (proposed) {
+    const registered = db.sourceIdentities(proposedId!)
+    const primaryBindings = registered.filter(identity => identity.rule !== 'url-v1')
+    const samePrimary = registered.some(identity => sourceIdentityKey(identity) === primaryKey)
+    const sameAlias = registered.some(identity => incoming.some(value => sourceIdentityKey(value) === sourceIdentityKey(identity)))
+    if (!samePrimary && (primaryBindings.length > 0 || (registered.some(identity => identity.rule === 'url-v1') && !sameAlias))) throw new SourceIdentityError('SOURCE_ORIGIN_CONFLICT', 'source_id 已属于另一份文档，不能改变来源身份。', [proposedId!])
+    if (owners.size && !owners.has(proposedId!)) throw new SourceIdentityError('SOURCE_ORIGIN_CONFLICT', '已知 source_id 与来源映射冲突。', [proposedId!, ...owners])
+  }
+  if (!owners.size) {
+    // Existing IDs and content are never rewritten by migration. An explicit known ID can confirm a legacy candidate.
+    const rows = db.raw("SELECT entity_id FROM source WHERE json_extract(frontmatter,'$.metadata.source_format')='web_page' AND entity_id NOT IN (SELECT source_id FROM source_identity)").all() as Array<{ entity_id: string }>
+    const candidates = rows.filter(row => legacyIdentities(db, row.entity_id).some(identity => sourceIdentityKey(identity) === primaryKey)).map(row => row.entity_id)
+    if (proposed && proposedId && candidates.includes(proposedId)) owners.add(proposedId)
+    else if (candidates.length > 1) throw new SourceIdentityError('SOURCE_ORIGIN_AMBIGUOUS', '多份历史来源使用同一文档地址，请明确选择已有 source_id。', candidates)
+    else if (candidates[0]) throw new SourceIdentityError('SOURCE_ORIGIN_UNCONFIRMED', '历史地址尚无已确认映射；请核对候选后明确传其 source_id，不能仅凭旧 canonical 地址自动覆盖。', candidates)
+  }
+  const owner = [...owners][0]
+  if (owner && proposedId !== undefined && owner !== proposedId && (proposed || db.versions('source', proposedId).length)) throw new SourceIdentityError('SOURCE_ORIGIN_CONFLICT', '已有 source_id 与来源映射指向不同文档。', [proposedId, owner])
+  if (owner && !db.source(owner)) throw new SourceIdentityError('SOURCE_ORIGIN_UNAVAILABLE', '来源映射对应的文档已不可用。', [owner])
+  return { sourceId: owner ?? proposedId ?? newSourceId(), reused: !!owner || !!proposed }
+}

package/src/types.ts

@@ -1,4 +1,6 @@
+import { wikiGroupKey, type WikiKind } from './knowledge-contract.js'
 import { DIAGNOSIS_ENTITY_TYPES } from './diagnosis/schema.js'
+import type { ExtractionTimeoutMinutes } from './pipeline/types.js'
 
 /** Wiki Card 自己的生命周期。它描述卡片是否可展示、是否被审核或是否有编译问题。 */
 export type CardStatus = 'unreviewed' | 'draft' | 'reviewed' | 'active' | 'deprecated' | 'problem'
@@ -27,6 +29,8 @@ export type RerankProvider = 'bert-python' | 'none'
 export type CompileModelMode = 'default' | 'fixed'
 export interface CompileModelSelection {
   reasoningEffort?: string
+  /** Per-request output cap in tokens. Omitted means the selected model's default. */
+  maxTokens?: number
   mode: CompileModelMode
   provider?: string
   model?: string
@@ -298,6 +302,8 @@ export interface SourceRaw {
  * **真实文件**，读它与读这里的内容是同一份数据。
  */
 export interface SourceRawRead extends SourceRaw {
+  version?: number
+  readRef?: { kb?: string; source_id: string; version?: number; content_hash?: string }
   /**
    * 这份来源在磁盘上的绝对路径。
    *
@@ -382,10 +388,11 @@ export interface CardCoordinate {
 /**
  * 卡片的存储主键。
  *
- * `entityId` 仍是旧接口与版本表使用的稳定别名；真正决定一张有坐标卡片身份的，
- * 是这三个轴实体 id。加前缀是为了把「坐标主键」和「未绑定坐标的存量卡片」分开。
+ * `entityId` 是读取与版本表使用的稳定 ID。类型化 Wiki 由 Wiki 类型和完整三轴共同
+ * 确定身份；未指定类型时保留旧坐标键，供存量卡片兼容使用。知识库由所在数据库隔离。
  */
-export function cardCoordinateKey(coordinate: CardCoordinate): string {
+export function cardCoordinateKey(coordinate: CardCoordinate, kind?: WikiKind): string {
+  if (kind) return wikiGroupKey(kind, coordinate)
   return `coord:${coordinate.objectId}\u0001${coordinate.actionId}\u0001${coordinate.sceneId}`
 }
 
@@ -527,6 +534,7 @@ export interface SearchHit extends WikiNote {
  * 成立，而不是靠模型自觉。
  */
 export interface RecallEvidence {
+  readRef?: { kb?: string; source_id: string; version?: number; content_hash?: string; quote?: string }
   sourceId: string
   title?: string
   /** 覆盖查询词最多的那一段原文（已按上限截断）。 */
@@ -575,6 +583,7 @@ export interface RecallKnowledge {
   /** 出处：原文里原样复制的那一段。 */
   quote?: string
   sourceId?: string
+  readRef?: { kb?: string; source_id: string; version?: number; start?: number; end?: number; quote?: string }
   headingPath?: string[]
   /** 已经被并进哪一条。空串或缺省 = 它自己就是保留的那条。 */
   mergedInto?: string
@@ -788,10 +797,13 @@ export interface ContextBudgetReport {
   expandedCards: number
   /** 溢出文件的绝对路径（有溢出时才有；它在系统临时目录里，不随库走）。 */
   overflowPath?: string
+  omitted?: Array<{ target: string; title: string; requiredChars: number; read: { tool: string; args: { kb?: string; target: string } } }>
 }
 
 export interface RecallResult {
-  /** Stage 3: 融合（+ 重排）之后的 wikiNotes，最多 `recallTopK`。 */
+  foundCandidates?: boolean
+  contentDelivered?: boolean
+  /** Stage 3: 每篇 Wiki 的最佳章节，最多 `recallTopK` 篇；其他匹配章节在 context[].notes。 */
   hits: RecallHit[]
   /** Stage 4: the `contextTopN` notes expanded to their wiki + 1-hop graph. */
   context: ContextItem[]
@@ -839,7 +851,7 @@ export interface RecallResult {
   /** 各阶段耗时（毫秒）。它很小，所以不藏在 `detail` 后面 —— Agent 也会问「为什么慢」。 */
   timings?: RecallTimings
   recallId: string
-  /** 查询侧的意图与 OAS 解析结果，供诊断和召回解释使用。 */
+  /** 查询侧的 OAS 坐标解析结果，供诊断和召回解释使用。 */
   queryAnalysis?: import('./query-analysis.js').QueryAnalysis
   indexVersion?: number
   compileRunId?: string
@@ -871,6 +883,7 @@ export interface KnowledgeBase {
   extractionNote: string
   /** 编译模型路由：默认跟随 DSH，或固定到模型目录中的一项。 */
   compileModel: CompileModelSelection
+  extractionTimeoutMinutes: ExtractionTimeoutMinutes
   createdAt: string
   updatedAt: string
   sourceCount: number

package/src/wiki-availability.ts

@@ -0,0 +1,37 @@
+import type { Knowledge } from './knowledge.js'
+import type { CardKnowledgeRow } from './store/knowledge-db.js'
+import type { KnowledgeCard } from './types.js'
+
+export interface WikiTruth {
+  knowledge: ReadonlyMap<string, Knowledge>
+  sources: ReadonlyMap<string, number>
+  caseVersion(id: string): number | undefined
+}
+
+/** The saved Wiki generation, rather than the index build time, binds its supporting versions. */
+export function wikiUnavailableReason(card: KnowledgeCard, placements: readonly CardKnowledgeRow[], truth: WikiTruth): string | undefined {
+  if (card.status === 'deprecated') return '该 Wiki 已停用。'
+  if (card.sourceRefs.some(id => !truth.sources.has(id))) return '支撑该 Wiki 的 Source Raw 已缺失。'
+  const kind = card.metadata.wiki_kind
+  if (kind !== 'fact' && kind !== 'way') return undefined
+  if (card.metadata.wiki_coordinate_version !== 2) return '该 Wiki 仍使用旧聚合规则，请先重新组织 Wiki。'
+  const versions = card.metadata.knowledge_versions as Record<string, number> | undefined
+  const ids = new Set([...placements.map(item => item.knowledgeId), ...Object.keys(versions ?? {})])
+  if (kind === 'way' && ids.size === 0) return '方法缺少知识落位与版本依据，请重新组织 Wiki。'
+  for (const id of ids) {
+    const row = truth.knowledge.get(id)
+    if (!row || row.mergedInto || row.status === 'deprecated') return '支撑知识已撤回、合并或停用，请重新组织 Wiki。'
+    if ((row.kind ?? 'fact') !== (kind === 'way' ? 'procedure' : 'fact')) return 'Wiki 类型与支撑知识不一致，请重新组织 Wiki。'
+    if ((versions?.[id] !== undefined && versions[id] !== row.version) || (kind === 'way' && versions?.[id] === undefined)) return '支撑知识内容版本已变化，请重新组织 Wiki。'
+    if (card.coordinate && (row.objectId !== card.coordinate.objectId || row.actionId !== card.coordinate.actionId || row.sceneId !== card.coordinate.sceneId)) return '支撑知识坐标已变化，请重新组织 Wiki。'
+    const active = row.sources.filter(source => !source.withdrawn && (!source.documentId || truth.sources.has(source.documentId)))
+    if (!active.length) return '支撑知识的来源贡献已撤回，请重新组织 Wiki。'
+    if (kind === 'way') {
+      const method = row.data?.procedure
+      if (row.status === 'disputed' || !method || method.completeness !== 'complete' || !method.method.length
+        || method.caseRefs.some(ref => truth.caseVersion(ref.id) !== ref.version)
+        || active.some(source => source.documentId && source.toVersion !== undefined && truth.sources.get(source.documentId) !== source.toVersion)) return '支撑方法或证据版本已变化，请重新组织 Wiki。'
+    }
+  }
+  return undefined
+}

package/src/wiki-finalize.ts

@@ -9,7 +9,8 @@
  *
  * 1. **相关卡片**（`planRelated`）—— 卡片之间原来只有图上的边，卡片正文里什么都没有，
  *    人打开一张卡片看不到它跟谁有关系。现在把关系存进卡片的 `metadata.related_cards`，
- *    正文保持纯正文；面板和索引页按这份结构化数据展示。
+ *    面板和索引页按这份结构化数据展示。类型化 Wiki 的正文双链和导航另由
+ *    `wiki-links.ts` 生成，索引前剥离导航。
  * 2. **断链统计**（`deadLinksOf`）—— 为编译报告与索引页提供关系图的可见性，不修改卡片
  *    内容，也不写入卡片 metadata。
  * 3. **索引页**（`buildWikiIndex`）—— 知识库原来没有「这里有什么」的落盘入口：
@@ -24,12 +25,13 @@
  * ## 为什么只认 wiki 链接语法
  *
  * 旧相关块里写的是 `[[类型/标题|标题]]`，不是 markdown 相对链接。这个语法仍由迁移
- * 与纯函数测试保留，但新编译不再把它写进正文；正文里的 wiki 链接仍由断链检查识别。
+ * 与纯函数测试保留。新编译使用稳定 `[[类型/实体ID|显示名称]]`，正文里的有效链接
+ * 由断链检查识别；代码与 URL 内的示例不作为链接。
  *
  * @module
  */
 
-import { buildAliasIndex, candidateKey, normalizeCandidateName } from './extract.js'
+import { scanWikiLinks, wikiLinkCandidates } from './wiki-links.js'
 import type { KnowledgeCard } from './types.js'
 
 /**
@@ -89,17 +91,9 @@ export function relatedEntriesOf(metadata: Record<string, unknown> | undefined):
   })
 }
 
-/** 正文里的 wiki 链接：`[[类型/名称]]`、`[[类型/名称|显示文字]]`、`[[名称]]`。 */
-const WIKI_LINK = /\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g
-
 /** 卡片正文里出现的 wiki 链接目标（原样，未归一）。 */
 export function wikiLinkTargets(content: string): string[] {
-  const targets: string[] = []
-  for (const match of content.matchAll(WIKI_LINK)) {
-    const target = (match[1] ?? '').trim()
-    if (target) targets.push(target)
-  }
-  return targets
+  return scanWikiLinks(content).map(link => link.target)
 }
 
 /**
@@ -278,20 +272,10 @@ export interface DeadLink {
  * 会被整批报成断链。这里从最长的类型前缀开始试（即从左往右逐个 `/` 切）。
  */
 export function deadLinksOf(cards: KnowledgeCard[], index?: Map<string, KnowledgeCard>): DeadLink[] {
-  const resolved = index ?? buildAliasIndex(cards)
-  const byName = new Map<string, KnowledgeCard>()
-  for (const card of cards) {
-    for (const name of [card.entityId, card.title, ...aliasesOf(card)]) {
-      const normalized = normalizeCandidateName(name)
-      if (normalized && !byName.has(normalized)) byName.set(normalized, card)
-    }
-  }
+  void index // Retained for compatibility; all targets must resolve uniquely.
   const resolveTarget = (target: string): KnowledgeCard | undefined => {
-    for (let at = target.indexOf('/'); at > 0; at = target.indexOf('/', at + 1)) {
-      const hit = resolved.get(candidateKey({ type: target.slice(0, at), name: target.slice(at + 1) }))
-      if (hit) return hit
-    }
-    return byName.get(normalizeCandidateName(target))
+    const candidates = wikiLinkCandidates(cards, target)
+    return candidates.length === 1 ? candidates[0] : undefined
   }
   const dead: DeadLink[] = []
   for (const card of cards) {