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

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

@@ -1,56 +1,52 @@
-# 工坊会话里那一族：33 把（agent 手上真实有什么）
+# DIY 工具族：怎么选、怎么串
 
-[TOOLS.md](TOOLS.md) 讲**你写的模块**的能力怎么写；这一份讲**工坊会话里 agent 手上真实有什么**。
-浏览器那一半照 opencli 的子命令枚举，参数只有 `args`（原样转发）；为什么这么定见仓内 ADR-0062（这份指引不链仓内路径）。
+只写工具定义里没有的东西：什么时候用哪把、先后顺序、参数说明之外的坑。
+逐把的参数与返回以调用时拿到的工具定义为准；模块自身的能力见 [TOOLS.md](TOOLS.md)。
 
-## 1 前置（别的都排它后面）
+## 1 选哪把
 
-- 只在**工坊会话**里出现，且**那块板画在屏上**；看 / 动 / 网络 / 日志那一族还要**先立调试约定** `workbench_diy_debug_start`（请用户点头一次）：**没有约定一律当场拒、零命令**；不看屏 `_debug_pause`、收工 `_debug_stop`（顺手收网络与日志钩子）。
-- 会话钉死 `workbench`、每条带 `--window background`；`_list`/`_status`/`_panel`/`_components`/`_recon`/`_spec`/`_install`/`_show` 不碰他那一屏，不用开；`_find`/`_eval` 这些带 `read=` 时也**不碰**（走只读线，见 §2 末）。**写那一族（录制交接，见 §5）不走这条路**：它自己开一条 `workbench-rec` 会话，`_record_prepare` 要点头一次，`_record_read` / `_record_detail` / `_record_stop` 不问。
-
-## 2 14 把浏览器工具（工具名 → argv；前缀都是 `workbench_diy_`）
-
-`_state`→`state` · `_html`→`get html` · `_find`→`find` · `_click`→`click` · `_hover`→`hover` · `_type`→`type` · `_fill`→`fill` · `_keys`→`keys` · `_scroll`→`scroll` · `_wait`→`wait` · `_eval`→`eval` · `_screenshot`→`screenshot` · `_network`→`network` · `_dialog`→`dialog`
-
-干什么：名字直说；不直观的几个 —— `_state` URL + 标题 + 可点元素（ref 来源）、`_html` HTML（`--as json` 树）、`_find` 回 `{matches_n, entries[]}`、`_network` 收发包（`--follow`；body 拿不到）、`_screenshot` 写文件（`clip` 只裁一块）。
-
-**参数**（`scope` / `in` 默认都是 `page`）：
-
-- 公共：`unit?`（哪张卡；可省 —— 只剩一个模块就用它。**要卡作用域就得给**：写 `scope: 'card'` / `in: 'card'` 或用 `$card` 却不给 ⇒ **当场拒、零命令**）· `args?: string[]`（原样接在 `opencli browser workbench <verb…>` 后）· `timeoutMs?`（默认 30000）· `read?: string`（只读线档，见本节末）。
-- `scope: 'card'` 只给吃 CSS 的**七把**：`_find`（`--css`）· `_html`（`--selector`，没给它我们补）· `_click`/`_hover`/`_type`/`_fill`（**位置参数 0**）· `_wait`（**只在 `wait selector`**，位置参数 1）—— `card` = 给那个目标挂 `#wb-card-<unit> .wb-card `。
-- **只读线档**：任何一把带上 `read: <站点地址>` 就跑在**另一条会话** `workbench-read` 上 —— **不要调试约定、不要板在屏上、不认卡作用域**（`unit` / `scope: 'card'` / `in: 'card'` / `$card` 逐个当场拒、零命令），也**不要求会话工作区里有模块包**（它一行都没碰工作区）；结果与屏那一档**同一组字段**（`ok`/`exitCode`/`timedOut`/`truncated`/`stdout`/`stderr` 原样），另带 `session` 与 `opened`。`opened` = 我替你开过一次站点：跑之前先 `get url` 比域名，不在那个站点上就 `open <read>` 一次再跑。`_eval` 上沿用读线约定：脚本回 `{ ok: false, code: "not-logged-in" }` 时输出后补一句「去 <read> 登一次」（只补说明，结果字段一个不改）。**这一档取代了老的 `_probe`**（2026-10-20；来龙去脉在本仓 `docs/adr/0062` §6 与 `.scratch/diy-read-line/spec.md` —— 那两份不随包出货，只给改外壳的人）：老 `_probe` 那层结构化 `entries` 没有替代 —— `_find` 的 stdout 自己解析。
-- `in: 'card'` 只 `_eval`（注入卡根 `root`，**脚本自己 `return`**）；`clip`（CSS px）只 `_screenshot`（拍完本地裁）；`$card` **任何 `args` 里**都替换成 `#wb-card-<unit> .wb-card`。
-
-**拿回**：`{ ok, exitCode, timedOut, truncated, stdout, stderr }` + `workshop`/`unit`/`verb`/`argv`（`read=` 那一档改成 `session`/`opened`：只读线不碰工作区，所以没有 `workshop`/`unit`）；`_screenshot` 另给 `file`/`cropped`/`cropReason`。`ok` 只管进程，事实全在 `stdout`（报错也是一份 `{"error":{…}}`，`ok` 可能仍 `true`）；不抠 JSON / 不翻中文 / 不做 ok 归一，**要参数先问 `--help`**。**"原样"有折损**：`args` 里空串 / 纯空白 / 非字符串丢掉、留下的词前后 trim、`stdout`/`stderr` 也 trim ⇒ **`_fill` 清空不了输入框**、**`_type` 敲不了空格**，没有别的口子就如实说做不到。
-
-## 3 老工具 → 新命令
-
-| 老 | 新 |
-|---|---|
-| `_look` | `state` + `get html` + `eval` + `screenshot`（卡图靠 `clip`，上游没有 selector） |
-| `_reload` / `_viewport` | `eval 'location.reload()'` / `screenshot --width/--height` |
-| `_select` | **没了**（上游只认原生 `<select>`）；下拉两拍：卡内点触发器 → `scope: 'page'` + `--role menuitem` 按名字点 |
-| `_net_*` | `network`（`--follow` 臂上、收工 `_debug_stop` 顺手收；**取 body 走 `_eval` 的 `fetch`**） |
-| `_click` `_hover` `_type` `_fill` `_keys` `_scroll` / `_logs_*` | 同名，参数改成原样转发（`console` 是空桩，控制台只能我们做） |
-
-## 4 如实边界
-
-- `screenshot` **没有上游 selector**：卡图先 `eval` 量盒子再填 `clip`；不给路径我们补到工坊同级的 `shots/<unit|page>-<时间戳>.png`（否则回 base64）；要裁的块不在视口里就退回整屏图，原因在 `cropReason`。
-- `state` **没有 `scope`**（卡内定位用 `find --css '$card …'`）；**没有右键 / contextmenu**；ref 只在**一次快照**里有效，别跨调用存；`_dialog` 的 `accept|dismiss` 不校验；`_network --detail` **取不到 body**（缓存落在会话可写根之外）—— 走 `_eval` 里的 `fetch`。
-- 录制交接那条**会话捕获**（`_record_prepare` 起的：先短暂 `network --follow` 只做"臂上"，然后每 3 秒一次**非跟随** `browser <session> network --all --raw`，**落盘前先按 URL 去掉静态资源与 `data:`**（含 node 就过滤、没有就原样落），一轮一行追加到工坊同级的 `shots/rec-<unit>.jsonl`）**带 body**：非跟随那条会把 live 缓冲排空，连 `request.body`（入参）与 `body`（出参）一起打出来；跟随那条只打形状（只有方法 / URL / 状态 / ct / size / 时间），所以只拿它臂上、装完就杀。它盖**整场**、在浏览器那一层，比页面钩子全（钩子只认那一页自己的 `fetch`/`XHR` —— 应用提前把 `window.fetch` 存走、或在 iframe / Worker / WebSocket 里发，它就看不见）。**不许改成"用 opencli 默认过滤"**：那层是**按响应 ct 白名单**判的（只留 json/xml/text-plain/javascript），"按下写就立刻按结束"那条**回包还没到、ct 为空**的写会被当场丢掉 —— 实测 127 条里它只留 33 条、那条写没了；按 URL 去静态则是 127 → 30 条、那条写还在。
-- 另外 19 把：台账 `_list`/`_status`/`_install`/`_show`、组件与 kit 清单 `_components`（不填给清单与类型面根，`name=Button` 回它的类型文件与声明）、宿主运行态 `_panel`/`_status`、数据源 `_recon`、`_spec`（问一条 opencli 命令的形状，**插件也适用**）、`_logs_*`、约定本身 `_debug_*`、录制交接 `_record_*`（§5）。
-
-## 5 录制交接（四把）：抓那一次"在外站页面上点出来的写"，清单 → 挑一条 → 看原文
-
-| 工具 | 干什么 |
+| 要做什么 | 用 |
 |---|---|
