@dsh-workbench/core 0.3.10 → 0.3.11

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

@@ -1,113 +1,74 @@
 ---
 name: workbench-module-diy
-description: 在工作台里凭需求造一个模块（面板上的一块内容 + 它背后的能力）—— 用在「我想在面板上看到 X / 加一块卡」「让 agent 替我读或写某个东西」「agent 动完面板哪一格跟着变」这类话上。用户只说需求，实现由 agent 自己做、自己过门禁、自己在真卡片上逐条验过，最后给他一个能点开看的东西。
+description: 在工作台里把当前面板调明白，或者给它造一块新内容 —— 用在「这块板为什么空白 / 这张卡不对 / 它到底发了什么」「我想在面板上看到 X / 加一块卡」「让 agent 替我读或写某个东西」这类话上。用户只说需求，实现由 agent 自己做、自己验过。
 ---
 
-# 造一个工作台模块：他说需求，你做完自己验过再交给他
+# workbench-module-diy
 
-交付物是**面板上能点开的一块内容**，不是一份要他读的技术方案。
+| 触发 | 任务 | 前置 |
+|---|---|---|
+| 「这块板空白 / 这张卡不对 / 数据不对 / 它到底发了什么」 | 调：查现有面板 | `workbench_diy_panel` / `_status`；动屏要调试约定 |
+| 「我想在面板上看到 X / 加一块卡」 | 造：新建模块 | 一个能放代码的包（没有就问用户） |
 
-## 七步
+调交付"面板现在怎么样"的事实；造交付面板上能点开的一块内容。不交技术方案。
 
-1. **判域** —— 先读 [DESIGN.md](DESIGN.md) §0。不是所有需求都该在这里做；判完给他**一句人话 + 下一步**。
-2. **问三张表** —— 见 [STEPS.md](STEPS.md)。只问他看得见、能决定的事；**实现一律不问**。
-   这一步的产出是 ASCII 画面 + 三张表，不是文字。三张表当场落进模块里的 `design.json`
-   （命令与形状：[DESIGN.md](DESIGN.md) §5）—— 只留在对话里等于没定。
-3. **先定数据从哪来** —— [DATASOURCE.md](DATASOURCE.md)：干净机器上没有现成 skill 可抄，
-   用 `workbench_diy_eval` / `_find` 带 `read=<站点地址>`（跑在 `workbench-read` 上）复用他的登录去探 —— 没在站点上我自己开一次，`not-logged-in` / `not-on-site` 两条码按读线约定归一
-   都在那把工具里；探明后**固化成一条读**（`@dsh-workbench/shared/host` 的 `browserRead`）。顺手把三态写掉。
-   要 agent **真去改东西**（提交 / 发布 / 建单 / 改配置）的，读完 [WRITES.md](WRITES.md) 再动手：
-   四步（现成写命令 → 入参 / 出参来源 → 没有预览档的不许试写 → 写完后回读确认）。
-   有写工具就**顺手把审批屏那一屏也画进图里**（[DESIGN.md](DESIGN.md) §3 末尾那节 + KIT.md §3）：
-   标题一句 + `ApprovalPlan` 详情表 —— 那两格的形状是固定的（仓内 ADR-0065，这份指引不链仓内路径）。
-4. **从模板改** —— [BUILD.md](BUILD.md) §1–§2：在工坊里 `dsh-wb-module init` 一个骨架，
-   把 `design.json` 里的**三张表与数据源记录先改成你问出来的那份**（`design check` 会点名叫出还空着哪一格），
-   再改数据源与渲染。
-   **不从零写**。
-   命令写成 `pnpm exec dsh-wb-module …`（工坊里 PATH 上也有同名入口，但 `pnpm exec` 到处都对）。
-   `init` 完先在工坊里跑一次 `pnpm install`：模板默认带了 dsh 原语那个 devDependency
-   （[KIT.md](KIT.md) §8），不装 `pnpm typecheck` 会报"找不到模块"。
-5. **自己过门禁** —— `dsh-wb-module build` + `check` + `design check`；
-   红了自己修（[REVIEW.md](REVIEW.md) 有对照），不抛给他、也不贴报错给他看。
-6. **装上、上板** —— `workbench_diy_install`（`unit=<单元 id>`）装上：
-   它只认工坊里造好的那个模块，装完顺手在**这个项目**的面板上打开（装的是这台机器上的东西；**这一步不问审批**，见 [WIRING.md](WIRING.md) §3 —— 别对他说"请你点一下确认"，那一拍不会出现）。
-   **这一跳永远只走一次**：之后只重建、不重装（宿主侧秒级热换；改了 client.js 刷新一下页面）。
-   拿不准它现在走到哪一步（装了没 / 面板认得没 / 这个项目上开着没 / 产物齐不齐 / 源码比产物新没），
-   就问工具：`workbench_diy_status`（`unit=<单元 id>`）会把这几件事一次说清并给出下一步 ——
-   **别自己拼，也别再装一遍**；已经装过只是想上板，用 `workbench_diy_show`。
-7. **自己验收** —— 逐条对着三张表，在**真卡片**上走「打开哪 → 看什么 → 点什么 → 应该看到什么」。
-   要看 / 动**他那一屏**（浏览器那 14 把 + `logs_*`）得先开约定：
-   `workbench_diy_debug_start`（`unit=…`；会请他点头一次，他会被告知「调试中请留在那一屏」）——
-   **没有这场约定，上面那一族一律当场拒**；不看屏了先 `workbench_diy_debug_pause`，收工 `…_stop`。
-   （`workbench_diy_panel` / `_status` 不碰他那一屏，不用开；`_find` / `_eval` 带 `read=` 时也**不碰** —— 那走只读线。）
-   走法（全表与参数在 [FAMILY.md](FAMILY.md)）：
-   - **这一张卡长什么样**：`workbench_diy_screenshot`（要卡那一块就先 `eval` 量盒子、填 `clip`）+
-     `workbench_diy_html`（`--as json` 给结构树）；
-   - **元素与语义**：`workbench_diy_find`（`--css '$card …'`、或 `--role` / `--name`）、`workbench_diy_state`；
-   - **动手**：`workbench_diy_click` / `_hover` / `_type` / `_fill` / `_keys` / `_scroll` / `_wait`。
-     吃 CSS 的那几把有 `scope`（默认 `page`，`card` 才是这张卡里）；portal 出来的那一层（下拉 / 菜单 /
-     模态）要用 `scope: 'page'` + `--role menuitem` 按名字点；
-   - **派生读数**（对比度 / 被裁 / 可见文本）：`workbench_diy_eval`（`in: 'card'` 注入卡根 `root`，脚本自己 `return`）；
-   - **那一次读的收发包**：`workbench_diy_network`（`--follow` 臂上 → 做那件事 → `--detail <key>` 取 body）；
-   - **控制台**：`workbench_diy_logs_watch` → 做那件事 → `workbench_diy_logs_read`。
+## 流程
 
