dsh-data-domain-knowledge 0.1.0-alpha.13 → 0.1.0-alpha.14

package/lib/types/runtime.js

@@ -13,11 +13,14 @@ import { MAX_LOG_ITEMS, OperationLog, operationId } from './oplog.js';
 import { ExtractionRunStore, extractionRunId } from './extraction-runs.js';
 import { AxisRegistry, normalizeAxisName } from './axis-registry.js';
 import { KNOWLEDGE_STATE_LABEL, KnowledgeStore } from './knowledge.js';
-import { compositeEventIdentity, eventEntityFromRecords } from './events.js';
+import { compositeEventIdentity, eventEntityFromRecords, stripEventReferenceSection } from './events.js';
 import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandidates, RELATES_TO } from './extract.js';
 import { skeletonBody } from './extract-model.js';
-import { applyTrialAxisResolution, normalizeKnowledge, runWikiTrial, trialSummary } from './wiki-trial.js';
-import { candidatesFromReport, coordinateIdsOf } from './wiki-materialize.js';
+import { applyTrialAxisResolution, cardNameFor, normalizeKnowledge, runWikiTrial, trialSummary } from './wiki-trial.js';
+import { EXTRACTION_CONTRACT_VERSION } from './extract-table.js';
+import { KnowledgePipeline } from './pipeline/engine.js';
+import { PipelineStore } from './pipeline/store.js';
+import { candidatesFromReport, coordinateIdsOf, coordinateIsEmpty } from './wiki-materialize.js';
 import { buildOrganizePrompt, buildOrganizeSystem, checkOrganize, citationsFrom, layoutHash, layoutOf, parseOrganize, placementsOf, renderFootnoteDefinitions, renderOrganizeBody, } from './card-organize.js';
 import { FTS_FILE, loadSqlite, segment } from './fts.js';
 import { attachImagesToKnowledge, insertImage, planSourceImages } from './source-images.js';
@@ -684,38 +687,6 @@ function appendExtracted(existing, additions) {
     }
     return content;
 }
-/** 坐标 WikiCard 的事件摘要段由 Event 引用派生；全文与时间线留在独立 Event 实体。 */
-function withEventReferences(content, rawRefs, eventsById) {
-    let refs = [];
-    if (Array.isArray(rawRefs))
-        refs = rawRefs.filter((item) => typeof item === 'string');
-    else if (typeof rawRefs === 'string') {
-        try {
-            const parsed = JSON.parse(rawRefs);
-            if (Array.isArray(parsed))
-                refs = parsed.filter((item) => typeof item === 'string');
-        }
-        catch { /* 无效引用会作为空列表处理 */ }
-    }
-    const lines = content.split('\n');
-    const start = lines.findIndex(line => line.trim() === '## 关联 Event');
-    if (start >= 0) {
-        let end = start + 1;
-        while (end < lines.length && !/^#{1,2}\s+/.test(lines[end] ?? ''))
-            end += 1;
-        lines.splice(start, end - start);
-    }
-    const base = lines.join('\n').trimEnd();
-    const entries = [...new Set(refs)].map(id => eventsById.get(id)).filter((event) => event !== undefined);
-    if (entries.length === 0)
-        return base;
-    const bullets = entries.map(event => {
-        const occurredAt = event.occurredAt ? ` · ${event.occurredAt}` : '';
-        const summary = event.summary.trim() ? `：${event.summary.trim()}` : '';
-        return `- **${event.title}**${occurredAt}${summary}（${event.id}）`;
-    });
-    return `${base ? `${base}\n\n` : ''}## 关联 Event\n\n${bullets.join('\n')}`;
-}
 /** 把 `incoming` 按小节折进 `existing`；结构对不上时整段追加。 */
 function foldBody(existing, incoming) {
     if (!existing)
@@ -1008,9 +979,10 @@ function markdownImageRefs(content) {
  *    `tags` / `generated` / `sources`。它们是真 YAML 键，人能读、`grep` 得到、
  *    外部工具能按公开规范读走。`generated.at` 就是**采集时间**（OKF 里没有「抓取
  *    时间」这个概念，本文件何时被谁写出来就是它）。
- * 2. **我们自己的运行键**：`source_id` / `external_id` / `created_at` / `updated_at` /
- *    `metadata` / `lineage`。OKF 明确允许自定义键，且要求消费者不得因为未知键拒收，
- *    所以这两类可以同处一个 front matter。
+ * 2. **我们自己的运行键**：`created_at` / `updated_at` / `metadata` / `lineage`。
+ *    来源身份保存在 SQLite 的 `entity_id` / `external_id` 列，不在 front matter 重复一份。
+ *    OKF 明确允许自定义键，且要求消费者不得因为未知键拒收，所以运行元数据可以同处
+ *    一个 front matter。
  *
  * `metadata` 只剩**类型专属的扩展键**（转换任务 id、内容哈希、资产清单、格式…）：
  * 那些东西 OKF 没有对应概念，但也不该混进上面那组公开字段里。
@@ -1043,8 +1015,6 @@ function sourceFrontMatter(record, provenance) {
             ...(origin.lastModified?.trim() ? { last_modified: origin.lastModified.trim() } : {}),
         }));
     }
-    frontMatter.source_id = record.sourceId;
-    frontMatter.external_id = record.externalId ?? '';
     frontMatter.created_at = record.createdAt;
     frontMatter.updated_at = record.updatedAt;
     frontMatter.metadata = record.metadata;