-| `_record_prepare` | 开一扇窗**顶到最前**（**要用户点头一次**）、装浮条、臂上捕获。参数 `unit` / `url` / `doing`，可选 `expect:{method,urlContains}`；**不给 `url` 当场拒**，**跨域也当场拒**（那个模块的 `design.json` 说过读源时，只许同域录；还没说过就不拦）。返回带 `wrote: false` |
-| `_record_read` | 取那一段的**清单**：`rows`（每行 `index` / `key` / `at` / `method` / `url` / `status` / `ct` / `size` / `source` / `hasRequest` / `hasResponse` / `likelyWrite` / `marked`）· `hookCaught`（钩子这一段**原始**条数）· `capturedLines` / `capturedInSegment` / `capturedOutside` · `dropped` · `noBody` · `nav` · `captureRound`（会话捕获**最近一轮**成没成：`ok` / `fail` / 空 = 还没回）。**清单一条都不删、也不回体**：页面钩子（`[t0,t1]` 段）与会话捕获（整场按段切）合并，**同名只配掉一条钩子行**（缺的 key / 入参 / 出参由捕获那条补上）；捕获里两条同 method+url 是**两次真调用，都留着**。**`expect` 不再是过滤器**：它只给命中的行标 ⭐，⭐ 排在前面（不然只列最后十几条时它可能不在正文里）；不设 expect 时 ⭐ = 非 GET 或带 request body。**正文每一行把它要的两样直接摆出来**：`· [0] ⭐ POST 站点/路径（捕获 · 入参 有 · 出参 40 B · at 1792583917392）` —— 开头那串就是 `key` 原文（opencli 给的，可能带 `#2`），`at` 是毫秒时间戳；**没有 `key` 的钩子行**写成 `method url（钩子 · … · 无 key）`，那种行只在还开着时按 `index` 取得到。要哪一条的原文就带它的 `key`（或 `index`）去 `_record_detail`。没按开始 / 还在录都如实说，不假装"没有请求"。可选 `waitMs`（默认 0 = 立刻回，帽 15 分钟）：等不到就回 `timedOut` 并挂一条 notice 叫醒你 —— **一场就是一个周期（开始 → 结束）**，结束之后要再录就**重新 `_record_prepare` 一场**（同场没有"再按一次开始"这回事）。**他按「结束录制」不用他再跟你说一声**：录制期间宿主每 3 秒自己看一眼那一页（浮条在目标页里、推不到宿主；宿主能叫醒你的通道只有 `deliverDebugNotice`），一看到 `finished` 就推状态并发一条 notice 叫你来 `read` |
-| `_record_detail` | 取**某一条**的原文：入参（`request.body`）与出参（`response body`），外加请求头（可能含凭据，别落进 `design.json`）。参数 `key`（清单里那一条，原样给、含 `#2` 这种后缀）或 `index`（清单里的序号，只在那一场还开着时可用）；**同一个 key 跨轮会重名**（opencli 的 key 计数器每批重置），所以再带上清单里那行的 `at` 才钉得住是哪一次（不给就取最早那条，并在正文里说重名几次）。可选 `unit` —— 那一场**收工之后**要给 unit，我去读 `shots/rec-<unit>.jsonl.last`（`_record_stop` 会把原文留成 `.last`，下一场 prepare 开录时清掉它）。取不到时如实说"两边都没有"，并给兜底：DevTools 复制 curl。可选 `maxBody`（默认 60000 字符，0 = 不限） |
-| `_record_stop` | 停捕获、收掉那个标签、清状态（**收工前先读一次捕获文件**，与 read 同一套切段 / 合并；**原文另存成 `.last`**，所以收工之后还能 `_record_detail`；没挪成就不说"原文留在…"）。回一段能直接落 `design.json` 的原文（`probeCommand`）—— **只认第一条带 body 的**；一条都没有就回空串，并如实说"只有方法 / URL，body 拿不到 —— 补到 body 再落"（没 body 的写命令落下去是一条**会打错的**命令）。**先 read（或先 detail 完）再 stop** |
-
-左栏底部那一格给他的键（等出手 `[取消]` / 录制中 `[停]`）只**给 agent 发一条消息**，不直接改页面那一半（`[停]` 有意不动状态）；**录完那一档没有键** —— agent 自己来取、自己收工。
-一场过期（TTL 15 分钟）或台账被换走，**不会把采集循环留在地上**：看门那一拍看到台账没了就停捕获 + 收标签，
-循环本身也被宿主 pid 兜着（宿主重起后孤儿循环自己退）；`prepare` 开新一场前也先对同一落点收一次。
-细则、三颗键与如实边界（`fetch`/XHR 之外抓不到、50 条 / 16 KB 上限、一次一场 15 分钟）
-都在 [WRITES.md](WRITES.md) 步骤 3；纪律同那一份的「三条写纪律」。
+| 认路、装没装、起不起得来 | `_status`（`unit` 可省）；它的「下一步」就是下一件事 |
+| 卡片空白 / 崩了 / 读不到 | `_panel` |
+| 找 opencli 命令、看命令形状 | `_recon` → `_spec`（`--help -f json` 原样） |
+| kit 有什么 / 令牌叫什么 | `_components`（`bucket` / `name` 取声明；`scope: tokens` 现读 `--dsw-*` / `--wb-*`） |
+| 装一次 / 只上板 | `_install` / `_show` |
+| 发布前记这一版改了什么 | `_changelog`（`note` 必填；文件不在就先建） |
+| 发布 | `_publish`，只在用户说「帮我发布」之后 |
+| 看 / 动当前页 | `_state` · `_html` · `_find` · `_screenshot` · `_click` · `_hover` · `_type` · `_fill` · `_keys` · `_scroll` · `_wait` · `_network` · `_dialog` |
+| 控制台 | `_logs_watch` → 操作 → `_logs_read` → `_logs_stop` |
+| 抓「用户点了之后发了什么」 | `_record_prepare` → 用户操作 → `_record_read` → `_record_detail` → `_record_stop` |
+
+## 2 前置
+
+- 只在 DIY 模式的会话出现；面板得画在屏上。
+- 看 / 动 / 网络 / 日志族先 `_debug_start`（审批一次），否则整族拒、零命令；收工 `_debug_stop`。
+  `_pause` 只暂停看屏。不碰屏的：`_status` / `_panel` / `_components` / `_recon` / `_spec` /
+  `_install` / `_show` / `_changelog` / `_publish`；`_find` / `_eval` 带 `read=` 时也不碰。
+- 录制独立：`_record_prepare` 审批一次，其余不问；同时只有一场，要重来先 `_record_stop`。
+
+## 3 参数之外的坑
+
+- 浏览器工具都能带 `args` 原样转发；空串 / 纯空白 / 非字符串会被丢弃，词前后 trim ——
+  `_fill` 清不空、`_type` 打不了纯空格。
+- `ok` 只表示进程退出。事实在 `stdout`；错误体是 `{"error":{…}}`，`ok` 仍可能是 true。
+  不解析、不翻译；参数不明先 `args: ['<verb>', '--help']`。
+- 卡作用域：`unit` 指卡；`scope: 'card'` / `in: 'card'` / `$card` 需要它，
+  `$card` 在 args 里换成 `#wb-card-<unit> .wb-card`。
+- 只读线：带 `read: <地址>` 时跑在 `workbench-read` 会话，不碰屏、不认卡作用域、能代开站点；
+  `_eval` 返回 `not-logged-in` 时让用户去登录。
+- `_screenshot` 不给路径时写 artifacts 目录；拿不到选择器就先 `_eval` 量盒再 `clip`。
+- `state` 没有 `scope`；`_select` 不存在（下拉两拍）；ref 只在一次快照内有效；
+  `_dialog` 不校验 `accept|dismiss`；`_network --detail` 没有 body，要 body 用 `_eval` 的 fetch。
+- 录制按 URL 去静态资源后落盘；`_record_read` 不回体，取体用 `_record_detail`；
+  `_record_stop` 先读文件再另存 `.last`，所以先 read / detail 再 stop。取不到时给 DevTools 复制 curl。
+  场次 15 分钟过期；过期或台账变更会停捕获、收标签。
+
+## 4 发布
+
+只在用户明确说「帮我发布」后调。它一次做完预检 → 全门禁 → 按出口发布 → 发后核包，审批一次。
+发布前先 `_changelog` 把这一版写进 `CHANGELOG.md`：没有这一版的记录，`_publish` 会拦下。
+审批屏会把这一版的更新日志按 markdown 展示给用户。
+需要用户接管时返回 `needsUser: { step, text, command? }` 而不抛异常：把 `text` 说给用户、给命令，
+等「好了」再跑；不向用户要 token，不展示 `package.json`。

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

