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

package/src/knowledge-contract.ts

@@ -18,8 +18,13 @@ export interface KnowledgeContent {
 }
 
 export function wikiProjection(kind: KnowledgeKind, coordinate: { objectId: string; actionId: string; sceneId: string }): { objectId: string; actionId: string; sceneId: string } | undefined {
-  if (kind === 'case' || !coordinate.objectId || (kind === 'procedure' && !coordinate.actionId)) return undefined
-  return { objectId: coordinate.objectId, actionId: kind === 'procedure' ? coordinate.actionId : '', sceneId: '' }
+  if (kind === 'case' || !coordinate.objectId) return undefined
+  return { ...coordinate }
+}
+
+/** Wiki identity preserves the full coordinate and separates Fact from Way. Empty axes are exact values. */
+export function wikiGroupKey(kind: WikiKind, coordinate: { objectId: string; actionId: string; sceneId: string }): string {
+  return `wiki:${kind}:${coordinate.objectId}\u0001${coordinate.actionId}\u0001${coordinate.sceneId}`
 }
 
 export function procedureText(value: ProcedureContent): string {

package/src/layout.ts

@@ -1,5 +1,5 @@
 /**
- * Tita Agent 在磁盘上的布局（0029 定四段，0032 扩到六段，0062 v2 **取消了知识库里的段**）。
+ * Tita Agent 在磁盘上的布局（Agent 根路径固定四段，知识库内部不再使用段目录）。
  *
  * ## 为什么要有这个文件
  *
@@ -8,7 +8,7 @@
  * 都可能指向不同的卷，于是「这个 Agent 的东西在哪」这个问题没有唯一答案 ——
  * 备份要记得两个路径，换机器要改两处，用户也没法一眼看出磁盘上哪块是它的。
  *
- * 现在**只有一个设置**：Tita Agent 根路径。根路径下固定六段，职责互不重叠：
+ * 现在**只有一个设置**：Tita Agent 根路径。根路径下固定四段，职责互不重叠：
  *
  * ```
  * <agentRoot>/
@@ -24,7 +24,6 @@
  *       extraction-runs.sqlite 抽取轨迹
  *       access-audit.ndjson    访问审计
  *       feedback.ndjson        反馈
- *   intent/                    意图：intent.db（会话审计留痕）
  *   tmp/                       运行期临时文件：转换工作区、任务状态
  *     <YYYY-MM-DD>/            二级按日期分桶
  *   resource/                  Agent 跑起来所需要的家当（不是它的产出）
@@ -100,11 +99,7 @@
  *    不可重建的命名决定。按原理 5 的判据（「要不要跟着知识一起备份、迁移、删除」）它们
  *    必须跟着知识走，所以 0062 把它们搬进了 `knowledge.db`。今天 `memory/` 里**没有一样
  *    东西是不可重建的知识**，这才是这条原理想要的终态。
- * 6. **意图（`intent/`）与记忆平级，但它不分库。** 意图是**会话级**的：同一句话
- *    在哪个知识库下说，理解方式不该变。它的两份东西 —— 分类/act 注册表（配置）
- *    与每轮记录（留痕）—— 原来一个住在宿主的 settings 文档里、一个只在内存里，
- *    都不是「这个 Agent 自己的文件」；落进根路径之后，它们和知识、记忆一样可以
- *    被备份、被 diff、被用户直接读。
+ * 6. 会话目标由当前请求和坐标直接提供，不在 Agent 根路径下复制分类词表或会话记录库。
  *
  * 这个文件是布局的**唯一真源**：运行时、知识库注册表、转换内核、设置面板读到的
  * 都是这里算出来的路径，不在别处再拼一次字符串。
@@ -121,8 +116,8 @@ import { basename, dirname, join, resolve } from 'node:path'
  *
  * 分两组看，判据不同：
  *
- * - **Agent 自己的东西**：`domain_knowledge`（知识）、`memory`（记忆）、`intent`
- *   （意图记录）、`tmp`（运行期临时态）。判据是「能不能重建」。
+ * - **Agent 自己的东西**：`domain_knowledge`（知识）、`memory`（审计与版本记录）、
+ *   `tmp`（运行期临时态）。判据是「能不能重建」。
  * - **跑起来所需的依赖**：`resource`（模型、Python 环境、注册表）。判据是「属于谁」。
  *
  * **`output` 不在这里。** 交付物是**某个工作项目的产物**，不是这个 Agent 的固有状态：
@@ -130,7 +125,7 @@ import { basename, dirname, join, resolve } from 'node:path'
  * 所以它落在**当前工作区**的 `output/<日期>/` 下，而不是跟着 Agent 的家走。
  * 约定写在知识插件追加到标准模式系统提示词的行为规则里。
  */
-export const AGENT_DIRS = ['domain_knowledge', 'memory', 'intent', 'tmp', 'resource'] as const
+export const AGENT_DIRS = ['domain_knowledge', 'memory', 'tmp', 'resource'] as const
 export type AgentDirName = typeof AGENT_DIRS[number]
 
 /** 知识树那一段的目录名。 */
@@ -162,19 +157,10 @@ export const RESOURCE_DIR = 'resource'
  * 反馈与访问审计。它从知识树里**搬出来**了，理由见文件头第 5 条原理。
  */
 export const MEMORY_DIR = 'memory'
-/**
- * 意图那一段的目录名（0032）。
- *
- * 里面装的是意图的**会话审计留痕**：`intent.db`（当前记录 + 追加历史）。旧的
- * `records.ndjson` 只在首次打开时迁移，不再继续写入。
- * 分类与 act 是固定契约，不属于 Agent 的可编辑配置。
- */
-export const INTENT_DIR = 'intent'
-
 /**
  * 默认根路径：`~/.dsh/tita-agent`。
  *
- * `.dsh` 是 DSH 的用户级数据根；`tita-agent` 是本插件的专属目录。知识、记忆、意图、
+ * `.dsh` 是 DSH 的用户级数据根；`tita-agent` 是本插件的专属目录。知识、记忆、
  * 临时态与运行所需家当都收在这里，用户不需要再管理一条插件自己的路径。
  */
 export function defaultAgentRoot(): string {
@@ -223,7 +209,7 @@ export function knowledgeBaseRoot(agentRoot: string, kbId: string): string {
  * 交付物的落点：`<工作区>/output`。
  *
  * 刻意**不**由 `agentRoot` 推出来。交付物是**某个工作项目的产物** —— 同一个 Agent
- * 换一个项目打开，不该再看见上一个项目产出的图和数据。知识、记忆、意图记录是 Agent
+ * 换一个项目打开，不该再看见上一个项目产出的图和数据。知识与记忆是 Agent
  * 自己的、跨项目累积的东西，所以留在 `agentRoot`；交付物属于项目，所以跟着项目走。
  *
  * 二级目录按日期分桶（`output/<YYYY-MM-DD>/`），由转换内核的 `bucketByDay` 打开；
@@ -297,11 +283,9 @@ export interface AgentLayout {
   resource: string
   /** 记忆那一段（版本快照 / 反馈 / 访问审计），二级按知识库 id 分叉（0032）。 */
   memory: string
-  /** 意图那一段（intent.db）（0032）。 */
-  intent: string
 }
 
-/** 由根路径算出六段布局。纯函数，测试直接断言。 */
+/** 由根路径算出四段布局。纯函数，测试直接断言。 */
 export function agentLayout(agentRoot: string): AgentLayout {
   const root = resolve(agentRoot)
   return {
@@ -310,7 +294,6 @@ export function agentLayout(agentRoot: string): AgentLayout {
     tmp: join(root, TMP_DIR),
     resource: join(root, RESOURCE_DIR),
     memory: join(root, MEMORY_DIR),
-    intent: join(root, INTENT_DIR),
   }
 }
 
@@ -326,11 +309,6 @@ export function memoryRoot(agentRoot: string, kbId: string): string {
   return join(resolve(agentRoot), MEMORY_DIR, kbId)
 }
 
-/** `<agentRoot>/intent`：会话意图审计留痕（0032）。意图不分库。 */
-export function intentRoot(agentRoot: string): string {
-  return join(resolve(agentRoot), INTENT_DIR)
-}
-
 /**
  * 一个知识库根目录里**固定存在的三样东西**（PRD v2 §0.2）。
  *
@@ -396,7 +374,7 @@ export function looksLikeLegacyKnowledgeRoot(path: string): boolean {
  */
 export function ensureAgentLayout(agentRoot: string): AgentLayout {
   const layout = agentLayout(agentRoot)
-  for (const dir of [layout.domainKnowledge, layout.tmp, layout.resource, layout.memory, layout.intent]) {
+  for (const dir of [layout.domainKnowledge, layout.tmp, layout.resource, layout.memory]) {
     try {
       mkdirSync(dir, { recursive: true })
     } catch {

package/src/materialize-snapshot.ts

@@ -33,6 +33,7 @@ export interface MaterializationSnapshot {
   blockedAmbiguous: number
   /** 来源已变化 / 新抽取尚未归一的 Knowledge 条数。 */
   blockedAwaitingNormalize: number
+  blockedItems: Array<{ knowledgeId: string; sourceIds: string[]; groupKey?: string }>
   /** key → 这一组参与成卡的知识。 */
   knowledge: Map<string, Knowledge[]>
   /** key → 这一组的 Event。 */

package/src/migrate.ts

@@ -87,7 +87,9 @@ function skipped(reason: string, from?: string, to?: string): MigrationOutcome {
  * 把旧版完整的 Agent 根目录合并到新的固定根目录。
  *
  * 这和 `migrateLegacyKnowledgeTree` 不同：后者只认识一棵知识库树，而这里要把
- * `domain_knowledge`、`memory`、`intent`、`resource` 与 `tmp` 一起搬走。目标里已经有
+ * `domain_knowledge`、`memory`、`resource` 与 `tmp` 一起搬走。历史 `intent` 目录不再由插件
+ * 读取或迁移；如果它仍在旧根路径中，会阻止旧根目录被清空，保留原始数据供用户自行处理。
+ * 目标里已经有
  * 同名目录时逐层合并，任何同名文件都不覆盖，并把冲突留下来交给界面报告。
  */
 export function migrateLegacyAgentRoot(input: { agentRoot: string; legacyRoot: string }): MigrationOutcome {

package/src/model-text.ts

@@ -32,7 +32,7 @@ interface StreamChunkLike {
   type?: string
   text?: string
   usage?: TrialTokenUsage
-  reason?: { kind?: string; failure?: { code?: string; message?: string } }
+  reason?: { kind?: string; failure?: { code?: string; message?: string; status?: number; requestId?: string; retryAfterMs?: number } }
 }
 
 /**
@@ -69,21 +69,24 @@ export function buildModelRequest(input: {
   system?: string
   prompt: string
   reasoningEffort?: string
+  maxTokens?: number
   /** 路由与缓存亲和的会话身份。知识编译用 `knowledge:<库 id>`。 */
   sessionId: string
 }): {
   provider: string
   model: string
   reasoningEffort?: string
+  maxTokens?: number
   system?: string
   sessionId: string
   messages: Array<{ role: 'user'; content: Array<{ type: 'text'; text: string }> }>
 } {
-  const { provider, model, system, prompt, reasoningEffort, sessionId } = input
+  const { provider, model, system, prompt, reasoningEffort, maxTokens, sessionId } = input
   return {
     provider,
     model,
     ...(reasoningEffort ? { reasoningEffort } : {}),
+    ...(maxTokens !== undefined ? { maxTokens } : {}),
     ...(system ? { system } : {}),
     sessionId,
     messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
@@ -106,7 +109,7 @@ export async function collectModelText(
   let text = ''
   /** 流怎么结束的。用来区分「正常但空」「失败」「中止」三种情况。 */
   let finish: string | undefined
-  let failure: { code?: string; message?: string } | undefined
+  let failure: NonNullable<StreamChunkLike['reason']>['failure'] | undefined
 
   for await (const chunk of stream) {
     if (!chunk || typeof chunk !== 'object') continue
@@ -125,8 +128,9 @@ export async function collectModelText(
   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}`)
+    throw Object.assign(new Error(`模型调用失败（${code}）：${message}`), { code, status: failure?.status, requestId: failure?.requestId, retryAfterMs: failure?.retryAfterMs })
   }
+  if (!finish && text.length > 0) throw new Error('Stream ended without finish_reason；部分返回已保留')
   if (text.length === 0) {
     // 走到这里说明流正常结束（或者压根没有 finish 块）却没有一个字符。
     throw new Error(`模型没有返回任何文本（结束原因：${finish ?? '没有收到 finish 块'}）`)
@@ -156,7 +160,7 @@ export async function collectModelText(
  */
 export function isRetryableModelFailure(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error)
-  const code = /模型调用失败（([^）]*)）/.exec(message)?.[1]?.trim().toUpperCase() ?? ''
+  const code = (typeof (error as { code?: unknown })?.code === 'string' ? String((error as { code: string }).code).toUpperCase() : '') || (/模型调用失败（([^）]*)）/.exec(message)?.[1]?.trim().toUpperCase() ?? '')
 
   // 明确不可重试：配置问题与用户取消。宁可让人去改设置，也不要在错的地方重试。
   if (['ABORTED', 'INVALID_CREDENTIAL', 'AUTH', 'UNAUTHORIZED', 'NOT_FOUND', 'INVALID_REQUEST', 'CONTEXT_LENGTH', 'OUTPUT_TRUNCATED'].includes(code)) return false
@@ -166,9 +170,10 @@ export function isRetryableModelFailure(error: unknown): boolean {
 
   // 没有 code 的情况（旧适配器、或错误被包了一层）：按可辨认的措辞判断。
   if (/没有返回任何文本|没有收到 finish 块|Stream ended without finish_reason/i.test(message)) return true
-  if (/ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|socket hang up|premature close|other side closed|fetch failed|network error|HTTP 5\d\d|HTTP 429/i.test(message)) return true
+  if (/request\s+timed?\s*out|request_timeout|timeout_error|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|socket hang up|premature close|other side closed|fetch failed|network error|HTTP 5\d\d|HTTP 429/i.test(message)) return true
 
-  return false
+  const status = Number((error as { status?: number })?.status)
+  return status === 408 || status === 429 || (status >= 500 && status < 600)
 }
 
 /** 重试策略：最多几次、每次之前等多久。 */
@@ -183,6 +188,8 @@ export interface ModelRetryOptions {
   notice?: ((info: { attempt: number; attempts: number; error: unknown }) => string | null) | null
   /** 注入 sleep，测试里不必真的等。 */
   sleep?: (ms: number) => Promise<void>
+  signal?: AbortSignal
+  jitter?: boolean
 }
 
 /**
@@ -200,7 +207,13 @@ export async function callModelWithRetry(
 ): Promise<string> {
   const attempts = Math.max(1, Math.floor(options.attempts ?? 3))
   const delays = options.delaysMs ?? [2000, 6000]
-  const sleep = options.sleep ?? ((ms: number) => new Promise<void>(resolve => { setTimeout(resolve, ms) }))
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve, reject) => {
+    const done = (): void => { options.signal?.removeEventListener('abort', abort); resolve() }
+    const timer = setTimeout(done, ms)
+    const abort = (): void => { clearTimeout(timer); reject(options.signal?.reason) }
+    options.signal?.addEventListener('abort', abort, { once: true })
+    if (options.signal?.aborted) abort()
+  }))
   const notice = options.notice === undefined
     ? (info: { attempt: number; attempts: number; error: unknown }) =>
       `\n\n[模型流中断（${info.error instanceof Error ? info.error.message : String(info.error)}），正在重试 ${info.attempt}/${info.attempts - 1}]\n\n`
@@ -208,16 +221,21 @@ export async function callModelWithRetry(
 
   let lastError: unknown
   for (let attempt = 1; attempt <= attempts; attempt++) {
+    options.signal?.throwIfAborted()
     try {
       return await send(text => options.onDelta?.(text))
     } catch (error) {
       lastError = error
-      if (attempt >= attempts || !isRetryableModelFailure(error)) throw error
-      const delayMs = delays[Math.min(attempt - 1, delays.length - 1)] ?? 0
+      if (!isRetryableModelFailure(error)) throw error
+      if (attempt >= attempts) break
+      const retryAfter = Number((error as { retryAfterMs?: number })?.retryAfterMs)
+      const baseDelay = Number.isFinite(retryAfter) && retryAfter >= 0 ? Math.min(60_000, retryAfter) : delays[Math.min(attempt - 1, delays.length - 1)] ?? 0
+      const delayMs = Math.round(baseDelay * (options.jitter === false ? 1 : 0.7 + Math.random() * 0.6))
       options.onRetry?.({ attempt, attempts, error, delayMs })
       const line = notice?.({ attempt, attempts, error }) ?? ''
       if (line) options.onDelta?.(line)
       await sleep(delayMs)
+      options.signal?.throwIfAborted()
     }
   }
   /**
@@ -227,5 +245,9 @@ export async function callModelWithRetry(
    * 后者查额度、代理和上游状态。不写这一句，新加的重试在界面上等于不存在。
    */
   const message = lastError instanceof Error ? lastError.message : String(lastError)
-  throw new Error(`${message}（已自动重试 ${attempts - 1} 次仍失败；可稍后重试此阶段，或检查账号额度与网络代理）`)
+  if (attempts === 1) throw lastError
+  const details = lastError as { code?: string; status?: number; requestId?: string; retryAfterMs?: number } | undefined
+  throw Object.assign(new Error(`${message}（已自动重试 ${attempts - 1} 次仍失败；可继续未完成部分）`, { cause: lastError }), {
+    code: details?.code, status: details?.status, requestId: details?.requestId, retryAfterMs: details?.retryAfterMs,
+  })
 }

package/src/organize-contract.ts

@@ -19,7 +19,7 @@ export function buildOrganizeSystem(wikiKind: 'fact' | 'way' = 'fact'): string {
   return [
     '你在把一批已经抽好的知识组织成一张 Wiki 卡片。',
     '',
-    `文件类型：${wikiKind === 'way' ? 'Wiki Way；同 Object + Action 的 Procedure' : 'Wiki Fact；同 Object 的 Fact'}。Scene 可以不同，必须保留每条的条件、状态与限制。`,
+    `文件类型：${wikiKind === 'way' ? 'Wiki Way；同一 Object × Action × Scene 坐标下的 Procedure' : 'Wiki Fact；同一 Object × Action × Scene 坐标下的 Fact'}。不得把不同坐标的内容合并。空坐标分量不表示通用，保留每条的条件、状态与限制。`,
     '这些条目是 Knowledge 真源。你不许新增、',
     '删除或改动它们说的事实。你能做的是：分小节、定顺序、把它们改写成读得下去的',
     '叙述、给卡片起一个自然的标题、写一句概述。',
@@ -33,6 +33,7 @@ export function buildOrganizeSystem(wikiKind: 'fact' | 'way' = 'fact'): string {
     '3. **每句都要挂引用。** 陈述事实的句子末尾挂 `[^知识id]`，可以挂多个。',
     '   只有很短的导语（「这一节讲取数流程」）可以不挂。长句子不挂引用 = 没有来源的',
     '   断言，整份方案会被打回。',
+    '涉及其他 Object 的定义或方法时，使用给定目标的双链，不把另一份 Wiki 的全文复制进来。无法唯一定位时保留对象原名，由程序补充导航，不编造链接或新坐标。',
     '4. **标题只做归纳，不要机械拼接。** 标题要能让人一眼知道卡片讲什么；不要照抄候选卡名，',
     '   不要写成「对象的动作」「动作的动作」这类重复结构，不要加入知识里没有的新事实。',
     '   保留区分这张卡所需的业务对象、字段名和动作词。知识条目附带的原文标题路径是定位线索，',

package/src/pipeline/engine.ts

@@ -3,17 +3,30 @@ 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'
+import { PIPELINE_ACTIVE_STATES, PIPELINE_STAGE_LABEL, normalizeExtractionTimeoutMinutes, type ExtractionTimeoutMinutes, type MaterializationBatch, type MaterializationGroup, type PipelineAction, type PipelineActivityUpdate, type PipelineItemState, type PipelineModel, type PipelineSelection, type PipelineStage, type PipelineTask, type PipelineWorkStage } from './types.js'
 
 export interface PipelineSource extends SourceRaw { version: number; sourceHash: string }
 export interface PipelineContext {
   model: PipelineModel & { call?: ModelCall; why?: string }
   note: string
+  extractionTimeoutMinutes?: ExtractionTimeoutMinutes
   profile?: WikiTypeDef
   organize: boolean
   format: 'json' | 'table'
 }
 export interface PipelineBuildResult { summary: string; skipped?: boolean }
+export interface PipelineDeriveProgress {
+  done: number; total: number; reused: number; failed?: number
+  phase: PipelineActivityUpdate['phase']; summary: string
+  item?: { id: string; title: string; state: PipelineItemState['state'] }
+}
+export interface ExtractionExecution {
+  fingerprint: string
+  force: boolean
+  signal: AbortSignal
+  checkpoint: () => Promise<void>
+  progress: (text: string, activity?: PipelineActivityUpdate) => void
+}
 export interface PipelineHost {
   capture(): PipelineContext
   serialize<T>(work: () => Promise<T>): Promise<T>
@@ -21,23 +34,29 @@ export interface PipelineHost {
   /** 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>
+  extract(source: PipelineSource, context: PipelineContext, output: (text: string) => void, execution: ExtractionExecution): Promise<TrialReport>
   normalize(source: PipelineSource, checkpoint: ExtractionCheckpoint, context: PipelineContext, force: boolean, output: (text: string) => void): Promise<{ reused: boolean; warnings: string[] }>
-  derive?(sourceIds: string[] | undefined, context: PipelineContext, force: boolean, output: (text: string) => void, checkpoint: () => Promise<void>): Promise<{ done: number; total: number; reused: number; summary: string }>
+  derive?(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 }>
   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>
+  link?(): Promise<string>
+  build(taskId: string, checkpoint: () => Promise<void>, progress?: (text: string) => void): Promise<PipelineBuildResult>
   record(checkpoint: ExtractionCheckpoint): Promise<void>
 }
 
 class TaskCancelled extends Error {}
-interface Control { pause: boolean; cancel: boolean; resume?: () => void }
+interface Control { abort: AbortController; 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) {}
+  constructor(readonly store: PipelineStore, private readonly host: PipelineHost) {
+    for (const previous of store.tasks(10000).tasks.filter(task => task.recoverableOnRestart && !task.recoveryTaskId)) {
+      const resumed = this.start(previous.stage, { ...previous.selection, force: false })
+      this.patch(previous.id, { recoverableOnRestart: false, recoveryTaskId: resumed.task.id, summary: '服务重启，已自动创建续跑任务；复用已完成分片。' })
+    }
+  }
 
   start(stage: PipelineStage, selection: PipelineSelection = {}): { task: PipelineTask; completion: Promise<PipelineTask> } {
     if (this.closed) throw new Error('知识处理已关闭')
@@ -45,15 +64,16 @@ export class KnowledgePipeline {
     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 captured = this.host.capture()
+    const context = { ...captured, extractionTimeoutMinutes: normalizeExtractionTimeoutMinutes(captured.extractionTimeoutMinutes) }
     const { call: _call, why: _why, ...model } = context.model
     const task: PipelineTask = {
-      id: `pipeline_${randomUUID()}`, stage, state: 'queued', selection: structuredClone(selection), model,
+      id: `pipeline_${randomUUID()}`, stage, state: 'queued', selection: structuredClone(selection), model, extractionTimeoutMinutes: context.extractionTimeoutMinutes,
       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 })
+    this.controls.set(task.id, { abort: new AbortController(), 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)
@@ -62,7 +82,7 @@ export class KnowledgePipeline {
 
   close(): void {
     this.closed = true
-    for (const control of this.controls.values()) { control.cancel = true; control.pause = false; control.resume?.() }
+    for (const control of this.controls.values()) { control.abort.abort(new TaskCancelled('知识库已关闭，已完成结果保留')); control.cancel = true; control.pause = false; control.resume?.() }
   }
 
   control(id: string, action: PipelineAction): PipelineTask {
@@ -71,17 +91,18 @@ export class KnowledgePipeline {
     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: '当前文档或卡片处理完成后暂停' })
+      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' })
+      this.patch(id, { state: task.startedAt ? 'running' : 'queued', summary: task.startedAt ? '已继续运行' : '等待运行' })
       control.resume?.()
       control.resume = undefined
     } else {
+      control.abort.abort(new TaskCancelled('任务已停止，已完成分片保留'))
       control.cancel = true
       control.pause = false
-      this.patch(id, { state: 'cancelling', summary: '当前文档或卡片处理完成后停止' })
+      this.patch(id, { state: 'cancelling', summary: '已请求停止，正在结束当前步骤；已保存结果保留' })
       control.resume?.()
     }
     return this.store.task(id)!
@@ -92,7 +113,16 @@ export class KnowledgePipeline {
     this.store.putTask(task)
     return task
   }
-  private finishStage(id: string, outcome?: Pick<PipelineBuildResult, 'summary' | 'skipped'>): void {
+  private observe(id: string, activity: PipelineActivityUpdate, text?: string): void {
+    const observed = { ...activity, at: new Date().toISOString() }
+    const task = this.patch(id, { activity: observed, ...(text ? { summary: text } : {}) })
+    if (text) this.store.event(id, 'progress', text, task.currentStage === 'extract' || task.currentStage === 'normalize' ? activity.objectId : undefined, task.currentStage, observed)
+  }
+  private item(id: string, stage: PipelineWorkStage, key: string, value: PipelineItemState): void {
+    const task = this.store.task(id)!
+    this.patch(id, { items: { ...task.items, [stage]: { ...task.items?.[stage], [key]: value } } })
+  }
+  private finishStage(id: string, outcome?: Pick<PipelineBuildResult, 'summary' | 'skipped'> & { blocked?: number }): 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 } } })
   }
@@ -113,6 +143,9 @@ export class KnowledgePipeline {
     const flush = (): void => {
       if (!buffer) return
       this.store.event(id, 'output', buffer, sourceId, stage)
+      const activity = this.store.task(id)?.activity
+      // Persist liveness at most once a second; raw output remains in the event stream.
+      if (activity && Date.now() - Date.parse(activity.at) >= 1000) this.observe(id, { ...activity, phase: 'receiving' })
       buffer = ''
       last = Date.now()
     }
@@ -151,20 +184,27 @@ export class KnowledgePipeline {
       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)
+        this.observe(id, { phase: 'preparing' }, `开始${PIPELINE_STAGE_LABEL[stage]}`)
         if (stage === 'derive') {
           if (!this.host.derive) throw new Error('当前运行时不支持 Case 提炼')
           const output = this.output(id, stage)
+          this.observe(id, { phase: 'processing' }, '正在检查 Case 并提炼可复用方法')
           try {
-            const result = await this.host.derive(task.selection.sourceIds, context, Boolean(task.selection.force), output.append, () => this.checkpoint(id))
+            const result = await this.host.derive(task.selection.sourceIds, context, Boolean(task.selection.force), output.append, () => this.checkpoint(id), value => {
+              this.patch(id, { done: value.done, total: value.total, reused: value.reused, failed: value.failed ?? 0 })
+              if (value.item) this.item(id, stage, value.item.id, { title: value.item.title, state: value.item.state })
+              this.observe(id, { phase: value.phase, objectId: value.item?.id, objectTitle: value.item?.title }, value.summary)
+            })
             this.patch(id, result)
             this.finishStage(id, result)
           } finally { output.flush() }
           continue
         }
         if (stage === 'build') {
-          const result = await this.host.build(id, () => this.checkpoint(id))
+          this.observe(id, { phase: 'processing' }, '正在构建并发布检索索引')
+          const result = await this.host.build(id, () => this.checkpoint(id), text => this.observe(id, { phase: 'processing' }, text))
           this.patch(id, { done: 1, total: 1, summary: result.summary })
+          this.observe(id, { phase: 'completed' }, result.summary)
           this.finishStage(id, result)
           continue
         }
@@ -186,10 +226,13 @@ export class KnowledgePipeline {
            * 「坐标有歧义」与「来源变了、抽取结果还没归一」是两件事，报同一句话会让读的人
            * 去查错的地方。更要紧的是范围：按 `sourceIds` / `groupKeys` 缩小的那一趟，
            * 如果拿全库的数字报 `partial`，调用方会去重试一件它明确排除的事 —— 而它其实
-           * 全都做完了。坐标有歧义的那些行不属于任何分组，无法按来源归属，所以只在
-           * 没有选择范围时才计入。
+           * 全都做完了。被阻断的 Knowledge 保留来源归属和可确定的分组键，因此也按
+           * 同一选择范围计数；尚无坐标的行只参与来源范围与全库统计。
            */
-          const ambiguous = scoped ? 0 : batch.blockedAmbiguous
+          const ambiguous = scoped
+            ? (batch.blockedItems ?? []).filter(item => (!affectedSources || item.sourceIds.some(id => affectedSources.has(id)))
+              && (!selected || (item.groupKey !== undefined && selected.has(item.groupKey)))).length
+            : batch.blockedAmbiguous
           const awaiting = scoped
             ? groups.filter(group => group.state === 'blocked' && inScope(group)).reduce((sum, group) => sum + group.knowledgeCount, 0)
             : batch.blockedAwaitingNormalize
@@ -207,19 +250,27 @@ export class KnowledgePipeline {
           this.patch(id, { total: pending.length })
           for (const group of pending) {
             await this.checkpoint(id)
+            this.item(id, stage, group.key, { state: 'processing', title: group.title })
+            this.observe(id, { phase: 'processing', objectId: group.key, objectTitle: group.title }, `正在物化：${group.title}`)
             const output = this.output(id, stage)
+            let itemError: string | undefined
             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)}`
+              itemError = message
               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() }
+            this.item(id, stage, group.key, { state: itemError ? 'failed' : 'succeeded', title: group.title, summary: itemError })
+            this.observe(id, { phase: itemError ? 'failed' : 'completed', objectId: group.key, objectTitle: group.title }, itemError ?? `已保存卡片：${group.title}`)
             const current = this.store.task(id)!
             this.patch(id, { done: current.done + 1, summary: `已物化 ${current.done + 1}/${pending.length} 张：${group.title}` })
           }
+          await this.checkpoint(id)
+          if (this.host.link) this.store.event(id, 'output', await this.host.link(), undefined, stage)
           const current = this.store.task(id)!
           /**
            * 阶段结论要给 `summary`：任务列表的四段步轨读的是 `results[stage]`，
@@ -227,6 +278,7 @@ export class KnowledgePipeline {
            * 同一件事在半个屏幕上两种说法。
            */
           this.finishStage(id, {
+            blocked: deferred,
             summary: `已物化 ${current.done - current.failed}/${current.total} 张${deferred > 0 ? `；${deferred} 条待归一` : ''}${affectedSources !== undefined ? `（按来源范围缩小：${affectedSources.size} 份来源）` : ''}`,
           })
           /**
@@ -242,16 +294,23 @@ export class KnowledgePipeline {
         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)
+          this.item(id, stage, source.sourceId, { state: 'processing', title: source.title })
+          this.observe(id, { phase: 'processing', objectId: source.sourceId, objectTitle: source.title }, `${PIPELINE_STAGE_LABEL[stage]}：${source.title}`)
           const output = this.output(id, stage, source.sourceId)
           let reused = false
+          let itemError: string | undefined
           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)
+                const report = await this.host.extract(source, context, output.append, {
+                  fingerprint, force: task.selection.force === true, signal: this.controls.get(id)!.abort.signal,
+                  checkpoint: () => this.checkpoint(id), progress: (text, activity) => {
+                    this.observe(id, activity ?? { phase: 'processing', objectId: source.sourceId, objectTitle: source.title }, text)
+                  },
+                })
                 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.
@@ -280,6 +339,7 @@ export class KnowledgePipeline {
                   const detail = report.exceptions.slice(0, 3).map(item => `${item.step}：${item.message}`).join('；')
                   throw new Error(`${report.model.why ?? '抽取返回未通过校验'}${detail === '' ? '' : `（${detail}）`}`)
                 }
+                this.observe(id, { ...this.store.task(id)!.activity!, phase: 'saving' }, '正在提交文档抽取结果')
                 this.store.saveExtraction(checkpoint)
               }
             } else {
@@ -294,10 +354,13 @@ export class KnowledgePipeline {
           } catch (cause) {
             if (cause instanceof TaskCancelled) throw cause
             const message = `${source.title}：${cause instanceof Error ? cause.message : String(cause)}`
+            itemError = message
             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() }
+          this.item(id, stage, source.sourceId, { state: itemError ? 'failed' : reused ? 'reused' : 'succeeded', title: source.title, summary: itemError })
+          this.observe(id, { ...this.store.task(id)!.activity!, phase: itemError ? 'failed' : reused ? 'reused' : 'completed' }, itemError ?? `${source.title}：${reused ? '复用已有结果' : '处理完成'}`)
           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 ? ' · 复用已有结果' : ''}` })
         }

package/src/pipeline/progress.ts

@@ -0,0 +1,40 @@
+import { PIPELINE_ACTIVE_STATES, PIPELINE_STAGE_ORDER, type PipelineState, type PipelineTask, type PipelineWorkStage } from './types.js'
+
+export const PIPELINE_STATE_LABEL: Record<PipelineState, string> = {
+  queued: '排队中', running: '进行中', pausing: '等待暂停', paused: '已暂停', cancelling: '正在停止',
+  succeeded: '已完成', partial: '部分完成', failed: '失败', cancelled: '已停止', interrupted: '已中断',
+}
+export interface TaskStageObservation {
+  label: string
+  tone: 'neutral' | 'success' | 'warning' | 'blue'
+  detail: string
+}
+
+/** A stage observation always belongs to one execution, never a mixture of past runs. */
+export function observeTaskStage(task: PipelineTask, stage: PipelineWorkStage): TaskStageObservation {
+  if (task.stage !== 'all' && task.stage !== stage) return { label: '本次未运行', tone: 'neutral', detail: '此阶段不在本次任务范围内。' }
+  const result = task.results?.[stage]
+  if (result) {
+    const counts = `成功 ${Math.max(0, result.done - result.failed)}/${result.total}${result.reused ? ` · 复用 ${result.reused}` : ''}${result.failed ? ` · 失败 ${result.failed}` : ''}`
+    if (result.failed || result.blocked) return { label: result.failed ? '部分失败' : '有暂缓项', tone: 'warning', detail: `${result.summary ?? counts}${result.blocked ? ` · 暂缓 ${result.blocked} 条` : ''}` }
+    if (result.skipped || result.total === 0) return { label: '已跳过', tone: 'neutral', detail: result.summary ?? '本次没有需要处理的内容。' }
+    return { label: result.reused === result.total && stage !== 'build' ? '全部复用' : '已完成', tone: 'success', detail: result.summary ?? counts }
+  }
+  const current = task.currentStage ?? (task.stage === 'all' ? 'extract' : task.stage)
+  if (current === stage) return {
+    label: PIPELINE_STATE_LABEL[task.state],
+    tone: ['failed', 'partial', 'interrupted'].includes(task.state) ? 'warning' : task.state === 'paused' || task.state === 'cancelled' ? 'neutral' : task.state === 'succeeded' ? 'success' : 'blue',
+    detail: task.total > 0 ? `已处理 ${task.done}/${task.total} · 失败 ${task.failed} · 复用 ${task.reused}` : task.summary,
+  }
+  if (PIPELINE_STAGE_ORDER.indexOf(stage) < PIPELINE_STAGE_ORDER.indexOf(current)) return { label: '已跳过', tone: 'neutral', detail: '本次运行时未执行此阶段。' }
+  return PIPELINE_ACTIVE_STATES.includes(task.state)
+    ? { label: '等待执行', tone: 'neutral', detail: '本次任务到达此阶段后自动运行。' }
+    : { label: '未执行', tone: 'neutral', detail: '任务在到达此阶段前已结束。' }
+}
+
+/** Running work wins over newer queued work; queue order remains FIFO. */
+export function orderActiveTasks(tasks: PipelineTask[]): PipelineTask[] {
+  return tasks.filter(task => PIPELINE_ACTIVE_STATES.includes(task.state)).sort((left, right) =>
+    Number(left.state === 'queued' || !left.startedAt) - Number(right.state === 'queued' || !right.startedAt)
+    || left.queuedAt.localeCompare(right.queuedAt))
+}