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

package/src/index.ts

@@ -10,9 +10,18 @@ import type { LineageContext } from 'dsh-data-contracts/refs'
 import {
   DEFAULT_KNOWLEDGE_CONFIG, type Envelope, type KnowledgeBase, type KnowledgeConfig,
   type KnowledgeStatus, type RecallMode, type SchemaType, type SourceType, type SourceTypeDef, type SourceTypeDraft,
-  type WikiSchemaMode, type WikiTypeDef,
+  type WikiTypeDef,
 } from './types.js'
-import { defaultKnowledgeRoot, KnowledgeRuntime, success, failure, type KnowledgeRuntimeOptions, type WikiSchemaProvider } from './runtime.js'
+import {
+  defaultKnowledgeRoot,
+  KnowledgeRuntime,
+  MAX_IMPORT_SOURCES,
+  success,
+  failure,
+  type KnowledgeRuntimeOptions,
+  type WikiSchemaProvider,
+  type ModelSeam,
+} from './runtime.js'
 import { unwrapGroup } from './settings-volatile.js'
 import { DOC_PAGE_CHARS, DOC_PAGE_CHARS_MAX, documentContentPage } from './document-page.js'
 import type { ModelCall } from './extract-model.js'
@@ -75,6 +84,14 @@ export { CONVERT_SETTINGS_SCHEMA, INTENT_SETTINGS_SCHEMA }
  * 客户端按**路径**寻址（`{op:'set', path:['intent','categories']}`）。
  */
 import { Config, type KnowledgePluginConfig } 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, type KnowledgePluginConfig }
 
 /**
@@ -91,10 +108,64 @@ export function currentKnowledgeBases(): KnowledgeBases | undefined { return act
 type Args = Record<string, any>
 type WebServerLike = { register(route: { kind: 'exact' | 'prefix'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> }): () => unknown }
 
-function output() { return { schema: { type: 'json' } as const, render: (_args: unknown, value: unknown) => [{ type: 'text' as const, text: JSON.stringify(value) }] } }
-function tool(name: string, description: string, parameters: Record<string, unknown>, execute: (args: Args, exec: ToolRunContext) => Promise<unknown>) {
-  return defineTool({ name, description, parameters: parameters as any, output: output(), execute: execute as any } as any)
+/**
+ * 工具在**对话流**里的呈现（0045）。
+ *
+ * `meta` 产出的东西会随 `tool/result` 落进会话日志，Web 端由
+ * `src/client/KnowledgeToolRow.tsx` 读它渲染专用卡片（值必须是 JSON 可序列化的 ——
+ * 会话日志会整份校验，塞个函数或 Date 会在写日志时炸）。
+ *
+ * `call` / `result` 是与工具名无关的渲染意图（标题 / 分类 / 一段 Markdown），
+ * 给终端界面和「没有专用卡片的界面」兜底。三个都是**纯函数**：界面在实时流和会话回放
+ * 两条路径上都会调它们。
+ *
+ * 全部省略时行为与 0045 之前完全一致（一条工具名 + 一坨 JSON），所以只给真正需要
+ * 人看懂的工具加。
+ */
+interface ToolPresentation {
+  meta?: (args: Args, value: unknown) => unknown
+  call?: (args: Args) => unknown
+  result?: (args: Args, result: { content: unknown[]; isError: boolean; meta?: unknown }) => unknown
+}
+
+function output(presentation?: ToolPresentation) {
+  return {
+    schema: { type: 'json' } as const,
+    render: (_args: unknown, value: unknown) => [{ type: 'text' as const, text: JSON.stringify(value) }],
+    ...(presentation?.meta ? { presentationMeta: presentation.meta } : {}),
+  }
+}
+function tool(name: string, description: string, parameters: Record<string, unknown>, execute: (args: Args, exec: ToolRunContext) => Promise<unknown>, presentation?: ToolPresentation) {
+  return defineTool({
+    name, description, parameters: parameters as any, output: output(presentation), execute: execute as any,
+    ...(presentation?.call ? { presentCall: presentation.call } : {}),
+    ...(presentation?.result ? { presentResult: presentation.result } : {}),
+  } as any)
+}
+
+/**
+ * 信封 → `data`。
+ *
+ * 工具的 `execute` 返回的是一整个 `Envelope`（`{ok, status, data, warnings, error}`），
+ * 而呈现层要的是里面的 `data`。失败时 `data` 仍可能是空壳（比如
+ * `IMPORT_ALL_FAILED` 带着逐条原因），所以这里不抛，只取。
+ */
+function dataOf(value: unknown): Record<string, any> {
+  if (value && typeof value === 'object' && 'data' in (value as Record<string, unknown>)) {
+    const data = (value as { data?: unknown }).data
+    if (data && typeof data === 'object') return data as Record<string, any>
+  }
+  return {}
+}
+
+/** 一条 `presentResult` 的通用形状：用现成的 `meta` 换成一段人话，换不到就交回原内容。 */
+function resultViewOf(markdownOf: (meta: any) => string) {
+  return (_args: Args, result: { content: unknown[]; isError: boolean; meta?: unknown }) => {
+    if (result.isError || !result.meta) return undefined
+    return { card: 'generic' as const, content: [{ type: 'text' as const, text: markdownOf(result.meta) }] }
+  }
 }