@@ -1,138 +1,106 @@
-# kit 速查：要做什么 → 用哪一件 → 最小写法
+# kit：选型、组合、最小写法
 
-`check --only kit` 列**名字**（这台机器上真有的，别照抄别的模块），**逐件用法在 `.d.ts` 的 JSDoc 里**
-（`workbench_diy_components name=<名字>` 一回就是它）。这一份给的是**跨件**的：怎么拼、纪律、排布。
+`check --only kit` 列**当前安装的外壳真实有的**成员；逐件用法在 `.d.ts` 的 JSDoc（`workbench_diy_components name=<名>`）。
+本文件只给跨件规则与最小示例。全部从 `kit.components` / `kit.hooks` / `kit.lib` / `kit.api`
+（`@dsh-workbench/core/client`）取；示例中 `h = createElement`（从 `react` 引）。
 
-**能拿 kit 的就别自己画。** 理由只有一条：主题、语言、悬停、禁用、焦点环、空态、被裁的处理
-都只维护一份。自己画的不会跟着换主题，也不会跟着我们改口径 —— 这就是"同一个东西长得不一样"的来源。
-
-> 全部从 `const { … } = kit.components`（`@dsh-workbench/core/client`）拿。
-> 例子里的 `h` = `createElement`（`import { createElement as h } from 'react'`）。
+优先用 kit：kit 随外壳换主题、跟语言走。
 
 ## 1 卡片外壳
 
