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

package/src/runtime.ts

@@ -1,4 +1,12 @@
-import { wikiProjection, procedureText, type ProcedureContent } from './knowledge-contract.js'
+import { chooseSourceId } from './store/source-identity.js'
+import { readSourceExact, SourceReadError, type SourceReadInput } from './source-read.js'
+import { matchesScope, scopeError, type KnowledgeScope } from './retrieval/scope.js'
+import { runResumableExtraction, EXTRACTION_PLAN_VERSION } from './pipeline/resumable-extract.js'
+import { compileWikiNavigation, scanWikiLinks, stripWikiNavigation, wikiIndexContent, wikiLinkCandidates, wikiReference, type WikiReference } from './wiki-links.js'
+import { wikiProjection, wikiGroupKey, procedureText, type ProcedureContent, type WikiKind } from './knowledge-contract.js'
+import { wikiUnavailableReason } from './wiki-availability.js'
+import { SourceIdentityError, resolveSourceIdentities, normalizeSourceUrl, type SourceIdentityInput, type SourceIdentity, isSourceId } from './source-identity.js'
+import { agentContextItem } from './recall-delivery.js'
 import { buildDeriveSystem, DERIVE_CONTRACT_VERSION } from './derive-contract.js'
 import { createHash, randomUUID } from 'node:crypto'
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
@@ -34,13 +42,13 @@ import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandida
 import { skeletonBody, type ModelCall } from './extract-model.js'
 import { applyTrialAxisResolution, cardNameFor, normalizeKnowledge, runWikiTrial, trialSummary, locateQuote, type AxisPromptBlock, type TrialAxisSet, type TrialAxisSetResolution } from './wiki-trial.js'
 import { EXTRACTION_CONTRACT_VERSION } from './extract-table.js'
-import { KnowledgePipeline, type PipelineContext, type PipelineSource } from './pipeline/engine.js'
+import { KnowledgePipeline, type PipelineContext, type PipelineDeriveProgress, type PipelineSource } from './pipeline/engine.js'
 import { PipelineStore, type ExtractionCheckpoint } from './pipeline/store.js'
-import type { MaterializationGroup, PipelineStatus } from './pipeline/types.js'
+import { normalizeExtractionTimeoutMinutes, type ExtractionTimeoutMinutes, type MaterializationGroup, type PipelineItemState, type PipelineStatus } from './pipeline/types.js'
 import type { MaterializationSnapshot } from './materialize-snapshot.js'
 import { candidatesFromReport, coordinateIdsOf, coordinateIsEmpty, type MaterializedCard } from './wiki-materialize.js'
 import {
-  sectionRecords,
+  sectionRecords, ORGANIZE_VERSION,
   buildOrganizePrompt, buildOrganizeSystem, checkOrganize, citationsFrom, layoutHash, layoutOf,
   parseOrganize, placementsOf, renderFootnoteDefinitions, renderOrganizeBody,
   type CardCitationRecord, type CardLayoutRecord, type OrganizeInput, type OrganizePlan,
@@ -597,7 +605,9 @@ function recallKnowledgeOf(row: Knowledge, section: string): RecallKnowledge {
     ...(first?.toVersion === undefined ? {} : { sourceVersion: first.toVersion }),
     ...(first?.currentVersion === undefined ? {} : { currentSourceVersion: first.currentVersion }),
     ...(first?.quote ? { quote: first.quote } : {}),
-    ...(first?.documentId ? { sourceId: first.documentId } : {}),
+    ...(first?.documentId ? { sourceId: first.documentId, readRef: { source_id: first.documentId,
+      ...(first.toVersion === undefined ? {} : { version: first.toVersion }),
+      ...(first.locator ? { start: first.locator.start, end: first.locator.end } : {}), quote: first.quote } } : {}),
     ...(first && first.headingPath.length > 0 ? { headingPath: first.headingPath } : {}),
   }
 }
