@dsh-workbench/core 0.1.16 → 0.1.18

package/dist/types/modules/panels/model/service.d.ts

@@ -1,24 +1,26 @@
 import type { WorkspaceStore } from '@dsh-workbench/shared/host';
 import type { UnitManifest } from '@dsh-workbench/shared';
-import { type PanelEntry } from './config';
+import { type BoardTarget, type PanelEntry, type ScopeBoards } from './config';
 export declare const PANELS_MODULE_ID = "panels";
 export declare const PANELS_FILE = "config.json";
 export declare const RELEASED_FILE = "released.json";
 export interface PanelsService {
-    list(workspace: string | null): PanelEntry[];
+    list(workspace: string | null, target?: BoardTarget): PanelEntry[];
+    boards(workspace: string | null): ScopeBoards;
     isReleased(id: string): boolean;
     release(id: string): void;
     accept(id: string): void;
     subscribe(listener: () => void): () => void;
     isEnabled(id: string, workspace: string | null): boolean;
-    show(id: string, workspace: string | null): PanelEntry[];
-    hide(id: string, workspace: string | null): PanelEntry[];
-    move(id: string, index: number, workspace: string | null): PanelEntry[];
-    resetWorkspace(workspace: string | null): PanelEntry[];
+    show(id: string, workspace: string | null, target?: BoardTarget): PanelEntry[];
+    hide(id: string, workspace: string | null, target?: BoardTarget): PanelEntry[];
+    move(id: string, index: number, workspace: string | null, target?: BoardTarget): PanelEntry[];
+    reset(workspace: string | null, target?: BoardTarget): PanelEntry[];
 }
 export declare function createPanelsService(options: {
     manifests: () => readonly UnitManifest[];
     store: WorkspaceStore;
+    owned?: (() => readonly string[]) | undefined;
     logger?: {
         warn?(message: string): void;
     } | undefined;

package/dist/types/shared/api/bundle-install.d.ts

@@ -8,7 +8,7 @@ export interface BundleRegistries {
     readonly fallbackRegistries: readonly BundleRegistry[];
     readonly resolved: string | null;
 }
-export type BundleInspectProblem = 'invalid-spec' | 'already-installed' | 'not-found' | 'not-a-package' | 'not-a-bundle' | 'network' | 'unknown';
+export type BundleInspectProblem = 'invalid-spec' | 'already-installed' | 'not-found' | 'not-a-package' | 'not-a-bundle' | 'not-a-workbench-module' | 'not-a-module-or-plugin' | 'network' | 'unknown';
 export type BundleSpecKind = 'registry' | 'path' | 'git' | 'tarball';
 export interface BundleInspectionAccepted {
     readonly status: 'accepted';
@@ -74,10 +74,16 @@ export interface BundleSupplyPayload {
     readonly state: BundleSupplyState;
     readonly reason?: string;
 }
+export interface BundleInstalledPlugin {
+    readonly kind: 'opencli-plugin';
+    readonly pkg: string;
+    readonly name?: string;
+}
 export interface BundleInstallPayload {
     readonly change: BundleChange;
     readonly module: BundleModulePayload;
     readonly supply: BundleSupplyPayload;
+    readonly plugin?: BundleInstalledPlugin;
 }
 export interface BundleRemovePayload {
     readonly change: BundleChange;
@@ -92,6 +98,7 @@ export interface ModuleVersion {
     readonly installed: string;
     readonly latest?: string;
     readonly local?: boolean;
+    readonly refused?: readonly string[];
 }
 export interface ModuleVersionsPayload {
     readonly modules: readonly ModuleVersion[];

package/dist/types/shared/api/host/__tests__/registry-declaration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/api/host/__tests__/unit-roster-facts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/api/host/bundle-routes.d.ts

@@ -1,5 +1,6 @@
 import type { DshHostContext, DshShell } from '@dsh-workbench/shared';
 import { type RouteHandler } from '@dsh-workbench/shared/host';
 export declare function bundleRegistriesHandler(ctx: DshHostContext): RouteHandler;
+export declare function resetRefusalLog(): void;
 export declare function moduleVersionsHandler(ctx: DshHostContext, shell: DshShell | undefined): RouteHandler;
 export declare function bundleInspectHandler(ctx: DshHostContext): RouteHandler;

package/dist/types/shared/api/host/installed-module.d.ts

@@ -22,5 +22,12 @@ export interface ProfileModule {
     readonly registry?: string;
     readonly local?: boolean;
 }
+export declare function profileManifestOf(profileDir: string | null): Readonly<Record<string, unknown>> | undefined;
 export declare function profileModules(profileDir: string | null): readonly ProfileModule[];
+export declare function moduleDeclarationOf(profileDir: string | null, pkg: string): unknown;
+export interface DeclarationGap {
+    readonly pkg: string;
+    readonly problems: readonly string[];
+}
+export declare function declarationGaps(profileDir: string | null): readonly DeclarationGap[] | undefined;
 export declare function readInstalledModule(profileDir: string | null, pkg: string): InstalledModule;

package/dist/types/shared/api/host/mount-units.d.ts

@@ -1,14 +1,15 @@
 import type { DshHostContext } from '@dsh-workbench/shared';
 import type { UnitManifest } from '@dsh-workbench/shared/host';
 import { type RouteTable } from '@dsh-workbench/shared/host';
-import type { ContextRenderer, UnitHostFace, UnitMountDeps, UnitMountResult, UnitCall } from '@dsh-workbench/shared/host';
+import type { ContextRenderer, UnitMountDeps, UnitMountResult, UnitCall } from '@dsh-workbench/shared/host';
+import type { HostUnit } from './unit-registry';
 import { type UnitReadiness } from './unit-readiness';
 export interface UnitFailure {
     readonly id: string;
     readonly reason: string;
 }
 export interface MountedUnit {
-    readonly face: UnitHostFace;
+    readonly host: HostUnit;
     readonly result: UnitMountResult;
     readonly readiness: UnitReadiness;
 }
@@ -40,13 +41,14 @@ interface NamedEntry {
     handle(payload: unknown): unknown;
 }
 export declare function failureReasonOf(error: unknown): string;
-export declare function mountUnits(faces: readonly UnitHostFace[], deps: {
+export declare function mountUnits(units: readonly HostUnit[], deps: {
     ctx: DshHostContext;
     logger?: {
         info?(m: string): void;
         warn?(m: string): void;
     } | undefined;
     manifests: () => readonly UnitManifest[];
+    ownedUnits?: () => readonly string[];
     opencliCommand?: string;
     probe?: UnitMountDeps['probe'];
     store?: UnitMountDeps['store'];

package/dist/types/shared/api/host/package-content.d.ts

@@ -0,0 +1,6 @@
+import type { DshShell } from '@dsh-workbench/shared';
+export declare function withPackageDir<T>(options: {
+    readonly shell?: DshShell | undefined;
+    readonly spec: string;
+    readonly registry?: string | undefined;
+}, visit: (dir: string) => T): Promise<T | undefined>;

package/dist/types/shared/api/host/package-content.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/api/host/package-kind.d.ts

@@ -0,0 +1,21 @@
+export type PackageKind = 'opencli-plugin' | 'dsh-bundle' | 'both' | 'neither';
+export interface PackageVerdict {
+    readonly kind: PackageKind;
+    readonly pkg?: string;
+    readonly pluginName?: string;
+}
+export interface NpmRef {
+    readonly name: string;
+    readonly version?: string;
+}
+export declare const OPENCLI_MANIFEST_FILE = "opencli-plugin.json";
+export declare function splitNpmSpec(spec: string): NpmRef | undefined;
+export declare function isCommandFile(name: string): boolean;
+export declare function pluginManifestOf(dir: string): Readonly<Record<string, unknown>> | undefined;
+export declare function hasCommandFile(dir: string): boolean;
+export declare function pluginAt(dir: string): {
+    readonly name?: string;
+} | undefined;
+export declare function dshMarkersOf(raw: unknown): boolean;
+export declare function verdictOf(dir: string): PackageVerdict | undefined;
+export declare function refusalReason(): string;

package/dist/types/shared/api/host/package-kind.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/api/host/package-route.d.ts

@@ -0,0 +1,23 @@
+import type { DshShell } from '@dsh-workbench/shared';
+import { type ResolvedPluginSource } from '@dsh-workbench/shared/host';
+export type PackageRouteKind = 'opencli-plugin' | 'dsh-bundle' | 'neither';
+export interface PackageRoute {
+    readonly kind: PackageRouteKind;
+    readonly pkg?: string;
+    readonly pluginName?: string;
+}
+export declare const LOCAL_PLUGIN_ENV = "DSH_WB_OPENCLI_PLUGIN_PATH";
+export declare const PLUGIN_REGISTRY_ENV = "DSH_WB_OPENCLI_PLUGIN_REGISTRY";
+export declare function packageRouteOf(options: {
+    readonly spec: string;
+    readonly shell?: DshShell | undefined;
+    readonly registry?: string | undefined;
+    readonly force?: boolean;
+}): Promise<PackageRoute | undefined>;
+export declare function resetPackageRouteCache(): void;
+export declare function pluginInstallPlan(options: {
+    readonly spec: string;
+    readonly command: string;
+    readonly registry?: string | undefined;
+    readonly pluginName?: string | undefined;
+}): ResolvedPluginSource;

package/dist/types/shared/api/host/package-route.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/api/host/registry-declaration.d.ts

@@ -0,0 +1,23 @@
+import type { DshShell } from '@dsh-workbench/shared';
+export declare function localDirOf(spec: string): string | undefined;
+export declare function packageManifestOf(dir: string): Readonly<Record<string, unknown>> | undefined;
+export declare function dshRecordOf(dir: string): unknown | undefined;
+export declare function packageNameOf(dir: string): string | undefined;
+export declare function pathDeclarationOf(spec: string): unknown | undefined;
+export interface RegistryDshLookup {
+    readonly readable: boolean;
+    readonly raw: unknown;
+}
+export declare function registryDshOf(options: {
+    shell: DshShell;
+    name: string;
+    registry?: string | undefined;
+    force?: boolean;
+}): Promise<RegistryDshLookup>;
+export declare function registryDeclarationOf(options: {
+    shell: DshShell;
+    name: string;
+    registry: string;
+    force?: boolean;
+}): Promise<unknown | undefined>;
+export declare function declarationRefusalOf(name: string, raw: unknown): readonly string[];

package/dist/types/shared/api/host/unit-registry.d.ts

@@ -1,9 +1,38 @@
 import type { UnitManifest } from '@dsh-workbench/shared';
-import type { UnitHostFace } from '@dsh-workbench/shared/host';
+import type { UnitModuleFace, UnitOwnedFace } from '@dsh-workbench/shared/host';
+export interface UnitRefusal {
+    readonly unit: string;
+    readonly pkg?: string;
+    readonly reasons: readonly string[];
+}
+export type UnitSource = {
+    readonly kind: 'package';
+    readonly pkg: string;
+} | {
+    readonly kind: 'owned';
+};
+export interface HostUnit {
+    readonly unit: string;
+    readonly manifest: UnitManifest;
+    readonly face: UnitModuleFace;
+    readonly source: UnitSource;
+}
+export interface UnitDeclarationSource {
+    readonly pkg: string;
+    readonly declaration: unknown;
+}
 export interface UnitRegistry {
-    register(face: UnitHostFace): () => void;
-    all(): readonly UnitHostFace[];
+    register(face: UnitModuleFace): () => void;
+    registerOwned(face: UnitOwnedFace): () => void;
+    all(): readonly HostUnit[];
+    owned(): readonly string[];
+    refusals(): readonly UnitRefusal[];
     manifests(): readonly UnitManifest[];
     subscribe(listener: () => void): () => void;
 }
-export declare function createUnitRegistry(): UnitRegistry;
+export declare function createUnitRegistry(options: {
+    declarationOf: (unit: string) => UnitDeclarationSource | undefined;
+    logger?: {
+        warn?(message: string): void;
+    } | undefined;
+}): UnitRegistry;

package/dist/types/shared/api/host/unit-roster-facts.d.ts

@@ -0,0 +1,5 @@
+import type { UnitRegistry } from './unit-registry';
+export declare function bindRosterFacts(options: {
+    readonly units: UnitRegistry;
+    readonly bump: (facts: readonly string[]) => void;
+}): () => void;

package/dist/types/shared/api/installed-plugins.d.ts

@@ -0,0 +1,12 @@
+export declare const INSTALLED_PLUGINS_ROUTE = "panels/plugins";
+export interface InstalledPlugin {
+    readonly pkg: string;
+    readonly name?: string;
+    readonly installed?: string;
+    readonly latest?: string;
+    readonly local?: boolean;
+    readonly broken?: boolean;
+}
+export interface InstalledPluginsPayload {
+    readonly plugins: readonly InstalledPlugin[];
+}

package/dist/types/shared/api/unit-manifests.d.ts

@@ -0,0 +1,5 @@
+import type { UnitManifest } from '@dsh-workbench/shared';
+export declare const UNIT_MANIFESTS_ROUTE = "unit-manifests";
+export interface UnitManifestsPayload {
+    readonly manifests: readonly UnitManifest[];
+}

package/dist/types/shared/api/unit-manifests.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/hooks/bundle-queries.d.ts

@@ -1,5 +1,7 @@
 import type { ApiResponse } from '@dsh-workbench/shared';
 import { type BundleInspectionPayload, type BundleRegistriesPayload, type ModuleVersionsPayload } from '../api/bundle-install';
+import { type InstalledPluginsPayload } from '../api/installed-plugins';
 export declare function readBundleRegistries(): Promise<ApiResponse<BundleRegistriesPayload>>;
 export declare function readBundleInspection(spec: string, registry?: string): Promise<ApiResponse<BundleInspectionPayload>>;
 export declare function readModuleVersions(force?: boolean): Promise<ApiResponse<ModuleVersionsPayload>>;
+export declare function readInstalledPlugins(force?: boolean): Promise<ApiResponse<InstalledPluginsPayload>>;

package/dist/types/shared/hooks/use-facts.d.ts

@@ -1,2 +1,3 @@
 export declare function useFactRevision(fact: string): number;
+export declare function subscribeFactRevision(fact: string, listener: () => void): () => void;
 export declare function useFactInvalidate(): (fact?: string) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/core",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "个人工作台：Agent 工作台外壳（左栏 + 常驻对话 + 自研右侧数据面板）。",
   "type": "module",
   "icon": "./icon.svg",
@@ -87,7 +87,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dsh-workbench/shared": "0.1.16"
+    "@dsh-workbench/shared": "0.1.18"
   },
   "scripts": {
     "build": "node scripts/build.mjs && node scripts/build-types.mjs",

package/skills/workbench-module-diy/BUILD.md

@@ -46,7 +46,7 @@ pnpm exec dsh-wb-module init <unit> --dir <工坊>/packages/module-<unit> --temp
 `<unit>` 是小写短横线标识（如 `my-thing`），它同时是单元 id、包名后缀、卡片样式前缀。
 **它必须全局唯一** —— 和工作台里其它模块、和外壳里已有的单元都不能撞；撞了装上去当场抛。
 
-生成的骨架是**能直接跑的**（十条判据 + 三个脚本开箱全绿；门禁还在，模板改坏了当场报）。
+生成的骨架是**能直接跑的**（十一条判据 + 三个脚本开箱全绿；门禁还在，模板改坏了当场报）。
 
 **两个模板，按需要挑**（加 `--template <名字>`）：
 
@@ -61,7 +61,7 @@ pnpm exec dsh-wb-module init <unit> --dir <工坊>/packages/module-<unit> --temp
 
 | 文件 | 职责 |
 |---|---|
-| `package.json` | 自述清单：包名、`dsh.bundle.patch`、`dsh.client`、`dsh.workbench.unit/faces`、四个脚本、peer 依赖 |
+| `package.json` | 自述清单：包名、`dsh.bundle.patch`、`dsh.client`、`dsh.workbench.unit`、`dsh.workbenchFaces{host,client}`（工具链字段，**不在协议里**，但门禁必填）、四个脚本、peer 依赖 |
 | `cordis.patch.yml` | 把自己插进 profile 的那一行 |
 | `src/host.ts` | 宿主面：`manifest` + `mount()`（路由 / 工具） |
 | `src/client.tsx` | 浏览器面：`manifest` + `card` |
@@ -85,7 +85,7 @@ README 里 `<!-- dsh-wb:design:start/end -->` 之间那一段**由它生成**（
 
 ```bash
 dsh-wb-module build                 # 出 client.js 与 dist/host.js
-dsh-wb-module check                 # 十条判据，全跑
+dsh-wb-module check                 # 十一条判据，全跑
 dsh-wb-module check --only cards    # 单跑一条（contracts / bundles / source / primitives /
                                     #   kit / cards / standalone / markers / alias / style）
 ```
@@ -104,13 +104,13 @@ pnpm test        # vitest
 pnpm selfcheck   # 构建 + 把 client.js 当加载器跑一遍（`diy` 骨架里还多一条 `design check`）
 ```
 
-**自己的门禁自己过，红了别抛给用户。** 十条判据在 [REVIEW.md](REVIEW.md) 里逐条翻了人话。
+**自己的门禁自己过，红了别抛给用户。** 十一条判据在 [REVIEW.md](REVIEW.md) 里逐条翻了人话。
 ⚠️ **`check` 不替你跑 `pnpm test`**（它只看形状与产物）：状态级的渲染、换算、边界都在你自己的
 `test` 里 —— 骨架开箱就带一份，改了数据源与渲染就顺手把它跑一遍，别让红线留在包里。
 ⚠️ **工坊里恒有两条是「不适用」，那不是「通过」**：`独立构建` 扫的是 `packages/*` 里的外壳源码
 （工坊里没有），`公开包无内部标识` 只扫要发出去的包（DIY 模块一律 `private`）。汇总行下面会把
 这次没查的那几条逐条列出来；**要验它们，回工作台仓库根跑一次 `dsh-wb-module check`**。
-所以「8 通过 · 2 不适用」不等于十条全绿 —— 别把这句话念给用户听。
+所以「8 通过 · 2 不适用」不等于十一条全绿 —— 别把这句话念给用户听。
 
 装上板那一步不是命令，是一把 agent 工具：`workbench_diy`（`action=list` 看工坊里有什么、`action=status, unit=<单元 id>`
 看它现在走到哪一步、`action=install` 装上并上板、`action=open` 只上板）—— 见 §7。

package/skills/workbench-module-diy/DESIGN.md

@@ -83,7 +83,7 @@
 - 门禁是绿的 —— 那是 agent 自己的门槛，不用他关心。
 - 下次他再说一句"改一下"，不用从头问：设计留下的记录还在。
 
-## 5 落点：`design.json`（机器形状）
+## 5 落点：`design.json`（设计底稿：人话一处，机器字段在清单）
 
 三张表 + 状态矩阵 + 数据源记录 + 验收清单住在模块根目录的 `design.json`，README 里那一段**由它生成**
 （夹在 `<!-- dsh-wb:design:start/end -->` 之间，别手改 —— 下一次 `check` 会判红）：
@@ -100,6 +100,12 @@ key 固定 `idle|loading|ready|empty|unreadable`）+ `config[]` + `capabilities[
 `config` / `capabilities` **允许空数组**（"这份模块故意没有能力"是一种决定）；其余空着就是没定的事。
 `link` 这类**可选格**留空渲染成 `—`，不算空格。
 
+`design.json` 是**设计底稿**：只装人话。"这条能力在哪些工作区出现"**哪里都别写** ——
+它既不在底稿、也不在清单：那是**用户**的事（他在 `workbench_panels` 里决定，见 [TOOLS.md](TOOLS.md) §12）。
+协议里那个 `scope`（`tools[].scope` / `card.scope`）**已经删掉**：用户口径是「模块开发者不能定义 scope，
+scope 永远是用户来决定的」（见 [ADR-0038 §2.4 / §6.16](../../../../docs/adr/0038-module-declaration-protocol.md)）。
+`contracts` 只拿名字把底稿与清单对起来（键集合对账）。
+
 五态那五行是矩阵的行，**不能省**；但某一态对这份模块确实不适用时，写一句为什么就行 ——
 `{ "key": "idle", "na": "读的是账号，不随项目变：没选项目时这张卡压根不渲染" }`，
 那一行不填 `sees` / `canDo` / `agentCan`，表里渲染成「（这份模块不适用）…」。

package/skills/workbench-module-diy/REVIEW.md

@@ -1,16 +1,17 @@
-# 门禁红了怎么办：十条判据的人话对照表
+# 门禁红了怎么办：十一条判据的人话对照表
 
 跑 `dsh-wb-module check`（或单跑一条 `--only <名字>`）。
 **每一条红的都在讲一件真出过事的事**，不是形式主义。红了就照下面修，别抛给用户。
 
 | 判据 | 它防的事故 | 红了的典型说法 | 怎么修 |
 |---|---|---|---|
-| `contracts` | dsh 组合阶段**不校验**你 `package.json` 里的声明 —— 错的 `external` 要到浏览器 `require` 那一刻才炸 | `单元 id "x" 与 … 撞了` / `faces.client 指的文件不存在` / `没有对 @dsh-workbench/core 的 peer 依赖` / `没有 typecheck 脚本` / `它不是 private，却既没声明 publishConfig.access=public…` | 按报的那一条改 `package.json`；`unit` 换个不撞的名字；四个脚本补全；私有不发就保持 `private: true` |
+| `contracts` | dsh 组合阶段**不校验**你 `package.json` 里的声明 —— 错的 `external` 要到浏览器 `require` 那一刻才炸；清单与代码、底稿与清单之间漂了也没人拦 | `单元 id "x" 与 … 撞了` / `dsh.workbenchFaces.client 指的文件不存在` / `dsh.workbenchFaces.host 没声明` / `没有对 @dsh-workbench/core 的 peer 依赖` / `没有 typecheck 脚本` / `它不是 private，却既没声明 publishConfig.access=public…` / `src/declared-tools.ts 与清单对不上（生成物过期…）` / `工具名的字面量又写回了源码` / `…没有 key` / `dsh.workbench 声明的能力与代码真正注册的对不上` / `design.json 的能力行里有「x」，清单的 tools[] 里却没有它` | 按报的那一条改 `package.json`（生成物对不上就跑 `dsh-wb-module sync`；工具名的字面量只许留在清单里）；`unit` 换个不撞的名字；`dsh.workbenchFaces` 补上两个**源码**入口；四个脚本补全；私有不发就保持 `private: true`。**工具只声明在清单里**（`dsh.workbench.tools`）且必须与 `mount()` 里 `registerTools()` 真正注册的**不重不漏**；写了 `design.json` 的话，它的 `capabilities[].name` 与清单的 `tools[].name` 也要不重不漏（U1c 的**键集合对账**，只对名字 —— 内容各写一处）；`gate.deniedTools` 是可选的运行期收窄，门禁不再对它做声明对账（协议里的 `scope` 已删 —— 哪些工作区出现由用户的板决定） |
+| `protocol` | `dsh.workbench` 是外壳读你得懂的那份声明：缺版本、形状不对、**多一个键**、枚举值不认都要在装机前拦下来。多出来的键最阴 —— 外壳会**静默忽略**它（拼错一个键 = 那句话白写） | `没有 apiVersion` / `apiVersion 是 99，这份只认 1` / `声明了 apiVersion 就要把静态半写全 —— 缺 dsh.workbench.tools` / `dsh.workbench 里有协议 v1 不认识的键 "faces"` / `card 里有不认的键 "enabledByDefault"`（这个键连外壳里都没有了 —— A-3 删的，见 [ADR-0038](../../../../docs/adr/0038-module-declaration-protocol.md) §6.7） / `tools[0] 里有协议不认的键 "scopes"` / `tools[0] 里有不认的键 "scope"`（`scope` 自本轮更正起**不在协议里**：能力在哪些工作区出现由用户的板决定，见 [ADR-0038 §2.4 / §6.16](../../../../docs/adr/0038-module-declaration-protocol.md)） | 补 `"apiVersion": 1`；把 `unit` / `card` / `tools` / `host` 四个键写全（没卡片写 `"card": null`、没工具写 `"tools": []`、一个服务都不要写 `"host": { "inject": [] }`）；删掉协议外的键（`faces` 自 A-2 起搬到 `dsh.workbenchFaces`，写回 `dsh.workbench` 里就是生字段）；`scope` **不要写**（协议不认它，写了就是生字段）。字段清单见 `dsh-wb-module` 的 README「协议」那一节 |
 | `bundles` | 两个运行时互串：浏览器产物里带 node 内置、宿主产物里带 DOM / react | `浏览器产物里出现了 node 内置 …` / `宿主产物里出现了 react` | 宿主面别 import 浏览器侧的东西；浏览器面别 import `node:*`。两侧只通过服务名相接 |
 | `source` | 非种子词的 `@deepseek-ai/*`、宿主侧碰 dsh 的浏览器包、`@/` 指到工作台源码 | `…在宿主侧可达` / `不是平台种子词` | 宿主侧只用 Node 侧的东西；dsh 原语一律走 `kit`；`@/` 只指自己的 `src/` |
 | `primitives` | 声明了 `external` 却没有产物物证 ⇒ dsh 原语被**内联**成第二份实例 | `…用了却没声明 external` / `宿主产物里出现了` | 在 `dsh.client.external` 里显式声明它；确认产物里是 `require(...)` 而不是被打包进来 |
 | `kit` | 用了 peer 下限那份外壳**还没有**的 kit 成员 ⇒ 卡片首帧 `Element type is invalid`，整块面板被 React 卸掉 | `kit.components.X 在这份外壳里没有` / `peer 下限比 devDependency 还旧` | 只用 peer 范围里真有的成员；把 `peerDependencies` 的下限提到你实际用的那档 |
-| `cards` | 卡片拿**空数据**就抛 ⇒ 用户看到"卡片一直不出来 / 点一下白屏" | `空数据下卡片抛了` / `卡片只画出一个节点` / `卡片没套外壳的卡壳` | 让卡片在没数据时也画得出来（已有的加载 / 空 / 阻断态）；外面套 `kit.components.Card` |
+| `cards` | 卡片拿**空数据**就抛 ⇒ 用户看到"卡片一直不出来 / 点一下白屏" | `空数据下卡片抛了` / `卡片只画出一个节点` / `卡片没套外壳的卡壳` / `清单的 card.titleKey「x」在模块字典的 en 里没有` / `…没有落点` | 让卡片在没数据时也画得出来（已有的加载 / 空 / 阻断态）；外面套 `kit.components.Card`；清单写了 `titleKey`，`registerUnit` 交的 `messages` 里 `zh` / `en` 都得有那一条（漏了面板上显示的是原始键名） |
 | `standalone` | "只有工作台源码在场才编得过" ⇒ 发布出去就散架 | `build 在外壳源码不在场时失败` / `typecheck 在外壳源码不在场时失败` | 别引用工作台源码；`tsconfig` 里 `paths` 的值必须是**相对路径**（`"./src/*"`，不是 `"src/*"`） |
 | `markers` | 内网域名 / 企业内部名泄进要公开发布的包 | `命中内网 npm 源` / `命中内网域名` | 那些值不该写进包里；要配就落到模块自己的配置面，或走用户自己声明的来源 |
 | `alias` | `@/` 伸进工作台源码 ⇒ 装的人手上没有那份源码 | `…指向外壳源码` | `@/` 只许指自己的 `src/`；跨包的东西走包名 |

package/skills/workbench-module-diy/TOOLING.md

@@ -12,7 +12,7 @@
 
 | 纪律（出处） | 固化形态 |
 |---|---|
-| 十条判据（[REVIEW.md](REVIEW.md)） | `dsh-wb-module check`（`--only <判据>` 单跑；`--only kit` 列这份外壳的 kit 成员） |
+| 十一条判据（[REVIEW.md](REVIEW.md)） | `dsh-wb-module check`（`--only <判据>` 单跑；`--only kit` 列这份外壳的 kit 成员） |
 | 落点、文件形状、四个脚本（[BUILD.md](BUILD.md) §1–§2） | `dsh-wb-module init --template diy`（骨架带一条真读盘的数据源）+ `scripts/smoke.mjs` |
 | 装、上板、不重装（[WIRING.md](WIRING.md) §3） | `workbench_diy`（`install` / `open` / `status`）+ `workbench_panels` |
 | 空着的格就是还没定的事（[DESIGN.md](DESIGN.md) §5） | `design.json` + `design check`（点名叫出空格）/ `render` / `accept` |
@@ -27,7 +27,7 @@
 | DOM 读怎么读（[DATASOURCE.md](DATASOURCE.md) 第 2 步） | `probe`（探）+ `browserFind`（固化）—— 切格 / 按列取值是两个纯函数 |
 | 链接只有一副样子（[PANEL.md](PANEL.md) §6） | kit 的 `Link` 是唯一一份（**没有 `icon` 口子**），`check --only style` 拦裸 `<a>` |
 | 输入框不用自己配样式（[PANEL.md](PANEL.md) §5.1） | `TextField` 的默认内边距 + kit 的 `Field`（标签 + 提示的排布） |
-| 同一把工具在有些项目里不该出现（[TOOLS.md](TOOLS.md) §12） | `gate.deniedTools` + `design.json` 能力行的 `scope`；`check --only contracts` 只查正向 —— 反向会误伤"按自己的开关收窄"那一种用法 |
+| 这个单元在哪些工作区出现（[TOOLS.md](TOOLS.md) §12） | **不是模块能声明的事** —— 用户用 `workbench_panels` 的板决定（卡片与全部工具同判）；协议里的 `scope` 已删。`gate.deniedTools` 是可选的运行期收窄，门禁不再对它做声明对账 |
 
 ## 留给 agent 的（判断，不该固化）
 

package/skills/workbench-module-diy/TOOLS.md

@@ -79,7 +79,7 @@
 ### 6.1 写法（清单 + 两个函数；缺一个门禁就红）
 
 ```ts
-tools: [{ name: 'workbench_demo_rebuild', writes: true }],
+tools: [{ name: 'workbench_demo_rebuild', writes: true, key: 'rebuild' }],
 
 needsApproval: (call) => ({
   kind: 'ask',
@@ -91,6 +91,9 @@ needsApproval: (call) => ({
 approvalDetail: async (call) => ({ zh: '会覆盖这 3 个模块的产物，不碰源码', en: '…' }),
 ```
 
+* `key` 是代码里那个短名（lowerCamelCase）。给了它就 `dsh-wb-module sync` 一次，生成
+  `src/declared-tools.ts`，代码写 `DECLARED_TOOLS.rebuild.name` —— 工具名的字面量只剩清单这一处
+  （键写错是编译错；生成物过期、半写 key、源码里又写字面量，门禁都红）。一个 key 都不写也行（不适用那一档）。
 * `needsApproval` 回 `{ kind: 'read' }` = 这件不用问；回 `{ kind: 'ask', … }` = 要问；
   **清单写着 `writes: true` 却不认领，外壳当场 deny**（"在套件的 needsApproval 里补一条审批"）——
   但那条错误只有真跑一次才看得见，所以 `check --only contracts` 会替用户先看一遍：缺 `needsApproval`、
@@ -250,5 +253,12 @@ return {
 `packages/workbench/src/modules/panels/index.ts`）：某张卡在这个项目上没开 → 那张卡的工具全不出现；
 工坊那把窄门工具 `workbench_diy` **只在工坊会话里**出现，别处一律不出现。
 
-表里怎么写：`design.json` 的能力行有「在哪些项目里出现」那一格（`scope`：`always` / `workspace`）。
-写了 `workspace` 就必须真的实现 `gate.deniedTools` —— 表和代码对不上，`check --only contracts` 会红。
+**"这条能力在哪些工作区出现"不用你声明 —— 那是用户的事。** 用户口径：「模块开发者不能定义 scope，
+scope 永远是用户来决定的」。他在 `workbench_panels`（agent 工具）里把它们放上/收起；一个单元在不在，
+它的卡片与**全部**工具同判（外壳的 `resolveScope` 只看两份板：本工作区那份，否则机器级那份）。
+协议里那个 `scope`（`dsh.workbench.tools[].scope` / `card.scope`）**已经删掉**，写它就是写了一个
+不认识的键、`check --only protocol` 当场红（见 [ADR-0038 §2.4 / §6.16](../../../../docs/adr/0038-module-declaration-protocol.md)）。
+`design.json` 的能力行也没有这一格。
+
+`gate.deniedTools` 仍然可以接，但它是**可选**的运行期收窄（"这个能力还没配好，先按我自己的开关藏起来"），
+**不是**一条声明出来的承诺：门禁不再拿任何声明去对账它（那条判据已删 —— 没有作者侧声明就没有可比的东西）。