-**`Card`** —— 一张卡的壳：标题 + 刷新钮 + 卡片体。面板上每一格都是它。
+- `Card`：标题 + 刷新 + 内容。面板每格都用它。
 
 ```tsx
 h(Card, { t: props.t, title: t('myunit.cardTitle'),
   refreshing: resource.phase === 'loading', onRefresh: props.onRefresh }, body)
 ```
 
-**`CardHead`** —— 你自己拼卡头时用它（`Card` 内部就是它）。prop 见 `.d.ts`；
-`platformHref` 只给这一颗就够，那颗 ↗ 立刻画出来。
-
-**`CardAnchor`** —— 外壳自己盖的锚点（`#wb-card-<unit>`）。**别自己写**，也别删。
+- `CardHead`：自拼卡头时用；`platformHref` 给一个即出 ↗。
+- `CardAnchor`：外壳锚点 `#wb-card-<unit>`；不写不删。
+- `CardBoundary`：卡片错误边界；不要自己 try/catch 渲染。
 
-**`CardBoundary`** —— 卡片级错误边界。一张卡炸了不许把整块面板带走；**别自己 try/catch 包渲染**。
+## 2 状态
 
-## 2 状态：这是下限最集中的地方
+五态：待机 / 在读 / 就绪 / 就绪但空 / 读不到。
 
