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

package/lib/types/index.js

@@ -1,15 +1,16 @@
 import { createReadStream, existsSync } from 'node:fs';
-import { stat } from 'node:fs/promises';
-import { extname, isAbsolute, join, resolve, sep } from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { DEFAULT_KNOWLEDGE_CONFIG, } from './types.js';
-import { KnowledgeRuntime, success, failure } from './runtime.js';
+import { KnowledgeRuntime, MAX_IMPORT_SOURCES, success, failure, } from './runtime.js';
 import { unwrapGroup } from './settings-volatile.js';
+import { DOC_PAGE_CHARS, DOC_PAGE_CHARS_MAX, documentContentPage } from './document-page.js';
 import { agentLayout, defaultAgentRoot, ensureAgentLayout, intentRoot, knowledgeBaseRoot, legacyDefaultKnowledgeRoot, memoryRoot, presetSourceDir, resourceRegistry, resourceRoot, } from './layout.js';
 import { migrateLegacyKnowledgeTree, migrateLegacyMemory, migrateLegacyResources } from './migrate.js';
 import { legacyResourceHome } from './types.js';
 import { PickerError, createDirectory, listDirectory, pickDirectory, pickerKind, pickerOf, } from './directory-picker.js';
-import { DiagnosisStore } from './diagnosis/store.js';
 import { KNOWLEDGE_SETTINGS_SCHEMA, SETTINGS_NAMESPACE } from './settings-schema.js';
 import { DEFAULT_KB_ID, KnowledgeBases } from './knowledge-bases.js';
 import { applyConvert, CONVERT_SETTINGS_NAMESPACE, CONVERT_SETTINGS_SCHEMA, MOUNT_PATH as CONVERT_MOUNT_PATH, } from './convert/host.js';
@@ -46,6 +47,8 @@ export { CONVERT_SETTINGS_SCHEMA, INTENT_SETTINGS_SCHEMA };
  * 客户端按**路径**寻址（`{op:'set', path:['intent','categories']}`）。
  */
 import { Config } from './config-schema.js';
+import { buildModelRequest, collectModelText } from './model-text.js';
+import { addSourceCallView, addSourceMetaOf, addSourceResultMarkdown, importCallView, importMetaOf, importResultMarkdown, recallCallView, recallMetaOf, recallResultMarkdown, rebuildCallView, rebuildMetaOf, rebuildResultMarkdown, writeCardsCallView, writeCardsMetaOf, writeCardsResultMarkdown, } from './present.js';
 export { Config };
 /**
  * The live multi-knowledge-base registry, set by `apply()`.
@@ -57,9 +60,42 @@ export { Config };
  */
 let activeKnowledgeBases;
 export function currentKnowledgeBases() { return activeKnowledgeBases; }
