@dsh-workbench/module-tools 0.1.16 → 0.1.18

package/src/checks/contracts.mjs

@@ -10,17 +10,26 @@
 //   · `dsh.client` 的 inject / external 每一条都能落到图里的一行（seed 词 / 平台包 / workspace 包）；
 //   · `dsh.workbench`（**这是个模块**）：
 //       - `unit` 形状合法、全局唯一（撞了就是装上去当场抛）；
-//       - `faces.host` / `faces.client` 指的入口文件真的在；
+//       - `dsh.workbenchFaces.host` / `.client` 指的源码入口文件真的在 ——
+//         它是**工具链字段**，不在 `dsh.workbench` 协议里（ADR-0038 §7 第 7 条）：
+//         `source` 判据靠这两个入口做可达性分析，所以它必须是源码路径、必须声明；
 //       - 对壳有 peer 依赖（它跑在外壳交出来的服务上）；
 //       - 有自己的接线自检脚本（模块侧也必须机器判据，不能只靠人眼）。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `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 {
+  DECLARED_TOOLS_FILE,
+  declaredToolsProblemOf,
+  declaredToolsWithoutKey,
+  declaredToolsApplies,
+} from '../declared-tools.mjs';
 import { discoverPackages, workspaceRootOf } from '../discover.mjs';
 import { SEED_SHORT } from '../seed.mjs';
 
@@ -188,6 +197,38 @@ function productsTextOf(dir) {
   return text;
 }
 