-先想清五态（`design.json` 的状态矩阵就是这五格）：**待机 / 在读 / 就绪 / 就绪但空 / 读不到** —— 每一态都要有东西画。
-
-| 什么时候 | 用 |
+| 场景 | 用 |
 |---|---|
-| 有内容了 | `StateBlock`（标题 + `hint` 一行 + 正文） |
-| 要他先选一个 / 正在读 / 读不到 | `CenteredState`（居中一屏） |
-| 就绪但空 | `EmptyState`（它只是 `CenteredState` 的简写） |
-| 在读、且你已经有大概形状 | `SkeletonRows`（骨架） |
-| 一句说明 / 一句报错 | `Note`（`tone: 'problem'` 是报错） |
-
-prop 与默认值看 `.d.ts`。
+| 有内容 | `StateBlock`（标题 + `hint` + 正文） |
+| 需先选 / 在读 / 读不到 | `CenteredState` |
+| 就绪但空 | `EmptyState` |
+| 在读且有形状 | `SkeletonRows` |
+| 一句说明 / 报错 | `Note`（`tone: 'problem'`） |
 
 ```tsx
 h(CenteredState, { icon: null, title: t('myunit.loading'), hint: t('myunit.loadingHint'), compact: true })
 h(CenteredState, { icon: null, title: t('myunit.errorTitle'), detail: `${code}: ${message}`, hint: t('myunit.errorHint'), compact: true })
 h(EmptyState, { text: t('myunit.empty'), icon: h(IconPanelScreen, { size: 20 }), compact: true })
 h(StateBlock, { title: rows.title, hint: `3 条 · ${when}`, resolving: t('myunit.rows') }, table)
-h(Note, { children: t('myunit.hint') })
 ```
 
-**读不到就说读不到**：`detail` 里放原始错误码与那句话，**绝不显示 0**（0 是"真的是 0"）。
+读不到：`detail` 放原始错误码与原文；不显示 0。
 
-## 3 一行一行
+## 3 行与记录
 
-**`Rows` + `Row`** —— 键值行（左边名字、右边值）。**别自己写 `ul`/`li` 或 div 行**：
-分隔线、行距、对齐、两端溢出都在这两件里。
+- `Rows` + `Row`：键值行；不手写 `ul` / `li` / div 行。
 
 ```tsx
 h(Rows, null,
   ...items.map((one) => h(Row, { key: one.name, label: one.name, value: `${size} · ${when}` })))
 ```
 
-**`ActivityBlock` / `ActivityLine` / `ActivityAction`** —— "它做过什么"那一块（prop 见 `.d.ts`）。时间一律用它。
-
-**`LongTaskRow`** —— 长任务那一行（五态，prop 见 `.d.ts`）；别自己画进度。传 `stop` 要宿主认 `signal`、peer 抬到带它那版（[TOOLS.md](TOOLS.md) §9）。
-
-**`ApprovalDetail` / `ApprovalPlan`** —— 审批屏那两格（写操作才要点头）；口径与那张 ASCII 见 [DESIGN.md](DESIGN.md) §3 末节。
+- `ActivityBlock` / `ActivityLine` / `ActivityAction`：活动记录；时间用它。
+- `LongTaskRow`：长任务行（五态）；不画进度条。传 `stop` 需宿主响应 signal 且 peer 下限到位（[TOOLS.md](TOOLS.md) §9）。
+- `ApprovalDetail` / `ApprovalPlan`：审批屏两格；形状见 [DESIGN.md](DESIGN.md) §3 末节。
 
 ## 4 表单
 
-**`Form`** —— **整张表单**（面那一层）：`fields` 配置进，行怎么排、错误摆哪、什么时候校验、提交怎么被挡住、
-第一处错误怎么带进视口、操作区怎么排全归它。**一张完整的表单就用它**（口径见 §5，逐件看 `.d.ts`）。
+`Form` 管理整张表单：字段、校验时机、错误位置、首错聚焦、操作区。
 
 ```tsx
 h(Form<{ branch: string }>, {
-  fields: [
-    { key: 'branch', label: t('myunit.branch'), value: draft.branch, onChange: onBranch,  // 值与改写同一处
-      validate: (v) => (v === '' ? t('myunit.branchRequired') : undefined),
-      control: (b) => h(TextField, { id: b.id, name: b.name, invalid: b.invalid,
-        disabled: b.disabled, value: b.value, onChange: (e) => b.onChange(e.currentTarget.value) }) },
-  ],
-  submit: { label: t('myunit.save'), busyLabel: t('myunit.saving') },   // cancel / extra 见 `.d.ts`
-  onSubmit: save,                                                // 有错就不调它；values 就是这个类型
+  fields: [{
+    key: 'branch', label: t('myunit.branch'), value: draft.branch, onChange: onBranch,  // 值与改写同格
+    validate: (v) => (v === '' ? t('myunit.branchRequired') : undefined),
+    control: (b) => h(TextField, { id: b.id, name: b.name, invalid: b.invalid,
+      disabled: b.disabled, value: b.value, onChange: (e) => b.onChange(e.currentTarget.value) }),
+  }],
+  submit: { label: t('myunit.save'), busyLabel: t('myunit.saving') },
+  onSubmit: save,
 })
 ```
 
