@dsh-workbench/module-tools 0.2.13 → 0.2.15

package/README.md

@@ -26,10 +26,10 @@ dsh-wb-module publish               # 发货前的清单：门禁 + 三张表 +
 | `source` | 源码边界：不直接引 dsh 的包、不引不是种子词的 `@deepseek-ai/*` |
 | `primitives` | dsh 原语只从模块表（`kit`）拿 |
 | `kit` | 这份外壳的 kit 成员到底有哪些（缺什么会当场点名） |
-| `cards` | 卡片渲染：五态都要画得出来，空数据不许抛 |
+| `cards` | 卡片渲染：**八态 × zh/en 各渲一遍**（外壳侧输入 idle / loading / loading-刷新保留旧值（含旧时间戳 `at`）/ ready / ready-空容器 / unreadable-error / unreadable-能力闸缺插件 / unreadable-能力闸缺命令；`useApiResource` 与 `useCapabilityGate` 由判据喂，`useUnitBoard` 用模块仓里装的那份**真壳**）—— 不许抛、不许空白、文字里不许出现 `undefined` / `NaN` / `[object Object]` / `null`、不许裸键名、要套外壳的卡壳、清单 `titleKey` 在两语字典里都有落点。**不断言"画的是哪一态那一屏"**（那归模块自己的逐态测试与 `design.json` 状态矩阵）；模块没装外壳时逐态那半跳过、单次全桩渲染照旧跑 |
 | `standalone` | 独立构建：产物不依赖工坊里跑 |
 | `markers` | 公开包无内部标识（内网域名、企业内部名） |
-| `style` | 样式归属：模块不许定义外壳类（`wb-*`）的规则（判据看**复合选择器**，`:global(.wb-x)` 也算，只有同一个复合选择器里带模块自己的类才放行）；**裸 `<a>` 与裸交互控件（`<button>` / `<input>` / `<select>`）都判红** —— 前者用 kit 的 `Link`，后者用 `Button` / `TextField` / `SelectField` / `ChoiceGroup`；只有 `<textarea>` 与 `input[type=hidden\|file]` 例外（两处都没有那种形态）；**手写的「标签 + 控件」行（标签元素紧邻 `SelectField` / `TextField` / `ChoiceGroup` / `Input`）与模块自己给 `field`/`form` 容器设的行距（`gap` / 上下 `margin`）也判红** —— 这一层归 kit 的 `FormRow(s)`（[ADR-0052](../../docs/adr/0052-the-form-row-is-one-component.md)：面 → 行 → 控件）；现存违规收进 `FORM_ROW_EXEMPT`（棘轮：迁一处删一行，且表里已经不再命中的行会当场报红） |
+| `style` | 样式归属：模块不许定义外壳类（`wb-*`）的规则（判据看**复合选择器**，`:global(.wb-x)` 也算，只有同一个复合选择器里带模块自己的类才放行）；**裸 `<a>` 与裸交互控件（`<button>` / `<input>` / `<select>`）都判红** —— 前者用 kit 的 `Link`，后者用 `Button` / `TextField` / `SelectField` / `ChoiceGroup`；只有 `<textarea>` 与 `input[type=hidden\|file]` 例外（两处都没有那种形态）；**手写的「标签 + 控件」行（标签元素紧邻 `SelectField` / `TextField` / `ChoiceGroup` / `Input`）与模块自己给 `field`/`form` 容器设的行距（`gap` / 上下 `margin`）也判红** —— 这一层归 kit 的 `FormRow(s)`（[ADR-0052](../../docs/adr/0052-the-form-row-is-one-component.md)：面 → 行 → 控件）；现存违规收进 `FORM_ROW_EXEMPT`（棘轮：迁一处删一行，且表里已经不再命中的行会当场报红）；**手写的操作区（借了 `wb-formActions` 槽类手摆按钮）也判红** —— 操作区归 kit 的 `FormActions`（[ADR-0054](../../docs/adr/0054-the-action-area-is-one-component.md)：顺序 / 一个区一颗 `primary` / `danger` 的位置 / 间距 / 窄容器换行都由它定，调用点只给数据与语义），现存违规收进 `FORM_ACTIONS_EXEMPT`（同一套棘轮：迁一处删一行，表里不再命中的行当场报红） |
 | `alias` | 模块不指外壳：源码里没有指向外壳 `@/` 的引用 |
 
 三态输出：`✔ 通过` / `○ 不适用` / `✖ 不过`；有任何不过就退出 1。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "esbuild": "^0.28.2",
