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

package/src/client/KnowledgeBaseTab.tsx

@@ -0,0 +1,1454 @@
+/**
+ * 知识库 Tab —— 一个知识库的**内容**，按知识链路拆成四个分栏。
+ *
+ * 分栏与架构图上的节点对应（SourceRaw / Wiki / 知识图谱 / **召回重排**）。
+ * 0033 把「召回」与「重排」合成一栏：它们回答的是同一个问题（跑一次真实召回长什么样），
+ * 分栏时用户得先跑召回、再切到重排才能看到同一次运行的全貌。流水线上它们仍是两步，
+ * 合的是界面 —— 架构图里也仍是两个节点，只是都落到这一栏。
+ * 图上一个节点点「去配置」，落到的就是这里的某一栏。
+ *
+ * 0034 把这条分工线收干净了 —— **每一层只装一种东西，一个旋钮只有一个家**：
+ *
+ * 1. **四个分栏只装内容**：这一段的产物、计数、真实运行面板。分栏里不再有任何设置块，
+ *    也不再留「设置已移到顶部齿轮」那种**路牌**（路牌是搬迁留下的债，它说明入口离
+ *    「你会想起要改它」的那一刻太远）。参数改成卡片头上一枚「参数」chip：打开的还是
+ *    那一个设置抽屉，只是落到对应的分块上。
+ * 2. **设置抽屉装方案级参数**（存储 / 收录闸门 / 构建 / 召回 / 重排 / Agent preset）：
+ *    一个 namespace，整个方案一份。
+ * 3. **类型定义抽屉装本库词汇表**（来源类型 / Wiki 类型）：按知识库持久化，切库就换一套。
+ *    它与设置是**两种作用域**，所以是两个容器而不是一个 —— 见 `TypeDefinitionDrawer.tsx`。
+ *
+ * 产品逻辑参考腾讯 WeKnora：知识库是一等对象（独立配置、独立内容）。每个知识库有自己的
+ * 根目录、来源分类注册表与 Wiki 类型注册表；知识库下有文件列表，每个文件有详情页与版本
+ * 历史（可回滚）。
+ *
+ * 0029：「文件类型 → 解析引擎」那张规则表撤掉了 —— 它的 `engine` 一列没有任何一处读
+ * 它（真正选适配器的是转换内核自己的格式表）。上传选择框的 `accept` 改为问内核要，
+ * 文件类型筛选项与计数改为从这一库真实的文档推导。
+ *
+ * 0025 的两处结构性变化：
+ * 1. **编译设置里的「Schema 类型」撤掉**。wiki 类型注册表就是 schema，入口在「类型定义」；
+ *    那个逗号分隔的 `schemaTypes` 文本框既不参与校验也不被生成逻辑读取。
+ * 2. **Wiki 也有一等版本历史**。卡片每次正文变化先快照到 `04_memory/card-versions/`，
+ *    可以回滚，回滚本身也可回滚 —— 与 SourceRaw 用同一套模型。
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState, type ChangeEvent, type ReactNode } from 'react'
+import {
+  AlertCircle, Check, Eye, FileText, FileUp, FolderOpen,
+  Layers3, RefreshCw, Search, ShieldCheck, Tags, Trash2, Upload, X,
+} from '@tita-data-agent/ui/icons'
+import type { LucideIcon } from '@tita-data-agent/ui/icons'
+import { Badge, Button, Card, Input, Label, SelectMenu, cn } from '@tita-data-agent/ui/components'
+import {
+  Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle,
+  Drawer, DrawerBody, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle,
+} from '@tita-data-agent/ui/overlays'
+import { ObjectPicker } from '@tita-data-agent/ui/workspace'
+import { RestoreDialog, type VersionManagerEntry } from '@tita-data-agent/ui/versions'
+import { styles } from './styles.ts'
+import { formatBytes, formatDateTime, formatTime } from './format.ts'
+import { PreviewContent, PreviewMeta, PreviewVersions } from './PreviewSections.tsx'
+import type { KnowledgeTab } from './architecture.tsx'
+import { KnowledgeStepRail } from './KnowledgeStepRail.tsx'
+import { NodeSettingsPanel, SettingsChip, useScope, type SettingsNode, type SettingsScopeLike } from './NodeSettings.tsx'
+import { RecallPanel } from './RecallPanel.tsx'
+import { KnowledgeGraphView } from './KnowledgeGraphView.tsx'
+import type { GraphEdgeView, GraphNodeView } from './graph/layout.ts'
+import type { WikiTypeView } from './WikiTypeEditor.tsx'
+import { WikiFlowCard } from './WikiFlowCard.tsx'
+import { TypeDefinitionDrawer } from './TypeDefinitionDrawer.tsx'
+
+// ------------------------------------------------------------------ contract
+// Mirrors the plugin HTTP contract (see plugins/dsh-data-domain-knowledge/README.md).
+
+/**
+ * 一条来源业务分类（source_type，issue 0013）。
+ *
+ * 三档默认值刻意分开：`fallback` 必存不可停用、`builtin` 可改可停用不可删、
+ * 其余为用户自定义（可增可删）。`sourceCount > 0` 时不允许删除。
+ */
+export interface SourceTypeDef {
+  id: string
+  label: string
+  description: string
+  signals: string[]
+  excludes: string[]
+  enabled: boolean
+  builtin: boolean
+  fallback: boolean
+  sourceCount: number
+}
+
+export interface SourceClassifierStep {
+  type: string
+  rule: string
+  label: string
+  enabled: boolean
+  exists: boolean
+}
+
+/** 内置**只读**判定提示词：用户看得见、改不了。 */
+export interface SourceClassifierPrompt {
+  readonly: true
+  version: number
+  title: string
+  priority: Array<{ type: string; rule: string }>
+  steps: SourceClassifierStep[]
+  confidenceRule: string
+  fallback: { type: string; note: string }
+  escalation: { code: string; note: string }
+  extensionRule: string
+}
+
+export interface SourceTypeCatalog {
+  types: SourceTypeDef[]
+  classifierPrompt: SourceClassifierPrompt
+  fallbackTypeId: string
+  builtinIds: string[]
+}
+
+/**
+ * 分类编辑弹窗提交的草稿（0034）。signals / excludes 在弹窗里是多行文本，提交时按行拆。
+ *
+ * 类型定义在这里、写路径在 `saveSourceType`：抽屉（`TypeDefinitionDrawer`）只负责呈现
+ * 与它自己的弹窗状态，不自己发请求 —— 同一份数据不因为多了一个入口就多一个写入口。
+ */
+export interface SourceTypeDraft {
+  mode: 'create' | 'edit'
+  id: string
+  label: string
+  description: string
+  signals: string
+  excludes: string
+}
+
+export interface KnowledgeBase {
+  id: string
+  name: string
+  description: string
+  rootDir: string
+  isDefault: boolean
+  sourceTypes: SourceTypeDef[]
+  /** Wiki 卡片类型注册表（0024）。 */
+  wikiTypes: WikiTypeView[]
+  /** `report` 只标记问题，`strict` 拒绝不合规的写入。 */
+  wikiSchemaMode: 'strict' | 'report'
+  /** 计算字段：这套 schema 是否已偏离出厂定义。 */
+  wikiTypesCustomized: boolean
+  createdAt: string
+  updatedAt: string
+  sourceCount: number
+  cardCount: number
+  noteCount: number
+  buildVersion: number
+}
+
+export interface KnowledgeDocument {
+  docId: string
+  title: string
+  sourceType: string
+  /** 该分类是否仍在注册表里；false 时渲染成「未知分类」。 */
+  sourceTypeKnown?: boolean
+  sourceFormat: string
+  parser: string
+  externalId: string
+  contentHash: string
+  bytes: number
+  assetCount: number
+  createdAt: string
+  updatedAt: string
+  versionCount: number
+  relativePath: string
+  ext: string
+}
+
+export interface KnowledgeDocumentDetail extends KnowledgeDocument {
+  content: string
+  frontmatter: Record<string, unknown>
+  assets: Array<{ rel: string; bytes: number; url: string }>
+  lineage?: Record<string, string>
+}
+
+export interface DocumentVersion {
+  versionId: string
+  createdAt: string
+  contentHash: string
+  bytes: number
+  sourceFormat: string
+  label: string
+  isCurrent: boolean
+}
+
+/** Wiki 卡片（0025：带上 metadata，界面要能显示 schema 待补项）。 */
+export interface KnowledgeCardView {
+  entityId: string
+  entityType: string
+  title: string
+  status: string
+  summary?: string
+  content: string
+  sourceRefs: string[]
+  metadata?: Record<string, unknown>
+  updatedAt: string
+}
+
+/** 一张 wiki 卡片的历史版本快照。 */
+export interface WikiCardVersionView {
+  versionId: string
+  createdAt: string
+  contentHash: string
+  bytes: number
+  title: string
+  status: string
+  label: string
+  isCurrent: boolean
+}
+
+interface Envelope<T> { ok?: boolean; data?: T; warnings?: string[]; error?: { code?: string; message?: string; suggestion?: string } | null }
+
+async function requestJson<T>(url: string, init?: RequestInit): Promise<Envelope<T>> {
+  const response = await fetch(url, init)
+  const text = await response.text()
+  if (!text.trim()) throw new Error(`服务端返回空响应（HTTP ${response.status}）`)
+  let payload: Envelope<T>
+  try {
+    payload = JSON.parse(text) as Envelope<T>
+  } catch {
+    throw new Error(`服务端返回了无效响应（HTTP ${response.status}）`)
+  }
+  const error = payload.error
+  if (!response.ok || payload.ok === false) {
+    const detail = [error?.code, error?.message].filter(Boolean).join(' · ') || `请求失败（${response.status}）`
+    throw new Error(error?.suggestion ? `${detail} — ${error.suggestion}` : detail)
+  }
+  return payload
+}
+
+/** Text-ish formats the browser can read and POST as SourceRaw directly. */
+const DIRECT_READ_EXT = new Set(['.md', '.markdown', '.txt', '.json', '.tsv', '.csv', '.html'])
+
+const CONVERT_POLL_MS = 500
+const CONVERT_TIMEOUT_MS = 180_000
+
+interface Props {
+  visible: boolean
+  /** Tells the parent to refresh its own stats after a write. */
+  onChanged?: () => void
+  /** Lets the parent scope its recall test / upload to the selected base. */
+  onActiveBaseChange?: (base: { id: string; name: string } | null) => void
+  /** 知识库设置作用域：召回 / 重排面板读它算默认参数，收录闸门读它决定能不能上传。 */
+  knowledge?: SettingsScopeLike
+  /** 架构图节点跳转过来时要落到哪一栏。`nonce` 变化即重新应用。 */
+  focus?: { tab: KnowledgeTab; nonce: number }
+  /**
+   * 卡片头的「参数」chip 落到设置抽屉的哪一块（0034）。**设置不在这一层** —— 这里只
+   * 转交一个「打开并定位」的意图，抽屉与它读写的 scope 都还在 `KnowledgePanel` 手里。
+   */
+  onOpenSettings?: (target: SettingsNode) => void
+}
+
+/** 卡片 metadata 里的待补项（0024 的 report 模式会把问题留在卡片上）。 */
+function schemaIssuesOf(card: KnowledgeCardView): Array<{ level?: string; message?: string }> {
+  const raw = card.metadata?.schema_issues
+  return Array.isArray(raw) ? raw as Array<{ level?: string; message?: string }> : []
+}
+
+export function KnowledgeBaseTab({ visible, onChanged, onActiveBaseChange, knowledge, focus, onOpenSettings }: Props): ReactNode {
+  const [bases, setBases] = useState<KnowledgeBase[]>([])
+  const [activeId, setActiveId] = useState('')
+  const [documents, setDocuments] = useState<KnowledgeDocument[]>([])
+  const [cards, setCards] = useState<KnowledgeCardView[]>([])
+  const [total, setTotal] = useState(0)
+  const [query, setQuery] = useState('')
+  const [extFilter, setExtFilter] = useState('')
+  /**
+   * 来源分类筛选。**它同时是上传分类**：这个 select 回答的是同一个问题 ——
+   * 「这一份文件以什么业务身份进来」。分成两个控件就会出现「筛着 A 类，却把新文件
+   * 存成 B 类」，而两个控件还都叫「来源分类」。
+   */
+  const [typeFilter, setTypeFilter] = useState('')
+  /** Wiki 卡片列表的筛选（与 SourceRaw 那一块同形）。 */
+  const [cardQuery, setCardQuery] = useState('')
+  const [cardType, setCardType] = useState('')
+  const [cardStatus, setCardStatus] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [busy, setBusy] = useState<string | null>(null)
+  const [notice, setNotice] = useState<{ tone: 'success' | 'error'; text: string } | null>(null)
+  const [tab, setTab] = useState<KnowledgeTab>('source-raw')
+  const [editOpen, setEditOpen] = useState(false)
+  const [draft, setDraft] = useState({ id: '', name: '', description: '' })
+  /**
+   * 来源分类注册表（0013）。`active.sourceTypes` 提供分类行（含实时 sourceCount），
+   * `catalog` 只负责那段**内置只读**的判定提示词——它不随知识库变化，但仍按库
+   * 拉取，因为停用的分类要在提示词里标记出来。
+   */
+  const [catalog, setCatalog] = useState<SourceTypeCatalog | null>(null)
+  /**
+   * 「类型定义」抽屉（0034）：本库的词汇表 —— 来源分类 + Wiki 卡片 schema。
+   * 弹窗草稿在抽屉内部，这里只留开关与写路径。
+   */
+  const [typeDefOpen, setTypeDefOpen] = useState(false)
+  /** 上传 / 导入时用的来源分类；注册表变了要跟着回退，不能指向一个已停用的 id。 */
+  const [uploadType, setUploadType] = useState('document')
+  const [detail, setDetail] = useState<{ document: KnowledgeDocumentDetail; versions: DocumentVersion[] } | null>(null)
+  const [detailLoading, setDetailLoading] = useState(false)
+  const [restoreTarget, setRestoreTarget] = useState<VersionManagerEntry | null>(null)
+  /** Wiki 卡片详情与版本（0025）。 */
+  const [cardDetail, setCardDetail] = useState<{ card: KnowledgeCardView; versions: WikiCardVersionView[] } | null>(null)
+  const [cardLoading, setCardLoading] = useState(false)
+  const [cardRestore, setCardRestore] = useState<VersionManagerEntry | null>(null)
+  const [graph, setGraph] = useState<{ nodes: GraphNodeView[]; edges: GraphEdgeView[] }>({ nodes: [], edges: [] })
+  /** 当前知识库的编译统计：卡片版本数、增量计数、向量条目都只在这里有。 */
+  const [stats, setStats] = useState<Record<string, unknown>>({})
+  const importInput = useRef<HTMLInputElement>(null)
+  /**
+   * 上传选择框的 `accept`：转换内核报出来的扩展名 ∪ 浏览器能直读的扩展名。
+   *
+   * 拉一次就够 —— 内核的适配器表在一次进程里不变；拿不到就留空（不限制）。
+   */
+  const [acceptExts, setAcceptExts] = useState<string[]>([])
+  useEffect(() => {
+    if (!visible) return undefined
+    let alive = true
+    void requestJson<{ adapters?: Array<{ extensions?: string[] }> }>('/convert/api/capabilities')
+      .then(payload => {
+        if (!alive) return
+        const fromKernel = (payload.data?.adapters ?? []).flatMap(adapter => adapter.extensions ?? [])
+        setAcceptExts([...new Set([...fromKernel, ...DIRECT_READ_EXT])].sort())
+      })
+      .catch(() => { /* 内核不在就不限制：让内核给出准确的错误，比前端猜一张表强 */ })
+    return () => { alive = false }
+  }, [visible])
+  /** Mirrors `activeId` so callbacks can resolve the target base without stale closures. */
+  const activeIdRef = useRef('')
+  /**
+   * `query` / `typeFilter` 的镜像，理由同上但用途不同：搜索框的防抖计时器在 250ms
+   * 后触发，那时它需要的是**此刻**的另一个筛选条件，而不是它被排下时的那一个。
+   * 两个控件的改动是各自独立的，谁都不该把对方拖回旧值。
+   */
+  const queryRef = useRef('')
+  const typeFilterRef = useRef('')
+
+  useEffect(() => { activeIdRef.current = activeId }, [activeId])
+  useEffect(() => { queryRef.current = query }, [query])
+  useEffect(() => { typeFilterRef.current = typeFilter }, [typeFilter])
+
+  const active = bases.find(base => base.id === activeId)
+  const knowledgeValue = useScope(knowledge).value
+  /**
+   * 收录闸门（方案级设置，`source-raw` 组）。**默认开**：设置没读到（未接设置服务）时
+   * 不该把上传锁死 —— 那就成了「读不到配置 = 不能用」，比读不到更糟。
+   */
+  const gateClosed = knowledgeValue?.allowSourceTruth === false
+
+  // The parent scopes its recall test / upload UI to whatever base is selected here.
+  useEffect(() => {
+    onActiveBaseChange?.(active ? { id: active.id, name: active.name } : null)
+  }, [active?.id, active?.name, onActiveBaseChange]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  /** 架构图节点跳转：落到对应分栏。 */
+  useEffect(() => {
+    if (visible && focus) setTab(focus.tab)
+  }, [visible, focus?.tab, focus?.nonce]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  /** `sourceId → wiki cards`, so a file row can say how many slices it produced. */
+  const cardsBySource = useMemo(() => {
+    const index = new Map<string, KnowledgeCardView[]>()
+    for (const card of cards) {
+      for (const ref of card.sourceRefs ?? []) {
+        const list = index.get(ref)
+        if (list) list.push(card)
+        else index.set(ref, [card])
+      }
+    }
+    return index
+  }, [cards])
+
+  /** Pull the base list, keep (or repair) the active selection, and resolve it. */
+  const loadBases = useCallback(async (preferred?: string): Promise<{ next: KnowledgeBase[]; resolved: string }> => {
+    const payload = await requestJson<{ bases: KnowledgeBase[]; defaultBaseId: string }>('/knowledge/bases')
+    const next = payload.data?.bases ?? []
+    const requested = preferred ?? activeIdRef.current
+    const resolved = next.some(base => base.id === requested)
+      ? requested
+      : payload.data?.defaultBaseId ?? next[0]?.id ?? ''
+    setBases(next)
+    setActiveId(resolved)
+    activeIdRef.current = resolved
+    return { next, resolved }
+  }, [])
+
+  /**
+   * 文件列表。搜索与来源分类都**交给服务端**（它本来就有 `query` / `source_type` 两个
+   * 过滤口），文件类型没有对应的服务端口，所以在拿回来的一页里筛。
+   *
+   * `limit=500` 是接口允许的上限：文件类型筛在客户端做，只取默认的 50 条会让
+   * 「筛出 3 个」变成「这一页里有 3 个」—— 两个意思差得很远。
+   */
+  const loadDocuments = useCallback(async (baseId: string, search: string, sourceType: string): Promise<void> => {
+    const params = new URLSearchParams({ kb: baseId, limit: '500' })
+    if (search.trim()) params.set('query', search.trim())
+    if (sourceType) params.set('source_type', sourceType)
+    const payload = await requestJson<{ documents: KnowledgeDocument[]; total: number }>(`/knowledge/documents?${params.toString()}`)
+    const all = payload.data?.documents ?? []
+    setDocuments(all)
+    setTotal(payload.data?.total ?? all.length)
+  }, [])
+
+  /** Compiled wiki cards of one base — the local answer to WeKnora's chunk list. */
+  const loadCards = useCallback(async (baseId: string): Promise<void> => {
+    try {
+      const payload = await requestJson<{ cards: KnowledgeCardView[] }>(`/knowledge/cards?kb=${encodeURIComponent(baseId)}`)
+      setCards(payload.data?.cards ?? [])
+    } catch { setCards([]) }
+  }, [])
+
+  /** 图谱节点与边：知识图谱分栏列的就是它，不另外画一张小图（架构图已经画了）。 */
+  const loadGraph = useCallback(async (baseId: string): Promise<void> => {
+    try {
+      const payload = await requestJson<{ nodes?: GraphNodeView[]; edges?: GraphEdgeView[] }>(`/knowledge/graph?action=list&limit=50&kb=${encodeURIComponent(baseId)}`)
+      setGraph({ nodes: payload.data?.nodes ?? [], edges: payload.data?.edges ?? [] })
+    } catch { setGraph({ nodes: [], edges: [] }) }
+  }, [])
+
+  /** 当前知识库的编译统计。设置快照里没有这些字段，所以这里单独拉一次。 */
+  const loadStats = useCallback(async (baseId: string): Promise<void> => {
+    try {
+      const payload = await requestJson<Record<string, unknown>>(`/knowledge/stats?kb=${encodeURIComponent(baseId)}`)
+      setStats(payload.data ?? {})
+    } catch { setStats({}) }
+  }, [])
+
+  /** 内置只读判定提示词 + 注册表快照；SourceRaw 分栏里按库拉一次。 */
+  const loadCatalog = useCallback(async (baseId: string): Promise<void> => {
+    try {
+      const payload = await requestJson<SourceTypeCatalog>(`/knowledge/source-types?kb=${encodeURIComponent(baseId)}`)
+      setCatalog(payload.data ?? null)
+    } catch { setCatalog(null) }
+  }, [])
+
+  const refresh = useCallback(async (preferred?: string, search = '', sourceType = ''): Promise<void> => {
+    setLoading(true)
+    try {
+      const { resolved } = await loadBases(preferred)
+      if (resolved) await Promise.all([loadDocuments(resolved, search, sourceType), loadCards(resolved), loadGraph(resolved), loadCatalog(resolved), loadStats(resolved)])
+    } catch (error) {
+      setNotice({ tone: 'error', text: error instanceof Error ? error.message : String(error) })
+    } finally {
+      setLoading(false)
+    }
+  }, [loadBases, loadCards, loadDocuments, loadGraph, loadCatalog, loadStats])
+
+  useEffect(() => { if (visible) void refresh() }, [visible]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  /**
+   * 搜索框：打字是**连续输入**，所以防抖 250ms，不必每个字符打一次服务端。
+   *
+   * 这里**只跟 `query`**。原来它也跟 `typeFilter`，而下拉是**离散选择** —— 共用
+   * 一个防抖的直接后果就是「选完「全部来源分类」，列表要愣 250ms 才动」（GUI 反馈
+   * 2026-09-22）。两类交互的节奏不同，就不该共用一条延时。
+   */
+  useEffect(() => {
+    if (!visible) return undefined
+    const timer = setTimeout(() => {
+      const baseId = activeIdRef.current
+      if (baseId) void loadDocuments(baseId, query, typeFilterRef.current).catch(() => undefined)
+    }, 250)
+    return () => clearTimeout(timer)
+  }, [visible, activeId, query, loadDocuments])
+
+  /**
+   * 分类下拉：选完立刻请求，不进退避。
+   *
+   * 它是服务端筛选（`source_type` 是接口参数），所以客户端做不了 —— 但「立刻」
+   * 仍然成立：一次请求就是这个选择本身，没有理由再等一个为打字准备的延时。
+   */
+  const selectTypeFilter = useCallback((next: string): void => {
+    setTypeFilter(next)
+    // 「筛什么就按什么收录」：选中某一类时，上传分类跟着一致。
+    if (next) setUploadType(next)
+    const baseId = activeIdRef.current
+    if (baseId) void loadDocuments(baseId, queryRef.current, next).catch(() => undefined)
+  }, [loadDocuments])
+
+  /** 上传分类必须始终指向一个「存在且启用」的分类，停用后自动回退。 */
+  useEffect(() => {
+    const enabled = (active?.sourceTypes ?? []).filter(def => def.enabled)
+    if (enabled.length === 0 || enabled.some(def => def.id === uploadType)) return
+    setUploadType(enabled.find(def => def.id === 'document')?.id ?? enabled[0]!.id)
+  }, [active?.sourceTypes, uploadType])
+
+  const say = (tone: 'success' | 'error', text: string): void => { setNotice({ tone, text }); onChanged?.() }
+
+  // ----------------------------------------------------------------- actions
+
+  const saveBase = async (): Promise<void> => {
+    setBusy('base')
+    try {
+      const isNew = !draft.id
+      const body = JSON.stringify({ name: draft.name.trim(), description: draft.description.trim() })
+      const init: RequestInit = { method: isNew ? 'POST' : 'PATCH', headers: { 'content-type': 'application/json' }, body }
+      const payload = await requestJson<{ base: KnowledgeBase }>(isNew ? '/knowledge/bases' : `/knowledge/bases/${encodeURIComponent(draft.id)}`, init)
+      setEditOpen(false)
+      await refresh(payload.data?.base.id)
+      say('success', isNew ? `已创建知识库「${draft.name.trim()}」` : '知识库已更新')
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const removeBase = async (id: string): Promise<void> => {
+    setBusy('base-delete')
+    try {
+      await requestJson(`/knowledge/bases/${encodeURIComponent(id)}`, { method: 'DELETE' })
+      await refresh()
+      say('success', '知识库已删除')
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  /**
+   * 新增走 POST、编辑走 PATCH。
+   *
+   * 两条路都要把**判定文案**一起提交——服务端会强制 description / signals /
+   * excludes 的完整性，这是「用户追加新类型时必须用文字标明怎么判断」的落点。
+   *
+   * 草稿由「类型定义」抽屉传入：弹窗状态属于抽屉，写路径属于这里。
+   */
+  const saveSourceType = async (draft: SourceTypeDraft): Promise<void> => {
+    const base = active
+    if (!base) return
+    const body = {
+      kb: base.id,
+      id: draft.id.trim(),
+      label: draft.label.trim(),
+      description: draft.description.trim(),
+      signals: draft.signals.split('\n').map(line => line.trim()).filter(Boolean),
+      excludes: draft.excludes.split('\n').map(line => line.trim()).filter(Boolean),
+    }
+    const isNew = draft.mode === 'create'
+    setBusy('source-type')
+    try {
+      await requestJson(isNew ? '/knowledge/source-types' : `/knowledge/source-types/${encodeURIComponent(body.id)}`, {
+        method: isNew ? 'POST' : 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      })
+      await loadBases(base.id)
+      await loadCatalog(base.id)
+      say('success', isNew ? `已新增分类「${body.label}」` : `分类「${body.label}」已更新`)
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const toggleSourceType = async (def: SourceTypeDef, enabled: boolean): Promise<void> => {
+    const base = active
+    if (!base) return
+    setBusy(`source-type-${def.id}`)
+    try {
+      await requestJson(`/knowledge/source-types/${encodeURIComponent(def.id)}`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ kb: base.id, enabled }),
+      })
+      await loadBases(base.id)
+      await loadCatalog(base.id)
+      say('success', `${def.label} 已${enabled ? '启用' : '停用'}`)
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const removeSourceType = async (def: SourceTypeDef): Promise<void> => {
+    const base = active
+    if (!base) return
+    setBusy(`source-type-${def.id}`)
+    try {
+      await requestJson(`/knowledge/source-types/${encodeURIComponent(def.id)}?kb=${encodeURIComponent(base.id)}`, { method: 'DELETE' })
+      await loadBases(base.id)
+      await loadCatalog(base.id)
+      say('success', `已删除分类「${def.label}」`)
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  /**
+   * Wiki 类型注册表与 schema 生效方式都走 base PATCH（与 fileTypes / sourceTypes 同一条写路径）。
+   *
+   * `wikiTypes` 是**完整的期望列表**：服务端守卫会拦住"删掉在用类型/内置类型"的整表提交。
+   */
+  const patchWikiTypes = async (next: WikiTypeView[], describe: string): Promise<void> => {
+    const base = active
+    if (!base) return
+    setBusy('wiki-types')
+    try {
+      await requestJson(`/knowledge/bases/${encodeURIComponent(base.id)}`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ wikiTypes: next }),
+      })
+      await loadBases(base.id)
+      say('success', describe)
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const patchWikiSchemaMode = async (mode: 'strict' | 'report'): Promise<void> => {
+    const base = active
+    if (!base) return
+    setBusy('wiki-mode')
+    try {
+      await requestJson(`/knowledge/bases/${encodeURIComponent(base.id)}`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ wikiSchemaMode: mode }),
+      })
+      await loadBases(base.id)
+      say('success', mode === 'strict' ? '已开启严格模式：缺必填小节 / 字段将拒绝写入' : '已切回 report 模式：只标记问题，不拦截写入')
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  /** 清除 wiki 类型与模式上的用户层覆盖，回到出厂 11 个类型。 */
+  const resetWikiTypes = async (): Promise<void> => {
+    const base = active
+    if (!base) return
+    setBusy('wiki-types')
+    try {
+      await requestJson(`/knowledge/bases/${encodeURIComponent(base.id)}`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ resetWikiTypes: true }),
+      })
+      await loadBases(base.id)
+      say('success', '已恢复出厂 Wiki 类型')
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const writeSource = async (title: string, content: string, externalId: string): Promise<void> => {
+    const base = active
+    if (!base) throw new Error('请先选择一个知识库')
+    await requestJson('/knowledge/sources', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ kb: base.id, source_type: uploadType, title, external_id: externalId, content }),
+    })
+  }
+
+  /** Convert one file with the kernel, then ingest the delivery into the active base. */
+  const convertAndIngest = async (file: File): Promise<void> => {
+    const base = active
+    if (!base) throw new Error('请先选择一个知识库')
+    const form = new FormData()
+    form.append('file', file, file.name)
+    form.append('title', file.name)
+    const submitted = await requestJson<{ id: string }>('/convert/api/tasks', { method: 'POST', body: form })
+    const taskId = submitted.data?.id
+    if (!taskId) throw new Error('转换内核没有返回 taskId')
+    const deadline = Date.now() + CONVERT_TIMEOUT_MS
+    for (;;) {
+      const payload = await requestJson<{ state?: string; error?: { code?: string; message?: string } | null }>(`/convert/api/tasks/${encodeURIComponent(taskId)}`)
+      const state = payload.data?.state
+      if (state === 'succeeded') break
+      if (state === 'failed' || state === 'cancelled') {
+        throw new Error(`转换失败：${payload.data?.error?.code ?? state} ${payload.data?.error?.message ?? ''}`.trim())
+      }
+      if (Date.now() > deadline) throw new Error('转换超时，可在任务列表里稍后重试')
+      await new Promise(resolve => setTimeout(resolve, CONVERT_POLL_MS))
+    }
+    await requestJson('/convert/api/ingest', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ task_id: taskId, kb: base.id, title: file.name, source_type: uploadType }),
+    })
+  }
+
+  /** 分类 id → 显示名；不在注册表里的一律显示「未知分类」（文档本身不再被丢弃）。 */
+  const sourceTypeLabel = (id: string): string => active?.sourceTypes.find(def => def.id === id)?.label ?? '未知分类'
+
+  const handleImport = async (event: ChangeEvent<HTMLInputElement>): Promise<void> => {
+    const files = Array.from(event.target.files ?? [])
+    event.target.value = ''
+    const base = active
+    if (!files.length || !base) return
+    setBusy('import'); setNotice(null)
+    let done = 0
+    const failures: string[] = []
+    try {
+      for (const file of files) {
+        try {
+          const ext = file.name.slice(file.name.lastIndexOf('.')).toLowerCase()
+          // 文本类扩展名**直读**，不走转换内核。
+          //
+          // 0029 之前这里还看「文件类型规则里这个扩展名绑了哪个引擎」，而那个字段
+          // 内核根本不读 —— 它只在这里把 `直读` 改成 `anydoc`，让一份 Markdown 绕
+          // 一圈转换内核再落成同一份纯文本。规则表拆掉之后这里只剩一条真话：
+          // 能直读的就直读，不能的交给内核，由内核按它自己的格式表选适配器。
+          if (DIRECT_READ_EXT.has(ext)) {
+            const content = await file.text()
+            if (!content.trim()) throw new Error('文件内容为空')
+            await writeSource(file.name, content, `upload:${file.name}:${file.lastModified}`)
+          } else {
+            await convertAndIngest(file)
+          }
+          done += 1
+        } catch (error) {
+          failures.push(`${file.name}：${error instanceof Error ? error.message : String(error)}`)
+        }
+      }
+      if (failures.length === 0) say('success', `已导入 ${done} 个文件到「${base.name}」`)
+      else say('error', `成功 ${done} 个，失败 ${failures.length} 个 — ${failures[0]}`)
+      await loadBases(base.id)
+      await Promise.all([loadDocuments(base.id, query, typeFilter), loadCards(base.id)])
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  // ------------------------------------------------------- SourceRaw 详情
+
+  const openDetail = async (document: KnowledgeDocument): Promise<void> => {
+    const baseId = activeIdRef.current
+    if (!baseId) return
+    // 两个预览抽屉互斥：打开这一个就清掉另一个。不清的话，关掉卡片抽屉会让**残留
+    // 的**原文状态重新满足 `open`，于是面板「自己又弹回来」——互斥必须两边都成立。
+    setCardDetail(null)
+    setDetailLoading(true)
+    setDetail({ document: { ...document, content: '', frontmatter: {}, assets: [] }, versions: [] })
+    try {
+      const q = `?kb=${encodeURIComponent(baseId)}`
+      const docPayload = await requestJson<{ document: KnowledgeDocumentDetail }>(`/knowledge/documents/${encodeURIComponent(document.docId)}${q}`)
+      const versionPayload = await requestJson<{ versions: DocumentVersion[] }>(`/knowledge/documents/${encodeURIComponent(document.docId)}/versions${q}`)
+      if (docPayload.data?.document) {
+        setDetail({ document: docPayload.data.document, versions: versionPayload.data?.versions ?? [] })
+      }
+    } catch (error) {
+      setNotice({ tone: 'error', text: error instanceof Error ? error.message : String(error) })
+      setDetail(null)
+    } finally {
+      setDetailLoading(false)
+    }
+  }
+
+  const restoreVersion = async (): Promise<void> => {
+    const target = restoreTarget
+    const current = detail
+    const baseId = activeIdRef.current
+    if (!target || !current || !baseId) return
+    setBusy('restore')
+    try {
+      await requestJson(`/knowledge/documents/${encodeURIComponent(current.document.docId)}/revert?kb=${encodeURIComponent(baseId)}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ versionId: target.id }),
+      })
+      setRestoreTarget(null)
+      await openDetail(current.document)
+      await Promise.all([loadDocuments(baseId, query, typeFilter), loadCards(baseId)])
+      say('success', `已回滚到 V${target.number}`)
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const deleteDocument = async (document: KnowledgeDocument): Promise<void> => {
+    const baseId = activeIdRef.current
+    if (!baseId) return
+    setBusy(`doc-${document.docId}`)
+    try {
+      await requestJson(`/knowledge/documents/${encodeURIComponent(document.docId)}?kb=${encodeURIComponent(baseId)}`, { method: 'DELETE' })
+      if (detail?.document.docId === document.docId) setDetail(null)
+      await loadBases(baseId)
+      await Promise.all([loadDocuments(baseId, query, typeFilter), loadCards(baseId)])
+      say('success', `已删除「${document.title}」`)
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  // ------------------------------------------------------------ Wiki 详情
+
+  /** 点开一张卡片：内容 + 版本历史。版本由服务端在每次正文变化前快照。 */
+  const openCard = async (card: KnowledgeCardView): Promise<void> => {
+    const baseId = activeIdRef.current
+    if (!baseId) return
+    setDetail(null)
+    setCardLoading(true)
+    setCardDetail({ card, versions: [] })
+    try {
+      const q = `?kb=${encodeURIComponent(baseId)}&entity_type=${encodeURIComponent(card.entityType)}`
+      const [detailPayload, versionPayload] = await Promise.all([
+        requestJson<{ card: KnowledgeCardView }>(`/knowledge/cards/${encodeURIComponent(card.entityId)}${q}`),
+        requestJson<{ versions: WikiCardVersionView[] }>(`/knowledge/cards/${encodeURIComponent(card.entityId)}/versions${q}`),
+      ])
+      setCardDetail({ card: detailPayload.data?.card ?? card, versions: versionPayload.data?.versions ?? [] })
+    } catch (error) {
+      setNotice({ tone: 'error', text: error instanceof Error ? error.message : String(error) })
+      setCardDetail(null)
+    } finally {
+      setCardLoading(false)
+    }
+  }
+
+  const revertCard = async (): Promise<void> => {
+    const target = cardRestore
+    const current = cardDetail
+    const baseId = activeIdRef.current
+    if (!target || !current || !baseId) return
+    setBusy('card-revert')
+    try {
+      await requestJson(`/knowledge/cards/${encodeURIComponent(current.card.entityId)}/revert?kb=${encodeURIComponent(baseId)}&entity_type=${encodeURIComponent(current.card.entityType)}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ versionId: target.id }),
+      })
+      setCardRestore(null)
+      await openCard(current.card)
+      await loadCards(baseId)
+      say('success', `卡片已回滚到 V${target.number}（回滚前版本也已快照，可以再回滚回来）`)
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  // --------------------------------------------------------------- 编译
+
+  const rebuild = async (only: 'wiki' | 'all'): Promise<void> => {
+    const baseId = activeIdRef.current
+    if (!baseId) return
+    setBusy('compile'); setNotice(null)
+    try {
+      const payload = await requestJson<{
+        version?: number; skipped?: boolean
+        cardsReused?: number; cardsRecompiled?: number; cardsAdded?: number; cardsRemoved?: number
+        notesReused?: number; notesRecompiled?: number
+      }>('/knowledge/rebuild', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ only, kb: baseId }),
+      })
+      const data = payload.data ?? {}
+      await loadBases(baseId)
+      await Promise.all([loadCards(baseId), loadGraph(baseId), loadStats(baseId)])
+      if (data.skipped) {
+        say('success', `没有变化：复用 ${data.notesReused ?? 0} 条 wikiNotes，索引仍是 v${data.version ?? 1}`)
+      } else {
+        say('success', only === 'wiki'
+          ? `增量编译完成：复用 ${data.cardsReused ?? 0} 张 / 重编 ${data.cardsRecompiled ?? 0} 张卡片，新增 ${data.cardsAdded ?? 0}、移除 ${data.cardsRemoved ?? 0}，索引 v${data.version ?? 1}`
+          : `全量重建完成：${data.notesRecompiled ?? 0} 条 wikiNotes 重新切分，索引 v${data.version ?? 1}`)
+      }
+    } catch (error) {
+      say('error', error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const pickerItems = useMemo(() => bases.map(base => ({
+    id: base.id,
+    name: base.name,
+    meta: `${base.sourceCount} 个文件 · ${base.cardCount} 张卡片 · v${base.buildVersion}`,
+    detail: base.rootDir,
+  })), [bases])
+
+  const versionEntries: VersionManagerEntry[] = (detail?.versions ?? []).map((version, index, all) => ({
+    id: version.versionId,
+    number: all.length - index,
+    summary: `${version.label || version.sourceFormat || 'document'} · ${formatBytes(version.bytes)} · ${version.contentHash.slice(0, 8)}`,
+    actor: 'user',
+    time: formatTime(version.createdAt),
+    status: version.isCurrent ? 'committed' : 'superseded',
+    stepCount: 0,
+    replayable: false,
+  }))
+
+  const cardVersionEntries: VersionManagerEntry[] = (cardDetail?.versions ?? []).map((version, index, all) => ({
+    id: version.versionId,
+    number: all.length - index,
+    summary: `${version.label} · ${formatBytes(version.bytes)} · ${version.contentHash.slice(0, 8)}`,
+    actor: 'user',
+    time: formatTime(version.createdAt),
+    status: version.isCurrent ? 'committed' : 'superseded',
+    stepCount: 0,
+    replayable: false,
+  }))
+
+  /**
+   * 按文件类型筛选的下拉项，**从这一库真实的文档推导**。
+   *
+   * 0029 之前它来自每个库那份「文件类型规则」表：既会列出 0 个文件的类型，也会
+   * 漏掉文档里有、但没人登记过的扩展名。按实际文档算，两项毛病都没有。
+   */
+  const extOptions = useMemo(() => {
+    const counts = new Map<string, number>()
+    for (const document of documents) counts.set(document.ext, (counts.get(document.ext) ?? 0) + 1)
+    return [...counts.entries()]
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([ext, count]) => ({ value: ext, label: `${ext}（${count}）` }))
+  }, [documents])
+  /**
+   * `/knowledge/stats` 在这里是 `Record<string, unknown>`（它同时承载编译设置快照），
+   * 所以 `lastBuild` 要显式收窄一次再读 —— 否则每个字段都得写一遍类型断言。
+   */
+  const lastBuild = (stats.lastBuild ?? {}) as Record<string, unknown>
+  const currentVersionId = detail?.versions.find(version => version.isCurrent)?.versionId
+  const currentCardVersionId = cardDetail?.versions.find(version => version.isCurrent)?.versionId
+  const detailCards = detail ? cardsBySource.get(detail.document.docId) ?? [] : []
+  const pendingCards = cards.filter(card => schemaIssuesOf(card).length > 0)
+
+  /**
+   * 文件类型筛在客户端做（接口没有这个过滤口），其余两个筛选在服务端。
+   * 列表与计数都读这一份派生值，所以「筛出 3 个」与表头的数字不可能对不上。
+   */
+  const visibleDocuments = useMemo(
+    () => extFilter ? documents.filter(document => document.ext === extFilter) : documents,
+    [documents, extFilter],
+  )
+
+  /** Wiki 卡片列表的三个筛选。**类型选项取自「库里实际有什么」**，不是注册表全集 —— 筛一个空类型没有意义。 */
+  const cardTypes = useMemo(() => [...new Set(cards.map(card => card.entityType))].sort(), [cards])
+  const cardStatuses = useMemo(() => [...new Set(cards.map(card => card.status))].sort(), [cards])
+  const visibleCards = useMemo(() => {
+    const needle = cardQuery.trim().toLocaleLowerCase()
+    return cards.filter(card =>
+      (!cardType || card.entityType === cardType)
+      && (!cardStatus || card.status === cardStatus)
+      && (!needle || `${card.title}\n${card.entityId}\n${card.summary ?? ''}`.toLocaleLowerCase().includes(needle)))
+  }, [cards, cardQuery, cardType, cardStatus])
+
+  /**
+   * 步骤轨上每一步的真实事实。计数来自落盘与设置：`active` 的计数是服务端算的，
+   * 图谱计数优先读 `/knowledge/stats`（它统计的是全量），拿不到才退回这一页拉到的前 50 条。
+   */
+  const stepFacts = useMemo(() => ({
+    'source-raw': { value: active ? `${active.sourceCount} 个文件` : '—', note: '按格式路由解析，同 external_id 幂等' },
+    wiki: { value: active ? `${active.cardCount} 张卡片` : '—', note: '卡片 → wikiNotes，未变的逐字复用' },
+    graph: { value: `${stats.graphNodes ?? graph.nodes.length} 节点 / ${stats.graphEdges ?? graph.edges.length} 边`, note: 'supported_by 溯源边 + relates_to 关系边' },
+    recall: { value: `topK ${String(knowledgeValue?.recallTopK ?? 10)}`, note: `${String(knowledgeValue?.recallMode ?? 'hybrid')} 三路融合` },
+    rerank: { value: `topN ${String(knowledgeValue?.contextTopN ?? 5)}`, note: 'BERT cross-encoder 精排' },
+  }), [active, stats.graphNodes, stats.graphEdges, graph.nodes.length, graph.edges.length, knowledgeValue?.recallTopK, knowledgeValue?.recallMode, knowledgeValue?.contextTopN])
+
+  // --------------------------------------------------------------- 分栏内容
+
+  /** SourceRaw：筛选 + 文件列表。分类的**定义**在工具栏「类型定义」里，这里只消费它。 */
+  const renderSourceRaw = (): ReactNode => <div className={styles.viewStack}>
+    <Card className={styles.kbCard}>
+      <div className={styles.kbCardHead}>
+        <div><h3><FolderOpen size={13} />原始文档</h3></div>
+        {/* 「添加文件」挂在卡片头上，不塞进筛选行：它是这张列表的动作，不是筛选条件。
+            挤在筛选行里，宿主侧栏的宽度下它必然被挤到第二行单独站着。 */}
+        <div className={styles.kbCardActions}>
+          <span className={styles.kbCount}>
+            {visibleDocuments.length === total ? `${total} 个` : `筛出 ${visibleDocuments.length} / ${total} 个`}
+          </span>
+          {/* 0034：收录闸门在设置里，这里**读它**。此前这个开关没有任何一处读 —— 闸门
+              关着时按钮照样可点，然后由服务端报错。参数搬进抽屉之后，「它现在是不是开着」
+              必须在动作上看得出来，否则用户只会看到一次莫名其妙的失败。 */}
+          <Button
+            variant="default"
+            size="sm"
+            onClick={() => importInput.current?.click()}
+            disabled={busy !== null || !active || gateClosed}
+            title={gateClosed ? '收录闸门已关闭：设置 → SourceRaw 收录' : '添加文件'}
+          >
+            <Upload size={14} />{busy === 'import' ? '导入中…' : '添加文件'}
+          </Button>
+        </div>
+      </div>
+      {/* 一行筛选：搜索 · 来源分类 · 文件类型 · 刷新 · 添加文件。
+          0027 之前这里是两行（上传行 + 筛选行），而「来源分类」出现在两处 —— 一处决定
+          新文件以什么身份进来，另一处只筛列表。同一个名字两个控件，人就会以为筛着的
+          那一类就是新文件会落到的那一类。现在它只有一个：**筛什么，就按什么收录**。 */}
+      <div className={styles.kbFilterRow}>
+        <Input className={styles.kbFilterSearch} value={query} placeholder="搜索标题、external_id 或 hash" onChange={(event: ChangeEvent<HTMLInputElement>) => setQuery(event.target.value)} />
+        <SelectMenu
+          value={typeFilter}
+          onValueChange={selectTypeFilter}
+          disabled={!active}
+          className="max-w-[220px]"
+          aria-label="按来源分类筛选"
+          options={[
+            { value: '', label: '全部来源分类' },
+            ...(active?.sourceTypes ?? []).map(def => ({ value: def.id, label: `${def.label}（${def.sourceCount}）` })),
+          ]}
+        />
+        <SelectMenu
+          value={extFilter}
+          onValueChange={setExtFilter}
+          className="max-w-[220px]"
+          aria-label="按文件类型筛选"
+          options={[{ value: '', label: '全部文件类型' }, ...extOptions.map(option => ({ value: option.value, label: option.label }))]}
+        />
+        <Button variant="ghost" size="icon" title="刷新" aria-label="刷新文件列表" onClick={() => void refresh(activeId, query, typeFilter)}><RefreshCw size={14} /></Button>
+      </div>
+      <p className={styles.kbFilterHint}>
+        新文件按 <b>{sourceTypeLabel(typeFilter || uploadType)}</b> 收录。这个选择器同时是筛选与收录分类：选中某一类时两者一致，选「全部」时只放开筛选。
+        {(query || extFilter) ? ` 当前筛选：${[query && `关键词「${query}」`, extFilter && `类型 ${extFilter}`].filter(Boolean).join(' · ')}` : ''}
+      </p>
+      {visibleDocuments.length === 0 && <p className={styles.kbEmpty}>
+        {loading
+          ? '加载中…'
+          : documents.length > 0
+            ? '当前筛选没有命中的文件。清掉筛选条件就能看到这个知识库的全部文件。'
+            : '这个知识库还没有文件。用右边的「添加文件」开始：纯文本直读，Word / PDF / 表格走转换内核。'}
+      </p>}
+      <ul className={styles.kbDocList}>
+        {visibleDocuments.map(document => {
+          const docCards = cardsBySource.get(document.docId) ?? []
+          return <li key={document.docId} className={styles.kbDocRow}>
+            <button type="button" className={styles.kbDocMain} onClick={() => void openDetail(document)}>
+              <span className={styles.kbDocTitle}><FileText size={13} />{document.title}</span>
+              <span className={styles.kbDocMeta}>
+                {sourceTypeLabel(document.sourceType)}{document.sourceTypeKnown === false ? '（未知分类）' : ''}
+                {' · '}{document.ext}
+                {' · '}{document.sourceFormat || 'unknown'}
+                {' · '}{formatBytes(document.bytes)}
+                {document.assetCount > 0 ? ` · ${document.assetCount} 图` : ''}
+                {' · '}{document.versionCount} 个版本
+                {' · '}{docCards.length > 0 ? `${docCards.length} 张卡片` : '尚未编译出卡片'}
+                {' · '}{formatTime(document.updatedAt)}
+              </span>
+            </button>
+            <span className={styles.kbDocActions}>
+              <Button variant="ghost" size="icon" title="详情" aria-label={`查看 ${document.title} 详情`} onClick={() => void openDetail(document)}><Eye size={13} /></Button>
+              <Button variant="ghost" size="icon" title="删除" aria-label={`删除 ${document.title}`} disabled={busy !== null} onClick={() => void deleteDocument(document)}><Trash2 size={13} /></Button>
+            </span>
+          </li>
+        })}
+      </ul>
+    </Card>
+
+    {/* 两块都不在这一栏里了，各有各的家（0034）：
+        - **来源类型**（本库词汇表）→ 工具栏的「类型定义」抽屉。它与 Wiki 类型是同一类
+          东西（按库持久化的注册表），分居两栏时「改卡片 schema 去哪」得先回答「它属于
+          编译那一段」——而那是实现细节。
+        - **SourceRaw 收录与存储**（方案级闸门）→ 顶部齿轮的设置抽屉。
+        这里不再留任何指路文字：工具栏与卡片头各自带着入口，路牌只是搬迁留下的债。 */}
+  </div>
+
+  /** Wiki：卡片列表（一等内容）+ 编译 + 抽取流程 + schema 注册表。 */
+  const renderWiki = (): ReactNode => <div className={styles.viewStack}>
+    {/* 卡片列表排在第一位，和 SourceRaw 的文件列表同一个位置、同一套筛选行 ——
+        两栏的「这一层有什么」都应该是打开就能看到的第一件东西。0027 之前这里
+        先是一张编译统计卡，卡片列表在第三位，得先读过参数才看得到内容。 */}
+    <Card className={styles.kbCard}>
+      <div className={styles.kbCardHead}>
+        <div><h3><FileText size={13} />wiki 卡片</h3></div>
+        <span className={styles.kbCount}>
+          {visibleCards.length === cards.length ? `${cards.length} 张` : `筛出 ${visibleCards.length} / ${cards.length} 张`}
+        </span>
+      </div>
+      <div className={styles.kbFilterRow}>
+        <Input className={styles.kbFilterSearch} value={cardQuery} placeholder="搜索标题、entity_id 或摘要" onChange={(event: ChangeEvent<HTMLInputElement>) => setCardQuery(event.target.value)} />
+        <SelectMenu
+          value={cardType}
+          onValueChange={setCardType}
+          className="max-w-[220px]"
+          aria-label="按卡片类型筛选"
+          options={[
+            { value: '', label: '全部卡片类型' },
+            ...cardTypes.map(type => ({ value: type, label: `${type}（${cards.filter(card => card.entityType === type).length}）` })),
+          ]}
+        />
+        <SelectMenu
+          value={cardStatus}
+          onValueChange={setCardStatus}
+          className="max-w-[220px]"
+          aria-label="按状态筛选"
+          options={[
+            { value: '', label: '全部状态' },
+            ...cardStatuses.map(status => ({ value: status, label: `${status}（${cards.filter(card => card.status === status).length}）` })),
+          ]}
+        />
+        <Button variant="ghost" size="icon" title="刷新" aria-label="刷新卡片列表" onClick={() => void loadCards(activeIdRef.current)}><RefreshCw size={14} /></Button>
+      </div>
+      {pendingCards.length > 0 && <p className={styles.kbFilterHint}>有 <b>{pendingCards.length}</b> 张卡片缺必填小节 / 字段（report 模式只标记不拦截）。筛「待补」请用状态筛选，或在工具栏「类型定义」里切换生效方式。</p>}
+      {visibleCards.length === 0 && <p className={styles.kbEmpty}>
+        {cards.length > 0
+          ? '当前筛选没有命中的卡片。清掉筛选条件就能看到这个知识库的全部卡片。'
+          : <>还没有卡片。先「增量编译」（Pass 0 会从正文标题、<b>[[链接]]</b> 与 frontmatter 抽候选），或让 Agent 用 <b>write_knowledge_card</b> 写入 —— 写入前会按 wiki 类型的 schema 校验。</>}
+      </p>}
+      <ul className={styles.cardList}>
+        {visibleCards.map(card => {
+          const issues = schemaIssuesOf(card)
+          // Pass 0 抽出来的卡片是**机器猜的**，与 Agent 写入的卡片必须能一眼分开：
+          // 前者的状态永远是 unreviewed，但「没审核」和「是抽出来的」是两件事。
+          const extracted = card.metadata?.extraction === 'pass0'
+          return <li key={card.entityId} className={styles.cardRow}>
+            <button type="button" className={styles.cardRowMain} onClick={() => void openCard(card)}>
+              <div className={styles.cardRowHead}>
+                <Badge tone={card.status === 'active' || card.status === 'reviewed' ? 'success' : card.status === 'problem' ? 'warning' : 'neutral'}>{card.status}</Badge>
+                <span className={styles.cardRowTitle} title={card.entityId}>{card.title}</span>
+                {extracted && <Badge tone="blue">候选</Badge>}
+                {issues.length > 0 && <Badge tone="warning">待补 {issues.length}</Badge>}
+                <span className={styles.kbTypeCount}>{formatTime(card.updatedAt)}</span>
+              </div>
+              <p className={styles.cardRowText}>{card.summary || card.content.replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/\s+/g, ' ').slice(0, 160) || '（空卡片）'}</p>
+              <span className={styles.kbCode}>{card.entityType} · {card.entityId} · {card.sourceRefs.length} 个出处</span>
+            </button>
+          </li>
+        })}
+      </ul>
+    </Card>
+
+    <Card className={styles.kbCard}>
+      <div className={styles.kbCardHead}>
+        <div><h3><Layers3 size={13} />编译 wiki 与 wikiNotes</h3></div>
+        <div className={styles.kbCardActions}>
+          <Button variant="outline" size="sm" onClick={() => void rebuild('wiki')} disabled={busy !== null}><RefreshCw size={13} />{busy === 'compile' ? '编译中…' : '增量编译'}</Button>
+          <Button variant="ghost" size="sm" onClick={() => void rebuild('all')} disabled={busy !== null}>全量重编</Button>
+        </div>
+      </div>
+      <p className={styles.kbHint}>
+        <b>增量</b>：只有正文 / 标题 / 状态 / 出处变过的卡片会重新切分成 wikiNotes，其余卡片的召回单元**逐字复用**（unitId 不变，向量也不重编码）。
+        语料完全没变时这一次编译是**空操作**：不写产物、不升版本，因为升版本会让整份向量缓存作废。
+      </p>
+      <div className={styles.infoList}>
+        <div><span>wiki 卡片</span><strong>{active?.cardCount ?? 0}</strong></div>
+        <div><span>wikiNotes</span><strong>{active?.noteCount ?? 0}</strong></div>
+        <div><span>已纳入增量指纹</span><strong>{String(stats.trackedCards ?? '—')}</strong></div>
+        <div><span>卡片版本快照</span><strong>{String(stats.cardVersions ?? 0)}</strong></div>
+        <div><span>索引版本</span><strong>v{active?.buildVersion ?? 0}</strong></div>
+        <div><span>待补 schema 的卡片</span><strong>{pendingCards.length}</strong></div>
+        {/* Pass 0 的四个诚实计数：抽了几个候选、拒了几个、建了几张、并进几张。
+            它们来自上一轮编译的 build-manifest，不是估算。 */}
+        <div><span>上一轮抽出候选</span><strong>{String(lastBuild.candidatesExtracted ?? '—')}</strong></div>
+        <div><span>新建 / 合并卡片</span><strong>{stats.lastBuild ? `${lastBuild.cardsCreated ?? 0} / ${lastBuild.cardsMerged ?? 0}` : '—'}</strong></div>
+      </div>
+    </Card>
+
+    <WikiFlowCard />
+
+    {/* **Wiki 类型**（卡片 schema）也不在这一栏了（0034）：它和来源类型是同一类东西
+        —— 按库持久化的词汇表，一个决定「一份文件以什么业务身份进来」，一个决定「一张
+        卡片要长成什么样」。两处合到工具栏的「类型定义」抽屉里，schema 的入口就只有
+        一个。这里消费它（写卡片时按它校验），但不定义它。 */}
+  </div>
+
+  /**
+   * 知识图谱：**一张真的图**，能按节点类型 / 边类型筛，能搜，能点。
+   *
+   * 0027 之前这里是「节点清单 + 折叠起来的边清单」——那回答的是「有哪些」，
+   * 回答不了「连成什么样」，而后者才是打开这一栏的理由。
+   * 构建设置是产出这张图的参数，所以入口挂在**这张卡片的头上**（0034）：参数离它
+   * 产出的东西只有一次点击，而不再是一句「已移到顶部齿轮」。
+   */
+  const renderGraph = (): ReactNode => <div className={styles.viewStack}>
+    <KnowledgeGraphView
+      nodes={graph.nodes} edges={graph.edges} visible={visible && tab === 'graph'}
+      sourceTitles={new Map(documents.map(document => [document.docId, document.title]))}
+    />
+
+    <Card className={styles.kbCard}>
+      <div className={styles.kbCardHead}>
+        <div><h3>构建产物</h3></div>
+        {onOpenSettings && <div className={styles.kbCardActions}>
+          <SettingsChip target="build" onOpen={onOpenSettings} />
+        </div>}
+      </div>
+      <div className={styles.infoList}>
+        <div><span>图谱节点</span><strong>{String(stats.graphNodes ?? graph.nodes.length)}</strong></div>
+        <div><span>图谱边</span><strong>{String(stats.graphEdges ?? graph.edges.length)}</strong></div>
+        <div><span>向量条目</span><strong>{String(stats.vectorCount ?? 0)}</strong></div>
+        <div><span>最近构建</span><strong>{formatTime(typeof stats.builtAt === 'string' ? stats.builtAt : undefined)}</strong></div>
+      </div>
+      <p className={styles.kbHint}>
+        图上有两类边：<b>supported_by</b>（wiki 卡片 → SourceRaw 的溯源边，每张卡片都能指回它的原始文档）与
+        <b>relates_to</b>（wiki ↔ wiki 的实体关系边，由编译时的 Pass 0 从正文 <b>[[链接]]</b> 与 frontmatter 的关系声明里抽出）。
+        关系边的两端都必须已经存在，抽到一半的关系会被丢掉并在编译报告里计数 —— 图上不会出现悬空的节点。
+      </p>
+    </Card>
+  </div>
+
+  /**
+   * 召回重排：真实运行面板。设置在这张面板的卡头上（参数 chip），不在这栏正文里。
+   *
+   * 两枚 chip 而不是一枚：这一栏同时消费**两组**参数（召回的候选池/阈值/路线，
+   * 与上下文的 topN/重排阈值），而它们是抽屉里的两个分块。给一枚就只能落到其中
+   * 一组，另一组又变回「要自己找」。文案与抽屉分块同源（`SettingsChip` 读
+   * `NODE_SETTINGS`），所以两处不会漂移。
+   */
+  const renderRecall = (): ReactNode => <div className={styles.viewStack}>
+    <RecallPanel
+      visible={visible && tab === 'recall'}
+      kbId={active?.id}
+      {...(active?.name ? { kbName: active.name } : {})}
+      {...(onOpenSettings ? { settingsChip: <>
+        <SettingsChip target="recall" onOpen={onOpenSettings} />
+        <SettingsChip target="context" onOpen={onOpenSettings} />
+      </> } : {})}
+      resetKey={`${active?.id ?? ''}:${String(knowledgeValue?.recallTopK ?? '')}:${String(knowledgeValue?.recallMode ?? '')}:${String(knowledgeValue?.contextTopN ?? '')}`}
+      defaults={{
+        ...(typeof knowledgeValue?.recallMode === 'string' ? { mode: knowledgeValue.recallMode } : {}),
+        ...(typeof knowledgeValue?.recallTopK === 'number' ? { topK: knowledgeValue.recallTopK } : {}),
+        ...(typeof knowledgeValue?.contextTopN === 'number' ? { topN: knowledgeValue.contextTopN } : {}),
+      }}
+    />
+  </div>
+
+  return <div className={styles.kbLayout}>
+    {/* 一行顶栏：选库 · 这一库的计数 · 动作。**它在步骤轨之上** —— 先选「哪个知识库」，
+        再看「这个知识库走到哪一步」。反过来（先看到五个步骤的计数，再选库）会让那些
+        计数在切换知识库之前是别人的数字。
+        0027 之前这是三行（选库 + 改名、编译 + 控制台、计数），而「改名 / 描述」
+        还和库选择器里那行菜单重复了一遍 —— 同一件事两个入口，就会有人改完一处
+        以为另一处也跟着变了。库路径也不在这里了：它是「存储位置」设置，
+        入口在面板顶部的齿轮里。
+        0034：「类型定义」也挂在这一行 —— 它是**按库**的动作（来源分类与卡片 schema 都是
+        这一库的词汇表），所以它和「选哪个库」同层；而它**不是**第六个步骤：步骤轨是
+        一条流水线，词汇表不属于任何一段（理由见 `TypeDefinitionDrawer.tsx`）。
+        0035：**计数撤出这一行**，三个动作与选择器一起左对齐。计数没有丢 —— 步骤轨每一步
+        第二行写的就是「这一段现在有多少东西」（`stepFacts`），而这一行只回答「现在看哪个
+        库、能对它做什么」。把同一批数字在一屏里说两遍，会让选择器与动作被挤到两头。 */}
+    <div className={styles.kbToolbar}>
+      <ObjectPicker
+        label="知识库"
+        name={active?.name ?? (loading ? '加载中…' : '没有知识库')}
+        items={pickerItems}
+        currentId={activeId}
+        createLabel="新建知识库"
+        placeholder="还没有知识库"
+        emptyLabel="还没有知识库，先新建一个"
+        allowDeleteCurrent={false}
+        onSelect={id => { setActiveId(id); activeIdRef.current = id; setExtFilter(''); setTypeFilter(''); setQuery('') }}
+        onCreate={() => { setDraft({ id: '', name: '', description: '' }); setEditOpen(true) }}
+        onRename={id => { const base = bases.find(item => item.id === id); if (base) { setDraft({ id: base.id, name: base.name, description: base.description }); setEditOpen(true) } }}
+        onDelete={id => { void removeBase(id) }}
+      />
+      {/* 三个动作同形：图标 + 文字的 outline 按钮，同一个 30px 高。内核控制台是一个
+          **链接**，所以它走 `Button asChild` 拿到同一套外观 —— 早先它是一枚裸的
+          `.tita-uiButton` 锚点，在这两枚按钮旁边读起来像第三种控件。 */}
+      <span className={styles.kbToolbarActions}>
+        <Button
+          variant="outline"
+          size="sm"
+          disabled={!active}
+          title={active ? `编辑 ${active.name} 的来源类型与 Wiki 类型` : '先选择一个知识库'}
+          onClick={() => setTypeDefOpen(true)}
+        ><Tags size={13} />类型定义</Button>
+        <Button variant="outline" size="sm" onClick={() => void rebuild('wiki')} disabled={busy !== null || !active}><RefreshCw size={14} />{busy === 'compile' ? '编译中…' : '编译'}</Button>
+        <Button variant="outline" size="sm" asChild>
+          <a href="/convert/" target="_blank" rel="noreferrer" title="打开解析内核控制台"><FileUp size={14} />解析内核</a>
+        </Button>
+      </span>
+    </div>
+
+    {/* 分栏是**一条流水线**，所以切换器是步骤轨而不是一排等宽 tab：收录 → 编译 →
+        关联 → 检索 → 精排。方向本身就是信息（写入侧在左、读取侧在右）。 */}
+    <KnowledgeStepRail tab={tab} onChange={setTab} facts={stepFacts} />
+
+    {notice && <p className={cn(styles.kbNotice, notice.tone === 'error' && styles.kbNoticeError)} role="status">
+      <AlertCircle size={13} /><span>{notice.text}</span>
+      <button type="button" className={styles.kbNoticeClose} aria-label="关闭提示" onClick={() => setNotice(null)}><X size={12} /></button>
+    </p>}
+
+    {/* 分栏内容按当前值渲染：切换器是步骤轨（不是 Radix Tabs），所以这里自己按值渲染。 */}
+    {tab === 'source-raw' && renderSourceRaw()}
+    {tab === 'wiki' && renderWiki()}
+    {tab === 'graph' && renderGraph()}
+    {tab === 'recall' && renderRecall()}
+
+    {/* 一个上传入口。accept 是**转换内核自己报的扩展名** ∪ 可直读的扩展名。
+        0029 之前它来自每个库那份「文件类型规则」表：那张表会和内核真实支持的格式
+        漂移（登记了 .docx 而内核不收，或反过来），于是选择框灰掉一个其实能转的文件。
+        问内核就没有这个问题 —— 它就是判定的那一方。拿不到就不限制：让内核给出准确的
+        FORMAT_UNSUPPORTED，比前端猜一张表强。 */}
+    <input ref={importInput} type="file" multiple hidden
+      {...(acceptExts.length > 0 ? { accept: acceptExts.join(',') } : {})}
+      onChange={event => void handleImport(event)} />
+
+    <Dialog open={editOpen} onOpenChange={setEditOpen}>
+      {editOpen && <DialogContent>
+        <DialogHeader><DialogTitle>{draft.id ? '编辑知识库' : '新建知识库'}</DialogTitle></DialogHeader>
+        <div className={styles.kbForm}>
+          <label className={styles.kbField}><Label>名称</Label>
+            <Input value={draft.name} onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft({ ...draft, name: event.target.value })} placeholder="例如：产品文档" />
+          </label>
+          <label className={styles.kbField}><Label>描述</Label>
+            <Input value={draft.description} onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft({ ...draft, description: event.target.value })} placeholder="这个知识库放什么" />
+          </label>
+          <p className={styles.kbHint}>每个知识库有自己的根目录、来源分类与 Wiki 类型注册表；默认知识库沿用现有的知识库根目录。</p>
+        </div>
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => setEditOpen(false)}>取消</Button>
+          <Button variant="default" disabled={!draft.name.trim() || busy !== null} onClick={() => void saveBase()}><Check size={13} />保存</Button>
+        </DialogFooter>
+      </DialogContent>}
+    </Dialog>
+
+    {/* 本库的词汇表（0034）：来源分类注册表 + Wiki 卡片 schema，一个抽屉、一个入口。
+        它**不是**设置抽屉里的第七块 —— 那两个注册表按库持久化，而设置是整个方案一份。
+        弹窗状态在这个组件内部；写路径仍走上面那几个 `patch*` / `saveSourceType`。 */}
+    {active && <TypeDefinitionDrawer
+      open={typeDefOpen}
+      onOpenChange={setTypeDefOpen}
+      kbId={active.id}
+      kbName={active.name}
+      sourceTypes={active.sourceTypes ?? []}
+      wikiTypes={active.wikiTypes ?? []}
+      schemaMode={active.wikiSchemaMode ?? 'report'}
+      customized={active.wikiTypesCustomized === true}
+      catalog={catalog}
+      busy={busy}
+      onSaveSourceType={saveSourceType}
+      onToggleSourceType={toggleSourceType}
+      onRemoveSourceType={removeSourceType}
+      onApplyWikiTypes={patchWikiTypes}
+      onModeChange={patchWikiSchemaMode}
+      onResetWikiTypes={resetWikiTypes}
+    />}
+
+    <RestoreDialog
+      open={restoreTarget !== null}
+      onOpenChange={open => { if (!open) setRestoreTarget(null) }}
+      targetLabel={restoreTarget ? `V${restoreTarget.number}` : ''}
+      targetSummary={restoreTarget?.summary}
+      artifactLabel="知识文档"
+      pending={busy === 'restore'}
+      onConfirm={() => void restoreVersion()}
+    />
+
+    <RestoreDialog
+      open={cardRestore !== null}
+      onOpenChange={open => { if (!open) setCardRestore(null) }}
+      targetLabel={cardRestore ? `V${cardRestore.number}` : ''}
+      targetSummary={cardRestore?.summary}
+      artifactLabel="wiki 卡片"
+      pending={busy === 'card-revert'}
+      onConfirm={() => void revertCard()}
+    />
+
+    {/* **两个预览抽屉互斥**（0030）。
+        它们原来是两个独立的 Radix 模态，`open` 只跟自己的 state 走 —— 于是「原文预览
+        开着，又从别处点开一张卡片」就真的能叠成两层：两个遮罩、两套 Esc 监听，点一下
+        叉号或空白处两个都关掉。把互斥写在 `open` 上，而不是指望每个入口都记得清理另
+        一个 state —— 「同时开两个」在这里变成不可表达的状态。 */}
+    <Drawer open={detail !== null && cardDetail === null} onOpenChange={next => { if (!next) setDetail(null) }}>
+      {detail && <DrawerContent className={styles.drawer} resizable resizeKey="tita-source-preview">
+        <DrawerHeader>
+          <DrawerTitle>{detail.document.title}</DrawerTitle>
+          <DrawerDescription>{detail.document.relativePath}</DrawerDescription>
+        </DrawerHeader>
+        <DrawerBody className={styles.drawerStack}>
+          {/* 0035：两种预览是**同一套分块**（元信息 → 内容 → 版本），SourceRaw 只多一块
+              「编译产物」。顺序不是随手排的：先确认「这是什么」（元信息，含 hash 与分类），
+              再读「它写了什么」（内容），再看「它编译出了什么」（派生结论），最后才是
+              「改过几次」（版本）。0030 那条「原文在编译产物之前」在这里仍然成立。
+              时间一律用标准格式（`formatDateTime`）—— 抽屉里是逐字核对事实的地方。 */}
+          <PreviewMeta rows={[
+            { label: '类型', value: `${detail.document.ext} · ${detail.document.sourceFormat || 'unknown'}` },
+            { label: '解析器', value: detail.document.parser || '—' },
+            { label: '来源分类', value: `${sourceTypeLabel(detail.document.sourceType)} · ${detail.document.sourceType}` },
+            { label: 'external_id', value: detail.document.externalId || '—', code: true },
+            { label: 'content_hash', value: detail.document.contentHash || '—', code: true },
+            { label: '大小', value: formatBytes(detail.document.bytes) },
+            { label: '创建', value: formatDateTime(detail.document.createdAt) },
+            { label: '更新', value: formatDateTime(detail.document.updatedAt) },
+          ]} />
+
+          <PreviewContent content={detail.document.content} assets={detail.document.assets} />
+
+          <div className={styles.drawerSection}>
+          {/* WeKnora 的详情页在文件下面列分块；这里列的是这个 SourceRaw 编译出的 wiki 卡片。 */}
+          <div className={styles.kbSubHead}><h4><Layers3 size={13} />编译产物</h4><span>{detailCards.length} 张卡片</span></div>
+          {detailCards.length === 0
+            ? <p className={styles.kbHint}>还没有从这个文件编译出 wiki 卡片。先「编译」，或在概览里让 Agent 用 <b>write_knowledge_card</b> 引用它。</p>
+            : <ul className={styles.cardList}>
+              {detailCards.map(card => <li key={card.entityId} className={styles.cardRow}>
+                <button type="button" className={styles.cardRowMain} onClick={() => void openCard(card)}>
+                  <div className={styles.cardRowHead}>
+                    <Badge tone={card.status === 'active' || card.status === 'reviewed' ? 'success' : 'neutral'}>{card.status}</Badge>
+                    <span className={styles.cardRowTitle} title={card.entityId}>{card.title}</span>
+                    <span className={styles.kbTypeCount}>{formatDateTime(card.updatedAt)}</span>
+                  </div>
+                  <p className={styles.cardRowText}>{card.summary || card.content.replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/\s+/g, ' ').slice(0, 160) || '（空卡片）'}</p>
+                  <span className={styles.kbCode}>{card.entityType} · {card.entityId}</span>
+                </button>
+              </li>)}
+            </ul>}
+          </div>
+
+          <PreviewVersions
+            entries={versionEntries}
+            loading={detailLoading}
+            emptyLabel="这个文件还没有历史版本（每次内容变化都会自动留一份快照）。"
+            actions={{
+              restorableId: currentVersionId,
+              onRestore: entry => setRestoreTarget(entry),
+            }}
+          />
+        </DrawerBody>
+      </DrawerContent>}
+    </Drawer>
+
+    {/* wiki 卡片的侧边栏：与 SourceRaw 详情**同一种形态** —— 标题、元信息、内容、版本。 */}
+    <Drawer open={cardDetail !== null} onOpenChange={next => { if (!next) setCardDetail(null) }}>
+      {cardDetail && <DrawerContent className={styles.drawer} resizable resizeKey="tita-wiki-preview">
+        <DrawerHeader>
+          <DrawerTitle>{cardDetail.card.title}</DrawerTitle>
+          <DrawerDescription>{cardDetail.card.entityType} · {cardDetail.card.entityId}</DrawerDescription>
+        </DrawerHeader>
+        <DrawerBody className={styles.drawerStack}>
+          <PreviewMeta rows={[
+            { label: '状态', value: cardDetail.card.status },
+            { label: '类型', value: cardDetail.card.entityType },
+            { label: 'entity_id', value: cardDetail.card.entityId, code: true },
+            { label: '更新', value: formatDateTime(cardDetail.card.updatedAt) },
+            { label: '出处', value: cardDetail.card.sourceRefs.join(', ') || '—', code: true },
+          ]} />
+
+          {/* schema 待补紧跟在元信息后面：它是对「状态」那一行的展开，不是正文的一部分。 */}
+          {schemaIssuesOf(cardDetail.card).length > 0 && <details className={styles.kbPrompt} open>
+            <summary><ShieldCheck size={12} /> schema 待补 {schemaIssuesOf(cardDetail.card).length} 项（report 模式：只标记不拦截）</summary>
+            <ul className={styles.kbPromptSteps}>
+              {schemaIssuesOf(cardDetail.card).map((issue, index) => <li key={`${issue.message ?? index}`}><code>{issue.level ?? 'warning'}</code> {issue.message}</li>)}
+            </ul>
+          </details>}
+
+          <PreviewContent content={cardDetail.card.content} />
+
+          <PreviewVersions
+            hint="卡片正文每次变化前都会留一份快照；回滚是往前的写入，所以回滚前的那一版也会被快照 —— 回滚本身也可以回滚。"
+            entries={cardVersionEntries}
+            loading={cardLoading}
+            emptyLabel="这张卡片还没有历史版本（正文变化时才会生成快照；只改状态不会造版本）。"
+            actions={{
+              restorableId: currentCardVersionId,
+              onRestore: entry => setCardRestore(entry),
+            }}
+          />
+        </DrawerBody>
+      </DrawerContent>}
+    </Drawer>
+  </div>
+}