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

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, 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,27 +66,20 @@ 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}$/
 
 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` 同一规则，避免两处漂移。 */
@@ -103,7 +106,44 @@ function parseFields(text: string): WikiFieldSpec[] {
 
 const LAYER_LABEL: Record<WikiTypeView['layer'], string> = { type: '类型层', instance: '实例层' }
 
-export function WikiTypeSection({ kbId, types, mode, customized, canEdit, busy, onApply, onModeChange, onReset }: Props): ReactNode {
+/**
+ * 只读字段的记号：一个 `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, canEdit, busy, onApply }: Props): ReactNode {
   const [draft, setDraft] = useState<WikiTypeDraft>(EMPTY_DRAFT)
   const [notice, setNotice] = useState<{ tone: 'success' | 'error'; text: string } | null>(null)
   const [rules, setRules] = useState('')
@@ -129,7 +169,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 +193,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,35 +210,43 @@ 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
-          checked={mode === 'strict'}
-          disabled={!canEdit || busy}
-          onCheckedChange={checked => void onModeChange(checked ? 'strict' : 'report')}
-        />
-        <span>
-          <strong>严格模式</strong>
-          <small>{mode === 'strict' ? '缺必填小节 / 字段直接拒绝写入' : '只把问题标在卡片上，不拦截写入'}</small>
-        </span>
-      </label>
+      {/* 0044：原来的「严格模式」开关（缺必填小节 / 字段直接拒绝写入）撤掉了。
+          缺信息现在照常入库、只标成待补 —— 留一个什么都不拦的开关，比没有更糟：
+          界面上摆着它，人就会以为它在起作用。校验的结果仍然报在右边那行。 */}
       <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>
@@ -210,31 +256,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 +306,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 +343,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 +378,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 标题。
+ *
+ * 这两件事原来混在一段文本里。而编译器的三层校验本来就分开报错
+ * （少字段报字段、少小节报小节），定义界面按同样的分法展示，人看到"格式错误"
+ * 才知道该往哪补。
+ */
+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>
+}

package/src/client/arch/AgentArchitectureGraph.tsx

@@ -14,8 +14,12 @@
  *    缩放**不用 G6 的 `fitView` / `zoomTo`**：这版 G6 对 HTML 节点算不出内容包围盒，
  *    两个 API 都实测无效（画布按 0.45 定了尺寸，内容仍按 1:1 画出去被裁掉）。
  *    改成画布永远按设计尺寸渲染、再缩整块板：比例是我们算的，不依赖 G6 的判断。
- * 4. **画布不接管视口。** 不注册 `drag-canvas` / `zoom-canvas`：滚轮该滚容器，
- *    而不是缩画布；平移交给滚动条。G6 在这一页只负责画和点选。
+ * 4. **画布不让人拖，整图居中。** 0050 撤掉了 0042 那套「空格 + 拖拽平移」：
+ *    那张图会被拖到一边、留出半屏空白，而用户要的是「一眼看全、永远居中」。
+ *    现在整图按**两个方向**适应容器（`fit: 'both'`）并用 `safe center` 居中 ——
+ *    图永远完整落在框里，所以既不需要平移也不需要滚动。1:1 档放不下时容器自己
+ *    出滚动条（那一档的用途就是读字，读数优先于「一屏看全」）。
+ *    仍然不注册 G6 的 `drag-canvas` / `zoom-canvas`：滚轮该滚容器而不是缩画布。
  * 5. **操作是浮层，画布上没有图例。**
  *    0026 把图例、提示、状态统计和全屏按钮放在画布上方的一条 flex 行里，栏宽一窄
  *    `flex-wrap` 就把全屏按钮甩到第二行最左边 —— 用户看到的「全屏不在右上角」就是这么来的。
