@dsh-workbench/module-tools 0.3.11 → 1.0.0-beta.1

package/src/datasource-file.mjs

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DATASOURCE_FILE = 'src/datasource.ts';
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readsOf(design) {
+  const list = design?.reads;
+  if (Array.isArray(list) && list.length > 0) return list;
+  const one = design?.datasource;
+  return one === undefined || one === null || typeof one !== 'object' ? [] : [one];
+}
+
+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];
+}
+
+export function datasourceEntriesOf(design) {
+  return [
+    ...readsOf(design).map((read) => ({ key: text(read?.key), recipe: read?.recipe, calls: read?.calls })),
+    ...writesOf(design).map((write) => ({ key: text(write?.key), recipe: write?.recipe })),
+  ].filter((one) => one.key !== '' && one.recipe !== undefined && one.recipe !== null);
+}
+
+function stringLiteral(value) {
+  return `'${value
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t')}'`;
+}
+
+function keyLiteral(key) {
+  return /^[A-Za-z_$][\w$]*$/.test(key) ? key : stringLiteral(key);
+}
+
+function tsLiteral(value, indent) {
+  if (typeof value === 'string') return stringLiteral(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    return `[${value.map((one) => tsLiteral(one, indent + 1)).join(', ')}]`;
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value).filter(([, one]) => one !== undefined);
+    if (entries.length === 0) return '{}';
+    const pad = '  '.repeat(indent + 1);
+    const close = '  '.repeat(indent);
+    return `{\n${entries
+      .map(([key, one]) => `${pad}${keyLiteral(key)}: ${tsLiteral(one, indent + 1)},`)
+      .join('\n')}\n${close}}`;
+  }
+  return 'null';
+}
+
+export function renderDatasource(design) {
+  const entries = datasourceEntriesOf(design);
+  const lines = ['export const DATASOURCE = {'];
+  for (const entry of entries) {
+    lines.push(`  ${keyLiteral(entry.key)}: ${tsLiteral(entry.recipe, 1)},`);
+  }
+  lines.push('} as const;');
+  const batched = entries.filter((entry) => entry.calls !== undefined && entry.calls !== null);
+  if (batched.length > 0) {
+    lines.push('', 'export const DATASOURCE_CALLS = {');
+    for (const entry of batched) {
+      lines.push(`  ${keyLiteral(entry.key)}: ${tsLiteral(entry.calls, 1)},`);
+    }
+    lines.push('} as const;');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function datasourceProblemOf(dir, design) {
+  const entries = datasourceEntriesOf(design);
+  const at = join(dir, DATASOURCE_FILE);
+  if (entries.length === 0) {
+    if (!existsSync(at)) return undefined;
+    return (
+      `${DATASOURCE_FILE} 在，但 design.json 里没有 key + recipe 的读 / 写 —— ` +
+      '补上配方（跑 `dsh-wb-module sync` 刷新），或者删掉这个生成物'
+    );
+  }
+  if (!existsSync(at)) {
+    return `${DATASOURCE_FILE} 不在 —— design.json 里有 key + recipe 的读 / 写，就该有生成物，跑 \`dsh-wb-module sync\``;
+  }
+  const strip = (source) => source.replace(/\s+/g, '').replace(/"/g, "'");
+  if (strip(readFileSync(at, 'utf8')) !== strip(renderDatasource(design))) {
+    return (
+      `${DATASOURCE_FILE} 与 design.json 对不上（生成物过期，或有人手改了它）—— ` +
+      '跑 `dsh-wb-module sync` 刷新。别手改：它是生成的'
+    );
+  }
+  return undefined;
+}

package/src/declared-tools.mjs

@@ -1,23 +1,3 @@
-// 工具名只有**一处写者**：清单（`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';
 
@@ -35,19 +15,16 @@ 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/**`（那里只许贴导出的 JSDoc，生成这份一行都不加），改它无效、过期会红。 */
 export function renderDeclaredTools(raw) {
   const rows = toolsOf(raw).map(
     (tool) =>
@@ -63,7 +40,6 @@ export function renderDeclaredTools(raw) {
   ].join('\n');
 }
 
-/** 生成物与清单对不上的原因（`undefined` = 新鲜，或不适用）。 */
 export function declaredToolsProblemOf(dir, raw) {
   if (!declaredToolsApplies(raw)) return undefined;
   const missing = declaredToolsWithoutKey(raw);

package/src/design.mjs

@@ -1,26 +1,11 @@
-// 三张表的**唯一真相**：`design.json`。
-//
-// ── 为什么要有这个文件 ────────────────────────────────────────────────────────
-//
-// 在这之前，三张表只活在 README 的散文里：SKILL.md 说"空着的格就是还没定的事，别带着空格往下做"，
-// 可**没有一条判据看得见那些格**。于是它靠 agent 自觉：忘了填、填了一半、只留在对话里 —— 都没人拦。
-// README 是给人读的落点，不是给机器判的形状。
-//
-// 现在的分工：
-//   · `design.json` —— 机器可读的需求底稿（三张表 + 状态矩阵 + 数据源记录 + 写通道记录 + 验收清单）；
-//   · `README.md`   —— 由它**生成**的那一段（夹在 `<!-- dsh-wb:design:start/end -->` 之间）；
-//   · `dsh-wb-module design check` —— 把**空着的格**列出来（红），并核对 README 没落后于 design.json。
-//
-// 这样"空格"第一次有了形状：填空 → 再往下做；写完 → 自己在真卡片上逐条走通，`design accept` 打勾。
-
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { callsProblemOf, describeRecipe, recipeProblemOf } from '@dsh-workbench/shared/host';
 
 export const DESIGN_FILE = 'design.json';
 export const START_MARK = '<!-- dsh-wb:design:start -->';
 export const END_MARK = '<!-- dsh-wb:design:end -->';
 
-/** 卡片五态 —— 与指引 PANEL.md 的状态矩阵、`check:cards` 的渲染判据同一套。 */
 export const STATE_KEYS = ['idle', 'loading', 'ready', 'empty', 'unreadable'];
 const STATE_LABELS = {
   idle: '待机（还没选东西）',
@@ -32,7 +17,6 @@ const STATE_LABELS = {
 const LETTERS = ['A', 'B', 'C', 'D', 'E'];
 const PENDING = '（待填）';
 
-/** 必填的行字段；`optional` 的那些留空不算空。 */
 const ROWS = {
   panel: { fields: ['cell', 'conclusion'], optional: ['link'] },
   config: {
@@ -51,16 +35,8 @@ const ROWS = {
 const DATASOURCE_FIELDS = ['read', 'params', 'credentials', 'notLoggedIn', 'timeout'];
 const WRITE_FIELDS = ['command', 'params', 'credentials', 'preview', 'readback', 'undo', 'failure'];
 
-/** `params` 里写了"必填"，就得说清凭什么是必填 —— 来源只能是这五个词之一
- *  （`已证` 那句话的来源是**录下来的图**上那个红 `*`，或者**契约**里 `--help -f json` 的 `required`）。**气味判据不是解析器**：
- *  只看来源有没有写出来，不看句式、不数个数、不认字段名，也不校验来源是不是真的 ——
- *  真话假话只有人和复核能判（照 `undo` 那条的原话：逼作者想过，不逼他造假）。 */
 const SOURCE_TAGS = ['已证', '声明', '人证', '契约', '未定'];
 
-/** `params` 里有没有一处「必填」**没被否掉** —— `非必填` / `不必填`（只看紧邻的那个字符）才算被否掉。
- *  这是**字符级守卫**，只挡这一种写法：不认"必填项""必填字段"以外的语法、不做否定句理解。
- *  为什么非要有它：`design check` 是模块作者天天跑的门禁，`非必填` 这种**明确说不要**的写法
- *  被误咬一次，他下次就把这条判据当噪音 —— 误红的代价比漏一两次大得多。 */
 function hasBareRequired(value) {
   let at = value.indexOf('必填');
   while (at !== -1) {
@@ -71,8 +47,6 @@ function hasBareRequired(value) {
   return false;
 }
 
-/** 一条卡背后可以有多条读（甚至跨站点）：规范形状 `reads: [ … ]`，一条一行；
- *  `datasource: { … }` 是只有一条读时的写法（老模块都长这样，继续认）。 */
 function readsOf(design) {
   const list = design?.reads;
   if (Array.isArray(list) && list.length > 0) return list;
@@ -80,8 +54,6 @@ 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;
@@ -89,7 +61,6 @@ function writesOf(design) {
   return one === undefined || one === null || typeof one !== 'object' ? [] : [one];
 }
 
-/** 「他能自己配什么」有两种，分不清就会写成一个不落盘的选择还自称配置： */
 function persistenceLabel(value) {
   const raw = text(value);
   if (raw === 'prefs') return '存起来（按工作区记，刷新还在）';
@@ -97,11 +68,39 @@ function persistenceLabel(value) {
   return cell(raw);
 }
 
+function recipeSummaryOf(recipe) {
+  try {
+    const described = describeRecipe(recipe);
+    const auth =
+      described.auth === undefined
+        ? 'cookie'
+        : `${described.auth.source} → ${described.auth.place}${described.auth.name === undefined ? '' : `（${described.auth.name}）`}`;
+    return `${described.method} ${described.url} · ${auth}`;
+  } catch (error) {
+    return `（配方不合法：${error.message}）`;
+  }
+}
+
+function callsSummaryOf(recipe, calls) {
+  try {
+    return Object.keys(calls)
+      .map((name) => {
+        const described = describeRecipe(recipe, calls[name]);
+        return `${name}: ${described.url}`;
+      })
+      .join('；');
+  } catch (error) {
+    return `（批量不合法：${error.message}）`;
+  }
+}
+
 function datasourceRowsOf(read) {
   return [
     '| 项 | 值（照抄，别转述） |',
     '|---|---|',
     `| 哪条读（命令 / URL） | ${cell(read?.read)} |`,
+    ...(read?.recipe === undefined ? [] : [`| 调用形状（配方） | ${cell(recipeSummaryOf(read.recipe))} |`]),
+    ...(read?.calls === undefined ? [] : [`| 一次打几条（批量） | ${cell(callsSummaryOf(read.recipe, read.calls))} |`]),
     `| 参数（缺省 / 范围 / 上限） | ${cell(read?.params)} |`,
     `| 凭据从哪来 | ${cell(read?.credentials)} |`,
     `| 没登录 / 凭据过期时是什么样 | ${cell(read?.notLoggedIn)} |`,
@@ -115,6 +114,7 @@ function writeRowsOf(write) {
     '| 项 | 值（照抄，别转述） |',
     '|---|---|',
     `| 哪条写（命令 / URL + 方法） | ${cell(write?.command)} |`,
+    ...(write?.recipe === undefined ? [] : [`| 调用形状（配方） | ${cell(recipeSummaryOf(write.recipe))} |`]),
     `| 参数（必填 / 取值枚举 / 上限） | ${cell(write?.params)} |`,
     `| 凭据从哪来 | ${cell(write?.credentials)} |`,
     `| 有没有预览档（没有就写"没有，一次就是真的"） | ${cell(write?.preview)} |`,
@@ -148,6 +148,16 @@ export function readDesign(root) {
   }
 }
 
+export function acceptanceOf(root) {
+  const design = readDesign(root);
+  const rows = asRows(design?.acceptance);
+  return {
+    total: rows.length,
+    checked: rows.filter((one) => one?.checked === true).length,
+    acceptedAt: typeof design?.acceptedAt === 'string' ? design.acceptedAt : undefined,
+  };
+}
+
 function skeleton(manifest = {}) {
   return {
     unit: text(manifest?.dsh?.workbench?.unit) || text(manifest.name).replace(/^.*\/module-/, ''),
@@ -179,7 +189,6 @@ function need(cells, value, path) {
   if (pending(value)) cells.push(path);
 }
 
-/** 空着的格 —— 这就是"别带着空格往下做"那条纪律的机器形状。 */
 export function emptyCells(design) {
   const cells = [];
   for (const field of ['unit', 'name', 'oneLine']) need(cells, design?.[field], field);
@@ -209,11 +218,10 @@ export function emptyCells(design) {
       cells.push(`states[${index}]（缺 ${key} 这一态）`);
       continue;
     }
-    // 这一态对这份模块确实不适用时，写一句**为什么**就行（例：账号级的卡没有"还没选项目"这一态）。
-    // 行仍然要占着 —— 五态是矩阵的行，不是"能省则省"的清单；省掉的只是那三个格子。
+
     if (text(row.na) !== '') continue;
     for (const field of ['sees', 'canDo']) need(cells, row[field], `states.${key}.${field}`);
-    // 这份模块故意没有 agent 能力时，`agentCan` 没有内容可写 —— 那几格不必硬填一句同义反复。
+
     if (!noCapabilities) need(cells, row.agentCan, `states.${key}.agentCan`);
   }
 
@@ -222,21 +230,71 @@ export function emptyCells(design) {
   reads.forEach((read, index) => {
     const label = reads.length === 1 ? 'datasource' : `reads[${index}]`;
     for (const field of DATASOURCE_FIELDS) need(cells, read?.[field], `${label}.${field}`);
+
+    const recipe = read?.recipe;
+    const custom = read?.custom;
+    if (recipe !== undefined && custom !== undefined) {
+      cells.push(`${label}.recipe（recipe 与 custom 只能二选一）`);
+    }
+    if (recipe !== undefined) {
+      const problem = recipeProblemOf(recipe);
+      if (problem !== undefined) cells.push(`${label}.recipe（${problem}）`);
+    }
+    if (read?.calls !== undefined) {
+      if (recipe === undefined) cells.push(`${label}.calls（calls 要有 recipe）`);
+      else {
+        const problem = callsProblemOf(recipe, read.calls);
+        if (problem !== undefined) cells.push(`${label}.calls（${problem}）`);
+      }
+    }
+    if (custom !== undefined && text(custom?.why) === '') cells.push(`${label}.custom.why`);
+
+    const key = text(read?.key);
+    if (key !== '' && !/^[a-z][A-Za-z0-9]*$/.test(key)) cells.push(`${label}.key（lowerCamelCase）`);
   });
 
   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}`);
-    // 写了"必填"却不带来源词 ⇒ 点名（`非必填` / `不必填` 那种**明确说不要**的不算，见 hasBareRequired）。
-    // 空着 / `（待填）` 是上一轮那条 `pending` 的事，两条不叠。
-    // 判的是**值**不是表头：渲染出来的行名「参数（必填 / 取值枚举 / 上限）」不在这条路上。
+
     const params = text(write?.params);
     if (!pending(params) && hasBareRequired(params) && !SOURCE_TAGS.some((tag) => params.includes(tag))) {
       cells.push(`${label}.params.source`);
     }
+
+    const recipe = write?.recipe;
+    const custom = write?.custom;
+    if (recipe !== undefined && custom !== undefined) {
+      cells.push(`${label}.recipe（recipe 与 custom 只能二选一）`);
+    }
+    if (recipe !== undefined) {
+      const problem = recipeProblemOf(recipe);
+      if (problem !== undefined) cells.push(`${label}.recipe（${problem}）`);
+    }
+    if (custom !== undefined && text(custom?.why) === '') cells.push(`${label}.custom.why`);
+
+    const key = text(write?.key);
+    if (key !== '' && !/^[a-z][A-Za-z0-9]*$/.test(key)) cells.push(`${label}.key（lowerCamelCase）`);
   });
 
+  const keys = new Set();
+  const seen = new Map();
+  for (const [readIndex, read] of reads.entries()) {
+    const key = text(read?.key);
+    if (key === '') continue;
+    if (keys.has(key)) cells.push(`数据源 key 重复：${key}（${seen.get(key)} 与 读 ${String(readIndex + 1)}）`);
+    else seen.set(key, `读 ${String(readIndex + 1)}`);
+    keys.add(key);
+  }
+  for (const [writeIndex, write] of writes.entries()) {
+    const key = text(write?.key);
+    if (key === '') continue;
+    if (keys.has(key)) cells.push(`数据源 key 重复：${key}（${seen.get(key)} 与 写 ${String(writeIndex + 1)}）`);
+    else seen.set(key, `写 ${String(writeIndex + 1)}`);
+    keys.add(key);
+  }
+
   return cells;
 }
 
@@ -245,7 +303,6 @@ function cell(value) {
   return raw === '' ? PENDING : raw.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ');
 }
 
-/** 可空的格：空着是**合法**的（例：这张卡没有外链），渲染成 `—` 而不是"待填"。 */
 function soft(value) {
   const raw = text(value);
   return raw === '' || raw === PENDING ? '—' : cell(raw);
@@ -257,6 +314,25 @@ function tableOf(header, rows) {
   return [`| ${header} |`, divider, ...rows.map((row) => `| ${row.join(' | ')} |`)].join('\n');
 }
 
+export function designWarningsOf(design) {
+  const reads = readsOf(design);
+  const writes = writesOf(design);
+  const warnings = [];
+  reads.forEach((read, index) => {
+    if (read?.custom === undefined) return;
+    const label = reads.length === 1 ? 'datasource' : `reads[${index}]`;
+    const why = text(read.custom?.why);
+    warnings.push(`${label}.custom（${why === '' ? '没写 why' : why}）—— 配方盖不住的读，理由要留在底稿里`);
+  });
+  writes.forEach((write, index) => {
+    if (write?.custom === undefined) return;
+    const label = writes.length === 1 ? 'write' : `writes[${index}]`;
+    const why = text(write.custom?.why);
+    warnings.push(`${label}.custom（${why === '' ? '没写 why' : why}）—— 配方盖不住的写，理由要留在底稿里`);
+  });
+  return warnings;
+}
+
 export function renderDesign(design) {
   const panel = asRows(design?.panel);
   const config = asRows(design?.config);
@@ -403,6 +479,7 @@ function checkDesign(root) {
     process.exit(1);
   }
   const cells = emptyCells(design);
+  const warnings = designWarningsOf(design);
   const rows = (key) => asRows(design[key]).length;
   const acceptance = asRows(design.acceptance);
   const accepted = acceptance.filter((one) => one?.checked === true).length;
@@ -412,6 +489,7 @@ function checkDesign(root) {
   const fresh = at === undefined ? false : readme.slice(at.start, at.end) === `${START_MARK}\n${renderDesign(design)}\n`;
 
   console.log(`design.json：面板 ${rows('panel')} 行 · 状态 ${STATE_KEYS.length} 态 · 配置 ${rows('config')} 项 · 能力 ${rows('capabilities')} 条 · 联动 ${rows('linkage')} 行 · 验收 ${accepted}/${acceptance.length}`);
+  for (const one of warnings) console.log(`⚠ ${one}`);
   if (cells.length > 0) {
     console.error(`✖ 还空着 ${cells.length} 格（"空着的格就是还没定的事"，别带着空格往下做）：`);
     for (const one of cells) console.error(`  · ${one}`);

package/src/discover.mjs

@@ -1,4 +1,3 @@
-
 import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
@@ -29,13 +28,7 @@ export function discoverPackages({ root = process.cwd() } = {}) {
   const packagesDir = join(workspace, 'packages');
   if (existsSync(packagesDir)) {
     for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {
-      // 点开头的目录一律不认：那是**自检的临时探针**（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));
     }
@@ -44,8 +37,7 @@ export function discoverPackages({ root = process.cwd() } = {}) {
   const seen = new Set();
   const found = [];
   for (const dir of dirs) {
-    // 按**真实路径**去重：`process.cwd()` 与 workspace 拼出来的路径可能是同一条目录的两种写法
-    // （软链，典型是 macOS 的 /tmp → /private/tmp），不规范化就会把同一个包扫两遍、报两遍。
+
     const key = existsSync(dir) ? realpathSync(dir) : dir;
     if (seen.has(key)) continue;
     seen.add(key);

package/src/font-scale.mjs

@@ -1,49 +1,10 @@
-// 字号口径（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) {
@@ -55,7 +16,6 @@ export function shellFontScaleIn(files) {
   return sizes;
 }
 
-/** 合起来的刻度：dsh 别名那 7 档 + 外壳自己 token 里的档（现读）。 */
 export function fontScaleOf(shellTokenFiles = []) {
   return new Set([...DSH_ALIAS_FONT_SIZES, ...shellFontScaleIn(shellTokenFiles)]);
 }
@@ -64,12 +24,10 @@ 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)) {
@@ -78,11 +36,6 @@ function sizeTokenRefs(value) {
   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);
@@ -116,11 +69,6 @@ function walk(dir, acc = []) {
   return acc;
 }
 
-/**
- * 扫一组根下的字号声明并归类。`roots` 是 `{ label, dir }`：label 是报出来的包名。
- * 测试文件不扫（用例里那几处是断言用的字符串，不是界面字号）；`node_modules` / `dist` 不扫。
- * 返回里 `refFiles` / `litFiles` 是**涉及文件数**（同一个文件只算一次）。
- */
 export function auditFontSizes({ roots, scale }) {
   const refs = [];
   const offScale = [];
@@ -174,7 +122,6 @@ export function auditFontSizes({ roots, scale }) {
 
 const formatSize = (value) => String(value);
 
-/** 最多印十来行明细：刻度外的先印（那是这份清单要的东西），再印刻度上的。 */
 const DETAIL_LIMIT = 12;
 
 function detailOf(hit, verdict) {
@@ -184,13 +131,6 @@ function detailOf(hit, verdict) {
     : `· ${head} —— ${formatSize(hit.px)} 在刻度上，可收进令牌（但不是错）`;
 }
 
-/**
- * 拼成 `checks/style.mjs` 通过时的那几行 note：第一行汇总（各类条数 + 涉及文件数 + 指路），
- * 后面最多 `DETAIL_LIMIT` 行明细。零命中时只留一行"都是 0"。
- *
- * `doc` 是**必填**的：这几行 note 打印给模块作者，指路必须是他打得到的地方（调用方给，见
- * `checks/style.mjs` 的 `FONT_DOC`）—— 不留默认值，免得默认值哪天又变成一条跨仓路径印出去。
- */
 export function fontScaleNotes(report, scale, { doc }) {
   const sizes = [...scale].sort((a, b) => a - b).map(formatSize).join(' / ');
   const head =

package/src/init.mjs

@@ -9,21 +9,8 @@ const TEMPLATES = {
 };
 const UNIT_ID = /^[a-z][a-z0-9-]*$/;
 
-// 模板里那三处 `@dsh-workbench/*` 声明的不是"某个死数"，而是**盖章那一刻的工具链范围**：
-// 优先 init 所在工程里实际装着的那份外壳（用户手上真正会跑的那个版本），退回 module-tools
-// 自己的版本（同一次发布同版本，`^0.3.0` 这类范围对得上），两者都读不到时保持旧模板的
-// `^0.1.0` 并说一句人话 —— 静默盖个空范围会让生成的 package.json 声明一个谁也不认的依赖。
-// 为什么两个 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';
 
@@ -36,7 +23,7 @@ const dshUiVersion = (root) => {
       return { version: pinned, source: '外壳 manifest 里钉的（对账过的那版）' };
     }
   } catch {
-    // 读不到就走下面的兜底
+
   }
   console.error(
     `读不到外壳 manifest 里钉的 ${DSH_UI}：模板保持 ${FALLBACK_DSH_UI}（与外壳对账过的那版）；在装好依赖的工程里 init 就能盖上当下那版`,
@@ -95,9 +82,7 @@ export async function init({ root, args = [] }) {
     __SHELL_RANGE__: shellRange(root),
     __DSH_UI_VERSION__: dshUi.version,
   };
-  // 按**已知 token 名**逐个盖章，而不是按 `__[A-Z]+__` 的形状：名字里带下划线的 token
-  // （`__SHELL_RANGE__`）也要认；同时 DIY 模板 README 里真写着的 `workbench___UNIT___rebuild`
-  // 仍然只认内层那一个（按形状宽匹配会把三重下划线整段吞掉，工具名就盖不成 `workbench_demo_rebuild`）。
+
   const fill = (text) =>
     text.replace(new RegExp(Object.keys(tokens).join('|'), 'g'), (token) => tokens[token]);
   const templateDir = fileURLToPath(new URL(template, import.meta.url));