@dsh-workbench/module-tools 0.3.10 → 1.0.0-beta.0

package/src/seed.mjs

@@ -1,22 +1,3 @@
-// dsh 客户端模块表的**平台种子词** —— 一个模块的浏览器产物**天生**能 require 到它们。
-//
-// 名单真值出处：dsh 外壳声明平台模块的地方（rc.2 `packages/client/web/src/platform.ts` 的
-// `PLATFORM_MODULES`，装种子的 `seed.ts` 的 `getStaticModules()` 与它 `satisfies` 互锁）；
-// 装机产物里那张表在 `@deepseek-ai/dsh-web-frontend/dist/assets/index-*.js` 的 `SZ()`。
-// 证据与推理见 `.scratch/dsh-ui-alignment/spec.md` §0；「模块可以直接用它」的决定见 ADR-0028。
-//
-// 这份表是**唯一真相**：构建的 external 默认表（`build.mjs`）、契约判据（`contracts.mjs`）、
-// 源码边界（`checks/source.mjs`）与新增的原语判据（`checks/primitives.mjs`）都从这里取。
-// dsh 升版改了种子表，只改这一处。
-//
-// ⚠️ 2026-10-18（dsh 0.2.1-rc.2 对账）：这张表**漏过两个词** —— `zod` 与
-// `@tanstack/react-virtual`（dsh 那边一共 11 个，我们只抄了 9 个，`0.2.1-alpha.3` 就少，
-// 不是这次升级引入的）。漏的代价不对称：`build.mjs:17,161` 拿它当模块浏览器产物的默认
-// external 表 ⇒ 模块写 `import 'zod'` 会被**内联出第二份**；`contracts.mjs:39,551` 拿
-// `SEED_SHORT` 判 `dsh.client.external` 能不能落地 ⇒ 声明 `zod` 反而被判「落不到图里任何一行」。
-// 对账脚本：把 dsh 那份 `platform.ts` 的数组原样抄下来与这里逐字比（见两份报告
-// `.scratch/dsh-0.2.1-rc.2/report-client-surface.md` §2.1）。
-
 export const SEED_SPECIFIERS = [
   'react',
   'react/jsx-runtime',
@@ -31,10 +12,6 @@ export const SEED_SPECIFIERS = [
   '@deepseek-ai/dsh-client-ui-dockkit',
 ];
 
-/**
- * 外部声明里允许的**短名**（历史写法：`"ui-primitives"` 这类）与**全名**。
- * 契约判据按它放行，免得老包只因为写法短就被判红。
- */
 export const SEED_SHORT = new Set([
   'react',
   'react-dom',
@@ -50,10 +27,8 @@ export const SEED_SHORT = new Set([
 
 const SEED_LONG = new Set(SEED_SPECIFIERS);
 
-/** 是不是种子词（按完整说明符判断）。 */
 export const isSeedSpecifier = (specifier) => SEED_LONG.has(specifier);
 
-/** 种子词里那些 **dsh 的** 包 —— 它们只在浏览器侧存在，宿主侧一个都不许碰。 */
 export const BROWSER_SEED_SPECIFIERS = SEED_SPECIFIERS.filter(
   (name) => name.startsWith('@deepseek-ai/'),
 );

package/src/shell-type-files.mjs

@@ -1,15 +1,3 @@
-// kit 成员 → 类型文件：外壳那两个包的类型树（`@dsh-workbench/shared` 的 `dist` 与外壳自己的 `dist/types`）。
-//
-// 为什么要扫：kit 的成员是**运行期**从外壳产物 `client.js` 里跑出来的（见 `checks/kit.mjs`），
-// 产物里没有"这个成员来自哪个模块"；而类型树里每个成员的声明都躺在某份 `.d.ts` 里 ——
-// 扫一遍就能把"名字"落到"文件"，于是 agent「想问哪个直接去看那份文件」有确切路径。
-//
-// 为什么是名字扫描而不是真正的类型解析：这些 `.d.ts` 是 tsc 生成的、声明形状规整
-// （`export declare const X` / `export interface X` / `export { X } from '…'`），而 kit 的成员
-// 本来就是运行期对象上的键名。扫描不引 TypeScript 依赖、贵在稳；代价是"同名声明出现在多处"时
-// 要挑一个（挑法见 `preferred`），以及极少数成员指到的是 barrel 而不是最终实现文件。
-// 实测本机 190 个 kit 成员 190 个都落得到文件（见 `.scratch/dsh-primitives-face/verify.md` §2）。
-
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
@@ -39,35 +27,24 @@ function namesIn(clause) {
     .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
 }
 
-/** 外壳那两个包的类型树（`shared` 没装就只给外壳那棵）。 */
 export function shellTypeRoots(shellClientPath) {
   const shellRoot = dirname(shellClientPath);
   const roots = {};
   const shellTypes = join(shellRoot, 'dist', 'types');
   if (existsSync(shellTypes)) roots.shell = shellTypes;
-  // 打印用"从 node_modules 看"的那条路径（pnpm 的真身在 `.pnpm/` 哈希目录里）；读文件两条都行。
+
   const viaNodeModules = join(shellRoot, 'node_modules', '@dsh-workbench', 'shared', 'dist');
   try {
-    // 解析 "." 那个入口（= `dist/index.js`）再取 dirname —— shared 的 `exports` 里**没有**
-    // `./package.json` 这一条，直接 resolve 它的 package.json 会 ERR_PACKAGE_PATH_NOT_EXPORTED。
+
     const sharedEntry = createRequire(join(shellRoot, 'package.json')).resolve('@dsh-workbench/shared');
     const sharedTypes = dirname(sharedEntry);
     if (existsSync(sharedTypes)) roots.shared = existsSync(viaNodeModules) ? viaNodeModules : sharedTypes;
   } catch {
-    // 没装 shared：只有外壳自己那棵，仍然能落一部分成员
+
   }
   return { shellRoot, roots };
 }
 
-/**
- * 同名多处时挑哪个：组件 > hooks > 库 > 其他 > **套件内部（`app/` / `modules/`）垫底**，同档挑路径短的。
- *
- * 垫底那一档是 2026-10-20 补的（ADR-0067 的 kit JSDoc 判据撞出来的）：kit 的 `readText`（共享包
- * `config/storage.ts`）与外壳内部 `modules/panels/model/diy-report.ts` 里的同名函数撞了，而 `modules/`
- * 那条路径在 `node_modules` 那份类型树旁边**更短**，于是 `--file readText` 一直指到别人的实现上。
- * kit 的成员只从 `client.tsx` 那几处 spread 来（共享包 + 外壳 `shared/**`），套件内部不会是它 ——
- * 所以垫底只影响撞名时的取舍，掉不到"本来该选的那份"。
- */
 function preferred(candidates) {
   const rank = (file) =>
     file.includes('/components/')
@@ -82,10 +59,6 @@ function preferred(candidates) {
   return [...candidates].sort((a, b) => rank(a.file) - rank(b.file) || a.file.length - b.file.length)[0];
 }
 
-/**
- * 把 kit 的成员名落到类型文件。
- * 返回 `{ roots, files: Map<名字, 绝对路径>, missing: 名字[] }` —— `roots` 是两棵类型树的绝对根。
- */
 export function memberFilesOf(shellClientPath, names) {
   const { roots } = shellTypeRoots(shellClientPath);
   const index = new Map();

package/src/sync.mjs

@@ -1,8 +1,3 @@
-// `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 {
@@ -13,6 +8,13 @@ import {
   declaredToolsWithoutKey,
   renderDeclaredTools,
 } from './declared-tools.mjs';
+import { readDesign } from './design.mjs';
+import {
+  DATASOURCE_FILE,
+  datasourceEntriesOf,
+  datasourceProblemOf,
+  renderDatasource,
+} from './datasource-file.mjs';
 
 export async function sync({ root }) {
   const manifestPath = join(root, 'package.json');
@@ -23,29 +25,44 @@ export async function sync({ root }) {
   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}: 清单里没有工具，不用生成物`);
+  const design = readDesign(root);
+  const entries = datasourceEntriesOf(design);
+  if (tools.length === 0 && entries.length === 0) {
+    console.log(`${unit}: 清单里没有工具、design.json 里也没有带 key 的配方，不用生成物`);
     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`；生成物按清单生成它，代码里引用工具名就写它、不写字面量）',
+  if (tools.length > 0) {
+    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`；生成物按清单生成它，代码里引用工具名就写它、不写字面量）',
+      );
+    }
+
+    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 ? ' —— 原来那份和清单对不上，已刷新' : ''),
     );
   }
 
-  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 ? ' —— 原来那份和清单对不上，已刷新' : ''),
-  );
+  if (entries.length > 0) {
+    const at = join(root, DATASOURCE_FILE);
+    const had = existsSync(at);
+    const stale = datasourceProblemOf(root, design);
+    writeFileSync(at, renderDatasource(design));
+    console.log(
+      `${unit}: 写了 ${DATASOURCE_FILE}（${entries.length} 条配方，按 design.json 生成）` +
+        (had && stale !== undefined ? ' —— 原来那份和底稿对不上，已刷新' : ''),
+    );
+  }
 }

package/template/AGENTS.md.tpl

@@ -0,0 +1,33 @@
+# __NAME__ · agent 工作说明
+
+这个包是工作台模块（单元 `__UNIT__`）。`README.md` 讲模块本身；这份讲 agent 在这份代码里怎么干活。
+
+## 命令
+
+```bash
+pnpm install
+pnpm build        # dist/host.js + client.js
+pnpm typecheck
+pnpm test
+pnpm selfcheck
+pnpm check        # 十三条模块判据
+pnpm lint
+pnpm design check
+```
+
+发布（维护者确认之后）：
+
+```bash
+dsh-wb-module release --target team|public|tarball|git
+```
+
+`--dry-run` 只预览，`--verify` 只核已发布的包。
+
+## 不要
+
+- 手改 `client.js` / `dist/**`：构建产物，改 `src/**` 后重新 build。
+
+## 先读
+
+- `README.md`：模块行为与数据源。
+- 工作台模块指引：`@dsh-workbench/core/skills/workbench-module-diy/`（dsh / 工作台的约束随外壳出货）。

package/template/CHANGELOG.md.tpl

@@ -0,0 +1,7 @@
+# 更新日志
+
+## v0.1.0
+
+### ✨ 新增
+
+- 第一个版本

package/template/README.md.tpl

@@ -19,39 +19,12 @@ pnpm check        # dsh-wb-module check
 pnpm lint         # dsh-wb-module lint（`--fix` 就地改文件；`check` 永不动手）
 ```
 
-形状是**分层多文件**：`src/components/HelloCard.tsx` 是这张卡（卡壳 + 两句正文），
-`src/client.tsx` 只剩面（注册 + 把 props 交给组件），`src/host.ts` 是宿主面，
-`src/messages.ts` 是文案。目录**按需要出现** —— 这份没有纯逻辑，所以没有 `src/model/`；
-一旦有了（换算 / 状态机 / 类型），就放 `src/model/**` 并配一份同目录测试。
-两个面在第 10 层、`components/` 第 2 层、`model/` 与 `messages.ts` 第 1 层：
-上层只许 import 下层的，`arch.config.mjs` 那份方言 + `check` 的 `arch` 判据会当场报
-（宿主侧 import `components/**` 是跨运行时，也红）。
+形状：`src/components/HelloCard.tsx` 是卡片，`src/client.tsx` 只注册，`src/host.ts` 是宿主面，
+`src/messages.ts` 是文案；有纯逻辑就放 `src/model/**` 并配一份同目录测试。
 
-包根还有两份**只有两行**的方言配置，各自一条判据按"文件在不在"上车：
-`arch.config.mjs`（`moduleArch()`：层序 / 反向依赖 / 跨运行时）与
-`eslint.config.mjs`（`moduleLint()`：`console` / `as any` / hooks 那几条 / 手搓颜色字面量）；
-要开口子都从工厂参数进，别手写一份自己的配置。
+## 开发与发布
 
-装进本地工作台：
+开发命令见上面的六个脚本；dsh / 工作台的模块约束见工作台模块指引（随外壳出货）；agent 的工作说明见 `AGENTS.md`。
 
-```bash
-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.json` 里的 `private` 去掉，并显式写上发布目标
-（`publishConfig.access: "public"` 或指向内网源的 `publishConfig.registry`）——
-`private: true` 的包不许发到任何源，这是刻意的默认。
+发布（维护者确认之后）：`dsh-wb-module release --target team|public|tarball|git`；
+`--dry-run` 只预览，`--verify` 只核已发布的包。

package/template/package.json.tpl

@@ -8,7 +8,7 @@
     ".": "./dist/host.js",
     "./client": "./client.js"
   },
-  "files": ["dist", "client.js", "cordis.patch.yml"],
+  "files": ["dist", "client.js", "cordis.patch.yml", "CHANGELOG.md"],
   "scripts": {
     "build": "dsh-wb-module build",
     "typecheck": "tsc --noEmit",
@@ -26,7 +26,7 @@
       "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
     },
     "workbench": {
-      "apiVersion": 1,
+      "apiVersion": 2,
       "unit": "__UNIT__",
       "card": { "titleKey": "__UNIT__.cardTitle", "order": 90 },
       "tools": [],

package/template/src/client.tsx.tpl

@@ -1,26 +1,9 @@
-import type { ReactElement } from 'react';
+import type { ClientContext, UnitClientApi, UnitClientFace } from '@dsh-workbench/core/contract';
 import { HelloCard } from './components/HelloCard';
 import { messages } from './messages';
 
 const UNIT_ID = '__UNIT__';
 
-type Translate = (key: string, params?: Record<string, unknown>) => string;
-
-interface UnitClientFace {
-  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 }) => ReactElement;
-}
-
-interface UnitClientApi {
-  registerUnit(face: UnitClientFace): () => void;
-}
-
-interface ClientContext {
-  get<T = unknown>(name: string): T | undefined;
-  effect(effect: () => void | (() => void), label?: string): () => void;
-}
-
 const face: UnitClientFace = {
   unit: UNIT_ID,
   messages,

package/template/src/host.ts.tpl

@@ -1,24 +1,11 @@
+import type { HostContext, UnitModuleFace, UnitRegistry } from '@dsh-workbench/core/contract';
+
 const UNIT_ID = '__UNIT__';
 
 export const name = '__NAME__';
 
 export const inject = ['workbenchUnits'];
 
-interface UnitModuleFace {
-  readonly unit: string;
-  mount(): { routes: Record<string, never>; registerTools(): Array<() => void> };
-}
-
-interface UnitRegistry {
-  register(face: UnitModuleFace): () => void;
-}
-
-interface HostContext {
-  get<T = unknown>(name: string): T | undefined;
-  effect(effect: () => void | (() => void), label?: string): () => void;
-  logger?: { warn?(message: string): void } | undefined;
-}
-
 const face: UnitModuleFace = {
   unit: UNIT_ID,
   mount: () => ({ routes: {}, registerTools: () => [] }),

package/template/types/globals.d.ts

@@ -1,16 +1,3 @@
-/**
- * 浏览器半侧的运行时垫片。
- *
- * dsh 的客户端模块格式是 `window.__ModuleLoader__.load({ id, factory(require) })`，
- * 所以 `require` 不来自模块系统，而是宿主给的作用域。
- */
-
-/**
- * React 19 的 `@types/react` 移除了全局 `JSX` 命名空间，而本工程用的是
- * **经典 JSX 运行时**（`jsxFactory: "h"`）：`react/jsx-runtime` 不在浏览器模块表里，
- * 所以不能切到自动运行时。这里把全局命名空间接到 `React.JSX` 上 —— 这是官方迁移说明
- * 给经典运行时的做法，写完 JSX 就有完整类型，产出仍是 `h(...)`。
- */
 import type * as ReactTypes from 'react';
 
 declare global {
@@ -18,7 +5,7 @@ declare global {
     interface Element extends ReactTypes.JSX.Element {}
     interface ElementClass extends ReactTypes.JSX.ElementClass {}
     interface IntrinsicElements extends ReactTypes.JSX.IntrinsicElements {}
-    /** 有了它，返回 ReactNode 的组件（含 Fragment）才合法 —— React 19 的类型靠这条判断。 */
+
     type ElementType = ReactTypes.JSX.ElementType;
     interface IntrinsicAttributes extends ReactTypes.JSX.IntrinsicAttributes {}
     interface ElementAttributesProperty extends ReactTypes.JSX.ElementAttributesProperty {}

package/template-diy/AGENTS.md.tpl

@@ -0,0 +1,33 @@
+# __NAME__ · agent 工作说明
+
+这个包是工作台模块（单元 `__UNIT__`）。`README.md` 讲模块本身；这份讲 agent 在这份代码里怎么干活。
+
+## 命令
+
+```bash
+pnpm install
+pnpm build        # dist/host.js + client.js
+pnpm typecheck
+pnpm test
+pnpm selfcheck
+pnpm check        # 十三条模块判据
+pnpm lint
+pnpm design check
+```
+
+发布（维护者确认之后）：
+
+```bash
+dsh-wb-module release --target team|public|tarball|git
+```
+
+`--dry-run` 只预览，`--verify` 只核已发布的包。
+
+## 不要
+
+- 手改 `client.js` / `dist/**`：构建产物，改 `src/**` 后重新 build。
+
+## 先读
+
+- `README.md`：模块行为与数据源。
+- 工作台模块指引：`@dsh-workbench/core/skills/workbench-module-diy/`（dsh / 工作台的约束随外壳出货）。

package/template-diy/CHANGELOG.md.tpl

@@ -0,0 +1,7 @@
+# 更新日志
+
+## v0.1.0
+
+### ✨ 新增
+
+- 第一个版本

package/template-diy/README.md.tpl

@@ -161,106 +161,6 @@ GET /api/__UNIT__/overview?path=<绝对路径>&limit=<1..50>
 卡片侧读数的 hook 是 `kit.hooks.useApiResource`（`route` 就是 `__UNIT__/overview`）。
 注意它的 `value` 是**整个响应对象**（成功时形如 `{ ok: true, ...payload }`），不是 `payload` 本身。
 
-## 这个模块会不会写东西、要不要跑一会儿、靠什么跑起来
-
-**这张卡只读** —— 上面那条 `/overview` 就是全部。要动手（提交、发布、批量改）就得再加两样，
-下面三段是**最小可抄的写法**；不需要的整段删掉，别留半截。
-
-### 会写：清单里标出来 + 认领审批
-
-> 每个工具都写一个 `key`（代码里那个短名，lowerCamelCase），然后 `dsh-wb-module sync` 生成
-> `src/declared-tools.ts`：代码写 `DECLARED_TOOLS.rebuild.name` —— 工具名的字面量只留在清单里。
-
-```ts
-tools: [{ name: 'workbench___UNIT___rebuild', writes: true, key: 'rebuild' }],
-
-needsApproval: (call) => ({
-  kind: 'ask',
-  reason: '会覆盖产物',
-  question: { zh: '要重建这 3 个模块吗？', en: 'Rebuild these 3 modules?' },
-  fallback: { zh: '会覆盖它们的 dist 与 client.js', en: 'Overwrites their dist and client.js' },
-}),
-
-approvalDetail: async (call) => ({ zh: '会覆盖 3 个模块的产物，不碰源码', en: '…' }),
-```
-
-清单写着 `writes: true` 而不认领，外壳**当场 deny**（用户看到的是一次莫名其妙的拒绝）——
-`dsh-wb-module check --only contracts` 会替你先把这条看一遍。用户侧看到的问话就是
-`question` + `approvalDetail` 合起来的那几行：**一行一个事实，别写"这个操作会写数据"这种空话。**
-
-### 跑一会儿：长任务
-
-```ts
-mount({ longTasks, ... }) {
-  const runs = longTasks?.create({
-    key: 'rebuild',
-    run: async ({ payload, onStep, signal }) => {
-      onStep({ kind: 'start', text: '开始…' });
-      // signal 被 abort = 有人按了停止（用户 / agent）：每一轮都看一眼 `signal.aborted`，能收手就收手
-      /* … */
-      return {};
-    },
-    outcome: (result) => ({ why: '…' }),
-    view: (snapshot) => ({ steps: String(snapshot.steps.length) }),
-  });
-  return { routes: {}, registerTools: () => [], ...(runs === undefined ? {} : { longTasks: runs }) };
-}
-```
-
-起这一趟的那把工具里（`execute(args, exec)` 拿得到现场）记下来源：
-
-```ts
-runs.start({ workspace, target, payload, session: sessionIdOf(exec) ?? undefined });
-```
-
-`sessionIdOf`（`@dsh-workbench/shared/host`）说这次调用是哪个会话发的。**不记来源 = 用户按的**
-（或这一版之前起的）—— 停它要走审批；外壳自带的那两把 `workbench_long_tasks_list` /
-`workbench_long_tasks_stop` 就是这么判"谁的"（自己起的免审批，别人的 / 用户按的要审批，
-不在当前工作区的直接拒绝）。
-
-浏览器侧用 kit 那套画（`kit.hooks.useLongTask` + `<LongTaskRow …/>`）：状态有五种 ——
-`running` 进行中 / `needs-login` 要登录 / `stopped` 停下的（用户按停）/ `ok` 完成 / `failed` 出错。
-
-要给用户那颗停止钮，就在卡片上给那一行的 `LongTaskRow` 传 `stop`
-（词与取值照 dsh 任务列表那行：aria `停止任务 {label}` → 上膛 → 可见字 `确认停止`、
-aria `再次点击确认停止`，3 秒落膛；**失败那半是我们自己的** —— 不往钮里写「停止失败」，
-而是把这次请求失败的原话画在那一行下面，`failed` 给什么画什么）；**要停就认 `signal`，不认就别画** ——
-画了就是骗人：外壳只会把这一趟标成 `stopped`，你的活儿还在跑（内部是 opencli 子进程那类编排，
-今天最多做到"我们不再等它"）。要用这个新 prop 就得装带这次改动的那份外壳 ——
-把自己 `peerDependencies['@dsh-workbench/core']` 的下限抬到那一版。
-
-### 存起来：他能自己配什么（`prefs`）
-
-选一次就想让它一直算数（钉哪个环境、忽略哪些、超时多久）→ 走 `prefs` 通道：**按项目记、刷新还在**。
-只是"这次看哪一种"→ 当 route 参数传，别落盘。两种都写进 `design.json` 的 `config[].persistence`
-（`prefs` / `view`）—— 表里写了 `prefs`，产物里就必须真的接上（`check --only contracts` 会拦）。
-
-宿主半侧在 `mount` 里返回（最好单独一个纯文件，像 `src/prefs.ts` 那样能单测）：
-
-```ts
-prefs: {
-  resource: 'your-module',
-  handle: (payload) => applyPref(deps.store.for(UNIT_ID, workspace), payload),
-}
-```
-
-浏览器半侧：`useHostWrite({ channel: 'prefs', resource: 'your-module' })` + `FormRows` / `FormRow` /
-`TextField`，外面套 `SettingsSection`，保存用 `SaveBar`；存失败留在原地。（标签、行距与输入框内边距都是
-外壳给的默认，不用为这个写 CSS。）语义：没写过 ≠ 选空、清空要把文件收掉、不认识的值报错并列出还认的候选。
-
-### 靠什么跑起来：`env`
-
-```ts
-env: {
-  command: 'opencli',
-  libs: [{ name: 'x-lib', registryEnv: 'DSH_WORKBENCH_X_REGISTRY', registryDefault: 'https://…/', purpose: '装它干嘛' }],
-  plugins: [{ name: 'x', commands: ['a', 'b'], installSource: { kind: 'npm', package: 'opencli-plugin-x', registryEnv: '…' } }],
-}
-```
-
-外壳的隔离运行时按它装、按它探（`workbench_modules_list` 里逐条看得到）。**没装好时用户看到的那句话
-由你写**：`libInstallCommand({ need })` 会连源和缓存目录一起拼好，原样给他，别自己拼 npm 命令。
-
 ## 卡片画哪五态
 
 `src/model/overview.ts` 的 `overviewStateOf({ phase, value, error })` 是一条纯函数，
@@ -279,38 +179,9 @@ env: {
 这时刻意继续画旧数据（右上角的转圈由 `Card` 的 `refreshing` 表示），不退回骨架：
 一次刷新不该让整张卡闪一下。
 
-## 装进本地工作台
+## 开发与发布
 
-```bash
-dsh plugin --profile workbench add <本目录>
-```
+开发命令见上面的六个脚本；dsh / 工作台的模块约束见工作台模块指引（随外壳出货）；agent 的工作说明见 `AGENTS.md`。
 
-## 改的时候这些是硬约束
-
-* **只用 kit 里真有的成员**：`check:kit` 拿产物实际取的成员去对 peer 下限那份外壳的 kit，
-  取了旧外壳没有的成员会在用户机器上首帧渲染就炸（peer 下限因此不许比 devDependency 旧）。
-* **两个运行时不许互引**：宿主侧不许碰 DOM / react，浏览器侧不许碰 `node:` / `process.env` / `Buffer`
-  （`check:bundles` 对着产物查）。所以目录读在 `src/host.ts`，卡片只管画。
-  跨运行时那一条**层号拦不住**（`components/` 第 2 层、`host.ts` 第 10 层，"向下依赖"看着合法）——
-  是 `arch` 判据按面判的：`src/components/**` 整片算 client 面，宿主侧 import 它当场红。
-* **层序**：`src/model/**`（纯逻辑，第 1 层）谁都能读，但它**不碰** react / kit / dsh / `node:*`；
-  视图在 `src/components/**`（第 2 层），只许 import 第 1 层；两个面在第 10 层。
-  要加一层就在 `arch.config.mjs` 里明写（`moduleArch({ layers: … })`）—— 多出来的目录默认是 S01 红。
-* **语法卫生**（第十三条）：`eslint.config.mjs` 那份方言管 `console.log` / `as any` / 手搓颜色字面量 /
-  `!important` / hooks 那几条（`rules-of-hooks`、渲染期写 ref、漏依赖是 **error**，其余 recommended 是 **warn**）。
-  `check` 把 error 算红、`warn` 只计数；要动手就先 `dsh-wb-module lint --fix`（`check` 一个字节都不改）。
-  个别地方真要破例就在 `eslint.config.mjs` 里 `moduleLint({ rules })` 开口子，别悄悄换成手写配置
-  （判据按方言指纹认它）。
-* `@/` 只许指自己（`@/modules/__UNIT__/*`）；共享代码走包名；`@deepseek-ai/dsh-*` 只在客户端侧用，
-  且必须同时写进 `package.json` 的 `dsh.client.external`。
-* **自己的样式走 CSS Modules**（`src/x.module.css` + `import styles from './x.module.css'`）：
-  类名照常写就行 —— 构建会**按文件路径哈希**（跨模块不会撞），但**别带 `wb-` 前缀**：
-  `wb-*` 是外壳的全局类名，模块定义它、或借契约里没有的那一个，`check:style` 都会判红。
-  要借外壳契约里的类，写 `:global(.wb-…)`，而且那个类必须在契约里。
-  这份骨架带了一份最小的 `src/components/OverviewCard.module.css`（就一档列间距），
-  演示"样式与组件同目录"；`types/styles.d.ts` 是它给 `tsc` 的类名表声明（少了它 `styles.largest` 直接红）。
-* **源码零注释**（`src/**`）：要说的都写在这里。
-
-要发布：把 `package.json` 里的 `private` 去掉，并显式写上发布目标
-（`publishConfig.access: "public"` 或指向内网源的 `publishConfig.registry`）——
-`private: true` 的包不许发到任何源，这是刻意的默认。
+发布（维护者确认之后）：`dsh-wb-module release --target team|public|tarball|git`；
+`--dry-run` 只预览，`--verify` 只核已发布的包。

package/template-diy/package.json.tpl

@@ -8,7 +8,7 @@
     ".": "./dist/host.js",
     "./client": "./client.js"
   },
-  "files": ["dist", "client.js", "cordis.patch.yml"],
+  "files": ["dist", "client.js", "cordis.patch.yml", "CHANGELOG.md"],
   "scripts": {
     "build": "dsh-wb-module build",
     "typecheck": "tsc --noEmit",
@@ -27,7 +27,7 @@
       "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
     },
     "workbench": {
-      "apiVersion": 1,
+      "apiVersion": 2,
       "unit": "__UNIT__",
       "card": { "titleKey": "__UNIT__.cardTitle", "order": 90 },
       "tools": [],

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

@@ -1,37 +1,9 @@
-import type { ReactElement } from 'react';
+import type { ClientContext, UnitClientApi, UnitClientFace } from '@dsh-workbench/core/contract';
 import { OverviewCard } from './components/OverviewCard';
 import { messages } from './messages';
 
 const UNIT_ID = '__UNIT__';
 
-type Translate = (key: string, params?: Record<string, unknown>) => string;
-
-interface WorkspaceView {
-  readonly path: string;
-}
-
-interface BoardProps {
-  readonly world: { readonly current: { readonly workspace?: WorkspaceView | null } };
-  readonly refreshToken: number;
-  readonly onRefresh: () => void;
-  readonly t: Translate;
-}
-
-interface UnitClientFace {
-  readonly unit: string;
-  readonly messages: { readonly zh: Readonly<Record<string, string>>; readonly en: Readonly<Record<string, string>> };
-  readonly card: (props: BoardProps) => ReactElement;
-}
-
-interface UnitClientApi {
-  registerUnit(face: UnitClientFace): () => void;
-}
-
-interface ClientContext {
-  get<T = unknown>(name: string): T | undefined;
-  effect(effect: () => void | (() => void), label?: string): () => void;
-}
-
 const face: UnitClientFace = {
   unit: UNIT_ID,
   messages,