@dsh-workbench/module-tools 0.3.2 → 0.3.4

package/src/design.mjs

@@ -7,11 +7,11 @@
 // README 是给人读的落点，不是给机器判的形状。
 //
 // 现在的分工：
-//   · `design.json` —— 机器可读的需求底稿（三张表 + 状态矩阵 + 数据源记录 + 验收清单）；
+//   · `design.json` —— 机器可读的需求底稿（三张表 + 状态矩阵 + 数据源记录 + 写通道记录 + 验收清单）；
 //   · `README.md`   —— 由它**生成**的那一段（夹在 `<!-- dsh-wb:design:start/end -->` 之间）；
 //   · `dsh-wb-module design check` —— 把**空着的格**列出来（红），并核对 README 没落后于 design.json。
 //
-// 这样"空格"第一次有了形状：填空 → 再往下做；写完 → `design accept` 逐条打勾。
+// 这样"空格"第一次有了形状：填空 → 再往下做；写完 → 自己在真卡片上逐条走通，`design accept` 打勾。
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -49,6 +49,7 @@ const ROWS = {
   acceptance: { fields: ['step'] },
 };
 const DATASOURCE_FIELDS = ['read', 'params', 'credentials', 'notLoggedIn', 'timeout'];
+const WRITE_FIELDS = ['command', 'params', 'credentials', 'preview', 'readback', 'undo', 'failure'];
 
 /** 一条卡背后可以有多条读（甚至跨站点）：规范形状 `reads: [ … ]`，一条一行；
  *  `datasource: { … }` 是只有一条读时的写法（老模块都长这样，继续认）。 */
@@ -59,6 +60,15 @@ function readsOf(design) {
   return one === undefined || one === null || typeof one !== 'object' ? [] : [one];
 }
 
+/** 写侧与读侧对称：一个动作可以打几条写（先建后发布那种），规范形状 `writes: [ … ]`；
+ *  `write: { … }` 是只有一条写时的写法。**没有写通道的模块不写就行** —— 这里不判"一条都没有"。 */
+function writesOf(design) {
+  const list = design?.writes;
+  if (Array.isArray(list) && list.length > 0) return list;
+  const one = design?.write;
+  return one === undefined || one === null || typeof one !== 'object' ? [] : [one];
+}
+
 /** 「他能自己配什么」有两种，分不清就会写成一个不落盘的选择还自称配置： */
 function persistenceLabel(value) {
   const raw = text(value);
@@ -80,6 +90,21 @@ function datasourceRowsOf(read) {
   ];
 }
 
+function writeRowsOf(write) {
+  return [
+    '| 项 | 值（照抄，别转述） |',
+    '|---|---|',
+    `| 哪条写（命令 / URL + 方法） | ${cell(write?.command)} |`,
+    `| 参数（必填 / 取值枚举 / 上限） | ${cell(write?.params)} |`,
+    `| 凭据从哪来 | ${cell(write?.credentials)} |`,
+    `| 有没有预览档（没有就写"没有，一次就是真的"） | ${cell(write?.preview)} |`,
+    `| 写完之后怎么回读确认（哪条读 / 出参哪个字段） | ${cell(write?.readback)} |`,
+    `| 配对的那个撤销 / 删除（没有就写"没有配对，一次就是真的"） | ${cell(write?.undo)} |`,
+    `| 失败长什么样（含"可能已经写了"） | ${cell(write?.failure)} |`,
+    `| 当初探明 / 预览用的那次调用（原文） | ${soft(write?.probeCommand)} |`,
+  ];
+}
+
 function text(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -121,6 +146,7 @@ function skeleton(manifest = {}) {
       timeout: '',
       probeCommand: '',
     },
+    writes: [],
     acceptance: [{ step: '' }],
   };
 }
@@ -178,6 +204,12 @@ export function emptyCells(design) {
     for (const field of DATASOURCE_FIELDS) need(cells, read?.[field], `${label}.${field}`);
   });
 
+  const writes = writesOf(design);
+  writes.forEach((write, index) => {
+    const label = writes.length === 1 ? 'write' : `writes[${index}]`;
+    for (const field of WRITE_FIELDS) need(cells, write?.[field], `${label}.${field}`);
+  });
+
   return cells;
 }
 
