@dsh-workbench/module-tools 1.1.13 → 1.1.14-beta.0

package/README.md

@@ -6,14 +6,13 @@
 ## 六条命令走一遍
 
 ```bash
-pnpm exec dsh-wb-module init my-unit --template diy   # 建骨架（minimal 是默认）
-cd my-unit && pnpm install
+pnpm exec dsh-wb-module init my-unit                    # 建骨架（唯一模板，已默认）
 pnpm build        # dist/host.js + 套了 loader 壳的 client.js
 pnpm check        # 十三条判据
 pnpm design check # 设计底稿有没有空格、README 有没有落后
 ```
 
-要发货再加一步 `pnpm publish`：跑门禁、核 `files` 与 `npm pack` 清单，**只 dry run，不真发**。
+要发货再加一步 `pnpm exec dsh-wb-module publish`：跑门禁、核 `files` 与 `npm pack` 清单，默认 **只 dry run，不真发**。
 维护者确认要真发时跑 `pnpm exec dsh-wb-module release`：全门禁（build / check / design / typecheck / test / selfcheck）、
 验收必须全勾、预检（登录 / license / git 远端）、按 `--target` 发到团队源 / 公网 npm / 安装包 / git，
 最后从出口侧核包（`--dry-run` 只预览，`--verify` 只核已发布的包）。配了可写 git 索引源时，
@@ -23,7 +22,7 @@ pnpm design check # 设计底稿有没有空格、README 有没有落后
 空仓库先跑 `dsh-wb-module market-init <git 地址>`：生成索引目录 `market/` 与 README 并推首个 commit
 （用仓库声明的默认分支，读不到时用 `--ref` 指定）。在工作台里配了可写索引源之后，
 `release` 默认出口就是 `market`：产物与索引一起进那个仓库。
-发布过程中每一步都写进 `~/.dsh/workbench/releases/<unit>.json`；中断后带 `--resume` 接着发
+发布过程中每一步都写进 `$DSH_WORKBENCH_HOME/releases/<unit>.json`（默认 `~/.dsh/workbench`）；中断后带 `--resume` 接着发
 （沿用记录里的出口、版本与索引计划，产物没变就不重跑门禁）。
 这一版在 `CHANGELOG.md` 里没有记录时，带 `--changelog-note "这一版改了什么"`
 （`--changelog-type` 选分类，缺省 changed）发一次就写进去，文件不在会先建骨架；
@@ -48,18 +47,26 @@ pnpm design check # 设计底稿有没有空格、README 有没有落后
 
 | 命令 | 作用 |
 |---|---|
-| `dsh-wb-module init <unit> [--dir <目录>] [--template minimal\|diy] [--description "一句话"]` | 建模块骨架 |
+| `dsh-wb-module init <unit> [--dir <目录>] [--template diy] [--description "一句话"]` | 建模块骨架（只有 `diy` 一个模板，也是默认） |
 | `dsh-wb-module market-init <git 地址\|目录> [--ref <分支>] [--path <索引路径>]` | 初始化市场索引仓库：写 `market/` + README，推首个 commit |
 | `dsh-wb-module build` | 出 `dist/host.js`（单文件 ESM）与 `client.js`（套 loader 壳） |
-| `dsh-wb-module check [--only <判据>]` | 十三条判据；`--only` 单跑，也当查询口用；`--list [--json\|--markdown]` 只列判据元数据 |
+| `dsh-wb-module check [--only <判据>] [--package <包名或 unit>]` | 十三条判据；`--only` 单跑，也当查询口用；`--package` 只报这个模块的问题（见下）；`--list [--json\|--markdown]` 只列判据元数据 |
 | `dsh-wb-module lint [--fix]` | 用模块自己那份 `eslint.config.mjs`；`--fix` 写回文件 |
 | `dsh-wb-module sync` | 按清单生成 `src/declared-tools.ts`，按 `design.json` 的 `key + recipe` 生成 `src/datasource.ts` |
 | `dsh-wb-module design <init\|check\|render\|accept>` | 设计底稿：填、查空格、生成 README、验收打勾 |
+| `dsh-wb-module migrate [--dry-run]` | 把模块清单迁到当前代：`apiVersion` → 3、缺/空的 `workbenchFaces` 补默认；源码类问题只给提示（check 会点名） |
 | `dsh-wb-module changelog check [版本]` | 查这一版有没有记录；发布时用 `release --changelog-note` 写进去 |
 | `dsh-wb-module publish` | 发货前清单：门禁 + `files` + `npm pack`（只 dry run） |
 | `dsh-wb-module release` | 真发布：team / public / tarball / git；全门禁 + 验收闸 + 预检接管 + 发后核包 + 更新市场索引（`--dry-run` / `--verify`） |
 
