@dsh-workbench/module-tools 1.1.18 → 1.1.19-beta.0

package/README.md

@@ -31,8 +31,10 @@ pnpm design check # 设计底稿有没有空格、README 有没有落后
 `package.json` 缺 `files` 里的 `CHANGELOG.md` 一样拦下；`author` 没写时从本机 `git config` 补进 manifest，索引与产物都带上。
 标签只住在市集条目上（`metadata.labels`），**不写进 `package.json`**：清单的键是协议定死的
 （`apiVersion` / `unit` / `title` / `card` / `tools` / `host` / `needs`），往里塞私货 check 会判红。
-发布时带 `--label <短词>`（可重复，最多两个）：它并进索引条目的 `metadata.labels`；
+标签可选：`--label <短词>`（可重复，最多两个）并进索引条目的 `metadata.labels`；
 不传就沿用老清单里已经写过的（`dsh.workbench.market.labels`，只在读那一侧认）。
+分类 `--category <短词>` 是市场发布的要求：条目还没有分类时必须给一个（工作台的发布审批会拦），
+已有分类可以不带；它写进 `metadata.category`，发现页的分类 chip 就是按它汇总的，新模块带一个新分类，页面自动多一个。
 标题 / 署名 / 说明仍保持索引里现有的那份不动。
 要换署名时带 `--author "姓名 <邮箱>"`（或只给姓名）：它写回 `package.json`，索引、产物与提交都用它，
 `--refresh` 时也一样。**发布本身不改市集里的标题 / 署名 / 说明**：这些元数据只由 `--refresh`（或显式 `--author`）写，
@@ -57,7 +59,7 @@ pnpm design check # 设计底稿有没有空格、README 有没有落后
 | `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） |
-| `dsh-wb-module release` | 真发布：team / public / tarball / git；全门禁 + 验收闸 + 预检接管 + 发后核包 + 更新市场索引（`--dry-run` / `--verify`） |
+| `dsh-wb-module release` | 真发布：team / public / tarball / git / market / local；全门禁 + 验收闸 + 预检接管 + 发后核包 + 更新市场索引（`--dry-run` / `--verify`） |
 
 `--cwd <目录>` 指定**工作目录**，默认当前目录。注意判据仍按**工作区**发现模块：往上找
 `pnpm-workspace.yaml`（或 `package.json` 的 `workspaces`），按它声明的 glob 展开包目录

package/bin/dsh-wb-module.mjs

@@ -2,6 +2,8 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { Command } from 'commander';
+import { WORKBENCH_API_VERSION } from '@dsh-workbench/shared/host';
+import { RELEASE_TARGETS } from '@dsh-workbench/shared/contract/protocol/release';
 import { build } from '../src/build.mjs';
 import { CHECKS, check } from '../src/check.mjs';
 import { changelog } from '../src/changelog.mjs';
@@ -63,17 +65,18 @@ const MIGRATE_HELP = `
 用法：
   migrate [--cwd <模块目录>] [--dry-run]
 
-把模块清单迁到当前代：apiVersion → 3、缺/空的 workbenchFaces 补默认入口。
+把模块清单迁到当前代：apiVersion → ${WORKBENCH_API_VERSION}、缺/空的 workbenchFaces 补默认入口。
 源码类问题（kit 成员移除、裸控件、card: null 对账）不自动改 —— check 会逐条点名。`;
 
 const RELEASE_HELP = `
 选项：
-  --target team|public|tarball|git|market|local         出口；省略按配置默认（可写索引优先 market）
+  --target ${RELEASE_TARGETS.join('|')}         出口；省略按配置默认（可写索引优先 market）
   --version patch|minor|major|x.y.z                     版本；省略时已存在就自动 patch
   --registry <url> --access restricted|public --npmrc <文件>
   --license <id> --out <目录> --git <remote>
   --author <署名>                                       换署名（姓名，或 姓名 <邮箱>）；写回 package.json