-**`Form<Values>` 把每一格的键与值类型钉住**（不写类型参数 = 默认档、不钉，每格要自己收窄）；
-**值与它的改写写在同一格**（`value` + `onChange`，`control` 从绑定取 `binding.value` / `binding.onChange`
-—— `Form` 不持有值）；**会 `visible: false` 的键在 `Values` 里写可选**（`branch?: string` ⇒ 值是
-`string | undefined`）。`validate` 是同步纯函数、第二参是整张值表（跨字段读得到别的格）；**控件永远由
-`control` 给**（没有"给个 `options` 自己选控件"的 DSL）。
-
-**控件那几件** —— `Field`（没进 `FormRow` 时兜住标签 + 说明）· `TextField`（`invalid` 标红）·
-`ChoiceGroup`（`multi` 区分多选）· `SelectField`（默认常规下拉框，`variant: 'ghost'` 是无边框那档，
-**不是原生 `<select>`**）· `SaveBar`（设置面底下那条"取消 / 保存"）：都是只给数据与语义 prop 的哑组件，
-**逐件看 `.d.ts`**。
-
-**`FormActions`** —— **操作区**（一组按钮，形状见 `.d.ts`；**整张表单里由 `Form` 组**）。
-**顺序 / 间距 / 换行都归它** —— `primary` 永远在右、`danger` 紧挨它左侧、一个区只许一颗 `primary`、
-窄了自动折行且 `primary` 落在右下角；`busy` 自带 `Spinner`。**别自己写 `gap` / `margin` / 顺序，
-也别借 `.wb-formActions` 槽类手摆**（F3 红）。`danger` 只标"破坏性"（**永远不当填充的 `primary`**）；
-**二次确认那半归调用点**。
+规则：`Form<Values>` 钉键与值类型；值与 `onChange` 同格；`visible: false` 的键在 `Values` 中可选；
+`validate` 同步纯函数、第二参为整张值表；控件只经 `control` 提供。
 
-**别手写 `<button>` / `<input>` / `<select>`**（dsh 有 `Button`，kit 有上面这几件；手写的判据会红）。
-`<textarea>` 例外（dsh 与 kit 都没有多行输入）。
+控件：`Field`（未进 `FormRow` 时包标签与说明）· `TextField`（`invalid`）· `ChoiceGroup`（`multi`）·
+`SelectField`（常规下拉；`variant: 'ghost'` 无边框；非原生 select）· `SaveBar`（取消 / 保存）。
+不手写 `<button>` / `<input>` / `<select>`；`<textarea>` 例外。
 
-**`ConfirmBar`** —— 「先问一句再动手」那一条（标题 / 说明 / 键值 / 失败那句 / 动作区一次收口）：
-键值走 `Rows` / `Row`、错走 `Note tone="problem"`、动作走 `FormActions` —— **别自己拼这四个槽**。
-**要不要问归调用点**（`danger` 只标"破坏性"）。口径见 ADR-0073。
+`FormActions`：操作区。`primary` 靠右、`danger` 在其左、每区一个 `primary`、窄屏折行；`busy` 带 `Spinner`。
+不写 `gap` / `margin` / 顺序，不借 `.wb-formActions` 槽类（F3 红）。`danger` 仅标破坏性；二次确认归调用点。
 
-怎么排（标签位置、错误态、尺寸）见 §5。
+`ConfirmBar`：确认条。键值走 `Rows`，错误走 `Note tone="problem"`，动作走 `FormActions`；不重拼这四槽。
+是否询问归调用点。
 
-## 4′ hook 怎么搭（逐件看 `.d.ts`）
+## 4′ hooks
 
-kit 的 hook 也分四个场合，**别自己 `useState` + `setTimeout` 造一套**（面板要同一套口径）：
-
-| 场合 | 用它 |
+| 场景 | 用 |
 |---|---|
