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

package/src/index.ts

@@ -32,6 +32,7 @@ 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 {
   agentLayout, defaultAgentRoot, ensureAgentLayout, intentRoot, knowledgeBaseRoot,
   memoryRoot, presetSourceDir, resourceRegistry, resourceRoot, type AgentLayout,
@@ -474,7 +475,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     }
     const provider = configured.mode === 'fixed' ? configured.provider : defaultProvider
     const model = configured.mode === 'fixed' ? configured.model : defaultModel
-    const effectiveReasoningEffort = configured.mode === 'default' ? reasoningEffort : undefined
+    const effectiveReasoningEffort = configured.reasoningEffort || (configured.mode === 'default' ? reasoningEffort : undefined)
     if (!provider || !model) {
       return { why: `编译模型没有选好（provider=${provider ?? '空'} / model=${model ?? '空'}）` }
     }
@@ -482,7 +483,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
       provider,
       model,
       ...(effectiveReasoningEffort ? { reasoningEffort: effectiveReasoningEffort } : {}),
-      call: async ({ system, prompt, sessionId, onUsage }) => {
+      call: async ({ system, prompt, sessionId, onUsage, onDelta }) => {
         /**
          * 先走 DSH 的公开解析接口，再开始发 prompt。这样固定模型过期、默认模型失效时，
          * 编译会在模型调用边界明确失败，而不是落成一次看似成功的规则抽取。
@@ -491,7 +492,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           try {
             await llm.resolveCallConfig({
               provider, model,
-              ...(configured.mode === 'default' && reasoningEffort ? { reasoningEffort } : {}),
+              ...(effectiveReasoningEffort ? { reasoningEffort: effectiveReasoningEffort } : {}),
             })
           } catch (cause) {
             const detail = cause instanceof Error ? cause.message : String(cause)
@@ -513,13 +514,13 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           // 而不是留空 —— 留空会在 OpenCode 路由上 400。
           sessionId: sessionId ?? 'knowledge:default',
         })
-        return collectModelText(llm.stream(request) as AsyncIterable<never>, onUsage)
+        return collectModelText(llm.stream(request) as AsyncIterable<never>, onUsage, onDelta)
       },
     }
   }
   let environment: KnowledgeEnvironment
   const runtimeOptions = (): KnowledgeRuntimeOptions => ({
-    environmentGuard: () => environment.requireReady(),
+    environmentGuard: kind => environment.requireReady(kind),
     // 0029：家当目录。配置里三个路径为空时，运行时从这里解析模型与解释器。
     resourceRoot: resourceRoot(config.agentRoot),
     // 0032：记忆段。默认库的记忆落在 `<agentRoot>/memory/default`，与知识树平级。
@@ -556,7 +557,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     // 0044：非默认库的 runtime 也要拿到模型接缝。只传 `config` 不够 —— 默认库走上面
     // 那个 `new KnowledgeRuntime(... runtimeOptions())`，别的库走注册表这条支路，
     // 两边必须都带上，否则「新建一个库 → 导入文档」静默变成规则抽取。
-  runtimeOptions: () => ({ resourceRoot: resourceRoot(config.agentRoot), modelSeam: modelSeamFor, environmentGuard: () => environment.requireReady() }),
+  runtimeOptions: () => ({ resourceRoot: resourceRoot(config.agentRoot), modelSeam: modelSeamFor, environmentGuard: kind => environment.requireReady(kind) }),
   })
   compileModelForBase = id => bases.compileModelOf(id)
   runtime.baseId = bases.defaultId
@@ -566,12 +567,35 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     snapshot: () => ({ config: runtime.config, paths: runtime.resourcePaths() }),
     probe: kind => runtime.environmentProbe(kind),
     reload: () => { runtime.reloadResources(); bases.reloadResources() },
+    activateSelection: async () => {
+      const keys = ['embeddingProvider', 'embeddingModel', 'rerankProvider', 'rerankModel'] as const
+      const previous = Object.fromEntries(keys.map(key => [key, config[key]]))
+      const managed = { embeddingProvider: 'wemm-python', embeddingModel: '', rerankProvider: 'bert-python', rerankModel: '' }
+      const write = async (values: Record<string, unknown>): Promise<void> => {
+        const group = pluginConfig.knowledge as unknown as Record<string, unknown> | undefined
+        if (!group) throw new Error('模型设置不可写')
+        for (const key of keys) {
+          const reference = group[key] as { write?: (value: unknown) => unknown } | undefined
+          if (reference && typeof reference.write === 'function') await reference.write(values[key])
+          else group[key] = values[key]
+        }
+        config = normalizeKnowledge(pluginConfig.knowledge)
+        runtime.updateConfig(config); bases.updateRuntimeConfig(config)
+      }
+      try { await write(managed) } catch (cause) { await write(previous); throw cause }
+      return () => {
+        const current = normalizeKnowledge(pluginConfig.knowledge)
+        // A later manual setting change belongs to the user and must survive rollback.
+        const restored = Object.fromEntries(keys.map(key => [key, current[key] === managed[key] ? previous[key] : current[key]]))
+        return write(restored)
+      }
+    },
   })
-  // Startup checks imports and resource files; model inference runs on demand.
-  void environment.check(false).catch(() => undefined)
+  // 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 }
-  const compileModelCatalog = async (kbId: string): Promise<{
+  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 } }
+  const compileModelCatalog = async (kbId: string, queryModelRoute: { provider?: string; model?: string } = {}): Promise<{
     selection: CompileModelSelection
     default: { provider?: string; model?: string; reasoningEffort?: string; available: boolean }
     models: CompileModelCatalogItem[]
@@ -582,8 +606,10 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     const defaultRoute = service?.currentSelection?.() ?? {}
     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'] }>
     } | undefined
-    const providers = [...new Set([defaultRoute.provider, compileModelForBase(kbId).provider].filter((value): value is string => Boolean(value)))]
+    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[] = []
     const failures: string[] = []
     if (!llm?.listModels) {
@@ -610,6 +636,17 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     }
 
     const selection = compileModelForBase(kbId)
+    const effortProvider = selection.mode === 'fixed' ? selection.provider : defaultRoute.provider
+    const effortModel = selection.mode === 'fixed' ? selection.model : defaultRoute.model
+    const requestedProvider = queryModelRoute.provider || effortProvider
+    const requestedModel = queryModelRoute.model || effortModel
+    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 }
+        catch (cause) { failures.push(`思考强度目录：${cause instanceof Error ? cause.message : String(cause)}`) }
+      }
+    }
     const selected = selection.mode === 'fixed' && selection.provider && selection.model
       ? models.find(item => item.provider === selection.provider && item.id === selection.model)
       : undefined
@@ -777,23 +814,56 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
   applyIntent(ctx, { intentRoot: () => intentRoot(config.agentRoot) })
 
   /**
-   * 需要本轮用户审批的知识写工具。`images.publish` 只写入本地素材目录，按用户要求免审批。
+   * 需要本轮用户审批的知识写工具。`image_publish` 只写入本地素材目录，按用户要求免审批。
    *
    * 0044 换过一批名字：`write_knowledge_card`（只接受已确认提议）退役了，因为正文现在
    * 只读、卡片由编译直接写入；`list_card_proposals` 也退役了，因为待办队列不存在了。
    * 新增的两个是**入库之后**的动作：加备注、review 抬分。
    */
-  const writeTools = new Set(['add_source', 'import_sources', 'propose_wiki_cards', 'annotate_wiki_card', 'review_wiki_card', 'set_knowledge_status', 'rebuild_knowledge', 'record_feedback'])
+  ctx.tools.register(tool('run_knowledge_pipeline', 'Run one independent knowledge stage. Import only saves sources by default. Stages: extract Knowledge/Event, normalize existing results, materialize selected complete card groups, build retrieval indexes, or all. Returns a durable background task; inspect it with get_knowledge_pipeline.', {
+    stage: { type: 'string', required: true, enum: ['extract', 'normalize', 'materialize', 'build', 'all'] },
+    kb: { type: 'string' }, source_ids: { type: 'array', description: 'Optional explicit source IDs; omit for all sources. An empty selection is rejected.' },
+    group_keys: { type: 'array', description: 'Optional full card group keys returned by get_knowledge_pipeline.' }, force: { type: 'boolean', description: 'Explicitly rerun the selected stage despite an unchanged checkpoint.' },
+  }, async args => withRuntime(args.kb, async target => {
+    const pipeline = await target.pipeline()
+    const { task } = pipeline.start(args.stage as PipelineStage, { sourceIds: args.source_ids, groupKeys: args.group_keys, force: args.force === true })
+    return success({ task, url: `/knowledge/pages/tasks?kb=${encodeURIComponent(target.baseId)}&task=${encodeURIComponent(task.id)}` })
+  })))
+  ctx.tools.register(tool('get_knowledge_pipeline', 'Read pending stages, materializable card groups, persistent task history, or incremental public model output. Use the returned next cursor as after on the next call.', {
+    kb: { type: 'string' }, task_id: { type: 'string' }, after: { type: 'integer' },
+  }, async args => withRuntime(args.kb, async (target): Promise<Envelope<Record<string, unknown>>> => {
+    const pipeline = await target.pipeline()
+    return args.task_id
+      ? success({ task: pipeline.store.task(args.task_id) ?? null, ...pipeline.store.events(args.task_id, Math.max(0, args.after ?? 0)) })
+      : success({ status: await target.pipelineStatus(), ...pipeline.store.tasks() })
+  })))
+  const writeTools = new Set(['add_source', 'import_sources', 'propose_wiki_cards', 'annotate_wiki_card', 'review_wiki_card', 'set_knowledge_status', 'rebuild_knowledge', 'run_knowledge_pipeline', 'record_feedback'])
   ctx.on('tools/pre-execute', (exec, next): Promise<PreToolDecision> => {
     if (writeTools.has(exec.name)) return Promise.resolve({ kind: 'ask', reason: '该操作会写入 Tita Knowledge Store，需要本轮用户审批。' })
     return next()
   })
-  ctx.tools.register(tool('recall_knowledge', 'Recall compiled knowledge through keyword and vector candidate routes, rerank wiki sections, then return the top wiki cards with their matched sections and provenance.', { 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 } : {}) })), {
+  ctx.tools.register(tool('recall_knowledge', 'Recall compiled Knowledge through keyword and vector candidate routes, rerank WikiCard sections, then return cards with matched sections, provenance, and Event reference IDs. Use get_knowledge_events to read referenced Events.', { 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),
   }))
