@dsh-workbench/module-tools 0.1.14 → 0.1.16

package/src/checks/contracts.mjs

@@ -13,12 +13,15 @@
 //       - `faces.host` / `faces.client` 指的入口文件真的在；
 //       - 对壳有 peer 依赖（它跑在外壳交出来的服务上）；
 //       - 有自己的接线自检脚本（模块侧也必须机器判据，不能只靠人眼）。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
 
 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';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { discoverPackages, workspaceRootOf } from '../discover.mjs';
 import { SEED_SHORT } from '../seed.mjs';
 
 const ROOT = process.env.DSH_WB_ROOT ?? fileURLToPath(new URL('../../../../', import.meta.url));
@@ -32,6 +35,237 @@ const UNIT_ID = /^[a-z][a-z0-9-]*$/;
 
 const SHELL = '@dsh-workbench/core';
 
+export const title = '模块契约';
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+// 把模块的**宿主产物**挂起来，拿到它的面（清单 + needsApproval / approvalDetail）。
+// 与模块自己的 smoke 用的是同一条路：apply() 要一个 workbenchUnits，register 里把面接住。
+// 挂不起来（产物缺失、apply 抛、mount 需要真的 store）一律返回 undefined —— 那是别的判据的事，
+// 这里只负责"清单说它会写，那它有没有认领审批"。
+async function unitFaceOf(dir) {
+  const entry = join(dir, 'dist/host.js');
+  if (!existsSync(entry)) return undefined;
+  try {
+    const mod = await import(pathToFileURL(entry).href);
+    if (typeof mod.apply !== 'function') return undefined;
+    const faces = [];
+    mod.apply({
+      get: (key) =>
+        key === 'workbenchUnits'
+          ? {
+              register(face) {
+                faces.push(face);
+                return () => {};
+              },
+            }
+          : undefined,
+      effect: (fn) => {
+        fn();
+      },
+      logger: { warn: () => {}, info: () => {} },
+    });
+    return faces[0];
+  } catch {
+    return undefined;
+  }
+}
+
+function isRegistry(value) {
+  return /^(https?|file):\/\//.test(value);
+}
+
+function envProblemsOf(name, env) {
+  const problems = [];
+  const libs = env.libs ?? [];
+  const plugins = env.plugins ?? [];
+  if (text(env.command) === '' && libs.length === 0 && plugins.length === 0) {
+    problems.push(`${name}: env 是空的 —— 要么删掉它，要么写清这个模块靠什么才跑得起来（command / libs / plugins）`);
+  }
+  libs.forEach((need, index) => {
+    const at = `env.libs[${index}]`;
+    if (text(need?.name) === '') problems.push(`${name}: ${at} 没写 name`);
+    if (text(need?.registryEnv) === '') {
+      problems.push(`${name}: ${at} 没写 registryEnv —— 用户的内网源没法覆盖它，换源时只能改代码`);
+    }
+    if (!isRegistry(text(need?.registryDefault))) {
+      problems.push(
+        `${name}: ${at}.registryDefault 不是 http(s):// 或 file:// 的源地址 —— ${JSON.stringify(need?.registryDefault)}`,
+      );
+    }
+    if (text(need?.purpose) === '') {
+      problems.push(`${name}: ${at} 没写 purpose —— "装它干嘛"就是给用户看的那半句，不能空`);
+    }
+  });
+  plugins.forEach((need, index) => {
+    const at = `env.plugins[${index}]`;
+    if (text(need?.name) === '') problems.push(`${name}: ${at} 没写 name`);
+    for (const command of need?.commands ?? []) {
+      if (text(command) === '') problems.push(`${name}: ${at}.commands 里有空字符串`);
+    }
+    const source = need?.installSource;
+    if (source === undefined) return;
+    if (source.kind === 'npm') {
+      if (text(source.package) === '') problems.push(`${name}: ${at}.installSource 是 npm 却没写 package`);
+      if (text(source.registryEnv) === '') problems.push(`${name}: ${at}.installSource 没写 registryEnv`);
+    } else if (source.kind === 'git') {
+      if (text(source.url) === '') problems.push(`${name}: ${at}.installSource 是 git 却没写 url`);
+    } else if (source.kind === 'local') {
+      if (text(source.env) === '') problems.push(`${name}: ${at}.installSource 是 local 却没写 env`);
+    } else {
+      problems.push(
+        `${name}: ${at}.installSource.kind 不认识 —— ${JSON.stringify(source.kind)}（只有 npm / git / local）`,
+      );
+    }
+  });
+  return problems;
+}
+
+// opencli 的隔离运行时（唯一真相在 packages/shared/src/host/opencli-runtime.ts；module-tools 不依赖
+// shared，所以这里按同一套约定重算一遍 —— 认同一组环境变量，测试与 selfcheck 靠它注入 fixture）。
+const OPENCLI_CATALOG_ENV = 'DSH_WB_OPENCLI_CATALOG';
+const OPENCLI_NPM_PACKAGE = '@jackwener/opencli';
+
+function isolatedRootOf() {
+  const home = process.env.DSH_HOME?.trim();
+  return `${home === undefined || home === '' ? `${process.env.HOME ?? ''}/.dsh` : home}/workbench/opencli`;
+}
+
+function catalogPathOf() {
+  const override = process.env[OPENCLI_CATALOG_ENV]?.trim();
+  return override === undefined || override === ''
+    ? `${isolatedRootOf()}/toolchain/node_modules/${OPENCLI_NPM_PACKAGE}/cli-manifest.json`
+    : override;
+}
+
+function pluginDirOf(plugin) {
+  return `${isolatedRootOf()}/plugins-npm/node_modules/opencli-plugin-${plugin}`;
+}
+
+function pluginCommandsIn(dir) {
+  try {
+    return readdirSync(dir)
+      .filter((one) => one.endsWith('.js'))
+      .map((one) => one.slice(0, -3))
+      .filter((one) => one !== 'index' && !one.startsWith('_'));
+  } catch {
+    return undefined;
+  }
+}
+
+function catalogBySite() {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(catalogPathOf(), 'utf8'));
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(parsed)) return undefined;
+  const bySite = new Map();
+  for (const one of parsed) {
+    if (typeof one !== 'object' || one === null) continue;
+    const site = text(one['site']);
+    const name = text(one['name']);
+    if (site === '' || name === '') continue;
+    const set = bySite.get(site) ?? new Set();
+    set.add(name);
+    for (const alias of Array.isArray(one['aliases']) ? one['aliases'] : []) {
+      if (typeof alias === 'string' && alias !== '') set.add(alias);
+    }
+    bySite.set(site, set);
+  }
+  return bySite;
+}
+
+function productsTextOf(dir) {
+  let text = '';
+  for (const rel of ['dist/host.js', 'client.js']) {
+    const full = join(dir, rel);
+    if (existsSync(full)) text += `\n${readFileSync(full, 'utf8')}`;
+  }
+  return text;
+}
+
+function hostProductOf(dir) {
+  try {
+    return readFileSync(join(dir, 'dist/host.js'), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function designRowsOf(dir, key) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(join(dir, 'design.json'), 'utf8'));
+  } catch {
+    return undefined;
+  }
+  return Array.isArray(parsed?.[key]) ? parsed[key] : [];
+}
+
+function fakeLongTasks(created) {
+  return {
+    create(options) {
+      created.push(options);
+      return {
+        start: () => ({}),
+        snapshot: () => null,
+        active: () => null,
+        current: () => [],
+        onChange: () => () => {},
+      };
+    },
+  };
+}
+
+// 契约里 mount 一定拿得到 deps.store（外壳给的是 WorkspaceStore）。假的 deps 少给这一样，
+// 用到 store 的模块（存偏好是最常见的用法）就会在这里抛、被当成"mount 坏了"，
+// 然后在审批那条判据上被冤枉成"没给出合法口径"。所以假 store 也给它一个：
+// for / machine / scan 都回同一个内存文件区，写进去的东西后面读得回来。
+function fakeStore() {
+  const files = new Map();
+  const one = () => ({
+    dir: 'memory',
+    read: (name) => (files.has(name) ? files.get(name) : null),
+    write: (name, value) => {
+      files.set(name, value);
+    },
+    remove: (name) => {
+      files.delete(name);
+    },
+    list: () => [...files.keys()],
+  });
+  return { for: () => one(), machine: () => one(), scan: () => [one()] };
+}
+
+function mountOf(face, created) {
+  if (face === undefined || typeof face.mount !== 'function') return undefined;
+  try {
+    return face.mount({
+      ctx: {
+        get: () => undefined,
+        effect: (fn) => {
+          fn();
+        },
+        logger: { warn: () => {}, info: () => {} },
+      },
+      manifests: () => [],
+      opencliCommand: 'opencli',
+      store: fakeStore(),
+      longTasks: fakeLongTasks(created),
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+const LONG_TASK_METHODS = ['start', 'snapshot', 'active', 'current', 'onChange'];
+
+const LONG_TASK_RENDERERS = ['useLongTask', 'LongTaskRow', 'longTaskDot'];
+
 function installed(specifier, from) {
   try {
     createRequire(join(from, 'package.json')).resolve(`${packageOf(specifier)}/package.json`);
@@ -41,151 +275,422 @@ function installed(specifier, from) {
   }
 }
 
+/**
+ * 这个包是不是"裸"的：上面没有任何 workspace（`pnpm-workspace.yaml` 或 `packages/`），
+ * 自己也没装依赖。裸目录里 `init` 出来的骨架就是这样 —— 它报的 inject/external 落不到图里
+ * **不是声明写错**，而是"它压根不在一个 workspace 里"，而原文把这句话说成了"声明有问题"。
+ */
+function barePackage(pkg) {
+  return workspaceRootOf(pkg.dir) === pkg.dir && !existsSync(join(pkg.dir, 'node_modules'));
+}
+
 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;
+export async function run() {
+  const packages = discoverPackages({ root: process.cwd() });
+  const known = new Set(packages.map((pkg) => pkg.manifest.name));
+  const problems = [];
+  const unresolvedIn = new Set();
+  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;
+  for (const pkg of packages) {
+    const name = pkg.manifest.name;
+    const dsh = pkg.manifest.dsh;
+    if (dsh === undefined) continue;
+    declared += 1;
 
-  // `dsh.bundle.patch` 允许是**一个字符串，也允许是一个数组**（dsh 自己的 dsh-web-app 就是数组：
-  // 它的 cordis.patch.yml + 四个 preset 文件全挂在这一处）。这里原来只按字符串处理，
-  // 于是第一个用数组的包会把判据**打崩**（ERR_INVALID_ARG_TYPE，堆栈指在 path.join 上，
-  // 而真正的问题是"声明形状没接住"）—— 外壳加 DIY 的 preset 时踩到。
-  const patches = dsh.bundle?.patch;
-  for (const patch of patches === undefined ? [] : Array.isArray(patches) ? patches : [patches]) {
-    if (!existsSync(join(pkg.dir, patch))) {
-      problems.push(`${name}: dsh.bundle.patch 指的 ${patch} 不存在`);
+    // `dsh.bundle.patch` 允许是**一个字符串，也允许是一个数组**（dsh 自己的 dsh-web-app 就是数组：
+    // 它的 cordis.patch.yml + 四个 preset 文件全挂在这一处）。这里原来只按字符串处理，
+    // 于是第一个用数组的包会把判据**打崩**（ERR_INVALID_ARG_TYPE，堆栈指在 path.join 上，
+    // 而真正的问题是"声明形状没接住"）—— 外壳加 DIY 的 preset 时踩到。
+    const patches = dsh.bundle?.patch;
+    for (const patch of patches === undefined ? [] : Array.isArray(patches) ? patches : [patches]) {
+      if (!existsSync(join(pkg.dir, patch))) {
+        problems.push(`${name}: dsh.bundle.patch 指的 ${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.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) {
+            unresolvedIn.add(pkg);
+            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'))) {
+    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}: 单元 ${JSON.stringify(unit)} 在外壳里还有一份（${SHELL}/src/modules/${unit}/）—— ` +
-          `同一个单元不许两边都住：两份真相，装上模块注册表当场抛`,
+        `${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}`);
+    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 —— ` +
-        `发布目标必须显式写出来（公网 / 内网），否则等于把私有模块发到公共源`,
-    );
-  }
+    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 依赖 —— 模块跑在外壳交出来的服务上，装的时候必须能说清版本`,
-    );
-  }
+    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/，模块出包之后没人替它跑`,
+        );
+      }
+    }
+
+    // 外部供给：清单里声明了 env，就要把"靠什么跑起来"和"没装好时怎么办"都说清。
+    // 外壳只按 env 去装（app/host.ts 把 plugins/libs 交给隔离运行时跑 probe/install），
+    // 它不知道这个能力叫什么 —— 所以"照做"那句安装命令必须由模块自己给。
+    const created = [];
+    const face = await unitFaceOf(pkg.dir);
+    const mounted = face === undefined ? undefined : mountOf(face, created);
+    const env = face?.manifest?.env;
+    if (env !== undefined) {
+      problems.push(...envProblemsOf(name, env));
+      const products = productsTextOf(pkg.dir);
+
+      // 声明的插件命令必须真的存在：拿 opencli 自带目录（按 site 归组，别名也算）与这台机器上
+      // 已装的插件包对一遍。**插件两头都找不到的就不管**（那说明这台机器还没装它，没得对，别误伤）——
+      // 拦的是"插件明明在，命令名却写错了"：那样用户那边的"缺命令"永远补不上。
+      const catalog = catalogBySite();
+      (env.plugins ?? []).forEach((plugin, index) => {
+        const pluginName = text(plugin?.name);
+        const declared = (plugin?.commands ?? []).map((one) => text(one)).filter((one) => one !== '');
+        if (pluginName === '' || declared.length === 0) return;
+        const builtIn = catalog?.get(pluginName);
+        const installed = pluginCommandsIn(pluginDirOf(pluginName));
+        if (builtIn === undefined && installed === undefined) return;
+        const known = new Set([...(builtIn ?? []), ...(installed ?? [])]);
+        const missing = declared.filter((one) => !known.has(one));
+        if (missing.length === 0) return;
+        const knownList = [...known].sort();
+        problems.push(
+          `${name}: env.plugins[${index}]（${pluginName}）声明的命令 ${missing.join(' / ')} 在插件里找不到 —— ` +
+            `它真有这些：${knownList.slice(0, 8).join(' / ')}${knownList.length > 8 ? ' …' : ''}。` +
+            `命令名写错的话，用户那边的"缺命令"永远补不上（用 \`opencli ${pluginName} --help\` 看原名）`,
+        );
+      });
+
+      if ((env.libs ?? []).length > 0 && !products.includes('libInstallCommand')) {
+        problems.push(
+          `${name}: 声明了 env.libs 却没用 libInstallCommand（@dsh-workbench/shared/host 里现成的）—— ` +
+            `lib 没装好时用户只看到"没装"，没有能照做的那条安装命令`,
+        );
+      }
+    }
+
+    // 「他能自己配什么」有两种：视图内选择（route 参数，刷新回默认）与偏好（prefs + store，刷新还在）。
+    // 设计表里写了哪一种就得真的接上哪一种 —— 否则用户改完刷新回到默认，而表上写着"能配"。
+    // （**与 env 无关**：没有 env 的模块一样要查，所以放在 env 块外面。）
+    const configRows = designRowsOf(pkg.dir, 'config');
+    const wiredPrefs = /\bprefs\s*:/.test(hostProductOf(pkg.dir));
+    const declaredPrefs = (configRows ?? []).some((one) => text(one?.['persistence']) === 'prefs');
+    if (declaredPrefs && !wiredPrefs) {
+      problems.push(
+        `${name}: 设计表里有一行写着"存起来"（config[].persistence = 'prefs'），产物里却没有接 prefs —— ` +
+          '用户改完刷新就回到默认，等于没存。接法：mount 返回 `prefs: { resource, handle }`，handle 里用 deps.store 落盘',
+      );
+    }
+    if (wiredPrefs && !declaredPrefs) {
+      problems.push(
+        `${name}: 产物里接了 prefs（能给用户配东西），设计表的 config[] 里却没有一行 persistence = 'prefs' —— ` +
+          '代码里能配、表上没写，下一个读表的人就不知道它刷新还在',
+      );
+    }
 
-  for (const script of ['build', 'typecheck', 'test', 'selfcheck']) {
-    if (pkg.manifest.scripts?.[script] === undefined) {
+    // 「这把能力在哪些项目里出现」：表里写了 workspace（按项目收窄），产物里就得真的实现 gate.deniedTools ——
+    // 否则每个项目里它都出现在工具清单里，agent 调了才发现不行（两次调用白花，而且它还会再试）。
+    // 反向**不查**：`deniedTools` 也用来"按自己的开关收窄"（比如能力没配好先藏起来），那不是项目作用域 ——
+    // 查反向会把这种合法用法判红。
+    const capabilityRows = designRowsOf(pkg.dir, 'capabilities');
+    const declaredWorkspaceScope = (capabilityRows ?? []).some((one) => text(one?.['scope']) === 'workspace');
+    if (declaredWorkspaceScope && !/\bdeniedTools\b/.test(hostProductOf(pkg.dir))) {
       problems.push(
-        `${name}: 没有 ${script} 脚本 —— 模块包必须自带整套门禁：` +
-          `外壳的 arch / 覆盖率 / 运行时边界都只扫自己的 src/，模块出包之后没人替它跑`,
+        `${name}: 设计表里有一条能力写着"只在某些项目里出现"（capabilities[].scope = 'workspace'），` +
+          '产物里却没有实现 gate.deniedTools —— 每个项目的工具清单里都有它，agent 调了才知道不行。' +
+          '接法：mount 返回 `gate: { deniedTools(workspace) { … }, subscribe }`（见 TOOLS.md §12）',
       );
     }
+
+    // 长任务：跑一会儿的事，注册了就得让用户看得见那四盏灯。
+    //
+    // 外壳按 mount 结果里的 longTasks 投影出 `${unit}/runs`（kit 的 useLongTask 读的就是它）。
+    // 契约里的状态只有四种：running / needs-login / ok / failed（`longTaskDot` 把它们映成
+    // 进行中 / 要登录 / 完成 / 出错）——**没有"停止"**，所以这里不查停止，只查"能不能画出来"：
+    //   · 注册表形状要全（少了方法，外壳那条 runs 路由读不动）；
+    //   · create 的 key 非空、run 与 view 都是函数（没有 view，卡片上那行就没有可渲染的快照）；
+    //   · 真的注册了长任务，客户端产物里就得出现 kit 那套（useLongTask / LongTaskRow / longTaskDot），
+    //     否则用户点完只看到"没反应"。
+    if (created.length > 0 || mounted?.longTasks !== undefined) {
+      const registry = mounted?.longTasks;
+      if (registry !== undefined) {
+        const missing = LONG_TASK_METHODS.filter((method) => typeof registry[method] !== 'function');
+        if (missing.length > 0) {
+          problems.push(
+            `${name}: 长任务注册表缺方法 ${missing.join(' / ')} —— 外壳按它给这个单元投影出 /runs 路由，` +
+              `kit 的 useLongTask 读的就是那条（注册表用 @dsh-workbench/shared/host 的 createLongTaskRegistry 建）`,
+          );
+        }
+      }
+      for (const options of created) {
+        if (text(options?.key) === '') {
+          problems.push(`${name}: longTasks.create 没给 key —— 一个单元可以有好几件跑一会儿的事，key 是它们的名字`);
+        }
+        if (typeof options?.run !== 'function') {
+          problems.push(`${name}: longTasks.create({key:'${String(options?.key ?? '')}'}) 没给 run —— 那它跑什么`);
+        }
+        if (typeof options?.view !== 'function') {
+          problems.push(
+            `${name}: longTasks.create({key:'${String(options?.key ?? '')}'}) 没给 view —— 卡片上那行要渲染的快照没处来`,
+          );
+        }
+      }
+      const clientText = existsSync(join(pkg.dir, 'client.js'))
+        ? readFileSync(join(pkg.dir, 'client.js'), 'utf8')
+        : '';
+      if (!LONG_TASK_RENDERERS.some((one) => clientText.includes(one))) {
+        problems.push(
+          `${name}: 注册了长任务，但客户端产物里没有 ${LONG_TASK_RENDERERS.join(' / ')}（kit 里那套）—— ` +
+            `用户点完只看得到"没反应"，看不到进行中 / 要登录 / 完成 / 出错`,
+        );
+      }
+    }
+
+    // 联动层：agent 动完 / 读完，面板那一格怎么知道要重读。
+    //
+    // 只查**形状**：`context.render` 不能拿假参数去调 —— 成熟模块在参数形状不对时是**故意 throw** 的
+    // （coding-issues 的 render 就是"缺陷引用的形状不对 → throw"），拿假参数调会误伤正确的模块。
+    // `factsOf` / `warmReads` 可以安全地拿空参数调一次，看它回的东西形状对不对。
+    if (mounted !== undefined) {
+      const factsOf = mounted.factsOf;
+      if (factsOf !== undefined && typeof factsOf !== 'function') {
+        problems.push(`${name}: factsOf 不是函数 —— 外壳调它的时候会当场抛`);
+      } else if (typeof factsOf === 'function') {
+        let claimed;
+        try {
+          claimed = factsOf({ source: '__contract_probe__', args: {}, result: undefined });
+        } catch {
+          claimed = undefined;
+        }
+        const ok =
+          claimed === undefined ||
+          (Array.isArray(claimed) && claimed.every((one) => text(one) !== ''));
+        if (!ok) {
+          problems.push(
+            `${name}: factsOf 要么回 undefined（这次跟面板无关）、要么回一串非空的事实名 —— ` +
+              `现在回的是 ${JSON.stringify(claimed)}（事实名用 factOfRoute('<unit>/<路由>') 起，别自己拼）`,
+          );
+        }
+      }
+
+      const context = mounted.context;
+      if (context !== undefined) {
+        const kinds = context.kinds;
+        if (!Array.isArray(kinds) || kinds.length === 0 || kinds.some((one) => text(one) === '')) {
+          problems.push(
+            `${name}: context.kinds 要是非空的一串类别名 —— agent 引用你这一格时，认哪几类由它决定`,
+          );
+        }
+        if (typeof context.render !== 'function') {
+          problems.push(`${name}: context.render 不是函数 —— agent 引用你这一格时没人把它渲染成人话`);
+        }
+      }
+
+      const warmReads = mounted.warmReads;
+      if (warmReads !== undefined) {
+        if (typeof warmReads !== 'function') {
+          problems.push(`${name}: warmReads 不是函数`);
+        } else {
+          let reads;
+          try {
+            reads = warmReads();
+          } catch {
+            reads = undefined;
+          }
+          const ok =
+            Array.isArray(reads) &&
+            reads.every(
+              (one) => Array.isArray(one) && one.length > 0 && one.every((part) => text(part) !== ''),
+            );
+          if (!ok) {
+            problems.push(
+              `${name}: warmReads() 要回一串 [['<unit>', '<target>']] —— 现在回的是 ${JSON.stringify(reads)}`,
+            );
+          }
+        }
+      }
+    }
+
+    // 声明会写的工具，必须同时认领"这次要不要点头"。
+    //
+    // 外壳每次调用前都会问套件：writes:true 的工具，needsApproval 不给 verdict.kind==='ask'
+    // 就**当场 deny**（原文："在套件的 needsApproval 里补一条审批（含"这次会发生什么"），别让写静默过去"）——
+    // 那条错误只有真跑一次才看得见，用户看到的是一次莫名其妙的拒绝。所以门禁在出包前先看一遍：
+    //   · needsApproval 要给完整的 ask 口径（理由 + 问句 + 兜底文案，zh/en 都要）；
+    //   · approvalDetail 要说清"这次会发生什么"（审批屏上就靠它，缺了只剩一句通用问句）。
+    const writeTools = (face?.manifest?.tools ?? []).filter((one) => one?.writes === true);
+    if (writeTools.length > 0) {
+      if (mounted === undefined) {
+        problems.push(
+          `${name}: 清单里有会写的工具，但宿主面挂不起来（apply / mount 抛了）—— ` +
+            `这条审批口径验不了，先把挂载依赖修好（模块自己的 smoke 也是这么挂的）`,
+        );
+        continue;
+      }
+      for (const tool of writeTools) {
+        const call = { name: tool.name, arguments: {}, workspace: null };
+        let verdict;
+        try {
+          verdict = mounted?.needsApproval?.(call);
+        } catch {
+          verdict = undefined;
+        }
+        // 合法口径有两种：`{ kind: 'read' }`（这件事不用问 —— 例：没什么可做的）与
+        // `{ kind: 'ask', reason, question{zh,en}, fallback{zh,en} }`（要问，且问得清）。
+        // 别的返回值（**包括 undefined**）外壳会当场 deny —— 那才是要拦的。
+        const read = verdict?.kind === 'read';
+        const ask =
+          verdict?.kind === 'ask' &&
+          text(verdict.reason) !== '' &&
+          text(verdict.question?.zh) !== '' &&
+          text(verdict.question?.en) !== '' &&
+          text(verdict.fallback?.zh) !== '' &&
+          text(verdict.fallback?.en) !== '';
+        if (!read && !ask) {
+          problems.push(
+            `${name}: 工具 ${tool.name} 的清单里写着 writes:true，但 needsApproval 没给出合法口径 —— ` +
+              `要么 { kind: 'read' }（这件事不用问），要么 { kind: 'ask', reason, question: {zh,en}, ` +
+              `fallback: {zh,en} }（要问，且问得清）。别的返回值外壳会当场 deny`,
+          );
+          continue;
+        }
+        let facts;
+        try {
+          facts = await mounted?.approvalDetail?.(call);
+        } catch {
+          facts = undefined;
+        }
+        const described =
+          facts !== undefined &&
+          ('blocked' in facts
+            ? text(facts.blocked) !== ''
+            : text(facts.zh) !== '' && text(facts.en) !== '');
+        if (!described) {
+          problems.push(
+            `${name}: 写工具 ${tool.name} 没给 approvalDetail（"这次会发生什么"，zh/en 或 {blocked}）—— ` +
+              `审批屏上用户只能看到一句通用问句，看不到会动什么`,
+          );
+        }
+      }
+    }
   }
-}
 
-const unitList = [...units.entries()].map(([unit, name]) => `${unit} ← ${name}`).join(' · ');
+  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);
+  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]} —— ` +
+            `外壳不许认识任何模块（那等于把"中央清单"搬进外壳）；模块靠服务名挂进来`,
+        );
       }
-    };
-    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) {
+    const notes = [`${declared} 个带 dsh 声明的包，其中 ${modules} 个模块`];
+    // 落不到图里最常见的成因不是"声明写错"，而是"这个包不在任何 workspace 里"（裸目录里 init
+    // 出来的骨架）。不点出来的话，屏幕上的话会把责任推给那两条声明，而真正该做的是换到工坊里跑。
+    const bare = [...unresolvedIn].filter(barePackage);
+    if (bare.length > 0) {
+      notes.push(
+        `上面有 ${bare.length} 个包是**裸**的：它上面没有 pnpm-workspace.yaml、自己也没有 node_modules —— ` +
+          `那几条 inject/external 正是因为找不到任何同伴包才落不到图里。` +
+          `做法：在工坊里造（$DSH_HOME/workbench/diy/packages/module-<名字>），或者先在这个工作区里 pnpm install。`,
       );
     }
+    return { status: 'fail', notes, problems };
   }
-}
 
-if (problems.length > 0) {
-  console.error(`✖ 模块契约 ${problems.length} 条不过（${declared} 个带 dsh 声明的包，其中 ${modules} 个模块）：`);
-  for (const problem of problems) console.error(`  · ${problem}`);
-  process.exit(1);
+  return {
+    status: 'pass',
+    notes: [
+      `${declared} 个带 dsh 声明的包（${modules} 个模块）· bundle 落点存在 · ` +
+        `inject/external 都能落到图里 · 单元 id 唯一 · 面文件与 peer 都在 · 各有接线自检`,
+      '（test 不在这儿跑：状态级的东西在模块自己的 vitest 里 —— 四个脚本自己跑一遍）',
+      `单元：${unitList}`,
+    ],
+    problems: [],
+  };
 }
-
-console.log(
-  `✔ 模块契约通过：${declared} 个带 dsh 声明的包（${modules} 个模块）· bundle 落点存在 · ` +
-    `inject/external 都能落到图里 · 单元 id 唯一 · 面文件与 peer 都在 · 各有接线自检`,
-);
-console.log(`  单元：${unitList}`);