@dsh-workbench/core 0.3.10 → 0.3.11

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

@@ -1,150 +1,87 @@
-# 实现参考（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、包名后缀、卡片样式前缀。
-**它必须全局唯一** —— 和工作台里其它模块、和外壳里已有的单元都不能撞；撞了装上去当场抛。
-
-生成的骨架是**能直接跑的**（十三条判据 + 六个脚本开箱全绿；门禁还在，模板改坏了当场报）。
-
-**两个模板，按需要挑**（加 `--template <名字>`）：
+`<unit>`：小写短横线，同时是单元 id、包名后缀、样式前缀；全局唯一（与已装模块、外壳单元冲突时装配抛错）。
+骨架开箱即绿（十三条判据 + 六脚本）。
 
-| 模板 | 是什么 | 什么时候用 |
+| 模板 | 内容 | 适用 |
 |---|---|---|
-| `minimal`（不写就是它） | 空壳：卡壳、文案、测试都接好了，但**没有数据源** | 你已经清楚要读什么、想从零写 |
-| `diy` | 一张**读当前项目的样板卡**：宿主侧一条真读目录的只读路由、卡片五态（待机 / 加载 / 就绪 / 就绪但空 / 出错） | 你要照着改出一个"真能出数据"的最小版本 —— **建议先用它** |
+| `minimal`（默认） | 空壳：卡壳、文案、测试；无数据源 | 已明确读什么 |
+| `diy` | 样板卡：宿主一条只读路由 + 五态 | 需要可运行的数据样板（推荐） |
 
-⚠️ `diy` 那份是**给别人照抄的**，所以它自己也必须开箱全绿 —— 门禁会**两个模板各 init 一遍、各跑一遍全套**。
+骨架分层：`src/model/**`（纯逻辑）、`src/components/**`（视图 + 同目录 `*.module.css`）、
+`src/messages.ts`、`src/host.ts`、`src/client.tsx`、`scripts/smoke.mjs`、`design.json`。
+模板原文可直接读。非显然项：
 
-骨架是**分层多文件**的（不是单文件）：目录**按需要出现** —— 空壳可以只有 `components/`，
-有状态逻辑才需要 `model/`（`diy` 两样都有，`minimal` 不硬造 `model/`）。骨架里的文件各有其职
-（`minimal` 是空壳那几份，`diy` 多一份 `design.json`、`src/model/`、`src/components/OverviewCard.test.ts` 与 `types/styles.d.ts`，见下面那张 ⚠️）：
-
-| 文件 | 职责 |
+| 文件 | 要点 |
 |---|---|
-| `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 命令与脚本
+| `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 建） |
 
-```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。
-
-⚠️ 写成 `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` 写回）
+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 写回
 ```
 
-**自己的门禁自己过，红了别抛给用户。** 十三条判据在 [REVIEW.md](REVIEW.md) 里逐条翻了人话。
-⚠️ **`check` 不替你跑 `pnpm test`**（它只看形状与产物）：状态级的渲染、换算、边界都在你自己的
-`test` 里 —— 骨架开箱就带一份，改了数据源与渲染就顺手把它跑一遍，别让红线留在包里。
-⚠️ **工坊里恒有两条是「不适用」，那不是「通过」**：`独立构建` 要外壳源码在场才跑得起来，
-`公开包无内部标识` 只扫要发出去的包（DIY 模块一律 `private`）。汇总行下面会把
-这次没查的那几条逐条列出来；所以「8 通过 · 2 不适用」不等于十三条全绿 —— 别把这句话念给用户听。
+用 `pnpm exec dsh-wb-module …`。`package.json` 六个脚本（`build` / `typecheck` / `test` / `selfcheck` /
+`check` / `lint`）必须保留，`contracts` 点名缺失。
+
+- `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 +89,19 @@ 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()` 返回 `{ 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` 看结果。 |
+| 拒绝 | 不允许 | 这个环境是生产；先在确认条上点「发布到生产」。 |
+| 日志 | 出错了 | `[cmdb] release v1.2.3 failed: HTTP 502 (retryable)` |

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