+  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('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))))
@@ -824,30 +894,28 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     })),
   })))
 
-  ctx.tools.register(tool(
-    'images.publish',
-    '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.',
-    {
-      file_path: { type: 'string', description: '宿主可读取的本地图片文件路径；与 content_base64 二选一' },
-      content_base64: { type: 'string', description: '图片的标准 Base64，或 data:image/...;base64,...；与 file_path 二选一' },
-      filename: { type: 'string', description: '可选文件名；默认使用 file_path 的文件名，Base64 输入默认 image-<hash>.<ext>' },
-      mime_type: { type: 'string', description: '可选 MIME 类型；必须与图片二进制内容一致' },
-      kb: { type: 'string', description: '知识库 id；省略时写入默认库' },
-    },
-    async args => withRuntime(args.kb, async target => {
-      try {
-        return success(await publishKnowledgeImage(target.rootDir, target.baseId, {
-          filePath: args.file_path,
-          contentBase64: args.content_base64,
-          filename: args.filename,
-          mimeType: args.mime_type,
-        }))
-      } catch (cause) {
-        if (cause instanceof ImagePublishError) return failure({}, cause.code, cause.message, false, cause.suggestion)
-        return failure({}, 'IMAGE_PUBLISH_FAILED', `图片写入失败：${cause instanceof Error ? cause.message : String(cause)}`, true)
-      }
-    }),
-  ))
+  const imagePublishParameters = {
+    file_path: { type: 'string', description: '宿主可读取的本地图片文件路径；与 content_base64 二选一' },
+    content_base64: { type: 'string', description: '图片的标准 Base64，或 data:image/...;base64,...；与 file_path 二选一' },
+    filename: { type: 'string', description: '可选文件名；默认使用 file_path 的文件名，Base64 输入默认 image-<hash>.<ext>' },
+    mime_type: { type: 'string', description: '可选 MIME 类型；必须与图片二进制内容一致' },
+    kb: { type: 'string', description: '知识库 id；省略时写入默认库' },
+  }
+  const publishImage = async (args: Args) => withRuntime(args.kb, async target => {
+    try {
+      return success(await publishKnowledgeImage(target.rootDir, target.baseId, {
+        filePath: args.file_path,
+        contentBase64: args.content_base64,
+        filename: args.filename,
+        mimeType: args.mime_type,
+      }))
+    } catch (cause) {
+      if (cause instanceof ImagePublishError) return failure({}, cause.code, cause.message, false, cause.suggestion)
+      return failure({}, 'IMAGE_PUBLISH_FAILED', `图片写入失败：${cause instanceof Error ? cause.message : String(cause)}`, true)
+    }
+  })
+  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) })), {
     call: addSourceCallView,
@@ -868,7 +936,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
    * `compile` 默认开：批量导入的意图几乎总是「进来就能用」。关掉它的场景是「先全部
    * 落盘、稍后统一编译」——那时卡片还没生成，工具返回里会明说 `compile: null`。
    */
-  ctx.tools.register(tool('import_sources', 'Import many SourceRaw documents and compile them into Wiki cards in ONE call (one approval, one compile, per-source failures reported instead of aborting the batch). Use this instead of calling add_source repeatedly. 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: '默认 true：写入后立刻编译成 WikiCard。false 表示只落盘' }, 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 } : {}) })), ...(args.compile === false ? { compile: false } : {}), 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: `来源数组，每项 { 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) }))
   /**
    * `propose_wiki_cards` —— 把一批卡片**直接写进 `02_wiki`**（工具名不变，语义在 0044 改了）。
    *
@@ -924,7 +992,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     lineage: lineageOf(args, exec),
   }))))
   ctx.tools.register(tool('set_knowledge_status', 'Change a Wiki card status. This status belongs to the Card lifecycle; it does not change Knowledge truth status. problem requires problem_note and recovery must pass through unreviewed. DSH requests one user approval before execution.', { entity_id: { type: 'string', required: true }, status: { type: 'string', enum: ['unreviewed', 'draft', 'reviewed', 'active', 'deprecated', 'problem'], required: true }, problem_note: { type: 'string' }, 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.setStatus(args.entity_id, args.status as CardStatus, args.problem_note, lineageOf(args, exec)))))
-  ctx.tools.register(tool('rebuild_knowledge', 'Rebuild schema/wiki/compiled knowledge indexes. DSH requests one user approval before execution.', { only: { type: 'string', enum: ['all', 'schema', 'wiki', 'embeddings'] }, 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.rebuild(args.only ?? 'all', lineageOf(args, exec))), {
+  ctx.tools.register(tool('rebuild_knowledge', 'Rebuild schema/wiki/compiled knowledge indexes from saved cards without document extraction. Use run_knowledge_pipeline for extract, normalize, materialize, or the full chain. DSH requests one user approval before execution.', { only: { type: 'string', enum: ['all', 'schema', 'wiki', 'embeddings'] }, 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.rebuild(args.only ?? 'all', lineageOf(args, exec), { extract: false })), {
     call: rebuildCallView,
     meta: (args, value) => rebuildMetaOf(args?.only ?? 'all', dataOf(value)),
     result: resultViewOf(rebuildResultMarkdown),
@@ -1004,7 +1072,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         const url = query(req)
         const id = kbIdOf(url.searchParams.get('kb'))
         if (!bases.get(id)) return sendEnvelope(res, failure({}, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true, '先 GET /knowledge/bases 拿到可用 id。'))
-        return send(res, 200, success(await compileModelCatalog(id)))
+        return send(res, 200, success(await compileModelCatalog(id, { provider: url.searchParams.get('provider') ?? undefined, model: url.searchParams.get('model') ?? undefined })))
       } },
       { kind: 'exact' as const, path: '/knowledge/stats', handler: async (req: IncomingMessage, res: ServerResponse) => {
         const resolved = resolveBase(query(req).searchParams.get('kb'))
@@ -1093,6 +1161,47 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
         return send(res, 200, success({ progress: resolved.runtime.compileProgressView(url.searchParams.get('runId') ?? undefined) }))
       } },
+      { kind: 'exact' as const, path: '/knowledge/pipeline', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        try {
+          const body = req.method === 'POST' ? await readBody(req, 100_000) : {}
+          const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'))
+          if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+          if (req.method === 'GET') return send(res, 200, success(await resolved.runtime.pipelineStatus()))
+          if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '知识处理只接受 GET 或 POST'))
+          const pipeline = await resolved.runtime.pipeline()
+          const started = pipeline.start(body.stage as PipelineStage, { sourceIds: body.sourceIds, groupKeys: body.groupKeys, force: body.force === true })
+          return send(res, 202, success({ task: started.task }))
+        } catch (cause) { return send(res, 400, envelopeError('PIPELINE_INVALID', cause instanceof Error ? cause.message : String(cause))) }
+      } },
+      { kind: 'exact' as const, path: '/knowledge/pipeline-tasks', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        try {
+          if (req.method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '任务历史只接受 GET'))
+          const url = query(req)
+          const resolved = resolveBase(url.searchParams.get('kb'))
+          if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+          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 }) }))
+        } 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) => {
+        try {
+          const url = query(req)
+          const body = req.method === 'POST' ? await readBody(req, 20_000) : {}
+          const resolved = resolveBase(body.kb ?? url.searchParams.get('kb'))
+          if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+          const pipeline = await resolved.runtime.pipeline()
+          const id = typeof body.id === 'string' ? body.id : url.searchParams.get('id') ?? ''
+          const task = pipeline.store.task(id)
+          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') 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) }))
+        } catch (cause) { return send(res, 409, envelopeError('PIPELINE_TASK_REJECTED', cause instanceof Error ? cause.message : String(cause))) }
+      } },
       { kind: 'exact' as const, path: '/knowledge/extraction-tasks', handler: async (req: IncomingMessage, res: ServerResponse) => {
         if (req.method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '抽取任务只接受 GET'))
         const resolved = resolveBase(query(req).searchParams.get('kb'))
@@ -1156,7 +1265,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'))
           if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
           return send(res, 202, success(resolved.runtime.startCompile(body.only ?? 'all', lineageOf(body), {
-            ...(typeof body.extract === 'boolean' ? { extract: body.extract } : {}),
+            extract: body.extract === true,
             ...(body.forceExtract === true ? { forceExtract: true } : {}),
           })))
         } catch (cause) {
@@ -1183,7 +1292,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
               ...(item?.external_id ? { externalId: String(item.external_id) } : {}),
               ...(item?.metadata && typeof item.metadata === 'object' ? { metadata: item.metadata as Record<string, unknown> } : {}),
             })),
-            ...(body.compile === false ? { compile: false } : {}),
+            compile: body.compile === true,
             lineage: lineageOf(body),
           }))
         } catch (cause) {
@@ -1276,7 +1385,8 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
            * 任何一条轨迹 —— 「这个实体是哪次抽出来的」就答不上了。
            */
           const runId = extractionRunId()
-          const seam = modelSeamFor()
+          const seam = modelSeamFor(resolved.runtime.baseId)
+          const draft = await (await resolved.runtime.axisRegistry())?.draft()
           const axesBlock = await resolved.runtime.axisPromptBlockView()
           const note = resolved.runtime.extractionNote()
           const report = await runWikiTrial({
@@ -1286,7 +1396,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             ...(typeof body.subject === 'string' && body.subject.trim() ? { subject: body.subject.trim() } : {}),
             /** 与编译相同：先查注册表，再把有候选的坐标合并成一次模型补判。 */
             resolveAxisSet: axes => resolved.runtime.resolveTrialAxisSet({
-              axes,
+              registry: draft?.registry, axes,
               axesBlock,
               runId,
               call: seam.call,
@@ -1309,7 +1419,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             },
             ...('call' in seam ? { call: seam.call } : {}),
             ...('why' in seam ? { callWhy: seam.why } : {}),
-          })
+          }).finally(() => draft?.close())
           const summary = trialSummary(report)
 
           /**
@@ -1325,24 +1435,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             lineage: lineageOf(body),
           })
 
-          /**
-           * 把这次抽出来的 Knowledge 收进真源（0063 §2）。
-           *
-           * **只在跑一份已入库的文档时收。** 理由有两条：来源要指得回一份**真实的**
-           * 文档（临时正文的 `documentId` 是一个标题字符串，存下来就是悬空引用）；
-           * 而「这条知识是哪份文档说的」正是它可验证的前提。
-           *
-           * **只收引文核对得上的那些。** 引文对不上原文 = 模型改写了，那条判断不是从
-           * 原文推出来的（§5.7 的引文核验）。把它当知识存进真源，等于让一句编出来的话
-           * 看起来像有出处 —— 而报告里已经把它报成例外了，那里才是它该待的地方。
-           */
-          const ingest = docId
-            ? await resolved.runtime.ingestTrialKnowledge({
-              runId, knowledge: report.knowledge,
-              objects: report.objects, actions: report.actions, scenes: report.scenes,
-            })
-            : { saved: 0, merged: 0, skipped: 0 }
-          return send(res, 200, success({ ...report, summary, run, ingest }))
+          return send(res, 200, success({ ...report, summary, run }))
         } catch (cause) {
           return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)))
         }
