@dsh-workbench/module-tools 0.3.3 → 0.3.5

package/README.md

@@ -30,7 +30,7 @@ dsh-wb-module publish               # 发货前的清单：门禁 + 三张表 +
 | `cards` | 卡片渲染：**八态 × zh/en 各渲一遍**（外壳侧输入 idle / loading / loading-刷新保留旧值（含旧时间戳 `at`）/ ready / ready-空容器 / unreadable-error / unreadable-能力闸缺插件 / unreadable-能力闸缺命令；`useApiResource` 与 `useCapabilityGate` 由判据喂，`useUnitBoard` 用模块仓里装的那份**真壳**）—— 不许抛、不许空白、文字里不许出现 `undefined` / `NaN` / `[object Object]` / `null`、不许裸键名、要套外壳的卡壳、清单 `titleKey` 在两语字典里都有落点。**不断言"画的是哪一态那一屏"**（那归模块自己的逐态测试与 `design.json` 状态矩阵）；模块没装外壳时逐态那半跳过、单次全桩渲染照旧跑 |
 | `standalone` | 独立构建：产物不依赖工坊里跑 |
 | `markers` | 公开包无内部标识（内网域名、企业内部名） |
-| `style` | 样式归属：模块不许定义外壳类（`wb-*`）的规则（判据看**复合选择器**，`:global(.wb-x)` 也算，只有同一个复合选择器里带模块自己的类才放行）；**裸 `<a>` 与裸交互控件（`<button>` / `<input>` / `<select>`）都判红** —— 前者用 kit 的 `Link`，后者用 `Button` / `TextField` / `SelectField` / `ChoiceGroup`；只有 `<textarea>` 与 `input[type=hidden\|file]` 例外（两处都没有那种形态）；**手写的「标签 + 控件」行（标签元素紧邻 `SelectField` / `TextField` / `ChoiceGroup` / `Input`）与模块自己给 `field`/`form` 容器设的行距（`gap` / 上下 `margin`）也判红** —— 这一层归 kit 的 `FormRow(s)`（面 → 行 → 控件）；现存违规收进 `FORM_ROW_EXEMPT`（棘轮：迁一处删一行，且表里已经不再命中的行会当场报红）；**手写的操作区（借了 `wb-formActions` 槽类手摆按钮）也判红** —— 操作区归 kit 的 `FormActions`（顺序 / 一个区一颗 `primary` / `danger` 的位置 / 间距 / 窄容器换行都由它定，调用点只给数据与语义），现存违规收进 `FORM_ACTIONS_EXEMPT`（同一套棘轮：迁一处删一行，表里不再命中的行当场报红） |
+| `style` | 样式归属：模块不许定义外壳类（`wb-*`）的规则（判据看**复合选择器**，`:global(.wb-x)` 也算，只有同一个复合选择器里带模块自己的类才放行）；**裸 `<a>` 与裸交互控件（`<button>` / `<input>` / `<select>`）都判红** —— 前者用 kit 的 `Link`（**只判「正文里的文字链」那一种**；三种 `Link` 表达不了的形态不判、逐文件收在 `ANCHOR_EXEMPT` 里：**图标链**（`<a className="wb-iconButton">` 包一枚图标 —— `Link` 会多画一颗箭头）· **按钮皮的链**（`.anchorButton` 那类"看起来像按钮、实际是链接"，ADR-0054 §11 判过：必须是链接的动作留真 `<a>`，不许塞成 `window.open` 按钮）· **整行链**（`.issueLink` 那类 `flex: 1` / `color: inherit` 的行的布局槽）。`<a` **写在行尾**（属性在下一行）也算 —— 这条是**全文**匹配、不逐行，别改回去），后者用 `Button` / `TextField` / `SelectField` / `ChoiceGroup`；只有 `<textarea>` 与 `input[type=hidden\|file]` 例外（两处都没有那种形态）；**手写的「标签 + 控件」行（标签元素紧邻 `SelectField` / `TextField` / `ChoiceGroup` / `Input`）与模块自己给 `field`/`form` 容器设的行距（`gap` / 上下 `margin`）也判红** —— 这一层归 kit 的 `FormRow(s)`（面 → 行 → 控件）；现存违规收进 `FORM_ROW_EXEMPT`（棘轮：迁一处删一行，且表里已经不再命中的行会当场报红）；**手写的操作区（借了 `wb-formActions` 槽类手摆按钮）也判红** —— 操作区归 kit 的 `FormActions`（顺序 / 一个区一颗 `primary` / `danger` 的位置 / 间距 / 窄容器换行都由它定，调用点只给数据与语义），现存违规收进 `FORM_ACTIONS_EXEMPT`（同一套棘轮：迁一处删一行，表里不再命中的行当场报红）；**手写的整张表单也判红** —— 模块源码（`.tsx` / `.ts`，测试文件除外）里的**裸 `<form>` 元素**与**手写行的槽类 `wb-formRow` / `wb-formRows` / `wb-field`** 都算，整张表单的面（行的排布 / 校验的时机 / 错误摆哪 / 提交怎么被挡住 / 第一处错误怎么找 / 操作区怎么排）归 kit 的 `Form`（`fields` 进、其余全归它，调用点只给数据与语义），现存违规收进 `FORM_EXEMPT`（同一套棘轮：迁一处删一行，表里不再命中的行当场报红）；那一族判据**故意窄**（`wb-field` 后面跟着 `Label`/`Hint` 这些**兄弟**类的不算，测试文件也算在射程外），模块自己用 div 拼一张既没有 `<form>`、也没借槽类的表单**不判** —— 判宽了就是"用户每次改界面都先撞门禁"，已知漏报见 `style.mjs` 里那一段注释 |
 | `alias` | 模块不指外壳：源码里没有指向外壳 `@/` 的引用 |
 | `arch` | 模块自己的**分层形状**（下面单开一节）：层序表外的目录 / 反向依赖 / 跨运行时 / 巨文件 / 模型层没测试 / 样式里手搓数值与 `!important`。**只跑带 `arch.config.mjs` 的模块** —— 没有这份文件就是 `○ 不适用`，不是红 |
 | `lint` | 模块自己的**语法卫生**（下面单开一节）：`as any` / 残留 `console` / `debugger` / 内联颜色字面量 / 字符串里的 `!important` / react-hooks。**只跑带 `eslint.config.mjs` 的模块** —— 没有那份文件就是 `○ 不适用`，不是红；规则住在 module-tools 的方言里、随工具链同代 |

