@dsh-workbench/module-tools 0.3.3 → 0.3.5

package/src/checks/style.mjs

@@ -5,7 +5,7 @@
 // CSS Modules 的哈希类名靠"同一份文件、同一个导出"配对，调用点拿到 undefined 时真机渲染成
 // `class="undefined"` —— 元素整片没样式，而且控制台一声不响。
 //
-// ④ 表单的「行」归 `FormRow(s)`（[ADR-0052](../../../docs/adr/0052-the-form-row-is-one-component.md)）：
+// ④ 表单的「行」归 `FormRow(s)`（[ADR-0052](../../../../docs/adr/0052-the-form-row-is-one-component.md)）：
 //    控件有主（`TextField` / `SelectField` / `ChoiceGroup`）、面有主（`SettingsSection` / `SaveBar`），
 //    中间那层"标签 + 控件这一行怎么排"从前没有主 ⇒ 每人都自己写一遍：cmdb 一套 `.cmdbField`
 //    （`display:flex` + `.cmdbFieldLabel{width:72px}`）+ 三档 gap（`.cmdbForm` 8 / `.cmdbEnvs` 8 /
@@ -25,7 +25,38 @@ import { auditFontSizes, fontScaleNotes, fontScaleOf } from '../font-scale.mjs';
 
 // 外链一律走 kit 的 `Link`：它自带的样式（正文色 / hover 下划线 / 12px / 那个外链小箭头）是唯一一份。
 // 手写 `<a>` / `h('a', …)` 拿到的是浏览器默认样式，而且每个人写的都不一样（这正是"同一个东西样式不一样"的来源）。