-`--cwd <目录>` 指定包目录，默认当前目录。
+`--cwd <目录>` 指定**工作目录**，默认当前目录。注意判据仍按**工作区**发现模块：往上找
+`pnpm-workspace.yaml`（或 `package.json` 的 `workspaces`），按它声明的 glob 展开包目录
+（`packages/**`、`apps/*`、多层目录都行；没有声明时退回 `packages/*`）——`--cwd` 不会把范围缩到一个模块。
+只想看自己那个模块用 `check --package <包名或 unit>`。
+
+`--package` 是**开发期便利**，不是门禁：它仍全量扫描、只过滤报告与退出码，所以
+「我这个模块绿」不等于「工作区绿」。门禁 / 发布 / release 不要带它。要只让判据看见一个包，
+用环境变量 `DSH_WB_ROOT=<包目录>`（工具链自己的自检就是这么隔离的）。
 
 ## 十三条判据
 
@@ -70,7 +77,7 @@ pnpm design check # 设计底稿有没有空格、README 有没有落后
 <!-- dsh-wb-module:begin checks -->
 | 判据 | 层 | 摘要 |
 |---|---|---|
-| `contracts` | manifest | 单元 id、两个面、四个脚本、files、peer 下限，以及清单与代码注册对账 |
+| `contracts` | manifest | 单元 id、两个面、四个脚本、peer 依赖存在，以及清单与代码注册对账 |
 | `protocol` | manifest | dsh.workbench 的 apiVersion、静态半形状与未知键 |
 | `bundles` | build | 宿主产物不含浏览器侧、浏览器产物不内联外壳 CSS 与夹具 |
 | `source` | source | 零注释、包与运行时入口分开、不手写进程/锁/原子写 |
@@ -112,11 +119,14 @@ export default moduleArch();
 | `src/messages.ts` | 1 | 文案（zh / en） |
 | `src/components/**` | 2 | 浏览器侧视图件；样式与它同目录（`X.module.css`） |
 | `src/host.ts` · `src/client.tsx` | 10 | 两个面 |
-| `**/*.test.ts(x)` | 99 | 测试 |
+| `src/host/**` | 10 | 宿主侧内部实现（按需出现）：`moduleArch()` 默认就认这一层；对外仍只有 `src/host.ts` 一个面 |
+| `src/**/__tests__/**` | 99 | 测试：住**被测代码同目录**的 `__tests__/`；`.test.ts(x)` 散在 `src/` 里判 S74 |
 
 两个运行时靠另一条规则隔离：`src/components/**` 整片算浏览器面，宿主侧 import 一个组件是硬红
-（层号拦不住它：components 第 2 层、host 第 10 层）。内置阈值比 arch-guard 默认更严：
-文件与视图各 200 行、函数 80 行；`src/model/**` 有文件就必须有测试。
+（层号拦不住它：components 第 2 层、host 第 10 层）。`src/host/**` 与两个面同层（10），
+所以浏览器面从它 import 时层号不报红 —— 运行时边界要自己守。内置阈值比 arch-guard 默认更严：
+文件与视图各 200 行、函数 80 行；`src/model/**` 有文件就必须有测试（`__tests__/` 下 —— M08），
+测试文件不在 `__tests__/` 里判 S74。
 
 要开口子**从参数进**（别改判据；每条口子都有名字，评审看得见）：
 
