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

package/README.md

@@ -196,7 +196,7 @@ export default [
 `dsh-wb-module lint --fix` 先写回再跑一遍看还剩什么。**`check` 永远不动手改文件** ——
 门禁是判据，不是修复器。
 
-模板生成三份文档：`readme.json` 是终端用户文案源（标题、简介、会看到什么、能做什么、agent 能做什么、数据从哪来、排障、FAQ），`README.md` 只由它生成；`DEVELOPING.md` 是作者文档（实现、路由、判据、数据源与三张表），由 `design.json` 生成。`design render` 刷新这两份；`design check` 会拦住空文案、占位符和技术词；旧模块先跑 `design migrate`，它把旧 `README.md` 原样保存为 `DEVELOPING.md`，再生成 `readme.json` 与用户 README。
+模板生成三份文档：`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`：三张表
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "1.2.8-beta.0",
+  "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.8-beta.0"
+    "@dsh-workbench/shared": "1.2.8-beta.1"
   },
   "repository": {
     "type": "git",

package/src/design.mjs

@@ -432,9 +432,30 @@ export function renderDesign(design) {
   ].join('\n');
 }
 
-function sectionOf(heading, body) {
-  const text0 = text(body);
-  return text0 === '' ? [] : [`## ${heading}`, '', text0, ''];
+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) {
@@ -443,7 +464,21 @@ export function renderUserReadme(source) {
   const faq = asRows(source?.faq);
   const install = text(source?.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
     ? []
     : [
@@ -457,6 +492,7 @@ export function renderUserReadme(source) {
     '',
     summary,
     '',
+    ...shotLines,
     ...sectionOf('你会看到什么', source?.see),
     ...sectionOf('你能做什么', source?.do),
     ...sectionOf('agent 能替你做什么', source?.agent),
@@ -499,12 +535,18 @@ export function userSourceSkeleton(manifest, design) {
   return {
     title: manifestTitleOf(manifest) || text(design?.name) || '模块',
     summary: text(design?.oneLine) || text(manifest?.description),
-    see: '（待填：终端用户会在卡片上看到什么；不要写组件名、图号、像素值）',
-    do: '（待填：终端用户自己能点什么、能改什么）',
-    agent: '（待填：agent 能替用户做什么；哪些动作会先弹审批）',
-    data: '（待填：数据从哪个系统来、用谁的登录、会不会写数据）',
+    shots: [
+      {
+        caption: '（可选：图注，比如「卡片」「设置面」「审批」）',
+        ascii: '（待填：一张卡片布局草图，用界面真实文案，按屏幕从上到下的顺序画）',
+      },
+    ],
+    see: ['（待填：用户在卡片上看到的第一样东西）'],
+    do: ['（待填：用户自己能点的一个按钮或能改的一项设置）'],
+    agent: ['（待填：agent 能替用户做的一件事；写之前要不要批准）'],
+    data: ['（待填：数据从哪来、用谁的登录、读还是写）'],
     install: '',
-    trouble: '（待填：没登录、超时、读不到时用户会看到什么、下一步点哪）',
+    trouble: ['（待填：出问题时用户看到什么、下一步点哪）'],
     faq: [],
   };
 }
@@ -523,18 +565,37 @@ const USER_COPY_FORBIDDEN = [
   ['平台内部字段', /\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 value = text(source?.[field]);
-    if (value === '') problems.push(`${field} 是空的 —— README 的「${field}」还没有用户文案`);
-    else if (value.includes('（待填')) problems.push(`${field} 还留着「（待填）」`);
+    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']) {
-    const value = text(source?.[field]);
-    for (const [label, pattern] of USER_COPY_FORBIDDEN) {
-      if (pattern.test(value)) problems.push(`${field} 里有${label} —— 这段只给终端用户看`);
+    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()) {

package/template-diy/readme.json.tpl

@@ -1,11 +1,27 @@
 {
   "title": "__UNIT__ 模块",
   "summary": "__DESC__",
-  "see": "（待填：用户在卡片上会看到什么。写画面和数字，不写组件名、图号、像素值）",
-  "do": "（待填：用户自己能点什么、能改什么；没有就写「只能看，不能改」）",
-  "agent": "（待填：agent 能替用户做什么；哪些动作会先弹审批。没有就写「这个模块没有给 agent 开放工具」）",
-  "data": "（待填：数据从哪个系统来、用谁的登录、会不会写数据。没有数据源就写「没有数据源」）",
+  "shots": [
+    {
+      "caption": "卡片",
+      "ascii": "（待填：一张卡片布局草图，用界面真实文案，按屏幕从上到下的顺序画）"
+    }
+  ],
+  "see": [
+    "（待填：用户在卡片上看到的第一样东西）"
+  ],
+  "do": [
+    "（待填：用户自己能点的一个按钮或能改的一项设置）"
+  ],
+  "agent": [
+    "（待填：agent 能替用户做的一件事；写之前要不要批准）"
+  ],
+  "data": [
+    "（待填：数据从哪来、用谁的登录、读还是写）"
+  ],
   "install": "",
-  "trouble": "（待填：没登录、超时、读不到时用户会看到什么，下一步点哪）",
+  "trouble": [
+    "（待填：出问题时用户看到什么、下一步点哪）"
+  ],
   "faq": []
 }