-| 卡片里的一次读（自带同 key 合流 / 事实订阅 / 上报面板） | `useApiResource`（非 hook 的本体是 `requestResource`，**用了就一定要 `release`**） |
-| 写完让面板重取 / 听事实变化 | `useFactInvalidate` · `useFactRevision` · `subscribeFactRevision`（非 hook，记得退订） |
-| "至少转一会儿"的忙态 | `useVisibleBusy`（投影那两件 `busyView` / `heldPhase`） |
-| 一格**卡片**起步（gate + 忙 + 探针 + 上报 + blocker 一次叠好） | `useUnitBoard`（`read(gated)` 里自己调 `useApiResource`） |
-| 只要一格的能力门 / 整张能力表 | `useCapabilityGate` / `useCapabilityMap` |
-| 写（**别在组件里 `fetch`**） / 轮询长任务 | `useHostWrite` / `useLongTask`（画用 `LongTaskRow`；判「还在跑」`longTaskIsLive`、写完让这一格立刻重读 `refresh()`） |
+| 卡片一次读（同 key 合流 / 事实订阅 / 上报） | `useApiResource`（非 hook 为 `requestResource`，用后必须 `release`） |
+| 写后重取 / 听事实变化 | `useFactInvalidate` · `useFactRevision` · `subscribeFactRevision`（非 hook 要退订） |
+| 最短忙态 | `useVisibleBusy`（`busyView` / `heldPhase`） |
+| 整卡起步（gate + 忙 + 探针 + 上报 + blocker） | `useUnitBoard`（`read(gated)` 内调 `useApiResource`） |
+| 单点 / 整表能力门 | `useCapabilityGate` / `useCapabilityMap` |
+| 写（组件内不 fetch）/ 长任务轮询 | `useHostWrite` / `useLongTask`（`LongTaskRow`；`longTaskIsLive`；写后 `refresh()`） |
 
-取数那条链的图见 [LINKAGE.md](LINKAGE.md) §8，写通道与配置见 [PANEL.md](PANEL.md) §5。
+取数链见 [LINKAGE.md](LINKAGE.md) §8；配置见 [PANEL.md](PANEL.md) §5。
 
-## 5 表单这一层：`Form`（面）→ 行 → 控件
+## 5 表单三层：面 → 行 → 控件
 
-表单三层：**面**（`Form`，写法见 §4：值 / 校验 / 操作区全归它）→ **行**（`FormRows` + `FormRow`）→
-**控件**（`TextField` / `SelectField` / `ChoiceGroup`）。**一张表单一个面**。**别再自己摆操作区** ——
-它自己组 `[...extra, ...cancel, submit(primary)]`（提交钮永远在右；「一会在左一会在右」就是自己摆的结果）；
-其余口径（时机 / 第一处错误 / `busy` / `disabled`）看它的 JSDoc 与 ADR-0068 / ADR-0074。
+一张表单一个 `Form`；不要另摆操作区（`Form` 组 `[...extra, ...cancel, submit(primary)]`）。
 
-`FormRows` + `FormRow` + `FormActions` 留给**不是整张表单**的地方：单行（一格字段嵌在别处）、
-非表单的一组动作（工具栏、卡头那几颗钮）—— 那里才自己拼这三件：
+`FormRows` + `FormRow` + `FormActions` 仅用于非整表场景：单行嵌入、工具栏、卡头按钮。
 
 ```tsx
 h(FormRows, null,
@@ -140,64 +108,41 @@ h(FormRows, null,
     h(SelectField, { value, options, onChange: setMode })))
 ```
 
-- **标签归 `FormRow`**（默认在左，`layout: 'stacked'` 才上下堆叠）；**控件只给数据与语义 prop**，
-  进了 `FormRow` 就别再给控件自己的 `label` / `hint`（会多一个标签、还退回上下堆叠）。
-- **`hint` 与 `problem` 二选一**：有错先显示错。
-
-**错误态**：位置与长相归 `FormRow.problem` + 控件的 `invalid`；**算错的逻辑留在模块**（纯函数 + 文案，
-交给 `FormField.validate`）—— **别指望外壳给校验引擎**（不做 `rules` / 异步 / 联动），
-**"提交过没有"与聚焦第一处错也归 `Form`**（别自己记布尔、别自己调 `revealFirstProblem`）。
-
-**选择类用哪件**：候选多 / 要搜索 / 要分组 / 名单可能读不到 ⇒ `SelectField`；候选少、要一眼看全 / 多选 ⇒
-`ChoiceGroup`（`loading` / `emptyText` / `variant` 两件一个意思）。**loading 那颗一律是 `Spinner`**。
-
-**尺寸口径**：字段控件默认 **28**，别自己调高；行距只有一档、标签列宽也归 `FormRow(s)`
-（长标签不折行、同一组共用一个标签列，别自己给标签写宽度）；**控件的宽度也别自己写**
-（字段控件自己吃满控件槽那一格，ADR-0052 §13）。非行的子项（如分组标题）自动通栏。
+- 标签归 `FormRow`（默认左置；`layout: 'stacked'` 堆叠）。进了 `FormRow` 就不再给控件 `label` / `hint`。
+  `hint` 与 `problem` 二选一，错误优先。
+- 错误：位置与外观归 `FormRow.problem` + 控件 `invalid`；校验逻辑留在模块（纯函数 + 文案，交给 `validate`）。
+  "是否提交过"与首错聚焦归 `Form`。
+- 选择：候选多 / 需搜索 / 需分组 / 可能读不到 → `SelectField`；候选少 / 要全览 / 多选 → `ChoiceGroup`。
+  loading 一律 `Spinner`。
+- 尺寸：字段控件默认 28；行距与标签列宽归 `FormRow(s)`；控件宽度归控件槽。非行子项自动通栏。
 