+function sourceFilesOf(dir) {
+  const srcDir = join(dir, 'src');
+  if (!existsSync(srcDir)) return [];
+  const found = [];
+  const walk = (at) => {
+    for (const entry of readdirSync(at, { withFileTypes: true })) {
+      const full = join(at, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === '__tests__' || entry.name === 'node_modules') continue;
+        walk(full);
+      } else if (/\.tsx?$/.test(entry.name) && !/\.test\.tsx?$/.test(entry.name)) {
+        found.push(full);
+      }
+    }
+  };
+  walk(srcDir);
+  return found;
+}
+
+// `plugin: '<字面量>'` 与同一行里 `?? '<字面量>'` 的兜底：都该是**清单里声明过**的那个插件名。
+// 插件名只该有一处真相（能拿到 `deps.manifest` 的地方就用它），但模块级代码拿不到 manifest ⇒ 只能写字面量。
+// 这条判据拦的是"改了清单没改代码"（或反过来）：那样外壳会按错的名字去装 / 去探那个插件，而用户只看到
+// "缺命令"这种没头没尾的状态。只查 `plugin:` 那几行，别的字面量不管（不猜）。
+function pluginLiteralsOf(line) {
+  if (!/\bplugin\s*:/.test(line)) return [];
+  const found = [];
+  const direct = /plugin\s*:\s*['"]([^'"]+)['"]/.exec(line);
+  if (direct !== null) found.push(direct[1]);
+  for (const match of line.matchAll(/\?\?\s*['"]([^'"]+)['"]/g)) found.push(match[1]);
+  return found;
+}
+
 function hostProductOf(dir) {
   try {
     return readFileSync(join(dir, 'dist/host.js'), 'utf8');
@@ -241,15 +282,59 @@ function fakeStore() {
   return { for: () => one(), machine: () => one(), scan: () => [one()] };
 }
 
-function mountOf(face, created) {
+// mount 也一定拿得到 shell 与 workspaceRegistry（外壳给的是 dsh 交出来的服务）。
+// 少给这两样，模块的**降级写法**就会生效 —— 而"拿不到 shell 就只交 routes + registerTools"
+// 是合法写法（实测 pduiv2 的 coding-issues / coding-analysis 就这么写），降级后的面本来就不带
+// 审批钩子，判据却会把这读成"没认领审批"：红的是判据自己的环境，不是模块。
+// （与上面 `store` 那笔账同一条纪律：假 deps 少给一样，模块就在这条判据上被冤枉。）
+function fakeShell() {
+  return {
+    resolve: () => undefined,
+    execute: async () => ({
+      result: async () => ({
+        exitCode: null,
+        timedOut: false,
+        aborted: false,
+        stdout: { text: '', truncated: false },
+        stderr: { text: '', truncated: false },
+      }),
+    }),
+  };
+}
+
+function fakeWorkspaceRegistry() {
+  return {
+    get: () => undefined,
+    resolveByPath: async () => undefined,
+    create: async () => undefined,
+  };
+}
+
+function mountOf(face, created, manifest, tools) {
   if (face === undefined || typeof face.mount !== 'function') return undefined;
+  // 假服务**一次 mount 内是同一个对象**（真外壳给的就是同一个）—— 有的模块会拿两次再比。
+  const shell = fakeShell();
+  const workspaceRegistry = fakeWorkspaceRegistry();
+  const toolRegistry = {
+    register(tool) {
+      tools.push(tool);
+      return () => {};
+    },
+  };
   try {
     return face.mount({
+      manifest,
       ctx: {
-        get: () => undefined,
+        get: (key) => {
+          if (key === 'tools') return toolRegistry;
+          if (key === 'shell') return shell;
+          if (key === 'workspaceRegistry') return workspaceRegistry;
+          return undefined;
+        },
         effect: (fn) => {
           fn();
         },
+        provide: () => {},
         logger: { warn: () => {}, info: () => {} },
       },
       manifests: () => [],
@@ -266,6 +351,39 @@ const LONG_TASK_METHODS = ['start', 'snapshot', 'active', 'current', 'onChange']
 
 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];
+  if (schema.type === 'string') return 'probe';
+  if (schema.type === 'number' || schema.type === 'integer') return 1;
+  if (schema.type === 'boolean') return true;
+  if (schema.type === 'array') return [];
+  if (schema.type === 'object') return {};
+  return null;
+}
+
+function probeCallOf(tool) {
+  const schema = tool?.parameters;
+  if (typeof schema !== 'object' || schema === null) {
+    return { arguments: {}, shaped: false };
+  }
+  const properties = typeof schema.properties === 'object' && schema.properties !== null ? schema.properties : {};
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const args = {};
+  for (const key of required) args[key] = placeholderOf(properties[key]);
+  return { arguments: args, shaped: true };
+}
+
 function installed(specifier, from) {
   try {
     createRequire(join(from, 'package.json')).resolve(`${packageOf(specifier)}/package.json`);
@@ -289,12 +407,28 @@ 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();
+  if (declared.join('\n') === actual.join('\n')) return [];
+  return [
+    `${name}: dsh.workbench 声明的能力与代码真正注册的对不上 —— ` +
+      `清单 [${declared.join(', ')}]、代码 [${actual.join(', ')}]。` +
+      `清单是工具面的**唯一**来源（外壳按它算收窄、市场按它画花名册）：` +
+      `漏声明 = 那个工具不会被收起也不会进花名册；多声明 = 花名册里有个永远不存在的工具`,
+  ];
+}
+
 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();
+  // 判据"看到了但下不了结论"的那些，写进 notes（红绿两边都印）——
+  // 与其给一个撑不住的 verdict，不如把作者该自己确认的那一件事说清楚（ADR-0038 §6.15）。
+  const probeNotes = [];
   let declared = 0;
   let modules = 0;
 
@@ -359,12 +493,49 @@ 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}`);
+    } else if (declaredToolsApplies(dsh.workbench)) {
+      const bare = declaredToolsWithoutKey(dsh.workbench);
+      const literals = [];
+      const generated = join(pkg.dir, DECLARED_TOOLS_FILE);
+      for (const file of sourceFilesOf(pkg.dir)) {
+        if (file === generated) continue;
+        const text = readFileSync(file, 'utf8');
+        for (const tool of dsh.workbench.tools) {
+          const one = `'${tool.name}'`;
+          const two = `"${tool.name}"`;
+          if (text.includes(one) || text.includes(two)) {
+            literals.push(`${relative(pkg.dir, file)} 里的 ${tool.name}`);
+          }
+        }
+      }
+      if (literals.length > 0) {
+        problems.push(
+          `${name}: 工具名的字面量又写回了源码 —— ${literals.join(' / ')}。` +
+            `清单里已经有 key，代码该引用生成物（\`DECLARED_TOOLS.<key>.name\`）：` +
+            `名字只有清单一处写者，写两遍就会漂，而漂了没有任何编译错`,
+        );
+      }
+      if (bare.length > 0) {
+        problems.push(`${name}: 清单里 ${bare.join(' / ')} 没有 key`);
+      }
+    }
+
     for (const face of ['host', 'client']) {
-      const rel = dsh.workbench.faces?.[face];
+      const rel = dsh.workbenchFaces?.[face];
       if (typeof rel !== 'string') {
-        problems.push(`${name}: dsh.workbench.faces.${face} 没声明`);
+        problems.push(
+          `${name}: dsh.workbenchFaces.${face} 没声明 —— 这两个源码入口是工具链字段` +
+            `（不在 dsh.workbench 协议里）：source 判据靠它们判"哪一半"，缺了它判不了`,
+        );
       } else if (!existsSync(join(pkg.dir, rel))) {
-        problems.push(`${name}: dsh.workbench.faces.${face} 指的文件不存在 —— ${rel}`);
+        problems.push(`${name}: dsh.workbenchFaces.${face} 指的文件不存在 —— ${rel}`);
       }
     }
 
@@ -396,10 +567,37 @@ 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);
-    const env = face?.manifest?.env;
+    const mounted = face === undefined ? undefined : mountOf(face, created, manifest, tools);
+    const env = manifest?.env;
+
+    if (manifest !== undefined) {
+      if (face === undefined) {
+        problems.push(
+          `${name}: 声明了 ${manifest.tools.length} 个能力，但宿主面挂不起来（dist/host.js 缺、或 apply 抛了）` +
+            `—— 声明的能力对不了账，先把面修好`,
+        );
+      } else {
+        try {
+          mounted?.registerTools();
+        } catch (error) {
+          problems.push(`${name}: registerTools() 抛了 —— ${String(error)}`);
+        }
+        problems.push(
+          ...reconcileTools(
+            name,
+            manifest,
+            tools.map((tool) => (typeof tool?.name === 'string' ? tool.name : '')),
+          ),
+        );
+      }
+    }
+
     if (env !== undefined) {
       problems.push(...envProblemsOf(name, env));
       const products = productsTextOf(pkg.dir);
@@ -426,6 +624,27 @@ export async function run() {
         );
       });
 