@@ -1,130 +1,102 @@
-# 数据从哪来：干净机器上先用 opencli 探，再把它固化成一条读
+# 数据源：探一条读，再固化
 
-用户往往只说"我要看发布情况""我想看缺陷看板" —— 他不知道那套系统叫什么、接口在哪、要什么参数。
-干净机器上你也没有现成的 skill 可抄。所以这一步是**探查**，不是查手册。
+用户只说"我要看 X"，不提供接口。干净机器上没有现成 skill。步骤是探查，不是查手册。
 
-## 先判：这是 DIY 域还是工程域
+## 判域
 
-| 情况 | 判 |
+| 情况 | 域 |
 |---|---|
-| 他已经在浏览器里登录过那套系统 | **DIY 域** —— 用 opencli 复用他的登录去探（下面四步） |
-| 要**新凭据**（新账号 / 密钥 / token） | **工程域** —— 停下来，说清要谁去配什么 |
+| 用户已在浏览器登录过该系统 | DIY：用 opencli 复用登录探（下文四步） |
+| 要新凭据（账号 / 密钥 / token） | 工程：停，说清谁配什么 |
 
-判的是「**要不要新凭据**」，不是「要不要接新平台」。复用已有登录的探查，正是把一大类需求留在 DIY 域的原因。
-其余几类（本地文件 / 已有命令 / 不要凭据的 GET → 直接造；新服务 / 新依赖 / 改外壳 → 工程域）：[DESIGN.md](DESIGN.md) §0 那张全表。
+判据是"要不要新凭据"，不是"要不要接新平台"。其余类型见 [DESIGN.md](DESIGN.md) §0。
 
 ## 四步
 