-   这些工具的参数**原样转发**给 opencli、返回体也是它的原样 —— 不知道某个子命令收什么，就
-   `args: ['<verb>', '--help']` 问它；事实在 `stdout` 里（`ok` 只管进程）。
-   哪一条不对，**先取证再改**（`workbench_diy_panel` 一次看清面板上每张卡是读到了、读不到还是崩了；
-   四步取证见 [REVIEW.md](REVIEW.md)），改完再走**同一处**。
-   逐条都走通了，再 `dsh-wb-module design accept` 把验收打勾（**没走通的不许打勾**；走不通的如实说没验过）。
-   审批那一格是**他的**：模块里要用户点头的写能力，得他真用一次时点 —— 你代不了，清单里写清
-   「这条要你真用一次」，别打勾说验过。
-   验完把结论告诉他：**装好了、面板上哪一格**（不用请他逐条点头 —— 他随时能自己点开看；
-   他说哪不对，回到同一处取证再改）。不给他看 diff、日志、代码。
+**0. 认路** —— 跑 `workbench_diy_status`，取 `工作区：<dir>`。
 
-## 每个问题都带推荐答案
+**调** —— 用 [REVIEW.md](REVIEW.md) 的四步取证。动屏前 `workbench_diy_debug_start`（`unit` 可省）。
+抓"点了之后发了什么"：`workbench_diy_record_prepare` → 用户操作 → `_record_read`；收工 `_debug_stop` / `_record_stop`。
+不需要源码、工具链、工坊。
 
-他一个字就能过（"就这样"）。他不确定就按推荐走并标出来，别卡住。
-必须他拍板的决定，翻译成"**你会看到什么**"再问，不问"用 A 还是 B"。
+**造** —— 模块落 `<dir>`。那里没有能放代码的包（没 `package.json`，或有但没声明 workspace）时，问用户二选一：
+在这里建 workspace，还是去工坊那个脚手架工作区。不改用户仓库结构。
+从「造一个模块」进入的会话已在工坊里，`<dir>` 就是工坊。
 
-## 知识索引
+1. **判域** —— [DESIGN.md](DESIGN.md) §0。输出一句结论 + 下一步。
+2. **问三张表** —— 问法见 [STEPS.md](STEPS.md)；只问用户能决定的事，实现不问。ASCII 画面 + 三张表当场写进
+   `design.json`（[DESIGN.md](DESIGN.md) §5）。
+3. **定数据源** —— [DATASOURCE.md](DATASOURCE.md)：探明后固化成一条读（`browserRead` / `browserFind`），写三态。
+   写操作先读 [WRITES.md](WRITES.md) 四步；有写工具就把审批屏画进 ASCII（[DESIGN.md](DESIGN.md) §3 末节）。
+4. **套模板** —— [BUILD.md](BUILD.md) §1–§2：`pnpm exec dsh-wb-module init <unit> --template diy`，
+   先把 `design.json` 改成问出来的那份，再改数据源与渲染。init 后 `pnpm install`。不从零写。
+   改渲染时文案按 [COPY.md](COPY.md)：先判读者（卡片给人 / 描述给 agent / 原始输出进 detail）。
+5. **过门禁** —— `dsh-wb-module build` + `check` + `design check`；红了自己修（[REVIEW.md](REVIEW.md)），
+   不把报错贴给用户。
+6. **装、上板** —— `workbench_diy_install`（`unit=…`）。只装一次；之后 `dsh-wb-module build` 即可。
+   状态不明问 `workbench_diy_status`（`unit=…`）；只缺上板用 `workbench_diy_show`。装不问审批。
+7. **验收** —— 对着三张表在真卡片上走「打开哪 → 看什么 → 点什么 → 应该看到什么」。
+   看 / 动屏前 `workbench_diy_debug_start`（否则整族拒）；`_panel` / `_status` / `read=` 档不用。
+   工具全表 [FAMILY.md](FAMILY.md)。走通才 `dsh-wb-module design accept`；走不通如实记"未验"。
+   审批项标注「要你真用一次」，不打勾。结论只报：已装、在面板哪一格。
 
