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

package/src/checks/kit.mjs

@@ -170,8 +170,9 @@ export async function run() {
           if (missing.length > 0) {
             problems.push(
               `${name}: 产物用了这份外壳（${shellClient}）里没有的 ${missing.join('、')} —— ` +
-                `顶层解构不会抛（拿到 undefined），卡片首帧渲染才炸 "Element type is invalid"，` +
-                `而外壳没有错误边界 ⇒ 整块面板会跟着没。要么去掉/换掉这些成员，要么把 peer 下限提到真正需要的那版`,
+                `顶层解构不会抛（拿到 undefined），卡片首帧渲染才炸 "Element type is invalid"；` +
+                `外壳会把这张卡收进错误态（只炸这一张，但用户看到的是错误页而不是你的卡）。` +
+                `要么去掉/换掉这些成员，要么把 peer 下限提到真正需要的那版`,
             );
           }
         }

package/src/checks/lint.mjs

@@ -111,7 +111,7 @@ async function loadConfig(pkg) {
     return {
       error:
         `${pkg.manifest.name}: ${CONFIG_FILE} 跑不起来 —— ${messageOf(error)}` +
-        '（先确认这份配置能 import、没有语法错，再确认它 import 的东西在工坊里解析得到）',
+        '（先确认这份配置能 import、没有语法错，再确认它 import 的东西在工作区里解析得到）',
     };
   }
 
