@dsh-workbench/core 0.3.10 → 1.0.0-beta.0

package/scripts/seed-profile.sh

@@ -6,7 +6,7 @@
 #
 # **设置不在这里继承**（这里曾经把 web 的 cordis.patch.yml 快照一份过来）：
 # 工作台自己的 patch 是唯一真相，想搬 web 的哪几行由用户走「设置 → 配置同步」。
-# 为什么这么分（安装 vs 设置）、为什么不再是自动的：.scratch/config-sync/spec.md
+# 为什么这么分（安装 vs 设置）、为什么不再是自动的：内部设计记录
 #
 # 幂等 / 可续跑：profile 已存在就跳过创建，隔离层已存在就跳过追加
 # —— 重复运行不会覆盖任何东西。
@@ -23,8 +23,11 @@ set -euo pipefail
 
 DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
 PROFILE="${WORKBENCH_PROFILE:-workbench}"
-SRC_PROFILE="$DSH_HOME/profiles/web"
+SRC_PROFILE_NAME="${WORKBENCH_SOURCE_PROFILE:-web}"
+SRC_PROFILE="$DSH_HOME/profiles/$SRC_PROFILE_NAME"
 DST_PROFILE="$DSH_HOME/profiles/$PROFILE"
+WORKBENCH_HOME="${DSH_WORKBENCH_HOME:-$DSH_HOME/$PROFILE}"
+export DSH_WORKBENCH_HOME="$WORKBENCH_HOME"
 PKG='@dsh-workbench/core'
 REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 GIT_TOP="$(git -C "$REPO_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
@@ -93,8 +96,10 @@ if [ "${1:-}" = "ensure-selected" ]; then
   exit 0
 fi
 
-[ -f "$SRC_PROFILE/package.json" ] ||
-  die "找不到 $SRC_PROFILE —— 请先跑一次 'dsh web'，让 web profile 落地。"
+HAS_SOURCE=0
+if [ -f "$SRC_PROFILE/package.json" ]; then
+  HAS_SOURCE=1
+fi
 [ -f "$ISOLATION" ] || die "找不到 $ISOLATION"
 
 DST_PATCH="$DST_PROFILE/cordis.patch.yml"
@@ -107,8 +112,8 @@ DST_PATCH="$DST_PROFILE/cordis.patch.yml"
 if [ -f "$DST_PROFILE/package.json" ]; then
   echo "→ profile '$PROFILE' 已存在，跳过创建"
 else
-  echo "→ 创建 profile '$PROFILE'（模板: web）"
-  dsh "$PROFILE" --from-default-profile web --dump-config >/dev/null
+  echo "→ 创建 profile '$PROFILE'（模板: ${SRC_PROFILE_NAME}）"
+  dsh "$PROFILE" --from-default-profile "$SRC_PROFILE_NAME" --dump-config >/dev/null
 fi
 
 [ -f "$DST_PATCH" ] || die "profile 缺少 $DST_PATCH"
@@ -119,8 +124,10 @@ fi
 # 改过（例如启用了某个可选 bundle）。所以这里把 web 清单里的 bundles
 # 并进来，同时保留 workbench 自己已有的额外项（例如 @dsh-workbench/core），
 # 使脚本可重复运行。
+if [ "$HAS_SOURCE" = "1" ]; then
 WB_MANIFEST="$DST_PROFILE/package.json" \
   WEB_MANIFEST="$SRC_PROFILE/package.json" \
+  WB_SOURCE_NAME="$SRC_PROFILE_NAME" \
   node -e '
 const fs = require("node:fs");
 const read = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
@@ -137,15 +144,18 @@ wb.dsh = Object.assign({}, wb.dsh, {
   profile: Object.assign({}, webProfile, wbProfile, { bundles: merged }),
 });
 fs.writeFileSync(process.env.WB_MANIFEST, JSON.stringify(wb, null, 2) + "\n");
-console.log("→ 已继承 web 的 bundle 列表: " + merged.join(", "));
+console.log("→ 已继承 " + process.env.WB_SOURCE_NAME + " 的 bundle 列表: " + merged.join(", "));
 '
+else
+  echo "→ 本机还没有来源 profile '$SRC_PROFILE_NAME'；用 dsh 出厂模板的 bundle 列表（如需继承它的设置/插件，先跑一次来源 profile）"
+fi
 
 # ── 第 2.5 步：修掉旧版启动器留下的"装出来的那份被当成仓库副本" ──────────
 #
 # 旧判据只问 `git rev-parse --show-toplevel`（"**某个祖先**是不是仓库"），于是包目录落在任何
 # 仓库里的机器（最常见：`$HOME` 是 dotfiles 仓库，而 npm/nvm 的前缀就在 `$HOME` 下）在 setup