-| 什么时候读 | 读哪份 |
-|---|---|
-| 判这个需求该不该在这里做 | [DESIGN.md](DESIGN.md) §0 |
-| 两条分工、三张表、怎么用 ASCII 跟他说话 | [DESIGN.md](DESIGN.md) |
-| 步骤 1 / 2 / 3 各自问什么、什么时候算做完 | [STEPS.md](STEPS.md) |
-| **数据从哪来**（干净机器上怎么找到那一条读） | [DATASOURCE.md](DATASOURCE.md) |
-| **要 agent 真去改东西**（提交 / 发布 / 建单 / 改配置：写通道四步） | [WRITES.md](WRITES.md) |
-| 面板上该有什么、状态矩阵怎么写、界面习惯 | [PANEL.md](PANEL.md) |
-| **要做什么 → 用哪件 kit → 最小写法**（照抄面） | [KIT.md](KIT.md) |
-| **kit / dsh 原语里到底有什么、某一件怎么用**（DIY 会话里直接调这把工具） | `workbench_diy_components`（`name=Button` 回它的类型文件与声明；工程域用 `check --only kit` · `--only primitives`）· [KIT.md](KIT.md) §8 |
-| **kit 那些 hook 怎么搭**（四个场合、一格卡片怎么拼） | [KIT.md](KIT.md) §4′（逐件的 API 看 `.d.ts` 的 JSDoc 或 `workbench_diy_components`） |
-| 能力怎么划、传什么拿回什么、哪几件要点头 | [TOOLS.md](TOOLS.md) |
-| **工坊会话里那 33 把的全表**（枚举 opencli 的 14 把 + 看/装/探 + 调试约定 + 录制交接、参数与如实边界） | [FAMILY.md](FAMILY.md) |
-| agent 动完面板哪一格变、他正在干的时候看哪儿 | [LINKAGE.md](LINKAGE.md) |
-| 落点、文件形状、命令、两个面 | [BUILD.md](BUILD.md) |
-| 依赖、会被拦的写法、装、热换、发布 | [WIRING.md](WIRING.md) |
-| 门禁红了、装上去没反应、改完没热换 | [REVIEW.md](REVIEW.md) |
-| 用户说"卡片不对 / 一片空白 / 一直转圈"（四步取证） | [REVIEW.md](REVIEW.md) 那一节 · `workbench_diy_panel`（``） |
-| 哪条纪律已经固化成工具、哪些还留给 agent | [TOOLING.md](TOOLING.md) |
+## 索引
 
-## 找不到一件事的时候，按这个顺序找
+| 需要 | 读 |
+|---|---|
+| 判域、分工、三张表、ASCII 规则 | [DESIGN.md](DESIGN.md) |
+| 三步的问法、产出、完成判据 | [STEPS.md](STEPS.md) |
+| 探测数据源、固化读、错误码 | [DATASOURCE.md](DATASOURCE.md) |
+| 写通道四步、回读、撤销 | [WRITES.md](WRITES.md) |
+| 面板内容、状态矩阵、界面规则 | [PANEL.md](PANEL.md) |
+| 选 kit 组件、表单、hooks | [KIT.md](KIT.md) |
+| agent 能力、审批、长任务、外部供给 | [TOOLS.md](TOOLS.md) |
+| 文案：三类读者、主句 / 原文、人 / agent / 开发 | [COPY.md](COPY.md) |
+| DIY 工具族的参数与返回 | [FAMILY.md](FAMILY.md) |
+| 面板何时刷新、事实名 | [LINKAGE.md](LINKAGE.md) |
+| 落点、模板文件、命令、两个面 | [BUILD.md](BUILD.md) |
+| 依赖、禁区、安装、热换、发布 | [WIRING.md](WIRING.md) |
+| 门禁报错、卡片故障取证 | [REVIEW.md](REVIEW.md) |
+| 哪些检查已固化成命令 | [TOOLING.md](TOOLING.md) |
 
-1. **先跑门禁**：`dsh-wb-module check --only <那一条>` 的报错原文最准。
-   「外壳的 kit 里到底有什么组件 / hooks」「dsh 原语里有什么、某一件怎么用」在工坊会话里直接调
-   `workbench_diy_components`（不填给清单，`name=Button` 回它的类型文件与声明）；工程域用
-   `check --only kit` · `check --only primitives`（`--all` 全表、`--json` 机器档）。
-2. **再看模板**：已经有一个同形状、能跑的最小实现，比任何描述都准 ——
-   在你工坊的 `node_modules/@dsh-workbench/module-tools/template-diy/`（带真数据源的样板）
-   与 `template/`（空壳）里，原文都是可读的。
-3. **最后看你装的那份外壳**：`node_modules/@dsh-workbench/core/dist/types/**` 是它的类型面，
-   `node_modules/@dsh-workbench/core/skills/workbench-module-diy/**` 就是这份指引。
-   它的 README 与 `docs/HANDOFF.md` / `docs/OPERATIONS.md` 也在包里。
+## 查不到时
 
