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

package/lib/types/index.js

@@ -1,3 +1,4 @@
+import { newSourceId } from './source-identity.js';
 import { embeddingModel } from './environment/model-catalog.js';
 import { createReadStream } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
@@ -14,21 +15,17 @@ import { KnowledgeEnvironment } from './environment/service.js';
 import { DOC_PAGE_CHARS, DOC_PAGE_CHARS_MAX, documentContentPage } from './document-page.js';
 import { runWikiTrial, trialSummary } from './wiki-trial.js';
 import { extractionRunId } from './extraction-runs.js';
-import { agentLayout, defaultAgentRoot, ensureAgentLayout, intentRoot, knowledgeBaseRoot, memoryRoot, resourceRegistry, resourceRoot, } from './layout.js';
+import { DEFAULT_EXTRACTION_TIMEOUT_MINUTES, PIPELINE_ACTIVE_STATES, isExtractionTimeoutMinutes } from './pipeline/types.js';
+import { agentLayout, defaultAgentRoot, ensureAgentLayout, knowledgeBaseRoot, memoryRoot, resourceRegistry, resourceRoot, } from './layout.js';
 import { PickerError, createDirectory, listDirectory, pickDirectory, pickerKind, pickerOf, } from './directory-picker.js';
 import { KNOWLEDGE_SETTINGS_SCHEMA, SETTINGS_NAMESPACE } from './settings-schema.js';
 import { DEFAULT_KB_ID, KnowledgeBases } from './knowledge-bases.js';
 import { ImagePublishError, publishKnowledgeImage } from './images.js';
 import { applyConvert, CONVERT_SETTINGS_NAMESPACE, CONVERT_SETTINGS_SCHEMA, MOUNT_PATH as CONVERT_MOUNT_PATH, } from './convert/host.js';
-import { applyIntent, INTENT_MOUNT_PATH, INTENT_SERVICE, } 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 };
-export { applyIntent as applyIntentHost, INTENT_MOUNT_PATH, INTENT_SERVICE };
 export const name = 'dsh-data-domain-knowledge';
 /**
  * `settings` 在 0.1.7 之后**不再需要**：设置已经是本 entry 的 config
@@ -51,6 +48,7 @@ export { CONVERT_SETTINGS_SCHEMA };
  */
 import { Config } 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, recallCallView, recallMetaOf, recallResultMarkdown, rebuildCallView, rebuildMetaOf, rebuildResultMarkdown, writeCardsCallView, writeCardsMetaOf, writeCardsResultMarkdown, } from './present.js';
 export { Config };
 /**
@@ -137,7 +135,7 @@ function lineageOf(args, exec) {
     if (sessionId)
         lineage.sessionId = sessionId;
     const fields = [
-        ['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)
@@ -149,7 +147,6 @@ function lineageFromUrl(url) {
     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,
@@ -335,8 +332,7 @@ export function apply(ctx, pluginConfig = {}) {
     /**
      * 这两组的把手，`loader/volatile-update` 时调 `reprocess()` 按新值重灌。
      *
-     * 先声明后赋值：事件只在运行时触发，而两组的装配在下面（`applyConvert` /
-     * `applyIntent`）。
+     * 先声明后赋值：事件只在运行时触发，转换宿主在下面的 `applyConvert` 中装配。
      */
     let convertHost;
     /**
@@ -361,6 +357,7 @@ export function apply(ctx, pluginConfig = {}) {
      */
     /** 注册表在默认 runtime 之后才构造；用一个可替换的读取器避开构造期 TDZ。 */
     let compileModelForBase = () => ({ ...DEFAULT_COMPILE_MODEL });
