@dsh-workbench/core 0.3.10 → 0.3.11

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,40 @@ 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-*` / `--wb-*`）。重点数字用 `--dsw-font-xl-24` + `tabular-nums`；
+   刻度外字面值在模块 `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。

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

@@ -1,142 +1,103 @@
-# 联动：agent 做完，用户看到什么
+# 联动：谁在动、何时变、哪一格变
 
-步骤 3 的参考。写的是用户什么时候看到哪一格变，不写这条链怎么接。
+步骤 3 的参考。实现见 §8。
 
-## 1 什么时候面板该动
+## 1 触发规则
 
-| 谁在动 | 用户看到什么 |
+| 触发 | 面板 |
 |---|---|
-| agent **读**了面板这一格的数据 | **那一格**变（按最窄的那个切片重读），值跟对话里那份一样 |
-| agent 读的是面板上没有的东西（明细、日志、某一档子集） | **不动**（面板没有那一格） |
-| agent 只预览、还没真的做 | **不动**（预览不改任何东西） |
-| agent 真的做了 | 相关的那一格**变成新值** |
-| 他自己按的动作 | 那一格**立刻变**，并在原地看到"正在做 / 做完了" |
-| 他自己改了偏好 | 保存后立刻按新的显示 |
-| 别的窗口 / 另一个会话也在改 | 他这里也会变（不需要他刷新） |
+| agent 读面板这一格 | 该格按最窄切片重读；值与对话一致 |
+| agent 读面板外的东西（明细 / 日志 / 子集） | 不变 |
+| agent 只预览 | 不变 |
+| agent 真写 | 相关格变新值 |
+| 用户自按动作 | 该格立即变，原地显示进行中 / 完成 |
+| 用户改偏好 | 保存后按新偏好显示 |
+| 其他窗口 / 会话改动 | 跟随变，无需刷新 |
 
-⚠️ **"读 → 也变"这条是用户定的口径**：理由是「agent 调用工具的时候面板数据也受益」—— agent 刚在对话里
-念了数字，面板得是同一份，否则他到底信哪个。
+一次说清变哪一级：整板 / 一张卡 / 一行。"刷新一下"不合格。只动该动的格，粒度落到"某投影 + 最窄参数"
+（`cmdb/builds?env=dev`）；否则会整卡重读。
 
-**一次说清动的是哪一格**：整块板、某一张卡、还是某一行。写"刷新一下"不算说清 —— 那会让实现的人整卡重读。
+## 2 进行中
 
-**只动该动的那一格**：agent 在一个环境做了一次，不该让别的环境、别的列、整张卡一起重新读一遍（读一次很慢，他会看到整块退回"在读"）。**颗粒度就是这句话在实现里的样子**：动的那一格要能落到"某条投影 + 最窄的那个参数"（`cmdb/builds?env=dev` 这种），写进联动表里。
+- 显示可读的步骤名，不用内部步骤号。
+- 要登录：给登录入口；登录后续跑，不重来。
+- 失败：卡在哪步、一句原因、原始输出（折叠）、一条可照做的路。
+- 不画进度条、不画流程控制台。
 
-## 2 agent 正在干的时候
+中途停止可续：用户说"接着做"即从上次继续。
 
-- 显示到**哪一步**（"正在合并分支"这种他能读懂的一步，不是内部步骤名）；
-- 要**登录**就给他一条去登录的路，登录完这次继续，不用他重来；
-- **失败**给他：卡在哪一步、一句能读的原因、原始输出（折叠起来），以及一条能照做的路；
-- **不画进度条、不画流程控制台**：状态 + 链接 + 原始输出就够。
+## 3 "交给 agent"的内容
 
-一次做一半就停也不是问题：他回来说一句"接着做"，能接着上一次继续，不用从头再来。
+- 哪一类 + 哪个对象 + 多少（按用户点的那一行，不是全量）。
+- 一句"用哪个能力取明细"（agent 打不开面板的 ↗）。
+- 不塞明细本身。
+- 保持用户点的分类；认不出就报错，不退回全量。
 
-## 3 他点"交给 agent"之后，agent 拿到什么
+## 4 收起模块
 
-- **哪一类 + 哪个对象 + 多少**（他点的是哪一行，agent 就该拿到哪一类，不能四行点了都给它同一份全部）；
-- 加一句**该用哪个能力往下拿明细**（agent 打不开面板上那个 ↗，明细只能它自己再问一次）；
-- **明细本身不要塞进去**（一页几十行按会话付费，而 agent 拿到那句指引自己会去要）；
-- 他点的那一类要跟着走（点"圈复杂度"就只给圈复杂度，不能悄悄退回整份）；
-- 认不出的那一类要**当场说错**，不许默默退回整份（他要的是这一块，给全部比报错更糟）。
+收起 = 该项目内 agent 也失去该能力。收起时说明；收起后能力清单更新，对话显示"能力有更新"；其他项目不受影响。
 
-## 4 收起模块意味着什么
+## 5 不陈旧
 
