@dsh-workbench/module-tools 0.1.16 → 0.1.18

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';
@@ -22,17 +22,60 @@ const CLASS_TOKEN = /(^|[^-\w])\.?(wb-[a-zA-Z0-9-]+)/g;
 // 契约 = 外壳**所有**声明了 `wb-*` 的样式表，不只是那份全局 `board.css`：
 // ADR-0029 要求组件的样式跟组件走，所以 `wb-card` / `wb-rows` / `wb-note` 这些已经搬进
 // `packages/shared/src/components/*.css`（谁渲染谁拥有）。契约跟着搬，模块借用它们才不误报。
-const CONTRACT_FILES = [
-  fileURLToPath(new URL('../../../workbench/src/shared/styles/board.css', import.meta.url)),
-  ...(() => {
-    const dir = fileURLToPath(new URL('../../../shared/src/components', import.meta.url));
-    return existsSync(dir)
-      ? readdirSync(dir)
-          .filter((name) => name.endsWith('.css'))
-          .map((name) => join(dir, name))
-      : [];
-  })(),
-];
+// 契约按**两种安装形态**解析，两边必须给同一份名单（实测过差别，见 spec §24.4）：
+//   · 在外壳仓里跑：源码就在隔壁（`workbench/src/shared/styles/board.css` + `shared/src/components/*.css`）；
+//   · 在模块仓里跑：只能从**已装的外壳**读 —— `@dsh-workbench/core/dist/board.css`（构建时随包出货的那份
+//     契约副本，见 `packages/workbench/scripts/build.mjs`）与 `@dsh-workbench/shared/src/components/*.css`
+//     （shared 本来就发源码）。
+// 从前只写死了相对 module-tools 自己的路径 ⇒ 装进模块仓后 `board.css` 找不到，契约退化成"只有 shared 组件
+// 那一份"，于是 `board.css` 里的合法借用（例如 `wb-iconButton`）被**误报**；而且借用检查在契约缺失时
+// 会 `contract.has` 抛异常（"契约文件不在"那条 note 根本到不了）。
+const SOURCE_BOARD = fileURLToPath(new URL('../../../workbench/src/shared/styles/board.css', import.meta.url));
+const SOURCE_COMPONENTS = fileURLToPath(new URL('../../../shared/src/components', import.meta.url));
+const INSTALLED_BOARD = join('node_modules', '@dsh-workbench', 'core', 'dist', 'board.css');
+const INSTALLED_COMPONENTS = join('node_modules', '@dsh-workbench', 'shared', 'src', 'components');
+
+function installedUnder(dir, tail) {
+  let at = resolve(dir);
+  for (;;) {
+    const candidate = join(at, tail);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(at);
+    if (parent === at) return undefined;
+    at = parent;
+  }
+}
+
+function cssFilesIn(dir) {
+  try {
+    return readdirSync(dir)
+      .filter((name) => name.endsWith('.css'))
+      .map((name) => join(dir, name));
+  } catch {
+    return [];
+  }
+}
+
+function contractFilesFor(moduleDir) {
+  const board = existsSync(SOURCE_BOARD) ? SOURCE_BOARD : installedUnder(moduleDir, INSTALLED_BOARD);
+  const components = existsSync(SOURCE_COMPONENTS)
+    ? SOURCE_COMPONENTS
+    : installedUnder(moduleDir, INSTALLED_COMPONENTS);
+  return [
+    ...(board === undefined ? [] : [board]),
+    ...(components === undefined ? [] : cssFilesIn(components)),
+  ];
+}
+
+function contractOf(moduleDir) {
+  const files = contractFilesFor(moduleDir);
+  if (files.length === 0) return null;
+  return new Set(
+    files.flatMap((file) =>
+      Array.from(readFileSync(file, 'utf8').matchAll(CLASS_TOKEN), (match) => match[2]),
+    ),
+  );
+}
 
 export const title = '样式归属';
 