@@ -251,7 +251,7 @@ export async function run() {
 
   if (problems.length > 0) {
 
-    const only = process.env.DSH_WB_ONLY === 'lint';
+    const only = process.env.DSH_WB_ONLY === 'lint' || process.env.DSH_WB_PACKAGE_FILTER !== '';
     const shown = only ? problems : problems.slice(0, MAX_PROBLEMS);
     const notes = [
       '红了怎么修：先看位置与规则名，再决定"改代码"还是"就地 eslint-disable-next-line"；' +

package/src/checks/primitives.mjs

@@ -115,9 +115,9 @@ function faceOf(modulePackages) {
     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}"（两处都要）。`,
+      `  模板默认带这一行；加完在 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) } };

package/src/discover.mjs

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 
 function manifestOf(dir) {
   const file = join(dir, 'package.json');
@@ -11,41 +11,211 @@ function manifestOf(dir) {
   }
 }
 
+function stripComment(line) {
+  const at = line.indexOf('#');
+  return at === -1 ? line : line.slice(0, at);
+}
+
+function unquote(value) {
+  return value.trim().replace(/^['"]|['"]$/g, '').trim();
+}
+
+function flowPatterns(text) {
+  const inner = text.trim().replace(/^\[/, '').replace(/\]$/, '');
+  if (inner.trim() === '') return [];
+  return inner
+    .split(',')
+    .map(unquote)
+    .filter((one) => one !== '');
+}
+
+function patternsFromYaml(text) {
+  const lines = text.split(/\r?\n/);
+  const patterns = [];
+  let state = 'idle';
+  for (const raw of lines) {
+    const line = stripComment(raw);
+    if (line.trim() === '') continue;
+    if (state === 'idle') {
+      const match = /^packages\s*:\s*(.*)$/.exec(line);
+      if (match === null) continue;
+      const rest = match[1].trim();
+      if (rest.startsWith('[')) {
+        const flow = flowPatterns(rest);
+        patterns.push(...flow);
+        return { declared: true, patterns, empty: flow.length === 0 };
+      }
+      if (rest !== '') return { declared: true, patterns: flowPatterns(rest) };
+      state = 'block';
+      continue;
+    }
+    const item = /^\s*-\s*(.+?)\s*$/.exec(line);
+    if (item !== null) {
+      const value = unquote(item[1]);
+      if (value !== '') patterns.push(value);
+      continue;
+    }
+    return { declared: true, patterns };
+  }
+  return state === 'block' ? { declared: true, patterns } : { declared: false, patterns: [] };
+}
+
+function patternsOf(root) {
+  const yaml = join(root, 'pnpm-workspace.yaml');
+  if (existsSync(yaml)) {
+    const parsed = patternsFromYaml(readFileSync(yaml, 'utf8'));
+    if (parsed.declared) {
+      if (parsed.patterns.length === 0 && parsed.empty !== true) {
+        throw new Error(
+          `pnpm-workspace.yaml 里有 packages 但没有解析出任何条目：${yaml} —— ` +
+            '支持缩进/不缩进的块列表、行内数组与 ! 排除；花括号、字符类等写法请改成显式目录',
+        );
+      }
+      return parsed;
+    }
+  }
+  const manifest = manifestOf(root);
+  const workspaces = manifest?.workspaces;
+  if (Array.isArray(workspaces)) {
+    return { declared: true, patterns: workspaces.filter((one) => typeof one === 'string') };
+  }
+  if (workspaces !== null && typeof workspaces === 'object' && Array.isArray(workspaces.packages)) {
+    return { declared: true, patterns: workspaces.packages.filter((one) => typeof one === 'string') };
+  }
+  return { declared: false, patterns: [] };
+}
+
 export function workspaceRootOf(start) {
   if (process.env.DSH_WB_ROOT) return process.env.DSH_WB_ROOT;
   let dir = start;
+  let legacy;
   for (;;) {
-    if (existsSync(join(dir, 'packages')) || existsSync(join(dir, 'pnpm-workspace.yaml'))) return dir;
+    if (existsSync(join(dir, 'pnpm-workspace.yaml'))) return dir;
+    const manifest = manifestOf(dir);
+    if (manifest !== undefined) {
+      const workspaces = manifest.workspaces;
+      if (Array.isArray(workspaces) || (workspaces !== null && typeof workspaces === 'object')) return dir;
+    }
+    if (legacy === undefined && existsSync(join(dir, 'packages'))) legacy = dir;
     const parent = dirname(dir);
-    if (parent === dir) return start;
+    if (parent === dir) return legacy ?? start;
     dir = parent;
   }
 }
 
+function isDir(dir) {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function segmentMatches(name, segment) {
+  if (/[{}[\]()|+@!]/.test(segment)) {
+    throw new Error(`工作区 glob 里这个写法暂不支持：${segment}（改成 *、** 或显式目录）`);
+  }
+  const pattern = segment
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\?/g, '[^/]');
+  return new RegExp(`^${pattern}$`).test(name);
+}
+
+function childDirs(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.name !== 'node_modules' && !entry.name.startsWith('.'))
+      .map((entry) => join(dir, entry.name))
+      .filter((child) => isDir(child));
+  } catch {
+    return [];
+  }
+}
+
+function walkDirs(dir, out) {
+  out.push(dir);
+  for (const child of childDirs(dir)) walkDirs(child, out);
+  return out;
+}
+
+function expandPattern(root, pattern) {
+  if (/[{}[\]()|+]/.test(pattern)) {
+    throw new Error(`工作区 glob 里这个写法暂不支持：${pattern}（改成 *、** 或显式目录）`);
+  }
+  const parts = pattern.replace(/\\/g, '/').split('/').filter((one) => one !== '' && one !== '.');
+  let current = [root];
+  for (const part of parts) {
+    const next = [];
+    for (const base of current) {
+      if (part === '**') {
+        walkDirs(base, next);
+        continue;
+      }
+      if (part.includes('*') || part.includes('?')) {
+        for (const child of childDirs(base)) {
+          if (segmentMatches(basename(child), part)) next.push(child);
+        }
+        continue;
+      }
+      const exact = join(base, part);
+      if (isDir(exact)) next.push(exact);
+    }
+    current = next;
+  }
+  return current;
+}
+
+const cache = new Map();
+
+function legacyPackages(root) {
+  return childDirs(join(root, 'packages'));
+}
+
 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 })) {
+  const parsed = patternsOf(workspace);
+  const positive = parsed.patterns.filter((one) => !one.startsWith('!'));
+  const negative = parsed.patterns.filter((one) => one.startsWith('!')).map((one) => one.slice(1));
+  const key = [workspace, root, parsed.patterns.join('|')].join('\0');
+  const cached = cache.get(key);
+  if (cached !== undefined) return cached.map((pkg) => ({ ...pkg }));
 
-      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
-      dirs.push(join(packagesDir, entry.name));
+  const dirs = [];
+  const push = (dir) => {
+    if (existsSync(dir)) dirs.push(dir);
+  };
+  if (!parsed.declared) {
+    for (const dir of legacyPackages(workspace)) push(dir);
+  } else {
+    const excluded = new Set();
+    for (const pattern of negative) {
+      for (const dir of expandPattern(workspace, pattern)) excluded.add(realpathSync(dir));
+    }
+    for (const pattern of positive) {
+      for (const dir of expandPattern(workspace, pattern)) {
+        if (excluded.has(realpathSync(dir))) continue;
+        push(dir);
+      }
     }
   }
-  dirs.push(root, workspace);
+  const isolated = process.env.DSH_WB_ROOT?.trim();
+  const inside = isolated === undefined || isolated === '' || resolve(root).startsWith(resolve(workspace) + sep);
+  if (inside) push(root);
+  push(workspace);
+
   const seen = new Set();
   const found = [];
   for (const dir of dirs) {
-
-    const key = existsSync(dir) ? realpathSync(dir) : dir;
-    if (seen.has(key)) continue;
-    seen.add(key);
+    const resolved = existsSync(dir) ? realpathSync(dir) : dir;
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
     const manifest = manifestOf(dir);
     if (manifest === undefined || typeof manifest.name !== 'string') continue;
     found.push({ dir, manifest });
   }
-  return found;
+  cache.set(key, found);
+  return found.map((pkg) => ({ ...pkg }));
 }
 
 export function discoverModulePackages(options = {}) {

package/src/init.mjs

@@ -4,7 +4,6 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const TEMPLATES = {
-  minimal: '../template',
   diy: '../template-diy',
 };
 const UNIT_ID = /^[a-z][a-z0-9-]*$/;
@@ -26,7 +25,7 @@ const dshUiVersion = (root) => {
 
   }
   console.error(
-    `读不到外壳 manifest 里钉的 ${DSH_UI}：模板保持 ${FALLBACK_DSH_UI}（与外壳对账过的那版）；在装好依赖的工程里 init 就能盖上当下那版`,
+    `读不到外壳 manifest 里钉的 ${DSH_UI}：模板保持 ${FALLBACK_DSH_UI}（与外壳对账过的那版）；工程里装过依赖时 init 会盖上当下那版`,
   );
   return { version: FALLBACK_DSH_UI, source: '兜底常量（没读到外壳 manifest）' };
 };
@@ -46,7 +45,7 @@ const shellRange = (root) => {
   const own = versionIn(fileURLToPath(new URL('../package.json', import.meta.url)));
   if (own !== undefined) return `^${own}`;
   console.error(
-    `读不到 @dsh-workbench/core 与 module-tools 的版本：模板里那三处 @dsh-workbench/* 保持 ${FALLBACK_RANGE}（与以前一样）；在装好依赖的工程里 init 就能盖上当下范围`,
+    `读不到 @dsh-workbench/core 与 module-tools 的版本：模板里那三处 @dsh-workbench/* 保持 ${FALLBACK_RANGE}（与以前一样）；工程里装过依赖时 init 会盖上当下范围`,
   );
   return FALLBACK_RANGE;
 };
@@ -54,13 +53,13 @@ const shellRange = (root) => {
 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 <目录>] [--template minimal|diy] [--description <文字>]');
+    console.error('用法：dsh-wb-module init <unit> [--dir <目录>] [--template diy] [--description <文字>]');
     console.error('  unit 是小写短横线标识（它同时是单元 id、包名后缀、卡片 class 前缀）');
-    console.error('  --template diy：带一个真数据源 + 卡片的样板（默认 minimal 是空壳）');
+    console.error('  --template diy：唯一模板（真数据源 + 卡片 + 可跑流程/工具），也是默认');
     process.exit(2);
   }
   const picked = args[args.indexOf('--template') + 1];
-  const which = args.includes('--template') ? picked : 'minimal';
+  const which = args.includes('--template') ? picked : 'diy';
   const template = TEMPLATES[which];
   if (template === undefined) {
     console.error(`不认识的模板：${String(which)}（可用：${Object.keys(TEMPLATES).join(' / ')}）`);
@@ -68,8 +67,9 @@ export async function init({ root, args = [] }) {
   }
   const at = args.indexOf('--dir');
   const target = at === -1 ? join(root, `module-${unit}`) : args[at + 1];
+  const describedAt = args.indexOf('--description');
   const description =
-    args[args.indexOf('--description') + 1] ?? `${unit} 模块：独立 dsh 插件包`;
+    describedAt === -1 ? `${unit} 模块：独立 dsh 插件包` : (args[describedAt + 1] ?? `${unit} 模块：独立 dsh 插件包`);
   if (existsSync(target) && readdirSync(target).length > 0) {
     console.error(`${target} 已经存在且不是空目录，不覆盖`);
     process.exit(2);
@@ -114,6 +114,5 @@ export async function init({ root, args = [] }) {
   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/lint.mjs

@@ -1,6 +1,7 @@
 import js from '@eslint/js';
 import react from 'eslint-plugin-react';
 import reactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
 import tseslint from 'typescript-eslint';
 
 export const FINGERPRINT = 'dsh-wb/module-lint';
@@ -58,23 +59,10 @@ const PLATFORM_READ = {
     "MemberExpression[object.name='process'][property.name='platform'], " +
     "MemberExpression[object.object.name='process'][object.property.name='versions'][property.name='electron'], " +
     "MemberExpression[object.name='window'][property.name='dshDesktop'], " +
-    "MemberExpression[property.name='hostOs'], " +
     "MemberExpression[object.name='navigator'][property.name='userAgent']",
   message:
-    '平台/外壳差异走能力面（HostSurface / ClientSurface）：模块源码不直接读 ' +
-    'process.platform / versions.electron / dshDesktop / hostOs / navigator.userAgent',
-};
-
-const NODE_GLOBALS = {
-  Buffer: 'readonly',
-  URL: 'readonly',
-  URLSearchParams: 'readonly',
-  console: 'readonly',
-  fetch: 'readonly',
-  module: 'readonly',
-  process: 'readonly',
-  setTimeout: 'readonly',
-  clearTimeout: 'readonly',
+    '平台/外壳差异走能力面：宿主面读 deps.surface（HostSurface），浏览器面读 kit.hooks.usePlatform()；' +
+    '模块源码不直接读 process.platform / versions.electron / dshDesktop / navigator.userAgent',
 };
 
 const SCRIPT_RULES = {
@@ -174,7 +162,7 @@ export function moduleLint(options = {}) {
     {
       name: 'dsh-wb/module-lint/scripts',
       files: SCRIPT_FILES,
-      languageOptions: { globals: NODE_GLOBALS },
+      languageOptions: { globals: { ...globals.node } },
       rules: SCRIPT_RULES,
     },
     ...overrideRules,

package/src/market-index.mjs

@@ -415,7 +415,7 @@ export function resolveIndexPlan({ args = [], home, exec }) {
   if (plan === undefined) {
     if (asked === 'auto' || asked === '') return undefined;
     throw new MarketIndexError(
-      `这个工坊还没配可写的 git 索引源。给我一个能推的 git 仓库（或它在本机的 clone 路径），我配成索引源并建一份 ${MARKET_DIR}/。`,
+      `这台机器还没配可写的 git 索引源。给我一个能推的 git 仓库（或它在本机的 clone 路径），我配成索引源并建一份 ${MARKET_DIR}/。`,
       'index-write',
     );
   }

package/src/migrate.mjs

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const API_VERSION = 3;
+
+const DEFAULT_FACES = { host: 'src/host.ts', client: 'src/client.tsx' };
+
+export async function migrate({ root, args = [] }) {
+  const dryRun = args.includes('--dry-run');
+  const file = join(root, 'package.json');
+  if (!existsSync(file)) {
+    console.error(`这里没有 package.json：${root}`);
+    process.exit(2);
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    console.error(`package.json 不是合法 JSON：${error.message}`);
+    process.exit(2);
+  }
+
+  const dsh = manifest.dsh;
+  const workbench = dsh?.workbench;
+  if (workbench === undefined) {
+    console.error('这个包没声明 dsh.workbench：先 cd 到模块目录再跑（或加 --cwd <模块目录>）');
+    process.exit(2);
+  }
+
+  const changes = [];
+  if (workbench.apiVersion !== API_VERSION) {
+    changes.push(`dsh.workbench.apiVersion：${JSON.stringify(workbench.apiVersion)} → ${String(API_VERSION)}`);
+    workbench.apiVersion = API_VERSION;
+  }
+
+  if (dsh.workbenchFaces === undefined) {
+    changes.push(`dsh.workbenchFaces：补默认 ${DEFAULT_FACES.host} / ${DEFAULT_FACES.client}`);
+    dsh.workbenchFaces = { ...DEFAULT_FACES };
+  } else {
+    for (const [kind, fallback] of Object.entries(DEFAULT_FACES)) {
+      if (typeof dsh.workbenchFaces[kind] === 'string' && dsh.workbenchFaces[kind] !== '') continue;
+      changes.push(`dsh.workbenchFaces.${kind}：补 ${fallback}`);
+      dsh.workbenchFaces[kind] = fallback;
+    }
+  }
+
+  for (const [kind, rel] of Object.entries(dsh.workbenchFaces)) {
+    if (!existsSync(join(root, rel))) {
+      console.warn(`⚠ workbenchFaces.${kind} 指的 ${rel} 不存在 —— 先把这个入口建出来`);
+    }
+  }
+
+  if (changes.length === 0) {
+    console.log('已经是当前代：清单不用改。');
+  } else if (dryRun) {
+    console.log(`会改 ${String(changes.length)} 处（--dry-run 没写）：`);
+    for (const one of changes) console.log(`  · ${one}`);
+  } else {
+    writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+    console.log(`改好 ${String(changes.length)} 处：`);
+    for (const one of changes) console.log(`  · ${one}`);
+  }
+
+  if (workbench.card === null || workbench.card === undefined) {
+    console.log('清单 card 是 null / 缺：如果 client.js 真登记了卡，跑 `check --only cards` 看 —— 补 `"card": { "order": … }` 或去掉那张卡的登记。');
+  }
+  console.log('源码类迁移不自动改：`check` 会逐条点名（kit 成员、裸控件、apiVersion 之外的协议字段），照提示改源码。');
+}

package/src/release-journal.mjs

@@ -2,6 +2,8 @@ import { createHash, randomUUID } from 'node:crypto';
 import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
+import { workbenchRootOf } from './release-util.mjs';
+
 const FINGERPRINT_FILES = [
   'package.json',
   'design.json',
@@ -13,7 +15,7 @@ const FINGERPRINT_FILES = [
 ];
 
 function statePathOf(home, unit) {
-  return join(home, 'workbench', 'releases', `${unit}.json`);
+  return join(workbenchRootOf(home), 'releases', `${unit}.json`);
 }
 
 export function readState(home, unit) {

package/src/release-target.mjs

@@ -159,7 +159,7 @@ export function registryInfoOf(root, manifest, args, target, fallbackRegistry) {
     if (registry === '') {
       throw new NeedsUser(
         'registry',
-        '这个工坊还没配团队源。让公司把 registry 和 token 写进 `.npmrc`；或者我先给你打一个安装包。',
+        '这台机器还没配团队源。让公司把 registry 和 token 写进 `.npmrc`；或者我先给你打一个安装包。',
         undefined,
         { target },
       );

package/src/release-util.mjs

@@ -80,8 +80,14 @@ export function dshHomeOf(home) {
   return home ?? process.env.DSH_HOME?.trim() ?? join(homedir(), '.dsh');
 }
 
+export function workbenchRootOf(home) {
+  const configured = process.env.DSH_WORKBENCH_HOME?.trim();
+  if (configured !== undefined && configured !== '') return configured;
+  return join(dshHomeOf(home), 'workbench');
+}
+
 export function artifactsDirOf(home, unit) {
-  return join(dshHomeOf(home), 'workbench', 'artifacts', unit);
+  return join(workbenchRootOf(home), 'artifacts', unit);
 }
 
 export function publishTagOf(version) {

package/template-diy/AGENTS.md.tpl

@@ -1,33 +1,25 @@
 # __NAME__ · agent 工作说明
 
-这个包是工作台模块（单元 `__UNIT__`）。`README.md` 讲模块本身；这份讲 agent 在这份代码里怎么干活。
+工作台模块（单元 `__UNIT__`）。模块行为与数据看 `README.md`；这份只说工具链怎么用。
 
-## 命令
+## 干活循环
 
-```bash
-pnpm install
-pnpm build        # dist/host.js + client.js
-pnpm typecheck
-pnpm test
-pnpm selfcheck
-pnpm check        # 十三条模块判据
-pnpm lint
-pnpm design check
-```
+改 `src/**` 后：
 
-发布（维护者确认之后）：
+1. `pnpm build` —— 产出 `dist/host.js` + 套了 loader 壳的 `client.js`；产物由它生成。
+2. `pnpm check` —— 十三条判据，读的就是上一步的产物。单跑一条用 `pnpm check --only <判据名>`；
+   **全绿**才算这件活做完。怎么读红、常见红：`@dsh-workbench/core/skills/workbench-module-diy/REVIEW.md`。
+3. `pnpm test` —— `src/**/__tests__/` 下、与改动同目录的 `*.test.ts`；新逻辑配对应用例，**全绿**才算完。
 
-```bash
-dsh-wb-module release --target team|public|tarball|git
-```
+`pnpm selfcheck` = build + `design check` + smoke；`design.json` 里的（待填）填完才绿。
 
-`--dry-run` 只预览，`--verify` 只核已发布的包。
+## 工具链约定
 
-## 不要
-
-- 手改 `client.js` / `dist/**`：构建产物，改 `src/**` 后重新 build。
+- 清单是工具名唯一真相：`dsh-wb-module sync` 生成 `src/declared-tools.ts`，代码引 `DECLARED_TOOLS`。
+- 判据读构建产物：改了 `src/**` 先 build 再 check。
+- 发布：`dsh-wb-module release --target team|public|tarball|git`；`--dry-run` 只预览，`--verify` 只核已发布的包。
 
 ## 先读
 
-- `README.md`：模块行为与数据源。
-- 工作台模块指引：`@dsh-workbench/core/skills/workbench-module-diy/`（dsh / 工作台的约束随外壳出货）。
+- `README.md`：模块行为、数据源、三张表。
+- `@dsh-workbench/core/skills/workbench-module-diy/`：路由 / 工具 / 卡片 / 文案的写法与约定（随外壳出货）。