-⚠️ **你手上就是这两份**：工坊会话里够得到的是 `node_modules/@dsh-workbench/…` ——
-外壳与 `dsh-wb-module` 都在那儿；别处没有。
+1. `dsh-wb-module check --only <判据>` 的报错原文。
+2. kit / dsh 原语：`workbench_diy_components`（DIY 会话）；工程域 `check --only kit` / `--only primitives`。
+3. 模板：`node_modules/@dsh-workbench/module-tools/template-diy/` 与 `template/`。
+4. 安装包的类型面：`node_modules/@dsh-workbench/core/dist/types/**`；本指引：`node_modules/@dsh-workbench/core/skills/workbench-module-diy/**`。
 
-## 三条不许松的
+## 硬约束
 
-- **dsh 已经有的，先从 `kit` 拿**（`@dsh-workbench/core/client`），不许从 DOM + CSS 重画；
-  也不直接 import dsh 的包 —— 直接引会被门禁拦，而且那是第二份实例。
-- **工坊里的模块一律 `private: true`，不发到任何源。**
-- **源码里只许 JSDoc，且贴着导出**（用法住在声明里，tsc 把它搬进 `.d.ts`）；`//`、实现里的解释、
-  以及 `.css` 里的注释照旧不许有。要说的"为什么"写进模块自己的 `README.md` 或 spec。
+- dsh 已有的从 `kit` 拿（`@dsh-workbench/core/client`）；不手搓 DOM + CSS，不直接 import dsh 的包。
+- DIY 模块 `private: true`，不发任何源。
+- 源码只许贴导出的 JSDoc；`//`、实现内注释、`.css` 注释都不许。理由写模块 `README.md` 或 spec。

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

@@ -1,97 +1,94 @@
-# 三步：每一步问什么、要定什么、什么时候算做完
+# 三步：问什么、产出什么、何时算完
 
-[DESIGN.md](DESIGN.md) 是三张表的来历，本文是每一步的**问法**与**完成判据**。
+每一步的结果当场写进 `design.json`：`panel` / `states` / `config` / `capabilities` / `linkage` /
+`datasource` / `reads[]` / `writes[]` / `acceptance`。`design check` 列出空格。
 
-每一步定下来的东西都**当场落进**模块里的 `design.json`：面板 = `panel` / `states`、配置 = `config`、
-能力 = `capabilities`、联动 = `linkage`、数据源 = `datasource` / `reads[]`、写通道 = `writes[]`（单条可写 `write{}`）、验收 = `acceptance`。
-`dsh-wb-module design check` 会把空着的格列出来 —— **只留在对话里等于没定**。
+## 步骤 1 — 面板
 
-## 步骤 1 — 面板：他看什么，他配什么
+一次问一组，每组给推荐答案：
 
-先问出来（一次问一组，每组带推荐答案）：
+- 打开面板第一眼看到什么？拿它做什么决定？
+- 哪些事要能自己配？配完看到什么不同？
+- 哪些事一定会说给 agent 听？原话是什么？
 
-- 打开这块面板，他**第一眼**要看到什么？他拿这个答案去做什么决定？
-- 哪些事他要能自己配？配完以后，他看到的会有什么不同？
-- 哪些事他一定会说给 agent 听？**那句话原文**是什么？
+定四件事：
 
-要定的四件事：
+1. **展示清单**，每条一句人话：这一格是什么 / 一眼得出什么结论 / 点一下去哪。详情、评论、流转、日志不在面板做。
+2. **配置清单**：管什么 / 默认 / 候选从哪来 / 选错怎样 / 按项目记 / 何时生效 / 怎么清。
+3. **分流**：反复做且要动平台的 → 交给 agent；多步、长等、中途要人、失败要续的 → 封成一个动作（按钮 + 交给 agent 的入口）；
+   只是看 → 只读。
+4. **状态矩阵**：每态「看到什么 / 能做什么 / agent 能接着做什么」。
 
-1. **展示清单**（每条一句人话）：这一格是什么、一眼能得出什么结论、点一下可以去哪（去平台看详情 / 交给 agent）。详情、评论、流转、日志这类**零散操作不在面板做**。
-2. **配置清单**：用他的话说清 这管什么 / 默认是什么 / 他能选的值从哪来 / 选错了会怎样 / 按项目分别记 / 他自己按的才生效 / 怎么清掉。
-3. **分流**：他会反复做、要动平台上东西的事 → 交给 agent；一次要动好几下、要等很久、中途要他登录或点头、失败要能接着来的 → 封成一个动作，给他一个按钮（+ 一个交给 agent 的入口）；只是看看 → 只读呈现。
-4. **状态矩阵**：每种状态下"屏幕上是什么 + 他能做什么 + agent 能接着做什么"。
+产出：ASCII 画面（卡片、设置面、每种状态）+ 状态矩阵（左列图号）+ 图例。
 
-**这一步做完要给他看的**：**ASCII 画面** —— 卡片、设置面、每一种状态都画出来 + 状态矩阵（左列图号）与图例。
+判据：
 
-**完成判据**
+- 用户对着图确认过每种状态，或指出哪格不对。
+- 每格是用户看得见或能操作的事，没有"系统内部会…"。
+- 矩阵每个词都能在图例里指到屏幕；图例不能只是同义词。
+- 每种缺失有一句可照做的话：缺什么、去哪补、谁补。
+- 每个控件对应一句用户会对 agent 说的话，界面上有该句的位置。
+- 真机造不出的状态也有设计。
 