-  --label <短词>                                        给市集条目打标签（1–2 个，可重复）；写回 package.json
+  --label <短词>                                        给市集条目打标签（1–2 个，可重复）；只进索引条目
+  --category <短词>                                     给市集条目定分类（一个短词）；只进索引条目，不传沿用已有的
   --changelog-note <文字> --changelog-type added|changed|fixed|removed|security|deprecated
                                                         这一版还没有更新日志时写进 CHANGELOG.md（文件不在先建）
   --index auto|none|<目录|git 地址>                     发布后要更新的索引源

package/package.json

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

package/src/arch.mjs

@@ -13,9 +13,7 @@ import {
 import { createRule } from '@arch-guard/core';
 import { DECLARED_TOOLS_FILE } from './declared-tools.mjs';
 import { SEED_SPECIFIERS } from './seed.mjs';
-
-const HOST_FACE = 'src/host.ts';
-const CLIENT_FACE = 'src/client.tsx';
+import { CLIENT_FACE, HOST_FACE } from './faces.mjs';
 
 const LAYERS = { model: 1, components: 2, host: 10 };
 

package/src/build.mjs

@@ -5,6 +5,7 @@ import { isAbsolute, join, relative } from 'node:path';
 import { build as esbuild } from 'esbuild';
 import { SEED_SPECIFIERS } from './seed.mjs';
 import { cssInjectionCode } from './css-injection.mjs';
+import { CLIENT_ENTRY_CANDIDATES, HOST_ENTRY_CANDIDATES } from './faces.mjs';
 
 const SHELL_CLIENT = '@dsh-workbench/core/client';
 const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.js', '.json'];
@@ -113,7 +114,7 @@ export async function build({ root }) {
   const plugins = [aliasResolver({ root, unit })];
   const nodeBuiltins = [...builtinModules, ...builtinModules.map((name) => `node:${name}`)];
 
-  const hostEntry = pickEntry(root, ['src/plugin.host.ts', 'src/host.ts']);
+  const hostEntry = pickEntry(root, HOST_ENTRY_CANDIDATES);
   if (hostEntry !== undefined) {
     await esbuild({
       absWorkingDir: root,
@@ -130,8 +131,8 @@ export async function build({ root }) {
     });
   }
 
-  const clientEntry = pickEntry(root, ['src/plugin.client.ts', 'src/client.tsx']);
-  if (clientEntry === undefined) throw new Error('找不到浏览器侧入口（src/plugin.client.ts 或 src/client.tsx）');
+  const clientEntry = pickEntry(root, CLIENT_ENTRY_CANDIDATES);
+  if (clientEntry === undefined) throw new Error(`找不到浏览器侧入口（${CLIENT_ENTRY_CANDIDATES.join(' 或 ')}）`);
   const client = await esbuild({
     absWorkingDir: root,
     entryPoints: [clientEntry],

package/src/checks/contracts.mjs

@@ -4,6 +4,8 @@ import { homedir } from 'node:os';
 import { join, relative } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
+  OPENCLI_CATALOG_ENV,
+  OPENCLI_NPM_PACKAGE,
   buildSupplyIndex,
   createHostKit,
   hostSurface,
@@ -18,6 +20,7 @@ import {
 } from '../declared-tools.mjs';
 import { discoverPackages, workspaceRootOf } from '../discover.mjs';
 import { readDesign } from '../design.mjs';
+import { DEFAULT_FACES } from '../faces.mjs';
 import { datasourceProblemOf } from '../datasource-file.mjs';
 import { SEED_SHORT } from '../seed.mjs';
 
@@ -65,9 +68,6 @@ async function unitFaceOf(dir) {
   }
 }
 
-const OPENCLI_CATALOG_ENV = 'DSH_WB_OPENCLI_CATALOG';
-const OPENCLI_NPM_PACKAGE = '@jackwener/opencli';
-
 function workbenchRootOf() {
   const configured = process.env.DSH_WORKBENCH_HOME?.trim();
   if (configured !== undefined && configured !== '') return configured;
@@ -540,7 +540,7 @@ export async function run() {
         problems.push(
           `${name}: dsh.workbenchFaces.${face} 没声明 —— 这两个源码入口是工具链字段` +
             `（不在 dsh.workbench 协议里）：source 判据靠它们判"哪一半"，缺了它判不了` +
-            `（\`dsh-wb-module migrate\` 会补默认的 ${face === 'host' ? 'src/host.ts' : 'src/client.tsx'}）`,
+            `（\`dsh-wb-module migrate\` 会补默认的 ${DEFAULT_FACES[face]}）`,
         );
       } else if (!existsSync(join(pkg.dir, rel))) {
         problems.push(`${name}: dsh.workbenchFaces.${face} 指的文件不存在 —— ${rel}`);

package/src/checks/style.mjs

@@ -289,6 +289,7 @@ export async function run() {
   const anchorHits = new Set();
   const modules = discoverModulePackages({ root: process.cwd() });
   const contracts = new Map(modules.map((pkg) => [pkg.dir, contractOf(pkg.dir)]));
+  let dshTokens = null;
   if (modules.length > 0) {
     const searched = [
       process.cwd(),
@@ -297,6 +298,7 @@ export async function run() {
       join(dshHome(), 'workbench', 'diy'),
     ];
     const tokens = readTokens(searched);
+    dshTokens = tokens.dsw;
     const dswNames = (tokens.dsw?.entries ?? []).map((one) => one.name);
     const wbNames = (tokens.wb?.entries ?? []).map((one) => one.name);
     const known = new Set([...dswNames, ...wbNames]);
@@ -675,11 +677,11 @@ export async function run() {
       ? '没有手写的整张表单（没有裸 <form>，也没有借表单槽类手摆行）'
       : `表单这一层还有 ${formHits.size} 个文件在 FORM_EXEMPT 里等外壳发版后迁（棘轮：迁一处删一行）`;
 
-  const fontScale = fontScaleOf(SHELL_FONT_SCALE_FILES);
+  const fontScale = fontScaleOf(SHELL_FONT_SCALE_FILES, dshTokens);
   const fontNotes = fontScaleNotes(
     auditFontSizes({ roots: fontRootsIn(modules), scale: fontScale }),
     fontScale,
-    { doc: FONT_DOC },
+    { doc: FONT_DOC, dshMissing: dshTokens === null },
   );
   return {
     status: 'pass',

package/src/faces.mjs

@@ -0,0 +1,7 @@
+export const HOST_FACE = 'src/host.ts';
+export const CLIENT_FACE = 'src/client.tsx';
+
+export const DEFAULT_FACES = { host: HOST_FACE, client: CLIENT_FACE };
+
+export const HOST_ENTRY_CANDIDATES = ['src/plugin.host.ts', HOST_FACE];
+export const CLIENT_ENTRY_CANDIDATES = ['src/plugin.client.ts', CLIENT_FACE];

package/src/font-scale.mjs

@@ -1,8 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 
-export const DSH_ALIAS_FONT_SIZES = [11, 12, 13, 14, 16, 20, 24];
-
 const SHELL_FONT_TOKEN = /--wb-font-[a-z0-9-]+\s*:\s*([0-9]+(?:\.[0-9]+)?)px/g;
 
 export function shellFontScaleIn(files) {
@@ -16,8 +14,26 @@ export function shellFontScaleIn(files) {
   return sizes;
 }
 
-export function fontScaleOf(shellTokenFiles = []) {
-  return new Set([...DSH_ALIAS_FONT_SIZES, ...shellFontScaleIn(shellTokenFiles)]);
+const TOKEN_FONT_SIZE = /([0-9]*\.?[0-9]+)(px|rem)/g;
+
+export function tokenFontSizesIn(source) {
+  const sizes = new Set();
+  if (source === null || source === undefined) return sizes;
+  for (const entry of source.entries ?? []) {
+    if (!entry.name.includes('font-size')) continue;
+    for (const value of [entry.values?.light, entry.values?.dark]) {
+      if (typeof value !== 'string') continue;
+      for (const hit of value.matchAll(TOKEN_FONT_SIZE)) {
+        const number = Number(hit[1]);
+        sizes.add(hit[2] === 'rem' ? number * 16 : number);
+      }
+    }
+  }
+  return sizes;
+}
+
+export function fontScaleOf(shellTokenFiles = [], dshTokens = null) {
+  return new Set([...shellFontScaleIn(shellTokenFiles), ...tokenFontSizesIn(dshTokens)]);
 }
 
 const CSS_FONT_SIZE = /(?:^|[;{\s])font-size\s*:\s*([^;{}]+)/g;
@@ -131,10 +147,13 @@ function detailOf(hit, verdict) {
     : `· ${head} —— ${formatSize(hit.px)} 在刻度上，可收进令牌（但不是错）`;
 }
 
-export function fontScaleNotes(report, scale, { doc }) {
+export function fontScaleNotes(report, scale, { doc, dshMissing = false }) {
   const sizes = [...scale].sort((a, b) => a - b).map(formatSize).join(' / ');
+  const source = dshMissing
+    ? '外壳 --wb-font-* 的定义（dsh 主题没读到，--dsw-font-* 未纳入）'
+    : '外壳 --wb-font-* 与 dsh --dsw-font-* 的定义';
   const head =
-    `字号口径（黄，不判红）：刻度 ${sizes}（从 --dsw-font-* 与 --wb-font-* 的**定义**读出来，` +
+    `字号口径（黄，不判红）：刻度 ${sizes}（从 ${source}读出来，` +
     `出处见 ${doc}）；引用令牌 ${report.refs.length} 处 / ${report.refFiles.size} 文件（合规，不列）；` +
     `刻度外字面值 ${report.offScale.length} 处 / ${report.litFiles.size} 文件；` +
     `刻度上字面值 ${report.onScale.length} 处；相对单位（em/%）判不了 ${report.relative.length} 处`;

package/src/market-index.mjs

@@ -1,6 +1,7 @@
 import { cpSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
+import { MARKET_INDEX_DIR, MARKET_INDEX_PATH } from '@dsh-workbench/shared/contract/protocol/market-index';
 
 import {
   MARKET_ENTRIES_README_LINES,
@@ -18,8 +19,8 @@ import {
   sortMarketVersions,
 } from '@dsh-workbench/shared/host';
 
-const MARKET_DIR = 'market';
-const LEGACY_FILE = 'market.json';
+const MARKET_DIR = MARKET_INDEX_DIR;
+const LEGACY_FILE = MARKET_INDEX_PATH;
 const SAFE_PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 const WORKSPACE_PREFIX = 'workspace:';
 const ARTIFACT_DIRS = ['dist'];
@@ -321,6 +322,19 @@ export function mergeEntryLabels(entry, labels) {
   return { ...entry, metadata: { ...(entry.metadata ?? {}), labels: wanted } };
 }
 
+export function categoryOfManifest(manifest) {
+  const dsh = recordOf(recordOf(manifest).dsh);
+  const workbench = recordOf(dsh.workbench);
+  const category = recordOf(workbench.market).category;
+  return typeof category === 'string' ? category.trim() : '';
+}
+
+export function mergeEntryCategory(entry, category) {
+  if (typeof category !== 'string' || category === '') return entry;
+  if (entry.metadata?.category === category) return entry;
+  return { ...entry, metadata: { ...(entry.metadata ?? {}), category } };
+}
+
 export function entryMetaOf(manifest) {
   const author = authorOf(manifest);
   const homepage = typeof manifest.homepage === 'string' ? manifest.homepage.trim() : '';
@@ -741,6 +755,7 @@ export function updateMarketIndex(options) {
         }
       }
       next = mergeEntryLabels(next, options.labels);
+      next = mergeEntryCategory(next, options.category);
       writeEntryFile(workdir, dir, next);
       indexSha = commitOf(exec, workdir, `chore(market): ${entryName}`, identityOf(manifest));
       report({ phase: 'index-committed', indexCommit: indexSha });
@@ -815,6 +830,18 @@ export function refreshMarketEntry(options) {
     }
     const latest = existing.versions[0]?.version ?? '';
     const meta = entryMetaOf(manifest);
+    const keptLabels = Array.isArray(options.labels) && options.labels.length > 0
+      ? [...options.labels]
+      : (existing.metadata?.labels ?? []);
+    const keptCategory = typeof options.category === 'string' && options.category !== ''
+      ? options.category
+      : (existing.metadata?.category ?? '');
+    const metadata = { ...(meta.metadata ?? {}) };
+    if (keptLabels.length === 0) delete metadata.labels;
+    else metadata.labels = keptLabels;
+    if (keptCategory === '') delete metadata.category;
+    else metadata.category = keptCategory;
+    meta.metadata = metadata;
     const next = { ...existing };
     for (const key of ['title', 'description', 'author', 'homepage', 'metadata']) {
       if (Object.hasOwn(meta, key)) next[key] = meta[key];

package/src/migrate.mjs

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { WORKBENCH_API_VERSION } from '@dsh-workbench/shared/host';
+import { DEFAULT_FACES } from './faces.mjs';
 
-const API_VERSION = 3;
-
-const DEFAULT_FACES = { host: 'src/host.ts', client: 'src/client.tsx' };
+const API_VERSION = WORKBENCH_API_VERSION;
 
 export async function migrate({ root, args = [] }) {
   const dryRun = args.includes('--dry-run');

package/src/release-target.mjs

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { RELEASE_TARGETS } from '@dsh-workbench/shared/contract/protocol/release';
 import { dirname, join, relative, resolve, sep } from 'node:path';
 
 import {
@@ -11,7 +12,7 @@ import {
   tailOf,
 } from './release-util.mjs';
 
-const TARGETS = ['team', 'public', 'tarball', 'git', 'market', 'local'];
+const TARGETS = RELEASE_TARGETS;
 const PUBLIC_REGISTRIES = ['https://registry.npmjs.org/', 'https://registry.npmmirror.com/'];
 
 function isPublicRegistry(registry) {

package/src/release.mjs

@@ -51,6 +51,7 @@ import {
 import {
   MarketIndexError,
   authorTextOf,
+  categoryOfManifest,
   claimProblemText,
   identityOf,
   labelsOfManifest,
@@ -158,7 +159,7 @@ function writeStateKeepingRun(home, unit, value) {
   writeState(home, unit, run === undefined ? value : { ...value, run });
 }
 
-function stopSummaryOf(target, manifest, version, changes, changelog, labels) {
+function stopSummaryOf(target, manifest, version, changes, changelog, labels, category = '') {
   return {
     ok: true,
     stop: 'workspace-only',
@@ -167,6 +168,7 @@ function stopSummaryOf(target, manifest, version, changes, changelog, labels) {
     version,
     changes,
     ...(labels.length === 0 ? {} : { labels }),
+    ...(category === '' ? {} : { category }),
     ...(changelog === undefined ? {} : { changelog }),
     install: '',
   };
@@ -293,6 +295,10 @@ export async function runRelease({
     throw new ReleaseError('--label 只认一行短词：不能是空的');
   }
   if (askedLabels.length > 2) throw new ReleaseError('--label 最多两个 —— 一个模块的标签是 1–2 个短词');
+  const askedCategory = (argValue(args, '--category') ?? '').trim();
+  if (askedCategory !== '' && /[\r\n]/u.test(askedCategory)) {
+    throw new ReleaseError('--category 只认一个短词：不能换行');
+  }
   const manifest = readManifest(root);
   const unit = manifest?.dsh?.workbench?.unit;
   if (typeof unit !== 'string' || unit === '') throw new ReleaseError('这不是一个 wb 模块包（没有 dsh.workbench.unit）');
@@ -359,6 +365,8 @@ export async function runRelease({
   const labels = askedLabels;
   const labelsForIndex = labels.length > 0 ? labels : labelsOfManifest(manifest);
   const labelsChange = verify || labels.length === 0 ? undefined : `标签 ← ${labels.join(' · ')}`;
+  const categoryForIndex = askedCategory !== '' ? askedCategory : categoryOfManifest(manifest);
+  const categoryChange = verify || askedCategory === '' ? undefined : `分类 ← ${askedCategory}`;
   const explicitApplied = explicitAuthor !== undefined && !verify && !dryRun;
   if (explicitApplied && !indexOnly) {
     manifest.author = explicitAuthor;
@@ -397,7 +405,15 @@ export async function runRelease({
     const cardTitle = cardTitleFromMessages(root, unit);
     const titled = cardTitle === undefined ? manifest : { ...manifest, title: cardTitle };
     const publisher = authorTextOf(manifest) || authored.author || '';
-    const result = refreshMarketEntry({ plan: indexPlan, exec, home, manifest: titled, publisher });
+    const result = refreshMarketEntry({
+      plan: indexPlan,
+      exec,
+      home,
+      manifest: titled,
+      publisher,
+      ...(labelsForIndex.length === 0 ? {} : { labels: labelsForIndex }),
+      ...(categoryForIndex === '' ? {} : { category: categoryForIndex }),
+    });
     if (result.updated !== true && result.reason !== undefined) {
       throw new ReleaseError(`刷新市集元数据没走通：${result.reason}`);
     }
@@ -419,9 +435,11 @@ export async function runRelease({
               '市集元数据已刷新',
               ...(explicitAuthor === undefined ? [] : ['author ← --author']),
               ...(labelsChange === undefined ? [] : [labelsChange]),
+              ...(categoryChange === undefined ? [] : [categoryChange]),
             ]
           : [],
       ...(labels.length === 0 ? {} : { labels }),
+      ...(categoryForIndex === '' ? {} : { category: categoryForIndex }),
       install: '',
       text:
         result.updated === true
@@ -535,6 +553,7 @@ export async function runRelease({
       publisher: authorTextOf(manifestNow),
       metadata: authorChange !== undefined,
       ...(labelsForIndex.length === 0 ? {} : { labels: labelsForIndex }),
+      ...(categoryForIndex === '' ? {} : { category: categoryForIndex }),
       exec,
       home,
       now: () => Date.now(),
@@ -544,6 +563,7 @@ export async function runRelease({
   const changesOf = (version) => [
     ...(authorChange === undefined ? [] : [authorChange]),
     ...(labelsChange === undefined ? [] : [labelsChange]),
+    ...(categoryChange === undefined ? [] : [categoryChange]),
     ...(version === manifest.version ? [] : [`version → ${version}`]),
     ...(changelogChange === undefined ? [] : [changelogChange]),
   ];
@@ -764,6 +784,7 @@ export async function runRelease({
       files,
       changes: changesOf(version),
       ...(labels.length === 0 ? {} : { labels }),
+      ...(categoryForIndex === '' ? {} : { category: categoryForIndex }),
       ...(changelogReport === undefined ? {} : { changelog: changelogReport }),
       install: '',
       market: indexPreviewOf(manifest.name, version),
@@ -780,7 +801,7 @@ export async function runRelease({
     if (workspaceOnly) {
       writeManifest(root, next);
       if (tracking) advanceRun(home, unit, { phase: 'workspace', fingerprint: artifactFingerprintOf(root) });
-      const stopSummary = stopSummaryOf(target, next, version, changesOf(version), changelogReport, labels);
+      const stopSummary = stopSummaryOf(target, next, version, changesOf(version), changelogReport, labels, categoryForIndex);
       emit(out, json, stopSummary);
       return stopSummary;
     }
@@ -794,6 +815,7 @@ export async function runRelease({
       publisher,
       metadata: authorChange !== undefined,
       ...(labelsForIndex.length === 0 ? {} : { labels: labelsForIndex }),
+      ...(categoryForIndex === '' ? {} : { category: categoryForIndex }),
       exec,
       home,
       now: () => Date.now(),
@@ -877,7 +899,7 @@ export async function runRelease({
     if (tracking) advanceRun(home, unit, { phase: 'version', version, fingerprint: artifactFingerprintOf(root) });
     writeStateKeepingRun(home, unit, stateOf(info, next, version, 'intent'));
     if (workspaceOnly) {
-      const stopSummary = stopSummaryOf(target, next, version, changesOf(version), changelogReport, labels);
+      const stopSummary = stopSummaryOf(target, next, version, changesOf(version), changelogReport, labels, categoryForIndex);
       emit(out, json, stopSummary);
       return stopSummary;
     }
@@ -964,7 +986,7 @@ export async function runRelease({
       });
       if (workspaceOnly) {
         const stopSummary = {
-          ...stopSummaryOf(target, next, version, changesOf(version), changelogReport, labels),
+          ...stopSummaryOf(target, next, version, changesOf(version), changelogReport, labels, categoryForIndex),
           files: checked.files,
           git: { url: info.url, tag: info.tagOf(version), commit: checked.commit },
         };
@@ -1049,7 +1071,7 @@ export async function runRelease({
     if (!resumeMatchesTree) runCliStage(exec, root, ['check'], stageOptions);
     writeStateKeepingRun(home, unit, stateOf(info, next, version, 'intent'));
     if (workspaceOnly) {
-      const stopSummary = stopSummaryOf(target, next, version, changes, changelogReport, labels);
+      const stopSummary = stopSummaryOf(target, next, version, changes, changelogReport, labels, categoryForIndex);
       emit(out, json, stopSummary);
       return stopSummary;
     }

package/template-diy/AGENTS.md.tpl

@@ -7,7 +7,7 @@
 改 `src/**` 后：
 
 1. `pnpm build` —— 产出 `dist/host.js` + 套了 loader 壳的 `client.js`；产物由它生成。
-2. `pnpm check` —— 十三条判据，读的就是上一步的产物。单跑一条用 `pnpm check --only <判据名>`；
+2. `pnpm check` —— 十四条判据，读的就是上一步的产物。单跑一条用 `pnpm check --only <判据名>`；
    **全绿**才算这件活做完。怎么读红、常见红：`@dsh-workbench/core/skills/workbench-module-diy/REVIEW.md`。
 3. `pnpm test` —— `src/**/__tests__/` 下、与改动同目录的 `*.test.ts`；新逻辑配对应用例，**全绿**才算完。
 

package/template-diy/README.md.tpl

@@ -9,8 +9,8 @@
 ```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   # 十三条可以单跑
+dsh-wb-module check     # 十四条判据：契约 / 声明协议 / 产物边界 / 源码边界 / 执行缝 / 架构 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳 / 代码卫生（eslint）
+dsh-wb-module check --only cards   # 十四条可以单跑
 ```
 
 包自带的六个脚本（`build` / `typecheck` / `test` / `selfcheck` 是 `check` 的契约判据要求的那四个；`check` 跑全部判据，`lint` 只跑源码卫生那一条）：

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

@@ -1,7 +1,7 @@
 // 这份模块自己的真读断言：换数据源时改这一份，不要删 smoke.mjs 里那一整段。
 //
 // `assertModule()` 只在这里拿到真东西（路由表与 check），想验什么就写什么：
-// 卡片画的数从哪来，这里真的调一次 —— `check` 的十三条判据一条都不碰这条。
+// 卡片画的数从哪来，这里真的调一次 —— `check` 的十四条判据一条都不碰这条。
 
 import { readdirSync } from 'node:fs';
 import { dirname } from 'node:path';

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

@@ -6,7 +6,7 @@
 //
 // ★ 这份脚本验的是**形状**：它认不出成员名，所以换数据源、换卡片内容都不用改它。
 //   模板自己的"真读"与"真跑"在 `scripts/smoke.assert.mjs` 里：换数据源时改那一份，
-//   不要删这里的调用 —— 卡片画的数从哪来，`check` 的十三条判据一条都不碰，只有这里会真调一次。
+//   不要删这里的调用 —— 卡片画的数从哪来，`check` 的十四条判据一条都不碰，只有这里会真调一次。
 //
 // 负例在最后一段：服务不在的时候必须**报出来**，不许静默通过 —— 静默的模块是最难查的那种坏。
 

package/template-diy/src/components/SetupFlow.tsx.tpl

@@ -0,0 +1,71 @@
+import { createElement as h } from 'react';
+import { kit } from '@dsh-workbench/core/client';
+
+const UNIT_ID = '__UNIT__';
+const SETUP_ROUTE = `${UNIT_ID}/setup`;
+
+const { SetupShell, TextField } = kit.components;
+const { useUnitSetup } = kit.hooks;
+
+interface SetupPayload {
+  readonly configured?: boolean;
+  readonly values?: { readonly name?: string };
+}
+
+export interface SetupFlowProps {
+  readonly t: (key: string) => string;
+  readonly path: string;
+  readonly onDone: () => void;
+}
+
+export function SetupFlow({ t, path, onDone }: SetupFlowProps): ReturnType<typeof h> {
+  const setup = useUnitSetup({
+    steps: [
+      {
+        id: 'name',
+        title: t(`${UNIT_ID}.setup.title`),
+        render: (ctx) =>
+          h(TextField, {
+            value: String(ctx.values['name'] ?? ''),
+            placeholder: t(`${UNIT_ID}.setup.namePlaceholder`),
+            disabled: ctx.busy,
+            onChange: (event) => {
+              ctx.setValues({ ...ctx.values, name: event.target.value });
+            },
+          }),
+        submit: async (values) => {
+          const response = await kit.api.apiPost<{ ok: boolean }>(SETUP_ROUTE, {
+            path,
+            name: String(values['name'] ?? ''),
+          });
+          return response.ok ? { ok: true } : { ok: false, message: response.error.message };
+        },
+      },
+    ],
+    read: async () => {
+      const response = await kit.api.apiGet<SetupPayload>(SETUP_ROUTE, { path });
+      if (!response.ok) return { configured: false, values: {} };
+      return {
+        configured: response.configured === true,
+        values: { name: response.values?.name ?? '' },
+      };
+    },
+    onReady: () => {
+      onDone();
+    },
+  });
+  return h(SetupShell, {
+    setup,
+    labels: {
+      back: t(`${UNIT_ID}.setup.back`),
+      next: t(`${UNIT_ID}.setup.next`),
+      finish: t(`${UNIT_ID}.setup.finish`),
+      save: t(`${UNIT_ID}.setup.save`),
+      saving: t(`${UNIT_ID}.setup.saving`),
+      cancel: t(`${UNIT_ID}.setup.cancel`),
+      reading: t(`${UNIT_ID}.setup.reading`),
+      failed: t(`${UNIT_ID}.setup.failed`),
+    },
+    renderHome: () => null,
+  });
+}

package/template-diy/src/messages.ts.tpl

@@ -24,6 +24,16 @@ export const messages = {
     '__UNIT__.prefsLabel': '最大的几个文件',
     '__UNIT__.prefsHint': '这个选择按项目存（刷新还在）；只影响卡片显示，不改读到的数据',
     '__UNIT__.prefsUnit': ' 个',
+    '__UNIT__.setup.title': '显示名',
+    '__UNIT__.setup.namePlaceholder': '给这个模块起个显示名',
+    '__UNIT__.setup.back': '上一步',
+    '__UNIT__.setup.next': '下一步',
+    '__UNIT__.setup.finish': '完成',
+    '__UNIT__.setup.save': '保存',
+    '__UNIT__.setup.saving': '保存中',
+    '__UNIT__.setup.cancel': '取消',
+    '__UNIT__.setup.reading': '正在读配置…',
+    '__UNIT__.setup.failed': '读不到配置',
   },
   en: {
     '__UNIT__.cardTitle': 'Directory overview',
@@ -50,5 +60,15 @@ export const messages = {
     '__UNIT__.prefsLabel': 'Largest files shown',
     '__UNIT__.prefsHint': 'Stored per project (survives refresh); affects display only, not the data',
     '__UNIT__.prefsUnit': '',
+    '__UNIT__.setup.title': 'Display name',
+    '__UNIT__.setup.namePlaceholder': 'Give this module a display name',
+    '__UNIT__.setup.back': 'Back',
+    '__UNIT__.setup.next': 'Next',
+    '__UNIT__.setup.finish': 'Finish',
+    '__UNIT__.setup.save': 'Save',
+    '__UNIT__.setup.saving': 'Saving',
+    '__UNIT__.setup.cancel': 'Cancel',
+    '__UNIT__.setup.reading': 'Reading config…',
+    '__UNIT__.setup.failed': 'Cannot read config',
   },
 };