@dsh-workbench/module-tools 1.2.7 → 1.2.8-beta.1

package/README.md

@@ -9,7 +9,7 @@
 pnpm exec dsh-wb-module init my-unit                    # 建骨架（唯一模板，已默认）
 pnpm build        # dist/host.js + 套了 loader 壳的 client.js
 pnpm check        # 十四条判据
-pnpm design check # 设计底稿有没有空格、README 有没有落后
+pnpm design check # 设计底稿有没有空格、readme.json / README / DEVELOPING 有没有落后
 ```
 
 要发货再加一步 `pnpm exec dsh-wb-module publish`：跑门禁、核 `files` 与 `npm pack` 清单，默认 **只 dry run，不真发**。
@@ -55,7 +55,7 @@ pnpm design check # 设计底稿有没有空格、README 有没有落后
 | `dsh-wb-module check [--only <判据>] [--package <包名或 unit>]` | 十四条判据；`--only` 单跑，也当查询口用；`--package` 只报这个模块的问题（见下）；`--list [--json\|--markdown]` 只列判据元数据 |
 | `dsh-wb-module lint [--fix]` | 用模块自己那份 `eslint.config.mjs`；`--fix` 写回文件 |
 | `dsh-wb-module sync` | 按清单生成 `src/declared-tools.ts`，按 `design.json` 的 `key + recipe` 生成 `src/datasource.ts` |
-| `dsh-wb-module design <init\|check\|render\|accept>` | 设计底稿：填、查空格、生成 README、验收打勾 |
+| `dsh-wb-module design <init\|migrate\|check\|render\|accept>` | 设计底稿：填、拆旧 README、查空格、生成 README 与 DEVELOPING、验收打勾 |
 | `dsh-wb-module migrate [--dry-run]` | 把模块清单迁到当前代：`apiVersion` → 3、缺/空的 `workbenchFaces` 补默认；源码类问题只给提示（check 会点名） |
 | `dsh-wb-module changelog check [版本]` | 查这一版有没有记录；发布时用 `release --changelog-note` 写进去 |
 | `dsh-wb-module publish` | 发货前清单：门禁 + `files` + `npm pack`（只 dry run） |
@@ -196,10 +196,12 @@ export default [
 `dsh-wb-module lint --fix` 先写回再跑一遍看还剩什么。**`check` 永远不动手改文件** ——
 门禁是判据，不是修复器。
 
+模板生成三份文档：`readme.json` 是终端用户文案源（标题、简介、卡片布局草图 `shots[]`、会看到什么、能做什么、agent 能做什么、数据从哪来、排障、FAQ，后五段是短条目），`README.md` 只由它生成；`DEVELOPING.md` 是作者文档（实现、路由、判据、数据源与三张表），由 `design.json` 生成。`design render` 刷新这两份；`design check` 会拦住空文案、占位符和技术词；旧模块先跑 `design migrate`，它把旧 `README.md` 原样保存为 `DEVELOPING.md`，再生成 `readme.json` 与用户 README。
+
 ## `design.json`：三张表
 
 面板 / 能力 / 联动三张表、状态矩阵、数据源记录、写通道记录、验收清单都住在模块根目录的
-`design.json`，README 里那一段由它生成（夹在 `<!-- dsh-wb:design:start/end -->` 之间）。
+`design.json`，DEVELOPING.md 里那一段由它生成（夹在 `<!-- dsh-wb:design:start/end -->` 之间）。README.md 的用户文案不看 design.json，只看模块根的 `readme.json`。
 
 它是**设计底稿**：三张表与探明记录装人话（`oneLine` / `shape` / `approvalText` / 三张表的文字）；
 读源那一条可以多带 `key` 与 `recipe` 两个机器字段 —— 它们只用于生成 `src/datasource.ts`，
@@ -208,7 +210,7 @@ export default [
 `design.json` 的模块不查。
 
 有写能力的模块另在 `writes[]` 里落命令 / 入参 / 出参 / 预览档 / 回读 / 失败形状，
-渲染成 README 里的「写通道探明记录」。没有写通道就不用写，不会因此变红。
+渲染成 DEVELOPING.md 里的「写通道探明记录」。没有写通道就不用写，不会因此变红。
 写也能落配方：`writes[]` 里加一对 `key` + `recipe`，`sync` 把它和读一起生成进
 `DATASOURCE`（`data.submit(DATASOURCE.<key>)`）；配方盖不住的写写 `custom: { why }`（warn）。
 
@@ -262,8 +264,8 @@ export default [
 - 形状与六种配方见模块 DIY 的 [`DATASOURCE.md`](../core/skills/workbench-module-diy/DATASOURCE.md)。
 
 ```bash
-dsh-wb-module design check    # 空着的格一格格点名叫出来 + README 有没有落后
-dsh-wb-module design render   # 用 design.json 重新生成 README 那一段
+dsh-wb-module design check    # 空着的格一格格点名叫出来 + README / DEVELOPING 有没有落后
+dsh-wb-module design render   # 用 readme.json 重新生成 README，用 design.json 刷新 DEVELOPING 那一段
 dsh-wb-module design accept   # 在真卡片上逐条走通后打勾
 ```
 
@@ -325,7 +327,7 @@ dsh-wb-module design accept   # 在真卡片上逐条走通后打勾
 `eslint.config.mjs`。
 
 `init` 连模板里的 `*.tpl` 一起拷、按已知 token 名逐个盖章（`__UNIT__` / `__NAME__` / `__DESC__` /
-`__SHELL_RANGE__` / `__DSH_UI_VERSION__`）、剥掉后缀，再用 `design.json` 生成 README 那一段。
+`__SHELL_RANGE__` / `__DSH_UI_VERSION__`）、剥掉后缀，再用 `readme.json` 生成 README、用 `design.json` 生成 DEVELOPING 那一段。
 `__SHELL_RANGE__` 取 init 所在工程实装的那份外壳版本；读不到就退回 module-tools 自己的版本；
 两者都读不到才保持 `^0.1.0` 并在 stderr 上说一句。
 
@@ -336,7 +338,7 @@ node scripts/selfcheck/index.mjs
 ```
 
 工具箱的回归网：模板 `init` 一遍、跑全套；判据的正例与负例都要对；打包清单不含
-`.tpl` 残留；`design` 的空格、README 同步、`accept`；`publish` 的清单；`release` 的验收闸、
+`.tpl` 残留；`design` 的空格、README / DEVELOPING 同步、`accept`；`publish` 的清单；`release` 的验收闸、
 dry-run、真发后的元数据与发布失败回滚。
 
 ## 相关文档

package/bin/dsh-wb-module.mjs

