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

package/src/client/TypeDefinitionDrawer.tsx

@@ -17,17 +17,28 @@
  * 自己的编辑弹窗 —— 同一份数据不因为多了一个入口就多一个写入口。
  */
 
-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 { useEffect, useRef, useState, type ChangeEvent, type ReactNode } from 'react'
+import { Check, Pencil, Plus, ShieldCheck, Trash2, X } from '@tita-data-agent/ui/icons'
+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'
 
+/**
+ * 抽屉该把哪一节推到你眼前。
+ *
+ * 它由**入口**决定，不是抽屉自己的偏好：从工具栏的「类型定义」进来，先看到的是
+ * 「这一栏是给本库定义词汇表的」这件事（来源类型在最上面）；而从某张卡片上的
+ * 「类型定义」进来，人是奔着 Wiki 类型去的 —— 那时还落在来源类型上，等于要滚一遍
+ * 才能看到自己点的那一节。
+ */
+export type TypeDefinitionSection = 'source' | 'wiki'
+
 export interface TypeDefinitionDrawerProps {
   open: boolean
   onOpenChange: (open: boolean) => void
@@ -37,7 +48,6 @@ export interface TypeDefinitionDrawerProps {
   kbId: string
   sourceTypes: SourceTypeDef[]
   wikiTypes: WikiTypeView[]
-  schemaMode: 'strict' | 'report'
   customized: boolean
   catalog: SourceTypeCatalog | null
   busy: string | null
@@ -45,15 +55,41 @@ export interface TypeDefinitionDrawerProps {
   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>
+  /** 打开时滚到哪一节（默认 `source`）。 */
+  section?: TypeDefinitionSection
 }
 
-const EMPTY_DRAFT: SourceTypeDraft = { mode: 'create', id: '', label: '', description: '', signals: '', excludes: '' }
+const EMPTY_DRAFT: SourceTypeDraft = { mode: 'create', id: '', label: '', description: '', signals: '', excludes: '', metadataFields: [] }
+
+/**
+ * 这一节的说明**从正文搬进了图标**（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,
+  open, onOpenChange, kbName, kbId, sourceTypes, wikiTypes, customized, catalog, busy,
+  onSaveSourceType, onToggleSourceType, onRemoveSourceType, onApplyWikiTypes, section = 'source',
 }: TypeDefinitionDrawerProps): ReactNode {
   /**
    * 分类编辑弹窗的草稿。它属于这个抽屉 —— 注册表搬进来之后，只有这里会开这个弹窗。
@@ -65,41 +101,70 @@ export function TypeDefinitionDrawer({
 
   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') }
+      ? { open: true, mode: 'edit', id: def.id, label: def.label, description: def.description, signals: def.signals.join('\n'), excludes: def.excludes.join('\n'), metadataFields: (def.metadataFields ?? []).map(field => ({ ...field })) }
       : { ...EMPTY_DRAFT, open: true })
   }
 
+  /** Wiki 类型那一节的副标题计数（原本由 `WikiTypeSection` 自己渲染）。 */
+  const enabledWikiTypes = wikiTypes.filter(type => type.enabled).length
+
+  const sourceSectionRef = useRef<HTMLElement | null>(null)
+  const wikiSectionRef = useRef<HTMLElement | null>(null)
+  /**
+   * 打开时把目标那一节滚到顶部。
+   *
+   * 用 `scrollIntoView({ block: 'start' })` 而不是给容器设 `scrollTop`：滚动容器
+   * （`DrawerBody`）会变，写死一个 offsetTop 迟早会错位。`useEffect` 依赖 `open` —— 抽屉
+   * 关闭时内容不在 DOM 里，ref 是空的，只有打开的那一次才有效。
+   */
+  useEffect(() => {
+    if (!open) return
+    const target = section === 'wiki' ? wikiSectionRef.current : sourceSectionRef.current
+    target?.scrollIntoView({ block: 'start' })
+  }, [open, section])
+
   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">
+          <section ref={sourceSectionRef} 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 +187,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>
 
@@ -142,28 +206,21 @@ export function TypeDefinitionDrawer({
             </details>}
           </section>
 
-          <section className={styles.settingsSection} aria-labelledby="tita-typedef-wiki-title">
+          <section ref={wikiSectionRef} 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}
-              mode={schemaMode}
-              customized={customized}
               canEdit={busy === null}
               busy={busy !== null}
               onApply={onApplyWikiTypes}
-              onModeChange={onModeChange}
-              onReset={onResetWikiTypes}
             />
           </section>
         </div>
@@ -173,39 +230,82 @@ 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>
+            {/* 元数据字段声明（0048）。为什么是结构化行而不是「每行一条」的文本：
+                一个字段有 key / 标签 / 必填三样，压进一行就得发明一个分隔符语法，
+                而这里要填的 key 恰恰是 front matter 的路径（`sources[0].author`），
+                它不该被一个自定义语法二次解析。 */}
+            <Field label="元数据字段" hint="这一类来源该带哪些元数据。key 用 front matter 的顶层键（或 sources[0].author 这种路径）；勾了「必填」而缺失时，录入与详情里会提示，但不会拒收这份来源。">
+              <div className={styles.kbFieldRows}>
+                {(draft.metadataFields ?? []).map((field, index) => <div className={styles.kbFieldRow} key={`field-${index}`}>
+                  <Input
+                    value={field.key} spellCheck={false} placeholder="sources[0].author" aria-label="元数据键"
+                    onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft({
+                      ...draft,
+                      metadataFields: (draft.metadataFields ?? []).map((item, at) => at === index ? { ...item, key: event.target.value } : item),
+                    })}
+                  />
+                  <Input
+                    value={field.label ?? ''} spellCheck={false} placeholder="作者 / 账号" aria-label="显示名"
+                    onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft({
+                      ...draft,
+                      metadataFields: (draft.metadataFields ?? []).map((item, at) => at === index ? { ...item, label: event.target.value } : item),
+                    })}
+                  />
+                  <label className={styles.kbFieldRequired}>
+                    <Switch
+                      checked={field.required === true}
+                      onCheckedChange={next => setDraft({
+                        ...draft,
+                        metadataFields: (draft.metadataFields ?? []).map((item, at) => at === index ? { ...item, required: next === true } : item),
+                      })}
+                    />必填
+                  </label>
+                  <Button
+                    variant="ghost" size="icon" aria-label={`删除字段 ${field.key || index + 1}`}
+                    onClick={() => setDraft({ ...draft, metadataFields: (draft.metadataFields ?? []).filter((_, at) => at !== index) })}
+                  ><X size={13} /></Button>
+                </div>)}
+                <Button
+                  variant="outline" size="sm"
+                  onClick={() => setDraft({ ...draft, metadataFields: [...(draft.metadataFields ?? []), { key: '', label: '' }] })}
+                ><Plus size={12} />添加字段</Button>
+              </div>
+            </Field>
           </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 })}