@@ -1570,7 +1663,10 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         return send(res, 400, envelopeError('REQUEST_INVALID', `不认识的 action: ${action || '（空）'}`))
       } },
       /**
-       * 抽取轨迹（`extraction_run`）：按文档列、按 id 读全文。
+       * 轨迹（`extraction_run`）：按文档或阶段列、按 id 读全文。
+       *
+       * 2026-10-18 起三段共用这张表（`stage` 列：`extract` / `normalize` / `materialize`）。
+       * `stage` 省略 = 三段一起 —— 面板里那份「这份文档的轨迹」就是这么读的。
        *
        * 列表**不返回报告本体** —— 一条报告几十到几百 KB，翻一页列表不该按全文付费。
        * 点开某一条走 `/knowledge/extraction-run?id=…`（单独一条路由，不是路径参数：
@@ -1582,8 +1678,11 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         const resolved = resolveBase(url.searchParams.get('kb'))
         if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
         const docId = url.searchParams.get('doc_id')
+        const stageParam = url.searchParams.get('stage')
+        const stage = stageParam === 'extract' || stageParam === 'normalize' || stageParam === 'materialize' ? stageParam : undefined
         const page = await resolved.runtime.listExtractionRuns({
           ...(docId === null ? {} : { docId }),
+          ...(stage === undefined ? {} : { stage }),
           limit: clampInt(url.searchParams.get('limit'), 20, 1, 100),
           offset: clampInt(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER),
         })
@@ -1696,10 +1795,8 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         return send(res, 200, success({ cases: (await storeOf(resolved.runtime).snapshot()).cases }))
       } },
       /**
-       * 一次排查结束：落一条 `agent_diagnosis_case` 的 SourceRaw，并写入一张案例卡片。
-       *
-       * 0044：卡片不再只提议 —— 它直接入库并标成 `unreviewed`。响应给 `sourceId` 与
-       * `entityId`，界面据此说清「记录留下了，卡片也建了，等人 review」。
+       * 一次排查结束只落一条 SourceRaw。Case 视图从记录派生；Knowledge / Event 的抽取、
+       * 归一和 WikiCard 物化由知识处理阶段分别执行。
        */
       { kind: 'exact' as const, path: '/diagnosis/run', handler: async (req: IncomingMessage, res: ServerResponse) => {
         if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 endpoint 只接受 POST'))
@@ -1712,9 +1809,9 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         }
         const outcome = await storeOf(resolved.runtime).recordRun(record)
         if (outcome.problems.length > 0 && outcome.sourceId === undefined) {
-          return send(res, 200, failure({ sourceId: '', entityId: '' }, 'RUN_WRITE_FAILED', outcome.problems.join('；'), true))
+          return send(res, 200, failure({ sourceId: '' }, 'RUN_WRITE_FAILED', outcome.problems.join('；'), true))
         }
-        return send(res, 200, success({ sourceId: outcome.sourceId ?? '', entityId: outcome.entityId ?? '' }, outcome.problems))
+        return send(res, 200, success({ sourceId: outcome.sourceId ?? '' }, outcome.problems))
       } },
       /**
        * 入库之后的两个人工动作（0044）：加备注、review 抬分。
@@ -1862,6 +1959,24 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             if (rest.length === 2) {
               if (method === 'PATCH') {
                 const body = await readBody(req)
+                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.mode === 'fixed' && (!provider || !model)) return send(res, 400, envelopeError('MODEL_INVALID', '固定模型需要 provider 和 model'))
+                  const llm = ctx.get('llm')
+                  if (provider && model && llm?.resolveCallConfig) {
+                    try {
+                      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 } : {}) })
+                    }
+                    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', '模型不可用，无法校验思考强度'))
+                }
                 const updated = await bases.update(baseId, {
                   name: body.name, description: body.description,
                   extractionNote: typeof body.extractionNote === 'string' ? body.extractionNote : undefined,
@@ -2083,6 +2198,26 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
               let documents = await resolved.runtime.listDocuments()
               const search = (url.searchParams.get('query') ?? '').trim().toLocaleLowerCase()
               if (search) documents = documents.filter(item => `${item.docId}\n${item.title}\n${item.externalId}`.toLocaleLowerCase().includes(search))
+              /**
+               * 文件类型的计数对着**搜索之后、类型筛选之前**的集合算。
+               *
+               * 下拉要能切换类型，所以每个类型的数量必须是「当前搜索下有多少份」，
+               * 而不是「当前这一页里有多少份」—— 后者会让选项随翻页变来变去。
+               */
+              const extCounts: Record<string, number> = {}
+              for (const item of documents) {
+                const key = item.ext || '—'
+                extCounts[key] = (extCounts[key] ?? 0) + 1
+              }
+              /**
+               * 文件类型筛选**在服务端**做（0070）。
+               *
+               * 原来是「客户端取前 500 份、再在这一页里筛」：超过 500 份的库，第 501 份起
+               * 在面板上根本不可达，而表头把这种截断显示成「筛出 500 / 600 个」——
+               * 读起来像用户自己开了筛选。既然这里已经支持 `offset`，筛选就该和分页同层。
+               */
+              const ext = (url.searchParams.get('ext') ?? '').trim()
+              if (ext) documents = documents.filter(item => item.ext === ext)
               const total = documents.length
               const offset = clampInt(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER)
               const limit = clampInt(url.searchParams.get('limit'), 50, 1, 500)
