@dsh-workbench/module-tools 1.1.12 → 1.1.14-beta.0

package/template-diy/README.md.tpl

@@ -2,11 +2,12 @@
 
 `__UNIT__` 模块：一个独立的 dsh 插件包，只认外壳的服务名，不认识外壳源码。
 
-这份是 **DIY 模板**（`--template diy`）生成的骨架：一张**读当前项目目录的只读卡**，
-数据从宿主侧**真读**一个目录算出来（`node:fs`），不是一个写死的样板。
+这份是 **唯一模板**（`--template diy`，也是默认）生成的骨架：一张**读当前项目目录的只读卡**，
+数据从宿主侧**真读**一个目录算出来（`node:fs`），另带一条**能跑**的流程 / 长任务 / 真工具 /
+动作通道样板；不是一个写死的样板。
 
 ```bash
-dsh-wb-module init <unit> --dir <目录> --template diy   # 生成这份骨架（默认模板是没有数据源的空壳）
+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   # 十三条可以单跑
@@ -17,8 +18,8 @@ dsh-wb-module check --only cards   # 十三条可以单跑
 ```bash
 pnpm build        # 构建产物
 pnpm typecheck    # tsc --noEmit
-pnpm test         # vitest：路由真读数 + 卡片五态
-pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍 + 调一次 <unit>/overview 看它真读盘
+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` 永不动手）
 ```