+    let extractionTimeoutForBase = () => DEFAULT_EXTRACTION_TIMEOUT_MINUTES;
     const modelSeamFor = (kbId = DEFAULT_KB_ID) => {
         /**
          * **只能用 `ctx.get(name)`，不能用属性访问。**
@@ -411,7 +408,9 @@ export function apply(ctx, pluginConfig = {}) {
             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。这样固定模型过期、默认模型失效时，
                  * 编译会在模型调用边界明确失败，而不是落成一次看似成功的规则抽取。
@@ -421,6 +420,7 @@ export function apply(ctx, pluginConfig = {}) {
                         await llm.resolveCallConfig({
                             provider, model,
                             ...(effectiveReasoningEffort ? { reasoningEffort: effectiveReasoningEffort } : {}),
+                            ...(outputLimit !== undefined ? { maxTokens: outputLimit } : {}),
                         });
                     }
                     catch (cause) {
@@ -438,7 +438,7 @@ export function apply(ctx, pluginConfig = {}) {
                  * （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',
@@ -456,12 +456,13 @@ export function apply(ctx, pluginConfig = {}) {
                  * 所以缓存亲和仍然成立。不可重试的错误（凭据、请求体、截断、用户取消）
                  * 由 `isRetryableModelFailure` 放行，不在错的地方多等两分钟。
                  */
-                return callModelWithRetry(onDeltaOfAttempt => collectModelText(llm.stream(request), onUsage, onDeltaOfAttempt), { ...(onDelta ? { onDelta } : {}) });
+                return callModelWithRetry(onDeltaOfAttempt => collectModelText(llm.stream({ ...request, ...(signal ? { signal } : {}) }), onUsage, onDeltaOfAttempt), { ...(onDelta ? { onDelta } : {}), attempts: retryAttempts, signal });
             },
         };
     };
     let environment;
     const runtimeOptions = () => ({
+        extractionTimeoutMinutes: () => extractionTimeoutForBase(DEFAULT_KB_ID),
         environmentGuard: kind => environment.requireReady(kind),
         // 0029：家当目录。配置里三个路径为空时，运行时从这里解析模型与解释器。
         resourceRoot: resourceRoot(config.agentRoot),
@@ -501,6 +502,7 @@ export function apply(ctx, pluginConfig = {}) {
         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({
@@ -587,7 +589,10 @@ export function apply(ctx, pluginConfig = {}) {
             const item = models.find(model => model.provider === requestedProvider && model.id === requestedModel);
             if (item) {
                 try {
-                    item.reasoning = (await llm.resolveModelInfo(requestedProvider, requestedModel)).reasoning;
+                    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)}`);
@@ -725,7 +730,7 @@ export function apply(ctx, pluginConfig = {}) {
         /**
          * 交付物落在**工作项目**下：`<工作区>/output/<日期>/`，不是 Agent 根路径。
          *
-         * 根路径下的四段（知识 / 记忆 / 意图 / 家当）是**这个 Agent 自己的东西**，跨项目
+         * 根路径下的几段（知识 / 记忆 / 家当）是**这个 Agent 自己的东西**，跨项目
          * 累积；交付物是**某个项目的产物**，换一个项目打开就不该再看见。两者判据不同，
          * 所以落点也不同。
          *
@@ -745,26 +750,6 @@ export function apply(ctx, pluginConfig = {}) {
             return target ? { runtime: target, knowledgeRoot: target.rootDir } : undefined;
         },
     });
-    // 意图记录模块 (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);
-    /**
-     * `intent_*` 工具在 Host 层注册，使标准模式可以调用它们；工具执行端只接受
-     * standard 会话，其他 preset 不会写入或读取意图记录。
-     */
-    ctx.effect(() => registerIntentTools(ctx, intentService), 'tita knowledge: global intent tools');
     /**
      * 规则正文由当前会话 preset 决定；设置里的 volatile 引用在每次组装提示词时解包，
      * 因此开关保存后立即生效，不需要重建 Agent 会话。
@@ -806,50 +791,39 @@ export function apply(ctx, pluginConfig = {}) {
             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, 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) => ({ 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, 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) => 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) => 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 的**发现入口**。
      *
@@ -900,7 +874,13 @@ export function apply(ctx, pluginConfig = {}) {
     });
     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),
@@ -916,10 +896,10 @@ export function apply(ctx, pluginConfig = {}) {
      * 两者的差别只在「一次多少份」，落盘路径、分类闸门、编译链路完全共用 ——
      * 这个工具的 `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 改了）。
      *
@@ -1063,6 +1043,19 @@ export function apply(ctx, pluginConfig = {}) {
                         return sendEnvelope(res, resolved.failure);
                     return send(res, 200, success(await resolved.runtime.stats()));
                 } },
+            { kind: 'exact', path: '/knowledge/wiki', handler: async (req, res) => {
+                    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),
+                        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', path: '/knowledge/cases', handler: async (req, res) => {
                     if (req.method !== 'GET')
                         return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', 'Case 只接受 GET'));
@@ -1089,6 +1082,7 @@ export function apply(ctx, pluginConfig = {}) {
                     const rerankParam = url.searchParams.get('rerank');
                     // 响应里始终带 routes + backend，前端据此显示「Coordinate / 关键词 / 向量」三路状态。
                     return send(res, 200, await resolved.runtime.recall(url.searchParams.get('query') ?? '', topK === null ? undefined : Number(topK), url.searchParams.get('include_problems') === 'true', (url.searchParams.get('mode') ?? 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')) }),
@@ -1191,7 +1185,7 @@ export function apply(ctx, pluginConfig = {}) {
                         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)));
@@ -1213,6 +1207,8 @@ export function apply(ctx, pluginConfig = {}) {
                             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))
@@ -1323,8 +1319,13 @@ export function apply(ctx, pluginConfig = {}) {
                             sources: (Array.isArray(body.sources) ? body.sources : []).map((item) => ({
                                 ...(item?.title ? { title: String(item.title) } : {}),
                                 content: item?.content,
+                                ...(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 } : {}),
+                                ...(item?.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}),
                             })),
                             compile: body.compile === true,
                             lineage: lineageOf(body),
@@ -1341,7 +1342,7 @@ export function apply(ctx, pluginConfig = {}) {
                             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'));
@@ -1349,6 +1350,11 @@ export function apply(ctx, pluginConfig = {}) {
                         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, Number(url.searchParams.get('max_chars') ?? 40000) || 40000, lineageFromUrl(url), Number(url.searchParams.get('offset') ?? 0) || 0, Number(url.searchParams.get('source_offset') ?? 0) || 0));
                     }
                     catch (cause) {
@@ -1972,9 +1978,8 @@ export function apply(ctx, pluginConfig = {}) {
                          * ```
                          * /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 的方案说明
                          * ```
                          *
@@ -2002,12 +2007,10 @@ export function apply(ctx, pluginConfig = {}) {
                                 : 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 方案说明' : '整页';
+                                        ? '知识处理'
+                                        : rest[1] === 'help' && rest[2] === 'compile'
+                                            ? '编译链路'
+                                            : rest[1] === 'help' && rest[2] === 'overview' ? 'Agent 方案说明' : '整页';
                             res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' });
                             res.end(standalonePageHtml(title));
                             return;
@@ -2039,6 +2042,8 @@ export function apply(ctx, pluginConfig = {}) {
                             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;
                                         const catalog = await compileModelCatalog(baseId);
@@ -2046,6 +2051,8 @@ export function apply(ctx, pluginConfig = {}) {
                                         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');
@@ -2055,7 +2062,7 @@ export function apply(ctx, pluginConfig = {}) {
                                                 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)));
@@ -2067,6 +2074,7 @@ export function apply(ctx, pluginConfig = {}) {
                                     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,