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

package/src/knowledge-bases.ts

@@ -30,6 +30,7 @@ import {
 } from './types.js'
 import { defaultKnowledgeRoot, failure, KnowledgeRuntime, success, type KnowledgeRuntimeOptions } from './runtime.js'
 import { defaultAgentRoot, knowledgeBaseRoot, memoryRoot, resourceRoot } from './layout.js'
+import { writeTextAtomic } from './fs-atomic.js'
 
 /** 持久化形态：配置 + 计算字段缓存分区。 */
 interface KnowledgeBaseRecord {
@@ -118,12 +119,13 @@ function textOr(input: unknown, fallback: string): string {
 
 function compileModelOf(input: unknown): CompileModelSelection {
   const value = record(input)
-  if (value.mode !== 'fixed') return { ...DEFAULT_COMPILE_MODEL }
+  const effort = typeof value.reasoningEffort === 'string' && value.reasoningEffort.trim() ? { reasoningEffort: value.reasoningEffort.trim() } : {}
+  if (value.mode !== 'fixed') return { ...DEFAULT_COMPILE_MODEL, ...effort }
   const provider = typeof value.provider === 'string' ? value.provider.trim() : ''
   const model = typeof value.model === 'string' ? value.model.trim() : ''
   // 旧版本没有这个字段，或留下了半截配置时，安全地回到 DSH 默认模型。
   if (!provider || !model) return { ...DEFAULT_COMPILE_MODEL }
-  return { mode: 'fixed', provider, model }
+  return { mode: 'fixed', provider, model, ...effort }
 }
 
 function normalizeExt(value: unknown, fallback: string): string {
@@ -142,16 +144,6 @@ function emptyBase(id: string): KnowledgeBase {
   }
 }
 
-async function writeTextAtomic(path: string, content: string): Promise<void> {
-  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
-  try {
-    await writeFile(temporary, content, 'utf8')
-    await rename(temporary, path)
-  } finally {
-    try { await unlink(temporary) } catch { /* rename already consumed it */ }
-  }
-}
-
 export function defaultDataHome(): string {
   return resourceRoot(defaultAgentRoot())
 }

package/src/knowledge.ts

@@ -96,6 +96,8 @@ export interface KnowledgeSource {
   currentVersion?: number
   evidenceStatus?: 'current' | 'historical' | 'unversioned' | 'missing' | 'human'
   quoteInCurrentVersion?: boolean
+  /** A completed newer extraction withdrew this document contribution. */
+  withdrawn?: boolean
   createdAt: string
 }
 
@@ -227,6 +229,7 @@ export interface KnowledgeVersion {
  * 「`object_id` 这个参数不在」与「`object_id=` 空值」。
  */
 export interface KnowledgeQuery {
+  excludeWithdrawn?: boolean
   objectId?: string
   actionId?: string
   sceneId?: string
@@ -537,6 +540,7 @@ export class KnowledgeStore {
           throw cause
         }
       }
+      if (!hasColumn(this.db, 'knowledge_sources', 'withdrawn')) this.db.exec('ALTER TABLE knowledge_sources ADD COLUMN withdrawn INTEGER NOT NULL DEFAULT 0')
       if (!hasColumn(this.db, 'knowledge', 'head_version')) {
         this.db.exec("ALTER TABLE knowledge ADD COLUMN head_version INTEGER NOT NULL DEFAULT 0")
       }
@@ -637,7 +641,7 @@ export class KnowledgeStore {
     if (existing !== null && normalizeKnowledge(existing.text) !== normalized) throw new Error('KNOWLEDGE_ID_COLLISION')
 
     if (existing === null) {
-      this.db.exec('BEGIN')
+      this.db.exec('SAVEPOINT knowledge_ingest')
       try {
         this.db.prepare(
           'INSERT INTO knowledge (id, text, normalized, object_id, action_id, scene_id, status, run_id, merged_into, head_version, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
@@ -654,10 +658,10 @@ export class KnowledgeStore {
           at: now,
         })
         this.db.prepare('UPDATE knowledge SET head_version = 1 WHERE id = ?').run(id)
-        this.db.exec('COMMIT')
+        this.db.exec('RELEASE knowledge_ingest')
         return { knowledge: this.read(id)!, merged: false, addedSources: added }
       } catch (cause) {
-        this.db.exec('ROLLBACK')
+        this.db.exec('ROLLBACK TO knowledge_ingest; RELEASE knowledge_ingest')
         throw cause
       }
     }
@@ -744,6 +748,10 @@ export class KnowledgeStore {
       const row = normalizeSource(source, now)
       const key = sourceKey(row)
       if (seen.has(key)) {
+        if (existingByKey.get(key)?.withdrawn) {
+          this.db!.prepare('UPDATE knowledge_sources SET withdrawn=0 WHERE knowledge_id=? AND document_id=? AND quote=? AND COALESCE(to_version,-1)=?')
+            .run(id, row.documentId, row.quote, row.toVersion ?? -1)
+        }
         continue
       }
       seen.add(key)
@@ -963,6 +971,7 @@ export class KnowledgeStore {
   } {
     const where: string[] = [query.includeMerged === true ? '1 = 1' : "merged_into = ''"]
     const params: Record<string, unknown> = {}
+    if (query.excludeWithdrawn) where.push('EXISTS (SELECT 1 FROM knowledge_sources active_source WHERE active_source.knowledge_id = knowledge.id AND active_source.withdrawn = 0)')
     if (query.ids !== undefined) {
       // 空数组是一个**取值**（筛出空集），不能退化成「不过滤」—— 那会让一次失败的落位
       // 查询变成「把整库的知识塞进这次召回」。
@@ -976,7 +985,17 @@ export class KnowledgeStore {
     if (!skip.has('status') && query.status !== undefined) { where.push('status = :status'); params.status = query.status }
     if (query.runId !== undefined) { where.push('run_id = :runId'); params.runId = query.runId }
     if (query.noCoordinate === true) where.push("object_id = '' AND action_id = '' AND scene_id = ''")
-    if (query.text) { where.push('normalized LIKE :text'); params.text = `%${normalizeKnowledge(query.text)}%` }
+    if (query.text) {
+      /**
+       * LIKE 的元字符必须转义（0070）。
+       *
+       * `normalizeKnowledge` 会保留 `%` 与 `_`，而 `?q=` 是用户能直接传的：查询 `%`
+       * 会拼成 `%%%`，命中整库并虚报 total；`a_b` 还会顺带匹配 `axb`。反斜杠自己也要
+       * 先转义 —— 否则用户输入的一个 `\` 会把后面的字符变成转义序列。
+       */
+      where.push("normalized LIKE :text ESCAPE '\\'")
+      params.text = `%${normalizeKnowledge(query.text).replace(/[\\%_]/g, char => `\\${char}`)}%`
+    }
     if (query.cardId !== undefined) {
       /*
        * `card_knowledge` 归**另一个模块**所有（`store/knowledge-db.ts`），而两个模块
@@ -1516,6 +1535,7 @@ function rowToKnowledge(row: Record<string, unknown>, sourceRows: Array<Record<s
       author: String(source.author ?? ''),
       statement: String(source.statement ?? ''),
       ...(source.to_version === null || source.to_version === undefined ? {} : { toVersion: Number(source.to_version) }),
+      ...(Number(source.withdrawn) === 1 ? { withdrawn: true } : {}),
       createdAt: String(source.created_at),
     })),
   }

package/src/materialize-snapshot.ts

@@ -0,0 +1,46 @@
+/**
+ * 物化阶段的语料快照（0070）—— **只有服务端看得见**。
+ *
+ * 它刻意不放在 `pipeline/types.ts` 里：那个模块被客户端 import（`PIPELINE_ACTIVE_STATES`
+ * 这类值），而本文件的字段类型来自 `knowledge.ts` / `events.ts` / `source-images.ts` /
+ * `card-organize.ts`，它们全都 `import 'node:…'`。把服务端模块拉进客户端的类型程序，
+ * 浏览器与 Node 的类型边界就没了（这条规矩写在 `wiki-trial-types.ts` 里）。
+ * 引擎只把这个对象原样传回去，所以它在引擎那边是 `unknown`。
+ *
+ * ## 为什么是「一次阶段运行算一份」
+ *
+ * 物化是逐组的，而每一组都要用到全库的东西：别组的正文（图片分发）、全部卡片（相关推荐）、
+ * 全部事件、全部知识。每组现算一遍就是 O(组数 × 语料) —— 几百张卡时单线程跑不完。
+ *
+ * ## 快照的边界
+ *
+ * 语料在**同一条串行队列里**是不变的（归一排在物化后面）。但别的写入者（另一个进程、
+ * 同一个库的另一条路径）不受这条队列约束，所以写回之前仍然要**单独复查这一组**的
+ * 事实（`freshGroupFingerprint`）；而**人工裁决**从来不被快照 —— 卡片状态在每次写之前
+ * 重读并与旧值比对（见 `materializePipelineGroup`）。
+ */
+import type { OrganizeRelatedCandidate } from './card-organize.js'
+import type { EventEntity } from './events.js'
+import type { Knowledge } from './knowledge.js'
+import type { MaterializationGroup } from './pipeline/types.js'
+import type { SourceImage } from './source-images.js'
+
+export interface MaterializationSnapshot {
+  groups: MaterializationGroup[]
+  /** 坐标仍有歧义 + 等待归一，两部分的合计（分开的两个字段见下）。 */
+  blocked: number
+  /** 坐标仍有歧义的 Knowledge 条数。这些行不属于任何分组。 */
+  blockedAmbiguous: number
+  /** 来源已变化 / 新抽取尚未归一的 Knowledge 条数。 */
+  blockedAwaitingNormalize: number
+  /** key → 这一组参与成卡的知识。 */
+  knowledge: Map<string, Knowledge[]>
+  /** key → 这一组的 Event。 */
+  events: Map<string, EventEntity[]>
+  /** 图片分发：全部来源正文，阶段内只读一次。 */
+  sources: Array<{ sourceId: string; content: string }>
+  /** 图片分发计划：整库算一次，按组取。 */
+  images: Map<string, SourceImage[]>
+  /** 相关推荐计划：整库算一次，按组取（键是分组键，不是卡片身份）。 */
+  related: Map<string, OrganizeRelatedCandidate[]>
+}

package/src/model-text.ts

@@ -101,6 +101,7 @@ export function buildModelRequest(input: {
 export async function collectModelText(
   stream: AsyncIterable<StreamChunkLike>,
   onUsage?: (usage: TrialTokenUsage) => void,
+  onDelta?: (text: string) => void,
 ): Promise<string> {
   let text = ''
   /** 流怎么结束的。用来区分「正常但空」「失败」「中止」三种情况。 */
@@ -112,6 +113,7 @@ export async function collectModelText(
     if (chunk.type === 'usage' && chunk.usage) onUsage?.(chunk.usage)
     if (chunk.type === 'text-delta' && typeof chunk.text === 'string') {
       text += chunk.text
+      onDelta?.(chunk.text)
       continue
     }
     if (chunk.type === 'finish') {
@@ -120,9 +122,9 @@ export async function collectModelText(
     }
   }
 
-  if (failure) {
-    const code = failure.code?.trim() || '未知错误码'
-    const message = failure.message?.trim() || '模型服务没有给出说明'
+  if (failure || finish === 'error' || finish === 'aborted' || finish === 'max-tokens') {
+    const code = failure?.code?.trim() || (finish === 'max-tokens' ? 'OUTPUT_TRUNCATED' : '未知错误码')
+    const message = failure?.message?.trim() || (finish === 'max-tokens' ? '输出达到长度上限，部分返回已保留，请调整模型限制后重试' : '模型服务没有给出说明')
     throw new Error(`模型调用失败（${code}）：${message}`)
   }
   if (text.length === 0) {

package/src/oplog.ts

@@ -30,6 +30,7 @@
 import { mkdir } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { loadSqlite, type SqliteDatabase } from './fts.js'
+import { applyRetention } from './retention.js'
 import type { OperationDetail, OperationKind, OperationStatus } from './types.js'
 
 /** 谁发起的：面板按钮，还是 Agent 的工具。 */
@@ -125,6 +126,12 @@ export class OperationLog {
     this.db.prepare(
       'INSERT INTO operations (id, kind, status, actor, kb, title, summary, started_at, finished_at, detail) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
     ).run(entry.id, entry.kind, entry.status, entry.actor, entry.kb, entry.title, entry.summary, entry.startedAt, entry.finishedAt ?? null, JSON.stringify(entry.detail))
+    /*
+     * 处理日志的保留上限（0070）。这张表原来只增不减：每编译一次、每导入一批都加行，
+     * 而 `detail` 里还塞着整批文件清单。上限同样只作用在**水位以上**的新行 ——
+     * 升级那一刻已有的日志一条不删（见 `retention.ts`）。
+     */
+    applyRetention(this.db, 'operations', { table: 'operations', key: 'rowid', keep: 2000 })
   }
 
   async patch(

package/src/pipeline/engine.ts

@@ -0,0 +1,312 @@
+import { randomUUID } from 'node:crypto'
+import type { ModelCall } from '../extract-model.js'
+import type { SourceRaw, WikiTypeDef } from '../types.js'
+import type { TrialReport } from '../wiki-trial-types.js'
+import { PipelineStore, type ExtractionCheckpoint } from './store.js'
+import { PIPELINE_ACTIVE_STATES, PIPELINE_STAGE_LABEL, type MaterializationBatch, type MaterializationGroup, type PipelineAction, type PipelineModel, type PipelineSelection, type PipelineStage, type PipelineTask } from './types.js'
+
+export interface PipelineSource extends SourceRaw { version: number; sourceHash: string }
+export interface PipelineContext {
+  model: PipelineModel & { call?: ModelCall; why?: string }
+  note: string
+  profile?: WikiTypeDef
+  organize: boolean
+  format: 'json' | 'table'
+}
+export interface PipelineBuildResult { summary: string; skipped?: boolean }
+export interface PipelineHost {
+  capture(): PipelineContext
+  serialize<T>(work: () => Promise<T>): Promise<T>
+  sources(): Promise<PipelineSource[]>
+  /** One source by id. Same shape as an element of `sources()`. */
+  source(sourceId: string): Promise<PipelineSource | undefined>
+  fingerprint(source: PipelineSource, context: PipelineContext): Promise<string>
+  extract(source: PipelineSource, context: PipelineContext, output: (text: string) => void): Promise<TrialReport>
+  normalize(source: PipelineSource, checkpoint: ExtractionCheckpoint, context: PipelineContext, force: boolean, output: (text: string) => void): Promise<{ reused: boolean; warnings: string[] }>
+  groups(context: PipelineContext): Promise<MaterializationBatch>
+  materialize(group: MaterializationGroup, context: PipelineContext, output: (text: string) => void, snapshot: unknown): Promise<void>
+  build(taskId: string, checkpoint: () => Promise<void>): Promise<PipelineBuildResult>
+  record(checkpoint: ExtractionCheckpoint): Promise<void>
+}
+
+class TaskCancelled extends Error {}
+interface Control { pause: boolean; cancel: boolean; resume?: () => void }
+
+/** One writer queue per base, shared with the legacy index builder. */
+export class KnowledgePipeline {
+  private closed = false
+  private controls = new Map<string, Control>()
+  constructor(readonly store: PipelineStore, private readonly host: PipelineHost) {}
+
+  start(stage: PipelineStage, selection: PipelineSelection = {}): { task: PipelineTask; completion: Promise<PipelineTask> } {
+    if (this.closed) throw new Error('知识处理已关闭')
+    if (!['extract', 'normalize', 'materialize', 'build', 'all'].includes(stage)) throw new Error('不支持的知识处理阶段')
+    for (const value of [selection.sourceIds, selection.groupKeys]) {
+      if (value !== undefined && (!Array.isArray(value) || value.length === 0 || value.some(id => typeof id !== 'string' || !id.trim()))) throw new Error('选择范围不能为空；不传范围表示处理当前阶段的全部待办')
+    }
+    const context = this.host.capture()
+    const { call: _call, why: _why, ...model } = context.model
+    const task: PipelineTask = {
+      id: `pipeline_${randomUUID()}`, stage, state: 'queued', selection: structuredClone(selection), model,
+      queuedAt: new Date().toISOString(), done: 0, total: 0, reused: 0, failed: 0,
+      summary: '等待运行', warnings: [],
+    }
+    this.store.putTask(task)
+    this.controls.set(task.id, { pause: false, cancel: false })
+    const completion = this.host.serialize(() => this.execute(task.id, context))
+    // Starting a background task must not create an unhandled rejection.
+    void completion.catch(() => undefined)
+    return { task, completion }
+  }
+
+  close(): void {
+    this.closed = true
+    for (const control of this.controls.values()) { control.cancel = true; control.pause = false; control.resume?.() }
+  }
+
+  control(id: string, action: PipelineAction): PipelineTask {
+    const task = this.store.task(id)
+    const control = this.controls.get(id)
+    if (!task || !control || !PIPELINE_ACTIVE_STATES.includes(task.state)) throw new Error('任务已结束；请重新运行所需阶段')
+    if (action === 'pause') {
+      control.pause = true
+      this.patch(id, { state: task.state === 'queued' ? 'paused' : 'pausing', summary: '当前文档或卡片处理完成后暂停' })
+    } else if (action === 'resume') {
+      if (!control.pause) throw new Error('任务没有暂停')
+      control.pause = false
+      this.patch(id, { state: task.startedAt ? 'running' : 'queued' })
+      control.resume?.()
+      control.resume = undefined
+    } else {
+      control.cancel = true
+      control.pause = false
+      this.patch(id, { state: 'cancelling', summary: '当前文档或卡片处理完成后停止' })
+      control.resume?.()
+    }
+    return this.store.task(id)!
+  }
+
+  private patch(id: string, patch: Partial<PipelineTask>): PipelineTask {
+    const task = { ...this.store.task(id)!, ...patch }
+    this.store.putTask(task)
+    return task
+  }
+  private finishStage(id: string, outcome?: Pick<PipelineBuildResult, 'summary' | 'skipped'>): void {
+    const task = this.store.task(id)!
+    if (task.currentStage) this.patch(id, { results: { ...task.results, [task.currentStage]: { done: task.done, total: task.total, reused: task.reused, failed: task.failed, ...outcome } } })
+  }
+  private async checkpoint(id: string): Promise<void> {
+    const control = this.controls.get(id)
+    while (control) {
+      if (control.cancel) throw new TaskCancelled('任务已停止，已完成的文档与阶段会保留')
+      if (!control.pause) return
+      this.patch(id, { state: 'paused', summary: '已暂停，可继续运行' })
+      await new Promise<void>(resolve => { control.resume = resolve })
+    }
+  }
+  private output(id: string, stage: Exclude<PipelineStage, 'all'>, sourceId?: string): { append: (text: string) => void; flush: () => void } {
+    let buffer = ''
+    let last = Date.now()
+    let bytes = 0
+    let capped = false
+    const flush = (): void => {
+      if (!buffer) return
+      this.store.event(id, 'output', buffer, sourceId, stage)
+      buffer = ''
+      last = Date.now()
+    }
+    let failure: unknown
+    const timer = setInterval(() => { try { flush() } catch (cause) { failure = cause; clearInterval(timer) } }, 250)
+    timer.unref()
+    return {
+      append: text => {
+        if (failure) throw failure
+        bytes += Buffer.byteLength(text)
+        if (bytes > 4 * 1024 * 1024) {
+          if (!capped) { flush(); this.store.event(id, 'warning', '实时预览超过 4 MB；完整返回保存在本次抽取报告中。', sourceId, stage); capped = true }
+          return
+        }
+        buffer += text
+        if (buffer.length >= 1024 || Date.now() - last >= 250) flush()
+      }, flush: () => { clearInterval(timer); if (failure) throw failure; flush() },
+    }
+  }
+  private async execute(id: string, context: PipelineContext): Promise<PipelineTask> {
+    const task = this.store.task(id)!
+    const stages = task.stage === 'all' ? ['extract', 'normalize', 'materialize', 'build'] as const : [task.stage]
+    try {
+      await this.checkpoint(id)
+      this.patch(id, { state: 'running', startedAt: new Date().toISOString() })
+      const allSources = await this.host.sources()
+      const sourceIds = task.selection.sourceIds === undefined ? undefined : new Set(task.selection.sourceIds)
+      if (sourceIds && [...sourceIds].some(sourceId => !allSources.some(source => source.sourceId === sourceId))) throw new Error('选择范围中有已删除或不存在的来源')
+      const sources = allSources.filter(source => !sourceIds || sourceIds.has(source.sourceId))
+      /**
+       * 坐标仍有歧义、等归一的 Knowledge 条数。它不是失败，所以既不进 `failed`、
+       * 也不提前结束链路（否则一个歧义 mention 就能让整库索引永不发布）；
+       * 但它也不是「全部完成」，所以最终状态报 `partial`。
+       */
+      let deferred = 0
+      for (const stage of stages) {
+        await this.checkpoint(id)
+        this.patch(id, { currentStage: stage, done: 0, total: 0, reused: 0, failed: 0, summary: PIPELINE_STAGE_LABEL[stage] })
+        this.store.event(id, 'progress', PIPELINE_STAGE_LABEL[stage], undefined, stage)
+        if (stage === 'build') {
+          const result = await this.host.build(id, () => this.checkpoint(id))
+          this.patch(id, { done: 1, total: 1, summary: result.summary })
+          this.finishStage(id, result)
+          continue
+        }
+        if (stage === 'materialize') {
+          const batch = await this.host.groups(context)
+          const { groups } = batch
+          const selected = task.selection.groupKeys ? new Set(task.selection.groupKeys) : undefined
+          if (selected && [...selected].some(key => !groups.some(group => group.key === key))) throw new Error('选择的卡片分组已变化，请刷新待物化列表')
+          /**
+           * 来源范围对**任何**阶段都生效，不只对 `all`：`start()` 会校验 `sourceIds`
+           * 非空，调用方因此有理由认为它生效了。只对 `all` 生效等于静默忽略选择。
+           */
+          const affectedSources = sourceIds ? new Set(sources.map(source => source.sourceId)) : undefined
+          const scoped = selected !== undefined || affectedSources !== undefined
+          const inScope = (group: MaterializationGroup): boolean => (!selected || selected.has(group.key)) && (!affectedSources || group.sourceIds.some(sourceId => affectedSources.has(sourceId)))
+          /**
+           * 待归一的量要**按选择范围**数，且两个原因分开说（0070）。
+           *
+           * 「坐标有歧义」与「来源变了、抽取结果还没归一」是两件事，报同一句话会让读的人
+           * 去查错的地方。更要紧的是范围：按 `sourceIds` / `groupKeys` 缩小的那一趟，
+           * 如果拿全库的数字报 `partial`，调用方会去重试一件它明确排除的事 —— 而它其实
+           * 全都做完了。坐标有歧义的那些行不属于任何分组，无法按来源归属，所以只在
+           * 没有选择范围时才计入。
+           */
+          const ambiguous = scoped ? 0 : batch.blockedAmbiguous
+          const awaiting = scoped
+            ? groups.filter(group => group.state === 'blocked' && inScope(group)).reduce((sum, group) => sum + group.knowledgeCount, 0)
+            : batch.blockedAwaitingNormalize
+          if (ambiguous > 0 || awaiting > 0) {
+            deferred = ambiguous + awaiting
+            const parts = [
+              ambiguous > 0 ? `${ambiguous} 条 Knowledge 的坐标仍有歧义` : '',
+              awaiting > 0 ? `${awaiting} 条 Knowledge 的来源已变化或新抽取待归一` : '',
+            ].filter(Boolean)
+            const message = `${parts.join('；')}，暂不物化；本次不影响索引构建。`
+            this.patch(id, { warnings: [...this.store.task(id)!.warnings, message] })
+            this.store.event(id, 'warning', message, undefined, stage)
+          }
+          const pending = groups.filter(group => group.state !== 'blocked' && inScope(group) && (task.selection.force || group.state !== 'current'))
+          this.patch(id, { total: pending.length })
+          for (const group of pending) {
+            await this.checkpoint(id)
+            const output = this.output(id, stage)
+            try { await this.host.materialize(group, context, output.append, batch.snapshot) }
+            catch (cause) {
+              if (cause instanceof TaskCancelled) throw cause
+              const message = `${group.title}：${cause instanceof Error ? cause.message : String(cause)}`
+              const current = this.store.task(id)!
+              this.patch(id, { failed: current.failed + 1, warnings: [...current.warnings, message] })
+              this.store.event(id, 'warning', message, undefined, stage)
+            }
+            finally { output.flush() }
+            const current = this.store.task(id)!
+            this.patch(id, { done: current.done + 1, summary: `已物化 ${current.done + 1}/${pending.length} 张：${group.title}` })
+          }
+          const current = this.store.task(id)!
+          /**
+           * 阶段结论要给 `summary`：任务列表的四段步轨读的是 `results[stage]`，
+           * 缺了它那一段会显示成「已完成」（成功色），而任务徽标写着「部分完成」——
+           * 同一件事在半个屏幕上两种说法。
+           */
+          this.finishStage(id, {
+            summary: `已物化 ${current.done - current.failed}/${current.total} 张${deferred > 0 ? `；${deferred} 条待归一` : ''}${affectedSources !== undefined ? `（按来源范围缩小：${affectedSources.size} 份来源）` : ''}`,
+          })
+          /**
+           * **真的**有分组失败时才提前结束（含 `build`）：这里与 `blocked` 的处理刻意不同。
+           *
+           * `blocked` 是「等归一」的待办，不是失败，所以它不阻断；而这里是某一张卡没写成功
+           * （模型报错、写库失败），此时发布索引等于把一个半成品当成品推给召回 ——
+           * 而重试的代价很小：已经物化好的那些分组指纹没变，下一次会被判成 `current` 直接跳过。
+           */
+          if (current.failed) return this.patch(id, { state: current.failed === current.total ? 'failed' : 'partial', finishedAt: new Date().toISOString(), summary: `物化结束：成功 ${current.total - current.failed}/${current.total}；已完成卡片保留，可重试。` })
+          continue
+        }
+        this.patch(id, { total: sources.length })
+        for (const source of sources) {
+          await this.checkpoint(id)
+          this.store.event(id, 'progress', `${PIPELINE_STAGE_LABEL[stage]}：${source.title}`, source.sourceId, stage)
+          const output = this.output(id, stage, source.sourceId)
+          let reused = false
+          try {
+            if (stage === 'extract') {
+              const fingerprint = await this.host.fingerprint(source, context)
+              const cached = task.selection.force ? undefined : this.store.cached(source.sourceId, source.version, fingerprint)
+              if (cached) { this.store.selectExtraction(source.sourceId, cached.id); reused = true }
+              else {
+                const report = await this.host.extract(source, context, output.append)
+                if (this.closed) throw new TaskCancelled('知识库已关闭，已完成结果保留')
+                const checkpoint: ExtractionCheckpoint = { id: `extract_${randomUUID()}`, sourceId: source.sourceId, sourceVersion: source.version, sourceHash: source.sourceHash, fingerprint, report, createdAt: new Date().toISOString() }
+                // The host checks the captured source version again before activation.
+                // Read that one source back, not the whole library: the old form re-hashed
+                // every document body once per document, which is O(N²) over a big base.
+                const current = await this.host.source(source.sourceId)
+                if (!current || current.version !== source.version || current.sourceHash !== source.sourceHash) {
+                  await this.host.record(checkpoint)
+                  this.store.event(id, 'report', checkpoint.id, source.sourceId, stage)
+                  throw new Error('来源在抽取期间已变化；返回已保留在历史中，请抽取最新版本')
+                }
+                await this.host.record(checkpoint)
+                this.store.event(id, 'report', checkpoint.id, source.sourceId, stage)
+                /**
+                 * 没通过校验时**要说清是哪一条不合格**（0070）。
+                 *
+                 * 原来只报一句 `model.why`（「抽取返回未通过校验」），"哪些引文对不上" 只留在
+                 * 审计报告里，而人看不到那一层。现在把 `exceptions` 的前三条带进错误里 ——
+                 * 面板上的失败行直接能读出原因。
+                 *
+                 * 这里**不缓存**这一份失败返回（试过，退回去了）：缓存会让下一次重跑不再调模型，
+                 * 而同一个阶段结束时的承诺是「可重试此阶段」——「重试」按下去什么都不发生，
+                 * 比多花一次模型调用糟得多。完整返回已经由 `host.record` 收进审计库。
+                 */
+                if (report.model.parsed !== true) {
+                  const detail = report.exceptions.slice(0, 3).map(item => `${item.step}：${item.message}`).join('；')
+                  throw new Error(`${report.model.why ?? '抽取返回未通过校验'}${detail === '' ? '' : `（${detail}）`}`)
+                }
+                this.store.saveExtraction(checkpoint)
+              }
+            } else {
+              const checkpoint = this.store.head(source.sourceId).extracted
+              if (!checkpoint) throw new Error('尚无抽取结果，请先运行抽取')
+              if (checkpoint.sourceVersion !== source.version || checkpoint.sourceHash !== source.sourceHash) throw new Error('抽取结果依据旧版来源，请先抽取最新版本')
+              const result = await this.host.normalize(source, checkpoint, context, task.selection.force === true, output.append)
+              reused = result.reused
+              if (result.warnings.length) this.patch(id, { warnings: [...this.store.task(id)!.warnings, ...result.warnings.map(warning => `${source.title}：${warning}`)] })
+              for (const warning of result.warnings) this.store.event(id, 'warning', warning, source.sourceId, stage)
+            }
+          } catch (cause) {
+            if (cause instanceof TaskCancelled) throw cause
+            const message = `${source.title}：${cause instanceof Error ? cause.message : String(cause)}`
+            const current = this.store.task(id)!
+            this.patch(id, { failed: current.failed + 1, warnings: [...current.warnings, message] })
+            this.store.event(id, 'warning', message, source.sourceId, stage)
+          } finally { output.flush() }
+          const current = this.store.task(id)!
+          this.patch(id, { done: current.done + 1, reused: current.reused + Number(reused), summary: `${PIPELINE_STAGE_LABEL[stage]} ${current.done + 1}/${sources.length}${reused ? ' · 复用已有结果' : ''}` })
+        }
+        this.finishStage(id)
+        if (this.store.task(id)!.failed > 0) {
+          const current = this.store.task(id)!
+          this.patch(id, { state: current.failed === current.total ? 'failed' : 'partial', finishedAt: new Date().toISOString(), summary: `${PIPELINE_STAGE_LABEL[stage]}结束：成功 ${current.total - current.failed}/${current.total}，失败 ${current.failed}；已完成结果保留，可重试此阶段。` })
+          return this.store.task(id)!
+        }
+      }
+      await this.checkpoint(id)
+      const current = this.store.task(id)!
+      /**
+       * `deferred > 0` 时状态是 `partial`：这一趟把能做的都做了（包括发布索引），
+       * 但还有一批分组在等归一。报 `succeeded` 会让人以为「物化完了」。
+       */
+      const suffix = deferred > 0 ? ` · 另有 ${deferred} 条 Knowledge 待归一（坐标歧义或来源已变），暂未物化` : ''
+      return this.patch(id, { state: deferred > 0 ? 'partial' : 'succeeded', finishedAt: new Date().toISOString(), summary: (task.stage === 'all' ? `全链路完成 · 抽取 ${current.results?.extract?.done ?? 0} 份（复用 ${current.results?.extract?.reused ?? 0} 份） · 物化 ${current.results?.materialize?.done ?? 0} 张 · 索引已发布` : `${PIPELINE_STAGE_LABEL[task.stage]}完成 · 处理 ${current.done} 项 · 复用 ${current.reused} 项`) + suffix })
+    } catch (cause) {
+      return this.patch(id, { state: cause instanceof TaskCancelled ? 'cancelled' : 'failed', finishedAt: new Date().toISOString(), summary: cause instanceof Error ? cause.message : String(cause) })
+    } finally { this.controls.delete(id) }
+  }
+}