@@ -31,89 +32,84 @@ pnpm lint         # dsh-wb-module lint（`--fix` 就地改文件；`check` 永
 —— 要改三张表就改 `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 -->
-### 表 1 面板：他看什么、他能自己配什么
-
-| 这一格 | 一眼能得出什么结论 | 点一下可以去哪 |
-|---|---|---|
-| 这个目录占了多少空间 | 该不该清、谁在占 | （本骨架没有外链；要加就把目标写这儿） |
-
-| 能自己配的 | 管什么 | 默认是什么 | 可选值从哪来 | 选错了会怎样 |
-|---|---|---|---|---|
-| 列几个最大的文件 | 明细长度 | `5` | `1..50` | 夹回范围内，不报错 |
-
-状态矩阵（每种状态：他看到什么 / 他能做什么 / agent 能接着做什么）——
-图号对着下面「卡片画哪五态」那一节：
-
-| # | 状态 | 他看到什么 | 他能做什么 | agent 能接着做什么 |
-|---|---|---|---|---|
-| A | 待机（没选项目） | 「先打开一个项目」，不发请求 | 去左栏开一个项目 | 说清"要先有项目" |
-| B | 加载 | 「正在读目录」 | 等 | —— |
-| C | 就绪 | 路径 + N 文件 / M 目录 / 总字节 + 最大的几个 | 刷新 | 读一次这一格（联动见表 3） |
-| D | 就绪但空 | 「这个目录是空的」 | 换一个目录 | 同上 |
-| E | 读不到 | 读不到这个目录 + 宿主的原话 | 重试 / 改路径 | 同上 |
-
-### 表 2 agent：他能替用户做什么、哪几件要点头
-
-| 能力 | 一句话 | 传什么 / 拿回什么（贴真实调用与返回） | 要点头吗 | 点头时他看到的"会发生什么" |
-|---|---|---|---|---|
-| （这份骨架故意没有能力：`dsh.workbench.tools` 是空的。要加就照这张表填，只读的不点头、动东西的要点头） | | | | |
-
-### 表 3 联动：agent 动完，这个模块哪一格变
-
-| 谁在动 | 面板什么时候变 | 哪一格变（投影 + 最窄那个参数） | 用户看到什么 |
-|---|---|---|---|
-| agent 读一次这一格 | 读完立刻 | 本单元那条只读投影（`__UNIT__/overview`），只带这个目录 | 那一格变成 agent 看到的那份数 |
-| agent 只预览 / 只说了句话 | 不动 | —— | 面板没变 |
-| 用户自己按刷新 | 立刻 | 同上 | 转一下，然后是新值 |
-
-### 数据源探明记录
-
-`opencli` 只是**侦察兵**：探明之后固化成**一条**读，日常只走这一条
-（这条就是 `src/host.ts` 里那个数据源）。改数据源时先改这张表，再改代码。
-
-| 项 | 值（照抄，别转述） |
-|---|---|
-| 哪条读（命令 / URL） | 本机目录本身：`readdirSync(path)` + `statSync`（不走网络、不要凭据） |
-| 参数（缺省 / 范围 / 上限） | `path` 必填（卡片给当前项目）；`limit` 默认 `5`，夹在 `1..50` |
-| 凭据从哪来 | 不需要 |
-| 没登录 / 凭据过期时是什么样 | 不适用（本机读盘，没有登录这回事） |
-| 超时 / 连不上时是什么样 | 路径不存在 / 没权限 / 不是目录 → HTTP 200 + `ok:false`，码 `overview-unreadable` |
-| 当初探明用的那次调用（原文） | `node -e "require('node:fs').readdirSync(process.cwd())"` |
-
+（这一段由 `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` | 本模块的架构方言，**只有两行**（`import { moduleArch }` + `export default moduleArch()`）—— 层序表 / 两个运行时 / 阈值只有 `@dsh-workbench/module-tools/arch` 那一份，随工具链同代 | — |
+| `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/overview.test.ts` | 模型层的配对测试（有 `src/model/**` 就必须有 —— `arch` 的 M08） | 99 |
+| `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/components/OverviewCard.tsx` | 卡片：`Card` 壳 + 五态（待机 / 加载 / 就绪 / 出错，其中"就绪但空"单列一态）+ 最大的几个文件 | 2 |
+| `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/OverviewCard.test.ts` | 这张卡五态各画得出来（测试跟着被测的东西住） | 99 |
-| `src/host.ts` | 宿主面：`readOverview()`（真读目录）+ 一条只读路由 `<unit>/overview`；类型从 `./model/overview` 引 | 10 |
+| `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/plugin.test.ts` | 面注册 + 路由真读的断言 | 99 |
-| `scripts/smoke.mjs` | 接线自检：卡片进没进外壳、路由真读没真读 | — |
+| `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.ts` 的 `readOverview(path, limit)`：
+宿主侧，`src/host/overview.ts` 的 `readOverview(path, limit)`：
 
 * `readdirSync(path, { withFileTypes: true })` 数出**目录数**；
 * 每个普通文件 `statSync` 一次，累加**总字节**、记下 `name / bytes / mtime`（mtime 是 ISO 串）；
@@ -164,8 +160,8 @@ GET /api/__UNIT__/overview?path=<绝对路径>&limit=<1..50>
 ## 卡片画哪五态
 
 `src/model/overview.ts` 的 `overviewStateOf({ phase, value, error })` 是一条纯函数，
-每个分支各对应一屏（`src/model/overview.test.ts` 直接断言这条函数，
-`src/components/OverviewCard.test.ts` 再把每一屏画一遍）：
+每个分支各对应一屏（`src/model/__tests__/overview.test.ts` 直接断言这条函数，
+`src/components/__tests__/OverviewCard.test.ts` 再把每一屏画一遍）：
 
 | 态 | 什么时候 | 画什么 |
 |---|---|---|

package/template-diy/design.json.tpl

@@ -3,37 +3,35 @@
   "name": "__NAME__",
   "oneLine": "__DESC__",
   "panel": [
-    { "cell": "这个目录占了多少空间", "conclusion": "该不该清、谁在占", "link": "" }
+    { "cell": "（待填）", "conclusion": "（待填）", "link": "" }
   ],
   "states": [
-    { "key": "idle", "sees": "「先打开一个项目」，不发请求", "canDo": "去左栏开一个项目", "agentCan": "说清「要先有项目」" },
-    { "key": "loading", "sees": "「正在读目录」", "canDo": "等", "agentCan": "——" },
-    { "key": "ready", "sees": "路径 + N 文件 / M 目录 / 总字节 + 最大的几个", "canDo": "刷新", "agentCan": "读一次这一格（联动见表 3）" },
-    { "key": "empty", "sees": "「这个目录是空的」", "canDo": "换一个目录", "agentCan": "同上" },
-    { "key": "unreadable", "sees": "「读不到这个目录」+ 宿主的原话", "canDo": "重试 / 改路径", "agentCan": "同上" }
+    { "key": "idle", "sees": "（待填）", "canDo": "（待填）", "agentCan": "（待填）" },
+    { "key": "loading", "sees": "（待填）", "canDo": "（待填）", "agentCan": "（待填）" },
+    { "key": "ready", "sees": "（待填）", "canDo": "（待填）", "agentCan": "（待填）" },
+    { "key": "empty", "sees": "（待填）", "canDo": "（待填）", "agentCan": "（待填）" },
+    { "key": "unreadable", "sees": "（待填）", "canDo": "（待填）", "agentCan": "（待填）" }
   ],
   "config": [
-    { "persistence": "view", "key": "列几个最大的文件", "watches": "明细长度", "default": "5", "valuesFrom": "1..50", "wrongChoice": "夹回范围内，不报错" }
+    { "persistence": "prefs", "key": "（待填）", "watches": "（待填）", "default": "（待填）", "valuesFrom": "（待填）", "wrongChoice": "（待填）" }
+  ],
+  "capabilities": [
+    { "name": "__UNIT___run", "oneLine": "（待填）", "shape": "（待填）", "approval": "不点头（只读）" },
+    { "name": "__UNIT___add_note", "oneLine": "（待填）", "shape": "（待填）", "approval": "点头（写本模块笔记）" }
   ],
-  "capabilities": [],
   "linkage": [
-    { "who": "agent 读一次这一格", "when": "读完立刻", "whatChanges": "本单元那条只读投影（__UNIT__/overview），只带这个目录", "userSees": "那一格变成 agent 看到的那份数" },
-    { "who": "agent 只预览 / 只说了句话", "when": "不动", "whatChanges": "——", "userSees": "面板没变" },
-    { "who": "用户自己按刷新", "when": "立刻", "whatChanges": "同上", "userSees": "转一下，然后是新值" }
+    { "who": "（待填）", "when": "（待填）", "whatChanges": "（待填）", "userSees": "（待填）" }
   ],
   "datasource": {
-    "read": "本机目录本身：readdirSync(path) + statSync（不走网络、不要凭据）",
-    "params": "path 必填（卡片给当前项目）；limit 默认 5，夹在 1..50",
-    "credentials": "不需要",
-    "notLoggedIn": "不适用（本机读盘，没有登录这回事）",
-    "timeout": "路径不存在 / 没权限 / 不是目录 → HTTP 200 + ok:false，码 overview-unreadable",
-    "probeCommand": "node -e \"require('node:fs').readdirSync(process.cwd())\""
+    "read": "（待填）",
+    "params": "（待填）",
+    "credentials": "（待填）",
+    "notLoggedIn": "（待填）",
+    "timeout": "（待填）",
+    "probeCommand": "（待填）"
   },
   "writes": [],
   "acceptance": [
-    { "step": "打开面板 → 看到这张卡 → 路径 + N 文件 / M 目录 / 总字节", "checked": false },
-    { "step": "换一个空目录 → 看到「这个目录是空的」（不是空白、也不是 0）", "checked": false },
-    { "step": "把 limit 调成 50 → 明细变长；调成 0 → 夹回 1，不报错", "checked": false },
-    { "step": "让 agent 读一次这一格 → 面板那一格变成同一份数", "checked": false }
+    { "step": "（待填）", "checked": false }
   ]
 }

package/template-diy/package.json.tpl

@@ -16,7 +16,7 @@
     "selfcheck": "dsh-wb-module build && dsh-wb-module design check && node scripts/smoke.mjs",
     "check": "dsh-wb-module check",
     "lint": "dsh-wb-module lint",
-    "design": "dsh-wb-module design check",
+    "design": "dsh-wb-module design",
     "prepack": "dsh-wb-module build"
   },
   "dsh": {
@@ -31,11 +31,15 @@
       "unit": "__UNIT__",
       "title": { "zh": "__UNIT__ 模块", "en": "__UNIT__ module" },
       "card": { "order": 90 },
-      "tools": [],
+      "tools": [
+        { "name": "__UNIT___run", "writes": false, "key": "run" },
+        { "name": "__UNIT___add_note", "writes": true, "key": "addNote" }
+      ],
       "host": { "inject": [] }
     },
     "workbenchFaces": { "host": "src/host.ts", "client": "src/client.tsx" }
   },
+  "dependencies": { "@dsh-workbench/shared": "__SHELL_RANGE__" },
   "peerDependencies": { "@dsh-workbench/core": "__SHELL_RANGE__", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },
   "devDependencies": {

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

@@ -0,0 +1,28 @@
+// 这份模块自己的真读断言：换数据源时改这一份，不要删 smoke.mjs 里那一整段。
+//
+// `assertModule()` 只在这里拿到真东西（路由表与 check），想验什么就写什么：
+// 卡片画的数从哪来，这里真的调一次 —— `check` 的十三条判据一条都不碰这条。
+
+import { readdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const moduleDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export async function assertModule({ check, routes, UNIT_ID }) {
+  const route = `${UNIT_ID}/overview`;
+  if (typeof routes[route] !== 'function') {
+    check(`真读路由 ${route} 还在`, false, '换数据源时把 smoke.assert.mjs 的断言一起改掉，别静默跳过');
+    return;
+  }
+
+  const answer = await routes[route](new URLSearchParams({ path: moduleDir, limit: '3' }));
+  const entries = readdirSync(moduleDir, { withFileTypes: true });
+  const files = entries.filter((entry) => entry.isFile());
+  const names = new Set(files.map((entry) => entry.name));
+
+  check('路由真读了本目录：ok，回的是这个 path', answer?.ok === true && answer?.path === moduleDir, JSON.stringify(answer?.error ?? answer?.path));
+  check('读到的文件数与真实目录一致（不是写死的）', answer?.files === files.length, `answer=${answer?.files} 实际=${files.length}`);
+  check('最大的几个文件不超过 limit，而且都是真文件', (answer?.largest?.length ?? 0) >= 1 && answer.largest.length <= 3 && answer.largest.every((one) => names.has(one.name)), JSON.stringify(answer?.largest));
+  check('读不到时回 ok:false 的 error，而不是抛', (await routes[route](new URLSearchParams({ path: `${moduleDir}/不存在的目录` })))?.ok === false);
+}

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

@@ -5,19 +5,22 @@
 // 于是"模块注册的卡片到底进没进外壳"变成一条机器判据，而不再是人的眼睛。
 //
 // ★ 这份脚本验的是**形状**：它认不出成员名，所以换数据源、换卡片内容都不用改它。
-//   下面那一段"那条只读路由真读盘"是**这份模板自己的故事**（`<unit>/overview`）：你把数据源换成
-//   别的之后，它会自动跳过并提醒你，在同一个位置补一条**你自己的**真读断言 —— 卡片画的数从哪来，
-//   `check` 的十条判据一条都不碰，只有这里会真的去调一次。
+//   模板自己的"真读"与"真跑"在 `scripts/smoke.assert.mjs` 里：换数据源时改那一份，
+//   不要删这里的调用 —— 卡片画的数从哪来，`check` 的十三条判据一条都不碰，只有这里会真调一次。
 //
 // 负例在最后一段：服务不在的时候必须**报出来**，不许静默通过 —— 静默的模块是最难查的那种坏。
 
 import { readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createFlowHost, createLongTaskHost } from '@dsh-workbench/shared/host';
 
 const PLUGIN_ID = '__NAME__';
 const UNIT_ID = '__UNIT__';
-const OVERVIEW_ROUTE = `${UNIT_ID}/overview`;
+const RUN_TOOL = `${UNIT_ID}_run`;
+const ADD_TOOL = `${UNIT_ID}_add_note`;
+const RUN_RESOURCE = `${UNIT_ID}-run`;
+const moduleDir = dirname(dirname(fileURLToPath(import.meta.url)));
 const failures = [];
 
 function check(name, ok, detail) {
@@ -62,12 +65,23 @@ function fakeKit() {
   };
 }
 
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const externals = new Set([
+  '@dsh-workbench/core/client',
+  ...(manifest.dsh?.client?.inject ?? []),
+  ...(manifest.dsh?.client?.external ?? []),
+]);
+
 function moduleRequire(name) {
   if (name === 'react') {
     // 必须是**真的元素对象**：返回 null 的话，"卡片画得出来"这类断言会永远假红。
-    return { createElement: (type, props, ...children) => ({ type, props: props ?? {}, children }) };
+    return {
+      createElement: (type, props, ...children) => ({ type, props: props ?? {}, children }),
+      useState: (initial) => [typeof initial === 'function' ? initial() : initial, () => {}],
+    };
   }
   if (name === '@dsh-workbench/core/client') return { kit: fakeKit() };
+  if (externals.has(name)) return anyStub(`require(${name})`);
   throw new Error(`模块包不该 require ${JSON.stringify(name)}：模块表里只有外壳的 seed 词与外部声明`);
 }
 
@@ -178,11 +192,79 @@ hostExports.apply({
 });
 
 check('宿主面注册进了外壳', hostFaces.length === 1, `注册了 ${hostFaces.length} 个`);
-// 给一份最小 deps：宿主面的 `mount(deps)` 会去 `deps.ctx.get('shell')` 拿服务，
-// 不给 deps 的话**任何真的用了 `mount(deps)` 的模块**都会在这里崩 —— 而那不是模块的错。
+// 给一份最小 deps：宿主面的 `mount(deps)` 会去 `deps.ctx.get('tools')` / `deps.flow` /
+// `deps.longTasks` 拿东西，少一个都可能在这里崩 —— 而那不是模块的错。
+// 这几项与外壳真正交出去的 `UnitMountDeps`（HostKit）对齐；模块要用更多成员，就在这里补。
+const registeredTools = [];
+const moduleFiles = new Map();
+function moduleStore(workspace) {
+  const at = moduleFiles.get(workspace) ?? new Map();
+  moduleFiles.set(workspace, at);
+  return {
+    read: (name) => at.get(name) ?? null,
+    write: (name, value) => {
+      at.set(name, value);
+    },
+    remove: (name) => {
+      at.delete(name);
+    },
+    list: () => [...at.keys()],
+  };
+}
+const flowHost = createFlowHost();
+const longTaskHost = createLongTaskHost({ scope: `smoke-${UNIT_ID}`, unit: UNIT_ID, bump: () => {} });
+const hostDeps = {
+  ctx: {
+    get: (name) =>
+      name === 'tools'
+        ? {
+            register(tool) {
+              registeredTools.push(tool);
+              return () => {};
+            },
+          }
+        : undefined,
+    effect: (fn) => {
+      fn();
+    },
+    provide: () => {},
+    logger: { warn: () => {} },
+  },
+  logger: { warn: () => {} },
+  manifest: { id: UNIT_ID },
+  manifests: () => [],
+  ownedUnits: () => [],
+  data: (() => {
+    const missing = async () => ({ ok: false, error: { code: 'invalid-request', message: 'smoke: 没有 DataReader' } });
+    return { read: missing, request: missing, requestMany: async () => ({}), submit: missing };
+  })(),
+  flow: flowHost,
+  sessionIdOf: () => null,
+  sessionWorkspace: () => null,
+  libInstallCommand: () => '',
+  surface: anyStub('surface'),
+  env: {},
+  store: {
+    for: (_unit, workspace) => moduleStore(workspace ?? ''),
+    machine: () => moduleStore(''),
+    scan: () => [],
+  },
+  longTasks: longTaskHost.host,
+  longTaskRuns: () => new Map(),
+  git: {
+    origin: async () => ({ kind: 'no-origin' }),
+    branch: async () => ({ kind: 'no-branch' }),
+    head: async () => ({ kind: 'no-head' }),
+  },
+  libs: {
+    load: async () => {
+      throw new Error('smoke: libs 未装');
+    },
+  },
+};
 let mounted = {};
 try {
-  mounted = hostFaces[0]?.mount({ ctx: { get: () => undefined }, logger: { warn: () => {} } }) ?? {};
+  mounted = hostFaces[0]?.mount(hostDeps) ?? {};
 } catch (error) {
   failures.push(`宿主面的 mount(deps) 抛了：${error.message}`);
 }
@@ -190,32 +272,70 @@ try {
 const routes = mounted.routes ?? {};
 const strays = Object.keys(routes).filter((key) => key !== UNIT_ID && !key.startsWith(`${UNIT_ID}/`));
 check(`每条路由都住在自己那一格（${UNIT_ID} 或 ${UNIT_ID}/…）`, strays.length === 0, strays.join(', '));
+const disposers = mounted.registerTools?.();
+check('registerTools() 交得出一份清理函数清单', Array.isArray(disposers) && disposers.length === 2);
 check(
-  'registerTools() 交得出一份清单（这份模块没有工具时是空数组）',
-  Array.isArray(mounted.registerTools?.()),
+  `工具清单里有 ${RUN_TOOL} 与 ${ADD_TOOL}`,
+  registeredTools.some((tool) => tool?.name === RUN_TOOL) && registeredTools.some((tool) => tool?.name === ADD_TOOL),
+  JSON.stringify(registeredTools.map((tool) => tool?.name)),
 );
 
-// ── 这份模板自己的故事：那条只读路由**真读了本目录** ──────────────────────
-//
-// 换了数据源的模块在这里会落到 else 那一支：**跳过**而不是假绿 —— 并且在同一条路径上提醒你
-// 补一条自己的真读断言（不然"卡片画的数从哪来"就没人验了）。
-if (typeof routes[OVERVIEW_ROUTE] === 'function') {
-  const here = dirname(dirname(fileURLToPath(import.meta.url)));
-  const answer = await routes[OVERVIEW_ROUTE](new URLSearchParams({ path: here, limit: '3' }));
-  check('路由真读了本目录：ok 且数得出文件', answer?.ok === true, JSON.stringify(answer?.error ?? answer?.path));
-  check(
-    '读到的文件数与最大的几个文件都是真的（不是写死的）',
-    answer?.files >= 1 && answer?.largest?.length >= 1,
-    `files=${answer?.files} largest=${answer?.largest?.length}`,
-  );
-  check(
-    '读不到时回 ok:false 的 error，而不是抛',
-    (await routes[OVERVIEW_ROUTE](new URLSearchParams({ path: `${here}/不存在的目录` })))?.ok === false,
-  );
-} else {
-  console.log(`○ 跳过「真读本目录」那一组：这份模块已经没有 ${OVERVIEW_ROUTE}（换过数据源了）。`);
-  console.log('  在同一个位置补上**你自己那条读**的断言 —— 卡片画的数从哪来，只有这里能真调一次。');
+// ── 模板自己的故事：流程真跑一遍，长任务最后落到 ok ──────────────────────
+const startAction = (mounted.actions ?? []).find((one) => one.resource === RUN_RESOURCE);
+check('动作通道里有起流程的入口（卡片那颗钮走的就是它）', typeof startAction?.handle === 'function');
+const started = startAction?.handle({ path: moduleDir });
+check('起一趟流程拿得到 runId', started?.ok === true && typeof started?.runId === 'string', JSON.stringify(started));
+let snapshot = started?.runId === undefined ? null : (mounted.longTasks?.snapshot(started.runId) ?? null);
+const deadline = Date.now() + 5000;
+while (snapshot !== null && snapshot.status === 'running' && Date.now() < deadline) {
+  await new Promise((resolve) => {
+    setTimeout(resolve, 20);
+  });
+  snapshot = mounted.longTasks?.snapshot(started.runId);
 }
+check('流程整条跑到 ok', snapshot?.status === 'ok', String(snapshot?.status));
+check(
+  '流水里有「读目录」',
+  (snapshot?.steps ?? []).some((step) => step.includes('读目录')),
+  (snapshot?.steps ?? []).join(' | '),
+);
+
+// ── 写通道：笔记（动作通道 + 写工具）+ 审批；配置按工作区存 ──────────────
+const NOTES_ROUTE = `${UNIT_ID}/notes`;
+const PREFS_ROUTE = `${UNIT_ID}/prefs`;
+const NOTE_RESOURCE = `${UNIT_ID}-add-note`;
+const noteTool = registeredTools.find((tool) => tool?.name === `${UNIT_ID}_add_note`);
+const noteDecl = (manifest.dsh?.workbench?.tools ?? []).find((tool) => tool?.name === `${UNIT_ID}_add_note`);
+check('写工具注册上了，清单里也声明成 writes: true（壳才会走审批）', noteTool !== undefined && noteDecl?.writes === true);
+check(
+  '写工具要点头，审批屏说得出会写什么',
+  mounted.needsApproval?.({ name: `${UNIT_ID}_add_note`, arguments: { text: 'x' } })?.kind === 'ask' &&
+    typeof mounted.approvalDetail?.({ name: `${UNIT_ID}_add_note`, arguments: { text: 'x' } })?.zh === 'string',
+);
+const noteAction = mounted.actions?.find((one) => one.resource === NOTE_RESOURCE);
+const noteAdded = noteAction?.handle({ path: moduleDir, text: 'smoke 记的一条' });
+check('动作通道能写一条笔记（点击即确认）', noteAdded?.ok === true, JSON.stringify(noteAdded?.error));
+const notesAnswer = await routes[NOTES_ROUTE](new URLSearchParams({ path: moduleDir }));
+check(
+  '笔记读得回来，且就是刚写的那条',
+  notesAnswer?.ok === true && notesAnswer?.notes?.some((one) => one.text === 'smoke 记的一条'),
+  JSON.stringify(notesAnswer?.notes),
+);
+const prefsBefore = await routes[PREFS_ROUTE](new URLSearchParams({ path: moduleDir }));
+check('配置默认是 5', prefsBefore?.prefs?.limit === 5, JSON.stringify(prefsBefore?.prefs));
+const prefsWrote = mounted.prefs?.handle({ workspace: moduleDir, limit: 10 });
+const prefsAfter = await routes[PREFS_ROUTE](new URLSearchParams({ path: moduleDir }));
+check(
+  '配置按工作区存得住（写 10 后读回 10）',
+  prefsWrote?.prefs?.limit === 10 && prefsAfter?.prefs?.limit === 10,
+  JSON.stringify(prefsAfter?.prefs),
+);
+const otherPrefs = await routes[PREFS_ROUTE](new URLSearchParams({ path: `${moduleDir}/src` }));
+check('另一个工作区没被带上（还是默认 5）', otherPrefs?.prefs?.limit === 5, JSON.stringify(otherPrefs?.prefs));
+
+// ── 这个模块自己的真读断言：换数据源时改 scripts/smoke.assert.mjs ──────────
+const { assertModule } = await import('./smoke.assert.mjs');
+await assertModule({ check, routes, mounted, UNIT_ID });
 
 // ── 需求底稿在不在：这份骨架的"设计记录"住 README，别只留在对话里 ──────────
 //