+              onClick={() => void onSaveSourceType({
+                mode: draft.mode, id: draft.id, label: draft.label, description: draft.description,
+                signals: draft.signals, excludes: draft.excludes,
+                // 空的 key 行是「加了但还没填」，直接丢掉：不把半成品写进注册表。
+                metadataFields: (draft.metadataFields ?? []).filter(field => field.key.trim() !== '').map(field => ({ ...field, key: field.key.trim(), label: (field.label ?? '').trim() })),
+              })}
             ><Check size={13} />保存</Button>
           </DialogFooter>
         </DialogContent>}

package/src/client/WikiCardReview.tsx

@@ -0,0 +1,266 @@
+/**
+ * 「review 与备注」—— 0044 的门开在**卡片预览抽屉**里，不再单独占一屏。
+ *
+ * ## 为什么从列表页搬到这里
+ *
+ * 0044 第一版在 wiki 卡片列表上面插了一块「入库后的 review」待办区，按卡片逐条列出。
+ * 那等于把同一张卡片的信息摊在两个地方：列表里一行（状态 / 类型 / 时间），待办区里
+ * 一大块（正文、三层校验、备注、动作）。人点开卡片看内容时，恰恰是**他正要判断这张卡
+ * 对不对**的那一刻 —— review 的动作就应该长在那只手上，而不是让人退回去、在另一个
+ * 区域里重新找到同一张卡。
+ *
+ * 现在：列表负责「哪几张需要我看」（状态徽标就在行上），抽屉负责「看它、判它、记它」。
+ *
+ * ## 三件事分得开
+ *
+ * - **状态**：`已 review` / `没人看过`，写在抽屉头的事实位上（不靠颜色单独表达）。
+ * - **待补**：三层校验（格式 / 引用 / 语义）报上来的缺口。缺信息**不拦入库**，所以它
+ *   是常态而不是事故；逐条列出是为了让人知道补什么（多半要去改类型定义）。
+ * - **人写的话**：备注与异常点。正文只读，人想改判断就写在这里 —— 这是这一块唯一
+ *   可写的东西。
+ *
+ * ## 为什么没有「全部通过」
+ *
+ * 批量动作一定会取代逐条判断，而 review 的全部价值就是逐条看过。这里一次只服务一张卡。
+ */
+
+import { useEffect, useState, type ReactNode } from 'react'
+import {
+  AlertCircle, Check, CheckCheck, MessageSquarePlus, RotateCcw, ShieldCheck, TriangleAlert, X,
+} from '@tita-data-agent/ui/icons'
+import { Badge, Button, Textarea, cn } from '@tita-data-agent/ui/components'
+import { DrawerSectionHead } from './DrawerSection.tsx'
+import { requestJson } from './request.ts'
+import { styles } from './styles.ts'
+import type { KnowledgeCardView } from './KnowledgeBaseTab.tsx'
+
+/**
+ * 三层校验的标签。三层分开报不是洁癖（0021 §6.5）：**格式错说明卡片没填完，
+ * 引用错说明图断了，语义错说明这条知识本身没用**。三者对应的动作完全不同
+ * （补字段 / 修边 / 重写），混成同一个「校验失败」人就学不会怎么补。
+ */
+const LEVEL_LABEL: Record<string, { label: string; tone: 'warning' | 'violet' | 'neutral' }> = {
+  format: { label: '格式', tone: 'warning' },
+  reference: { label: '引用', tone: 'violet' },
+  semantic: { label: '语义', tone: 'neutral' },
+}
+
+/** 没人看过时的评分（与服务端 `CARD_REVIEW_BASE_SCORE` 同值，只用于显示兜底）。 */
+const BASE_SCORE = 0.35
+
+function issuesOf(card: KnowledgeCardView): Array<{ level?: string; field?: string; message?: string }> {
+  const raw = card.metadata?.schema_issues
+  return Array.isArray(raw) ? raw as Array<{ level?: string; field?: string; message?: string }> : []
+}
+
+function anomaliesOf(card: KnowledgeCardView): NonNullable<KnowledgeCardView['annotations']> {
+  return (card.annotations ?? []).filter(item => item.kind === 'anomaly')
+}
+
+function notesOf(card: KnowledgeCardView): NonNullable<KnowledgeCardView['annotations']> {
+  return (card.annotations ?? []).filter(item => item.kind !== 'anomaly')
+}
+
+export function WikiCardReview({ kbId, card, onChanged, onOpenWikiTypes }: {
+  kbId: string
+  /** 抽屉当前打开的那张卡片 —— 这一块只服务它一张。 */
+  card: KnowledgeCardView
+  /** review / 备注写盘成功之后通知父级重新读取这张卡片与卡片列表。 */
+  onChanged?: () => void
+  /** 「去改类型定义」的入口。待补项多半是类型定义那一边的问题。 */
+  onOpenWikiTypes?: () => void
+}): ReactNode {
+  const [busy, setBusy] = useState(false)
+  const [composing, setComposing] = useState(false)
+  const [kind, setKind] = useState<'note' | 'anomaly'>('note')
+  const [draft, setDraft] = useState('')
+  const [notice, setNotice] = useState<{ tone: 'success' | 'error'; text: string } | null>(null)
+
+  /**
+   * 抽屉换到另一张卡片时把草稿与提示清掉。
+   *
+   * 少了这一步，`composing` 与 `draft` 会跟着抽屉留下来：人在 A 卡片写了一半，
+   * 关掉再开 B 卡片，输入框里还是 A 的话，一按保存就写到 B 头上。
+   */
+  useEffect(() => { setComposing(false); setDraft(''); setKind('note'); setNotice(null) }, [card.entityId])
+
+  const reviewed = card.review?.state === 'reviewed'
+  const score = card.review?.score ?? BASE_SCORE
+  const issues = issuesOf(card)
+  const anomalies = anomaliesOf(card)
+  const notes = notesOf(card)
+
+  const call = async (path: string, body: Record<string, unknown>): Promise<boolean> => {
+    setNotice(null)
+    try {
+      await requestJson(path, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ kb: kbId, ...body }),
+      })
+      return true
+    } catch (error) {
+      setNotice({ tone: 'error', text: error instanceof Error ? error.message : String(error) })
+      return false
+    }
+  }
+
+  const review = async (action: 'review' | 'unreview'): Promise<void> => {
+    setBusy(true)
+    const ok = await call('/knowledge/card-review', { entity_id: card.entityId, entity_type: card.entityType, action })
+    if (ok) {
+      setNotice({
+        tone: 'success',
+        text: action === 'review'
+          ? '已 review：评分写进卡片，下一次编译之后召回排序会用到它'
+          : '已撤销 review：评分放回出厂值，下一次编译之后召回排序会用到它',
+      })
+      onChanged?.()
+    }
+    setBusy(false)
+  }
+
+  const annotate = async (noteKind: 'note' | 'anomaly', note: string, removeId?: string): Promise<void> => {
+    setBusy(true)
+    const ok = await call('/knowledge/card-annotate', {
+      entity_id: card.entityId,
+      entity_type: card.entityType,
+      ...(removeId ? { remove_id: removeId } : { kind: noteKind, note }),
+    })
+    if (ok) {
+      setNotice({
+        tone: 'success',
+        text: removeId
+          ? '备注已撤销'
+          : noteKind === 'anomaly'
+            ? '已标为异常点：它照样召回得到，只是排在后面'
+            : '已加一条备注',
+      })
+      setComposing(false)
+      setDraft('')
+      onChanged?.()
+    }
+    setBusy(false)
+  }
+
+  return <section className={styles.drawerSection}>
+    <DrawerSectionHead icon={<ShieldCheck size={13} />} title="review 与备注">
+      <span className={styles.drawerHeadFact}>{reviewed ? '已 review' : '没人看过'} · 评分 {score.toFixed(2)}</span>
+    </DrawerSectionHead>
+
+    {/* 这一屏的规矩要写在明面上，而且要说清它与上一版的差别 —— 用户对「编译没生效」的
+        印象正来自上一版「提议不落卡」。 */}
+    <p className="max-w-[68ch] text-[11px] leading-relaxed text-tita-ink-muted">
+      卡片已经在库里、能被召回了 —— review 是事后判断，不是准入：它抬高召回评分。
+      正文只读，发现对不上就加备注；标注异常点不会让它消失，只会把它排到后面。
+      {card.review?.reviewedBy ? `（${reviewed ? 'review 人' : '上次 review 人'}：${card.review.reviewedBy}）` : ''}
+    </p>
+
+    {notice && <p
+      role="status"
+      className={cn('flex items-start gap-1.5 text-[11px] leading-relaxed', notice.tone === 'error' ? 'text-tita-danger' : 'text-tita-ink-muted')}
+    >
+      {notice.tone === 'error' ? <AlertCircle size={12} className="mt-0.5 shrink-0" /> : <Check size={12} className="mt-0.5 shrink-0" />}
+      <span className="min-w-0 flex-1">{notice.text}</span>
+    </p>}
+
+    <div className="flex flex-wrap items-center gap-1.5">
+      <Button
+        variant={reviewed ? 'outline' : 'default'} size="sm"
+        className="h-[28px] min-h-[28px] px-2.5 text-[11.5px]"
+        disabled={busy}
+        title={reviewed ? '撤销 review：评分放回出厂值' : '标记为看过：评分抬高，召回时排在前面一点'}
+        onClick={() => void review(reviewed ? 'unreview' : 'review')}
+      >{reviewed ? <><RotateCcw size={12} />撤销 review</> : <><CheckCheck size={12} />review 通过</>}</Button>
+      <Button
+        variant="outline" size="sm"
+        className="h-[28px] min-h-[28px] px-2.5 text-[11.5px]"
+        aria-expanded={composing}
+        onClick={() => composing ? (setComposing(false), setDraft('')) : (setComposing(true), setDraft(''), setKind('note'))}
+      ><MessageSquarePlus size={12} />加备注</Button>
+      {issues.length > 0 && onOpenWikiTypes && <Button
+        variant="ghost" size="sm"
+        className="h-[28px] min-h-[28px] px-2.5 text-[11.5px]"
+        onClick={onOpenWikiTypes}
+      >去改类型定义</Button>}
+    </div>
+
+    {/* 待补：三层校验的问题逐条列出。它排在人写的备注前面 —— 「卡片缺什么」是事实，
+        「人怎么看它」是判断，事实先读。 */}
+    {issues.length > 0 && <div className="flex flex-col gap-1">
+      <span className="text-[10.5px] font-semibold text-tita-ink-muted">待补 {issues.length} 项（缺信息不拦入库，后面有涉及的文档会补上）</span>
+      <ul className="flex flex-col gap-0.5">
+        {issues.map((issue, index) => {
+          const level = LEVEL_LABEL[issue.level ?? ''] ?? { label: issue.level ?? '问题', tone: 'neutral' as const }
+          return <li key={`${issue.field ?? ''}-${index}`} className="flex items-start gap-1.5 text-[11px] leading-relaxed text-tita-ink-muted">
+            <Badge tone={level.tone}>{level.label}</Badge>
+            <span className="min-w-0 flex-1">{issue.field ? `${issue.field}：` : ''}{issue.message}</span>
+          </li>
+        })}
+      </ul>
+    </div>}
+
+    {/* 人写的话：异常点在前（它们是这一块里唯一「已经知道有问题」的东西），普通备注在后。 */}
+    <div className="flex flex-col gap-1">
+      <span className="text-[10.5px] font-semibold text-tita-ink-muted">备注 {anomalies.length + notes.length > 0 ? `· ${anomalies.length + notes.length} 条` : ''}</span>
+      {anomalies.length + notes.length === 0
+        ? <p className="text-[11px] leading-relaxed text-tita-ink-faint">还没有备注。发现卡片与来源对不上，就写一条 —— 原始文档不会因此被改动。</p>
+        : <ul className="flex flex-col gap-1">
+          {[...anomalies, ...notes].map(item => <li key={item.id} className="flex items-start gap-1.5 text-[11px] leading-relaxed">
+            {item.kind === 'anomaly'
+              ? <TriangleAlert size={12} className="mt-0.5 shrink-0 text-tita-warning" />
+              : <MessageSquarePlus size={12} className="mt-0.5 shrink-0 text-tita-ink-faint" />}
+            <span className={cn('min-w-0 flex-1', item.kind === 'anomaly' ? 'text-tita-ink' : 'text-tita-ink-muted')}>{item.note}</span>
+            <span className="shrink-0 text-[10px] text-tita-ink-faint">{item.author ?? item.createdAt?.slice(0, 10) ?? ''}</span>
+            <Button
+              variant="ghost" size="icon"
+              className="h-[22px] w-[22px] min-w-[22px] shrink-0"
+              title="撤销这条备注" aria-label={`撤销备注：${item.note}`}
+              disabled={busy}
+              onClick={() => void annotate(item.kind, item.note, item.id)}
+            ><X size={11} /></Button>
+          </li>)}
+        </ul>}
+    </div>
+
+    {composing && <div className="flex flex-col gap-1.5 rounded-lg border border-tita-line bg-tita-canvas p-2">
+      {/* 两条路是**两种判断**，不是两个样式：普通备注是解释，异常点是「这里对不上」。 */}
+      <div className="flex items-center gap-1.5">
+        <Button
+          variant={kind === 'note' ? 'default' : 'outline'} size="sm"
+          className="h-[26px] min-h-[26px] px-2 text-[11px]"
+          onClick={() => setKind('note')}
+        ><MessageSquarePlus size={11} />普通备注</Button>
+        <Button
+          variant={kind === 'anomaly' ? 'default' : 'outline'} size="sm"
+          className="h-[26px] min-h-[26px] px-2 text-[11px]"
+          onClick={() => setKind('anomaly')}
+        ><TriangleAlert size={11} />异常点</Button>
+      </div>
+      <Textarea
+        value={draft}
+        autoFocus
+        rows={3}
+        aria-label="备注内容"
+        placeholder={kind === 'anomaly'
+          ? '哪里对不上？例如「这个数与 2025-03 复盘里的 12.4% 不一致」'
+          : '记一句判断，例如「口径在 Q3 手册里改过，本节还是旧的」'}
+        className="min-h-[62px] text-[11.5px] leading-relaxed"
+        onChange={event => setDraft(event.target.value)}
+      />
+      <div className="flex items-center gap-1.5">
+        <Button
+          variant="default" size="sm"
+          className="h-[28px] min-h-[28px] px-2.5 text-[11.5px]"
+          disabled={busy || draft.trim().length === 0}
+          onClick={() => void annotate(kind, draft.trim())}
+        ><Check size={12} />保存备注</Button>
+        <Button
+          variant="ghost" size="sm"
+          className="h-[28px] min-h-[28px] px-2.5 text-[11.5px]"
+          onClick={() => { setComposing(false); setDraft('') }}
+        >取消</Button>
+      </div>
+    </div>}
+  </section>
+}