@dsh-workbench/module-tools 0.1.16 → 0.1.18

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/bin/dsh-wb-module.mjs

@@ -5,14 +5,15 @@ import { check } from '../src/check.mjs';
 import { design } from '../src/design.mjs';
 import { init } from '../src/init.mjs';
 import { publish } from '../src/publish.mjs';
+import { sync } from '../src/sync.mjs';
 
 const [command, ...rest] = process.argv.slice(2);
 const cwd = process.env.DSH_WB_MODULE_CWD ?? process.cwd();
 
-const commands = { build, check, init, design, publish };
+const commands = { build, check, init, design, publish, sync };
 
 if (!command || !commands[command]) {
-  console.error('用法：dsh-wb-module <build|check|init|design|publish> [--cwd <目录>]\n      dsh-wb-module check [--only contracts|bundles|source|primitives|kit|cards|standalone|markers|style|alias]\n      dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]\n      dsh-wb-module design <init|check|render|accept>   # 三张表：填、查空格、生成 README、验收打勾\n      dsh-wb-module publish                              # 发货前的清单：门禁 + npm pack 清单 + files 漏项（只 dry run）');
+  console.error('用法：dsh-wb-module <build|check|init|design|publish|sync> [--cwd <目录>]\n      dsh-wb-module check [--only contracts|bundles|source|primitives|kit|cards|standalone|markers|style|alias]\n      dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]\n      dsh-wb-module design <init|check|render|accept>   # 三张表：填、查空格、生成 README、验收打勾\n      dsh-wb-module sync                                 # 按清单生成 src/declared-tools.ts（工具名只有清单一处写者）\n      dsh-wb-module publish                              # 发货前的清单：门禁 + npm pack 清单 + files 漏项（只 dry run）');
   process.exit(2);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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.18"
   },
   "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';
@@ -223,6 +223,28 @@ export async function run() {
       continue;
     }
 
+    // 清单的 `card.titleKey` 是**面板那一格的标题**，它的文案住在模块自己交的字典里
+    // （`registerUnit` 那个面的 `messages`，`zh` / `en` 都必填）。键拼错、或字典漏了那一条 ⇒
+    // 面板上显示的就是原始键名（`demo.cardTitle`），而且一声不响 —— 这条判据盯它。
+    const titleKey = pkg.manifest.dsh?.workbench?.card?.titleKey;
+    if (typeof titleKey === 'string' && titleKey !== '') {
+      const messages = registered?.messages;
+      if (messages === undefined || messages === null || typeof messages !== 'object') {
+        problems.push(
+          `${name}: 清单的 card.titleKey「${titleKey}」没有落点 —— registerUnit 交的面里没有 messages，` +
+            '面板上那一格会显示原始键名',
+        );
+      } else {
+        const missing = ['zh', 'en'].filter((one) => typeof messages[one]?.[titleKey] !== 'string');
+        if (missing.length > 0) {
+          problems.push(
+            `${name}: 清单的 card.titleKey「${titleKey}」在模块字典的 ${missing.join(' / ')} 里没有 —— ` +
+              '面板上那一格会显示原始键名。清单写了 titleKey，字典就得有这一条（zh / en 都要）',
+          );
+        }
+      }
+    }
+
     const props = {
       world: { current: {} },
       t: (key) => key,
@@ -288,7 +310,7 @@ export async function run() {
   }
   return {
     status: 'pass',
-    notes: [`${rows.length} 张卡片在**空数据**下都画得出来（不许抛）`, ...rows],
+    notes: [`${rows.length} 张卡片在**空数据**下都画得出来（不许抛）；清单的 card.titleKey 在字典里都有落点`, ...rows],
     problems: [],
   };
 }