-1. **问出他在看什么（用他的词）** —— "你平时是在哪个网页 / 哪个软件里看这个的？" 记下他说的入口。
-   **不要**问"你们用 argocd 还是 jenkins" —— 他多半不知道，也答不上来。
-2. **数据从哪来 —— 四层，从上往下试**（**用户不知道 opencli 是什么，这一整步是你的活**：
-   别问他"你用哪个插件 / 有没有 API"，他说的是"我想看 X"，把 X 翻成关键词是你的活）。
-
-   ① **先看 opencli 自带的**：`workbench_diy_recon`（`keyword=<站点名 / 系统名 / 域名>`，
-      也可以直接给 `url` 让它取域名）。它回这台机器上**已经能用**的能力：站点、命令、`strategy`
-      （PUBLIC / COOKIE / INTERCEPT / UI）以及**要不要用户的 Chrome 登录**，还有能直接照抄的那一行。
-      **有就直接复用：不用装、不用点头。** 官方那份发现指引：`opencli skills read opencli-usage`。
-      - **命中了要看全**：一个词常常翻出好几组（打 `arxiv` 会同时带出 `hf`、`semanticscholar`），
-        只看第一组就会漏掉能互补的命令（引用数、相关推荐那类）；
-      - **挑的时候优先 `public`**：不用他的 Chrome、不用登录、不用点头，卡也最容易验；
-        `cookie` / `ui` / `intercept` 的先把"他有没有登录"这件事摆到明面上。
-      - **一张卡背后可以有多条读**（甚至跨站点）：design.json 用 `reads: [ … ]` 一条一行写全，
-        每条各自的"参数 / 凭据 / 没登录长什么样 / 超时长什么样"都别省 —— 卡片上要按条给失败态。
-   ② **再看这台机器另装的插件**：recon 会一并列出来（另一面是 `opencli plugin list`）。用
-      `opencli <插件> <命令>`，参数用 `--help` 看 —— 也可以 `workbench_diy_spec`（`command='<site> <name>'`）
-      一次问全：它把 `--help -f json` **原样**回（插件与内置都能问）。
-   ③ **官方有、这台机器没有** → 才考虑装：社区插件 `opencli plugin install github:user/repo`、
-      外部 CLI `opencli external install <名字>`，或在模块清单里声明 `manifest.env.plugins`
-      （`installSource`：npm 包 / git / 本地）。**装是这台机器上的持久变更、而且会跑别人的代码 → 要用户
-      点头**，优先内网或官方源。
-   ④ **都没有** → 才自己开发，而且两条官方流程都能用：
-      - 只读一次 → 下面那条 `probe`；
-      - 想长期用 → 给这个站点写 adapter：`opencli skills read opencli-adapter-author`（侦察 → 字段解码 →
-        写 → verify）；以后 adapter 失效：`opencli skills read opencli-autofix`。
-
-   **④ 才轮到探** —— 用工具：`workbench_diy_eval`（`read=<那套系统的地址>, args=["<一段回 JSON 的脚本>"]`；
-   页面里没有接口就给 `css=<选择器>`，走的是同一条固定 DOM 读，`{entries:[{text}]}` 直接回给你）。
-   它用**用户浏览器里现有的登录**去读，并把"读不到"归一成阻断屏认的那几个码 —— 两拍（不在站点上就自己
-   打开 `url` 再读一遍）、刚重启时的重试、平台码到阻断码的映射**都在工具里**，不用你记。
-   目标是找到**承载数据的那一处**：列表页本身，或它背后的那一个 XHR。记下：URL、需要的参数、凭据从哪来。
-   要手工看别的东西（列请求、点页面）时才直接用 `opencli`。
-   - **不知道数据在哪**时先跑一条侦察脚本（`script`）：`performance.getEntriesByType('resource')`
-     里筛 `/api/`、`.json` —— 有一串就是**接口读**（顺它去 fetch）；一条都没有、页面上却有一整块
-     表格 / 列表，那就是 **DOM 读**（换 `css` 读它）。这个判断一次就够，别反复试。
-   - 手工用 `opencli` 时记住：**它随工作台预装**（隔离运行时在 `$DSH_HOME/workbench/opencli/`，
-     启动体检自己装，**不碰**用户本机的 `~/.opencli`）；没装好时它会自己说"opencli 的隔离运行时
-     还没装好" —— 把体检那屏的原话转给用户，别硬编 URL 猜（那正是"看起来能用、其实读不到"的来源）。
-   - 脚本的三条约定（工具就按这个判）：不在站点上回 `{ ok: false, code: "not-on-site" }`；登录过期回
-     `{ ok: false, code: "not-logged-in" }`（工具归一成 `auth-required`）；成功回 `{ ok: true, ...数据 }`。
-   - **`browser network --detail` 在会话里拿不到 body**：捕获缓存写在会话可写根之外
-     （`EPERM … opencli/home/.opencli/cache/browser-network`），只能列请求 key，`--detail` 永远
-     `cache_missing`。换这条：`opencli browser <session> eval "<一段 fetch 脚本>"` —— 在页面里用
-     他的登录去读，返回 JSON。它既能当探数的手段，也常常**直接就是那条固化读**。
-   - **新 session 的 `eval` 会静默开一个 `about:blank` 标签页**（不是报错）—— 它落在 opencli 自己的后台容器窗里，不抢焦点、也不进用户当前窗。所以"读之前先判在不在
-     那个站点"必须写在脚本第一行：`if (location.origin !== "https://…") return { ok: false, code: "not-on-site" }`。
-     固化读的完整形状是**两拍**：不在站点上 → `open` 那个页 → 等一会儿（约 1 秒）再 eval 一遍。
-     每一拍都由 shared 的 `backgroundLine` 拼（前缀 `env OPENCLI_WINDOW=background`）—— 别绕开它直接拼
-     `opencli browser …`：漏一拍就是把用户的 Chrome 顶到面前一次。
-   - **读自己一条会话，屏是另一条 —— 这两条不许同名**。`browserRead` / `browserFind` 的默认会话是
-     `BROWSER_READ_SESSION`（`workbench-read`）；`BROWSER_SCREEN_SESSION`（`workbench`）是
-     **工坊看/动族给"用户当前那一页"上租约**用的那条。两条同名的后果是"一读就把用户那一页导航走"
-     （`open` 那一拍落在租约那个标签上）—— 2026-10-19「套餐余额」卡片一挂载就跳 `/wallet` 就是这个。
-     想给自己一条专线（不跟别的模块抢同一个 tab）就传自己的名字：`session: "<unit>"`。
-   - **页面里没有接口时（DOM 读）不要用 `eval` 去 `document.querySelectorAll`**：产物边界判据会拦
-     （宿主产物里不许出现 `document.` / `window.` 字样），而且那样解析只能窝在字符串里、测不了。
-     探的时候 `workbench_diy_find`（`read=…, args=["--css", "<选择器>"]`）就是这个口子；
-     固化时走 `browserFind`，它内部用的就是 `opencli browser <session> find --css '<选择器>' --limit N --text-max M`，
-     回 `{ entries: [{ text, tag, nth }] }` —— **一行的单元格按换行拼在 `text` 里**（`美元\n668.3\n…`），
-     所以"切格 + 按列序取值"是两个纯函数，能单测。很多公开站点一条 XHR 都不发，就该走这条。
-   - **工作台刚重启时桥还没起来**：第一次读会以"命令跑不起来"失败（不是"数据读不到"）——
-     等一秒再读一次就好。超时**不**重试：那已经等满了。这条与上面两条一样，`browserRead` 里都写好了。
-3. **试一条最小读** —— 先证明"能拿到"，再写模块：
-   - 拿得到结构化输出 → 记下字段形状
-   - 要登录但已过期 → 记下"未登录"长什么样
-   - 超时 / 被墙 → 记下这两种失败的形状
-   这一步的产出是**一条可重复的命令或请求**，不是"我探过了"。
-4. **固化进模块** —— 先把它照抄进 `design.json`（只有一条读写 `datasource{}`；一条卡有好几条读写 `reads[]`，一条一行；字段一样：哪条读 / 参数 / 凭据 /
-   没登录长什么样 / 超时长什么样 / 当初那次调用的原文），再写进模块的**宿主半侧**：用 `@dsh-workbench/shared/host` 导出的
-   `browserRead({ shell, script, url, loginUrl })`（**接口读**：探明的那一段脚本原样搬进去就行 ——
-   两拍、重试、平台码映射、`message` / `hint` / `detail` / `helpUrl` 四个字段都在它里面；
-   会话不传就落在读那条上，想给自己一条专线再传 `session: "<unit>"`）或
-   `browserFind({ shell, css, url, session })`（**DOM 读**：它替你问"现在停在哪一页"（`browser get url`），
-   不在就 `open` 再读一遍，失败时把 opencli 自己说的原因带出来），或者只读路由里的一个 HTTP GET。之后卡片只依赖**这一条**；渲染怎么改都不动它。
-
-   这一步只管**读**。要 agent 真去**改**东西（提交 / 发布 / 建单 / 改配置），那半边走 [WRITES.md](WRITES.md)。
-
-`opencli` 是**侦察兵，不是日常通道**：探明之后，日常读必须是一条固定的、便宜的、能解释的调用。
-
-## 固化时一并写掉三态
-
-拿不到数据是常态（第一次读、登录过期、站点改版、接口超时）。卡片**必须**画得出来：
-
-| 情况 | 卡片说什么 |
+1. **问入口** —— "你平时在哪个网页 / 软件里看这个？"记下入口。不问"用 argocd 还是 jenkins"。
+   把用户的需求翻成站点 / 系统关键词是你的工作。
+
+2. **按四层找数据**：
+
+   ① **opencli 自带**：`workbench_diy_recon`（`keyword=<站点 / 系统 / 域名>`，或 `url` 取域名）。
+   返回可用能力：站点、命令、`strategy`（PUBLIC / COOKIE / INTERCEPT / UI）、是否需要用户 Chrome 登录、
+   可直接复用的命令。**命中即复用，不装不审批。** 官方发现指引：`opencli skills read opencli-usage`。
+   一个词可能带出多组（如 `arxiv` 带 `hf`、`semanticscholar`），看全。优先 `public`；`cookie` / `ui` /
+   `intercept` 先确认用户登录状态。一张卡可有多条读（可跨站点）：`design.json` 用 `reads[]` 一条一行，
+   每条写参数 / 凭据 / 未登录 / 超时，卡片按条给失败态。
+
+   ② **这台机器另装的插件**：recon 一并列出（或 `opencli plugin list`）。参数用 `--help`，或
+   `workbench_diy_spec`（`command='<site> <name>'`）取 `--help -f json` 原文（插件与内置均可）。
+
+   ③ **官方有、这台机器没有** → 安装：`opencli plugin install github:user/repo`、`opencli external install <名>`，
+   或模块清单 `manifest.env.plugins`。安装改这台机器且执行第三方代码 → 需用户审批；优先内网或官方源。
+
+   ④ **都没有** → 开发：一次性探用下文的 eval；长期用写 adapter（`opencli skills read opencli-adapter-author`，
+   失效用 `opencli-autofix`）。
+
+   **探**：`workbench_diy_eval`（`read=<地址>, args=["<回 JSON 的脚本>"]`；无接口给 `css=<选择器>`，
+   走固定 DOM 读，返回 `{entries:[{text}]}`）。它复用用户浏览器登录，并把失败归一成阻断屏错误码；
+   两拍、重启重试、平台码映射都在工具内。目标：找到承载数据的位置（列表页或其后的 XHR），
+   记 URL、参数、凭据来源。
+
+   - 不知道数据在哪：先跑 `performance.getEntriesByType('resource')`，筛 `/api/`、`.json`。
+     有 → 接口读；无但页面有整块表格 → DOM 读。判断一次即可。
+   - `opencli` 随工作台预装（隔离运行时 `$DSH_HOME/workbench/opencli/`，启动体检安装，不碰 `~/.opencli`）。
+     未装好时工具会报"隔离运行时还没装好"；转述原文，不猜 URL。
+   - 脚本约定：不在站点 → `{ ok: false, code: "not-on-site" }`；登录过期 → `{ ok: false, code: "not-logged-in" }`
+     （工具归一为 `auth-required`）；成功 → `{ ok: true, ...数据 }`。
+   - 新 session 的 `eval` 会静默开 `about:blank`（后台容器窗，不抢焦点）。脚本第一行判断
+     `location.origin`；不在站点则 `open` 该页，等约 1 秒再 eval。两拍都用 shared 的 `backgroundLine`
+     拼（前缀 `env OPENCLI_WINDOW=background`），不要直接拼 `opencli browser …`。
+   - 读与屏用不同会话：`browserRead` / `browserFind` 默认 `workbench-read`；`workbench` 是看 / 动族的
+     屏会话。同名会把用户的页导航走。需要独立标签就传 `session: "<unit>"`。
+   - DOM 读不要在 `eval` 里 `querySelectorAll`：宿主产物禁止 `document.`，且无法单测。探时用
+     `workbench_diy_find`（`read=…, args=["--css", "<选择器>"]`）；固化用 `browserFind`
+     （`find --css … --limit N --text-max M`，返回 `{ entries: [{ text, tag, nth }] }`；
+     一行单元格按换行拼在 `text` 内，"切格 + 按列取值"做成两个纯函数）。
+   - 工作台刚重启时桥未就绪：首次读报"命令跑不起来"，等一秒重读；超时不重试。
+
+3. **试一条最小读** —— 先证明能拿到，再写模块。记录：结构化字段形状；未登录长什么样；超时 / 被墙的形状。
+   产出必须是一条可重复的命令或请求。
+
+4. **固化进模块** —— 先写入 `design.json`（单读 `datasource{}`；多读 `reads[]` 一条一行；字段：
+   哪条读 / 参数 / 凭据 / 没登录 / 超时 / 当时调用原文），再写宿主半侧：用 `@dsh-workbench/shared/host` 的
+   `browserRead({ shell, script, url, loginUrl })`（接口读；两拍、重试、错误码映射、`message` / `hint` /
+   `detail` / `helpUrl` 内置；不传 `session` 用读会话）或 `browserFind({ shell, css, url, session })`（DOM 读；
+   自动判断当前页、必要时 `open`），或一个只读 HTTP GET。卡片只依赖这一条。
+   写操作走 [WRITES.md](WRITES.md)。
+
+`opencli` 是**侦察兵，不是日常通道**：探明后，日常读必须是一条固定、便宜、可解释的调用。
+
+## 三态
+
+拿不到数据是常态。卡片必须画得出：
+
+| 情况 | 文案 |
 |---|---|
