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

package/src/client/TypeDefinitionDrawer.tsx

@@ -19,12 +19,13 @@
 
 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 { Button, Field, Input, Switch, Textarea, 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 { InfoHint } from './InfoHint.tsx'
 import type { SourceTypeCatalog, SourceTypeDef, SourceTypeDraft } from './KnowledgeBaseTab.tsx'
 import { WikiTypeSection, type WikiTypeView } from './WikiTypeEditor.tsx'
 
@@ -51,6 +52,32 @@ export interface TypeDefinitionDrawerProps {
 
 const EMPTY_DRAFT: SourceTypeDraft = { mode: 'create', id: '', label: '', description: '', signals: '', excludes: '' }
 
+/**
+ * 这一节的说明**从正文搬进了图标**（2026-09-26 GUI 反馈）。
+ *
+ * 原来标题下面挂着两段常驻说明、按钮旁边再挂一段，一共五行解释文字压在十一个分类
+ * 上面 —— 打开这个抽屉是来改词汇表的，词汇表本身却被推到第二屏。说明的内容有价值
+ * （「兜底分类必须存在且不可停用」这种话不能删），所以挪进 `InfoHint`：要看的时候
+ * 悬停或聚焦就有，不看的时候不占版面。下面 Wiki 类型那一节同理。
+ */
+const SOURCE_TYPE_HINT = 'source_type 描述业务场景，不描述文件格式（载体走 source_format）。三档默认值：兜底分类必须存在且不可停用；内置分类可改文案、可停用，但不能删除；自定义分类可增可删，新增时必须写清判定文案——它会拼进内置提示词里交给 Agent 判断。分类下还有来源时不能删除，先迁移。'
+
+/**
+ * 一个分类的判定文案：定义 + 典型信号 + 排除项。
+ *
+ * 这三样是 Agent 判断「这条来源算不算这一类」的全部依据，但铺在行上会占三四行，
+ * 把十一行的列表拉成一屏。所以它们进行首那枚图标，行本身只留身份与操作。
+ */
+function sourceTypeHint(def: SourceTypeDef): string {
+  const parts = [def.description || '还没有写定义 —— Agent 只能靠名字猜它是哪一类。']
+  if (def.signals.length > 0) parts.push(`典型信号：${def.signals.join('；')}`)
+  if (def.excludes.length > 0) parts.push(`不归这一类：${def.excludes.join('；')}`)
+  return parts.join('。')
+}
+
+/** Wiki 类型那一节的说明，同样从常驻段落搬进图标。 */
+const WIKI_TYPE_HINT = '每个类型规定必填小节与必填字段，写卡片时按它校验。这就是编译设置里的 Schema 类型——早先那种「逗号分隔的类型名文本框」已撤掉，它既不参与校验也不被生成逻辑读取，是个改了不生效的假开关。从原文件生成卡片时：先按「定义 + 例如」判断属于哪一类，再按必填小节写正文、按必填字段填 front matter；模板卡由小节派生，新建卡片时照抄即可。'
+
 export function TypeDefinitionDrawer({
   open, onOpenChange, kbName, kbId, sourceTypes, wikiTypes, schemaMode, customized, catalog, busy,
   onSaveSourceType, onToggleSourceType, onRemoveSourceType, onApplyWikiTypes, onModeChange, onResetWikiTypes,
@@ -69,37 +96,51 @@ export function TypeDefinitionDrawer({
       : { ...EMPTY_DRAFT, open: true })
   }
 
+  /** Wiki 类型那一节的副标题计数（原本由 `WikiTypeSection` 自己渲染）。 */
+  const enabledWikiTypes = wikiTypes.filter(type => type.enabled).length
+
   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> */}
+        {/* 标题与说明**包在一个 div 里**：`DrawerHeader` 是 `flex justify-between`，
+            两个平级子元素会并排 —— 标题被挤成两行，说明占掉剩下那一行。版本抽屉与
+            版本面板也是这么包的（那里同样是「标题 + 一整句说明」）。 */}
+        <div>
+          <DrawerTitle>类型定义</DrawerTitle>
+          {/*
+            作用域写在标题下面，只写一次：切库换的是**这一套**，不是方案的参数。
+
+            这段 2026-09-26 之前是**注释掉的**，而测试断言的是这段文字本身 —— 于是它一直
+            绿着，绿色的来源却是注释，抽屉里其实没有任何作用域说明（`kbName` 也跟着成了
+            一个没人读的 prop）。现在它是真的渲染出来：这一栏是**按库**的词汇表，而同一个
+            面板右上角那个齿轮里是**本方案**的参数，两者「切库会不会跟着换」不一样，
+            不说就只能靠用户自己撞出来。
+
+            设置抽屉的标题下没有对应的一句，那是有意的：齿轮的默认预期本来就是「方案级」，
+            而「这个抽屉跟着当前知识库走」才是需要说出来的那一半。
+          */}
+          <DrawerDescription>
+            本库定义{kbName ? <> · <b>{kbName}</b></> : null} —— 来源分类与 Wiki 类型只属于这个知识库，切库就换一套；
+            方案级参数（存储 / 收录闸门 / 构建 / 召回 / 重排）在右上角齿轮的「设置」里。
+          </DrawerDescription>
+        </div>
       </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>
+                <h3 id="tita-typedef-source-title"><ShieldCheck size={13} /> 来源类型<InfoHint text={SOURCE_TYPE_HINT} /></h3>
               </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>
+                  <InfoHint text={sourceTypeHint(def)} />
                 </span>
                 <span className={styles.kbTypeCount}>{def.sourceCount} 个来源</span>
                 <Switch
@@ -122,7 +163,6 @@ export function TypeDefinitionDrawer({
               </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>
 
@@ -145,15 +185,12 @@ export function TypeDefinitionDrawer({
           <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>
+                <h3 id="tita-typedef-wiki-title">Wiki 类型（卡片 schema）<InfoHint text={WIKI_TYPE_HINT} /></h3>
               </div>
-              <span className={styles.kbCount}>{wikiTypes.length} 个类型</span>
+              {/* 计数从 `WikiTypeSection` 的副标题搬到这里：那块副标题与这一节的标题
+                  是同一个名字，一个抽屉里同一句话写两遍。 */}
+              <span className={styles.kbCount}>{enabledWikiTypes} / {wikiTypes.length} 启用{customized ? ' · 已自定义' : ''}</span>
             </div>
-            <p className={styles.kbHint}>
-              这就是编译设置里的 <b>Schema 类型</b>。早先那种「逗号分隔的类型名文本框」已撤掉 ——
-              它既不参与校验也不被生成逻辑读取，是个改了不生效的假开关。
-            </p>
             <WikiTypeSection
               kbId={kbId}
               types={wikiTypes}
@@ -173,32 +210,29 @@ export function TypeDefinitionDrawer({
         {draft.open && <DialogContent>
           <DialogHeader><DialogTitle>{draft.mode === 'create' ? '新增来源分类' : `编辑来源分类 · ${draft.label}`}</DialogTitle></DialogHeader>
           <div className={styles.kbForm}>
-            <label className={styles.kbField}><Label>分类 id</Label>
+            <Field label="分类 id" hint="小写字母 / 数字 / 下划线，创建后不可修改——它是写进 SourceRaw frontmatter 的稳定标识。">
               <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>
+            </Field>
+            <Field 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}
+            </Field>
+            <Field label="一句话定义（必填）" hint="写清「是什么」，不要写成「包含哪些文件」——载体格式走 source_format，Agent 靠这句话判断。">
+              <Textarea 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}
+            </Field>
+            <Field label="signals · 典型信号（每行一条，至少 2 条）">
+              <Textarea 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}
+            </Field>
+            <Field label="excludes · 排除项（每行一条，至少 1 条）" hint="每条都要写出「该归到哪个分类」（用 id 或标签）；指向不存在的分类会被拒绝，否则边界是悬空的。">
+              <Textarea 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>
+            </Field>
           </div>
           <DialogFooter>
             <Button variant="ghost" onClick={closeEditor}>取消</Button>

package/src/client/WikiTypeEditor.tsx

@@ -9,15 +9,26 @@
  * 组件自包含：列表与编辑弹窗在这里，数据由父级（知识库面板）以 props 传入，
  * 写入统一走 `onApply`（整表替换）。它另外自己拉一次 `/knowledge/wiki-types`
  * 取"待补"清单与内置只读判定规则——那是展示信息，不影响写入契约。
+ *
+ * 2026-09-26 的呈现修正（0040 §4.3 / §4.4）都收在同一个毛病上：**只读内容与可编辑
+ * 内容原来长得一样**。所以这一屏现在有三条硬规则：
+ *
+ * 1. 不可编辑的值不给控件形态：内置类型的 id 用 `readOnly`（沉底 + 浅描边 + 文本
+ *    光标，可选中复制），模板卡预览用只读排版块，都不再是"看起来能点"的输入框。
+ * 2. 模板卡预览**按层分两块**：必填字段落在 front matter、必填小节是正文标题，
+ *    三层校验本来就分开报错，这里就分开呈现。
+ * 3. `diagnosis/*` 这类带命名空间的 id 在列表里按前缀折成一组（0040 §4.3）。
  */
 
 import { useCallback, useEffect, useState, type ChangeEvent, type ReactNode } from 'react'
 import {
-  AlertCircle, Check, ClipboardCheck, Eye, Pencil, Plus, RotateCcw, ShieldCheck, Trash2, X,
+  AlertCircle, Check, ChevronRight, 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 { Badge, Button, Field, Input, SelectMenu, Switch, Textarea, cn } from '@tita-data-agent/ui/components'
 import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from '@tita-data-agent/ui/overlays'
 import { styles } from './styles.ts'
+import { InfoHint } from './InfoHint.tsx'
+import { wikiTypeRows } from './wiki-type-groups.ts'
 
 export interface WikiSectionSpec { label: string; required: boolean }
 export interface WikiFieldSpec { name: string; required: boolean; note: string }
@@ -29,7 +40,6 @@ export interface WikiTypeView {
   layer: 'type' | 'instance'
   sections: WikiSectionSpec[]
   fields: WikiFieldSpec[]
-  sourceTypes: string[]
   examples: string[]
   template: string
   enabled: boolean
@@ -56,12 +66,10 @@ interface WikiTypeDraft {
   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 EMPTY_DRAFT: WikiTypeDraft = { open: false, mode: 'create', id: '', label: '', description: '', layer: 'type', sections: '', fields: '', examples: '' }
 
 const TYPE_ID_PATTERN = /^[a-z][a-z0-9_/-]{1,60}$/
 
@@ -103,6 +111,43 @@ function parseFields(text: string): WikiFieldSpec[] {
 
 const LAYER_LABEL: Record<WikiTypeView['layer'], string> = { type: '类型层', instance: '实例层' }
 
+/**
+ * 只读字段的记号：一个 `data-` 属性，样式写在插件的 `styles.css` 里。
+ *
+ * 为什么不直接给工具类：**插件没有自己的 Tailwind 构建**（`packages/ui` 的
+ * `tailwind.css` 只在它自己构建时按源码扫一遍，插件改不了那份清单），所以
+ * `disabled:opacity-50` 这类只在恰好被别处用到时才存在。而 `Input` 的 `readonly`
+ * 样式只解决"沉底 + 浅描边"，缺"这不能改"的那点灰（0040 §4.4 第 1 条）。
+ * 给一个属性而不是直接改 `input[readonly]`：这条规约只该作用于**声明了它**的字段，
+ * 不能顺手把别处的只读输入框也一起改掉。
+ */
+const READ_ONLY_FIELD = { 'data-tita-readonly': 'true' } as const
+
+/**
+ * 带命名空间的前缀中文别名（0040 §4.3）。
+ *
+ * 组名默认取前缀本身 —— 只有真正需要翻译的才写进这张表。写死五个 `diagnosis/*`
+ * 的 id 是不行的：自定义类型也允许带斜杠，`diagnosis` 前缀下的类型是可增删的。
+ */
+/** 预览里没有任何可显示的必填字段 / 小节时，也要把这一块画出来：两块的分工本身是信息。 */
+const PREVIEW_EMPTY = '（没有必填项 —— 这一类不受它约束）'
+
+/**
+ * 一个类型的口径：定义 + 必填小节 + 必填字段。
+ *
+ * 这三样原来铺在每一行卡片上（十一个类型就是三十多行小字），把列表拉成一屏多 ——
+ * 而这一页要做的事是「看一眼有哪些类型、哪个没启用」。所以它们进行首那枚图标，
+ * 行本身只留身份、张数与操作。同样的处理也用在「来源类型」的每一行上。
+ */
+function wikiTypeHint(type: WikiTypeView): string {
+  const required = type.sections.filter(section => section.required).map(section => section.label)
+  const fields = type.fields.filter(field => field.required).map(field => field.name)
+  const parts = [type.description || '（没有定义：模型只能靠猜）']
+  parts.push(`必填小节：${required.join(' / ') || '（无）'}`)
+  if (fields.length > 0) parts.push(`必填字段：${fields.join(' / ')}`)
+  return parts.join('。')
+}
+
 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)
@@ -129,7 +174,6 @@ export function WikiTypeSection({ kbId, types, mode, customized, canEdit, busy,
         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 })
@@ -154,7 +198,6 @@ export function WikiTypeSection({ kbId, types, mode, customized, canEdit, busy,
       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,
@@ -172,18 +215,35 @@ export function WikiTypeSection({ kbId, types, mode, customized, canEdit, busy,
   const remove = (type: WikiTypeView): Promise<void> =>
     onApply(types.filter(item => item.id !== type.id), `已删除卡片类型「${type.label}」`)
 
-  const enabledCount = types.filter(type => type.enabled).length
+  /**
+   * 一行类型。**一行就是一行**：身份（名字 / id / 层级 / 自定义）+ 说明图标，
+   * 右边是张数、开关、编辑、删除。
+   *
+   * 提出来是因为它现在有两条渲染路径 —— 平铺的行、分组里的行 —— 而两条路径必须是
+   * **同一个行**。复制一份出来，迟早会在其中一份上改样式或加操作，然后两处不一样。
+   */
+  const renderRow = (type: WikiTypeView): ReactNode => <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>}
+      <InfoHint text={wikiTypeHint(type)} />
+    </span>
+    {/* 张数是**算出来的**，不是填进去的：它没有编辑入口，所以也不该长得像控件。 */}
+    <span className={styles.kbTypeCount} title="由该库已落库卡片实时算出，不可编辑">{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>
 
   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
@@ -210,31 +270,33 @@ export function WikiTypeSection({ kbId, types, mode, customized, canEdit, busy,
       <button type="button" className={styles.kbNoticeClose} aria-label="关闭提示" onClick={() => setNotice(null)}><X size={12} /></button>
     </p>}
 
+    {/*
+      列表按 id 前缀分组（0040 §4.3）：`diagnosis/*` 是**一套 schema**，五个类型
+      铺在一级看起来就是五个互不相干的条目。分组是呈现层行为 —— 注册表结构、
+      `entity_type`、组内顺序都不动。
+
+      **「摆成几行」这件事不在 JSX 里算**，在 `wikiTypeRows()` 里算。上一版把判断写成
+      一个三元，`prefix === ''` 那一支只渲染了 `members[0]` —— 于是六个没有斜杠的通用
+      类型在界面上只剩第一个，另外五个不见了，而且没有任何报错、所有测试都是绿的。
+      把计划抽成纯函数之后，这一条由 `tests/wiki-type-groups.test.mjs` 钉住：
+      **行的总数必须与注册表一一对应，一个都不能少**。
+    */}
     <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>)}
+      {wikiTypeRows(types).map(row => row.kind === 'row'
+        ? renderRow(row.type)
+        : <li key={`group:${row.prefix}`} className={styles.wikiTypeGroup}>
+          <details className={styles.wikiTypeGroupBox} open>
+            <summary className={styles.wikiTypeGroupHead}>
+              {/* 折叠箭头用 lucide 的实体图标，不用 `▾` 这种字符顶替：那个字符的
+                  描边粗细、基线、大小都不属于这套图标系统，缩放时先散架的就是它。 */}
+              <ChevronRight size={12} className={styles.wikiTypeGroupCaret} aria-hidden />
+              <span className={styles.wikiTypeGroupLabel}>{row.label}</span>
+              <code className={styles.kbSourceId}>{row.prefix}/*</code>
+              <span className={styles.wikiTypeGroupCount}>{row.members.length} 个类型</span>
+            </summary>
+            <ul className={styles.wikiTypeGroupList}>{row.members.map(renderRow)}</ul>
+          </details>
+        </li>)}
     </ul>
 
     {issueCount > 0 && <details className={styles.kbPrompt}>
@@ -258,22 +320,34 @@ export function WikiTypeSection({ kbId, types, mode, customized, canEdit, busy,
       {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>
+          {/*
+            id 两态两种控件形态（0040 §4.4 第 1 条）：
+            - 新建：真的是一个要填的输入框；
+            - 编辑：**现在是只读值**，不是"看起来能点的灰框"。用 `readOnly` 而不是
+              `disabled`——只读的值还该能被选中复制（它是卡片的 `entity_type`，
+              人常常要把它拷去写卡片），`disabled` 连选中都做不到。样式见
+              `READ_ONLY_FIELD`：沉底 + 浅描边 + 文本光标，由共享 `Input` 自带。
+          */}
+          {draft.mode === 'edit'
+            ? <Field as="div" label={<>类型 id<Badge tone="neutral">只读</Badge></>} hint={<>创建后不可修改——它是卡片的 <code>entity_type</code>，改了等于换一个类型。</>}>
+              <Input value={draft.id} readOnly spellCheck={false} {...READ_ONLY_FIELD} />
+            </Field>
+            : <Field label="类型 id" hint={<>小写字母开头，可含数字 / 下划线 / 连字符 / 斜杠（如 <code>diagnosis/symptom</code>）；创建后不可修改——它是卡片的 <code>entity_type</code>。</>}>
+              <Input value={draft.id} spellCheck={false} placeholder="metric"
+                onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft({ ...draft, id: event.target.value })} />
+            </Field>}
+          <Field 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}
+          </Field>
+          <Field label="定义（必填）" hint="写清这一类「是什么」——它是模型判断卡片属于哪一类的第一依据。">
+            <Textarea 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>
+          </Field>
+          {/* 选择控件不是 labelable 元素里可被包裹的那种：Radix 的 trigger 是 `<button>`，
+              外层再套一个 `<label>` 会让点标题也把菜单打开。所以这一格用 `as="div"`。 */}
+          <Field as="div" label="层级">
             <SelectMenu
               value={draft.layer}
               onValueChange={next => setDraft({ ...draft, layer: next as 'type' | 'instance' })}
@@ -283,35 +357,23 @@ export function WikiTypeSection({ kbId, types, mode, customized, canEdit, busy,
                 { value: 'instance', label: '实例层（只发生过一次，如案例）' },
               ]}
             />
-          </div>
-          <label className={styles.kbField}><Label>必填小节（每行一条，结尾加 ? 表示可选）</Label>
-            <textarea className={styles.kbTextarea} value={draft.sections} spellCheck={false}
+          </Field>
+          <Field label="必填小节（每行一条，结尾加 ? 表示可选）" hint="小节就是正文的 Markdown 标题，也是模板卡与校验的依据。">
+            <Textarea 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}
+          </Field>
+          <Field label={<>字段（每行一条：<code>名称|说明</code>，说明后加 <code>|可选</code> 表示非必填）</>} hint="字段落在 front matter / metadata 上，是机器读的部分。">
+            <Textarea 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}
+          </Field>
+          <Field label="例如 · 用户会怎么提到它（每行一条）" hint="按用户的真实说法写，模型靠它判断该生成哪一类卡片。">
+            <Textarea 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>}
+          </Field>
+          <TemplateCardPreview sections={parseSections(draft.sections)} fields={parseFields(draft.fields)} />
         </div>
         <DialogFooter>
           <Button variant="ghost" onClick={() => setDraft(EMPTY_DRAFT)}>取消</Button>
@@ -330,3 +392,57 @@ export function WikiTemplateHint({ template }: { template: string }): ReactNode
     <pre className={styles.kbPre}>{template}</pre>
   </details>
 }
+
+/**
+ * 模板卡预览（0040 §4.4 第 3、4 条）。**它是只读的**：内容由 `fields` / `sections`
+ * 派生，人在这里什么都改不了 —— 真源是上面那两个输入框。
+ *
+ * 所以它不用输入框形态。原来是一个 `<textarea>`；人第一反应是"这里能编辑"，
+ * 试两次才发现点不动，那是纯粹的误导。现在是一块沉底的只读排版块 + 一枚「只读」
+ * 徽标 + 文本光标可选中的等宽内容，形态与旁边那几个控件明显不同。
+ *
+ * 并且**按层分成两块**：
+ * - front matter：必填字段。落在卡片的 metadata 上，是机器读的部分；
+ * - 正文小节：必填小节。正文的 Markdown 标题。
+ *
+ * 这两件事原来混在一段文本里。而 `write_knowledge_card` 的三层校验本来就分开报错
+ * （少字段报字段、少小节报小节），定义界面按同样的分法展示，人看到"格式错误"
+ * 才知道该往哪补。
+ */
+function TemplateCardPreview({ sections, fields }: { sections: WikiSectionSpec[]; fields: WikiFieldSpec[] }): ReactNode {
+  const requiredFields = fields.filter(field => field.required)
+  const requiredSections = sections.filter(section => section.required)
+  return <section className={styles.wikiPreview} aria-labelledby="tita-wiki-preview-title">
+    <div className={styles.wikiPreviewHead}>
+      <h4 id="tita-wiki-preview-title">模板卡预览</h4>
+      <Badge tone="neutral">只读</Badge>
+      <span className={styles.wikiPreviewOrigin}>由上面的字段与小节派生，不单独保存</span>
+    </div>
+
+    <div className={styles.wikiPreviewBlock}>
+      <h5 className={styles.wikiPreviewBlockTitle}>front matter · 必填字段</h5>
+      <p className={styles.wikiPreviewBlockNote}>写在卡片正文之前，卡片的机器可读部分；顺序按你填的顺序。</p>
+      {requiredFields.length > 0
+        ? <dl className={styles.wikiPreviewFields}>
+          {requiredFields.map(field => <div key={field.name} className={styles.wikiPreviewField}>
+            <dt><code>{field.name}</code>:</dt>
+            <dd>{field.note || '（还没写说明）'}</dd>
+          </div>)}
+        </dl>
+        : <p className={styles.wikiPreviewEmpty}>{PREVIEW_EMPTY}</p>}
+    </div>
+
+    <div className={styles.wikiPreviewBlock}>
+      <h5 className={styles.wikiPreviewBlockTitle}>正文 · 必填小节</h5>
+      <p className={styles.wikiPreviewBlockNote}>写在正文里的 Markdown 标题，缺哪一个都会被点名。</p>
+      {requiredSections.length > 0
+        ? <ul className={styles.wikiPreviewSections}>
+          {requiredSections.map(section => <li key={section.label}>
+            <code>{`## ${section.label}`}</code>
+            <span className={styles.wikiPreviewPlaceholder}>（写什么）</span>
+          </li>)}
+        </ul>
+        : <p className={styles.wikiPreviewEmpty}>{PREVIEW_EMPTY}</p>}
+    </div>
+  </section>
+}