dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/client/NodeSettings.tsx

@@ -0,0 +1,392 @@
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react'
+import { Button, Input, SelectMenu, Switch, cn } from '@tita-data-agent/ui/components'
+import { AlertCircle, Check, LoaderCircle, SlidersHorizontal } from '@tita-data-agent/ui/icons'
+import { DirectoryPickerField } from './DirectoryPicker.tsx'
+import { InfoHint } from './InfoHint.tsx'
+
+/**
+ * 方案级设置。
+ *
+ * 0025：设置**不再挂在架构节点上**。每个字段组由它真正生效的那个功能 tab 渲染：
+ * 意图路由在「意图 → 配置」，收录 / 存储在「知识库 → SourceRaw」，构建在「知识库 →
+ * 知识图谱」，召回在「知识库 → 召回」，重排在「知识库 → 重排」。
+ *
+ * 0029 把后半句推翻了：**知识库相关的设置组全部收进顶部齿轮的抽屉里**，知识库
+ * 各个分栏只留内容。理由是分栏的读法是「这条链路上发生了什么」，而设置是「这个
+ * 方案怎么跑」—— 把旋钮散在每一段的正文里，用户要改一个参数就得先想「它属于
+ * 哪一段」，而那个归属本来就是实现细节。现在归属只有一个：设置。
+ *
+ * 同一个 0029 里，设置**不再有保存按钮**：改动即生效。设置是几个标量，没有「一次
+ * 提交一组变更」的事务语义，攒着不写只会制造「我改了但它没生效」这一种失败。
+ *
+ * `KnowledgePanel` still binds the `tita-data-agent-*` namespaces, so these forms read
+ * and write the same Host settings as before.
+ */
+
+export interface SettingsSnapshot {
+  status: 'loading' | 'ready' | 'unavailable'
+  value?: Record<string, unknown>
+  /**
+   * Raw user layer as stored. A field's **presence** here (not its value) is what
+   * marks it overridden, so editors can offer "恢复默认" honestly.
+   */
+  user?: unknown
+  writable?: boolean
+  mode?: 'host' | 'memory'
+  revision?: number
+}
+
+export interface SettingsScopeLike {
+  getSnapshot(): SettingsSnapshot
+  subscribe(listener: () => void): () => void
+  set(field: string, value: unknown): Promise<void>
+  /** Clear the user override so the field reverts to the composition default. */
+  unset?(field: string): Promise<void>
+}
+
+/** 设置组。`compile` 已撤（schema 类型归 Wiki 类型注册表），不再是一个设置组。 */
+export type SettingsNode = 'intent' | 'storage' | 'build' | 'recall' | 'context'
+
+interface FieldSpec {
+  key: string
+  label: string
+  kind: 'text' | 'number' | 'select' | 'toggle' | 'picker'
+  fallback: string | number | boolean
+  hint?: string
+  options?: Array<{ value: string; label: string }>
+  /** Comma-separated array field: shown as text, saved as `string[]`. */
+  list?: boolean
+}
+
+interface NodeSpec {
+  scope: 'intent' | 'knowledge'
+  title: string
+  description: string
+  fields: FieldSpec[]
+}
+
+export const NODE_SETTINGS: Record<SettingsNode, NodeSpec> = {
+  intent: {
+    scope: 'intent',
+    title: '意图路由设置',
+    description: '控制 Agent 如何理解问题并组织任务。分类与 act 词表在「意图 → 意图配置」里编辑，这里只管下面两个数值。',
+    fields: [
+      { key: 'clarifyThreshold', label: '澄清阈值', kind: 'number', fallback: 0.65, hint: '低于它的记录标 lowConfidence，只标注不拦截' },
+      { key: 'ttlSeconds', label: 'Intent TTL（秒）', kind: 'number', fallback: 600 },
+      // 0023：`routingPromptEnabled` 与 `maxComposeDepth` 都已移除。前者是因为分类规则
+      // 随 `intent_record` 的工具描述一起下发、必须始终在场（没有关闭这一说）；后者是
+      // 既不在 schema 里也没人读的死开关。真正生效却一直缺入口的 `fallbackEnabled` 补上。
+      { key: 'fallbackEnabled', label: 'Host 兜底记录', kind: 'toggle', fallback: true, hint: '模型漏调 intent_record 时，轮次结束补一条 source=fallback 的 unknown 记录' },
+    ],
+  },
+  /**
+   * 存储位置 —— 0029 的**第一块**，也是唯一一块「决定别的东西在哪」的设置。
+   *
+   * 它只有一个字段：Tita Agent 根路径。知识树、交付物、临时文件都从它推出来，
+   * 所以用户不需要理解四段结构就能用，而四段结构又必须**被看见**（见
+   * `LayoutPreview`）—— 否则「我的东西在哪」还是要靠猜。
+   */
+  storage: {
+    scope: 'knowledge',
+    title: '存储设置',
+    description: '知识树、记忆、意图记录、临时文件与家当都在这里。交付物不在这里 —— 它落在工作区的 output/<日期>/。',
+    fields: [
+      { key: 'agentRoot', label: 'Tita Agent 根路径', kind: 'picker', fallback: '', hint: '改完根路径后重新打开 Tita Data Agent' },
+    ],
+  },
+  // 0025：`compile` 设置组已撤。它曾经只有一个 `schemaTypes` 逗号分隔文本框，
+  // 而类型闸门读的一直是 Wiki 类型注册表……那个字段既不参与校验也不被生成逻辑读取，
+  // 是 0013 处理 `sourceAppendTypes` 时同一类假开关。schema 的入口只有一个：
+  // 「知识库 → Wiki → Wiki 类型」。
+  build: {
+    scope: 'knowledge',
+    title: '构建设置',
+    description: 'wikiNotes 的向量编码方式与构建所用的 Python 环境。模型不可用时会降级到关键词路。',
+    fields: [
+      { key: 'embeddingProvider', label: 'Embedding Provider', kind: 'select', fallback: 'wemm-python', options: [{ value: 'wemm-python', label: 'WeMM Python（本地）' }, { value: 'ollama', label: 'Ollama（文本）' }, { value: 'none', label: '关闭（FTS fallback）' }] },
+      { key: 'embeddingDevice', label: '运行设备', kind: 'select', fallback: 'auto', options: [{ value: 'auto', label: '自动（优先 MPS）' }, { value: 'mps', label: 'Apple MPS' }, { value: 'cpu', label: 'CPU' }] },
+      { key: 'embeddingModel', label: 'Embedding Model', kind: 'text', fallback: '', hint: '本地模型目录，或一个 HuggingFace 模型名' },
+      { key: 'embeddingBaseUrl', label: 'Embedding 地址', kind: 'text', fallback: 'http://127.0.0.1:11434' },
+      { key: 'embeddingDimension', label: '向量维度', kind: 'number', fallback: 1024 },
+      { key: 'embeddingBatchSize', label: 'Embedding 批大小', kind: 'number', fallback: 8 },
+      { key: 'embeddingTimeoutMs', label: '编码超时（毫秒）', kind: 'number', fallback: 120000 },
+      { key: 'python', label: 'Python', kind: 'text', fallback: '', hint: '解释器路径；留空用根路径下那个本地环境' },
+    ],
+  },
+  recall: {
+    scope: 'knowledge',
+    title: '知识库召回设置',
+    description: '两路召回（关键词 BM25 + 向量）各自超采成一个候选池，融合（RRF）后交给重排。知识图谱不再是一路，它只给候选池里的条目加权。',
+    fields: [
+      { key: 'recallTopK', label: '最终条数（hits）', kind: 'number', fallback: 10, hint: '1–50，默认 10。这是给模型的最终条数，不是召回深度' },
+      { key: 'recallCandidatePool', label: '候选池深度', kind: 'number', fallback: 50, hint: '1–200，默认 50。融合与重排都作用在它上面 —— 太小则重排救不回排在窗口外的那条' },
+      { key: 'recallMode', label: '默认召回路线', kind: 'select', fallback: 'hybrid', options: [{ value: 'hybrid', label: 'Hybrid（关键词 + 向量 + 图谱 boost）' }, { value: 'vector', label: '仅向量' }, { value: 'fts', label: '仅关键词' }, { value: 'graph', label: '同 Hybrid（图谱已不是独立一路）' }] },
+      { key: 'keywordThreshold', label: '关键词阈值', kind: 'number', fallback: 0.3, hint: '0–1，默认 0.3。归一化 BM25 的相对阈值：挡得住弱命中，挡不住「整批都弱」' },
+      { key: 'vectorThreshold', label: '向量阈值（余弦）', kind: 'number', fallback: 0.15, hint: '−1–1，默认 0.15。**绝对**阈值，弃答主要靠它' },
+    ],
+  },
+  context: {
+    scope: 'knowledge',
+    title: '知识库重排设置',
+    description: 'BERT cross-encoder 对**候选池**精排，低于阈值的一律丢弃，再取上下文条数。阈值是整条链路里唯一跨查询可比的相关性判据，所以「弃答」主要靠它。',
+    fields: [
+      { key: 'contextTopN', label: '上下文 TopN', kind: 'number', fallback: 5, hint: '1–recallTopK，默认 5。同一张 wiki 最多 2 条，其余名额留给别的卡片' },
+      { key: 'rerankThreshold', label: '重排阈值', kind: 'number', fallback: 0.2, hint: '−10–10，默认 0.2。原始 cross-encoder 分（与 WeKnora 同刻度）：低于它的不进上下文' },
+      { key: 'rerankProvider', label: 'Rerank Provider', kind: 'select', fallback: 'bert-python', options: [{ value: 'bert-python', label: 'BERT Python（本地）' }, { value: 'none', label: '关闭（按融合分数）' }] },
+      { key: 'rerankModel', label: 'Rerank Model', kind: 'text', fallback: '', hint: '本地模型目录，或一个 HuggingFace 模型名' },
+      { key: 'rerankTimeoutMs', label: '重排超时（毫秒）', kind: 'number', fallback: 60000 },
+    ],
+  },
+}
+
+/** 知识库那一组设置组的**展示顺序**。抽屉按它渲染。 */
+export const KNOWLEDGE_SETTINGS_ORDER: SettingsNode[] = ['storage', 'build', 'recall', 'context']
+
+/**
+ * 卡片头上的「参数」入口（0034）。
+ *
+ * 0029 把设置收进抽屉之后，知识库的每一栏都留了一句「设置已移到顶部齿轮」——
+ * 那是一块**路牌**：它说明入口离「你会想起要改它」的那一刻太远。chip 把同一件事
+ * 变成一次点击，而且它**不新开一个家** —— 打开的还是那一个抽屉、那一块面板，只是
+ * 落到对应的分块上（`highlight` + 滚动定位）。
+ *
+ * 文案取自 `NODE_SETTINGS[target].title`，与抽屉里的分块标题**同源**：两处各写一份，
+ * 迟早会出现 chip 写「构建参数」而抽屉写「构建设置」。
+ */
+export function SettingsChip({ target, onOpen }: { target: SettingsNode; onOpen: (target: SettingsNode) => void }): ReactNode {
+  const title = NODE_SETTINGS[target].title
+  return <Button
+    variant="ghost"
+    size="sm"
+    title={`打开设置 · ${title}`}
+    onClick={() => onOpen(target)}
+  ><SlidersHorizontal size={12} />{title}</Button>
+}
+
+/** 分块锚点：抽屉靠它把「参数」chip 的落点滚到眼前。 */
+export function settingsAnchorId(node: SettingsNode): string {
+  return `tita-settings-${node}`
+}
+
+const UNAVAILABLE_SNAPSHOT: SettingsSnapshot = { status: 'unavailable', writable: false, mode: 'memory' }
+
+/**
+ * Settings scope → snapshot。导出是因为召回 / 重排面板也要读同一份值做默认参数：
+ * 三个面板各订阅一次、各算一次默认值，就会出现「设置里 topK=20、召回面板还按 10 跑」。
+ */
+export function useScope(scope: SettingsScopeLike | undefined): SettingsSnapshot {
+  return useSyncExternalStore(
+    listener => scope?.subscribe(listener) ?? (() => undefined),
+    () => scope?.getSnapshot() ?? UNAVAILABLE_SNAPSHOT,
+    () => scope?.getSnapshot() ?? UNAVAILABLE_SNAPSHOT,
+  )
+}
+
+function readField(spec: FieldSpec, value: Record<string, unknown> | undefined): string | boolean {
+  const raw = value?.[spec.key]
+  if (spec.kind === 'toggle') return typeof raw === 'boolean' ? raw : spec.fallback as boolean
+  if (Array.isArray(raw)) return raw.map(String).join(', ')
+  if (raw === undefined || raw === null) return String(spec.fallback)
+  return String(raw)
+}
+
+function writeField(spec: FieldSpec, draft: string | boolean): unknown {
+  if (spec.kind === 'toggle') return Boolean(draft)
+  if (spec.kind === 'number') return Number(draft)
+  if (spec.list) return String(draft).split(',').map(item => item.trim()).filter(Boolean)
+  return String(draft)
+}
+
+/** 只有打字型的字段需要防抖；开关与下拉点一下就是一个决定，立刻写。 */
+function needsDebounce(spec: FieldSpec): boolean {
+  return spec.kind === 'text' || spec.kind === 'number'
+}
+
+function TextField({ spec, value, onChange, disabled, resolved }: { spec: FieldSpec; value: string; onChange: (value: string) => void; disabled: boolean; resolved?: string }) {
+  return <label className="tita-settingField">
+    <span>{spec.label}</span>
+    {/* 留空 = 自动。占位符显示**解析后**的真实路径 —— 否则「自动」等于没说。 */}
+    <Input
+      type={spec.kind === 'number' ? 'number' : 'text'}
+      value={value}
+      disabled={disabled}
+      {...(resolved ? { placeholder: resolved } : {})}
+      onChange={event => onChange(event.target.value)}
+    />
+    {/* 说明跟在它解释的那个字段下面，不是攒成一堆放在面板底部 ——
+        底部那行「字段名：说明；字段名：说明」是把标签和说明各念一遍。 */}
+    {spec.hint && <small className="tita-settingHint">{spec.hint}</small>}
+    {resolved && <small className="tita-settingHint">留空 = 自动：<code>{resolved}</code></small>}
+  </label>
+}
+
+/**
+ * A dropdown field. The wrapper is a `<div>`, not the `<label>` the text and
+ * toggle fields use: the control is a `<button>` now (Radix's trigger), and a
+ * `<label>` around a button makes the visible field name an ambiguous second
+ * name. The name travels on the trigger's `aria-label` instead, and the visible
+ * `<span>` stays the thing a person reads.
+ */
+function SelectField({ spec, value, onChange, disabled }: { spec: FieldSpec; value: string; onChange: (value: string) => void; disabled: boolean }) {
+  return <div className="tita-settingField">
+    <span>{spec.label}</span>
+    <SelectMenu
+      value={value}
+      disabled={disabled}
+      onValueChange={onChange}
+      options={spec.options ?? []}
+      aria-label={spec.label}
+    />
+    {spec.hint && <small className="tita-settingHint">{spec.hint}</small>}
+  </div>
+}
+
+/**
+ * 开关字段。
+ *
+ * 它现在和文本 / 下拉 / 目录选择**共用同一套结构**：标签在上、控件在中、说明在下。
+ *
+ * 原来它是「带边框和底色的整行」，另外三种是无边框的堆叠 —— 四种字段两种长相，而且
+ * 标签用 `<strong>`、说明塞在标签里，对齐方式也对不上。更实际的问题是那个边框：
+ * 小节本身已经是一张卡片，字段再包一层就是**卡片套卡片**。
+ */
+function ToggleField({ spec, value, onChange, disabled }: { spec: FieldSpec; value: boolean; onChange: (value: boolean) => void; disabled: boolean }) {
+  return <label className="tita-settingField">
+    <span>{spec.label}</span>
+    <Switch checked={value} disabled={disabled} onCheckedChange={onChange} />
+    {spec.hint && <small className="tita-settingHint">{spec.hint}</small>}
+  </label>
+}
+
+/** 写入状态。`saved` 只短暂出现，`error` 留到下一次改动。 */
+type SaveState = 'idle' | 'saving' | 'saved' | 'error'
+
+export function NodeSettingsPanel({ node, intent, knowledge, extra, pickerKind = null, resolved = {}, highlight = false }: {
+  node: SettingsNode
+  intent?: SettingsScopeLike
+  knowledge?: SettingsScopeLike
+  /** 字段之后追加的内容。存储组用它放四段布局预览 —— 预览是那个字段的**结果**。 */
+  extra?: ReactNode
+  /** 宿主提供哪种目录选择交互；`null` 表示没挂目录选择器。 */
+  pickerKind?: string | null
+  /** 字段键 → 「留空时实际会用什么」。0029：家当路径空着就是跟着根路径走。 */
+  resolved?: Record<string, string>
+  /** 由卡片头的「参数」chip 定位过来的那一块：一次性强调 + 接管焦点。 */
+  highlight?: boolean
+}): ReactNode {
+  const spec = NODE_SETTINGS[node]
+  const scope = spec.scope === 'intent' ? intent : knowledge
+  const state = useScope(scope)
+  const [draft, setDraft] = useState<Record<string, string | boolean>>({})
+  const [saveState, setSaveState] = useState<SaveState>('idle')
+  const [error, setError] = useState<string | null>(null)
+  /** 待落地的防抖写入，按字段键索引。 */
+  const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>())
+  /** 正在进行的写入数。用它挡住「写完 → revision 变 → 重置草稿」把输入抹掉。 */
+  const inflight = useRef(0)
+  const savedTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    // 有写入在飞的时候不重置草稿：那一刻 `state.value` 还是旧值，重置会把用户刚
+    // 敲进去的字符弹回去。写入落地后 revision 会再变一次，那次才重置。
+    if (inflight.current > 0) return
+    setDraft(Object.fromEntries(spec.fields.map(field => [field.key, readField(field, state.value)])))
+  }, [node, state.revision, state.value])
+
+  // 卸载时把还没落地的防抖写入丢掉并清计时器：一个已经离开的面板不该再写设置。
+  useEffect(() => () => {
+    for (const timer of timers.current.values()) clearTimeout(timer)
+    timers.current.clear()
+    if (savedTimer.current) clearTimeout(savedTimer.current)
+  }, [])
+
+  const disabled = !state.writable || state.status !== 'ready'
+
+  const persist = useCallback(async (field: FieldSpec, raw: string | boolean): Promise<void> => {
+    if (!scope || disabled) return
+    inflight.current += 1
+    setSaveState('saving'); setError(null)
+    try {
+      await scope.set(field.key, writeField(field, raw))
+      setSaveState('saved')
+      if (savedTimer.current) clearTimeout(savedTimer.current)
+      // 「已保存」只是一个确认，不是一条状态：两秒后收回，免得它常驻成一个
+      // 用户以为要点的按钮。
+      savedTimer.current = setTimeout(() => setSaveState(current => current === 'saved' ? 'idle' : current), 2000)
+    } catch (cause) {
+      setSaveState('error')
+      setError(cause instanceof Error ? cause.message : '设置保存失败')
+    } finally {
+      inflight.current -= 1
+    }
+  }, [scope, disabled])
+
+  const update = (field: FieldSpec, value: string | boolean): void => {
+    setDraft(current => ({ ...current, [field.key]: value }))
+    if (!needsDebounce(field)) {
+      void persist(field, value)
+      return
+    }
+    const existing = timers.current.get(field.key)
+    if (existing) clearTimeout(existing)
+    timers.current.set(field.key, setTimeout(() => {
+      timers.current.delete(field.key)
+      void persist(field, value)
+    }, 600))
+  }
+
+  const meta = state.status === 'loading'
+    ? '正在读取配置…'
+    : state.status === 'unavailable'
+      ? '设置服务不可用'
+      : saveState === 'saving'
+        ? '保存中…'
+        : saveState === 'saved'
+          ? '已保存'
+          : saveState === 'error'
+            ? '未保存'
+            : state.mode === 'host' ? '改动即生效' : '当前会话'
+
+  const anchor = settingsAnchorId(node)
+  const titleId = `${anchor}-title`
+
+  return <section
+    id={anchor}
+    className={cn('tita-settingsSection', highlight && 'tita-settingsSectionOn')}
+    // `tabIndex={-1}` 让「参数」chip 打开的抽屉能把焦点交给这一块：键盘用户落到
+    // 参数所在的地方，而不是抽屉顶部再自己找一遍。`aria-labelledby` 顺带把这一块
+    // 的名字给它 —— 抽屉里六块并排，读屏用户需要知道自己在哪一块上。
+    tabIndex={-1}
+    aria-labelledby={titleId}
+  >
+    <div className="tita-settingsSectionHeader">
+      {/* 说明从标题下面挪到图标后面：常驻文字会把控件挤出首屏，而说明本身有价值。
+          见 `InfoHint`。 */}
+      <div><h3 id={titleId}>{spec.title}<InfoHint text={spec.description} /></h3></div>
+      <div className={`tita-settingMeta${saveState === 'error' ? ' tita-settingMetaBad' : ''}`} role="status" aria-live="polite">
+        {saveState === 'saving' && <LoaderCircle size={11} className="tita-spin" />}
+        {saveState === 'saved' && <Check size={11} />}
+        {meta}
+      </div>
+    </div>
+    {error && <div className="tita-settingsError" role="alert"><AlertCircle size={13} />{error}</div>}
+    <div className="tita-settingsGrid">
+      {spec.fields.map(field => field.kind === 'toggle'
+        ? <ToggleField key={field.key} spec={field} value={Boolean(draft[field.key])} onChange={value => update(field, value)} disabled={disabled} />
+        : field.kind === 'select'
+          ? <SelectField key={field.key} spec={field} value={String(draft[field.key] ?? '')} onChange={value => update(field, value)} disabled={disabled} />
+          : field.kind === 'picker'
+            ? <DirectoryPickerField
+              key={field.key}
+              label={field.label}
+              value={String(draft[field.key] ?? '')}
+              disabled={disabled}
+              pickerKind={pickerKind}
+              onError={setError}
+              onChange={value => update(field, value)}
+            />
+            : <TextField key={field.key} spec={field} value={String(draft[field.key] ?? '')} onChange={value => update(field, value)} disabled={disabled} {...(resolved[field.key] ? { resolved: resolved[field.key]! } : {})} />)}
+    </div>
+    {extra}
+  </section>
+}