-| 没登录 / 凭据过期 | "去 XX 登录一下"（可点，指到他平时那个入口） |
+| 没登录 / 凭据过期 | "去 XX 登录一下"（可点，指到用户常用入口） |
 | 超时 / 网络不通 | "这次没读到，稍后重试" + 重试 |
-| 站点改版、字段没了 | "读到的形状和预期不一样"（别显示空白，也别显示 0） |
+| 站点改版、字段缺失 | "读到的形状和预期不一样"；不显示空白、不显示 0 |
 
-任何一种输入（待机 / 在读 / 有值 / 有值但空 / 读不到）下抛异常、屏上冒出 `undefined` / `NaN` 的卡片 = 用户眼里的"卡片一直不出来"。这条 `check --only cards` 会拦（见 [REVIEW.md](REVIEW.md)）。
+任何输入（待机 / 在读 / 有值 / 空 / 读不到）下抛异常或出现 `undefined` / `NaN` 的卡片都会让用户认为"卡片不出来"。
+`check --only cards` 拦这条（[REVIEW.md](REVIEW.md)）。
 
-## 错误码不是随便写的（阻断屏按它换文案）
+## 错误码
 
-外壳的阻断屏只认下面这几个码，`helpUrl` 才是把"重试"变成"去登录"的那一步。平台自己回什么码
-（例：`AUTH_UNAUTHORIZED`）**别直接透传**，先映射到这张表里的一个：
+平台码（如 `AUTH_UNAUTHORIZED`）先映射，不透传：
 
