@dsh-workbench/module-tools 0.0.0-stage → 0.1.1

package/bin/dsh-wb-module.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { build } from '../src/build.mjs';
+import { check } from '../src/check.mjs';
+import { init } from '../src/init.mjs';
+
+const [command, ...rest] = process.argv.slice(2);
+const cwd = process.env.DSH_WB_MODULE_CWD ?? process.cwd();
+
+const commands = { build, check, init };
+
+if (!command || !commands[command]) {
+  console.error('用法：dsh-wb-module <build|check|init> [--cwd <目录>] [--only contracts|bundles|source|cards]\n      dsh-wb-module init <unit> [--dir <目录>] [--description <文字>]');
+  process.exit(2);
+}
+
+const value = (flag) => {
+  const at = rest.indexOf(flag);
+  return at === -1 ? undefined : rest[at + 1];
+};
+const args = [];
+for (let i = 0; i < rest.length; i += 1) {
+  if (rest[i] === '--cwd' || rest[i] === '--only') {
+    i += 1;
+    continue;
+  }
+  args.push(rest[i]);
+}
+
+const root = resolve(value('--cwd') ?? cwd);
+if (root !== process.cwd()) process.chdir(root);
+
+await commands[command]({ root, only: value('--only'), args });

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "dsh-wb-module": "./bin/dsh-wb-module.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "scripts": {
+    "selfcheck": "node scripts/selfcheck.mjs"
+  }
 }

package/src/build.mjs