@@ -651,6 +661,11 @@ const NO_DELETION: DocumentDeletion = {
 }
 
 export interface ImportedSourceReport {
+  reusedSource?: boolean
+  proposedSourceId?: string
+  sourceIdentity?: SourceIdentity[]
+  version?: number
+  readRef?: { kb?: string; source_id: string; version?: number; content_hash: string }
   index: number
   sourceId: string
   title?: string
@@ -661,6 +676,7 @@ export interface ImportedSourceReport {
 
 /** 批量导入里失败的一条。**带着原因回来**，因为局部失败要求调用方能只重试那几条。 */
 export interface ImportFailure {
+  candidates?: string[]
   index: number
   title?: string
   code: string
@@ -1181,7 +1197,7 @@ function parseLineage(value: unknown): LineageContext | undefined {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
   const record = value as Record<string, unknown>
   const lineage: LineageContext = {}
-  for (const key of ['sessionId', 'turnId', 'intentId', 'taskId', 'subtaskId', 'parentSubtaskId', 'runId', 'traceId', 'domain'] as const) {
+  for (const key of ['sessionId', 'turnId', 'taskId', 'subtaskId', 'parentSubtaskId', 'runId', 'traceId', 'domain'] as const) {
     if (typeof record[key] === 'string' && record[key].trim()) lineage[key] = record[key].trim().slice(0, 160)
   }
   return Object.keys(lineage).length > 0 ? lineage : undefined
@@ -1311,7 +1327,7 @@ export function splitWikiNotes(card: Pick<KnowledgeCard, 'summary' | 'content'>)
   const sections: Array<{ heading: string; lines: string[] }> = []
   let current: { heading: string; lines: string[] } | undefined
   let fence: string | undefined
-  for (const line of card.content.trim().split('\n')) {
+  for (const line of stripWikiNavigation(card.content).trim().split('\n')) {
     const code = line.match(/^\s*(?:(?:\d+[.)]|[-+*])\s+)?(`{3,}|~{3,})(.*)$/)
     if (code) {
       if (!fence) fence = code[1]!
@@ -1776,6 +1792,7 @@ export interface KnowledgeRuntimeOptions {
    * 省略时算没有备注 —— 独立运行时与单元测试不必先造一个注册表。
    */
   extractionNote?: () => string
+  extractionTimeoutMinutes?: () => ExtractionTimeoutMinutes
   /**
    * 0029：家当目录（`<agentRoot>/resource`）。
    *
@@ -1831,6 +1848,7 @@ export interface ModelSeam {
   provider?: string
   model?: string
   reasoningEffort?: string
+  maxTokens?: number
 }
 
 /**
@@ -1862,6 +1880,7 @@ export interface CompileStepView {
   /** 这一段的计数事实，一行一条。第一条通常是进度（`读取文档 3/40`）。 */
   facts: string[]
 }
+type CompileActivityView = Omit<CompileStepView, 'id'> & { id: CompileStepId | 'publish' }
 
 export type CompileTaskState = 'queued' | 'running' | 'pausing' | 'paused' | 'cancelling' | 'succeeded' | 'failed' | 'cancelled'
 export type CompileTaskAction = 'pause' | 'resume' | 'cancel'
@@ -1997,6 +2016,7 @@ export class KnowledgeRuntime {
   readonly rootDir: string
   /** 本库的坐标提取备注（0068）。见 {@link KnowledgeRuntimeOptions.extractionNote}。 */
   private readonly extractionNoteProvider?: () => string
+  private readonly extractionTimeoutProvider?: () => ExtractionTimeoutMinutes
   /**
    * Id of the knowledge base this runtime serves. `KnowledgeBases` sets it when
    * it creates/caches a runtime; asset URLs are built from it. Standalone
@@ -2165,6 +2185,7 @@ export class KnowledgeRuntime {
     // 运行时实际在 B」这种两处说法。
     this.config = { ...DEFAULT_KNOWLEDGE_CONFIG, ...config }
     this.extractionNoteProvider = options.extractionNote
+    this.extractionTimeoutProvider = options.extractionTimeoutMinutes
     this.memoryDir = options.memoryRoot ? resolve(options.memoryRoot) : join(this.rootDir, '04_memory')
     this.staticModelCall = options.modelCall
     this.environmentGuard = options.environmentGuard
@@ -3179,8 +3200,8 @@ export class KnowledgeRuntime {
    * 每条的原因仍然在 `sources[].message` 里。
    */
   async importSources(input: {
-    sources: Array<{ title?: string; content: string; externalId?: string; metadata?: Record<string, unknown>; allowDuplicateTitle?: boolean }>
-    /** 默认编译（`only: 'wiki'`）。关掉它就只做写入，留给调用方自己决定何时编译。 */
+    sources: Array<{ sourceId?: string; expectedVersion?: number; sourceUrl?: string; sourceIdentity?: SourceIdentityInput; title?: string; content: string; externalId?: string; metadata?: Record<string, unknown>; allowDuplicateTitle?: boolean }>
+    /** 默认只保存 Source Raw；显式 true 才运行完整处理流程。 */
     compile?: boolean
     lineage?: LineageContext
   }): Promise<Envelope<ImportSourcesResult>> {
@@ -3198,9 +3219,20 @@ export class KnowledgeRuntime {
     const written: ImportedSourceReport[] = []
     const failed: ImportFailure[] = []
     const warnings: string[] = []
+    const seenSourceIds = new Set<string>()
     for (const [index, item] of items.entries()) {
+      if (item?.sourceId && seenSourceIds.has(item.sourceId)) {
+        failed.push({ index, title: item.title, code: 'SOURCE_ID_DUPLICATED_IN_BATCH', message: '同一批次中的独立输入必须使用不同 source_id。' })
+        warnings.push(`第 ${index + 1} 份来源重复使用 source_id，未写入。`)
+        continue
+      }
+      if (item?.sourceId) seenSourceIds.add(item.sourceId)
       const title = item?.title?.trim() || undefined
       const result = await this.addSource({
+        ...(item?.sourceId ? { sourceId: item.sourceId } : {}),
+        ...(item?.expectedVersion === undefined ? {} : { expectedVersion: item.expectedVersion }),
+        ...(item?.sourceUrl === undefined ? {} : { sourceUrl: item.sourceUrl }),
+        ...(item?.sourceIdentity === undefined ? {} : { sourceIdentity: item.sourceIdentity }),
         ...(title ? { title } : {}),
         content: item?.content,
         ...(item?.externalId ? { externalId: item.externalId } : {}),
@@ -3210,7 +3242,7 @@ export class KnowledgeRuntime {
       })
       if (result.ok === false) {
         const message = result.error?.message ?? '写入失败'
-        failed.push({ index, ...(title ? { title } : {}), code: result.error?.code ?? 'SOURCE_WRITE_FAILED', message })
+        failed.push({ index, ...(title ? { title } : {}), code: result.error?.code ?? 'SOURCE_WRITE_FAILED', message, candidates: result.data.candidates })
         // 逐条失败也要出现在 warnings 里：`ImportSourcesResult.failed` 是结构化账本，
         // 而 warnings 是不管谁在读都必须看见的那一句。
         warnings.push(`第 ${index + 1} 份来源${title ? `「${title}」` : ''}没有写入：${message}`)
@@ -3218,7 +3250,7 @@ export class KnowledgeRuntime {
       }
       written.push({
         index,
-        sourceId: result.data.sourceId,
+        sourceId: result.data.sourceId, version: result.data.version, readRef: result.data.readRef, reusedSource: result.data.reusedSource, proposedSourceId: result.data.proposedSourceId, sourceIdentity: result.data.sourceIdentity,
         ...(title ? { title } : {}),
         bytes: typeof item?.content === 'string' ? item.content.length : 0,
       })
@@ -3317,14 +3349,17 @@ export class KnowledgeRuntime {
     externalId?: string
     metadata?: Record<string, unknown>
     sourceId?: string
+    expectedVersion?: number
+    sourceUrl?: string
+    sourceIdentity?: SourceIdentityInput
     lineage?: LineageContext
     provenance?: SourceProvenance
     /**
      * 允许与已有的来源同标题（0051）。默认 `false`：重名是错误，拒收并要求改标题。
-     * 传 `true` 时落成 `<标题>-<内容哈希前 6 位>.md`，并回一条 warning。
+     * 传 `true` 时按各自 Source Raw ID 并存，并回一条 warning。
      */
     allowDuplicateTitle?: boolean
-  }): Promise<Envelope<{ sourceId: string; lineage?: LineageContext }>> {
+  }): Promise<Envelope<{ sourceId: string; proposedSourceId?: string; reusedSource?: boolean; sourceIdentity?: SourceIdentity[]; candidates?: string[]; possibleDuplicateIds?: string[]; version?: number; readRef?: { kb?: string; source_id: string; version?: number; content_hash: string }; lineage?: LineageContext }>> {
     if (!this.config.allowSourceTruth) return failure({ sourceId: '' }, 'SOURCE_TRUTH_DISABLED', '当前配置禁止写入 SourceTruth', false)
     if (typeof input.content !== 'string' || input.content.trim().length === 0) return failure({ sourceId: '' }, 'CONTENT_REQUIRED', 'content 不能为空', true)
     /**
@@ -3344,86 +3379,50 @@ export class KnowledgeRuntime {
     if (db === null) {
       return failure({ sourceId: '' }, 'STORE_UNAVAILABLE', this.storeProblem ?? '知识库不可用', true, '检查 Node 版本（正文进库之后需要 22.5+ 的 node:sqlite）与知识库文件的属主标记。')
     }
-    const sourceId = input.sourceId?.trim() || hash(input.externalId ?? input.content)
-    if (!SAFE_ID.test(sourceId)) return failure({ sourceId: '' }, 'SOURCE_ID_INVALID', 'source_id 含有非法字符', false)
-    const title = input.title?.trim() || sourceId
-    /**
-     * 重名（0051）：**默认拒收**。
-     *
-     * 判据从「目标路径被谁占着」换成「库里有没有人用这个标题」。文件名没有
-     * 之后看起来这条该消失，其实不该 —— 它要解决的问题不是「文件会互相覆盖」，而是
-     * 「库里有两份同名材料」这件事**必须让人知道**。所以三条出路原样保留：
-     *
-     * 1. 同一个 `sourceId`（同一份东西重复导入）→ 就是它自己，不冲突；
-     * 2. 另一个 `sourceId` 用了这个标题 → **拒收**，报错里带上「被谁占着」；
-     * 3. 调用方明确要留两份同名材料 → 传 `allowDuplicateTitle`，回一条 warning。
-     *
-     * 为什么不静默加后缀：那样人永远不知道库里有俩「复盘」。也不静默覆盖：那等于直接
-     * 丢一份知识。
-     */
+    const proposedSourceId = input.sourceId
+    if (proposedSourceId !== undefined && !isSourceId(proposedSourceId)) return failure({ sourceId: '' }, 'SOURCE_ID_INVALID', 'source_id 含有非法字符', false)
+    let sourceId = proposedSourceId ?? '', reusedSource = false
+    let record!: SourceRaw
     let duplicateNote: string | undefined
-    const owner = db.sourceIdByTitle(title)
-    if (owner !== undefined && owner !== sourceId) {
-      if (input.allowDuplicateTitle !== true) {
-        return failure(
-          { sourceId: '' },
-          'SOURCE_TITLE_DUPLICATED',
-          `标题「${title}」已被来源 ${owner} 占用，改一个标题再来`,
-          true,
-          '换一个有区分度的标题（例如带上日期或版本），或显式传 allow_duplicate_title: true 让两份并存。',
-        )
-      }
-      duplicateNote = `标题「${title}」与来源 ${owner} 重复，已按 allow_duplicate_title 并存；建议改成有区分度的标题。`
-    }
-    /**
-     * 写入交给存储层：它在**一个事务**里做三件事 —— 正文进 `blob`、加一行 `revision`、
-     * 更新当前态。而「正文没变就不造版本」也在那里（幂等重入的常态，回滚可回滚的依据）。
-     *
-     * 0062 之前这三件事散在三处，其中「版本快照」是单独写一个文件的 —— 于是崩在中间
-     * 就是「文件变了、历史没记」，只能靠启动对账兜底。
-     */
-    const existing = db.source(sourceId)
-    const record: SourceRaw = {
-      sourceId,
-      title,
-      content: input.content,
-      ...(input.externalId ? { externalId: input.externalId } : {}),
-      metadata: input.metadata ?? {},
-      ...(input.lineage ? { lineage: input.lineage } : {}),
-      createdAt: existing?.record.createdAt ?? new Date().toISOString(),
-      updatedAt: new Date().toISOString(),
-    }
-    /**
-     * 溯源：调用方给了就用它；没给就**从正文自己声明的地址**补一条最小的；再没有才退回
-     * 外部标识（`upload:<文件名>:<mtime>` 这种，它带着文件的名字）。
-     *
-     * 补进去的都是**已经知道的事实**，不含猜测 —— 但少了这一步，「这份材料从哪来」的
-     * 答案就取决于它当初是走哪条路进来的：转换内核那条路写 `resource` 与 `sources[]`，
-     * 直接读上传这条什么都不写。
-     */
-    const declaredOrigin = declaredOriginOf(record.content)
-    const provenance: SourceProvenance = input.provenance ?? {
-      ...(declaredOrigin === undefined ? {} : { resource: declaredOrigin }),
-      sources: [{
-        id: 'origin',
-        resource: declaredOrigin ?? input.externalId?.trim() ?? record.title,
-        title: record.title,
-      }],
-    }
-    const frontMatter = sourceFrontMatter(record, provenance)
-    /**
-     * 底稿（0067）：调用方这一趟带进来的优先，没有就**沿用库里已有的那一份**。
-     *
-     * 沿用是必须的：`addSource` 也是「只改记账字段」那条路（补溯源、改标题、修 front
-     * matter），而底稿是正文之外的资产 —— 在这条路上把它清掉，等于让人改一次标题就丢一次
-     * 重跑的依据。清空底稿只有一条路：连同这份来源一起删掉。
-     */
-    const original = sourceOriginalOf(input.metadata) ?? existing?.original
+    let possibleDuplicateIds: string[] = []
+    let identities: SourceIdentity[] = []
     try {
-      db.transact({ opId: operationId(), actor: 'panel', summary: `写入来源「${title}」` }, tx => {
+      if (input.sourceUrl !== undefined && input.sourceIdentity?.url !== undefined && normalizeSourceUrl(input.sourceUrl).href !== normalizeSourceUrl(input.sourceIdentity.url).href) throw new SourceIdentityError('SOURCE_ORIGIN_CONFLICT', 'source_url 与 source_identity.url 不一致。')
+      if (input.sourceIdentity !== undefined || input.sourceUrl !== undefined) identities = resolveSourceIdentities({ ...input.sourceIdentity, ...(input.sourceUrl === undefined ? {} : { url: input.sourceUrl }) })
+      // transact writes the operation row first: identity lookup, source write and binding share one writer lock.
+      db.transact({ opId: operationId(), actor: 'panel', summary: `写入来源「${input.title ?? proposedSourceId ?? '新来源'}」` }, tx => {
+        const choice = chooseSourceId(db, proposedSourceId, identities)
+        sourceId = choice.sourceId; reusedSource = choice.reused
+        const existing = db.source(sourceId)
+        if (!existing) possibleDuplicateIds = (db.raw("SELECT s.entity_id FROM source s JOIN revision r ON r.entity_kind='source' AND r.entity_id=s.entity_id AND r.version=s.head_version WHERE r.blob_hash=? AND s.entity_id<>? ORDER BY s.entity_id LIMIT 20")
+          .all(createHash('sha256').update(input.content).digest('hex'), sourceId) as Array<{ entity_id: string }>).map(row => row.entity_id)
+        if (input.expectedVersion !== undefined && (!Number.isInteger(input.expectedVersion) || input.expectedVersion < 0 || (existing?.version ?? 0) !== input.expectedVersion)) throw new SourceIdentityError('SOURCE_VERSION_CONFLICT', '来源版本已变化，请按 source_id 读取当前版本后再更新。', [sourceId])
+        const title = input.title?.trim() || existing?.record.title || sourceId
+        const owner = db.sourceIdByTitle(title)
+        if (owner !== undefined && owner !== sourceId && existing?.record.title !== title) {
+          if (input.allowDuplicateTitle !== true) throw new SourceIdentityError('SOURCE_TITLE_DUPLICATED', `标题「${title}」已被来源 ${owner} 占用；请改标题或显式允许同名并存。`, [owner])
+          duplicateNote = `标题「${title}」与来源 ${owner} 重复，已按 allow_duplicate_title 并存。`
+        }
+        record = {
+          sourceId, title, content: input.content,
+          ...((input.externalId ?? existing?.record.externalId) ? { externalId: input.externalId ?? existing?.record.externalId } : {}),
+          metadata: input.metadata ?? existing?.record.metadata ?? {},
+          ...(input.lineage ? { lineage: input.lineage } : {}),
+          createdAt: existing?.record.createdAt ?? new Date().toISOString(), updatedAt: new Date().toISOString(),
+        }
+        // Body-declared URLs remain provenance only. They never claim or redirect source identity.
+        const origin = input.sourceUrl ?? input.sourceIdentity?.url ?? declaredOriginOf(record.content)
+          ?? (typeof existing?.frontmatter.resource === 'string' ? existing.frontmatter.resource : undefined)
+        const provenance: SourceProvenance = input.provenance ?? {
+          ...(origin ? { resource: origin } : {}), sources: [{ id: 'origin', resource: origin ?? input.externalId?.trim() ?? title, title }],
+        }
+        const frontMatter = { ...(existing?.frontmatter ?? {}), ...sourceFrontMatter(record, provenance) }
+        const original = sourceOriginalOf(input.metadata) ?? existing?.original
         tx.putSource(record, frontMatter, { actor: 'user', kind: 'named', summary: `写入来源「${title}」` }, original)
+        for (const identity of identities) tx.bindSourceIdentity(identity, sourceId)
       })
     } catch (cause) {
+      if (cause instanceof SourceIdentityError) return failure({ sourceId, candidates: cause.candidates }, cause.code, cause.message, false)
       return failure({ sourceId: '' }, 'STORE_WRITE_FAILED', `写进知识库失败：${cause instanceof Error ? cause.message : String(cause)}`, true)
     }
     /**
@@ -3447,7 +3446,7 @@ export class KnowledgeRuntime {
     this.sourceIndex = undefined
     return success(
       {
-        sourceId,
+        sourceId, proposedSourceId, reusedSource, possibleDuplicateIds, sourceIdentity: db.sourceIdentities(sourceId), version: db.source(sourceId)?.version, readRef: { kb: this.baseId || 'default', source_id: sourceId, version: db.source(sourceId)?.version, content_hash: createHash('sha256').update(record.content).digest('hex') },
         ...(record.lineage ? { lineage: record.lineage } : {}),
         assets: { refs: imageRefs.length, missing: missingImages.length },
       },
@@ -4386,7 +4385,8 @@ export class KnowledgeRuntime {
 
     const listed = input.knowledge ? { knowledge: input.knowledge, total: input.knowledge.length } : await store.list({
       objectId: input.coordinate.objectId,
-      ...(input.existing?.metadata.wiki_kind ? { kind: input.existing.metadata.wiki_kind === 'way' ? 'procedure' as const : 'fact' as const, ...(input.coordinate.actionId ? { actionId: input.coordinate.actionId } : {}) } : { actionId: input.coordinate.actionId, sceneId: input.coordinate.sceneId }),
+      actionId: input.coordinate.actionId, sceneId: input.coordinate.sceneId,
+      ...(input.existing?.metadata.wiki_kind ? { kind: input.existing.metadata.wiki_kind === 'way' ? 'procedure' as const : 'fact' as const } : {}),
       excludeWithdrawn: true,
       limit: MAX_ORGANIZE_KNOWLEDGE,
     })
@@ -4438,7 +4438,7 @@ export class KnowledgeRuntime {
       hash,
       layout,
       reuse,
-      system: buildOrganizeSystem(input.coordinate.actionId ? 'way' : 'fact'),
+      system: buildOrganizeSystem(input.existing?.metadata.wiki_kind === 'way' || listed.knowledge[0]?.kind === 'procedure' ? 'way' : 'fact'),
       prompt: buildOrganizePrompt(organizeInput),
     }
   }
@@ -4637,7 +4637,7 @@ export class KnowledgeRuntime {
       const plan = planRelated(cards, relations, await this.projectedRelated(cards))
       const entries = plan.get(cardKey(card))
       if (entries === undefined || entries.length === 0) return {}
-      return { related: entries.map(entry => ({ title: entry.title, entityType: entry.entityType, reason: entry.reason })) }
+      return { related: entries.map(entry => ({ title: entry.title, entityType: entry.entityType, entityId: entry.entityId, reason: entry.reason })) }
     } catch {
       // 相关投影是**增强**：算不出来时不给清单，于是正文里一个 `[[…]]` 都不许出现 —— 而不是把卡片卡住。
       return {}
@@ -4868,7 +4868,9 @@ export class KnowledgeRuntime {
     const createdAt = typeof existing?.frontmatter.created_at === 'string' && existing.frontmatter.created_at ? existing.frontmatter.created_at : updatedAt
     const provenance = [...(input.provenance ?? []), ...(input.lineage ? [{ ...input.lineage, role: 'created' as const, refType: 'knowledge_card', refId: input.entityId }] : [])]
     // 旧版本曾把 schema_issues 写入 metadata。重写卡片时主动摘掉它，避免旧的待补结果继续出现。
-    const { schema_issues: _staleIssues, ...metadata } = input.metadata ?? {}
+    const { schema_issues: _staleIssues, ...metadata } = input.metadata ?? previous?.metadata ?? {}
+    if (status === 'deprecated' && (input.origin === 'review' || input.origin === 'manual' || (input.origin === undefined && previous?.status !== 'deprecated'))) metadata.wiki_deprecation_origin = 'manual'
+    if (status !== 'deprecated') delete metadata.wiki_deprecation_origin
     void _staleIssues
     // 备注与 review **默认继承库里已有的**：不传不等于清空（见入参注释）。
     const annotations = input.annotations ?? previousAnnotations ?? []
@@ -4949,7 +4951,106 @@ export class KnowledgeRuntime {
     return success({ entityId: input.entityId, ...(input.lineage ? { lineage: input.lineage } : {}) })
   }
 
-  /** Resolve one card by id, optionally constrained to a type (ids are unique per type). */
+  /** Shared by direct reads, index publication and recall; always reads live contributions. */
+  private async wikiUnavailability(cards: readonly KnowledgeCard[], suppliedPlacements?: Map<string, CardKnowledgeRow[]>): Promise<Map<string, string>> {
+    const truth = await this.storeHandle()
+    const knowledge = await this.knowledgeStore()
+    if (!truth || !knowledge) return new Map(cards.map(card => [cardKey(card), '知识真源不可用，无法核验 Wiki。']))
+    const placements = suppliedPlacements ?? truth.placementsOf(cards.map(card => card.entityId))
+    const ids = [...new Set(cards.flatMap(card => [...(placements.get(card.entityId) ?? []).map(row => row.knowledgeId), ...Object.keys(card.metadata.knowledge_versions as object ?? {})]))]
+    const rows = new Map<string, Knowledge>()
+    for (let offset = 0; offset < ids.length; offset += 500) {
+      const page = await knowledge.list({ ids: ids.slice(offset, offset + 500), includeMerged: true, limit: 500 })
+      for (const row of page.knowledge) rows.set(row.id, row)
+    }
+    const sources = new Map((truth.raw('SELECT entity_id,head_version FROM source').all() as Array<{ entity_id: string; head_version: number }>).map(row => [row.entity_id, row.head_version]))
+    const cases = new Map<string, number | undefined>()
+    const result = new Map<string, string>()
+    for (const card of cards) {
+      const reason = wikiUnavailableReason(card, placements.get(card.entityId) ?? [], { knowledge: rows, sources, caseVersion: id => {
+        if (!cases.has(id)) cases.set(id, truth.event(id)?.version)
+        return cases.get(id)
+      } })
+      if (reason) result.set(cardKey(card), reason)
+    }
+    return result
+  }
+
+  /** Read a stable Wiki link or browse an Object's coordinates without flattening its files. */
+  async readWiki(input: KnowledgeScope & { target?: string; object?: string; includeContent?: boolean; limit?: number; offset?: number; maxChars?: number; contentOffset?: number; contentMaxChars?: number; expectedVersion?: number; linkLimit?: number; linkOffset?: number } = {}): Promise<Envelope<Record<string, unknown>>> {
+    const empty = { wikis: [], total: 0, offset: input.offset ?? 0, hasMore: false, outgoing: [], backlinks: [] }
+    const limit = input.limit ?? 20, offset = input.offset ?? 0, maxChars = input.maxChars ?? (this.config.contextMaxChars || 20000)
+    const linkLimit = input.linkLimit ?? 20, linkOffset = input.linkOffset ?? 0
+    const pageChars = input.contentMaxChars ?? Math.min(20000, maxChars)
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100 || !Number.isInteger(offset) || offset < 0) return failure(empty, 'WIKI_PAGE_INVALID', 'limit 必须为 1–100，offset 必须为非负整数。', false)
+    if (!Number.isInteger(maxChars) || maxChars < 1 || maxChars > 200000 || !Number.isInteger(pageChars) || pageChars < 1 || pageChars > 40000 || !Number.isInteger(linkLimit) || linkLimit < 1 || linkLimit > 100 || !Number.isInteger(linkOffset) || linkOffset < 0) return failure(empty, 'WIKI_BUDGET_INVALID', 'max_chars 为 1–200000，content_max_chars 为 1–40000，link_limit 为 1–100，link_offset 为非负整数。', false)
+    if (scopeError(input)) return failure(empty, 'SCOPE_INVALID', scopeError(input)!, false)
+    if (input.contentOffset !== undefined && (!input.target || !Number.isInteger(input.contentOffset) || input.contentOffset < 0)) return failure(empty, 'WIKI_CONTENT_OFFSET_INVALID', '正文分页需要唯一 target 和非负整数 content_offset。', false)
+    if (input.expectedVersion !== undefined && (!input.target || !Number.isInteger(input.expectedVersion) || input.expectedVersion < 1)) return failure(empty, 'WIKI_VERSION_INVALID', 'expected_version 需要唯一 target 和正整数版本号。', false)
+    if (!input.target?.trim() && !input.objectId?.trim() && !input.object?.trim()) return failure(empty, 'WIKI_SCOPE_REQUIRED', '请提供双链 target、object_id 或明确的 Object 名称。', false)
+    const cards = await this.loadCards()
+    let objectId = input.objectId
+    if (input.object !== undefined) {
+      const name = input.object.trim().toLocaleLowerCase()
+      const objects = (await this.listAxisEntities('object') ?? []).filter(object => object.status !== 'deprecated' && object.status !== 'merged'
+        && [object.id, object.name, ...object.aliases].some(value => value.toLocaleLowerCase() === name))
+      if (objects.length !== 1) return failure({ ...empty, candidates: objects.map(object => ({ id: object.id, name: object.name })) }, objects.length ? 'OBJECT_AMBIGUOUS' : 'OBJECT_NOT_FOUND', 'Object 名称未唯一解析，请使用明确的 object_id。', false)
+      if (objectId !== undefined && objectId !== objects[0]!.id) return failure(empty, 'OBJECT_SCOPE_CONFLICT', 'object 与 object_id 指向不同对象。', false)
+      objectId = objects[0]!.id
+    }
+    let selected = cards.filter(card => matchesScope(card, { ...input, objectId }))
+    if (input.target?.trim()) {
+      selected = wikiLinkCandidates(selected, input.target)
+      if (selected.length !== 1) return failure({ ...empty, candidates: selected.map(card => ({ ...wikiReference(card), coordinate: card.coordinate, wikiKind: card.metadata.wiki_kind })) }, selected.length ? 'WIKI_LINK_AMBIGUOUS' : 'WIKI_NOT_FOUND', '双链未唯一指向 Wiki，请使用稳定 target。', false)
+      if (selected[0]!.status === 'deprecated') return failure(empty, 'WIKI_UNAVAILABLE', '目标 Wiki 已停用，请按 Object 查找当前文件。', false)
+    }
+    selected = selected.filter(card => card.status !== 'deprecated').sort((a, b) => wikiReference(a).target.localeCompare(wikiReference(b).target))
+    const page = selected.slice(offset, offset + limit), includeContent = input.includeContent ?? Boolean(input.target)
+    const truth = await this.storeHandle()
+    const unavailableByKey = await this.wikiUnavailability(page, truth?.placementsOf(page.map(card => card.entityId)))
+    const wikis: Array<Record<string, unknown>> = []
+    let usedChars = 0
+    for (const card of page) {
+      const unavailable = unavailableByKey.get(cardKey(card)), version = truth?.card(card.entityId)?.version
+      if (input.expectedVersion !== undefined && input.expectedVersion !== version) return failure(empty, 'WIKI_VERSION_CHANGED', 'Wiki 已更新，请重新读取，避免拼接不同版本的正文。', false)
+      const ref = wikiReference(card)
+      const entry: Record<string, unknown> = { ...ref, coordinate: card.coordinate, wikiKind: card.metadata.wiki_kind, status: card.status, version, available: !unavailable,
+        ...(unavailable ? { reason: unavailable } : {}), ...(card.coordinate ? { coordinateLabels: await this.coordinateNames(card.coordinate) } : {}), contentDelivered: false }
+      if (includeContent && !unavailable) {
+        if (input.contentOffset !== undefined) {
+          if (input.contentOffset > card.content.length) return failure(empty, 'WIKI_CONTENT_OFFSET_INVALID', 'content_offset 超过正文长度。', false)
+          const end = Math.min(card.content.length, input.contentOffset + Math.min(pageChars, maxChars - usedChars))
+          const content = card.content.slice(input.contentOffset, end), truncated = end < card.content.length
+          entry.contentPage = { content, offset: input.contentOffset, totalChars: card.content.length, returnedChars: content.length, truncated, nextOffset: truncated ? end : null }
+          entry.contentDelivered = true; entry.contentComplete = input.contentOffset === 0 && !truncated
+          usedChars += content.length
+          if (truncated) entry.nextRead = { tool: 'read_knowledge_wiki', args: { kb: this.baseId || 'default', target: ref.target, expected_version: version, content_offset: end, content_max_chars: pageChars, max_chars: maxChars } }
+        } else {
+          const cost = JSON.stringify(card).length
+          if (usedChars + cost <= maxChars) { entry.wiki = card; entry.contentDelivered = true; entry.contentComplete = true; usedChars += cost }
+          else { entry.requiredChars = cost; entry.contentComplete = false; entry.nextRead = { tool: 'read_knowledge_wiki', args: { kb: this.baseId || 'default', target: ref.target, expected_version: version, content_offset: 0, content_max_chars: pageChars, max_chars: maxChars } } }
+        }
+      }
+      wikis.push(entry)
+    }
+    const first = input.target ? page[0] : undefined, live = cards.filter(card => card.status !== 'deprecated')
+    const outgoing = first ? [...new Map(scanWikiLinks(first.content).flatMap(link => {
+      const targets = wikiLinkCandidates(live, link.target)
+      return targets.length === 1 && targets[0]!.entityId !== first.entityId ? [[targets[0]!.entityId, wikiReference(targets[0]!)] as const] : []
+    })).values()].sort((a, b) => a.target.localeCompare(b.target)) : []
+    const backlinks = first ? live.filter(card => card.entityId !== first.entityId && scanWikiLinks(card.content).some(link => {
+      const targets = wikiLinkCandidates(live, link.target)
+      return targets.length === 1 && targets[0]!.entityId === first.entityId
+    })).map(wikiReference).sort((a, b) => a.target.localeCompare(b.target)) : []
+    const data = { wikis, total: selected.length, offset, hasMore: offset + page.length < selected.length, nextOffset: offset + page.length < selected.length ? offset + page.length : null,
+      outgoing: outgoing.slice(linkOffset, linkOffset + linkLimit), backlinks: backlinks.slice(linkOffset, linkOffset + linkLimit),
+      links: { offset: linkOffset, limit: linkLimit, outgoingTotal: outgoing.length, backlinksTotal: backlinks.length, nextOffset: linkOffset + linkLimit < Math.max(outgoing.length, backlinks.length) ? linkOffset + linkLimit : null },
+      budget: { maxChars, usedChars, omittedCards: wikis.filter(item => includeContent && item.available && !item.contentDelivered).length } }
+    await this.audit('wiki.read', { target: input.target, objectId, includeContent, returned: page.length, usedChars })
+    return success(data)
+  }
+
+  /** Resolve one card by its stable ID, optionally constrained to a type. */
   async readCard(entityId: string, entityType?: SchemaType): Promise<KnowledgeCard | undefined> {
     const db = await this.storeHandle()
     if (db === null) return undefined
@@ -5023,7 +5124,43 @@ export class KnowledgeRuntime {
   async readCase(id: string, version?: number): Promise<EventEntity | undefined> {
     const db = await this.storeHandle()
     if (version !== undefined && (!Number.isInteger(version) || version < 1)) return undefined
-    return version === undefined ? db?.event(id) : db?.caseVersion(id, version)
+    if (!db?.event(id)) return undefined
+    return version === undefined ? db.event(id) : db.caseVersion(id, version)
+  }
+
+  async queryCases(input: KnowledgeScope & { ids?: string[]; version?: number; query?: string; limit?: number; offset?: number; includeContent?: boolean; maxChars?: number; contentOffset?: number }): Promise<Envelope<Record<string, unknown>>> {
+    const empty = { cases: [], missing_ids: [], total: 0, hasMore: false }
+    const limit = input.limit ?? 20, offset = input.offset ?? 0, maxChars = input.maxChars ?? 20000
+    if (scopeError(input)) return failure(empty, 'SCOPE_INVALID', scopeError(input)!, false)
+    if (!Number.isInteger(limit) || limit < 1 || limit > 50 || !Number.isInteger(offset) || offset < 0 || !Number.isInteger(maxChars) || maxChars < 1 || maxChars > 100000) return failure(empty, 'CASE_PAGE_INVALID', 'limit 为 1–50，offset 为非负整数，max_chars 为 1–100000。', false)
+    if (input.ids !== undefined && (!Array.isArray(input.ids) || !input.ids.length || input.ids.length > 50 || input.ids.some(id => typeof id !== 'string' || !id.trim()))) return failure(empty, 'CASE_IDS_INVALID', 'case_ids 必须含 1–50 个有效 ID。', false)
+    const ids = input.ids ? [...new Set(input.ids)] : undefined
+    if (input.version !== undefined && (!ids || ids.length !== 1 || !Number.isInteger(input.version) || input.version < 1)) return failure(empty, 'CASE_VERSION_INVALID', '历史版本读取要求一个 Case ID 和正整数 version。', false)
+    if (input.contentOffset !== undefined && (!ids || ids.length !== 1 || !Number.isInteger(input.contentOffset) || input.contentOffset < 0)) return failure(empty, 'CASE_CONTENT_OFFSET_INVALID', '正文分页需要一个 Case ID 和非负整数 content_offset。', false)
+    if (input.query !== undefined && (typeof input.query !== 'string' || !input.query.trim() || ids)) return failure(empty, 'CASE_QUERY_INVALID', 'query 必须非空，且不与 case_ids 同传。', false)
+    if (!ids && !input.query?.trim() && ![input.objectId, input.actionId, input.sceneId].some(value => value !== undefined)) return failure(empty, 'CASE_QUERY_REQUIRED', '请提供 case_ids、当前子问题 query 或坐标范围。', false)
+    const read = ids ? await Promise.all(ids.map(id => this.readCase(id, input.version))) : await this.loadEvents()
+    const terms = input.query ? [...new Set(segment(input.query))] : []
+    const matched = read.filter((item): item is EventEntity => !!item)
+      .filter(item => ![input.objectId, input.actionId, input.sceneId].some(value => value !== undefined) || item.records.some(record => matchesScope({ coordinate: record.coordinateIds }, input)))
+      .map(item => ({ item, score: terms.length ? terms.filter(term => JSON.stringify(item).toLowerCase().includes(term.toLowerCase())).length / terms.length : 1 }))
+      .filter(row => row.score > 0).sort((a, b) => b.score - a.score || a.item.id.localeCompare(b.item.id))
+    const cases: Array<Record<string, unknown>> = [], includeContent = input.includeContent ?? Boolean(ids)
+    let usedChars = 0
+    for (const { item, score } of matched.slice(offset, offset + limit)) {
+      const raw = JSON.stringify(item), version = item.version ?? 1
+      const sourceReads = item.sources.map(source => ({ kb: this.baseId || 'default', source_id: source.documentId, version: source.sourceVersion, ...(source.locator ? { start: source.locator.start, end: source.locator.end } : {}), quote: source.quote, historicalVersionKnown: source.sourceVersion !== undefined }))
+      const ref = { id: item.id, title: item.title, version, sourceReads, coordinate: item.coordinateIds, occurredAt: item.occurredAt, historicalEvidence: true, score }
+      if (includeContent && input.contentOffset !== undefined) {
+        if (input.contentOffset > raw.length) return failure(empty, 'CASE_CONTENT_OFFSET_INVALID', 'content_offset 超过 Case 正文长度。', false)
+        const end = Math.min(raw.length, input.contentOffset + maxChars), content = raw.slice(input.contentOffset, end)
+        cases.push({ ...ref, contentPage: { format: 'json', content, offset: input.contentOffset, totalChars: raw.length, truncated: end < raw.length },
+          ...(end < raw.length ? { nextRead: { tool: 'get_knowledge_cases', args: { kb: this.baseId || 'default', case_ids: [item.id], version, content_offset: end, max_chars: maxChars } } } : {}) }); usedChars += content.length
+      } else if (includeContent && usedChars + raw.length <= maxChars) { cases.push({ ...item, sourceReads, historicalEvidence: true, contentDelivered: true }); usedChars += raw.length }
+      else cases.push({ ...ref, contentDelivered: false, requiredChars: raw.length, nextRead: { tool: 'get_knowledge_cases', args: { kb: this.baseId || 'default', case_ids: [item.id], version, ...(raw.length > maxChars ? { content_offset: 0 } : {}), max_chars: maxChars } } })
+    }
+    await this.audit('case.read', { ids, query: input.query, returned: cases.length, usedChars })
+    return success({ cases, missing_ids: ids?.filter((_, index) => read[index] === undefined) ?? [], total: matched.length, offset, hasMore: offset + limit < matched.length, nextOffset: offset + limit < matched.length ? offset + limit : null, retrieval: ids ? 'id' : 'keyword', budget: { maxChars, usedChars } })
   }
 
   async loadEvents(): Promise<EventEntity[]> {
@@ -5040,7 +5177,7 @@ export class KnowledgeRuntime {
     if (card.status === 'problem' && status !== 'unreviewed') return failure({ entityId, status }, 'STATUS_TRANSITION_INVALID', 'problem 不能直接恢复为其他状态，请先改为 unreviewed', false)
     const eventLineage = withRun(lineage, 'knowledge-status')
     const provenance = [...(card.provenance ?? []), ...(eventLineage ? [{ ...eventLineage, role: 'executed' as const, refType: 'knowledge_status', refId: entityId }] : [])]
-    const written = await this.writeCard({ ...card, status, sourceRefs: card.sourceRefs, provenance, metadata: { ...card.metadata, ...(problemNote?.trim() ? { problem_note: problemNote.trim() } : {}) } })
+    const written = await this.writeCard({ ...card, status, sourceRefs: card.sourceRefs, provenance, origin: 'review', metadata: { ...card.metadata, ...(problemNote?.trim() ? { problem_note: problemNote.trim() } : {}) } })
     if (written.ok === false) return failure({ entityId, status }, written.error.code, written.error.message, written.error.retryable, written.error.suggestion)
     return success({ entityId, status, ...(eventLineage ? { lineage: eventLineage } : {}) })
   }
@@ -5087,7 +5224,7 @@ export class KnowledgeRuntime {
      * `metadata.related_cards`；这里继续剥离旧版本正文里的标记，保证存量卡片迁移期间
      * 也不会把导航送进召回。
      */
-    const recallBody = stripEventReferenceSection(stripRelatedSection(card.content))
+    const recallBody = wikiIndexContent(stripEventReferenceSection(stripRelatedSection(card.content)))
     for (const [index, chunk] of splitWikiNotes({ ...card, content: recallBody }).entries()) {
       const baseId = `${card.entityType}:${card.entityId}`
       const stableSection = layoutOf(card.metadata)?.sections?.find(section => section.title === chunk.heading)
@@ -5649,7 +5786,7 @@ export class KnowledgeRuntime {
         existing: card,
         ...(input.imagePlan.byCard.get(key) === undefined ? {} : { images: input.imagePlan.byCard.get(key) }),
         ...(relatedPlan.get(key) === undefined ? {} : {
-          related: (relatedPlan.get(key) ?? []).map(entry => ({ title: entry.title, entityType: entry.entityType, reason: entry.reason })),
+          related: (relatedPlan.get(key) ?? []).map(entry => ({ title: entry.title, entityType: entry.entityType, entityId: entry.entityId, reason: entry.reason })),
         }),
         call: input.call,
       })
@@ -6211,12 +6348,11 @@ export class KnowledgeRuntime {
   // ------------------------------------------- Finalize · 索引 / 断链 / 相关（0049）
 
   /**
-   * 收尾段的**结构化数据层**：把相关卡片写进 `metadata.related_cards`，清理旧版本写进
-   * 正文的相关块，并把断链统计交给编译报告与索引页。
+   * 编译收尾：生成类型化 Wiki 的稳定双链与导航，更新 `metadata.related_cards`，
+   * 清理旧相关块，并把断链统计交给编译报告与索引页。
    *
-   * 相关卡片是派生导航数据，不是知识正文。它放在 metadata 里有三个好处：正文不会被
-   * 机器段落污染，召回不需要再剥离导航块，面板也能直接按结构展示。旧卡片上的
-   * `<!-- compiled:related -->` 只在这里做一次兼容清理。
+   * 导航只放链接，不复制目标正文；面板使用结构化元数据，检索排除生成的导航块。
+   * 旧卡片上的 `<!-- compiled:related -->` 在这里兼容清理。
    *
    * 三段都是确定性的，所以这个函数可以重复跑：正文和结构化相关数据都没变化时不写盘。
    */
@@ -6230,11 +6366,24 @@ export class KnowledgeRuntime {
      * 它是**算出来的**，不是谁声明的：这张卡里的知识引用了哪个轴实体，而那个轴自己
      * 有一张卡，就有了链接。模型抽出来的关系（`relations`）是第二层。
      */
-    const projected = await this.projectedRelated(cards)
-    const related = planRelated(cards, relations, projected)
-    /** 统计清理旧导航块之后的正文断链；相关卡片本身不再伪装成正文链接。 */
-    const nextCards = cards.map(card => ({ ...card, content: stripEventReferenceSection(stripRelatedSection(card.content)) }))
-    const deadLinks = deadLinksOf(nextCards)
+    const axes = (await this.listAxisEntities() ?? []).filter(axis => axis.status !== 'deprecated' && axis.status !== 'merged')
+    const objects = axes.filter(axis => axis.kind === 'object')
+    const names = new Map(axes.map(axis => [axis.id, axis.name]))
+    const labeled = cards.map(card => card.metadata.wiki_kind && card.coordinate ? { ...card, metadata: { ...card.metadata,
+      wiki_coordinate_labels: { object: names.get(card.coordinate.objectId) ?? card.coordinate.objectId, action: names.get(card.coordinate.actionId) ?? card.coordinate.actionId, scene: names.get(card.coordinate.sceneId) ?? card.coordinate.sceneId },
+    } } : card)
+    const live = labeled.filter(card => card.status !== 'deprecated')
+    const nextCards = labeled.map(card => {
+      const base = { ...card, content: stripEventReferenceSection(stripRelatedSection(card.content)) }
+      if (!card.metadata.wiki_kind || card.status === 'deprecated') return base
+      const navigation = compileWikiNavigation(base, live, objects)
+      return { ...base, content: navigation.content, metadata: { ...base.metadata,
+        wiki_links: navigation.outgoing, wiki_inline_targets: navigation.inlineTargets, wiki_object_refs: navigation.objectIds,
+      } }
+    })
+    const projected = await this.projectedRelated(nextCards)
+    const related = planRelated(live, relations, projected)
+    const deadLinks = deadLinksOf(nextCards.filter(card => card.status !== 'deprecated'))
     let rewritten = 0
     for (const [index, card] of cards.entries()) {
       const key = cardKey(card)
@@ -6242,7 +6391,7 @@ export class KnowledgeRuntime {
       const entries = related.get(key) ?? []
       const previousEntries = relatedEntriesOf(card.metadata)
       const contentChanged = nextCard.content !== card.content
-      const relatedChanged = JSON.stringify(previousEntries) !== JSON.stringify(entries)
+      const relatedChanged = JSON.stringify(previousEntries) !== JSON.stringify(entries) || JSON.stringify(card.metadata.wiki_coordinate_labels) !== JSON.stringify(nextCard.metadata.wiki_coordinate_labels) || JSON.stringify(card.metadata.wiki_links) !== JSON.stringify(nextCard.metadata.wiki_links) || JSON.stringify(card.metadata.wiki_inline_targets) !== JSON.stringify(nextCard.metadata.wiki_inline_targets) || JSON.stringify(card.metadata.wiki_object_refs) !== JSON.stringify(nextCard.metadata.wiki_object_refs)
       if (!contentChanged && !relatedChanged) continue
       /**
        * 没有来源的卡片写不进去（`writeCard` 要求 `source_refs` 非空），而这是**唯一**
@@ -6263,7 +6412,7 @@ export class KnowledgeRuntime {
         status: card.status,
         ...(card.owner ? { owner: card.owner } : {}),
         ...(card.provenance ? { provenance: card.provenance } : {}),
-        metadata: { ...card.metadata, [RELATED_METADATA_KEY]: entries },
+        metadata: { ...nextCard.metadata, [RELATED_METADATA_KEY]: entries },
         origin: 'compile',
       })
       if (written.ok === false) {
@@ -6387,13 +6536,9 @@ export class KnowledgeRuntime {
     }
   }
 
-  /** 一条上下文条目「值多少字符」：命中条目算它那些 note 的正文，扩展条目算标题 + 摘要（+ 正文）。 */
-  private contextCost(item: ContextItem, full: boolean): number {
-    const card = item.wiki
-    if (card === null) return 0
-    const shallow = card.title.length + (card.summary?.length ?? 0)
-    const knowledge = (item.knowledge ?? []).reduce((sum, row) => sum + row.text.length + row.state.length + 8, 0)
-    return knowledge + shallow + card.content.length
+  /** 与 Agent 实际收到的上下文条目使用同一序列化形状，包含完整 Wiki、依据和引用。 */
+  private contextCost(item: ContextItem): number {
+    return JSON.stringify(agentContextItem(item)).length
   }
 
   /** 溢出目录：**系统临时目录**，不随知识库走（0050 的取舍，见 issue）。 */
@@ -6421,17 +6566,14 @@ export class KnowledgeRuntime {
     const { items, maxChars, recallId } = input
     const hitCards = items.filter(item => item.reason === 'hit').length
     const expandedCards = items.length - hitCards
-    const totalChars = items.reduce((sum, item) => sum + this.contextCost(item, true), 0)
+    const totalChars = items.reduce((sum, item) => sum + this.contextCost(item), 0)
     if (!Number.isFinite(maxChars) || maxChars <= 0) {
       return { items, report: { maxChars: 0, usedChars: totalChars, omittedCards: 0, omittedChars: 0, hitCards, expandedCards } }
     }
     const keptItems: ContextItem[] = []
     let used = 0
     for (const item of items) {
-      const full = this.contextCost(item, true)
-      const shallow = this.contextCost(item, false)
-      // 命中条目按整条算（它的正文就是证据）；扩展条目可以先按「浅」那一档进。
-      const cost = item.reason === 'hit' ? full : shallow
+      const cost = this.contextCost(item)
       if (used + cost > maxChars) continue
       used += cost
       keptItems.push(item)
@@ -6442,17 +6584,18 @@ export class KnowledgeRuntime {
       maxChars,
       usedChars: used,
       omittedCards: omitted.length,
-      omittedChars: omitted.reduce((sum, item) => sum + this.contextCost(item, true), 0),
+      omittedChars: omitted.reduce((sum, item) => sum + this.contextCost(item), 0),
       hitCards: keptItems.filter(item => item.reason === 'hit').length,
       expandedCards: keptItems.filter(item => item.reason === 'expansion').length,
     }
     if (omitted.length === 0) return { items: keptItems, report }
     const overflowPath = await this.writeRecallOverflow({ items, recallId, usedChars: used, maxChars })
     report.overflowPath = overflowPath
+    report.omitted = omitted.flatMap(item => item.wiki ? [{ target: `${item.wiki.entityType}/${item.wiki.entityId}`, title: item.wiki.title, requiredChars: this.contextCost(item), read: { tool: 'read_knowledge_wiki', args: { kb: this.baseId || 'default', target: `${item.wiki.entityType}/${item.wiki.entityId}` } } }] : [])
     return {
       items: keptItems,
       report,
-      notice: `还有 ${report.omittedCards} 张卡片共 ${report.omittedChars} 字符没有放进上下文，完整内容在 ${overflowPath}；需要更多信息时直接读这个文件（它是本次召回的临时产物，不保证长期存在）。`,
+      notice: `还有 ${report.omittedCards} 张卡片共 ${report.omittedChars} 字符没有放进上下文，完整内容在 ${overflowPath}；可按 budget.omitted 中的稳定 target 调用 read_knowledge_wiki 补读；此文件仅供本机诊断，不保证长期存在。`,
     }
   }
 
@@ -6554,13 +6697,17 @@ export class KnowledgeRuntime {
    * 而不是报错：这一层是**增强**，它坏了不该让编译失败。
    */
   private async projectedRelated(cards: KnowledgeCard[]): Promise<Array<{ fromKey: string; toKey: string }>> {
+    const links = cards.flatMap(card => scanWikiLinks(card.content).flatMap(link => {
+      const candidates = wikiLinkCandidates(cards.filter(target => target.status !== 'deprecated'), link.target)
+      return candidates.length === 1 && candidates[0]!.entityId !== card.entityId ? [{ fromKey: cardKey(card), toKey: cardKey(candidates[0]!) }] : []
+    }))
     const knowledge = await this.knowledgeStore()
-    if (knowledge === null) return []
+    if (knowledge === null) return links
     const db = await this.storeHandle()
-    if (db === null) return []
+    if (db === null) return links
     let placements: Map<string, CardKnowledgeRow[]>
-    try { placements = db.placements() } catch { return [] }
-    if (placements.size === 0) return []
+    try { placements = db.placements() } catch { return links }
+    if (placements.size === 0) return links
     /**
      * 单轴卡：坐标里恰好只有一个分量非空。
      *
@@ -6585,11 +6732,11 @@ export class KnowledgeRuntime {
       bucket.push(key)
       byAxis.set(axis, bucket)
     }
-    if (byAxis.size === 0) return []
+    if (byAxis.size === 0) return links
     const ids = [...new Set([...placements.values()].flat().map(row => row.knowledgeId))]
-    if (ids.length === 0) return []
+    if (ids.length === 0) return links
     let axes: Map<string, { objectId: string; actionId: string; sceneId: string }>
-    try { axes = await knowledge.axesOf(ids) } catch { return [] }
+    try { axes = await knowledge.axesOf(ids) } catch { return links }
     const pairs = new Map<string, { fromKey: string; toKey: string }>()
     for (const [cardId, rows] of placements) {
       const fromKeys = keyById.get(cardId) ?? []
@@ -6609,7 +6756,7 @@ export class KnowledgeRuntime {
         }
       }
     }
-    return [...pairs.values()]
+    return [...pairs.values(), ...links]
   }
 
   /**
@@ -8127,7 +8274,7 @@ export class KnowledgeRuntime {
         : card.metadata.wiki_kind
           ? events.filter(event => {
             const c = event.coordinateIds
-            return c.objectId === card.coordinate!.objectId && (card.metadata.wiki_kind === 'fact' || c.actionId === card.coordinate!.actionId)
+            return coordinateKeyOf(c) === coordinateKeyOf(card.coordinate!)
           }).map(event => event.id).sort()
           : (eventsByCoordinate.get(coordinateKeyOf(card.coordinate)) ?? []).sort()
       const oldRaw = card.metadata.event_refs
@@ -8229,7 +8376,7 @@ export class KnowledgeRuntime {
 
     for (const event of input.events) {
       const seenEvidence = new Set<string>()
-      const evidence = [...event.sources, ...event.timeline.flatMap(step => step.sources)].filter(source => {
+      const evidence = [...event.sources, ...event.timeline.flatMap(step => step.sources)].map(source => ({ ...source, sourceVersion: db.source(source.documentId)?.version })).filter(source => {
         if (!source.found) return false
         const key = source.documentId + '|' + source.quote
         if (seenEvidence.has(key)) return false
@@ -8273,7 +8420,7 @@ export class KnowledgeRuntime {
         symptom: event.symptom,
         coordinate: { object: event.object, action: event.action, scene: event.scene },
         coordinateIds,
-        timeline: event.timeline,
+        timeline: event.timeline.map(step => ({ ...step, sources: step.sources.map(source => ({ ...source, sourceVersion: db.source(source.documentId)?.version })) })),
         rootCause: event.rootCause,
         rootCauseStatus: event.rootCauseStatus,
         outcome: event.outcome,
@@ -8338,7 +8485,7 @@ export class KnowledgeRuntime {
       if (!db || !audit || !await this.knowledgeStore()) throw new Error('知识库或任务历史不可用，无法启动处理任务')
       const store = new PipelineStore(db.connection(), audit.connection())
       const engine = new KnowledgePipeline(store, {
-        capture: () => ({ model: this.modelSeamNow(), note: this.extractionNote(), profile: structuredClone(this.organizeProfile()), organize: this.config.cardOrganize, format: 'table' }),
+        capture: () => ({ model: this.modelSeamNow(), note: this.extractionNote(), extractionTimeoutMinutes: normalizeExtractionTimeoutMinutes(this.extractionTimeoutProvider?.()), profile: structuredClone(this.organizeProfile()), organize: this.config.cardOrganize, format: 'table' }),
         serialize: work => {
           this.compilePending += 1
           const run = this.compileTail.then(work, work)
@@ -8359,25 +8506,33 @@ export class KnowledgeRuntime {
          * 指纹，否则归一自己学到的实体（它们本来就出现在这份文档里）会让它永远无法复用。
          */
         fingerprint: (source, context) => this.pipelineExtractionFingerprint(source, context),
-        extract: async (source, context, onDelta) => {
+        extract: async (source, context, onDelta, execution) => {
           if (!context.model.call) throw new Error(`抽取模型不可用：${context.model.why ?? '请在编译设置中选择模型'}`)
           const axes = await this.axisPromptBlock(source.content)
-          return runWikiTrial({ title: source.title, text: source.content, docId: source.sourceId, axes, note: context.note, call: context.model.call, modelRequest: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort }, outputFormat: context.format, sessionId: `knowledge:${this.baseId || 'default'}`, onDelta })
+          return runResumableExtraction({ title: source.title, text: source.content, sourceId: source.sourceId, store, ...execution, recoveryTimeoutMs: normalizeExtractionTimeoutMinutes(context.extractionTimeoutMinutes) * 60_000, fingerprint: `${execution.fingerprint}:v${source.version}`, axes, note: context.note, call: context.model.call, modelRequest: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort, maxTokens: context.model.maxTokens }, outputFormat: context.format, sessionId: `knowledge:${this.baseId || 'default'}`, onDelta })
         },
         normalize: (source, checkpoint, context, force, output) => this.normalizePipelineSource(store, source, checkpoint, context, force, output),
         /**
          * 引擎只把 `snapshot` 原样传回来，所以那边看到的是 `unknown`；这里把它取回成
          * 真实类型（见 `materialize-snapshot.ts` 里为什么不放在 `pipeline/types.ts`）。
          */
-        derive: (sourceIds, context, force, output, checkpoint) => this.deriveProcedures(sourceIds, context, force, output, checkpoint),
+        derive: (sourceIds, context, force, output, checkpoint, progress) => this.deriveProcedures(sourceIds, context, force, output, checkpoint, progress),
         groups: async context => {
           const snapshot = await this.materializationSnapshot(store, context)
-          return { groups: snapshot.groups, blocked: snapshot.blocked, blockedAmbiguous: snapshot.blockedAmbiguous, blockedAwaitingNormalize: snapshot.blockedAwaitingNormalize, snapshot }
+          return { groups: snapshot.groups, blocked: snapshot.blocked, blockedAmbiguous: snapshot.blockedAmbiguous, blockedAwaitingNormalize: snapshot.blockedAwaitingNormalize, blockedItems: snapshot.blockedItems, snapshot }
         },
         materialize: (group, context, output, snapshot) => this.materializePipelineGroup(store, group, context, output, snapshot as MaterializationSnapshot),
-        build: async (taskId, checkpoint) => {
+        link: async () => {
+          const warnings: string[] = []
+          const finalized = await this.runFinalizeStage(await this.loadCards(), Object.values(await this.readExtractedRelations()).flat(), warnings)
+          if (warnings.length) throw new Error(warnings.join('；'))
+          return `已更新 Wiki 双链与导航：${finalized.rewritten} 份`
+        },
+        build: async (taskId, checkpoint, progress) => {
           let result: Envelope<RebuildReport>
-          try { result = await this.compileOnce(taskId, 'all', undefined, { extract: false, checkpoint }) }
+          try { result = await this.compileOnce(taskId, 'all', undefined, { extract: false, checkpoint, onProgress: step => {
+            if ((step.id === 'index' || step.id === 'build' || step.id === 'publish') && step.state === 'running') progress?.(step.facts.join('；'))
+          } }) }
           catch (cause) { await this.settleProgressFailure(taskId, cause); throw cause }
           this.settleProgressReport(taskId, result)
           if (!result.ok) throw new Error(result.error.message)
@@ -8443,7 +8598,7 @@ export class KnowledgeRuntime {
       .filter(entry => [entry.name, ...entry.aliases].map(normalizeAxisName).some(value => value.length > 0 && text.includes(value)))
       .map(entry => ({ id: entry.id, name: entry.name, aliases: entry.aliases, description: entry.description, guidance: entry.guidance }))
       .sort((left, right) => left.id.localeCompare(right.id)))
-    return contentHashOf(JSON.stringify({ source: source.sourceHash, title: source.title, contract: EXTRACTION_CONTRACT_VERSION, note: context.note, format: context.format, axes: relevant, model: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } }))
+    return contentHashOf(JSON.stringify({ source: source.sourceHash, title: source.title, contract: EXTRACTION_CONTRACT_VERSION, plan: EXTRACTION_PLAN_VERSION, note: context.note, format: context.format, axes: relevant, model: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } }))
   }
 
   private async normalizationFingerprint(checkpoint: ExtractionCheckpoint, context: PipelineContext): Promise<string> {
@@ -8568,14 +8723,14 @@ export class KnowledgeRuntime {
       const cards = await this.loadCards()
       const relations = Object.values(await this.readExtractedRelations()).flat()
       for (const [key, entries] of planRelated(cards, relations, await this.projectedRelated(cards))) {
-        if (entries.length > 0) plan.set(key, entries.map(entry => ({ title: entry.title, entityType: entry.entityType, reason: entry.reason })))
+        if (entries.length > 0) plan.set(key, entries.map(entry => ({ title: entry.title, entityType: entry.entityType, entityId: entry.entityId, reason: entry.reason })))
       }
     } catch { /* 增强项：算不出来就不给清单 */ }
     return plan
   }
 
   /** Independent, checkpointed Case -> Procedure compilation. No execution is inferred. */
-  private async deriveProcedures(sourceIds: string[] | undefined, context: PipelineContext, force: boolean, output: (text: string) => void, checkpoint: () => Promise<void>): Promise<{ done: number; total: number; reused: number; summary: string }> {
+  private async deriveProcedures(sourceIds: string[] | undefined, context: PipelineContext, force: boolean, output: (text: string) => void, checkpoint: () => Promise<void>, progress?: (value: PipelineDeriveProgress) => void): Promise<{ done: number; total: number; reused: number; summary: string }> {
     const db = await this.storeHandle()
     const knowledge = await this.knowledgeStore()
     if (!db || !knowledge) throw new Error('Knowledge 存储不可用')
@@ -8584,24 +8739,29 @@ export class KnowledgeRuntime {
     const selected = sourceIds ? new Set(sourceIds) : undefined
     const cases = (await this.loadEvents()).filter(item => !selected || item.records.some(record => selected.has(record.sourceId)))
     let done = 0, reused = 0
+    progress?.({ done, total: cases.length, reused, phase: 'preparing', summary: `已读取 ${cases.length} 个 Case` })
     const strings = (value: unknown): string[] => Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string').map(v => v.trim()).filter(Boolean) : []
     for (const item of cases) {
       await checkpoint()
+      const observe = (phase: PipelineDeriveProgress['phase'], state: PipelineItemState['state'], summary: string, failed = 0): void => progress?.({ done: done + failed, total: cases.length, reused, failed, phase, summary, item: { id: item.id, title: item.title, state } })
+      observe('processing', 'processing', `正在检查 Case：${item.title}`)
       const caseVersion = item.version ?? 1
       const evidence = [...item.sources, ...item.timeline.flatMap(step => step.sources)]
       const sourceVersions = new Map(evidence.map(e => [e.documentId, db.source(e.documentId)?.version]))
       const fingerprint = contentHashOf(JSON.stringify({ contract: DERIVE_CONTRACT_VERSION, item: { ...item, updatedAt: undefined }, sourceVersions: [...sourceVersions], model: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } }))
-      const receipt = db.raw('SELECT fingerprint, knowledge_ids FROM pipeline_derivations WHERE case_id=?').get(item.id) as { fingerprint: string; knowledge_ids: string } | undefined
-      if (!force && receipt?.fingerprint === fingerprint) { done++; reused++; continue }
+      const receipt = db.raw('SELECT fingerprint, response, knowledge_ids FROM pipeline_derivations WHERE case_id=?').get(item.id) as { fingerprint: string; response: string; knowledge_ids: string } | undefined
+      // Replay validated cached output through ingest too: normalization may have withdrawn its support.
+      const cachedResponse = !force && receipt?.fingerprint === fingerprint ? receipt.response : undefined
       const auditId = randomUUID()
       const request = { system: buildDeriveSystem(), prompt: JSON.stringify({ case: { ...item, version: caseVersion }, sourceEvidence: evidence, sourceVersions: [...sourceVersions] }) }
-      let response = '{"procedures":[],"skipped_cases":[]}'
+      let response = cachedResponse ?? '{"procedures":[],"skipped_cases":[]}'
       db.raw('INSERT INTO pipeline_derivation_runs VALUES (?,?,?,?,?,?,?,?,?)').run(auditId, item.id, caseVersion, fingerprint, JSON.stringify(request), '', 'running', null, new Date().toISOString())
       try {
-        if (item.timeline.some(step => step.type === 'check' || step.type === 'action')) {
+        if (cachedResponse === undefined && item.timeline.some(step => step.type === 'check' || step.type === 'action')) {
           if (!context.model.call) throw new Error(`提炼模型不可用：${context.model.why ?? '请选择模型'}`)
+          observe('waiting-model', 'processing', `正在提炼 Case：${item.title}`)
           response = await context.model.call({ ...request, sessionId: `knowledge:${this.baseId || 'default'}:derive`, onDelta: output })
-        } else output(`Case ${item.id} 没有已执行过程，不反推 Procedure。\n`)
+        } else if (cachedResponse === undefined) output(`Case ${item.id} 没有已执行过程，不反推 Procedure。\n`)
         const parsed = JSON.parse(response.trim().replace(/^```(?:json)?\s*/, '').replace(/\s*```$/, '')) as { procedures?: Array<Record<string, unknown>> }
         if (!Array.isArray(parsed.procedures)) throw new Error('Case 提炼返回缺少 procedures 数组')
         if (this.closed || db.event(item.id)?.version !== caseVersion || [...sourceVersions].some(([id, version]) => db.source(id)?.version !== version)) throw new Error('Case 或来源在提炼期间变化，请重试')
@@ -8636,7 +8796,10 @@ export class KnowledgeRuntime {
         db.raw("UPDATE pipeline_derivation_runs SET response=?,state='succeeded' WHERE id=?").run(response, auditId)
         output(`Case ${item.id}：保存 ${ids.length} 条候选 Procedure。\n`)
         done++
+        if (cachedResponse !== undefined) reused++
+        observe(cachedResponse !== undefined ? 'reused' : 'completed', cachedResponse !== undefined ? 'reused' : 'succeeded', `${item.title}：已保存 ${ids.length} 条候选方法`)
       } catch (cause) {
+        observe('failed', 'failed', `${item.title}：${cause instanceof Error ? cause.message : String(cause)}`, 1)
         db.raw("UPDATE pipeline_derivation_runs SET response=?,state='failed',error=? WHERE id=?").run(response, cause instanceof Error ? cause.message : String(cause), auditId)
         throw cause
       }
@@ -8651,7 +8814,7 @@ export class KnowledgeRuntime {
    * 两处必须用同一个表达式，否则「什么算变化」就有两套说法。
    */
   private pipelineGroupFingerprint(knowledge: Knowledge[], context: PipelineContext): string {
-    return contentHashOf(JSON.stringify({ knowledge: knowledge.map(row => ({ id: row.id, kind: row.kind ?? 'fact', data: row.data, text: row.text, status: row.status, sources: row.sources.filter(source => !source.withdrawn) })).sort((a, b) => a.id.localeCompare(b.id)), profile: context.profile, organize: context.organize, model: context.organize ? { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } : undefined }))
+    return contentHashOf(JSON.stringify({ contract: 'coordinate-wiki-v2', organizeVersion: context.organize ? ORGANIZE_VERSION : undefined, knowledge: knowledge.map(row => ({ id: row.id, kind: row.kind ?? 'fact', data: row.data, text: row.text, status: row.status, sources: row.sources.filter(source => !source.withdrawn) })).sort((a, b) => a.id.localeCompare(b.id)), profile: context.profile, organize: context.organize, model: context.organize ? { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } : undefined }))
   }
 
   /**
@@ -8688,12 +8851,12 @@ export class KnowledgeRuntime {
     ].filter(Boolean).map(text => `- ${text}[^${row.id}]`).join('\n')
   }
 
-  private async freshGroupFingerprint(coordinate: CardCoordinate, context: PipelineContext, db: KnowledgeDb): Promise<string> {
+  private async freshGroupFingerprint(coordinate: CardCoordinate, wikiKind: WikiKind, context: PipelineContext, db: KnowledgeDb): Promise<string> {
     const store = await this.knowledgeStore()
     if (!store) return ''
     const raw: Knowledge[] = []
     for (let offset = 0;; offset += 500) {
-      const page = await store.list({ objectId: coordinate.objectId, kind: coordinate.actionId ? 'procedure' : 'fact', ...(coordinate.actionId ? { actionId: coordinate.actionId } : {}), excludeWithdrawn: true, limit: 500, offset })
+      const page = await store.list({ objectId: coordinate.objectId, kind: wikiKind === 'way' ? 'procedure' : 'fact', actionId: coordinate.actionId, sceneId: coordinate.sceneId, excludeWithdrawn: true, limit: 500, offset })
       raw.push(...page.knowledge)
       if (offset + page.knowledge.length >= page.total) break
     }
@@ -8705,7 +8868,7 @@ export class KnowledgeRuntime {
       if (source) bodies.set(id, { version: source.version, content: source.record.content })
     }
     const rows = raw
-      .filter(row => row.status !== 'deprecated' && (row.kind !== 'procedure' || (row.data?.procedure?.completeness === 'complete' && row.data.procedure.method.length > 0 && row.status !== 'disputed' && row.data.procedure.caseRefs.every(ref => db.event(ref.id)?.version === ref.version) && !row.sources.some(source => source.toVersion !== undefined && db.source(source.documentId)?.version !== source.toVersion))))
+      .filter(row => row.status !== 'deprecated' && (row.kind !== 'procedure' || (row.data?.procedure?.completeness === 'complete' && row.data.procedure.method.length > 0 && row.status !== 'disputed' && row.data.procedure.caseRefs.every(ref => db.event(ref.id)?.version === ref.version) && !row.sources.some(source => !source.withdrawn && source.toVersion !== undefined && db.source(source.documentId)?.version !== source.toVersion))))
       .map(row => assessKnowledgeEvidence(row, db, bodies))
       .map(row => ({ ...row, sources: row.sources.filter(source => !source.withdrawn && source.evidenceStatus !== 'missing') }))
       .filter(row => row.sources.length > 0)
@@ -8726,12 +8889,13 @@ export class KnowledgeRuntime {
      */
     const plans = options.plans !== false
     const unresolved = store.unresolvedKnowledge()
-    const grouped = new Map<string, { coordinate: CardCoordinate; knowledge: Knowledge[] }>()
+    const grouped = new Map<string, { coordinate: CardCoordinate; wikiKind: WikiKind; knowledge: Knowledge[] }>()
     let blockedAmbiguous = 0
     let blockedAwaitingNormalize = 0
-    const groupFor = (coordinate: CardCoordinate) => {
-      const key = coordinateKeyOf(coordinate)
-      if (!grouped.has(key)) grouped.set(key, { coordinate, knowledge: [] })
+    const blockedItems: MaterializationSnapshot['blockedItems'] = []
+    const groupFor = (coordinate: CardCoordinate, wikiKind: WikiKind) => {
+      const key = wikiGroupKey(wikiKind, coordinate)
+      if (!grouped.has(key)) grouped.set(key, { coordinate, wikiKind, knowledge: [] })
       return grouped.get(key)!
     }
     const caseStore = await this.storeHandle()
@@ -8739,24 +8903,29 @@ export class KnowledgeRuntime {
       if (row.kind === 'case') continue
       const coordinate = wikiProjection(row.kind ?? 'fact', row)
       const method = row.data?.procedure
-      if (!coordinate || (row.kind === 'procedure' && (!method || method.completeness !== 'complete' || !method.method.length || row.status === 'disputed' || method.caseRefs.some(ref => caseStore?.event(ref.id)?.version !== ref.version) || row.sources.some(source => source.toVersion !== undefined && caseStore?.source(source.documentId)?.version !== source.toVersion)))) { blockedAmbiguous += 1; continue }
-      groupFor(coordinate).knowledge.push(row)
+      if (!coordinate || (row.kind === 'procedure' && (!method || method.completeness !== 'complete' || !method.method.length || row.status === 'disputed' || method.caseRefs.some(ref => caseStore?.event(ref.id)?.version !== ref.version) || row.sources.some(source => source.toVersion !== undefined && caseStore?.source(source.documentId)?.version !== source.toVersion)))) {
+        blockedAmbiguous += 1
+        blockedItems.push({ knowledgeId: row.id, sourceIds: [...new Set(row.sources.map(source => source.documentId).filter(Boolean))], ...(coordinate ? { groupKey: wikiGroupKey(row.kind === 'procedure' ? 'way' : 'fact', coordinate) } : {}) })
+        continue
+      }
+      groupFor(coordinate, row.kind === 'procedure' ? 'way' : 'fact').knowledge.push(row)
     }
     const db = await this.storeHandle()
     const events = new Map<string, EventEntity[]>()
     for (const event of db?.events() ?? []) {
       const coordinate = event.coordinateIds
       if (!coordinate.objectId) continue
-      for (const projection of [wikiProjection('fact', coordinate), wikiProjection('procedure', coordinate)]) {
-        if (!projection) continue
-        const key = coordinateKeyOf(projection)
+      for (const kind of ['fact', 'way'] as const) {
+        const key = wikiGroupKey(kind, coordinate)
         const bucket = events.get(key) ?? []
         bucket.push(event)
         events.set(key, bucket)
       }
     }
     const cards = await this.loadCards()
-    const byCoordinate = new Map(cards.filter(card => card.coordinate).map(card => [coordinateKeyOf(card.coordinate!), card]))
+    const groupKeyOf = (card: KnowledgeCard): string => card.coordinate && (card.metadata.wiki_kind === 'fact' || card.metadata.wiki_kind === 'way')
+      ? wikiGroupKey(card.metadata.wiki_kind, card.coordinate) : card.coordinate ? coordinateKeyOf(card.coordinate) : ''
+    const byCoordinate = new Map(cards.filter(card => card.coordinate).map(card => [groupKeyOf(card), card]))
     const groups: MaterializationGroup[] = []
     const knowledge = new Map<string, Knowledge[]>()
     for (const [key, value] of grouped) {
@@ -8770,11 +8939,13 @@ export class KnowledgeRuntime {
       const needsNormalization = this.needsNormalizationForGroup(store, value.knowledge, unresolved, db)
       if (needsNormalization) blockedAwaitingNormalize += value.knowledge.length
       knowledge.set(key, value.knowledge)
-      groups.push({ key, wikiKind: value.coordinate.actionId ? 'way' : 'fact', title: existing?.title ?? `${names.object}${names.action ? ` · ${names.action}` : ''} · ${value.coordinate.actionId ? 'Wiki Way' : 'Wiki Fact'}`, coordinate: value.coordinate, knowledgeCount: value.knowledge.length, eventCount: events.get(key)?.length ?? 0, sourceIds: contributingSources, ...(existing ? { cardId: existing.entityId } : {}), state: needsNormalization ? 'blocked' : current ? 'current' : existing ? 'changed' : 'new', ...(needsNormalization ? { reason: '分组中的来源已变化、新抽取待归一或坐标有歧义，请先完成归一' } : {}), fingerprint })
+      groups.push({ key, wikiKind: value.wikiKind, title: existing?.title ?? `${names.object}${names.action ? ` · ${names.action}` : ''}${names.scene ? ` · ${names.scene}` : ''} · ${value.wikiKind === 'way' ? 'Wiki Way' : 'Wiki Fact'}`, coordinate: value.coordinate, knowledgeCount: value.knowledge.length, eventCount: events.get(key)?.length ?? 0, sourceIds: contributingSources, ...(existing ? { cardId: existing.entityId } : {}), state: needsNormalization ? 'blocked' : current ? 'current' : existing ? 'changed' : 'new', ...(needsNormalization ? { reason: '分组中的来源已变化、新抽取待归一或坐标有歧义，请先完成归一' } : {}), fingerprint })
     }
     for (const card of cards) {
-      if (!card.coordinate || grouped.has(coordinateKeyOf(card.coordinate)) || !store.materialization(coordinateKeyOf(card.coordinate)) || card.status === 'deprecated') continue
-      groups.push({ key: coordinateKeyOf(card.coordinate), title: card.title, coordinate: card.coordinate, knowledgeCount: 0, eventCount: 0, sourceIds: card.sourceRefs, cardId: card.entityId, state: card.sourceRefs.some(id => unresolved.sources.has(id)) ? 'blocked' : 'withdrawn', ...(card.sourceRefs.some(id => unresolved.sources.has(id)) ? { reason: '来源中的坐标仍有歧义，请先完成归一' } : {}), fingerprint: 'withdrawn' })
+      const key = groupKeyOf(card)
+      const legacyReceipt = card.coordinate ? store.materialization(coordinateKeyOf(card.coordinate)) : undefined
+      if (!card.coordinate || grouped.has(key) || (!store.materialization(key) && !legacyReceipt && card.metadata.pipeline_materialization !== true) || card.status === 'deprecated') continue
+      groups.push({ key, wikiKind: card.metadata.wiki_kind === 'way' ? 'way' : 'fact', title: card.title, coordinate: card.coordinate, knowledgeCount: 0, eventCount: 0, sourceIds: card.sourceRefs, cardId: card.entityId, state: card.sourceRefs.some(id => unresolved.sources.has(id)) ? 'blocked' : 'withdrawn', ...(card.sourceRefs.some(id => unresolved.sources.has(id)) ? { reason: '来源中的坐标仍有歧义，请先完成归一' } : {}), fingerprint: 'withdrawn' })
     }
     const sources = plans ? (await this.loadSources()).map(source => ({ sourceId: source.sourceId, content: source.content })) : []
     const imagePlan = plans
@@ -8805,7 +8976,7 @@ export class KnowledgeRuntime {
     return {
       groups: groups.sort((a, b) => a.title.localeCompare(b.title)),
       blocked: blockedAmbiguous + blockedAwaitingNormalize,
-      blockedAmbiguous, blockedAwaitingNormalize,
+      blockedAmbiguous, blockedAwaitingNormalize, blockedItems,
       knowledge, events, sources, images: imagePlan.byCard, related: relatedByKey,
     }
   }
@@ -8836,7 +9007,7 @@ export class KnowledgeRuntime {
       const statusBeforeDeprecate = (await this.readCard(existing.entityId))?.status
       if (statusBeforeDeprecate === undefined) throw new Error('卡片在处理期间已被删除，本次物化未提交，请刷新后重试')
       if (statusBeforeDeprecate !== existing.status) throw new Error(`卡片在处理期间被人工改动（状态 ${existing.status} → ${statusBeforeDeprecate}），本次物化未提交，请重试`)
-      const written = await this.writeCard({ ...existing, status: 'deprecated', origin: 'compile' })
+      const written = await this.writeCard({ ...existing, metadata: { ...existing.metadata, wiki_deprecation_origin: existing.status === 'deprecated' && existing.metadata.wiki_deprecation_origin !== 'withdrawal' ? 'manual' : 'withdrawal' }, status: 'deprecated', origin: 'compile' })
       if (!written.ok) throw new Error(written.error.message)
       store.materialized(group.key, group.fingerprint, existing.entityId)
       // 停用也是一次物化：卡片从可召回里退出，这一步发生过，就该留一条轨迹。
@@ -8855,7 +9026,7 @@ export class KnowledgeRuntime {
     let content = knowledge.map(row => `## ${row.data?.procedure?.question ?? row.text.split('\n')[0]!.slice(0, 60)}\n\n${this.organizeKnowledgeText(row)}[^${row.id}]${boundaries.get(row.id) ? `\n\n### 适用条件与边界\n\n${boundaries.get(row.id)}` : ''}`).join('\n\n')
     let summary = knowledge[0]?.text ?? ''
     let placements: CardKnowledgeRow[] = knowledge.map((row, index) => ({ knowledgeId: row.id, section: row.data?.procedure?.question ?? row.text.split('\n')[0]!.slice(0, 60), ordinal: index + 1, origin: 'compiler' }))
-    let metadata: Record<string, unknown> = { ...(existing?.metadata ?? {}), pipeline_materialization: true, wiki_kind: group.wikiKind ?? (group.coordinate.actionId ? 'way' : 'fact') }
+    let metadata: Record<string, unknown> = { ...(existing?.metadata ?? {}), pipeline_materialization: true, wiki_kind: group.wikiKind ?? 'fact', wiki_coordinate_version: 2, knowledge_versions: Object.fromEntries(knowledge.map(row => [row.id, row.version])) }
     const entityId = existing?.entityId ?? `coord-${hash(group.key)}`
     const images = snapshot.images.get(group.key) ?? []
     const related = existing && snapshot.related.has(group.key) ? { related: snapshot.related.get(group.key)! } : {}
@@ -8880,7 +9051,7 @@ export class KnowledgeRuntime {
      * 「只有知识行变了」；这条按坐标重算整组指纹，能把那种变化也挡住。
      */
     if (this.needsNormalizationForGroup(store, knowledge, store.unresolvedKnowledge(), db)) throw new Error('卡片组织期间事实发生变化，结果未提交，请重试')
-    if (await this.freshGroupFingerprint(group.coordinate, context, db) !== group.fingerprint) throw new Error('卡片分组在处理期间事实发生了变化，结果未提交，请重试')
+    if (await this.freshGroupFingerprint(group.coordinate, group.wikiKind ?? 'fact', context, db) !== group.fingerprint) throw new Error('卡片分组在处理期间事实发生了变化，结果未提交，请重试')
     if (this.closed) throw new Error('知识库已关闭，本次物化未提交')
     /**
      * 状态必须**在写之前**重读，并且和读到的旧值比对。
@@ -8896,7 +9067,8 @@ export class KnowledgeRuntime {
     if (statusAtWrite !== existing?.status) {
       throw new Error(`卡片在处理期间被人工改动（状态 ${existing?.status ?? '未知'} → ${statusAtWrite ?? '未知'}），本次物化未提交，请重试`)
     }
-    const written = await this.writeCard({ entityType, entityId, title, content, summary, sourceRefs: group.sourceIds, status: statusAtWrite === 'deprecated' ? 'unreviewed' : statusAtWrite ?? 'unreviewed', coordinate: group.coordinate, placements, metadata, origin: 'compile' })
+    const nextStatus = statusAtWrite === 'deprecated' && existing?.metadata.wiki_deprecation_origin === 'withdrawal' ? 'unreviewed' : statusAtWrite ?? 'unreviewed'
+    const written = await this.writeCard({ entityType, entityId, title, content, summary, sourceRefs: group.sourceIds, status: nextStatus, coordinate: group.coordinate, placements, metadata, origin: 'compile' })
     if (!written.ok) throw new Error(written.error.message)
     db.setCardEvents(entityId, eventIds)
     store.materialized(group.key, group.fingerprint, entityId)
@@ -8915,7 +9087,7 @@ export class KnowledgeRuntime {
       card: {
         id: entityId,
         title,
-        status: statusAtWrite === 'deprecated' ? 'unreviewed' : statusAtWrite ?? 'unreviewed',
+        status: nextStatus,
         characters: content.length,
         events: eventIds.length,
         images: images.length,
@@ -8939,7 +9111,9 @@ export class KnowledgeRuntime {
     const db = await this.derivedHandle()
     const manifest = db?.artifact('build-manifest.json')
     const hashes = manifest ? (JSON.parse(manifest) as { cardHashes?: Record<string, string> }).cardHashes ?? {} : {}
-    const cards = await this.loadCards()
+    const allCards = await this.loadCards()
+    const unavailable = await this.wikiUnavailability(allCards)
+    const cards = allCards.filter(card => !card.metadata.wiki_kind || !unavailable.has(cardKey(card)))
     const indexPending = cards.some(card => hashes[`${card.entityType}:${card.entityId}`] !== this.cardHashOf(card)) || Object.keys(hashes).length !== cards.length
     return { sources: rows, groups, blocked, pendingNew: groups.filter(group => group.state === 'new').length, pendingUpdated: groups.filter(group => group.state === 'changed').length, pendingWithdrawn: groups.filter(group => group.state === 'withdrawn').length, indexPending }
   }
@@ -9131,7 +9305,7 @@ export class KnowledgeRuntime {
    * 跑一趟编译的**实体**（0066）。它不做排队，也不对外承诺「你 await 它就等于你发起了
    * 它」—— 那两件事分别在 `enqueueCompile()` 与 `rebuild()` / `startCompile()` 里。
    */
-  private async compileOnce(runId: string, only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean; forceExtract?: boolean; checkpoint?: () => Promise<void> } = {}): Promise<Envelope<RebuildReport>> {
+  private async compileOnce(runId: string, only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean; forceExtract?: boolean; checkpoint?: () => Promise<void>; onProgress?: (step: CompileActivityView) => void } = {}): Promise<Envelope<RebuildReport>> {
     if (only === 'all' || only === 'embeddings') await this.environmentGuard?.('embedding')
     this.publication = { artifacts: new Map() }
     const configAtStart = JSON.stringify({ config: this.config, fingerprint: this.embeddingFingerprint() })
@@ -9165,18 +9339,23 @@ export class KnowledgeRuntime {
           }
         this.publication.artifacts.set(COMPILE_SNAPSHOT, JSON.stringify(snapshot))
         await this.checkpointCompileTask(runId)
+        const changedWiki = await this.wikiUnavailability(snapshot.cards, new Map(snapshot.placements))
+        if (snapshot.cards.some(card => card.metadata.wiki_kind && changedWiki.has(cardKey(card)))) throw new Error('WIKI_CHANGED_DURING_BUILD: Wiki 的支撑知识在构建期间变化，请重新组织并构建索引')
         if (JSON.stringify({ config: this.config, fingerprint: this.embeddingFingerprint() }) !== configAtStart) throw new Error('COMPILE_CONFIG_CHANGED: 编译期间设置已变化，请重新编译')
         await options.checkpoint?.()
+        options.onProgress?.({ id: 'publish', state: 'running', facts: ['正在统一发布检索索引版本'] })
         db.publish(this.publication)
         this.vectorIndex = null
       }
       return result
     } finally {
       this.publication = undefined
+      // Compilation filters unavailable projections; the browsing cache still represents all saved Wiki.
+      this.cards = await this.loadCards()
     }
   }
 
-  private async prepareCompile(runId: string, only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean; forceExtract?: boolean } = {}): Promise<Envelope<RebuildReport>> {
+  private async prepareCompile(runId: string, only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean; forceExtract?: boolean; onProgress?: (step: CompileActivityView) => void } = {}): Promise<Envelope<RebuildReport>> {
     /**
      * 进度记录**先占位**：`runId` 一落下去，这一趟就有了名字 —— 之后无论从哪个出口结束
      * （三种 return，或者抛异常），收口都能认出这条记录属于谁。
@@ -9258,6 +9437,7 @@ export class KnowledgeRuntime {
     const setStep = (id: CompileStepId, state: CompileStepView['state'], facts: string[]): void => {
       const current = this.compileProgress ?? blankProgress(runId, only, startedAt, 'running', queuedAt)
       this.writeCompileProgress({ ...current, steps: current.steps.map(step => step.id === id ? { ...step, state, facts } : step) })
+      options.onProgress?.({ id, state, facts })
     }
     this.cards = await this.loadCards()
     const sources = await this.loadSources()
@@ -9436,6 +9616,9 @@ export class KnowledgeRuntime {
     await this.checkpointCompileTask(runId)
     // 相关 metadata 或旧正文清理刚落盘：stage 2 必须看到最新卡片。
     if (finalize.rewritten > 0) this.cards = await this.loadCards()
+    const unavailableWiki = await this.wikiUnavailability(this.cards)
+    for (const card of this.cards) if (card.metadata.wiki_kind && unavailableWiki.has(cardKey(card))) warnings.push(`Wiki「${card.title}」未进入索引：${unavailableWiki.get(cardKey(card))}`)
+    this.cards = this.cards.filter(card => !card.metadata.wiki_kind || !unavailableWiki.has(cardKey(card)))
     /**
      * 索引页也是这次编译的产物，所以它变了也算「语料变了」。
      *
@@ -9848,12 +10031,11 @@ export class KnowledgeRuntime {
   }
 
   /**
-   * Coordinate 路：先解析 Query 中出现的 Object / Action / Scene，再把命中的卡片拆成
+   * Coordinate 路：解析 Query 中出现的 Object / Action / Scene，再把命中的卡片拆成
    * Section 候选。它和 FTS / Vector 使用同一个 `unitId` 粒度，后面才能统一 RRF 与重排。
    *
    * 这里不让模型自由生成实体名：注册表负责 canonical / alias 命中，只有真实存在的
-   * 坐标 id 才能进入候选。意图目前使用轻量规则分类，结果会随 queryAnalysis 一起返回，
-   * 后续接入模型消歧时不需要改变召回合同。
+   * 坐标 id 才能进入候选。未解析的原文继续交给关键词、向量路线与统一重排。
    */
   private async coordinateRoute(
     query: string,
@@ -10243,7 +10425,8 @@ export class KnowledgeRuntime {
       for (const ref of hit.sourceRefs) {
         const source = corpus.get(ref)
         if (!source) continue
-        evidence.push(...evidenceExcerpts(ref, source.title, source.content, queryTerms))
+        const version = (await this.storeHandle())?.source(ref)?.version
+        evidence.push(...evidenceExcerpts(ref, source.title, source.content, queryTerms).map(excerpt => ({ ...excerpt, readRef: { kb: this.baseId || 'default', source_id: ref, version, content_hash: createHash('sha256').update(source.content).digest('hex'), quote: excerpt.excerpt.replace(/…$/, '') } })))
       }
       if (evidence.length > 0) {
         hit.evidence = evidence
@@ -10317,7 +10500,7 @@ export class KnowledgeRuntime {
       const collected = new Map<string, RecallKnowledge>()
       for (const row of perHit[index] ?? []) {
         const resolved = rows.get(row.knowledgeId)
-        if (resolved !== undefined) collected.set(resolved.id, resolved)
+        if (resolved !== undefined) collected.set(resolved.id, { ...resolved, ...(resolved.readRef ? { readRef: { ...resolved.readRef, kb: this.baseId || 'default' } } : {}) })
       }
       if (collected.size > 0) {
         hit.knowledge = [...collected.values()]
@@ -10356,7 +10539,7 @@ export class KnowledgeRuntime {
     includeProblems = false,
     mode?: RecallMode,
     lineage?: LineageContext,
-    options: { contextTopN?: number; rerank?: boolean; contextMaxChars?: number; detail?: boolean } = {},
+    options: KnowledgeScope & { contextTopN?: number; rerank?: boolean; contextMaxChars?: number; detail?: boolean } = {},
   ): Promise<Envelope<RecallResult>> {
     const recallId = generatedId('recall')
     /**
@@ -10395,6 +10578,8 @@ export class KnowledgeRuntime {
     if (mode !== undefined && !['fts', 'vector', 'hybrid'].includes(String(mode))) {
       return failure(empty(), 'MODE_INVALID', '召回 mode 只支持 fts、vector、hybrid；graph 不是召回模式', false)
     }
+    if (scopeError(options)) return failure(empty(), 'SCOPE_INVALID', scopeError(options)!, false)
+    if (options.contextMaxChars !== undefined && (!Number.isInteger(options.contextMaxChars) || options.contextMaxChars < 0)) return failure(empty(), 'CONTEXT_BUDGET_INVALID', 'context_max_chars 必须为非负整数。', false)
     if (!query?.trim()) return failure(empty(), 'QUERY_REQUIRED', 'query 不能为空', true)
     if (!Number.isInteger(recallTopK) || recallTopK < 1 || recallTopK > 50) return failure(empty(), 'LIMIT_INVALID', '召回 top_k 必须是 1 到 50 的整数', false)
     if (!Number.isInteger(requestedTopN) || requestedTopN < 1 || (options.contextTopN !== undefined && requestedTopN > recallTopK)) return failure(empty(), 'CONTEXT_TOP_N_INVALID', `上下文 top_n 必须是 1 到 ${recallTopK} 的整数`, false)
@@ -10443,26 +10628,17 @@ export class KnowledgeRuntime {
     for (const key of liveKeys) {
       if (snapshotCardByKey.get(key)?.sourceRefs.some(ref => !liveSourceIds.has(ref))) liveKeys.delete(key)
     }
-    // A method becomes unavailable immediately when its supporting Case or structured content changes.
-    // Do not wait for a later rebuild to stop serving the old instructions.
-    const unsafeProcedures = new Set(snapshot.knowledge.filter(row => {
-      if (row.kind !== 'procedure') return false
-      const current = truthAtRead?.raw('SELECT status,head_version FROM knowledge WHERE id=?').get(row.id) as { status: string; head_version: number } | undefined
-      return !current || current.status === 'deprecated' || current.status === 'disputed' || current.head_version !== row.version
-        || !row.data?.procedure || row.data.procedure.completeness !== 'complete'
-        || row.data.procedure.caseRefs.some(ref => truthAtRead?.event(ref.id)?.version !== ref.version)
-        || row.sources.some(source => source.toVersion !== undefined && truthAtRead?.source(source.documentId)?.version !== source.toVersion)
-    }).map(row => row.id))
-    const unsafeCardIds = new Set(snapshot.placements.filter(([, placements]) => placements.some(p => unsafeProcedures.has(p.knowledgeId))).map(([id]) => id))
-    for (const key of liveKeys) if (unsafeCardIds.has(snapshotCardByKey.get(key)?.entityId ?? '')) liveKeys.delete(key)
+    const unavailableWiki = await this.wikiUnavailability(snapshot.cards, new Map(snapshot.placements))
+    for (const key of unavailableWiki.keys()) liveKeys.delete(key)
     let publishedGraph = visibleGraph(snapshot.graph, truthAtRead ? liveGraphKeys(truthAtRead) : new Set())
     const currentByKey = new Map(liveCards.map(card => [cardKey(card), card]))
     let cards: KnowledgeCard[] = snapshot.cards.filter(card => liveKeys.has(cardKey(card))).map(card => {
       const current = currentByKey.get(cardKey(card))!
       return { ...card, status: current.status, annotations: current.annotations, review: current.review,
         metadata: { ...card.metadata, ...(current.metadata.evidence_needs_review === true ? { evidence_needs_review: true } : {}) } }
-    })
-    const eligible = snapshot.notes.filter(unit => liveKeys.has(`${unit.entityType}:${unit.entityId}`)
+    }).filter(card => matchesScope(card, options))
+    const scopedKeys = new Set(cards.map(cardKey))
+    const eligible = snapshot.notes.filter(unit => scopedKeys.has(`${unit.entityType}:${unit.entityId}`)
       && (includeProblems || currentByKey.get(`${unit.entityType}:${unit.entityId}`)?.status !== 'problem'))
     const eligibleIds = new Set(eligible.map(unit => unit.unitId))
     /**
@@ -10571,13 +10747,9 @@ export class KnowledgeRuntime {
     let rerankScored: Array<{ unitId: string; logit: number; rerankScore: number; kept: boolean }> = []
     if (options.rerank === false || this.config.rerankProvider === 'none') {
       rerank = { status: 'skipped', provider: this.config.rerankProvider }
-      hits = hits.slice(0, recallTopK)
     } else {
       const rerankQuery = [
         query,
-        ...(queryAnalysis.intent.id !== 'unknown' && queryAnalysis.intent.confidence >= 0.7
-          ? [`意图：${queryAnalysis.intent.id}`]
-          : []),
         ...(['object', 'action', 'scene'] as const).flatMap(kind => {
           const values = queryAnalysis.axes[kind].map(item => item.name).slice(0, 3)
           return values.length > 0 ? [`${kind}：${values.join('、')}`] : []
@@ -10594,7 +10766,15 @@ export class KnowledgeRuntime {
     }
     // 重排换的是相关性顺序，评分加权仍然要压在最上面 —— 否则「review 过的排前面一点」
     // 只在关掉重排时成立，而重排默认是开着的。
-    hits = [...hits].sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId)).slice(0, recallTopK)
+    hits = [...hits].sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId))
+    const rankedSections = hits
+    // Select complete Wiki identities before applying top_k. Each Wiki contributes its best section.
+    const selectedWikiKeys = new Set<string>()
+    hits = rankedSections.filter(hit => {
+      const key = `${hit.entityType}:${hit.entityId}`
+      if (selectedWikiKeys.has(key) || selectedWikiKeys.size >= recallTopK) return false
+      selectedWikiKeys.add(key); return true
+    })
 
     // --- R4 · 证据片段 -----------------------------------------------------
     const truth = await this.storeHandle()
@@ -10664,7 +10844,7 @@ export class KnowledgeRuntime {
      * 不再各自占一个上下文名额。
      */
     const notesByWiki = new Map<string, RecallHit[]>()
-    for (const hit of hits) {
+    for (const hit of rankedSections.filter(hit => selectedWikiKeys.has(wikiKey(hit)) && finalKeys.has(wikiKey(hit)))) {
       const key = wikiKey(hit)
       const bucket = notesByWiki.get(key)
       if (bucket) bucket.push(hit)
@@ -10720,8 +10900,7 @@ export class KnowledgeRuntime {
     /**
      * 上下文预算（0050）：装箱 + 溢出。
      *
-     * 让位顺序写死在 `packContext` 里：先保证命中 note 的正文完整（它是证据），
-     * 再给扩展卡片的标题 + 摘要 + 关系，最后才给扩展卡片的正文。
+     * 让位顺序写死在 `packContext` 里：优先交付命中的完整 Wiki，再交付扩展 Wiki。
      */
     /**
      * 每次调用可以覆盖预算（0050）：指路行里就写着「读不到就调大预算重新召回」，
@@ -10729,6 +10908,14 @@ export class KnowledgeRuntime {
      */
     const maxChars = options.contextMaxChars ?? this.config.contextMaxChars
     const packed = await this.packContext({ items, maxChars, recallId })
+    const deliveredKeys = new Set(packed.items.flatMap(item => item.wiki ? [cardKey(item.wiki)] : []))
+    // Diagnostic HTTP requests may inspect unbudgeted candidate text. Normal delivery cannot leak it.
+    const deliveredHits = options.detail ? hits : hits.map(hit => {
+      if (deliveredKeys.has(wikiKey(hit))) return hit
+      const { evidence: _evidence, knowledge: _knowledge, ...reference } = hit
+      return { ...reference, content: '' }
+    })
+    const deliveredWiki = options.detail ? wiki : wiki.filter(card => deliveredKeys.has(cardKey(card)))
     /** 哪些扩展卡片真的进了上下文（被预算挡住的也如实报出来）。 */
     expansion.included = packed.items
       .filter(item => item.reason === 'expansion' && item.wiki !== null)
@@ -10789,9 +10976,11 @@ export class KnowledgeRuntime {
     }
 
     const data: RecallResult = {
-      hits, context: packed.items, wiki, graph, backend, routes: ranRoutes, recallMode, rerank, recallTopK, candidatePool, fusedCount, contextTopN,
+      hits: deliveredHits, context: packed.items, wiki: deliveredWiki, graph, backend, routes: ranRoutes, recallMode, rerank, recallTopK, candidatePool, fusedCount, contextTopN,
       queryAnalysis,
-      insufficientEvidence, diagnostics, recallId, timings,
+      insufficientEvidence: insufficientEvidence || !packed.items.some(item => item.reason === 'hit' && item.wiki),
+      foundCandidates: hits.length > 0, contentDelivered: packed.items.some(item => item.reason === 'hit' && item.wiki),
+      diagnostics, recallId, timings,
       expansion, budget: packed.report,
       ...(ledger === undefined ? {} : { ledger }),
       ...(indexVersion === undefined ? {} : { indexVersion }),
@@ -10936,6 +11125,20 @@ export class KnowledgeRuntime {
    * 路径是知识库里的真实文件，读它与读这里的内容是同一份数据，而且没有配额。这样
    * 「一次读不完」就不再等于「读不到」，也不会出现「以为拿到全文、其实只有前 4 万字符」。
    */
+  async readSource(input: SourceReadInput, lineage?: LineageContext): Promise<Envelope<Record<string, unknown>>> {
+    if (!this.config.allowSourceTruth) return failure({}, 'SOURCE_TRUTH_DISABLED', '当前配置禁止访问 Source Raw。', false)
+    const db = await this.storeHandle()
+    if (!db) return failure({}, 'STORE_UNAVAILABLE', '来源存储不可用。', true)
+    try {
+      const data = readSourceExact(db, input)
+      await this.audit('source_truth.read_exact', { sourceId: input.sourceId, version: data.version, start: data.start, end: data.end, lineage })
+      return success({ ...data, sourceIdentity: db.sourceIdentities(input.sourceId), readRef: { ...(data.readRef as object), kb: this.baseId || 'default' }, nextRead: data.nextRead ? { ...(data.nextRead as Record<string, unknown>), args: { ...((data.nextRead as any).args), kb: this.baseId || 'default' } } : undefined })
+    } catch (error) {
+      if (error instanceof SourceReadError) return failure({}, error.code, error.message, false)
+      throw error
+    }
+  }
+
   async sourceTruth(query: string, limit = 20, maxChars = 40000, lineage?: LineageContext, offset = 0, sourceOffset = 0): Promise<Envelope<{ sources: SourceRawRead[]; sourceReadId: string; maxChars: number; offset: number; returnedChars: number; truncated: boolean; hasMoreInCurrentPage: boolean; totalMatchedSources: number; sourceOffset: number; hasMoreSources: boolean; nextSourceOffset?: number; lineage?: LineageContext }>> {
     const sourceReadId = generatedId('source-read')
     const empty = { sources: [] as SourceRawRead[], sourceReadId, maxChars, offset, returnedChars: 0, truncated: false, hasMoreInCurrentPage: false, totalMatchedSources: 0, sourceOffset, hasMoreSources: false }
@@ -10944,6 +11147,7 @@ export class KnowledgeRuntime {
     if (!Number.isInteger(offset) || offset < 0) return failure(empty, 'SOURCE_OFFSET_INVALID', 'offset 必须是不小于 0 的整数；它接着上一页的 returnedChars 往下读', false)
     if (!Number.isInteger(sourceOffset) || sourceOffset < 0) return failure(empty, 'SOURCE_OFFSET_INVALID', 'source_offset 必须是不小于 0 的整数；需要读更多来源时使用返回的 nextSourceOffset', false)
     const queryTokens = tokens(query)
+    const sourceDb = await this.storeHandle()
     const matchedSources = (await this.loadSources()).filter(item => !queryTokens.length || queryTokens.some(token => `${item.title}\n${item.content}`.toLocaleLowerCase().includes(token)))
     const sources = matchedSources.slice(sourceOffset, sourceOffset + limit)
     const hasMoreSources = sourceOffset + sources.length < matchedSources.length
@@ -10981,6 +11185,8 @@ export class KnowledgeRuntime {
       if (content.length === 0 && source.content.length > 0) continue
       bounded.push({
         ...source,
+        version: sourceDb?.source(source.sourceId)?.version,
+        readRef: { kb: this.baseId || 'default', source_id: source.sourceId, version: sourceDb?.source(source.sourceId)?.version, content_hash: createHash('sha256').update(source.content).digest('hex') },
         content,
         /*
          * 这里原先回一个**磁盘绝对路径**，工具描述让 Agent「截断了就去读那个文件」。