@dsh-workbench/core 0.3.4 → 0.3.6

package/dist/types/shared/hooks/use-card-summary.d.ts

@@ -1,7 +1,14 @@
+/**
+ * 卡片报给面板那一格的两个数：`refreshing` 还在不在忙、`at` 最近一次读到值的时间（没有是 `null`）。
+ */
 export interface CardSummary {
     readonly refreshing: boolean;
     readonly at: number | null;
 }
+/**
+ * 自己搭卡片、要把 `{ refreshing, at }` 在变化时交给调用点上报面板时调用；`onSummary` 要稳定引用
+ * （一般 `useCallback`），否则每次渲染都会上报一次。`useUnitBoard` 已经把这条接好。
+ */
 export declare function useCardSummary(onSummary: (summary: CardSummary) => void, summary: {
     readonly refreshing: boolean;
     readonly at: number | null | undefined;

package/dist/types/shared/hooks/use-diy-debug.d.ts

@@ -1,8 +1,21 @@
 import type { DebugState } from '@dsh-workbench/shared';
 import type { HostWrite } from './use-host-write';
+/**
+ * 调试约定的读路由（宿主侧那半同名）。
+ */
 export declare const DIY_DEBUG_ROUTE = "panels/diy-debug";
+/**
+ * 调试约定那条事实的名字：写完调 `useFactInvalidate(DIY_DEBUG_FACT)`，读者自动重取。
+ */
 export declare const DIY_DEBUG_FACT = "diy-debug";
+/**
+ * 要读“现在的调试约定是什么”时调用（左栏底部那枚状态）；跟着事实变化自动重取，不上报面板；
+ * 还没读到或后端说没有约定时都是 `null`。
+ */
 export declare function useDiyDebugState(): DebugState | null;
+/**
+ * 要发“开始 / 暂停 / 继续 / 结束调试”那几把动作时调用；写走 `diy-debug/act` 通道。
+ */
 export declare function useDiyDebugAct(): HostWrite<{
     text?: string;
 }>;

package/dist/types/shared/hooks/use-diy-record.d.ts

@@ -1,8 +1,21 @@
 import type { RecordState } from '@dsh-workbench/shared';
 import type { HostWrite } from './use-host-write';
+/**
+ * 录制交接的读路由（宿主侧那半同名）。
+ */
 export declare const DIY_RECORD_ROUTE = "panels/diy-record";
+/**
+ * 录制交接那条事实的名字：写完调 `useFactInvalidate(DIY_RECORD_FACT)`，读者自动重取。
+ */
 export declare const DIY_RECORD_FACT = "diy-record";
+/**
+ * 要读“这一段录制交接进行到哪了”时调用（左栏底部那枚状态）；跟着事实变化自动重取，不上报面板；
+ * 还没读到或后端说没有交接时都是 `null`。
+ */
 export declare function useDiyRecordState(): RecordState | null;
+/**
+ * 要发录制交接那几把动作（准备 / 读回 / 收尾）时调用；写走 `diy-record/act` 通道。
+ */
 export declare function useDiyRecordAct(): HostWrite<{
     text?: string;
 }>;

package/dist/types/shared/hooks/use-facts.d.ts

@@ -1,3 +1,13 @@
+/**
+ * 渲染里要“这条事实的版本号”时调用：版本一变，喂给 `useApiResource` 的 key 就变、读自动重来。
+ * 卡片读数默认订的 `factOfRoute(route)` 已经接好，只有要订别的事实才显式传 `fact`。
+ */
 export declare function useFactRevision(fact: string): number;
+/**
+ * 不在渲染里的地方（宿主事件、定时器里看到的旧值）要听事实变化时用它；返回值就是退订函数，用完记得退。
+ */
 export declare function subscribeFactRevision(fact: string, listener: () => void): () => void;
+/**
+ * 写完之后把这条事实标脏时调用：不标，面板就停在旧值；不传 `fact` 是把所有事实一起标脏。
+ */
 export declare function useFactInvalidate(): (fact?: string) => void;

package/dist/types/shared/hooks/use-host-write.d.ts

@@ -1,4 +1,8 @@
 import { type WriteChannel, type WriteOutcome } from '@dsh-workbench/shared';
+/**
+ * 一个写通道的句柄：`busy` 在发、`failed` / `detail` 上一条人话失败（没有是 `null`）、
+ * `send(body, { silent })` 回 `WriteOutcome`、`fail(message, detail?)` 本地就知道不行时自己塞一条、`clear()` 清掉。
+ */
 export interface HostWrite<T> {
     readonly busy: boolean;
     readonly failed: string | null;
@@ -9,9 +13,17 @@ export interface HostWrite<T> {
     fail(message: string, detail?: string): void;
     clear(): void;
 }
+/**
+ * 写通道的配置：`channel` 用哪个前缀、`resource` 挂在它的哪一格（多数通道留空）、`networkText` 网络不通时那句人话。
+ */
 export interface HostWriteOptions {
     readonly channel: WriteChannel;
     readonly resource?: string | undefined;
     readonly networkText: string;
 }
+/**
+ * 组件里要写（发 POST）时调用 —— 写只走这条，别在组件里自己 `fetch`。
+ * `send` 失败自动落到 `failed` + `detail`（界面直接显示，别自己拼）；`silent: true` 是不打扰：不动 `busy` / `failed`，
+ * 结果只从返回值拿。返回的 `busy` 是这一路写有没有在飞。
+ */
 export declare function useHostWrite<T>(options: HostWriteOptions): HostWrite<T>;

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

@@ -1,7 +1,21 @@
-import { type LongTaskStatus } from '@dsh-workbench/shared';
+import { type LongTaskStatus, type WriteOutcome } from '@dsh-workbench/shared';
+/**
+ * 这一单元的长任务清单与停止口：`runs` 是这次读交回的那一批（读数还没回来时是空数组）；
+ * `stop(id)` 请外壳停某一趟 —— 回执没成就带回一句人话（调用点自己决定说不说）；
+ * `stopping` 是正在请求停止的那一趟 id（没有就是 `null`），`stopFailed` 是上一次停止请求失败那句话（没有就是 `null`）。
+ */
 export interface LongTaskFeed<T> {
     readonly runs: readonly T[];
+    stop(id: string): Promise<WriteOutcome<unknown>>;
+    readonly stopping: string | null;
+    readonly stopFailed: string | null;
 }
+/**
+ * 卡片要轮询长任务那一行时调用：有在跑的（`running` / `needs-login`）按 `longTaskPollMs` 走快档、空闲走慢档；
+ * `workspace` 为 `null`、`mocked: true` 或 `enabled: false` 时不轮。换单元 / 换工作区就是换读数身份，
+ * 旧那批立刻清空、读数回来前 `runs` 是空数组。
+ * `stop(id)` 走 actions 通道的 `<单元>/runs/stop`；不在跑的那一趟会带回一句人话，不抛错。
+ */
 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.6",
   "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.6"
   },
   "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`）；别自己画进度。传 `stop` 要宿主认 `signal`、peer 抬到带它那版（[TOOLS.md](TOOLS.md) §9）。
 
-**`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)`
+（长标签不折行、同一组共用一个标签列，别自己给标签写宽度）；**控件的宽度也别自己写**
+（字段控件自己吃满控件槽那一格，ADR-0052 §13）。非行的子项（如分组标题）自动通栏。
 
 **反例（别这么写）**：
 
 ```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。