@@ -1551,6 +1521,9 @@ export class KnowledgeRuntime {
     /** 抽取轨迹（`<memoryDir>/extraction-runs.sqlite`）。同一个懒打开的理由。 */
     extractionRunsStore = null;
     extractionRunsReady = null;
+    closed = false;
+    pipelineEngine;
+    pipelineOpening;
     /** 轴注册表（`<memoryDir>/knowledge.sqlite`）。与抽取轨迹同一个懒打开的理由。 */
     axesStore = null;
     axesReady = null;
@@ -2292,6 +2265,10 @@ export class KnowledgeRuntime {
         return { vectors, device };
     }
     close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.pipelineEngine?.close();
         for (const task of this.compileTasks.values()) {
             if (['succeeded', 'failed', 'cancelled'].includes(task.progress.state))
                 continue;
@@ -2299,6 +2276,13 @@ export class KnowledgeRuntime {
             task.pauseRequested = false;
             task.resume?.();
         }
+        if (this.compilePending > 0) {
+            void this.compileTail.finally(() => this.closeStores());
+            return;
+        }
+        this.closeStores();
+    }
+    closeStores() {
         this.embeddingWorker?.close();
         this.embeddingWorker = null;
         this.rerankWorker?.close();
@@ -2680,39 +2664,26 @@ export class KnowledgeRuntime {
         if (written.length === 0) {
             return failure({ ...empty, failed, attempted: items.length }, 'IMPORT_ALL_FAILED', `${items.length} 份来源全部写入失败，没有任何东西进入知识库`, true, failed[0] ? `第一份的原因：${failed[0].message}` : undefined);
         }
-        /**
-         * 编译。**只要有一份写成就编**：成功的那几份已经是库里的知识，
-         * 「因为同批里有一份失败就不编」等于把已经进来的知识又挡在门外一次。
-         */
         let compile = null;
-        if (input.compile !== false) {
-            let rebuilt;
+        if (input.compile === true) {
             try {
-                rebuilt = await this.rebuild('wiki', input.lineage);
-            }
-            catch (cause) {
-                warnings.push(`来源已写入，编译未完成：${cause instanceof Error ? cause.message : String(cause)}`);
-            }
-            if (rebuilt === undefined)
-                return success({ written, failed, attempted: items.length, compile }, warnings);
-            if (rebuilt.ok === false) {
-                warnings.push(`来源已写入，但编译失败：${rebuilt.error?.message ?? '未知原因'}`);
-            }
-            else {
-                const data = rebuilt.data;
+                const before = new Map((await this.loadCards()).map(card => [card.entityId, this.cardHashOf(card)]));
+                const pipeline = await this.pipeline();
+                const task = await pipeline.start('all', { sourceIds: written.map(source => source.sourceId) }).completion;
+                const after = await this.loadCards();
                 compile = {
-                    cardsCreated: data.cardsCreated,
-                    cardsUpdated: data.cardsUpdated,
-                    cardsReused: data.cardsReused,
-                    notesReused: data.notesReused,
-                    notesRecompiled: data.notesRecompiled,
-                    sourcesExtracted: data.sourcesExtracted,
-                    sourcesSkipped: data.sourcesSkipped,
-                    cardsRemoved: data.cardsRemoved,
-                    embedding: data.embedding,
-                    version: data.version,
+                    taskId: task.id, state: task.state,
+                    cardsCreated: after.filter(card => !before.has(card.entityId)).length,
+                    cardsUpdated: after.filter(card => before.has(card.entityId) && before.get(card.entityId) !== this.cardHashOf(card)).length,
+                    sourcesExtracted: Math.max(0, (task.results?.extract?.done ?? 0) - (task.results?.extract?.reused ?? 0) - (task.results?.extract?.failed ?? 0)),
+                    sourcesSkipped: task.results?.extract?.reused ?? 0,
                 };
-                warnings.push(...(rebuilt.warnings ?? []));
+                warnings.push(...task.warnings);
+                if (task.state !== 'succeeded')
+                    warnings.push(`来源已保存；全链路未完成：${task.summary}。可在知识处理页面继续。`);
+            }
+            catch (cause) {
+                warnings.push(`来源已保存；知识处理未完成：${cause instanceof Error ? cause.message : String(cause)}`);
             }
         }
         return success({ written, failed, attempted: items.length, compile }, warnings);
@@ -3894,10 +3865,11 @@ export class KnowledgeRuntime {
         const store = await this.knowledgeStore();
         if (store === null)
             return { ok: false, reason: '知识库不可用，这次没有组织卡片（正文退回确定性布局）' };
-        const listed = await store.list({
+        const listed = input.knowledge ? { knowledge: input.knowledge, total: input.knowledge.length } : await store.list({
             objectId: input.coordinate.objectId,
             actionId: input.coordinate.actionId,
             sceneId: input.coordinate.sceneId,
+            excludeWithdrawn: true,
             limit: MAX_ORGANIZE_KNOWLEDGE,
         });
         if (listed.knowledge.length === 0) {
@@ -4075,7 +4047,8 @@ export class KnowledgeRuntime {
         if (call === undefined)
             return failure({ card, warnings: [] }, 'MODEL_UNAVAILABLE', '当前没有可用的模型，无法重新组织这张卡片', true, '检查模型配置后再试。');
         const profile = this.organizeProfile();
-        const related = await this.relatedForCard(card);
+        const organizationCard = { ...card, content: stripEventReferenceSection(card.content) };
+        const related = await this.relatedForCard(organizationCard);
         const images = await this.imagesForCard(card);
         const organized = await this.organizeCard({
             cardTitle: card.title,
@@ -4086,7 +4059,7 @@ export class KnowledgeRuntime {
             ...(profile === undefined ? {} : { requiredSections: profile.sections.filter(section => section.required).map(section => section.label) }),
             ...(related.related === undefined ? {} : { related: related.related }),
             ...(images.images.length === 0 ? {} : { images: images.images }),
-            existing: card,
+            existing: organizationCard,
             call,
         });
         if (organized.kind !== 'applied') {
@@ -4097,7 +4070,7 @@ export class KnowledgeRuntime {
             entityType: card.entityType,
             entityId: card.entityId,
             title: organized.title,
-            content: organized.content,
+            content: stripEventReferenceSection(organized.content),
             sourceRefs: card.sourceRefs,
             summary: organized.summary,
             status: card.status,
@@ -4183,6 +4156,7 @@ export class KnowledgeRuntime {
     }
     async organizeCard(input) {
         const context = await this.organizeContext({
+            knowledge: input.knowledge,
             cardTitle: input.cardTitle,
             coordinate: input.coordinate,
             profileId: input.profileId,
@@ -4511,7 +4485,7 @@ export class KnowledgeRuntime {
         return cards.flatMap(card => this.compileCardNotes(card));
     }
     compileCardNotes(card) {
-        if (card.status === 'problem')
+        if (card.status === 'problem' || card.status === 'deprecated')
             return [];
         const notes = [];
         /**
@@ -4529,7 +4503,7 @@ export class KnowledgeRuntime {
          * `metadata.related_cards`；这里继续剥离旧版本正文里的标记，保证存量卡片迁移期间
          * 也不会把导航送进召回。
          */
-        const recallBody = stripRelatedSection(card.content);
+        const recallBody = stripEventReferenceSection(stripRelatedSection(card.content));
         for (const [index, chunk] of splitWikiNotes({ ...card, content: recallBody }).entries()) {
             const baseId = `${card.entityType}:${card.entityId}`;
             const unitId = index === 0 ? baseId : `${baseId}#${index}`;
@@ -4595,7 +4569,7 @@ export class KnowledgeRuntime {
         const provider = this.config.rerankProvider;
         if (provider === 'none')
             return { hits, result: { status: 'skipped', provider, threshold } };
-        if (hits.length < 2)
+        if (hits.length === 0)
             return { hits, result: { status: 'skipped', provider, model: this.rerankModelPath, scored: hits.length, threshold } };
         if (this.rerankUnavailable)
             return { hits, result: { status: 'unavailable', provider, model: this.rerankModelPath, error: this.rerankUnavailable, threshold }, warning: `重排不可用，已按融合分数排序：${this.rerankUnavailable}` };
@@ -4843,7 +4817,6 @@ export class KnowledgeRuntime {
          */
         const profile = this.organizeProfile();
         const profileId = profile?.id ?? 'concept';
-        const eventsById = new Map((await this.loadEvents()).map(event => [event.id, event]));
         for (const item of pending.values()) {
             if (runId)
                 await this.checkpointCompileTask(runId);
@@ -4892,7 +4865,7 @@ export class KnowledgeRuntime {
                 && layoutOf(existing.metadata)?.origin === 'model';
             const finalTitle = preserveModelLayout ? existing.title : item.title;
             const contentBeforeEvents = preserveModelLayout ? existing.content : content;
-            const finalContent = withEventReferences(contentBeforeEvents, item.metadata.event_refs, eventsById);
+            const finalContent = stripEventReferenceSection(contentBeforeEvents);
             const finalSummary = preserveModelLayout ? existing.summary : item.summary;
             let finalPlacements = preserveModelLayout || item.placements === undefined
                 ? undefined
@@ -4986,7 +4959,7 @@ export class KnowledgeRuntime {
             for (const warning of written.warnings ?? [])
                 outcome.warnings.push(`卡片 ${card.entityId}：${warning}`);
         }
-        // WikiCard 是 Knowledge 与 Event 的坐标聚合层；Event 本体读自独立 event 表。
+        // WikiCard 只由 Knowledge 物化；Event 作为独立事实按坐标挂引用。
         const eventSync = await this.syncEventReferences();
         outcome.cardsUpdated += eventSync.updated;
         outcome.warnings.push(...eventSync.warnings);
@@ -5035,8 +5008,9 @@ export class KnowledgeRuntime {
          * 用的输入与收尾阶段那个相关块**完全相同**（同一份 `relations` + 同一个坐标投影），
          * 所以「正文里能提到谁」与「末尾相关块列了谁」不会是两个答案。
          */
-        const relatedPlan = planRelated(input.cards, input.relations, await this.projectedRelated(input.cards));
-        const withCoordinate = input.cards
+        const cardsWithoutLegacyEventSections = input.cards.map(card => ({ ...card, content: stripEventReferenceSection(card.content) }));
+        const relatedPlan = planRelated(cardsWithoutLegacyEventSections, input.relations, await this.projectedRelated(input.cards));
+        const withCoordinate = cardsWithoutLegacyEventSections
             .filter(card => card.coordinate !== undefined)
             .sort((left, right) => left.entityId.localeCompare(right.entityId));
         if (withCoordinate.length === 0)
@@ -5674,7 +5648,7 @@ export class KnowledgeRuntime {
         const projected = await this.projectedRelated(cards);
         const related = planRelated(cards, relations, projected);
         /** 统计清理旧导航块之后的正文断链；相关卡片本身不再伪装成正文链接。 */
-        const nextCards = cards.map(card => ({ ...card, content: stripRelatedSection(card.content) }));
+        const nextCards = cards.map(card => ({ ...card, content: stripEventReferenceSection(stripRelatedSection(card.content)) }));
         const deadLinks = deadLinksOf(nextCards);
         let rewritten = 0;
         for (const [index, card] of cards.entries()) {
@@ -6390,6 +6364,7 @@ export class KnowledgeRuntime {
      * 不能当成「没命中」。
      */
     async resolveTrialAxisSet(input) {
+        const resolve = (value) => this.resolveAxisMention({ ...value, registry: input.registry });
         const groups = [
             { kind: 'object', key: 'objects' },
             { kind: 'action', key: 'actions' },
@@ -6400,7 +6375,7 @@ export class KnowledgeRuntime {
         const axisKey = (kind, mention) => `${kind}\u0000${normalizeAxisName(mention)}`;
         const supplementalEntries = { object: [], action: [], scene: [] };
         try {
-            const registry = await this.axisRegistry();
+            const registry = input.registry ?? await this.axisRegistry();
             if (registry !== null) {
                 // 初次抽取的候选清单可能被截断。再按本批轴 mention 做一次本地召回，补进未下发的已有坐标。
                 const query = groups.flatMap(group => input.axes[group.key].flatMap(axis => [
@@ -6455,7 +6430,7 @@ export class KnowledgeRuntime {
                 const key = axisKey(group.kind, axis.name);
                 let lookup;
                 try {
-                    lookup = await this.resolveAxisMention({
+                    lookup = await resolve({
                         kind: group.kind,
                         mention: axis.name,
                         parentMention: axis.parentMention,
@@ -6519,7 +6494,7 @@ export class KnowledgeRuntime {
                     continue;
                 }
                 // 没有可供模型比较的现有候选时，沿用注册表的新建候选路径。
-                const created = await this.resolveAxisMention({
+                const created = await resolve({
                     kind: group.kind,
                     mention: axis.name,
                     parentMention: axis.parentMention,
@@ -6629,7 +6604,7 @@ export class KnowledgeRuntime {
             const key = axisKey(item.kind, item.axis.name);
             const judgment = decisions.get(key);
             if (judgment?.decision === 'new') {
-                const resolution = await this.resolveAxisMention({
+                const resolution = await resolve({
                     kind: item.kind,
                     mention: item.axis.name,
                     parentMention: item.axis.parentMention,
@@ -6643,7 +6618,7 @@ export class KnowledgeRuntime {
             if (judgment?.decision === 'match') {
                 const candidate = item.candidates.find(value => value.id === judgment.candidateId);
                 if (candidate) {
-                    const resolution = await this.resolveAxisMention({
+                    const resolution = await resolve({
                         kind: item.kind,
                         mention: item.axis.name,
                         parentMention: item.axis.parentMention,
@@ -6672,7 +6647,7 @@ export class KnowledgeRuntime {
         };
     }
     async resolveAxisMention(input) {
-        const registry = await this.axisRegistry();
+        const registry = input.registry ?? await this.axisRegistry();
         if (registry === null)
             return null;
         const runId = input.runId ?? '';
@@ -6688,7 +6663,7 @@ export class KnowledgeRuntime {
             if (parent.entity)
                 parentId = parent.entity.id;
         }
-        const preferId = await this.axisIdByName(input.kind, input.preferMention);
+        const preferId = await this.axisIdByName(input.kind, input.preferMention, registry);
         return registry.resolve({
             kind: input.kind, mention: input.mention,
             ...(parentId ? { parentId } : {}), ...(runId ? { runId } : {}),
@@ -6704,11 +6679,11 @@ export class KnowledgeRuntime {
      * 「是已有的某个东西」而那个名字在库里指两个实体时，把它当成指认就等于替人做了
      * 「哪一个」的决定 —— 而注册表的规矩是「不唯一就不猜」。
      */
-    async axisIdByName(kind, mention) {
+    async axisIdByName(kind, mention, supplied) {
         const name = (mention ?? '').trim();
         if (!name)
             return undefined;
-        const registry = await this.axisRegistry();
+        const registry = supplied ?? await this.axisRegistry();
         if (registry === null)
             return undefined;
         try {
@@ -7461,14 +7436,12 @@ export class KnowledgeRuntime {
             refs.push(event.id);
             eventsByCoordinate.set(key, refs);
         }
-        const eventIndex = new Map(events.map(event => [event.id, event]));
         const warnings = [];
         let updated = 0;
         for (const card of await this.loadCards()) {
-            const refs = card.coordinate === undefined
+            const refs = card.status === 'deprecated' || card.coordinate === undefined || card.entityType === 'diagnosis/case'
                 ? []
                 : (eventsByCoordinate.get(coordinateKeyOf(card.coordinate)) ?? []).sort();
-            db.setCardEvents(card.entityId, refs);
             const oldRaw = card.metadata.event_refs;
             let oldRefs = [];
             let oldRefsValid = false;
@@ -7486,13 +7459,17 @@ export class KnowledgeRuntime {
                 oldRefs = oldRaw.filter((item) => typeof item === 'string').sort();
                 oldRefsValid = true;
             }
-            const content = withEventReferences(card.content, refs, eventIndex);
+            const content = stripEventReferenceSection(card.content);
             const contentChanged = content !== card.content;
             const refsChanged = !oldRefsValid || JSON.stringify(refs) !== JSON.stringify(oldRefs);
-            if (!refsChanged && !contentChanged)
+            if (!refsChanged && !contentChanged) {
+                db.setCardEvents(card.entityId, refs);
                 continue;
-            if (!oldRefsValid && refs.length === 0 && oldRaw === undefined && !contentChanged)
+            }
+            if (!oldRefsValid && refs.length === 0 && oldRaw === undefined && !contentChanged) {
+                db.setCardEvents(card.entityId, refs);
                 continue;
+            }
             const written = await this.writeCard({
                 ...card,
                 sourceRefs: card.sourceRefs,
@@ -7501,9 +7478,11 @@ export class KnowledgeRuntime {
                 origin: 'internal',
             });
             if (written.ok === false)
-                warnings.push(`坐标 WikiCard ${card.title} 的 Event 聚合视图未更新：${written.error.message}`);
-            else
+                warnings.push(`WikiCard ${card.title} 的 Event 引用未更新：${written.error.message}`);
+            else {
+                db.setCardEvents(card.entityId, refs);
                 updated += 1;
+            }
         }
         return { updated, warnings };
     }
@@ -7524,10 +7503,6 @@ export class KnowledgeRuntime {
         const ids = {};
         for (const event of db.events()) {
             const remaining = event.records.filter(record => record.sourceId !== input.sourceId);
-            if (remaining.length === 0) {
-                db.removeEvent(event.id);
-                continue;
-            }
             const state = {
                 id: event.id,
                 identityKey: event.identityKey,
@@ -7629,8 +7604,12 @@ export class KnowledgeRuntime {
                 saved += 1;
         }
         for (const state of states.values()) {
-            if (!state.dirty || state.records.length === 0)
+            if (!state.dirty)
+                continue;
+            if (state.records.length === 0) {
+                db.removeEvent(state.id);
                 continue;
+            }
             const records = state.records;
             const entity = eventEntityFromRecords({
                 id: state.id,
@@ -7650,6 +7629,298 @@ export class KnowledgeRuntime {
         }
         return { saved, merged, skipped, ids, warnings };
     }
+    /** The stage runner shares this base's existing writer queue and audit database. */
+    async pipeline() {
+        if (this.closed)
+            throw new Error('知识库已关闭');
+        this.pipelineOpening ??= (async () => {
+            const db = await this.storeHandle();
+            const audit = await this.extractionRuns();
+            if (this.closed)
+                throw new Error('知识库已关闭');
+            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' }),
+                serialize: work => {
+                    this.compilePending += 1;
+                    const run = this.compileTail.then(work, work);
+                    this.compileTail = run.then(() => undefined, () => undefined).finally(() => { this.compilePending -= 1; });
+                    return run;
+                },
+                sources: () => this.pipelineSources(),
+                fingerprint: (source, context) => contentHashOf(JSON.stringify({ source: source.sourceHash, title: source.title, contract: EXTRACTION_CONTRACT_VERSION, note: context.note, format: context.format, model: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } })),
+                extract: async (source, context, onDelta) => {
+                    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 });
+                },
+                normalize: (source, checkpoint, context, force, output) => this.normalizePipelineSource(store, source, checkpoint, context, force, output),
+                groups: context => this.materializationGroups(store, context),
+                materialize: (group, context, output) => this.materializePipelineGroup(store, group, context, output),
+                build: async (taskId, checkpoint) => {
+                    let result;
+                    try {
+                        result = await this.compileOnce(taskId, 'all', undefined, { extract: false, checkpoint });
+                    }
+                    catch (cause) {
+                        await this.settleProgressFailure(taskId, cause);
+                        throw cause;
+                    }
+                    this.settleProgressReport(taskId, result);
+                    if (!result.ok)
+                        throw new Error(result.error.message);
+                    return `检索索引已发布：v${result.data.version}`;
+                },
+                record: async (checkpoint) => {
+                    const audit = await this.recordExtractionRun({ id: checkpoint.id, docId: checkpoint.sourceId, title: checkpoint.report.title, summary: trialSummary(checkpoint.report), report: checkpoint.report });
+                    if (!audit.saved)
+                        throw new Error(`抽取报告保存失败：${audit.why}`);
+                },
+            });
+            this.pipelineEngine = engine;
+            if (this.closed)
+                engine.close();
+            return engine;
+        })();
+        return this.pipelineOpening;
+    }
+    async pipelineSources() {
+        const db = await this.storeHandle();
+        if (!db)
+            throw new Error('来源存储不可用');
+        return db.sources().map(row => ({ ...row.record, version: row.version, sourceHash: contentHashOf(row.record.content) })).sort((a, b) => a.sourceId.localeCompare(b.sourceId));
+    }
+    async normalizationFingerprint(checkpoint, context) {
+        const registry = await this.axisRegistry();
+        const report = checkpoint.normalized?.report ?? checkpoint.report;
+        const query = [...report.objects, ...report.actions, ...report.scenes].flatMap(axis => [axis.name, axis.existing ?? '', axis.definition ?? '', axis.parentMention ?? '']).join('\n');
+        const candidates = await registry?.promptEntries(24, query);
+        const mentions = [...checkpoint.report.objects, ...checkpoint.report.actions, ...checkpoint.report.scenes].flatMap(axis => [axis.name, axis.existing ?? '', axis.parentMention ?? '']).map(normalizeAxisName).filter(Boolean);
+        const resolvedIds = new Set([...report.objects, ...report.actions, ...report.scenes].map(axis => axis.id).filter(Boolean));
+        // Ignore unrelated filler rows and registry recency; retain candidates that can affect these mentions.
+        const relevant = Object.fromEntries(Object.entries(candidates?.entries ?? {}).map(([kind, entries]) => [kind, entries.filter(entry => resolvedIds.has(entry.id) || mentions.some(mention => [entry.name, ...entry.aliases, entry.description].map(normalizeAxisName).some(value => value.includes(mention) || (value.length > 1 && mention.includes(value))))).sort((a, b) => a.id.localeCompare(b.id))]));
+        return contentHashOf(JSON.stringify({ extraction: checkpoint.id, model: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort }, candidates: relevant }));
+    }
+    async normalizePipelineSource(store, source, checkpoint, context, force, output) {
+        const fingerprint = await this.normalizationFingerprint(checkpoint, context);
+        if (!force && checkpoint.normalized?.fingerprint === fingerprint && store.head(source.sourceId).normalized?.id === checkpoint.id)
+            return { reused: true, warnings: [] };
+        if (!checkpoint.report.model.response)
+            throw new Error('抽取记录没有原始返回，无法归一；请重新抽取该文档');
+        const registry = await this.axisRegistry();
+        if (!registry)
+            throw new Error('实体注册表不可用');
+        const draft = await registry.draft();
+        try {
+            const axesBlock = await this.axisPromptBlock(source.content);
+            const call = context.model.call ? request => context.model.call({ ...request, onDelta: output }) : undefined;
+            const report = await runWikiTrial({
+                title: source.title, text: source.content, docId: source.sourceId, axes: axesBlock,
+                // Reparse the captured response; this callback never requests another extraction.
+                call: async () => checkpoint.report.model.response, modelRequest: checkpoint.report.model.request,
+                resolveAxisSet: axes => this.resolveTrialAxisSet({ registry: draft.registry, axes, axesBlock, runId: checkpoint.id, call, modelRequest: context.model }),
+            });
+            if (!report.model.parsed)
+                throw new Error(report.model.why ?? '抽取结果无法归一');
+            const db = await this.storeHandle();
+            const current = db?.source(source.sourceId);
+            if (this.closed)
+                throw new Error('知识库已关闭，本次归一未提交');
+            if (!db || !current || current.version !== source.version || contentHashOf(current.record.content) !== source.sourceHash)
+                throw new Error('来源在归一期间已变化，请重新抽取最新版本');
+            const sql = db.connection();
+            sql.exec('SAVEPOINT pipeline_normalize');
+            try {
+                draft.commit();
+                // Preserve evidence history while replacing this source's active contribution.
+                sql.prepare('UPDATE knowledge_sources SET withdrawn=1 WHERE document_id=?').run(source.sourceId);
+                const knowledge = await this.ingestTrialKnowledge({ runId: checkpoint.id, knowledge: report.knowledge, objects: report.objects, actions: report.actions, scenes: report.scenes, sourceVersions: { [source.sourceId]: source.version } });
+                const events = await this.ingestTrialEvents({ sourceId: source.sourceId, runId: checkpoint.id, events: report.events, objects: report.objects, actions: report.actions, scenes: report.scenes });
+                if (knowledge.skipped || events.skipped)
+                    throw new Error(`出处核验或写入失败：${knowledge.skipped} 条 Knowledge、${events.skipped} 个 Event；本次归一没有提交`);
+                const unresolvedKnowledgeIds = report.knowledge.filter(item => [['object', report.objects], ['action', report.actions], ['scene', report.scenes]].some(([kind, axes]) => {
+                    const name = item[kind];
+                    const axis = name ? axes.find(axis => axis.name === name) : undefined;
+                    return name !== null && (!axis || axis.outcome === 'ambiguous' || axis.outcome === 'no-registry');
+                })).map(item => knowledge.ids[item.id]).filter(Boolean);
+                const normalized = { report, knowledgeIds: knowledge.ids, eventIds: events.ids, unresolvedKnowledgeIds, fingerprint: '' };
+                // Store the post-resolution candidate snapshot so learning its own entities does not invalidate this run.
+                normalized.fingerprint = await this.normalizationFingerprint({ ...checkpoint, normalized }, context);
+                store.saveNormalization(checkpoint, normalized);
+                sql.exec('RELEASE pipeline_normalize');
+                // Updating Event references is a cheap relation refresh. It does not reorganize or index card content.
+                const eventReferences = await this.syncEventReferences();
+                return { reused: false, warnings: [...events.warnings, ...eventReferences.warnings, ...(unresolvedKnowledgeIds.length ? [`${unresolvedKnowledgeIds.length} 条 Knowledge 的坐标仍有歧义，保留事实与出处，暂不物化。`] : [])] };
+            }
+            catch (cause) {
+                sql.exec('ROLLBACK TO pipeline_normalize; RELEASE pipeline_normalize');
+                throw cause;
+            }
+        }
+        finally {
+            draft.close();
+        }
+    }
+    async activePipelineKnowledge() {
+        const knowledge = await this.knowledgeStore();
+        const db = await this.storeHandle();
+        if (!knowledge || !db)
+            return [];
+        const rows = [];
+        for (let offset = 0;; offset += 500) {
+            const page = await knowledge.list({ excludeWithdrawn: true, limit: 500, offset });
+            rows.push(...page.knowledge.filter(row => row.status !== 'deprecated').map(row => assessKnowledgeEvidence(row, db)).map(row => ({ ...row, sources: row.sources.filter(source => !source.withdrawn && source.evidenceStatus !== 'missing') })).filter(row => row.sources.length > 0));
+            if (offset + page.knowledge.length >= page.total)
+                break;
+        }
+        return rows;
+    }
+    async materializationGroups(store, context) {
+        const unresolved = store.unresolvedKnowledge();
+        const groups = new Map();
+        let blocked = 0;
+        const groupFor = (coordinate) => {
+            const key = coordinateKeyOf(coordinate);
+            if (!groups.has(key))
+                groups.set(key, { coordinate, knowledge: [] });
+            return groups.get(key);
+        };
+        for (const row of await this.activePipelineKnowledge()) {
+            const coordinate = { objectId: row.objectId, actionId: row.actionId, sceneId: row.sceneId };
+            if (coordinateIsEmpty(coordinate)) {
+                blocked += 1;
+                continue;
+            }
+            groupFor(coordinate).knowledge.push(row);
+        }
+        const db = await this.storeHandle();
+        const eventsByCoordinate = new Map();
+        for (const event of db?.events() ?? []) {
+            const coordinate = event.coordinateIds;
+            if (!coordinate.objectId || !coordinate.actionId || !coordinate.sceneId)
+                continue;
+            const key = coordinateKeyOf(coordinate);
+            const bucket = eventsByCoordinate.get(key) ?? [];
+            bucket.push(event);
+            eventsByCoordinate.set(key, bucket);
+        }
+        const cards = await this.loadCards();
+        const byCoordinate = new Map(cards.filter(card => card.coordinate).map(card => [coordinateKeyOf(card.coordinate), card]));
+        const result = [];
+        for (const [key, value] of groups) {
+            const names = await this.coordinateNames(value.coordinate);
+            const existing = byCoordinate.get(key);
+            // Event 只作为卡片引用；它的增删和正文变化不得触发 Knowledge 重新组织。
+            const fingerprint = contentHashOf(JSON.stringify({ knowledge: value.knowledge.map(row => ({ id: row.id, 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 }));
+            const receipt = store.materialization(key);
+            const current = existing && receipt?.fingerprint === fingerprint && receipt.cardId === existing.entityId;
+            const contributingSources = [...new Set(value.knowledge.flatMap(row => row.sources.map(source => source.documentId)))].filter(Boolean).sort();
+            const needsNormalization = value.knowledge.some(row => unresolved.ids.has(row.id)) || contributingSources.some(id => {
+                const source = db?.source(id);
+                const head = store.head(id);
+                return head.normalized ? head.normalized.sourceVersion !== source?.version || head.extracted?.id !== head.normalized.id : value.knowledge.some(row => row.sources.some(evidence => evidence.documentId === id && evidence.toVersion !== undefined && evidence.toVersion !== source?.version));
+            });
+            if (needsNormalization)
+                blocked += value.knowledge.length;
+            result.push({ key, title: existing?.title ?? cardNameFor(names.object || null, names.action || null, names.scene || null), coordinate: value.coordinate, knowledgeCount: value.knowledge.length, eventCount: eventsByCoordinate.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 || groups.has(coordinateKeyOf(card.coordinate)) || !store.materialization(coordinateKeyOf(card.coordinate)) || card.status === 'deprecated')
+                continue;
+            result.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' });
+        }
+        return { groups: result.sort((a, b) => a.title.localeCompare(b.title)), blocked };
+    }
+    async materializePipelineGroup(store, group, context, output) {
+        const db = await this.storeHandle();
+        if (!db)
+            throw new Error('知识库不可用');
+        const fresh = (await this.materializationGroups(store, context)).groups.find(item => item.key === group.key);
+        if (!fresh || fresh.fingerprint !== group.fingerprint)
+            throw new Error('卡片分组在处理期间已变化，请刷新并重试');
+        if (fresh.state === 'blocked')
+            throw new Error(fresh.reason);
+        const storedExisting = group.cardId ? await this.readCard(group.cardId) : undefined;
+        const existing = storedExisting
+            ? { ...storedExisting, content: stripEventReferenceSection(storedExisting.content) }
+            : undefined;
+        if (group.state === 'withdrawn') {
+            if (!existing)
+                return;
+            const written = await this.writeCard({ ...existing, status: 'deprecated', origin: 'compile' });
+            if (!written.ok)
+                throw new Error(written.error.message);
+            store.materialized(group.key, group.fingerprint, existing.entityId);
+            return;
+        }
+        const allKnowledge = await this.activePipelineKnowledge();
+        const knowledge = allKnowledge.filter(row => coordinateKeyOf({ objectId: row.objectId, actionId: row.actionId, sceneId: row.sceneId }) === group.key);
+        const events = db.events().filter(event => coordinateKeyOf(event.coordinateIds) === group.key);
+        const profile = context.profile;
+        const entityType = (profile?.id ?? 'concept');
+        let title = group.title;
+        let content = `## 知识\n\n${knowledge.map(row => `- ${row.text}`).join('\n')}`;
+        let summary = knowledge[0]?.text ?? '';
+        let placements = knowledge.map((row, index) => ({ knowledgeId: row.id, section: '知识', ordinal: index + 1, origin: 'compiler' }));
+        let metadata = { ...(existing?.metadata ?? {}), pipeline_materialization: true };
+        const entityId = existing?.entityId ?? `coord-${hash(group.key)}`;
+        const imagePlan = planSourceImages({
+            cards: (await this.materializationGroups(store, context)).groups.filter(item => item.state !== 'withdrawn').map(item => ({ key: item.key, content: allKnowledge.filter(row => coordinateKeyOf({ objectId: row.objectId, actionId: row.actionId, sceneId: row.sceneId }) === item.key).map(row => row.text).join('\n\n'), sourceRefs: item.sourceIds })),
+            sources: (await this.loadSources()).map(source => ({ sourceId: source.sourceId, content: source.content })),
+        });
+        const images = imagePlan.byCard.get(group.key) ?? [];
+        const related = existing ? await this.relatedForCard(existing) : {};
+        metadata.citations = citationsFrom({ placements, knowledge: new Map(knowledge.map(row => [row.id, { source: row.sources[0]?.documentId, heading: row.sources[0]?.headingPath.at(-1) }])) });
+        if (context.organize && knowledge.length > 0) {
+            if (!context.model.call)
+                throw new Error(`卡片组织模型不可用：${context.model.why ?? '请选择模型'}`);
+            const result = await this.organizeCard({ knowledge, images, ...related, cardTitle: title, coordinate: group.coordinate, profileId: entityType, force: true, suggestedSections: profile?.sections.map(section => section.label), requiredSections: profile?.sections.filter(section => section.required).map(section => section.label), existing, call: request => context.model.call({ ...request, onDelta: output }) });
+            if (result.kind !== 'applied')
+                throw new Error(result.kind === 'reused' ? '组织结果已变化，请刷新后重试' : result.warnings.join('；'));
+            title = result.title;
+            content = result.content;
+            summary = result.summary;
+            placements = result.placements;
+            metadata = { ...metadata, layout: result.layout, citations: result.citations };
+        }
+        for (const image of images)
+            content = insertImage(content, image);
+        const eventIds = events.map(event => event.id).sort();
+        content = stripEventReferenceSection(content);
+        metadata.event_refs = JSON.stringify(eventIds);
+        // Freeze the selected group's facts, not an arbitrary subset of its rows.
+        const latest = (await this.materializationGroups(store, context)).groups.find(item => item.key === group.key);
+        if (!latest || latest.fingerprint !== group.fingerprint || latest.state === 'blocked')
+            throw new Error('卡片组织期间事实发生变化，结果未提交，请重试');
+        if (this.closed)
+            throw new Error('知识库已关闭，本次物化未提交');
+        const written = await this.writeCard({ entityType, entityId, title, content, summary, sourceRefs: group.sourceIds, status: existing?.status === 'deprecated' ? 'unreviewed' : existing?.status ?? 'unreviewed', 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);
+    }
+    async pipelineStatus() {
+        const pipeline = await this.pipeline();
+        const sources = await this.pipelineSources();
+        const context = { model: this.modelSeamNow(), note: this.extractionNote(), profile: this.organizeProfile(), organize: this.config.cardOrganize, format: 'table' };
+        const rows = await Promise.all(sources.map(async (source) => {
+            const head = pipeline.store.head(source.sourceId);
+            const extracted = head.extracted?.sourceVersion === source.version && head.extracted.sourceHash === source.sourceHash;
+            const normalized = extracted && head.normalized?.id === head.extracted?.id && head.normalized?.normalized?.fingerprint === await this.normalizationFingerprint(head.normalized, context);
+            return { id: source.sourceId, title: source.title, version: source.version, extractionId: head.extracted?.id, normalizedId: head.normalized?.id, state: normalized ? 'normalized' : extracted ? 'extracted' : head.extracted ? 'outdated' : 'pending' };
+        }));
+        const { groups, blocked } = await this.materializationGroups(pipeline.store, context);
+        const db = await this.derivedHandle();
+        const manifest = db?.artifact('build-manifest.json');
+        const hashes = manifest ? JSON.parse(manifest).cardHashes ?? {} : {};
+        const cards = await this.loadCards();
+        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 };
+    }
     /** 抽取轨迹列表（新→旧，不含报告本体）。 */
     async listExtractionRuns(query = {}) {
         const store = await this.extractionRuns();
@@ -7853,10 +8124,12 @@ export class KnowledgeRuntime {
      * 它」—— 那两件事分别在 `enqueueCompile()` 与 `rebuild()` / `startCompile()` 里。
      */
     async compileOnce(runId, only = 'all', lineage, options = {}) {
-        await this.environmentGuard?.();
+        if (only === 'all' || only === 'embeddings')
+            await this.environmentGuard?.('embedding');
         this.publication = { artifacts: new Map() };
         const configAtStart = JSON.stringify({ config: this.config, fingerprint: this.embeddingFingerprint() });
         try {
+            await options.checkpoint?.();
             await this.loadCompiledState();
             const result = await this.prepareCompile(runId, only, lineage, options);
             await this.checkpointCompileTask(runId);
@@ -7889,6 +8162,7 @@ export class KnowledgeRuntime {
                 await this.checkpointCompileTask(runId);
                 if (JSON.stringify({ config: this.config, fingerprint: this.embeddingFingerprint() }) !== configAtStart)
                     throw new Error('COMPILE_CONFIG_CHANGED: 编译期间设置已变化，请重新编译');
+                await options.checkpoint?.();
                 db.publish(this.publication);
                 this.vectorIndex = null;
             }
@@ -8042,7 +8316,7 @@ export class KnowledgeRuntime {
                 tally.knowledge > 0
                     ? `抽出知识 ${tally.knowledge} 条`
                     : '未用模型：正文按 ## 小节切',
-                tally.skipped > 0 ? `跳过未变 ${tally.skipped} 份` : '指纹全变，没有可复用的',
+                tally.skipped > 0 ? `复用未变来源 ${tally.skipped} 份` : options.forceExtract ? '本次为手动强制重抽' : '正在检查新增或变化的来源',
             ];
             if (done < total) {
                 setStep('knowledge', 'running', knowledgeFacts);
@@ -9043,7 +9317,7 @@ export class KnowledgeRuntime {
          * 一次召回十来张卡，而库里可能有上千张。
          */
         try {
-            placements = snapshot?.placements.length ? new Map(snapshot.placements) : store.placementsOf([...new Set(hits.map(hit => hit.entityId))]);
+            placements = snapshot ? new Map(snapshot.placements) : store.placementsOf([...new Set(hits.map(hit => hit.entityId))]);
         }
         catch {
             return;
@@ -9065,7 +9339,7 @@ export class KnowledgeRuntime {
         const wanted = new Set(perHit.flat().map(row => row.knowledgeId));
         if (wanted.size === 0)
             return;
-        const rows = snapshot && snapshot.knowledge.length > 0
+        const rows = snapshot
             ? new Map(snapshot.knowledge.filter(row => wanted.has(row.id) && knowledge !== null)
                 .flatMap(row => {
                 // Deleted facts never reappear through a historical snapshot.
@@ -9159,14 +9433,17 @@ export class KnowledgeRuntime {
         if (!Number.isInteger(requestedTopN) || requestedTopN < 1 || (options.contextTopN !== undefined && requestedTopN > recallTopK))
             return failure(empty(), 'CONTEXT_TOP_N_INVALID', `上下文 top_n 必须是 1 到 ${recallTopK} 的整数`, false);
         try {
-            await this.environmentGuard?.();
+            if (recallMode !== 'fts')
+                await this.environmentGuard?.('embedding');
+            if (options.rerank !== false && this.config.rerankProvider !== 'none')
+                await this.environmentGuard?.('rerank');
         }
         catch (cause) {
             return failure(empty(), 'ENVIRONMENT_NOT_READY', cause instanceof Error ? cause.message : String(cause), true, '在 Tita 设置中完成环境准备并重新自检。');
         }
         const derived = await this.derivedHandle();
         const liveCards = await this.loadCards();
-        const liveKeys = new Set(liveCards.map(card => cardKey(card)));
+        const liveKeys = new Set(liveCards.filter(card => card.status !== 'deprecated').map(card => cardKey(card)));
         const snapshotHash = derived?.artifactHash(COMPILE_SNAPSHOT);
         const cached = snapshotHash && this.recallSnapshotCache?.hash === snapshotHash ? this.recallSnapshotCache : undefined;
         const raw = cached ? undefined : derived?.artifact(COMPILE_SNAPSHOT);
@@ -9327,7 +9604,7 @@ export class KnowledgeRuntime {
             ].join('\n');
             const reranked = await this.rerankNotes(rerankQuery, hits, this.config.rerankThreshold);
             rerankScored = reranked.scored ?? [];
-            hits = reranked.hits.slice(0, recallTopK);
+            hits = reranked.hits;
             rerank = reranked.result;
             if (reranked.warning)
                 warnings.push(reranked.warning);
@@ -9337,7 +9614,7 @@ export class KnowledgeRuntime {
         }
         // 重排换的是相关性顺序，评分加权仍然要压在最上面 —— 否则「review 过的排前面一点」
         // 只在关掉重排时成立，而重排默认是开着的。
-        hits = [...hits].sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId));
+        hits = [...hits].sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId)).slice(0, recallTopK);
         // --- R4 · 证据片段 -----------------------------------------------------
         const truth = await this.storeHandle();
         cards = cards.filter(card => truth?.card(card.entityId) !== undefined && card.sourceRefs.every(ref => truth?.source(ref) !== undefined));