@dsh-workbench/module-tools 0.1.16 → 0.1.17

package/README.md

@@ -8,7 +8,7 @@
 ```bash
 dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description "一句话"]
 dsh-wb-module build                 # 出 dist/host.js 与套了 loader 壳的 client.js
-dsh-wb-module check [--only <判据>]  # 十条判据；--only 可以单跑
+dsh-wb-module check [--only <判据>]  # 十一条判据；--only 可以单跑
 dsh-wb-module design <init|check|render|accept>
 dsh-wb-module publish               # 发货前的清单：门禁 + 三张表 + npm pack 清单（只 dry run）
 ```
@@ -16,11 +16,12 @@ dsh-wb-module publish               # 发货前的清单：门禁 + 三张表 +
 `--cwd <目录>` 指定包目录（默认当前目录）。模块目录里更省事的是骨架自带的脚本：
 `pnpm build` / `pnpm typecheck` / `pnpm test` / `pnpm selfcheck` / `pnpm design`。
 
-## 十条判据（`check`）
+## 十一条判据（`check`）
 
 | 判据 | 盯什么 |
 |---|---|
-| `contracts` | 模块契约：单元 id 唯一、两个面、四个脚本、`files`、peer 下限 |
+| `contracts` | 模块契约：单元 id 唯一、两个面、四个脚本、`files`、peer 下限；以及**清单 ↔ 代码**（真正注册的工具）与**底稿 ↔ 清单**（`design.json` 的能力名）两处对账（见下） |
+| `protocol` | 模块声明协议：`dsh.workbench` 的 `apiVersion` 要在、静态半形状要对、不许有协议不认识的键（`scope` 现在**就是**不认识的键之一 —— 见下） |
 | `bundles` | 产物边界：宿主面里不许出现浏览器侧的东西 |
 | `source` | 源码边界：不直接引 dsh 的包、不引不是种子词的 `@deepseek-ai/*` |
 | `primitives` | dsh 原语只从模块表（`kit`）拿 |
@@ -38,12 +39,65 @@ dsh-wb-module publish               # 发货前的清单：门禁 + 三张表 +
 三张表（面板 / 能力 / 联动）+ 状态矩阵 + 数据源记录 + 验收清单住在模块根目录的 `design.json`，
 README 里那一段由它生成（夹在 `<!-- dsh-wb:design:start/end -->` 之间）。
 
+`design.json` 是**设计底稿**：只装人话（`oneLine` / `shape` / `approvalText` / 面板那几张表的文字 /
+`datasource`），**不装机器字段**。**"这条能力在哪些工作区出现"不在底稿、也不在清单**：
+那是**用户**的事（他的面板板），模块作者声明不了（用户口径「模块开发者不能定义 scope，
+scope 永远是用户来决定的」，见 [ADR-0038](../../docs/adr/0038-module-declaration-protocol.md)
+§2.4 / §6.16）。
+`contracts` 会把底稿的能力名与清单的工具名做**键集合对账**（不重不漏，只对名字）：
+底稿多一条、清单多一把都点名判红；没有 `design.json` 的模块不查。
+
 ```bash
 dsh-wb-module design check    # 空着的格一格格点名叫出来 + README 有没有落后
 dsh-wb-module design render   # 用 design.json 重新生成 README 那一段
 dsh-wb-module design accept   # 用户逐条点头之后，把验收清单打勾
 ```
 