package/src/client/PreviewSections.tsx

@@ -0,0 +1,116 @@
+/**
+ * 预览抽屉的三个公共分块（0035）：**元信息 → 内容 → 版本**。
+ *
+ * SourceRaw 的原文预览与 wiki 卡片的预览必须是**同一种形态**。两处各写一遍结构，
+ * 就会出现「一个把元信息放最上面、一个放最下面」「一个能给文本预览、另一个不能」
+ * 这类漂移 —— 而它们回答的是同一个问题：这份东西是什么、写了什么、改过几次。
+ *
+ * 这一层只定义**顺序与分块**（小节标题 + 计数 + 内容），字段仍由调用方给：原文有
+ * `content_hash`，卡片有 `entity_id`，本来就不一样，硬凑成同一张表只会两处都别扭。
+ * 时间也由调用方格式化（见 `format.ts`）—— 元信息用标准格式，列表行用紧凑格式。
+ */
+
+import { useState, type ReactNode } from 'react'
+import { FileCode2, FileText, History, Image, ListTree } from '@tita-data-agent/ui/icons'
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@tita-data-agent/ui/components'
+import { VersionManager, type VersionManagerProps } from '@tita-data-agent/ui/versions'
+// 平台提供的 Markdown 原子（DSH 的模块表里有它，本插件的 client bundle 也已把它列为
+// external）。原文与卡片正文本身就是 Markdown，用 `<pre>` 显示等于把标题、表格、链接
+// 全都拍平成源码 —— 所以默认阅读态走它，源码视图是**另一个**选项，不是替代品。
+import { MarkdownText, type MarkdownLabels } from '@deepseek-ai/dsh-client-ui-primitives'
+import { formatBytes } from './format.ts'
+import { styles } from './styles.ts'
+
+/**
+ * Markdown 原子的界面文案。必须是**模块级常量**：平台明确要求这个对象引用稳定
+ * （换一个身份会让流式渲染的缓存整体作废），在渲染里现造一个对象正好踩中那条。
+ *
+ * 这三个词与 `plugins/dsh-data-notebook` 的同名常量逐字相同。没有抽回 `packages/ui`
+ * 是刻意的：`MarkdownLabels` 的类型来自**宿主提供的**平台包，而 data-notebook 的
+ * 独立整页入口必须能把平台包整块排除在 bundle 之外 —— 共享层一旦引它，那条「独立
+ * 页面不拉平台依赖」的约束就断了。三行文案不值得拿那条约束换。
+ */
+const MARKDOWN_LABELS: MarkdownLabels = {
+  code: { copyLabel: '复制', copiedLabel: '已复制' },
+  footnotes: '脚注',
+}
+
+/** 正文只渲染前 2 万字符：更长的原文在抽屉里没有阅读意义，也会拖慢 Markdown 渲染。 */
+const PREVIEW_CHARS = 20000
+
+export interface PreviewRow {
+  label: string
+  value: ReactNode
+  /** 等宽显示：hash / id / 路径这类要逐字比对的值。 */
+  code?: boolean
+}
+
+/** 元信息：一张两列的事实表。标签列宽固定，所以标签要短且彼此对齐。 */
+export function PreviewMeta({ rows }: { rows: PreviewRow[] }): ReactNode {
+  // 每一块都包一层 `drawerSection`：标题与它自己的内容是一块，块与块之间的间距由
+  // 外层 `drawerStack` 给。不包的话「元信息」标题和它下面那张表是两个同级节点，
+  // 外层 gap 会把标题和自己的表也拉开。
+  return <section className={styles.drawerSection}>
+    <div className={styles.kbSubHead}><h4><ListTree size={13} />元信息</h4></div>
+    <dl className={styles.kbKv}>
+      {rows.map(row => <div key={row.label}>
+        <dt>{row.label}</dt>
+        <dd className={row.code ? styles.kbCode : undefined}>{row.value}</dd>
+      </div>)}
+    </dl>
+  </section>
+}
+
+export interface PreviewAsset { rel: string; url: string; bytes: number }
+
+/**
+ * 内容：小节标题 + 视图切换 + 正文。
+ *
+ * 两个视图是**同一份内容**的两种读法：Markdown 是阅读态（默认），文本是源码态，
+ * 用于逐字核对 —— 与版本 diff 是同一种读法。切换不重新取数，也不改内容。
+ * 图片素材排在这一块的末尾：它也是内容，只是渲染器没能就地展开的那部分。
+ */
+export function PreviewContent({ content, assets = [] }: { content: string; assets?: PreviewAsset[] }): ReactNode {
+  const [view, setView] = useState<'md' | 'text'>('md')
+  const shown = content.slice(0, PREVIEW_CHARS)
+  const clipped = shown.length < content.length
+  return <section className={styles.drawerSection}><Tabs value={view} onValueChange={next => setView(next as 'md' | 'text')}>
+    <div className={styles.kbSubHead}>
+      <h4><FileText size={13} />内容</h4>
+      <TabsList className={`${styles.tabsList} ${styles.kbViewTabs}`}>
+        <TabsTrigger value="md">Markdown</TabsTrigger>
+        <TabsTrigger value="text"><FileCode2 size={11} />文本</TabsTrigger>
+      </TabsList>
+      <span>{content.length} 字符{clipped ? ` · 只渲染前 ${shown.length}` : ''}</span>
+    </div>
+    <TabsContent value="md">
+      <div className={styles.kbMarkdown}><MarkdownText text={shown} labels={MARKDOWN_LABELS} /></div>
+    </TabsContent>
+    <TabsContent value="text">
+      <pre className={styles.kbPre}>{shown}</pre>
+    </TabsContent>
+    {assets.length > 0 && <>
+      <div className={styles.kbSubHead}><h4><Image size={13} />图片素材</h4><span>{assets.length} 张</span></div>
+      <div className={styles.kbAssets}>
+        {assets.map(asset => <figure key={asset.rel} className={styles.kbAsset}>
+          <img src={asset.url} alt={asset.rel} loading="lazy" />
+          <figcaption>{formatBytes(asset.bytes)}</figcaption>
+        </figure>)}
+      </div>
+    </>}
+  </Tabs></section>
+}
+
+/**
+ * 版本：小节标题 + 计数 + 一句「什么时候会留快照」+ 时间线。
+ *
+ * `hint` 不是可有可无的装饰：两种产物的快照触发条件不同（原文是内容变化，卡片是
+ * 正文变化 —— 只改状态不造版本），不写清楚，用户会以为「我改过它，为什么没有版本」。
+ */
+export function PreviewVersions({ hint, ...manager }: { hint?: string } & VersionManagerProps): ReactNode {
+  return <section className={styles.drawerSection}>
+    <div className={styles.kbSubHead}><h4><History size={13} />版本</h4><span>{manager.entries?.length ?? 0} 个</span></div>
+    {hint && <p className={styles.kbHint}>{hint}</p>}
+    <VersionManager {...manager} />
+  </section>
+}