-把一块面板收起来 = **这个项目里 agent 也做不了这件事**。
+覆盖三种：切项目 → 立刻显示新项目；其他窗口 / 会话改动 → 跟随；程序刚更新 → 不因"我比你还新"而不收更新。
+允许秒级延迟，但要说明；不得停在旧值等手动刷新。
 
-- 这一条要在**点头收起的时候**就说清（"这个项目里它的能力也一起下线"）；
-- 收起之后 agent 手上的能力清单会变，用户会在对话里看到一句"能力有更新"；
-- 别的项目不受影响。
+## 6 联动表（步骤 3 产出）
 
-## 5 面板凭什么不旧
-
-三种情况都要有答案：
-
-1. **他切了项目** —— 看到的立刻是新项目的数据；
-2. **别的窗口 / 另一个会话也改了** —— 他这里会跟着变；
-3. **程序刚更新过（开发时最常见）** —— 不会因为"我比你还新"这种判断而永远收不到更新。
-
-允许有延迟（几秒），但延迟要说清；**不允许停在旧值上、只有手动点刷新才动**。
-
-## 6 联动场景表（步骤 3 的产出）
-
-| 谁在动 | 面板什么时候变 | 哪一格变 | 用户看到什么 |
+| 谁在动 | 何时变 | 哪一格 | 看到什么 |
 |---|---|---|---|
-| agent 读了面板这一格的数据 | 读完自动 | 那一格（最窄那个切片） | 那一格出已有的加载态（约半秒）→ 与对话同值 |
-| agent 读了面板上没有的那份 | 不变 | — | 对话里一段结果 |
-| agent 预览 | 不变 | — | 对话里"将要做什么" |
-| agent 真的做 | 做完之后自动 | 相关那一格 | 新值 |
-| 他自己按动作 | 立刻 + 做完再更新 | 那一格 | 确认条 → "正在做" → 结果 |
-| 他改偏好 | 保存后 | 整张卡按新偏好 | 回到看板、数据已换 |
-| agent 改他的面板 | 自动 | 面板多了 / 少了 / 换了顺序 | 界面变了 + 对话里"能力有更新" |
-| 装 / 卸能力 | 自动 | 相关的那几处 | 状态变 |
-| 一件长事在跑 | 自动刷新进度 | 那张卡的进度那一行 | 到哪一步 / 要登录 / 失败原因 |
-| 别的窗口也在改 | 自动 | 同"真的做" | 同"真的做" |
-| 程序刚更新过 | 全部重读一次 | 整块 | 不会退回旧值 |
-| 他自己点刷新 | 立刻 | 那一份 | 转圈，然后新值 |
-| 他切项目 | 立刻 | 整块 | 新项目的数据 |
-| 模块在这个项目被收起 | 自动 | 少一张卡 | 对话里"能力有更新" |
-
-## 7 读工具也要说清"它对应面板哪一格"
-
-用户会在对话里问到面板上就有的那格数字 —— 两处必须对得上（否则他得决定信哪个）。
-所以每把**读**工具在设计时就要回答三句：
-
-- 它读的那份数据，是面板上**哪一格**？
-- 那一格**最窄的切片**是什么（哪个环境的哪一列 / 哪一档筛选 / 就是整张卡）？
-- 手里那份**是不是就是**那一格的值？
-
-第三种答案决定面板怎么动：
-
-| 它读的是 | 面板 |
+| agent 读面板这一格 | 读完 | 该格（最窄切片） | 加载态（约半秒）→ 与对话同值 |
+| agent 读面板外 | 不变 | — | 对话内结果 |
+| agent 预览 | 不变 | — | 对话内"将要做什么" |
+| agent 真写 | 完成 | 相关格 | 新值 |
+| 用户自按 | 立即 + 完成再更新 | 该格 | 确认条 → 进行中 → 结果 |
+| 用户改偏好 | 保存后 | 整卡 | 回看板、数据已换 |
+| agent 改面板 / 装卸能力 | 自动 | 增删或顺序，或相关几处 | 界面变化 + "能力有更新" |
+| 长任务运行 | 自动推进度 | 卡的进度行 | 到哪步 / 要登录 / 失败原因 |
+| 其他窗口 / 程序更新 | 自动 | 同"真写" / 整板 | 同"真写" / 不回旧值 |
+| 切项目 / 点刷新 | 立即 | 整板 / 该份 | 新项目 / 转圈后新值 |
+| 模块在项目内被收起 | 自动 | 少一张卡 | "能力有更新" |
+
+## 7 读工具对应哪一格
+
+每把读工具回答三句，写进能力清单：
+
+1. 读的数据是面板哪一格？
+2. 该格最窄切片是什么（哪个环境哪一列 / 哪档筛选 / 整卡）？
+3. 手里这份是否就是该格的值？
+
+| 读的范围 | 面板 |
 |---|---|
