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

package/lib/types/index.js

@@ -4,7 +4,7 @@ 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';
@@ -47,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()`.
@@ -58,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); }
 /**
@@ -339,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`），默认模型要从它的
@@ -351,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());
@@ -393,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)
@@ -598,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)))));
@@ -637,40 +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, template card, and the number of card proposals awaiting human review. Call this before propose_wiki_cards / 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('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),
+    }));
     /**
-   * `write_knowledge_card` —— **它只接受一条已确认、且尚未落卡的提议**（0021 §6.1）。
-   *
-   * 工具名与参数形状不变（冻结契约），但语义收紧了：没有 `proposal_id` 就没有写入。
-   * 这不是流程洁癖 —— 类型层是**收敛**的那一层，它错一条，所有现象的排序一起错；
-   * 而 Agent 手里只要还留着一条「未经确认也能写」的路，上面那条规则就只是文档上的一句话。
-   *
-   * 正常动线是「Agent 提提议 → 人在面板确认 → 面板直接落卡」。这个工具服务于另一条
-   * 更慢的路：人在面板上**只确认**（不落卡），落卡交给 Agent 这一轮来做。
-   */
-    ctx.tools.register(tool('write_knowledge_card', 'Write a Wiki knowledge card for a proposal that a HUMAN has already confirmed (status=confirmed, not yet written). Cards can no longer be written without a confirmed proposal_id: call propose_wiki_cards first, then ask the user to review it in the knowledge panel. DSH requests one user approval before execution.', { proposal_id: { type: 'string', required: true, description: '已确认、尚未落卡的提议 id。它来自 propose_wiki_cards 的返回，确认动作只能由人在面板上做' }, 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.applyProposal(args.proposal_id, lineageOf(args, exec)))));
+     * `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),
+    }));
     /**
-     * `propose_wiki_cards` —— 草案工具（0024 §4）。
+     * `annotate_wiki_card` —— 给卡片加**人工备注**（0044）。
      *
-     * 入参是一条 `source_id`（提议挂在触发它的那条 SourceRaw 上）加一批草案。
-     * **它不落库**：草案停在待办队列里，等人确认。
+     * 这是「wiki 不可修改」的对偶：正文改不了，但判断改得了。`kind: 'anomaly'` 是
+     * 「这里有异常点」的显式标记（数字与原始文档对不上、两处口径互相矛盾），它会把卡片的
+     * 有效评分压到 `ANOMALY_SCORE` —— 异常卡片照样召回得到，只是排在后面，
+     * 而不是被藏起来（藏起来就没人会去修它）。
      */
-    ctx.tools.register(tool('propose_wiki_cards', 'Propose Wiki card drafts attached to a SourceRaw. This does NOT write any card: drafts stay in the review queue until a HUMAN confirms them in the knowledge panel. Call list_wiki_types first to pick entity_type and see the required sections/fields.', { 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 是卡片正文（小节 + ```json diagnosis 结构化块）' }, 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.proposeCards({ sourceId: args.source_id, proposals: (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 })) }))));
+    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),
+    }))));
     /**
-     * `list_card_proposals` —— Agent 自己看得到待办队列。
+     * `review_wiki_card` —— review 一张卡片，抬高它的召回评分（0044）。
      *
-     * 少了它，Agent 会**反复提同一条**：它看不到「我已经提过了」「这条被人拒了」。
-     * 判重其实在存储层（内容指纹），但工具层给出清单，模型才有机会换一种写法。
+     * 它**不是准入闸门**：卡片在 review 之前就已经入库、可召回了。两个动作都可逆 ——
+     * review 是一个可以被推翻的判断，不是一次性的凭证。
      */