@@ -105,7 +105,7 @@ const COMMANDS = {
   check: '十四条判据；--only 单跑，也当查询口用；--list 只列判据元数据',
   init: '建模块骨架（--dir / --template diy / --description；只有 diy 一个模板）',
   'market-init': '初始化市场索引仓库（写 market/ 与 README，推首个 commit）',
-  design: '设计底稿：init 填 / check 查空格 / render 生成 README / accept 打勾',
+  design: '设计底稿：init 填 / migrate 拆旧 README / check 查空格 / render 生成 README 与 DEVELOPING / accept 打勾',
   migrate: '把模块清单迁到当前代（apiVersion / workbenchFaces）；源码类问题只给提示',
   publish: '发货前清单：门禁 + files + npm pack（只 dry run）',
   release: '真发布：全门禁 + 验收闸 + 预检接管 + 发到出口 + 发后核包 + 更新市场索引（中断可 --resume）',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "1.2.7",
+  "version": "1.2.8-beta.1",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
     "semver": "^7.8.5",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.71.0",
-    "@dsh-workbench/shared": "1.2.7"
+    "@dsh-workbench/shared": "1.2.8-beta.1"
   },
   "repository": {
     "type": "git",

package/src/checks/contracts.mjs

@@ -727,7 +727,7 @@ export async function run() {
       for (const name0 of inDeclaration.filter((one) => !inDesign.includes(one))) {
         problems.push(
           `${name}: 清单的 tools[] 里声明了「${name0}」，design.json 的能力行里却没有它 —— ` +
-            '底稿是给人读的那半（它干嘛、要不要点头，`design render` 拿它出 README）：' +
+            '底稿是给人读的那半（它干嘛、要不要点头，`design render` 拿它出 DEVELOPING.md）：' +
             `要么在 design.json 的 capabilities[] 里为「${name0}」补一行，要么把它从清单里删掉`,
         );
       }

package/src/checks/source.mjs

@@ -218,7 +218,7 @@ export async function run() {
       const text = readFileSync(file, 'utf8');
       for (const line of commentViolationsOf(text, { css: file.endsWith('.css') })) {
         problems.push(
-          `${name}: ${rel}:${line} 有注释 —— 模块源码零注释（说明写 README.md 或 spec；eslint / ts / vitest 指令注释除外）`,
+          `${name}: ${rel}:${line} 有注释 —— 模块源码零注释（用户说明写 README.md，作者说明写 DEVELOPING.md 或 spec；eslint / ts / vitest 指令注释除外）`,
         );
       }
     }

package/src/design.mjs

@@ -1,8 +1,10 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { callsProblemOf, describeRecipe, recipeProblemOf } from '@dsh-workbench/shared/host';
 
 export const DESIGN_FILE = 'design.json';
+export const DEVELOPING_FILE = 'DEVELOPING.md';
+export const README_SOURCE_FILE = 'readme.json';
 export const START_MARK = '<!-- dsh-wb:design:start -->';
 export const END_MARK = '<!-- dsh-wb:design:end -->';
 
@@ -430,6 +432,184 @@ export function renderDesign(design) {
   ].join('\n');
 }
 
+function bodyLinesOf(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap((one) => {
+      const line = text(one);
+      return line === '' ? [] : [`- ${line}`];
+    });
+  }
+  const line = text(value);
+  return line === '' ? [] : [line];
+}
+
+function sectionOf(heading, value) {
+  const lines = bodyLinesOf(value);
+  return lines.length === 0 ? [] : [`## ${heading}`, '', ...lines, ''];
+}
+
+function shotsOf(source) {
+  const listed = Array.isArray(source?.shots) ? source.shots : [];
+  const single = text(source?.ascii) === '' ? [] : [{ caption: '', ascii: source.ascii }];
+  return [...single, ...listed].flatMap((one) => {
+    const drawing = typeof one?.ascii === 'string' ? one.ascii.replace(/\s+$/, '') : '';
+    if (drawing.trim() === '') return [];
+    return [{ caption: text(one?.caption), drawing }];
+  });
+}
+
+export function renderUserReadme(source) {
+  const title = text(source?.title) || '模块';
+  const summary = text(source?.summary);
+  const faq = asRows(source?.faq);
+  const install = text(source?.install) === ''
+    ? '在市场「已安装」里装或卸。装完在当前项目的面板里勾选这个模块，卡片才会出现；卸掉后卡片消失。'
+    : source?.install;
+  const shots = shotsOf(source);
+  const shotLines = shots.length === 0
+    ? []
+    : [
+        '## 卡片长这样',
+        '',
+        ...shots.flatMap((one) => [
+          ...(one.caption === '' ? [] : [`**${one.caption}**`, '']),
+          '```text',
+          one.drawing,
+          '```',
+          '',
+        ]),
+      ];
+  const faqLines = faq.length === 0
+    ? []
+    : [
+        '## 常见问题',
+        '',
+        ...faq.flatMap((one) => [`### ${text(one?.q)}`, '', text(one?.a), '']),
+      ];
+
+  return [
+    `# ${title}`,
+    '',
+    summary,
+    '',
+    ...shotLines,
+    ...sectionOf('你会看到什么', source?.see),
+    ...sectionOf('你能做什么', source?.do),
+    ...sectionOf('agent 能替你做什么', source?.agent),
+    ...sectionOf('数据从哪来', source?.data),
+    ...sectionOf('装和卸', install),
+    ...sectionOf('出问题先看', source?.trouble),
+    ...faqLines,
+  ].join('\n');
+}
+
+export function readUserSource(root) {
+  const file = join(root, README_SOURCE_FILE);
+  if (!existsSync(file)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
+  } catch (error) {
+    console.error(`✖ ${README_SOURCE_FILE} 不是合法 JSON：${error.message}`);
+    process.exit(1);
+  }
+}
+
+export function writeUserSource(root, value) {
+  writeFileSync(join(root, README_SOURCE_FILE), `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function manifestTitleOf(manifest) {
+  const title = manifest?.dsh?.workbench?.title;
+  if (typeof title === 'string' && title.trim() !== '') return title.trim();
+  if (title !== null && typeof title === 'object') {
+    const zh = text(title.zh);
+    if (zh !== '') return zh;
+    const en = text(title.en);
+    if (en !== '') return en;
+  }
+  return text(manifest?.name);
+}
+
+export function userSourceSkeleton(manifest, design) {
+  return {
+    title: manifestTitleOf(manifest) || text(design?.name) || '模块',
+    summary: text(design?.oneLine) || text(manifest?.description),
+    shots: [
+      {
+        caption: '（可选：图注，比如「卡片」「设置面」「审批」）',
+        ascii: '（待填：一张卡片布局草图，用界面真实文案，按屏幕从上到下的顺序画）',
+      },
+    ],
+    see: ['（待填：用户在卡片上看到的第一样东西）'],
+    do: ['（待填：用户自己能点的一个按钮或能改的一项设置）'],
+    agent: ['（待填：agent 能替用户做的一件事；写之前要不要批准）'],
+    data: ['（待填：数据从哪来、用谁的登录、读还是写）'],
+    install: '',
+    trouble: ['（待填：出问题时用户看到什么、下一步点哪）'],
+    faq: [],
+  };
+}
+
+const USER_COPY_FIELDS = ['title', 'summary', 'see', 'do', 'agent', 'data', 'trouble'];
+const USER_COPY_FORBIDDEN = [
+  ['反引号 / 代码片段', /`/],
+  ['代码块', /```/],
+  ['源码路径', /\bsrc\//],
+  ['设计底稿文件名', /\bdesign\.json\b/],
+  ['文案底稿文件名', /\breadme\.json\b/],
+  ['工具链命令', /\bdsh-wb-module\b/],
+  ['运行时名', /\bopencli\b/],
+  ['内部错误码', /\bauth-required\b|\bcli-[a-z-]+\b/],
+  ['客户端实现名', /\bapproval\.render\b/],
+  ['平台内部字段', /\bglobal_key\b/],
+];
+
+const BULLET_LIMIT = 70;
+
+function copyTextsOf(value) {
+  if (Array.isArray(value)) return value.map(text).filter((one) => one !== '');
+  const one = text(value);
+  return one === '' ? [] : [one];
+}
+
+export function userCopyProblemsOf(source) {
+  const problems = [];
+  if (source === undefined) return [`没有 ${README_SOURCE_FILE} —— 先跑 dsh-wb-module design init 或 design migrate`];
+  for (const field of USER_COPY_FIELDS) {
+    const values = copyTextsOf(source?.[field]);
+    if (values.length === 0) problems.push(`${field} 是空的 —— README 的「${field}」还没有用户文案`);
+    for (const value of values) {
+      if (value.includes('（待填')) problems.push(`${field} 还留着「（待填）」`);
+      if (Array.isArray(source?.[field]) && value.length > BULLET_LIMIT) {
+        problems.push(`${field} 有一条 ${String(value.length)} 字 —— 超过 ${String(BULLET_LIMIT)} 字就拆成两条，或者把细节放进图里`);
+      }
+    }
+  }
+  const shots = asRows(source?.shots);
+  if (shots.length === 0) problems.push('shots 是空的 —— 至少画一张卡片布局图');
+  for (const [index, one] of shots.entries()) {
+    if (text(one?.ascii).includes('（待填')) problems.push(`shots[${index}] 还留着「（待填）」`);
+  }
+  for (const field of ['title', 'summary', 'see', 'do', 'agent', 'data', 'install', 'trouble']) {
+    for (const value of copyTextsOf(source?.[field])) {
+      for (const [label, pattern] of USER_COPY_FORBIDDEN) {
+        if (pattern.test(value)) problems.push(`${field} 里有${label} —— 这段只给终端用户看`);
+      }
+    }
+  }
+  for (const [index, one] of asRows(source?.faq).entries()) {
+    if (text(one?.q) === '') problems.push(`faq[${index}].q 是空的`);
+    if (text(one?.a) === '') problems.push(`faq[${index}].a 是空的`);
+    for (const [label, pattern] of USER_COPY_FORBIDDEN) {
+      if (pattern.test(text(one?.q)) || pattern.test(text(one?.a))) {
+        problems.push(`faq[${index}] 里有${label} —— 这段只给终端用户看`);
+      }
+    }
+  }
+  return problems;
+}
+
 function regionOf(readme) {
   const start = readme.indexOf(START_MARK);
   const end = readme.indexOf(END_MARK);
@@ -437,11 +617,11 @@ function regionOf(readme) {
   return { start, end };
 }
 
-export function applyToReadme(root, markdown) {
-  const file = join(root, 'README.md');
+export function applyToDeveloping(root, markdown) {
+  const file = join(root, DEVELOPING_FILE);
   const block = `${START_MARK}\n${markdown}\n${END_MARK}`;
   if (!existsSync(file)) {
-    writeFileSync(file, `# ${text(manifestOf(root).name) || '模块'}\n\n${block}\n`);
+    writeFileSync(file, `# ${text(manifestOf(root).name) || '模块'} · 作者文档\n\n${block}\n`);
     return 'created';
   }
   const text0 = readFileSync(file, 'utf8');
@@ -464,6 +644,15 @@ export function applyToReadme(root, markdown) {
   return 'inserted';
 }
 
+export function writeUserReadme(root, source) {
+  const file = join(root, 'README.md');
+  const next = renderUserReadme(source);
+  const before = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (before === next) return 'same';
+  writeFileSync(file, next);
+  return before === '' ? 'created' : 'updated';
+}
+
 function manifestOf(root) {
   try {
     return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
@@ -484,9 +673,13 @@ function checkDesign(root) {
   const acceptance = asRows(design.acceptance);
   const accepted = acceptance.filter((one) => one?.checked === true).length;
 
-  const readme = existsSync(join(root, 'README.md')) ? readFileSync(join(root, 'README.md'), 'utf8') : '';
-  const at = regionOf(readme);
-  const fresh = at === undefined ? false : readme.slice(at.start, at.end) === `${START_MARK}\n${renderDesign(design)}\n`;
+  const developing = existsSync(join(root, DEVELOPING_FILE)) ? readFileSync(join(root, DEVELOPING_FILE), 'utf8') : '';
+  const at = regionOf(developing);
+  const fresh = at === undefined ? false : developing.slice(at.start, at.end) === `${START_MARK}\n${renderDesign(design)}\n`;
+  const source = readUserSource(root);
+  const copyProblems = userCopyProblemsOf(source);
+  const user = existsSync(join(root, 'README.md')) ? readFileSync(join(root, 'README.md'), 'utf8') : '';
+  const userFresh = source !== undefined && user === renderUserReadme(source);
 
   console.log(`design.json：面板 ${rows('panel')} 行 · 状态 ${STATE_KEYS.length} 态 · 配置 ${rows('config')} 项 · 能力 ${rows('capabilities')} 条 · 联动 ${rows('linkage')} 行 · 验收 ${accepted}/${acceptance.length}`);
   for (const one of warnings) console.log(`⚠ ${one}`);
@@ -494,13 +687,22 @@ function checkDesign(root) {
     console.error(`✖ 还空着 ${cells.length} 格（"空着的格就是还没定的事"，别带着空格往下做）：`);
     for (const one of cells) console.error(`  · ${one}`);
   }
-  if (!fresh) {
-    console.error('✖ README 里那一段落后于 design.json（或者没有标记）—— 跑 dsh-wb-module design render');
+  if (developing === '') {
+    console.error(`✖ 没有 ${DEVELOPING_FILE} —— 旧模块先跑 dsh-wb-module design migrate；新模块跑 design init`);
+  } else if (!fresh) {
+    console.error(`✖ ${DEVELOPING_FILE} 里那一段落后于 design.json（或者没有标记）—— 跑 dsh-wb-module design render`);
   }
-  if (cells.length === 0 && fresh) {
-    console.log(`✔ 三张表填全了，README 也是最新的${accepted === acceptance.length ? '，验收也打完了' : `；验收还差 ${acceptance.length - accepted} 条（自己在真卡片上逐条走通后跑 design accept）`}`);
+  if (copyProblems.length > 0) {
+    console.error(`✖ ${README_SOURCE_FILE} 还不能生成终端用户 README：`);
+    for (const one of copyProblems) console.error(`  · ${one}`);
   }
-  process.exit(cells.length === 0 && fresh ? 0 : 1);
+  if (!userFresh) {
+    console.error(`✖ README.md 落后于 ${README_SOURCE_FILE}（或还没生成用户说明）—— 跑 dsh-wb-module design render`);
+  }
+  if (cells.length === 0 && fresh && copyProblems.length === 0 && userFresh) {
+    console.log(`✔ 三张表填全了，README 与 ${DEVELOPING_FILE} 都是最新的${accepted === acceptance.length ? '，验收也打完了' : `；验收还差 ${acceptance.length - accepted} 条（自己在真卡片上逐条走通后跑 design accept）`}`);
+  }
+  process.exit(cells.length === 0 && fresh && copyProblems.length === 0 && userFresh ? 0 : 1);
 }
 
 export async function design({ root, args = [] }) {
@@ -511,12 +713,16 @@ export async function design({ root, args = [] }) {
       console.error(`✖ ${DESIGN_FILE} 已经在了；要重来先删掉它`);
       process.exit(1);
     }
-    const design0 = skeleton(manifestOf(root));
+    const manifest = manifestOf(root);
+    const design0 = skeleton(manifest);
     writeDesign(root, design0);
-    const how = applyToReadme(root, renderDesign(design0));
-    console.log(`✔ 写好 ${DESIGN_FILE}（三张表 + 状态矩阵 + 数据源记录 + 验收清单的空骨架）`);
-    console.log(`  README 的那一段：${how === 'created' ? '新建' : how === 'inserted' ? '插进「需求底稿」那一节' : '已更新'}`);
-    console.log('  接着把每一格填成"用户看得见的东西"，然后 dsh-wb-module design check');
+    const source = readUserSource(root) ?? userSourceSkeleton(manifest, design0);
+    writeUserSource(root, source);
+    const how = applyToDeveloping(root, renderDesign(design0));
+    writeUserReadme(root, source);
+    console.log(`✔ 写好 ${DESIGN_FILE} 与 ${README_SOURCE_FILE}（工程底稿 + 用户文案骨架）`);
+    console.log(`  ${DEVELOPING_FILE} 的那一段：${how === 'created' ? '新建' : how === 'inserted' ? '插进「需求底稿」那一节' : '已更新'}`);
+    console.log('  接着把两边的空格填成"用户看得见的东西"，然后 dsh-wb-module design check');
     return;
   }
 
@@ -526,8 +732,19 @@ export async function design({ root, args = [] }) {
       console.error(`✖ 没有 ${DESIGN_FILE} —— 先跑 dsh-wb-module design init`);
       process.exit(1);
     }
-    const how = applyToReadme(root, renderDesign(design0));
-    console.log(`✔ README 的那一段：${how === 'same' ? '本来就是最新的' : how === 'updated' ? '更新了' : how === 'inserted' ? '插进「需求底稿」那一节' : '建了 README'}`);
+    if (!existsSync(join(root, DEVELOPING_FILE))) {
+      console.error(`✖ 没有 ${DEVELOPING_FILE} —— 旧模块先跑 dsh-wb-module design migrate；新模块跑 design init`);
+      process.exit(1);
+    }
+    const source = readUserSource(root);
+    if (source === undefined) {
+      console.error(`✖ 没有 ${README_SOURCE_FILE} —— 旧模块先跑 dsh-wb-module design migrate；新模块跑 design init`);
+      process.exit(1);
+    }
+    const how = applyToDeveloping(root, renderDesign(design0));
+    const user = writeUserReadme(root, source);
+    console.log(`✔ ${DEVELOPING_FILE} 的那一段：${how === 'same' ? '本来就是最新的' : how === 'updated' ? '更新了' : how === 'inserted' ? '插进「需求底稿」那一节' : '已更新'}`);
+    console.log(`  README.md：${user === 'same' ? '本来就是最新的' : user === 'created' ? '新建' : '重生成'}`);
     return;
   }
 
@@ -545,16 +762,43 @@ export async function design({ root, args = [] }) {
     design0.acceptance = acceptance.map((one) => ({ ...one, checked: true }));
     design0.acceptedAt = new Date().toISOString();
     writeDesign(root, design0);
-    applyToReadme(root, renderDesign(design0));
+    applyToDeveloping(root, renderDesign(design0));
+    const source = readUserSource(root);
+    if (source !== undefined) writeUserReadme(root, source);
     console.log(`✔ ${acceptance.length} 条验收全部打勾（只在真的在真卡片上逐条走通过之后再跑这条）`);
     return;
   }
 
+  if (action === 'migrate') {
+    const design0 = readDesign(root);
+    if (design0 === undefined) {
+      console.error(`✖ 没有 ${DESIGN_FILE} —— 先跑 dsh-wb-module design init`);
+      process.exit(1);
+    }
+    if (existsSync(join(root, DEVELOPING_FILE))) {
+      console.error(`✖ ${DEVELOPING_FILE} 已经在了；拆过的模块不用再 migrate`);
+      process.exit(1);
+    }
+    const readmeFile = join(root, 'README.md');
+    if (existsSync(readmeFile)) {
+      copyFileSync(readmeFile, join(root, DEVELOPING_FILE));
+      console.log(`✔ 旧 README 已保存为 ${DEVELOPING_FILE}`);
+    }
+    const source = readUserSource(root) ?? userSourceSkeleton(manifestOf(root), design0);
+    writeUserSource(root, source);
+    const how = applyToDeveloping(root, renderDesign(design0));
+    const user = writeUserReadme(root, source);
+    console.log(`✔ ${DEVELOPING_FILE} 的那一段：${how === 'same' ? '本来就是最新的' : how === 'updated' ? '更新了' : '已更新'}`);
+    console.log(`✔ ${README_SOURCE_FILE} 与 README.md 已生成（${user === 'created' ? '新建' : '重生成'}）`);
+    console.log(`  接着把 ${README_SOURCE_FILE} 里的（待填）按终端用户视角填完，再 dsh-wb-module design check`);
+    return;
+  }
+
   if (action === 'check') {
     checkDesign(root);
     return;
   }
 
-  console.error(`不认识的 design 动作：${action}（可用：init / check / render / accept）`);
+  console.error(`不认识的 design 动作：${action}（可用：init / migrate / check / render / accept）`);
   process.exit(2);
 }

package/src/init.mjs

@@ -1,5 +1,5 @@
 import { cpSync, existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { DESIGN_FILE, applyToReadme, readDesign, renderDesign } from './design.mjs';
+import { DESIGN_FILE, applyToDeveloping, readDesign, readUserSource, renderDesign, writeUserReadme } from './design.mjs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -109,10 +109,14 @@ export async function init({ root, args = [] }) {
   };
   walk(target);
   const declared = readDesign(target);
-  if (declared !== undefined) applyToReadme(target, renderDesign(declared));
+  if (declared !== undefined) {
+    applyToDeveloping(target, renderDesign(declared));
+    const source = readUserSource(target);
+    if (source !== undefined) writeUserReadme(target, source);
+  }
   const tables = existsSync(join(target, DESIGN_FILE)) ? `${DESIGN_FILE} 里那份三张表` : '还没有三张表（dsh-wb-module design init 生成）';
   console.log(`${target} 建好了：${unit} 模块骨架（模板 ${which}；build / check / design / selfcheck 已接工具）`);
-  console.log(`  需求底稿在 ${tables}；空格用 dsh-wb-module design check 查，README 由它生成`);
+  console.log(`  需求底稿在 ${tables}；空格用 dsh-wb-module design check 查，readme.json 出用户 README，design.json 出 DEVELOPING.md`);
   console.log(`  模板默认带了 ${DSH_UI}@${dshUi.version}（${dshUi.source}）—— 这是 dsh 原语的类型面 + external 声明两处；`);
   console.log('  确实用不到就连 devDependencies 与 dsh.client.external 两处一起删，判据不拦。');
 }

package/src/release-journal.mjs

@@ -7,10 +7,12 @@ import { workbenchRootOf } from './release-util.mjs';
 const FINGERPRINT_FILES = [
   'package.json',
   'design.json',
+  'readme.json',
   'dist/host.js',
   'client.js',
   'cordis.patch.yml',
   'README.md',
+  'DEVELOPING.md',
   'CHANGELOG.md',
 ];
 

package/src/release-target.mjs

@@ -229,7 +229,7 @@ function gitInfoOf(root, manifest, args, exec) {
   });
   if (status.status !== 0) throw new ReleaseError(`读不了 git 状态：${tailOf(status.stderr)}`);
   const prefix = packagePath === '.' ? '' : `${packagePath}/`;
-  const allowed = ['dist', 'client.js', 'cordis.patch.yml', 'package.json', 'README.md', 'CHANGELOG.md', 'design.json'];
+  const allowed = ['dist', 'client.js', 'cordis.patch.yml', 'package.json', 'README.md', 'DEVELOPING.md', 'CHANGELOG.md', 'design.json', 'readme.json'];
   const dirty = status.stdout
     .trim()
     .split('\n')

package/src/release.mjs

@@ -139,7 +139,7 @@ function runGate(exec, root, options) {
 
 function gitPathsOf(info) {
   const prefix = info.packagePath === '.' ? '' : `${info.packagePath}/`;
-  return ['dist', 'client.js', 'cordis.patch.yml', 'package.json', 'README.md', 'CHANGELOG.md', 'design.json']
+  return ['dist', 'client.js', 'cordis.patch.yml', 'package.json', 'README.md', 'DEVELOPING.md', 'CHANGELOG.md', 'design.json', 'readme.json']
     .map((one) => `${prefix}${one}`)
     .filter((one) => existsSync(join(info.toplevel, one)));
 }

package/template-diy/AGENTS.md.tpl

@@ -1,6 +1,6 @@
 # __NAME__ · agent 工作说明
 
-工作台模块（单元 `__UNIT__`）。模块行为与数据看 `README.md`；这份只说工具链怎么用。
+工作台模块（单元 `__UNIT__`）。终端用户说明在 `README.md`（文案源 `readme.json`）；实现、数据源、设计底稿在 `DEVELOPING.md`；这份只说工具链怎么用。
 
 ## 干活循环
 
@@ -11,7 +11,7 @@
    **全绿**才算这件活做完。怎么读红、常见红：`@dsh-workbench/core/skills/workbench-module-diy/REVIEW.md`。
 3. `pnpm test` —— `src/**/__tests__/` 下、与改动同目录的 `*.test.ts`；新逻辑配对应用例，**全绿**才算完。
 
-`pnpm selfcheck` = build + `design check` + smoke；`design.json` 里的（待填）填完才绿。
+`pnpm selfcheck` = build + `design check` + smoke；`design.json` 与 `readme.json` 里的（待填）填完才绿。
 
 ## 工具链约定
 
@@ -21,5 +21,7 @@
 
 ## 先读
 
-- `README.md`：模块行为、数据源、三张表。
+- `readme.json`：终端用户文案源（标题、简介、会看到什么、能做什么、agent 能做什么、数据从哪来、排障、FAQ）。
+- `README.md`：由 `readme.json` 生成，不要手改。
+- `DEVELOPING.md`：实现、路由、判据、数据源与三张表。
 - `@dsh-workbench/core/skills/workbench-module-diy/`：路由 / 工具 / 卡片 / 文案的写法与约定（随外壳出货）。

package/template-diy/DEVELOPING.md.tpl

@@ -0,0 +1,185 @@
+# __NAME__ · 作者文档
+
+终端用户看 [README.md](README.md)（文案源 `readme.json`）；这份讲实现、路由、判据和设计底稿。
+
+`__UNIT__` 模块：一个独立的 dsh 插件包，只认外壳的服务名，不认识外壳源码。
+
+这份是 **唯一模板**（`--template diy`，也是默认）生成的骨架：一张**读当前项目目录的只读卡**，
+数据从宿主侧**真读**一个目录算出来（`node:fs`），另带一条**能跑**的流程 / 长任务 / 真工具 /
+动作通道样板；不是一个写死的样板。
+
+```bash
+dsh-wb-module init <unit> --dir <目录>              # 生成这份骨架（只有这一个模板）
+dsh-wb-module build     # 出 dist/host.js 与套了 loader 壳的 client.js
+dsh-wb-module check     # 十四条判据：契约 / 声明协议 / 产物边界 / 源码边界 / 执行缝 / 架构 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳 / 代码卫生（eslint）
+dsh-wb-module check --only cards   # 十四条可以单跑
+```
+
+包自带的六个脚本（`build` / `typecheck` / `test` / `selfcheck` 是 `check` 的契约判据要求的那四个；`check` 跑全部判据，`lint` 只跑源码卫生那一条）：
+
+```bash
+pnpm build        # 构建产物
+pnpm typecheck    # tsc --noEmit
+pnpm test         # vitest：路由真读数 + 卡片五态 + 长任务/工具契约
+pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍 + 真跑一趟流程 + 走 scripts/smoke.assert.mjs
+pnpm check        # dsh-wb-module check
+pnpm lint         # dsh-wb-module lint（`--fix` 就地改文件；`check` 永不动手）
+```
+
+## 需求底稿（做之前填，做完自己逐条走一遍）
+
+三张表既是**要问清的需求**，也是**最后的验收单** —— 表里每一格 agent 都要在真卡片上见过或点过。
+**空着的格就是还没定的事**，别带着空格往下做：落点是同目录的 `design.json`
+（`dsh-wb-module design check` 会把空格一格一格列出来），**下面标了 start/end 的那一段就是由它生成的**
+—— 要改三张表就改 `design.json`，再 `dsh-wb-module design render`；手改那一段会被 next 一次 check 判红。
+所以下次他说"改一下"不用从头问。
+
+**非生成段（这一节与下文）不会被 render 覆盖**：需求变了要自己改这里，`design render` 只管标记之间那一段。
+
+怎么问、怎么填：指引 `SKILL.md` 的七步 · `DESIGN.md`（判域 / 两条分工 / 三张表）·
+`STEPS.md`（每步问什么、什么时候算做完）· `PANEL.md` · `TOOLS.md` · `LINKAGE.md`。
+
+<!-- dsh-wb:design:start -->
+（这一段由 `design.json` 生成：改需求改 `design.json`，再 `dsh-wb-module design render`；手改会被下一次 check 判红。）
+<!-- dsh-wb:design:end -->
+
+## 生成出来的形状
+
+**分层多文件**，不是单文件：数字越小越底层，上层只许 import 下层的（`arch.config.mjs` 那条
+`arch` 判据盯着，`dsh-wb-module check` 会跑）。目录**按需要出现**：这份有状态逻辑，所以有 `model/`。
+宿主侧的辅助实现放 `src/host/`（`moduleArch()` 默认就认这一层；
+`src/host.ts` 仍是对外的宿主面，两个面只认 `dsh.workbenchFaces` 里那两个文件）。
+
+| 文件 | 是什么 | 层 |
+|---|---|---|
+| `package.json` | 自述清单：`dsh.workbench.unit` = `__UNIT__`、两个面（`src/host.ts` / `src/client.tsx`）、八个脚本、peer 下限 | — |
+| `arch.config.mjs` | 本模块的架构方言：`moduleArch()`（`src/host/**` 默认在层序里）—— 层序表 / 两个运行时 / 阈值只有 `@dsh-workbench/module-tools/arch` 那一份，随工具链同代 | — |
+| `eslint.config.mjs` | 本模块的**语法卫生方言**，同样两行：`moduleLint()` —— 规则表只有 `@dsh-workbench/module-tools/lint` 那一份（`console` / `as any` / hooks 那几条 / 手搓颜色与 `!important`）；要开口子就 `moduleLint({ rules })` | — |
+| `cordis.patch.yml` | 插进 dsh 组合的补丁 | — |
+| `design.json` | 三张表 + 状态矩阵 + 数据源记录 + 验收清单（**唯一真相**，上面那段由它生成；`dsh-wb-module design check/render/accept` 读写它） | — |
+| `src/model/overview.ts` | 纯逻辑：类型 + 五态状态机 + `formatBytes`。两个运行时都读得到，不碰 react / kit / dsh / `node:*` | 1 |
+| `src/model/__tests__/overview.test.ts` | 模型层的配对测试（有 `src/model/**` 就必须有 —— `arch` 的 M08） | 99 |
+| `src/model/flow.ts` | 样板流程的纯逻辑：`FlowDefinition` + 五态标题 / 是否还在跑；不碰宿主 | 1 |
+| `src/model/__tests__/flow.test.ts` | 流程模型的配对测试 | 99 |
+| `src/model/notes.ts` | 笔记的纯逻辑：校验 / 读回 / 最多 20 条 | 1 |
+| `src/model/__tests__/notes.test.ts` | 笔记模型的配对测试 | 99 |
+| `src/model/prefs.ts` | 配置的纯逻辑：按工作区存 `limit`（1..50），坏值回默认 | 1 |
+| `src/model/__tests__/prefs.test.ts` | 配置模型的配对测试 | 99 |
+| `src/messages.ts` | 卡片那几句文案（zh / en），键带 `<unit>.` 前缀 | 1 |
+| `src/declared-tools.ts` | 清单里工具名的生成物（`dsh-wb-module sync` 写；代码只引 `DECLARED_TOOLS.run.name` / `DECLARED_TOOLS.addNote.name`，不写字面量） | 1 |
+| `src/components/OverviewCard.tsx` | 卡片：`Card` 壳 + 五态 + 最大的几个文件 + 长任务行 + 笔记（写）/「显示几个」配置 | 2 |
+| `src/components/OverviewBody.tsx` | 五态各自那一屏（待机 / 加载 / 就绪 / 空 / 出错） | 2 |
+| `src/components/OverviewBody.module.css` | 就绪态「最大的几个文件」列表的布局 | 2 |
+| `src/components/RunSection.tsx` | 长任务那一块：跑流程的钮 + `LongTaskRow`（五态 / 停止） | 2 |
+| `src/components/NotesSection.tsx` | 笔记那一块：输入 + 存一条 + 列表 | 2 |
+| `src/components/PrefsSection.tsx` | 「最大的几个文件」配置（`SelectField`，按工作区存） | 2 |
+| `src/components/OverviewCard.module.css` | 这个组件自己的样式（CSS Modules，构建时类名按路径哈希）—— **样式跟组件同目录** | 2 |
+| `src/components/__tests__/OverviewCard.test.ts` | 这张卡五态各画得出来 + 写失败留在卡上（测试住同目录的 `__tests__/`）；流程 / 笔记 / 配置的接线由 `plugin.test.ts` 与 smoke 覆盖 | 99 |
+| `src/host.ts` | 宿主面：接线 + 三条只读路由（`overview` / `notes` / `prefs`）+ 挂工具 / 长任务 / 动作通道 / `prefs` / 审批口径 | 10 |
+| `src/host/overview.ts` | 宿主侧内部实现：`readOverview()`（真读目录）+ 路由回答 | 10 |
+| `src/host/sample.ts` | 宿主侧内部实现：样板流程的动作、长任务、只读工具 | 10 |
+| `src/host/notes.ts` | 宿主侧内部实现：笔记读写（`deps.store`）+ 写工具 + 动作通道 | 10 |
+| `src/client.tsx` | 浏览器面：**只剩面** —— 注册 + 把 props 交给 `components/OverviewCard` | 10 |
+| `src/__tests__/plugin.test.ts` | 面注册 + 路由真读 + 工具注册 + 流程真跑 + 笔记/配置/审批 | 99 |
+| `scripts/smoke.mjs` | 接线自检：卡片进没进外壳、工具注册、流程真跑、笔记真写、配置存得住；真读断言在 `smoke.assert.mjs` | — |
+| `scripts/smoke.assert.mjs` | **这个模块自己的**真读断言：换数据源时改这份，别删 smoke 里的调用 | — |
+| `CHANGELOG.md` | 版本记录（`dsh-wb-module release` 追加；`package.json.files` 里带它） | — |
+| `tsconfig.json` / `vitest.config.ts` / `types/globals.d.ts` / `types/styles.d.ts` | 经典 JSX 运行时（`jsxFactory: h`）、vitest 的别名、浏览器半侧的运行时垫片、`*.module.css` 的类名表声明 | — |
+| `DEVELOPING.md` | 就是本文（作者文档；用户说明在 `README.md`） | — |
+
+## 长任务、工具、写通道与配置（样板）
+
+这份骨架故意带了一组**可跑**的能力，示范五件事：
+
+- **宿主面接线**：`name` / `inject` / `apply` 用 `@dsh-workbench/shared/host` 的 `defineUnitHostPlugin`
+  一次给齐；写工具的审批口径用 `writeApprovalOf`；`recordOf` / `textOf` 也从那里取，别每个文件抄一份。
+- **只读工具**：`registerTools()` 是**调用时才注册**、返回的是清理函数；工具名必须和 `package.json` 的
+  `dsh.workbench.tools` 一字不差。`__UNIT___run` 起一趟流程，传 `runId` 则只看同一趟。
+- **长任务**：`deps.longTasks.create()` 交回一张注册表，`run` 里调 `deps.flow.run()` 并把
+  `onStep` 交给 `longTaskStepOf`（shared/host 的默认映射）；卡片用 `useLongTask` 读、`LongTaskRow` 画。
+- **写通道 + 审批**：`__UNIT___add_note` 在清单里写 `writes: true`，`mount()` 返回 `needsApproval`（这次要点头）
+  与 `approvalDetail`（审批屏上那句"会写什么"）；agent 调用前壳会拦一道。卡片那颗钮走动作通道
+  `<unit>-add-note`（点击即确认，不审批），与写工具共用同一份 `deps.store` 数据；网络 / 校验失败
+  留在按钮下面那一行，不静默。
+- **配置（prefs）**：`mount()` 返回 `prefs: { resource, handle }`，按工作区把"显示几个文件"存进
+  `deps.store`；卡片用 `useHostWrite({ channel: 'prefs' })` 写、用 `<unit>/prefs` 读。
+- **动作通道**：用户直接点的单步动作走 `<unit>-…` 资源；与工具共用实现，不另写一份。
+
+换成你自己的能力时，五处一起改：`src/model/*` 的纯逻辑、`src/host/*` 的实现、
+`src/host.ts` 的接线（路由 / 工具 / 动作 / prefs / 审批）、`src/components/OverviewCard.tsx` 的展示、
+`design.json` 的三张表与能力行。
+
+## 数据是在哪算出来的
+
+宿主侧，`src/host/overview.ts` 的 `readOverview(path, limit)`：
+
+* `readdirSync(path, { withFileTypes: true })` 数出**目录数**；
+* 每个普通文件 `statSync` 一次，累加**总字节**、记下 `name / bytes / mtime`（mtime 是 ISO 串）；
+* 按字节降序（同字节按名字）排，取前 `limit` 个当**最大的几个文件**。
+
+已知的取舍（不是 bug，是这份骨架刻意保持简单的地方）：
+
+* **符号链接不计数**：既不算文件也不算目录（想要跟随就自己换成 `statSync` + `lstatSync` 判断）；
+* **同步读**：模板优先让代码一眼看得懂；真接大目录时改成 `node:fs/promises` 版本更合适；
+* 只读**直接子项**，不递归。
+
+## 那条只读路由
+
+键是 `<unit>/overview`（`__UNIT__` 就是本模块的单元 id）——**必须住在自己那一格的命名空间里**，
+外壳装 / 升 / 卸时要能点名到它；写成别的名字注册当场就被判红。
+
+```
+GET /api/__UNIT__/overview?path=<绝对路径>&limit=<1..50>
+```
+
+查询参数：
+
+| 参数 | 缺省 | 说明 |
+|---|---|---|
+| `path` | 无（必填） | 要读的目录。卡片把 `props.world.current.workspace.path` 塞进来；缺了不回数据，直接回 `no-path` |
+| `limit` | `5` | 返回几个"最大的文件"，夹在 `1..50` 之间 |
+
+成功：
+
+```json
+{ "ok": true, "path": "/…", "files": 128, "dirs": 12, "bytes": 3145728,
+  "largest": [{ "name": "client.js", "bytes": 182400, "mtime": "2026-01-05T09:12:44.000Z" }] }
+```
+
+读不到（路径不存在 / 没权限 / 不是目录）：**HTTP 200 + `ok:false`**，错误码 `overview-unreadable`。
+压根没给 `path`：同样 `ok:false`，错误码 `no-path` —— 别拿宿主进程的工作目录当默认值：
+那会让"我没说要看哪儿"变成"屏幕上是 dsh 服务启动目录"，两个都不像用户想要的东西。
+之所以不让它抛：抛出去会被外壳的传输层转成 HTTP 500，卡片只剩一句"宿主返回 HTTP 500"，
+用户看不到是哪条路径出了什么事。
+
+```json
+{ "ok": false, "error": { "code": "overview-unreadable", "message": "ENOENT: no such file or directory, scandir '/…'" } }
+```
+
+卡片侧读数的 hook 是 `kit.hooks.useApiResource`（`route` 就是 `__UNIT__/overview`）。
+注意它的 `value` 是**整个响应对象**（成功时形如 `{ ok: true, ...payload }`），不是 `payload` 本身。
+
+## 卡片画哪五态
+
+`src/model/overview.ts` 的 `overviewStateOf({ phase, value, error })` 是一条纯函数，
+每个分支各对应一屏（`src/model/__tests__/overview.test.ts` 直接断言这条函数，
+`src/components/__tests__/OverviewCard.test.ts` 再把每一屏画一遍）：
+
+| 态 | 什么时候 | 画什么 |
+|---|---|---|
+| 待机 | 没有选中工作区（`path === ''`），请求压根不发（`useApiResource(…, { enabled: false })`，`phase` 停在 `idle`） | `CenteredState`：先打开一个项目 |
+| 加载 | 还没有值（首读），或 `phase === 'error'` 之外什么都没来 | `CenteredState`：正在读目录 |
+| 就绪 | 有值，且文件数 + 目录数 > 0 | `StateBlock`：路径 + 「N 个文件 · M 个目录 · 总字节」+ 最大的几个文件列表 |
+| 就绪但空 | 有值，但文件数 = 目录数 = 0 | `EmptyState`：这个目录是空的 |
+| 出错 | `phase === 'error'` | `CenteredState`：读不到这个目录 + 宿主的原话 |
+
+刷新时 `useApiResource` 会把 `phase` 打成 `loading` **同时保留上一次的 `value`** ——
+这时刻意继续画旧数据（右上角的转圈由 `Card` 的 `refreshing` 表示），不退回骨架：
+一次刷新不该让整张卡闪一下。
+
+## 开发与发布
+
+开发命令见上面的六个脚本；dsh / 工作台的模块约束见工作台模块指引（随外壳出货）；agent 的工作说明见 `AGENTS.md`。
+
+发布（维护者确认之后）：`dsh-wb-module release --target team|public|tarball|git`；
+`--dry-run` 只预览，`--verify` 只核已发布的包。

package/template-diy/README.md.tpl

@@ -1,183 +1,5 @@
 # __NAME__
 
-`__UNIT__` 模块：一个独立的 dsh 插件包，只认外壳的服务名，不认识外壳源码。
+__DESC__
 
-这份是 **唯一模板**（`--template diy`，也是默认）生成的骨架：一张**读当前项目目录的只读卡**，
-数据从宿主侧**真读**一个目录算出来（`node:fs`），另带一条**能跑**的流程 / 长任务 / 真工具 /
-动作通道样板；不是一个写死的样板。
-
-```bash
-dsh-wb-module init <unit> --dir <目录>              # 生成这份骨架（只有这一个模板）
-dsh-wb-module build     # 出 dist/host.js 与套了 loader 壳的 client.js
-dsh-wb-module check     # 十四条判据：契约 / 声明协议 / 产物边界 / 源码边界 / 执行缝 / 架构 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳 / 代码卫生（eslint）
-dsh-wb-module check --only cards   # 十四条可以单跑
-```
-
-包自带的六个脚本（`build` / `typecheck` / `test` / `selfcheck` 是 `check` 的契约判据要求的那四个；`check` 跑全部判据，`lint` 只跑源码卫生那一条）：
-
-```bash
-pnpm build        # 构建产物
-pnpm typecheck    # tsc --noEmit
-pnpm test         # vitest：路由真读数 + 卡片五态 + 长任务/工具契约
-pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍 + 真跑一趟流程 + 走 scripts/smoke.assert.mjs
-pnpm check        # dsh-wb-module check
-pnpm lint         # dsh-wb-module lint（`--fix` 就地改文件；`check` 永不动手）
-```
-
-## 需求底稿（做之前填，做完自己逐条走一遍）
-
-三张表既是**要问清的需求**，也是**最后的验收单** —— 表里每一格 agent 都要在真卡片上见过或点过。
-**空着的格就是还没定的事**，别带着空格往下做：落点是同目录的 `design.json`
-（`dsh-wb-module design check` 会把空格一格一格列出来），**下面标了 start/end 的那一段就是由它生成的**
-—— 要改三张表就改 `design.json`，再 `dsh-wb-module design render`；手改那一段会被 next 一次 check 判红。
-所以下次他说"改一下"不用从头问。
-
-**非生成段（这一节与下文）不会被 render 覆盖**：需求变了要自己改这里，`design render` 只管标记之间那一段。
-
-怎么问、怎么填：指引 `SKILL.md` 的七步 · `DESIGN.md`（判域 / 两条分工 / 三张表）·
-`STEPS.md`（每步问什么、什么时候算做完）· `PANEL.md` · `TOOLS.md` · `LINKAGE.md`。
-
-<!-- dsh-wb:design:start -->
-（这一段由 `design.json` 生成：改需求改 `design.json`，再 `dsh-wb-module design render`；手改会被下一次 check 判红。）
-<!-- dsh-wb:design:end -->
-
-## 生成出来的形状
-
-**分层多文件**，不是单文件：数字越小越底层，上层只许 import 下层的（`arch.config.mjs` 那条
-`arch` 判据盯着，`dsh-wb-module check` 会跑）。目录**按需要出现**：这份有状态逻辑，所以有 `model/`。
-宿主侧的辅助实现放 `src/host/`（`moduleArch()` 默认就认这一层；
-`src/host.ts` 仍是对外的宿主面，两个面只认 `dsh.workbenchFaces` 里那两个文件）。
-
-| 文件 | 是什么 | 层 |
-|---|---|---|
-| `package.json` | 自述清单：`dsh.workbench.unit` = `__UNIT__`、两个面（`src/host.ts` / `src/client.tsx`）、八个脚本、peer 下限 | — |
-| `arch.config.mjs` | 本模块的架构方言：`moduleArch()`（`src/host/**` 默认在层序里）—— 层序表 / 两个运行时 / 阈值只有 `@dsh-workbench/module-tools/arch` 那一份，随工具链同代 | — |
-| `eslint.config.mjs` | 本模块的**语法卫生方言**，同样两行：`moduleLint()` —— 规则表只有 `@dsh-workbench/module-tools/lint` 那一份（`console` / `as any` / hooks 那几条 / 手搓颜色与 `!important`）；要开口子就 `moduleLint({ rules })` | — |
-| `cordis.patch.yml` | 插进 dsh 组合的补丁 | — |
-| `design.json` | 三张表 + 状态矩阵 + 数据源记录 + 验收清单（**唯一真相**，上面那段由它生成；`dsh-wb-module design check/render/accept` 读写它） | — |
-| `src/model/overview.ts` | 纯逻辑：类型 + 五态状态机 + `formatBytes`。两个运行时都读得到，不碰 react / kit / dsh / `node:*` | 1 |
-| `src/model/__tests__/overview.test.ts` | 模型层的配对测试（有 `src/model/**` 就必须有 —— `arch` 的 M08） | 99 |
-| `src/model/flow.ts` | 样板流程的纯逻辑：`FlowDefinition` + 五态标题 / 是否还在跑；不碰宿主 | 1 |
-| `src/model/__tests__/flow.test.ts` | 流程模型的配对测试 | 99 |
-| `src/model/notes.ts` | 笔记的纯逻辑：校验 / 读回 / 最多 20 条 | 1 |
-| `src/model/__tests__/notes.test.ts` | 笔记模型的配对测试 | 99 |
-| `src/model/prefs.ts` | 配置的纯逻辑：按工作区存 `limit`（1..50），坏值回默认 | 1 |
-| `src/model/__tests__/prefs.test.ts` | 配置模型的配对测试 | 99 |
-| `src/messages.ts` | 卡片那几句文案（zh / en），键带 `<unit>.` 前缀 | 1 |
-| `src/declared-tools.ts` | 清单里工具名的生成物（`dsh-wb-module sync` 写；代码只引 `DECLARED_TOOLS.run.name` / `DECLARED_TOOLS.addNote.name`，不写字面量） | 1 |
-| `src/components/OverviewCard.tsx` | 卡片：`Card` 壳 + 五态 + 最大的几个文件 + 长任务行 + 笔记（写）/「显示几个」配置 | 2 |
-| `src/components/OverviewBody.tsx` | 五态各自那一屏（待机 / 加载 / 就绪 / 空 / 出错） | 2 |
-| `src/components/OverviewBody.module.css` | 就绪态「最大的几个文件」列表的布局 | 2 |
-| `src/components/RunSection.tsx` | 长任务那一块：跑流程的钮 + `LongTaskRow`（五态 / 停止） | 2 |
-| `src/components/NotesSection.tsx` | 笔记那一块：输入 + 存一条 + 列表 | 2 |
-| `src/components/PrefsSection.tsx` | 「最大的几个文件」配置（`SelectField`，按工作区存） | 2 |
-| `src/components/OverviewCard.module.css` | 这个组件自己的样式（CSS Modules，构建时类名按路径哈希）—— **样式跟组件同目录** | 2 |
-| `src/components/__tests__/OverviewCard.test.ts` | 这张卡五态各画得出来 + 写失败留在卡上（测试住同目录的 `__tests__/`）；流程 / 笔记 / 配置的接线由 `plugin.test.ts` 与 smoke 覆盖 | 99 |
-| `src/host.ts` | 宿主面：接线 + 三条只读路由（`overview` / `notes` / `prefs`）+ 挂工具 / 长任务 / 动作通道 / `prefs` / 审批口径 | 10 |
-| `src/host/overview.ts` | 宿主侧内部实现：`readOverview()`（真读目录）+ 路由回答 | 10 |
-| `src/host/sample.ts` | 宿主侧内部实现：样板流程的动作、长任务、只读工具 | 10 |
-| `src/host/notes.ts` | 宿主侧内部实现：笔记读写（`deps.store`）+ 写工具 + 动作通道 | 10 |
-| `src/client.tsx` | 浏览器面：**只剩面** —— 注册 + 把 props 交给 `components/OverviewCard` | 10 |
-| `src/__tests__/plugin.test.ts` | 面注册 + 路由真读 + 工具注册 + 流程真跑 + 笔记/配置/审批 | 99 |
-| `scripts/smoke.mjs` | 接线自检：卡片进没进外壳、工具注册、流程真跑、笔记真写、配置存得住；真读断言在 `smoke.assert.mjs` | — |
-| `scripts/smoke.assert.mjs` | **这个模块自己的**真读断言：换数据源时改这份，别删 smoke 里的调用 | — |
-| `CHANGELOG.md` | 版本记录（`dsh-wb-module release` 追加；`package.json.files` 里带它） | — |
-| `tsconfig.json` / `vitest.config.ts` / `types/globals.d.ts` / `types/styles.d.ts` | 经典 JSX 运行时（`jsxFactory: h`）、vitest 的别名、浏览器半侧的运行时垫片、`*.module.css` 的类名表声明 | — |
-| `README.md` | 就是本文 | — |
-
-## 长任务、工具、写通道与配置（样板）
-
-这份骨架故意带了一组**可跑**的能力，示范五件事：
-
-- **宿主面接线**：`name` / `inject` / `apply` 用 `@dsh-workbench/shared/host` 的 `defineUnitHostPlugin`
-  一次给齐；写工具的审批口径用 `writeApprovalOf`；`recordOf` / `textOf` 也从那里取，别每个文件抄一份。
-- **只读工具**：`registerTools()` 是**调用时才注册**、返回的是清理函数；工具名必须和 `package.json` 的
-  `dsh.workbench.tools` 一字不差。`__UNIT___run` 起一趟流程，传 `runId` 则只看同一趟。
-- **长任务**：`deps.longTasks.create()` 交回一张注册表，`run` 里调 `deps.flow.run()` 并把
-  `onStep` 交给 `longTaskStepOf`（shared/host 的默认映射）；卡片用 `useLongTask` 读、`LongTaskRow` 画。
-- **写通道 + 审批**：`__UNIT___add_note` 在清单里写 `writes: true`，`mount()` 返回 `needsApproval`（这次要点头）
-  与 `approvalDetail`（审批屏上那句"会写什么"）；agent 调用前壳会拦一道。卡片那颗钮走动作通道
-  `<unit>-add-note`（点击即确认，不审批），与写工具共用同一份 `deps.store` 数据；网络 / 校验失败
-  留在按钮下面那一行，不静默。
-- **配置（prefs）**：`mount()` 返回 `prefs: { resource, handle }`，按工作区把"显示几个文件"存进
-  `deps.store`；卡片用 `useHostWrite({ channel: 'prefs' })` 写、用 `<unit>/prefs` 读。
-- **动作通道**：用户直接点的单步动作走 `<unit>-…` 资源；与工具共用实现，不另写一份。
-
-换成你自己的能力时，五处一起改：`src/model/*` 的纯逻辑、`src/host/*` 的实现、
-`src/host.ts` 的接线（路由 / 工具 / 动作 / prefs / 审批）、`src/components/OverviewCard.tsx` 的展示、
-`design.json` 的三张表与能力行。
-
-## 数据是在哪算出来的
-
-宿主侧，`src/host/overview.ts` 的 `readOverview(path, limit)`：
-
-* `readdirSync(path, { withFileTypes: true })` 数出**目录数**；
-* 每个普通文件 `statSync` 一次，累加**总字节**、记下 `name / bytes / mtime`（mtime 是 ISO 串）；
-* 按字节降序（同字节按名字）排，取前 `limit` 个当**最大的几个文件**。
-
-已知的取舍（不是 bug，是这份骨架刻意保持简单的地方）：
-
-* **符号链接不计数**：既不算文件也不算目录（想要跟随就自己换成 `statSync` + `lstatSync` 判断）；
-* **同步读**：模板优先让代码一眼看得懂；真接大目录时改成 `node:fs/promises` 版本更合适；
-* 只读**直接子项**，不递归。
-
-## 那条只读路由
-
-键是 `<unit>/overview`（`__UNIT__` 就是本模块的单元 id）——**必须住在自己那一格的命名空间里**，
-外壳装 / 升 / 卸时要能点名到它；写成别的名字注册当场就被判红。
-
-```
-GET /api/__UNIT__/overview?path=<绝对路径>&limit=<1..50>
-```
-
-查询参数：
-
-| 参数 | 缺省 | 说明 |
-|---|---|---|
-| `path` | 无（必填） | 要读的目录。卡片把 `props.world.current.workspace.path` 塞进来；缺了不回数据，直接回 `no-path` |
-| `limit` | `5` | 返回几个"最大的文件"，夹在 `1..50` 之间 |
-
-成功：
-
-```json
-{ "ok": true, "path": "/…", "files": 128, "dirs": 12, "bytes": 3145728,
-  "largest": [{ "name": "client.js", "bytes": 182400, "mtime": "2026-01-05T09:12:44.000Z" }] }
-```
-
-读不到（路径不存在 / 没权限 / 不是目录）：**HTTP 200 + `ok:false`**，错误码 `overview-unreadable`。
-压根没给 `path`：同样 `ok:false`，错误码 `no-path` —— 别拿宿主进程的工作目录当默认值：
-那会让"我没说要看哪儿"变成"屏幕上是 dsh 服务启动目录"，两个都不像用户想要的东西。
-之所以不让它抛：抛出去会被外壳的传输层转成 HTTP 500，卡片只剩一句"宿主返回 HTTP 500"，
-用户看不到是哪条路径出了什么事。
-
-```json
-{ "ok": false, "error": { "code": "overview-unreadable", "message": "ENOENT: no such file or directory, scandir '/…'" } }
-```
-
-卡片侧读数的 hook 是 `kit.hooks.useApiResource`（`route` 就是 `__UNIT__/overview`）。
-注意它的 `value` 是**整个响应对象**（成功时形如 `{ ok: true, ...payload }`），不是 `payload` 本身。
-
-## 卡片画哪五态
-
-`src/model/overview.ts` 的 `overviewStateOf({ phase, value, error })` 是一条纯函数，
-每个分支各对应一屏（`src/model/__tests__/overview.test.ts` 直接断言这条函数，
-`src/components/__tests__/OverviewCard.test.ts` 再把每一屏画一遍）：
-
-| 态 | 什么时候 | 画什么 |
-|---|---|---|
-| 待机 | 没有选中工作区（`path === ''`），请求压根不发（`useApiResource(…, { enabled: false })`，`phase` 停在 `idle`） | `CenteredState`：先打开一个项目 |
-| 加载 | 还没有值（首读），或 `phase === 'error'` 之外什么都没来 | `CenteredState`：正在读目录 |
-| 就绪 | 有值，且文件数 + 目录数 > 0 | `StateBlock`：路径 + 「N 个文件 · M 个目录 · 总字节」+ 最大的几个文件列表 |
-| 就绪但空 | 有值，但文件数 = 目录数 = 0 | `EmptyState`：这个目录是空的 |
-| 出错 | `phase === 'error'` | `CenteredState`：读不到这个目录 + 宿主的原话 |
-
-刷新时 `useApiResource` 会把 `phase` 打成 `loading` **同时保留上一次的 `value`** ——
-这时刻意继续画旧数据（右上角的转圈由 `Card` 的 `refreshing` 表示），不退回骨架：
-一次刷新不该让整张卡闪一下。
-
-## 开发与发布
-
-开发命令见上面的六个脚本；dsh / 工作台的模块约束见工作台模块指引（随外壳出货）；agent 的工作说明见 `AGENTS.md`。
-
-发布（维护者确认之后）：`dsh-wb-module release --target team|public|tarball|git`；
-`--dry-run` 只预览，`--verify` 只核已发布的包。
+<!-- 这份说明由 `dsh-wb-module design render` 从 readme.json 生成；作者文档在 DEVELOPING.md。 -->

package/template-diy/package.json.tpl

@@ -8,7 +8,7 @@
     ".": "./dist/host.js",
     "./client": "./client.js"
   },
-  "files": ["dist", "client.js", "cordis.patch.yml", "CHANGELOG.md"],
+  "files": ["dist", "client.js", "cordis.patch.yml", "DEVELOPING.md", "CHANGELOG.md"],
   "scripts": {
     "build": "dsh-wb-module build",
     "typecheck": "tsc --noEmit",

package/template-diy/readme.json.tpl

@@ -0,0 +1,27 @@
+{
+  "title": "__UNIT__ 模块",
+  "summary": "__DESC__",
+  "shots": [
+    {
+      "caption": "卡片",
+      "ascii": "（待填：一张卡片布局草图，用界面真实文案，按屏幕从上到下的顺序画）"
+    }
+  ],
+  "see": [
+    "（待填：用户在卡片上看到的第一样东西）"
+  ],
+  "do": [
+    "（待填：用户自己能点的一个按钮或能改的一项设置）"
+  ],
+  "agent": [
+    "（待填：agent 能替用户做的一件事；写之前要不要批准）"
+  ],
+  "data": [
+    "（待填：数据从哪来、用谁的登录、读还是写）"
+  ],
+  "install": "",
+  "trouble": [
+    "（待填：出问题时用户看到什么、下一步点哪）"
+  ],
+  "faq": []
+}

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

@@ -337,13 +337,13 @@ check('另一个工作区没被带上（还是默认 5）', otherPrefs?.prefs?.l
 const { assertModule } = await import('./smoke.assert.mjs');
 await assertModule({ check, routes, mounted, UNIT_ID });
 
-// ── 需求底稿在不在：这份骨架的"设计记录"住 README，别只留在对话里 ──────────
+// ── 需求底稿在不在：这份骨架的"设计记录"住 DEVELOPING.md，别只留在对话里 ─────
 //
 // 只查**形状在不在**（那几节有没有被删掉），不查内容填得好不好 —— 内容由指引守，
 // 判据硬管内容只会逼出"把占位符原样留着"这种应付。
-const readme = readFileSync(new URL('../README.md', import.meta.url), 'utf8');
+const developing = readFileSync(new URL('../DEVELOPING.md', import.meta.url), 'utf8');
 for (const section of ['## 需求底稿', '### 表 1 面板', '### 表 2 agent', '### 表 3 联动', '### 数据源探明记录']) {
-  check(`README 里有「${section}」（需求与验收的落点）`, readme.includes(section));
+  check(`DEVELOPING.md 里有「${section}」（需求与验收的落点）`, developing.includes(section));
 }
 
 console.log(`\n${failures.length === 0 ? '模块自检通过' : `${failures.length} 条没过`}`);