@@ -0,0 +1,106 @@
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { join } from 'node:path';
+import { build as esbuild } from 'esbuild';
+
+const SHELL_CLIENT = '@dsh-workbench/core/client';
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.js', '.json'];
+const SINGLETON = /^@\/shared\/(hooks|components)\//;
+
+function pickEntry(root, names) {
+  for (const name of names) {
+    const full = join(root, name);
+    if (existsSync(full)) return name;
+  }
+  return undefined;
+}
+
+function aliasResolver({ root, unit }) {
+  const localSrc = join(root, 'src');
+  return {
+    name: 'dsh-wb-module:alias',
+    setup(context) {
+      context.onResolve({ filter: /^@\// }, (args) => {
+        if (SINGLETON.test(args.path)) {
+          throw new Error(
+            `${args.path} 必须从 kit 拿（运行时要单例），不能内联进模块包 —— 见 ADR-0026 §4 代价 #9`,
+          );
+        }
+        let base;
+        if (unit !== undefined && args.path.startsWith(`@/modules/${unit}/`)) {
+          base = join(localSrc, args.path.slice(`@/modules/${unit}/`.length));
+        } else {
+          const platform = /^@\/platforms\/[^/]+\/(.+)$/.exec(args.path);
+          if (platform) base = join(localSrc, 'platforms', platform[1]);
+        }
+        if (base === undefined) {
+          throw new Error(
+            `${args.path} 指向外壳源码，模块不许这样引 —— 改从包名引（@dsh-workbench/shared 或 /host）；` +
+              `模块自己的文件用 @/modules/${unit ?? '<unit>'}/… 或相对路径`,
+          );
+        }
+        for (const candidate of [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`]) {
+          if (existsSync(candidate)) return { path: candidate };
+        }
+        throw new Error(`解析不到：${args.path}（试过 ${base}.{ts,tsx} 与 ${base}/index.{ts,tsx}）`);
+      });
+    },
+  };
+}
+
+export async function build({ root }) {
+  const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  const id = manifest.name;
+  if (typeof id !== 'string' || id === '') throw new Error('package.json 里没有 name，认不出模块 id');
+  const unit = manifest.dsh?.workbench?.unit;
+  const declared = manifest.dsh?.client?.external ?? [];
+  const plugins = [aliasResolver({ root, unit })];
+  const nodeBuiltins = [...builtinModules, ...builtinModules.map((name) => `node:${name}`)];
+
+  const hostEntry = pickEntry(root, ['src/plugin.host.ts', 'src/host.ts']);
+  if (hostEntry !== undefined) {
+    await esbuild({
+      absWorkingDir: root,
+      entryPoints: [hostEntry],
+      outfile: 'dist/host.js',
+      bundle: true,
+      platform: 'node',
+      format: 'esm',
+      target: 'node20',
+      external: [...nodeBuiltins, '@dsh-workbench/shared', '@dsh-workbench/shared/host', '@dsh-workbench/core'],
+      resolveExtensions: RESOLVE_EXTENSIONS,
+      plugins,
+      logLevel: 'warning',
+    });
+  }
+
+  const clientEntry = pickEntry(root, ['src/plugin.client.ts', 'src/client.tsx']);
+  if (clientEntry === undefined) throw new Error('找不到浏览器侧入口（src/plugin.client.ts 或 src/client.tsx）');
+  const client = await esbuild({
+    absWorkingDir: root,
+    entryPoints: [clientEntry],
+    bundle: true,
+    platform: 'browser',
+    format: 'cjs',
+    target: 'es2022',
+    external: ['react', 'react-dom', SHELL_CLIENT, ...declared],
+    jsx: 'transform',
+    jsxFactory: 'h',
+    jsxFragment: 'Fragment',
+    resolveExtensions: RESOLVE_EXTENSIONS,
+    plugins,
+    write: false,
+    logLevel: 'warning',
+  });
+
+  const indented = client.outputFiles[0].text
+    .split('\n')
+    .map((line) => (line === '' ? line : `    ${line}`))
+    .join('\n');
+
+  const wrapped = `// ⚠️ 本文件由 dsh-wb-module build 生成，请勿手改。改 src/ 后跑：dsh-wb-module build\nwindow.__ModuleLoader__.load({\n  id: ${JSON.stringify(id)},\n  factory(require) {\n    const module = { exports: {} };\n    const exports = module.exports;\n${indented}\n    return module.exports;\n  },\n});\n`;
+
+  writeFileSync(join(root, 'client.js'), wrapped);
+  console.log(`${id}：client.js 已更新（${wrapped.length} 字节）`);
+}

package/src/check.mjs

@@ -0,0 +1,23 @@
+
+const CHECKS = {
+  contracts: { title: '模块契约', load: () => import('./checks/contracts.mjs') },
+  bundles: { title: '模块产物边界', load: () => import('./checks/bundles.mjs') },
+  source: { title: '模块源码边界', load: () => import('./checks/source.mjs') },
+  cards: { title: '卡片渲染', load: () => import('./checks/cards.mjs') },
+  standalone: { title: '独立构建', load: () => import('./checks/standalone.mjs') },
+  markers: { title: '公开包无内部标识', load: () => import('./checks/markers.mjs') },
+  style: { title: '样式归属', load: () => import('./checks/style.mjs') },
+  alias: { title: '模块不指外壳', load: () => import('./checks/alias.mjs') },
+};
+
+export async function check({ only } = {}) {
+  const names = only === undefined ? Object.keys(CHECKS) : [only];
+  for (const name of names) {
+    const entry = CHECKS[name];
+    if (entry === undefined) {
+      console.error(`不认识的判据：${name}（有：${Object.keys(CHECKS).join(' / ')}）`);
+      process.exit(2);
+    }
+    await entry.load();
+  }
+}

package/src/checks/alias.mjs

@@ -0,0 +1,49 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { discoverModulePackages } from '../discover.mjs';
+
+const SPECIFIER = /(?:from|import)\s*\(?\s*['"](@\/[^'"]+)['"]/g;
+
+function walk(dir, acc = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules' || entry === 'dist') continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, acc);
+    else if (/\.tsx?$/.test(entry)) acc.push(full);
+  }
+  return acc;
+}
+
+const modules = discoverModulePackages({ root: process.cwd() });
+const problems = [];
+for (const pkg of modules) {
+  const unit = pkg.manifest.dsh?.workbench?.unit;
+  const src = join(pkg.dir, 'src');
+  const viaPlatform = /(^|\/)platform-/.test(
+    Object.keys({ ...(pkg.manifest.dependencies ?? {}), ...(pkg.manifest.devDependencies ?? {}) }).join(' '),
+  );
+  if (unit === undefined) continue;
+  for (const file of walk(src)) {
+    const text = readFileSync(file, 'utf8');
+    text.split('\n').forEach((line, index) => {
+      for (const match of line.matchAll(SPECIFIER)) {
+        const specifier = match[1];
+        const own = specifier.startsWith(`@/modules/${unit}/`);
+        const selfPlatform = specifier.startsWith('@/platforms/') && !viaPlatform;
+        if (!own && !selfPlatform) {
+          problems.push(
+            `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 用了 ${specifier} —— ` +
+              `模块只许引自己的 @/modules/${unit}/*；共享代码走包名，平台知识走包名或本包的 @/platforms/*（用了平台包就不许再用）`,
+          );
+        }
+      }
+    });
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 模块源码不许出现指向外壳的 @/：${problems.length} 处`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  process.exit(1);
+}
+console.log(`✔ 模块不指外壳：${modules.length} 个模块的 src 里没有指向外壳的 @/`);

package/src/checks/bundles.mjs

@@ -0,0 +1,71 @@
+// 模块包的**运行时边界**（S2 第二块：门禁跟着自述清单走，覆盖到模块包）。
+//
+// 判据与外壳 `packages/workbench/scripts/check-runtimes.mjs` 是同一条：**能力，不是目录名**。
+// 外壳那份走的是 vite 的 import 图；这里走**产物** —— 模块的两个入口各打成一个文件，
+// 越界的依赖一定会被 inline 进来，所以：
+//
+//   浏览器产物里出现 node 内置  = 宿主传输层混进来了（例如某个视图 import 了 host/opencli）
+//   宿主产物里出现 DOM / react = 浏览器侧混进来了
+//
+// 判据要挑**只有宿主侧才有的能力**：node 内置、`process.env`、`Buffer`。
+// 这类错误在源码里看目录名是看不出来的（`model/blockers.ts` 这种纯函数浏览器当然可以用），
+// 所以只能按能力判 —— 而产物就是能力的物证。
+//
+// 覆盖范围跟着**自述清单**走：凡 `package.json` 里声明了 `dsh.workbench` 的包都被检查，
+// 新加一个模块不用改这个脚本。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { discoverModulePackages } from '../discover.mjs';
+
+
+const CLIENT_FORBIDDEN = [
+  ['node 内置', /\bnode:[a-z]/],
+  ['process.env（宿主环境）', /\bprocess\.env\b/],
+  ['Buffer（Node 全局）', /\bBuffer\b/],
+];
+
+const HOST_FORBIDDEN = [
+  ['DOM（document）', /\bdocument\./],
+  ['DOM（window）', /\bwindow\./],
+  ['react', /require\("react"\)/],
+];
+
+const modulePackages = () => discoverModulePackages({ root: process.cwd() });
+
+const problems = [];
+let checked = 0;
+
+for (const pkg of modulePackages()) {
+  const name = pkg.manifest.name;
+  const artifacts = [
+    { what: '浏览器产物', file: 'client.js', rules: CLIENT_FORBIDDEN },
+    { what: '宿主产物', file: 'dist/host.js', rules: HOST_FORBIDDEN },
+  ];
+
+  for (const artifact of artifacts) {
+    const full = join(pkg.dir, artifact.file);
+    if (!existsSync(full)) {
+      problems.push(`${name}: 找不到${artifact.what} ${artifact.file} —— 先 build 再 check`);
+      continue;
+    }
+    checked += 1;
+    const source = readFileSync(full, 'utf8');
+    for (const [label, pattern] of artifact.rules) {
+      if (pattern.test(source)) {
+        problems.push(
+          `${name}: ${artifact.what} ${artifact.file} 里出现了${label} —— ` +
+            `两个运行时混了（判据是能力：浏览器侧不许碰宿主传输层，宿主侧不许碰 DOM/react）`,
+        );
+      }
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 模块产物边界 ${problems.length} 条不过：`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  process.exit(1);
+}
+
+console.log(`✔ 模块产物边界通过：${checked} 份产物 · 浏览器侧无 node 内置 · 宿主侧无 DOM/react`);

package/src/checks/cards.mjs

@@ -0,0 +1,229 @@
+// 模块卡片能不能**画出来**（S1 视觉验收里唯一能机器化的那一半）。
+//
+// 「卡片出现」这句话里有两件事：
+//   ① 结构画得出来 —— 卡片的代码跑得通、返回一棵非空元素树。**这条能机器验**；
+//   ② 画成什么样（间距、颜色、两栏还是三栏）—— 只有人眼能判，这里不碰。
+//
+// 为什么用「空数据」当输入：外壳渲染卡片时，数据往往还没回来（第一次读、卡在审批、
+// 平台没登录）。所以**卡片在拿到空数据时不许抛** —— 这正是"卡片一直不出来 / 点一下白屏"
+// 那类事故的机器形态。给了数据才跑得通的卡片，等于把崩溃留到用户面前。
+//
+// 手法与 packages/workbench/scripts/selfcheck.mjs 里那套一致：产物是
+// `window.__ModuleLoader__.load({id, factory})`，用假的 loader / require 把它拉起来。
+// 覆盖范围跟着 `dsh.workbench` 自述清单走 —— 新模块不用改这里。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { discoverModulePackages } from '../discover.mjs';
+
+
+const modulePackages = () => discoverModulePackages({ root: process.cwd() });
+
+// 任何属性都拿得到、任何调用都返回自己的替身 —— 这样「外壳还没给数据」的各种形状
+// 都不会让卡片因为我们**没桩到某个字段**而假红。真红只留给卡片自己的代码。
+function anyStub(path = 'stub') {
+  const target = function () {
+    return anyStub(`${path}()`);
+  };
+  return new Proxy(target, {
+    get(_target, key) {
+      if (key === Symbol.toPrimitive) return () => 0;
+      if (key === Symbol.iterator) return function* () {};
+      if (key === 'then') return undefined;
+      if (key === 'length') return 0;
+      if (key === 'toString') return () => path;
+      return anyStub(`${path}.${String(key)}`);
+    },
+    apply() {
+      return anyStub(`${path}()`);
+    },
+  });
+}
+
+function fakeReact() {
+  const element = (type, props, ...children) => ({ type, props: props ?? {}, children });
+  return {
+    createElement: element,
+    createElementNS: (_namespace, type, props, ...children) => element(type, props, ...children),
+    Fragment: 'Fragment',
+    useState: (initial) => [typeof initial === 'function' ? initial() : initial, () => {}],
+    useReducer: (_reducer, initial) => [initial, () => {}],
+    useMemo: (factory) => factory(),
+    useCallback: (factory) => factory,
+    useRef: (initial) => ({ current: initial ?? null }),
+    useEffect: () => {},
+    useLayoutEffect: () => {},
+    useSyncExternalStore: (_subscribe, snapshot) => snapshot(),
+    useId: () => 'wb-id',
+    isValidElement: (value) => typeof value === 'object' && value !== null && 'type' in value,
+    Children: { toArray: (value) => (Array.isArray(value) ? value : [value]) },
+  };
+}
+
+function fakeKit() {
+  const callable = () => anyStub('result');
+  return {
+    hooks: new Proxy({}, { get: () => callable }),
+    components: new Proxy({}, { get: () => (props) => ({ type: 'stub', props: props ?? {}, children: [] }) }),
+    api: new Proxy({}, { get: () => callable }),
+    lib: anyStub('lib'),
+  };
+}
+
+function loadFace(clientFile) {
+  let captured;
+  const fakeWindow = {
+    // 浏览器里 `window.location` 永远在；缺了它，夹具模式的开关会先抛（第一次跑就踩到）。
+    location: { search: '', href: 'http://127.0.0.1:3081/' },
+    __ModuleLoader__: {
+      load: (entry) => {
+        captured = entry;
+      },
+    },
+  };
+  const expose = { window: fakeWindow, module: undefined, exports: undefined };
+  const source = readFileSync(clientFile, 'utf8');
+  const factoryOf = new Function('window', `${source}\nreturn undefined;`);
+  factoryOf(fakeWindow);
+  if (captured === undefined) throw new Error('client.js 没有调用 __ModuleLoader__.load()');
+  const module = { exports: {} };
+  expose.module = module;
+  expose.exports = module.exports;
+  const fakeRequire = (id) => {
+    if (id === 'react') return fakeReact();
+    if (id === '@dsh-workbench/core/client') return { kit: fakeKit() };
+    throw new Error(`产物 require 了没桩的外部：${id}`);
+  };
+  const produced = captured.factory(fakeRequire);
+  return { id: captured.id, exports: produced ?? module.exports };
+}
+
+// 递归**调用**函数组件 —— 不调用的话，树里只有最外层那个 `type`，
+// 卡片体内的代码一行都没跑（第一次写漏了这步，4 张卡片都只数出 3 个节点）。
+function render(node, depth, budget) {
+  if (node === null || node === undefined || typeof node === 'boolean') return 0;
+  if (typeof node === 'string' || typeof node === 'number') return 1;
+  if (Array.isArray(node)) {
+    let count = 0;
+    for (const one of node) count += render(one, depth, budget);
+    return count;
+  }
+  if (typeof node !== 'object') return 1;
+  if (budget.left <= 0) return 0;
+  budget.left -= 1;
+  budget.maxDepth = Math.max(budget.maxDepth, depth);
+
+  const children = [...(node.children ?? [])];
+  if (typeof node.type === 'function') {
+    if (depth > 40) throw new Error('组件递归超过 40 层（自引用？）');
+    const out = node.type({ ...(node.props ?? {}), children });
+    return 1 + render(out, depth + 1, budget);
+  }
+  let count = 1;
+  for (const child of children) count += render(child, depth, budget);
+  return count;
+}
+
+const problems = [];
+const rows = [];
+
+for (const pkg of modulePackages()) {
+  const name = pkg.manifest.name;
+  const clientFile = join(pkg.dir, 'client.js');
+  if (!existsSync(clientFile)) {
+    problems.push(`${name}: 没有 client.js —— 先 build`);
+    continue;
+  }
+
+  let face;
+  try {
+    const loaded = loadFace(clientFile);
+    face = loaded.exports;
+  } catch (error) {
+    problems.push(`${name}: 产物加载不起来 —— ${error.message}`);
+    continue;
+  }
+
+  let registered;
+  const ctx = {
+    get: (key) =>
+      key === 'workbenchUnits'
+        ? {
+            registerUnit: (value) => {
+              registered = value;
+              return () => {};
+            },
+          }
+        : undefined,
+    effect: (fn) => {
+      fn();
+      return () => {};
+    },
+    provide: () => {},
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+  };
+  const apply = face?.apply ?? face?.default?.apply;
+  if (typeof apply !== 'function') {
+    problems.push(`${name}: 产物没有导出 apply（外壳挂不上这个模块）`);
+    continue;
+  }
+  try {
+    apply(ctx);
+  } catch (error) {
+    problems.push(`${name}: apply 抛了 —— ${error.message}`);
+    continue;
+  }
+
+  const card = registered?.card;
+  if (typeof card !== 'function') {
+    problems.push(`${name}: apply 之后没登记卡片（registerUnit 没拿到 card）`);
+    continue;
+  }
+
+  const props = {
+    world: { current: {} },
+    t: (key) => key,
+    refreshToken: 0,
+    onRefresh: () => {},
+    onNavigate: () => {},
+    onOpenMarket: () => {},
+    onSummary: () => {},
+  };
+
+  let tree;
+  try {
+    tree = card(props);
+  } catch (error) {
+    problems.push(`${name}: 空数据下卡片抛了 —— ${error.message}`);
+    continue;
+  }
+
+  if (tree === null || tree === undefined) {
+    problems.push(`${name}: 空数据下卡片返回空（界面上就是一片空白）`);
+    continue;
+  }
+
+  const budget = { left: 20000, maxDepth: 0 };
+  let count;
+  try {
+    count = render(tree, 0, budget);
+  } catch (error) {
+    const where = (error.stack ?? '').split('\n').slice(1, 4).join(' | ');
+    problems.push(`${name}: 卡片体内的组件抛了 —— ${error.message}\n      ${where}`);
+    continue;
+  }
+  if (count <= 1) {
+    problems.push(`${name}: 卡片只画出一个节点 —— 卡片体没跑（或什么都没画）`);
+    continue;
+  }
+  rows.push(`${name}: 空数据下画得出 ${count} 个节点（最深 ${budget.maxDepth} 层）`);
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 卡片渲染 ${problems.length} 条不过：`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  process.exit(1);
+}
+
+console.log(`✔ 卡片渲染通过：${rows.length} 张卡片在**空数据**下都画得出来（不许抛）`);
+for (const row of rows) console.log(`  ${row}`);

package/src/checks/contracts.mjs

@@ -0,0 +1,183 @@
+// 跨包的**模块契约**检查（S2 的第一块：门禁读包的自述清单，不扫源码）。
+//
+// 为什么需要它：dsh 的组合阶段**不校验** `dsh.client.external` —— 实测把一个不存在的
+// 外部声明（`@dsh-workbench/core-nope/client`）写进模块包，它被原样收进启动图、
+// 宿主侧一声不吭、程序照起；错的声明要等浏览器 `require` 那一刻才炸。
+//
+// 判据全部来自各包 package.json 里的 `dsh` 字段（**自述清单**）：
+//   · `dsh.bundle.patch` 指的补丁文件真的在；
+//   · `dsh.client.platform` 是认识的平台；
+//   · `dsh.client` 的 inject / external 每一条都能落到图里的一行（seed 词 / 平台包 / workspace 包）；
+//   · `dsh.workbench`（**这是个模块**）：
+//       - `unit` 形状合法、全局唯一（撞了就是装上去当场抛）；
+//       - `faces.host` / `faces.client` 指的入口文件真的在；
+//       - 对壳有 peer 依赖（它跑在外壳交出来的服务上）；
+//       - 有自己的接线自检脚本（模块侧也必须机器判据，不能只靠人眼）。
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { discoverPackages } from '../discover.mjs';
+
+const ROOT = process.env.DSH_WB_ROOT ?? fileURLToPath(new URL('../../../../', import.meta.url));
+
+/** dsh 浏览器侧的固定 seed 词表（模块表里天生就有的那几个）。 */
+const SEED = new Set(['react', 'react-dom', 'cordis', 'dsh-client-store', 'ui-slots', 'ui-primitives', 'ui-dockkit']);
+
+const PLATFORMS = new Set(['web']);
+
+const UNIT_ID = /^[a-z][a-z0-9-]*$/;
+
+const SHELL = '@dsh-workbench/core';
+
+function installed(specifier, from) {
+  try {
+    createRequire(join(from, 'package.json')).resolve(`${packageOf(specifier)}/package.json`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function packageOf(specifier) {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
+const readPackages = () => discoverPackages({ root: process.cwd() });
+
+const packages = readPackages();
+const known = new Set(packages.map((pkg) => pkg.manifest.name));
+const problems = [];
+const units = new Map();
+let declared = 0;
+let modules = 0;
+
+for (const pkg of packages) {
+  const name = pkg.manifest.name;
+  const dsh = pkg.manifest.dsh;
+  if (dsh === undefined) continue;
+  declared += 1;
+
+  if (dsh.bundle?.patch !== undefined && !existsSync(join(pkg.dir, dsh.bundle.patch))) {
+    problems.push(`${name}: dsh.bundle.patch 指的文件不存在 —— ${dsh.bundle.patch}`);
+  }
+
+  if (dsh.client !== undefined) {
+    if (!PLATFORMS.has(dsh.client.platform)) {
+      problems.push(`${name}: dsh.client.platform 不认识 —— ${String(dsh.client.platform)}`);
+    }
+    for (const field of ['inject', 'external']) {
+      for (const specifier of dsh.client[field] ?? []) {
+        const resolvable =
+          SEED.has(specifier) ||
+          packageOf(specifier).startsWith('@deepseek-ai/') ||
+          known.has(packageOf(specifier)) ||
+          installed(specifier, pkg.dir);
+        if (!resolvable) {
+          problems.push(
+            `${name}: dsh.client.${field} 里的 ${JSON.stringify(specifier)} 落不到图里任何一行 —— ` +
+              `既不是 seed 词、也不是平台包、也不在 workspace 里、也不是装进来的依赖（dsh 自己不校验这条，错的声明要等浏览器 require 才炸）`,
+          );
+        }
+      }
+    }
+  }
+
+  if (dsh.workbench === undefined) continue;
+  modules += 1;
+
+  const unit = dsh.workbench.unit;
+  if (typeof unit !== 'string' || !UNIT_ID.test(unit)) {
+    problems.push(`${name}: dsh.workbench.unit 形状不对 —— ${JSON.stringify(unit)}（要小写连字符）`);
+  } else if (units.has(unit)) {
+    problems.push(
+      `${name}: 单元 id ${JSON.stringify(unit)} 与 ${units.get(unit)} 撞了 —— ` +
+        `两个包都声明同一个单元，装上去注册表当场抛（id 会进持久化配置）`,
+    );
+  } else {
+    units.set(unit, name);
+    const shellPkg = packages.find((item) => item.manifest.name === SHELL);
+    if (shellPkg !== undefined && existsSync(join(shellPkg.dir, 'src/modules', unit, 'unit.ts'))) {
+      problems.push(
+        `${name}: 单元 ${JSON.stringify(unit)} 在外壳里还有一份（${SHELL}/src/modules/${unit}/）—— ` +
+          `同一个单元不许两边都住：两份真相，装上模块注册表当场抛`,
+      );
+    }
+  }
+
+  for (const face of ['host', 'client']) {
+    const rel = dsh.workbench.faces?.[face];
+    if (typeof rel !== 'string') {
+      problems.push(`${name}: dsh.workbench.faces.${face} 没声明`);
+    } else if (!existsSync(join(pkg.dir, rel))) {
+      problems.push(`${name}: dsh.workbench.faces.${face} 指的文件不存在 —— ${rel}`);
+    }
+  }
+
+  const publishable = pkg.manifest.private !== true;
+  const registry = pkg.manifest.publishConfig?.registry;
+  const isPublic = pkg.manifest.publishConfig?.access === 'public';
+  if (publishable && !isPublic && (typeof registry !== 'string' || registry.includes('registry.npmjs.org'))) {
+    problems.push(
+      `${name}: 它不是 private，却既没声明 publishConfig.access=public、也没有指向内网源的 registry —— ` +
+        `发布目标必须显式写出来（公网 / 内网），否则等于把私有模块发到公共源`,
+    );
+  }
+
+  if (pkg.manifest.peerDependencies?.[SHELL] === undefined) {
+    problems.push(
+      `${name}: 没有对 ${SHELL} 的 peer 依赖 —— 模块跑在外壳交出来的服务上，装的时候必须能说清版本`,
+    );
+  }
+
+  for (const script of ['build', 'typecheck', 'test', 'selfcheck']) {
+    if (pkg.manifest.scripts?.[script] === undefined) {
+      problems.push(
+        `${name}: 没有 ${script} 脚本 —— 模块包必须自带整套门禁：` +
+          `外壳的 arch / 覆盖率 / 运行时边界都只扫自己的 src/，模块出包之后没人替它跑`,
+      );
+    }
+  }
+}
+
+const unitList = [...units.entries()].map(([unit, name]) => `${unit} ← ${name}`).join(' · ');
+
+const shellPkg = packages.find((pkg) => pkg.manifest.name === SHELL);
+if (shellPkg !== undefined) {
+  const suspects = [join(shellPkg.dir, 'package.json')];
+  const srcDir = join(shellPkg.dir, 'src');
+  if (existsSync(srcDir)) {
+    const walk = (dir) => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (/\.tsx?$/.test(entry.name)) suspects.push(full);
+      }
+    };
+    walk(srcDir);
+  }
+  for (const file of suspects) {
+    const text = readFileSync(file, 'utf8');
+    const hit = /@pagoda\/dsh-workbench-module-[a-z0-9-]+/.exec(text);
+    if (hit !== null) {
+      problems.push(
+        `${SHELL}: ${relative(ROOT, file)} 里点名了模块包 ${hit[0]} —— ` +
+          `外壳不许认识任何模块（那等于把"中央清单"搬进外壳）；模块靠服务名挂进来`,
+      );
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 模块契约 ${problems.length} 条不过（${declared} 个带 dsh 声明的包，其中 ${modules} 个模块）：`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  process.exit(1);
+}
+
+console.log(
+  `✔ 模块契约通过：${declared} 个带 dsh 声明的包（${modules} 个模块）· bundle 落点存在 · ` +
+    `inject/external 都能落到图里 · 单元 id 唯一 · 面文件与 peer 都在 · 各有接线自检`,
+);
+console.log(`  单元：${unitList}`);

package/src/checks/markers.mjs

@@ -0,0 +1,53 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { discoverPackages } from '../discover.mjs';
+
+const MARKERS = [
+  ['内网 cmdb 域名', /pagoda\.com\.cn/],
+  ['内网 coding.net 企业名', /\bbaiguokeji\b/i],
+  ['内网 coding.net 团队名', new RegExp('UED' + 'YHSJ')],
+  ['公司内部叫法', new RegExp('\u767e' + '\u679c')],
+  ['内网 npm 源', new RegExp('[a-z0-9-]+\\.pkg\\.coding\\.net', 'i')],
+];
+
+const SKIP = new Set(['node_modules', 'dist', 'coverage', '.git', '.turbo']);
+
+function walk(dir, acc = []) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP.has(entry)) continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, acc);
+    else acc.push(full);
+  }
+  return acc;
+}
+
+const publicPackages = discoverPackages({ root: process.cwd() }).filter(
+  (pkg) => pkg.manifest.publishConfig?.access === 'public',
+);
+const problems = [];
+for (const pkg of publicPackages) {
+  for (const file of walk(pkg.dir)) {
+    let text;
+    try {
+      text = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    text.split('\n').forEach((line, index) => {
+      for (const [label, pattern] of MARKERS) {
+        if (pattern.test(line)) {
+          problems.push(`${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 命中${label} —— ${line.trim().slice(0, 120)}`);
+        }
+      }
+    });
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 公开包里不许有公司内部标识：${problems.length} 处`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  console.error('  （发布前扫一遍：内网源地址、内网域名、企业内部名都不该出现在公网包里）');
+  process.exit(1);
+}
+console.log(`✔ 公开包无内部标识：${publicPackages.length} 个 access=public 的包扫过`);

package/src/checks/source.mjs

@@ -0,0 +1,102 @@
+// 模块包的**源码边界**（S2 第三块：门禁跟着自述清单走到模块包）。
+//
+// 外壳那份 `arch/rules/units.mjs` 是按**路径**发现套件的（`src/modules/<id>/unit.ts`），
+// 模块搬出 `src/` 之后它照跑但不报。那几条规则守的多是「外壳不许认识套件」——对模块包没意义；
+// 模块包自己要守的是另外四条，写在下面。判据全部来自源码里的 import 说明符，覆盖范围跟着
+// `dsh.workbench` 自述清单走（新加模块不用改这里）。
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { discoverModulePackages } from '../discover.mjs';
+
+
+const IMPORT = /from\s+'([^']+)'|import\s+'([^']+)'/g;
+
+function sourceFiles(dir, acc = []) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      if (entry === '__tests__' || entry === 'node_modules') continue;
+      sourceFiles(full, acc);
+    } else if (/\.tsx?$/.test(entry) && !/\.test\.tsx?$/.test(entry)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+function hasPlatformPackage(manifest) {
+  const names = Object.keys({ ...(manifest.dependencies ?? {}), ...(manifest.devDependencies ?? {}) });
+  return names.some((name) => /(^|\/)platform-/.test(name));
+}
+
+const modulePackages = () => discoverModulePackages({ root: process.cwd() });
+
+const problems = [];
+let scanned = 0;
+
+for (const pkg of modulePackages()) {
+  const name = pkg.manifest.name;
+  const unit = pkg.manifest.dsh.workbench.unit;
+  const srcDir = join(pkg.dir, 'src');
+  const viaPlatform = hasPlatformPackage(pkg.manifest);
+
+  if (viaPlatform && existsSync(join(srcDir, 'platforms'))) {
+    problems.push(
+      `${name}: 已经改用平台包了，src/platforms/ 就别再留一份 —— 平台知识两处都有，改平台要改两处`,
+    );
+  }
+
+  for (const file of sourceFiles(srcDir)) {
+    scanned += 1;
+    const rel = relative(pkg.dir, file);
+    const text = readFileSync(file, 'utf8');
+
+    for (const match of text.matchAll(IMPORT)) {
+      const specifier = match[1] ?? match[2];
+      if (specifier === undefined) continue;
+
+      if (specifier.startsWith('@deepseek-ai/')) {
+        problems.push(
+          `${name}: ${rel} 里 import 了 ${specifier} —— 平台契约要按需自己声明，不许直接吃 dsh 的包`,
+        );
+        continue;
+      }
+      if (specifier === '@/app' || specifier.startsWith('@/app/')) {
+        problems.push(
+          `${name}: ${rel} 里 import 了 ${specifier} —— 模块不许伸进外壳的入口/外壳层，只能走 kit 与 mount(deps)`,
+        );
+        continue;
+      }
+      const cross = /^@\/modules\/([^/]+)\//.exec(specifier);
+      if (cross !== null && cross[1] !== unit) {
+        problems.push(
+          `${name}: ${rel} 里 import 了 ${specifier} —— 模块之间不许互相 import（另一个套件没装就没有这份源码）`,
+        );
+        continue;
+      }
+      const platform = /^@\/platforms\/([^/]+)\/(.+)$/.exec(specifier);
+      if (platform !== null && viaPlatform) {
+        problems.push(
+          `${name}: ${rel} 里 import 了 ${specifier} —— 这个模块已经改用平台包了，平台知识走包名` +
+            `（比如 @pagoda-dsh-workbench/platform-coding），不许再用 @/platforms/*`,
+        );
+      } else if (platform !== null && !existsSync(join(srcDir, 'platforms', `${platform[2]}.ts`))) {
+        problems.push(
+          `${name}: ${rel} 里 import 了 ${specifier}，但本包 src/platforms/${platform[2]}.ts 不存在 —— ` +
+            `平台知识要么放在自己包里的 src/platforms/，要么整个走平台包，两条只能选一条`,
+        );
+      }
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 模块源码边界 ${problems.length} 条不过：`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  process.exit(1);
+}
+
+console.log(
+  `✔ 模块源码边界通过：${scanned} 个源文件 · 不吃平台包 · 不伸进外壳 app/ · 不跨模块 · 平台知识要么在自己包里、要么走平台包（不许两样都有）`,
+);

package/src/checks/standalone.mjs

@@ -0,0 +1,65 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { discoverModulePackages, discoverPackages } from '../discover.mjs';
+
+const SHELL = '@dsh-workbench/core';
+
+const shell = discoverPackages({ root: process.cwd() }).find((pkg) => pkg.manifest.name === SHELL);
+if (shell === undefined || !existsSync(join(shell.dir, 'src'))) {
+  console.log(`✔ 独立构建：本仓没有 ${SHELL} 的源码（模块侧靠"不许 @/ 指外壳"那条判据守）`);
+  process.exit(0);
+}
+
+const modules = discoverModulePackages({ root: process.cwd() });
+const visible = join(shell.dir, 'src');
+const hidden = join(shell.dir, 'src.hidden');
+
+const restore = () => {
+  if (existsSync(hidden) && !existsSync(visible)) renameSync(hidden, visible);
+};
+process.on('SIGINT', () => {
+  restore();
+  process.exit(130);
+});
+
+if (existsSync(hidden)) {
+  console.error(`上次没还原干净：${hidden} 还在，手动改名回去再跑。`);
+  process.exit(1);
+}
+
+const rows = [];
+const problems = [];
+renameSync(visible, hidden);
+try {
+  for (const pkg of modules) {
+    const name = pkg.manifest.name;
+    for (const script of ['build', 'typecheck']) {
+      if (pkg.manifest.scripts?.[script] === undefined) continue;
+      try {
+        execFileSync('pnpm', ['run', script], { cwd: pkg.dir, stdio: 'pipe' });
+        rows.push(`${name} ${script}: ✅`);
+      } catch (error) {
+        const output = `${error.stdout ?? ''}${error.stderr ?? ''}`;
+        const first = output
+          .split('\n')
+          .filter((line) => /error|Cannot find|Could not resolve|ERR_/.test(line))
+          .slice(0, 2)
+          .map((line) => line.trim())
+          .join(' | ');
+        rows.push(`${name} ${script}: ❌`);
+        problems.push(`${name} ${script} 在外壳源码不在场时失败 —— ${first.slice(0, 220)}`);
+      }
+    }
+  }
+} finally {
+  restore();
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 独立构建 ${problems.length} 条不过：`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  console.error('  （上面的清单就是"发布出去会散架"的地方：模块只许依赖已发布的接口）');
+  process.exit(1);
+}
+console.log(`✔ 独立构建通过：${modules.length} 个模块包在外壳源码不在场时都能 build + typecheck`);

package/src/checks/style.mjs

@@ -0,0 +1,46 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { discoverModulePackages } from '../discover.mjs';
+
+const SHELL_SELECTOR = /(^|[\s,>+~])\.wb-[a-z0-9-]+/;
+const RULE = /\.wb-[a-z0-9-]+[^{}]*\{/;
+
+function walk(dir, acc = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules' || entry === 'dist') continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, acc);
+    else acc.push(full);
+  }
+  return acc;
+}
+
+const problems = [];
+const modules = discoverModulePackages({ root: process.cwd() });
+for (const pkg of modules) {
+  for (const file of walk(pkg.dir)) {
+    if (!/\.(css|ts|tsx)$/.test(file)) continue;
+    let text;
+    try {
+      text = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    text.split('\n').forEach((line, index) => {
+      if (!RULE.test(line)) return;
+      const selector = line.slice(0, line.indexOf('{'));
+      if (!SHELL_SELECTOR.test(selector)) return;
+      problems.push(
+        `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 定义了外壳前缀的 CSS 规则 —— ${line.trim().slice(0, 100)}`,
+      );
+    });
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 模块不许定义外壳前缀的 CSS 规则：${problems.length} 处`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  console.error('  （wb-* 是全局类名：两份同名规则按注入顺序互相覆盖，用户看到的是随机的那个）');
+  process.exit(1);
+}
+console.log(`✔ 样式归属清楚：${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则`);

package/src/discover.mjs

@@ -0,0 +1,50 @@
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+function manifestOf(dir) {
+  const file = join(dir, 'package.json');
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function workspaceRootOf(start) {
+  if (process.env.DSH_WB_ROOT) return process.env.DSH_WB_ROOT;
+  let dir = start;
+  for (;;) {
+    if (existsSync(join(dir, 'packages')) || existsSync(join(dir, 'pnpm-workspace.yaml'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return start;
+    dir = parent;
+  }
+}
+
+export function discoverPackages({ root = process.cwd() } = {}) {
+  const workspace = workspaceRootOf(root);
+  const dirs = [];
+  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));
+    }
+  }
+  dirs.push(root, workspace);
+  const seen = new Set();
+  const found = [];
+  for (const dir of dirs) {
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    const manifest = manifestOf(dir);
+    if (manifest === undefined || typeof manifest.name !== 'string') continue;
+    found.push({ dir, manifest });
+  }
+  return found;
+}
+
+export function discoverModulePackages(options = {}) {
+  return discoverPackages(options).filter((pkg) => pkg.manifest.dsh?.workbench !== undefined);
+}

package/src/index.mjs

@@ -0,0 +1,2 @@
+export { build } from './build.mjs';
+export { check } from './check.mjs';

package/src/init.mjs

@@ -0,0 +1,48 @@
+import { cpSync, existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATE = fileURLToPath(new URL('../template', import.meta.url));
+const UNIT_ID = /^[a-z][a-z0-9-]*$/;
+
+export async function init({ root, args = [] }) {
+  const unit = args[0];
+  if (unit === undefined || !UNIT_ID.test(unit)) {
+    console.error('用法：dsh-wb-module init <unit> [--dir <目录>] [--description <文字>]');
+    console.error('  unit 是小写短横线标识（它同时是单元 id、包名后缀、卡片 class 前缀）');
+    process.exit(2);
+  }
+  const at = args.indexOf('--dir');
+  const target = at === -1 ? join(root, `module-${unit}`) : args[at + 1];
+  const description =
+    args[args.indexOf('--description') + 1] ?? `${unit} 模块：独立 dsh 插件包`;
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    console.error(`${target} 已经存在且不是空目录，不覆盖`);
+    process.exit(2);
+  }
+  const tokens = {
+    __UNIT__: unit,
+    __NAME__: `@dsh-workbench/module-${unit}`,
+    __DESC__: description,
+  };
+  const fill = (text) => text.replace(/__[A-Z]+__/g, (token) => tokens[token] ?? token);
+  cpSync(TEMPLATE, target, { recursive: true });
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!/\.(tpl|ts|tsx|json|md|yml)$/.test(entry.name)) continue;
+      writeFileSync(full, fill(readFileSync(full, 'utf8')));
+      if (/\.tpl$/.test(entry.name)) {
+        const stripped = join(dir, entry.name.replace(/\.tpl$/, ''));
+        cpSync(full, stripped);
+        rmSync(full);
+      }
+    }
+  };
+  walk(target);
+  console.log(`${target} 建好了：${unit} 模块骨架（build / check / selfcheck 已接工具）`);
+}

package/template/README.md.tpl

@@ -0,0 +1,18 @@
+# __NAME__
+
+`__UNIT__` 模块：一个独立的 dsh 插件包，只认外壳的服务名，不认识外壳源码。
+
+```bash
+dsh-wb-module build     # 出 dist/host.js 与套了 loader 壳的 client.js
+dsh-wb-module check     # 契约 / 产物边界 / 源码边界 / 卡片渲染
+```
+
+装进本地工作台：
+
+```bash
+dsh plugin --profile workbench add <本目录>
+```
+
+面板只读、写入只走 agent 工具；共享代码从 `@dsh-workbench/shared` 拿，
+单例机制（hooks / 容器组件 / 读缝）只能从 `@dsh-workbench/core/client` 的 kit 拿。
+要发布：把 `package.json` 里的 `private` 去掉、按需改 `publishConfig`。

package/template/cordis.patch.yml.tpl

@@ -0,0 +1,3 @@
+- insert:
+    - id: workbench-module-__UNIT__
+      name: '__NAME__'

package/template/package.json.tpl

@@ -0,0 +1,43 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "description": "__DESC__",
+  "type": "module",
+  "exports": {
+    ".": "./dist/host.js",
+    "./client": "./client.js"
+  },
+  "files": ["dist", "client.js", "cordis.patch.yml"],
+  "scripts": {
+    "build": "dsh-wb-module build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "selfcheck": "dsh-wb-module build && dsh-wb-module check",
+    "prepack": "dsh-wb-module build"
+  },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "inject": ["@dsh-workbench/core"],
+      "external": ["@dsh-workbench/core/client"]
+    },
+    "workbench": {
+      "unit": "__UNIT__",
+      "faces": { "host": "src/host.ts", "client": "src/client.tsx" }
+    }
+  },
+  "peerDependencies": { "@dsh-workbench/core": "^0.1.0", "react": "*" },
+  "peerDependenciesMeta": { "react": { "optional": true } },
+  "devDependencies": {
+    "@dsh-workbench/core": "^0.1.0",
+    "@dsh-workbench/module-tools": "^0.1.0",
+    "@types/node": "^24.19.0",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "typescript": "5.9",
+    "vitest": "^5.0.2"
+  },
+  "publishConfig": { "access": "public" }
+}

package/template/src/client.tsx.tpl

@@ -0,0 +1,27 @@
+import { createElement as h } from 'react';
+
+const UNIT_ID = '__UNIT__';
+
+export const inject = ['workbenchUnits'];
+
+export function apply(ctx) {
+  const units = ctx.get('workbenchUnits');
+  if (units === undefined) {
+    console.warn(`[${UNIT_ID}] 外壳没有提供 workbenchUnits 服务：这张卡片装不进来`);
+    return;
+  }
+  ctx.effect(
+    () =>
+      units.registerUnit({
+        manifest: {
+          id: UNIT_ID,
+          kind: 'board',
+          card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
+          tools: [],
+          host: { inject: [] },
+        },
+        card: () => h('section', { className: `wb-${UNIT_ID}` }, h('h2', null, `${UNIT_ID}`)),
+      }),
+    `${UNIT_ID}: 注册`,
+  );
+}

package/template/src/host.ts.tpl

@@ -0,0 +1,27 @@
+const UNIT_ID = '__UNIT__';
+
+export const name = '__NAME__';
+
+export const inject = ['workbenchUnits'];
+
+export function apply(ctx) {
+  const units = ctx.get('workbenchUnits');
+  if (units === undefined) {
+    ctx.logger?.warn?.(`[${UNIT_ID}] 外壳没有提供 workbenchUnits 服务：这个模块装不进来`);
+    return;
+  }
+  ctx.effect(
+    () =>
+      units.register({
+        manifest: {
+          id: UNIT_ID,
+          kind: 'board',
+          card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
+          tools: [],
+          host: { inject: [] },
+        },
+        mount: () => ({ routes: {}, registerTools: () => [] }),
+      }),
+    `${UNIT_ID}: 注册`,
+  );
+}

package/template/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "jsx": "react",
+    "jsxFactory": "h",
+    "jsxFragmentFactory": "Fragment",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noImplicitOverride": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "paths": { "@/modules/__UNIT__/*": ["src/*"] }
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "types/**/*.d.ts"]
+}

package/template/types/globals.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 浏览器半侧的运行时垫片。
+ *
+ * dsh 的客户端模块格式是 `window.__ModuleLoader__.load({ id, factory(require) })`，
+ * 所以 `require` 不来自模块系统，而是宿主给的作用域。
+ */
+
+/**
+ * React 19 的 `@types/react` 移除了全局 `JSX` 命名空间，而本工程用的是
+ * **经典 JSX 运行时**（`jsxFactory: "h"`）：`react/jsx-runtime` 不在浏览器模块表里，
+ * 所以不能切到自动运行时。这里把全局命名空间接到 `React.JSX` 上 —— 这是官方迁移说明
+ * 给经典运行时的做法，写完 JSX 就有完整类型，产出仍是 `h(...)`。
+ */
+import type * as ReactTypes from 'react';
+
+declare global {
+  namespace JSX {
+    interface Element extends ReactTypes.JSX.Element {}
+    interface ElementClass extends ReactTypes.JSX.ElementClass {}
+    interface IntrinsicElements extends ReactTypes.JSX.IntrinsicElements {}
+    /** 有了它，返回 ReactNode 的组件（含 Fragment）才合法 —— React 19 的类型靠这条判断。 */
+    type ElementType = ReactTypes.JSX.ElementType;
+    interface IntrinsicAttributes extends ReactTypes.JSX.IntrinsicAttributes {}
+    interface ElementAttributesProperty extends ReactTypes.JSX.ElementAttributesProperty {}
+    interface ElementChildrenAttribute extends ReactTypes.JSX.ElementChildrenAttribute {}
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.