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

package/src/client/RecallPanel.tsx

@@ -0,0 +1,399 @@
+/**
+ * 召回与重排的**真实运行面板**。
+ *
+ * 从 `KnowledgePanel` 里抽出来，是因为召回 / 重排现在是知识库下的两个分栏，
+ * 而评测 Tab 还要用同一套能力。三处判定口径若各写一遍，就会出现「同一个问题在
+ * 召回栏命中 3 条、在评测栏命中 5 条」这种最伤信任的差异。
+ *
+ * 只报真数据：命中分块、命中路线、得分都不省略。WeKnora 的检索测试同样把
+ * `chunk_index` / `score` 一起给出 —— 只报「命中 N 条」看不出召回质量。
+ */
+
+import { useEffect, useState, type ReactNode } from 'react'
+import { Check, CircleHelp, Play, Search } from '@tita-data-agent/ui/icons'
+import { Badge, Button, Card, Input, SelectMenu, cn } from '@tita-data-agent/ui/components'
+import { styles } from './styles.ts'
+
+/** 一条命中的 wikiNote。`match` 是**真正贡献了这次命中**的路线。 */
+export interface RecallHitView {
+  unitId: string
+  title: string
+  heading?: string
+  snippet: string
+  match: string
+  score: number
+  status?: string
+  entityType?: string
+  rerankScore?: number
+}
+
+/** 进入 Context Pack 的一条：命中的 wikiNote + 它解析出的父级 wiki 标题。 */
+export interface ContextItemView {
+  unitId: string
+  title: string
+  snippet: string
+  score: number
+  rerankScore?: number
+  wikiTitle?: string
+  wikiId?: string
+}
+
+export interface RecallResultView {
+  count: number
+  backend: string
+  routes?: string[]
+  contextCount: number
+  recallTopK: number
+  /** 融合与重排作用的候选池深度（0031）。它与 `recallTopK` 是两个数。 */
+  candidatePool?: number
+  contextTopN: number
+  rerank?: string
+  rerankProvider?: string
+  rerankThreshold?: number
+  rerankDropped?: number
+  /** 候选池里最高的原始 logit（0031）—— `dropped: 0` 时用它区分「都相关」与「阈值没在工作」。 */
+  rerankTopLogit?: number
+  /** cross-encoder 分词器词表大小；退化成 5 就该报警（0031）。 */
+  rerankVocabSize?: number
+  /** 一路都没过阈值：知识库里没有能回答这个问题的东西（0031）。 */
+  insufficientEvidence?: boolean
+  /** 每一路的真实状态与降级原因。 */
+  routesDetail?: Array<{ route: string; status: string; candidates?: number; kept?: number; topScore?: number; threshold?: number; reason?: string }>
+  graphBoost?: { applied: number; weight: number }
+  abstention?: string
+  diagnosticsReason?: string
+  encoder?: { ok: boolean; reason?: string }
+  hits: RecallHitView[]
+  context: ContextItemView[]
+  kbName?: string
+  indexVersion?: number
+}
+
+interface Envelope<T> { ok?: boolean; data?: T; error?: { code?: string; message?: string; suggestion?: string } | null }
+
+async function requestJson<T>(url: string): Promise<Envelope<T>> {
+  const response = await fetch(url)
+  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
+}
+
+/**
+ * 召回是**两路**（关键词 BM25 + 向量）加一个图谱 boost（0031）。
+ *
+ * 图谱不再是独立一路：它不能制造候选，只给已经在候选池里的条目加权。所以这一行显示的是
+ * 「加权了几条」，而不是「跑没跑」—— 后者对它已经没有意义。
+ */
+export const RECALL_ROUTES: Array<{ id: string; label: string; hint: string }> = [
+  { id: 'fts', label: '关键词', hint: 'FTS5 + BM25（中文按双字词切分）' },
+  { id: 'vector', label: '向量', hint: 'WeMM 向量近邻（binary 预筛 + int8 精算余弦）' },
+]
+
+export const RECALL_MODES: Array<{ id: string; label: string }> = [
+  { id: 'hybrid', label: '融合 + 图谱 boost（默认）' },
+  { id: 'fts', label: '仅关键词' },
+  { id: 'vector', label: '仅向量' },
+  { id: 'graph', label: '同融合（图谱已不是独立一路）' },
+]
+
+const HIT_ROUTES: Record<string, string> = {
+  fts: styles.hitRouteFts, vector: styles.hitRouteVector, graph: styles.hitRouteGraph, hybrid: styles.hitRouteHybrid,
+}
+const HIT_ROUTE_LABEL: Record<string, string> = { fts: '关键词', vector: '向量', graph: '知识图谱', hybrid: '三路融合' }
+
+/** 去掉 markdown 脚手架，让命中读起来是一段正文而不是源码。 */
+export function snippetOf(content: string, limit = 200): string {
+  const plain = content
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/^#{1,6}\s+/gm, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return plain.length > limit ? `${plain.slice(0, limit)}…` : plain
+}
+
+/**
+ * 路线状态行。
+ *
+ * 0031 起它读的是 `diagnostics.routes` 而不是「`routes` 里有没有这个 id」：**降级也要看得见**。
+ * 原来的写法只能表达「跑没跑」，于是向量路坏掉时芯片显示「（未跑）」而 `routes` 里却写着
+ * `vector` —— 同一屏上两处互相矛盾，而且都没说为什么。
+ */
+export function RecallRoutes({ routes, backend, routesDetail, graphBoost }: {
+  routes: string[]
+  backend?: string
+  routesDetail?: RecallResultView['routesDetail']
+  graphBoost?: RecallResultView['graphBoost']
+}): ReactNode {
+  const active = new Set(routes.map(route => route.toLocaleLowerCase()))
+  type RouteDetail = NonNullable<RecallResultView['routesDetail']>[number]
+  const detailOf = (id: string): RouteDetail | undefined => routesDetail?.find(item => item.route === id)
+  return <div className={styles.routeRow} aria-label="召回路线">
+    {RECALL_ROUTES.map(route => {
+      const detail = detailOf(route.id)
+      const ran = detail ? detail.status === 'ran' : (active.has(route.id) || (route.id === 'fts' && active.has('keyword')))
+      const degraded = detail?.status === 'degraded'
+      const title = degraded && detail?.reason ? `${route.hint} —— ${detail.reason}` : route.hint
+      const suffix = degraded ? '（降级）' : ran ? (detail?.kept !== undefined ? ` ${detail.kept}` : '') : '（未跑）'
+      return <span key={route.id} className={cn(styles.routeChip, ran && styles.routeChipOn, degraded && styles.routeChipOff)} title={title}>
+        {route.label}{suffix}
+      </span>
+    })}
+    {/* 图谱是 boost：显示它加权了几条，而不是「跑没跑」。 */}
+    <span className={styles.routeChip} title="图谱只给已在候选池里的条目加权，不能自己制造候选">
+      图谱 boost {graphBoost && graphBoost.applied > 0 ? `+${graphBoost.applied}` : '未生效'}
+    </span>
+    <span className={styles.routeBackend}>{backend ? backend.toUpperCase() : 'FTS'}</span>
+  </div>
+}
+
+function HitList({ hits }: { hits: RecallHitView[] }): ReactNode {
+  if (hits.length === 0) return null
+  return <ul className={styles.hitList}>
+    {hits.map(hit => <li key={hit.unitId} className={styles.hitRow}>
+      <div className={styles.hitHead}>
+        <span className={cn(styles.hitRoute, HIT_ROUTES[hit.match] ?? styles.hitRouteFts)}>{HIT_ROUTE_LABEL[hit.match] ?? hit.match}</span>
+        <span className={styles.hitTitle} title={hit.unitId}>{hit.title}{hit.heading ? ` · ${hit.heading}` : ''}</span>
+        <span className={styles.hitScore}>{hit.score.toFixed(3)}</span>
+      </div>
+      <p className={styles.hitSnippet}>{hit.snippet || '（这条 wikiNote 没有正文）'}</p>
+      <div className={styles.hitFoot}>
+        <span className={styles.kbCode}>{hit.unitId}</span>
+        {hit.status && <span>状态 {hit.status}</span>}
+        {hit.entityType && <span>{hit.entityType}</span>}
+        {hit.rerankScore !== undefined && <span>rerank {hit.rerankScore.toFixed(3)}</span>}
+      </div>
+    </li>)}
+  </ul>
+}
+
+/**
+ * 进入 Context Pack 的 topN。重排这一栏必须显示得分的**来源**：
+ * rerank 真跑过就给 rerank 分数，降级时按融合分数排就只给融合分数，不混着显示。
+ */
+function ContextList({ items, provider }: { items: ContextItemView[]; provider?: string }): ReactNode {
+  if (items.length === 0) return null
+  const reranked = provider !== 'none' && items.some(item => item.rerankScore !== undefined)
+  return <ol className={styles.contextList}>
+    {items.map((item, index) => <li key={item.unitId} className={styles.contextRow}>
+      <span className={styles.contextRank}>{index + 1}</span>
+      <div className={styles.contextCopy}>
+        <div className={styles.contextHead}>
+          <span className={styles.hitTitle} title={item.unitId}>{item.title}</span>
+          <span className={styles.hitScore}>{reranked && item.rerankScore !== undefined ? `rerank ${item.rerankScore.toFixed(3)}` : `融合 ${item.score.toFixed(3)}`}</span>
+        </div>
+        <p className={styles.hitSnippet}>{item.snippet || '（这条 wikiNote 没有正文）'}</p>
+        <div className={styles.hitFoot}>
+          <span className={styles.kbCode}>{item.unitId}</span>
+          {item.wikiTitle && <span>父级 wiki：{item.wikiTitle}</span>}
+        </div>
+      </div>
+    </li>)}
+  </ol>
+}
+
+export interface RecallPanelProps {
+  /** 作用范围：当前知识库；空表示默认库。 */
+  kbId?: string
+  kbName?: string
+  visible: boolean
+  /** `recall` 看命中切片，`rerank` 看进入上下文的 topN，`runner` 是评测里的紧凑版。 */
+  /**
+   * `recall` = 知识库 → **召回重排**那一栏（0033 起召回与重排合成一栏，一次运行
+   * 从上到下给出三路命中 → 融合排序 → 精排丢了多少 → 进上下文的 topN）。
+   * `runner` = 评测里的紧凑版单问题检查。
+   */
+  variant?: 'recall' | 'runner'
+  defaults?: { mode?: string; topK?: number; topN?: number }
+  /** 设置写完或知识库切换时，用它把面板重置回初始值。 */
+  resetKey?: string
+  /**
+   * 卡头上的「参数」入口（0033）。面板**不认识设置**：它只在自己的卡头上腾一个位置，
+   * 具体挂哪一块由调用方决定（召回栏挂召回设置、重排栏挂重排设置、评测栏不挂）。
+   * 参数住在设置抽屉里，这里只是那扇离现场更近的门。
+   */
+  settingsChip?: ReactNode
+}
+
+export function RecallPanel({ kbId, kbName, visible, variant = 'recall', defaults, resetKey, settingsChip }: RecallPanelProps): ReactNode {
+  const [query, setQuery] = useState('销售额')
+  const [mode, setMode] = useState(defaults?.mode ?? 'hybrid')
+  const [topK, setTopK] = useState(defaults?.topK ?? 10)
+  const [topN, setTopN] = useState(defaults?.topN ?? 5)
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [result, setResult] = useState<RecallResultView | null>(null)
+
+  // 知识库换了或设置存了：面板上的默认值跟着走，否则显示的还是上一个库的参数。
+  // 用 effect 而不是渲染期 setState：这条同步是「外部输入变了」而不是渲染推导。
+  const modeDefault = defaults?.mode
+  const topKDefault = defaults?.topK
+  const topNDefault = defaults?.topN
+  useEffect(() => {
+    if (!visible) return
+    if (modeDefault) setMode(modeDefault)
+    if (topKDefault) setTopK(topKDefault)
+    if (topNDefault) setTopN(topNDefault)
+    setResult(null)
+  }, [visible, resetKey, modeDefault, topKDefault, topNDefault])
+
+  const run = async (): Promise<void> => {
+    const trimmed = query.trim()
+    if (!trimmed) { setError('请输入要测试的召回问题。'); return }
+    setBusy(true); setError(null)
+    try {
+      const boundedTopN = Math.min(topN, topK)
+      const params = new URLSearchParams({ query: trimmed, top_k: String(topK), top_n: String(boundedTopN), mode })
+      if (kbId) params.set('kb', kbId)
+      const payload = await requestJson<{
+        hits?: Array<Partial<RecallHitView> & { content?: string }>
+        context?: Array<{ note?: Partial<RecallHitView> & { content?: string }; wiki?: { entityId?: string; title?: string } | null }>
+        backend?: string
+        routes?: string[]
+        recallTopK?: number
+        candidatePool?: number
+        insufficientEvidence?: boolean
+        rerank?: { status?: string; provider?: string; threshold?: number; dropped?: number; topLogit?: number; vocabSize?: number }
+        diagnostics?: {
+          routes?: RecallResultView['routesDetail']
+          graphBoost?: { applied: number; weight: number }
+          abstention?: string
+          reason?: string
+          encoder?: { ok: boolean; reason?: string }
+        }
+        indexVersion?: number
+      }>(`/knowledge/search?${params.toString()}`)
+      const data = payload.data ?? {}
+      const hits: RecallHitView[] = (data.hits ?? []).map(hit => ({
+        unitId: hit.unitId ?? hit.title ?? 'unknown',
+        title: hit.title ?? hit.unitId ?? '未命名切片',
+        ...(hit.heading ? { heading: hit.heading } : {}),
+        snippet: snippetOf(hit.content ?? ''),
+        match: hit.match ?? 'fts',
+        score: Number(hit.score ?? 0),
+        ...(hit.status ? { status: hit.status } : {}),
+        ...(hit.entityType ? { entityType: hit.entityType } : {}),
+        ...(hit.rerankScore === undefined ? {} : { rerankScore: hit.rerankScore }),
+      }))
+      const context: ContextItemView[] = (data.context ?? []).map(item => ({
+        unitId: item.note?.unitId ?? item.note?.title ?? 'unknown',
+        title: item.note?.title ?? item.note?.unitId ?? '未命名切片',
+        snippet: snippetOf(item.note?.content ?? ''),
+        score: Number(item.note?.score ?? 0),
+        ...(item.note?.rerankScore === undefined ? {} : { rerankScore: item.note.rerankScore }),
+        ...(item.wiki?.title ? { wikiTitle: item.wiki.title } : {}),
+        ...(item.wiki?.entityId ? { wikiId: item.wiki.entityId } : {}),
+      }))
+      setResult({
+        count: hits.length,
+        backend: data.backend ?? 'fts',
+        routes: data.routes,
+        contextCount: context.length,
+        recallTopK: topK,
+        candidatePool: data.candidatePool,
+        contextTopN: Math.min(topN, topK),
+        rerank: data.rerank?.status,
+        rerankProvider: data.rerank?.provider,
+        ...(data.rerank?.threshold === undefined ? {} : { rerankThreshold: data.rerank.threshold }),
+        ...(data.rerank?.dropped === undefined ? {} : { rerankDropped: data.rerank.dropped }),
+        ...(data.rerank?.topLogit === undefined ? {} : { rerankTopLogit: data.rerank.topLogit }),
+        ...(data.rerank?.vocabSize === undefined ? {} : { rerankVocabSize: data.rerank.vocabSize }),
+        ...(data.insufficientEvidence === undefined ? {} : { insufficientEvidence: data.insufficientEvidence }),
+        ...(data.diagnostics?.routes === undefined ? {} : { routesDetail: data.diagnostics.routes }),
+        ...(data.diagnostics?.graphBoost === undefined ? {} : { graphBoost: data.diagnostics.graphBoost }),
+        ...(data.diagnostics?.abstention === undefined ? {} : { abstention: data.diagnostics.abstention }),
+        ...(data.diagnostics?.reason === undefined ? {} : { diagnosticsReason: data.diagnostics.reason }),
+        ...(data.diagnostics?.encoder === undefined ? {} : { encoder: data.diagnostics.encoder }),
+        hits,
+        context,
+        ...(kbName ? { kbName } : {}),
+        ...(data.indexVersion === undefined ? {} : { indexVersion: data.indexVersion }),
+      })
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const title = variant === 'runner' ? '单问题召回检查' : '召回重排 · 三路召回 + 精排'
+  const description = variant === 'runner'
+    ? '换路线、调 topK，然后看真正命中的切片与得分 —— 不是只看一个命中总数。'
+    : '跑一次真实召回，从上到下看完整条链：三路各自命中了什么 → 融合后的排序 → cross-encoder 丢了多少 → 最终进入模型上下文的 topN 是哪几条。'
+
+  return <Card className={styles.workspaceCard}>
+    <div className={styles.cardHeader}>
+      <div><h3><Search size={14} />{title}</h3></div>
+      <div className={styles.cardHeaderActions}>
+        {settingsChip}
+        <Badge tone={result?.backend === 'hybrid' ? 'success' : 'neutral'}>{result?.backend === 'hybrid' ? '三路融合' : 'FTS fallback'}</Badge>
+      </div>
+    </div>
+    <div className={styles.recallTop}>
+      <p className={styles.cardDescription}>{description}</p>
+      <span className={styles.recallScope}>作用范围 <b>{result?.kbName ?? kbName ?? '默认知识库'}</b></span>
+    </div>
+    <div className={styles.inputRow}>
+      <Input value={query} placeholder="例如：销售额如何计算"
+        onChange={event => setQuery(event.target.value)}
+        onKeyDown={event => { if (event.key === 'Enter') void run() }} />
+      <Button variant="default" onClick={() => void run()} disabled={busy}>
+        {variant === 'runner' && <Play size={13} />}{busy ? '测试中…' : variant === 'runner' ? '运行检查' : '测试'}
+      </Button>
+    </div>
+    <div className={styles.recallControls}>
+      <div className={styles.recallControl}>
+        <span>路线</span>
+        <SelectMenu
+          className="w-auto"
+          value={mode}
+          disabled={busy}
+          onValueChange={setMode}
+          aria-label="召回路线"
+          options={RECALL_MODES.map(item => ({ value: item.id, label: item.label }))}
+        />
+      </div>
+      <label>召回 topK
+        <Input type="number" min={1} max={50} value={topK} disabled={busy}
+          onChange={event => setTopK(Math.max(1, Math.min(50, Number(event.target.value) || 1)))} />
+      </label>
+      <label>上下文 topN
+        <Input type="number" min={1} max={topK} value={Math.min(topN, topK)} disabled={busy}
+          onChange={event => setTopN(Math.max(1, Math.min(topK, Number(event.target.value) || 1)))} />
+      </label>
+    </div>
+    {error && <p className={cn(styles.kbNotice, styles.kbNoticeError)} role="alert">{error}</p>}
+    <RecallRoutes routes={result?.routes ?? []} backend={result?.backend} routesDetail={result?.routesDetail} graphBoost={result?.graphBoost} />
+    {/* 弃答不是失败，是一个结论：知识库里没有能回答这个问题的东西。如实说出来，
+        而不是把 5 条噪声塞给模型让它编。 */}
+    {result?.insufficientEvidence && <p className={cn(styles.kbNotice, styles.kbNoticeError)} role="status">
+      <CircleHelp size={13} /><span>知识库里没有能回答这个问题的内容{result.diagnosticsReason ? `：${result.diagnosticsReason}` : ''}（判据：{result.abstention === 'rerank-threshold' ? '重排阈值' : result.abstention === 'vector-threshold' ? '向量余弦阈值' : '关键词相对阈值，判据较弱'}）</span>
+    </p>}
+    {result && <Badge className={styles.resultBadge} tone={result.insufficientEvidence ? 'warning' : 'success'}>
+      <Check size={13} />命中 {result.count} 条 wikiNotes · 上下文 {result.contextCount} 条{result.candidatePool ? ` · 候选池 ${result.candidatePool}` : ''}{result.rerank ? ` · rerank ${result.rerank}${result.rerankThreshold === undefined ? '' : `（阈值 ${result.rerankThreshold}${result.rerankDropped ? `，丢 ${result.rerankDropped}` : ''}${result.rerankTopLogit === undefined ? '' : `，最高 ${result.rerankTopLogit.toFixed(2)}`}）`}` : ''}
+    </Badge>}
+    {result && (result.hits.length > 0
+      ? <HitList hits={result.hits} />
+      : <div className={styles.emptyState}><CircleHelp size={16} />这个路线组合没有命中任何 wikiNote</div>)}
+    {result && result.context.length > 0 && <>
+      <div className={styles.kbSubHead}><h4>进入上下文包的 topN</h4><span>{result.context.length} 条</span></div>
+      <ContextList items={result.context} provider={result.rerankProvider} />
+    </>}
+    <div className={styles.infoList}>
+      <div><span>召回 topK</span><strong>{result?.recallTopK ?? topK}</strong></div>
+      <div><span>上下文 topN</span><strong>{result?.contextTopN ?? Math.min(topN, topK)}</strong></div>
+      <div><span>默认召回路线</span><strong>{mode}</strong></div>
+      {/* 词表是重排能不能用的**可见证据**：只有 5 个特殊 token 时模型照样出分，
+          所以「真的加载了 250002 条词表」这件事得看得见（0031）。 */}
+      {result?.rerankVocabSize !== undefined && <div><span>重排词表</span><strong>{result.rerankVocabSize}</strong></div>}
+      <div><span>索引版本</span><strong>{result?.indexVersion ? `v${result.indexVersion}` : '—'}</strong></div>
+    </div>
+  </Card>
+}

package/src/client/TypeDefinitionDrawer.tsx

@@ -0,0 +1,215 @@
+/**
+ * 「类型定义」抽屉 —— **一个知识库的词汇表**：来源分类注册表 + Wiki 卡片 schema。
+ *
+ * 为什么它是抽屉，而不是步骤轨上的第六步（0034）：
+ *
+ * 1. 步骤轨是一条**流水线**（收录 → 编译 → 关联 → 检索 → 精排），每一步回答「这一段
+ *    链路上发生了什么」，而且与架构图 B 带的五个节点一一对应。类型定义不属于任何一段：
+ *    它是所有段共享的词汇表 —— `source_type` 被收录消费，wiki 类型被编译消费。塞进箭头
+ *    链里会读成「流水线以定义类型收尾」，而定义其实在收录之前。
+ * 2. 它与「设置」抽屉是**两种作用域**，这才是不能合容器的地方：这两个注册表**按知识库**
+ *    持久化（写的是 base 记录，切库就换一套），而存储 / 收录闸门 / 构建 / 召回 / 重排是
+ *    **方案级参数**（`tita-data-agent-knowledge` 一个 namespace，整个方案一份）。放同一栏
+ *    里，用户会合理地以为「切到另一个库，Embedding 模型和 topK 也跟着换」——而它们不会。
+ *    所以两个抽屉各自在标题下写明作用域，一个写着库名，一个写着「本方案」。
+ *
+ * 写路径仍在 `KnowledgeBaseTab`（它持有 base 与 busy 状态机）：这个组件只管呈现与它
+ * 自己的编辑弹窗 —— 同一份数据不因为多了一个入口就多一个写入口。
+ */
+
+import { useState, type ChangeEvent, type ReactNode } from 'react'
+import { Check, Pencil, Plus, ShieldCheck, Trash2 } from '@tita-data-agent/ui/icons'
+import { Button, Input, Label, Switch, 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 { styles } from './styles.ts'
+import type { SourceTypeCatalog, SourceTypeDef, SourceTypeDraft } from './KnowledgeBaseTab.tsx'
+import { WikiTypeSection, type WikiTypeView } from './WikiTypeEditor.tsx'
+
+export interface TypeDefinitionDrawerProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** 作用域说明里要写库名 —— 这两个注册表是按库的，切库就换一套。 */
+  kbName?: string
+  /** Wiki 类型目录（模板与只读规则）按库拉取，所以这一层也要库 id。 */
+  kbId: string
+  sourceTypes: SourceTypeDef[]
+  wikiTypes: WikiTypeView[]
+  schemaMode: 'strict' | 'report'
+  customized: boolean
+  catalog: SourceTypeCatalog | null
+  busy: string | null
+  onSaveSourceType: (draft: SourceTypeDraft) => Promise<void>
+  onToggleSourceType: (def: SourceTypeDef, enabled: boolean) => Promise<void>
+  onRemoveSourceType: (def: SourceTypeDef) => Promise<void>
+  onApplyWikiTypes: (next: WikiTypeView[], describe: string) => Promise<void>
+  onModeChange: (mode: 'strict' | 'report') => Promise<void>
+  onResetWikiTypes: () => Promise<void>
+}
+
+const EMPTY_DRAFT: SourceTypeDraft = { mode: 'create', id: '', label: '', description: '', signals: '', excludes: '' }
+
+export function TypeDefinitionDrawer({
+  open, onOpenChange, kbName, kbId, sourceTypes, wikiTypes, schemaMode, customized, catalog, busy,
+  onSaveSourceType, onToggleSourceType, onRemoveSourceType, onApplyWikiTypes, onModeChange, onResetWikiTypes,
+}: TypeDefinitionDrawerProps): ReactNode {
+  /**
+   * 分类编辑弹窗的草稿。它属于这个抽屉 —— 注册表搬进来之后，只有这里会开这个弹窗。
+   * 是一个 Radix Dialog 套在 Radix Drawer 上（两者同源，`RestoreDialog` 也这么用）：
+   * 编辑一份判定文案需要一块**受保护的焦点**，它不是可以边看列表边改的东西。
+   */
+  const [draft, setDraft] = useState<SourceTypeDraft & { open: boolean }>({ ...EMPTY_DRAFT, open: false })
+  const closeEditor = (): void => setDraft(current => ({ ...current, open: false }))
+
+  const openEditor = (def?: SourceTypeDef): void => {
+    setDraft(def
+      ? { open: true, mode: 'edit', id: def.id, label: def.label, description: def.description, signals: def.signals.join('\n'), excludes: def.excludes.join('\n') }
+      : { ...EMPTY_DRAFT, open: true })
+  }
+
+  return <Drawer open={open} onOpenChange={onOpenChange}>
+    {open && <DrawerContent className={styles.settingsDrawer} resizable resizeKey="tita-typedef-drawer">
+      <DrawerHeader>
+        <DrawerTitle>类型定义</DrawerTitle>
+        {/* 作用域写在标题下面，只写一次：切库换的是**这一套**，不是方案的参数。 */}
+        {/* <DrawerDescription>
+          本库定义{kbName ? <> · <b>{kbName}</b></> : null} —— 这两个注册表只属于这个知识库，切库就换一套。
+          方案级参数（存储 / 收录闸门 / 构建 / 召回 / 重排）在右上角齿轮的「设置」里。
+        </DrawerDescription> */}
+      </DrawerHeader>
+      <DrawerBody>
+        <div className={styles.settingsStack}>
+          <section className={styles.settingsSection} aria-labelledby="tita-typedef-source-title">
+            <div className={styles.settingsSectionHeader}>
+              <div>
+                <h3 id="tita-typedef-source-title"><ShieldCheck size={13} /> 来源类型</h3>
+                <p><b>source_type</b> 描述业务场景，不描述文件格式（载体走 source_format）。</p>
+              </div>
+              <span className={styles.kbCount}>{sourceTypes.length} 个分类</span>
+            </div>
+            <p className={styles.kbHint}>
+              三档默认值：<b>兜底分类</b>必须存在且不可停用；<b>内置分类</b>可改文案、可停用，但不能删除；
+              <b>自定义分类</b>可增可删，新增时必须写清判定文案——它会拼进下面那段内置提示词里交给 Agent 判断。
+              分类下还有来源时不能删除，先迁移。
+            </p>
+            <ul className={styles.kbSourceList}>
+              {sourceTypes.map(def => <li key={def.id} className={styles.kbSourceRow}>
+                <span className={styles.kbSourceName}>
+                  <span className={styles.kbSourceLabel}>{def.label}</span>
+                  <code className={styles.kbSourceId}>{def.id}</code>
+                  <span className={cn(styles.kbSourceTag, !def.fallback && styles.kbSourceTagLock)}>{def.fallback ? '兜底' : def.builtin ? '内置' : '自定义'}</span>
+                </span>
+                <span className={styles.kbTypeCount}>{def.sourceCount} 个来源</span>
+                <Switch
+                  checked={def.enabled}
+                  disabled={def.fallback || busy !== null}
+                  title={def.fallback ? '兜底分类不能停用：判定链全不命中时必须有一个归属' : `启用 / 停用 ${def.label}`}
+                  onCheckedChange={checked => void onToggleSourceType(def, checked)}
+                />
+                <Button variant="ghost" size="icon" title={`编辑 ${def.label} 的判定文案`} aria-label={`编辑分类 ${def.label}`} disabled={busy !== null} onClick={() => openEditor(def)}><Pencil size={13} /></Button>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  disabled={busy !== null || def.builtin || def.fallback || def.sourceCount > 0}
+                  title={def.builtin || def.fallback ? '内置 / 兜底分类不可删除，只能停用' : def.sourceCount > 0 ? `该分类下还有 ${def.sourceCount} 个来源，先迁移再删除` : `删除分类 ${def.label}`}
+                  aria-label={`删除分类 ${def.label}`}
+                  onClick={() => void onRemoveSourceType(def)}
+                >
+                  <Trash2 size={13} />
+                </Button>
+              </li>)}
+            </ul>
+            <div className={styles.kbSourceAdd}>
+              <p className={styles.kbHint}>追加分类（例如 <b>test_unit 测试用例</b>）时必须写清「怎么判断它是这一类」。</p>
+              <Button variant="outline" size="sm" onClick={() => openEditor()} disabled={busy !== null}><Plus size={13} />新增类型</Button>
+            </div>
+
+            {catalog && <details className={styles.kbPrompt}>
+              <summary><ShieldCheck size={12} /> 判定规则（内置，只读）· {catalog.classifierPrompt.title} v{catalog.classifierPrompt.version}</summary>
+              <p className={styles.kbPromptNote}>{catalog.classifierPrompt.confidenceRule}</p>
+              <ol className={styles.kbPromptSteps}>
+                {catalog.classifierPrompt.steps.map(step => <li key={step.type} className={cn(!step.enabled && styles.kbPromptOff)}>
+                  <code>{step.type}</code> {step.rule}
+                  {step.exists ? (step.enabled ? '' : '（已停用，不要落到它上面）') : '（该分类已不存在）'}
+                </li>)}
+              </ol>
+              <p className={styles.kbPromptNote}><b>兜底：</b>{catalog.classifierPrompt.fallback.note}</p>
+              <p className={styles.kbPromptNote}><b>拿不准时：</b>{catalog.classifierPrompt.escalation.note}</p>
+              <p className={styles.kbPromptNote}><b>自定义分类怎么参与：</b>{catalog.classifierPrompt.extensionRule}</p>
+              <p className={styles.kbPromptNote}>这段规则内置在代码里，不随知识库变化，也不允许修改；可编辑的只有每个分类自己的描述、signals 与 excludes。</p>
+            </details>}
+          </section>
+
+          <section className={styles.settingsSection} aria-labelledby="tita-typedef-wiki-title">
+            <div className={styles.settingsSectionHeader}>
+              <div>
+                <h3 id="tita-typedef-wiki-title">Wiki 类型（卡片 schema）</h3>
+                <p>每个类型规定必填小节与必填字段，写卡片时按它校验。</p>
+              </div>
+              <span className={styles.kbCount}>{wikiTypes.length} 个类型</span>
+            </div>
+            <p className={styles.kbHint}>
+              这就是编译设置里的 <b>Schema 类型</b>。早先那种「逗号分隔的类型名文本框」已撤掉 ——
+              它既不参与校验也不被生成逻辑读取，是个改了不生效的假开关。
+            </p>
+            <WikiTypeSection
+              kbId={kbId}
+              types={wikiTypes}
+              mode={schemaMode}
+              customized={customized}
+              canEdit={busy === null}
+              busy={busy !== null}
+              onApply={onApplyWikiTypes}
+              onModeChange={onModeChange}
+              onReset={onResetWikiTypes}
+            />
+          </section>
+        </div>
+      </DrawerBody>
+
+      <Dialog open={draft.open} onOpenChange={next => { if (!next) closeEditor() }}>
+        {draft.open && <DialogContent>
+          <DialogHeader><DialogTitle>{draft.mode === 'create' ? '新增来源分类' : `编辑来源分类 · ${draft.label}`}</DialogTitle></DialogHeader>
+          <div className={styles.kbForm}>
+            <label className={styles.kbField}><Label>分类 id</Label>
+              <Input value={draft.id} disabled={draft.mode === 'edit'} spellCheck={false} placeholder="test_unit"
+                onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft({ ...draft, id: event.target.value })} />
+              <span className={styles.kbHint}>小写字母 / 数字 / 下划线，创建后不可修改——它是写进 SourceRaw frontmatter 的稳定标识。</span>
+            </label>
+            <label className={styles.kbField}><Label>显示名</Label>
+              <Input value={draft.label} placeholder="测试用例"
+                onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft({ ...draft, label: event.target.value })} />
+            </label>
+            <label className={styles.kbField}><Label>一句话定义（必填）</Label>
+              <textarea className={styles.kbTextarea} value={draft.description} spellCheck={false}
+                placeholder="以单个可执行验证点为中心、用于判定某项功能是否正确的用例记录。"
+                onChange={(event: ChangeEvent<HTMLTextAreaElement>) => setDraft({ ...draft, description: event.target.value })} />
+              <span className={styles.kbHint}>写清「是什么」，不要写成「包含哪些文件」——载体格式走 source_format，Agent 靠这句话判断。</span>
+            </label>
+            <label className={styles.kbField}><Label>signals · 典型信号（每行一条，至少 2 条）</Label>
+              <textarea className={styles.kbTextarea} value={draft.signals} spellCheck={false}
+                placeholder={'包含前置条件 / 操作步骤 / 预期结果三要素\n带 case id、优先级、关联需求编号'}
+                onChange={(event: ChangeEvent<HTMLTextAreaElement>) => setDraft({ ...draft, signals: event.target.value })} />
+            </label>
+            <label className={styles.kbField}><Label>excludes · 排除项（每行一条，至少 1 条）</Label>
+              <textarea className={styles.kbTextarea} value={draft.excludes} spellCheck={false}
+                placeholder={'整份测试方案或测试计划归 document\n线上故障根因排查归 question'}
+                onChange={(event: ChangeEvent<HTMLTextAreaElement>) => setDraft({ ...draft, excludes: event.target.value })} />
+              <span className={styles.kbHint}>每条都要写出「该归到哪个分类」（用 id 或标签）；指向不存在的分类会被拒绝，否则边界是悬空的。</span>
+            </label>
+          </div>
+          <DialogFooter>
+            <Button variant="ghost" onClick={closeEditor}>取消</Button>
+            <Button
+              variant="default"
+              disabled={busy !== null || !draft.id.trim() || !draft.label.trim() || !draft.description.trim()}
+              onClick={() => void onSaveSourceType({ mode: draft.mode, id: draft.id, label: draft.label, description: draft.description, signals: draft.signals, excludes: draft.excludes })}
+            ><Check size={13} />保存</Button>
+          </DialogFooter>
+        </DialogContent>}
+      </Dialog>
+    </DrawerContent>}
+  </Drawer>
+}