@dsh-workbench/module-tools 0.3.11 → 1.0.0-beta.1

package/src/checks/cards.mjs

@@ -19,9 +19,6 @@ const FORBIDDEN = [
 
 const WORKSPACE = { path: '/tmp/repo', workspaceId: 'wb-card-probe' };
 
-// 刷新那一帧的旧时间戳（`at`）。真壳在 `ready` 那一步写 `Date.now()`，同一个 identity 重读时
-// 把它原样带进 loading 相（`use-api-resource.ts:102`）；这里给一个固定的过去时刻，判据不依赖
-// "现在几点"（同一个值每次跑都一样，负例才好断言）。
 const STALE_AT = 1_700_000_000_000;
 
 function anyStub(path = 'stub') {
@@ -103,51 +100,52 @@ const SNAPSHOTS = [
     resource: { phase: 'error', error: { code: 'network', message: '宿主没有响应' } },
     workspace: WORKSPACE,
   },
-  // P2 第一条：刷新形态（ADR-0022「刷新保留旧值」）。载荷与 `loading` 只差两格 —— `value` 与
-  // `at` 都在，而且是旧那份。`use-api-resource.ts:100-104` 在同一个 identity 重读时给的就是这一相
-  // （`{ phase: 'loading', value: prev.value, ...(prev.at === undefined ? {} : { at: prev.at }) }`，
-  // 而 `prev.at` 是 `ready` 那一步写的 `Date.now()`，所以真实这一相两格一起在）。卡片若把
-  // "loading 就没有值"写死，脏就出在这一帧；若把旧值当新值、或拿旧 `at` 当"刚读到"去算，脏也出在这一帧。
+
   {
     name: 'loading（刷新：保留旧值）',
     resource: { phase: 'loading', value: containerStub('api', 2), at: STALE_AT },
     workspace: WORKSPACE,
   },
-  // P2 第二条：能力闸。`useCapabilityGate` 给一个**明确的** `missing-plugin`（不是 `null`）：
-  // `use-unit-board.ts:47` 对 `capability === null` 直接不算 `blockerOfCapability`，喂 null 就退化成
-  // P1 的 idle 那一屏、一格新代码都走不到。`gated` 由能力状态按 `gateOf`（`unit-board.ts:13-17`）
-  // 算出来（missing-plugin ⇒ false），`resource` 照 `ready` 一份 —— 于是它跟 `ready` 只差闸这一格，
-  // 阻断屏与正文同时在场时谁优先是模块的事。
+
   {
     name: 'unreadable（能力闸：缺插件）',
     resource: { phase: 'ready', value: containerStub('api', 2) },
     workspace: WORKSPACE,
     capability: (unit) => ({
       unit,
-      status: 'missing-plugin',
-      required: ['demo-plugin'],
-      missing: ['demo-plugin'],
+      status: 'missing',
+      needs: [
+        {
+          id: 'extension:demo-plugin',
+          kind: 'extension',
+          name: 'demo-plugin',
+          status: 'missing',
+          detail: '逐态探针：缺 demo-plugin',
+        },
+      ],
       detail: '逐态探针：缺 demo-plugin',
     }),
   },
-  // P2 补记：能力闸的第二种 status —— `missing-commands`（插件在、命令旧）。它与缺插件那一帧
-  // 差的是两格：`status` 换掉，且 `fix` / `command` 都在（真壳 `probe-verdict.ts:109-116`：命令落后
-  // 的插件状态是 `outdated`，于是 `fix: 'update'`；`:158-160` 再带上那条升级命令）。这两格正好把
-  // `blockerOfCapability` 里 `install` 那一段走通：`fixAction`（`blocker.fix.update`）+ `copyAction`
-  // （`blocker.copy` + `command` 原文，`blocker-table.ts:109-123`），加上照旧的 retry —— 缺插件那一帧
-  // 两格都没给，install 是空的，只走到 retry。`sourceUnknown` 在 `fix` 在时不成立，所以不开市场那条。
+
   {
     name: 'unreadable（能力闸：缺命令）',
     resource: { phase: 'ready', value: containerStub('api', 2) },
     workspace: WORKSPACE,
     capability: (unit) => ({
       unit,
-      status: 'missing-commands',
-      required: ['demo-plugin'],
-      missing: ['demo.command'],
+      status: 'outdated',
+      needs: [
+        {
+          id: 'extension:demo-plugin',
+          kind: 'extension',
+          name: 'demo-plugin',
+          status: 'outdated',
+          missing: ['demo.command'],
+          detail: '逐态探针：demo-plugin 装在，缺 demo.command',
+          command: "'opencli' plugin update 'demo-plugin'",
+        },
+      ],
       detail: '逐态探针：demo-plugin 装在，缺 demo.command',
-      fix: 'update',
-      command: 'opencli plugin update demo-plugin',
     }),
   },
 ];
@@ -403,9 +401,7 @@ export async function run() {
       if (realKit === undefined) return fakeKit();
       const hooks = { ...(realKit.hooks ?? {}) };
       hooks.useApiResource = () => current.snapshot.resource;
-      // 闸这一格的默认（P1 五态都是它）：没查过 ⇒ capability null、gated true。快照带了
-      // `capability` 才换成那一份，`gated` 照 `gateOf(capability, 'capability')` 算 —— 判据不当
-      // 第二份真相：状态的语义归外壳，这里只是把"外壳会给的那一格"摆出来。
+
       hooks.useCapabilityGate = (unit) => {
         const capability = current.snapshot.capability?.(unit) ?? null;
         return {

package/src/checks/contracts.mjs

@@ -1,29 +1,8 @@
-// 跨包的**模块契约**检查（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` 形状合法、全局唯一（撞了就是装上去当场抛）；
-//       - `dsh.workbenchFaces.host` / `.client` 指的源码入口文件真的在 ——
-//         它是**工具链字段**，不在 `dsh.workbench` 协议里（ADR-0038 §7 第 7 条）：
-//         `source` 判据靠这两个入口做可达性分析，所以它必须是源码路径、必须声明；
-//       - 对壳有 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, pathToFileURL } from 'node:url';
-import { readDeclaration } from '@dsh-workbench/shared/host';
+import { buildSupplyIndex, readDeclaration, recipeProblemOf } from '@dsh-workbench/shared/host';
 import {
   DECLARED_TOOLS_FILE,
   declaredToolsProblemOf,
@@ -31,11 +10,12 @@ import {
   declaredToolsApplies,
 } from '../declared-tools.mjs';
 import { discoverPackages, workspaceRootOf } from '../discover.mjs';
+import { readDesign } from '../design.mjs';
+import { datasourceProblemOf } from '../datasource-file.mjs';
 import { SEED_SHORT } from '../seed.mjs';
 
 const ROOT = process.env.DSH_WB_ROOT ?? fileURLToPath(new URL('../../../../', import.meta.url));
 
-/** dsh 浏览器侧的固定 seed 词表（模块表里天生就有的那几个）—— 唯一真相在 `../seed.mjs`。 */
 const SEED = SEED_SHORT;
 
 const PLATFORMS = new Set(['web']);
@@ -50,10 +30,6 @@ 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;
@@ -82,58 +58,6 @@ async function unitFaceOf(dir) {
   }
 }
 
-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';
 
@@ -216,10 +140,6 @@ function sourceFilesOf(dir) {
   return found;
 }
 
-// `plugin: '<字面量>'` 与同一行里 `?? '<字面量>'` 的兜底：都该是**清单里声明过**的那个插件名。
-// 插件名只该有一处真相（能拿到 `deps.manifest` 的地方就用它），但模块级代码拿不到 manifest ⇒ 只能写字面量。
-// 这条判据拦的是"改了清单没改代码"（或反过来）：那样外壳会按错的名字去装 / 去探那个插件，而用户只看到
-// "缺命令"这种没头没尾的状态。只查 `plugin:` 那几行，别的字面量不管（不猜）。
 function pluginLiteralsOf(line) {
   if (!/\bplugin\s*:/.test(line)) return [];
   const found = [];
@@ -251,8 +171,7 @@ function fakeLongTasks(created) {
   return {
     create(options) {
       created.push(options);
-      // 形状跟着真外壳那份注册表走（`createLongTaskRegistry`）：假的那份少一个方法，
-      // 把注册表原样返回的模块就会被这条判据冤枉成"缺方法"——所以 `stop` / `live` 也在这里。
+
       return {
         start: () => ({}),
         snapshot: () => null,
@@ -266,10 +185,6 @@ function fakeLongTasks(created) {
   };
 }
 
-// 契约里 mount 一定拿得到 deps.store（外壳给的是 WorkspaceStore）。假的 deps 少给这一样，
-// 用到 store 的模块（存偏好是最常见的用法）就会在这里抛、被当成"mount 坏了"，
-// 然后在审批那条判据上被冤枉成"没给出合法口径"。所以假 store 也给它一个：
-// for / machine / scan 都回同一个内存文件区，写进去的东西后面读得回来。
 function fakeStore() {
   const files = new Map();
   const one = () => ({
@@ -286,11 +201,6 @@ function fakeStore() {
   return { for: () => one(), machine: () => one(), scan: () => [one()] };
 }
 
-// mount 也一定拿得到 shell 与 workspaceRegistry（外壳给的是 dsh 交出来的服务）。
-// 少给这两样，模块的**降级写法**就会生效 —— 而"拿不到 shell 就只交 routes + registerTools"
-// 是合法写法（实测 pduiv2 的 coding-issues / coding-analysis 就这么写），降级后的面本来就不带
-// 审批钩子，判据却会把这读成"没认领审批"：红的是判据自己的环境，不是模块。
-// （与上面 `store` 那笔账同一条纪律：假 deps 少给一样，模块就在这条判据上被冤枉。）
 function fakeShell() {
   return {
     resolve: () => undefined,
@@ -316,7 +226,7 @@ function fakeWorkspaceRegistry() {
 
 function mountOf(face, created, manifest, tools) {
   if (face === undefined || typeof face.mount !== 'function') return undefined;
-  // 假服务**一次 mount 内是同一个对象**（真外壳给的就是同一个）—— 有的模块会拿两次再比。
+
   const shell = fakeShell();
   const workspaceRegistry = fakeWorkspaceRegistry();
   const toolRegistry = {
@@ -343,6 +253,17 @@ function mountOf(face, created, manifest, tools) {
       },
       manifests: () => [],
       opencliCommand: 'opencli',
+      env: {},
+      git: {
+        origin: async () => ({ kind: 'no-origin' }),
+        branch: async () => ({ kind: 'no-branch' }),
+        head: async () => ({ kind: 'no-head' }),
+      },
+      libs: {
+        load: async () => {
+          throw new Error('gate: libs 未装');
+        },
+      },
       store: fakeStore(),
       longTasks: fakeLongTasks(created),
     });
@@ -355,16 +276,6 @@ const LONG_TASK_METHODS = ['start', 'snapshot', 'active', 'current', 'live', 'st
 
 const LONG_TASK_RENDERERS = ['useLongTask', 'LongTaskRow', 'longTaskDot'];
 
-// 审批探针要用的**合成调用**。
-//
-// 为什么不是 `{ arguments: {} }`：外壳调 needsApproval 时拿到的是 agent 真传的参数，
-// 而"这次要不要点头"本来就允许依赖参数 —— "带 confirm: true 才真的写"是最常见的合法口径。
-// 空参数探会把这类模块判成"没认领审批"（实测 pduiv2 那 4 条审批报错就是这么来的，
-// ADR-0038 §6.15）。所以能拿到工具的 `parameters`（JSON Schema）时，按**必填项**造一个
-// 形状合法的调用：枚举取第一个值，string / number / boolean / array / object 各给一个占位值。
-//
-// 拿不到（registerTools() 没注册出这把工具、或注册时没带 parameters）就退回空参数，
-// 并在判红时把这件事写进那句话 —— 那种情况下判据只能验到"钩子在不在"这一层。
 function placeholderOf(schema) {
   if (typeof schema !== 'object' || schema === null) return null;
   if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
@@ -389,36 +300,12 @@ function probeCallOf(tool) {
   return { arguments: args, shaped: true };
 }
 
-// 审批头行（dsh 那张卡的 `.headline`）的预算。
-//
-// 为什么要有这条：`.headline` 是**纯文本的一格**，没有 `white-space` —— 换行会被塌成空格，
-// 长句就不是"多几行"而是"一大坨"。三段都会落进那一格（外壳按 `明细 —— 问句 —— 附注` 拼）：
-//   · `approvalDetail` 的 zh/en  = 明细（模块写的"这次要动什么"，本该是一句短标题）
-//   · `question` 的 zh/en        = 问句（外壳拼在明细后面的那句"允许吗"）
-//   · `fallback` 的 zh/en        = 兜底整句（明细缺失时顶上来）
-// 长内容（文件路径 / diff / 列表 / 正文 / 多字段）该走模块的 `approval.render`：
-// 那是卡上**另一格**（`conversation.approval.detail`），有排版、能换行、能画 diff。
-// 实测（2026-10-16 一条真实审批卡）：明细里塞了一整条 commit message、问句 77 字、附注 75 字，
-// 屏幕上 5 行 300 字。
 export const HEAD_BUDGETS = { detail: 20, question: 40, fallback: 40 };
 
-// 英文那一侧只用来抓"真正的一坨"：按中文的 3 倍算。长度主要看中文那侧（用户读的是它），
-// 实测同一句的英文是中文的 2.2–2.8 倍（machine 直译的风格），按 2 倍算会把正常英文问句全判红。
 const EN_RATIO = 3;
 
-// 长度预算是**两轮**的：
-//   · 第 1 轮（占位短值，见 probeCallOf）：紧预算 —— 头行本来就该是一句短句；
-//   · 第 2 轮（长值，见 budgetProbeOf）：宽 3 倍 —— 专抓"把可变长字段塞进头行"。
-//    宽 3 倍是故意的：对象名、文件名这类标识符本来就有长有短，不该因为"名字长"判红；
-//    而一条 commit message、一段正文（60 字）塞进标题，3 倍也照样兜不住 —— 那才是要抓的。
 const LONG_SCALE = 3;
 
-// 只按必填项造的探针（`probeCallOf`）给的是**占位短值**（`probe` / `1` / `true`）——
-// 于是"把可变长字段塞进头行"这件事它是**瞎的**：实测那条真实审批卡的明细是
-// `改对象文件：对象「diep-dify」的「tencent-test-values.yaml」 仓库：helm 提交信息：<一整条 commit message>`（157 字），
-// 而探针上只有 20 字（`probe`）⇒ 判据照绿。所以第 2 轮把**自由文本字段**换成真长度（60 字）：
-// 名字里带 message / note / reason / body / text / content / comment / title / description / summary
-// 的字段（这些就是"人可以写一段话"的地方），其余 string（标识符）给 12 字的正常长度。
 const FREE_TEXT = /message|note|reason|body|text|content|comment|title|description|summary/i;
 const LONG_TEXT = '这里是一段真实长度的正文用来量头行预算不要把这种内容放进标题里'.repeat(2);
 const LONG_ID = '真实长度的名字十二个字';
@@ -488,11 +375,6 @@ 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'));
 }
@@ -502,7 +384,6 @@ function packageOf(specifier) {
   return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
 }
 
-/** 深比较两份 JSON：对象**键序无关**，数组**顺序有关**（工具那一串的顺序是声明的一部分）。 */
 function reconcileTools(name, manifest, toolNames) {
   const declared = manifest.tools.map((tool) => tool.name).sort();
   const actual = [...new Set(toolNames.filter((one) => one !== ''))].sort();
@@ -519,10 +400,11 @@ export async function run() {
   const packages = discoverPackages({ root: process.cwd() });
   const known = new Set(packages.map((pkg) => pkg.manifest.name));
   const problems = [];
+  const warnings = [];
   const unresolvedIn = new Set();
   const units = new Map();
-  // 判据"看到了但下不了结论"的那些，写进 notes（红绿两边都印）——
-  // 与其给一个撑不住的 verdict，不如把作者该自己确认的那一件事说清楚（ADR-0038 §6.15）。
+  const supplyDeclarations = [];
+
   const probeNotes = [];
   const headlineNotes = [];
   let declared = 0;
@@ -534,10 +416,6 @@ export async function run() {
     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))) {
@@ -589,10 +467,6 @@ export async function run() {
       }
     }
 
-    // 清单里的工具名与「代码里那份名字」的关系（ADR-0038 的 `tools[].key` 一节）：
-    // 给了 key 就走生成物那一档 —— `src/declared-tools.ts` 必须存在、且与清单一致（过期 = 红），
-    // 并且源码里不许再有工具名的字面量（名字只写在清单里，代码引用 `DECLARED_TOOLS.<key>.name`，
-    // 键写错是编译错）。一个 key 都没写的模块不适用（那是不用生成物那一档）。
     const declaredProblem = declaredToolsProblemOf(pkg.dir, dsh.workbench);
     if (declaredProblem !== undefined) {
       problems.push(`${name}: ${declaredProblem}`);
@@ -660,17 +534,21 @@ export async function run() {
       }
     }
 
-    // 外部供给：清单里声明了 env，就要把"靠什么跑起来"和"没装好时怎么办"都说清。
-    // 外壳只按 env 去装（app/host.ts 把 plugins/libs 交给隔离运行时跑 probe/install），
-    // 它不知道这个能力叫什么 —— 所以"照做"那句安装命令必须由模块自己给。
     const read = readDeclaration(name, dsh.workbench);
     const manifest = read.manifest;
     const created = [];
-    // 注册出来的**工具对象**（不只是名字）：审批探针要读它的 `parameters` 造形状合法的调用。
+
     const tools = [];
     const face = await unitFaceOf(pkg.dir);
     const mounted = face === undefined ? undefined : mountOf(face, created, manifest, tools);
-    const env = manifest?.env;
+    const needs = manifest?.needs;
+    warnings.push(...read.warnings);
+    if (manifest === undefined) {
+      for (const one of read.problems) problems.push(one);
+    }
+    if (manifest !== undefined) {
+      supplyDeclarations.push({ id: manifest.id, needs: needs ?? [] });
+    }
 
     if (manifest !== undefined) {
       if (face === undefined) {
@@ -694,15 +572,12 @@ export async function run() {
       }
     }
 
-    if (env !== undefined) {
-      problems.push(...envProblemsOf(name, env));
+    if (needs !== undefined) {
       const products = productsTextOf(pkg.dir);
+      const extensions = needs.filter((need) => need?.kind === 'extension');
 
-      // 声明的插件命令必须真的存在：拿 opencli 自带目录（按 site 归组，别名也算）与这台机器上
-      // 已装的插件包对一遍。**插件两头都找不到的就不管**（那说明这台机器还没装它，没得对，别误伤）——
-      // 拦的是"插件明明在，命令名却写错了"：那样用户那边的"缺命令"永远补不上。
       const catalog = catalogBySite();
-      (env.plugins ?? []).forEach((plugin, index) => {
+      extensions.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;
@@ -714,15 +589,13 @@ export async function run() {
         if (missing.length === 0) return;
         const knownList = [...known].sort();
         problems.push(
-          `${name}: env.plugins[${index}]（${pluginName}）声明的命令 ${missing.join(' / ')} 在插件里找不到 —— ` +
+          `${name}: needs 里第 ${index} 条 extension（${pluginName}）声明的命令 ${missing.join(' / ')} 在插件里找不到 —— ` +
             `它真有这些：${knownList.slice(0, 8).join(' / ')}${knownList.length > 8 ? ' …' : ''}。` +
             `命令名写错的话，用户那边的"缺命令"永远补不上（用 \`opencli ${pluginName} --help\` 看原名）`,
         );
       });
 
-      const declaredPlugins = new Set(
-        (env.plugins ?? []).map((one) => text(one?.name)).filter((one) => one !== ''),
-      );
+      const declaredPlugins = new Set(extensions.map((one) => text(one?.name)).filter((one) => one !== ''));
       if (declaredPlugins.size > 0) {
         for (const file of sourceFilesOf(pkg.dir)) {
           readFileSync(file, 'utf8')
@@ -732,7 +605,7 @@ export async function run() {
                 if (declaredPlugins.has(literal)) continue;
                 problems.push(
                   `${name}: ${relative(pkg.dir, file)}:${index + 1} 里的插件名「${literal}」不在清单的 ` +
-                    `env.plugins[] 里（清单里是 ${[...declaredPlugins].join(' / ')}）—— 改了清单没改代码` +
+                    `needs（kind=extension）里（清单里是 ${[...declaredPlugins].join(' / ')}）—— 改了清单没改代码` +
                     '（或反过来）会让外壳按错的名字去装 / 去探那个插件。插件名只有一处真相：' +
                     '能拿到 deps.manifest 的地方就用它，拿不到的地方至少与清单保持一致',
                 );
@@ -741,17 +614,21 @@ export async function run() {
         }
       }
 
-      if ((env.libs ?? []).length > 0 && !products.includes('libInstallCommand')) {
+      const usesLibPort = sourceFilesOf(pkg.dir).some((file) =>
+        /(?:\blibs\.load\b|\bworkflowFromLibs\b|\bLibReader\b)/.test(readFileSync(file, 'utf8')),
+      );
+      if (
+        needs.some((need) => need?.kind === 'lib') &&
+        !products.includes('libInstallCommand') &&
+        !usesLibPort
+      ) {
         problems.push(
-          `${name}: 声明了 env.libs 却没用 libInstallCommand（@dsh-workbench/shared/host 里现成的）—— ` +
+          `${name}: 声明了 lib 类 need 却既没用 libInstallCommand，也没走 core 的 LibReader（libs.load）—— ` +
             `lib 没装好时用户只看到"没装"，没有能照做的那条安装命令`,
         );
       }
     }
 
-    // 「他能自己配什么」有两种：视图内选择（route 参数，刷新回默认）与偏好（prefs + store，刷新还在）。
-    // 设计表里写了哪一种就得真的接上哪一种 —— 否则用户改完刷新回到默认，而表上写着"能配"。
-    // （**与 env 无关**：没有 env 的模块一样要查，所以放在 env 块外面。）
     const configRows = designRowsOf(pkg.dir, 'config');
     const hostProduct = hostProductOf(pkg.dir);
     const wiredPrefs = /\bprefs\s*:/.test(hostProduct);
@@ -769,9 +646,25 @@ export async function run() {
       );
     }
 
-    // 底稿与清单只对账**键集合**：`design.json` 的 `capabilities[].name` 与清单的 `tools[].name`
-    // 不重不漏（ADR-0038 §2.5）。**只对名字**：内容各写一处（人话在底稿、机器字段在清单），没有可比的东西。
-    // 没有 `design.json` 的模块不查（底稿是可选的，契约不要求它）；清单形状坏了的也不查（protocol 已经说话了）。
+    const design = readDesign(pkg.dir);
+    const datasourceProblem = datasourceProblemOf(pkg.dir, design);
+    if (datasourceProblem !== undefined) problems.push(`${name}: ${datasourceProblem}`);
+
+    const reads =
+      design !== undefined && Array.isArray(design.reads) && design.reads.length > 0
+        ? design.reads
+        : design !== undefined && design.datasource !== undefined
+          ? [design.datasource]
+          : [];
+    for (const read of reads) {
+      const recipe = read?.recipe;
+      if (recipe === undefined) continue;
+      const problem = recipeProblemOf(recipe);
+      if (problem !== undefined) {
+        problems.push(`${name}: design.json 的配方不合法（${problem}）—— 跑 \`dsh-wb-module design check\` 看点名`);
+      }
+    }
+
     const capabilityRows = designRowsOf(pkg.dir, 'capabilities');
     if (capabilityRows !== undefined && manifest !== undefined) {
       const inDesign = capabilityRows.map((one) => text(one?.name)).filter((one) => one !== '');
@@ -792,22 +685,6 @@ export async function run() {
       }
     }
 
-    // 长任务：跑一会儿的事，注册了就得让用户看得见那一行。
-    //
-    // 外壳按 mount 结果里的 longTasks 投影出 `${unit}/runs`（kit 的 useLongTask 读的就是它）。
-    // 契约里的状态是**五种**：running / needs-login / stopped / ok / failed（`longTaskDot` 把它们映成
-    // 进行中 / 要登录 / 灰点 / 完成 / 出错 —— `stopped` 落进默认分支，是"用户按停的"，不是成功也不是出错）。
-    // 契约里也**有"停止"**：注册表多一个 `stop(id)`，`run` 多收一个 `signal`。
-    // `start` 还可以带一个**可选**的 `session`（起这一趟的那个会话 id，模块从 `sessionIdOf(exec)` 拿）：
-    // 不记 = 用户在界面上按的 —— 外壳那两把 `workbench_long_tasks_*` 按它判"谁的"（自己起的免审批）。
-    // 判据**不查**这一条（它只查形状；"起的时候记没记来源"是形状之外的事）。
-    // 但"停止"在注册表这一侧的射程只有两件：外壳把 `signal` abort 掉、把这一趟标成 `stopped`；
-    // **真停不停得了看生产方认不认这个 signal** —— 那是模块的知识，判据查不了这一条
-    // （内部是 opencli 子进程那类编排，今天最多做到"我们不再等它"）。判据能查的是形状与"画得出来"：
-    //   · 注册表形状要全（少了方法，外壳那条 runs 路由 / 那颗停止钮就按不动）；
-    //   · create 的 key 非空、run 与 view 都是函数（没有 view，卡片上那行就没有可渲染的快照）；
-    //   · 真的注册了长任务，客户端产物里就得出现 kit 那套（useLongTask / LongTaskRow / longTaskDot），
-    //     否则用户点完只看到"没反应"。
     if (created.length > 0 || mounted?.longTasks !== undefined) {
       const registry = mounted?.longTasks;
       if (registry !== undefined) {
@@ -844,11 +721,6 @@ export async function run() {
       }
     }
 
-    // 联动层：agent 动完 / 读完，面板那一格怎么知道要重读。
-    //
-    // 只查**形状**：`context.render` 不能拿假参数去调 —— 成熟模块在参数形状不对时是**故意 throw** 的
-    // （coding-issues 的 render 就是"缺陷引用的形状不对 → throw"），拿假参数调会误伤正确的模块。
-    // `factsOf` / `warmReads` 可以安全地拿空参数调一次，看它回的东西形状对不对。
     if (mounted !== undefined) {
       const factsOf = mounted.factsOf;
       if (factsOf !== undefined && typeof factsOf !== 'function') {
@@ -909,21 +781,6 @@ export async function run() {
       }
     }
 
-    // 声明会写的工具，必须同时认领"这次要不要点头"。
-    //
-    // 外壳每次调用前都会问套件：writes:true 的工具，needsApproval 不给 verdict.kind==='ask'
-    // 就**当场 deny**（原文："在套件的 needsApproval 里补一条审批（含"这次会发生什么"），别让写静默过去"）——
-    // 那条错误只有真跑一次才看得见，用户看到的是一次莫名其妙的拒绝。所以门禁在出包前先看一遍。
-    //
-    // **这条判据只能验到哪一层**（原样写给以后改它的人）：
-    //   · 硬事实：一个 writes:true 的工具，mount() 有没有把 needsApproval 交出来；
-    //   · 判据能造出合成调用时：对那次调用给的 verdict 形状对不对；verdict 是 ask 时
-    //     approvalDetail 说没说清"这次会发生什么"；
-    //   · **验不了的**：真实写入调用会不会真的 ask。答案依赖参数的模块（"带 confirm: true 才真的写"）
-    //     在合成调用上依法回 `{ kind: 'read' }` —— 外壳那条路（shared/host/tool-approval.ts）在 read
-    //     时**根本不会问 approvalDetail**，所以这里也不再逼它给。这类模块列进 notes 让作者自己确认。
-    //   · 空参数探会误报：合成调用按声明里的 `parameters` 必填项造（见 probeCallOf），
-    //     造不出来时退回空参数并把这件事写进判红那句。
     const writeTools = (manifest?.tools ?? []).filter((one) => one?.writes === true);
     if (writeTools.length > 0) {
       if (mounted === undefined) {
@@ -960,12 +817,9 @@ export async function run() {
           );
           continue;
         }
-        // 合法口径有两种：`{ kind: 'read' }`（这件事不用问 —— 例：没什么可做的）与
-        // `{ kind: 'ask', reason, question{zh,en}, fallback{zh,en} }`（要问，且问得清）。
-        // 别的返回值（**包括 undefined**）外壳会当场 deny —— 那才是要拦的。
+
         const read = verdict?.kind === 'read';
-        // deny（ADR-0032 第五态）：套件说"这一通根本跑不成" —— 外壳在备料之前就拒，连问都不问。
-        // 合成调用上它合法，但和 read 一样验不到"真的调用会不会问"，进 notes 让作者自己确认。
+
         const deny = verdict?.kind === 'deny' && text(verdict.reason) !== '';
         const ask =
           verdict?.kind === 'ask' &&
@@ -984,9 +838,7 @@ export async function run() {
           );
           continue;
         }
-        // read / deny：这次调用不用点头。**不查 approvalDetail** —— 外壳在这两档都不会去问它
-        // （`approvalFor` 只在 verdict 是 ask 时才调 detailOf）。合成调用本来就不是一次真实写入，
-        // 拿它逼模块给"这次会发生什么"就是让判据替外壳问一个外壳不会问的问题。
+
         if (read || deny) {
           readOnProbe.push(tool.name);
           continue;
@@ -1003,8 +855,7 @@ export async function run() {
             ? text(facts.blocked) !== ''
             : text(facts.zh) !== '' && text(facts.en) !== '');
         problems.push(...headlineProblemsOf(name, tool.name, verdict, facts));
-        // 第二轮：**长值**探（把声明里的 string 都填成 40 字正文、可选字段也填上），
-        // 专抓"标题里带了可变长字段"—— 第一轮用的是占位短值，对这件事是瞎的（见 budgetProbeOf）。
+
         const longArgs = budgetProbeOf(registered.get(tool.name));
         if (longArgs !== undefined) {
           const longCall = { ...call, arguments: longArgs };
@@ -1077,7 +928,7 @@ export async function run() {
     }
     for (const file of suspects) {
       const text = readFileSync(file, 'utf8');
-      const hit = /@pagoda\/dsh-workbench-module-[a-z0-9-]+/.exec(text);
+      const hit = /(?:@[a-z0-9-]+\/)?dsh-workbench-module-[a-z0-9-]+/.exec(text);
       if (hit !== null) {
         problems.push(
           `${SHELL}: ${relative(ROOT, file)} 里点名了模块包 ${hit[0]} —— ` +
@@ -1087,10 +938,11 @@ export async function run() {
     }
   }
 
+  problems.push(...buildSupplyIndex(supplyDeclarations).problems);
+
   if (problems.length > 0) {
     const notes = [`${declared} 个带 dsh 声明的包，其中 ${modules} 个模块`, ...probeNotes, ...headlineNotes];
-    // 落不到图里最常见的成因不是"声明写错"，而是"这个包不在任何 workspace 里"（裸目录里 init
-    // 出来的骨架）。不点出来的话，屏幕上的话会把责任推给那两条声明，而真正该做的是换到工坊里跑。
+
     const bare = [...unresolvedIn].filter(barePackage);
     if (bare.length > 0) {
       notes.push(
@@ -1099,7 +951,7 @@ export async function run() {
           `做法：在工坊里造（$DSH_HOME/workbench/diy/packages/module-<名字>），或者先在这个工作区里 pnpm install。`,
       );
     }
-    return { status: 'fail', notes, problems };
+    return { status: 'fail', notes: [...notes, ...warnings.map((one) => `（警告）${one}`)], problems };
   }
 
   return {
@@ -1111,6 +963,7 @@ export async function run() {
       `单元：${unitList}`,
       ...probeNotes,
       ...headlineNotes,
+      ...warnings.map((one) => `（警告）${one}`),
     ],
     problems: [],
   };