-- 他**对着这些图**看过每一种状态，说过"就这样"或指出了哪一格不对。
-- 表里每一格都是他**看得见或能操作**的事，没有一句"系统内部会…"。
-- 矩阵里每个词都在图例里指到了屏幕上的样子；没有图例，或图例里只有同义词，都算没写完。
-- 每种缺失都有一句**能照做**的话：缺什么、去哪补、谁补（他 / agent / 平台）。
-- 每个控件都能翻译成一句他对 agent 说的话，且那句话在界面上有位置。
-- 每种状态都有设计 —— 真机上造不出来的那些也要写。
+→ [PANEL.md](PANEL.md)
 
-→ 清单怎么写、界面习惯、状态话术：[PANEL.md](PANEL.md)
+## 步骤 2 — agent 能力
 
-## 步骤 2 — agent：他能替用户做什么，哪几件要用户点头
+先问：
 
-先问出来：
+- 用户会怎么说这件事？agent 需要先知道什么？
+- agent 做完，用户需要知道什么？
+- 哪些是真动手、必须先点头？点头时要看到什么？
 
-- 他会怎么跟 agent 说这件事？agent 得先知道什么才不用猜？
-- agent 做完，他需要知道什么？
-- 哪几件是**真的动手了**、他必须先点头？点头时他想看到什么，才敢点？
+定五件事：
 
-要定的五件事：
+1. **能力清单**：每件事一句"agent 能做什么"；说明为何是独立的事，而不是某件事的选项。
+2. **入参 / 返回**：贴真实调用（参数 JSON）与真实返回正文（照抄）。补默认值、上限（不悄悄截）、
+   取值范围、给错怎么改。
+3. **全场景**：正常 / 没有 / 分不清是哪一份（不许猜）/ 参数错 / 超上限 / 能力未装好 / 要登录或超时 /
+   还有下一批 / 截断（说清截了什么、多少）/ 没有当前项目。
+4. **写操作两拍**：先预览（说清将要做什么），再执行。预览让用户判断"要不要做"，不是"要不要允许"。
+5. **点头范围**：改平台 / 改这台机器 / 改面板。点头时展示这次具体发生什么（对象、版本、环境）；
+   说不清就不问，停下让 agent 去查。
 
-1. **能力清单**：每件事一句"agent 能做什么"；并说清它为什么是一件独立的事，而不是已有一件事的一个选项。
-2. **传什么 / 拿回什么**：**贴真实的那一段** —— 真实调用（参数 JSON）＋ 真实返回正文（**照抄，不转述**），再附默认值（不给等于什么）、上限（要多少给多少，**不悄悄截**）、范围（只认哪几个值）、给错怎么改。凡是"大概是这样的"，都不算。
-3. **每件事的全场景**：正常 / 没有 / **说不清是哪一份**（不许猜，让他选）/ 参数不对 / 超出上限 / 能力还没装好 / 平台要登录或超时 / 还有下一批 / 太长截断了（说清截了什么、多少）/ 没有正在做的项目。
-4. **动手的事分两拍**：先预览（说清**将要做什么**，让他确认），再真的做。预览的话要让他能判断"要不要做"，不是"要不要允许"。
-5. **哪几件要点头**：会改平台上东西的、会改这台机器的、会改他面板的。
-   - 点头时他要看到**这次真的会发生什么**（哪一个对象、什么版本、到什么环境），不是"这个操作会写数据"。
-   - **说不清这次会发生什么就不许问**：停下，把原因告诉 agent 让它去查 —— 用户不该为一个看不清的后果点头。
+产出：真实调用与返回，逐条贴出。能连平台就真跑；不能就用真实代码输出并标注样例。
 
-**这一步做完要给他看的**：**真实的调用与返回**，一条一条贴出来给他看（不是概述）：能打到平台就真跑一遍、把记录贴出来；打不到就用真实代码产出的输出，并标明哪些值是样例。
+判据：
 
-**完成判据**
+- 每种情况有确定结果；拒绝文案带 agent 可执行的下一步。
+- 入参与返回照抄；边界给真实报错原文。
+- 分不清的那格不许猜、不许退回默认。
+- 截断、越界、分页说清边界与下一批。
+- 点头格写"会发生什么"，不写"这是什么操作"。
+- 用户自按入口不点头，但与 agent 同一条链路、同一结果。
 
-- 每件事的每种情况都有确定结果；拒绝的话里带 agent 能照做的下一步。
-- 每一件都贴着**真实调用与真实返回**（照抄的正文，不是转述）；边界情况给的是**真实的报错原文**。
-- "说不清是哪一份"这一格不许猜，也不许悄悄退回默认。
-- 截断、越界、分页都说清了边界在哪、下一批怎么拿。
-- 点头那一格写的是"会发生什么"，不是"这是什么操作"；补不齐后果的那条路是**停下**，不是硬问。
-- 用户自己按的那个入口不需要点头，但和 agent 走的是同一件事、看到同一个结果。
+→ [TOOLS.md](TOOLS.md)
 
-→ 能力怎么划、点头全场景、预览怎么写：[TOOLS.md](TOOLS.md)
+## 步骤 3 — 联动
 
-## 步骤 3 — 联动：agent 做完，用户看到什么
+先问：
 
-先问出来：
+- agent 改完，多久看到、哪一格变？
+- agent 只读，面板是否变、变哪格？（口径 [LINKAGE.md](LINKAGE.md) §1）
+- agent 跑几分钟时，用户看哪？
+- 点"交给 agent"后，agent 拿到什么？
 