@@ -133,6 +143,10 @@ export default moduleArch({
 `exceptions` 每条必须写 `reason`。怎么读红、常见红、还有哪些口子，见
 [REVIEW.md](../core/skills/workbench-module-diy/REVIEW.md)。
 
+宿主面写到 200 行还收不住时，把内部实现拆到 `src/host/**`（`diy` 模板就这么做，
+`moduleArch()` 默认就认这一层）。**不要**把它做成第三个
+`dsh.workbenchFaces` 入口 —— 两个面不可调。
+
 ### `lint`：模块包的语法卫生方言
 
 `arch` 管结构，`lint` 管单文件：`as any` 绕过契约、残留的 `console.log` / `debugger`、
@@ -144,8 +158,8 @@ export default moduleLint({ rootDir: import.meta.dirname });
 ```
 
 `moduleLint()` 返回一份**标准 flat config**：它同时是判据跑的那份与编辑器 / `eslint` 认的那份，
-没有第二份真相。依赖（`eslint`、`typescript-eslint`、两个 react 插件）装在 module-tools 一家，
-模块与工坊根的清单一个字都不用改。
+没有第二份真相。依赖（`eslint`、`typescript-eslint`、两个 react 插件、`globals`）装在 module-tools 一家，
+模块清单一个字都不用改（依赖由 module-tools 自己带）。
 
 要开口子从命令参数进：`moduleLint({ rootDir, ignores, rules })`，或者展开它再追自己的一块：
 
@@ -280,20 +294,19 @@ dsh-wb-module design accept   # 在真卡片上逐条走通后打勾
 5. **`dsh.workbenchFaces` 不是协议的一部分，但门禁必填**：它指向两半的**源码**，不能指向出货
    产物 —— 从 `dist/host.js` 反推不出是哪份源码把 dsh 的包拖进来的。
 
-## 两个模板
+## 模板
 
-| 模板 | 是什么 |
-|---|---|
-| `minimal`（默认） | 空壳：卡壳、文案、测试都接好了，没有数据源 |
-| `diy` | 一份真能跑的样板：宿主侧一条只读路由真读盘、卡片五态、三张表也是填好的 |
+只有**一个**模板（`diy`，也是默认）：一份真能跑的样板 —— 宿主侧三条只读路由真读盘、卡片五态与写失败提示、
+开箱（`（待填）`）的 `design.json`（填完 `design check` 才绿），外加一条可跑的长任务 / 两把工具（一只读一读写）/ 动作通道 / prefs。维护两份模板的成本
+没人付，所以不再有 `minimal` 空壳；要空骨架就从 `diy` 删掉数据源那几段。
 
-两个模板都是**分层多文件**骨架：纯逻辑住 `src/model/**`、视图件与同目录样式住
-`src/components/**`、文案住 `src/messages.ts`，两个面只剩注册与交 props。目录按需要出现 ——
-`minimal` 没有纯逻辑就不硬造 `model/`。各自带一份一行工厂的 `arch.config.mjs` 与两行的
+它是**分层多文件**骨架：纯逻辑住 `src/model/**`、视图件与同目录样式住 `src/components/**`、
+文案住 `src/messages.ts`，测试住被测代码同目录的 `__tests__/`，两个面只剩注册与交 props；宿主侧内部实现住 `src/host/**`
+（`moduleArch()` 默认就认这一层）。带一份 `arch.config.mjs` 与两行的
 `eslint.config.mjs`。
 
 `init` 连模板里的 `*.tpl` 一起拷、按已知 token 名逐个盖章（`__UNIT__` / `__NAME__` / `__DESC__` /
-`__SHELL_RANGE__`）、剥掉后缀，再用 `design.json` 生成 README 那一段。
+`__SHELL_RANGE__` / `__DSH_UI_VERSION__`）、剥掉后缀，再用 `design.json` 生成 README 那一段。
 `__SHELL_RANGE__` 取 init 所在工程实装的那份外壳版本；读不到就退回 module-tools 自己的版本；
 两者都读不到才保持 `^0.1.0` 并在 stderr 上说一句。
 
@@ -303,7 +316,7 @@ dsh-wb-module design accept   # 在真卡片上逐条走通后打勾
 node scripts/selfcheck/index.mjs
 ```
 
-工具箱的回归网：两个模板各 `init` 一遍、各跑全套；判据的正例与负例都要对；打包清单不含
+工具箱的回归网：模板 `init` 一遍、跑全套；判据的正例与负例都要对；打包清单不含
 `.tpl` 残留；`design` 的空格、README 同步、`accept`；`publish` 的清单；`release` 的验收闸、
 dry-run、真发后的元数据与发布失败回滚。
 

package/bin/dsh-wb-module.mjs

@@ -8,6 +8,7 @@ import { changelog } from '../src/changelog.mjs';
 import { design } from '../src/design.mjs';
 import { init } from '../src/init.mjs';
 import { marketInit } from '../src/market-init.mjs';
+import { migrate } from '../src/migrate.mjs';
 import { publish } from '../src/publish.mjs';
 import { release } from '../src/release.mjs';
 import { sync } from '../src/sync.mjs';
@@ -45,14 +46,25 @@ async function lint({ root, args }) {
   if (failed > 0) process.exit(1);
 }
 
-const commands = { build, check, init, 'market-init': marketInit, design, publish, release, sync, lint, changelog };
+const commands = { build, check, init, 'market-init': marketInit, design, migrate, publish, release, sync, lint, changelog };
 
 const CHECK_HELP = `
 查询口：
   check --only kit [--file <名字>]                      这份外壳的 kit 里有什么
   check --only primitives [--all|--files|--json] [--file <名字>]
                                                         这份外壳的 dsh 原语里有什么
-  check --list [--json|--markdown]                      只列判据元数据`;
+  check --list [--json|--markdown]                      只列判据元数据
+
+范围：
+  check --package <包名|unit>                           只报这个模块的问题（开发期便利，不是门禁）
+                                                        全量扫描、只过滤报告与退出码`;
+
+const MIGRATE_HELP = `
+用法：
+  migrate [--cwd <模块目录>] [--dry-run]
+
+把模块清单迁到当前代：apiVersion → 3、缺/空的 workbenchFaces 补默认入口。
+源码类问题（kit 成员移除、裸控件、card: null 对账）不自动改 —— check 会逐条点名。`;
 
 const RELEASE_HELP = `
 选项：
@@ -86,9 +98,10 @@ release --changelog-note "这一版改了什么"（文件不在会先建）。`;
 const COMMANDS = {
   build: '出 dist/host.js（单文件 ESM）与 client.js（套 loader 壳）',
   check: '十三条判据；--only 单跑，也当查询口用；--list 只列判据元数据',
-  init: '建模块骨架（--dir / --template minimal|diy / --description）',
+  init: '建模块骨架（--dir / --template diy / --description；只有 diy 一个模板）',
   'market-init': '初始化市场索引仓库（写 market/ 与 README，推首个 commit）',
   design: '设计底稿：init 填 / check 查空格 / render 生成 README / accept 打勾',
+  migrate: '把模块清单迁到当前代（apiVersion / workbenchFaces）；源码类问题只给提示',
   publish: '发货前清单：门禁 + files + npm pack（只 dry run）',
   release: '真发布：全门禁 + 验收闸 + 预检接管 + 发到出口 + 发后核包 + 更新市场索引（中断可 --resume）',
   sync: '按清单生成 src/declared-tools.ts，按 design.json 生成 src/datasource.ts',
@@ -121,7 +134,7 @@ const program = new Command('dsh-wb-module')
   .helpOption('-h, --help', '打印帮助')
   .addHelpText(
     'after',
-    '\n  --cwd <目录>  指定包目录（默认当前目录；也可用 DSH_WB_MODULE_CWD）\n  任何命令后跟 --help 都只打印帮助。\n',
+    '\n  --cwd <目录>  指定工作目录（默认当前目录；判据仍按工作区发现，可用 DSH_WB_MODULE_CWD）\n  任何命令后跟 --help 都只打印帮助。\n',
   );
 
 for (const [name, description] of Object.entries(COMMANDS)) {
@@ -135,6 +148,7 @@ for (const [name, description] of Object.entries(COMMANDS)) {
   if (name === 'release') sub.addHelpText('after', `${RELEASE_HELP}\n`);
   if (name === 'market-init') sub.addHelpText('after', `${MARKET_INIT_HELP}\n`);
   if (name === 'changelog') sub.addHelpText('after', `${CHANGELOG_HELP}\n`);
+  if (name === 'migrate') sub.addHelpText('after', `${MIGRATE_HELP}\n`);
   sub.action(async (_options, command) => {
     await dispatch(name, command.args);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "1.1.13",
+  "version": "1.1.14-beta.0",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",
@@ -15,14 +15,13 @@
   "files": [
     "bin",
     "src",
-    "template",
     "template-diy"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@arch-guard/core": "^0.11.2",
+    "@arch-guard/core": "^0.11.3",
     "@eslint/js": "^10.0.1",
     "commander": "^15.0.0",
     "esbuild": "^0.28.2",
@@ -30,10 +29,11 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
     "execa": "^10.2.0",
+    "globals": "^17.13.0",
     "semver": "^7.8.5",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.71.0",
-    "@dsh-workbench/shared": "1.1.13"
+    "@dsh-workbench/shared": "1.1.14-beta.0"
   },
   "repository": {
     "type": "git",

package/src/arch.mjs

@@ -17,7 +17,7 @@ import { SEED_SPECIFIERS } from './seed.mjs';
 const HOST_FACE = 'src/host.ts';
 const CLIENT_FACE = 'src/client.tsx';
 
-const LAYERS = { model: 1, components: 2 };
+const LAYERS = { model: 1, components: 2, host: 10 };
 
 const MESSAGES_ROLE = { id: 'lib:messages', pattern: 'src/messages.ts', layer: 1 };
 
@@ -25,18 +25,6 @@ const DECLARED_TOOLS_ROLE = { id: 'lib:declared-tools', pattern: DECLARED_TOOLS_
 
 const DEFAULT_THRESHOLDS = { fileLines: 200, viewLines: 200, functionLines: 80 };
 
-const TEST_LINES_REASON =
-  '测试文件是脚手架，不是产品代码：夹具、逐条断言、一条用例十来行，200 行这个阈值对它是错的口径；' +
-  '按它拆文件只会把测试脚手架摞进 src/ 的层里（作者反馈：一个模块被逼出过 src/host/testing.ts）。' +
-  '测试在方言里本来就有一条排他角色（layer 99，S21 跳过它），这条豁免与那条同一个理由。' +
-  '要形状与体积上的约束，请写进模块自己的测试（用例数、覆盖的行为），不要用文件行数卡它。';
-
-const TEST_LINES_EXCEPTIONS = [
-  { rule: 'S16', glob: '**/*.{test,spec}.{ts,tsx,mts,cts,js,mjs,cjs}', reason: TEST_LINES_REASON },
-
-  { rule: 'S16', glob: 'src/**/__tests__/**', reason: TEST_LINES_REASON },
-];
-
 const TESTS_DIR_ROLE = {
   id: 'lib:tests-dir',
   pattern: 'src/**/__tests__/**',
@@ -44,15 +32,6 @@ const TESTS_DIR_ROLE = {
   exclusive: true,
 };
 
-const STYLE_EXCEPTION = {
-  rule: 'D04',
-  glob: 'src/components/**',
-  reason:
-    '主题令牌由 dsh 在运行时提供（--dsw-*）：模块包**不拥有**令牌表，声明一份自己的' +
-    '就是编造一处不存在的真相。所以组件样式里引用的 --dsw-* 在本地查不闭合是正常的；' +
-    'dsh 改名会由外壳升级暴露，而不是由模块本地的表兜住。',
-};
-
 const SEED_PACKAGES = [
   ...new Set(
     SEED_SPECIFIERS.map((name) => (name.startsWith('@') ? name.split('/').slice(0, 2).join('/') : name.split('/')[0])),
@@ -74,6 +53,11 @@ const ALLOWED_DEPS = [
 
 const DESIGN = {
   styleDir: 'src/components',
+  externalTokens: [
+    { prefix: '--dsw-', provider: '@deepseek-ai/dsh-client-ui-theme' },
+    { prefix: '--ds-', provider: '@deepseek-ai/dsh-client-ui-theme' },
+    { prefix: '--wb-', provider: '@dsh-workbench/core' },
+  ],
   tokenDir: '',
   paletteFile: '',
   vendorDir: 'src/components/vendor',
@@ -201,7 +185,34 @@ const protocolsStayCanonical = createRule({
   },
 });
 
-const MODULE_RULES = [modelStaysPure, componentsStayBrowser, protocolsStayCanonical];
+const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?(?:\.tpl)?$/;
+const TESTS_HOME = /(?:^|\/)__tests__\//;
+
+const testsLiveInFolders = createRule({
+  id: 'S74',
+  domain: 'structure',
+  level: 'L2',
+  severity: 'error',
+  title: '测试文件住在 __tests__ 目录里',
+  hint: '测试与被测代码物理分开：挪进同目录的 __tests__/，相对路径的 import 各退一级。',
+  run(ctx) {
+    const findings = [];
+    for (const record of ctx.records) {
+      if (!TEST_FILE.test(record.rel)) continue;
+      if (TESTS_HOME.test(record.rel)) continue;
+      findings.push({
+        rule: 'S74',
+        file: record.rel,
+        line: 1,
+        text: `测试文件不在 __tests__ 目录里：${record.rel}`,
+        hint: '挪进同目录的 __tests__/，相对路径的 import 各退一级。',
+      });
+    }
+    return findings;
+  },
+});
+
+const MODULE_RULES = [modelStaysPure, componentsStayBrowser, protocolsStayCanonical, testsLiveInFolders];
 
 export function moduleArch(options = {}) {
   const {
@@ -259,7 +270,7 @@ export function moduleArch(options = {}) {
         },
       }),
 
-      { enable: ['S71', 'S72', 'S73'] },
+
     ],
     overrides: {
       include: ['src/**'],
@@ -279,7 +290,7 @@ export function moduleArch(options = {}) {
           { pattern: 'src/components/**', runtime: 'client' },
         ],
       },
-      exceptions: [STYLE_EXCEPTION, ...TEST_LINES_EXCEPTIONS, ...exceptions],
+      exceptions: [...exceptions],
     },
   };
 }

package/src/check.mjs

@@ -1,7 +1,9 @@
+import { discoverPackages } from './discover.mjs';
+
 export const CHECKS = {
   contracts: {
     title: '模块契约',
-    summary: '单元 id、两个面、四个脚本、files、peer 下限，以及清单与代码注册对账',
+    summary: '单元 id、两个面、四个脚本、peer 依赖存在，以及清单与代码注册对账',
     layer: 'manifest',
     load: () => import('./checks/contracts.mjs'),
   },
@@ -135,6 +137,29 @@ export async function check({ only, args = [] } = {}) {
   }
   const names = only === undefined ? Object.keys(CHECKS) : [only];
   const jsonMode = args.includes('--json');
+  const packageAt = args.indexOf('--package');
+  const wanted = packageAt === -1 ? undefined : args[packageAt + 1];
+  let filter;
+  let moduleNames = [];
+  if (wanted !== undefined) {
+    const packages = discoverPackages({ root: process.cwd() }).filter(
+      (pkg) => pkg.manifest.dsh?.workbench !== undefined,
+    );
+    const matched = packages.filter((pkg) => {
+      const name = pkg.manifest.name;
+      const unit = pkg.manifest.dsh?.workbench?.unit;
+      return name === wanted || name.endsWith(`/${wanted}`) || unit === wanted;
+    });
+    if (matched.length === 0) {
+      const available = packages.map((pkg) => `${pkg.manifest.name}（${String(pkg.manifest.dsh?.workbench?.unit ?? '')}）`);
+      console.error(`没有这个模块：${wanted}（这个工作区里有：${available.join(' / ')}）`);
+      process.exit(2);
+    }
+    filter = new Set(matched.map((pkg) => pkg.manifest.name));
+    moduleNames = packages.map((pkg) => pkg.manifest.name).filter((name) => !filter.has(name));
+    console.log(`（只查 ${[...filter].join(' / ')}：问题按包名过滤；完整门禁别带 --package）`);
+  }
+  process.env.DSH_WB_PACKAGE_FILTER = filter === undefined ? '' : '' + [...filter].length;
   const tally = { pass: 0, skip: 0, fail: 0 };
   const skipped = [];
   let ran = 0;
@@ -149,7 +174,26 @@ export async function check({ only, args = [] } = {}) {
 
       process.env.DSH_WB_ONLY = only === undefined ? '' : name;
       const module = await entry.load();
-      const result = await module.run();
+      let result = await module.run();
+      if (filter !== undefined && result.status === 'fail') {
+        const kept = result.problems.filter((problem) => {
+          const own = [...filter].some(
+            (pkgName) => problem.startsWith(`${pkgName}:`) || problem.startsWith(`${pkgName} `),
+          );
+          if (own) return true;
+          return !moduleNames.some(
+            (pkgName) => problem.startsWith(`${pkgName}:`) || problem.startsWith(`${pkgName} `),
+          );
+        });
+        const notes = [
+          ...result.notes,
+          `（--package：只列 ${[...filter].join(' / ')} 的问题，其余模块的问题这次不算）`,
+        ];
+        result =
+          kept.length === 0
+            ? { ...result, status: 'pass', problems: [], notes }
+            : { ...result, problems: kept, notes };
+      }
 
       const title = typeof module.title === 'string' && module.title !== '' ? module.title : entry.title;
       ran += 1;
@@ -178,11 +222,14 @@ export async function check({ only, args = [] } = {}) {
   }
 
   console.log(`${ran} 条判据：${tally.pass} 通过 · ${tally.skip} 不适用 · ${tally.fail} 不过`);
+  if (filter !== undefined) {
+    console.log(`  这次只报 ${[...filter].join(' / ')}；其余模块的红被过滤掉了 —— 门禁 / 发布请不带 --package 重跑。`);
+  }
 
   if (skipped.length > 0) {
     console.log(`  这 ${skipped.length} 条这次一条都没查（不是"没问题"）：`);
     for (const one of skipped) console.log(`  ○ ${one}`);
-    console.log('  换个 cwd 它们才跑得起来（工坊里「独立构建」扫不到外壳源码、「公开包无内部标识」只扫');
+    console.log('  换个 cwd 它们才跑得起来（工作区里「独立构建」扫不到外壳源码、「公开包无内部标识」只扫');
     console.log('  要发出去的包）—— 想验这两条，回工作台仓库根跑 `dsh-wb-module check`。');
   }
   if (tally.fail > 0) process.exit(1);

package/src/checks/arch.mjs

@@ -11,7 +11,7 @@ const HOW_TO_JOIN =
   `在模块包里放一份 ${CONFIG_FILE}，内容一行就够：\n` +
   `    import { moduleArch } from '@dsh-workbench/module-tools/arch';\n` +
   '    export default moduleArch();\n' +
-  '  形状（层序表 / 两个运行时 / 阈值）见 packages/module-tools/src/arch.mjs；' +
+  '  形状（层序表 / 两个运行时 / 阈值）见 @dsh-workbench/module-tools/arch 的文档与 README；' +
   '要开口子就从 moduleArch() 的参数进（deps / layers / roles / exceptions）。';
 
 const severityIndex = (rules) => new Map(rules.map((rule) => [rule.id, rule.severity]));
@@ -69,7 +69,7 @@ export async function run() {
       const message = error instanceof Error ? error.message : String(error);
       problems.push(
         `${name}: ${CONFIG_FILE} 跑不起来 —— ${message}（先确认这份配置能 import、没有语法错，` +
-          '再确认它 import 的东西在工坊里解析得到）',
+          '再确认它 import 的东西在工作区里解析得到）',
       );
       continue;
     }

package/src/checks/contracts.mjs

@@ -1,8 +1,15 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
 import { join, relative } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { buildSupplyIndex, readDeclaration, recipeProblemOf } from '@dsh-workbench/shared/host';
+import {
+  buildSupplyIndex,
+  createHostKit,
+  hostSurface,
+  readDeclaration,
+  recipeProblemOf,
+} from '@dsh-workbench/shared/host';
 import {
   DECLARED_TOOLS_FILE,
   declaredToolsProblemOf,
@@ -61,9 +68,15 @@ async function unitFaceOf(dir) {
 const OPENCLI_CATALOG_ENV = 'DSH_WB_OPENCLI_CATALOG';
 const OPENCLI_NPM_PACKAGE = '@jackwener/opencli';
 
-function isolatedRootOf() {
+function workbenchRootOf() {
+  const configured = process.env.DSH_WORKBENCH_HOME?.trim();
+  if (configured !== undefined && configured !== '') return configured;
   const home = process.env.DSH_HOME?.trim();
-  return `${home === undefined || home === '' ? `${process.env.HOME ?? ''}/.dsh` : home}/workbench/opencli`;
+  return `${home === undefined || home === '' ? join(homedir(), '.dsh') : home}/workbench`;
+}
+
+function isolatedRootOf() {
+  return `${workbenchRootOf()}/opencli`;
 }
 
 function catalogPathOf() {
@@ -224,8 +237,26 @@ function fakeWorkspaceRegistry() {
   };
 }
 
+function fakeDataReader() {
+  const missing = async () => ({
+    ok: false,
+    error: { code: 'invalid-request', message: 'gate: 没有注入 DataReader（模块只能走 deps.data 读数据）' },
+  });
+  return {
+    read: missing,
+    request: missing,
+    requestMany: async (_recipe, calls) => {
+      const out = {};
+      for (const name of Object.keys(calls)) out[name] = await missing();
+      return out;
+    },
+    submit: missing,
+  };
+}
+
 function mountOf(face, created, manifest, tools) {
-  if (face === undefined || typeof face.mount !== 'function') return undefined;
+  if (face === undefined) return {};
+  if (typeof face.mount !== 'function') return { error: '宿主面没有 mount(deps)' };
 
   const shell = fakeShell();
   const workspaceRegistry = fakeWorkspaceRegistry();
@@ -236,39 +267,45 @@ function mountOf(face, created, manifest, tools) {
     },
   };
   try {
-    return face.mount({
-      manifest,
-      ctx: {
-        get: (key) => {
-          if (key === 'tools') return toolRegistry;
-          if (key === 'shell') return shell;
-          if (key === 'workspaceRegistry') return workspaceRegistry;
-          return undefined;
+    return {
+      result: face.mount({
+        manifest,
+        ctx: {
+          get: (key) => {
+            if (key === 'tools') return toolRegistry;
+            if (key === 'shell') return shell;
+            if (key === 'workspaceRegistry') return workspaceRegistry;
+            return undefined;
+          },
+          effect: (fn) => {
+            fn();
+          },
+          provide: () => {},
+          logger: { warn: () => {}, info: () => {} },
         },
-        effect: (fn) => {
-          fn();
+        manifests: () => [],
+        ownedUnits: () => [],
+        data: fakeDataReader(),
+        ...createHostKit({ libInstallCommand: () => '', surface: hostSurface() }),
+        opencliCommand: 'opencli',
+        env: {},
+        git: {
+          origin: async () => ({ kind: 'no-origin' }),
+          branch: async () => ({ kind: 'no-branch' }),
+          head: async () => ({ kind: 'no-head' }),
         },
-        provide: () => {},
-        logger: { warn: () => {}, info: () => {} },
-      },
-      manifests: () => [],
-      opencliCommand: 'opencli',
-      env: {},
-      git: {
-        origin: async () => ({ kind: 'no-origin' }),
-        branch: async () => ({ kind: 'no-branch' }),
-        head: async () => ({ kind: 'no-head' }),
-      },
-      libs: {
-        load: async () => {
-          throw new Error('gate: libs 未装');
+        libs: {
+          load: async () => {
+            throw new Error('gate: libs 未装');
+          },
         },
-      },
-      store: fakeStore(),
-      longTasks: fakeLongTasks(created),
-    });
-  } catch {
-    return undefined;
+        store: fakeStore(),
+        longTasks: fakeLongTasks(created),
+        longTaskRuns: () => new Map(),
+      }),
+    };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
   }
 }
 
@@ -502,7 +539,8 @@ export async function run() {
       if (typeof rel !== 'string') {
         problems.push(
           `${name}: dsh.workbenchFaces.${face} 没声明 —— 这两个源码入口是工具链字段` +
-            `（不在 dsh.workbench 协议里）：source 判据靠它们判"哪一半"，缺了它判不了`,
+            `（不在 dsh.workbench 协议里）：source 判据靠它们判"哪一半"，缺了它判不了` +
+            `（\`dsh-wb-module migrate\` 会补默认的 ${face === 'host' ? 'src/host.ts' : 'src/client.tsx'}）`,
         );
       } else if (!existsSync(join(pkg.dir, rel))) {
         problems.push(`${name}: dsh.workbenchFaces.${face} 指的文件不存在 —— ${rel}`);
@@ -540,7 +578,9 @@ export async function run() {
 
     const tools = [];
     const face = await unitFaceOf(pkg.dir);
-    const mounted = face === undefined ? undefined : mountOf(face, created, manifest, tools);
+    const mountedOf = face === undefined ? undefined : mountOf(face, created, manifest, tools);
+    const mounted = mountedOf?.result;
+    const mountError = mountedOf?.error;
     const needs = manifest?.needs;
     warnings.push(...read.warnings);
     if (manifest === undefined) {
@@ -556,6 +596,11 @@ export async function run() {
           `${name}: 声明了 ${manifest.tools.length} 个能力，但宿主面挂不起来（dist/host.js 缺、或 apply 抛了）` +
             `—— 声明的能力对不了账，先把面修好`,
         );
+      } else if (mountError !== undefined) {
+        problems.push(
+          `${name}: 宿主面 mount(deps) 抛了 —— ${mountError}。` +
+            `先修 mount 里用到的那份 deps（宿主交的服务）与初始化，能力才对得了账`,
+        );
       } else {
         try {
           mounted?.registerTools();
@@ -784,10 +829,12 @@ export async function run() {
     const writeTools = (manifest?.tools ?? []).filter((one) => one?.writes === true);
     if (writeTools.length > 0) {
       if (mounted === undefined) {
-        problems.push(
-          `${name}: 清单里有会写的工具，但宿主面挂不起来（apply / mount 抛了）—— ` +
-            `这条审批口径验不了，先把挂载依赖修好（模块自己的 smoke 也是这么挂的）`,
-        );
+        if (mountError === undefined) {
+          problems.push(
+            `${name}: 清单里有会写的工具，但宿主面挂不起来（apply / mount 抛了）—— ` +
+              `这条审批口径验不了，先把挂载依赖修好（模块自己的 smoke 也是这么挂的）`,
+          );
+        }
         continue;
       }
       const registered = new Map(tools.map((tool) => [text(tool?.name), tool]));
@@ -948,7 +995,7 @@ export async function run() {
       notes.push(
         `上面有 ${bare.length} 个包是**裸**的：它上面没有 pnpm-workspace.yaml、自己也没有 node_modules —— ` +
           `那几条 inject/external 正是因为找不到任何同伴包才落不到图里。` +
-          `做法：在工坊里造（$DSH_HOME/workbench/diy/packages/module-<名字>），或者先在这个工作区里 pnpm install。`,
+          `它上面既没有 pnpm-workspace.yaml、自己也没有 node_modules —— 所以找不到任何同伴包。`,
       );
     }
     return { status: 'fail', notes: [...notes, ...warnings.map((one) => `（警告）${one}`)], problems };