@@ -71,7 +75,11 @@ export function AgentArchitectureGraph({ stats, version, selected, onSelect, sel
   selectDomainRef.current = onSelectDomain
   const [fullscreen, setFullscreen] = useState(false)
   const [mode, setMode] = useState<ZoomMode>('fit')
-  const { scale, boardH } = useFitScale(scroller, CANVAS_WIDTH, CANVAS_HEIGHT, visible, fullscreen, mode)
+  // **两个方向都适应**（0050）：图永远完整落在框里，所以不需要平移，也就没有「被拖偏」
+  // 这回事。全屏与侧栏同一套规则 —— 两个档位的差别只剩「适应」与「1:1」。
+  const { scale, boardH } = useFitScale(
+    scroller, CANVAS_WIDTH, CANVAS_HEIGHT, visible, fullscreen, mode, 'both',
+  )
   /** 选中态要在「建图 / 换数据 / 换选中」三条路径上都对得上，所以集中存一份。 */
   const stateRef = useRef({ selected, selectedDomain, stats, version })
   stateRef.current = { selected, selectedDomain, stats, version }
@@ -89,12 +97,13 @@ export function AgentArchitectureGraph({ stats, version, selected, onSelect, sel
       container: el,
       width: el.clientWidth || CANVAS_WIDTH,
       height: el.clientHeight || CANVAS_HEIGHT,
-      // 画布底色交给容器（`.tita-archScroll` 的 `--tita-surface`）：canvas 不认 CSS 变量，
+      // 画布底色交给容器（`.tita-archScrollStage` 的 `--tita-canvas`）：canvas 不认 CSS 变量，
       // 它会先 clearRect（清成全透明）再把 background 当 fillStyle 填 —— 传令牌字符串等于
       // 交给浏览器一个无效值，填色被忽略，默认的黑色 fillStyle 会直接盖上来。透明才是
       //「跟着主题走」在画布上的唯一正确写法，浅色下与原来的纯白一致。
       background: 'transparent',
-      // 画布不承担缩放平移：视口交给外层滚动条与缩放档，G6 只管画。
+      // 画布不承担缩放与移动：缩放由外层那块板上的 `transform` 决定，位置由容器的居中
+      // 决定（0050 起没有平移手势），G6 只管画与点选。
       // 图级 `node.type` / `edge.type` **不要设**：G6 v5 用它覆盖每个元素自己声明的
       // `type`，于是装饰节点会被当成 HTML 节点画成空盒子，整张图只剩悬空的卡片
       // （0025 起就是这样，实测确认）。类型一律由元素自己声明。
@@ -173,9 +182,11 @@ export function AgentArchitectureGraph({ stats, version, selected, onSelect, sel
     return () => document.removeEventListener('fullscreenchange', onChange)
   }, [])
 
-  // 画布永远是设计尺寸，缩放由这块板承担。`fit` 档下板高就是缩完的高度，
-  // 容器因此没有可滚的余量；`1:1` 档下板高是设计高度，横向（窄栏）或双向（全屏）滚动。
-  const scrollStyle = fullscreen ? undefined : { height: boardH }
+  // 画布永远是设计尺寸，缩放由板上的 transform 承担。**外面还要一层按比例定尺寸的框**：
+  // transform 不改变布局尺寸，只写 transform 的话容器内容永远按 1172×1132 参与布局，
+  // 居中就会偏（居中的是那块没缩的尺寸，不是看得见的图）。框的尺寸 = 缩完的尺寸，
+  // 于是「居中」居的正好是图的边界。
+  const frameStyle = { width: CANVAS_WIDTH * scale, height: CANVAS_HEIGHT * scale }
   const boardStyle = {
     width: CANVAS_WIDTH,
     height: CANVAS_HEIGHT,
@@ -189,21 +200,26 @@ export function AgentArchitectureGraph({ stats, version, selected, onSelect, sel
           浮层正文里，左上角那块说明板只是把图挡掉一角。 */}
       <div className={styles.archOverlay}>
         <div className={styles.archOverlayActions}>
-          {/* 缩放档：两段的分段控件。两段都在，是因为一个来回翻转的按钮说不清「现在是哪一档」。 */}
+          {/* 缩放档：两段的分段控件。两段都在，是因为一个来回翻转的按钮说不清「现在是哪一档」。
+              0050 撤掉了「空格 + 拖拽平移」的提示 —— 那个手势没有了（见文件头第 4 条）。 */}
           <div className={styles.archZoom} role="group" aria-label="缩放">
             <button type="button" className={cn(styles.archZoomOption, mode === 'fit' && styles.archZoomOn)}
-              aria-pressed={mode === 'fit'} onClick={() => setMode('fit')} title="整图缩到栏宽，一眼看全三条链路">适应</button>
+              aria-pressed={mode === 'fit'} onClick={() => setMode('fit')} title="整图缩进框里：一眼看全，永远居中">适应</button>
             <button type="button" className={cn(styles.archZoomOption, mode === 'actual' && styles.archZoomOn)}
-              aria-pressed={mode === 'actual'} onClick={() => setMode('actual')} title="按设计尺寸 1:1 显示，横向滚动查看">1:1</button>
+              aria-pressed={mode === 'actual'} onClick={() => setMode('actual')} title="按设计尺寸 1:1 显示，读字用；放不下时容器出滚动条">1:1</button>
           </div>
           <Button variant="outline" size="sm" onClick={toggleFullscreen} aria-pressed={fullscreen}>
             {fullscreen ? <Minimize2 size={14} /> : <Maximize2 size={14} />}{fullscreen ? '退出全屏' : '全屏'}
           </Button>
         </div>
       </div>
-      <div className={styles.archScroll} style={scrollStyle} ref={scroller}>
-        <div className={styles.archBoard} style={boardStyle}>
-          <div className={styles.archCanvas} ref={host} />
+      {/* 容器仍然是一个滚动容器（1:1 档放不下时要有出路），但**没有拖拽手势**：
+          0050 起它只负责「把整图居中摆好」。 */}
+      <div className={cn(styles.archScroll, styles.archScrollStage)} ref={scroller}>
+        <div className={styles.archFrame} style={frameStyle}>
+          <div className={styles.archBoard} style={boardStyle}>
+            <div className={styles.archCanvas} ref={host} />
+          </div>
         </div>
       </div>
       {/* 详情浮层：画布内，不缩放，可关闭。关掉之后画布恢复成完整的一张图。 */}

package/src/client/arch/NodeLogicPanel.tsx

@@ -21,7 +21,7 @@ import {
 import { Badge, Button, cn } from '@tita-data-agent/ui/components'
 import {
   NODE_META, NODE_STATUS_LABEL, jumpTargetOf, laneOf, nodeMetrics,
-  type KnowledgeStats, type KnowledgeTab, type NodeId, type NodeStatus, type PanelTab,
+  type KnowledgeStats, type KnowledgeTab, type NodeId, type NodeStatus, type PanelTab, type WorkspaceTabKind,
 } from '../architecture.tsx'
 import { LANE_PALETTE, recordRows } from './model.ts'
 import { styles } from '../styles.ts'
@@ -38,7 +38,8 @@ export interface NodeLogicPanelProps {
   version: number
   /** 跳到节点所属的功能 tab；`knowledgeTab` 存在时还要落到知识库里那一栏。 */
   onJump: (tab: PanelTab, knowledgeTab?: KnowledgeTab) => void
-  onOpenTab?: (kind: 'data-sheet' | 'data-notebook') => void
+  /** 打开一个工作区页面（Table / Notebook / 画布）。 */
+  onOpenTab?: (kind: WorkspaceTabKind) => void
   onClose: () => void
 }
 
@@ -123,9 +124,11 @@ export function NodeLogicPanel({ selected, stats, version, onJump, onOpenTab, on
             去配置<ArrowRight size={14} />
           </Button>
           : <p className={styles.archPanelHint}><CircleHelp size={13} />这个节点没有可配置页：{meta.status === 'host' ? '它由宿主提供' : meta.status === 'planned' ? '它还没实现，先在这里说明设计意图' : '它的行为由代码决定，没有可调参数'}。</p>}
-        {(selected === 'answer' || selected === 'data-sheet' || selected === 'data-notebook') && onOpenTab && <div className={styles.archPanelActions}>
+        {(selected === 'answer' || selected === 'data-sheet' || selected === 'data-notebook' || selected === 'data-canvas') && onOpenTab && <div className={styles.archPanelActions}>
           <Button variant="outline" size="sm" onClick={() => onOpenTab('data-sheet')}><ChevronRight size={13} />打开 Table</Button>
           <Button variant="outline" size="sm" onClick={() => onOpenTab('data-notebook')}><ChevronRight size={13} />打开 Notebook</Button>
+          {/* 画布与 Table / Notebook 并列：三者都是这一格的输出产物，之前少列了一个。 */}
+          <Button variant="outline" size="sm" onClick={() => onOpenTab('data-excalidraw')}><ChevronRight size={13} />打开画布</Button>
         </div>}
       </PanelSection>
     </div>