package/bin/dsh-wb-module.mjs

@@ -55,6 +55,9 @@ const commands = { build, check, init, design, publish, sync, lint };
 if (!command || !commands[command]) {
   console.error(`用法：dsh-wb-module <build|check|init|design|publish|sync|lint> [--cwd <目录>]
       dsh-wb-module check [--only ${Object.keys(CHECKS).join('|')}]
+      dsh-wb-module check --only kit                 # 单跑当查询口：这份外壳的 kit 里有什么（--file <名字> 给类型文件绝对路径）
+      dsh-wb-module check --only primitives [--all|--files|--json]
+                                                     # 单跑当查询口：dsh 原语里有什么 + --file <名字> 给类型文件绝对路径
       dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]
       dsh-wb-module design <init|check|render|accept>   # 三张表：填、查空格、生成 README、自验打勾
       dsh-wb-module sync                                 # 按清单生成 src/declared-tools.ts（工具名只有清单一处写者）

package/package.json

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

package/src/arch.mjs

@@ -49,6 +49,7 @@ import {
   styles,
 } from '@arch-guard/core/presets';
 import { DECLARED_TOOLS_FILE } from './declared-tools.mjs';
+import { SEED_SPECIFIERS } from './seed.mjs';
 
 // 两个面**就是** `dsh.workbenchFaces` 指的那两个文件（协议要求，见 ADR-0038）。改这两个名字
 // 等于改声明，判据（contracts / source）先红 —— 所以这里是常量，不是选项。
@@ -119,9 +120,28 @@ const STYLE_EXCEPTION = {
     'dsh 改名会由外壳升级暴露，而不是由模块本地的表兜住。',
 };
 
-// 模块包**运行时**允许的依赖：react（外壳经模块表提供）+ 外壳自己那两个包。
+// 模块包**运行时**允许的依赖：react（外壳经模块表提供）+ 外壳自己那两个包 + **平台种子词那一整族**。
+//
+// 种子词为什么要一起放进来（2026-10-19 补，用户口径「arch 没加依赖」）：那些包是 dsh 的模块表
+// 天生就提供的（`seed.mjs` 是唯一真相），模块引它们走 `dsh.client.external` 是**被允许的路**
+// （ADR-0028 §5 / ADR-0063）。但作者把它们写进 `dependencies` 时，P01 会报「未登记的运行时依赖」，
+// 而 arch-guard 给的那句修法是「加进 `deps({ allow })`」—— 对平台件这是**误导**：它逼每个模块
+// 为一条本来就合法的事开口子。所以这里按 `seed.mjs` 推导（dsh 加词，这张表自己跟着长），
+// 表外的包（真正的第三方 SDK）照旧要明着登记。
+//
+// 推荐写法仍是 **devDependency（类型）+ `dsh.client.external`**：放进 `dependencies` 不会报错，
+// 但 pnpm 会给模块装一份**运行时用不到的**副本（产物里是 `require`，实例由外壳给）。
+// 那是"浪费"不是"错误"，所以不由 arch 判；由 `check:source` / `check:primitives` 守真正的错误
+// （宿主侧碰它、漏声明 external、产物被内联）。
 // `@dsh-workbench/module-tools` 是构建/门禁工具，是 devDependency，不进这张表。
-const ALLOWED_DEPS = ['react', '@dsh-workbench/core', '@dsh-workbench/shared'];
+const SEED_PACKAGES = [
+  ...new Set(
+    SEED_SPECIFIERS.map((name) => (name.startsWith('@') ? name.split('/').slice(0, 2).join('/') : name.split('/')[0])),
+  ),
+];
+const ALLOWED_DEPS = [
+  ...new Set([...SEED_PACKAGES, '@dsh-workbench/core', '@dsh-workbench/shared']),
+];
 
 // 我们**不拥有**主题：颜色 / 圆角 / 字号 / 时长一律引用 dsh 的 `--dsw-*` 令牌，
 // 所以这里没有 tokenDir / palette（声明一个自己的令牌表就是编造一处不存在的真相，
@@ -150,7 +170,9 @@ const DESIGN = {
  * 复杂模块要开口子时**从参数进**（每条口子都有名字，评审时看得见），别改判据：
  *
  * - `fileLines` / `viewLines` / `functionLines`：放宽体积阈值（默认 200 / 200 / 80）
- * - `deps`：追加允许的运行时依赖（比如宿主侧接了某个 SDK）
+ * - `deps`：追加允许的运行时依赖（比如宿主侧接了某个 SDK）。dsh 的**平台种子词**
+ *   （`seed.mjs` 那一族：`react` / `zod` / `@deepseek-ai/dsh-client-*` …）与 `@dsh-workbench/*`
+ *   已经按种子表推导进表里，不用为它们开口子
  * - `roles`：追加角色（自定义目录 / 文件；`{ id, pattern, layer }`）。
  *   内置已有三条**文件级**角色：`src/messages.ts`、`src/declared-tools.ts`，以及 `__tests__/`
  *   目录下的文件（`src/` 内任意一层）—— 后两条一条是 `sync` 生成的、一条是方言声明的测试家，

package/src/check-flags.mjs

@@ -0,0 +1,22 @@
+// `dsh-wb-module check --only <名字>` 单跑时透传的开关。
+//
+// 聚合层只认 `--only` / `--cwd`，其余开关（`--all` / `--files` / `--json`）原样经
+// `DSH_WB_ONLY_ARGS`（JSON 数组）交给**单跑的那一条** —— 这是 `check.mjs` 的加法之一
+// （给 `run()` 加参数会让"所有判据都是无参 `run()`"这条统一形状多一个例外）。
+// 名字只有这一处写，别把环境变量名抄成第二份真相。
+export function flagsOf() {
+  try {
+    const parsed = JSON.parse(process.env.DSH_WB_ONLY_ARGS ?? '[]');
+    return Array.isArray(parsed) ? parsed.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** `--file <名字>` 那种带值的开关取它的值（没给值返回 undefined）。 */
+export function flagValue(flags, flag) {
+  const at = flags.indexOf(flag);
+  if (at === -1) return undefined;
+  const value = flags[at + 1];
+  return value === undefined || value.startsWith('--') ? undefined : value;
+}

package/src/check.mjs

@@ -19,6 +19,15 @@
 //     不适用 ○ <title>：（不适用）<notes>
 //     失败   ✖ <title> <N> 条不过：  然后逐条 `  · <problem>`
 // 最后一行是汇总；有任何 fail 就 exit 1。
+//
+// ── 两条加法（2026-10-19，dsh-primitives-face）────────────────────────────────
+//
+//   ① 开关透传：聚合层只认 `--only` / `--cwd`，其余开关（`--all` / `--json`）原样经
+//      `DSH_WB_ONLY_ARGS`（JSON 数组）交给**单跑的那一条**。为什么走 env 而不是给 `run()`
+//      加参数：所有判据的形状都是 `run()` 无参，加参数会让"统一形状"这条纪律多一个例外。
+//   ② 可选 `payload`：判据可以额外返回 `payload`；带着 `--json` 跑时，聚合层打它、**跳过**
+//      人话版 report 与最后的汇总行（stdout 只有一份 JSON）。老判据不返回它，行为一字不变 ——
+//      这是加法，不是新形状。
 
 // 名字与 title 一字不变 —— selfcheck 会把它与各判据模块导出的 `title` 逐个对一遍。
 export const CHECKS = {
@@ -58,11 +67,13 @@ function report(title, result) {
   for (const note of notes.slice(1)) console.log(`  ${note}`);
 }
 
-export async function check({ only } = {}) {
+export async function check({ only, args = [] } = {}) {
   const names = only === undefined ? Object.keys(CHECKS) : [only];
+  const jsonMode = args.includes('--json');
   const tally = { pass: 0, skip: 0, fail: 0 };
   const skipped = [];
   let ran = 0;
+  process.env.DSH_WB_ONLY_ARGS = JSON.stringify(args);
   try {
     for (const name of names) {
       const entry = CHECKS[name];
@@ -89,10 +100,18 @@ export async function check({ only } = {}) {
       }
       tally[result.status] += 1;
       if (result.status === 'skip') skipped.push(`${title}（${result.notes[0] ?? ''}）`);
-      report(title, result);
+      if (jsonMode && result.payload !== undefined) console.log(JSON.stringify(result.payload, null, 2));
+      else report(title, result);
     }
   } finally {
     process.env.DSH_WB_ONLY = '';
+    process.env.DSH_WB_ONLY_ARGS = '';
+  }
+
+  // `--json` 的 stdout 只有那几份 payload：汇总行与"不适用"那几段都是人话，不进机器档。
+  if (jsonMode) {
+    if (tally.fail > 0) process.exit(1);
+    return;
   }
 
   console.log(`${ran} 条判据：${tally.pass} 通过 · ${tally.skip} 不适用 · ${tally.fail} 不过`);

package/src/checks/kit.mjs

@@ -22,7 +22,9 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { flagValue, flagsOf } from '../check-flags.mjs';
 import { discoverModulePackages } from '../discover.mjs';
+import { memberFilesOf } from '../shell-type-files.mjs';
 import { shellClientPathOf, shellKitOf } from './shell-artifact.mjs';
 
 const SHELL = '@dsh-workbench/core';
@@ -82,14 +84,19 @@ function below(a, b) {
 // 只在单跑时打：外壳把整份 `@dsh-workbench/shared` barrel 摊进了每个桶，所以这份名单
 // 有一百多个名字 —— 聚合跑时它只是噪音，查询时才值钱。
 //
-// 返回的是若干 `notes`（每条一行，交给聚合层加缩进），而不是打印 —— 打印归 check.mjs。
+// 名字还要能落到**文件**（"想问哪个直接去看"）：默认打两棵类型树的绝对根 + 取法，
+// `--files` 打逐条 `名字 → 绝对路径`（190 条 / ~9k 字符，会被 tool-result-pruner 裁中间，
+// 所以它得配 `| grep <名字>` 用，默认档不内联）。`--json` 给机器档。
+//
+// 返回的是 `{ notes, payload }`（notes 每条一行，交给聚合层加缩进；payload 归 `--json`）——
+// 打印归 check.mjs。
 function faceNotes(asked, shells) {
   const faceShell = shells[shells.length - 1] ?? shellClientPathOf(process.cwd());
   if (!asked) {
-    return ['（想知道这份外壳的 kit 里有什么：dsh-wb-module check --only kit）'];
+    return { notes: ['（想知道这份外壳的 kit 里有什么：dsh-wb-module check --only kit）'] };
   }
   if (faceShell === undefined || !existsSync(faceShell)) {
-    return ['（没找到外壳的 client.js，列不出 kit 面：先确认 node_modules 里装着 @dsh-workbench/core）'];
+    return { notes: ['（没找到外壳的 client.js，列不出 kit 面：先确认 node_modules 里装着 @dsh-workbench/core）'] };
   }
   try {
     const kit = shellKitOf(faceShell);
@@ -97,23 +104,59 @@ function faceNotes(asked, shells) {
       .filter((bucket) => typeof kit[bucket] === 'object' && kit[bucket] !== null)
       .sort();
     if (buckets.length === 0) {
-      return [`（${faceShell} 里没取出 kit：外壳版本可能太旧）`];
+      return { notes: [`（${faceShell} 里没取出 kit：外壳版本可能太旧）`] };
     }
     const every = new Map();
     for (const bucket of buckets) {
       for (const name of Object.keys(kit[bucket])) every.set(name, (every.get(name) ?? 0) + 1);
     }
-    const notes = [`这份外壳（${faceShell}）的 kit 面 —— 只能用这些，别自己造：`];
-    for (const bucket of buckets) {
-      const names = Object.keys(kit[bucket]);
-      const only = names.filter((name) => every.get(name) === 1).sort();
-      notes.push(`  ${bucket}(${names.length})：${only.length === 0 ? '（全部来自下面的共用面）' : only.join(', ')}`);
+    const flags = flagsOf();
+    const one = flagValue(flags, '--file');
+    const { roots, files, missing } = memberFilesOf(faceShell, [...every.keys()]);
+    const rootLine =
+      Object.entries(roots).length === 0
+        ? '  类型面：读不到（外壳包里没有 dist/types，@dsh-workbench/shared 也没装）'
+        : `  类型面（绝对路径）：${Object.entries(roots).map(([pkg, dir]) => `${pkg} → ${dir}`).join(' ｜ ')}` +
+          ` （某个名字的文件：--file <名字>，或 --files | grep <名字>）`;
+
+    const notes = [`这份外壳（${faceShell}）的 kit 面 —— 只能用这些，别自己造：`, rootLine];
+    if (one !== undefined) {
+      const file = files.get(one);
+      notes.push(
+        file === undefined
+          ? `  --file ${one}：不在这份清单里（用 --files | grep ${one} 找找近似的名字）`
+          : `  --file ${one}：${file} （打开看它的 JSDoc 与 prop：sed -n '1,60p' 那一份）`,
+      );
+    }
+    if (flags.includes('--files')) {
+      notes.push(
+        `  名字 → 类型文件（绝对路径，全表 ${every.size} 条、会被 tool-result-pruner 裁中间：用 --files | grep <名字> 取一件）`,
+      );
+      for (const name of [...every.keys()].sort()) {
+        notes.push(`    ${name} → ${files.get(name) ?? '（没扫到，见上面那两棵根）'}`);
+      }
+      if (missing.length > 0) notes.push(`  ${missing.length} 个没扫到：${missing.join('、')}`);
+    } else if (one === undefined) {
+      for (const bucket of buckets) {
+        const names = Object.keys(kit[bucket]);
+        const only = names.filter((name) => every.get(name) === 1).sort();
+        notes.push(`  ${bucket}(${names.length})：${only.length === 0 ? '（全部来自下面的共用面）' : only.join(', ')}`);
+      }
+      const shared = [...every.entries()].filter(([, count]) => count > 1).map(([name]) => name).sort();
+      notes.push(`  共用面(${shared.length})：每个桶里都有 —— ${shared.join(', ')}`);
     }
-    const shared = [...every.entries()].filter(([, count]) => count > 1).map(([name]) => name).sort();
-    notes.push(`  共用面(${shared.length})：每个桶里都有 —— ${shared.join(', ')}`);
-    return notes;
+    return {
+      notes,
+      payload: {
+        shell: faceShell,
+        roots,
+        buckets: Object.fromEntries(buckets.map((bucket) => [bucket, Object.keys(kit[bucket])])),
+        files: Object.fromEntries([...every.keys()].sort().map((name) => [name, files.get(name) ?? null])),
+        missing,
+      },
+    };
   } catch (error) {
-    return [`（取不出这份外壳的 kit 面：${error instanceof Error ? error.message : String(error)}）`];
+    return { notes: [`（取不出这份外壳的 kit 面：${error instanceof Error ? error.message : String(error)}）`] };
   }
 }
 
@@ -183,19 +226,25 @@ export async function run() {
     }
   }
 
-  if (problems.length > 0) {
-    return { status: 'fail', notes: [], problems };
-  }
-
   const asked = process.env.DSH_WB_ONLY === 'kit';
   const face = faceNotes(asked, shells);
+  const payload = face.payload === undefined ? {} : { payload: face.payload };
+
+  if (problems.length > 0) {
+    // 清单是**事实**、红是**判据**：判据红不该把清单一起扣下。`--json` 的消费者（工坊那把
+    // `workbench_diy_components`）要靠这份机器档回答"这份外壳有哪些件"，而判据红经常是**别的
+    // 模块**的事 —— 2026-10-20 真机：三个模块用了 MockStrip / useFixturePick，工具整条查询直接
+    // 报错、agent 什么也没拿到。退出码照旧 1（红没被藏起来），problems 也一起进机器档。
+    const extra = face.payload === undefined ? {} : { payload: { ...face.payload, problems } };
+    return { status: 'fail', notes: [], problems, ...extra };
+  }
 
   if (inspected === 0) {
     const why =
       modulePackages.length === 0
         ? '没有模块包（没有声明 dsh.workbench 的包）—— 没有产物可对'
         : `${noArtifact} 个还没建产物（跳过）`;
-    return { status: 'skip', notes: [why, ...face], problems: [] };
+    return { status: 'skip', notes: [why, ...face.notes], problems: [], ...payload };
   }
 
   const notes = [
@@ -204,5 +253,5 @@ export async function run() {
   ];
   if (noArtifact > 0) notes.push(`${noArtifact} 个还没建产物（跳过）`);
   if (noShell > 0) notes.push(`${noShell} 个没装外壳（跳过面差）`);
-  return { status: 'pass', notes: [...notes, ...face], problems: [] };
+  return { status: 'pass', notes: [...notes, ...face.notes], problems: [], ...payload };
 }

package/src/checks/primitives.mjs

@@ -12,16 +12,46 @@
 //
 // 判据跟着 `dsh.workbench` 自述清单走：没用 dsh 原语的模块直接跳过（0 命中 = 通过）。
 //
+// ── 查询口：`check --only primitives` 单跑时顺带当"dsh 原语里有什么"的取数处 ──────────────
+//
+// 与 `--only kit` 同一个惯例（`kit.mjs` 的 faceNotes）：单跑时把**能用的东西**列出来，
+// 聚合跑时只留一句提示。这份清单的真相只有一处 —— 装机包里那份类型面
+// （`lib/types/**/*.d.ts`；源码树不随包发布），详见 `../primitives-surface.mjs` 与
+// `.scratch/dsh-primitives-face/spec.md`。
+//
+// 为什么放在这条判据里：它本来就要按模块逐个解析种子词的声明与产物，而"有哪些名字可用"正是
+// 造模块的人（尤其 DIY 工坊里那位）要的那件事；单开一个顶层命令要多一处分发、一处用法文案、
+// 一处文档，而这里的机制（`DSH_WB_ONLY`）已经在了。
+//
 // 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
-// 打印与退出码归 `../check.mjs` 那一层。
+// 打印与退出码归 `../check.mjs` 那一层。`--json` 时聚合层打 `payload`（见 `check.mjs` 头注释）。
 
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
+import { flagValue, flagsOf } from '../check-flags.mjs';
 import { discoverModulePackages } from '../discover.mjs';
+import {
+  PRIMITIVES_SPECIFIER,
+  installedPrimitives,
+  pinnedPrimitivesVersion,
+  surfaceOf,
+} from '../primitives-surface.mjs';
 import { BROWSER_SEED_SPECIFIERS, SEED_SPECIFIERS } from '../seed.mjs';
+import { shellClientPathOf, shellKitOf } from './shell-artifact.mjs';
 
 const IMPORT = /from\s*'([^']+)'|import\s*\(?\s*'([^']+)'/g;
 const SEED = new Set(SEED_SPECIFIERS);
+const SHELL = '@dsh-workbench/core';
+
+/** 摘要档每个桶最多列几个名字；`--all` 去掉截断。 */
+const SUMMARY_PER_BUCKET = 12;
+const BUCKETS = [
+  ['components', 'components'],
+  ['icons', 'icons'],
+  ['hooks', 'hooks'],
+  ['lib', 'lib'],
+];
 
 /** 短名写法（`ui-primitives`）也算声明过 —— 老包里有这种写法，不该因为写法短被判红。 */
 function declares(declared, specifier) {
@@ -46,8 +76,203 @@ function sourceFiles(dir, acc = []) {
 
 export const title = 'dsh 原语只从模块表拿';
 
+/** 从 `from` 找到一份能解析到的原语包：先看模块包自己装的，再看当前 cwd。 */
+function primitivesFrom(modulePackages) {
+  for (const pkg of modulePackages) {
+    const found = installedPrimitives(pkg.dir);
+    if (found !== undefined) return { ...found, from: pkg.dir };
+  }
+  const here = installedPrimitives(process.cwd());
+  return here === undefined ? undefined : { ...here, from: process.cwd() };
+}
+
+/** 外壳 manifest 的路径（那份 `devDependencies` 里钉着原语版本）。 */
+function shellManifestOf(from) {
+  try {
+    return createRequire(join(from, 'package.json')).resolve(`${SHELL}/package.json`);
+  } catch {
+    return undefined;
+  }
+}
+
+/** 外壳 kit 的成员表：`名字 → 桶`（取不到就空表 —— 求交只是锦上添花，不该把查询口弄崩）。 */
+function kitMembersOf(from) {
+  const client = shellClientPathOf(from);
+  if (client === undefined || !existsSync(client)) return new Map();
+  try {
+    const kit = shellKitOf(client);
+    const members = new Map();
+    for (const [bucket, value] of Object.entries(kit)) {
+      if (typeof value !== 'object' || value === null) continue;
+      for (const name of Object.keys(value)) if (!members.has(name)) members.set(name, bucket);
+    }
+    return members;
+  } catch {
+    return new Map();
+  }
+}
+
+function truncated(names, all) {
+  if (all || names.length <= SUMMARY_PER_BUCKET) return names.join(', ');
+  return `${names.slice(0, SUMMARY_PER_BUCKET).join(', ')} …（还有 ${names.length - SUMMARY_PER_BUCKET} 个，加 --all 看全表）`;
+}
+
+/**
+ * 单跑这一条时的清单。返回 `{ notes, payload }`：
+ * notes 是人话（聚合层逐行打），payload 是 `--json` 的机器档。
+ */
+function faceOf(modulePackages) {
+  const flags = flagsOf();
+  const all = flags.includes('--all');
+  const from = primitivesFrom(modulePackages) ?? { from: process.cwd() };
+  const shellManifest = shellManifestOf(from.from);
+  const pinned = shellManifest === undefined ? undefined : pinnedPrimitivesVersion(shellManifest);
+  const shellVersion = shellManifest === undefined ? undefined : versionOf(shellManifest);
+
+  const declaredLines = [];
+  const modules = [];
+  for (const pkg of modulePackages) {
+    const declared = pkg.manifest.devDependencies?.[PRIMITIVES_SPECIFIER];
+    modules.push({ name: pkg.manifest.name, declared: declared ?? null });
+    if (declared !== undefined) declaredLines.push(`${pkg.manifest.name} → ${declared}`);
+  }
+  const drift =
+    pinned === undefined ? [] : modules.filter((one) => one.declared !== null && one.declared !== pinned);
+  const moduleLine =
+    declaredLines.length > 0
+      ? `模块声明：${declaredLines.join(' ｜ ')}` +
+        (drift.length > 0
+          ? ` ⚠️ 与外壳钉的 ${pinned} 不一致（只提醒，不判红；对齐它的写法见下面那段）`
+          : '')
+      : '模块声明：（还没有模块声明它 —— 模板生成的骨架默认带这一行）';
+
+  const installed = installedPrimitives(from.from);
+  if (installed === undefined) {
+    const want = pinned ?? '<外壳钉的那版>';
+    const notes = [
+      `这份工程里没装 ${PRIMITIVES_SPECIFIER} —— 列不出清单。`,
+      `  它在 @deepseek-ai/dsh-client-ui-primitives 那个包的 lib/types/**/*.d.ts 里（源码不随包发布）。`,
+      `  先加一行再 pnpm install：`,
+      `    "devDependencies": { "${PRIMITIVES_SPECIFIER}": "${want}" }`,
+      `  两个模板默认带这一行；加完在 dsh.client.external 里也声明 "${PRIMITIVES_SPECIFIER}"（两处都要）。`,
+    ];
+    if (pinned !== undefined) notes.push(`  外壳（${SHELL}${shellVersion === undefined ? '' : `@${shellVersion}`}）钉的是 ${pinned} —— 对齐它。`);
+    return { notes, payload: { installed: null, pinned: pinned ?? null, modules, snippet: devDependencySnippet(want) } };
+  }
+
+  let surface;
+  try {
+    surface = surfaceOf(join(installed.dir, 'lib', 'types'));
+  } catch (error) {
+    return {
+      notes: [
+        `装了 ${PRIMITIVES_SPECIFIER}@${installed.version}，但读不出类型面：${error instanceof Error ? error.message : String(error)}`,
+        `  上游可能换了 emit 形状 —— 先打开 ${join(installed.dir, 'lib', 'types', 'index.d.ts')} 看一眼，再改 ../primitives-surface.mjs`,
+      ],
+      payload: { installed: { version: installed.version, dir: installed.dir }, pinned: pinned ?? null, modules, error: String(error) },
+    };
+  }
+
+  const kit = from.from === undefined ? new Map() : kitMembersOf(from.from);
+  const covered = [];
+  const only = { components: [], icons: [], hooks: [], lib: [] };
+  for (const [bucket] of BUCKETS) {
+    for (const name of surface[bucket]) {
+      if (kit.has(name)) covered.push({ name, bucket: kit.get(name) });
+      else only[bucket].push(name);
+    }
+  }
+  covered.sort((a, b) => a.name.localeCompare(b.name));
+
+  const notes = ['这份装机包的 dsh 原语面（kit 里没有的才用它）：'];
+  notes.push(`  装机：${installed.version}`);
+  notes.push(`  类型面（绝对路径）：${join(installed.dir, 'lib', 'types')} （某个名字的文件：--files | grep <名字>）`);
+  notes.push(
+    pinned === undefined
+      ? `  外壳钉的：读不到（${shellManifest ?? '找不到 @dsh-workbench/core 的 manifest'}）`
+      : `  外壳钉的：${pinned}${shellVersion === undefined ? '' : `（${SHELL}@${shellVersion} 的 devDependencies）`}${pinned === installed.version ? '' : ' ⚠️ 与装机那份不一致'}`,
+  );
+  notes.push(`  ${moduleLine}`);
+  const one = flagValue(flags, '--file');
+  if (one !== undefined) {
+    const file = surface.files[one];
+    notes.push(
+      file === undefined
+        ? `  --file ${one}：不在这份清单里（用 --files | grep ${one} 找找近似的名字）`
+        : `  --file ${one}：${file} （打开看它的 JSDoc 与 prop：sed -n '1,60p' 那一份）`,
+    );
+  }
+  if (flags.includes('--files')) {
+    notes.push(
+      `  名字 → 类型文件（绝对路径，全表约 ${Object.keys(surface.files).length} 条、会被 tool-result-pruner 裁中间：用 --files | grep <名字> 取一件）`,
+    );
+    const iconsFile = surface.files[surface.icons[0]];
+    for (const [bucket] of BUCKETS) {
+      const names = only[bucket];
+      if (names.length === 0) continue;
+      if (bucket === 'icons') {
+        notes.push(`    ${bucket}(${names.length})：全部在 ${iconsFile ?? '？'}`);
+        continue;
+      }
+      for (const name of names) notes.push(`    ${name} → ${surface.files[name] ?? '？'}`);
+    }
+  } else if (one === undefined) {
+    notes.push(
+      covered.length === 0
+        ? '  kit 里已有（优先用 kit）：（这份外壳的 kit 里没有同名的，下面这些都得引原语）'
+        : `  kit 里已有（优先用 kit，别重复引原语）：${truncated(covered.map((one) => `${one.name}(${one.bucket})`), all)}`,
+    );
+    notes.push(`  只有原语有（用之前先在 dsh.client.external 里声明 "${PRIMITIVES_SPECIFIER}"）：`);
+    for (const [bucket] of BUCKETS) {
+      const names = only[bucket];
+      if (names.length === 0) continue;
+      notes.push(`    ${bucket}(${names.length})：${truncated(names, all)}`);
+    }
+  }
+  if (one === undefined) {
+    notes.push('  package.json 两处这样写：');
+    notes.push(`    "dsh": { "client": { "external": [ …, "${PRIMITIVES_SPECIFIER}" ] } }`);
+    notes.push(`    "devDependencies": { "${PRIMITIVES_SPECIFIER}": "${pinned ?? installed.version}" }${pinned !== undefined && pinned !== installed.version ? '  ← 与外壳对齐的那版' : ''}`);
+  }
+
+  return {
+    notes,
+    payload: {
+      installed: { version: installed.version, dir: installed.dir },
+      roots: { primitives: join(installed.dir, 'lib', 'types') },
+      files: surface.files,
+      pinned: pinned ?? null,
+      shellVersion: shellVersion ?? null,
+      modules,
+      kitCovered: covered,
+      onlyPrimitives: only,
+      counts: { total: surface.total, ...Object.fromEntries(BUCKETS.map(([bucket]) => [bucket, only[bucket].length])) },
+      snippet: devDependencySnippet(pinned ?? installed.version),
+    },
+  };
+}
+
+function devDependencySnippet(version) {
+  return {
+    external: PRIMITIVES_SPECIFIER,
+    devDependency: { name: PRIMITIVES_SPECIFIER, version },
+  };
+}
+
+function versionOf(manifestPath) {
+  try {
+    const version = JSON.parse(readFileSync(manifestPath, 'utf8')).version;
+    return typeof version === 'string' ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function run() {
   const modulePackages = discoverModulePackages({ root: process.cwd() });
+  const face = process.env.DSH_WB_ONLY === 'primitives'
+    ? faceOf(modulePackages)
+    : { notes: ['（想知道 dsh 原语里有什么：dsh-wb-module check --only primitives）'], payload: undefined };
   const problems = [];
   let modulesUsingPrimitives = 0;
   let modulesUsingReactOnly = 0;
@@ -113,21 +338,28 @@ export async function run() {
     }
   }
 
+  const payload = face.payload === undefined ? {} : { payload: face.payload };
+
   if (problems.length > 0) {
-    return { status: 'fail', notes: [], problems };
+    return { status: 'fail', notes: face.notes, problems, ...payload };
   }
   if (modulePackages.length === 0) {
     return {
       status: 'skip',
-      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有 dsh 原语的声明与产物可对'],
+      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有 dsh 原语的声明与产物可对', ...face.notes],
       problems: [],
+      ...payload,
     };
   }
   if (modulesTouchingSeeds === 0) {
     return {
       status: 'skip',
-      notes: ['没有模块用到平台种子词（react / react-dom / dsh 的浏览器包）—— 没有可对照的声明与产物'],
+      notes: [
+        '没有模块用到平台种子词（react / react-dom / dsh 的浏览器包）—— 没有可对照的声明与产物',
+        ...face.notes,
+      ],
       problems: [],
+      ...payload,
     };
   }
   return {
@@ -135,7 +367,9 @@ export async function run() {
     notes: [
       `${modulesUsingPrimitives} 个模块在用 dsh 的包（都声明了 external、产物里都是 ` +
         `require、宿主产物里没有它们）· 另有 ${modulesUsingReactOnly} 个模块只用到 react/react-dom`,
+      ...face.notes,
     ],
     problems: [],
+    ...payload,
   };
 }