-function output() { return { schema: { type: 'json' }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] }; }
-function tool(name, description, parameters, execute) {
-    return defineTool({ name, description, parameters: parameters, output: output(), execute: execute });
+function output(presentation) {
+    return {
+        schema: { type: 'json' },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+        ...(presentation?.meta ? { presentationMeta: presentation.meta } : {}),
+    };
+}
+function tool(name, description, parameters, execute, presentation) {
+    return defineTool({
+        name, description, parameters: parameters, output: output(presentation), execute: execute,
+        ...(presentation?.call ? { presentCall: presentation.call } : {}),
+        ...(presentation?.result ? { presentResult: presentation.result } : {}),
+    });
+}
+/**
+ * 信封 → `data`。
+ *
+ * 工具的 `execute` 返回的是一整个 `Envelope`（`{ok, status, data, warnings, error}`），
+ * 而呈现层要的是里面的 `data`。失败时 `data` 仍可能是空壳（比如
+ * `IMPORT_ALL_FAILED` 带着逐条原因），所以这里不抛，只取。
+ */
+function dataOf(value) {
+    if (value && typeof value === 'object' && 'data' in value) {
+        const data = value.data;
+        if (data && typeof data === 'object')
+            return data;
+    }
+    return {};
+}
+/** 一条 `presentResult` 的通用形状：用现成的 `meta` 换成一段人话，换不到就交回原内容。 */
+function resultViewOf(markdownOf) {
+    return (_args, result) => {
+        if (result.isError || !result.meta)
+            return undefined;
+        return { card: 'generic', content: [{ type: 'text', text: markdownOf(result.meta) }] };
+    };
 }
 function envelopeError(code, message, suggestion) { return failure({}, code, message, false, suggestion); }
 /**
@@ -154,6 +190,36 @@ function clampInt(raw, fallback, min, max) {
         return fallback;
     return Math.min(max, Math.max(min, value));
 }
+function escapeHtml(value) {
+    return value.replace(/[&<>'"]/g, character => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', "'": '&#39;', '"': '&quot;',
+    })[character] ?? character);
+}
+/**
+ * 独立整页的 HTML 外壳。
+ *
+ * 与 Notebook 的整页同一个形状，而且**只做三件事**：标题、挂载点、把自己那个 bundle
+ * 拉起来。正文不在外壳里 —— 页面自己去 `/knowledge/documents/:docId/content` 一页一页地取，
+ * 所以这份 HTML 的大小与文档大小无关。
+ */
+function standaloneDocumentHtml(title) {
+    return `<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(title)} · 原文</title>
+  </head>
+  <body>
+    <div id="tita-document-root"></div>
+    <script src="/knowledge/doc-page.js"></script>
+  </body>
+</html>`;
+}
+/** 独立整页那个 bundle 的位置：`lib/types/index.js` → `lib/doc-page.js`。 */
+function documentPageBundle() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '../doc-page.js');
+}
 /** 删除守卫的 HTTP 状态：这三类冲突必须是 409，前端据此提示用户。 */
 const CONFLICT_CODES = new Set([
     'FILE_TYPE_IN_USE', 'BASE_IS_DEFAULT', 'BASE_IN_USE',
@@ -308,8 +374,21 @@ export function apply(ctx, pluginConfig = {}) {
      * 取不到 `llm` 或默认模型时返回 undefined，链路**退回纯规则抽取**：模型是增强，
      * 不是前提。
      */
-    const modelCallFor = () => {
+    const modelSeamFor = () => {
+        /**
+         * **只能用 `ctx.get(name)`，不能用属性访问。**
+         *
+         * cordis 的 `ReflectService.get` 注释写得很清楚：「Read a service from the store
+         * without the inject requirement」；而 `ctx.<name>` 走的是 Proxy 的 get trap，
+         * 名字不在本插件的 `inject` 里时**直接抛** `cannot get property "..." without inject`。
+         * 本插件只 inject 了 tools / webServer / systemPrompt，所以属性访问不是「可能取不到」，
+         * 而是「一取就炸」—— 在 `rebuild` 里炸掉一整次编译。
+         *
+         * 本机探针（cordis 4.0.4）实测：`ctx.get` 能看见后来才注册的服务，属性访问抛异常。
+         */
         const llm = ctx.get('llm');
+        if (!llm)
+            return { why: '当前上下文里取不到 `llm` 服务（模型调用入口）' };
         /**
          * `agentDefaultModel` 是一个**服务实例**（`dsh-agent-default-model` 的
          * `AgentDefaultModelConfig extends Service`），默认模型要从它的
@@ -320,33 +399,54 @@ export function apply(ctx, pluginConfig = {}) {
          * 结果是永远拿到 undefined —— 模型接缝静默失效。
          */
         const service = ctx.get('agentDefaultModel');
-        const route = service?.currentSelection?.();
-        if (!llm || !route?.provider || !route?.model)
-            return undefined;
+        if (!service)
+            return { why: '当前上下文里取不到 `agentDefaultModel` 服务 —— 默认模型那一行可能没挂上' };
+        const route = service.currentSelection?.();
+        if (!route?.provider || !route?.model) {
+            return { why: `默认模型没有选好（provider=${route?.provider ?? '空'} / model=${route?.model ?? '空'}）` };
+        }
         const { provider, model, reasoningEffort } = route;
-        return async ({ system, prompt }) => {
-            let text = '';
-            const request = { provider, model, ...(reasoningEffort ? { reasoningEffort } : {}), system, messages: [{ role: 'user', content: prompt }] };
-            for await (const chunk of llm.stream(request)) {
-                if (chunk?.type === 'text-delta' && typeof chunk.text === 'string')
-                    text += chunk.text;
-            }
-            return text;
-        };
-    };
-    const runtimeOptions = () => {
-        const modelCall = modelCallFor();
         return {
-            ...(defaultBaseSourceTypes ? { sourceTypes: defaultBaseSourceTypes } : {}),
-            ...(defaultBaseWikiSchema ? { wikiSchema: defaultBaseWikiSchema } : {}),
-            // 0029：家当目录。配置里三个路径为空时，运行时从这里解析模型与解释器。
-            resourceRoot: resourceRoot(config.agentRoot),
-            // 0032：记忆段。默认库的记忆落在 `<agentRoot>/memory/default`，与知识树平级。
-            memoryRoot: memoryRoot(config.agentRoot, DEFAULT_KB_ID),
-            // #3b：模型接缝（实体抽取与归并）。没有默认模型时不提供，链路自动退回规则抽取。
-            ...(modelCall ? { modelCall } : {}),
+            call: async ({ system, prompt, sessionId }) => {
+                /**
+                 * 请求形状与收流都交给 `model-text.ts`（0044 实机验证第三～五批）。
+                 *
+                 * 三处都踩过坑，前两处还都伪装成同一句告警「模型输出不是 JSON 对象」：
+                 * 请求里 `content` 写成字符串（平台在适配器里调 `.some()`，于是
+                 * `content.some is not a function`），只挑 `text-delta` 收流（平台把失败表达成
+                 * 终结性的 finish chunk，不是抛异常），以及**没带 `sessionId`**
+                 * （OpenCode 系路由回 400 `MissingSessionID`）。
+                 */
+                const request = buildModelRequest({
+                    provider, model, reasoningEffort, system, prompt,
+                    // 运行时按知识库给；接缝被单独调用时（测试）退回一个稳定值，
+                    // 而不是留空 —— 留空会在 OpenCode 路由上 400。
+                    sessionId: sessionId ?? 'knowledge:default',
+                });
+                return collectModelText(llm.stream(request));
+            },
         };
     };
+    const runtimeOptions = () => ({
+        ...(defaultBaseSourceTypes ? { sourceTypes: defaultBaseSourceTypes } : {}),
+        ...(defaultBaseWikiSchema ? { wikiSchema: defaultBaseWikiSchema } : {}),
+        // 0029：家当目录。配置里三个路径为空时，运行时从这里解析模型与解释器。
+        resourceRoot: resourceRoot(config.agentRoot),
+        // 0032：记忆段。默认库的记忆落在 `<agentRoot>/memory/default`，与知识树平级。
+        memoryRoot: memoryRoot(config.agentRoot, DEFAULT_KB_ID),
+        /**
+         * #3b：模型接缝（实体抽取与归并）。
+         *
+         * **给的是函数，不是值**（0044）。profile 的组合顺序是「package.json 的 bundles →
+         * `cordis.patch.yml`」，而 `agent-default-model` 在 patch 层 —— 插件 apply 的时刻问
+         * `ctx.get('agentDefaultModel')` 只会得到 undefined，而定死之后就再也不会变：
+         * 实测的直接后果是编译一路走规则路径（正文按 `##` 小节切），而界面上没有任何提示。
+         *
+         * 传函数之后，每次真正要用模型时才问一遍 `ctx`；解析不到时它**必须说出为什么**，
+         * 那句话会原样出现在 `rebuild` 的 warnings 里。
+         */
+        modelSeam: modelSeamFor,
+    });
     /** 默认知识库的根：`<agentRoot>/domain_knowledge/default`。 */
     const defaultBaseRoot = () => knowledgeBaseRoot(config.agentRoot, 'default');
     let runtime = new KnowledgeRuntime(defaultBaseRoot(), config, runtimeOptions());
@@ -362,10 +462,14 @@ export function apply(ctx, pluginConfig = {}) {
         registryFile: () => resourceRegistry(config.agentRoot),
         defaultRuntime: () => runtime,
         config: () => config,
+        // 0044：非默认库的 runtime 也要拿到模型接缝。只传 `config` 不够 —— 默认库走上面
+        // 那个 `new KnowledgeRuntime(... runtimeOptions())`，别的库走注册表这条支路，
+        // 两边必须都带上，否则「新建一个库 → 导入文档」静默变成规则抽取。
+        runtimeOptions: () => ({ modelSeam: modelSeamFor }),
     });
     runtime.baseId = bases.defaultId;
     defaultBaseSourceTypes = () => bases.sourceTypesOf(bases.defaultId);
-    defaultBaseWikiSchema = () => ({ types: bases.wikiTypesOf(bases.defaultId), mode: bases.wikiSchemaModeOf(bases.defaultId) });
+    defaultBaseWikiSchema = () => ({ types: bases.wikiTypesOf(bases.defaultId) });
     activeKnowledgeBases = bases;
     const kbIdOf = (value) => {
         if (value === undefined || value === null)
@@ -567,13 +671,25 @@ export function apply(ctx, pluginConfig = {}) {
     // 0032/0033：意图的配置与留痕落进 `<agentRoot>/intent`（与知识、记忆平级）。
     // 0.1.7：意图的设置不再走命名空间，随本 entry 的 config 一起下来。
     intentHost = applyIntent(ctx, { intentRoot: () => intentRoot(config.agentRoot), config: intentGroup });
-    const writeTools = new Set(['add_source', 'write_knowledge_card', 'set_knowledge_status', 'rebuild_knowledge', 'record_feedback']);
+    /**
+     * 需要本轮用户审批的写工具。
+     *
+     * 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.on('tools/pre-execute', (exec, next) => {
         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: multi-route recall over wikiNotes (top_k, default from settings), resolve each hit to its wiki and 1-hop graph, BERT-rerank, then return the top_n context pack.', { query: { type: 'string', required: true }, scope: { type: 'string' }, limit: { type: 'integer' }, top_k: { type: 'integer' }, top_n: { type: 'integer' }, rerank: { type: 'boolean' }, source_types: { type: 'array' }, include_problems: { type: 'boolean' }, mode: { type: 'string', enum: ['fts', 'vector', 'graph', '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.source_types ?? [], args.include_problems ?? false, args.mode, lineageOf(args, exec), { contextTopN: args.top_n, rerank: args.rerank }))));
+    ctx.tools.register(tool('recall_knowledge', 'Recall compiled knowledge: multi-route recall over wikiNotes (top_k, default from settings), BERT-rerank the candidate pool, then assemble the context as **wiki cards** — notes are deduplicated by their card (a card keeps all its hit sections), 1-hop graph neighbours are added after that dedupe, and the whole pack is bounded by context_max_chars (default 20000). Anything over the budget goes to a temp file whose absolute path is in budget.overflow_path; read that file with your own file tools when you need more.', { query: { type: 'string', required: true }, scope: { type: 'string' }, 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 就是它的绝对路径 —— 需要更多信息时直接读那个文件。' }, source_types: { type: 'array' }, include_problems: { type: 'boolean' }, mode: { type: 'string', enum: ['fts', 'vector', 'graph', '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.source_types ?? [], 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),
+    }));
     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. Returns the top max_chars characters (default and hard max 40000) shared across the matched sources. Each source carries its absolute file `path`, `returnedChars` and `totalChars`, and the envelope carries `truncated`. When truncated is true (or returnedChars < totalChars) the content is INCOMPLETE — read that `path` directly to get the rest rather than answering from a partial document.', { query: { type: 'string', required: true }, source_types: { type: 'array' }, limit: { type: 'integer' }, max_chars: { 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, target => target.sourceTruth(args.query, args.source_types ?? [], args.limit ?? 20, args.max_chars ?? 40000, lineageOf(args, exec)))));
@@ -606,11 +722,112 @@ export function apply(ctx, pluginConfig = {}) {
         })),
     })));
     ctx.tools.register(tool('list_source_types', 'List the SourceRaw business classifications (the per-knowledge-base source_type registry) together with the built-in read-only classifier prompt. Call this before add_source whenever the classification is not obvious; the registry is editable per knowledge base, so custom ids such as test_unit may exist.', { kb: { type: 'string', description: '目标知识库 id；省略则用默认库' }, session_key: { type: 'string' } }, async (args) => withRuntime(args.kb, target => Promise.resolve(target.sourceTypeCatalog()))));
-    ctx.tools.register(tool('list_wiki_types', 'List the Wiki card types (the per-knowledge-base card schema) with their required sections, required fields, expected source types and template card. Call this before write_knowledge_card: entity_type must be one of these ids, and the required sections/fields are what makes the card usable.', { kb: { type: 'string', description: '目标知识库 id；省略则用默认库' }, session_key: { type: 'string' } }, async (args) => withRuntime(args.kb, target => target.wikiTypeCatalog())));
-    ctx.tools.register(tool('add_source', 'Add or update a SourceRaw document (原始可追溯文档). source_type is a per-knowledge-base business classification: call list_source_types first when unsure, and never guess silently. DSH requests one user approval before execution.', { source_type: { type: 'string', required: true, description: '来源业务分类 id（按业务场景，不是文件格式）。先调 list_source_types 拿注册表；拿不准就返回候选问用户，不要默认 document。' }, title: { type: 'string' }, content: { type: 'string', required: true }, external_id: { type: 'string' }, metadata: { type: 'json' }, source_id: { 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.addSource({ sourceType: args.source_type, title: args.title, content: args.content, externalId: args.external_id, metadata: args.metadata, sourceId: args.source_id, lineage: lineageOf(args, exec) }))));
-    ctx.tools.register(tool('write_knowledge_card', 'Write a Wiki knowledge card with mandatory source_refs. New cards default to unreviewed. DSH requests one user approval before execution.', { entity_type: { type: 'string', required: true, description: 'Wiki 卡片类型 id：先按 list_wiki_types 的类型定义与「例如」判断，命中就直接用它；必填小节与必填字段见该类型的 schema' }, entity_id: { type: 'string', required: true }, title: { type: 'string', required: true }, content: { type: 'string', required: true }, source_refs: { type: 'array', required: true }, status: { type: 'string', enum: ['unreviewed', 'draft', 'reviewed', 'active', 'deprecated', 'problem'] }, summary: { type: 'string' }, metadata: { type: 'json' }, 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.writeCard({ entityType: args.entity_type, entityId: args.entity_id, title: args.title, content: args.content, sourceRefs: args.source_refs, status: args.status, summary: args.summary, metadata: args.metadata, lineage: lineageOf(args, exec) }))));
+    ctx.tools.register(tool('list_wiki_types', 'List the Wiki card types (the per-knowledge-base card schema) with their required sections, required fields, template card, and the current review progress (how many cards are reviewed / unreviewed / flagged as anomalies). Call this before propose_wiki_cards: entity_type must be one of these ids, and the required sections/fields are what makes the card usable.', { kb: { type: 'string', description: '目标知识库 id；省略则用默认库' }, session_key: { type: 'string' } }, async (args) => withRuntime(args.kb, target => target.wikiTypeCatalog())));
+    ctx.tools.register(tool('add_source', 'Add or update a SourceRaw document (原始可追溯文档). source_type is a per-knowledge-base business classification: call list_source_types first when unsure, and never guess silently. DSH requests one user approval before execution.', { source_type: { type: 'string', required: true, description: '来源业务分类 id（按业务场景，不是文件格式）。先调 list_source_types 拿注册表；拿不准就返回候选问用户，不要默认 document。' }, 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 才允许并存（落成 <标题>-<内容哈希前6位>.md，并回一条 warning）。' }, 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({ sourceType: args.source_type, 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,
+        meta: (args, value) => addSourceMetaOf(args, dataOf(value)),
+        result: resultViewOf(addSourceResultMarkdown),
+    }));
+    /**
+     * `import_sources` —— **批量导入 + 一次编译**（0045）。
+     *
+     * 在这之前，「让 Agent 批量编译入库」意味着 `add_source` × N 再 `rebuild_knowledge`：
+     * 十份文档就是十次审批弹窗、十次往返，而人真正要同意的是「把这十份导进去」这一件事。
+     * 这个工具把那件事做成一次调用。
+     *
+     * 它**不替代** `add_source`：单份文档仍然用那个（参数更少、审批理由更具体）。
+     * 两者的差别只在「一次多少份」，落盘路径、分类闸门、编译链路完全共用 ——
+     * 这个工具的 `execute` 就是循环调 `importSources`，而后者逐条调 `addSource`。
+     *
+     * `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. source_type is a per-knowledge-base business classification: call list_source_types first when unsure. DSH requests one user approval before execution.', {
+        sources: { type: 'array', required: true, description: `来源数组，每项 { source_type, title?, content, external_id?, metadata?, allow_duplicate_title? }；一次最多 ${MAX_IMPORT_SOURCES} 份，超了请分批。标题与已有来源重复的那一份会被拒（SOURCE_TITLE_DUPLICATED），逐条报出来而不是整批失败` },
+        compile: { type: 'boolean', description: '默认 true：写入后立刻编译成 wiki 卡片。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 => ({
+            sourceType: item?.source_type,
+            ...(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),
+    }));
+    /**
+     * `propose_wiki_cards` —— 把一批卡片**直接写进 `02_wiki`**（工具名不变，语义在 0044 改了）。
+     *
+     * 名字保持不变是因为它是冻结契约；但描述必须说清它现在真的会写。0040 v1.5 的员工是
+     * 「草案停在待办队列里等人确认」，0044 撤掉了那道门：**入库在前、review 在后**。
+     * 判据见 `runtime.writeCards` 的注释 —— 确认门把知识挡在了门外，而 review 的价值
+     * 不需要靠排队来实现。
+     *
+     * 正常动线是：`add_source` 落来源 → `rebuild_knowledge` 让编译按 schema 抽实体入库。
+     * 这个工具服务于另一条路：Agent 手里已经有结构化的卡片草案（例如从一次排查里读出来的），
+     * 直接写进来，不必再走一遍抽取。
+     */
+    ctx.tools.register(tool('propose_wiki_cards', 'Write Wiki cards compiled from a SourceRaw directly into 02_wiki. The confirmation gate was retired in 0044: cards land immediately and are marked unreviewed, so a human reviews them AFTER entry (review raises the card score; the body itself is read-only). Call list_wiki_types first to pick entity_type and to see the required sections/fields. DSH requests one user approval before execution.', { source_id: { type: 'string', required: true, description: '这批卡片引用的那条 SourceRaw 的 source_id（先 add_source）' }, proposals: { type: 'array', required: true, description: '卡片数组，每项 { action?, entity_type, entity_id, title, summary?, content, source_refs?, metadata? }；content 是卡片正文（按该类型的必填小节组织）' }, 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.writeCards({
+        sourceId: args.source_id,
+        cards: (Array.isArray(args.proposals) ? args.proposals : []).map(item => ({ action: item?.action, entityType: item?.entity_type, entityId: item?.entity_id, title: item?.title, summary: item?.summary, content: item?.content, sourceRefs: item?.source_refs, metadata: item?.metadata })),
+        lineage: lineageOf(args, exec),
+    })), {
+        call: writeCardsCallView,
+        meta: (args, value) => writeCardsMetaOf(dataOf(value), String(args?.source_id ?? '')),
+        result: resultViewOf(writeCardsResultMarkdown),
+    }));
+    /**
+     * `annotate_wiki_card` —— 给卡片加**人工备注**（0044）。
+     *
+     * 这是「wiki 不可修改」的对偶：正文改不了，但判断改得了。`kind: 'anomaly'` 是
+     * 「这里有异常点」的显式标记（数字与原始文档对不上、两处口径互相矛盾），它会把卡片的
+     * 有效评分压到 `ANOMALY_SCORE` —— 异常卡片照样召回得到，只是排在后面，
+     * 而不是被藏起来（藏起来就没人会去修它）。
+     */
+    ctx.tools.register(tool('annotate_wiki_card', 'Attach a human annotation to a Wiki card, or remove one. Wiki bodies are read-only — this is how a person records a judgement about a card ("this number disagrees with the source", "these two definitions conflict"). kind=anomaly additionally lowers the card score for recall ranking while keeping it retrievable. DSH requests one user approval before execution.', { entity_id: { type: 'string', required: true }, entity_type: { type: 'string' }, kind: { type: 'string', enum: ['note', 'anomaly'], description: '默认 note；anomaly 表示异常点' }, note: { type: 'string', description: '备注正文；撤销一条时省略并给 remove_id' }, author: { type: 'string' }, source_ref: { type: 'string', description: '这条备注针对哪一份来源（可选）' }, remove_id: { type: 'string', description: '要撤销的备注 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, exec) => withRuntime(args.kb, target => target.annotateCard({
+        entityId: args.entity_id,
+        ...(args.entity_type ? { entityType: args.entity_type } : {}),
+        ...(args.kind ? { kind: args.kind } : {}),
+        ...(args.note ? { note: args.note } : {}),
+        ...(args.author ? { author: args.author } : {}),
+        ...(args.source_ref ? { sourceRef: args.source_ref } : {}),
+        ...(args.remove_id ? { removeId: args.remove_id } : {}),
+        lineage: lineageOf(args, exec),
+    }))));
+    /**
+     * `review_wiki_card` —— review 一张卡片，抬高它的召回评分（0044）。
+     *
+     * 它**不是准入闸门**：卡片在 review 之前就已经入库、可召回了。两个动作都可逆 ——
+     * review 是一个可以被推翻的判断，不是一次性的凭证。
+     */
+    ctx.tools.register(tool('review_wiki_card', 'Mark a Wiki card as reviewed (raises its score, which mildly boosts it in recall ranking) or undo that. Review happens AFTER entry and is reversible — it is not a gate. DSH requests one user approval before execution.', { entity_id: { type: 'string', required: true }, entity_type: { type: 'string' }, action: { type: 'string', enum: ['review', 'unreview'], required: true }, reviewer: { 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.reviewCard({
+        entityId: args.entity_id,
+        ...(args.entity_type ? { entityType: args.entity_type } : {}),
+        action: args.action === 'unreview' ? 'unreview' : 'review',
+        ...(args.reviewer ? { reviewer: args.reviewer } : {}),
+        lineage: lineageOf(args, exec),
+    }))));
     ctx.tools.register(tool('set_knowledge_status', 'Change a Wiki card 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, 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. 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))), {
+        call: rebuildCallView,
+        meta: (args, value) => rebuildMetaOf(args?.only ?? 'all', dataOf(value)),
+        result: resultViewOf(rebuildResultMarkdown),
+    }));
     ctx.tools.register(tool('record_feedback', 'Record bounded feedback for a knowledge result. DSH requests one user approval before execution.', { feedback_id: { type: 'string' }, unit_id: { type: 'string' }, rating: { type: 'integer', required: true }, comment: { 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.recordFeedback({ feedbackId: args.feedback_id, unitId: args.unit_id, rating: args.rating, comment: args.comment, sessionKey: args.session_key, lineage: lineageOf(args, exec) }))));
     ctx.inject(['webServer'], webCtx => {
         const web = webCtx;
@@ -632,20 +849,27 @@ export function apply(ctx, pluginConfig = {}) {
         /**
          * 智能归因图谱的存储句柄，按 rootDir 缓存。
          *
-         * 每个知识库有自己的 `05_diagnosis/`，和它的 wiki / 编译产物同源；缓存键用
-         * rootDir 而不是 baseId，因为独立 runtime（未挂到知识库列表上的）也要能读写。
+         * 归因知识住在各库自己的 `01_source_raw/agent_diagnosis_case/` 与
+         * `02_wiki/diagnosis/` 里（`05_diagnosis/` 已于 v1.1 撤销），和它的 wiki 同源；
+         * 缓存键用 rootDir 而不是 baseId，因为独立 runtime（未挂到知识库列表上的）也要能读写。
          */
-        const diagnosisStores = new Map();
-        const storeOf = (target) => {
-            const cached = diagnosisStores.get(target.rootDir);
-            if (cached)
-                return cached;
-            // 卡片要经运行时的 writeCard 落盘（它同时校验 schema 与「出处必须真实存在」），
-            // 所以 store 拿的是运行时本身，不只是 rootDir。
-            const created = new DiagnosisStore(target);
-            diagnosisStores.set(target.rootDir, created);
-            return created;
-        };
+        const storeOf = (target) => target.diagnosisStore();
+        /**
+         * `/diagnosis/graph` 与 `/diagnosis/sample` 的同一个响应体。
+         *
+         * 两条路由必须长得一样：界面拿到的要么是「这个库当前的知识」，要么是「刚载入示例之后
+         * 的知识」，它不该为第二种再写一条解析分支。
+         *
+         * 字段各有理由，不是把 snapshot 摊平：
+         * - `issues` 三层校验的结果要能直接显示，而不是只写进日志；
+         * - `source` / `migrated` 让界面说清「读的是卡片还是旧 jsonl」「迁移有没有生效」；
+         * - `canLoadSample` 是空态的开关 —— 这个库还什么都没有时才为真。
+         */
+        const diagnosisPayload = (snapshot) => ({
+            graph: snapshot.graph, cases: snapshot.cases, issues: snapshot.issues,
+            seeded: snapshot.seeded, migrated: snapshot.migrated, source: snapshot.source,
+            canLoadSample: snapshot.canLoadSample, problems: snapshot.problems,
+        });
         const routes = [
             { kind: 'exact', path: '/knowledge/stats', handler: async (req, res) => {
                     const resolved = resolveBase(query(req).searchParams.get('kb'));
@@ -663,7 +887,14 @@ export function apply(ctx, pluginConfig = {}) {
                     const topN = url.searchParams.get('top_n');
                     const rerankParam = url.searchParams.get('rerank');
                     // 响应里始终带 routes + backend，前端据此显示「关键词 / 向量 / 知识图谱」三路状态。
-                    return send(res, 200, await resolved.runtime.recall(url.searchParams.get('query') ?? '', topK === null ? undefined : Number(topK), sourceTypes, url.searchParams.get('include_problems') === 'true', (url.searchParams.get('mode') ?? undefined), lineageFromUrl(url), { ...(topN === null ? {} : { contextTopN: Number(topN) }), ...(rerankParam === null ? {} : { rerank: rerankParam !== 'false' && rerankParam !== '0' }) }));
+                    return send(res, 200, await resolved.runtime.recall(url.searchParams.get('query') ?? '', topK === null ? undefined : Number(topK), sourceTypes, url.searchParams.get('include_problems') === 'true', (url.searchParams.get('mode') ?? undefined), lineageFromUrl(url), {
+                        ...(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')) }),
+                        // 面板账本（0050）：只在 HTTP 上给，工具调用不带 —— 几十行候选分数进
+                        // 模型上下文是纯噪声，而面板要的就是「哪条被丢了、各自多少分」。
+                        ...(url.searchParams.get('detail') === 'true' ? { detail: true } : {}),
+                    }));
                 } },
             { kind: 'exact', path: '/knowledge/embedding/health', handler: async (req, res) => {
                     const resolved = resolveBase(query(req).searchParams.get('kb'));
@@ -698,6 +929,37 @@ export function apply(ctx, pluginConfig = {}) {
                         return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)));
                     }
                 } },
+            /**
+             * 批量导入 + 一次编译（0045）。
+             *
+             * 与 `import_sources` 工具**同一条实现**（`runtime.importSources`）：
+             * 「面板能做的 Agent 也能做、Agent 能做的面板也能做」是这个插件一贯的规矩，
+             * 差异只允许出现在审批与呈现上，不允许出现在行为上。
+             */
+            { kind: 'exact', path: '/knowledge/import', handler: async (req, res) => {
+                    try {
+                        if (req.method !== 'POST')
+                            return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'));
+                        const body = await readBody(req, 4_000_000);
+                        const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'));
+                        if ('failure' in resolved)
+                            return sendEnvelope(res, resolved.failure);
+                        return send(res, 200, await resolved.runtime.importSources({
+                            sources: (Array.isArray(body.sources) ? body.sources : []).map((item) => ({
+                                sourceType: item?.source_type,
+                                ...(item?.title ? { title: String(item.title) } : {}),
+                                content: item?.content,
+                                ...(item?.external_id ? { externalId: String(item.external_id) } : {}),
+                                ...(item?.metadata && typeof item.metadata === 'object' ? { metadata: item.metadata } : {}),
+                            })),
+                            ...(body.compile === false ? { compile: false } : {}),
+                            lineage: lineageOf(body),
+                        }));
+                    }
+                    catch (cause) {
+                        return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)));
+                    }
+                } },
             { kind: 'exact', path: '/knowledge/sources', handler: async (req, res) => {
                     try {
                         if (req.method === 'POST') {
@@ -705,7 +967,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({ sourceType: body.source_type ?? 'document', title: body.title, content: body.content, externalId: body.external_id, metadata: body.metadata, sourceId: body.source_id, lineage: lineageOf(body) }));
+                            return send(res, 200, await resolved.runtime.addSource({ sourceType: body.source_type ?? 'document', 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) }));
                         }
                         if (req.method !== 'GET')
                             return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET 或 POST'));
@@ -800,14 +1062,24 @@ export function apply(ctx, pluginConfig = {}) {
                     const resolved = resolveBase(query(req).searchParams.get('kb'));
                     if ('failure' in resolved)
                         return sendEnvelope(res, resolved.failure);
-                    const snapshot = await storeOf(resolved.runtime).snapshot();
-                    // issues 一并返回：三层校验的结果要能直接显示在界面上，而不是只写进日志。
-                    // source / migrated / problems 一并返回：界面必须能说清「现在读的是卡片还是旧 jsonl」，
-                    // 以及迁移有没有生效 —— 这类状态靠猜就会变成一句含糊的「05_diagnosis」。
-                    return send(res, 200, success({
-                        graph: snapshot.graph, cases: snapshot.cases, issues: snapshot.issues,
-                        seeded: snapshot.seeded, migrated: snapshot.migrated, source: snapshot.source, problems: snapshot.problems,
-                    }));
+                    return send(res, 200, success(diagnosisPayload(await storeOf(resolved.runtime).snapshot())));
+                } },
+            /**
+             * 载入**内置示例**（0021 的示例内容，原来是自动写入的）。
+             *
+             * 它是一次显式的**写**：用户在这个库上还没录任何排查知识时，界面上那枚
+             * 「载入内置示例」按钮打的就是这里。单独一条路由而不是让读取顺手写 ——
+             * 读接口写用户的 `01_source_raw/` 正是上一版的毛病。
+             */
+            { kind: 'exact', path: '/diagnosis/sample', handler: async (req, res) => {
+                    if (req.method !== 'POST')
+                        return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'));
+                    const resolved = resolveBase(query(req).searchParams.get('kb'));
+                    if ('failure' in resolved)
+                        return sendEnvelope(res, resolved.failure);
+                    const store = storeOf(resolved.runtime);
+                    const { problems } = await store.loadSample();
+                    return send(res, 200, success(diagnosisPayload(await store.snapshot()), problems));
                 } },
             { kind: 'exact', path: '/diagnosis/cases', handler: async (req, res) => {
                     const resolved = resolveBase(query(req).searchParams.get('kb'));
@@ -815,6 +1087,70 @@ export function apply(ctx, pluginConfig = {}) {
                         return sendEnvelope(res, resolved.failure);
                     return send(res, 200, success({ cases: (await storeOf(resolved.runtime).snapshot()).cases }));
                 } },
+            /**
+             * 一次排查结束：落一条 `agent_diagnosis_case` 的 SourceRaw，并写入一张案例卡片。
+             *
+             * 0044：卡片不再只提议 —— 它直接入库并标成 `unreviewed`。响应给 `sourceId` 与
+             * `entityId`，界面据此说清「记录留下了，卡片也建了，等人 review」。
+             */
+            { kind: 'exact', path: '/diagnosis/run', handler: async (req, res) => {
+                    if (req.method !== 'POST')
+                        return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 endpoint 只接受 POST'));
+                    const body = await readBody(req, 2_000_000);
+                    const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'));
+                    if ('failure' in resolved)
+                        return sendEnvelope(res, resolved.failure);
+                    const record = body.record;
+                    if (!record || typeof record.runId !== 'string' || typeof record.symptomId !== 'string') {
+                        return send(res, 400, envelopeError('RUN_RECORD_INVALID', 'record 必须是 { runId, symptomId, startedAt, durationMinutes, path, evidence, rootCause?, misleading? }'));
+                    }
+                    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, success({ sourceId: outcome.sourceId ?? '', entityId: outcome.entityId ?? '' }, outcome.problems));
+                } },
+            /**
+             * 入库之后的两个人工动作（0044）：加备注、review 抬分。
+             *
+             * 它们取代了原来的 `/knowledge/card-proposals/review`。差别是**对象变了**：
+             * 以前 review 的是一条还没落库的提议（通过 = 允许入库），现在 review 的是一张
+             * 已经在 `02_wiki` 里、已经能召回的卡片（通过 = 抬高它的召回评分）。
+             * 前者是准入，后者是事后判断 —— 后者可逆，前者不可逆。
+             */
+            { kind: 'exact', path: '/knowledge/card-annotate', handler: async (req, res) => {
+                    if (req.method !== 'POST')
+                        return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 endpoint 只接受 POST'));
+                    const body = await readBody(req, 2_000_000);
+                    const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'));
+                    if ('failure' in resolved)
+                        return sendEnvelope(res, resolved.failure);
+                    return sendEnvelope(res, await resolved.runtime.annotateCard({
+                        entityId: String(body.entity_id ?? ''),
+                        ...(body.entity_type ? { entityType: String(body.entity_type) } : {}),
+                        ...(body.kind === 'anomaly' ? { kind: 'anomaly' } : body.kind === 'note' ? { kind: 'note' } : {}),
+                        ...(body.note ? { note: String(body.note) } : {}),
+                        ...(body.author ? { author: String(body.author) } : {}),
+                        ...(body.source_ref ? { sourceRef: String(body.source_ref) } : {}),
+                        ...(body.remove_id ? { removeId: String(body.remove_id) } : {}),
+                        lineage: lineageOf(body),
+                    }));
+                } },
+            { kind: 'exact', path: '/knowledge/card-review', handler: async (req, res) => {
+                    if (req.method !== 'POST')
+                        return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 endpoint 只接受 POST'));
+                    const body = await readBody(req, 2_000_000);
+                    const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'));
+                    if ('failure' in resolved)
+                        return sendEnvelope(res, resolved.failure);
+                    return sendEnvelope(res, await resolved.runtime.reviewCard({
+                        entityId: String(body.entity_id ?? ''),
+                        ...(body.entity_type ? { entityType: String(body.entity_type) } : {}),
+                        action: body.action === 'unreview' ? 'unreview' : 'review',
+                        ...(body.reviewer ? { reviewer: String(body.reviewer) } : {}),
+                        lineage: lineageOf(body),
+                    }));
+                } },
             { kind: 'prefix', path: '/knowledge', handler: async (req, res) => {
                     const method = req.method ?? 'GET';
                     try {
@@ -836,6 +1172,26 @@ export function apply(ctx, pluginConfig = {}) {
                             const body = await readBody(req);
                             return sendEnvelope(res, await withRuntime(body.kb, target => target.rebuild(body.only ?? 'all', lineageOf(body))));
                         }
+                        /**
+                         * 独立整页的 bundle（`lib/doc-page.js`，构建产物）。
+                         *
+                         * 它挂在本插件的 `/knowledge` 前缀下而不是另开一条顶层路由：整页是这个插件
+                         * 的一部分，路径上不该假装是一个独立服务。`no-cache` 是刻意的 —— 这份文件在
+                         * 开发时会被反复重建，缓存住它等于让人对着旧页面调试。
+                         */
+                        if (rest.length === 1 && rest[0] === 'doc-page.js') {
+                            if (method !== 'GET')
+                                return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'));
+                            try {
+                                const bundle = await readFile(documentPageBundle());
+                                res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' });
+                                res.end(bundle);
+                            }
+                            catch {
+                                return send(res, 404, envelopeError('NOT_FOUND', 'doc-page.js 不存在；先构建这个插件（pnpm build）'));
+                            }
+                            return;
+                        }
                         // ---------------------------------------------- /knowledge/bases
                         if (rest[0] === 'bases') {
                             if (rest.length === 1) {
@@ -863,7 +1219,7 @@ export function apply(ctx, pluginConfig = {}) {
                             if (rest.length === 2) {
                                 if (method === 'PATCH') {
                                     const body = await readBody(req);
-                                    const updated = await bases.update(baseId, { name: body.name, description: body.description, sourceTypes: body.sourceTypes, wikiTypes: body.wikiTypes, wikiSchemaMode: body.wikiSchemaMode, resetWikiTypes: body.resetWikiTypes === true });
+                                    const updated = await bases.update(baseId, { name: body.name, description: body.description, sourceTypes: body.sourceTypes, wikiTypes: body.wikiTypes, resetWikiTypes: body.resetWikiTypes === true });
                                     if (!updated.ok)
                                         return sendEnvelope(res, updated);
                                     return send(res, 200, success({ base: updated.data }, updated.warnings));
@@ -983,7 +1339,19 @@ export function apply(ctx, pluginConfig = {}) {
                                 const card = await resolved.runtime.readCard(entityId, entityType);
                                 if (!card)
                                     return sendEnvelope(res, failure({}, 'CARD_NOT_FOUND', `知识卡片不存在: ${entityId}`, true));
-                                return send(res, 200, success({ card }));
+                                // 正文里的图要能在面板里显示，就得给 URL（`imagePaths` 是磁盘路径，浏览器
+                                // 加载不了）。与 SourceRaw 详情同一种形状，两个预览抽屉共用一套解析。
+                                const assets = await resolved.runtime.assetsOfCard(card);
+                                /**
+                                 * 相关卡片（0049）：出链与入链。
+                                 *
+                                 * 由服务端算，而不是让客户端去解析正文里那一块 `## 相关` —— 正文里那块是
+                                 * 给人 `grep` 的（`[[类型/标题]]` 在面板里点不开），而抽屉里这几行是**可点的
+                                 * 入口**。两处读同一个计划（`planRelated`），所以不会出现「文件里写着 A、
+                                 * 界面上列着 B」。
+                                 */
+                                const related = await resolved.runtime.relatedOfCard(card);
+                                return send(res, 200, success({ card, assets, related }));
                             }
                             if (rest.length === 3 && rest[2] === 'versions') {
                                 if (method !== 'GET')
@@ -1031,6 +1399,12 @@ export function apply(ctx, pluginConfig = {}) {
                                 return sendEnvelope(res, resolved.failure);
                             if (rest.length === 2) {
                                 if (method === 'GET') {
+                                    /**
+                                     * 正文在这里**按 `SOURCE_PREVIEW_CHARS` 封顶**（`readDocument` 的默认值）。
+                                     * 抽屉只渲染前 4000 字符，而过去这个接口把整份正文发过去 —— 传输、JSON
+                                     * 解析、进 React state 全按全文的量级付费，那就是「打开弹层要等半天」。
+                                     * 要读全文有独立整页：`.../view`，一页一页地取。
+                                     */
                                     const document = await resolved.runtime.readDocument(docId);
                                     if (!document)
                                         return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true));
@@ -1052,6 +1426,35 @@ export function apply(ctx, pluginConfig = {}) {
                                     return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true));
                                 return send(res, 200, success({ versions }));
                             }
+                            /**
+                             * 独立整页的**正文分页**接口：一次一段，切点对齐空行（见 `documentContentPage`）。
+                             *
+                             * 它是 `.../view` 那个页面的数据源，也是「原文全文」唯一的分发口 ——
+                             * 面板那条明细接口刻意不发全文。
+                             */
+                            if (rest.length === 3 && rest[2] === 'content') {
+                                if (method !== 'GET')
+                                    return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'));
+                                const body = await resolved.runtime.readDocumentBody(docId);
+                                if (body === undefined)
+                                    return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true));
+                                const offset = clampInt(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER);
+                                const limit = clampInt(url.searchParams.get('limit'), DOC_PAGE_CHARS, 1, DOC_PAGE_CHARS_MAX);
+                                return send(res, 200, success(documentContentPage(body, offset, limit)));
+                            }
+                            /**
+                             * 独立整页的外壳。前端从抽屉里「新页面打开」跳过来，也可以直接粘贴这个地址。
+                             */
+                            if (rest.length === 3 && rest[2] === 'view') {
+                                if (method !== 'GET')
+                                    return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'));
+                                const document = await resolved.runtime.readDocument(docId);
+                                if (!document)
+                                    return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true));
+                                res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' });
+                                res.end(standaloneDocumentHtml(document.title));
+                                return;
+                            }
                             if (rest.length === 3 && rest[2] === 'revert') {
                                 if (method !== 'POST')
                                     return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'));