+## 协议：`dsh` 字段里的五段
+
+一个模块包在 `package.json` 里声明五件事，缺哪一段在哪一层炸都不一样：
+
+| 段 | 是什么 | 谁读 |
+|---|---|---|
+| `dsh.bundle.patch` | 把自己插进 profile 组合图的 cordis 补丁 | dsh 的组合器（**装载**） |
+| `dsh.client{platform,inject,external}` | 浏览器侧接线 | dsh 的客户端组合器（**dsh 自己不校验**，错的声明要等浏览器 `require` 才炸 —— 所以 `contracts` 替你查） |
+| `dsh.workbench` | **模块声明协议**（下详） | 门禁 · 市场 · 外壳 |
+| `dsh.workbenchFaces{host,client}` | **工具链元数据**（**不在协议里**）：两个 half 的**源码**入口 | 门禁：`source` 拿它算可达性、`contracts` 查它在位；运行期与装机预检都不读 |
+| `peerDependencies['@dsh-workbench/core']` | 服务面：外壳 provide 的服务在不在 | dsh 的 `evaluatePluginCompatibility` |
+
+### `dsh.workbench`（协议 v1）
+
+```jsonc
+"workbench": {
+  "apiVersion": 1,                                  // 必填。形状契约，缺了外壳不认这个模块
+  "unit": "hello",                                  // 单元 id（小写连字符），进持久化配置
+  "card": { "titleKey": "hello.cardTitle", "order": 90 },   // 没有卡片写 null
+  "tools": [{ "name": "hello_read", "writes": false }], // 没工具写 []
+  "host": { "inject": [] },                         // 这个单元要外壳的哪几个服务（判"能不能挂"）
+  "env": { "command": "opencli", "plugins": [], "libs": [] } // 可选：靠什么才跑得起来
+},
+"workbenchFaces": { "host": "src/host.ts", "client": "src/client.tsx" } // 工具链那一格（不在协议里）：两半的源码入口
+```
+
+五条口径：
+
+1. **声明了 `apiVersion` = 宣布静态半写全了** —— `unit` / `card` / `tools` / `host`
+   四个键都必须有（`card` 没有卡片写 `null`），`env` 没有外部供给时省略。
+2. **不许有协议不认识的键**：生字段会被外壳**静默忽略**（拼错一个键就等于那句话没写），
+   所以 `protocol` 判据先拦。**`scope` 不在协议里**：它曾经是（`card.scope` / `tools[].scope`），
+   现已删除 —— 一个能力在哪些工作区出现**只由用户的板决定**，作者写它 = 写了一个生字段、当场红
+   （`protocol` 会点名 `"scope"`）。见 [ADR-0038](../../docs/adr/0038-module-declaration-protocol.md) §2.4 / §6.16。
+3. **清单声明的工具 = 代码真正注册的工具**（U1b 起）：清单是工具面的**唯一**来源，
+   `contracts` 拿 `mount()` 里 `registerTools()` 真正注册的名字对账，两边漂了就红。
+4. **底稿 ↔ 清单只对账键集合**（U1c 起）：`design.json` 的 `capabilities[].name` 与清单的
+   `tools[].name` 不重不漏，**只对名字**（内容各写一处，没有可比的东西）；没有 `design.json`
+   的模块不查 —— 底稿是可选的设计材料。见 [ADR-0038](../../docs/adr/0038-module-declaration-protocol.md) §2.5 / §6.3。
+5. **`dsh.workbenchFaces` 不是协议的一部分，但门禁必填**（A-2 起）：它是 `dsh.workbench` 的
+   **兄弟键**，写两半的**源码**入口；`source` 判据靠它算"这段源码属于哪一半"。
+   写进 `dsh.workbench` 里会被判**生字段**（不留兼容），它也不能指向出货产物
+   —— 从 `dist/host.js` 反推不出是哪份源码把 dsh 的包拖进来的。见
+   [ADR-0038](../../docs/adr/0038-module-declaration-protocol.md) §7 第 7 条。
+
 ## 两个模板
 
 | 模板 | 是什么 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,8 @@
     "access": "public"
   },
   "dependencies": {
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "@dsh-workbench/shared": "0.1.17"
   },
   "scripts": {
     "selfcheck": "node scripts/selfcheck.mjs"

package/src/check.mjs

@@ -1,5 +1,4 @@
-// 十条判据的**聚合层**：跑、收集三态、打印、决定退出码。
-//
+// 判据的**聚合层**：跑、收集三态、打印、决定退出码。有几条以 `CHECKS` 表为准。
 // ── 为什么判据改成"导出函数"，打印与退出码都搬到这里 ──────────────────────────
 //
 // 在这之前，每条 `checks/*.mjs` 都是"import 即执行 + 自己 console.log + 自己 process.exit"
@@ -21,9 +20,10 @@
 //     失败   ✖ <title> <N> 条不过：  然后逐条 `  · <problem>`
 // 最后一行是汇总；有任何 fail 就 exit 1。
 
-// 十个名字与 title 一字不变 —— selfcheck 会把它与各判据模块导出的 `title` 逐个对一遍。
+// 名字与 title 一字不变 —— selfcheck 会把它与各判据模块导出的 `title` 逐个对一遍。
 export const CHECKS = {
   contracts: { title: '模块契约', load: () => import('./checks/contracts.mjs') },
+  protocol: { title: '模块声明协议', load: () => import('./checks/protocol.mjs') },
   bundles: { title: '模块产物边界', load: () => import('./checks/bundles.mjs') },
   source: { title: '模块源码边界', load: () => import('./checks/source.mjs') },
   primitives: { title: 'dsh 原语只从模块表拿', load: () => import('./checks/primitives.mjs') },

package/src/checks/alias.mjs

@@ -4,7 +4,7 @@
 // 解析得到 —— 装到别人那里就是构建期找不到文件（`check:standalone` 会把它变成红灯，
 // 这条判据则直接指到源码那一行）。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';

package/src/checks/bundles.mjs

@@ -14,7 +14,7 @@
 // 覆盖范围跟着**自述清单**走：凡 `package.json` 里声明了 `dsh.workbench` 的包都被检查，
 // 新加一个模块不用改这个脚本。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readFileSync } from 'node:fs';

package/src/checks/cards.mjs

@@ -12,7 +12,7 @@
 // `window.__ModuleLoader__.load({id, factory})`，用假的 loader / require 把它拉起来。
 // 覆盖范围跟着 `dsh.workbench` 自述清单走 —— 新模块不用改这里。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readFileSync } from 'node:fs';

package/src/checks/contracts.mjs

@@ -10,17 +10,20 @@
 //   · `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 { discoverPackages, workspaceRootOf } from '../discover.mjs';
 import { SEED_SHORT } from '../seed.mjs';
 
@@ -241,15 +244,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 +313,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 +369,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;
 
@@ -360,11 +456,14 @@ export async function run() {
     }
 
     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 +495,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);
@@ -438,7 +564,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 +580,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 +716,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 +736,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 +776,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 +803,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 +849,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 +870,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）—— 那会把排在后面的判据静默吞掉。
 

package/src/checks/style.mjs

@@ -5,7 +5,7 @@
 // CSS Modules 的哈希类名靠"同一份文件、同一个导出"配对，调用点拿到 undefined 时真机渲染成
 // `class="undefined"` —— 元素整片没样式，而且控制台一声不响。
 //
-// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';

package/src/design.mjs

@@ -41,8 +41,7 @@ const ROWS = {
     mayBeEmpty: true,
   },
   capabilities: {
-    fields: ['name', 'oneLine', 'shape', 'approval', 'scope'],
-    choices: { scope: ['always', 'workspace'] },
+    fields: ['name', 'oneLine', 'shape', 'approval'],
     optional: ['approvalText'],
     mayBeEmpty: true,
   },
@@ -68,15 +67,6 @@ function persistenceLabel(value) {
   return cell(raw);
 }
 
-/** 一条能力在哪些项目里出现：`always` = 每个项目都该看见；`workspace` = 只在某些项目里有意义，
- *  代码里必须真的用 `gate.deniedTools(workspace)` 把它收窄，否则表上写着窄、实际到处都在。 */
-function scopeLabel(value) {
-  const raw = text(value);
-  if (raw === 'always') return '哪个项目都能用';
-  if (raw === 'workspace') return '只在某些项目里出现（按项目收窄）';
-  return cell(raw);
-}
-
 function datasourceRowsOf(read) {
   return [
     '| 项 | 值（照抄，别转述） |',
@@ -264,16 +254,15 @@ export function renderDesign(design) {
     '### 表 2 agent：他能替用户做什么、哪几件要点头',
     '',
     tableOf(
-      '能力 | 一句话 | 传什么 / 拿回什么（贴真实调用与返回） | 要点头吗 | 点头时他看到的"会发生什么" | 在哪些项目里出现',
+      '能力 | 一句话 | 传什么 / 拿回什么（贴真实调用与返回） | 要点头吗 | 点头时他看到的"会发生什么"',
       capabilities.length === 0
-        ? [['（这份模块故意没有能力）', '—', '—', '—', '—', '—']]
+        ? [['（这份模块故意没有能力）', '—', '—', '—', '—']]
         : capabilities.map((one) => [
             cell(one?.name),
             cell(one?.oneLine),
             cell(one?.shape),
             cell(one?.approval),
             soft(one?.approvalText),
-            scopeLabel(one?.scope),
           ]),
     ),
     '',

package/src/publish.mjs

@@ -69,7 +69,7 @@ export async function publish({ root }) {
     if (existsSync(join(root, DESIGN_FILE))) runCli(root, ['design', 'check']);
     else console.log('○ 没有 design.json（三张表还没落成机器形状）—— 建议先 dsh-wb-module design init');
   } else {
-    console.log('○ 这不是一个 wb 模块包（没有 dsh.workbench.unit）—— 跳过十条判据，只查打包清单');
+    console.log('○ 这不是一个 wb 模块包（没有 dsh.workbench.unit）—— 跳过判据，只查打包清单');
   }
 
   const packed = packList(root);

package/template/package.json.tpl

@@ -24,9 +24,13 @@
       "external": ["@dsh-workbench/core/client"]
     },
     "workbench": {
+      "apiVersion": 1,
       "unit": "__UNIT__",
-      "faces": { "host": "src/host.ts", "client": "src/client.tsx" }
-    }
+      "card": { "titleKey": "__UNIT__.cardTitle", "order": 90 },
+      "tools": [],
+      "host": { "inject": [] }
+    },
+    "workbenchFaces": { "host": "src/host.ts", "client": "src/client.tsx" }
   },
   "peerDependencies": { "@dsh-workbench/core": "^0.1.0", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },

package/template/scripts/smoke.mjs.tpl

@@ -108,14 +108,12 @@ const ctx = {
 
 pluginExports.apply(ctx);
 check('卡片真的注册进了外壳', faces.length === 1, `注册了 ${faces.length} 个`);
-check(`注册的是 ${UNIT_ID} 单元`, faces[0]?.manifest.id === UNIT_ID, faces[0]?.manifest.id);
+check(`注册的是 ${UNIT_ID} 单元`, faces[0]?.unit === UNIT_ID, faces[0]?.unit);
 check('卡片是个能画的组件', typeof faces[0]?.card === 'function');
 check(
-  '卡片自己带标题与顺序（外壳的看板据此排）',
-  typeof faces[0]?.manifest.card?.titleKey === 'string' &&
-    faces[0].manifest.card.titleKey !== '' &&
-    typeof faces[0]?.manifest.card?.order === 'number',
-  JSON.stringify(faces[0]?.manifest.card),
+  '面只交 unit（标题与顺序住在 package.json 的 dsh.workbench 里，由外壳按 unit 交给浏览器）',
+  faces[0]?.manifest === undefined,
+  JSON.stringify(faces[0]?.manifest),
 );
 check(
   '卡片在空数据下也画得出来（不许抛）',

package/template/src/client.tsx.tpl

@@ -4,23 +4,11 @@ import { messages } from './messages';
 
 const UNIT_ID = '__UNIT__';
 
-interface UnitManifest {
-  readonly id: string;
-  readonly kind: string;
-  readonly card: {
-    readonly titleKey: string;
-    readonly order: number;
-    readonly enabledByDefault: boolean;
-  } | null;
-  readonly tools: readonly unknown[];
-  readonly host: { readonly inject: readonly string[] };
-}
-
 type Rendered = ReturnType<typeof h>;
 type Translate = (key: string, params?: Record<string, unknown>) => string;
 
 interface UnitClientFace {
-  readonly manifest: UnitManifest;
+  readonly unit: string;
   readonly messages: { readonly zh: Readonly<Record<string, string>>; readonly en: Readonly<Record<string, string>> };
   readonly card: (props: { readonly t: Translate; readonly onRefresh: () => void }) => Rendered;
 }
@@ -34,16 +22,8 @@ interface ClientContext {
   effect(effect: () => void | (() => void), label?: string): () => void;
 }
 
-const manifest: UnitManifest = {
-  id: UNIT_ID,
-  kind: 'board',
-  card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
-  tools: [],
-  host: { inject: [] },
-};
-
 const face: UnitClientFace = {
-  manifest,
+  unit: UNIT_ID,
   messages,
   card: (props) => {
     const { Card } = kit.components;

package/template/src/host.ts.tpl

@@ -4,25 +4,13 @@ export const name = '__NAME__';
 
 export const inject = ['workbenchUnits'];
 
-interface UnitManifest {
-  readonly id: string;
-  readonly kind: string;
-  readonly card: {
-    readonly titleKey: string;
-    readonly order: number;
-    readonly enabledByDefault: boolean;
-  } | null;
-  readonly tools: readonly unknown[];
-  readonly host: { readonly inject: readonly string[] };
-}
-
-interface UnitHostFace {
-  readonly manifest: UnitManifest;
+interface UnitModuleFace {
+  readonly unit: string;
   mount(): { routes: Record<string, never>; registerTools(): Array<() => void> };
 }
 
 interface UnitRegistry {
-  register(face: UnitHostFace): () => void;
+  register(face: UnitModuleFace): () => void;
 }
 
 interface HostContext {
@@ -31,16 +19,8 @@ interface HostContext {
   logger?: { warn?(message: string): void } | undefined;
 }
 
-const manifest: UnitManifest = {
-  id: UNIT_ID,
-  kind: 'board',
-  card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
-  tools: [],
-  host: { inject: [] },
-};
-
-const face: UnitHostFace = {
-  manifest,
+const face: UnitModuleFace = {
+  unit: UNIT_ID,
   mount: () => ({ routes: {}, registerTools: () => [] }),
 };
 

package/template/src/plugin.test.ts.tpl

@@ -39,7 +39,7 @@ describe('__NAME__ 的面', () => {
     });
     apply(ctx as never);
     expect(faces).toHaveLength(1);
-    expect((faces[0] as { manifest: { id: string } }).manifest.id).toBe('__UNIT__');
+    expect((faces[0] as { unit: string }).unit).toBe('__UNIT__');
   });
 
   it('浏览器半侧把自己的卡片注册进外壳', () => {
@@ -51,5 +51,6 @@ describe('__NAME__ 的面', () => {
     });
     applyClient(ctx as never);
     expect(faces).toHaveLength(1);
+    expect((faces[0] as { unit: string }).unit).toBe('__UNIT__');
   });
 });

package/template-diy/README.md.tpl

@@ -58,7 +58,7 @@ pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍 + 调
 
 | 能力 | 一句话 | 传什么 / 拿回什么（贴真实调用与返回） | 要点头吗 | 点头时他看到的"会发生什么" |
 |---|---|---|---|---|
-| （这份骨架故意没有能力：`manifest.tools` 是空的。要加就照这张表填，只读的不点头、动东西的要点头） | | | | |
+| （这份骨架故意没有能力：`dsh.workbench.tools` 是空的。要加就照这张表填，只读的不点头、动东西的要点头） | | | | |
 
 ### 表 3 联动：agent 动完，这个模块哪一格变
 

package/template-diy/package.json.tpl

@@ -25,9 +25,13 @@
       "external": ["@dsh-workbench/core/client"]
     },
     "workbench": {
+      "apiVersion": 1,
       "unit": "__UNIT__",
-      "faces": { "host": "src/host.ts", "client": "src/client.tsx" }
-    }
+      "card": { "titleKey": "__UNIT__.cardTitle", "order": 90 },
+      "tools": [],
+      "host": { "inject": [] }
+    },
+    "workbenchFaces": { "host": "src/host.ts", "client": "src/client.tsx" }
   },
   "peerDependencies": { "@dsh-workbench/core": "^0.1.0", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },

package/template-diy/scripts/smoke.mjs.tpl

@@ -115,14 +115,12 @@ const ctx = {
 
 pluginExports.apply(ctx);
 check('卡片真的注册进了外壳', faces.length === 1, `注册了 ${faces.length} 个`);
-check(`注册的是 ${UNIT_ID} 单元`, faces[0]?.manifest.id === UNIT_ID, faces[0]?.manifest.id);
+check(`注册的是 ${UNIT_ID} 单元`, faces[0]?.unit === UNIT_ID, faces[0]?.unit);
 check('卡片是个能画的组件', typeof faces[0]?.card === 'function');
 check(
-  '卡片自己带标题与顺序（外壳的看板据此排）',
-  typeof faces[0]?.manifest.card?.titleKey === 'string' &&
-    faces[0].manifest.card.titleKey !== '' &&
-    typeof faces[0]?.manifest.card?.order === 'number',
-  JSON.stringify(faces[0]?.manifest.card),
+  '面只交 unit（标题与顺序住在 package.json 的 dsh.workbench 里，由外壳按 unit 交给浏览器）',
+  faces[0]?.manifest === undefined,
+  JSON.stringify(faces[0]?.manifest),
 );
 check(
   '卡片在空数据下也画得出来（不许抛）',

package/template-diy/src/client.tsx.tpl

@@ -10,18 +10,6 @@ const KB = 1024;
 const { Card, MockStrip, CenteredState, EmptyState, StateBlock, IconPanelScreen } = kit.components;
 const { useApiResource, useFixturePick } = kit.hooks;
 
-interface UnitManifest {
-  readonly id: string;
-  readonly kind: string;
-  readonly card: {
-    readonly titleKey: string;
-    readonly order: number;
-    readonly enabledByDefault: boolean;
-  } | null;
-  readonly tools: readonly unknown[];
-  readonly host: { readonly inject: readonly string[] };
-}
-
 type Rendered = ReturnType<typeof h>;
 type Translate = (key: string, params?: Record<string, unknown>) => string;
 
@@ -37,7 +25,7 @@ interface BoardProps {
 }
 
 interface UnitClientFace {
-  readonly manifest: UnitManifest;
+  readonly unit: string;
   readonly messages: { readonly zh: Readonly<Record<string, string>>; readonly en: Readonly<Record<string, string>> };
   readonly card: (props: BoardProps) => Rendered;
 }
@@ -146,14 +134,6 @@ export function overviewStateOf(input: OverviewInput): OverviewState {
   return { kind: 'loading' };
 }
 
-const manifest: UnitManifest = {
-  id: UNIT_ID,
-  kind: 'board',
-  card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
-  tools: [],
-  host: { inject: [] },
-};
-
 function bodyOf(state: OverviewState, t: Translate): Rendered {
   if (state.kind === 'idle') {
     return h(CenteredState, {
@@ -207,7 +187,7 @@ function bodyOf(state: OverviewState, t: Translate): Rendered {
 }
 
 const face: UnitClientFace = {
-  manifest,
+  unit: UNIT_ID,
   messages,
   card: (props) => {
     const workspace = props.world.current.workspace;

package/template-diy/src/host.ts.tpl

@@ -56,25 +56,13 @@ function limitOf(search: URLSearchParams): number {
   return Math.min(MAX_LIMIT, Math.max(1, Math.trunc(parsed)));
 }
 
-interface UnitManifest {
-  readonly id: string;
-  readonly kind: string;
-  readonly card: {
-    readonly titleKey: string;
-    readonly order: number;
-    readonly enabledByDefault: boolean;
-  } | null;
-  readonly tools: readonly unknown[];
-  readonly host: { readonly inject: readonly string[] };
-}
-
-interface UnitHostFace {
-  readonly manifest: UnitManifest;
+interface UnitModuleFace {
+  readonly unit: string;
   mount(): { routes: Record<string, RouteHandler>; registerTools(): Array<() => void> };
 }
 
 interface UnitRegistry {
-  register(face: UnitHostFace): () => void;
+  register(face: UnitModuleFace): () => void;
 }
 
 interface HostContext {
@@ -83,16 +71,8 @@ interface HostContext {
   logger?: { warn?(message: string): void } | undefined;
 }
 
-const manifest: UnitManifest = {
-  id: UNIT_ID,
-  kind: 'board',
-  card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
-  tools: [],
-  host: { inject: [] },
-};
-
-const face: UnitHostFace = {
-  manifest,
+const face: UnitModuleFace = {
+  unit: UNIT_ID,
   mount: () => ({
     routes: {
       [OVERVIEW_ROUTE]: async (search: URLSearchParams) => {

package/template-diy/src/plugin.test.ts.tpl

@@ -51,12 +51,12 @@ import {
 } from './client';
 
 interface HostFace {
-  readonly manifest: { readonly id: string };
+  readonly unit: string;
   mount(): { readonly routes: Record<string, (search: URLSearchParams) => Promise<unknown>> };
 }
 
 interface ClientFace {
-  readonly manifest: { readonly id: string };
+  readonly unit: string;
   readonly card: (props: {
     readonly world: { readonly current: { readonly workspace?: { readonly path: string } | null } };
     readonly refreshToken: number;
@@ -163,8 +163,8 @@ describe('__NAME__ 的面', () => {
   });
 
   it('宿主半侧与浏览器半侧都把自己的面注册进外壳', () => {
-    expect(hostFace().manifest.id).toBe('__UNIT__');
-    expect(clientFace().manifest.id).toBe('__UNIT__');
+    expect(hostFace().unit).toBe('__UNIT__');
+    expect(clientFace().unit).toBe('__UNIT__');
   });
 });