@@ -2093,7 +2228,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
                * 两件事。放成并列的一张表，前端按 `docId` 查，文档类型不用为审计字段让步。
                */
               const extractionRuns = await resolved.runtime.extractionRunCounts()
-              return send(res, 200, success({ documents: documents.slice(offset, offset + limit), total, extractionRuns }))
+              return send(res, 200, success({ documents: documents.slice(offset, offset + limit), total, extCounts, extractionRuns }))
             }
             const docId = rest[1]!
             const resolved = resolveBase(kbParam)

package/src/intent/scope.ts

@@ -48,6 +48,7 @@ const DATA_PREDICATE_IDS = new Set([
 /** 发生实际数据工作的工具。意图工具本身不在这里，避免自调用激活门控。 */
 const DATA_TOOL_NAMES = new Set([
   'recall_knowledge',
+  'get_knowledge_events',
   'query_knowledge_graph',
   'query_source_truth',
   'list_knowledge_bases',

package/src/intent/tools.ts

@@ -91,6 +91,40 @@ export function sessionKeyOf(exec?: ToolRunContext): string | undefined {
   return typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : undefined
 }
 
+/**
+ * 这个会话是不是**子代理**。
+ *
+ * 子代理会加入父会话的组合，所以它会继承到 `intent_*` 两个工具。而意图记录描述的是
+ * 「用户在跟 Agent 要什么」：子代理做的是被拆出来的一个片段，它记一条只会污染任务树。
+ *
+ * 这条规矩原来写在 preset 的 delegation 行上（`toolFilter: { deny: [...] }`）。DSH 0.1.8
+ * 起 `toolFilter`（与 `persona`）**不再被 `dsh-tool-subagent` 接受** —— 带上它的 preset
+ * 直接挂载失败，整个组合都不会生效。平台给的替代是「在 Agent Preset 里配好工具，再用
+ * `agentPreset` 选中它」，而那**只对 spawn provider 有效**：fork / codex / claude-code
+ * 的子会话按定义继承父会话的组合，没有选择余地（`inheritsParentContext` 直接拒绝）。
+ *
+ * 所以判据搬进工具本身：看会话头，与「谁把子会话拉起来的」无关。四个 provider 一视同仁，
+ * 也不会再出现「新增一个 delegation 行忘了 deny」这种漏法。
+ *
+ * 判据取两个字段：`origin === 'subagent'` 是产品分类，`delegationDepth > 0` 是递归深度
+ * （持久化过，重启后仍然成立）。任一条成立就算子会话。
+ */
+export function isSubagentSession(exec?: ToolRunContext): boolean {
+  const header = exec?.agent?.session?.header
+  if (!header) return false
+  if (header.origin === 'subagent') return true
+  return typeof header.delegationDepth === 'number' && header.delegationDepth > 0
+}
+
+/** 子代理调这两个工具时统一回这一条：说清为什么，并给出该走的路。 */
+function subagentRefusal(): unknown {
+  return envelopeFailure({ sessionKey: null }, {
+    code: 'SUBAGENT_NOT_RECORDED',
+    message: '子代理不记录意图：意图描述的是用户与主 Agent 的交互。把要记的内容写进返回结果，由主 Agent 记录。',
+    retryable: false,
+  })
+}
+
 /**
  * 注册两个 `intent_*` 工具，返回一个把两者一起撤掉的 disposer。
  *
@@ -100,11 +134,14 @@ export function sessionKeyOf(exec?: ToolRunContext): string | undefined {
  * 返回 disposer。
  */
 export function registerIntentTools(ctx: { tools: ToolRegistryLike }, host: IntentToolHost): () => void {
-  const disposeRecord: unknown = ctx.tools.register(jsonTool('intent_record', host.routingPrompt(), INTENT_RECORD_PARAMS, (args, exec) => host.record(args, exec)))
+  const disposeRecord: unknown = ctx.tools.register(jsonTool('intent_record', host.routingPrompt(), INTENT_RECORD_PARAMS, (args, exec) => (
+    isSubagentSession(exec) ? subagentRefusal() : host.record(args, exec)
+  )))
   const disposeView: unknown = ctx.tools.register(jsonTool(
     'intent_store_view', 'View recent intent records and the active task ids for the current session.',
     { include_prompt: { type: 'boolean' } },
     (args: { include_prompt?: boolean }, exec) => {
+      if (isSubagentSession(exec)) return subagentRefusal()
       const sessionKey = sessionKeyOf(exec)
       if (!sessionKey) {
         return envelopeFailure({ sessionKey: null }, {