+      const declaredPlugins = new Set(
+        (env.plugins ?? []).map((one) => text(one?.name)).filter((one) => one !== ''),
+      );
+      if (declaredPlugins.size > 0) {
+        for (const file of sourceFilesOf(pkg.dir)) {
+          readFileSync(file, 'utf8')
+            .split('\n')
+            .forEach((line, index) => {
+              for (const literal of pluginLiteralsOf(line)) {
+                if (declaredPlugins.has(literal)) continue;
+                problems.push(
+                  `${name}: ${relative(pkg.dir, file)}:${index + 1} 里的插件名「${literal}」不在清单的 ` +
+                    `env.plugins[] 里（清单里是 ${[...declaredPlugins].join(' / ')}）—— 改了清单没改代码` +
+                    '（或反过来）会让外壳按错的名字去装 / 去探那个插件。插件名只有一处真相：' +
+                    '能拿到 deps.manifest 的地方就用它，拿不到的地方至少与清单保持一致',
+                );
+              }
+            });
+        }
+      }
+
       if ((env.libs ?? []).length > 0 && !products.includes('libInstallCommand')) {
         problems.push(
           `${name}: 声明了 env.libs 却没用 libInstallCommand（@dsh-workbench/shared/host 里现成的）—— ` +
@@ -438,7 +657,8 @@ export async function run() {
     // 设计表里写了哪一种就得真的接上哪一种 —— 否则用户改完刷新回到默认，而表上写着"能配"。
     // （**与 env 无关**：没有 env 的模块一样要查，所以放在 env 块外面。）
     const configRows = designRowsOf(pkg.dir, 'config');
-    const wiredPrefs = /\bprefs\s*:/.test(hostProductOf(pkg.dir));
+    const hostProduct = hostProductOf(pkg.dir);
+    const wiredPrefs = /\bprefs\s*:/.test(hostProduct);
     const declaredPrefs = (configRows ?? []).some((one) => text(one?.['persistence']) === 'prefs');
     if (declaredPrefs && !wiredPrefs) {
       problems.push(
@@ -453,18 +673,27 @@ export async function run() {
       );
     }
 
-    // 「这把能力在哪些项目里出现」：表里写了 workspace（按项目收窄），产物里就得真的实现 gate.deniedTools ——
-    // 否则每个项目里它都出现在工具清单里，agent 调了才发现不行（两次调用白花，而且它还会再试）。
-    // 反向**不查**：`deniedTools` 也用来"按自己的开关收窄"（比如能力没配好先藏起来），那不是项目作用域 ——
-    // 查反向会把这种合法用法判红。
+    // 底稿与清单只对账**键集合**：`design.json` 的 `capabilities[].name` 与清单的 `tools[].name`
+    // 不重不漏（ADR-0038 §2.5）。**只对名字**：内容各写一处（人话在底稿、机器字段在清单），没有可比的东西。
+    // 没有 `design.json` 的模块不查（底稿是可选的，契约不要求它）；清单形状坏了的也不查（protocol 已经说话了）。
     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}: 设计表里有一条能力写着"只在某些项目里出现"（capabilities[].scope = 'workspace'），` +
-          '产物里却没有实现 gate.deniedTools —— 每个项目的工具清单里都有它，agent 调了才知道不行。' +
-          '接法：mount 返回 `gate: { deniedTools(workspace) { … }, subscribe }`（见 TOOLS.md §12）',
-      );
+    if (capabilityRows !== undefined && manifest !== undefined) {
+      const inDesign = capabilityRows.map((one) => text(one?.name)).filter((one) => one !== '');
+      const inDeclaration = manifest.tools.map((tool) => tool.name);
+      for (const name0 of inDesign.filter((one) => !inDeclaration.includes(one))) {
+        problems.push(
+          `${name}: design.json 的能力行里有「${name0}」，清单的 tools[] 里却没有它 —— ` +
+            '能力只有清单那一处能出货（装机预检 / 市场 / 外壳都读它），底稿写了也是一句空话：' +
+            `要么把它补进 \`dsh.workbench.tools\`，要么从底稿里删掉`,
+        );
+      }
+      for (const name0 of inDeclaration.filter((one) => !inDesign.includes(one))) {
+        problems.push(
+          `${name}: 清单的 tools[] 里声明了「${name0}」，design.json 的能力行里却没有它 —— ` +
+            '底稿是给人读的那半（它干嘛、要不要点头，`design render` 拿它出 README）：' +
+            `要么在 design.json 的 capabilities[] 里为「${name0}」补一行，要么把它从清单里删掉`,
+        );
+      }
     }
 
     // 长任务：跑一会儿的事，注册了就得让用户看得见那四盏灯。