-| 面板这一格范围内的数据 | 那一格重读；**手里那份就是那一格的值**时可以直接交出去（面板不再打一遍平台） |
-| 面板上没有的东西（明细 / 日志 / 单条） | **不动**（面板没有那一格） |
-| 面板某一格的**子集**（只读 TODO、limit 更小） | **不动**，而且**不许**把子集当那一格交出去（那是错值）—— 要对得上就让 agent 读全量那一档 |
-
-三句都写进能力清单（用户看的是"哪一格会跟着动"）。
-
-→ 实现：本文 §1 与 §7。
+| 该格范围内 | 该格重读；手里就是该格值时可直接交出（不再重打平台） |
+| 面板外（明细 / 日志 / 单条） | 不变 |
+| 该格的子集（只读 TODO、更小 limit） | 不变；不得当该格交出（错值）—— 要一致就读全量档 |
 
-## 8 宿主侧的四个口子（实现形状）
+## 8 宿主侧实现
 
-上面说的"哪一格变"，落到代码就四个可选字段；**不写 `factsOf` 的模块，面板那一格不会自己新**。
+四个可选字段。不写 `factsOf` 的模块，面板格不会自己新。
 
 ```ts
 factsOf: (call) => (call.source === REBUILD_TOOL ? [factOfRoute(HEALTH_ROUTE)] : undefined),
 ```
 
-* `call.source` 是**能力名**、`call.args` 是它这次收到的参数；返回"这次动到了哪几条事实"，
-  返回 `[]` = 涉及但没有具体事实，`undefined` = 跟面板无关（例：明细、日志那种面板上没有的东西）。
-* 事实名不要自己拼字符串：用 `factOfRoute('<unit>/<路由>')`（`@dsh-workbench/shared`）——
-  **卡片读的那条路由对应哪条事实，就是它算出来的那条**。
-* **读能力也要认领**（§1 与 §7 的口径）：agent 只是读了一次，那一格也该重读。
-* 长任务动完也要认领：`longTasks.create({ …, facts: () => [factOfRoute(HEALTH_ROUTE)] })`。
+- `call.source` = 能力名，`call.args` = 本次参数。返回本次涉及的事实：`[]` = 涉及但无具体事实；
+  `undefined` = 与面板无关。
+- 事实名用 `factOfRoute('<unit>/<路由>')`（`kit.api.factOfRoute`），不要手拼。读能力也认领；长任务写
+  `longTasks.create({ …, facts: () => [factOfRoute(HEALTH_ROUTE)] })`。
 
 ```tsx
 const rev = useFactRevision(factOfRoute(HEALTH_ROUTE));
 const resource = useApiResource(ROUTE, query, rev, {});
 ```
 
-卡片的 `useApiResource` **默认就订阅** `factOfRoute(route)`（`use-api-resource.ts` 里那句
-`options.fact ?? factOfRoute(route)`），所以多数情况你什么都不用接；用户自己按的那个动作做完，
-用 `useFactInvalidate()()` 把这条事实标脏。
+`useApiResource` 默认订阅 `factOfRoute(route)`；用户自按动作完成后用 `useFactInvalidate()()` 标脏。
 
 ```ts
 context: { kinds: ['module'], render: async (ref) => `模块 ${ref.parts[0]}：…` },
 warmReads: () => [['<unit>', '<target>']],
 ```
 
-* `context`：agent 上下文里引用你这一格时（例：`diy-doctor/module/fx-rate`），由你把它渲染成人话；
-  `kinds` 列出你认哪几类，**参数形状不对就 `throw`**（说清"形状不对"，别默默回一段错的）。
-  判据只查形状（`kinds` 非空、`render` 是函数），**不会拿假参数调它** —— 那些参数只有真引用才有。
-* `warmReads`：**只给"走 opencli 适配器"的读用**。条目就是那条 opencli 命令的 argv，外壳在启动的
-  preflight 里拼成 `opencli <argv…> --site-session persistent -f json` 先跑一遍（把站点登录态与首屏焐热）。
-  例：`[['cmdb', 'enterprises']]`（一条 opencli 命令的 argv，还带测试）。
-  **本机读盘、browser bridge、直接打接口的读一律不要写这里** —— 写了外壳会去跑一条不存在的命令，
-  preflight 只会给个 warn；这些读没有"冷启动"可省，焐不热任何东西。
-* `values`（`deps.values`，`ValueHandoff`）：把一次写的结果交给别的单元 —— `values.hand({fact, key}, 值)`，
-  另一边 `values.take({fact, key})` 取；`key` 自己起（例：一次发布的结果给联动那一格用）。
-
-## 9 范例
-
-要一个"同形状、能跑"的样子：[SKILL.md](SKILL.md) 的「找不到一件事的时候」—— 模板
-（`template-diy/` / `template/`）与装机模块的源码都可以直接读。
+- `context`：把 agent 上下文里的引用渲染成人话；`kinds` 列出识别的类型；形状不对就 `throw`。
+- `warmReads`：只给走 opencli 适配器的读。条目是该 opencli 命令的 argv，启动 preflight 先跑一遍。
+  本地读盘、browser bridge、直连接口的读不要写。
+- `values`：跨单元传值。`values.hand({fact, key}, 值)` / `values.take({fact, key})`。