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

package/src/index.ts

@@ -1,3 +1,4 @@
+import { newSourceId } from './source-identity.js'
 import { embeddingModel } from './environment/model-catalog.js'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { createReadStream } from 'node:fs'
@@ -36,9 +37,9 @@ import { DOC_PAGE_CHARS, DOC_PAGE_CHARS_MAX, documentContentPage } from './docum
 import type { ModelCall } from './extract-model.js'
 import { runWikiTrial, trialSummary } from './wiki-trial.js'
 import { extractionRunId } from './extraction-runs.js'
-import type { PipelineStage } from './pipeline/types.js'
+import { DEFAULT_EXTRACTION_TIMEOUT_MINUTES, PIPELINE_ACTIVE_STATES, isExtractionTimeoutMinutes, type ExtractionTimeoutMinutes, type PipelineStage } from './pipeline/types.js'
 import {
-  agentLayout, defaultAgentRoot, ensureAgentLayout, intentRoot, knowledgeBaseRoot,
+  agentLayout, defaultAgentRoot, ensureAgentLayout, knowledgeBaseRoot,
   memoryRoot, resourceRegistry, resourceRoot, type AgentLayout,
 } from './layout.js'
 import {
@@ -55,21 +56,11 @@ import {
   type ConvertHost,
 } from './convert/host.js'
 import type { ConvertPluginConfig } from './convert/types.js'
-import {
-  applyIntent, INTENT_MOUNT_PATH, INTENT_SERVICE,
-  type IntentHost,
-  type IntentLineageService,
-  type IntentService,
-} from './intent/host.js'
-import { registerIntentTools } from './intent/tools.js'
 
 export * from './types.js'
 export * from './runtime.js'
 export * from './knowledge-bases.js'
-export * from './intent/types.js'
-export * from './intent/engine.js'
 export { applyConvert as applyConvertHost, CONVERT_SETTINGS_NAMESPACE, CONVERT_MOUNT_PATH, type ConvertHost }
-export { applyIntent as applyIntentHost, INTENT_MOUNT_PATH, INTENT_SERVICE, type IntentHost, type IntentLineageService }
 
 export const name = 'dsh-data-domain-knowledge'
 /**
@@ -93,6 +84,7 @@ export { CONVERT_SETTINGS_SCHEMA }
  */
 import { Config, type KnowledgePluginConfig } from './config-schema.js'
 import { buildModelRequest, callModelWithRetry, collectModelText } from './model-text.js'
+import { agentRecallEnvelope } from './recall-delivery.js'
 import {
   addSourceCallView, addSourceMetaOf, addSourceResultMarkdown,
   importCallView, importMetaOf, importResultMarkdown,
@@ -123,7 +115,7 @@ type WebServerLike = { register(route: { kind: 'exact' | 'prefix'; path: string;
  * `src/client/KnowledgeToolRow.tsx` 读它渲染专用卡片（值必须是 JSON 可序列化的 ——
  * 会话日志会整份校验，塞个函数或 Date 会在写日志时炸）。
  *
- * `call` / `result` 是与工具名无关的渲染意图（标题 / 分类 / 一段 Markdown），
+ * `call` / `result` 是与工具名无关的渲染参数（标题 / 分类 / 一段 Markdown），
  * 给终端界面和「没有专用卡片的界面」兜底。三个都是**纯函数**：界面在实时流和会话回放
  * 两条路径上都会调它们。
  *
@@ -212,7 +204,7 @@ function lineageOf(args: Args, exec?: ToolRunContext): LineageContext | undefine
   const sessionId = typeof args.session_key === 'string' && args.session_key.trim() ? args.session_key.trim() : exec?.agent?.session.header.id
   if (sessionId) lineage.sessionId = sessionId
   const fields: Array<[keyof LineageContext, string]> = [
-    ['turnId', 'turn_id'], ['intentId', 'intent_id'], ['taskId', 'task_id'],
+    ['turnId', 'turn_id'], ['taskId', 'task_id'],
     ['subtaskId', 'subtask_id'], ['parentSubtaskId', 'parent_subtask_id'], ['runId', 'run_id'], ['traceId', 'trace_id'], ['domain', 'domain'],
   ]
   for (const [target, source] of fields) if (typeof args[source] === 'string' && args[source].trim()) lineage[target] = args[source].trim().slice(0, 160)
@@ -223,7 +215,6 @@ function lineageFromUrl(url: URL): LineageContext | undefined {
   return lineageOf({
     session_key: url.searchParams.get('session_key') ?? undefined,
     turn_id: url.searchParams.get('turn_id') ?? undefined,
-    intent_id: url.searchParams.get('intent_id') ?? undefined,
     task_id: url.searchParams.get('task_id') ?? undefined,
     subtask_id: url.searchParams.get('subtask_id') ?? undefined,
     parent_subtask_id: url.searchParams.get('parent_subtask_id') ?? undefined,
@@ -407,8 +398,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
   /**
    * 这两组的把手，`loader/volatile-update` 时调 `reprocess()` 按新值重灌。
    *
-   * 先声明后赋值：事件只在运行时触发，而两组的装配在下面（`applyConvert` /
-   * `applyIntent`）。
+   * 先声明后赋值：事件只在运行时触发，转换宿主在下面的 `applyConvert` 中装配。
    */
   let convertHost: ConvertHost | undefined
   /**
@@ -434,6 +424,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
    */
   /** 注册表在默认 runtime 之后才构造；用一个可替换的读取器避开构造期 TDZ。 */
   let compileModelForBase: (id: string) => CompileModelSelection = () => ({ ...DEFAULT_COMPILE_MODEL })
+  let extractionTimeoutForBase: (id: string) => ExtractionTimeoutMinutes = () => DEFAULT_EXTRACTION_TIMEOUT_MINUTES
 
   const modelSeamFor = (kbId = DEFAULT_KB_ID): ModelSeam => {
     /**
@@ -489,7 +480,9 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
       provider,
       model,
       ...(effectiveReasoningEffort ? { reasoningEffort: effectiveReasoningEffort } : {}),
-      call: async ({ system, prompt, sessionId, onUsage, onDelta }) => {
+      ...(configured.maxTokens !== undefined ? { maxTokens: configured.maxTokens } : {}),
+      call: async ({ system, prompt, sessionId, onUsage, onDelta, signal, retryAttempts, maxTokens }) => {
+        const outputLimit = maxTokens ?? configured.maxTokens
         /**
          * 先走 DSH 的公开解析接口，再开始发 prompt。这样固定模型过期、默认模型失效时，
          * 编译会在模型调用边界明确失败，而不是落成一次看似成功的规则抽取。
@@ -499,6 +492,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             await llm.resolveCallConfig({
               provider, model,
               ...(effectiveReasoningEffort ? { reasoningEffort: effectiveReasoningEffort } : {}),
+              ...(outputLimit !== undefined ? { maxTokens: outputLimit } : {}),
             })
           } catch (cause) {
             const detail = cause instanceof Error ? cause.message : String(cause)
@@ -515,7 +509,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
          * （OpenCode 系路由回 400 `MissingSessionID`）。
          */
         const request = buildModelRequest({
-          provider, model, reasoningEffort: effectiveReasoningEffort, system, prompt,
+          provider, model, reasoningEffort: effectiveReasoningEffort, maxTokens: outputLimit, system, prompt,
           // 运行时按知识库给；接缝被单独调用时（测试）退回一个稳定值，
           // 而不是留空 —— 留空会在 OpenCode 路由上 400。
           sessionId: sessionId ?? 'knowledge:default',
@@ -534,14 +528,15 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
          * 由 `isRetryableModelFailure` 放行，不在错的地方多等两分钟。
          */
         return callModelWithRetry(
-          onDeltaOfAttempt => collectModelText(llm.stream(request) as AsyncIterable<never>, onUsage, onDeltaOfAttempt),
-          { ...(onDelta ? { onDelta } : {}) },
+          onDeltaOfAttempt => collectModelText(llm.stream({ ...request, ...(signal ? { signal } : {}) }) as AsyncIterable<never>, onUsage, onDeltaOfAttempt),
+          { ...(onDelta ? { onDelta } : {}), attempts: retryAttempts, signal },
         )
       },
     }
   }
   let environment: KnowledgeEnvironment
   const runtimeOptions = (): KnowledgeRuntimeOptions => ({
+    extractionTimeoutMinutes: () => extractionTimeoutForBase(DEFAULT_KB_ID),
     environmentGuard: kind => environment.requireReady(kind),
     // 0029：家当目录。配置里三个路径为空时，运行时从这里解析模型与解释器。
     resourceRoot: resourceRoot(config.agentRoot),
@@ -582,6 +577,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
   runtimeOptions: () => ({ resourceRoot: resourceRoot(config.agentRoot), modelSeam: modelSeamFor, environmentGuard: kind => environment.requireReady(kind) }),
   })
   compileModelForBase = id => bases.compileModelOf(id)
+  extractionTimeoutForBase = id => bases.extractionTimeoutMinutesOf(id)
   runtime.baseId = bases.defaultId
   activeKnowledgeBases = bases
   environment = new KnowledgeEnvironment({
@@ -617,7 +613,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
   // Reuse a matching persisted probe after restart; only stale or missing reports need a resource check.
   if (environment.view().report.state !== 'ready') void environment.check(false).catch(() => undefined)
 
-  type CompileModelCatalogItem = { provider: string; id: string; name: string; description?: string; available: boolean; current?: boolean; reasoning?: { efforts: Array<{ id: string; name: string; description?: string }>; defaultEffort?: string } }
+  type CompileModelCatalogItem = { provider: string; id: string; name: string; description?: string; available: boolean; current?: boolean; defaultMaxTokens?: number; reasoning?: { efforts: Array<{ id: string; name: string; description?: string }>; defaultEffort?: string } }
   const compileModelCatalog = async (kbId: string, queryModelRoute: { provider?: string; model?: string } = {}): Promise<{
     selection: CompileModelSelection
     default: { provider?: string; model?: string; reasoningEffort?: string; available: boolean }
@@ -630,7 +626,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     const llm = ctx.get('llm') as {
       listModels?: (provider: string) => Promise<Array<{ id: string; name?: string; description?: string }>>
       listProviders?: () => Array<{ id: string; name: string }>
-      resolveModelInfo?: (provider: string, model: string) => Promise<{ reasoning?: CompileModelCatalogItem['reasoning'] }>
+      resolveModelInfo?: (provider: string, model: string) => Promise<{ reasoning?: CompileModelCatalogItem['reasoning']; defaultMaxTokens?: number }>
     } | undefined
     const providers = [...new Set([...(llm?.listProviders?.() ?? []).map(provider => provider.id), defaultRoute.provider, compileModelForBase(kbId).provider].filter((value): value is string => Boolean(value)))]
     const models: CompileModelCatalogItem[] = []
@@ -666,7 +662,11 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     if (requestedProvider && requestedModel && llm?.resolveModelInfo) {
       const item = models.find(model => model.provider === requestedProvider && model.id === requestedModel)
       if (item) {
-        try { item.reasoning = (await llm.resolveModelInfo(requestedProvider, requestedModel)).reasoning }
+        try {
+          const info = await llm.resolveModelInfo(requestedProvider, requestedModel)
+          item.reasoning = info.reasoning
+          if (info.defaultMaxTokens !== undefined) item.defaultMaxTokens = info.defaultMaxTokens
+        }
         catch (cause) { failures.push(`思考强度目录：${cause instanceof Error ? cause.message : String(cause)}`) }
       }
     }
@@ -806,7 +806,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     /**
      * 交付物落在**工作项目**下：`<工作区>/output/<日期>/`，不是 Agent 根路径。
      *
-     * 根路径下的四段（知识 / 记忆 / 意图 / 家当）是**这个 Agent 自己的东西**，跨项目
+     * 根路径下的几段（知识 / 记忆 / 家当）是**这个 Agent 自己的东西**，跨项目
      * 累积；交付物是**某个项目的产物**，换一个项目打开就不该再看见。两者判据不同，
      * 所以落点也不同。
      *
@@ -827,30 +827,6 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     },
   })
 
-  // 意图记录模块 (issue 0020). The 意图 view was already one of this plugin's
-  // five panel tabs, but its Host lived in a second mount unit; 0020 folds it in
-  // so the declared information architecture and the code layout agree again.
-  // It keeps the `intent_record` / `intent_store_view` tools and `/intent/**` audit endpoints,
-  // and — critically — the `titaDataAgentIntent` Cordis service that `data-table`
-  // resolves by name.
-  // 意图只保留固定的会话审计契约；可编辑词表不再属于插件配置。
-  applyIntent(ctx, {
-    intentRoot: () => intentRoot(config.agentRoot),
-  })
-  // `applyIntent` provides this service from the same plugin fiber. During
-  // `apply()`, that fiber is still starting, so Cordis's default strict lookup
-  // hides the just-provided service until startup completes. The non-strict
-  // lookup is safe here because `applyIntent` ran immediately above.
-  const intentService = ctx.get(INTENT_SERVICE, false) as IntentService
-  /**
-   * `intent_*` 工具在 Host 层注册，使标准模式可以调用它们；工具执行端只接受
-   * standard 会话，其他 preset 不会写入或读取意图记录。
-   */
-  ctx.effect(
-    () => registerIntentTools(ctx as unknown as { tools: { register(definition: unknown): unknown } }, intentService),
-    'tita knowledge: global intent tools',
-  )
-
   /**
    * 规则正文由当前会话 preset 决定；设置里的 volatile 引用在每次组装提示词时解包，
    * 因此开关保存后立即生效，不需要重建 Agent 会话。
@@ -895,45 +871,37 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     if (writeTools.has(exec.name)) return Promise.resolve({ kind: 'ask', reason: '该操作会写入 Tita Knowledge Store，需要本轮用户审批。' })
     return next()
   })
-  ctx.tools.register(tool('recall_knowledge', 'Recall Wiki Fact and Wiki Way through H2 title and body search. Use the current subquestion as query when seeking a Procedure. Return complete Wiki files with conditions and evidence. Use get_knowledge_cases for historical Case evidence; a past root cause does not establish the current root cause.', { query: { type: 'string', required: true }, limit: { type: 'integer' }, top_k: { type: 'integer' }, top_n: { type: 'integer' }, rerank: { type: 'boolean' }, context_max_chars: { type: 'integer', description: '这次召回的上下文字符上限；省略则用设置里的值（默认 20000，0 = 不限）。超出部分落在系统临时目录，响应里的 budget.overflow_path 就是它的绝对路径 —— 需要更多信息时直接读那个文件。' }, include_problems: { type: 'boolean' }, mode: { type: 'string', enum: ['fts', 'vector', 'hybrid'] }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, parent_subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.recall(args.query, args.top_k ?? args.limit, args.include_problems ?? false, args.mode as RecallMode | undefined, lineageOf(args, exec), { contextTopN: args.top_n, rerank: args.rerank, ...(typeof args.context_max_chars === 'number' ? { contextMaxChars: args.context_max_chars } : {}) })), {
-    call: recallCallView,
-    // 查询词从参数来，命中从结果来 —— 两者拼成一张能看懂的账本。
-    meta: (args, value) => recallMetaOf({ ...dataOf(value), query: args?.query }),
-    result: resultViewOf(recallResultMarkdown),
+  const scopeParameters = { object_id: { type: 'string', description: 'Known Object ID. Omit for all; empty matches empty only.' }, action_id: { type: 'string' }, scene_id: { type: 'string' } }
+  const scopeOf = (args: Args) => ({ objectId: args.object_id, actionId: args.action_id, sceneId: args.scene_id, wikiKind: args.wiki_kind })
+  ctx.tools.register(tool('recall_knowledge', 'Search H2 sections, rank and deduplicate Wiki files, then deliver complete Wiki Fact / Wiki Way within the budget. Query the current subquestion for methods. top_k counts distinct Wiki candidates; top_n counts delivered hit files. Optional known coordinate IDs and wiki_kind filter every retrieval route before ranking. foundCandidates and contentDelivered distinguish matches from delivered bodies. For budget omissions call read_knowledge_wiki with budget.omitted[].read.args. Scores indicate retrieval relevance, not factual truth. Historical Case does not prove the present root cause.', {
+    query: { type: 'string', required: true }, ...scopeParameters, wiki_kind: { type: 'string', enum: ['fact', 'way'] },
+    limit: { type: 'integer', description: 'Compatibility alias for top_k.' }, top_k: { type: 'integer', description: 'Distinct Wiki candidates, 1–50.' }, top_n: { type: 'integer', description: 'Maximum complete hit Wiki files to deliver, no more than top_k.' },
+    rerank: { type: 'boolean' }, context_max_chars: { type: 'integer', description: 'Complete-context character budget; 0 explicitly disables the limit. Omitted files have stable read references in budget.omitted. overflowPath is a local diagnostic file, not the Agent continuation contract.' },
+    include_problems: { type: 'boolean' }, mode: { type: 'string', enum: ['fts', 'vector', 'hybrid'] }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, parent_subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' },
+  }, async (args, exec) => withRuntime(args.kb, async target => agentRecallEnvelope(await target.recall(args.query, args.top_k ?? args.limit, args.include_problems ?? false, args.mode as RecallMode | undefined, lineageOf(args, exec), { ...scopeOf(args), contextTopN: args.top_n, rerank: args.rerank, contextMaxChars: args.context_max_chars }))), {
+    call: recallCallView, meta: (args, value) => recallMetaOf({ ...dataOf(value), query: args?.query }), result: resultViewOf(recallResultMarkdown),
   }))
-  ctx.tools.register(tool('get_knowledge_cases', 'Read historical Case records referenced by Wiki metadata.case_refs. Timelines are evidence from a past instance, not proof of the present diagnosis.', {
-    case_ids: { type: 'array', required: true, description: 'Case IDs from Wiki metadata.case_refs; maximum 50 IDs.' },
-    version: { type: 'integer', description: 'Optional historical Case version from metadata.case_refs; requires exactly one case ID.' },
-    kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' },
-    run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' },
-  }, async args => withRuntime(args.kb, async target => {
-    const ids = [...new Set((Array.isArray(args.case_ids) ? args.case_ids : [])
-      .filter((id): id is string => typeof id === 'string' && id.trim() !== '').map(id => id.trim()))]
-    if (ids.length === 0) return failure({ cases: [], missing_ids: [] }, 'CASE_IDS_REQUIRED', '请传入 Wiki 的 case_refs 中的 Case ID。', false)
-    if (ids.length > 50) return failure({ cases: [], missing_ids: [] }, 'CASE_IDS_LIMIT', '一次最多读取 50 个 Case ID。', false)
-    if (args.version !== undefined && (ids.length !== 1 || !Number.isInteger(args.version) || args.version < 1)) return failure({ cases: [], missing_ids: ids }, 'CASE_VERSION_INVALID', '读取历史版本时，请传一个 Case ID 和正整数 version。', false)
-    const records = await Promise.all(ids.map(id => target.readCase(id, args.version)))
-    return success({ cases: records.filter(record => record !== undefined), missing_ids: ids.filter((_, index) => records[index] === undefined) })
-  })))
-  ctx.tools.register(tool('get_knowledge_events', 'Read Event records referenced by recalled WikiCards. Pass event IDs from card metadata.event_refs; the result includes full timelines, evidence, outcomes, and missing fields.', {
-    event_ids: { type: 'array', required: true, description: 'Event IDs from WikiCard metadata.event_refs; maximum 50 IDs.' },
-    kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' },
-    run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' },
-  }, async args => withRuntime(args.kb, async target => {
-    const ids = [...new Set((Array.isArray(args.event_ids) ? args.event_ids : [])
-      .filter((id): id is string => typeof id === 'string' && id.trim() !== '').map(id => id.trim()))]
-    if (ids.length === 0) return failure({ events: [], missing_ids: [] }, 'EVENT_IDS_REQUIRED', '请传入 WikiCard 的 event_refs 中的 Event ID。', false)
-    if (ids.length > 50) return failure({ events: [], missing_ids: [] }, 'EVENT_IDS_LIMIT', '一次最多读取 50 个 Event ID；请分批读取该 WikiCard 的 event_refs。', false)
-    const byId = new Map((await target.loadEvents()).map(event => [event.id, event]))
-    const events = ids.flatMap(id => {
-      const event = byId.get(id)
-      return event ? [event] : []
-    })
-    return success({ events, missing_ids: ids.filter(id => !byId.has(id)) })
-  })))
+  ctx.tools.register(tool('read_knowledge_wiki', 'Read a complete Wiki through a stable target or browse an Object directory. Omitted axes mean all; empty axes mean empty only. Directory mode omits content by default. include_content requests complete files within max_chars. If a file does not fit, follow nextRead for explicit body pages, concatenate them and read all conditions before applying a Procedure. expected_version prevents mixing Wiki versions. contentPage is partial unless contentComplete is true. Outgoing links and backlinks are independently bounded by link_limit; advance link_offset using links.nextOffset. Follow only relevant links.', {
+    target: { type: 'string' }, ...scopeParameters, object: { type: 'string' }, wiki_kind: { type: 'string', enum: ['fact', 'way'] },
+    include_content: { type: 'boolean' }, limit: { type: 'integer' }, offset: { type: 'integer' }, max_chars: { type: 'integer' }, content_offset: { type: 'integer' }, content_max_chars: { type: 'integer' }, expected_version: { type: 'integer' }, link_limit: { type: 'integer' }, link_offset: { type: 'integer' }, kb: { type: 'string' },
+  }, async args => withRuntime(args.kb, target => target.readWiki({ ...scopeOf(args), target: args.target, object: args.object, includeContent: args.include_content, limit: args.limit, offset: args.offset, maxChars: args.max_chars, contentOffset: args.content_offset, contentMaxChars: args.content_max_chars, expectedVersion: args.expected_version, linkLimit: args.link_limit, linkOffset: args.link_offset }))))
+  ctx.tools.register(tool('get_knowledge_cases', 'Find historical Case by current subquestion or exact coordinates, or read referenced case_ids. Search returns a paged directory with version-pinned nextRead references; ID reads include full records within max_chars. Pass one case_id and its version to read historical evidence. Oversized records use explicit contentPage JSON pages; concatenate and parse before using them. Historical actions, observations and outcomes do not prove the current cause.', {
+    case_ids: { type: 'array', description: '1–50 known Case IDs; omit for search.' }, query: { type: 'string' }, ...scopeParameters,
+    version: { type: 'integer' }, include_content: { type: 'boolean' }, limit: { type: 'integer' }, offset: { type: 'integer' }, max_chars: { type: 'integer' }, content_offset: { type: 'integer' },
+    kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' },
+  }, async args => withRuntime(args.kb, target => target.queryCases({ ...scopeOf(args), ids: args.case_ids, version: args.version, query: args.query, includeContent: args.include_content, limit: args.limit, offset: args.offset, maxChars: args.max_chars, contentOffset: args.content_offset }))))
   ctx.tools.register(tool('check_knowledge_embeddings', 'Inspect the local embedding provider and binary/int8 vector index without loading the model.', { kb: { type: 'string' }, session_key: { type: 'string' } }, async args => withRuntime(args.kb, target => target.embeddingHealth())))
   ctx.tools.register(tool('query_knowledge_graph', 'Query entities, neighbors, paths, lists and relation types in the compiled knowledge graph.', { action: { type: 'string', enum: ['entity', 'neighbors', 'path', 'list', 'types'], required: true }, entity_id: { type: 'string' }, id: { type: 'string' }, entity_type: { type: 'string' }, from_id: { type: 'string' }, to_id: { type: 'string' }, type: { type: 'string' }, status: { type: 'string' }, include_problem: { type: 'boolean' }, limit: { type: 'integer' }, depth: { type: 'integer' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, parent_subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.graphQuery(args.action, args.entity_id ?? args.id, args.entity_type ?? args.type, args.depth ?? 1, { fromId: args.from_id, toId: args.to_id, status: args.status, includeProblem: args.include_problem ?? false, limit: args.limit ?? 50 }, lineageOf(args, exec)))))
-  ctx.tools.register(tool('query_source_truth', 'Read SourceRaw (原始可追溯文档) with access audit. Each call returns up to `limit` matched sources and `max_chars` total characters. If `hasMoreInCurrentPage` is true, continue with `offset += returnedChars`. When it is false and `hasMoreSources` is true, continue with `source_offset = nextSourceOffset` and reset `offset` to 0. `truncated` stays true until both the current source page and all matching source pages are complete. Do not answer from partial content.', { query: { type: 'string', required: true }, limit: { type: 'integer' }, max_chars: { type: 'integer' }, offset: { type: 'integer' }, source_offset: { type: 'integer', description: '来源分页游标；当前页字符已读完后才使用 nextSourceOffset，并将 offset 重置为 0' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.sourceTruth(args.query, args.limit ?? 20, args.max_chars ?? 40000, lineageOf(args, exec), args.offset ?? 0, args.source_offset ?? 0))))
+  ctx.tools.register(tool('query_source_truth', 'Read a precise Source Raw using source_id plus the evidence version, optional content_hash and [start,end) UTF-16 offsets. Prefer readRef returned by knowledge tools. IDs are opaque and scoped to kb; never infer one from a title, path, hash or external_id. Unknown IDs, unavailable versions and mismatched hashes or quotes fail explicitly; there is no fallback to another source. Exact-read offset is relative to the selected range; follow nextRead to continue. Without source_id, query discovers sources and returns version-pinned readRef for precise follow-up. Discovery uses source_offset for source pages and offset for text pages; advance with returnedChars and nextSourceOffset. Do not apply incomplete evidence.', {
+    source_id: { type: 'string' }, version: { type: 'integer' }, content_hash: { type: 'string' }, start: { type: 'integer' }, end: { type: 'integer' }, quote: { type: 'string' }, query: { type: 'string' }, limit: { type: 'integer' }, max_chars: { type: 'integer' }, offset: { type: 'integer' }, source_offset: { type: 'integer' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' },
+  }, async (args, exec) => withRuntime(args.kb, async target => {
+    if (args.source_id !== undefined) {
+      if (args.query !== undefined || args.source_offset !== undefined) return failure({}, 'SOURCE_SELECTION_CONFLICT', '精确读取 source_id 时不要传 query 或 source_offset。', false)
+      return target.readSource({ sourceId: args.source_id, version: args.version, contentHash: args.content_hash, start: args.start, end: args.end, quote: args.quote, maxChars: args.max_chars, offset: args.offset }, lineageOf(args, exec))
+    }
+    if (typeof args.query !== 'string' || !args.query.trim() || [args.version, args.content_hash, args.start, args.end, args.quote].some(value => value !== undefined)) return failure({}, 'SOURCE_QUERY_REQUIRED', '搜索请传非空 query；版本、哈希和引文范围读取必须提供 source_id。', false)
+    return target.sourceTruth(args.query, args.limit ?? 20, args.max_chars ?? 40000, lineageOf(args, exec), args.offset ?? 0, args.source_offset ?? 0)
+  })))
   /**
    * 知识库 id 的**发现入口**。
    *
@@ -984,7 +952,12 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
   const imagePublishDescription = 'Publish one local image into a knowledge base assets bucket without user approval. Pass exactly one of `file_path` or `content_base64` (standard Base64 or a data URI); optional `filename` overrides the stored name, and optional `mime_type` must match the file bytes. Supports PNG, JPEG, GIF, WebP, AVIF, BMP and SVG up to 20 MiB. Returns the local asset URL and Markdown image reference.'
   ctx.tools.register(tool('image_publish', imagePublishDescription, imagePublishParameters, publishImage))
 
-  ctx.tools.register(tool('add_source', 'Add or update a SourceRaw document (原始可追溯文档). DSH requests one user approval before execution.', { title: { type: 'string' }, content: { type: 'string', required: true }, external_id: { type: 'string' }, metadata: { type: 'json' }, source_id: { type: 'string' }, allow_duplicate_title: { type: 'boolean', description: '默认 false：标题与已有来源重复时拒收（SOURCE_TITLE_DUPLICATED），要求改标题。传 true 才允许并存。' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.addSource({ title: args.title, content: args.content, externalId: args.external_id, metadata: args.metadata, sourceId: args.source_id, ...(args.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}), lineage: lineageOf(args, exec) })), {
+  ctx.tools.register(tool('allocate_source_ids', 'Allocate opaque Source Raw IDs before import. Keep one ID per independent input; reuse it across conversion, transport retries, renames and updates. IDs are not reserved documents until imported. Existing sources keep their current IDs. Never allocate a new ID to update an existing source.', { count: { type: 'integer', description: '1–100, default 1.' } }, async args => {
+    const count = args.count ?? 1
+    if (!Number.isInteger(count) || count < 1 || count > 100) return failure({ source_ids: [] }, 'SOURCE_COUNT_INVALID', 'count 必须为 1–100。', false)
+    return success({ source_ids: Array.from({ length: count }, () => newSourceId()) })
+  }))
+  ctx.tools.register(tool('add_source', 'Add or update Source Raw. For links/platform documents pass source_url or source_identity: identity lookup reuses the existing source_id, otherwise allocates one. For independent files first use allocate_source_ids and retain the ID across retries. Updates use the known source_id and preferably expected_version from an exact read (0 means create only). Titles, paths, body hashes and arbitrary external_id are not update keys. A preallocated unused ID may resolve to an existing document; always use the returned sourceId. Known IDs with contradictory origin fail. Returns a version-pinned readRef. DSH requests one user approval before execution.', { title: { type: 'string' }, content: { type: 'string', required: true }, external_id: { type: 'string' }, metadata: { type: 'json' }, source_id: { type: 'string' }, source_url: { type: 'string', description: 'Explicit acquisition URL, preserving query and fragment. Do not copy an unverified link from body text.' }, source_identity: { type: 'json', description: '{system, scope, document_id, document_type?, url?}; native identity requires system, scope and document_id. URL-only identity can use {url, scope?}.' }, expected_version: { type: 'integer' }, allow_duplicate_title: { type: 'boolean', description: '默认 false：标题与已有来源重复时拒收（SOURCE_TITLE_DUPLICATED），要求改标题。传 true 才允许并存。' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => (typeof args.source_id !== 'string' || !args.source_id.trim()) && args.source_url === undefined && args.source_identity === undefined ? failure({ sourceId: '' }, 'SOURCE_ID_REQUIRED', '请先分配 source_id；重试或更新复用已有 ID。', false) : withRuntime(args.kb, target => target.addSource({ title: args.title, content: args.content, externalId: args.external_id, metadata: args.metadata, sourceId: args.source_id, sourceUrl: args.source_url, sourceIdentity: args.source_identity, expectedVersion: args.expected_version, ...(args.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}), lineage: lineageOf(args, exec) })), {
     call: addSourceCallView,
     meta: (args, value) => addSourceMetaOf(args, dataOf(value)),
     result: resultViewOf(addSourceResultMarkdown),
@@ -1000,10 +973,10 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
    * 两者的差别只在「一次多少份」，落盘路径、分类闸门、编译链路完全共用 ——
    * 这个工具的 `execute` 就是循环调 `importSources`，而后者逐条调 `addSource`。
    *
-   * `compile` 默认开：批量导入的意图几乎总是「进来就能用」。关掉它的场景是「先全部
-   * 落盘、稍后统一编译」——那时卡片还没生成，工具返回里会明说 `compile: null`。
+   * `compile` 默认关闭：先保存来源，再由调用方决定何时处理。显式 true 才跑全链路；
+   * 未触发处理时工具返回 `compile: null`。
    */
-  ctx.tools.register(tool('import_sources', 'Import many SourceRaw documents in one call. By default only stores sources. Explicit compile:true runs extract, normalize, materialize, and index publication for the imported documents. Per-source import failures are reported without aborting the batch. DSH requests one user approval before execution.', { sources: { type: 'array', required: true, description: `来源数组，每项 { title?, content, external_id?, metadata?, allow_duplicate_title? }；一次最多 ${MAX_IMPORT_SOURCES} 份，超了请分批。标题与已有来源重复的那一份会被拒（SOURCE_TITLE_DUPLICATED），逐条报出来而不是整批失败` }, compile: { type: 'boolean', description: '默认 false：只保存来源；显式 true 才运行完整抽取、归一与物化' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.importSources({ sources: (Array.isArray(args.sources) ? args.sources : []).map(item => ({ ...(item?.title ? { title: item.title } : {}), content: item?.content, ...(item?.external_id ? { externalId: item.external_id } : {}), ...(item?.metadata ? { metadata: item.metadata } : {}), ...(item?.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}) })), compile: args.compile === true, lineage: lineageOf(args, exec) })), { call: importCallView, meta: (_args, value) => importMetaOf(dataOf(value)), result: resultViewOf(importResultMarkdown) }))
+  ctx.tools.register(tool('import_sources', 'Import many SourceRaw documents in one call. By default only stores sources. Explicit compile:true runs extract, normalize, materialize, and index publication for the imported documents. Per-source import failures are reported without aborting the batch. DSH requests one user approval before execution.', { sources: { type: 'array', required: true, description: `来源数组，每项 { source_id?, source_url?, source_identity?, expected_version?, title?, content, external_id?, metadata?, allow_duplicate_title? }；链接提供 source_url 或 source_identity，先查来源映射；独立文件先分配 source_id，重试沿用；以后续返回的 sourceId 为准；更新旧来源必须传其 source_id；一次最多 ${MAX_IMPORT_SOURCES} 份，超了请分批。标题与已有来源重复的那一份会被拒（SOURCE_TITLE_DUPLICATED），逐条报出来而不是整批失败` }, compile: { type: 'boolean', description: '默认 false：只保存来源；显式 true 才运行完整抽取、归一与物化' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => Array.isArray(args.sources) && args.sources.some(item => (typeof item?.source_id !== 'string' || !item.source_id.trim()) && item?.source_url === undefined && item?.source_identity === undefined) ? failure({}, 'SOURCE_ID_REQUIRED', '请先为每个输入分配 source_id；重试或更新沿用已有 ID。', false) : withRuntime(args.kb, target => target.importSources({ sources: (Array.isArray(args.sources) ? args.sources : []).map(item => ({ ...(item?.source_id ? { sourceId: item.source_id } : {}), ...(item?.expected_version === undefined ? {} : { expectedVersion: item.expected_version }), ...(item?.source_url === undefined ? {} : { sourceUrl: item.source_url }), ...(item?.source_identity === undefined ? {} : { sourceIdentity: item.source_identity }), ...(item?.title ? { title: item.title } : {}), content: item?.content, ...(item?.external_id ? { externalId: item.external_id } : {}), ...(item?.metadata ? { metadata: item.metadata } : {}), ...(item?.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}) })), compile: args.compile === true, lineage: lineageOf(args, exec) })), { call: importCallView, meta: (_args, value) => importMetaOf(dataOf(value)), result: resultViewOf(importResultMarkdown) }))
   /**
    * `propose_wiki_cards` —— 把一批卡片**直接写进 `02_wiki`**（工具名不变，语义在 0044 改了）。
    *
@@ -1146,6 +1119,17 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
         return send(res, 200, success(await resolved.runtime.stats()))
       } },
+      { kind: 'exact' as const, path: '/knowledge/wiki', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        if (req.method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', 'Wiki 读取只接受 GET'))
+        const url = query(req)
+        const resolved = resolveBase(url.searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        return sendEnvelope(res, await resolved.runtime.readWiki({ target: url.searchParams.get('target') ?? undefined, objectId: url.searchParams.get('object_id') ?? undefined, object: url.searchParams.get('object') ?? undefined,
+          actionId: url.searchParams.get('action_id') ?? undefined, sceneId: url.searchParams.get('scene_id') ?? undefined, wikiKind: (url.searchParams.get('wiki_kind') ?? undefined) as 'fact' | 'way' | undefined,
+          includeContent: url.searchParams.has('include_content') ? url.searchParams.get('include_content') === 'true' : undefined,
+          ...Object.fromEntries([['max_chars', 'maxChars'], ['content_offset', 'contentOffset'], ['content_max_chars', 'contentMaxChars'], ['expected_version', 'expectedVersion'], ['link_limit', 'linkLimit'], ['link_offset', 'linkOffset']].filter(([key]) => url.searchParams.has(key!)).map(([key, field]) => [field, Number(url.searchParams.get(key!))])),
+          limit: url.searchParams.has('limit') ? Number(url.searchParams.get('limit')) : undefined, offset: url.searchParams.has('offset') ? Number(url.searchParams.get('offset')) : undefined }))
+      } },
       { kind: 'exact' as const, path: '/knowledge/cases', handler: async (req: IncomingMessage, res: ServerResponse) => {
         if (req.method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', 'Case 只接受 GET'))
         const resolved = resolveBase(query(req).searchParams.get('kb'))
@@ -1173,6 +1157,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           (url.searchParams.get('mode') ?? undefined) as RecallMode | undefined,
           lineageFromUrl(url),
           {
+            ...scopeOf(Object.fromEntries(['object_id', 'action_id', 'scene_id', 'wiki_kind'].filter(key => url.searchParams.has(key)).map(key => [key, url.searchParams.get(key)]))),
             ...(topN === null ? {} : { contextTopN: Number(topN) }),
             ...(rerankParam === null ? {} : { rerank: rerankParam !== 'false' && rerankParam !== '0' }),
             ...(url.searchParams.get('context_max_chars') === null ? {} : { contextMaxChars: Number(url.searchParams.get('context_max_chars')) }),
@@ -1255,7 +1240,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           const pipeline = await resolved.runtime.pipeline()
           const limit = Math.min(100, Math.max(1, Number(url.searchParams.get('limit')) || 20))
           const offset = Math.max(0, Number(url.searchParams.get('offset')) || 0)
-          return send(res, 200, success({ ...pipeline.store.tasks(limit, offset), extractions: await resolved.runtime.listExtractionRuns({ limit, offset }) }))
+          return send(res, 200, success({ ...pipeline.store.tasks(limit, offset), activeTasks: pipeline.store.activeTasks(), extractions: await resolved.runtime.listExtractionRuns({ limit, offset }) }))
         } catch (cause) { return send(res, 400, envelopeError('PIPELINE_HISTORY_FAILED', cause instanceof Error ? cause.message : String(cause))) }
       } },
       { kind: 'exact' as const, path: '/knowledge/pipeline-task', handler: async (req: IncomingMessage, res: ServerResponse) => {
@@ -1270,6 +1255,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           if (!task) return send(res, 404, envelopeError('PIPELINE_NOT_FOUND', '任务不存在'))
           if (req.method === 'GET') return send(res, 200, success({ task, ...pipeline.store.events(id, Math.max(0, Number(url.searchParams.get('after')) || 0)) }))
           if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '任务只接受 GET 或 POST'))
+          if (body.action === 'retry' && PIPELINE_ACTIVE_STATES.includes(task.state)) throw new Error('任务仍在运行，请先停止或等待完成')
           if (body.action === 'retry') return send(res, 202, success({ task: pipeline.start(task.stage, { ...task.selection, force: false }).task }))
           if (!['pause', 'resume', 'cancel'].includes(body.action)) throw new Error('不支持的任务操作')
           return send(res, 200, success({ task: pipeline.control(id, body.action) }))
@@ -1362,8 +1348,13 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             sources: (Array.isArray(body.sources) ? body.sources : []).map((item: Record<string, unknown>) => ({
               ...(item?.title ? { title: String(item.title) } : {}),
               content: item?.content as string,
+              ...(item?.source_id ? { sourceId: String(item.source_id) } : {}),
+              ...(item?.source_url === undefined ? {} : { sourceUrl: item.source_url }),
+              ...(item?.source_identity === undefined ? {} : { sourceIdentity: item.source_identity }),
+              ...(item?.expected_version === undefined ? {} : { expectedVersion: item.expected_version }),
               ...(item?.external_id ? { externalId: String(item.external_id) } : {}),
               ...(item?.metadata && typeof item.metadata === 'object' ? { metadata: item.metadata as Record<string, unknown> } : {}),
+              ...(item?.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}),
             })),
             compile: body.compile === true,
             lineage: lineageOf(body),
@@ -1378,12 +1369,16 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             const body = await readBody(req, 1_200_000)
             const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'))
             if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
-            return send(res, 200, await resolved.runtime.addSource({ title: body.title, content: body.content, externalId: body.external_id, metadata: body.metadata, sourceId: body.source_id, ...(body.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}), lineage: lineageOf(body) }))
+            return send(res, 200, await resolved.runtime.addSource({ title: body.title, content: body.content, externalId: body.external_id, metadata: body.metadata, sourceId: body.source_id, sourceUrl: body.source_url, sourceIdentity: body.source_identity, expectedVersion: body.expected_version, ...(body.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}), lineage: lineageOf(body) }))
           }
           if (req.method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET 或 POST'))
           const url = query(req)
           const resolved = resolveBase(url.searchParams.get('kb'))
           if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+          if (url.searchParams.has('source_id')) return sendEnvelope(res, await resolved.runtime.readSource({ sourceId: url.searchParams.get('source_id')!,
+            contentHash: url.searchParams.get('content_hash') ?? undefined, quote: url.searchParams.get('quote') ?? undefined,
+            ...Object.fromEntries([['version', 'version'], ['start', 'start'], ['end', 'end'], ['offset', 'offset'], ['max_chars', 'maxChars']].filter(([key]) => url.searchParams.has(key!)).map(([key, field]) => [field, Number(url.searchParams.get(key!))])),
+          }, lineageFromUrl(url)))
           return send(res, 200, await resolved.runtime.sourceTruth(
             url.searchParams.get('query') ?? '',
             Number(url.searchParams.get('limit') ?? 20) || 20,
@@ -1964,9 +1959,8 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
            * ```
            * /knowledge/pages/trial?kb=<知识库 id>     抽取试跑
            * /knowledge/pages/run?kb=<库 id>&run=<轨迹 id>   一次抽取的完整报告
-           * /knowledge/pages/tasks?kb=<知识库 id>    抽取任务
+           * /knowledge/pages/tasks?kb=<知识库 id>    知识处理与编译设置
            * /knowledge/pages/help/compile             编译链路
-           * /knowledge/pages/help/intent              意图的逻辑
            * /knowledge/pages/help/overview?node=...   五个 Tab 的方案说明
            * ```
            *
@@ -1992,9 +1986,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
               : rest[1] === 'run'
                 ? '抽取轨迹'
                 : rest[1] === 'tasks'
-                  ? '抽取任务'
-                : rest[1] === 'help' && rest[2] === 'intent'
-                  ? '意图的逻辑'
+                  ? '知识处理'
                   : rest[1] === 'help' && rest[2] === 'compile'
                     ? '编译链路'
                     : rest[1] === 'help' && rest[2] === 'overview' ? 'Agent 方案说明' : '整页'
@@ -2028,12 +2020,14 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             if (rest.length === 2) {
               if (method === 'PATCH') {
                 const body = await readBody(req)
+                if (body.extractionTimeoutMinutes !== undefined && !isExtractionTimeoutMinutes(body.extractionTimeoutMinutes)) return send(res, 400, envelopeError('EXTRACTION_TIMEOUT_INVALID', '文档抽取时限只能选择 30、60 或 100 分钟，最大 100 分钟。'))
                 if (body.compileModel && typeof body.compileModel === 'object') {
                   const selection = body.compileModel as CompileModelSelection
                   const catalog = await compileModelCatalog(baseId)
                   const provider = selection.mode === 'fixed' ? selection.provider : catalog.default.provider
                   const model = selection.mode === 'fixed' ? selection.model : catalog.default.model
                   if (selection.mode !== 'fixed' && selection.mode !== 'default') return send(res, 400, envelopeError('MODEL_INVALID', '请选择跟随默认或固定模型'))
+                  if (selection.maxTokens !== undefined && (!Number.isSafeInteger(selection.maxTokens) || selection.maxTokens <= 0)) return send(res, 400, envelopeError('MODEL_INVALID', '单次最大输出必须是正整数 token；留空表示跟随模型默认。'))
                   if (selection.mode === 'fixed' && (!provider || !model)) return send(res, 400, envelopeError('MODEL_INVALID', '固定模型需要 provider 和 model'))
                   const llm = ctx.get('llm')
                   if (provider && model && llm?.resolveCallConfig) {
@@ -2041,7 +2035,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
                       const info = selection.reasoningEffort ? await llm.resolveModelInfo(provider, model) : undefined
                       const effort = info?.reasoning?.efforts.find(item => item.id === selection.reasoningEffort)
                       if (selection.reasoningEffort && !effort) throw new Error('所选模型不支持这个思考强度，请重新选择')
-                      await llm.resolveCallConfig({ provider, model, ...(effort ? { reasoningEffort: effort.id } : {}) })
+                      await llm.resolveCallConfig({ provider, model, ...(effort ? { reasoningEffort: effort.id } : {}), ...(selection.maxTokens !== undefined ? { maxTokens: selection.maxTokens } : {}) })
                     }
                     catch (cause) { return send(res, 400, envelopeError('MODEL_INVALID', cause instanceof Error ? cause.message : String(cause))) }
                   } else if (selection.reasoningEffort) return send(res, 400, envelopeError('MODEL_INVALID', '模型不可用，无法校验思考强度'))
@@ -2049,6 +2043,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
                 const updated = await bases.update(baseId, {
                   name: body.name, description: body.description,
                   extractionNote: typeof body.extractionNote === 'string' ? body.extractionNote : undefined,
+                  extractionTimeoutMinutes: body.extractionTimeoutMinutes,
                   compileModel: body.compileModel && typeof body.compileModel === 'object'
                     ? body.compileModel
                     : undefined,

package/src/knowledge-bases.ts

@@ -31,6 +31,7 @@ import {
 import { defaultKnowledgeRoot, failure, KnowledgeRuntime, success, type KnowledgeRuntimeOptions } from './runtime.js'
 import { defaultAgentRoot, knowledgeBaseRoot, memoryRoot, resourceRoot } from './layout.js'
 import { writeTextAtomic } from './fs-atomic.js'
+import { DEFAULT_EXTRACTION_TIMEOUT_MINUTES, isExtractionTimeoutMinutes, normalizeExtractionTimeoutMinutes, type ExtractionTimeoutMinutes } from './pipeline/types.js'
 
 /** 持久化形态：配置 + 计算字段缓存分区。 */
 interface KnowledgeBaseRecord {
@@ -49,6 +50,7 @@ interface KnowledgeBaseRecord {
   extractionNote: string
   /** 编译模型路由；它是注册表配置，不属于知识正文。 */
   compileModel: CompileModelSelection
+  extractionTimeoutMinutes: ExtractionTimeoutMinutes
   createdAt: string
   updatedAt: string
 }
@@ -120,12 +122,13 @@ function textOr(input: unknown, fallback: string): string {
 function compileModelOf(input: unknown): CompileModelSelection {
   const value = record(input)
   const effort = typeof value.reasoningEffort === 'string' && value.reasoningEffort.trim() ? { reasoningEffort: value.reasoningEffort.trim() } : {}
-  if (value.mode !== 'fixed') return { ...DEFAULT_COMPILE_MODEL, ...effort }
+  const output = typeof value.maxTokens === 'number' && Number.isSafeInteger(value.maxTokens) && value.maxTokens > 0 ? { maxTokens: value.maxTokens } : {}
+  if (value.mode !== 'fixed') return { ...DEFAULT_COMPILE_MODEL, ...effort, ...output }
   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, ...effort }
+  return { mode: 'fixed', provider, model, ...effort, ...output }
 }
 
 function normalizeExt(value: unknown, fallback: string): string {
@@ -140,6 +143,7 @@ function emptyBase(id: string): KnowledgeBase {
     id, name: id, description: '', rootDir: '', isDefault: false,
     extractionNote: '',
     compileModel: { ...DEFAULT_COMPILE_MODEL },
+    extractionTimeoutMinutes: DEFAULT_EXTRACTION_TIMEOUT_MINUTES,
     createdAt: '', updatedAt: '', sourceCount: 0, cardCount: 0, noteCount: 0, buildVersion: 0,
   }
 }
@@ -243,6 +247,7 @@ export class KnowledgeBases {
         // 卡片模板是系统固定契约，不按知识库维护注册表。
         // `KnowledgeRuntime` 自己提供默认模板。
         extractionNote: () => this.extractionNoteOf(base.id),
+        extractionTimeoutMinutes: () => this.extractionTimeoutMinutesOf(base.id),
         // 0032：记忆段跟着**这个库**走，二级用 id。`agentRoot` 没给时（只测注册表
         // 逻辑的单元测试）留空，runtime 会退回知识树里的 `04_memory`。
         ...(this.options.agentRoot ? { memoryRoot: memoryRoot(this.options.agentRoot(), base.id) } : {}),
@@ -338,6 +343,7 @@ export class KnowledgeBases {
       isDefault: false,
       extractionNote: '',
       compileModel: { ...DEFAULT_COMPILE_MODEL },
+      extractionTimeoutMinutes: DEFAULT_EXTRACTION_TIMEOUT_MINUTES,
       createdAt: now,
       updatedAt: now,
     }
@@ -351,14 +357,20 @@ export class KnowledgeBases {
    * 更新名称 / 描述 / 坐标提取备注。
    *
    */
-  async update(id: string, patch: { name?: string; description?: string; extractionNote?: string; compileModel?: CompileModelSelection }): Promise<Envelope<KnowledgeBase>> {
+  async update(id: string, patch: { name?: string; description?: string; extractionNote?: string; compileModel?: CompileModelSelection; extractionTimeoutMinutes?: ExtractionTimeoutMinutes }): Promise<Envelope<KnowledgeBase>> {
     this.ensureLoaded()
     const base = this.records.find(item => item.id === id)
     if (!base) return failure(emptyBase(id), 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
     // 守卫必须基于精确的实时计数，不能用可能过期的缓存。
     await this.refreshOne(base)
     let nextCompileModel = base.compileModel
+    if (patch.extractionTimeoutMinutes !== undefined && !isExtractionTimeoutMinutes(patch.extractionTimeoutMinutes)) {
+      return failure(this.view(base), 'EXTRACTION_TIMEOUT_INVALID', '文档抽取时限只能选择 30、60 或 100 分钟，最大 100 分钟。', false)
+    }
     if (patch.compileModel !== undefined) {
+      if (patch.compileModel.maxTokens !== undefined && (!Number.isSafeInteger(patch.compileModel.maxTokens) || patch.compileModel.maxTokens <= 0)) {
+        return failure(this.view(base), 'COMPILE_MODEL_INVALID', '单次最大输出必须是正整数 token；留空表示跟随模型默认。', false)
+      }
       if (patch.compileModel.mode !== 'default' && patch.compileModel.mode !== 'fixed') {
         return failure(this.view(base), 'COMPILE_MODEL_INVALID', '编译模型 mode 只能是 default 或 fixed', false, '从编译模型选择项中选择“跟随 DSH 默认模型”或一个固定模型。')
       }
@@ -377,6 +389,7 @@ export class KnowledgeBases {
     // 长度上限不是配额，是防呆：这条备注逐字进每一次抽取的提示词，几万字会把文档挤出去。
     if (patch.extractionNote !== undefined) base.extractionNote = String(patch.extractionNote).slice(0, 4000)
     base.compileModel = nextCompileModel
+    if (patch.extractionTimeoutMinutes !== undefined) base.extractionTimeoutMinutes = patch.extractionTimeoutMinutes
     base.updatedAt = new Date().toISOString()
     await this.refreshOne(base)
     await this.persist()
@@ -391,6 +404,10 @@ export class KnowledgeBases {
     this.ensureLoaded()
     return this.records.find(item => item.id === id)?.extractionNote ?? ''
   }
+  extractionTimeoutMinutesOf(id: string): ExtractionTimeoutMinutes {
+    this.ensureLoaded()
+    return normalizeExtractionTimeoutMinutes(this.records.find(item => item.id === id)?.extractionTimeoutMinutes)
+  }
 
   /** 当前知识库的编译模型路由。不存在的库回到默认路由，避免读路径抛错。 */
   compileModelOf(id: string): CompileModelSelection {
@@ -443,6 +460,7 @@ export class KnowledgeBases {
       isDefault: base.isDefault,
       extractionNote: base.extractionNote,
       compileModel: { ...base.compileModel },
+      extractionTimeoutMinutes: base.extractionTimeoutMinutes,
       createdAt: base.createdAt,
       updatedAt: base.updatedAt,
       sourceCount: stats?.sourceCount ?? 0,
@@ -462,6 +480,7 @@ export class KnowledgeBases {
       isDefault: true,
       extractionNote: '',
       compileModel: { ...DEFAULT_COMPILE_MODEL },
+      extractionTimeoutMinutes: DEFAULT_EXTRACTION_TIMEOUT_MINUTES,
       createdAt: now,
       updatedAt: now,
     }
@@ -524,6 +543,7 @@ export class KnowledgeBases {
       // 0068 之前存下来的注册表里没有这个键：算空串，不报错，也不影响别的字段。
       extractionNote: typeof value.extractionNote === 'string' ? value.extractionNote : '',
       compileModel: compileModelOf(value.compileModel),
+      extractionTimeoutMinutes: normalizeExtractionTimeoutMinutes(value.extractionTimeoutMinutes),
       createdAt: typeof value.createdAt === 'string' && value.createdAt ? value.createdAt : now,
       updatedAt: typeof value.updatedAt === 'string' && value.updatedAt ? value.updatedAt : now,
     }