-| 你回的 code | 用户看到 |
+| code | 用户看到 |
 |---|---|
-| `auth-required` + `helpUrl` | "需要登录 XX" + 一颗**去登录** + 一颗**重试**（`helpUrl` 缺了就只剩重试） |
-| `cli-timeout` | **一条细提示**（不换整卡）+ 重试 |
-| `cli-exec-failed` | 整卡换成"读不到" + 重试，`hint` 写清他该去确认什么 |
-| `permission-denied` + `helpUrl` | "没有权限" + 打开权限页 + 重试 |
-| 其它 | 整卡换成你给的 `message` + 重试 |
+| `auth-required` + `helpUrl` | "需要登录 XX" + 去登录 + 重试（无 `helpUrl` 只剩重试） |
+| `cli-timeout` | 细提示（不换整卡）+ 重试 |
+| `cli-exec-failed` | 整卡"读不到" + 重试；`hint` 写清确认什么 |
+| `permission-denied` + `helpUrl` | "没有权限" + 权限页 + 重试 |
+| 其他 | 整卡显示 `message` + 重试 |
 
-三个字段各有各的位置：`message` 是标题、`hint` 是下面那句能照做的话、`detail` 是折叠起来的原始
-输出 —— 写全了用户才知道"这一屏为什么长这样、下一步点哪"。
+字段位置：`message` 标题、`hint` 可照做的一句、`detail` 折叠的原始输出。
 
-## 你自己的门禁会查
+## 门禁
 
-- 数据源写在**宿主半侧**，卡片只消费它的返回；
-- 只读路由出错时回 `{ ok: false, error: { code, message, hint? } }`（HTTP 仍是 200，外壳原样转发）；
-- 验收时把「正常 / 空 / 出错」三条路都走一遍 —— 真机上造不出来的那几条，写清**怎么才能真看到**（换个空目录、换个不存在的路径那种），并在模块自己的 `plugin.test.ts` 里把这几态各喂一遍。
+- 数据源在宿主半侧；卡片只消费返回。
+- 只读路由错误返回 `{ ok: false, error: { code, message, hint? } }`（HTTP 200，外壳转发）。
+- 验收走正常 / 空 / 出错三条路；真机造不出的状态写清如何触发，并在 `plugin.test.ts` 各喂一遍。