@dsh-workbench/core 0.3.4 → 0.3.5

package/dist/types/shared/hooks/use-long-task.d.ts

@@ -1,7 +1,15 @@
 import { type LongTaskStatus } from '@dsh-workbench/shared';
+/**
+ * 这一单元的长任务清单：`runs` 是这次读交回的那一批（读数还没回来时是空数组）。
+ */
 export interface LongTaskFeed<T> {
     readonly runs: readonly T[];
 }
+/**
+ * 卡片要轮询长任务那一行时调用：有在跑的（`running` / `needs-login`）按 `longTaskPollMs` 走快档、空闲走慢档；
+ * `workspace` 为 `null`、`mocked: true` 或 `enabled: false` 时不轮。换单元 / 换工作区就是换读数身份，
+ * 旧那批立刻清空、读数回来前 `runs` 是空数组。
+ */
 export declare function useLongTask<T extends {
     readonly id: string;
     readonly status: LongTaskStatus;

package/dist/types/shared/hooks/use-unit-board.d.ts

@@ -6,10 +6,19 @@ import type { ApiError } from '@dsh-workbench/shared';
 import type { ResourceState } from './use-api-resource';
 import type { CapabilityGate } from './use-capability-gate';
 import { type CardSummary } from './use-card-summary';
+/**
+ * 卡片读数的最小形状：`state` 是 `useApiResource` 那一格，加上 `refreshing` / `at`（来自 `CardSummary`）
+ * 与 `settling`（挂过最短可见时长的那截收尾）。
+ */
 export interface CardFeed extends CardSummary {
     readonly state: ResourceState<unknown>;
     readonly settling?: boolean | undefined;
 }
+/**
+ * 起步一张卡片要交的东西：这一格的 `unit`、能力门 `gate`、`refreshToken`、`onRefresh` / `onSummary` 两个回调、
+ * 自己的读数函数 `read(gated)`（收到的是“放行没”，为真才去读）、翻译 `t`（`enabled: false` 时整格不读）；
+ * `platformBlocker(error, t)` 把平台错误翻成 blocker。
+ */
 export interface UnitBoardOptions<TFeed extends CardFeed> {
     readonly unit: string;
     readonly gate: CapabilityGate;
@@ -21,6 +30,10 @@ export interface UnitBoardOptions<TFeed extends CardFeed> {
     readonly enabled?: boolean | undefined;
     readonly platformBlocker?: ((error: ApiError, t: Translate) => ModuleBlocker | undefined) | undefined;
 }
+/**
+ * `useUnitBoard` 叠出来的整组：`feed`（含 `state`）、`capability`、`gated`（放行没）、`refresh`、`forceProbe`、`summary`，
+ * 外加拆好的那几个 blocker 字段。
+ */
 export interface UnitBoard<TFeed extends CardFeed> extends UnitBlockers {
     readonly feed: TFeed;
     readonly capability: CapabilityPayload | null;
@@ -29,4 +42,8 @@ export interface UnitBoard<TFeed extends CardFeed> extends UnitBlockers {
     readonly forceProbe: () => void;
     readonly summary: CardSummary;
 }
+/**
+ * 卡片起步就用它：把“gate 不放行就不读”、忙 / 安定（按 `MIN_BUSY_MS` 挂最短可见时长）、读数报错时
+ * 自动 `forceProbe`、`useCardSummary` 上报面板、blocker 拆分一次叠好。`read(gated)` 里自己调 `useApiResource`。
+ */
 export declare function useUnitBoard<TFeed extends CardFeed>(options: UnitBoardOptions<TFeed>): UnitBoard<TFeed>;

package/dist/types/shared/hooks/use-visible-busy.d.ts

@@ -1,8 +1,25 @@
+/**
+ * 读数的相位：`idle` 还没开读 · `loading` 在飞 · `ready` 有值 · `error` 失败。
+ */
 export type HeldPhase = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * “在忙，还是只是收尾”的投影：`settling` 为真时读数已经回来、界面还挂着。
+ */
 export interface BusyView {
     readonly busy: boolean;
     readonly settling: boolean;
 }
+/**
+ * 把“正在刷新”折进相位：`refreshing` 且已是 `ready` 记作 `loading`，让“旧值还显示、新的在路上”有名字。
+ */
 export declare function heldPhase(phase: HeldPhase, refreshing: boolean): HeldPhase;
+/**
+ * 由 `active` 与 `useVisibleBusy` 挂出来的 `visible` 投影出 `{ busy, settling }`；纯函数，好测。
+ */
 export declare function busyView(active: boolean, visible: boolean): BusyView;
+/**
+ * 需要“最少转一会儿”的忙态时调用：`active` 变真立刻 `busy`；变假时若这次没转满 `floorMs`，`busy` 先挂着，
+ * 这期间 `settling` 为真表示读数在回来的路上。`floorMs` 传共享包的 `MIN_BUSY_MS`，别自己编 ——
+ * 取数几毫秒就回来时不挂这一会儿，用户看到的是“闪一下”，比不转更难读。
+ */
 export declare function useVisibleBusy(active: boolean, floorMs: number): BusyView;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/core",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "个人工作台：Agent 工作台外壳（左栏 + 常驻对话 + 自研右侧数据面板）。",
   "type": "module",
   "icon": "./icon.svg",
@@ -87,7 +87,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dsh-workbench/shared": "0.3.4"
+    "@dsh-workbench/shared": "0.3.5"
   },
   "scripts": {
     "build": "node scripts/build.mjs && node scripts/build-types.mjs",

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

@@ -42,7 +42,7 @@
       - 想长期用 → 给这个站点写 adapter：`opencli skills read opencli-adapter-author`（侦察 → 字段解码 →
         写 → verify）；以后 adapter 失效：`opencli skills read opencli-autofix`。
 
-   **④ 才轮到探** —— 用工具：`workbench_diy_probe`（`url=<那套系统的地址>, script=<一段回 JSON 的脚本>`；
+   **④ 才轮到探** —— 用工具：`workbench_diy_eval`（`read=<那套系统的地址>, args=["<一段回 JSON 的脚本>"]`；
    页面里没有接口就给 `css=<选择器>`，走的是同一条固定 DOM 读，`{entries:[{text}]}` 直接回给你）。
    它用**用户浏览器里现有的登录**去读，并把"读不到"归一成阻断屏认的那几个码 —— 两拍（不在站点上就自己
    打开 `url` 再读一遍）、刚重启时的重试、平台码到阻断码的映射**都在工具里**，不用你记。
@@ -72,7 +72,7 @@
      想给自己一条专线（不跟别的模块抢同一个 tab）就传自己的名字：`session: "<unit>"`。
    - **页面里没有接口时（DOM 读）不要用 `eval` 去 `document.querySelectorAll`**：产物边界判据会拦
      （宿主产物里不许出现 `document.` / `window.` 字样），而且那样解析只能窝在字符串里、测不了。
-     探的时候 `workbench_diy_probe`（`url=…, css=<选择器>`）就是这个口子；
+     探的时候 `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 都不发，就该走这条。

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

@@ -6,7 +6,7 @@
 ## 1 前置（别的都排它后面）
 
 - 只在**工坊会话**里出现，且**那块板画在屏上**；看 / 动 / 网络 / 日志那一族还要**先立调试约定** `workbench_diy_debug_start`（请用户点头一次）：**没有约定一律当场拒、零命令**；不看屏 `_debug_pause`、收工 `_debug_stop`（顺手收网络与日志钩子）。
-- 会话钉死 `workbench`、每条带 `--window background`；`_list`/`_status`/`_panel`/`_components`/`_recon`/`_probe`/`_spec`/`_install`/`_show` 不碰他那一屏，不用开。**写那一族（录制交接，见 §5）不走这条路**：它自己开一条 `workbench-rec` 会话，`_record_prepare` 要点头一次，`_record_read` / `_record_detail` / `_record_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_`）
 
@@ -16,11 +16,12 @@
 
 **参数**（`scope` / `in` 默认都是 `page`）：
 
-- 公共：`unit?`（哪张卡；可省 —— 只剩一个模块就用它。**要卡作用域就得给**：写 `scope: 'card'` / `in: 'card'` 或用 `$card` 却不给 ⇒ **当场拒、零命令**）· `args?: string[]`（原样接在 `opencli browser workbench <verb…>` 后）· `timeoutMs?`（默认 30000；≤ 0 或非数也按默认）。
+- 公共：`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`；`_screenshot` 另给 `file`/`cropped`/`cropReason`。`ok` 只管进程，事实全在 `stdout`（报错也是一份 `{"error":{…}}`，`ok` 可能仍 `true`）；不抠 JSON / 不翻中文 / 不做 ok 归一，**要参数先问 `--help`**。**"原样"有折损**：`args` 里空串 / 纯空白 / 非字符串丢掉、留下的词前后 trim、`stdout`/`stderr` 也 trim ⇒ **`_fill` 清空不了输入框**、**`_type` 敲不了空格**，没有别的口子就如实说做不到。
+**拿回**：`{ 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 老工具 → 新命令
 
@@ -37,7 +38,7 @@
 - `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 条、那条写还在。
-- 另外 20 把：台账 `_list`/`_status`/`_install`/`_show`、组件与 kit 清单 `_components`（不填给清单与类型面根，`name=Button` 回它的类型文件与声明）、宿主运行态 `_panel`/`_status`、数据源 `_recon`/`_probe`、`_spec`（问一条 opencli 命令的形状，**插件也适用**）、`_logs_*`、约定本身 `_debug_*`、录制交接 `_record_*`（§5）。
+- 另外 19 把：台账 `_list`/`_status`/`_install`/`_show`、组件与 kit 清单 `_components`（不填给清单与类型面根，`name=Button` 回它的类型文件与声明）、宿主运行态 `_panel`/`_status`、数据源 `_recon`、`_spec`（问一条 opencli 命令的形状，**插件也适用**）、`_logs_*`、约定本身 `_debug_*`、录制交接 `_record_*`（§5）。
 
 ## 5 录制交接（四把）：抓那一次"在外站页面上点出来的写"，清单 → 挑一条 → 看原文
 

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

@@ -1,7 +1,7 @@
 # kit 速查：要做什么 → 用哪一件 → 最小写法
 
-`dsh-wb-module check --only kit` 列的是**名字**，这一份给的是**用法**。两处都别看漏：
-名字那份是这台机器上**真有的**（别照抄别的模块），这一份是**怎么拼**。
+`check --only kit` 列**名字**（这台机器上真有的，别照抄别的模块），**逐件用法在 `.d.ts` 的 JSDoc 里**
+（`workbench_diy_components name=<名字>` 一回就是它）。这一份给的是**跨件**的：怎么拼、纪律、排布。
 
 **能拿 kit 的就别自己画。** 理由只有一条：主题、语言、悬停、禁用、焦点环、空态、被裁的处理
 都只维护一份。自己画的不会跟着换主题，也不会跟着我们改口径 —— 这就是"同一个东西长得不一样"的来源。
@@ -14,17 +14,12 @@
 **`Card`** —— 一张卡的壳：标题 + 刷新钮 + 卡片体。面板上每一格都是它。
 
 ```tsx
-h(Card, {
-  t: props.t,
-  title: t('myunit.cardTitle'),
-  refreshing: resource.phase === 'loading',
-  onRefresh: props.onRefresh,
-}, body)
+h(Card, { t: props.t, title: t('myunit.cardTitle'),
+  refreshing: resource.phase === 'loading', onRefresh: props.onRefresh }, body)
 ```
 
-**`CardHead`** —— 你自己拼卡头时用它（`Card` 内部就是它）：`t` / `title` / `meta` / `refreshing` /
-`onRefresh` / `gear` / `onToggleGear`（右上那颗齿轮展开设置面）/ **`platformHref`**（跳整张卡对应的
-那个系统：只给这一颗就够，那颗 ↗ 立刻画出来）。
+**`CardHead`** —— 你自己拼卡头时用它（`Card` 内部就是它）。prop 见 `.d.ts`；
+`platformHref` 只给这一颗就够，那颗 ↗ 立刻画出来。
 
 **`CardAnchor`** —— 外壳自己盖的锚点（`#wb-card-<unit>`）。**别自己写**，也别删。
 
@@ -32,8 +27,7 @@ h(Card, {
 
 ## 2 状态：这是下限最集中的地方
 
-先想清五态（`design.json` 的状态矩阵就是这五格）：**待机 / 在读 / 就绪 / 就绪但空 / 读不到**。
-每一态都要有东西画，一个不落。
+先想清五态（`design.json` 的状态矩阵就是这五格）：**待机 / 在读 / 就绪 / 就绪但空 / 读不到** —— 每一态都要有东西画。
 
 | 什么时候 | 用 |
 |---|---|
@@ -43,6 +37,8 @@ h(Card, {
 | 在读、且你已经有大概形状 | `SkeletonRows`（骨架） |
 | 一句说明 / 一句报错 | `Note`（`tone: 'problem'` 是报错） |
 
+prop 与默认值看 `.d.ts`；下面是**怎么拼**。
+
 ```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 })
@@ -51,7 +47,7 @@ h(StateBlock, { title: rows.title, hint: `3 条 · ${when}`, resolving: t('myuni
 h(Note, { children: t('myunit.hint') })
 ```
 
-**读不到就说读不到**：`detail` 里放原始错误码与那句话，**绝不显示 0**（0 是"真的是 0"，不是"没读到"）。
+**读不到就说读不到**：`detail` 里放原始错误码与那句话，**绝不显示 0**（0 是"真的是 0"）。
 
 ## 3 一行一行
 
@@ -63,137 +59,146 @@ h(Rows, null,
   ...items.map((one) => h(Row, { key: one.name, label: one.name, value: `${size} · ${when}` })))
 ```
 
-**`ActivityBlock` / `ActivityLine` / `ActivityAction`** —— "它做过什么"那一块：
-`ActivityLine` 有 `dot` / `text` / `at`（时间）/ `actions`；`ActivityAction` 是行尾那个动作
-（`label` / `icon` / `href` 或 `onClick` / `failed`）。时间一律用它，别自己拼。
+**`ActivityBlock` / `ActivityLine` / `ActivityAction`** —— "它做过什么"那一块（prop 见 `.d.ts`）。时间一律用它。
+
+**`LongTaskRow`** —— 长任务那一行（四态 + 步骤 + 原文，prop 见 `.d.ts`）；
+跑得久的事（发布、扫描、迁移）都用它，别自己画进度。
 
-**`LongTaskRow`** —— 长任务那一行：`status`（四态）+ `headline` + `problem` + `links` + `steps` +
-`raw`。跑得久的事（发布、扫描、迁移）都用它，别自己画进度。
+**`ApprovalDetail` / `ApprovalPlan`** —— 审批屏那两格（写操作才要点头）；口径与那张 ASCII 见 [DESIGN.md](DESIGN.md) §3 末节。
 
-**`ApprovalDetail` / `ApprovalPlan`** —— 审批屏那两格（写操作才要点头）；口径与那张 ASCII 见 [DESIGN.md](DESIGN.md) §3 末节。## 4 表单
+## 4 表单
 
-**`Field`** —— 标签 + 输入的排布（`label` / `hint`），输入框放里面。
+**`Form`** —— **整张表单**（面那一层）：`fields` 配置进，行怎么排、错误摆哪、什么时候校验、提交怎么被挡住、
+第一处错误怎么带进视口、操作区怎么排全归它。**一张完整的表单就用它**（口径见 §5，逐件看 `.d.ts`）。
 
 ```tsx
-h(Field, { label: t('myunit.mode'), hint: t('myunit.modeHint') },
-  h(TextField, { value, onChange: (event) => setMode(event.target.value) }))
+h(Form, {
+  fields: [
+    { key: 'branch', label: t('myunit.branch'), value: branch,   // 值只读给校验看，读写仍归你
+      validate: (v) => (v === '' ? t('myunit.branchRequired') : undefined),
+      control: (b) => h(TextField, { id: b.id, name: b.name, invalid: b.invalid,
+        disabled: b.disabled, value: branch, onChange: (e) => setBranch(e.currentTarget.value) }) },
+  ],
+  submit: { label: t('myunit.save'), busyLabel: t('myunit.saving') },
+  cancel: { label: t('myunit.cancel'), onClick: onCancel },      // 排在提交钮左边
+  extra: [{ key: 'retry', label: t('myunit.retry'), onClick: onRetry }],   // 其余动作排最左
+  onSubmit: save,                                                // 有错就不调它
+})
 ```
 
-**`TextField`** —— 单行输入（`invalid` 标红；其余是原生 input 的 props）。
-**`ChoiceGroup`** —— 单选 / 多选（`multi` 区分；`value` 或 `values` + `onChange`；选项 `{ value, label, description? }`；`disabled` 在整组上）。
-**`SelectField`** —— 下拉：默认是**常规下拉框**（跟 `TextField` 一套），无边框那种给 `variant: 'ghost'`；
-搜索、分组、禁用项、加载态、空态、页脚都是它的 prop。
-（它是 dsh 那套按钮 + portal 菜单，**不是原生 `<select>`** —— 验收时 agent 要驱动它得走两拍：
-卡内点触发器 → `scope: page` + `--role menuitem` 按名字点；`workbench_diy_select` 那把工具已经不在了。）
-**`SaveBar`** —— 设置面底下那条"取消 / 保存"（`busy` / `disabled` / `labels` / `onCancel` / `onSave`）。
-**`FormActions`** —— **操作区**（一组按钮）：`actions: { key, label, kind?: 'default' | 'danger' | 'primary', onClick, disabled?, busy? }[]`。
+**值仍归调用点**（`Form` 一个值都不存）：`binding` 只递 `id` / `name` / `invalid` / `disabled`，
+`value` 与 `onChange` 由 `control` 里自己接。**控件永远由 `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` 槽类手摆**（`check --only style` 的 F3 会红）。
+窄了自动折行且 `primary` 落在右下角；`busy` 自带 `Spinner`。**别自己写 `gap` / `margin` / 顺序，
+也别借 `.wb-formActions` 槽类手摆**（F3 红）。`danger` 只标"破坏性"（**永远不当填充的 `primary`**）；
+**二次确认那半归调用点**。
 
-```tsx
-h(FormActions, { actions: [
-  { key: 'retry', label: t('myunit.retry'), onClick: onRetry, disabled: busy },
-  { key: 'confirm', label: t('myunit.confirm'), kind: 'primary', onClick: submit, disabled: busy },
-] })
-```
+**别手写 `<button>` / `<input>` / `<select>`**（dsh 有 `Button`，kit 有上面这几件；手写的判据会红）。
+`<textarea>` 例外（dsh 与 kit 都没有多行输入）。
 
-`danger` 只标"这是破坏性的"（渲成描边 + 危险色，**永远不当填充的 `primary`**）；**二次确认那半归调用点**
-（先问一句或弹窗都行）。
+怎么排成一行（标签位置、错误态、尺寸）见 §5。
 
-**别手写 `<button>` / `<input>` / `<select>`**：dsh 有 `Button`（`variant` / `size`），
-kit 有上面这几件；手写的会拿到浏览器默认样式，而且**判据会红**（`check --only style`）。
-`<textarea>` 例外（dsh 与 kit 都没有多行输入）——真要用就直接写，其余形态别开这个口子。
+## 4′ hook 怎么搭（逐件看 `.d.ts`）
 
-控件怎么排成一行（标签位置、错误态、尺寸）见 §5。
+kit 的 hook 也分四个场合，**别自己 `useState` + `setTimeout` 造一套**（面板要同一套口径）：
 
-## 5 表单这一层：面 → 行 → 控件
+| 场合 | 用它 |
+|---|---|
+| 卡片里的一次读（自带同 key 合流 / 事实订阅 / 上报面板） | `useApiResource`（非 hook 的本体是 `requestResource`，**用了就一定要 `release`**） |
+| 写完让面板重取 / 听事实变化 | `useFactInvalidate` · `useFactRevision` · `subscribeFactRevision`（非 hook，记得退订） |
+| "至少转一会儿"的忙态 | `useVisibleBusy`（投影那两件 `busyView` / `heldPhase`） |
+| 一格**卡片**起步（gate + 忙 + 探针 + 上报 + blocker 一次叠好） | `useUnitBoard`（`read(gated)` 里自己调 `useApiResource`） |
+| 只要一格的能力门 / 整张能力表 | `useCapabilityGate` / `useCapabilityMap` |
+| 写（**别在组件里 `fetch`**） / 轮询长任务 | `useHostWrite` / `useLongTask`（画用 `LongTaskRow`、点用 `longTaskDot`） |
+
+取数那条链的图见 [LINKAGE.md](LINKAGE.md) §8，写通道与配置见 [PANEL.md](PANEL.md) §5。
+
+## 5 表单这一层：`Form`（面）→ 行 → 控件
 
-表单三层：**面**（`SettingsSection` / `SaveBar`）→ **行**（`FormRows` + `FormRow`）→
-**控件**（`TextField` / `SelectField` / `ChoiceGroup`）。**一行一个字段**，行这一层只有一个出处。
+表单三层：**面**（`Form`）→ **行**（`FormRows` + `FormRow`）→ **控件**（`TextField` / `SelectField` /
+`ChoiceGroup`）。**一张表单一个面**。
+
+**整张表单用 `Form`**（写法见 §4）：`fields` 配置进；**值仍归调用点**（`value` / `onChange` 由 `control`
+里自己接，`binding` 只递 `id` / `name` / `invalid` / `disabled`）；**控件永远由 `control` 给**（没有"给个
+`options` 自己选控件"的 DSL）；`validate` 是同步纯函数；`visible: false` 的那格当它不存在（不渲染 /
+不校验 / 不进 `values`）。**别再自己摆操作区** —— 它自己组 `[...extra, ...cancel, submit(primary)]`
+（提交钮永远在右；「一会在左一会在右」就是自己摆的结果）。其余口径（时机 / 第一处错误 / `busy` /
+`disabled` / `key`）看它的 JSDoc 与 ADR-0068。
+
+`FormRows` + `FormRow` + `FormActions` 留给**不是整张表单**的地方：单行（一格字段嵌在别处，比如卡片里
+那一条设定）、非表单的一组动作（工具栏、卡头那几颗钮）。那里才自己拼这三件：
 
 ```tsx
 h(FormRows, null,
   h(FormRow, { label: t('myunit.mode'), hint: t('myunit.modeHint') },
-    h(SelectField, { value, options, onChange: setMode })),
-  h(FormRow, { label: t('myunit.env'), problem: problemOfEnv },
-    h(ChoiceGroup, { label: t('myunit.env'), name: 'env', options, value: env, onChange: setEnv })))
+    h(SelectField, { value, options, onChange: setMode })))
 ```
 
-- **标签归 `FormRow`**（`label`）：默认标签在左，`layout: 'stacked'` 才是上下堆叠（`Field` 那种排布）。
-  **控件只给数据与语义 prop**，不写外观类名（§7 第 1 条）。进了 `FormRow` 就别再给控件自己的
-  `label` / `hint`（`SelectField` 那两件是没 `FormRow` 时的兜底，重复给会多一个标签、还退回上下堆叠）。
-- **`hint` 与 `problem` 二选一**：给了 `problem` 就不画 `hint` —— 同一格不叠两段话，有错先显示错。
+- **标签归 `FormRow`**（默认在左，`layout: 'stacked'` 才上下堆叠）；**控件只给数据与语义 prop**，
+  进了 `FormRow` 就别再给控件自己的 `label` / `hint`（会多一个标签、还退回上下堆叠）。
+- **`hint` 与 `problem` 二选一**：有错先显示错。
 
-**错误态**：位置与长相由 `FormRow.problem` + 控件的 `invalid` 定（`SelectField` / `TextField` 同形，
-`ChoiceGroup` 见它自己的档）。**校验逻辑留在模块**：只写"算错误"的纯函数与文案
-（例：cmdb 的 `CmdbFormProblem` 那类），**别指望外壳给校验引擎**（不做 `rules` / `validate`、
-不做联动、不持有值）。提交失败后调 `kit.lib.revealFirstProblem(root)`（`root` = 表单容器）——
-把第一处错误带进视口、并聚焦它里面的控件。
+**错误态**：位置与长相归 `FormRow.problem` + 控件的 `invalid`；**算错的逻辑留在模块**（纯函数 + 文案，
+交给 `FormField.validate`）—— **别指望外壳给校验引擎**（不做 `rules` / 异步 / 联动、不持有值），
+**"提交过没有"与聚焦第一处错也归 `Form`**（别自己记布尔、别自己调 `revealFirstProblem`）。
 
-**选择类用哪件**：候选多 / 要搜索 / 要分组 / 名单可能读不到 ⇒ `SelectField`（`search` 默认开、
-`emptyText`、`loading` + `loadingText`、`fallback`、`variant: 'boxed' | 'ghost'`）；
-候选少、要一眼看全 / 多选 ⇒ `ChoiceGroup`（`multi`、`variant`、`loading` + `loadingText`、
-`emptyText`、`options[].description`）。两件的 `loading` / `loadingText` / `emptyText` / `variant`
-是一个意思；**loading 那颗一律是 `Spinner`**（`h(Spinner, { size: 14 })`）—— **别自己写转圈**。
+**选择类用哪件**：候选多 / 要搜索 / 要分组 / 名单可能读不到 ⇒ `SelectField`；候选少、要一眼看全 / 多选 ⇒
+`ChoiceGroup`（`loading` / `emptyText` / `variant` 两件一个意思）。**loading 那颗一律是 `Spinner`**。
 
-**尺寸口径**：字段控件默认 **28**（dsh 紧凑档），**别自己调高**；行距**只有一档**、归 `FormRow(s)`，
-模块里不该出现管行距的 `gap` / `margin`（横向的、卡片/清单网格的不算）。标签列也归它：
-**长标签不折行；同一 `FormRows` 共用一个标签列（列宽由最长的标签定），别自己给标签写宽度**
-（非行的子项，比如分组标题 `<p>`，自动通栏）。
+**尺寸口径**：字段控件默认 **28**，别自己调高；行距只有一档、标签列宽也归 `FormRow(s)`
+（长标签不折行、同一组共用一个标签列，别自己给标签写宽度）。非行的子项（如分组标题）自动通栏。
 
 **反例（别这么写）**：
 
 ```tsx
-h('span', { className: styles.label }, t('myunit.mode'))   // ← 紧邻控件的手写标签行：`check --only style` 红
-h('div', { className: styles.form }, …)                    // ← .form { gap: 8px }：自己管行距也红
+h('span', { className: styles.label }, …)     // ← 手写标签行：F1 红
+h('div', { className: styles.form }, …)       // ← 自己管行距（.form { gap }）：F2 红
+h('form', …)                                  // ← 裸 <form> / 手写行槽类：F4 红（表单归 Form）
 ```
 
-`<span className={styles.label}>` 紧邻控件、或给表单容器自己写 `gap` —— 这正是 `check --only style` 那条
-棘轮（F1 手写行 / F2 自己管行距）盯的东西：这么写直接红。
-
-**时点**：这一层随外壳**发版**后模块才能用 —— 模块的 `peerDependencies` 下限得先有它
-（`check --only kit` 拿 peer 下限那份外壳比，不抬必红）。包下限是 `^0.2.14`。
+**时点**：这一层随外壳发版后模块才能用（`check --only kit` 拿 peer 下限那份外壳比，不抬必红）。
+**`Form` 是新成员**：要用它得等外壳**发一版含它的版本**，再把 `@dsh-workbench/core` 的 peer
+下限抬到**那一版**（版本号随发版填，别照抄别的件）；`FormRow(s)` / `FormActions` 的下限是另一件事。
 
 ## 6 别的
 
-- **`Link`** —— **唯一**的外链写法：`h(Link, { href, children })`。自带新窗口 + `rel="noopener noreferrer"`
-  + 正文色 + hover 下划线 + 那颗小箭头。**别去掉箭头、别在文案里自带 `→`、别手写 `<a>`**（判据红）。
-- **`SettingsSection`** —— 一屏设置里的一节（`label` / `title` / `action`）。
-- **`Stack`** —— 竖排 + 统一间距（懒得分组时的默认容器）。
-- **`BlockerState`** —— 阻断屏：要登录 / 没权限 / 能力没装好那一类（`blocker` / `t` / `onRetry` / `onOpenMarket`）。
-- **`Tip`** —— Tooltip：图标钮与只有图的地方**必须**有它（或 `aria-label`）。
-- **真机上造不出来的那几态**：**拿你自己那份 `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`）；prop 看 `.d.ts`。
+- **真机上造不出来的那几态**：拿你自己那份 `plugin.test.ts` 把五态各喂一遍（`check --only cards`
+  拿七种外壳侧输入各喂一遍，只问"退化得干不干净"）。
+- **图标** —— `IconPanelScreen` / `IconModuleMark` / `IconNpm` / `IconOpencli`；其余图形一律从 dsh 的
+  `Icon*Regular` 拿，**别自己画图标**。
 
 ## 7 三条纪律
 
-1. **调用点只给数据与语义**：`h(Card, { title, refreshing, onRefresh }, …)`。别从外面塞外观类名
-   —— 只有布局槽例外（通栏、外边距、网格位置）。
-2. **字号与颜色走 kit 与令牌**（`--dsw-*` / `--wb-*`），不写字面值。**重点可以大**：
-   一个"余额 / 总数"那种要突出的数字，用刻度里最大那档 `--dsw-font-xl-24`（24/32、600），
-   数字加 `font-variant-numeric: tabular-nums`（见 [PANEL.md](PANEL.md) §6）。
-   刻度外非要一个字面值（比如更大的标题数）时，在模块 `README.md` 里写一句为什么。
+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 里是不是已经有了？
 
 ## 8 kit 里没有、但你确定要标准控件
 
 **先问工具**：DIY 会话里调 `workbench_diy_components`（不填给清单与类型面根；`name=Button`
-直接回它的类型文件与那份声明）。工程域用 `dsh-wb-module check --only primitives`
+回它的类型文件与声明）。工程域用 `dsh-wb-module check --only primitives`
 （`--all` 全表 / `--json` 机器档）—— 分桶导出 + 与 kit 求交（`kit 里已有` 的优先用）+
-该写进 `package.json` 的那两行。骨架默认已备好。
-**要看某一件的 prop / 用法**：`--file <名字>` 给绝对路径（`kit` 那条同形：
-`check --only kit --file Card`），`--files | grep <名字>` 出全表 —— 每件都有一个同名（或就近）的 `.d.ts`。
+该写进 `package.json` 的那两行；骨架默认已备好。
+**要看某一件**：`--file <名字>`（`--files | grep <名字>` 全表）。
 
 ```jsonc
 "dsh": { "client": { "external": [ "@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives" ] } },
 "devDependencies": { "@deepseek-ai/dsh-client-ui-primitives": "<外壳钉的那版，精确版>" }
 ```
 
-改完 `pnpm install` 一次（不装 `pnpm typecheck` 报"找不到模块"）。三条会红的边界：只在浏览器侧引
-（宿主侧碰它 `source` 判红）；版本对齐外壳钉的那份（`init` 盖的就是它，别用 `^`）；能拿 kit 的别引。
-宿主侧的契约按需自己声明（[PANEL.md](PANEL.md) §9）。
+改完 `pnpm install` 一次；三条会红的边界（只在浏览器侧引 / 版本精确对齐 / 能拿 kit 的别引）与
+宿主侧的契约都见 [PANEL.md](PANEL.md) §9。

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

@@ -90,12 +90,11 @@ return {
 ```
 
 **浏览器半侧**：写走 `prefs` 通道，读还是模块自己的只读口（别为配置另开一条）。
-`Field`（标签 + 提示 + 输入框的排布）与 `wb-textField` 的内边距都是外壳给的默认，**模块不需要为"能看"写 CSS**：
+排版与内边距都是外壳给的默认（`Field` / `TextField`），**模块不需要为"能看"写 CSS**：
 
 ```tsx
 const write = useHostWrite({ channel: 'prefs', resource: 'your-module' });
-// Field + TextField / ChoiceGroup，外面套 SettingsSection，保存用 SaveBar；失败留在原地
-// （输入框的内边距和"标签 + 提示"的排布由外壳给默认，模块不用自己写 CSS）
+// 控件用 kit 的（Field + TextField / ChoiceGroup），外面套 SettingsSection，保存用 SaveBar；失败留在原地
 write.send({ ignored, timeoutSeconds, workspace });
 ```
 
@@ -120,19 +119,28 @@ agent 那一侧也要能通过模块自己的能力读到同一份偏好。
 - **默认收起**：历史、明细折叠，露出最近一条；只有一条时不给折叠三角（没有可展开的东西）。
 - **屏幕上的字越少越好**：他能看懂的（红点绿点、数字）就不用再写一段规则解释；删掉的东西不要留一行说明。
 - **默认状态点**只有四种意思：在做 / 做完了 / 出错 / 没在跑。
-- **外链一律用 kit 的 `Link`**（`h(Link, { href: … }, 文案)`），而且**它自带的样子就是唯一一份**：
-  新窗口 + `rel="noopener noreferrer"` + 12px 正文色 + hover 下划线 + 自带那个外链小箭头。
-  **别去掉箭头、别换箭头、别自己调**（没有 `icon` 这个口子）—— 全仓的链接必须长得一样。
+- **外链一律用 kit 的 `Link`**（`h(Link, { href: … }, 文案)`）：新窗口 + `rel` + 自带外链箭头，
+  **它自带的样子就是唯一一份，别去掉箭头、别换箭头、别自己调**（没有 `icon` 这个口子）——
+  全仓的链接必须长得一样。
   模块源码里手写 `<a>` / `h('a', …)` 会被「样式归属」判据**直接判红**。
   **文案里也不许自带箭头**（`'去网关看账单 →'` 这种）—— 箭头由组件给，自带的话页面上就是两颗。
   它内部已经把 dsh 的图标原语包好了，所以模块**不用**为它声明 `client.external`。
-- **"去看某处"用哪个**：跳**整张卡对应的系统** → 卡头的图标按钮（`CardHead.platformHref`：只有图标 + Tooltip。
-  **给这一个就够了**，那颗 ↗ 立刻就画；`platform` / `platformTitle` 是可选的，只决定 Tooltip 与
-  `aria-label` 上的字 —— 少给一个**不会**少画那颗 ↗）；
+- **哪几种手写 `<a>` 不算 `Link`（判据不该咬、也别硬迁）**：判据钉的是**"手写 `<a>` 这件事本身"**
+  （`Link` 是唯一出处），下面三类**有意**留着，因为它们**不是"正文链接"**——
+  - **图标链**（icon-only 的 `<a>`，靠 `title` / `aria-label` 顶着）：`Link` 一定会多画一颗 ↗，
+    套进去就是两颗，尺寸与槽位它也表达不了 ⇒ 留 `<a>`。
+  - **按钮皮的链**（`.anchorButton` 那类 28 高 / 描边的"看起来像按钮、实际是链接"）：**必须是链接的动作
+    留真 `<a>`** —— `href` 带来的是中键新开、右键复制链接、悬停看 URL；塞成
+    `onClick: () => window.open(…)` 的按钮，这三件一起丢。
+  - **整行链**（一行整体可点，`flex: 1` / `color: inherit`）：它是**那条行的布局槽**，不是正文里的字。
+  **要放宽这一条就走棘轮**：那张已知豁免表（`module-tools` 的 `style` 判据里，`ANCHOR_EXEMPT`）
+  **只许减不许加**（迁一处删一行）；真要加一格，那是**改判据口径**，得写清"为什么 `Link` 表达不了它"。
+  口径的权威那份是 `style.mjs` 里 `BARE_ANCHOR` 那一段注释（`ANCHOR_EXEMPT` 上面）
+  与 `module-tools/README.md` 的 `style` 那一行。
+- **"去看某处"用哪个**：跳**整张卡对应的系统** → 卡头那颗图标按钮（`CardHead.platformHref`，给这一个就够）；
   跳**一个具体页面 / 一条具体记录** → `Link`（正文里的文字链接）；**触发一个动作**（刷新、重建、去登录）→
   dsh 的 `Button`，或阻断屏里的 `action`。区别在"跳去哪"和"它是不是一个动作"，不在好看不好看。
-- **标签 + 输入框的排布用 `Field`**，输入框用 `TextField` —— 内边距与排版是外壳给的默认，
-  别为"能看"写模块自己的 CSS（见 §5.1）。
+- **标签 + 输入框用 `Field` + `TextField`**（排布与内边距是外壳的默认，别自己写 CSS，见 §5.1）。
 - **要做什么用哪件，照 [KIT.md](KIT.md) 抄**（"要做什么 → 用哪件 → 最小写法"的表）。
   下面几条是口径，KIT.md 是写法。
 - **字号与重点**：走那把刻度（`--dsw-font-*`：11 / 12 / 13 / 14 / 16 / 20 / 24），

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

@@ -14,7 +14,7 @@
 | `standalone` | "只有工作台源码在场才编得过" ⇒ 发出去就散架 | 别引用工作台源码；`tsconfig` 的 `paths` 用**相对路径**（`"./src/*"`） |
 | `markers` | 内网域名 / 企业内部名泄进要公开发布的包 | 别写进包里；要配就落到模块自己的配置面 |
 | `alias` | `@/` 伸进工作台源码 ⇒ 装的人手上没那份源码 | `@/` 只许指自己 `src/`；跨包走包名 |
-| `style` | 模块定义 `.wb-*` 覆盖外壳类；手写「标签+控件」行 / 操作区 | 样式走 `*.module.css`（不带 `wb-` 前缀）；借外壳类写 `:global(.wb-…)`；行与操作区用 kit 的 `FormRow(s)` / `FormActions`（[KIT.md](KIT.md) §5） |
+| `style` | 模块定义 `.wb-*` 覆盖外壳类；手写行 / 操作区 / **整张表单**（F1–F4） | 样式走 `*.module.css`（不带 `wb-` 前缀）；借外壳类写 `:global(.wb-…)`；行与操作区用 kit 的 `FormRow(s)` / `FormActions`，整张表单用 `Form`（[KIT.md](KIT.md) §5）。**F4**：源码里出现裸 `<form`、或手写行槽类（`wb-formRow` / `wb-formRows` / `wb-field`）⇒ 红（口径见 ADR-0068） |
 | `arch` | 结构退化（巨文件 / 反向依赖 / 跨运行时 / 表外目录 / 模型层没测试） | 见「第十二条 `arch`」 |
 | `lint` | 单文件语法卫生（`as any` / 残留 `console`、`debugger` / 内联颜色、`!important` / react-hooks） | 见「第十三条 `lint`」 |
 
@@ -120,9 +120,9 @@ export default [
 他说"一片空白 / 一直转圈 / 数字不对"时，**先取证再改代码**；前一步有结论就停在那儿修：
 
 1. **`workbench_diy_panel`** —— 这个工作区面板现在什么样：哪几张卡、每张最后一次取数是读到了还是读不到（带宿主回的码与原文）、崩过没（原因 + 次数）。有答案就别往下走。
-1.5 **看这一张卡**（`workbench_diy_screenshot` / `workbench_diy_html` / `workbench_diy_find` / `workbench_diy_eval`）—— 打的是**用户当前那一页**上工坊那块板里这张卡（`unit=…`）：`screenshot` 给图（要卡那一块先量盒子、填 `clip`）、`html --as json` 给结构树、`find` 给元素与 `ref`、`eval` 算派生读数（对比度 / 可见文本；`in: 'card'` 注入卡根 `root`，脚本自己 `return`）。配合上一步把"看起来不对"说成"哪一处不对"。**这一族（浏览器那 14 把 + `logs_*`）要先 `workbench_diy_debug_start`**（`unit=…`；会请用户点头一次）—— 没有这场约定一律当场拒；不看屏先 `_pause`，收工 `_stop`。（`_panel` / `_status` / `_probe` 不碰他那一屏，不用开。）
+1.5 **看这一张卡**（`workbench_diy_screenshot` / `_html` / `_find` / `_eval`）—— 打的是**用户当前那一页**上工坊那块板里这张卡（`unit=…`；四把的入参与拿回见 [FAMILY.md](FAMILY.md) §2），配合上一步把"看起来不对"说成"哪一处不对"。**这一族（浏览器那 14 把 + `logs_*`）要先 `workbench_diy_debug_start`**（`unit=…`；会请用户点头一次）—— 没有这场约定一律当场拒；不看屏先 `_pause`，收工 `_stop`。（`_panel` / `_status` 不碰他那一屏，不用开；`_find` / `_eval` 带 `read=` 时也不碰。）
 2. **`workbench_diy_status`（`unit=…`）** —— 看"起得来"那一行：模块起不来时原因就在那里（装配抛的错 / 声明被拒的原文）。
-3. **自己把那条读跑一遍**：卡片画的就是模块那条宿主路由的返回值 —— `curl '<工作台地址>/workbench/api/<unit>/<route>'`（默认 `http://127.0.0.1:3081`）。接口对而卡片不对 ⇒ 渲染侧；接口就错 ⇒ 宿主侧（照 [DATASOURCE.md](DATASOURCE.md) 重探）。要**浏览器里那一次**的原文，用 `workbench_diy_probe`（`script` 里 `fetch` 自己那条读）。
-4. **最后才看用户那一页**：要控制台走三拍 —— `workbench_diy_logs_watch` → 做那件你怀疑会报错的事 → `workbench_diy_logs_read`（读完 `workbench_diy_logs_stop` 卸掉；钩子上限：每页 200 条、单条 400 字、随刷新消失）。**别用 `opencli browser <会话> console`** —— 那是个 stub（恒回空数组、还 exit 0）。要在页面里跑自己的代码用 `workbench_diy_probe`（**读会话**那页）；看**用户那一页**是什么、有哪些可点的用 `workbench_diy_state`。宿主侧热换 / 装载的报错在**起工作台那个终端**里。
+3. **自己把那条读跑一遍**：卡片画的就是模块那条宿主路由的返回值 —— `curl '<工作台地址>/workbench/api/<unit>/<route>'`（默认 `http://127.0.0.1:3081`）。接口对而卡片不对 ⇒ 渲染侧；接口就错 ⇒ 宿主侧（照 [DATASOURCE.md](DATASOURCE.md) 重探）。要**浏览器里那一次**的原文，用 `workbench_diy_eval`（`read=<站点地址>`，脚本里 `fetch` 自己那条读）。
+4. **最后才看用户那一页**：要控制台走三拍 —— `workbench_diy_logs_watch` → 做那件你怀疑会报错的事 → `workbench_diy_logs_read`（读完 `_logs_stop` 卸掉；上限：每页 200 条 / 单条 400 字、随刷新消失）。**别用 `opencli browser <会话> console`** —— 那是个 stub（恒回空数组、还 exit 0）。要在页面里跑自己的代码用 `workbench_diy_eval` 的 `read=` 档；看**用户那一页**有什么可点的用 `workbench_diy_state`。宿主侧热换 / 装载的报错在**起工作台那个终端**里。
 
 两条纪律：**别让用户截图或替你转述报错**；**验收就是你自己拿这一族走** —— 逐条对着三张表走「打开哪 → 看什么 → 点什么 → 应该看到什么」，`screenshot`/`html`/`find`/`eval` 的读数、动作族的返回、`workbench_diy_network` 的收发包、`logs_*` 的报错都算证据；走通再 `design accept`，走不通的如实说没验过（用户不必在场，也不用请他逐条点头）。工具参数与返回体都是 opencli 的原样（见 [FAMILY.md](FAMILY.md)）。面板运行态是**用户那一页自己报上来的**，第 1 步没有内容时，先让他把工作台切到工坊那个工作区、刷新一次页面再看。

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

@@ -14,7 +14,7 @@ description: 在工作台里凭需求造一个模块（面板上的一块内容
    这一步的产出是 ASCII 画面 + 三张表，不是文字。三张表当场落进模块里的 `design.json`
    （命令与形状：[DESIGN.md](DESIGN.md) §5）—— 只留在对话里等于没定。
 3. **先定数据从哪来** —— [DATASOURCE.md](DATASOURCE.md)：干净机器上没有现成 skill 可抄，
-   用 `workbench_diy_probe`（`url=…, script=…`）复用他的登录去探 —— 两拍、重试、失败码归一
+   用 `workbench_diy_eval` / `_find` 带 `read=<站点地址>`（跑在 `workbench-read` 上）复用他的登录去探 —— 没在站点上我自己开一次，`not-logged-in` / `not-on-site` 两条码按读线约定归一
    都在那把工具里；探明后**固化成一条读**（`@dsh-workbench/shared/host` 的 `browserRead`）。顺手把三态写掉。
    要 agent **真去改东西**（提交 / 发布 / 建单 / 改配置）的，读完 [WRITES.md](WRITES.md) 再动手：
    四步（现成写命令 → 入参 / 出参来源 → 没有预览档的不许试写 → 写完后回读确认）。
@@ -39,7 +39,7 @@ description: 在工作台里凭需求造一个模块（面板上的一块内容
    要看 / 动**他那一屏**（浏览器那 14 把 + `logs_*`）得先开约定：
    `workbench_diy_debug_start`（`unit=…`；会请他点头一次，他会被告知「调试中请留在那一屏」）——
    **没有这场约定，上面那一族一律当场拒**；不看屏了先 `workbench_diy_debug_pause`，收工 `…_stop`。
-   （`workbench_diy_panel` / `_status` / `_probe` 不碰他那一屏，不用开。）
+   （`workbench_diy_panel` / `_status` 不碰他那一屏，不用开；`_find` / `_eval` 带 `read=` 时也**不碰** —— 那走只读线。）
    走法（全表与参数在 [FAMILY.md](FAMILY.md)）：
    - **这一张卡长什么样**：`workbench_diy_screenshot`（要卡那一块就先 `eval` 量盒子、填 `clip`）+
      `workbench_diy_html`（`--as json` 给结构树）；
@@ -78,7 +78,7 @@ description: 在工作台里凭需求造一个模块（面板上的一块内容
 | 面板上该有什么、状态矩阵怎么写、界面习惯 | [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 怎么用**（什么时候调、取数什么时候重来、"在忙"为什么还要挂一会儿） | [HOOKS.md](HOOKS.md) |
+| **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) |
@@ -109,4 +109,5 @@ description: 在工作台里凭需求造一个模块（面板上的一块内容
 - **dsh 已经有的，先从 `kit` 拿**（`@dsh-workbench/core/client`），不许从 DOM + CSS 重画；
   也不直接 import dsh 的包 —— 直接引会被门禁拦，而且那是第二份实例。
 - **工坊里的模块一律 `private: true`，不发到任何源。**
-- **源码零注释**：要说的写进模块自己的 `README.md`。
+- **源码里只许 JSDoc，且贴着导出**（用法住在声明里，tsc 把它搬进 `.d.ts`）；`//`、实现里的解释、
+  以及 `.css` 里的注释照旧不许有。要说的"为什么"写进模块自己的 `README.md` 或 spec。