+
 function envelopeError(code: string, message: string, suggestion?: string) { return failure({}, code, message, false, suggestion) }
 
 /**
@@ -370,8 +441,22 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
    * 取不到 `llm` 或默认模型时返回 undefined，链路**退回纯规则抽取**：模型是增强，
    * 不是前提。
    */
-  const modelCallFor = (): ModelCall | undefined => {
-    const llm = ctx.get('llm') as { stream(options: Record<string, unknown>): AsyncIterable<{ type?: string; text?: string }> } | undefined
+  const modelSeamFor = (): ModelSeam => {
+    /**
+     * **只能用 `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') as
+      { stream(options: Record<string, unknown>): AsyncIterable<{ type?: string; text?: string }> } | undefined
+    if (!llm) return { why: '当前上下文里取不到 `llm` 服务（模型调用入口）' }
+
     /**
      * `agentDefaultModel` 是一个**服务实例**（`dsh-agent-default-model` 的
      * `AgentDefaultModelConfig extends Service`），默认模型要从它的
@@ -381,32 +466,55 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
      * 所以那个类自己也是用 `this.config.provider.get()` 读的。第一版就是按普通属性读的，
      * 结果是永远拿到 undefined —— 模型接缝静默失效。
      */
-    const service = ctx.get('agentDefaultModel') as { currentSelection?: () => { provider?: string; model?: string; reasoningEffort?: string } } | undefined
-    const route = service?.currentSelection?.()
-    if (!llm || !route?.provider || !route?.model) return undefined
-    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 service = ctx.get('agentDefaultModel') as
+      { currentSelection?: () => { provider?: string; model?: string; reasoningEffort?: string } } | undefined
+    if (!service) return { why: '当前上下文里取不到 `agentDefaultModel` 服务 —— 默认模型那一行可能没挂上' }
+    const route = service.currentSelection?.()
+    if (!route?.provider || !route?.model) {
+      return { why: `默认模型没有选好（provider=${route?.provider ?? '空'} / model=${route?.model ?? '空'}）` }
     }
-  }
-  const runtimeOptions = (): KnowledgeRuntimeOptions => {
-    const modelCall = modelCallFor()
+    const { provider, model, reasoningEffort } = route
     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) as AsyncIterable<never>)
+      },
     }
   }
+  const runtimeOptions = (): KnowledgeRuntimeOptions => ({
+    ...(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 = (): string => knowledgeBaseRoot(config.agentRoot, 'default')
   let runtime = new KnowledgeRuntime(defaultBaseRoot(), config, runtimeOptions())
@@ -423,10 +531,14 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     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: unknown): string => {
@@ -631,12 +743,24 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
   // 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): Promise<PreToolDecision> => {
     if (writeTools.has(exec.name)) return Promise.resolve({ kind: 'ask', reason: '该操作会写入 Tita Knowledge Store，需要本轮用户审批。' })
     return next()
   })
-  ctx.tools.register(tool('recall_knowledge', 'Recall compiled knowledge: 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 as RecallMode | undefined, 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 as RecallMode | undefined, lineageOf(args, exec), { contextTopN: args.top_n, rerank: args.rerank, ...(typeof args.context_max_chars === 'number' ? { contextMaxChars: args.context_max_chars } : {}) })), {
+    call: recallCallView,
+    // 查询词从参数来，命中从结果来 —— 两者拼成一张能看懂的账本。
+    meta: (args, value) => recallMetaOf({ ...dataOf(value), query: args?.query }),
+    result: resultViewOf(recallResultMarkdown),
+  }))
   ctx.tools.register(tool('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)))))
@@ -669,42 +793,116 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     })),
   })))
   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) }))))
