@dsh-workbench/module-tools 0.1.17 → 0.2.0

package/bin/dsh-wb-module.mjs

@@ -5,14 +5,15 @@ import { check } from '../src/check.mjs';
 import { design } from '../src/design.mjs';
 import { init } from '../src/init.mjs';
 import { publish } from '../src/publish.mjs';
+import { sync } from '../src/sync.mjs';
 
 const [command, ...rest] = process.argv.slice(2);
 const cwd = process.env.DSH_WB_MODULE_CWD ?? process.cwd();
 
-const commands = { build, check, init, design, publish };
+const commands = { build, check, init, design, publish, sync };
 
 if (!command || !commands[command]) {
-  console.error('用法：dsh-wb-module <build|check|init|design|publish> [--cwd <目录>]\n      dsh-wb-module check [--only contracts|bundles|source|primitives|kit|cards|standalone|markers|style|alias]\n      dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]\n      dsh-wb-module design <init|check|render|accept>   # 三张表：填、查空格、生成 README、验收打勾\n      dsh-wb-module publish                              # 发货前的清单：门禁 + npm pack 清单 + files 漏项（只 dry run）');
+  console.error('用法：dsh-wb-module <build|check|init|design|publish|sync> [--cwd <目录>]\n      dsh-wb-module check [--only contracts|bundles|source|primitives|kit|cards|standalone|markers|style|alias]\n      dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]\n      dsh-wb-module design <init|check|render|accept>   # 三张表：填、查空格、生成 README、验收打勾\n      dsh-wb-module sync                                 # 按清单生成 src/declared-tools.ts（工具名只有清单一处写者）\n      dsh-wb-module publish                              # 发货前的清单：门禁 + npm pack 清单 + files 漏项（只 dry run）');
   process.exit(2);
 }
 

package/package.json

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

package/src/checks/cards.mjs

@@ -218,11 +218,50 @@ 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(
+          `${name}: 清单写的是 "card": null，产物却登记了一张卡片 —— 两处说法不一致：` +
+            '要么把清单补成一张卡（titleKey + order），要么把这张卡从产物里去掉',
+        );
+        continue;
+      }
+      rows.push(`${name}: 清单写的是 "card": null —— 这个模块没有卡片，产物里也确实没登记（跳过渲染判定）`);
+      continue;
+    }
     if (typeof card !== 'function') {
-      problems.push(`${name}: apply 之后没登记卡片（registerUnit 没拿到 card）`);
+      problems.push(`${name}: 清单写了 card.titleKey，apply 之后却没登记卡片（registerUnit 没拿到 card）`);
       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;
+      if (messages === undefined || messages === null || typeof messages !== 'object') {
+        problems.push(
+          `${name}: 清单的 card.titleKey「${titleKey}」没有落点 —— registerUnit 交的面里没有 messages，` +
+            '面板上那一格会显示原始键名',
+        );
+      } else {
+        const missing = ['zh', 'en'].filter((one) => typeof messages[one]?.[titleKey] !== 'string');
+        if (missing.length > 0) {
+          problems.push(
+            `${name}: 清单的 card.titleKey「${titleKey}」在模块字典的 ${missing.join(' / ')} 里没有 —— ` +
+              '面板上那一格会显示原始键名。清单写了 titleKey，字典就得有这一条（zh / en 都要）',
+          );
+        }
+      }
+    }
+
     const props = {
       world: { current: {} },
       t: (key) => key,
@@ -288,7 +327,11 @@ export async function run() {
   }
   return {
     status: 'pass',
-    notes: [`${rows.length} 张卡片在**空数据**下都画得出来（不许抛）`, ...rows],
+    notes: [
+      `${rows.length} 个模块过了卡片这一关：有卡片的都在**空数据**下画得出来（不许抛）、清单的 titleKey 在字典里都有落点；` +
+        '清单写 "card": null 的，产物里也确实没登记卡片（声明与代码同一句话）',
+      ...rows,
+    ],
     problems: [],
   };
 }

package/src/checks/contracts.mjs

@@ -24,6 +24,12 @@ import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { readDeclaration } from '@dsh-workbench/shared/host';
+import {
+  DECLARED_TOOLS_FILE,
+  declaredToolsProblemOf,
+  declaredToolsWithoutKey,
+  declaredToolsApplies,
+} from '../declared-tools.mjs';
 import { discoverPackages, workspaceRootOf } from '../discover.mjs';
 import { SEED_SHORT } from '../seed.mjs';
 