-const BARE_ANCHOR = /(h\(\s*['"]a['"]|jsx\(\s*['"]a['"]|<a[\s>])/;
+//
+// **这条是全局匹配（`g`），按全文找再回推行号 —— 与 `bareControlsIn` / `bareFormsIn` 同形，别改回逐行。**
+// 为什么（2026-10-21 实测踩到，`.scratch/uiux-ownership/` 候选 1）：JSX 里 `<a` 习惯写在**行尾**
+// （属性在下一行），而 `<a(?=[\s>/])` 要的那个 `[\s>/]` 在**下一行**；逐行 `.test(line)` 里
+// 既没有那个字符、也没有换行本身 ⇒ **行尾写的 `<a` 一处都抓不到**。实测：pduiv2 5 个真模块包里
+// 有 **8 处**裸 `<a>`，**8 处全部**写在行尾，逐行那条的命中是 **0** —— 判据与它自己的文档
+//（`PANEL.md` §6「手写 `<a>` 会被「样式归属」判据直接判红」）打架了半年。全文匹配后正好 **8 命中**。
+// 「一个元素会跨行写属性」这条理由与 `bareFormsIn` 上一行那句是**同一条**，别只给表单那一条用。
+//
+// **哪种 `<a>` 不算 `Link`（所以不算"绕过"，收在 ANCHOR_EXEMPT 里）**：`Link` 的形态只有一种 ——
+// **正文里的文字链**（文字 + 行尾那颗 ↗ 小箭头，12px、hover 下划线）。三种是它表达不了的：
+//   ① **图标链**：`<a className="wb-iconButton">` 里包一枚图标（平台跳转 / 看日志那些）——
+//      `Link` 一定会多画一颗箭头，套进去就是两颗；
+//   ② **按钮皮的链**：`.anchorButton` 那种 28 高 / 描边的"看起来像按钮、实际是链接"——
+//      [ADR-0054](docs/adr/0054-the-action-area-is-one-component.md) §11 判过：**必须是链接的动作留真 `<a>`**，
+//      不许塞成 `onClick: () => window.open(…)` 的按钮（那一次会把中键新开 / 右键复制链接 / 悬停看 URL 一起丢掉）；
+//   ③ **整行链**：`.issueLink` 那种 `flex: 1` / `gap` / `color: inherit` 的**行的布局槽**——
+//      它是一条行的皮，不是正文里的字。
+// 这三类今天在真模块包里有 6 处（argocd 的 EnvRows 两处图标链、coding-analysis 的 AnalysisBody 一处图标链、
+// EnvSettings / AnalysisStates 两处按钮皮的链、coding-issues 的 IssueRow 一处整行链），逐文件收在
+// `ANCHOR_EXEMPT` 里；**该迁 `Link` 的是另外 2 处**（argocd 的 EnvRows / IdentityFields 那两条「去登录」文字链）。
+//
+// **两端边界**（与 `CLASS_TOKEN` / `FORM_SLOT_CLASS` 同一套口径，2026-10-21 复核者提醒后补的）：
+//   · **右**：`<a(?=[\s>/])` —— `<abbr>` 不算（`<a` 后面是 `b`），`<aside>` 也不算；
+//   · **左**：`(?<![\w$])` —— **`<` 前面不许是标识符字符**。挡的是 JS 里那个真实形态：
+//     `if (count<a ) …`（`count < a` 写掉了空格）今天会命中 `<a ` ⇒ 报一个跟界面无关的红。
+//     用 lookbehind（非消费）而不是 `(^|[^\w$])` 那种前缀，是因为这一条要按 `match.index`
+//     **回推行号**（`bareAnchorsIn`）：消费式前缀落在上一行的换行上时，行号会算到上一行去。
+// **`h('a'` / `jsx('a'` 那两支也吃同一个左边界**（整组一起套），所以 `myh('a', …)` 不算。
+// **仍然红的、如实记**：`<a` 写在**字符串**里（例如提示文案里那句 `<a href=…>`）—— 与 `BARE_FORM` 那条
+// 一样是**文本级**匹配，这是取舍不是漏报（要收紧先改口径，判据不自己长）。
+const BARE_ANCHOR = /(?<![\w$])(?:h\(\s*['"]a['"]|jsx\(\s*['"]a['"]|<a(?=[\s>/]))/g;
 
 // 交互控件同一条理由：按钮 / 单行输入 / 下拉在 kit 与 dsh 原语里都有对应形态
 // （`Button` · `TextField` · `SelectField` / `ChoiceGroup`），手写的那一份拿到的是浏览器默认样式 ——
@@ -76,7 +107,7 @@ 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)）：操作区那一层
+// 口径（[ADR-0054](../../../../docs/adr/0054-the-action-area-is-one-component.md)）：操作区那一层
 // （主操作在右 / 一颗 primary / 危险动作紧挨它左侧 / 间距 / 窄容器换行）从前没有主，只有一条
 // 借来的槽类 `.wb-formActions`（它只管右对齐 + gap）。于是顺序各摆各的 —— 2026-10-17 用户在
 // argocd 绑定身份那屏说「这两个按钮的位置换一下」就是现场（pduiv2 `b7977862`）。
@@ -92,6 +123,39 @@ const ZERO_LENGTH = /^(?:0|0px|0rem|0em|0%|none|auto)$/i;
 // 若自己写 `gap` / 上下 `margin`，还会被 F2 顺带抓到。
 const ACTION_AREA_CLASS = /wb-formActions/;
 
+// ── F4「手写的整张表单」：该走 `Form` ─────────────────────────────────────────────
+//
+// 口径照抄 [ADR-0054](../../../../docs/adr/0054-the-action-area-is-one-component.md) §5 与 §9：判据**只**回答
+// "这一层是不是绕过组件自己搭的"，**不钉"看起来对不对"**。表单的**面**（行怎么排、错误摆哪、什么时候
+// 校验、提交怎么被挡住、第一处错误怎么找、操作区怎么排）从前没有主 ⇒ 每个调用点自己拼。
+// 用户看到的就是按钮"一会在左一会在右"：`.wb-formActions` 的 `justify-content: flex-end` 只在它的盒子
+// 有富余宽度时才有效，放进横向 flex / 网格格子里（子项按内容宽收缩）就顶到左边 —— 同一个组件两个位置两种观感。
+//
+// 判据：模块源码（`.tsx` / `.ts`，测试文件除外）里出现下面任一个 ⇒ 红，改用 kit 的 `Form`：
+//   ① 裸 `<form>` 元素（`<form` …`>`，含 `h('form', …)` / `jsx('form', …)`）—— 表单这一层归 `Form`；
+//   ② 手写行的槽类 `wb-formRow` / `wb-formRows` / `wb-field`。
+// **为什么只钉这两条（宁可漏报）**：与 F3 同一套口径 —— 这三个槽类只为"行/字段"这一层存在
+//（`shared/src/components/FormRows.css` 的 `.wb-formRow(s)`、`Field.css` 的 `.wb-field`），
+// 出现它们 = 明确在绕过 `FormRow(s)` 手摆行，**零误报**；`<form>` 是浏览器元素，这一层的唯一出处是 kit 的 `Form`。
+// **窄在哪**：`wb-field` 后面跟着标识符或 `-` 的不算 —— `wb-fieldLabel` / `wb-fieldHint` 是那一层的
+// **兄弟**类（`Field` 自己渲染，借用它们不等于"手写了一行"），归属见 F1/F2，别在这里一并判红。
+// **已知漏报（如实记）**：模块自己用 div 拼一张既没有 `<form>`、也没借槽类的表单，这一版不判 ——
+// 判宽了就是"用户每次改界面都先撞门禁"（ADR-0054 §5 那条代价照旧）。这一条靠 KIT.md 与 `Form` 的
+// JSDoc 顶上（ADR-0067：用法住在声明里）。`Form` 这一层的决定、四条行为口径与**完整的漏报清单**
+// （含"借 `wb-formLabel` 自己拼行 F4 不判"那条）见
+// [ADR-0068](../../../../docs/adr/0068-the-form-is-one-component.md)。
+const BARE_FORM = /(?:h\(\s*['"]form['"]|jsx\(\s*['"]form['"]|<form(?=[\s>/]))/g;
+// 这三个槽类的名字：**左右两端都要有边界**（与 `CLASS_TOKEN` 同一套口径，别只写右边那一个）。
+// 只写右边（原来的 `wb-field(?![\w-])`）时，**粘在前缀上的根本不是槽类**却会被判红 ——
+// `data-wb-field="x"`（属性名；独立复核者 2026-10-21 报的那一处）· `xwb-field` · `my-wb-formRows`，全中。
+// 左边用 `(?<![-\w])`：`-` 与标识符字符都不许紧贴在 `wb-` 前面（`my-wb-field` 不算，`className="wb-field"` 算）。
+// **为什么用 lookbehind、不用 `CLASS_TOKEN` 那种消费式前缀 `(^|[^-\w])`**：这一条匹配出来就 `match[0]`，
+// 报错话里印的是 `${slot[0]}` —— 消费式前缀会把前缀一起印进那句人话；用 lookbehind 既印得准，
+// 也不用像 `CLASS_TOKEN` 那样回头按偏移找名字（少一处偏移算术就少一处错的可能）。
+// **今天 0 现实命中**（本仓 + pduiv2 五个模块包都 grep 过：`data-wb-*` 只有 `data-wb-dot` /
+// `data-wb-problem` / `data-wb-select-reveal` 这类，一个都不是槽类）—— 收的是**潜在**误报，不是现实伤。
+const FORM_SLOT_CLASS = /(?<![-\w])(?:wb-formRows?(?![\w-])|wb-field(?![\w-]))/;
+
 /** 类名里有没有 `field(s)` / `form(s)` 这个词（按 camelCase 切词，`platform` 不算）。 */
 function isFormContainer(token) {
   return token.split(/(?=[A-Z])/).some((word) => /^(?:fields?|forms?)$/i.test(word))
@@ -198,6 +262,63 @@ const FORM_ROW_EXEMPT = new Map([]);
 // 直接报红（不再有豁免这一层）。
 const FORM_ACTIONS_EXEMPT = new Map([]);
 
+// 历史豁免：**已知**的手写表单（裸 `<form>` / 借了 `wb-formRow(s)` / `wb-field` 槽类手摆行）。
+// 它跟上面三张又是**另一件事、另一个迁移时点**：等的是外壳把 `Form` 这一层发出来（含 `Form` 的那一版）。
+// 理由都指向 ADR-0054 §5（判据边界：只钉"有没有绕过组件"）与 §9（为什么只钉槽类、宁可漏报）。
+// 这是**棘轮**：迁一处删一行；某个包在眼前却一处都不再命中时，那条豁免当场报红
+//（见 run() 里的 staleFormRows）。键同形：`<包名>:<相对模块根的文件路径>`。
+// 2026-10-21 实测（只读扫眼前这几个真模块包）：**0 命中** ——
+// pduiv2 `dsh-workbench-{argocd,cmdb,coding-analysis,coding-issues,gitops}`（`<form` 一处没有，
+// 三个槽类一处没有）、本仓 `module-hello`（`platform-coding` 不是模块包，没有 `dsh.workbench`）。
+// 所以这里留成**空表**，不许为了"看起来有事做"把规则收宽或写成"全部"：
+// 它就是这条判据的棘轮位 —— 谁开始手写表单，直接报红（不再有豁免这一层）。
+const FORM_EXEMPT = new Map([]);
+
+// 历史豁免：**已知**的手写裸 `<a>`。它跟上面四张**又是另一件事、另一个迁移时点**：
+// 那一张等的是外壳把 `Link` 发出来（`Link` 从 0.2.x 起就有 ⇒ **这一张没有"等发版"这回事**，
+// 它等的是**逐处判断"这一条到底该不该用 Link"**）。
+// 为什么单开一张、不混进 `CONTROL_EXEMPT`：那一张等的是 kit 成员（`Button` / `TextField`…），
+// 这一张要记的是"三种 `Link` 表达不了的形态"（图标链 / 按钮皮的链 / 整行链）——
+// 口径写在 `BARE_ANCHOR` 那一段注释里，README 的 `style` 那一行也有一份。
+// 这是**棘轮**：迁一处删一行；某个包在眼前却一处都不再命中时，那条豁免当场报红
+//（见 run() 里的 staleAnchorRows）。键同形：`<包名>:<相对模块根的文件路径>`。
+//
+// 2026-10-21 实测（只读 pduiv2）：**8 处 / 6 个文件**，全部收在这里 ——
+// 这一天之前它们**一处都没被判据抓到**（`BARE_ANCHOR` 还是逐行匹配，而 8 处 `<a` 全写在行尾）。
+// 理由分两类，逐条写在下面：**「该迁 `Link`」2 处**（两条「去登录」文字链，是 `Link` 的形状）、
+// **「有意的不算」6 处**（图标链 / 按钮皮的链 / 整行链）。哪一处是迁、哪一处是留，别照抄文件名判断 ——
+// **一个文件里可以两种都有**（`module-argocd: src/views/EnvRows.tsx` 就是：两条图标链该留、一条文字链该迁）。
+const ANCHOR_EXEMPT = new Map([
+  [
+    '@pagoda-dsh-workbench/module-argocd:src/views/EnvRows.tsx',
+    '3 处：:212 / :298 是**图标链**（`<a className="wb-iconButton">` + 一枚 ↗，`Link` 会多画一颗箭头）⇒ 有意保留；' +
+      ':401 是 `.inlineLink` + 文案「去登录」+ ↗12 ⇒ **该迁 `Link`**（这一处是"迁一处删一行"里要删的那一格，不是这一行）',
+  ],
+  [
+    '@pagoda-dsh-workbench/module-argocd:src/views/IdentityFields.tsx',
+    '1 处：:50 是 `.loginLink` + 文案「去登录」+ ↗12 ⇒ **该迁 `Link`**（迁完把这一行删掉；迁的时候会**有意**变两处观感：' +
+      '字号 11 → 12（`Link` 是 `--dsw-font-xxs-12`）、多一条 hover 下划线）',
+  ],
+  [
+    '@pagoda-dsh-workbench/module-coding-analysis:src/views/AnalysisBody.tsx',
+    '1 处：:42 是**图标链**（`wb-iconButton` 槽 + 一枚 ↗ + `title` / `aria-label`）⇒ 有意保留',
+  ],
+  [
+    '@pagoda-dsh-workbench/module-coding-analysis:src/views/EnvSettings.tsx',
+    '1 处：:166 是**按钮皮的链**（`.anchorButton`：28 高 / 描边 / 12px）—— ADR-0054 §11 逐字判过' +
+      '「必须是链接的动作留真 `<a>`，不许塞成 `window.open` 的按钮」⇒ 有意保留',
+  ],
+  [
+    '@pagoda-dsh-workbench/module-coding-analysis:src/views/AnalysisStates.tsx',
+    '1 处：:122 同 `EnvSettings.tsx:166`（同一个 `.anchorButton` 皮、同一屏的兄弟）⇒ 有意保留',
+  ],
+  [
+    '@pagoda-dsh-workbench/module-coding-issues:src/components/IssueRow.tsx',
+    '1 处：:194 是**整行链**（`.issueLink`：`flex: 1` / `gap: 8` / `color: inherit`）—— 它是那条行的布局槽，' +
+      '不是正文里的文字链 ⇒ 有意保留',
+  ],
+]);
+
 /** 裸控件出现的位置 —— 逐行看不了（一个元素会跨行），所以在全文里按标签找，再回推行号。 */
 function bareControlsIn(text) {
   const hits = [];
@@ -214,6 +335,25 @@ function bareControlsIn(text) {
   return hits;
 }
 
+/** 裸 `<form>` 出现的位置 —— 一个元素会跨行写属性，所以按全文找、再回推行号。 */
+function bareFormsIn(text) {
+  return Array.from(text.matchAll(BARE_FORM), (match) => ({
+    line: text.slice(0, match.index).split('\n').length,
+  }));
+}
+
+/** 裸 `<a>` 出现的位置 —— 与 `bareControlsIn` / `bareFormsIn` 同一条理由：一个元素会跨行写属性
+ * （`<a` 常常就落在行尾），所以按**全文**找、再回推行号，不逐行看。
+ * 开头那一句 `lastIndex` 归零是**防呆**：`matchAll` 会照抄原正则的 `lastIndex`，
+ * 而这个正则是带 `g` 的共享常量 —— 谁哪天在别处对它 `.test(...)` 一次（旧版就是逐行 `.test`），
+ * 下一次 `matchAll` 就从那个位置接着找，**静默漏掉前半份命中**。实测过这个坑。 */
+function bareAnchorsIn(text) {
+  BARE_ANCHOR.lastIndex = 0;
+  return Array.from(text.matchAll(BARE_ANCHOR), (match) => ({
+    line: text.slice(0, match.index).split('\n').length,
+  }));
+}
+
 const CLASS_TOKEN = /(^|[^-\w])\.?(wb-[a-zA-Z0-9-]+)/g;
 // 契约 = 外壳**所有**声明了 `wb-*` 的样式表，不只是那份全局 `board.css`：
 // ADR-0029 要求组件的样式跟组件走，所以 `wb-card` / `wb-rows` / `wb-note` 这些已经搬进
@@ -340,9 +480,12 @@ export async function run() {
   const controls = [];
   const rows = [];
   const actionAreas = [];
+  const forms = [];
   // 这一轮"命中过"的 `包:文件`（含被豁免的）—— 豁免表里那些不再命中的行靠它发现（棘轮）。
   const formRowHits = new Set();
   const actionAreaHits = new Set();
+  const formHits = new Set();
+  const anchorHits = 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) {
@@ -383,13 +526,17 @@ export async function run() {
       if (isTestSource(file)) continue;
       if (!/\.tsx?$/.test(file)) continue;
       const exemptControls = CONTROL_EXEMPT.has(`${pkg.manifest.name}:${relative(pkg.dir, file)}`);
-      lines.forEach((line, index) => {
-        if (!BARE_ANCHOR.test(line)) return;
+      const anchorKey = `${pkg.manifest.name}:${relative(pkg.dir, file)}`;
+      const exemptAnchors = ANCHOR_EXEMPT.has(anchorKey);
+      for (const hit of bareAnchorsIn(text)) {
+        anchorHits.add(anchorKey);
+        if (exemptAnchors) continue;
         anchors.push(
-          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 手写了裸 <a> —— ` +
-            `外链一律用 kit 的 Link（新窗口、noopener、自带那个外链小箭头；样式只有这一份）：${line.trim().slice(0, 80)}`,
+          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${hit.line} 手写了裸 <a> —— ` +
+            `正文里的文字链一律用 kit 的 Link（新窗口、noopener、自带那个外链小箭头；样式只有这一份）：` +
+            `${(lines[hit.line - 1] ?? '').trim().slice(0, 80)}`,
         );
-      });
+      }
       if (!exemptControls) {
         for (const hit of bareControlsIn(text)) {
           controls.push(
@@ -425,6 +572,29 @@ export async function run() {
             `${line.trim().slice(0, 80)}`,
         );
       });
+      const formKey = `${pkg.manifest.name}:${relative(pkg.dir, file)}`;
+      const exemptForms = FORM_EXEMPT.has(formKey);
+      for (const hit of bareFormsIn(text)) {
+        formHits.add(formKey);
+        if (exemptForms) continue;
+        forms.push(
+          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${hit.line} 手写了裸 <form> —— ` +
+            '改用 kit 的 Form（fields 进、其余全归它：行的排布 / 校验时机 / 错误摆哪 / 提交怎么被挡住 / ' +
+            '第一处错误怎么找 / 操作区怎么排）：' +
+            `${(lines[hit.line - 1] ?? '').trim().slice(0, 80)}`,
+        );
+      }
+      lines.forEach((line, index) => {
+        const slot = line.match(FORM_SLOT_CLASS);
+        if (slot === null) return;
+        formHits.add(formKey);
+        if (exemptForms) return;
+        forms.push(
+          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 手写了表单的行（借了外壳的槽类 ${slot[0]}）—— ` +
+            '改用 kit 的 Form（面 → 行 → 控件：标签 + 控件这一行归 FormRow(s)，整张表单的面归 Form）：' +
+            `${line.trim().slice(0, 80)}`,
+        );
+      });
       if (contract === null) continue;
       lines.forEach((line, index) => {
         for (const match of line.matchAll(CLASS_TOKEN)) {
@@ -485,9 +655,26 @@ export async function run() {
       `${key} 还在 FORM_ACTIONS_EXEMPT 里，但一处都不再命中 —— 按棘轮删掉这一行（原由：${reason}）`,
     );
   }
+  const staleFormRows = [];
+  for (const [key, reason] of FORM_EXEMPT) {
+    const owner = key.slice(0, key.indexOf(':'));
+    if (!present.has(owner) || formHits.has(key)) continue;
+    staleFormRows.push(
+      `${key} 还在 FORM_EXEMPT 里，但一处都不再命中 —— 按棘轮删掉这一行（原由：${reason}）`,
+    );
+  }
+  const staleAnchorRows = [];
+  for (const [key, reason] of ANCHOR_EXEMPT) {
+    const owner = key.slice(0, key.indexOf(':'));
+    if (!present.has(owner) || anchorHits.has(key)) continue;
+    staleAnchorRows.push(
+      `${key} 还在 ANCHOR_EXEMPT 里，但一处都不再命中 —— 按棘轮删掉这一行（原由：${reason}）`,
+    );
+  }
 
   if (bindings.length + problems.length + borrowed.length + anchors.length + controls.length
-    + rows.length + actionAreas.length + staleRows.length + staleActionRows.length > 0) {
+    + rows.length + actionAreas.length + forms.length + staleRows.length + staleActionRows.length
+    + staleFormRows.length + staleAnchorRows.length > 0) {
     const notes = [];
     if (bindings.length > 0) {
       notes.push(
@@ -511,8 +698,10 @@ export async function run() {
     }
     if (anchors.length > 0) {
       notes.push(
-        `${anchors.length} 处是「手写了裸 <a>」：（外链用 kit 的 Link —— 样式只有一份，改一处全局一致；` +
-          '裸 <a> 拿到的是浏览器默认样式，看着和卡片其它地方不是一套）',
+        `${anchors.length} 处是「手写了裸 <a>」：（**正文里的文字链**用 kit 的 Link —— 样式只有一份，` +
+          '改一处全局一致；裸 <a> 拿到的是浏览器默认样式，看着和卡片其它地方不是一套。' +
+          '三种不算"绕过"的形态 —— 图标链 / 按钮皮的链 / 整行链 —— 逐文件收在 `ANCHOR_EXEMPT` 里，' +
+          '口径见 style.mjs 里 `BARE_ANCHOR` 那一段注释与 README 的 `style` 那一行）',
       );
     }
     if (controls.length > 0) {
@@ -540,6 +729,16 @@ export async function run() {
           '窄口径与已知漏报见 style.mjs 里那一段注释）',
       );
     }
+    if (forms.length > 0) {
+      notes.push(
+        `${forms.length} 处是「手写了整张表单（裸 <form> 元素，或借了外壳的槽类 wb-formRow / wb-formRows / wb-field）」：（` +
+          '表单那一层归 `Form` —— fields 进、其余全归它：行的排布、校验的时机（还没提交过时一格错都不显示）、' +
+          '错误摆哪、提交怎么被挡住、第一处错误怎么带进视口、操作区怎么排都由组件定，调用点只给数据与语义。' +
+          '`wb-formRow` / `wb-formRows` / `wb-field` 这三个槽类只为"行 / 字段"这一层存在，出现它们就是自己摆了一套：' +
+          '改用 kit 的 `Form`（`<Form fields={…} onSubmit={…} submit={…} />`）。' +
+          '窄口径与已知漏报见 style.mjs 里那一段注释）',
+      );
+    }
     if (staleRows.length > 0) {
       notes.push(
         `${staleRows.length} 条 FORM_ROW_EXEMPT 已经不命中了：（棘轮：迁完一处删一行 —— ` +
@@ -552,7 +751,19 @@ export async function run() {
           '一个包迁完 FormActions 之后，它那几行豁免要跟着删，别留着让表长起来）',
       );
     }
-    // 各类问题各自成串，按原来的输出顺序（绑定 → 规则 → 借用 → 裸 <a> → 裸控件 → 表单行 → 操作区 → 过期豁免）拼在一起。
+    if (staleFormRows.length > 0) {
+      notes.push(
+        `${staleFormRows.length} 条 FORM_EXEMPT 已经不命中了：（棘轮：迁完一处删一行 —— ` +
+          '一个包迁完 Form 之后，它那几行豁免要跟着删，别留着让表长起来）',
+      );
+    }
+    if (staleAnchorRows.length > 0) {
+      notes.push(
+        `${staleAnchorRows.length} 条 ANCHOR_EXEMPT 已经不命中了：（棘轮：迁完一处删一行 —— ` +
+          '一个文件里的裸 <a> 都迁成 Link（或那个文件没了）之后，它那一行豁免要跟着删，别留着让表长起来）',
+      );
+    }
+    // 各类问题各自成串，按原来的输出顺序（绑定 → 规则 → 借用 → 裸 <a> → 裸控件 → 表单行 → 操作区 → 整张表单 → 过期豁免）拼在一起。
     return {
       status: 'fail',
       notes,
@@ -564,8 +775,11 @@ export async function run() {
         ...controls,
         ...rows,
         ...actionAreas,
+        ...forms,
         ...staleRows,
         ...staleActionRows,
+        ...staleFormRows,
+        ...staleAnchorRows,
       ],
     };
   }
@@ -603,6 +817,10 @@ export async function run() {
     actionAreaHits.size === 0
       ? '没有手写的操作区'
       : `操作区这一层还有 ${actionAreaHits.size} 个文件在 FORM_ACTIONS_EXEMPT 里等外壳发版后迁（棘轮：迁一处删一行）`;
+  const formNote =
+    formHits.size === 0
+      ? '没有手写的整张表单（没有裸 <form>，也没有借表单槽类手摆行）'
+      : `表单这一层还有 ${formHits.size} 个文件在 FORM_EXEMPT 里等外壳发版后迁（棘轮：迁一处删一行）`;
   // 黄的那一条：各类条数 + 涉及文件数 + 最多十来行明细 + 指路文档（口径见上面那一段注释）。
   const fontScale = fontScaleOf(SHELL_FONT_SCALE_FILES);
   const fontNotes = fontScaleNotes(
@@ -613,7 +831,7 @@ export async function run() {
   return {
     status: 'pass',
     notes: [
-      `${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}；${exemptNote}；${actionNote}`,
+      `${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}；${exemptNote}；${actionNote}；${formNote}`,
       ...fontNotes,
     ],
     problems: [],

package/src/declared-tools.mjs

@@ -47,7 +47,7 @@ export function declaredToolsWithoutKey(raw) {
     .map((tool) => JSON.stringify(tool?.name));
 }
 
-/** 生成物的正文。**不给注释**：它落在模块的 `src/**`（零注释那一条管到这里），改它无效、过期会红。 */
+/** 生成物的正文。**不给注释**：它落在模块的 `src/**`（那里只许贴导出的 JSDoc，生成这份一行都不加），改它无效、过期会红。 */
 export function renderDeclaredTools(raw) {
   const rows = toolsOf(raw).map(
     (tool) =>

package/src/design.mjs

@@ -49,7 +49,7 @@ const ROWS = {
   acceptance: { fields: ['step'] },
 };
 const DATASOURCE_FIELDS = ['read', 'params', 'credentials', 'notLoggedIn', 'timeout'];
-const WRITE_FIELDS = ['command', 'params', 'credentials', 'preview', 'readback', 'failure'];
+const WRITE_FIELDS = ['command', 'params', 'credentials', 'preview', 'readback', 'undo', 'failure'];
 
 /** 一条卡背后可以有多条读（甚至跨站点）：规范形状 `reads: [ … ]`，一条一行；
  *  `datasource: { … }` 是只有一条读时的写法（老模块都长这样，继续认）。 */
@@ -99,6 +99,7 @@ function writeRowsOf(write) {
     `| 凭据从哪来 | ${cell(write?.credentials)} |`,
     `| 有没有预览档（没有就写"没有，一次就是真的"） | ${cell(write?.preview)} |`,
     `| 写完之后怎么回读确认（哪条读 / 出参哪个字段） | ${cell(write?.readback)} |`,
+    `| 配对的那个撤销 / 删除（没有就写"没有配对，一次就是真的"） | ${cell(write?.undo)} |`,
     `| 失败长什么样（含"可能已经写了"） | ${cell(write?.failure)} |`,
     `| 当初探明 / 预览用的那次调用（原文） | ${soft(write?.probeCommand)} |`,
   ];

package/src/discover.mjs

@@ -29,7 +29,15 @@ export function discoverPackages({ root = process.cwd() } = {}) {
   const packagesDir = join(workspace, 'packages');
   if (existsSync(packagesDir)) {
     for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {
-      if (entry.isDirectory()) dirs.push(join(packagesDir, entry.name));
+      // 点开头的目录一律不认：那是**自检的临时探针**（mkdtemp 造、跑完删；名字前那一点就是为了
+      // 不跟真包混）。不排除它们有个很坑的后果 —— 别的链/别的进程正在写一个探针时，这条链会把
+      // 它当成真模块包算进契约 / 卡片 / kit 那几条，于是红得跟你改的东西毫无关系：
+      //   2026-10-19 实测：一条链留下的 `.writes-*` 让另一条链的 lint 阶段
+      //   ERR_MODULE_NOT_FOUND（探针里的 eslint.config.mjs 解析不到 module-tools）；
+      //   另一条链正在写的 `.init-*` 让四条判据集体红（"它们会被当成真的模块包参与后面的每一条判据"）。
+      // 残留探针本身仍由自检那条「探针清理干净」点名叫出来 —— 这里只是**不让它参与判据**。
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+      dirs.push(join(packagesDir, entry.name));
     }
   }
   dirs.push(root, workspace);

package/src/init.mjs

@@ -16,6 +16,34 @@ const UNIT_ID = /^[a-z][a-z0-9-]*$/;
 // 为什么两个 token 共用一个值：`check:kit` 的口径是 peer 下限不许低于 devDependency 下限。
 const FALLBACK_RANGE = '^0.1.0';
 
+// 模板默认带的那份 dsh 原语（`devDependencies` 精确版 + `dsh.client.external` 一行）。
+//
+// 版本取自**装机外壳 manifest 的 `devDependencies`** —— 那是外壳编译时对账过的那版
+// （`packages/workbench/package.json` 的 `@deepseek-ai/dsh-client-ui-primitives`），
+// 不是外壳自己的版本号，两者不是一个号（外壳 0.3.x / 原语 0.2.1-rc.x）。
+// 为什么用精确版：类型面要对齐对账过的那一版；`^` 会把"没验过的下一版"放进来。
+// 读不到时兜底 + 说一句人话（与 FALLBACK_RANGE 同一处理）：静默留空会让生成的
+// package.json 声明一个谁也不认的版本。见 `.scratch/dsh-primitives-face/spec.md` §3.1。
+const FALLBACK_DSH_UI = '0.2.1-rc.2';
+const DSH_UI = '@deepseek-ai/dsh-client-ui-primitives';
+
+const dshUiVersion = (root) => {
+  try {
+    const pinned = JSON.parse(
+      readFileSync(join(root, 'node_modules/@dsh-workbench/core/package.json'), 'utf8'),
+    ).devDependencies?.[DSH_UI];
+    if (typeof pinned === 'string' && pinned !== '') {
+      return { version: pinned, source: '外壳 manifest 里钉的（对账过的那版）' };
+    }
+  } catch {
+    // 读不到就走下面的兜底
+  }
+  console.error(
+    `读不到外壳 manifest 里钉的 ${DSH_UI}：模板保持 ${FALLBACK_DSH_UI}（与外壳对账过的那版）；在装好依赖的工程里 init 就能盖上当下那版`,
+  );
+  return { version: FALLBACK_DSH_UI, source: '兜底常量（没读到外壳 manifest）' };
+};
+
 const versionIn = (file) => {
   try {
     const version = JSON.parse(readFileSync(file, 'utf8')).version;
@@ -59,11 +87,13 @@ export async function init({ root, args = [] }) {
     console.error(`${target} 已经存在且不是空目录，不覆盖`);
     process.exit(2);
   }
+  const dshUi = dshUiVersion(root);
   const tokens = {
     __UNIT__: unit,
     __NAME__: `@dsh-workbench/module-${unit}`,
     __DESC__: description,
     __SHELL_RANGE__: shellRange(root),
+    __DSH_UI_VERSION__: dshUi.version,
   };
   // 按**已知 token 名**逐个盖章，而不是按 `__[A-Z]+__` 的形状：名字里带下划线的 token
   // （`__SHELL_RANGE__`）也要认；同时 DIY 模板 README 里真写着的 `workbench___UNIT___rebuild`
@@ -98,4 +128,7 @@ export async function init({ root, args = [] }) {
   const tables = existsSync(join(target, DESIGN_FILE)) ? `${DESIGN_FILE} 里那份三张表` : '还没有三张表（dsh-wb-module design init 生成）';
   console.log(`${target} 建好了：${unit} 模块骨架（模板 ${which}；build / check / design / selfcheck 已接工具）`);
   console.log(`  需求底稿在 ${tables}；空格用 dsh-wb-module design check 查，README 由它生成`);
+  console.log(`  模板默认带了 ${DSH_UI}@${dshUi.version}（${dshUi.source}）—— 这是 dsh 原语的类型面 + external 声明两处；`);
+  console.log('  装完先在这个 workspace 里跑一次 pnpm install，pnpm typecheck 才认得到它（骨架的判据不依赖它）。');
+  console.log('  确实用不到就连 devDependencies 与 dsh.client.external 两处一起删，判据不拦。');
 }

package/src/lint.mjs

@@ -221,7 +221,7 @@ export function moduleLint(options = {}) {
       name: FINGERPRINT,
       files: SRC_FILES,
       rules: {
-        // `catch {}` 是本仓零注释约定下的刻意写法（注释要用 `_` 前缀表达在场），不是漏写。
+        // `catch {}` 是"实现里不留注释"这条约定下的刻意写法（要表达在场就 `_` 前缀命名），不是漏写。
         'no-empty': ['error', { allowEmptyCatch: true }],
         'prefer-const': 'error',
         // 上一期的非目标之一：`as any` 把契约绕过去 —— 复杂模块最先烂在这里。

package/src/primitives-surface.mjs

@@ -0,0 +1,120 @@
+// dsh 原语本包的**可见面**：从装机那份类型面（`lib/types/**/*.d.ts`）取出导出名，按名字形状分桶。
+//
+// 为什么读类型面而不是源码：这个包发布出去的 `files` 只有
+// `lib/index.js` / `lib/**/*.css` / `lib/types/**/*.d.ts` —— **源码树不随包发布**
+// （`package.json` 的 `exports['./src/*']` 在装机包里是死条目），类型面是唯一机器可读的清单。
+//
+// 为什么不上 TypeScript API：module-tools 自己没有 `typescript` 依赖（只有 `typescript-eslint`
+// 的 peer），而这份 barrel 是 tsc 生成的、形状稳定：`export { A, B } from './X.tsx'` +
+// `export type { … }`（滤掉）+ 少量 `export declare const X` + 一条 `export *`（要跟着走）。
+// 代价是"上游换了 emit 形状没人知道"—— 由 selfcheck 那条"清单非空 / 含 Button / `Icon*Regular` ≥ 90"
+// 兜住（`.scratch/dsh-primitives-face/spec.md` §3.4 / §8.1）。
+//
+// 分桶**只按名字形状**，不判用途：`Icon*` → 图标；`^use[A-Z]` → hooks；首字母大写 → 组件；
+// 其余（常量、纯函数）→ 工具。"这件是不是该用、该怎么用"是判断，留给 agent / 人（TOOLING.md 那条口径）。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+export const PRIMITIVES_SPECIFIER = '@deepseek-ai/dsh-client-ui-primitives';
+
+/** 从 `from`（一个包的目录）解析这个原语包；解析不到返回 undefined。 */
+export function installedPrimitives(from) {
+  try {
+    const require = createRequire(join(from, 'package.json'));
+    const manifest = require.resolve(`${PRIMITIVES_SPECIFIER}/package.json`);
+    const parsed = JSON.parse(readFileSync(manifest, 'utf8'));
+    const version = typeof parsed.version === 'string' ? parsed.version : undefined;
+    // 打印/落点用它**从 node_modules 看**的那条路径（pnpm 把真身放在 `.pnpm/` 哈希目录里，
+    // `require.resolve` 给的是 realpath）—— agent 照着能直接打开，也短得多。
+    const viaNodeModules = join(from, 'node_modules', ...PRIMITIVES_SPECIFIER.split('/'));
+    const dir = existsSync(join(viaNodeModules, 'package.json')) ? viaNodeModules : dirname(manifest);
+    return { manifest, dir, version };
+  } catch {
+    return undefined;
+  }
+}
+
+/** 外壳 manifest 里钉的那份原语版本（`devDependencies` 那一格）—— 模板盖章与漂移 note 都用它。 */
+export function pinnedPrimitivesVersion(manifestPath) {
+  try {
+    const pinned = JSON.parse(readFileSync(manifestPath, 'utf8')).devDependencies?.[PRIMITIVES_SPECIFIER];
+    return typeof pinned === 'string' && pinned !== '' ? pinned : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `export … from '…'` 一条条看：`export type` 滤掉、`export *` 跟着走、其余按名字拆。 */
+const STATEMENT = /export\s+(type\s+)?(\*|\{[^}]*\})\s*from\s*'([^']+)'/g;
+const DECLARED = /^export declare (?:const|function|class)\s+([A-Za-z_$][\w$]*)/gm;
+const MAX_STAR_DEPTH = 3;
+
+/** 说明符落到同目录的 `.d.ts`：`./icons/index.tsx` → `<types>/icons/index.d.ts`。 */
+function dtsTargetOf(fromFile, specifier) {
+  const base = join(dirname(fromFile), specifier);
+  const stripped = base.replace(/\.(tsx?|jsx?|mjs|cjs)$/, '');
+  const candidates = [`${stripped}.d.ts`, join(stripped, 'index.d.ts'), `${base}.d.ts`];
+  return candidates.find((one) => existsSync(one));
+}
+
+function namesOf(statement) {
+  return statement
+    .replace(/^\{/, '')
+    .replace(/\}$/, '')
+    .split(',')
+    .map((raw) => raw.trim().split(/\s+as\s+/).pop().trim())
+    .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+}
+
+function collect(file, origin, acc, depth) {
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch {
+    return;
+  }
+  for (const match of text.matchAll(DECLARED)) acc.set(match[1], { origin, file });
+  for (const match of text.matchAll(STATEMENT)) {
+    if (match[1] !== undefined) continue;
+    if (match[2] === '*') {
+      if (depth >= MAX_STAR_DEPTH) continue;
+      const target = dtsTargetOf(file, match[3]);
+      if (target !== undefined) collect(target, origin, acc, depth + 1);
+      continue;
+    }
+    // 名字**声明**在哪份 `.d.ts`：`export { Button } from './Button.tsx'` 的答案就是
+    // `lib/types/Button.d.ts` —— 这条信息就是"agent 想用哪个直接去看"的落点，别丢。
+    const declaredIn = dtsTargetOf(file, match[3]) ?? file;
+    for (const name of namesOf(match[2])) acc.set(name, { origin, file: declaredIn });
+  }
+}
+
+/**
+ * 装机那份类型面的导出，按名字形状分成四桶。
+ * `typesDir` = 原语包的 `lib/types`；读不到入口时抛（调用方给人话，不给空表）。
+ * `files` = 名字 → 声明它的那份 `.d.ts` 的绝对路径（188 枚图标同指 `icons/index.d.ts`）。
+ */
+export function surfaceOf(typesDir) {
+  const entry = join(typesDir, 'index.d.ts');
+  if (!existsSync(entry)) throw new Error(`类型面不在：${entry}`);
+  const found = new Map();
+  collect(entry, 'root', found, 0);
+  const iconsEntry = join(typesDir, 'icons', 'index.d.ts');
+  if (existsSync(iconsEntry)) collect(iconsEntry, 'icons', found, 0);
+
+  const buckets = { components: [], icons: [], hooks: [], lib: [] };
+  const files = {};
+  for (const [name, { origin, file }] of found) {
+    files[name] = file;
+    if (origin === 'icons' && !name.startsWith('Icon')) buckets.lib.push(name);
+    else if (name.startsWith('Icon')) buckets.icons.push(name);
+    else if (/^use[A-Z]/.test(name)) buckets.hooks.push(name);
+    else if (/^[A-Z][A-Z0-9_]*$/.test(name)) buckets.lib.push(name);
+    else if (/^[A-Z]/.test(name)) buckets.components.push(name);
+    else buckets.lib.push(name);
+  }
+  for (const key of Object.keys(buckets)) buckets[key].sort();
+  return { ...buckets, total: found.size, files };
+}