-    /**
-   * `write_knowledge_card` —— **它只接受一条已确认、且尚未落卡的提议**（0021 §6.1）。
+  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`：
+   * 十份文档就是十次审批弹窗、十次往返，而人真正要同意的是「把这十份导进去」这一件事。
+   * 这个工具把那件事做成一次调用。
    *
-   * 工具名与参数形状不变（冻结契约），但语义收紧了：没有 `proposal_id` 就没有写入。
-   * 这不是流程洁癖 —— 类型层是**收敛**的那一层，它错一条，所有现象的排序一起错；
-   * 而 Agent 手里只要还留着一条「未经确认也能写」的路，上面那条规则就只是文档上的一句话。
+   * 它**不替代** `add_source`：单份文档仍然用那个（参数更少、审批理由更具体）。
+   * 两者的差别只在「一次多少份」，落盘路径、分类闸门、编译链路完全共用 ——
+   * 这个工具的 `execute` 就是循环调 `importSources`，而后者逐条调 `addSource`。
    *
-   * 正常动线是「Agent 提提议 → 人在面板确认 → 面板直接落卡」。这个工具服务于另一条
-   * 更慢的路：人在面板上**只确认**（不落卡），落卡交给 Agent 这一轮来做。
+   * `compile` 默认开：批量导入的意图几乎总是「进来就能用」。关掉它的场景是「先全部
+   * 落盘、稍后统一编译」——那时卡片还没生成，工具返回里会明说 `compile: null`。
    */