-# 时会把**全局安装目录**以 `link:` 装进 profile —— 市场里工作台那一行因此说「这份是本仓正在
-# 开发的那一份，不从源上取。」（不比对源、不提示更新），而 `npm i -g …@latest` 还会悄悄换掉
+# 时会把**全局安装目录**以 `link:` 装进 profile —— 市场里工作台那一行因此打上「本地」标
+# （不比对源、不提示更新），而 `npm i -g …@latest` 还会悄悄换掉
 # profile 跑的东西。判据窄到只认那一个坏形状：**我自己是装出来的那份**（GIT_TOP 为空）
 # **且 profile 里那条 `link:` 指着的正是我自己这份目录** —— 指别处的 link:（用户自己链的）不动。
 if [ -z "$GIT_TOP" ] && [ -f "$DST_PROFILE/package.json" ]; then
@@ -184,6 +194,7 @@ else
   printf '\n' >>"$DST_PATCH"
   cat "$ISOLATION" >>"$DST_PATCH"
   echo "→ 已追加隔离层（sessions / storages / attachments 分家）"
+  rm -f "$DST_PATCH.tmp"
 fi
 
 # ── 第 4 步：建 DIY 工坊 ────────────────────────────────────────────────
@@ -206,7 +217,8 @@ cat <<EOF
 
 profile '$DST_PROFILE' 的骨架好了（bundle 清单 + 会话/存储/附件隔离层）。
 
-设置**不在**这里继承：想要 web 那边的模型供应商 / 搜索源 / MCP，起工作台后去
+设置与本地插件按创建时的勾选从 $SRC_PROFILE_NAME 继承；直接跑 setup 时只继承
+bundle 清单，想要 web 那边的模型供应商 / 搜索源 / MCP，起工作台后去
 「设置 → 配置同步」按行勾（读的是那个 profile 的 cordis.patch.yml；搬完重启生效）。
 
 装 bundle —— 两条**等价**的路，任选一条（都走 dsh 的 runPluginCommand，装完会

package/scripts/seed-workshop.sh

@@ -20,6 +20,8 @@
 set -euo pipefail
 
 DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+WORKBENCH_HOME="${DSH_WORKBENCH_HOME:-$DSH_HOME/workbench}"
+export DSH_WORKBENCH_HOME="$WORKBENCH_HOME"
 SELF="${BASH_SOURCE[0]}"
 while [ -L "$SELF" ]; do
   SELF="$(cd "$(dirname "$SELF")" && pwd -P)/$(readlink "$SELF")"
@@ -36,8 +38,8 @@ MODE="${1:-skeleton}"
 # 仓库副本，去 link 一个不存在的 `../module-tools`，脚本当场死在 `cd` 上 —— 而它是**后台**
 # 被拉起来的（宿主自举 / 启动器），症状就是"工坊怎么都没建起来，一声不响"。
 #
-# 所以认仓库要认**本仓的形状**：根上同时有 packages/workbench 与 packages/module-tools。
-if [ -n "$GIT_TOP" ] && [ -f "$GIT_TOP/packages/workbench/package.json" ] &&
+# 所以认仓库要认**本仓的形状**：根上同时有 packages/core 与 packages/module-tools。
+if [ -n "$GIT_TOP" ] && [ -f "$GIT_TOP/packages/core/package.json" ] &&
   [ -f "$GIT_TOP/packages/module-tools/package.json" ]; then
   IN_REPO=1
 else
@@ -71,8 +73,8 @@ fi
 # 冻结接口：状态文件 $DSH_HOME/workbench/diy/.sync.json =
 #   { state: "ok"|"syncing"|"failed", version: <基准版本>, at: <ISO>, reason?: <一句话> }
 SHELL_ROOT="${DSH_WB_SHELL_ROOT:-}"
-DIY_DIR="$DSH_HOME/workbench/diy"
-SEED_LOG="$DSH_HOME/workbench/seed.log"
+DIY_DIR="$WORKBENCH_HOME/diy"
+SEED_LOG="$WORKBENCH_HOME/seed.log"
 SYNC_STATE="$DIY_DIR/.sync.json"
 SYNC_LOCK="$DIY_DIR/.sync.lock"
 SYNC_BACKOFF_SECONDS=3600
@@ -103,7 +105,7 @@ target_version() {
 }
 
 # 外壳 manifest 里钉的那份 dsh UI 版本（模块模板默认带的那个 devDependency，见
