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

package/src/index.ts

@@ -1,7 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { createReadStream, existsSync } from 'node:fs'
-import { stat } from 'node:fs/promises'
-import { extname, isAbsolute, join, resolve, sep } from 'node:path'
+import { readFile, stat } from 'node:fs/promises'
+import { dirname, extname, isAbsolute, join, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { defineTool, type PreToolDecision, type ToolRunContext } from '@deepseek-ai/dsh-tools'
@@ -13,6 +14,7 @@ import {
 } from './types.js'
 import { defaultKnowledgeRoot, KnowledgeRuntime, success, failure, type KnowledgeRuntimeOptions, type WikiSchemaProvider } 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'
 import {
   agentLayout, defaultAgentRoot, ensureAgentLayout, intentRoot, knowledgeBaseRoot, legacyDefaultKnowledgeRoot,
@@ -24,6 +26,7 @@ import {
   PickerError, createDirectory, listDirectory, pickDirectory, pickerKind, pickerOf,
 } from './directory-picker.js'
 import { DiagnosisStore } from './diagnosis/store.js'
+import type { DiagnosisRunRecord } from './diagnosis/types.js'
 import { KNOWLEDGE_SETTINGS_SCHEMA, SETTINGS_NAMESPACE } from './settings-schema.js'
 import { DEFAULT_KB_ID, KnowledgeBases } from './knowledge-bases.js'
 import {
@@ -180,6 +183,39 @@ function clampInt(raw: string | null, fallback: number, min: number, max: number
   return Math.min(max, Math.max(min, value))
 }
 
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>'"]/g, character => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', "'": '&#39;', '"': '&quot;',
+  })[character] ?? character)
+}
+
+/**
+ * 独立整页的 HTML 外壳。
+ *
+ * 与 Notebook 的整页同一个形状，而且**只做三件事**：标题、挂载点、把自己那个 bundle
+ * 拉起来。正文不在外壳里 —— 页面自己去 `/knowledge/documents/:docId/content` 一页一页地取，
+ * 所以这份 HTML 的大小与文档大小无关。
+ */
+function standaloneDocumentHtml(title: string): string {
+  return `<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(title)} · 原文</title>
+  </head>
+  <body>
+    <div id="tita-document-root"></div>
+    <script src="/knowledge/doc-page.js"></script>
+  </body>
+</html>`
+}
+
+/** 独立整页那个 bundle 的位置：`lib/types/index.js` → `lib/doc-page.js`。 */
+function documentPageBundle(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '../doc-page.js')
+}
+
 /** 删除守卫的 HTTP 状态：这三类冲突必须是 409，前端据此提示用户。 */
 const CONFLICT_CODES = new Set([
   'FILE_TYPE_IN_USE', 'BASE_IS_DEFAULT', 'BASE_IN_USE',
@@ -633,9 +669,40 @@ 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, expected source types and template card. Call this before write_knowledge_card: entity_type must be one of these ids, and the required sections/fields are what makes the card usable.', { kb: { type: 'string', description: '目标知识库 id；省略则用默认库' }, session_key: { type: 'string' } }, async args => withRuntime(args.kb, target => target.wikiTypeCatalog())))
+  ctx.tools.register(tool('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('write_knowledge_card', 'Write a Wiki knowledge card with mandatory source_refs. New cards default to unreviewed. DSH requests one user approval before execution.', { entity_type: { type: 'string', required: true, description: 'Wiki 卡片类型 id：先按 list_wiki_types 的类型定义与「例如」判断，命中就直接用它；必填小节与必填字段见该类型的 schema' }, entity_id: { type: 'string', required: true }, title: { type: 'string', required: true }, content: { type: 'string', required: true }, source_refs: { type: 'array', required: true }, status: { type: 'string', enum: ['unreviewed', 'draft', 'reviewed', 'active', 'deprecated', 'problem'] }, summary: { type: 'string' }, metadata: { type: 'json' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.writeCard({ entityType: args.entity_type, entityId: args.entity_id, title: args.title, content: args.content, sourceRefs: args.source_refs, status: args.status, summary: args.summary, metadata: args.metadata, lineage: lineageOf(args, exec) }))))
+    /**
+   * `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` —— 草案工具（0024 §4）。
+   *
+   * 入参是一条 `source_id`（提议挂在触发它的那条 SourceRaw 上）加一批草案。
+   * **它不落库**：草案停在待办队列里，等人确认。
+   */
+  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 })) }))))
+
+  /**
+   * `list_card_proposals` —— Agent 自己看得到待办队列。
+   *
+   * 少了它，Agent 会**反复提同一条**：它看不到「我已经提过了」「这条被人拒了」。
+   * 判重其实在存储层（内容指纹），但工具层给出清单，模型才有机会换一种写法。
+   */
+  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('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('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) }))))
@@ -663,16 +730,26 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
      * 每个知识库有自己的 `05_diagnosis/`，和它的 wiki / 编译产物同源；缓存键用
      * rootDir 而不是 baseId，因为独立 runtime（未挂到知识库列表上的）也要能读写。
      */