-**反例（别这么写）**：
-
-```tsx
-h('span', { className: styles.label }, …)     // ← 手写标签行：F1 红
-h('div', { className: styles.form }, …)       // ← 自己管行距（.form { gap }）：F2 红
-h('form', …)                                  // ← 裸 <form> / 手写行槽类：F4 红（表单归 Form）
-```
+反例：手写标签行（F1）、自管行距（F2）、裸 `<form>` / 手写行槽类（F4）。
 
-**时点**：这一层随外壳发版后模块才能用（`check --only kit` 拿 peer 下限那份外壳比，不抬必红）。
-**`Form` / `ConfirmBar` 是新成员**：要用得等外壳**发一版含它的版本**，再把 peer 下限抬到**那一版**
-（版本随发版填，别照抄别的件）；`FormRow(s)` / `FormActions` 的下限是另一件事。
+时点：`Form` / `ConfirmBar` 需外壳发版含它们后，把 peer 下限抬到该版。
 
-## 6 别的
+## 6 其他
 
-- **`Link`** —— **唯一**的外链写法（`h(Link, { href, children })`）：**别去掉箭头、别在文案里自带 `→`、
-  别手写 `<a>`**（判据红）。
-- **`SettingsSection` / `Stack` / `BlockerState` / `Tip`** —— 一屏设置里的一节 / 竖排间距 / 阻断屏 /
-  Tooltip（只有图的地方**必须**有它或 `aria-label`）；prop 看 `.d.ts`。
-- **真机上造不出来的那几态**：拿你自己那份 `plugin.test.ts` 把五态各喂一遍（`check --only cards`
-  拿七种外壳侧输入各喂一遍，只问"退化得干不干净"）。
-- **图标** —— `IconPanelScreen` / `IconModuleMark` / `IconNpm` / `IconOpencli`；其余图形一律从 dsh 的
-  `Icon*Regular` 拿，**别自己画图标**。
+- `Link`：唯一外链（`h(Link, { href, children })`）；不去箭头、文案不带 `→`、不手写 `<a>`。
+- `SettingsSection` / `Stack` / `BlockerState` / `Tip`：设置节 / 竖排 / 阻断屏 / Tooltip（纯图必须有它或 `aria-label`）。
+- 图标：`IconPanelScreen` / `IconModuleMark` / `IconNpm` / `IconOpencli`；其余从 dsh `Icon*Regular` 取，不自绘。
+- 真机造不出的状态：`plugin.test.ts` 覆盖五态。
 
-## 7 三条纪律
+## 7 规则
 
-1. **调用点只给数据与语义**。别从外面塞外观类名 —— 只有布局槽例外（通栏、外边距、网格位置）。
-2. **字号与颜色走 kit 与令牌**（`--dsw-*` / `--wb-*`），不写字面值。**重点可以大**：要突出的数字用
-   `--dsw-font-xl-24`（24/32、600）加 `font-variant-numeric: tabular-nums`（见 [PANEL.md](PANEL.md) §6）；
-   刻度外非要字面值时，在模块 `README.md` 里写一句为什么。
-3. **自己写 CSS 只写布局**（flex / grid / gap / 对齐）。要一个新的"长得像控件"的东西时，
-   先问一句：kit 里是不是已经有了？
+1. 调用点只给数据与语义；外观类名只允许布局槽（通栏、外边距、网格位置）。
+2. 字号与颜色走 kit 与令牌。重点数字用 `--dsw-font-xl-24` + `tabular-nums`；
+   令牌名现查不猜：`workbench_diy_components` 给 `scope: 'tokens'`（现读装着的 dsh 与外壳；`name=--dsw-…` 连浅/深值）。
+   刻度外字面值在模块 `README.md` 说明（[PANEL.md](PANEL.md) §6）。
+3. 自写 CSS 只写布局（flex / grid / gap / 对齐）。
 
-## 8 kit 里没有、但你确定要标准控件
+## 8 需要 kit 没有的标准控件
 
-**先问工具**：DIY 会话里调 `workbench_diy_components`（不填给清单；`name=Button` 回它的类型与声明）。工程域用 `dsh-wb-module check --only primitives`
-（`--all` 全表 / `--json` 机器档）—— 分桶导出 + 与 kit 求交（`kit 里已有` 的优先用）+
-该写进 `package.json` 的那两行；骨架默认已备好。
-**要看某一件**：`--file <名字>`（`--files | grep <名字>`）。
+查：`workbench_diy_components`（DIY 会话）或 `check --only primitives`（`--all` / `--json` / `--file <名>`）。
+写入：
 
 ```jsonc
 "dsh": { "client": { "external": [ "@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives" ] } },
-"devDependencies": { "@deepseek-ai/dsh-client-ui-primitives": "<外壳钉的那版，精确版>" }
+"devDependencies": { "@deepseek-ai/dsh-client-ui-primitives": "<与外壳一致的精确版>" }
 ```
 
-改完 `pnpm install` 一次；三条会红的边界（只在浏览器侧引 / 版本精确对齐 / 能拿 kit 的别引）与
-宿主侧的契约都见 [PANEL.md](PANEL.md) §9。
+改后 `pnpm install`。边界见 [PANEL.md](PANEL.md) §9。