-# `.scratch/dsh-primitives-face/spec.md` §3.1）。源优先**基准**（正在跑的那份外壳），
+# `内部设计记录` §3.1）。源优先**基准**（正在跑的那份外壳），
 # 没有才退回跑脚本这份副本 —— 与 link_workshop_skills 同一条口径。
 # 读不到就留空：调用方按"不写这一项"处理（模块 `init` 那边有自己的兜底常量与一句人话）。
 shell_primitives_version() {
@@ -143,7 +145,7 @@ compute_specs() {
     SHARED_SPEC="^$version"
   fi
   # dsh 原语（模块模板默认带的那个）：**精确版**，与模块自己那份 devDependency 对齐 ——
-  # 类型面要对齐对账过的那一版（`.scratch/dsh-primitives-face/spec.md` §3.1）。
+  # 类型面要对齐对账过的那一版（`内部设计记录` §3.1）。
   # 空 = 读不到外壳 manifest，就**不写这一项**（模块 `init` 有自己的兜底常量）。
   local primitives_version
   primitives_version="$(shell_primitives_version)"
@@ -286,9 +288,7 @@ sync_lock_stale() {
 
 # 强行清锁：只给"判定持锁者已崩"那条路用（那时锁已经不是原主的了）。
 drop_sync_lock() {
-  case "${SYNC_LOCK:-}" in
-    */workbench/diy/.sync.lock) rm -rf "$SYNC_LOCK" ;;
-  esac
+  if [ "${SYNC_LOCK:-}" = "$WORKBENCH_HOME/diy/.sync.lock" ]; then rm -rf "$SYNC_LOCK"; fi
 }
 
 # 抢锁的返回值：0 = 抢到；1 = 同一代的人正装着（跳过）；2 = 这地方建不出锁；3 = 另一代正装着、等过一轮没抢到。
@@ -346,13 +346,11 @@ stop_sync_heartbeat() {
 
 # 只删**自己的**锁：锁被清过 / 换了主人时，这里必须放手（否则新持锁者的 install 被砍在半路）。
 release_sync_lock() {
-  case "${SYNC_LOCK:-}" in
-    */workbench/diy/.sync.lock)
-      if [ -n "${SYNC_LOCK_TOKEN:-}" ] && [ "$(lock_field owner)" = "$SYNC_LOCK_TOKEN" ]; then
-        rm -rf "$SYNC_LOCK"
-      fi
-      ;;
-  esac
+  if [ "${SYNC_LOCK:-}" = "$WORKBENCH_HOME/diy/.sync.lock" ]; then
+    if [ -n "${SYNC_LOCK_TOKEN:-}" ] && [ "$(lock_field owner)" = "$SYNC_LOCK_TOKEN" ]; then
+      rm -rf "$SYNC_LOCK"
+    fi
+  fi
 }
 
 # sync：幂等、可重跑、可续。**复核过才写 ok**。
@@ -529,15 +527,15 @@ fi
 # 转发脚本而不是软链：同 `bin/opencli-isolated` 那条坑 —— pnpm publish 之后包里的脚本没有 x 位，
 # 软链过去一执行就是 Permission denied。x 位由 chmod 当场给。
 # ⚠️ 先 rm -f：旧版本留下的软链还在时，`>` 会顺着软链把真脚本覆盖掉。
-ENTRY_DIR="$DSH_HOME/workbench/bin"
+ENTRY_DIR="$WORKBENCH_HOME/bin"
 mkdir -p "$ENTRY_DIR"
 rm -f "$ENTRY_DIR/dsh-wb-module"
 cat >"$ENTRY_DIR/dsh-wb-module" <<EOF
 #!/bin/sh
-BIN="$DSH_HOME/workbench/diy/node_modules/.bin/dsh-wb-module"
+BIN="$WORKBENCH_HOME/diy/node_modules/.bin/dsh-wb-module"
 if [ -x "\$BIN" ]; then exec "\$BIN" "\$@"; fi
 if command -v pnpm >/dev/null 2>&1; then
-  exec pnpm --dir "$DSH_HOME/workbench/diy" exec dsh-wb-module "\$@"
+  exec pnpm --dir "$WORKBENCH_HOME/diy" exec dsh-wb-module "\$@"
 fi
 echo "dsh-wb-module: 工坊的依赖还没装 —— 先跑 dsh-workbench setup" >&2
 exit 127

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

@@ -1,150 +1,79 @@
-# 实现参考（DIY 域）：把模块造成一个独立包
+# 实现：落点、模板、命令、两个面
 
-本文只管"怎么落"：工坊、骨架、文件、命令、两个面。接上外壳与交付（依赖 / 禁区 / 装 / 热换 / 发布）
-在 [WIRING.md](WIRING.md)。设计口径看 [DESIGN.md](DESIGN.md) 与 [STEPS.md](STEPS.md)；
-门禁红了看 [REVIEW.md](REVIEW.md)。
+只管怎么落。依赖 / 安装 / 热换 / 发布见 [WIRING.md](WIRING.md)；需求见 [DESIGN.md](DESIGN.md) / [STEPS.md](STEPS.md)；
+门禁见 [REVIEW.md](REVIEW.md)。
 
-## 0 一个模块就是一个独立的 dsh 插件包
+## 0 模块结构
 
-它不是工作台源码的一部分，**不认识工作台源码**：它把自己插进 dsh 的 profile，
-外壳通过服务名 `workbenchUnits` 收下它。所以"造模块"只发生在一个目录里，不动外壳一个字节。
-
-它同时是两半：
-
-| 半 | 文件 | 跑在哪 | 干什么 |
+| 半 | 文件 | 运行于 | 职责 |
 |---|---|---|---|
-| 宿主半侧 | `src/host.ts` → `dist/host.js` | Node（dsh 宿主进程） | 注册服务、路由、agent 工具、长任务 |
-| 浏览器半侧 | `src/client.tsx` → `client.js` | 页面里 | 画那张卡片、注册审批明细渲染器 |
+| 宿主 | `src/host.ts` → `dist/host.js` | dsh 宿主进程（Node） | 服务、路由、agent 工具、长任务 |
+| 浏览器 | `src/client.tsx` → `client.js` | 页面 | 卡片、审批明细渲染 |
 
-两侧不许互相 import。它们只通过外壳交出来的服务名相接。
+两侧不互相 import，只经服务名 `workbenchUnits` 相接。
 
-## 1 落点：工坊
+## 1 落点
 
 ```
-$DSH_HOME/workbench/diy/            ← 工坊（一个 pnpm workspace，依赖已经装好、与外壳同代）
-  package.json  pnpm-workspace.yaml  .npmrc  node_modules/
+<工作区>/                 ← `workbench_diy_status` 的 `工作区：`
+  pnpm-workspace.yaml     ← 包声明
   packages/
-    module-<unit>/                  ← 你要造的模块住这儿
+    module-<unit>/
 ```
 
-一个模块一个目录，一个目录一个包。**不要**把源码写到别处，也不要去动工坊根上的配置。
+工作区可以是 monorepo / 单包 / 空项目。模块必须落在会话工作区内，包目录由工作区声明
+（`pnpm-workspace.yaml` 的 `packages:`、`package.json` 的 `workspaces`，或根本身即包）。不改工作区根配置。
 
-⚠️ **骨架不在就先补上**：启动器会自愈（少了才建），没建起来时跑一次 `dsh-workbench setup`（幂等）
-再回来跑模块命令 —— 没有骨架时门禁会把"模块不在任何 workspace 里"讲成"声明写错了"，那是症状。
-工具链跟外壳**不同代**时不用你管：**每一次工作台启动**都会拿"正在跑的那份外壳"（基准经
-`DSH_WB_SHELL_ROOT` 显式传入）比一次，不同代就在后台把它同步到同代 —— 所以升级之后
-**下一次启动**就对上了（`workbench_diy_status` 里能看到「⏳ 工坊工具链正在后台同步到 <版本>」，
-或同步没成时的「⚠️ 工坊工具链还是上一代（…）：<原因>」加一条修法；同步那几行在
-`$DSH_HOME/workbench/seed.log`）。
+⚠️ 无可放代码的包（无 `package.json` 或未声明 workspace）→ 问用户：在此建 workspace，还是去工坊脚手架工作区。
+不改用户仓库为 monorepo。从「造一个模块」进入的会话已在工坊，`<dir>` 即工坊。
+工具链与外壳不同代不用处理：启动时比对并后台同步（`workbench_diy_status` 有状态）。
 
-工坊里的 `@dsh-workbench/*` **只有一份**（工坊根的 `link:` + 一份 `pnpm.overrides` 钉着）：模块自己的
-`pnpm build` / `pnpm exec dsh-wb-module` 和工坊根的 `.bin/dsh-wb-module` 是同一个二进制，
-`check --only kit` 比的也是用户**真正在跑**的那份外壳。别在模块里另装一份——两代并存是静默的
-（你会在模块里看到旧模板、旧报错，而工坊根那份什么都说得好好的）。
+模块内的 `pnpm build` / `pnpm exec dsh-wb-module` 与工作区根同一二进制，不要在模块里另装（会静默出现两代）。
 
-## 2 从模板改，不从零写
+## 2 从模板开始
 
 ```bash
-pnpm exec dsh-wb-module init <unit> --dir <工坊>/packages/module-<unit> --template diy --description "<一句话>"
+pnpm exec dsh-wb-module init <unit> --dir <工作区>/packages/module-<unit> --template diy --description "<一句话>"
 ```
 
-`<unit>` 是小写短横线标识（如 `my-thing`），它同时是单元 id、包名后缀、卡片样式前缀。
-**它必须全局唯一** —— 和工作台里其它模块、和外壳里已有的单元都不能撞；撞了装上去当场抛。
-
-生成的骨架是**能直接跑的**（十三条判据 + 六个脚本开箱全绿；门禁还在，模板改坏了当场报）。
+`<unit>`：小写短横线，同时是单元 id、包名后缀、样式前缀；全局唯一（与已装模块、外壳单元冲突时装配抛错）。
+骨架开箱即绿（十三条判据 + 六脚本）。
 
-**两个模板，按需要挑**（加 `--template <名字>`）：
-
-| 模板 | 是什么 | 什么时候用 |
+| 模板 | 内容 | 适用 |
 |---|---|---|
-| `minimal`（不写就是它） | 空壳：卡壳、文案、测试都接好了，但**没有数据源** | 你已经清楚要读什么、想从零写 |
-| `diy` | 一张**读当前项目的样板卡**：宿主侧一条真读目录的只读路由、卡片五态（待机 / 加载 / 就绪 / 就绪但空 / 出错） | 你要照着改出一个"真能出数据"的最小版本 —— **建议先用它** |
-
-⚠️ `diy` 那份是**给别人照抄的**，所以它自己也必须开箱全绿 —— 门禁会**两个模板各 init 一遍、各跑一遍全套**。
+| `minimal`（默认） | 空壳：卡壳、文案、测试；无数据源 | 已明确读什么 |
+| `diy` | 样板卡：宿主一条只读路由 + 五态 | 需要可运行的数据样板（推荐） |
 
-骨架是**分层多文件**的（不是单文件）：目录**按需要出现** —— 空壳可以只有 `components/`，
-有状态逻辑才需要 `model/`（`diy` 两样都有，`minimal` 不硬造 `model/`）。骨架里的文件各有其职
-（`minimal` 是空壳那几份，`diy` 多一份 `design.json`、`src/model/`、`src/components/OverviewCard.test.ts` 与 `types/styles.d.ts`，见下面那张 ⚠️）：
+骨架分层：`src/model/**`（纯逻辑）、`src/components/**`（视图 + 同目录 `*.module.css`）、
+`src/messages.ts`、`src/host.ts`、`src/client.tsx`、`scripts/smoke.mjs`、`design.json`。
+模板原文可直接读。非显然项：
 
-| 文件 | 职责 |
+| 文件 | 要点 |
 |---|---|
-| `package.json` | 自述清单：包名、`dsh.bundle.patch`、`dsh.client`（`external` 默认带 `@dsh-workbench/core/client` 与 dsh 原语那行）、`dsh.workbench.unit`、`dsh.workbenchFaces{host,client}`（工具链字段，门禁必填）、六个脚本、peer 依赖；原语那行由 `init` 盖精确版（[KIT.md](KIT.md) §8） |
-| `arch.config.mjs` | 模块自己的**架构方言**：**只有一行**工厂调用 `moduleArch()`（从 `@dsh-workbench/module-tools/arch` 来）。层序表 / 两个运行时 / 阈值只有那一份，随工具链同代 |
-| `eslint.config.mjs` | 模块自己的**语法卫生方言**：**只有两行** —— `moduleLint({ rootDir: import.meta.dirname })`（从 `@dsh-workbench/module-tools/lint` 来；`rootDir` 把 tsconfig 根钉在这个模块上，多份配置并存时 typescript-eslint 才猜得出）。规则 / ignores 只有那一份，随工具链同代；要放行某条就从 `moduleLint({ rules, ignores })` 开口子，别改方言那些块（判据比整份 8 块，逐块点名），也别手写一份自己的（自己 import 方言再照抄整份则分不出来） |
-| `cordis.patch.yml` | 把自己插进 profile 的那一行 |
-| `src/model/**` | 纯逻辑：类型、换算、状态机（`diy` 是 `overview.ts` + 配对测试）。两个运行时都能读，不碰 react / kit / dsh / `node:*` |
-| `src/components/**` | 浏览器侧的视图件，**样式与它同目录**（`X.module.css`；`diy` 是 `OverviewCard.tsx`）。整片算 client 面，宿主侧碰不得 |
-| `src/host.ts` | 宿主面：`manifest` + `mount()`（路由 / 工具）；类型从 `src/model/` 引，同一个概念不留两处真相 |
-| `src/client.tsx` | 浏览器面：`manifest` + `card` —— **只剩面**（注册 + 把 props 交给 `components/` 那个组件） |
-| `src/messages.ts` | zh / en 文案；键必须带 `<unit>.` 前缀，两种语言同构 |
-| `src/plugin.test.ts` | 单测：两侧都把自己的面注册进了外壳（`diy` 还多一条宿主路由） |
-| `src/components/X.test.ts` | 组件自己的渲染断言（`diy` 把 `OverviewCard` 的五态各画一遍拆在这儿。**测试文件不吃方言的 S16「文件 200 行」**（2026-10-19 起内置豁免，后缀式与 `__tests__/` 两种命名都算），所以并回一个文件也不会红 —— 拆开只为读着顺） |
-| `vitest.config.ts` | 测试配置（`@/modules/<unit>/` 的别名） |
-| `scripts/smoke.mjs` | `selfcheck`：把 `client.js` 当浏览器加载器跑一遍，看卡片真进没进外壳 |
-| `tsconfig.json` | `paths` 里 `@/modules/<unit>/*` → `./src/*`，值必须是**相对路径** |
-| `types/globals.d.ts` | 经典 JSX 运行时的全局类型垫片 |
-| `types/styles.d.ts` | CSS Modules 的类名表声明（`declare module '*.module.css'`）。`globals.d.ts` 顶层有 import、是模块，那里的 `declare module` 会变成模块增强而不是环境声明 —— 用了 `X.module.css` 就必须有这一份（`diy` 有） |
-| `design.json` | 三张表 + 状态矩阵 + 数据源记录 + 验收清单（**唯一真相**；README 里那一段由它生成） |
-| `README.md` | 这个模块自己的说明 |
-
-改哪一个：**画什么改 `src/components/*.tsx` + 它同目录的 `*.module.css`，纯逻辑（换算 / 状态机 / 类型）
-改 `src/model/**`，文案改 `src/messages.ts`；`src/client.tsx` 只留注册那一层**，需要能力再动 `src/host.ts`。
-模板已经把组件套好了外壳的卡壳（`kit.components.Card`）、三态与测试；你只改里面。
-**宿主侧不许 import `src/components/**`** —— 那是跨运行时，`arch` 判据当场红（层号拦不住它：
-components 第 2 层、host 第 10 层）。
-
-⚠️ **三张表落在 `design.json`**（`diy` 骨架自带一份填好的，`minimal` 里没有 —— 用它就照
-[DESIGN.md](DESIGN.md) §5 建一个）：把它改成你刚问出来的那份，**再改代码**。
-README 里 `<!-- dsh-wb:design:start/end -->` 之间那一段**由它生成**（`design render`）—— 手改会判红。
-
-## 3 命令与脚本
-
-```bash
-dsh-wb-module build                 # 出 client.js 与 dist/host.js
-dsh-wb-module check                 # 十三条判据，全跑
-dsh-wb-module check --only cards    # 单跑一条（contracts / protocol / bundles / source / arch / lint /
-                                    #   primitives / kit / cards / standalone / markers / style / alias）
-dsh-wb-module check --only primitives [--all|--json]   # 查询口：dsh 原语里有什么
-dsh-wb-module lint [--fix]          # 跑模块自己那份 eslint 配置；--fix 写回
-```
-
-三张表的填/查/生成/打勾见 [DESIGN.md](DESIGN.md) §5。
+| `arch.config.mjs` | 一行 `moduleArch()`（`@dsh-workbench/module-tools/arch`）；层序、运行时、阈值随工具链 |
+| `eslint.config.mjs` | 两行 `moduleLint({ rootDir: import.meta.dirname })`；`rootDir` 钉 tsconfig 根 |
+| `types/styles.d.ts` | 用 `X.module.css` 必须有；`globals.d.ts` 是模块，其 `declare module` 不算环境声明 |
+| `design.json` | 三张表 / 矩阵 / 数据源 / 验收；README 段由它生成（`minimal` 无此文件，按 [DESIGN.md](DESIGN.md) §5 建） |
 
-⚠️ 写成 `pnpm exec dsh-wb-module …`（工坊里 PATH 上也有同名入口，由启动器挂）；
-模块目录里更省事的是那几个脚本（`pnpm build` / `pnpm selfcheck`）。
+修改位置：视图改 `src/components/*.tsx` + 同目录 `*.module.css`；逻辑改 `src/model/**`；文案改 `src/messages.ts`；
+`src/client.tsx` 只留注册。宿主侧不 import `src/components/**`（跨运行时，`arch` 判红）。
 
-`package.json` 里那前四个脚本都要留着（契约判据会查）；`check` 是第五条（`arch` 方言的 M09 要这个脚本名）；`lint` 是第六条（`lint` 判据要它）：
+## 3 命令
 
-```bash
-pnpm build       # 构建
-pnpm typecheck   # tsc --noEmit（init 后先 pnpm install）
-pnpm test        # vitest
-pnpm selfcheck   # 构建 + 把 client.js 当加载器跑一遍（`diy` 骨架里还多一条 `design check`）
-pnpm check       # dsh-wb-module check：十三条判据
-pnpm lint        # dsh-wb-module lint：语法卫生（`pnpm lint -- --fix` 写回）
-```
+用 `pnpm exec dsh-wb-module …`；命令、`--only` 判据名与模板参数看 `--help` / `check --list`，不在指引里抄。
+`package.json` 六个脚本（`build` / `typecheck` / `test` / `selfcheck` / `check` / `lint`）必须保留，
+`contracts` 点名缺失。
 
-**自己的门禁自己过，红了别抛给用户。** 十三条判据在 [REVIEW.md](REVIEW.md) 里逐条翻了人话。
-⚠️ **`check` 不替你跑 `pnpm test`**（它只看形状与产物）：状态级的渲染、换算、边界都在你自己的
-`test` 里 —— 骨架开箱就带一份，改了数据源与渲染就顺手把它跑一遍，别让红线留在包里。
-⚠️ **工坊里恒有两条是「不适用」，那不是「通过」**：`独立构建` 要外壳源码在场才跑得起来，
-`公开包无内部标识` 只扫要发出去的包（DIY 模块一律 `private`）。汇总行下面会把
-这次没查的那几条逐条列出来；所以「8 通过 · 2 不适用」不等于十三条全绿 —— 别把这句话念给用户听。
+- `check` 不跑 `pnpm test`；状态、换算、边界测试自己跑。
+- "不适用"不是"通过"：`standalone` 需外壳源码在场，`markers` 只扫公开包（DIY 模块 `private`）。
+  汇总行会列出未检查项。
 
-装上板那一步不是命令，是一套 agent 工具：`workbench_diy_list` 看工坊里有什么、
-`workbench_diy_status`（`unit=<单元 id>`）看它现在走到哪一步、`workbench_diy_install` 装上并上板、
-`workbench_diy_show` 只上板 —— 见 §7。**上完板自己逐条走一遍（这就是验收那一拍）**：浏览器那 14 把
-（`state` / `get html` / `find` / `click` / `hover` / `type` / `fill` / `keys` / `scroll` / `wait` / `eval` /
-`screenshot` / `network` / `dialog`，argv 与结果原样转发，全表见 [FAMILY.md](FAMILY.md)）打的是
-**用户当前那一页**上工坊那块板里的那张卡 —— 用户那一页不会被换掉，但他得把工作台切到前台。
-**看屏 / 动屏那一族（浏览器那 14 把 / `logs_*`）要先 `workbench_diy_debug_start`**（`unit=…`；
-会请他点头一次）—— 没有这场约定它们一律当场拒；不看屏了先 `_pause`、收工 `_stop`。
-卡片有没有报错先看 `workbench_diy_panel` 的「崩过 / 读到了」；真要这一页的控制台，用
-`workbench_diy_logs_watch` → 做那件事 → `workbench_diy_logs_read`（钩子有上限，见 [REVIEW.md](REVIEW.md) 四步取证的 4）。
+安装 / 上板是 agent 工具：`workbench_diy_install`、`workbench_diy_show`、`workbench_diy_status`
+（[WIRING.md](WIRING.md) §3）。上板后逐条走查即验收。
 
-## 4 两个面的形状
+## 4 两个面
 
-宿主面（`src/host.ts`）：
+宿主面：
 
 ```ts
 export const name = '<包名>';
@@ -152,25 +81,20 @@ export const inject = ['workbenchUnits'];
 
 export function apply(ctx) {
   const units = ctx.get('workbenchUnits');
-  if (units === undefined) return;          // 外壳没交这个服务：报一声，别静默
+  if (units === undefined) return;
   ctx.effect(() => units.register({ manifest, mount }), '<unit>: 注册');
 }
 ```
 
-`mount()` 返回 `{ routes, registerTools, prefs? }`：
-`routes` 是交给外壳去挂 `/workbench/api/<路由>` 的只读投影（只许 GET）；
-`registerTools` 交出这个模块的 agent 工具。**路由的键必须住自己那一格**（`<unit>` 或 `<unit>/…`），
-否则装配期直接抛；只读路由要表达"出错"时回 `{ ok: false, error: { code, message, hint? } }`（HTTP 仍是 200，外壳原样转发）。
-
-浏览器面（`src/client.tsx`）：`units.registerUnit({ manifest, messages, card })`。
-`card` 拿到 `{ t, world, refreshToken, onRefresh, onSummary }`（`world.current.workspace` 就是当前项目），
-返回一棵元素树。**三态用外壳给的组件，别自己画**：
-加载 → `kit.components.SkeletonRows`；空 → `kit.components.EmptyState`（不带按钮）；
-出错 → `kit.components.BlockerState` + `kit.lib.blockerOfError(error, t)`。
-⚠️ **`idle` 是独立的一格**（没工作区、或取数被 `enabled: false` 关掉时），不许画成"空" ——
-"空"和"还没开始"是两件事，说错了他会去查他根本没配的东西。
+`mount({ data })` 的 `data` 是统一数据端口（`DataReader`）；读数据用 `data.read(...)`，不要自己 import adapter。
+`mount()` 返回 `{ routes, registerTools, prefs? }`。`routes` 挂 `/workbench/api/<路由>`，只许 GET，
+键必须在 `<unit>` 或 `<unit>/…` 之下（否则装配抛错）。错误返回
+`{ ok: false, error: { code, message, hint? } }`（HTTP 200，外壳转发）。`registerTools` 提供模块工具。
 
-**卡片必须在拿不到数据时也画得出来**（第一次读、卡在审批、平台没登录）。
-任何一种输入（待机 / 在读 / 有值 / 有值但空 / 读不到）下抛异常、屏上冒出 `undefined` / `NaN` 的卡片 = 用户眼里的"卡片一直不出来"。这是 `check --only cards` 守的那条。
+浏览器面：`units.registerUnit({ manifest, messages, card })`。`card` 收到
+`{ t, world, refreshToken, onRefresh, onSummary }`（`world.current.workspace` 为当前项目），返回元素。
+三态用 kit：加载 `kit.components.SkeletonRows`；空 `kit.components.EmptyState`（无按钮）；
+错误 `kit.components.BlockerState` + `kit.lib.blockerOfError(error, t)`。
 
-→ 拿到依赖、装上、改一行、发出去：[WIRING.md](WIRING.md)。
+`idle` 是独立态（无工作区或 `enabled: false`），不画成空态。
+卡片在任意输入下不得抛异常或出现 `undefined` / `NaN`（`check --only cards`）。

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

@@ -0,0 +1,89 @@
+# 文案：先判读者
+
+一块模块同时给三种人写字：卡片给人、工具描述给 agent、原始输出给开发者。判错读者，后面全错。
+
+## 1 三类读者
+
+| 读者 | 读什么 | 判据 |
+|---|---|---|
+| **agent** | 工具描述、参数说明、返回、错误、`reason` / `{blocked}`、中断通知、`context.render` | 读完知道下一次调什么 |
+| **终端用户** | 卡片、空态、阻断、按钮、配置、审批屏、agent 的交代 | 读完知道点哪 / 要不要做，且不写代码 |
+| **开发者** | 日志、`detail`、原始输出 | 排障时能对照、能检索 |
+
+审批字段的归属容易混：
+
+| 字段 | 读者 |
+|---|---|
+| `needsApproval.question` / `fallback`、`approvalDetail` / `approval.render`、`approval_note` | 终端用户 |
+| `needsApproval.reason`（deny）、`{blocked}` | agent |
+
+## 2 两层：主句 + 原文
+
+同一处既有用户又有技术细节时，成对写：
+
+- **主句**：给人，不含错误码、路径、堆栈、内部词。
+- **原文**：给开发者，原样，放 `detail` / 折叠区 / 日志。
+
+两条判据：
+
+1. 遮住原文只读主句：用户知道发生了什么、下一步做什么。
+2. 遮住主句只读原文：开发能定位。
+
+## 3 人侧
+
+1. **可复述**：不写代码的人读完能说出下一步。
+2. **名词看得见**：用界面上的词；`unit` / 套件 / 宿主 / schema / payload / 运行时 不进主句。
+3. **一句一个意思**：不靠括号补解释，一句不放两个动作。
+4. **不露空值**：读不到就说读不到，不写 `0` / `undefined` / `NaN` / 裸键名。
+
+状态四义、时间写相对时间、单位跟数字：见 [PANEL.md](PANEL.md) §7。
+审批那一屏的写法：见 [DESIGN.md](DESIGN.md) §3 —— 标题一句，事实进详情，明细一行一个事实。
+中文与英文都写；英文重写，不直译。
+
+## 4 agent 侧
+
+**agent 自己推得出的，不写。** 工具名、参数名、schema、上一次返回已经说了的，不重复第二遍。
+
+- 删：字段清单、枚举释义、参数名复述、理由、输出里已有的话。
+- 留：写与危险、跨工具下一步与字面量、非显然的默认与上限、会误导的坑、安全事实。
+- 描述：一句“是什么” + 一句“什么时候用”；不写“这个工具用于……”。
+- 返回：事实 + 总数 / 分页 + 下一次调用；ID、版本、单位原样。
+- 错误：发生了什么 + 能不能重试 + 下一步；不甩堆栈。
+- 通知：自包含 —— 谁做了什么 + 哪件事变了 + 现在做什么。
+
+加字先减字。模块工具的提示词没有字数闸，自己守。
+
+## 5 开发侧
+
+- **原文**：日志、堆栈、命令不翻译、不美化。
+- **可检索**：保留错误码、路径、ID、时间戳。
+- **不进主句**：这些内容用户能看到时，折叠并标注“原始输出 / 堆栈 / 命令”；主句不依赖它。
+
+日志一行：目标 + 发生了什么 + 关键值原样。不写“出错了”这种没有定位信息的句子。
+
+## 6 硬规则
+
+- 读不到写读不到，不写 0。
+- 主句只放人话；错误码、路径、堆栈、内部词放原文。
+- 事实原样：ID、版本、单位、时间戳不改写、不四舍五入。
+- 不引用不存在的工具、字段、页面、命令。
+- 不写“系统内部错误 / 请稍候”这类没有信息的句子。
+
+## 7 验
+
+1. 真卡片：五态、两语各看一遍；`dsh-wb-module check --only cards` 抓 `undefined` / `NaN` / 裸键。
+2. 遮住测试两条都过。
+3. 工具：注册后读描述，逐句问“模型推得出来吗”；真调一次读返回；漏参数读报错。
+4. 拿五个用户会说的话试：只凭描述能不能挑中这把工具。
+
+## 8 例
+
+| 面 | 改前 | 改后 |
+|---|---|---|
+| 空态 | 暂无数据 | 这个环境还没有构建记录。换一个环境，或先跑一次构建。 |
+| 阻断 | 系统内部错误，请稍后重试 | 这次没读到发布记录。检查网络后重试。 |
+| 按钮 | 确定 | 发布到生产 |
+| 描述 | 用于查看构建状态的工具 | 看某个环境最近一次构建：状态、耗时、提交；用户说“发布没成功”就先调它。 |
+| 返回 | 操作成功 | 已发布 v1.2.3 到生产；下一步 `_build` 看结果。 |
+| 拒绝 | 不允许 | 这个环境是生产；先在确认条上点「发布到生产」。 |
+| 日志 | 出错了 | `[inventory] release v1.2.3 failed: HTTP 502 (retryable)` |