-    "@dsh-workbench/shared": "0.2.13"
+    "@dsh-workbench/shared": "0.2.15"
   },
   "scripts": {
     "selfcheck": "node scripts/selfcheck.mjs"

package/src/checks/cards.mjs

@@ -1,28 +1,29 @@
-// 模块卡片能不能**画出来**（S1 视觉验收里唯一能机器化的那一半）。
-//
-// 「卡片出现」这句话里有两件事：
-//   ① 结构画得出来 —— 卡片的代码跑得通、返回一棵非空元素树。**这条能机器验**；
-//   ② 画成什么样（间距、颜色、两栏还是三栏）—— 只有人眼能判，这里不碰。
-//
-// 为什么用「空数据」当输入：外壳渲染卡片时，数据往往还没回来（第一次读、卡在审批、
-// 平台没登录）。所以**卡片在拿到空数据时不许抛** —— 这正是"卡片一直不出来 / 点一下白屏"
-// 那类事故的机器形态。给了数据才跑得通的卡片，等于把崩溃留到用户面前。
-//
-// 手法与 packages/workbench/scripts/selfcheck.mjs 里那套一致：产物是
-// `window.__ModuleLoader__.load({id, factory})`，用假的 loader / require 把它拉起来。
-// 覆盖范围跟着 `dsh.workbench` 自述清单走 —— 新模块不用改这里。
-//
-// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
-// 打印与退出码归 `../check.mjs` 那一层。
-
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
 import { discoverModulePackages } from '../discover.mjs';
+import { shellClientPathOf, shellKitOf } from './shell-artifact.mjs';
 
 export const title = '卡片渲染';
 
-// 任何属性都拿得到、任何调用都返回自己的替身 —— 这样「外壳还没给数据」的各种形状
-// 都不会让卡片因为我们**没桩到某个字段**而假红。真红只留给卡片自己的代码。
+const LANGUAGES = ['zh', 'en'];
+
+const FORBIDDEN = [
+  { token: 'undefined', pattern: /\bundefined\b/ },
+  { token: 'NaN', pattern: /\bNaN\b/ },
+  { token: '[object Object]', pattern: /\[object Object\]/ },
+  { token: 'null', pattern: /\bnull\b/ },
+];
+
+const WORKSPACE = { path: '/tmp/repo', workspaceId: 'wb-card-probe' };
+
+// 刷新那一帧的旧时间戳（`at`）。真壳在 `ready` 那一步写 `Date.now()`，同一个 identity 重读时
+// 把它原样带进 loading 相（`use-api-resource.ts:102`）；这里给一个固定的过去时刻，判据不依赖
+// "现在几点"（同一个值每次跑都一样，负例才好断言）。
+const STALE_AT = 1_700_000_000_000;
+
 function anyStub(path = 'stub') {
   const target = function () {
     return anyStub(`${path}()`);
@@ -42,12 +43,126 @@ function anyStub(path = 'stub') {
   });
 }
 
+function containerStub(path, size) {
+  const elementAt = (index) => containerStub(`${path}[${index}]`, size);
+  const asArray = () => Array.from({ length: size }, (_unused, index) => elementAt(index));
+  const scalar = size > 0 ? 1 : 0;
+  const methods = {
+    map: (fn) => asArray().map(fn),
+    filter: (fn) => asArray().filter(fn),
+    forEach: (fn) => asArray().forEach(fn),
+    find: (fn) => asArray().find(fn),
+    findIndex: (fn) => asArray().findIndex(fn),
+    some: (fn) => asArray().some(fn),
+    every: (fn) => asArray().every(fn),
+    reduce: (fn, initial) => asArray().reduce(fn, initial),
+    flatMap: (fn) => asArray().flatMap(fn),
+    slice: (from, to) => asArray().slice(from, to),
+    at: (index) => asArray().at(index),
+    indexOf: (value) => asArray().indexOf(value),
+    includes: (value) => asArray().includes(value),
+    join: (separator) => asArray().join(separator),
+    concat: (other) => asArray().concat(other),
+    reverse: () => asArray().reverse(),
+    sort: () => asArray(),
+    keys: () => asArray().keys(),
+    values: () => asArray().values(),
+    entries: () => asArray().entries(),
+    toArray: () => asArray(),
+  };
+  return new Proxy(function () {}, {
+    get(_target, key) {
+      if (key === 'ok') return true;
+      if (key === Symbol.toPrimitive) return () => scalar;
+      if (key === Symbol.iterator) return () => asArray()[Symbol.iterator]();
+      if (key === 'then') return undefined;
+      if (key === 'length') return size;
+      if (key === 'toString' || key === 'valueOf') return () => scalar;
+      if (key === 'constructor') return Object;
+      if (key in methods) return methods[key];
+      if (typeof key === 'symbol') return undefined;
+      return containerStub(`${path}.${String(key)}`, size);
+    },
+    apply() {
+      return containerStub(`${path}()`, size);
+    },
+  });
+}
+
+const SNAPSHOTS = [
+  { name: 'idle', resource: { phase: 'idle' }, workspace: null },
+  { name: 'loading', resource: { phase: 'loading' }, workspace: WORKSPACE },
+  { name: 'ready', resource: { phase: 'ready', value: containerStub('api', 2) }, workspace: WORKSPACE },
+  {
+    name: 'empty（有值但容器空）',
+    resource: { phase: 'ready', value: containerStub('api', 0) },
+    workspace: WORKSPACE,
+  },
+  {
+    name: 'unreadable',
+    resource: { phase: 'error', error: { code: 'network', message: '宿主没有响应' } },
+    workspace: WORKSPACE,
+  },
+  // P2 第一条：刷新形态（ADR-0022「刷新保留旧值」）。载荷与 `loading` 只差两格 —— `value` 与
+  // `at` 都在，而且是旧那份。`use-api-resource.ts:100-104` 在同一个 identity 重读时给的就是这一相
+  // （`{ phase: 'loading', value: prev.value, ...(prev.at === undefined ? {} : { at: prev.at }) }`，
+  // 而 `prev.at` 是 `ready` 那一步写的 `Date.now()`，所以真实这一相两格一起在）。卡片若把
+  // "loading 就没有值"写死，脏就出在这一帧；若把旧值当新值、或拿旧 `at` 当"刚读到"去算，脏也出在这一帧。
+  {
+    name: 'loading（刷新：保留旧值）',
+    resource: { phase: 'loading', value: containerStub('api', 2), at: STALE_AT },
+    workspace: WORKSPACE,
+  },
+  // P2 第二条：能力闸。`useCapabilityGate` 给一个**明确的** `missing-plugin`（不是 `null`）：
+  // `use-unit-board.ts:47` 对 `capability === null` 直接不算 `blockerOfCapability`，喂 null 就退化成
+  // P1 的 idle 那一屏、一格新代码都走不到。`gated` 由能力状态按 `gateOf`（`unit-board.ts:13-17`）
+  // 算出来（missing-plugin ⇒ false），`resource` 照 `ready` 一份 —— 于是它跟 `ready` 只差闸这一格，
+  // 阻断屏与正文同时在场时谁优先是模块的事。
+  {
+    name: 'unreadable（能力闸：缺插件）',
+    resource: { phase: 'ready', value: containerStub('api', 2) },
+    workspace: WORKSPACE,
+    capability: (unit) => ({
+      unit,
+      status: 'missing-plugin',
+      required: ['demo-plugin'],
+      missing: ['demo-plugin'],
+      detail: '逐态探针：缺 demo-plugin',
+    }),
+  },
+  // P2 补记：能力闸的第二种 status —— `missing-commands`（插件在、命令旧）。它与缺插件那一帧
+  // 差的是两格：`status` 换掉，且 `fix` / `command` 都在（真壳 `probe-verdict.ts:109-116`：命令落后
+  // 的插件状态是 `outdated`，于是 `fix: 'update'`；`:158-160` 再带上那条升级命令）。这两格正好把
+  // `blockerOfCapability` 里 `install` 那一段走通：`fixAction`（`blocker.fix.update`）+ `copyAction`
+  // （`blocker.copy` + `command` 原文，`blocker-table.ts:109-123`），加上照旧的 retry —— 缺插件那一帧
+  // 两格都没给，install 是空的，只走到 retry。`sourceUnknown` 在 `fix` 在时不成立，所以不开市场那条。
+  {
+    name: 'unreadable（能力闸：缺命令）',
+    resource: { phase: 'ready', value: containerStub('api', 2) },
+    workspace: WORKSPACE,
+    capability: (unit) => ({
+      unit,
+      status: 'missing-commands',
+      required: ['demo-plugin'],
+      missing: ['demo.command'],
+      detail: '逐态探针：demo-plugin 装在，缺 demo.command',
+      fix: 'update',
+      command: 'opencli plugin update demo-plugin',
+    }),
+  },
+];
+
 function fakeReact() {
   const element = (type, props, ...children) => ({ type, props: props ?? {}, children });
-  return {
+  const passthrough = (props, ...children) => element('stub:passthrough', props, ...children);
+  const base = {
     createElement: element,
     createElementNS: (_namespace, type, props, ...children) => element(type, props, ...children),
     Fragment: 'Fragment',
+    Component: class {},
+    PureComponent: class {},
+    createContext: (value) => ({ Provider: passthrough, Consumer: passthrough, _currentValue: value }),
+    useContext: () => anyStub('context'),
     useState: (initial) => [typeof initial === 'function' ? initial() : initial, () => {}],
     useReducer: (_reducer, initial) => [initial, () => {}],
     useMemo: (factory) => factory(),
@@ -55,20 +170,52 @@ function fakeReact() {
     useRef: (initial) => ({ current: initial ?? null }),
     useEffect: () => {},
     useLayoutEffect: () => {},
+    useInsertionEffect: () => {},
     useSyncExternalStore: (_subscribe, snapshot) => snapshot(),
     useId: () => 'wb-id',
+    useTransition: () => [false, (fn) => fn()],
+    useDeferredValue: (value) => value,
     isValidElement: (value) => typeof value === 'object' && value !== null && 'type' in value,
-    Children: { toArray: (value) => (Array.isArray(value) ? value : [value]) },
+    cloneElement: (node, props, ...children) =>
+      element(node.type, { ...(node.props ?? {}), ...(props ?? {}) }, ...children),
+    memo: (fn) => fn,
+    forwardRef: (fn) => fn,
+    Children: {
+      toArray: (value) =>
+        Array.isArray(value) ? value : value === undefined || value === null ? [] : [value],
+      map: (value, fn) =>
+        (Array.isArray(value) ? value : value === undefined || value === null ? [] : [value]).map(fn),
+      count: (value) =>
+        Array.isArray(value) ? value.length : value === undefined || value === null ? 0 : 1,
+    },
   };
+  return new Proxy(base, { get: (target, key) => (key in target ? target[key] : () => null) });
+}
+
+function fakeJsxRuntime() {
+  const react = fakeReact();
+  return {
+    Fragment: react.Fragment,
+    jsx: (type, props) => react.createElement(type, props, ...(props?.children ?? [])),
+    jsxs: (type, props) => react.createElement(type, props, ...(props?.children ?? [])),
+    jsxDEV: (type, props) => react.createElement(type, props, ...(props?.children ?? [])),
+  };
+}
+
+function fakeDshPackage() {
+  const stub = (props) => ({
+    type: 'stub:dsh',
+    props: props ?? {},
+    children:
+      props?.children === undefined ? [] : Array.isArray(props.children) ? props.children : [props.children],
+  });
+  return new Proxy({}, { get: () => stub });
 }
 
 function fakeKit() {
   const callable = () => anyStub('result');
   return {
     hooks: new Proxy({}, { get: () => callable }),
-    // 组件替身**带上自己的名字**（`stub:Card`）：卡片壳现在是 `kit.components.Card` 这个组件，
-    // 产物里不会再出现 `wb-card` 这个类名 —— 判据要能认出"用了外壳给的卡壳"。
-    // children 要**往下传**：吞掉的话，卡片体内用 kit 组件写的内容就永远渲染不到（节点数会假少）。
     components: new Proxy(
       {},
       {
@@ -87,23 +234,9 @@ function fakeKit() {
   };
 }
 
-/**
- * dsh 的客户端包（平台种子词）在**卡片渲染**这里的替身。
- *
- * 模块的产物里 `require("@deepseek-ai/dsh-client-ui-primitives")` 是**规范**（ADR-0028：
- * 标成 external 才是"用外壳那一份"）。判据在 node 里跑产物，就得像外壳的模块表那样把这些
- * 种子词交出去 —— 不然合规的模块反而卡在"没桩的外部"（实际上就是这么发现的）。
- * 组件与 hooks 都长成函数：卡片判据只问"画不画得出非空元素树"。
- */
-function fakeDshPackage() {
-  const stub = (props) => ({ type: 'stub', props: props ?? {}, children: [] });
-  return new Proxy({}, { get: (_target, key) => (key === 'default' ? stub : stub) });
-}
-
-function loadFace(clientFile) {
+function loadFace(clientFile, makeKit) {
   let captured;
   const fakeWindow = {
-    // 浏览器里 `window.location` 永远在；缺了它，读它的客户端代码（含 `?wbMock=1` 那个开关）会先抛。
     location: { search: '', href: 'http://127.0.0.1:3081/' },
     __ModuleLoader__: {
       load: (entry) => {
@@ -121,7 +254,8 @@ function loadFace(clientFile) {
   expose.exports = module.exports;
   const fakeRequire = (id) => {
     if (id === 'react') return fakeReact();
-    if (id === '@dsh-workbench/core/client') return { kit: fakeKit() };
+    if (id === 'react/jsx-runtime' || id === 'react/jsx-dev-runtime') return fakeJsxRuntime();
+    if (id === '@dsh-workbench/core/client') return { kit: makeKit() };
     if (id.startsWith('@deepseek-ai/')) return fakeDshPackage();
     throw new Error(`产物 require 了没桩的外部：${id}`);
   };
@@ -129,23 +263,29 @@ function loadFace(clientFile) {
   return { id: captured.id, exports: produced ?? module.exports };
 }
 
-// 递归**调用**函数组件 —— 不调用的话，树里只有最外层那个 `type`，
-// 卡片体内的代码一行都没跑（第一次写漏了这步，4 张卡片都只数出 3 个节点）。
-//
-// 顺手把**用到的类名**收集起来：卡片得自己套外壳的卡片契约类（见文件尾那条判据）。
 function render(node, depth, budget) {
   if (node === null || node === undefined || typeof node === 'boolean') return 0;
-  if (typeof node === 'string' || typeof node === 'number') return 1;
+  if (typeof node === 'string' || typeof node === 'number') {
+    budget.texts.push(String(node));
+    return 1;
+  }
   if (Array.isArray(node)) {
     let count = 0;
     for (const one of node) count += render(one, depth, budget);
     return count;
   }
-  if (typeof node !== 'object') return 1;
+  if (typeof node !== 'object') {
+    budget.texts.push(String(node));
+    return 1;
+  }
   if (budget.left <= 0) return 0;
   budget.left -= 1;
   budget.maxDepth = Math.max(budget.maxDepth, depth);
-
+  for (const [key, value] of Object.entries(node.props ?? {})) {
+    if (key === 'key' || key === 'ref') continue;
+    if (typeof value === 'string') budget.texts.push(value);
+    else if (typeof value === 'number' && Number.isNaN(value)) budget.texts.push('NaN');
+  }
   const classes = node.props?.className;
   if (typeof classes === 'string') {
     for (const one of classes.split(/\s+/)) if (one !== '') budget.classNames.add(one);
@@ -153,7 +293,6 @@ function render(node, depth, budget) {
   if (typeof node.type === 'string' && node.type.startsWith('stub:')) {
     budget.stubs.add(node.type.slice('stub:'.length));
   }
-
   const children = [...(node.children ?? [])];
   if (typeof node.type === 'function') {
     if (depth > 40) throw new Error('组件递归超过 40 层（自引用？）');
@@ -165,10 +304,75 @@ function render(node, depth, budget) {
   return count;
 }
 
+async function shellDictionariesOf() {
+  const require = createRequire(import.meta.url);
+  const entry = require.resolve('@dsh-workbench/shared');
+  const module = await import(pathToFileURL(join(dirname(entry), 'i18n/index.js')).href);
+  return module.dictionaries;
+}
+
+function ownOf(dictionaries, language) {
+  const one = dictionaries?.[language];
+  return typeof one === 'object' && one !== null ? one : {};
+}
+
+function translatorOf(language, messages, shellDictionaries, missing, snapshot) {
+  const own = ownOf(messages, language);
+  const shell = ownOf(shellDictionaries, language);
+  return (key, params) => {
+    const template = typeof own[key] === 'string' ? own[key] : shell[key];
+    if (typeof template !== 'string') {
+      missing.push({ language, key, snapshot });
+      return `\u0000missing:${key}\u0000`;
+    }
+    if (params === undefined || params === null) return template;
+    return template.replace(/\{(\w+)\}/g, (whole, name) =>
+      name in params ? String(params[name]) : whole,
+    );
+  };
+}
+
+function forbiddenHitsOf(texts) {
+  const hits = [];
+  const seen = new Set();
+  for (const text of texts) {
+    for (const { token, pattern } of FORBIDDEN) {
+      if (!pattern.test(text)) continue;
+      const key = `${token}\u0000${text}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      hits.push({ token, text });
+    }
+  }
+  return hits;
+}
+
+function shellClientsOf(modulePackages) {
+  const found = new Set();
+  for (const pkg of modulePackages) {
+    const client = shellClientPathOf(pkg.dir);
+    if (client !== undefined && existsSync(client)) found.add(client);
+  }
+  return [...found];
+}
+
 export async function run() {
   const modulePackages = discoverModulePackages({ root: process.cwd() });
   const problems = [];
   const rows = [];
+  const footnotes = [];
+  let degraded = 0;
+
+  let shellDictionaries;
+  try {
+    shellDictionaries = await shellDictionariesOf();
+  } catch (error) {
+    shellDictionaries = undefined;
+    footnotes.push(
+      `（取不出 @dsh-workbench/shared 的字典：${error instanceof Error ? error.message : String(error)}）` +
+        ' —— 逐态那半跳过（单次全桩渲染照旧跑），因为裸键名判定要模块 ∪ 外壳两份字典',
+    );
+  }
 
   for (const pkg of modulePackages) {
     const name = pkg.manifest.name;
@@ -178,9 +382,44 @@ export async function run() {
       continue;
     }
 
+    const declared = pkg.manifest.dsh?.workbench?.card ?? null;
+    const declaresCard =
+      declared !== null && typeof declared.titleKey === 'string' && declared.titleKey !== '';
+
+    const shellClient = shellClientPathOf(pkg.dir);
+    const hasShell = shellClient !== undefined && existsSync(shellClient);
+    const current = { snapshot: SNAPSHOTS[0] };
+    let realKit;
+    let shellProblem;
+    if (hasShell && shellDictionaries !== undefined) {
+      try {
+        realKit = shellKitOf(shellClient, { react: fakeReact(), dshPackage: fakeDshPackage() });
+      } catch (error) {
+        shellProblem = error instanceof Error ? error.message : String(error);
+      }
+    }
+
+    const makeKit = () => {
+      if (realKit === undefined) return fakeKit();
+      const hooks = { ...(realKit.hooks ?? {}) };
+      hooks.useApiResource = () => current.snapshot.resource;
+      // 闸这一格的默认（P1 五态都是它）：没查过 ⇒ capability null、gated true。快照带了
+      // `capability` 才换成那一份，`gated` 照 `gateOf(capability, 'capability')` 算 —— 判据不当
+      // 第二份真相：状态的语义归外壳，这里只是把"外壳会给的那一格"摆出来。
+      hooks.useCapabilityGate = (unit) => {
+        const capability = current.snapshot.capability?.(unit) ?? null;
+        return {
+          capability,
+          gated: capability === null || capability.status === 'ok' || capability.status === 'unchecked',
+          forceProbe: () => {},
+        };
+      };
+      return { ...realKit, hooks };
+    };
+
     let face;
     try {
-      const loaded = loadFace(clientFile);
+      const loaded = loadFace(clientFile, makeKit);
       face = loaded.exports;
     } catch (error) {
       problems.push(`${name}: 产物加载不起来 —— ${error.message}`);
@@ -218,12 +457,6 @@ export async function run() {
     }
 
     const card = registered?.card;
-    // 清单说"没有卡片"（`"card": null`）与产物说"没有卡片"必须是同一件事 —— 两处说法不一致就是
-    // 声明与代码打架：登记了的那张卡没人会画（外壳只认清单），它只会一直烂在产物里。
-    // 这条判据的名字就是它防的事：gitops 当初为了哄旧判据挂了一张"我这张卡片就是说我没有卡片"的占位卡。
-    const declared = pkg.manifest.dsh?.workbench?.card ?? null;
-    const declaresCard =
-      declared !== null && typeof declared.titleKey === 'string' && declared.titleKey !== '';
     if (!declaresCard) {
       if (typeof card === 'function') {
         problems.push(
@@ -240,9 +473,6 @@ export async function run() {
       continue;
     }
 
-    // 清单的 `card.titleKey` 是**面板那一格的标题**，它的文案住在模块自己交的字典里
-    // （`registerUnit` 那个面的 `messages`，`zh` / `en` 都必填）。键拼错、或字典漏了那一条 ⇒
-    // 面板上显示的就是原始键名（`demo.cardTitle`），而且一声不响 —— 这条判据盯它。
     const titleKey = pkg.manifest.dsh?.workbench?.card?.titleKey;
     if (typeof titleKey === 'string' && titleKey !== '') {
       const messages = registered?.messages;
@@ -263,7 +493,7 @@ export async function run() {
     }
 
     const props = {
-      world: { current: {} },
+      world: { current: { sessionId: null, workspace: null } },
       t: (key) => key,
       refreshToken: 0,
       onRefresh: () => {},
@@ -272,49 +502,154 @@ export async function run() {
       onSummary: () => {},
     };
 
-    let tree;
-    try {
-      tree = card(props);
-    } catch (error) {
-      problems.push(`${name}: 空数据下卡片抛了 —— ${error.message}`);
+    if (realKit === undefined) {
+      const why =
+        shellProblem !== undefined
+          ? `取不出这份外壳的 kit（${shellClient}）—— ${shellProblem}`
+          : shellDictionaries === undefined
+            ? '取不出 @dsh-workbench/shared 的字典'
+            : '没装外壳（@dsh-workbench/core）';
+      let tree;
+      try {
+        tree = card(props);
+      } catch (error) {
+        problems.push(`${name}: 空数据下卡片抛了 —— ${error.message}`);
+        continue;
+      }
+      if (tree === null || tree === undefined) {
+        problems.push(`${name}: 空数据下卡片返回空（界面上就是一片空白）`);
+        continue;
+      }
+      const budget = { left: 20000, maxDepth: 0, classNames: new Set(), stubs: new Set(), texts: [] };
+      let count;
+      try {
+        count = render(tree, 0, budget);
+      } catch (error) {
+        const where = (error.stack ?? '').split('\n').slice(1, 4).join(' | ');
+        problems.push(`${name}: 卡片体内的组件抛了 —— ${error.message}\n      ${where}`);
+        continue;
+      }
+      if (count <= 1) {
+        problems.push(`${name}: 卡片只画出一个节点 —— 卡片体没跑（或什么都没画）`);
+        continue;
+      }
+      if (!(budget.classNames.has('wb-card') || budget.stubs.has('Card'))) {
+        problems.push(
+          `${name}: 卡片没套外壳的卡壳 —— 用 kit.components.Card（推荐），或自己写契约类 wb-card + ` +
+            `wb-cardBody；裸内容在面板里看起来就"不是一张卡片"`,
+        );
+        continue;
+      }
+      footnotes.push(`${name}: ${why} —— 逐态渲染跳过，只跑了单次全桩渲染`);
+      rows.push(`${name}: 空数据下画得出 ${count} 个节点（最深 ${budget.maxDepth} 层）`);
+      degraded += 1;
       continue;
     }
 
-    if (tree === null || tree === undefined) {
-      problems.push(`${name}: 空数据下卡片返回空（界面上就是一片空白）`);
-      continue;
-    }
+    const missing = [];
+    const counts = new Map();
+    const textsBySnapshot = new Map();
+    const classNames = new Set();
+    const stubs = new Set();
 
-    const budget = { left: 20000, maxDepth: 0, classNames: new Set(), stubs: new Set() };
-    let count;
-    try {
-      count = render(tree, 0, budget);
-    } catch (error) {
-      const where = (error.stack ?? '').split('\n').slice(1, 4).join(' | ');
-      problems.push(`${name}: 卡片体内的组件抛了 —— ${error.message}\n      ${where}`);
-      continue;
+    for (const snapshot of SNAPSHOTS) {
+      current.snapshot = snapshot;
+      counts.set(snapshot.name, []);
+      for (const language of LANGUAGES) {
+        const budget = { left: 20000, maxDepth: 0, classNames: new Set(), stubs: new Set(), texts: [] };
+        const where = `${snapshot.name}（${language}）`;
+        props.t = translatorOf(
+          language,
+          registered?.messages,
+          shellDictionaries,
+          missing,
+          snapshot.name,
+        );
+        props.world = { current: { sessionId: null, workspace: snapshot.workspace } };
+
+        let tree;
+        try {
+          tree = card(props);
+        } catch (error) {
+          problems.push(`${name}: ${where} 卡片抛了 —— ${error.message}`);
+          continue;
+        }
+        if (tree === null || tree === undefined) {
+          problems.push(`${name}: ${where} 卡片返回空 —— 这一态下卡片没画出来（界面上就是一片空白）`);
+          continue;
+        }
+        let count;
+        try {
+          count = render(tree, 0, budget);
+        } catch (error) {
+          const stack = (error.stack ?? '').split('\n').slice(1, 4).join(' | ');
+          problems.push(`${name}: ${where} 卡片体内的组件抛了 —— ${error.message}\n      ${stack}`);
+          continue;
+        }
+        if (count <= 1) {
+          problems.push(
+            `${name}: ${where} 卡片只画出 ${count} 个节点 —— 这一态下卡片体没跑（或只剩一层空壳）`,
+          );
+          continue;
+        }
+        counts.get(snapshot.name).push(count);
+        for (const one of budget.classNames) classNames.add(one);
+        for (const one of budget.stubs) stubs.add(one);
+        const bucket = textsBySnapshot.get(snapshot.name) ?? [];
+        bucket.push(...budget.texts);
+        textsBySnapshot.set(snapshot.name, bucket);
+        for (const hit of forbiddenHitsOf(budget.texts)) {
+          problems.push(
+            `${name}: ${where} 屏上出现了 ${hit.token} —— 这一态下卡片把它摆到了文字上。` +
+              `命中的那串：${hit.text.slice(0, 120)}`,
+          );
+        }
+      }
     }
-    if (count <= 1) {
-      problems.push(`${name}: 卡片只画出一个节点 —— 卡片体没跑（或什么都没画）`);
-      continue;
+
+    if (missing.length > 0) {
+      const grouped = new Map();
+      for (const one of missing) {
+        const key = `${one.language}\u0000${one.key}`;
+        if (!grouped.has(key)) grouped.set(key, { key: one.key, language: one.language, snapshots: [] });
+        const entry = grouped.get(key);
+        if (!entry.snapshots.includes(one.snapshot)) entry.snapshots.push(one.snapshot);
+      }
+      for (const entry of grouped.values()) {
+        problems.push(
+          `${name}: t('${entry.key}') 在 ${entry.language} 里没有落点（问它的快照：` +
+            `${entry.snapshots.join('、')}）—— 屏上会显示原始键名。` +
+            '命中判定 = 模块 messages ∪ 外壳 dictionaries',
+        );
+      }
     }
-    // 卡片得**套上外壳给的卡壳**：要么用 `kit.components.Card` 这个组件（推荐、也是 hello 现在的做法），
-    // 要么自己写契约类 `wb-card`（`board.css` 里那条，兄弟模块现在还是这么写的）。
-    //
-    // 用户实测（2026-10-09）："我们的 hello module 怎么不是卡片" —— 面板里那块内容既没有底色也没有
-    // 描边，看着就是标题加一段话。原因是卡片函数没套壳：当时用的是 `wb-view`（那是面板列布局），
-    // 更早那份装进 profile 的产物还自己搓过 `wb-hello*`。两种都查得出来：组件走 stub 名，类名走 classNames。
-    const shelled = budget.classNames.has('wb-card') || budget.stubs.has('Card');
-    if (!shelled) {
+
+    if (!(classNames.has('wb-card') || stubs.has('Card'))) {
       problems.push(
         `${name}: 卡片没套外壳的卡壳 —— 用 kit.components.Card（推荐），或自己写契约类 wb-card + ` +
           `wb-cardBody；裸内容在面板里看起来就"不是一张卡片"`,
       );
       continue;
     }
-    rows.push(`${name}: 空数据下画得出 ${count} 个节点（最深 ${budget.maxDepth} 层）`);
+
+    const per = SNAPSHOTS.map(
+      (snapshot) => `${snapshot.name} ${counts.get(snapshot.name).join('/') || '—'}`,
+    ).join(' · ');
+    rows.push(`${name}: ${SNAPSHOTS.length} 态 × zh/en 都画得出 —— ${per} 个节点`);
+
+    const shapes = new Set(
+      SNAPSHOTS.map((snapshot) => [...new Set(textsBySnapshot.get(snapshot.name) ?? [])].sort().join('\n')),
+    );
+    if (shapes.size === 1) {
+      footnotes.push(
+        `${name}: ${SNAPSHOTS.length} 个快照渲染出来的文本完全一样 —— 不判红，只当线索：它的取数可能没走 ` +
+          'kit.hooks.useApiResource，或这张卡片本来就不随态分叉',
+      );
+    }
   }
 
+  const shellClients = shellDictionaries === undefined ? [] : shellClientsOf(modulePackages);
+
   if (problems.length > 0) {
     return { status: 'fail', notes: [], problems };
   }
@@ -328,9 +663,19 @@ export async function run() {
   return {
     status: 'pass',
     notes: [
-      `${rows.length} 个模块过了卡片这一关：有卡片的都在**空数据**下画得出来（不许抛）、清单的 titleKey 在字典里都有落点；` +
-        '清单写 "card": null 的，产物里也确实没登记卡片（声明与代码同一句话）',
+      `${rows.length} 个模块过了卡片这一关：` +
+        (degraded === 0
+          ? `${SNAPSHOTS.length} 态 × zh/en 各渲染一遍`
+          : `逐态那半这次有 ${degraded} 个模块跳过（没装外壳 / 取不出外壳，见下），其余 ${SNAPSHOTS.length} 态 × zh/en 各渲染一遍`) +
+        ' —— 不抛、非空白、文字里没有 ' +
+        'undefined / NaN / [object Object] / null、没有裸键名、套了外壳的卡壳、清单的 titleKey 在两语字典里都有落点。' +
+        `（断言的是"${SNAPSHOTS.length} 种外壳侧输入下都退化得漂亮"，不是"画的是哪一态那一屏" —— 屏的对错归模块自己的 ` +
+        'card-states.test.ts 与 design.json 状态矩阵）',
+      ...(shellClients.length === 0
+        ? []
+        : [`逐态用的真壳（模块仓里装的那份 client.js）：${shellClients.join('、')}`]),
       ...rows,
+      ...footnotes,
     ],
     problems: [],
   };

package/src/checks/kit.mjs

@@ -21,9 +21,9 @@
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { discoverModulePackages } from '../discover.mjs';
+import { shellClientPathOf, shellKitOf } from './shell-artifact.mjs';
 
 const SHELL = '@dsh-workbench/core';
 const KIT_SPECIFIER = '@dsh-workbench/core/client';
@@ -59,44 +59,6 @@ function kitUsageOf(text) {
   return used;
 }
 
-function shellKitOf(clientPath) {
-  const stub = () => null;
-  const seed = new Proxy(
-    { default: stub },
-    { get: (target, key) => (key in target ? target[key] : stub) },
-  );
-  // react 得给一个**能 extends 的类**：外壳自己那段 `class CardBoundary extends Component`
-  // 在工厂体里就跑（错误边界只能这么写），换成箭头函数会当场 "not a constructor"。
-  const react = new Proxy(
-    { default: stub, Component: class {} },
-    { get: (target, key) => (key in target ? target[key] : stub) },
-  );
-  let exports;
-  const load = (registration) => {
-    exports = registration.factory((specifier) => {
-      if (specifier === 'react' || specifier === 'react/jsx-runtime' || specifier === 'react-dom') return react;
-      if (specifier.startsWith('@deepseek-ai/')) return seed;
-      if (specifier === SHELL) return exports;
-      throw new Error(`外壳产物里出现了一个不认识的 require("${specifier}")`);
-    });
-  };
-  const window = { __ModuleLoader__: { load } };
-  // 要的就是"按浏览器加载器那样把这份产物跑一遍"，静态解析会骗人（no-new-func 在本仓的 eslint 配置里没开）
-  new Function('window', readFileSync(clientPath, 'utf8'))(window);
-  return exports?.kit ?? {};
-}
-
-function shellClientPathOf(pkgDir) {
-  const override = process.env.DSH_WB_CORE_CLIENT;
-  if (override !== undefined && override.trim() !== '') return override.trim();
-  try {
-    const require = createRequire(join(pkgDir, 'package.json'));
-    return join(dirname(require.resolve(`${SHELL}/package.json`)), 'client.js');
-  } catch {
-    return undefined;
-  }
-}
-
 function floorOf(range) {
   if (typeof range !== 'string') return undefined;
   const match = /(\d+)\.(\d+)\.(\d+)/.exec(range);

package/src/checks/shell-artifact.mjs

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const SHELL = '@dsh-workbench/core';
+
+function defaultReact() {
+  const stub = () => null;
+  return new Proxy(
+    { default: stub, Component: class {} },
+    { get: (target, key) => (key in target ? target[key] : stub) },
+  );
+}
+
+function defaultSeed() {
+  const stub = () => null;
+  return new Proxy(
+    { default: stub },
+    { get: (target, key) => (key in target ? target[key] : stub) },
+  );
+}
+
+export function shellClientPathOf(pkgDir) {
+  const override = process.env.DSH_WB_CORE_CLIENT;
+  if (override !== undefined && override.trim() !== '') return override.trim();
+  try {
+    const require = createRequire(join(pkgDir, 'package.json'));
+    return join(dirname(require.resolve(`${SHELL}/package.json`)), 'client.js');
+  } catch {
+    return undefined;
+  }
+}
+
+export function shellKitOf(clientPath, options = {}) {
+  const react = options.react ?? defaultReact();
+  const seed = options.dshPackage ?? defaultSeed();
+  let exports;
+  const load = (registration) => {
+    exports = registration.factory((specifier) => {
+      if (specifier === 'react' || specifier === 'react/jsx-runtime' || specifier === 'react-dom') {
+        return react;
+      }
+      if (specifier.startsWith('@deepseek-ai/')) return seed;
+      if (specifier === SHELL) return exports;
+      throw new Error(`外壳产物里出现了一个不认识的 require("${specifier}")`);
+    });
+  };
+  const window = { __ModuleLoader__: { load } };
+  new Function('window', readFileSync(clientPath, 'utf8'))(window);
+  return exports?.kit ?? {};
+}

package/src/checks/style.mjs

@@ -21,6 +21,7 @@ import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { shellRulesIn } from '../css-shell.mjs';
 import { discoverModulePackages } from '../discover.mjs';
+import { auditFontSizes, fontScaleNotes, fontScaleOf } from '../font-scale.mjs';
 
 // 外链一律走 kit 的 `Link`：它自带的样式（正文色 / hover 下划线 / 12px / 那个外链小箭头）是唯一一份。
 // 手写 `<a>` / `h('a', …)` 拿到的是浏览器默认样式，而且每个人写的都不一样（这正是"同一个东西样式不一样"的来源）。
@@ -39,17 +40,14 @@ const BARE_CONTROLS = [
 const NATIVE_ONLY_INPUT = /type\s*[:=]\s*['"](?:hidden|file)['"]/;
 
 // 历史豁免：**已知**的手写控件，各有各的理由，跟着各自的迁移走 ——
-//   · `module-cmdb/src/views/ChooseEnvsBody.tsx`（一处：`role="radio"` 那一列选项行）
-//     ＝ 对应 kit 的 `ChoiceGroup`（不是 `SelectField`）；换不换是那个模块自己的一次改动
-//     （分组标题与标记是它的排版）。
 //   ①（ADR-0051 §4 那次）`module-cmdb/src/views/MenuField.tsx` 的两处手写钮已经迁完
 //   （2026-10-17，外壳发到 0.2.12 之后；cmdb `a1a37e60` / argocd `d85627a7`），那一行按棘轮删掉了 ——
 //   留着这段是因为它就是这条纪律的由来：模块的 peer 下限得先有 `SelectField`，否则装上就崩。
+//   ②（ADR-0052 §10 那次）`module-cmdb/src/views/ChooseEnvsBody.tsx` 的 `role="radio"` 选项行
+//   已经迁 `ChoiceGroup`（2026-10-17，外壳 0.2.13 之后），这一行同样按棘轮删掉了。
 // 这是**棘轮**：迁完一处就删一行，别只加不减（名单长起来等于这条判据没有）。
 // 键是 `<包名>:<相对模块根的文件路径>`。
-const CONTROL_EXEMPT = new Set([
-  '@pagoda-dsh-workbench/module-cmdb:src/views/ChooseEnvsBody.tsx',
-]);
+const CONTROL_EXEMPT = new Set([]);
 
 // ── F1「手写的标签+控件行」与 F2「自己管行距」：都该走 FormRow(s)（ADR-0052） ──────────
 //
@@ -76,6 +74,24 @@ const FORM_LAYER = /<(FormRows?|Field)\b/;
 const NOT_A_FORM = /card|list|item|issue|env|dot|sub|chip|badge|tag|tab|nav|menu/i;
 const ZERO_LENGTH = /^(?:0|0px|0rem|0em|0%|none|auto)$/i;
 
+// ── F3「手写的操作区」：该走 `FormActions`（ADR-0054） ─────────────────────────────
+//
+// 口径（[ADR-0054](../../../docs/adr/0054-the-action-area-is-one-component.md)）：操作区那一层
+// （主操作在右 / 一颗 primary / 危险动作紧挨它左侧 / 间距 / 窄容器换行）从前没有主，只有一条
+// 借来的槽类 `.wb-formActions`（它只管右对齐 + gap）。于是顺序各摆各的 —— 2026-10-17 用户在
+// argocd 绑定身份那屏说「这两个按钮的位置换一下」就是现场（pduiv2 `b7977862`）。
+//
+// 判据：模块源码（`.tsx`，测试文件除外）里出现 **`wb-formActions`** ⇒ 红，改用 kit 的 `FormActions`。
+// **为什么只钉这一条（宁可漏报）**：`wb-formActions` 只为操作区存在，出现它 = 明确在手写操作区，
+// 零误报。更宽的启发式（"同一容器里两颗以上 `Button`"）会把**合法的并排小钮**判红 —— 实测
+// `module-argocd:src/views/EnvRows.tsx` 有三处 `.actions` 容器装的是平台跳转图标钮 + 转会话 chip +
+// 同步钮（行级图标簇，没有 primary，不归 `FormActions`），`confirmActions` / `releaseConfirmActions` /
+// `envBlockActions` 这些类名也都不该判红。
+// **已知漏报**：模块自己搭容器（`<div className={styles.actions}>` 里两颗 `Button`）而不借槽类时，
+// 这一版不判 —— 只能靠评审 / SKILL 抓；`FormActions` 里那些类名带 `form` 的（如 `.formActions`）
+// 若自己写 `gap` / 上下 `margin`，还会被 F2 顺带抓到。
+const ACTION_AREA_CLASS = /wb-formActions/;
+
 /** 类名里有没有 `field(s)` / `form(s)` 这个词（按 camelCase 切词，`platform` 不算）。 */
 function isFormContainer(token) {
   return token.split(/(?=[A-Z])/).some((word) => /^(?:fields?|forms?)$/i.test(word))
@@ -169,13 +185,18 @@ function handwrittenRowsIn(text) {
 // 这是**棘轮**：迁一处删一行。而且这一版会**替你发现哪一行已经不用留了** ——
 // 某个包在眼前（被判据扫到）却一处都不再命中时，那条豁免当场报红（见 run() 里的 staleRows）。
 // 键与 `CONTROL_EXEMPT` 同形：`<包名>:<相对模块根的文件路径>`。
-const FORM_ROW_EXEMPT = new Map([
-  ['@pagoda-dsh-workbench/module-cmdb:src/views/CmdbSettings.tsx', 'cmdb 绑定表单 4 处「标签 span + SelectField」；等外壳 0.2.13 发出 FormRow 后随它迁（ADR-0052 §5/§7）'],
-  ['@pagoda-dsh-workbench/module-cmdb:src/views/EnvChoice.tsx', 'cmdb 环境行 3 处「标签 span + SelectField」；同上，随 FormRow 迁（ADR-0052 §5/§7）'],
-  ['@pagoda-dsh-workbench/module-cmdb:src/views/Cmdb.module.css', 'cmdb 自己那套 `.cmdbField` 行布局与 `.cmdbForm`/`.cmdbFieldLabel` 三档行距（8/8/2）；迁 FormRow 时一并删（ADR-0052 §7 第 ② 条）'],
-  ['@pagoda-dsh-workbench/module-argocd:src/views/IdentityFields.tsx', 'argocd 自己那套两列 grid 的 2 处「标签 span + TextField/SelectField」；随 FormRow 迁（ADR-0052 §1/§5）'],
-  ['@pagoda-dsh-workbench/module-argocd:src/views/IdentityFields.module.css', 'argocd `.fields` 网格自己管行距（gap）；行距归 FormRow(s)（ADR-0052 §7 第 ② 条）'],
-]);
+const FORM_ROW_EXEMPT = new Map([]);
+
+// 历史豁免：**已知**的手写操作区（借了 `wb-formActions` 槽类手摆按钮）。它跟上面两张又是
+// **另一件事、另一个迁移时点**：等的是外壳把 `FormActions` 这一层发出来（ADR-0054 §12）。
+// 理由都指向 ADR-0054：§2 是四条规则（顺序 / 颗数 / 危险 / 窄容器）、§9 是判据为什么只钉这一条、
+// §12 是发版后的迁移顺序。这是**棘轮**：迁一处删一行；某个包在眼前却一处都不再命中时，
+// 那条豁免当场报红（见 run() 里的 staleActionRows）。键同形：`<包名>:<相对模块根的文件路径>`。
+// 2026-10-17 实测（只读 pduiv2）：8 处 / 6 个文件 —— 全部收在这里，一条都不许写成"全部"。
+// 2026-10-17 清空：外壳 0.2.14（含 `FormActions`）发出后，那 8 处逐条迁完（ADR-0054 §12 的 runbook），
+// 按棘轮一行一行删到空。留着这张空表是这条判据的棘轮位：谁再借 `wb-formActions` 手摆操作区，
+// 直接报红（不再有豁免这一层）。
+const FORM_ACTIONS_EXEMPT = new Map([]);
 
 /** 裸控件出现的位置 —— 逐行看不了（一个元素会跨行），所以在全文里按标签找，再回推行号。 */
 function bareControlsIn(text) {
@@ -210,6 +231,48 @@ const SOURCE_COMPONENTS = fileURLToPath(new URL('../../../shared/src/components'
 const INSTALLED_BOARD = join('node_modules', '@dsh-workbench', 'core', 'dist', 'board.css');
 const INSTALLED_COMPONENTS = join('node_modules', '@dsh-workbench', 'shared', 'src', 'components');
 
+// ── 字号口径（S5，用户 2026-10-17 定的那条）：只报「刻度外手搓字面值」，**黄，不判红** ─────────
+//
+// 口径、刻度出处与"将来怎么变红"写在 `.scratch/font-scale/spec.md`（这份 note 的指路目标）。
+// 扫三个来源：外壳自己的 `src`、shared 的 `src`、本次发现的模块包；外壳两处与上面那份契约
+// （`SOURCE_BOARD` / `SOURCE_COMPONENTS`）走同一条路 —— 源码在隔壁时读源码，仓外的模块工作区
+// 读不到就少扫那一半（note 里只报实际扫到的）。测试文件不扫（用例里那些是断言字符串，不是界面字号）。
+//
+// 为什么落在这一条上：`check:style` 今天就有"通过时也打 note"的做法（豁免表那两行），
+// 这里只是又一条同类 note；**不新增判据、不改退出码、不加开关**。外壳 CSS 那边本来就有红判据
+// （arch-guard 的 D12：`font-size` 字面值必须写 `var(...)`），所以那半边的 0 命中是"红已经守住"
+// 的结果；这份黄清单补的是 D12 看不到的地方：`.tsx` 内联 `fontSize`、shared、以及模块包。
+const SOURCE_SHELL_SRC = fileURLToPath(new URL('../../../workbench/src', import.meta.url));
+const SOURCE_SHARED_SRC = fileURLToPath(new URL('../../../shared/src', import.meta.url));
+const SHELL_FONT_SCALE_FILES = [
+  fileURLToPath(new URL('../../../workbench/src/shared/styles/tokens/scale.css', import.meta.url)),
+  fileURLToPath(new URL('../../../workbench/src/shared/styles/tokens.css', import.meta.url)),
+];
+const FONT_DOC = '.scratch/font-scale/spec.md';
+
+/** 包名（读 package.json；读不到就用兜底名，别让一条 note 把判据带崩）。 */
+function packageNameOf(dir, fallback) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    return typeof manifest.name === 'string' ? manifest.name : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/** 字号口径要扫的根：外壳 + shared（源码在隔壁才有）+ 本次发现的模块包。 */
+function fontRootsIn(modules) {
+  const roots = [];
+  for (const [dir, fallback] of [
+    [SOURCE_SHELL_SRC, '@dsh-workbench/core'],
+    [SOURCE_SHARED_SRC, '@dsh-workbench/shared'],
+  ]) {
+    if (existsSync(dir)) roots.push({ label: packageNameOf(join(dir, '..'), fallback), dir });
+  }
+  for (const pkg of modules) roots.push({ label: pkg.manifest.name, dir: pkg.dir });
+  return roots;
+}
+
 function installedUnder(dir, tail) {
   let at = resolve(dir);
   for (;;) {
@@ -274,8 +337,10 @@ export async function run() {
   const anchors = [];
   const controls = [];
   const rows = [];
+  const actionAreas = [];
   // 这一轮"命中过"的 `包:文件`（含被豁免的）—— 豁免表里那些不再命中的行靠它发现（棘轮）。
   const formRowHits = new Set();
+  const actionAreaHits = new Set();
   const modules = discoverModulePackages({ root: process.cwd() });
   const contracts = new Map(modules.map((pkg) => [pkg.dir, contractOf(pkg.dir)]));
   for (const pkg of modules) {
@@ -345,6 +410,19 @@ export async function run() {
           );
         }
       }
+      const actionKey = `${pkg.manifest.name}:${relative(pkg.dir, file)}`;
+      const exemptActions = FORM_ACTIONS_EXEMPT.has(actionKey);
+      lines.forEach((line, index) => {
+        if (!ACTION_AREA_CLASS.test(line)) return;
+        actionAreaHits.add(actionKey);
+        if (exemptActions) return;
+        actionAreas.push(
+          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 手写了操作区（借了外壳的槽类 wb-formActions）—— ` +
+            `用 kit 的 FormActions（ADR-0054 §2：主操作在右、一个区一颗 primary、danger 紧挨它左侧且有二次确认、` +
+            '间距与窄容器换行都归它）：' +
+            `${line.trim().slice(0, 80)}`,
+        );
+      });
       if (contract === null) continue;
       lines.forEach((line, index) => {
         for (const match of line.matchAll(CLASS_TOKEN)) {
@@ -397,9 +475,17 @@ export async function run() {
       `${key} 还在 FORM_ROW_EXEMPT 里，但一处都不再命中 —— 按棘轮删掉这一行（原由：${reason}）`,
     );
   }
+  const staleActionRows = [];
+  for (const [key, reason] of FORM_ACTIONS_EXEMPT) {
+    const owner = key.slice(0, key.indexOf(':'));
+    if (!present.has(owner) || actionAreaHits.has(key)) continue;
+    staleActionRows.push(
+      `${key} 还在 FORM_ACTIONS_EXEMPT 里，但一处都不再命中 —— 按棘轮删掉这一行（原由：${reason}）`,
+    );
+  }
 
   if (bindings.length + problems.length + borrowed.length + anchors.length + controls.length
-    + rows.length + staleRows.length > 0) {
+    + rows.length + actionAreas.length + staleRows.length + staleActionRows.length > 0) {
     const notes = [];
     if (bindings.length > 0) {
       notes.push(
@@ -443,17 +529,42 @@ export async function run() {
           '换 `<FormRow label={…}>{控件}</FormRow>`，行距一起归它。窄口径与已知漏报见 style.mjs 里那两段注释）',
       );
     }
+    if (actionAreas.length > 0) {
+      notes.push(
+        `${actionAreas.length} 处是「手写了操作区（借了外壳的槽类 wb-formActions）」：（ADR-0054：` +
+          '操作区那一层归 `FormActions` —— 顺序（主操作在右、danger 紧挨它左侧）、一个区一颗 `primary`、' +
+          '间距、窄容器换行都由组件定；调用点只给"有哪些动作、哪个是主要、点了做什么"。' +
+          '`wb-formActions` 这个槽类只为操作区存在，出现它就是自己摆了一套：换 `<FormActions actions={…} />`。' +
+          '窄口径与已知漏报见 style.mjs 里那一段注释）',
+      );
+    }
     if (staleRows.length > 0) {
       notes.push(
         `${staleRows.length} 条 FORM_ROW_EXEMPT 已经不命中了：（棘轮：迁完一处删一行 —— ` +
           '一个包迁完 FormRow 之后，它那几行豁免要跟着删，别留着让表长起来）',
       );
     }
-    // 各类问题各自成串，按原来的输出顺序（绑定 → 规则 → 借用 → 裸 <a> → 裸控件 → 表单行 → 过期豁免）拼在一起。
+    if (staleActionRows.length > 0) {
+      notes.push(
+        `${staleActionRows.length} 条 FORM_ACTIONS_EXEMPT 已经不命中了：（棘轮：迁完一处删一行 —— ` +
+          '一个包迁完 FormActions 之后，它那几行豁免要跟着删，别留着让表长起来）',
+      );
+    }
+    // 各类问题各自成串，按原来的输出顺序（绑定 → 规则 → 借用 → 裸 <a> → 裸控件 → 表单行 → 操作区 → 过期豁免）拼在一起。
     return {
       status: 'fail',
       notes,
-      problems: [...bindings, ...problems, ...borrowed, ...anchors, ...controls, ...rows, ...staleRows],
+      problems: [
+        ...bindings,
+        ...problems,
+        ...borrowed,
+        ...anchors,
+        ...controls,
+        ...rows,
+        ...actionAreas,
+        ...staleRows,
+        ...staleActionRows,
+      ],
     };
   }
 
@@ -486,9 +597,23 @@ export async function run() {
     formRowHits.size === 0
       ? '没有手写的「标签+控件」行，也没有模块自己管的行距'
       : `表单「行」这一层还有 ${formRowHits.size} 个文件在 FORM_ROW_EXEMPT 里等外壳发版后迁（棘轮：迁一处删一行）`;
+  const actionNote =
+    actionAreaHits.size === 0
+      ? '没有手写的操作区'
+      : `操作区这一层还有 ${actionAreaHits.size} 个文件在 FORM_ACTIONS_EXEMPT 里等外壳发版后迁（棘轮：迁一处删一行）`;
+  // 黄的那一条：各类条数 + 涉及文件数 + 最多十来行明细 + 指路文档（口径见上面那一段注释）。
+  const fontScale = fontScaleOf(SHELL_FONT_SCALE_FILES);
+  const fontNotes = fontScaleNotes(
+    auditFontSizes({ roots: fontRootsIn(modules), scale: fontScale }),
+    fontScale,
+    { doc: FONT_DOC },
+  );
   return {
     status: 'pass',
-    notes: [`${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}；${exemptNote}`],
+    notes: [
+      `${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}；${exemptNote}；${actionNote}`,
+      ...fontNotes,
+    ],
     problems: [],
   };
 }

package/src/font-scale.mjs

@@ -0,0 +1,213 @@
+// 字号口径（S5，用户 2026-10-17 定的那条）：**不禁大字号，只禁"刻度外手搓"**。
+//
+// 口径原文：「某个卡片的重点数字大是合法的（例如套餐余额那个 28px），只禁刻度外手搓。
+// 所以：先把**刻度**从令牌定义里读出来（那是唯一真相），再列出不在刻度上、且不是引用令牌的字面值。」
+//
+// 这个模块只**读**、只**归类**、只**拼 note**：它不判红、不改退出码、没有开关、也不写文件。
+// 今天这份清单落在 `checks/style.mjs` 通过时的那几行 note 上（黄）；真做成红要等棘轮那一半
+// 想清楚（口径与将来的形态写在 `.scratch/font-scale/spec.md`）。
+//
+// 三类的口径（同名同义，全程只用这三个词）：
+//   a) 引用令牌 —— `var(--dsw-font-*)` / `var(--wb-font-*)`，合规，只报总数；
+//   b) 刻度外字面值 —— 数值不在刻度上，**这份就是要的清单**；
+//   c) 刻度上字面值 —— 数值在刻度上但没写成 `var(...)`：最容易收进令牌的一批，但**不是错**。
+//
+// 为什么刻度要"读"而不是写死：令牌定义是唯一真相。外壳侧现读 `tokens/scale.css` 与
+// `tokens.css`；dsh 侧在外壳仓里解析不到（见下面 DSH_ALIAS_FONT_SIZES 那段），那一半是照抄的常量。
+// 两边都不发明档位 —— dsh 没有的档写在外壳自己的 token 里才算数。
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/**
+ * dsh 别名刻度 —— `--dsw-font-*-font-size` 的**值**，7 档。
+ *
+ * 出处：装出来的 dsh 那份 `@deepseek-ai/dsh-client-ui-theme/lib/client.js:1425`
+ * （2026-10-17 实测，dsh 0.2.1；那一整行是 CSS 变量声明），逐条抄的值：
+ *   `--dsw-font-xxxs-11-font-size: 11px` · `--dsw-font-xxs-12-font-size: 12px` ·
+ *   `--dsw-font-xs-13-font-size: 13px` · `--dsw-font-s-14-font-size: 14px` ·
+ *   `--dsw-font-base-16-font-size: 16px` · `--dsw-font-l-20-font-size: 20px` ·
+ *   `--dsw-font-xl-24-font-size: 24px`
+ * 两个坑，抄的时候都按**值**收、不按名字：
+ *   · `--dsw-font-m-18` 的值其实是 **16px**（名字与值不一致），所以刻度里没有 18 这一档；
+ *   · markdown 那几个（h1 `calc(21px + delta)` / h2 19 / h3 18 / small 12 …）是**内容字号**，
+ *     跟着用户的 `--dsh-content-font-size` 走，不是面板排版的档，不收。
+ *
+ * 为什么是常量而不是现读：外壳仓里根本没有 dsh 的 theme 包（只有 `dsh-client-ui-primitives`），
+ * `require.resolve` 直接 MODULE_NOT_FOUND；`--dsw-*` 是 dsh 实例在**运行时**注入的，源码树里没有定义。
+ * 哪天真要它现读（在装齐 dsh 的环境里）：resolve 到 theme 之后解析同一批 `-font-size` 的值，
+ * 再把这份常量删掉 —— 别让它长成第二份真相。
+ */
+export const DSH_ALIAS_FONT_SIZES = [11, 12, 13, 14, 16, 20, 24];
+
+/** 外壳自己的字号令牌（`--wb-font-*: <n>px`）—— 刻度定义，不是手搓值。 */
+const SHELL_FONT_TOKEN = /--wb-font-[a-z0-9-]+\s*:\s*([0-9]+(?:\.[0-9]+)?)px/g;
+
+/** 从外壳的令牌文件里读出它自己的那几档（文件不在场就跳过：仓外的工作区读不到）。 */
+export function shellFontScaleIn(files) {
+  const sizes = new Set();
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    for (const hit of readFileSync(file, 'utf8').matchAll(SHELL_FONT_TOKEN)) {
+      sizes.add(Number(hit[1]));
+    }
+  }
+  return sizes;
+}
+
+/** 合起来的刻度：dsh 别名那 7 档 + 外壳自己 token 里的档（现读）。 */
+export function fontScaleOf(shellTokenFiles = []) {
+  return new Set([...DSH_ALIAS_FONT_SIZES, ...shellFontScaleIn(shellTokenFiles)]);
+}
+
+const CSS_FONT_SIZE = /(?:^|[;{\s])font-size\s*:\s*([^;{}]+)/g;
+const CSS_FONT_SHORTHAND = /(?:^|[;{\s])font\s*:\s*([^;{}]+)/g;
+const JS_FONT_SIZE = /\bfontSize\s*[:=]\s*\{?\s*(['"]?)([^,}'"\n]+)\1\s*\}?/g;
+const FONT_TOKEN_REF = /var\(\s*(--[a-z0-9-]*font[a-z0-9-]*)/g;
+// `--dsw-font-family` / `--dsw-font-mono` 也带 `font`，但它们是字族不是字号 ——
+// `font: 11px/18px var(--dsw-font-family)` 那行的字号是字面的 11px，不能算"引用令牌"。
+const FONT_FAMILY_TOKEN = /font-(?:family|mono)/;
+const NUMERIC_VALUE = /^([0-9]*\.?[0-9]+)(px|rem|em|%)?$/;
+
+/** 值里引用的**字号**令牌名（排掉字族/等宽那两族）。 */
+function sizeTokenRefs(value) {
+  const names = [];
+  for (const hit of value.matchAll(FONT_TOKEN_REF)) {
+    if (!FONT_FAMILY_TOKEN.test(hit[1])) names.push(hit[1]);
+  }
+  return names;
+}
+
+/**
+ * 把一个字号声明的值分成 ref / size / relative / keyword。
+ * `relative` 是 `em` / `%`（跟着父级走，判不了刻度外）、`keyword` 是 `inherit` / `unset` 这类。
+ * `rem` 按 1rem = 16px 折（本仓没有根字号覆盖；dsh 也没改 `html` 的 font-size）。
+ */
+export function classifyFontValue(value) {
+  const raw = String(value).trim();
+  const refs = sizeTokenRefs(raw);
+  if (refs.length > 0) return { kind: 'ref', refs };
+  const first = (raw.split(/\s+/)[0] ?? '').replace(/\/.*$/, '');
+  const hit = NUMERIC_VALUE.exec(first);
+  if (hit === null) return { kind: 'keyword', value: first };
+  const unit = hit[2] ?? 'px';
+  if (unit === 'em' || unit === '%') return { kind: 'relative', value: first };
+  const px = unit === 'rem' ? Number(hit[1]) * 16 : Number(hit[1]);
+  return { kind: 'size', px, value: first };
+}
+
+function isTestSource(file) {
+  return /(^|[\\/])__tests__[\\/]/.test(file) || /\.test\.[cm]?tsx?$/.test(file);
+}
+
+function walk(dir, acc = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    if (entry === 'node_modules' || entry === 'dist') continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, acc);
+    else if (/\.(css|ts|tsx)$/.test(full)) acc.push(full);
+  }
+  return acc;
+}
+
+/**
+ * 扫一组根下的字号声明并归类。`roots` 是 `{ label, dir }`：label 是报出来的包名。
+ * 测试文件不扫（用例里那几处是断言用的字符串，不是界面字号）；`node_modules` / `dist` 不扫。
+ * 返回里 `refFiles` / `litFiles` 是**涉及文件数**（同一个文件只算一次）。
+ */
+export function auditFontSizes({ roots, scale }) {
+  const refs = [];
+  const offScale = [];
+  const onScale = [];
+  const relativeSizes = [];
+  const refFiles = new Set();
+  const litFiles = new Set();
+  for (const root of roots) {
+    for (const file of walk(root.dir)) {
+      if (!/\.css$/.test(file) && isTestSource(file)) continue;
+      let text;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const rel = relative(root.dir, file);
+      text.split('\n').forEach((line, at) => {
+        const values = [];
+        for (const hit of line.matchAll(CSS_FONT_SIZE)) values.push({ value: hit[1], decl: hit[0] });
+        for (const hit of line.matchAll(CSS_FONT_SHORTHAND)) values.push({ value: hit[1], decl: hit[0] });
+        for (const hit of line.matchAll(JS_FONT_SIZE)) values.push({ value: hit[2], decl: hit[0] });
+        for (const one of values) {
+          const verdict = classifyFontValue(one.value);
+          if (verdict.kind === 'keyword') continue;
+          const where = {
+            pkg: root.label,
+            file: rel,
+            line: at + 1,
+            decl: one.decl.replace(/^[;{\s]+/, '').trim().slice(0, 56),
+          };
+          if (verdict.kind === 'ref') {
+            refFiles.add(`${root.label}:${rel}`);
+            refs.push(where);
+            continue;
+          }
+          litFiles.add(`${root.label}:${rel}`);
+          if (verdict.kind === 'relative') {
+            relativeSizes.push({ ...where, px: verdict.value });
+          } else if (scale.has(verdict.px)) {
+            onScale.push({ ...where, px: verdict.px });
+          } else {
+            offScale.push({ ...where, px: verdict.px });
+          }
+        }
+      });
+    }
+  }
+  return { refs, offScale, onScale, relative: relativeSizes, refFiles, litFiles };
+}
+
+const formatSize = (value) => String(value);
+
+/** 最多印十来行明细：刻度外的先印（那是这份清单要的东西），再印刻度上的。 */
+const DETAIL_LIMIT = 12;
+
+function detailOf(hit, verdict) {
+  const head = `${hit.pkg}: ${hit.file}:${hit.line} ${hit.decl}`;
+  return verdict === 'off'
+    ? `· ${head} —— ${formatSize(hit.px)} 不在刻度上（刻度外）`
+    : `· ${head} —— ${formatSize(hit.px)} 在刻度上，可收进令牌（但不是错）`;
+}
+
+/**
+ * 拼成 `checks/style.mjs` 通过时的那几行 note：第一行汇总（各类条数 + 涉及文件数 + 指路），
+ * 后面最多 `DETAIL_LIMIT` 行明细。零命中时只留一行"都是 0"。
+ */
+export function fontScaleNotes(report, scale, { doc = '.scratch/font-scale/spec.md' } = {}) {
+  const sizes = [...scale].sort((a, b) => a - b).map(formatSize).join(' / ');
+  const head =
+    `字号口径（黄，不判红）：刻度 ${sizes}（从 --dsw-font-* 与 --wb-font-* 的**定义**读出来，` +
+    `出处见 ${doc}）；引用令牌 ${report.refs.length} 处 / ${report.refFiles.size} 文件（合规，不列）；` +
+    `刻度外字面值 ${report.offScale.length} 处 / ${report.litFiles.size} 文件；` +
+    `刻度上字面值 ${report.onScale.length} 处；相对单位（em/%）判不了 ${report.relative.length} 处`;
+  const all = [
+    ...report.offScale.map((hit) => detailOf(hit, 'off')),
+    ...report.onScale.map((hit) => detailOf(hit, 'on')),
+  ];
+  if (all.length === 0) {
+    return [`${head} —— 面板的字号全走令牌，一处刻度外的字面值都没有`];
+  }
+  const notes = [head, ...all.slice(0, DETAIL_LIMIT)];
+  if (all.length > DETAIL_LIMIT) {
+    notes.push(
+      `…另有 ${all.length - DETAIL_LIMIT} 处（刻度外 ${report.offScale.length} / 刻度上 ${report.onScale.length}），` +
+        `完整清单见 ${doc}`,
+    );
+  }
+  return notes;
+}

package/template-diy/README.md.tpl

@@ -208,9 +208,9 @@ prefs: {
 }
 ```
 
-浏览器半侧：`useHostWrite({ channel: 'prefs', resource: 'your-module' })` + `Field` / `TextField`，外面套
-`SettingsSection`，保存用 `SaveBar`；存失败留在原地。（输入框内边距与"标签 + 提示"排布是外壳给的默认，
-不用为这个写 CSS。）语义：没写过 ≠ 选空、清空要把文件收掉、不认识的值报错并列出还认的候选。
+浏览器半侧：`useHostWrite({ channel: 'prefs', resource: 'your-module' })` + `FormRows` / `FormRow` /
+`TextField`，外面套 `SettingsSection`，保存用 `SaveBar`；存失败留在原地。（标签、行距与输入框内边距都是
+外壳给的默认，不用为这个写 CSS。）语义：没写过 ≠ 选空、清空要把文件收掉、不认识的值报错并列出还认的候选。
 
 ### 靠什么跑起来：`env`