-- agent 改完，他需要多久看到、看到哪一格变？
-- agent 只是**读**了一下（看一眼），面板该不该动、动哪一格？（口径：读的是这一格 → 这一格变；
-  读的是面板上没有的东西 → 不动。见 [LINKAGE.md](LINKAGE.md) §1）
-- agent 正在干（要几分钟）的时候，他看哪儿？
-- 他点"交给 agent"之后，agent 手上拿到的是什么？
+定五件事：
 
-要定的五件事：
+1. **何时变**：读这一格 → 该格按最窄切片重读，值与对话一致；读面板外的东西（明细 / 日志 / 子集）→ 不变；
+   预览 → 不变；真写 → 该格新值；用户自按 → 立刻变。
+2. **进行中**：显示到哪步；要登录给链接；失败给原因与原始输出。不画进度条、不画流程控制台。
+3. **交给 agent 的内容**：哪一类、哪个对象、多少，加一句用哪个能力取明细。
+4. **收起模块 = 该项目内 agent 也失去该能力**，开始时说明。
+5. **不陈旧**：切项目、别的窗口在改、程序刚更新，三者要么实时要么说清。
 
-1. **什么时候面板该动**：agent **读了这一格** → 那一格按最窄切片变（值跟对话里那份一样）；读的是面板上没有的东西（明细 / 日志 / 某档子集）→ **不动**；只预览 → **不动**；真的做了 → 那一格变成新值；他自己按的动作 → 那一格立刻变。
-2. **正在干的时候**：显示到哪一步、要登录给他链接、失败给他原因和原始输出；**不画进度条、不画流程控制台**。
-3. **"交给 agent"之后 agent 拿到什么**：哪一类、哪个对象、多少，加一句"该用哪个能力再往下拿"（agent 打不开面板上那个 ↗，明细得靠它自己再问一次）。
-4. **收起模块 = 这个项目里 agent 也做不了这件事**，要在一开始就说清。
-5. **面板凭什么不旧**：切项目、别的窗口也在改、程序刚更新过 —— 这三种都要么实时、要么说清。
+产出："变之前 / 变之后"两张 ASCII + 联动表（何时变、哪格变）。
 
-**这一步做完要给他看的**：**"变之前 / 变之后"两张 ASCII 并排** + 一张联动表（每格说清什么时候变、哪一格变）。
+判据：
 
-**完成判据**
+- 用户对着两张图看过一次真实变化。
+- 每格说清"何时变、哪格变、看到什么"；"哪一格"细到"某投影 + 最窄参数"（`cmdb/builds?env=dev`）。
+- 面板不停在旧值；允许延迟但要说清。
+- 每个"交给 agent"都说清 agent 收到的内容。
 
-- 他**对着那两张图**看过至少一次真实的变化（agent 做完面板变成什么样）。
-- 每一格都说清"什么时候变、哪一格变、用户看到什么"，没有"刷新一下"这类模糊说法；
-  "哪一格"要细到能落成"某条投影 + 最窄那个参数"（`cmdb/builds?env=dev` 这种），
-  不然实现的人只会整卡重读（[LINKAGE.md](LINKAGE.md) §1 末段）。
-- 面板自己永远不会停在旧值上（允许有延迟，但延迟要说清）。
-- 每一颗"交给 agent"都说清了进到 agent 眼里的那段话是什么。
-
-→ 联动场景表：[LINKAGE.md](LINKAGE.md)
+→ [LINKAGE.md](LINKAGE.md)

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

@@ -1,55 +1,38 @@
-# 哪些纪律已经固化成工具，哪些留给 agent
+# 命令 vs 判断
 
-这份是 DIY 指引（`SKILL.md` / `STEPS.md` / `PANEL.md` / `TOOLS.md` / `LINKAGE.md` / `BUILD.md` /
-`WIRING.md` / `REVIEW.md` / `DATASOURCE.md` / `DESIGN.md`）与**工具面**之间的对照表。判据只有一条：
+机器能判定的用命令；需要判断的留给 agent。
 
-> **机器能判定的，就不该让 agent 记；只有需要判断的，才留给人。**
+## 用命令
 
-它回答两件事：**这条纪律还用不用我盯着**（不用 → 跑哪一条命令），
-以及**手上这件事能不能也做成工具**（判断类的别做）。
-
-## 机器判的（跑一次就有答案）
-
-| 纪律（出处） | 固化形态 |
+| 要得到 | 命令 |
 |---|---|