@@ -580,10 +809,18 @@ export async function run() {
     //
     // 外壳每次调用前都会问套件：writes:true 的工具，needsApproval 不给 verdict.kind==='ask'
     // 就**当场 deny**（原文："在套件的 needsApproval 里补一条审批（含"这次会发生什么"），别让写静默过去"）——
-    // 那条错误只有真跑一次才看得见，用户看到的是一次莫名其妙的拒绝。所以门禁在出包前先看一遍：
-    //   · needsApproval 要给完整的 ask 口径（理由 + 问句 + 兜底文案，zh/en 都要）；
-    //   · approvalDetail 要说清"这次会发生什么"（审批屏上就靠它，缺了只剩一句通用问句）。
-    const writeTools = (face?.manifest?.tools ?? []).filter((one) => one?.writes === true);
+    // 那条错误只有真跑一次才看得见，用户看到的是一次莫名其妙的拒绝。所以门禁在出包前先看一遍。
+    //
+    // **这条判据只能验到哪一层**（原样写给以后改它的人）：
+    //   · 硬事实：一个 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) {
         problems.push(
@@ -592,13 +829,32 @@ export async function run() {
         );
         continue;
       }
+      const registered = new Map(tools.map((tool) => [text(tool?.name), tool]));
+      const readOnProbe = [];
       for (const tool of writeTools) {
-        const call = { name: tool.name, arguments: {}, workspace: null };
+        const probe = probeCallOf(registered.get(tool.name));
+        const call = { name: tool.name, arguments: probe.arguments, workspace: null };
+        const cannotShape = probe.shaped
+          ? ''
+          : `（registerTools() 没注册出 ${tool.name} 的 parameters，判据只能用空参数探 —— ` +
+            `你的判断依赖参数的话，注册时把 parameters 那个 JSON Schema 一起交出来）`;
+        if (typeof mounted.needsApproval !== 'function') {
+          problems.push(
+            `${name}: 工具 ${tool.name} 的清单里写着 writes:true，但 mount() 的返回值里没有 needsApproval —— ` +
+              `外壳每次调用前都问它"这次要不要点头"，没有它就只有一句"没认领"，**每一次调用都当场被拒**。` +
+              `做法：mount() 返回的对象里加 needsApproval(call)，认出这把工具再给 verdict：` +
+              `{ kind: 'read' }（这次不用问）或 { kind: 'ask', reason, question: {zh,en}, fallback: {zh,en} }（要问，且问得清）`,
+          );
+          continue;
+        }
         let verdict;
         try {
-          verdict = mounted?.needsApproval?.(call);
-        } catch {
-          verdict = undefined;
+          verdict = mounted.needsApproval(call);
+        } catch (error) {
+          problems.push(
+            `${name}: 工具 ${tool.name} 的 needsApproval 在合成调用 ${JSON.stringify(call.arguments)} 上抛了 —— ${String(error)}`,
+          );
+          continue;
         }
         // 合法口径有两种：`{ kind: 'read' }`（这件事不用问 —— 例：没什么可做的）与
         // `{ kind: 'ask', reason, question{zh,en}, fallback{zh,en} }`（要问，且问得清）。
@@ -613,15 +869,23 @@ export async function run() {
           text(verdict.fallback?.en) !== '';
         if (!read && !ask) {
           problems.push(
-            `${name}: 工具 ${tool.name} 的清单里写着 writes:true，但 needsApproval 没给出合法口径 —— ` +
+            `${name}: 工具 ${tool.name} 的清单里写着 writes:true，但 needsApproval 对合成调用 ` +
+              `${JSON.stringify(call.arguments)} 没给出合法口径 —— ` +
               `要么 { kind: 'read' }（这件事不用问），要么 { kind: 'ask', reason, question: {zh,en}, ` +
-              `fallback: {zh,en} }（要问，且问得清）。别的返回值外壳会当场 deny`,
+              `fallback: {zh,en} }（要问，且问得清）。别的返回值外壳会当场 deny${cannotShape}`,
           );
           continue;
         }
+        // read：这次调用不用点头。**不查 approvalDetail** —— 外壳在 read 时也不会去问它
+        // （`approvalFor` 只在 verdict 是 ask 时才调 detailOf）。合成调用本来就不是一次真实写入，
+        // 拿它逼模块给"这次会发生什么"就是让判据替外壳问一个外壳不会问的问题。
+        if (read) {
+          readOnProbe.push(tool.name);
+          continue;
+        }
         let facts;
         try {
-          facts = await mounted?.approvalDetail?.(call);
+          facts = await mounted.approvalDetail?.(call);
         } catch {
           facts = undefined;
         }
@@ -632,11 +896,20 @@ export async function run() {
             : text(facts.zh) !== '' && text(facts.en) !== '');
         if (!described) {
           problems.push(
-            `${name}: 写工具 ${tool.name} 没给 approvalDetail（"这次会发生什么"，zh/en 或 {blocked}）—— ` +
-              `审批屏上用户只能看到一句通用问句，看不到会动什么`,
+            `${name}: 写工具 ${tool.name} 的 needsApproval 对合成调用回了 ask（要点头），` +
+              `但 approvalDetail 没说清"这次会发生什么"（zh/en 或 {blocked}）—— ` +
+              `审批屏上用户只能看到一句通用问句，看不到会动什么${cannotShape}`,
           );
         }
       }
+      if (readOnProbe.length > 0) {
+        probeNotes.push(
+          `写工具 ${readOnProbe.join(' / ')} 按合成调用回了"这次不用问"（kind: 'read'）—— ` +
+            `判据只能验到这一步：它是不是"参数里带 confirm 才真的写"那种**合法**口径，` +
+            `合成调用看不出来（必填项给的是占位值，不是真实写入参数）。作者自己确认一次：` +
+            `真的调用会不会 ask、ask 时 approvalDetail 说没说清`,
+        );
+      }
     }
   }
 