-    const diagnosisStores = new Map<string, DiagnosisStore>()
-    const storeOf = (target: KnowledgeRuntime): DiagnosisStore => {
-      const cached = diagnosisStores.get(target.rootDir)
-      if (cached) return cached
-      // 卡片要经运行时的 writeCard 落盘（它同时校验 schema 与「出处必须真实存在」），
-      // 所以 store 拿的是运行时本身，不只是 rootDir。
-      const created = new DiagnosisStore(target)
-      diagnosisStores.set(target.rootDir, created)
-      return created
-    }
+    const storeOf = (target: KnowledgeRuntime): DiagnosisStore => target.diagnosisStore()
+
+    /**
+     * `/diagnosis/graph` 与 `/diagnosis/sample` 的同一个响应体。
+     *
+     * 两条路由必须长得一样：界面拿到的要么是「这个库当前的知识」，要么是「刚载入示例之后
+     * 的知识」，它不该为第二种再写一条解析分支。
+     *
+     * 字段各有理由，不是把 snapshot 摊平：
+     * - `issues` 三层校验的结果要能直接显示，而不是只写进日志；
+     * - `source` / `migrated` 让界面说清「读的是卡片还是旧 jsonl」「迁移有没有生效」；
+     * - `canLoadSample` 是空态的开关 —— 这个库还什么都没有时才为真。
+     */
+    const diagnosisPayload = (snapshot: Awaited<ReturnType<DiagnosisStore['snapshot']>>): Record<string, unknown> => ({
+      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' as const, path: '/knowledge/stats', handler: async (req: IncomingMessage, res: ServerResponse) => {
@@ -818,20 +895,80 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
       { kind: 'exact' as const, path: '/diagnosis/graph', handler: async (req: IncomingMessage, res: ServerResponse) => {
         const resolved = resolveBase(query(req).searchParams.get('kb'))
         if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
-        const snapshot = await storeOf(resolved.runtime).snapshot()
-        // issues 一并返回：三层校验的结果要能直接显示在界面上，而不是只写进日志。
-        // source / migrated / problems 一并返回：界面必须能说清「现在读的是卡片还是旧 jsonl」，
-        // 以及迁移有没有生效 —— 这类状态靠猜就会变成一句含糊的「05_diagnosis」。
-        return send(res, 200, success({
-          graph: snapshot.graph, cases: snapshot.cases, issues: snapshot.issues,
-          seeded: snapshot.seeded, migrated: snapshot.migrated, source: snapshot.source, problems: snapshot.problems,
-        }))
+        return send(res, 200, success(diagnosisPayload(await storeOf(resolved.runtime).snapshot())))
+      } },
+      /**
+       * 载入**内置示例**（0021 的示例内容，原来是自动写入的）。
+       *
+       * 它是一次显式的**写**：用户在这个库上还没录任何排查知识时，界面上那枚
+       * 「载入内置示例」按钮打的就是这里。单独一条路由而不是让读取顺手写 ——
+       * 读接口写用户的 `01_source_truth/` 正是上一版的毛病。
+       */
+      { 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'))
+        const resolved = resolveBase(query(req).searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        const store = storeOf(resolved.runtime)
+        const { problems } = await store.loadSample()
+        return send(res, 200, success(diagnosisPayload(await store.snapshot()), problems))
       } },
       { kind: 'exact' as const, path: '/diagnosis/cases', handler: async (req: IncomingMessage, res: ServerResponse) => {
         const resolved = resolveBase(query(req).searchParams.get('kb'))
         if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
         return send(res, 200, success({ cases: (await storeOf(resolved.runtime).snapshot()).cases }))
       } },
+      /**
+       * 一次排查结束：落一条 `agent_diagnosis_case` 的 SourceRaw，并顺手**提议**一张案例卡片。
+       *
+       * 两件事一起做但性质不同：日志是实例层的原始记录（Agent 的产物，可以直接落），
+       * 案例卡片落在收敛的那一侧（只能提议，等人确认）。所以响应里分别给 `sourceId`
+       * 与 `proposalId` —— 界面要能说清「记录已经留下了，但那张卡片还在等人 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'))
+        const body = await readBody(req, 2_000_000)
+        const resolved = resolveBase(body.kb ?? query(req).searchParams.get('kb'))
+        if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
+        const record = body.record as DiagnosisRunRecord | undefined
+        if (!record || typeof record.runId !== 'string' || typeof record.symptomId !== 'string') {
+          return send(res, 400, envelopeError('RUN_RECORD_INVALID', 'record 必须是 { runId, symptomId, startedAt, durationMinutes, path, evidence, rootCause?, misleading? }'))
+        }
+        const outcome = await storeOf(resolved.runtime).recordRun(record)
+        if (outcome.problems.length > 0 && outcome.sourceId === undefined) {
+          return send(res, 200, failure({ sourceId: '', proposalId: '' }, 'RUN_WRITE_FAILED', outcome.problems.join('；'), true))
+        }
+        return send(res, 200, success({ sourceId: outcome.sourceId ?? '', proposalId: outcome.proposalId ?? '' }, outcome.problems))
+      } },
+      /**
+       * 卡片提议的待办队列（0021 §6.1）。
+       *
+       * 读接口给「知识库 → Wiki」的待办区用；写接口是**人的 review 动作**，
+       * 刻意不做成 Agent 工具 —— 确认权收在人手里，Agent 只有 `propose_wiki_cards`。
+       */
+      { 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'))
+        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 }))
+      } },
+      { kind: 'exact' as const, path: '/knowledge/card-proposals/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,
+          ...(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),
+        }))
+      } },
       { kind: 'prefix' as const, path: '/knowledge', handler: async (req: IncomingMessage, res: ServerResponse) => {
         const method = req.method ?? 'GET'
         try {
@@ -852,6 +989,25 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             return sendEnvelope(res, await withRuntime(body.kb, target => target.rebuild(body.only ?? 'all', lineageOf(body))))
           }
 
+          /**
+           * 独立整页的 bundle（`lib/doc-page.js`，构建产物）。
+           *
+           * 它挂在本插件的 `/knowledge` 前缀下而不是另开一条顶层路由：整页是这个插件
+           * 的一部分，路径上不该假装是一个独立服务。`no-cache` 是刻意的 —— 这份文件在
+           * 开发时会被反复重建，缓存住它等于让人对着旧页面调试。
+           */
+          if (rest.length === 1 && rest[0] === 'doc-page.js') {
+            if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
+            try {
+              const bundle = await readFile(documentPageBundle())
+              res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' })
+              res.end(bundle)
+            } catch {
+              return send(res, 404, envelopeError('NOT_FOUND', 'doc-page.js 不存在；先构建这个插件（pnpm build）'))
+            }
+            return
+          }
+
           // ---------------------------------------------- /knowledge/bases
           if (rest[0] === 'bases') {
             if (rest.length === 1) {
@@ -1025,6 +1181,12 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
             if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
             if (rest.length === 2) {
               if (method === 'GET') {
+                /**
+                 * 正文在这里**按 `SOURCE_PREVIEW_CHARS` 封顶**（`readDocument` 的默认值）。
+                 * 抽屉只渲染前 4000 字符，而过去这个接口把整份正文发过去 —— 传输、JSON
+                 * 解析、进 React state 全按全文的量级付费，那就是「打开弹层要等半天」。
+                 * 要读全文有独立整页：`.../view`，一页一页地取。
+                 */
                 const document = await resolved.runtime.readDocument(docId)
                 if (!document) return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true))
                 return send(res, 200, success({ document }))
@@ -1042,6 +1204,31 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
               if (versions.length === 0) return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true))
               return send(res, 200, success({ versions }))
             }
+            /**
+             * 独立整页的**正文分页**接口：一次一段，切点对齐空行（见 `documentContentPage`）。
+             *
+             * 它是 `.../view` 那个页面的数据源，也是「原文全文」唯一的分发口 ——
+             * 面板那条明细接口刻意不发全文。
+             */
+            if (rest.length === 3 && rest[2] === 'content') {
+              if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
+              const body = await resolved.runtime.readDocumentBody(docId)
+              if (body === undefined) return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true))
+              const offset = clampInt(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER)
+              const limit = clampInt(url.searchParams.get('limit'), DOC_PAGE_CHARS, 1, DOC_PAGE_CHARS_MAX)
+              return send(res, 200, success(documentContentPage(body, offset, limit)))
+            }
+            /**
+             * 独立整页的外壳。前端从抽屉里「新页面打开」跳过来，也可以直接粘贴这个地址。
+             */
+            if (rest.length === 3 && rest[2] === 'view') {
+              if (method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 GET'))
+              const document = await resolved.runtime.readDocument(docId)
+              if (!document) return sendEnvelope(res, failure({}, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true))
+              res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' })
+              res.end(standaloneDocumentHtml(document.title))
+              return
+            }
             if (rest.length === 3 && rest[2] === 'revert') {
               if (method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '该 knowledge endpoint 只接受 POST'))
               const body = await readBody(req)

package/src/knowledge-bases.ts

@@ -29,12 +29,12 @@ import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import {
   BUILTIN_SOURCE_TYPES, defaultSourceTypes, FALLBACK_SOURCE_TYPE, isBuiltinSourceType,
-  MAX_SOURCE_TYPES, SOURCE_TYPE_ID_PATTERN, validateSourceTypeDraft, validateSourceTypeText, WIKI_TYPE_ID_PATTERN,
+  LEGACY_SOURCE_TYPE_IDS, MAX_SOURCE_TYPES, SOURCE_TYPE_ID_PATTERN, validateSourceTypeDraft, validateSourceTypeText, WIKI_TYPE_ID_PATTERN,
   type Envelope, type KnowledgeBase, type KnowledgeConfig,
   type SourceTypeDef, type SourceTypeDraft, type WikiSchemaMode, type WikiTypeDef,
 } from './types.js'
 import {
-  defaultWikiTypes, isBuiltinWikiType, parseFieldLines, parseSectionLines, templateCardFor,
+  defaultWikiTypes, isBuiltinWikiType, LEGACY_WIKI_TYPE_IDS, parseFieldLines, parseSectionLines, templateCardFor,
   validateWikiTypeDraft, validateWikiTypeText, type WikiTypeDraft,
 } from './wiki-types.js'
 import { defaultKnowledgeRoot, failure, KnowledgeRuntime, success } from './runtime.js'
@@ -592,7 +592,6 @@ export class KnowledgeBases {
       layer: patch.layer ?? existing.layer,
       sections: patch.sections ?? existing.sections,
       fields: patch.fields ?? existing.fields,
-      sourceTypes: patch.sourceTypes ?? existing.sourceTypes,
       examples: patch.examples ?? existing.examples,
     }
     const problem = validateWikiTypeText(merged)
@@ -606,7 +605,6 @@ export class KnowledgeBases {
       layer: merged.layer === 'instance' ? 'instance' : 'type',
       sections,
       fields,
-      sourceTypes: this.stringList(merged.sourceTypes),
       examples: this.stringList(merged.examples),
       template: templateCardFor(sections, fields),
       enabled: patch.enabled === undefined ? existing.enabled : patch.enabled !== false,
@@ -664,7 +662,6 @@ export class KnowledgeBases {
       layer: draft.layer === 'instance' ? 'instance' : 'type',
       sections,
       fields,
-      sourceTypes: this.stringList(draft.sourceTypes),
       examples: this.stringList(draft.examples),
       template: templateCardFor(sections, fields),
       enabled: true,
@@ -683,15 +680,21 @@ export class KnowledgeBases {
    *
    * 与 `normalizeSourceTypes` 同一套语义：老配置（没有 `wikiTypes` 字段）升级时补齐内置，
    * 缺失的内置类型被恢复（内置只允许停用，不允许删除）。
+   *
+   * 0040 的两次改名（`check` → `check_point`、`failure-mode` → `failure_reason`）在这里
+   * 也认别名：存量配置里那一项写着旧 id，不认的话它会被当成一个**自定义类型**留下来，
+   * 而内置的那一项会被补回来 —— 于是注册表里同时有 `diagnosis/check` 与
+   * `diagnosis/check-point` 两个类型，卡片该归哪个就再也说不清了。
    */
   private normalizeWikiTypes(raw: unknown): WikiTypeDef[] {
     const persisted = Array.isArray(raw) ? raw : []
     const byId = new Map<string, Record<string, unknown>>()
     for (const item of persisted) {
       const value = record(item)
-      const id = typeof value.id === 'string' ? value.id.trim() : ''
+      const rawId = typeof value.id === 'string' ? value.id.trim() : ''
+      const id = LEGACY_WIKI_TYPE_IDS[rawId] ?? rawId
       if (!id || !WIKI_TYPE_ID_PATTERN.test(id) || byId.has(id)) continue
-      byId.set(id, value)
+      byId.set(id, { ...value, id })
     }
     const defaults = defaultWikiTypes()
     const builtins = defaults.map(def => {
@@ -703,7 +706,7 @@ export class KnowledgeBases {
     const customs: WikiTypeDef[] = []
     for (const [id, value] of byId) {
       if (isBuiltinWikiType(id)) continue
-      const base: WikiTypeDef = { id, label: id, description: '', layer: 'type', sections: [], fields: [], sourceTypes: [], examples: [], template: '', enabled: true, builtin: false, cardCount: 0 }
+      const base: WikiTypeDef = { id, label: id, description: '', layer: 'type', sections: [], fields: [], examples: [], template: '', enabled: true, builtin: false, cardCount: 0 }
       const draft = this.wikiTypeFromRecord(base, value)
       // 只有能写出骨架的自定义类型才值得留下；否则它既没有模板也校验不了。
       if (validateWikiTypeText(draft).ok) customs.push(draft)
@@ -722,7 +725,6 @@ export class KnowledgeBases {
       layer: value.layer === 'instance' ? 'instance' : base.layer,
       sections: sections.length > 0 ? sections : base.sections.map(section => ({ ...section })),
       fields: Array.isArray(value.fields) ? fields : base.fields.map(field => ({ ...field })),
-      sourceTypes: Array.isArray(value.sourceTypes) ? this.stringList(value.sourceTypes) : [...base.sourceTypes],
       examples: this.stringList(value.examples).length > 0 ? this.stringList(value.examples) : [...base.examples],
       template: textOr(value.template, base.template),
       enabled: value.enabled !== false,
@@ -735,7 +737,7 @@ export class KnowledgeBases {
   private wikiTypesDifferFromDefaults(types: WikiTypeDef[]): boolean {
     const signature = (list: WikiTypeDef[]): string => JSON.stringify(list.map(def => ({
       id: def.id, label: def.label, description: def.description, layer: def.layer, enabled: def.enabled,
-      sections: def.sections, fields: def.fields, sourceTypes: def.sourceTypes, examples: def.examples,
+      sections: def.sections, fields: def.fields, examples: def.examples,
     })))
     const defaults = defaultWikiTypes()
     if (types.length !== defaults.length) return true
@@ -880,18 +882,22 @@ export class KnowledgeBases {
   /**
    * 把磁盘上的 `sourceTypes` 规整成一个**必定包含全部内置分类**的合法注册表。
    *
-   * 两个关键行为：
+   * 三个关键行为：
    * 1. 老注册表（没有 `sourceTypes` 字段）升级时自动补上全部内置分类；
-   * 2. 任何缺失的内置分类都会被补回来——内置分类只允许停用，不允许删除。
+   * 2. 任何缺失的内置分类都会被补回来——内置分类只允许停用，不允许删除；
+   * 3. **改名过的内置分类按别名认**（`LEGACY_SOURCE_TYPE_IDS`）：存量配置里那一项写着
+   *    旧 id，不认的话它会被当成一个自定义分类留下来，而新的内置项同时被补回来 ——
+   *    于是「注册表里到底有什么」永远说不清。
    */
   private normalizeSourceTypes(raw: unknown): SourceTypeDef[] {
     const persisted = Array.isArray(raw) ? raw : []
     const byId = new Map<string, Record<string, unknown>>()
     for (const item of persisted) {
       const value = record(item)
-      const id = typeof value.id === 'string' ? value.id.trim() : ''
+      const rawId = typeof value.id === 'string' ? value.id.trim() : ''
+      const id = LEGACY_SOURCE_TYPE_IDS[rawId] ?? rawId
       if (!id || !SOURCE_TYPE_ID_PATTERN.test(id) || byId.has(id)) continue
-      byId.set(id, value)
+      byId.set(id, { ...value, id })
     }
     const defaults = defaultSourceTypes()
     const builtins = defaults.map(def => {
@@ -1065,7 +1071,6 @@ export class KnowledgeBases {
         layer: value.layer === 'instance' ? 'instance' : previous.layer,
         sections: Array.isArray(value.sections) ? value.sections : previous.sections,
         fields: Array.isArray(value.fields) ? value.fields : previous.fields,
-        sourceTypes: Array.isArray(value.sourceTypes) ? value.sourceTypes : previous.sourceTypes,
         examples: Array.isArray(value.examples) ? value.examples : previous.examples,
       }
       const problem = validateWikiTypeText(draft)
@@ -1079,7 +1084,6 @@ export class KnowledgeBases {
         layer: draft.layer === 'instance' ? 'instance' : 'type',
         sections,
         fields,
-        sourceTypes: this.stringList(draft.sourceTypes),
         examples: this.stringList(draft.examples),
         template: templateCardFor(sections, fields),
         enabled: value.enabled === undefined ? previous.enabled : value.enabled !== false,
@@ -1098,7 +1102,6 @@ export class KnowledgeBases {
         layer: value.layer === 'instance' ? 'instance' : previous?.layer ?? 'type',
         sections: Array.isArray(value.sections) ? value.sections : previous?.sections ?? [],
         fields: Array.isArray(value.fields) ? value.fields : previous?.fields ?? [],
-        sourceTypes: Array.isArray(value.sourceTypes) ? value.sourceTypes : previous?.sourceTypes ?? [],
         examples: Array.isArray(value.examples) ? value.examples : previous?.examples ?? [],
       }
       const problem = previous ? validateWikiTypeText(draft) : validateWikiTypeDraft(draft, new Set(existing.map(def => def.id)))
@@ -1112,7 +1115,6 @@ export class KnowledgeBases {
         layer: draft.layer === 'instance' ? 'instance' : 'type',
         sections,
         fields,
-        sourceTypes: this.stringList(draft.sourceTypes),
         examples: this.stringList(draft.examples),
         template: templateCardFor(sections, fields),
         enabled: value.enabled === undefined ? previous?.enabled ?? true : value.enabled !== false,