@@ -51,19 +94,13 @@ function isTestSource(file) {
 }
 
 export async function run() {
-  const contract = CONTRACT_FILES.some((file) => existsSync(file))
-    ? new Set(
-        CONTRACT_FILES.filter((file) => existsSync(file)).flatMap((file) =>
-          Array.from(readFileSync(file, 'utf8').matchAll(CLASS_TOKEN), (match) => match[2]),
-        ),
-      )
-    : null;
-
   const problems = [];
   const borrowed = [];
   const anchors = [];
   const modules = discoverModulePackages({ root: process.cwd() });
+  const contracts = new Map(modules.map((pkg) => [pkg.dir, contractOf(pkg.dir)]));
   for (const pkg of modules) {
+    const contract = contracts.get(pkg.dir);
     for (const file of walk(pkg.dir)) {
       if (!/\.(css|ts|tsx)$/.test(file)) continue;
       let text;
@@ -84,15 +121,14 @@ export async function run() {
 
       if (isTestSource(file)) continue;
       if (!/\.tsx?$/.test(file)) continue;
-      if (contract !== null) {
-        lines.forEach((line, index) => {
-          if (!BARE_ANCHOR.test(line)) return;
-          anchors.push(
-            `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 手写了裸 <a> —— ` +
-              `外链一律用 kit 的 Link（新窗口、noopener、自带那个外链小箭头；样式只有这一份）：${line.trim().slice(0, 80)}`,
-          );
-        });
-      }
+      lines.forEach((line, index) => {
+        if (!BARE_ANCHOR.test(line)) return;
+        anchors.push(
+          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 手写了裸 <a> —— ` +
+            `外链一律用 kit 的 Link（新窗口、noopener、自带那个外链小箭头；样式只有这一份）：${line.trim().slice(0, 80)}`,
+        );
+      });
+      if (contract === null) continue;
       lines.forEach((line, index) => {
         for (const match of line.matchAll(CLASS_TOKEN)) {
           const name = match[2];
@@ -149,7 +185,8 @@ export async function run() {
     if (borrowed.length > 0) {
       notes.push(
         `${borrowed.length} 处是「模块借用了契约里没有的 wb-* 类」：（契约是本仓 board.css：模块只许借它里面有的类。` +
-          '没有的那个要么是拼错/改了名漏改，要么本该进 board.css —— 空类名在真机上就是没样式，而且没人会报错）',
+          '没有的那个要么是拼错/改了名漏改，要么本该进 board.css —— 空类名在真机上就是没样式，而且没人会报错。' +
+          '名单是**外壳出货的那份**（`@dsh-workbench/core/dist/board.css` + 外壳组件自己的样式表））',
       );
     }
     if (anchors.length > 0) {
@@ -170,10 +207,23 @@ export async function run() {
     };
   }
 
+  const noContract = modules
+    .filter((pkg) => contracts.get(pkg.dir) === null)
+    .map((pkg) => pkg.manifest.name);
+  if (noContract.length === modules.length) {
+    return {
+      status: 'skip',
+      notes: [
+        '找不到外壳出货的那份契约（`@dsh-workbench/core/dist/board.css` 与 `@dsh-workbench/shared` 的组件样式表都不在）' +
+          '—— 模块借的 wb-* 类这一项这次一条都没查，不是"没问题"',
+      ],
+      problems: [],
+    };
+  }
   const contractNote =
-    contract === null
-      ? '契约文件不在（这次只查了"模块不许定义 wb-*"）'
-      : `借用的类都在契约里（board.css + 外壳组件自己的样式表）`;
+    noContract.length === 0
+      ? '借用的类都在契约里（外壳出货的 board.css + 外壳组件自己的样式表）'
+      : `${noContract.join(' / ')} 那一边找不到外壳的契约，借用这一项没查`;
   return {
     status: 'pass',
     notes: [`${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}`],

package/src/declared-tools.mjs

@@ -0,0 +1,85 @@
+// 工具名只有**一处写者**：清单（`dsh.workbench.tools[].name`）。
+//
+// 代码里注册一个工具必须报它的名字，所以从前那份字面量在清单与代码里各写一遍 —— 只能靠判据对账
+// （`check:contracts` 的 reconcileTools 就是这么干的）。`tools[].key` + `dsh-wb-module sync` 把
+// 代码那一半**生成**出来：
+//
+//     dsh-wb-module sync   →   src/declared-tools.ts
+//         export const DECLARED_TOOLS = {
+//           sync: { name: 'workbench_argocd_sync', writes: true },
+//         } as const;
+//
+// 于是：改名只动清单一处；代码引用的是**键**（`DECLARED_TOOLS.sync.name`），键写错是编译错；
+// 生成物落后于清单由判据当场判红。
+//
+// 方向是**单向**的：绝不回写 `package.json`（ADR-0038 §2.5 已经拒了"生成式回写"：`package.json`
+// 有两个写者（人与生成器）就会静默覆盖）。
+//
+// 输出与比对都按"各家 prettier 都可能重排"来设计：字面量用单引号（本生态的 TS 风格），
+// 比对时**忽略空白、把两种引号当同一件事** —— 重排不算过期，值变了才算。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DECLARED_TOOLS_FILE = 'src/declared-tools.ts';
+
+export function declaredToolsPathOf(dir) {
+  return join(dir, DECLARED_TOOLS_FILE);
+}
+
+function toolsOf(raw) {
+  return Array.isArray(raw?.tools) ? raw.tools : [];
+}
+
+function keyOf(tool) {
+  return typeof tool?.key === 'string' && tool.key.trim() !== '' ? tool.key.trim() : '';
+}
+
+/** 一个 key 都没写的模块不适用（那是不用生成物那一档，判据也不找它）。 */
+export function declaredToolsApplies(raw) {
+  return toolsOf(raw).some((tool) => keyOf(tool) !== '');
+}
+
+/** 还没写 key 的那些工具（有 key 就得每个都有：半写会让生成物少几条，而代码里还在写字面量）。 */
+export function declaredToolsWithoutKey(raw) {
+  return toolsOf(raw)
+    .filter((tool) => keyOf(tool) === '')
+    .map((tool) => JSON.stringify(tool?.name));
+}
+
+/** 生成物的正文。**不给注释**：它落在模块的 `src/**`（零注释那一条管到这里），改它无效、过期会红。 */
+export function renderDeclaredTools(raw) {
+  const rows = toolsOf(raw).map(
+    (tool) =>
+      `  ${keyOf(tool)}: { name: '${tool.name}', writes: ${tool.writes === true} },`,
+  );
+  return [
+    'export const DECLARED_TOOLS = {',
+    ...rows,
+    '} as const;',
+    '',
+    'export type DeclaredToolKey = keyof typeof DECLARED_TOOLS;',
+    '',
+  ].join('\n');
+}
+
+/** 生成物与清单对不上的原因（`undefined` = 新鲜，或不适用）。 */
+export function declaredToolsProblemOf(dir, raw) {
+  if (!declaredToolsApplies(raw)) return undefined;
+  const missing = declaredToolsWithoutKey(raw);
+  if (missing.length > 0) {
+    return `清单里 ${missing.join(' / ')} 没有 key —— 有 key 就走生成物那一档，那就每个工具都得有一个`;
+  }
+  const at = declaredToolsPathOf(dir);
+  if (!existsSync(at)) {
+    return `${DECLARED_TOOLS_FILE} 不在 —— 清单里给了 key 就该有生成物，跑 \`dsh-wb-module sync\` 生成`;
+  }
+  const strip = (text) => text.replace(/\s+/g, '').replace(/"/g, "'");
+  if (strip(readFileSync(at, 'utf8')) !== strip(renderDeclaredTools(raw))) {
+    return (
+      `${DECLARED_TOOLS_FILE} 与清单对不上（生成物过期，或有人手改了它）—— ` +
+      '跑 `dsh-wb-module sync` 刷新。别手改：它是生成的'
+    );
+  }
+  return undefined;
+}

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/src/sync.mjs

@@ -0,0 +1,51 @@
+// `dsh-wb-module sync`：按清单生成 `src/declared-tools.ts`（单向，清单 → 代码）。
+//
+// 为什么需要它、生成物长什么样、为什么绝不回写 package.json：见 `declared-tools.mjs` 开头与
+// ADR-0038 的 `tools[].key` 一节。
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  DECLARED_TOOLS_FILE,
+  declaredToolsApplies,
+  declaredToolsPathOf,
+  declaredToolsProblemOf,
+  declaredToolsWithoutKey,
+  renderDeclaredTools,
+} from './declared-tools.mjs';
+
+export async function sync({ root }) {
+  const manifestPath = join(root, 'package.json');
+  if (!existsSync(manifestPath)) throw new Error(`${manifestPath} 不在 —— sync 要在模块包目录里跑`);
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const raw = manifest.dsh?.workbench;
+  const unit = typeof raw?.unit === 'string' ? raw.unit : manifest.name;
+  if (raw === undefined) throw new Error(`${unit}: package.json 里没有 dsh.workbench —— 这不是模块包`);
+
+  const tools = Array.isArray(raw.tools) ? raw.tools : [];
+  if (tools.length === 0) {
+    console.log(`${unit}: 清单里没有工具，不用生成物`);
+    return;
+  }
+
+  const missing = declaredToolsWithoutKey(raw);
+  if (missing.length > 0) {
+    const hint = declaredToolsApplies(raw)
+      ? '有 key 就走生成物那一档，那就每个工具都得有一个'
+      : '给每个工具加一个 lowerCamelCase 的 key，代码里就不再写工具名的字面量';
+    throw new Error(
+      `${unit}: 清单里 ${missing.join(' / ')} 没有 key —— ${hint}。例如：\n` +
+        `${tools.map((tool) => `  "key": "…",  // ${JSON.stringify(tool.name)}`).join('\n')}\n` +
+        '（key 是代码里那个短名：`DECLARED_TOOLS.<key>.name`。见 ADR-0038 的 `tools[].key` 一节）',
+    );
+  }
+
+  const at = declaredToolsPathOf(root);
+  const had = existsSync(at);
+  const stale = declaredToolsProblemOf(root, raw);
+  writeFileSync(at, renderDeclaredTools(raw));
+  console.log(
+    `${unit}: 写了 ${DECLARED_TOOLS_FILE}（${tools.length} 个工具，按清单生成）` +
+      (had && stale !== undefined ? ' —— 原来那份和清单对不上，已刷新' : ''),
+  );
+}

package/template/README.md.tpl

@@ -23,6 +23,16 @@ pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍，看
 dsh plugin --profile workbench add <本目录>
 ```
 
+要加能力：`package.json` 的 `dsh.workbench.tools[]` 里每个工具写 `name` / `writes` / `key`
+（`key` 是代码里那个短名，lowerCamelCase），然后跑一次
+
+```bash
+dsh-wb-module sync   # 按清单生成 src/declared-tools.ts
+```
+
+代码里写 `DECLARED_TOOLS.<key>.name` —— **工具名的字面量只留在清单这一处**。生成物过期、半写 `key`、
+或源码里又写了一遍工具名字面量，`check` 都会红（`sync` 会告诉你缺哪个工具的 `key`）。
+
 面板只读、写入只走 agent 工具；共享代码从 `@dsh-workbench/shared` 拿，
 单例机制（hooks / 容器组件 / 读缝）只能从 `@dsh-workbench/core/client` 的 kit 拿。
 dsh 已有的组件与样式**先从 kit 拿**，别从 DOM + CSS 重画。

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 动完，这个模块哪一格变
 
@@ -155,8 +155,11 @@ GET /api/__UNIT__/overview?path=<绝对路径>&limit=<1..50>
 
 ### 会写：清单里标出来 + 认领审批
 
+> 每个工具都写一个 `key`（代码里那个短名，lowerCamelCase），然后 `dsh-wb-module sync` 生成
+> `src/declared-tools.ts`：代码写 `DECLARED_TOOLS.rebuild.name` —— 工具名的字面量只留在清单里。
+
 ```ts
-tools: [{ name: 'workbench___UNIT___rebuild', writes: true }],
+tools: [{ name: 'workbench___UNIT___rebuild', writes: true, key: 'rebuild' }],
 
 needsApproval: (call) => ({
   kind: 'ask',

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;