@@ -669,7 +942,7 @@ export async function run() {
   }
 
   if (problems.length > 0) {
-    const notes = [`${declared} 个带 dsh 声明的包，其中 ${modules} 个模块`];
+    const notes = [`${declared} 个带 dsh 声明的包，其中 ${modules} 个模块`, ...probeNotes];
     // 落不到图里最常见的成因不是"声明写错"，而是"这个包不在任何 workspace 里"（裸目录里 init
     // 出来的骨架）。不点出来的话，屏幕上的话会把责任推给那两条声明，而真正该做的是换到工坊里跑。
     const bare = [...unresolvedIn].filter(barePackage);
@@ -690,6 +963,7 @@ export async function run() {
         `inject/external 都能落到图里 · 单元 id 唯一 · 面文件与 peer 都在 · 各有接线自检`,
       '（test 不在这儿跑：状态级的东西在模块自己的 vitest 里 —— 四个脚本自己跑一遍）',
       `单元：${unitList}`,
+      ...probeNotes,
     ],
     problems: [],
   };

package/src/checks/kit.mjs

@@ -17,7 +17,7 @@
 //
 // 判据跟着 `dsh.workbench` 自述清单走；没有 client.js 的包这里没事可查（由 build/契约判据管）。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readFileSync } from 'node:fs';