@@ -206,6 +238,7 @@ export function renderDesign(design) {
   const acceptance = asRows(design?.acceptance);
   const states = asRows(design?.states);
   const reads = readsOf(design);
+  const writes = writesOf(design);
 
   const stateRows = STATE_KEYS.map((key, index) => {
     const row = states.find((one) => text(one?.key) === key) ?? {};
@@ -277,7 +310,16 @@ export function renderDesign(design) {
     ...(reads.length <= 1
       ? [...datasourceRowsOf(reads[0]), '']
       : reads.flatMap((one, index) => [`#### 读 ${String(index + 1)}`, '', ...datasourceRowsOf(one), ''])),
-    '### 验收（做完逐条打勾：`dsh-wb-module design accept`）',
+    ...(writes.length === 0
+      ? []
+      : [
+          '### 写通道探明记录',
+          '',
+          ...(writes.length <= 1
+            ? [...writeRowsOf(writes[0]), '']
+            : writes.flatMap((one, index) => [`#### 写 ${String(index + 1)}`, '', ...writeRowsOf(one), ''])),
+        ]),
+    '### 验收（自己在真卡片上逐条走通后打勾：`dsh-wb-module design accept`）',
     '',
     ...acceptanceRows,
     '',
@@ -351,7 +393,7 @@ function checkDesign(root) {
     console.error('✖ README 里那一段落后于 design.json（或者没有标记）—— 跑 dsh-wb-module design render');
   }
   if (cells.length === 0 && fresh) {
-    console.log(`✔ 三张表填全了，README 也是最新的${accepted === acceptance.length ? '，验收也打完了' : `；验收还差 ${acceptance.length - accepted} 条（用户点头后跑 design accept）`}`);
+    console.log(`✔ 三张表填全了，README 也是最新的${accepted === acceptance.length ? '，验收也打完了' : `；验收还差 ${acceptance.length - accepted} 条（自己在真卡片上逐条走通后跑 design accept）`}`);
   }
   process.exit(cells.length === 0 && fresh ? 0 : 1);
 }
@@ -399,7 +441,7 @@ export async function design({ root, args = [] }) {
     design0.acceptedAt = new Date().toISOString();
     writeDesign(root, design0);
     applyToReadme(root, renderDesign(design0));
-    console.log(`✔ ${acceptance.length} 条验收全部打勾（只在他真的逐条看过之后再跑这条）`);
+    console.log(`✔ ${acceptance.length} 条验收全部打勾（只在真的在真卡片上逐条走通过之后再跑这条）`);
     return;
   }
 

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

@@ -0,0 +1,309 @@
+// 模块包的**语法卫生方言**（eslint 的模块版）。
+//
+// 为什么要有这一份：arch-guard 的 README 把自己的边界写得很清楚 ——「本工具不是 linter：
+// 单文件语法卫生（any、console、`!important`、颜色字面量、行数上限…）交给 eslint / oxlint /
+// stylelint / knip」。上一期（`./arch.mjs`）把**结构**那半边管住了，语法这半边一条都没有：
+// `as any` 把契约绕过去、`console.log` 留在产物里、渲染期写 ref、漏依赖、内联颜色 ——
+// 这些都不改变文件的形状，S16 / S23 那种判据永远看不见。
+//
+// 为什么方言住 module-tools、而不是让每个模块抄一份配置：与 `moduleArch()` 逐条同一个理由 ——
+// ① 抄一份就会各自漂成十几份"方言"；② 方言应当跟**工具链**同代（工坊三个包随外壳同代自愈，
+// 见 ADR-0056），规则变严时用户重跑一次门禁就跟着严，不用重抄。模板里那份 `eslint.config.mjs`
+// 只留一行工厂调用，要改规则就在**这一处**改。
+//
+// 为什么依赖装在 module-tools 一家（eslint / @eslint/js / typescript-eslint / 两个 react 插件）：
+// 模块与工坊根的清单**一个字都不用改** —— 这个文件 import 的是 module-tools 自己的依赖，
+// Node 从 module-tools 的位置解析；代价是工坊安装多约 17MB（第一次），换来的是用户拿到
+// `dsh-wb-module lint [--fix]` 就能跑，不必自己装一套 eslint 再跟版本漂移打架。
+//
+// 为什么是这几条规则（逐条的口径都在下面各块的注释里）：挑的是"语法级就能判、命中了基本
+// 就是真错"的那批 —— 不做类型感知规则（`no-floating-promises` 那种要建 program，模块 tsconfig
+// 形状各异、慢一个量级；外壳自己那份也把它排到 L2，见 `.scratch/eslint/spec.md`）。
+//
+// 指纹（**逐块比整份方言**，不只是比个名字）：本文件导出的 `DIALECT_BLOCKS` 是 `moduleLint()`
+// （不带 options）产出的**全部块**（`@eslint/js/recommended` · 三块 `typescript-eslint/*` ·
+// `dsh-wb/module-lint` 那四块），只排除两块 options 驱动的（`/overrides`、`/root`）。
+// 全局 ignores 那一块单列成 `DIALECT_IGNORES`，按**超集**比（模块可以多忽略，不许少忽略）。
+// 判据（`./checks/lint.mjs`）import 模块那份配置之后**逐块对**：名字 / `files` / `rules` 有一处
+// 不一致就红。这不是风格洁癖：没有它，模块可以把下限悄悄削掉（只留一个同名空块、筛掉基础层）
+// 而门禁照绿 —— 2026-10-19 verifier 先用 `export default [{ name: 'dsh-wb/module-lint',
+// rules: {} }]` 绕过去；随后又量到"只比 `dsh-wb/module-lint*` 那 4 块"还不够：**基础层**
+//（`@eslint/js/recommended` 与三块 `typescript-eslint/*`）与**全局 ignores 块**都不在比对面里。
+// 两者入口不同：前者**有名字**，要筛掉得显式点名（`filter((b) => b.name !== '@eslint/js/recommended')`）；
+// 后者是唯一**没有名字**的那块（全局 ignores 不能带 `name`），`filter((b) => b.name !== undefined)`
+// 筛掉的正是它。后果一样（下限被削），所以比对面扩到整份。
+//
+// **残余（这类校验的天花板，文档要如实写）**：模块若自己 import 本方言、再把这几块**照抄**成
+// 一份自己的配置（`moduleLint().map((b) => ({ ...b }))` 这类），判据分不出来 —— 它比的是形状，
+// 不是"这段代码从哪来"。这条的目标是**抬高门槛 + 让改动必须明着写**（改方言那几块会被点名；
+// 开口子只能走 `moduleLint({ rules, ignores })` 或自己追加一块），**不是**防住蓄意伪造。
+
+import js from '@eslint/js';
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import tseslint from 'typescript-eslint';
+
+/** 方言主块的名字。判据按它认"这一块属于方言"；改名字等于改协议。 */
+export const FINGERPRINT = 'dsh-wb/module-lint';
+
+// 只有 options 才会变的两块：它们不进"固定的方言"清单（判据不拿它们比 —— 开口子正是改它们）。
+const OPTION_BLOCK_NAMES = new Set([`${FINGERPRINT}/overrides`, `${FINGERPRINT}/root`]);
+
+// 全局 ignores 那一块（`{ ignores: [...] }`：没有 `name` / `files` / `rules`）。它**不按形状**比，
+// 单列成下面的 `DIALECT_IGNORES` 按**超集**比 —— 模块多忽略几条可以（那是开口子），少一条不行。
+// 导出它是为了让判据按**同一处**认出这一块，不在判据里另写一份"什么样的块算全局 ignores"。
+export function isGlobalIgnoresBlock(block) {
+  return (
+    block !== null &&
+    typeof block === 'object' &&
+    Array.isArray(block.ignores) &&
+    block.files === undefined &&
+    block.rules === undefined
+  );
+}
+
+/** 对象/数组递归重建、对象键排序：同一份形状在任何机器上 `JSON.stringify` 都是同一个串。 */
+function sortedDeep(value) {
+  if (Array.isArray(value)) return value.map(sortedDeep);
+  if (value === null || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, sortedDeep(value[key])]),
+  );
+}
+
+/**
+ * 一块方言的**规范形状**（判据逐块比的就是它）：名字 + `files`（没有就是 `null`）+ 键排序后的
+ * `rules`。只认这三样 —— `plugins` / `settings` / `languageOptions` 是"怎么跑起来"的细节，
+ * 掉了它们 ESLint 自己会报错，不必在这里比。
+ */
+export function dialectShapeOf(block) {
+  return {
+    name: block.name,
+    files: block.files ?? null,
+    rules: sortedDeep(block.rules ?? {}),
+  };
+}
+
+// 产物与声明不判：`dist/**` 是 build 出来的，`client.js` 是浏览器面的产物，`*.d.ts` 是声明
+// （`types/styles.d.ts` 那种）。
+//
+// `src/components/vendor/**` 是**唯一**允许 `!important` 的地方 —— 与 arch 方言的
+// `DESIGN.vendorDir` 同一处（`./arch.mjs`）：那是"覆盖第三方样式"的那一格，不是我们的代码。
+const DEFAULT_IGNORES = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/coverage/**',
+  '**/client.js',
+  '**/*.d.ts',
+  '**/components/vendor/**',
+];
+
+// `src/**` 里能一眼看出"手搓外观"的两串字面量。CSS 那一半归 arch-guard 的 D 族
+// （`*.module.css` 已经管着 D09 / D12 / D17），这一半管 **TS 里的内联样式** —— 两条合起来
+// "手搓外观"才闭合：写进 CSS 文件的和写进 style={{}} 的都跑不掉。
+const COLOR_LITERAL = {
+  selector:
+    'Literal[value=/^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/], Literal[value=/^(?:rgba?|hsla?)\\(/]',
+  message: '颜色字面量：引用 dsh 的 --dsw-* 令牌，别写死颜色',
+};
+const BANG_IMPORTANT = {
+  selector: 'Literal[value=/!important/]',
+  message: '!important：只许在 src/components/vendor/** 里覆盖第三方样式',
+};
+
+// `js.configs.recommended` 的 `no-undef` 在 `.mjs` / `.js` 上是开的（TS 那边 typescript-eslint
+// 把它关了，类型才是那里的真相）。脚本与配置文件要干"算路径、起进程"的活，Node 的全局量得列出来。
+//
+// `URLSearchParams` 那一行是**实测**撞出来的：模板自带的 `scripts/smoke.mjs` 用它拼取数地址，
+// 照抄仓库根那份 globals（没有它）会让模板开箱就两条 `no-undef`。
+const NODE_GLOBALS = {
+  Buffer: 'readonly',
+  URL: 'readonly',
+  URLSearchParams: 'readonly',
+  console: 'readonly',
+  fetch: 'readonly',
+  module: 'readonly',
+  process: 'readonly',
+  setTimeout: 'readonly',
+  clearTimeout: 'readonly',
+};
+
+// 非源码那一组（脚本 / 配置）。为什么不判 `console`：`scripts/smoke.mjs` 里那 6 处 `console.log`
+// 是它的**本职工作**（把一次冒烟的结果打给人看）—— 把 `no-console` 加到这一组，模板开箱就红，
+// 而那是误报。所以 `no-console` 只住在下面那个 `src/**` 块里。
+//
+// 这一组是 2026-10-19 拆 selfcheck 时真被两类**静默**错误咬过才补的（标识符少写引号、模板串
+// 写进了普通字符串），与仓库根那份同表；命中基本就是真错，不必跟噪声搏斗。
+const SCRIPT_RULES = {
+  'no-template-curly-in-string': 'error',
+  'require-atomic-updates': ['error', { allowProperties: true }],
+  'no-promise-executor-return': 'error',
+  'no-async-promise-executor': 'error',
+  'no-throw-literal': 'error',
+  'no-useless-catch': 'error',
+  'no-constant-binary-expression': 'error',
+  'no-unmodified-loop-condition': 'error',
+  'no-self-compare': 'error',
+  'no-sequences': 'error',
+  'no-var': 'error',
+  eqeqeq: ['error', 'smart'],
+};
+
+const SRC_FILES = ['src/**/*.{ts,tsx}'];
+const TSX_FILES = ['**/*.tsx'];
+const TS_FILES = ['**/*.{ts,tsx}'];
+// `*.config.{js,mjs,cjs}` 把模块根那几份配置（`eslint.config.mjs` / `arch.config.mjs` /
+// 以后可能有的 `*.config.mjs`）一起收进来；`scripts/**` 是模块自己的脚本。
+const SCRIPT_FILES = ['scripts/**/*.{js,mjs,cjs}', '*.config.{js,mjs,cjs}'];
+
+/**
+ * 模块包的 eslint 方言。模板里那两行就是默认值：
+ *
+ * ```js
+ * import { moduleLint } from '@dsh-workbench/module-tools/lint';
+ * export default moduleLint({ rootDir: import.meta.dirname });
+ * ```
+ *
+ * （为什么模板那份带 `rootDir`、不传行不行：见上面 `rootDir` 那一段 —— 单配置可省，多份并存必需。）
+ *
+ * 复杂模块要开口子时**从参数进**（每条口子都有名字，评审时看得见），别换掉方言：
+ *
+ * - `ignores`：追加忽略的 glob（默认那六条见 `DEFAULT_IGNORES`）
+ * - `rules`：追加 / 覆盖规则，**最后一块**，所以它对所有文件生效、且压过前面每一块
+ * - `rootDir`：这份配置所在的那个目录（模块自己那份配置里写 `import.meta.dirname`）。
+ *   为什么要有它：typescript-eslint 的 parser 在**没拿到** `tsconfigRootDir` 时会去猜 —— 猜法是看
+ *   "现在正在评估哪份 `eslint.config.*`"（V8 调用栈）。一个进程里只有一份配置时它猜得对（用户在
+ *   自己模块里 `eslint .` 就是这种情形，所以**不传也能跑**）；但只要同时有多份（本仓根上那份
+ *   + 模块自己那份，ESLint 会按目录就近选一份），它就猜不出来，**每个文件一条解析错**
+ *   （`No tsconfigRootDir was set, and multiple candidate TSConfigRootDirs are present`，
+ *   2026-10-19 整链实测）。模块这份配置声明了自己的根目录，这一条就没了。
+ *
+ * 要按目录细调（比如"只给 `src/legacy/**` 放行 `no-explicit-any`"），就在自己那份配置里
+ * 展开再追一块：
+ *
+ * ```js
+ * export default [
+ *   ...moduleLint({ rules: { 'no-console': 'off' } }),
+ *   { files: ['src/legacy/**'], rules: { '@typescript-eslint/no-explicit-any': 'off' } },
+ * ];
+ * ```
+ *
+ * @param {{ ignores?: string[], rules?: Record<string, unknown>, rootDir?: string }} [options]
+ * @returns {import('eslint').Linter.Config[]} 标准 flat config 数组（编辑器与 eslint 认的就是它）
+ */
+export function moduleLint(options = {}) {
+  const { ignores = [], rules = {}, rootDir } = options;
+  const overrideRules = Object.keys(rules).length === 0 ? [] : [{ name: 'dsh-wb/module-lint/overrides', rules }];
+  // 解析根目录那一块只在**明说** rootDir 时出现：不说就维持"typescript-eslint 自己猜"（单配置情形
+  // 猜得对，且不给用户的模块凭空塞一个他不知道的 parserOptions）。
+  const rootBlock =
+    rootDir === undefined
+      ? []
+      : [
+          {
+            name: 'dsh-wb/module-lint/root',
+            languageOptions: { parserOptions: { tsconfigRootDir: rootDir } },
+          },
+        ];
+
+  return [
+    // 第一条是**全局 ignores**（只有 `ignores` 一个键；加 `name` 会让 ESLint 不把它当全局忽略）。
+    { ignores: [...DEFAULT_IGNORES, ...ignores] },
+    ...rootBlock,
+    // 基础正确性：`no-unreachable` / `no-dupe-keys` / `no-undef`…
+    js.configs.recommended,
+    // `any` / `@ts-ignore` / 空的 interface 那一批。typescript-eslint 的 recommended 是**语法级**的
+    // （不建 program），所以它不属于"被推迟的类型感知规则"。
+    ...tseslint.configs.recommended,
+    {
+      name: FINGERPRINT,
+      files: SRC_FILES,
+      rules: {
+        // `catch {}` 是本仓零注释约定下的刻意写法（注释要用 `_` 前缀表达在场），不是漏写。
+        'no-empty': ['error', { allowEmptyCatch: true }],
+        'prefer-const': 'error',
+        // 上一期的非目标之一：`as any` 把契约绕过去 —— 复杂模块最先烂在这里。
+        '@typescript-eslint/no-explicit-any': 'error',
+        // 死代码。`^_` 放行：参数位保留（给契约留形状）时用下划线命名，是刻意的。
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          { args: 'after-used', argsIgnorePattern: '^_', caughtErrors: 'none', ignoreRestSiblings: true },
+        ],
+        // arch-guard 把 H01（console 残留）委派给了 eslint。放行 `warn` / `error`：真报错要能报，
+        // 调试残留（`log` / `info` / `debug`）不许留。
+        'no-console': ['error', { allow: ['warn', 'error'] }],
+        'no-debugger': 'error',
+        // 手搓外观的 TS 那一半（CSS 那一半归 arch-guard 的 D 族）。
+        'no-restricted-syntax': ['error', COLOR_LITERAL, BANG_IMPORTANT],
+      },
+    },
+    {
+      name: 'dsh-wb/module-lint/react',
+      files: TSX_FILES,
+      plugins: { react },
+      // `pragma: 'h'` 是模板的形状（`h()` 手写，不经 JSX 编译）：`jsx-uses-react` / `jsx-key`
+      // 这类规则照样咬得住手写的 `h()`。版本写死而不是 `detect`：`detect` 要读文件系统、
+      // 还会打一句警告，而模块拿到的 react 是外壳经模块表给的那一份（与外壳同代）。
+      settings: { react: { version: '19.3.0', pragma: 'h', fragment: 'Fragment' } },
+      rules: {
+        'react/jsx-key': 'error',
+        'react/jsx-no-duplicate-props': 'error',
+        'react/jsx-no-target-blank': 'error',
+        'react/no-children-prop': 'error',
+        'react/no-unknown-property': 'error',
+        'react/jsx-no-comment-textnodes': 'error',
+        'react/jsx-uses-vars': 'error',
+        'react/jsx-uses-react': 'error',
+      },
+    },
+    {
+      name: 'dsh-wb/module-lint/react-hooks',
+      files: TS_FILES,
+      plugins: { 'react-hooks': reactHooks },
+      rules: {
+        // 这一组是**这一期最值钱的一条**：本仓 2026-10-16 那次真实事故（渲染期写 `useRef.current`、
+        // 漏订阅、依赖写错）就是没有 lint 造成的。recommended 全量先按 **warn** 收进来（新规则
+        // 先看一段时间，不挡门禁），四条已知会真炸的提到 **error**。
+        ...Object.fromEntries(Object.keys(reactHooks.configs.recommended.rules).map((rule) => [rule, 'warn'])),
+        'react-hooks/rules-of-hooks': 'error',
+        'react-hooks/refs': 'error',
+        'react-hooks/exhaustive-deps': 'error',
+        'react-hooks/immutability': 'error',
+      },
+    },
+    {
+      name: 'dsh-wb/module-lint/scripts',
+      files: SCRIPT_FILES,
+      languageOptions: { globals: NODE_GLOBALS },
+      rules: SCRIPT_RULES,
+    },
+    ...overrideRules,
+  ];
+}
+
+/**
+ * `moduleLint()`（不带 options）产出的**整份方言**的规范形状 —— 判据拿它**逐块比**。
+ *
+ * 比对面（2026-10-19 扩过一次，是个行为变更）：**全部块**，只排除两块 options 驱动的
+ * （`/overrides`、`/root`）；全局 ignores 那一块也不在这里（它没有 `name` / `files` / `rules`，
+ * 形状比不了），单列成下面的 `DIALECT_IGNORES` 按**超集**比。也就是说现在这些块也必须在：
+ * `@eslint/js/recommended` · `typescript-eslint/base` · `typescript-eslint/eslint-recommended` ·
+ * `typescript-eslint/recommended`，以及 `dsh-wb/module-lint` 那四块 —— 一共 8 块。
+ *
+ * 为什么算一次就够：方言只有这一份，`moduleLint()` 不带 options 时产出是确定的（同一套常量、
+ * 同一个 `tseslint.configs.recommended`），所以"该长什么样"可以在导入时钉死，判据不必自己
+ * 再拼一遍。放在文件**最尾**：`moduleLint()` 读的是上面那批模块级常量，早算会撞 TDZ。
+ */
+export const DIALECT_BLOCKS = moduleLint()
+  .filter((block) => !isGlobalIgnoresBlock(block))
+  .filter((block) => !(typeof block?.name === 'string' && OPTION_BLOCK_NAMES.has(block.name)))
+  .map(dialectShapeOf);
+
+/**
+ * 全局 ignores 的默认那几条（"一条都不许少"的那半）。判据按**超集**比：模块可以再多忽略几条
+ * （那是 `moduleLint({ ignores })` 这个命名口子），但少一条就点名缺哪条。
+ */
+export const DIALECT_IGNORES = [...DEFAULT_IGNORES];
+

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 };
+}