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

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

@@ -1,55 +0,0 @@
-# 哪些纪律已经固化成工具，哪些留给 agent
-
-这份是 DIY 指引（`SKILL.md` / `STEPS.md` / `PANEL.md` / `TOOLS.md` / `LINKAGE.md` / `BUILD.md` /
-`WIRING.md` / `REVIEW.md` / `DATASOURCE.md` / `DESIGN.md`）与**工具面**之间的对照表。判据只有一条：
-
-> **机器能判定的，就不该让 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 的事。