package/src/checks/markers.mjs

@@ -4,7 +4,7 @@
 // 不能照搬"本 workspace 里所有 access=public 的包" —— 在外壳仓里等价，但把这个工具拿到
 // 别人的 monorepo（例如 pdv2）里跑时，那条会把人家二十几个自家 SDK 包一起判了。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';

package/src/checks/primitives.mjs

@@ -12,7 +12,7 @@
 //
 // 判据跟着 `dsh.workbench` 自述清单走：没用 dsh 原语的模块直接跳过（0 命中 = 通过）。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';

package/src/checks/protocol.mjs

@@ -0,0 +1,57 @@
+// 模块声明协议：`dsh.workbench` 的**版本**与**静态半形状**。
+//
+// 这一条是**薄壳**：真正的形状判定在 `@dsh-workbench/shared` 的 `declarationProblemsOf()`。
+// 三个调用方共用那一份实现，所以协议只有一处定义：
+//   · 门禁（本判据）
+//   · 外壳（装配期把声明读成运行期清单，ADR-0038 §2.2）
+//   · 装机预检（拿 registry 元数据里的 package.json 就能调，ADR-0038 §2.6）
+// 在 U1b 之前本文件自己带了一套形状校验 —— 那意味着外壳与门禁会各判各的，
+// 正是"两份同类真相"。现在它只剩"把当前目录的包扫一遍、把问题倒出来"。
+//
+// 分工：contracts 管"这个包长得对不对"（unit 唯一、`dsh.workbenchFaces` 在、peer 在、审批认领了没），
+// 本判据管"这份声明读不读得懂"（版本认不认、静态半形状对不对、有没有生字段）。
+//
+// `faces` 自 A-2 起**不在协议里**（ADR-0038 §7 第 7 条）：它指的是**源码**入口
+// （`src/host.ts` / `src/client.tsx`），而协议是"装的人手上有什么"那份清单 —— 装机预检与外壳
+// 都不用它。它搬到 `dsh.workbench` 的**兄弟键** `dsh.workbenchFaces`，由 contracts / source 读；
+// 于是它既不是协议里的合法键（写回 `dsh.workbench` 里会被判生字段），也不会被协议"顺手校验"。
+
+import { declarationProblemsOf } from '@dsh-workbench/shared/host';
+
+export const title = '模块声明协议';
+
+export async function run() {
+  const { discoverPackages } = await import('../discover.mjs');
+  const packages = discoverPackages({ root: process.cwd() });
+  const problems = [];
+  const versions = new Set();
+  let declared = 0;
+
+  for (const pkg of packages) {
+    const raw = pkg.manifest.dsh?.workbench;
+    if (raw === undefined) continue;
+    problems.push(...declarationProblemsOf(pkg.manifest.name, raw));
+    if (typeof raw === 'object' && raw !== null && Number.isInteger(raw.apiVersion)) {
+      declared += 1;
+      versions.add(raw.apiVersion);
+    }
+  }
+
+  if (problems.length > 0) {
+    return {
+      status: 'fail',
+      notes: [`${packages.length} 个包里带 dsh.workbench 声明的已逐个读过`],
+      problems,
+    };
+  }
+
+  return {
+    status: 'pass',
+    notes: [
+      declared === 0
+        ? '这个工作区里还没有模块（没有带 dsh.workbench 的包）'
+        : `${declared} 个模块都声明了协议 v${[...versions].sort().join(' / v')}，静态半形状齐、没有生字段`,
+    ],
+    problems: [],
+  };
+}