-    ctx.tools.register(tool('list_card_proposals', 'List Wiki card proposals awaiting human review (plus the rejected ones, so you do not re-propose something a human already turned down). Proposals never land in 02_wiki until a human confirms them.', { status: { type: 'string', enum: ['pending', 'confirmed', 'rejected', 'all'], description: '默认 pending' }, kb: { type: 'string' }, session_key: { type: 'string' } }, async (args) => withRuntime(args.kb, async (target) => {
-        const wanted = args.status ?? 'pending';
-        const all = await target.cardProposals().list();
-        const items = all.filter(item => wanted === 'all' || item.status === wanted);
-        return success({ total: items.length, proposals: items.map(item => ({ id: item.id, status: item.status, trigger: item.trigger, action: item.action, entity_type: item.entityType, entity_id: item.entityId, title: item.title, source_ref: item.sourceRef, issues: item.issues, ...(item.reason ? { reason: item.reason } : {}) })) });
-    })));
+    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;
@@ -692,8 +849,9 @@ 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 storeOf = (target) => target.diagnosisStore();
         /**
@@ -711,8 +869,6 @@ export function apply(ctx, pluginConfig = {}) {
             graph: snapshot.graph, cases: snapshot.cases, issues: snapshot.issues,
             seeded: snapshot.seeded, migrated: snapshot.migrated, source: snapshot.source,
             canLoadSample: snapshot.canLoadSample, problems: snapshot.problems,
-            // 待确认的提议条数：归因这一栏只挂角标，review 在「知识库 → Wiki」的待办区。
-            proposals: snapshot.proposals,
         });
         const routes = [
             { kind: 'exact', path: '/knowledge/stats', handler: async (req, res) => {
@@ -731,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'));
@@ -766,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') {
@@ -773,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'));
@@ -875,7 +1069,7 @@ export function apply(ctx, pluginConfig = {}) {
              *
              * 它是一次显式的**写**：用户在这个库上还没录任何排查知识时，界面上那枚
              * 「载入内置示例」按钮打的就是这里。单独一条路由而不是让读取顺手写 ——
-             * 读接口写用户的 `01_source_truth/` 正是上一版的毛病。
+             * 读接口写用户的 `01_source_raw/` 正是上一版的毛病。
              */
             { kind: 'exact', path: '/diagnosis/sample', handler: async (req, res) => {
                     if (req.method !== 'POST')
@@ -894,11 +1088,10 @@ export function apply(ctx, pluginConfig = {}) {
                     return send(res, 200, success({ cases: (await storeOf(resolved.runtime).snapshot()).cases }));
                 } },
             /**
-             * 一次排查结束：落一条 `agent_diagnosis_case` 的 SourceRaw，并顺手**提议**一张案例卡片。
+             * 一次排查结束：落一条 `agent_diagnosis_case` 的 SourceRaw，并写入一张案例卡片。
              *
-             * 两件事一起做但性质不同：日志是实例层的原始记录（Agent 的产物，可以直接落），
-             * 案例卡片落在收敛的那一侧（只能提议，等人确认）。所以响应里分别给 `sourceId`
-             * 与 `proposalId` —— 界面要能说清「记录已经留下了，但那张卡片还在等人 review」。
+             * 0044：卡片不再只提议 —— 它直接入库并标成 `unreviewed`。响应给 `sourceId` 与
+             * `entityId`，界面据此说清「记录留下了，卡片也建了，等人 review」。
              */
             { kind: 'exact', path: '/diagnosis/run', handler: async (req, res) => {
                     if (req.method !== 'POST')
@@ -913,40 +1106,48 @@ export function apply(ctx, pluginConfig = {}) {
                     }
                     const outcome = await storeOf(resolved.runtime).recordRun(record);
                     if (outcome.problems.length > 0 && outcome.sourceId === undefined) {
-                        return send(res, 200, failure({ sourceId: '', proposalId: '' }, 'RUN_WRITE_FAILED', outcome.problems.join('；'), true));
+                        return send(res, 200, failure({ sourceId: '', entityId: '' }, 'RUN_WRITE_FAILED', outcome.problems.join('；'), true));
                     }
-                    return send(res, 200, success({ sourceId: outcome.sourceId ?? '', proposalId: outcome.proposalId ?? '' }, outcome.problems));
+                    return send(res, 200, success({ sourceId: outcome.sourceId ?? '', entityId: outcome.entityId ?? '' }, outcome.problems));
                 } },
             /**
-             * 卡片提议的待办队列（0021 §6.1）。
+             * 入库之后的两个人工动作（0044）：加备注、review 抬分。
              *
-             * 读接口给「知识库 → Wiki」的待办区用；写接口是**人的 review 动作**，
-             * 刻意不做成 Agent 工具 —— 确认权收在人手里，Agent 只有 `propose_wiki_cards`。
+             * 它们取代了原来的 `/knowledge/card-proposals/review`。差别是**对象变了**：
+             * 以前 review 的是一条还没落库的提议（通过 = 允许入库），现在 review 的是一张
+             * 已经在 `02_wiki` 里、已经能召回的卡片（通过 = 抬高它的召回评分）。
+             * 前者是准入，后者是事后判断 —— 后者可逆，前者不可逆。
              */
-            { kind: 'exact', path: '/knowledge/card-proposals', handler: async (req, res) => {
-                    const url = query(req);
-                    const resolved = resolveBase(url.searchParams.get('kb'));
+            { 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);
-                    const wanted = url.searchParams.get('status') ?? 'pending';
-                    const all = await resolved.runtime.cardProposals().list();
-                    const items = all.filter(item => wanted === 'all' || item.status === wanted);
-                    return send(res, 200, success({ total: items.length, proposals: items }));
+                    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-proposals/review', handler: async (req, res) => {
+            { 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);
-                    const action = body.action === 'reject' ? 'reject' : body.action === 'confirm' ? 'confirm' : 'confirm-and-write';
-                    return sendEnvelope(res, await resolved.runtime.reviewProposal({
-                        proposalId: String(body.proposal_id ?? ''),
-                        action,
+                    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) } : {}),
-                        ...(body.reason ? { reason: String(body.reason) } : {}),
-                        ...(body.patch ? { patch: body.patch } : {}),
                         lineage: lineageOf(body),
                     }));
                 } },
@@ -1018,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));
@@ -1138,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')