@dsh-workbench/module-tools 0.3.3 → 0.3.4

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.4",
   "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.4"
   },
   "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,
   };
 }

package/src/design.mjs

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

package/src/discover.mjs

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

package/src/init.mjs

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

package/src/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 };
+}

package/src/shell-type-files.mjs

@@ -0,0 +1,103 @@
+// kit 成员 → 类型文件：外壳那两个包的类型树（`@dsh-workbench/shared` 的 `dist` 与外壳自己的 `dist/types`）。
+//
+// 为什么要扫：kit 的成员是**运行期**从外壳产物 `client.js` 里跑出来的（见 `checks/kit.mjs`），
+// 产物里没有"这个成员来自哪个模块"；而类型树里每个成员的声明都躺在某份 `.d.ts` 里 ——
+// 扫一遍就能把"名字"落到"文件"，于是 agent「想问哪个直接去看那份文件」有确切路径。
+//
+// 为什么是名字扫描而不是真正的类型解析：这些 `.d.ts` 是 tsc 生成的、声明形状规整
+// （`export declare const X` / `export interface X` / `export { X } from '…'`），而 kit 的成员
+// 本来就是运行期对象上的键名。扫描不引 TypeScript 依赖、贵在稳；代价是"同名声明出现在多处"时
+// 要挑一个（挑法见 `preferred`），以及极少数成员指到的是 barrel 而不是最终实现文件。
+// 实测本机 190 个 kit 成员 190 个都落得到文件（见 `.scratch/dsh-primitives-face/verify.md` §2）。
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const PATTERNS = [
+  /^export declare (?:const|function|class) (\w+)/gm,
+  /^export (?:interface|type) (\w+)/gm,
+  /^export \{([^}]*)\}/gm,
+  /^declare (?:const|function|class) (\w+)/gm,
+  /^(?:interface|type) (\w+)/gm,
+];
+
+function walk(dir, acc = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, acc);
+    else if (full.endsWith('.d.ts')) acc.push(full);
+  }
+  return acc;
+}
+
+function namesIn(clause) {
+  if (!clause.includes(',') && !clause.includes(' ')) return [clause];
+  return clause
+    .split(',')
+    .map((raw) => raw.trim().split(/\s+as\s+/).pop().trim())
+    .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+}
+
+/** 外壳那两个包的类型树（`shared` 没装就只给外壳那棵）。 */
+export function shellTypeRoots(shellClientPath) {
+  const shellRoot = dirname(shellClientPath);
+  const roots = {};
+  const shellTypes = join(shellRoot, 'dist', 'types');
+  if (existsSync(shellTypes)) roots.shell = shellTypes;
+  // 打印用"从 node_modules 看"的那条路径（pnpm 的真身在 `.pnpm/` 哈希目录里）；读文件两条都行。
+  const viaNodeModules = join(shellRoot, 'node_modules', '@dsh-workbench', 'shared', 'dist');
+  try {
+    // 解析 "." 那个入口（= `dist/index.js`）再取 dirname —— shared 的 `exports` 里**没有**
+    // `./package.json` 这一条，直接 resolve 它的 package.json 会 ERR_PACKAGE_PATH_NOT_EXPORTED。
+    const sharedEntry = createRequire(join(shellRoot, 'package.json')).resolve('@dsh-workbench/shared');
+    const sharedTypes = dirname(sharedEntry);
+    if (existsSync(sharedTypes)) roots.shared = existsSync(viaNodeModules) ? viaNodeModules : sharedTypes;
+  } catch {
+    // 没装 shared：只有外壳自己那棵，仍然能落一部分成员
+  }
+  return { shellRoot, roots };
+}
+
+/** 同名多处时挑哪个：组件 > hooks > 库 > 其他，同档挑路径短的。 */
+function preferred(candidates) {
+  const rank = (file) =>
+    file.includes('/components/') ? 0 : file.includes('/hooks/') ? 1 : file.includes('/lib/') ? 2 : 3;
+  return [...candidates].sort((a, b) => rank(a.file) - rank(b.file) || a.file.length - b.file.length)[0];
+}
+
+/**
+ * 把 kit 的成员名落到类型文件。
+ * 返回 `{ roots, files: Map<名字, 绝对路径>, missing: 名字[] }` —— `roots` 是两棵类型树的绝对根。
+ */
+export function memberFilesOf(shellClientPath, names) {
+  const { roots } = shellTypeRoots(shellClientPath);
+  const index = new Map();
+  for (const root of Object.values(roots)) {
+    for (const file of walk(root)) {
+      let text;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const pattern of PATTERNS) {
+        for (const match of text.matchAll(pattern)) {
+          for (const name of namesIn(match[1])) {
+            if (!index.has(name)) index.set(name, []);
+            const found = index.get(name);
+            if (!found.some((one) => one.file === file)) found.push({ file });
+          }
+        }
+      }
+    }
+  }
+  const files = new Map();
+  const missing = [];
+  for (const name of names) {
+    const candidates = index.get(name);
+    if (candidates === undefined || candidates.length === 0) missing.push(name);
+    else files.set(name, preferred(candidates).file);
+  }
+  return { roots, files, missing };
+}

package/template/package.json.tpl

@@ -23,7 +23,7 @@
     "client": {
       "platform": "web",
       "inject": ["@dsh-workbench/core"],
-      "external": ["@dsh-workbench/core/client"]
+      "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
     },
     "workbench": {
       "apiVersion": 1,
@@ -37,6 +37,7 @@
   "peerDependencies": { "@dsh-workbench/core": "__SHELL_RANGE__", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "__DSH_UI_VERSION__",
     "@dsh-workbench/core": "__SHELL_RANGE__",
     "@dsh-workbench/module-tools": "__SHELL_RANGE__",
     "@types/node": "^24.19.0",

package/template-diy/package.json.tpl

@@ -24,7 +24,7 @@
     "client": {
       "platform": "web",
       "inject": ["@dsh-workbench/core"],
-      "external": ["@dsh-workbench/core/client"]
+      "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
     },
     "workbench": {
       "apiVersion": 1,
@@ -38,6 +38,7 @@
   "peerDependencies": { "@dsh-workbench/core": "__SHELL_RANGE__", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "__DSH_UI_VERSION__",
     "@dsh-workbench/core": "__SHELL_RANGE__",
     "@dsh-workbench/module-tools": "__SHELL_RANGE__",
     "@types/node": "^24.19.0",