package/src/checks/source.mjs

@@ -5,11 +5,15 @@
 // 模块包自己要守的是另外几条，写在下面。判据全部来自源码里的 import 说明符，覆盖范围跟着
 // `dsh.workbench` 自述清单走（新加模块不用改这里）。
 //
-// 关于 dsh 的包：「哪一半」**不靠目录名猜**，而是从两个入口（`faces.host` / `faces.client`）
-// 做一次本包内可达性分析。种子词（模块表里天生就有的那几个）在**只被客户端入口可达**的文件里
-// 可以用（ADR-0028）；宿主侧一个都不许碰 —— 那些包只在浏览器侧存在。
+// 关于 dsh 的包：「哪一半」**不靠目录名猜**，而是从两个入口（`dsh.workbenchFaces.host` /
+// `dsh.workbenchFaces.client`）做一次本包内可达性分析。种子词（模块表里天生就有的那几个）在
+// **只被客户端入口可达**的文件里可以用（ADR-0028）；宿主侧一个都不许碰 —— 那些包只在浏览器侧存在。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 这两个入口是 dsh.workbenchFaces 的**唯一**用途（工具链字段，不是协议的一部分，见 ADR-0038 §7 第 7 条）：
+// 装机预检与外壳都不读它。所以这里必须拿**源码**入口 —— 从产物 dist/host.js 反推不出是哪一份源码
+// 把 dsh 的包拖进来的。
+//
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
@@ -102,7 +106,7 @@ export async function run() {
   for (const pkg of modulePackages) {
     const name = pkg.manifest.name;
     const unit = pkg.manifest.dsh.workbench.unit;
-    const faces = pkg.manifest.dsh.workbench.faces ?? {};
+    const workbenchFaces = pkg.manifest.dsh.workbenchFaces ?? {};
     const srcDir = join(pkg.dir, 'src');
     const viaPlatform = hasPlatformPackage(pkg.manifest);
 
@@ -112,8 +116,10 @@ export async function run() {
       );
     }
 
-    const hostReach = faces.host === undefined ? new Set() : reachableFrom(pkg.dir, unit, faces.host);
-    const clientReach = faces.client === undefined ? new Set() : reachableFrom(pkg.dir, unit, faces.client);
+    const hostReach =
+      workbenchFaces.host === undefined ? new Set() : reachableFrom(pkg.dir, unit, workbenchFaces.host);
+    const clientReach =
+      workbenchFaces.client === undefined ? new Set() : reachableFrom(pkg.dir, unit, workbenchFaces.client);
     const sideOf = (file) => {
       const host = hostReach.has(file);
       const client = clientReach.has(file);
@@ -147,7 +153,7 @@ export async function run() {
                   : '这个文件在宿主侧可达';
             problems.push(
               `${name}: ${rel} 里 import 了 ${specifier}（dsh 的浏览器包，是平台种子词）—— ${why}，` +
-                `而它只在浏览器侧存在。把它挪到只被 faces.client 可达的文件里`,
+                `而它只在浏览器侧存在。把它挪到只被 dsh.workbenchFaces.client 可达的文件里`,
             );
             continue;
           }

package/src/checks/standalone.mjs

@@ -4,7 +4,7 @@
 // 最后无论成败都还原。藏起来还过不了 = 这条模块在用"只有本仓才有"的相对路径 / 别名 ——
 // 发布出去会散架。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。所以这里**不许**自己退出：
 // 仓外工作区（没有外壳源码）以前就是"提前成功退出"（退出码 0）—— 那会把排在后面的判据静默吞掉。