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

package/src/client/WikiFlowCard.tsx

@@ -0,0 +1,226 @@
+/**
+ * 「Wiki 抽取流程」卡片（issue 0024 的流程说明）。
+ *
+ * 它把"原文件 → Wiki 卡片"这段**单文档抽取**画成四个阶段，并明确标出每一段的
+ * 实现状态——**没有实现的不画成已实现**：这张图是给人看的契约，不是宣传。
+ *
+ * 与腾讯 WeKnora 四阶段 Map-Reduce 的对应关系写在每一段的"对应 WeKnora"一行里：
+ * 我们是**单文档**抽取，所以它的「批内 Taxonomy 规划」退化成「按库复用已有类型」，
+ * 「Pass 1..N 分块引文」在文档不长时与候选抽取合并成一次调用。
+ */
+
+import type { ReactNode } from 'react'
+import {
+  ArrowDown, Box, Check, FileText, GitBranch, Layers3, RefreshCw, ShieldCheck, Sparkles, Wrench,
+} from '@tita-data-agent/ui/icons'
+import { Badge, Card, cn } from '@tita-data-agent/ui/components'
+import { styles } from './styles.ts'
+
+type StageStatus = 'done' | 'partial' | 'todo'
+
+interface Stage {
+  id: string
+  icon: typeof FileText
+  tone: 'blue' | 'violet' | 'green' | 'amber'
+  pass: string
+  title: string
+  /** 这一段的输入 → 输出。 */
+  io: string
+  /** 这一段做什么（要点，`**…**` 会被渲染成粗体）。 */
+  body: string[]
+  /** 是否调用模型。 */
+  llm: boolean
+  /** 与 WeKnora 四阶段的对应关系。 */
+  weknora: string
+  status: StageStatus
+  statusNote: string
+}
+
+const STAGES: Stage[] = [
+  {
+    id: 'candidates',
+    icon: Sparkles,
+    tone: 'violet',
+    pass: 'Pass 0',
+    title: '候选抽取：实体 / 概念 / 关系',
+    io: '一个 SourceRaw → 候选项列表',
+    body: [
+      '每个候选项的身份是**三件事一起定**：类型 + 名称（slug）+ 证据分块。类型与名称必须同时决定，因为 slug 的命名空间就是 `<类型>/<名称>`。',
+      '关系抽两处：卡片之间的 wiki 链接（正文里的 `[[类型/名称|标题]]`），以及实体之间的**图谱边**（`03_compiled/knowledge_graph.json`，目前只有 `supported_by` 溯源边）。',
+      '**slug 稳定性**：文档里提到的实体如果已有对应页面，复用它的 slug，不要另起一个近义 slug。',
+    ],
+    llm: false,
+    weknora: '对应它的 Pass 0（抽 entities + concepts，强制复用已有 slug）。',
+    status: 'partial',
+    statusNote: '已实现**规则抽取**（正文标题、[[链接]]、frontmatter 的 candidates / entities / concepts / relations），编译时自动跑、增量跳过没变的来源；模型驱动的候选工具（propose_wiki_cards）还没有 —— 所以「抽什么」目前由文档结构决定，不是由模型判断。',
+  },
+  {
+    id: 'normalize',
+    icon: GitBranch,
+    tone: 'blue',
+    pass: '归一',
+    title: '与已有 Wiki 合并：同指一物就复用',
+    io: '候选项列表 + 库内已有卡片 → 去重后的落点',
+    body: [
+      '**判重按 slug 与别名，不按标题字符串**：标题可以改，slug 是稳定标识。',
+      '核心原则是「**相关 ≠ 相同**」——相关的话题不要合并，只有同指一物才合并。',
+      '命中已有 → 记下"增量合并到该页"；没命中 → 记下"新建"。',
+      'WeKnora 的「批内 Taxonomy 规划」在单文档场景退化成**库内复用**：优先沿用已有的类型与命名，不为了一个新页面另起一套。',
+    ],
+    llm: false,
+    weknora: '对应它的 Taxonomy 规划 + WikiDeduplicationPrompt（related ≠ same）；批内统筹改为库内复用。',
+    status: 'done',
+    statusNote: '已实现：按 entityId / title / metadata.aliases 建别名索引判重，同指一物就合并 source_refs（重复的出处不会写第二遍），关系候选不参与合并。',
+  },
+  {
+    id: 'write',
+    icon: FileText,
+    tone: 'green',
+    pass: '落卡',
+    title: '写卡片：命中的增量合并，没命中的按模板新建',
+    io: '落点 + 证据 → 02_wiki/<类型>/<id>.md',
+    body: [
+      '必须带 `source_refs`，且每个来源都要真实存在（写了不存在的来源会被直接拒绝）。',
+      '必填小节与必填字段按**类型 schema** 填；缺了要么被拒（严格模式）要么标成待补（report 模式）。',
+      '新建的卡片是 `unreviewed`，不自动当成已审核的知识。',
+      '正文必须**严格接地**：只写证据里有的东西，去重，不写自链接。',
+    ],
+    llm: true,
+    weknora: '对应它的 Reduce：按 slug 增量合并页面，提示词硬约束接地 / 禁幻觉 / 去重 / 禁自链接。',
+    status: 'done',
+    statusNote: '已实现：write_knowledge_card + 类型 schema 与三层校验（0024）',
+  },
+  {
+    id: 'finalize',
+    icon: Wrench,
+    tone: 'amber',
+    pass: 'Finalize',
+    title: '收尾：索引、死链、交叉链接、质检',
+    io: '02_wiki → wikiNotes / 图谱 / 待补清单',
+    body: [
+      '重建索引页、清理死链、补交叉链接——这几步**不调用模型**，纯靠规则与图算法。',
+      '跑三层校验（format / reference / semantic），产出"待补 N 张"清单，人可以按清单补。',
+      '之后才轮到编译：卡片 → wikiNotes → 向量 + 图谱。',
+    ],
+    llm: false,
+    weknora: '对应它的 Finalize（重建索引 / 清死链 / 补交叉链接，纯 SQL + 图算法）。',
+    status: 'partial',
+    statusNote: '部分实现：三层质检已实现；索引页 / 死链 / 交叉链接待实现',
+  },
+]
+
+const STATUS_META: Record<StageStatus, { label: string; tone: 'success' | 'warning' | 'neutral' }> = {
+  done: { label: '已实现', tone: 'success' },
+  partial: { label: '部分实现', tone: 'warning' },
+  todo: { label: '待实现', tone: 'neutral' },
+}
+
+const TONE_CLASS: Record<Stage['tone'], string> = {
+  blue: styles.wikiFlowBlue,
+  violet: styles.wikiFlowViolet,
+  green: styles.wikiFlowGreen,
+  amber: styles.wikiFlowAmber,
+}
+
+/** 三条判定规则 —— 对应"抽取 → 判类型 → 看是否已存在"这三步，但顺序与判据都被钉死。 */
+const RULES: Array<{ order: string; title: string; body: string }> = [
+  {
+    order: '1',
+    title: '类型在抽取时就要定，不能留到最后再判',
+    body: '候选项的身份是「类型 + 名称 + 证据」。slug 的命名空间是 `<类型>/<名称>`，类型晚定一步，slug 就得重算一次。',
+  },
+  {
+    order: '2',
+    title: '类型只能来自注册表，**不命中不要自创**',
+    body: '自创一个类型等于这张卡片没有 schema：没有必填小节、没有模板、校验不了。都不命中时落到 `concept`，或先在「Wiki 类型」里把它登记成正式类型再抽。',
+  },
+  {
+    order: '3',
+    title: '「是否已存在」按 slug 与别名判，不按标题',
+    body: '命中的走**增量合并**（旧版本先快照，回滚本身也可回滚），没命中的才新建 `draft`。相关不等于相同：别把相近的话题并成一条。',
+  },
+]
+
+/** 把文案里的 `**强调**` 渲染成粗体，避免在 JSX 里写 Markdown 却显示成星号。 */
+function rich(text: string): ReactNode {
+  return text.split(/\*\*([^*]+)\*\*/g).map((part, index) => (index % 2 === 1 ? <b key={index}>{part}</b> : <span key={index}>{part}</span>))
+}
+
+export function WikiFlowCard(): ReactNode {
+  return <Card className={styles.kbCard}>
+    <div className={styles.kbCardHead}>
+      <div><h3><RefreshCw size={13} />Wiki 抽取流程（原文件 → Wiki）</h3></div>
+      <span className={styles.kbCount}>4 段 · 目前没有一段由管线自己调模型</span>
+    </div>
+    <p className={styles.kbHint}>
+      单文档抽取的完整链路。<b>与已落库的卡片合并是这条链路的中心</b>——它决定这次是"新建一页"还是"补进已有页面"，
+      也决定 slug 能不能稳定下来。状态徽标按代码现状标注：没实现的不画成已实现。
+      前两段现在由编译管线用**规则**完成（编译时自动跑，正文没变的来源按指纹跳过）；
+      设计里那两次模型调用（候选抽取工具、归一提示词）还没有，所以这两段标的是「部分实现」。
+    </p>
+
+    <div className={styles.wikiFlow}>
+      <div className={styles.wikiFlowSource}>
+        <FileText size={14} />
+        <span>
+          <strong>SourceRaw</strong>
+          <small>01_source_truth/*.md — 原始可追溯文档，本身不进召回</small>
+        </span>
+      </div>
+
+      {STAGES.map(stage => {
+        const Icon = stage.icon
+        const status = STATUS_META[stage.status]
+        return <div className={styles.wikiFlowStageWrap} key={stage.id}>
+          <span className={styles.wikiFlowArrow} aria-hidden="true"><ArrowDown size={14} /></span>
+          <div className={cn(styles.wikiFlowStage, TONE_CLASS[stage.tone])}>
+            <div className={styles.wikiFlowStageHead}>
+              <span className={styles.wikiFlowPass}><Icon size={13} />{stage.pass}</span>
+              <strong>{stage.title}</strong>
+              <Badge tone={status.tone}>{status.label}</Badge>
+              <span className={styles.wikiFlowLlm}>{stage.llm ? '调用模型' : '不调用模型'}</span>
+            </div>
+            <p className={styles.wikiFlowIo}>{stage.io}</p>
+            <ul className={styles.wikiFlowBody}>
+              {stage.body.map(line => <li key={line}>{rich(line)}</li>)}
+            </ul>
+            <p className={styles.wikiFlowNote}><b>对应 WeKnora：</b>{stage.weknora}</p>
+            <p className={styles.wikiFlowNote}>{stage.statusNote}</p>
+          </div>
+        </div>
+      })}
+
+      <span className={styles.wikiFlowArrow} aria-hidden="true"><ArrowDown size={14} /></span>
+      <div className={styles.wikiFlowSink}>
+        <Layers3 size={14} />
+        <span>
+          <strong>Wiki 卡片 → wikiNotes → 向量 / 图谱</strong>
+          <small>02_wiki/&lt;类型&gt;/&lt;id&gt;.md → 03_compiled/* — 召回单元在编译段才产生</small>
+        </span>
+      </div>
+    </div>
+
+    <div className={styles.kbSubHead}><h4><ShieldCheck size={13} />三条判定规则（内置，只读）</h4></div>
+    <ul className={styles.wikiFlowRules}>
+      {RULES.map(rule => <li key={rule.order}>
+        <span className={styles.wikiFlowRuleOrder}><Check size={11} />{rule.order}</span>
+        <span>
+          <strong>{rich(rule.title)}</strong>
+          <small>{rich(rule.body)}</small>
+        </span>
+      </li>)}
+    </ul>
+
+    <div className={styles.wikiFlowDiff}>
+      <Box size={13} />
+      <span>
+        WeKnora 是<b>知识库级后台管道</b>（Redis 队列 + 每 KB 并发治理 + Neo4j），本仓库不照抄：
+        模型调用一律经 Agent，所以前两段由工具驱动、由人复核。<b>抽取粒度</b>
+        （focused / standard / exhaustive）这个旋钮值得抄——它把"抽多少"变成用户能理解的东西。
+      </span>
+    </div>
+  </Card>
+}
+
+/** 流程内的三条判定规则（与卡片同源，供文档与工具描述复用）。 */
+export const WIKI_FLOW_RULES = RULES

package/src/client/WikiTypeEditor.tsx

@@ -0,0 +1,332 @@
+/**
+ * 「Wiki 类型」配置区块（issue 0024）——**这张界面就是"SourceRaw → Wiki"的约束入口**。
+ *
+ * 它决定三件事：
+ * 1. 能生成哪些类型的卡片（`entities` 清单，停用的类型模型不该再用）；
+ * 2. 每类卡片**必须**有哪些小节与字段（缺了要么被拒、要么标成待补，看生效方式）；
+ * 3. 模板卡长什么样（由小节派生，新建卡片时照抄）。
+ *
+ * 组件自包含：列表与编辑弹窗在这里，数据由父级（知识库面板）以 props 传入，
+ * 写入统一走 `onApply`（整表替换）。它另外自己拉一次 `/knowledge/wiki-types`
+ * 取"待补"清单与内置只读判定规则——那是展示信息，不影响写入契约。
+ */
+
+import { useCallback, useEffect, useState, type ChangeEvent, type ReactNode } from 'react'
+import {
+  AlertCircle, Check, ClipboardCheck, Eye, Pencil, Plus, RotateCcw, ShieldCheck, Trash2, X,
+} from '@tita-data-agent/ui/icons'
+import { Badge, Button, Input, Label, SelectMenu, Switch, cn } from '@tita-data-agent/ui/components'
+import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from '@tita-data-agent/ui/overlays'
+import { styles } from './styles.ts'
+
+export interface WikiSectionSpec { label: string; required: boolean }
+export interface WikiFieldSpec { name: string; required: boolean; note: string }
+
+export interface WikiTypeView {
+  id: string
+  label: string
+  description: string
+  layer: 'type' | 'instance'
+  sections: WikiSectionSpec[]
+  fields: WikiFieldSpec[]
+  sourceTypes: string[]
+  examples: string[]
+  template: string
+  enabled: boolean
+  builtin: boolean
+  cardCount: number
+}
+
+export interface WikiTypeIssue {
+  entityId: string
+  entityType: string
+  level: string
+  field?: string
+  message: string
+}
+
+interface WikiTypeDraft {
+  open: boolean
+  mode: 'create' | 'edit'
+  id: string
+  label: string
+  description: string
+  layer: 'type' | 'instance'
+  /** 每行一条；结尾加 `?` 表示可选小节。 */
+  sections: string
+  /** 每行一条，`name|说明`；`name|说明|可选` 表示非必填。 */
+  fields: string
+  /** 每行一个来源分类 id；留空表示不限制。 */
+  sourceTypes: string
+  examples: string
+}
+
+const EMPTY_DRAFT: WikiTypeDraft = { open: false, mode: 'create', id: '', label: '', description: '', layer: 'type', sections: '', fields: '', sourceTypes: '', examples: '' }
+
+const TYPE_ID_PATTERN = /^[a-z][a-z0-9_/-]{1,60}$/
+
+interface Props {
+  kbId: string
+  types: WikiTypeView[]
+  mode: 'strict' | 'report'
+  /** 用户是否改过（决定「恢复默认」是否可用）。 */
+  customized: boolean
+  canEdit: boolean
+  busy: boolean
+  /** 整表替换 wikiTypes。 */
+  onApply: (next: WikiTypeView[], describe: string) => Promise<void>
+  onModeChange: (mode: 'strict' | 'report') => Promise<void>
+  onReset: () => Promise<void>
+}
+
+/** 由小节派生模板卡 —— 与服务端 `templateCardFor` 同一规则，避免两处漂移。 */
+function templatePreview(sections: WikiSectionSpec[], fields: WikiFieldSpec[]): string {
+  const head = fields.filter(field => field.required).map(field => `> 必填字段：\`${field.name}\`（${field.note}）`)
+  const body = sections.map(section => `## ${section.label}\n\n（${section.required ? '必填' : '可选'}：写什么）\n`).join('\n')
+  const required = sections.filter(section => section.required).map(section => section.label)
+  return [required.length > 0 ? `<!-- 必填小节：${required.join(' / ')} -->` : '', ...head, '', body].filter(Boolean).join('\n')
+}
+
+function parseSections(text: string): WikiSectionSpec[] {
+  return text.split('\n').map(line => line.trim()).filter(Boolean).map(line => {
+    const optional = line.endsWith('?')
+    return { label: optional ? line.slice(0, -1).trim() : line, required: !optional }
+  }).filter(section => section.label.length > 0)
+}
+
+function parseFields(text: string): WikiFieldSpec[] {
+  return text.split('\n').map(line => line.trim()).filter(Boolean).map(line => {
+    const [name = '', note = '', optional = ''] = line.split('|').map(part => part.trim())
+    return { name, note, required: optional !== '可选' && optional !== 'optional' }
+  }).filter(field => field.name.length > 0)
+}
+
+const LAYER_LABEL: Record<WikiTypeView['layer'], string> = { type: '类型层', instance: '实例层' }
+
+export function WikiTypeSection({ kbId, types, mode, customized, canEdit, busy, onApply, onModeChange, onReset }: Props): ReactNode {
+  const [draft, setDraft] = useState<WikiTypeDraft>(EMPTY_DRAFT)
+  const [notice, setNotice] = useState<{ tone: 'success' | 'error'; text: string } | null>(null)
+  const [rules, setRules] = useState('')
+  const [issues, setIssues] = useState<WikiTypeIssue[]>([])
+  const [issueCount, setIssueCount] = useState(0)
+
+  const load = useCallback(async (): Promise<void> => {
+    try {
+      const response = await fetch(`/knowledge/wiki-types?kb=${encodeURIComponent(kbId)}`)
+      const payload = await response.json() as { data?: { rules?: string; issues?: WikiTypeIssue[]; issueCount?: number } }
+      setRules(payload.data?.rules ?? '')
+      setIssues(payload.data?.issues ?? [])
+      setIssueCount(payload.data?.issueCount ?? 0)
+    } catch { /* 待补清单是展示信息，取不到不影响编辑 */ }
+  }, [kbId])
+
+  useEffect(() => { if (canEdit || kbId) void load() }, [load, canEdit])
+
+  const openEditor = (type?: WikiTypeView): void => {
+    setNotice(null)
+    setDraft(type
+      ? {
+        open: true, mode: 'edit', id: type.id, label: type.label, description: type.description, layer: type.layer,
+        sections: type.sections.map(section => section.required ? section.label : `${section.label}?`).join('\n'),
+        fields: type.fields.map(field => [field.name, field.note, field.required ? '' : '可选'].filter(Boolean).join('|')).join('\n'),
+        sourceTypes: type.sourceTypes.join('\n'),
+        examples: type.examples.join('\n'),
+      }
+      : { ...EMPTY_DRAFT, open: true })
+  }
+
+  const save = async (): Promise<void> => {
+    const id = draft.id.trim()
+    const label = draft.label.trim()
+    const description = draft.description.trim()
+    const sections = parseSections(draft.sections)
+    if (!TYPE_ID_PATTERN.test(id)) { setNotice({ tone: 'error', text: '类型 id 必须是小写字母开头，可含数字 / 下划线 / 连字符 / 斜杠，例如 metric、diagnosis/symptom' }); return }
+    if (draft.mode === 'create' && types.some(type => type.id === id)) { setNotice({ tone: 'error', text: `类型 id 已存在：${id}` }); return }
+    if (!label) { setNotice({ tone: 'error', text: '显示名不能为空' }); return }
+    if (description.length < 8) { setNotice({ tone: 'error', text: '定义必填：写清这个类型「是什么」，模型靠它判断卡片属于哪一类' }); return }
+    if (sections.length === 0) { setNotice({ tone: 'error', text: '至少写一个小节' }); return }
+    if (!sections.some(section => section.required)) { setNotice({ tone: 'error', text: '至少要有一个必填小节（不加 `?` 的即为必填）' }); return }
+    const fields = parseFields(draft.fields)
+    const next: WikiTypeView = {
+      id,
+      label,
+      description,
+      layer: draft.layer,
+      sections,
+      fields,
+      sourceTypes: draft.sourceTypes.split('\n').map(line => line.trim()).filter(Boolean),
+      examples: draft.examples.split('\n').map(line => line.trim()).filter(Boolean),
+      template: templatePreview(sections, fields),
+      enabled: types.find(type => type.id === id)?.enabled ?? true,
+      builtin: types.find(type => type.id === id)?.builtin ?? false,
+      cardCount: types.find(type => type.id === id)?.cardCount ?? 0,
+    }
+    const list = draft.mode === 'create' ? [...types, next] : types.map(type => type.id === id ? next : type)
+    setDraft(EMPTY_DRAFT)
+    await onApply(list, draft.mode === 'create' ? `已新增卡片类型「${label}」` : `卡片类型「${label}」已更新`)
+  }
+
+  const toggle = (type: WikiTypeView, enabled: boolean): Promise<void> =>
+    onApply(types.map(item => item.id === type.id ? { ...item, enabled } : item), `${type.label} 已${enabled ? '启用' : '停用'}`)
+
+  const remove = (type: WikiTypeView): Promise<void> =>
+    onApply(types.filter(item => item.id !== type.id), `已删除卡片类型「${type.label}」`)
+
+  const enabledCount = types.filter(type => type.enabled).length
+
+  return <>
+    <div className={styles.kbSubHead}>
+      <h4><ClipboardCheck size={13} />Wiki 类型（卡片 schema）</h4>
+      <span>{enabledCount} / {types.length} 启用{customized ? ' · 已自定义' : ''}</span>
+    </div>
+    <p className={styles.kbHint}>
+      从原文件生成 Wiki 卡片时，<b>类型决定这张卡片该长什么样</b>：先按「定义 + 例如」判断属于哪一类，
+      再按<b>必填小节</b>写正文、按<b>必填字段</b>填 front matter。模板卡由小节派生，新建卡片时照抄即可。
+    </p>
+
+    <div className={styles.wikiTypeBar}>
+      <label className={styles.wikiTypeMode}>
+        <Switch
+          checked={mode === 'strict'}
+          disabled={!canEdit || busy}
+          onCheckedChange={checked => void onModeChange(checked ? 'strict' : 'report')}
+        />
+        <span>
+          <strong>严格模式</strong>
+          <small>{mode === 'strict' ? '缺必填小节 / 字段直接拒绝写入' : '只把问题标在卡片上，不拦截写入'}</small>
+        </span>
+      </label>
+      <span className={styles.wikiTypeIssueCount} title="对该库已落库卡片跑三层校验的结果">
+        {issueCount > 0 ? `${issueCount} 张卡片待补` : '卡片均符合 schema'}
+      </span>
+      <span className={styles.kbCardActions}>
+        {canEdit && <Button variant="ghost" size="sm" disabled={busy || !customized} title={customized ? '清除自定义，回到出厂类型' : '当前就是出厂类型'} onClick={() => void onReset()}><RotateCcw size={13} />恢复默认</Button>}
+        <Button variant="outline" size="sm" disabled={!canEdit || busy} onClick={() => openEditor()}><Plus size={13} />新增类型</Button>
+      </span>
+    </div>
+
+    {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>}
+
+    <ul className={styles.wikiTypeList}>
+      {types.map(type => <li key={type.id} className={styles.wikiTypeRow}>
+        <span className={styles.wikiTypeName}>
+          <span className={styles.wikiTypeLabel}>{type.label}</span>
+          <code className={styles.kbSourceId}>{type.id}</code>
+          <Badge tone={type.layer === 'instance' ? 'warning' : 'neutral'}>{LAYER_LABEL[type.layer]}</Badge>
+          {type.builtin ? '' : <span className={styles.wikiTypeTag}>自定义</span>}
+        </span>
+        <span className={styles.wikiTypeMeta}>
+          {type.description || '（没有定义：模型只能靠猜）'}
+          <br />
+          必填小节：{type.sections.filter(section => section.required).map(section => section.label).join(' / ') || '（无）'}
+          {type.fields.filter(field => field.required).length > 0 ? `；必填字段：${type.fields.filter(field => field.required).map(field => field.name).join(' / ')}` : ''}
+        </span>
+        <span className={styles.kbTypeCount}>{type.cardCount} 张</span>
+        <Switch checked={type.enabled} disabled={!canEdit || busy} onCheckedChange={checked => void toggle(type, checked)} />
+        <Button variant="ghost" size="icon" title={`编辑 ${type.label}`} aria-label={`编辑类型 ${type.label}`} disabled={!canEdit || busy} onClick={() => openEditor(type)}><Pencil size={13} /></Button>
+        <Button
+          variant="ghost" size="icon"
+          disabled={!canEdit || busy || type.builtin || type.cardCount > 0}
+          title={type.builtin ? '内置类型不可删除，只能停用' : type.cardCount > 0 ? `该类型下还有 ${type.cardCount} 张卡片，先改类型再删除` : `删除类型 ${type.label}`}
+          aria-label={`删除类型 ${type.label}`}
+          onClick={() => void remove(type)}
+        ><Trash2 size={13} /></Button>
+      </li>)}
+    </ul>
+
+    {issueCount > 0 && <details className={styles.kbPrompt}>
+      <summary><AlertCircle size={12} /> 待补清单（前 {issues.length} / {issueCount} 条）</summary>
+      <ul className={styles.wikiTypeIssues}>
+        {issues.map((issue, index) => <li key={`${issue.entityId}-${index}`}>
+          <code>{issue.entityId}</code>
+          <span className={styles.wikiTypeIssueLevel}>{issue.level}</span>
+          <span>{issue.message}</span>
+        </li>)}
+      </ul>
+    </details>}
+
+    {rules && <details className={styles.kbPrompt}>
+      <summary><ShieldCheck size={12} /> 判定规则（内置，只读）</summary>
+      <p className={styles.kbPromptNote}>{rules.split('\n').map((line, index) => <span key={index}>{line}<br /></span>)}</p>
+      <p className={styles.kbPromptNote}>这段规则由代码内置（`WIKI_TYPE_RULES`），不随知识库变化，也不允许修改；可编辑的只有每个类型的定义、小节、字段与示例。</p>
+    </details>}
+
+    <Dialog open={draft.open} onOpenChange={open => { if (!open) setDraft(EMPTY_DRAFT) }}>
+      {draft.open && <DialogContent>
+        <DialogHeader><DialogTitle>{draft.mode === 'create' ? '新增 Wiki 卡片类型' : `编辑类型 · ${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="metric"
+              onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft({ ...draft, id: event.target.value })} />
+            <span className={styles.kbHint}>小写字母开头，可含数字 / 下划线 / 连字符 / 斜杠（如 <code>diagnosis/symptom</code>）；创建后不可修改——它是卡片的 <code>entity_type</code>。</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}>写清这一类「是什么」——它是模型判断卡片属于哪一类的第一依据。</span>
+          </label>
+          <div className={styles.kbField}><Label>层级</Label>
+            <SelectMenu
+              value={draft.layer}
+              onValueChange={next => setDraft({ ...draft, layer: next as 'type' | 'instance' })}
+              aria-label="层级"
+              options={[
+                { value: 'type', label: '类型层（可复用，如口径、假设）' },
+                { value: 'instance', label: '实例层（只发生过一次，如案例）' },
+              ]}
+            />
+          </div>
+          <label className={styles.kbField}><Label>必填小节（每行一条，结尾加 ? 表示可选）</Label>
+            <textarea className={styles.kbTextarea} value={draft.sections} spellCheck={false}
+              placeholder={'口径定义\n计算逻辑\n负责人?'}
+              onChange={(event: ChangeEvent<HTMLTextAreaElement>) => setDraft({ ...draft, sections: event.target.value })} />
+            <span className={styles.kbHint}>小节就是正文的 Markdown 标题，也是模板卡与校验的依据。</span>
+          </label>
+          <label className={styles.kbField}><Label>字段（每行一条：<code>名称|说明</code>，说明后加 <code>|可选</code> 表示非必填）</Label>
+            <textarea className={styles.kbTextarea} value={draft.fields} spellCheck={false}
+              placeholder={'formula|可执行的表达式或伪代码\nowner|谁对这个口径负责'}
+              onChange={(event: ChangeEvent<HTMLTextAreaElement>) => setDraft({ ...draft, fields: event.target.value })} />
+            <span className={styles.kbHint}>字段落在 front matter / metadata 上，是机器读的部分。</span>
+          </label>
+          <label className={styles.kbField}><Label>期望来源分类（每行一个 id，留空表示不限制）</Label>
+            <textarea className={styles.kbTextarea} value={draft.sourceTypes} spellCheck={false}
+              placeholder={'document\nprd'}
+              onChange={(event: ChangeEvent<HTMLTextAreaElement>) => setDraft({ ...draft, sourceTypes: event.target.value })} />
+            <span className={styles.kbHint}>来自「来源类型」的 id。来源不匹配时只提示，不阻断写作。</span>
+          </label>
+          <label className={styles.kbField}><Label>例如 · 用户会怎么提到它（每行一条）</Label>
+            <textarea className={styles.kbTextarea} value={draft.examples} spellCheck={false}
+              placeholder={'上个月的 GMV 怎么算\n转化率的口径是什么'}
+              onChange={(event: ChangeEvent<HTMLTextAreaElement>) => setDraft({ ...draft, examples: event.target.value })} />
+            <span className={styles.kbHint}>按用户的真实说法写，模型靠它判断该生成哪一类卡片。</span>
+          </label>
+          {(draft.sections.trim() || draft.fields.trim()) && <div className={styles.kbField}>
+            <Label>模板卡预览（由小节派生，只读）</Label>
+            <pre className={styles.kbPre}>{templatePreview(parseSections(draft.sections), parseFields(draft.fields))}</pre>
+          </div>}
+        </div>
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => setDraft(EMPTY_DRAFT)}>取消</Button>
+          <Button variant="default" disabled={busy || !draft.id.trim() || !draft.label.trim()} onClick={() => void save()}><Check size={13} />保存</Button>
+        </DialogFooter>
+      </DialogContent>}
+    </Dialog>
+  </>
+}
+
+/** 卡片的模板卡查看入口：编辑弹窗外也让人能直接照抄。 */
+export function WikiTemplateHint({ template }: { template: string }): ReactNode {
+  if (!template) return null
+  return <details className={styles.kbPrompt}>
+    <summary><Eye size={12} /> 模板卡</summary>
+    <pre className={styles.kbPre}>{template}</pre>
+  </details>
+}