-| 十三条判据（[REVIEW.md](REVIEW.md)） | `dsh-wb-module check`（`--only <判据>` 单跑；`--only kit` 列这份外壳的 kit 成员；`--only arch` 跑模块自己的分层形状；`--only lint` 跑模块自己的语法卫生） |
-| 落点、分层文件形状、六个脚本（[BUILD.md](BUILD.md) §1–§2） | `dsh-wb-module init --template diy`（骨架带分层目录 + 一行 `arch.config.mjs` + 两行 `eslint.config.mjs`（`moduleLint({ rootDir: import.meta.dirname })`）+ 一条真读盘的数据源）+ `scripts/smoke.mjs` |
-| 语法卫生红了、要自动修（[REVIEW.md](REVIEW.md) 第十三条） | `dsh-wb-module lint [--fix]`（**`check` 永不动手改文件**；`--fix` 才写回） |
-| 装、上板、不重装（[WIRING.md](WIRING.md) §3） | `workbench_diy_install` / `workbench_diy_show` / `workbench_diy_status`（工坊那一跳自己上板） |
-| 想知道 dsh 原语 / 这份外壳的 kit 里有什么、某一件怎么用（[KIT.md](KIT.md) §8） | `workbench_diy_components`（不填给清单 + 类型面根；`name=Button` 回它的类型文件与那份声明——JSDoc 里写着默认值与语义；`bucket=icons` 把那一桶列全——`all=true` 的全表在真工坊超 8192、中间会被修剪器裁掉，按桶取才装得下；工程域用 `dsh-wb-module check --only primitives --file <名字>`） |
-| 它到底起得来没（装配抛的错 / 声明被拒的原文） | `workbench_diy_status`（"起得来"那一行，见 [REVIEW.md](REVIEW.md) 四步取证的第二步） |
-| 看 / 动**用户那一屏**之前要先取得约定（ADR-0055 §7「调试是一次约定」） | `workbench_diy_debug_start`（`unit=…`，**要用户点头一次**）—— 没有它，浏览器那 14 把 / `logs_*` **一律当场拒**（拒的时候一条命令都不发）；不看屏了 `_pause`、收工 `_stop`（**收工顺手把网络捕获与日志钩子也收了**）。`_panel` / `_status` 不碰他那一屏，不用开（`_find` / `_eval` 的 `read=` 档也不碰 —— 那是只读线）。**全表与参数见 [FAMILY.md](FAMILY.md)** |
-| 抓那一次**在外站页面上点出来的写**（他的写只发生一次，也不在我们那条会话里） | `_record_prepare`（`unit` / `url` / `doing`，**要用户点头一次**）→ 请他按「开始录制」→ 做**一次**那动作 → 按「结束录制」→ `_record_read` 取那一段 → `_record_stop` 收工（**先 read 再 stop**）。它不走调试约定，只碰自己的 `workbench-rec` 会话；三颗键、边界与实话见 [FAMILY.md](FAMILY.md) §5 · [WRITES.md](WRITES.md) 步骤 3 |
-| 看 / 动那一屏的浏览器动作怎么发（枚举 opencli，argv 与结果原样转发） | 14 把：`workbench_diy_state` / `_html` / `_find` / `_click` / `_hover` / `_type` / `_fill` / `_keys` / `_scroll` / `_wait` / `_eval` / `_screenshot` / `_network` / `_dialog` —— 公共参数只有 `unit?` / `args?` / `timeoutMs?`（另有 `scope` / `in` / `clip` 只长在该长的那几把上；`$card` 在任何 `args` 里都替换）。**不知道参数就问 `--help`**（也照样转发）；返回体是 opencli 的原样，事实在 `stdout` 里 |
-| 这一页的控制台 / 网络怎么取证（[REVIEW.md](REVIEW.md) 四步取证） | `workbench_diy_logs_watch` / `_read` / `_stop`（钩子有上限：每页 200 条、单条 400 字）—— **opencli 的 `console` 是空桩**（恒回空数组、还 exit 0），控制台只能我们自己做；网络是 `workbench_diy_network` 一把（`--follow` 臂上、`--failed` / `--since` 这些原样转发；收工 `_debug_stop` 顺手收），但**`--detail` 取不到 body** —— 缓存落在会话可写根之外，只能列请求 key；要 body 走 `_eval` 里的 `fetch`。网络那一头工作台走的是**隔离 opencli**（自己的 `HOME`），它的缓存与你自己 shell 里 `~/.opencli` 那份不是同一个 —— 核验要用工具，别看错文件 |
-| 面板上现在是什么样（每张卡读到没 / 崩没崩） | `workbench_diy_panel`（浏览器半侧上报，宿主按 unit 留最新一条） |
-| 空着的格就是还没定的事（[DESIGN.md](DESIGN.md) §5） | `design.json` + `design check`（点名叫出空格）/ `render` / `accept` |
-| 发货前的清单（[WIRING.md](WIRING.md) §5） | `dsh-wb-module publish`（门禁 + 打包清单 `files` 漏项，只 dry run） |
-| 干净机器上的第一脚（[SKILL.md](SKILL.md) 第 4 步） | 启动器自愈骨架 + PATH 上的 `dsh-wb-module` |
-| 会写的工具要点几次头（[TOOLS.md](TOOLS.md) §6） | `writes: true` + `needsApproval` + `approvalDetail`，`check --only contracts` 查 |
-| 跑一会儿的事怎么让用户看见（[TOOLS.md](TOOLS.md) §9） | `longTasks`（注册表含 `stop`）+ kit 的 `useLongTask` / `LongTaskRow`，`check --only contracts` 查**形状** |
-| agent 要能看 / 停长任务（[TOOLS.md](TOOLS.md) §9） | **外壳自带**的 `workbench_long_tasks_list` / `workbench_long_tasks_stop`（自己起的免审批、别人的 / 用户按的要审批、外地工作区直接拒绝）—— 模块不用自己写；"谁起的"靠 `runs.start({ …, session: sessionIdOf(exec) ?? undefined })` 记（**不记 = 用户按的**） |
-| 这个能力要靠什么才跑得起来（[TOOLS.md](TOOLS.md) §8） | `manifest.env` + `libInstallCommand`，`check --only contracts` 查 |
-| 配置存不存（[PANEL.md](PANEL.md) §5.1） | `config[].persistence`（`prefs` / `view`）+ `check --only contracts` |
-| agent 动完面板哪一格变（[LINKAGE.md](LINKAGE.md) §8） | `factsOf` + `factOfRoute` / `context` / `warmReads` / `values`，`check --only contracts` 只查形状 |
-| kit 不够用时能不能引 dsh 的界面原语（[PANEL.md](PANEL.md) §9 · [KIT.md](KIT.md) §8） | 只在客户端侧引 + `dsh.client.external` 里声明 + `devDependencies` 精确版对齐外壳钉的那份；宿主侧一个字都不许碰（`check --only source` / `--only primitives`） |
-| dsh 原语里到底有什么（名字 / 哪几件 kit 已有 / 该写哪两行 / **这一件在哪份类型文件**） | `dsh-wb-module check --only primitives`（单跑当查询口；`--all` 全表、`--file <名字>` 给绝对路径、`--files \| grep` 全表、`--json` 机器档）；kit 那条同形（`--only kit --file Card`）—— 取装机那份 `lib/types/**/*.d.ts`，不手抄清单 |
-| DOM 读怎么读（[DATASOURCE.md](DATASOURCE.md) 第 2 步） | `probe`（探）+ `browserFind`（固化）—— 切格 / 按列取值是两个纯函数 |
-| 链接只有一副样子（[PANEL.md](PANEL.md) §6） | kit 的 `Link` 是唯一一份（**没有 `icon` 口子**），`check --only style` 拦裸 `<a>` |
-| 输入框不用自己配样式（[PANEL.md](PANEL.md) §5.1） | `TextField` 的默认内边距 + kit 的 `Field`（标签 + 提示的排布） |
-| 这个单元在哪些工作区出现（[TOOLS.md](TOOLS.md) §12） | **不是模块能声明的事** —— 用户用 `workbench_panels_*` 的板决定（卡片与全部工具同判）。`gate.deniedTools` 是可选的运行期收窄 |
-
-## 留给 agent 的（判断，不该固化）
-
-- **判域**：这个需求该不该在这里做 —— [DESIGN.md](DESIGN.md) §0
-- **问三张表**：用他的词问、把决定翻译成"你会看到什么"、取舍与口径
-- **探数时的创造性**：找哪个列表页、看哪个 XHR（"怎么读一次"已固化，见上表）
-- **信息设计与排版**：一屏放什么、结论放哪、字少到什么程度 —— [PANEL.md](PANEL.md)
-- **安全取舍**："说不清这次会发生什么就不许问" —— [TOOLS.md](TOOLS.md) §6
-- **联动颗粒度**：动的是整卡、某一行、还是某一列 —— [LINKAGE.md](LINKAGE.md) §1
-  （工具只能保证"形状对"，"该多窄"是判断）
-- **停不停得了**：那颗停止钮画不画（`LongTaskRow` 的 `stop`）、`run` 收到的 `signal` 认不认
-  （[TOOLS.md](TOOLS.md) §9）—— 判据只看形状；"外壳把这一趟标成 `stopped`、你的活儿还在跑"这件事
-  机器看不出来，是模块自己的取舍
-
-工具只负责把**事实**摆出来（状态、报错原文、预览结果），判断仍然是人 / agent 的事。
+| 十三条判据 | `dsh-wb-module check`（`--only <判据>`） |
+| 骨架 | `dsh-wb-module init --template diy` |
+| 语法卫生修复 | `dsh-wb-module lint [--fix]` |
+| 三张表空格 / README / 验收 | `design check` / `render` / `accept` |
+| kit 成员与用法 | `workbench_diy_components`（`name=…`、`bucket=icons`）；工程域 `check --only kit` |
+| dsh 原语 | `check --only primitives`（`--all` / `--file <名>` / `--json`） |
+| 模块是否起得来 | `workbench_diy_status` |
+| 面板运行态 | `workbench_diy_panel` |
+| 安装 / 上板 | `workbench_diy_install` / `_show` / `_status` |
+| 屏操作约定 | `workbench_diy_debug_start`（否则 14 把 + `logs_*` 拒） |
+| 录制写请求 | `_record_prepare` → `_record_read` → `_record_stop` |
+| 控制台 / 网络 | `_logs_watch` / `_read` / `_stop`；`_network`（body 用 `_eval` 的 fetch） |
+| 审批声明 | `writes: true` + `needsApproval` + `approvalDetail`（`contracts` 查） |
+| 长任务 | `longTasks` + `useLongTask` / `LongTaskRow`（`contracts` 查形状） |
+| 外部依赖 | `manifest.env` + `libInstallCommand`（`contracts` 查） |
+| 配置持久化 | `config[].persistence` |
+| 联动事实 | `factsOf` + `factOfRoute` / `context` / `warmReads` / `values`（`contracts` 查形状） |
+| 发布预检 | `dsh-wb-module publish`（dry run） |
+
+## 留给 agent
+
+- 判域（[DESIGN.md](DESIGN.md) §0）。
+- 用用户语言问三张表、把决定翻译成"你会看到什么"（[STEPS.md](STEPS.md)）。
+- 探测数据位置（列表页、XHR）（[DATASOURCE.md](DATASOURCE.md)）。
+- 信息设计与排版（[PANEL.md](PANEL.md)）。
+- 审批的安全取舍：说不清后果就不问（[TOOLS.md](TOOLS.md) §6）。
+- 联动粒度：整卡 / 行 / 列（[LINKAGE.md](LINKAGE.md) §1）。
+- 停止钮画不画、是否响应 signal（[TOOLS.md](TOOLS.md) §9）。
+
+工具只给事实（状态、报错原文、预览），判断归 agent。