-  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)))))
+  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` —— 草案工具（0024 §4）。
+   * `propose_wiki_cards` —— 把一批卡片**直接写进 `02_wiki`**（工具名不变，语义在 0044 改了）。
+   *
+   * 名字保持不变是因为它是冻结契约；但描述必须说清它现在真的会写。0040 v1.5 的员工是
+   * 「草案停在待办队列里等人确认」，0044 撤掉了那道门：**入库在前、review 在后**。
+   * 判据见 `runtime.writeCards` 的注释 —— 确认门把知识挡在了门外，而 review 的价值
+   * 不需要靠排队来实现。
    *
-   * 入参是一条 `source_id`（提议挂在触发它的那条 SourceRaw 上）加一批草案。
-   * **它不落库**：草案停在待办队列里，等人确认。
+   * 正常动线是：`add_source` 落来源 → `rebuild_knowledge` 让编译按 schema 抽实体入库。
+   * 这个工具服务于另一条路：Agent 手里已经有结构化的卡片草案（例如从一次排查里读出来的），
+   * 直接写进来，不必再走一遍抽取。
    */
-  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('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),
+  }))
 
   /**
-   * `list_card_proposals` —— Agent 自己看得到待办队列。
+   * `annotate_wiki_card` —— 给卡片加**人工备注**（0044）。
    *
-   * 少了它，Agent 会**反复提同一条**：它看不到「我已经提过了」「这条被人拒了」。
-   * 判重其实在存储层（内容指纹），但工具层给出清单，模型才有机会换一种写法。
+   * 这是「wiki 不可修改」的对偶：正文改不了，但判断改得了。`kind: 'anomaly'` 是
+   * 「这里有异常点」的显式标记（数字与原始文档对不上、两处口径互相矛盾），它会把卡片的
+   * 有效评分压到 `ANOMALY_SCORE` —— 异常卡片照样召回得到，只是排在后面，
+   * 而不是被藏起来（藏起来就没人会去修它）。
    */
-  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('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 as SchemaType } : {}),
+    ...(args.kind ? { kind: args.kind as 'note' | 'anomaly' } : {}),
+    ...(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 as SchemaType } : {}),
+    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 as KnowledgeStatus, 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 => {
@@ -727,8 +925,9 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     /**
      * 智能归因图谱的存储句柄，按 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: KnowledgeRuntime): DiagnosisStore => target.diagnosisStore()
 
@@ -747,8 +946,6 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
       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 = [
@@ -773,7 +970,14 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           url.searchParams.get('include_problems') === 'true',
           (url.searchParams.get('mode') ?? undefined) as RecallMode | undefined,
           lineageFromUrl(url),
-          { ...(topN === null ? {} : { contextTopN: Number(topN) }), ...(rerankParam === null ? {} : { rerank: rerankParam !== 'false' && rerankParam !== '0' }) },
+          {
+            ...(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' as const, path: '/knowledge/embedding/health', handler: async (req: IncomingMessage, res: ServerResponse) => {
@@ -803,13 +1007,41 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)))
         }
       } },
+      /**
+       * 批量导入 + 一次编译（0045）。
+       *
+       * 与 `import_sources` 工具**同一条实现**（`runtime.importSources`）：
+       * 「面板能做的 Agent 也能做、Agent 能做的面板也能做」是这个插件一贯的规矩，
+       * 差异只允许出现在审批与呈现上，不允许出现在行为上。
+       */
+      { kind: 'exact' as const, path: '/knowledge/import', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        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: Record<string, unknown>) => ({
+              sourceType: item?.source_type as SourceType,
+              ...(item?.title ? { title: String(item.title) } : {}),
+              content: item?.content as string,
+              ...(item?.external_id ? { externalId: String(item.external_id) } : {}),
+              ...(item?.metadata && typeof item.metadata === 'object' ? { metadata: item.metadata as Record<string, unknown> } : {}),
+            })),
+            ...(body.compile === false ? { compile: false } : {}),
+            lineage: lineageOf(body),
+          }))
+        } catch (cause) {
+          return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)))
+        }
+      } },
       { kind: 'exact' as const, path: '/knowledge/sources', handler: async (req: IncomingMessage, res: ServerResponse) => {
         try {
           if (req.method === 'POST') {
             const body = await readBody(req, 1_200_000)
             const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'))
             if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
-            return send(res, 200, await resolved.runtime.addSource({ 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'))
           const url = query(req)
@@ -902,7 +1134,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
        *
        * 它是一次显式的**写**：用户在这个库上还没录任何排查知识时，界面上那枚
        * 「载入内置示例」按钮打的就是这里。单独一条路由而不是让读取顺手写 ——
-       * 读接口写用户的 `01_source_truth/` 正是上一版的毛病。
+       * 读接口写用户的 `01_source_raw/` 正是上一版的毛病。
        */
       { kind: 'exact' as const, path: '/diagnosis/sample', handler: async (req: IncomingMessage, res: ServerResponse) => {
         if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'))
@@ -918,11 +1150,10 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         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' as const, path: '/diagnosis/run', handler: async (req: IncomingMessage, res: ServerResponse) => {
         if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 endpoint 只接受 POST'))
@@ -935,37 +1166,44 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
         }
         const outcome = await storeOf(resolved.runtime).recordRun(record)
         if (outcome.problems.length > 0 && outcome.sourceId === undefined) {
-          return send(res, 200, failure({ sourceId: '', 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' as const, path: '/knowledge/card-proposals', handler: async (req: IncomingMessage, res: ServerResponse) => {
-        const url = query(req)
-        const resolved = resolveBase(url.searchParams.get('kb'))
+      { kind: 'exact' as const, path: '/knowledge/card-annotate', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        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) as SchemaType } : {}),
+          ...(body.kind === 'anomaly' ? { kind: 'anomaly' as const } : body.kind === 'note' ? { kind: 'note' as const } : {}),
+          ...(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' as const, path: '/knowledge/card-proposals/review', handler: async (req: IncomingMessage, res: ServerResponse) => {
+      { kind: 'exact' as const, path: '/knowledge/card-review', handler: async (req: IncomingMessage, res: ServerResponse) => {
         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) as SchemaType } : {}),
+          action: body.action === 'unreview' ? 'unreview' : 'review',
           ...(body.reviewer ? { reviewer: String(body.reviewer) } : {}),
-          ...(body.reason ? { reason: String(body.reason) } : {}),
-          ...(body.patch ? { patch: body.patch as { title?: string; summary?: string; content?: string } } : {}),
           lineage: lineageOf(body),
         }))
       } },
@@ -1033,7 +1271,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             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 as SourceTypeDef[] | undefined, wikiTypes: body.wikiTypes as WikiTypeDef[] | undefined, wikiSchemaMode: body.wikiSchemaMode as WikiSchemaMode | undefined, resetWikiTypes: body.resetWikiTypes === true })
+                const updated = await bases.update(baseId, { name: body.name, description: body.description, sourceTypes: body.sourceTypes as SourceTypeDef[] | undefined, wikiTypes: body.wikiTypes as WikiTypeDef[] | undefined, resetWikiTypes: body.resetWikiTypes === true })
                 if (!updated.ok) return sendEnvelope(res, updated)
                 return send(res, 200, success({ base: updated.data }, updated.warnings))
               }
@@ -1141,7 +1379,19 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
               if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
               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') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))