@@ -191,6 +197,38 @@ function productsTextOf(dir) {
   return text;
 }
 
+function sourceFilesOf(dir) {
+  const srcDir = join(dir, 'src');
+  if (!existsSync(srcDir)) return [];
+  const found = [];
+  const walk = (at) => {
+    for (const entry of readdirSync(at, { withFileTypes: true })) {
+      const full = join(at, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === '__tests__' || entry.name === 'node_modules') continue;
+        walk(full);
+      } else if (/\.tsx?$/.test(entry.name) && !/\.test\.tsx?$/.test(entry.name)) {
+        found.push(full);
+      }
+    }
+  };
+  walk(srcDir);
+  return found;
+}
+
+// `plugin: '<字面量>'` 与同一行里 `?? '<字面量>'` 的兜底：都该是**清单里声明过**的那个插件名。
+// 插件名只该有一处真相（能拿到 `deps.manifest` 的地方就用它），但模块级代码拿不到 manifest ⇒ 只能写字面量。
+// 这条判据拦的是"改了清单没改代码"（或反过来）：那样外壳会按错的名字去装 / 去探那个插件，而用户只看到
+// "缺命令"这种没头没尾的状态。只查 `plugin:` 那几行，别的字面量不管（不猜）。
+function pluginLiteralsOf(line) {
+  if (!/\bplugin\s*:/.test(line)) return [];
+  const found = [];
+  const direct = /plugin\s*:\s*['"]([^'"]+)['"]/.exec(line);
+  if (direct !== null) found.push(direct[1]);
+  for (const match of line.matchAll(/\?\?\s*['"]([^'"]+)['"]/g)) found.push(match[1]);
+  return found;
+}
+
 function hostProductOf(dir) {
   try {
     return readFileSync(join(dir, 'dist/host.js'), 'utf8');
@@ -455,6 +493,40 @@ export async function run() {
       }
     }
 
+    // 清单里的工具名与「代码里那份名字」的关系（ADR-0038 的 `tools[].key` 一节）：
+    // 给了 key 就走生成物那一档 —— `src/declared-tools.ts` 必须存在、且与清单一致（过期 = 红），
+    // 并且源码里不许再有工具名的字面量（名字只写在清单里，代码引用 `DECLARED_TOOLS.<key>.name`，
+    // 键写错是编译错）。一个 key 都没写的模块不适用（那是不用生成物那一档）。
+    const declaredProblem = declaredToolsProblemOf(pkg.dir, dsh.workbench);
+    if (declaredProblem !== undefined) {
+      problems.push(`${name}: ${declaredProblem}`);
+    } else if (declaredToolsApplies(dsh.workbench)) {
+      const bare = declaredToolsWithoutKey(dsh.workbench);
+      const literals = [];
+      const generated = join(pkg.dir, DECLARED_TOOLS_FILE);
+      for (const file of sourceFilesOf(pkg.dir)) {
+        if (file === generated) continue;
+        const text = readFileSync(file, 'utf8');
+        for (const tool of dsh.workbench.tools) {
+          const one = `'${tool.name}'`;
+          const two = `"${tool.name}"`;
+          if (text.includes(one) || text.includes(two)) {
+            literals.push(`${relative(pkg.dir, file)} 里的 ${tool.name}`);
+          }
+        }
+      }
+      if (literals.length > 0) {
+        problems.push(
+          `${name}: 工具名的字面量又写回了源码 —— ${literals.join(' / ')}。` +
+            `清单里已经有 key，代码该引用生成物（\`DECLARED_TOOLS.<key>.name\`）：` +
+            `名字只有清单一处写者，写两遍就会漂，而漂了没有任何编译错`,
+        );
+      }
+      if (bare.length > 0) {
+        problems.push(`${name}: 清单里 ${bare.join(' / ')} 没有 key`);
+      }
+    }
+
     for (const face of ['host', 'client']) {
       const rel = dsh.workbenchFaces?.[face];
       if (typeof rel !== 'string') {
@@ -552,6 +624,27 @@ export async function run() {
         );
       });
 
+      const declaredPlugins = new Set(
+        (env.plugins ?? []).map((one) => text(one?.name)).filter((one) => one !== ''),
+      );
+      if (declaredPlugins.size > 0) {
+        for (const file of sourceFilesOf(pkg.dir)) {
+          readFileSync(file, 'utf8')
+            .split('\n')
+            .forEach((line, index) => {
+              for (const literal of pluginLiteralsOf(line)) {
+                if (declaredPlugins.has(literal)) continue;
+                problems.push(
+                  `${name}: ${relative(pkg.dir, file)}:${index + 1} 里的插件名「${literal}」不在清单的 ` +
+                    `env.plugins[] 里（清单里是 ${[...declaredPlugins].join(' / ')}）—— 改了清单没改代码` +
+                    '（或反过来）会让外壳按错的名字去装 / 去探那个插件。插件名只有一处真相：' +
+                    '能拿到 deps.manifest 的地方就用它，拿不到的地方至少与清单保持一致',
+                );
+              }
+            });
+        }
+      }
+
       if ((env.libs ?? []).length > 0 && !products.includes('libInstallCommand')) {
         problems.push(
           `${name}: 声明了 env.libs 却没用 libInstallCommand（@dsh-workbench/shared/host 里现成的）—— ` +

package/src/checks/style.mjs

@@ -22,17 +22,60 @@ const CLASS_TOKEN = /(^|[^-\w])\.?(wb-[a-zA-Z0-9-]+)/g;
 // 契约 = 外壳**所有**声明了 `wb-*` 的样式表，不只是那份全局 `board.css`：
 // ADR-0029 要求组件的样式跟组件走，所以 `wb-card` / `wb-rows` / `wb-note` 这些已经搬进
 // `packages/shared/src/components/*.css`（谁渲染谁拥有）。契约跟着搬，模块借用它们才不误报。
-const CONTRACT_FILES = [
-  fileURLToPath(new URL('../../../workbench/src/shared/styles/board.css', import.meta.url)),
-  ...(() => {
-    const dir = fileURLToPath(new URL('../../../shared/src/components', import.meta.url));
-    return existsSync(dir)
-      ? readdirSync(dir)
-          .filter((name) => name.endsWith('.css'))
-          .map((name) => join(dir, name))
-      : [];
-  })(),
-];
+// 契约按**两种安装形态**解析，两边必须给同一份名单（实测过差别，见 spec §24.4）：
+//   · 在外壳仓里跑：源码就在隔壁（`workbench/src/shared/styles/board.css` + `shared/src/components/*.css`）；
+//   · 在模块仓里跑：只能从**已装的外壳**读 —— `@dsh-workbench/core/dist/board.css`（构建时随包出货的那份
+//     契约副本，见 `packages/workbench/scripts/build.mjs`）与 `@dsh-workbench/shared/src/components/*.css`
+//     （shared 本来就发源码）。
+// 从前只写死了相对 module-tools 自己的路径 ⇒ 装进模块仓后 `board.css` 找不到，契约退化成"只有 shared 组件
+// 那一份"，于是 `board.css` 里的合法借用（例如 `wb-iconButton`）被**误报**；而且借用检查在契约缺失时
+// 会 `contract.has` 抛异常（"契约文件不在"那条 note 根本到不了）。
+const SOURCE_BOARD = fileURLToPath(new URL('../../../workbench/src/shared/styles/board.css', import.meta.url));
+const SOURCE_COMPONENTS = fileURLToPath(new URL('../../../shared/src/components', import.meta.url));
+const INSTALLED_BOARD = join('node_modules', '@dsh-workbench', 'core', 'dist', 'board.css');
+const INSTALLED_COMPONENTS = join('node_modules', '@dsh-workbench', 'shared', 'src', 'components');
+
+function installedUnder(dir, tail) {
+  let at = resolve(dir);
+  for (;;) {
+    const candidate = join(at, tail);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(at);
+    if (parent === at) return undefined;
+    at = parent;
+  }
+}
+
+function cssFilesIn(dir) {
+  try {
+    return readdirSync(dir)
+      .filter((name) => name.endsWith('.css'))
+      .map((name) => join(dir, name));
+  } catch {
+    return [];
+  }
+}
+
+function contractFilesFor(moduleDir) {
+  const board = existsSync(SOURCE_BOARD) ? SOURCE_BOARD : installedUnder(moduleDir, INSTALLED_BOARD);
+  const components = existsSync(SOURCE_COMPONENTS)
+    ? SOURCE_COMPONENTS
+    : installedUnder(moduleDir, INSTALLED_COMPONENTS);
+  return [
+    ...(board === undefined ? [] : [board]),
+    ...(components === undefined ? [] : cssFilesIn(components)),
+  ];
+}
+
+function contractOf(moduleDir) {
+  const files = contractFilesFor(moduleDir);
+  if (files.length === 0) return null;
+  return new Set(
+    files.flatMap((file) =>
+      Array.from(readFileSync(file, 'utf8').matchAll(CLASS_TOKEN), (match) => match[2]),
+    ),
+  );
+}
 
 export const title = '样式归属';
 
@@ -51,19 +94,13 @@ function isTestSource(file) {
 }
 
 export async function run() {
-  const contract = CONTRACT_FILES.some((file) => existsSync(file))
-    ? new Set(
-        CONTRACT_FILES.filter((file) => existsSync(file)).flatMap((file) =>
-          Array.from(readFileSync(file, 'utf8').matchAll(CLASS_TOKEN), (match) => match[2]),
-        ),
-      )
-    : null;
-
   const problems = [];
   const borrowed = [];
   const anchors = [];
   const modules = discoverModulePackages({ root: process.cwd() });
+  const contracts = new Map(modules.map((pkg) => [pkg.dir, contractOf(pkg.dir)]));
   for (const pkg of modules) {
+    const contract = contracts.get(pkg.dir);
     for (const file of walk(pkg.dir)) {
       if (!/\.(css|ts|tsx)$/.test(file)) continue;
       let text;
@@ -84,15 +121,14 @@ export async function run() {
 
       if (isTestSource(file)) continue;
       if (!/\.tsx?$/.test(file)) continue;
-      if (contract !== null) {
-        lines.forEach((line, index) => {
-          if (!BARE_ANCHOR.test(line)) return;
-          anchors.push(
-            `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 手写了裸 <a> —— ` +
-              `外链一律用 kit 的 Link（新窗口、noopener、自带那个外链小箭头；样式只有这一份）：${line.trim().slice(0, 80)}`,
-          );
-        });
-      }
+      lines.forEach((line, index) => {
+        if (!BARE_ANCHOR.test(line)) return;
+        anchors.push(
+          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 手写了裸 <a> —— ` +
+            `外链一律用 kit 的 Link（新窗口、noopener、自带那个外链小箭头；样式只有这一份）：${line.trim().slice(0, 80)}`,
+        );
+      });
+      if (contract === null) continue;
       lines.forEach((line, index) => {
         for (const match of line.matchAll(CLASS_TOKEN)) {
           const name = match[2];
@@ -149,7 +185,8 @@ export async function run() {
     if (borrowed.length > 0) {
       notes.push(
         `${borrowed.length} 处是「模块借用了契约里没有的 wb-* 类」：（契约是本仓 board.css：模块只许借它里面有的类。` +
-          '没有的那个要么是拼错/改了名漏改，要么本该进 board.css —— 空类名在真机上就是没样式，而且没人会报错）',
+          '没有的那个要么是拼错/改了名漏改，要么本该进 board.css —— 空类名在真机上就是没样式，而且没人会报错。' +
+          '名单是**外壳出货的那份**（`@dsh-workbench/core/dist/board.css` + 外壳组件自己的样式表））',
       );
     }
     if (anchors.length > 0) {
@@ -170,10 +207,23 @@ export async function run() {
     };
   }
 
+  const noContract = modules
+    .filter((pkg) => contracts.get(pkg.dir) === null)
+    .map((pkg) => pkg.manifest.name);
+  if (noContract.length === modules.length) {
+    return {
+      status: 'skip',
+      notes: [
+        '找不到外壳出货的那份契约（`@dsh-workbench/core/dist/board.css` 与 `@dsh-workbench/shared` 的组件样式表都不在）' +
+          '—— 模块借的 wb-* 类这一项这次一条都没查，不是"没问题"',
+      ],
+      problems: [],
+    };
+  }
   const contractNote =
-    contract === null
-      ? '契约文件不在（这次只查了"模块不许定义 wb-*"）'
-      : `借用的类都在契约里（board.css + 外壳组件自己的样式表）`;
+    noContract.length === 0
+      ? '借用的类都在契约里（外壳出货的 board.css + 外壳组件自己的样式表）'
+      : `${noContract.join(' / ')} 那一边找不到外壳的契约，借用这一项没查`;
   return {
     status: 'pass',
     notes: [`${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}`],

package/src/declared-tools.mjs

@@ -0,0 +1,85 @@
+// 工具名只有**一处写者**：清单（`dsh.workbench.tools[].name`）。
+//
+// 代码里注册一个工具必须报它的名字，所以从前那份字面量在清单与代码里各写一遍 —— 只能靠判据对账
+// （`check:contracts` 的 reconcileTools 就是这么干的）。`tools[].key` + `dsh-wb-module sync` 把
+// 代码那一半**生成**出来：
+//
+//     dsh-wb-module sync   →   src/declared-tools.ts
+//         export const DECLARED_TOOLS = {
+//           sync: { name: 'workbench_argocd_sync', writes: true },
+//         } as const;
+//
+// 于是：改名只动清单一处；代码引用的是**键**（`DECLARED_TOOLS.sync.name`），键写错是编译错；
+// 生成物落后于清单由判据当场判红。
+//
+// 方向是**单向**的：绝不回写 `package.json`（ADR-0038 §2.5 已经拒了"生成式回写"：`package.json`
+// 有两个写者（人与生成器）就会静默覆盖）。
+//
+// 输出与比对都按"各家 prettier 都可能重排"来设计：字面量用单引号（本生态的 TS 风格），
+// 比对时**忽略空白、把两种引号当同一件事** —— 重排不算过期，值变了才算。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DECLARED_TOOLS_FILE = 'src/declared-tools.ts';
+
+export function declaredToolsPathOf(dir) {
+  return join(dir, DECLARED_TOOLS_FILE);
+}
+
+function toolsOf(raw) {
+  return Array.isArray(raw?.tools) ? raw.tools : [];
+}
+
+function keyOf(tool) {
+  return typeof tool?.key === 'string' && tool.key.trim() !== '' ? tool.key.trim() : '';
+}
+
+/** 一个 key 都没写的模块不适用（那是不用生成物那一档，判据也不找它）。 */
+export function declaredToolsApplies(raw) {
+  return toolsOf(raw).some((tool) => keyOf(tool) !== '');
+}
+
+/** 还没写 key 的那些工具（有 key 就得每个都有：半写会让生成物少几条，而代码里还在写字面量）。 */
+export function declaredToolsWithoutKey(raw) {
+  return toolsOf(raw)
+    .filter((tool) => keyOf(tool) === '')
+    .map((tool) => JSON.stringify(tool?.name));
+}
+
+/** 生成物的正文。**不给注释**：它落在模块的 `src/**`（零注释那一条管到这里），改它无效、过期会红。 */
+export function renderDeclaredTools(raw) {
+  const rows = toolsOf(raw).map(
+    (tool) =>
+      `  ${keyOf(tool)}: { name: '${tool.name}', writes: ${tool.writes === true} },`,
+  );
+  return [
+    'export const DECLARED_TOOLS = {',
+    ...rows,
+    '} as const;',
+    '',
+    'export type DeclaredToolKey = keyof typeof DECLARED_TOOLS;',
+    '',
+  ].join('\n');
+}
+
+/** 生成物与清单对不上的原因（`undefined` = 新鲜，或不适用）。 */
+export function declaredToolsProblemOf(dir, raw) {
+  if (!declaredToolsApplies(raw)) return undefined;
+  const missing = declaredToolsWithoutKey(raw);
+  if (missing.length > 0) {
+    return `清单里 ${missing.join(' / ')} 没有 key —— 有 key 就走生成物那一档，那就每个工具都得有一个`;
+  }
+  const at = declaredToolsPathOf(dir);
+  if (!existsSync(at)) {
+    return `${DECLARED_TOOLS_FILE} 不在 —— 清单里给了 key 就该有生成物，跑 \`dsh-wb-module sync\` 生成`;
+  }
+  const strip = (text) => text.replace(/\s+/g, '').replace(/"/g, "'");
+  if (strip(readFileSync(at, 'utf8')) !== strip(renderDeclaredTools(raw))) {
+    return (
+      `${DECLARED_TOOLS_FILE} 与清单对不上（生成物过期，或有人手改了它）—— ` +
+      '跑 `dsh-wb-module sync` 刷新。别手改：它是生成的'
+    );
+  }
+  return undefined;
+}

package/src/sync.mjs

@@ -0,0 +1,51 @@
+// `dsh-wb-module sync`：按清单生成 `src/declared-tools.ts`（单向，清单 → 代码）。
+//
+// 为什么需要它、生成物长什么样、为什么绝不回写 package.json：见 `declared-tools.mjs` 开头与
+// ADR-0038 的 `tools[].key` 一节。
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  DECLARED_TOOLS_FILE,
+  declaredToolsApplies,
+  declaredToolsPathOf,
+  declaredToolsProblemOf,
+  declaredToolsWithoutKey,
+  renderDeclaredTools,
+} from './declared-tools.mjs';
+
+export async function sync({ root }) {
+  const manifestPath = join(root, 'package.json');
+  if (!existsSync(manifestPath)) throw new Error(`${manifestPath} 不在 —— sync 要在模块包目录里跑`);
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const raw = manifest.dsh?.workbench;
+  const unit = typeof raw?.unit === 'string' ? raw.unit : manifest.name;
+  if (raw === undefined) throw new Error(`${unit}: package.json 里没有 dsh.workbench —— 这不是模块包`);
+
+  const tools = Array.isArray(raw.tools) ? raw.tools : [];
+  if (tools.length === 0) {
+    console.log(`${unit}: 清单里没有工具，不用生成物`);
+    return;
+  }
+
+  const missing = declaredToolsWithoutKey(raw);
+  if (missing.length > 0) {
+    const hint = declaredToolsApplies(raw)
+      ? '有 key 就走生成物那一档，那就每个工具都得有一个'
+      : '给每个工具加一个 lowerCamelCase 的 key，代码里就不再写工具名的字面量';
+    throw new Error(
+      `${unit}: 清单里 ${missing.join(' / ')} 没有 key —— ${hint}。例如：\n` +
+        `${tools.map((tool) => `  "key": "…",  // ${JSON.stringify(tool.name)}`).join('\n')}\n` +
+        '（key 是代码里那个短名：`DECLARED_TOOLS.<key>.name`。见 ADR-0038 的 `tools[].key` 一节）',
+    );
+  }
+
+  const at = declaredToolsPathOf(root);
+  const had = existsSync(at);
+  const stale = declaredToolsProblemOf(root, raw);
+  writeFileSync(at, renderDeclaredTools(raw));
+  console.log(
+    `${unit}: 写了 ${DECLARED_TOOLS_FILE}（${tools.length} 个工具，按清单生成）` +
+      (had && stale !== undefined ? ' —— 原来那份和清单对不上，已刷新' : ''),
+  );
+}

package/template/README.md.tpl

@@ -23,6 +23,16 @@ pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍，看
 dsh plugin --profile workbench add <本目录>
 ```
 
+要加能力：`package.json` 的 `dsh.workbench.tools[]` 里每个工具写 `name` / `writes` / `key`
+（`key` 是代码里那个短名，lowerCamelCase），然后跑一次
+
+```bash
+dsh-wb-module sync   # 按清单生成 src/declared-tools.ts
+```
+
+代码里写 `DECLARED_TOOLS.<key>.name` —— **工具名的字面量只留在清单这一处**。生成物过期、半写 `key`、
+或源码里又写了一遍工具名字面量，`check` 都会红（`sync` 会告诉你缺哪个工具的 `key`）。
+
 面板只读、写入只走 agent 工具；共享代码从 `@dsh-workbench/shared` 拿，
 单例机制（hooks / 容器组件 / 读缝）只能从 `@dsh-workbench/core/client` 的 kit 拿。
 dsh 已有的组件与样式**先从 kit 拿**，别从 DOM + CSS 重画。

package/template-diy/README.md.tpl

@@ -155,8 +155,11 @@ GET /api/__UNIT__/overview?path=<绝对路径>&limit=<1..50>
 
 ### 会写：清单里标出来 + 认领审批
 
+> 每个工具都写一个 `key`（代码里那个短名，lowerCamelCase），然后 `dsh-wb-module sync` 生成
+> `src/declared-tools.ts`：代码写 `DECLARED_TOOLS.rebuild.name` —— 工具名的字面量只留在清单里。
+
 ```ts
-tools: [{ name: 'workbench___UNIT___rebuild', writes: true }],
+tools: [{ name: 'workbench___UNIT___rebuild', writes: true, key: 'rebuild' }],
 
 needsApproval: (call) => ({
   kind: 'ask',