@dsh-workbench/core 0.3.11 → 1.0.0-beta.1

package/scripts/seed-profile.sh

@@ -6,7 +6,7 @@
 #
 # **设置不在这里继承**（这里曾经把 web 的 cordis.patch.yml 快照一份过来）：
 # 工作台自己的 patch 是唯一真相，想搬 web 的哪几行由用户走「设置 → 配置同步」。
-# 为什么这么分（安装 vs 设置）、为什么不再是自动的：.scratch/config-sync/spec.md
+# 为什么这么分（安装 vs 设置）、为什么不再是自动的：内部设计记录
 #
 # 幂等 / 可续跑：profile 已存在就跳过创建，隔离层已存在就跳过追加
 # —— 重复运行不会覆盖任何东西。
@@ -23,8 +23,11 @@ set -euo pipefail
 
 DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
 PROFILE="${WORKBENCH_PROFILE:-workbench}"
-SRC_PROFILE="$DSH_HOME/profiles/web"
+SRC_PROFILE_NAME="${WORKBENCH_SOURCE_PROFILE:-web}"
+SRC_PROFILE="$DSH_HOME/profiles/$SRC_PROFILE_NAME"
 DST_PROFILE="$DSH_HOME/profiles/$PROFILE"
+WORKBENCH_HOME="${DSH_WORKBENCH_HOME:-$DSH_HOME/$PROFILE}"
+export DSH_WORKBENCH_HOME="$WORKBENCH_HOME"
 PKG='@dsh-workbench/core'
 REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 GIT_TOP="$(git -C "$REPO_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
@@ -93,8 +96,10 @@ if [ "${1:-}" = "ensure-selected" ]; then
   exit 0
 fi
 
-[ -f "$SRC_PROFILE/package.json" ] ||
-  die "找不到 $SRC_PROFILE —— 请先跑一次 'dsh web'，让 web profile 落地。"
+HAS_SOURCE=0
+if [ -f "$SRC_PROFILE/package.json" ]; then
+  HAS_SOURCE=1
+fi
 [ -f "$ISOLATION" ] || die "找不到 $ISOLATION"
 
 DST_PATCH="$DST_PROFILE/cordis.patch.yml"
@@ -107,8 +112,8 @@ DST_PATCH="$DST_PROFILE/cordis.patch.yml"
 if [ -f "$DST_PROFILE/package.json" ]; then
   echo "→ profile '$PROFILE' 已存在，跳过创建"
 else
-  echo "→ 创建 profile '$PROFILE'（模板: web）"
-  dsh "$PROFILE" --from-default-profile web --dump-config >/dev/null
+  echo "→ 创建 profile '$PROFILE'（模板: ${SRC_PROFILE_NAME}）"
+  dsh "$PROFILE" --from-default-profile "$SRC_PROFILE_NAME" --dump-config >/dev/null
 fi
 
 [ -f "$DST_PATCH" ] || die "profile 缺少 $DST_PATCH"
@@ -119,8 +124,10 @@ fi
 # 改过（例如启用了某个可选 bundle）。所以这里把 web 清单里的 bundles
 # 并进来，同时保留 workbench 自己已有的额外项（例如 @dsh-workbench/core），
 # 使脚本可重复运行。
+if [ "$HAS_SOURCE" = "1" ]; then
 WB_MANIFEST="$DST_PROFILE/package.json" \
   WEB_MANIFEST="$SRC_PROFILE/package.json" \
+  WB_SOURCE_NAME="$SRC_PROFILE_NAME" \
   node -e '
 const fs = require("node:fs");
 const read = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
@@ -137,15 +144,18 @@ wb.dsh = Object.assign({}, wb.dsh, {
   profile: Object.assign({}, webProfile, wbProfile, { bundles: merged }),
 });
 fs.writeFileSync(process.env.WB_MANIFEST, JSON.stringify(wb, null, 2) + "\n");
-console.log("→ 已继承 web 的 bundle 列表: " + merged.join(", "));
+console.log("→ 已继承 " + process.env.WB_SOURCE_NAME + " 的 bundle 列表: " + merged.join(", "));
 '
+else
+  echo "→ 本机还没有来源 profile '$SRC_PROFILE_NAME'；用 dsh 出厂模板的 bundle 列表（如需继承它的设置/插件，先跑一次来源 profile）"
+fi
 
 # ── 第 2.5 步：修掉旧版启动器留下的"装出来的那份被当成仓库副本" ──────────
 #
 # 旧判据只问 `git rev-parse --show-toplevel`（"**某个祖先**是不是仓库"），于是包目录落在任何
 # 仓库里的机器（最常见：`$HOME` 是 dotfiles 仓库，而 npm/nvm 的前缀就在 `$HOME` 下）在 setup
-# 时会把**全局安装目录**以 `link:` 装进 profile —— 市场里工作台那一行因此说「这份是本仓正在
-# 开发的那一份，不从源上取。」（不比对源、不提示更新），而 `npm i -g …@latest` 还会悄悄换掉
+# 时会把**全局安装目录**以 `link:` 装进 profile —— 市场里工作台那一行因此打上「本地」标
+# （不比对源、不提示更新），而 `npm i -g …@latest` 还会悄悄换掉
 # profile 跑的东西。判据窄到只认那一个坏形状：**我自己是装出来的那份**（GIT_TOP 为空）
 # **且 profile 里那条 `link:` 指着的正是我自己这份目录** —— 指别处的 link:（用户自己链的）不动。
 if [ -z "$GIT_TOP" ] && [ -f "$DST_PROFILE/package.json" ]; then
@@ -184,6 +194,7 @@ else
   printf '\n' >>"$DST_PATCH"
   cat "$ISOLATION" >>"$DST_PATCH"
   echo "→ 已追加隔离层（sessions / storages / attachments 分家）"
+  rm -f "$DST_PATCH.tmp"
 fi
 
 # ── 第 4 步：建 DIY 工坊 ────────────────────────────────────────────────
@@ -206,7 +217,8 @@ cat <<EOF
 
 profile '$DST_PROFILE' 的骨架好了（bundle 清单 + 会话/存储/附件隔离层）。
 
-设置**不在**这里继承：想要 web 那边的模型供应商 / 搜索源 / MCP，起工作台后去
+设置与本地插件按创建时的勾选从 $SRC_PROFILE_NAME 继承；直接跑 setup 时只继承
+bundle 清单，想要 web 那边的模型供应商 / 搜索源 / MCP，起工作台后去
 「设置 → 配置同步」按行勾（读的是那个 profile 的 cordis.patch.yml；搬完重启生效）。
 
 装 bundle —— 两条**等价**的路，任选一条（都走 dsh 的 runPluginCommand，装完会

package/scripts/seed-workshop.sh

@@ -20,6 +20,8 @@
 set -euo pipefail
 
 DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+WORKBENCH_HOME="${DSH_WORKBENCH_HOME:-$DSH_HOME/workbench}"
+export DSH_WORKBENCH_HOME="$WORKBENCH_HOME"
 SELF="${BASH_SOURCE[0]}"
 while [ -L "$SELF" ]; do
   SELF="$(cd "$(dirname "$SELF")" && pwd -P)/$(readlink "$SELF")"
@@ -36,8 +38,8 @@ MODE="${1:-skeleton}"
 # 仓库副本，去 link 一个不存在的 `../module-tools`，脚本当场死在 `cd` 上 —— 而它是**后台**
 # 被拉起来的（宿主自举 / 启动器），症状就是"工坊怎么都没建起来，一声不响"。
 #
-# 所以认仓库要认**本仓的形状**：根上同时有 packages/workbench 与 packages/module-tools。
-if [ -n "$GIT_TOP" ] && [ -f "$GIT_TOP/packages/workbench/package.json" ] &&
+# 所以认仓库要认**本仓的形状**：根上同时有 packages/core 与 packages/module-tools。
+if [ -n "$GIT_TOP" ] && [ -f "$GIT_TOP/packages/core/package.json" ] &&
   [ -f "$GIT_TOP/packages/module-tools/package.json" ]; then
   IN_REPO=1
 else
@@ -71,8 +73,8 @@ fi
 # 冻结接口：状态文件 $DSH_HOME/workbench/diy/.sync.json =
 #   { state: "ok"|"syncing"|"failed", version: <基准版本>, at: <ISO>, reason?: <一句话> }
 SHELL_ROOT="${DSH_WB_SHELL_ROOT:-}"
-DIY_DIR="$DSH_HOME/workbench/diy"
-SEED_LOG="$DSH_HOME/workbench/seed.log"
+DIY_DIR="$WORKBENCH_HOME/diy"
+SEED_LOG="$WORKBENCH_HOME/seed.log"
 SYNC_STATE="$DIY_DIR/.sync.json"
 SYNC_LOCK="$DIY_DIR/.sync.lock"
 SYNC_BACKOFF_SECONDS=3600
@@ -103,7 +105,7 @@ target_version() {
 }
 
 # 外壳 manifest 里钉的那份 dsh UI 版本（模块模板默认带的那个 devDependency，见
-# `.scratch/dsh-primitives-face/spec.md` §3.1）。源优先**基准**（正在跑的那份外壳），
+# `内部设计记录` §3.1）。源优先**基准**（正在跑的那份外壳），
 # 没有才退回跑脚本这份副本 —— 与 link_workshop_skills 同一条口径。
 # 读不到就留空：调用方按"不写这一项"处理（模块 `init` 那边有自己的兜底常量与一句人话）。
 shell_primitives_version() {
@@ -143,7 +145,7 @@ compute_specs() {
     SHARED_SPEC="^$version"
   fi
   # dsh 原语（模块模板默认带的那个）：**精确版**，与模块自己那份 devDependency 对齐 ——
-  # 类型面要对齐对账过的那一版（`.scratch/dsh-primitives-face/spec.md` §3.1）。
+  # 类型面要对齐对账过的那一版（`内部设计记录` §3.1）。
   # 空 = 读不到外壳 manifest，就**不写这一项**（模块 `init` 有自己的兜底常量）。
   local primitives_version
   primitives_version="$(shell_primitives_version)"
@@ -286,9 +288,7 @@ sync_lock_stale() {
 
 # 强行清锁：只给"判定持锁者已崩"那条路用（那时锁已经不是原主的了）。
 drop_sync_lock() {
-  case "${SYNC_LOCK:-}" in
-    */workbench/diy/.sync.lock) rm -rf "$SYNC_LOCK" ;;
-  esac
+  if [ "${SYNC_LOCK:-}" = "$WORKBENCH_HOME/diy/.sync.lock" ]; then rm -rf "$SYNC_LOCK"; fi
 }
 
 # 抢锁的返回值：0 = 抢到；1 = 同一代的人正装着（跳过）；2 = 这地方建不出锁；3 = 另一代正装着、等过一轮没抢到。
@@ -346,13 +346,11 @@ stop_sync_heartbeat() {
 
 # 只删**自己的**锁：锁被清过 / 换了主人时，这里必须放手（否则新持锁者的 install 被砍在半路）。
 release_sync_lock() {
-  case "${SYNC_LOCK:-}" in
-    */workbench/diy/.sync.lock)
-      if [ -n "${SYNC_LOCK_TOKEN:-}" ] && [ "$(lock_field owner)" = "$SYNC_LOCK_TOKEN" ]; then
-        rm -rf "$SYNC_LOCK"
-      fi
-      ;;
-  esac
+  if [ "${SYNC_LOCK:-}" = "$WORKBENCH_HOME/diy/.sync.lock" ]; then
+    if [ -n "${SYNC_LOCK_TOKEN:-}" ] && [ "$(lock_field owner)" = "$SYNC_LOCK_TOKEN" ]; then
+      rm -rf "$SYNC_LOCK"
+    fi
+  fi
 }
 
 # sync：幂等、可重跑、可续。**复核过才写 ok**。
@@ -529,15 +527,15 @@ fi
 # 转发脚本而不是软链：同 `bin/opencli-isolated` 那条坑 —— pnpm publish 之后包里的脚本没有 x 位，
 # 软链过去一执行就是 Permission denied。x 位由 chmod 当场给。
 # ⚠️ 先 rm -f：旧版本留下的软链还在时，`>` 会顺着软链把真脚本覆盖掉。
-ENTRY_DIR="$DSH_HOME/workbench/bin"
+ENTRY_DIR="$WORKBENCH_HOME/bin"
 mkdir -p "$ENTRY_DIR"
 rm -f "$ENTRY_DIR/dsh-wb-module"
 cat >"$ENTRY_DIR/dsh-wb-module" <<EOF
 #!/bin/sh
-BIN="$DSH_HOME/workbench/diy/node_modules/.bin/dsh-wb-module"
+BIN="$WORKBENCH_HOME/diy/node_modules/.bin/dsh-wb-module"
 if [ -x "\$BIN" ]; then exec "\$BIN" "\$@"; fi
 if command -v pnpm >/dev/null 2>&1; then
-  exec pnpm --dir "$DSH_HOME/workbench/diy" exec dsh-wb-module "\$@"
+  exec pnpm --dir "$WORKBENCH_HOME/diy" exec dsh-wb-module "\$@"
 fi
 echo "dsh-wb-module: 工坊的依赖还没装 —— 先跑 dsh-workbench setup" >&2
 exit 127

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

@@ -60,17 +60,9 @@ pnpm exec dsh-wb-module init <unit> --dir <工作区>/packages/module-<unit> --t
 
 ## 3 命令
 
-```bash
-dsh-wb-module build                 # 生成 client.js 与 dist/host.js
-dsh-wb-module check                 # 十三条判据
-dsh-wb-module check --only cards    # 单条（contracts / protocol / bundles / source / arch / lint /
-                                    #   primitives / kit / cards / standalone / markers / style / alias）
-dsh-wb-module check --only primitives [--all|--json]   # 查询 dsh 原语
-dsh-wb-module lint [--fix]          # 模块 eslint；--fix 写回
-```
-
-用 `pnpm exec dsh-wb-module …`。`package.json` 六个脚本（`build` / `typecheck` / `test` / `selfcheck` /
-`check` / `lint`）必须保留，`contracts` 点名缺失。
+用 `pnpm exec dsh-wb-module …`；命令、`--only` 判据名与模板参数看 `--help` / `check --list`，不在指引里抄。
+`package.json` 六个脚本（`build` / `typecheck` / `test` / `selfcheck` / `check` / `lint`）必须保留，
+`contracts` 点名缺失。
 
 - `check` 不跑 `pnpm test`；状态、换算、边界测试自己跑。
 - "不适用"不是"通过"：`standalone` 需外壳源码在场，`markers` 只扫公开包（DIY 模块 `private`）。
@@ -94,6 +86,7 @@ export function apply(ctx) {
 }
 ```
 
+`mount({ data })` 的 `data` 是统一数据端口（`DataReader`）；读数据用 `data.read(...)`，不要自己 import adapter。
 `mount()` 返回 `{ routes, registerTools, prefs? }`。`routes` 挂 `/workbench/api/<路由>`，只许 GET，
 键必须在 `<unit>` 或 `<unit>/…` 之下（否则装配抛错）。错误返回
 `{ ok: false, error: { code, message, hint? } }`（HTTP 200，外壳转发）。`registerTools` 提供模块工具。

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

@@ -86,4 +86,4 @@
 | 描述 | 用于查看构建状态的工具 | 看某个环境最近一次构建：状态、耗时、提交；用户说“发布没成功”就先调它。 |
 | 返回 | 操作成功 | 已发布 v1.2.3 到生产；下一步 `_build` 看结果。 |
 | 拒绝 | 不允许 | 这个环境是生产；先在确认条上点「发布到生产」。 |
-| 日志 | 出错了 | `[cmdb] release v1.2.3 failed: HTTP 502 (retryable)` |
+| 日志 | 出错了 | `[inventory] release v1.2.3 failed: HTTP 502 (retryable)` |

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

@@ -6,14 +6,14 @@
 
 | 情况 | 域 |
 |---|---|
-| 用户已在浏览器登录过该系统 | DIY：用 opencli 复用登录探（下文四步） |
+| 用户已在浏览器登录过该系统 | DIY：用 opencli 复用登录探（下文五步） |
 | 要新凭据（账号 / 密钥 / token） | 工程：停，说清谁配什么 |
 
 判据是"要不要新凭据"，不是"要不要接新平台"。其余类型见 [DESIGN.md](DESIGN.md) §0。
 
-## 四步
+## 五步
 
-1. **问入口** —— "你平时在哪个网页 / 软件里看这个？"记下入口。不问"用 argocd 还是 jenkins"。
+1. **问入口** —— "你平时在哪个网页 / 软件里看这个？"记下入口。不问"用 deploy 还是 jenkins"。
    把用户的需求翻成站点 / 系统关键词是你的工作。
 
 2. **按四层找数据**：
@@ -29,7 +29,7 @@
    `workbench_diy_spec`（`command='<site> <name>'`）取 `--help -f json` 原文（插件与内置均可）。
 
    ③ **官方有、这台机器没有** → 安装：`opencli plugin install github:user/repo`、`opencli external install <名>`，
-   或模块清单 `manifest.env.plugins`。安装改这台机器且执行第三方代码 → 需用户审批；优先内网或官方源。
+   或模块清单 `needs` 里 `kind: "extension"` 的那些。安装改这台机器且执行第三方代码 → 需用户审批；优先内网或官方源。
 
    ④ **都没有** → 开发：一次性探用下文的 eval；长期用写 adapter（`opencli skills read opencli-adapter-author`，
    失效用 `opencli-autofix`）。
@@ -39,6 +39,9 @@
    两拍、重启重试、平台码映射都在工具内。目标：找到承载数据的位置（列表页或其后的 XHR），
    记 URL、参数、凭据来源。
 
+   **Desktop**：这条 `read=` 探索线照旧；Desktop 只是不能对 Electron 里的工作台页做屏调试，
+   不影响站点探索。录制（`_record_*`）也照旧。
+
    - 不知道数据在哪：先跑 `performance.getEntriesByType('resource')`，筛 `/api/`、`.json`。
      有 → 接口读；无但页面有整块表格 → DOM 读。判断一次即可。
    - `opencli` 随工作台预装（隔离运行时 `$DSH_HOME/workbench/opencli/`，启动体检安装，不碰 `~/.opencli`）。
@@ -48,25 +51,107 @@
    - 新 session 的 `eval` 会静默开 `about:blank`（后台容器窗，不抢焦点）。脚本第一行判断
      `location.origin`；不在站点则 `open` 该页，等约 1 秒再 eval。两拍都用 shared 的 `backgroundLine`
      拼（前缀 `env OPENCLI_WINDOW=background`），不要直接拼 `opencli browser …`。
-   - 读与屏用不同会话：`browserRead` / `browserFind` 默认 `workbench-read`；`workbench` 是看 / 动族的
-     屏会话。同名会把用户的页导航走。需要独立标签就传 `session: "<unit>"`。
-   - DOM 读不要在 `eval` 里 `querySelectorAll`：宿主产物禁止 `document.`，且无法单测。探时用
-     `workbench_diy_find`（`read=…, args=["--css", "<选择器>"]`）；固化用 `browserFind`
-     （`find --css … --limit N --text-max M`，返回 `{ entries: [{ text, tag, nth }] }`；
-     一行单元格按换行拼在 `text` 内，"切格 + 按列取值"做成两个纯函数）。
+   - 读与屏用不同会话：`data.read({ kind: 'browser' })` 默认读会话 `workbench-read`；`workbench` 是看 / 动族的屏会话。同名会把用户的页导航走。需要独立标签就传 `session: "<unit>"`。
+   - DOM 读不要在宿主脚本里 `querySelectorAll`：宿主产物禁止 `document.`，且无法单测。探时用
+     `workbench_diy_find`（`read=…, args=["--css", "<选择器>"]`）；固化用
+     `data.read({ kind: 'browser', url, script })` 返回 JSON，把"切格 + 按列取值"做成两个纯函数。
    - 工作台刚重启时桥未就绪：首次读报"命令跑不起来"，等一秒重读；超时不重试。
 
 3. **试一条最小读** —— 先证明能拿到，再写模块。记录：结构化字段形状；未登录长什么样；超时 / 被墙的形状。
    产出必须是一条可重复的命令或请求。
 
-4. **固化进模块** —— 先写入 `design.json`（单读 `datasource{}`；多读 `reads[]` 一条一行；字段：
-   哪条读 / 参数 / 凭据 / 没登录 / 超时 / 当时调用原文），再写宿主半侧：用 `@dsh-workbench/shared/host` 的
-   `browserRead({ shell, script, url, loginUrl })`（接口读；两拍、重试、错误码映射、`message` / `hint` /
-   `detail` / `helpUrl` 内置；不传 `session` 用读会话）或 `browserFind({ shell, css, url, session })`（DOM 读；
-   自动判断当前页、必要时 `open`），或一个只读 HTTP GET。卡片只依赖这一条。
-   写操作走 [WRITES.md](WRITES.md)。
-
-`opencli` 是**侦察兵，不是日常通道**：探明后，日常读必须是一条固定、便宜、可解释的调用。
+4. **落配方** —— 把探明结果填成 `design.json` 里这条读的 `recipe`：`origin`、`request`（method / path /
+   query / body / contentType）、`auth`（凭据从哪来、放到哪）、`response`（json / text、取哪一格）。
+   同时把 `key` 写成 lowerCamelCase。配方与"哪条读 / 参数 / 凭据 / 没登录 / 超时 / 当时调用原文"
+   并存：前两格给人看，后一格给壳用。形状见下面「配方」。
+5. **固化进模块** —— 跑 `dsh-wb-module sync`，它把 `key + recipe` 生成到 `src/datasource.ts`；
+   宿主半侧 `mount({ data })` 只写一行 `data.request(DATASOURCE.<key>, overrides?)`（读）或
+   `data.submit(...)`（写，在工具里）。路由把 `DataResult` 摊平成 `{ ok: true, ...data }` /
+   `{ ok: false, error }`，卡片只依赖这条路由。写操作走 [WRITES.md](WRITES.md)。
+
+## 配方
+
+```json
+{
+  "key": "balance",
+  "recipe": {
+    "origin": "https://x.example.com",
+    "loginUrl": "https://x.example.com/login",
+    "request": { "method": "GET", "path": "/api/balance", "query": { "scope": "self" } },
+    "response": { "kind": "json", "path": "data" }
+  },
+  "read": "GET /api/balance（登录态 cookie）",
+  "params": "scope 固定 self",
+  "credentials": "复用浏览器登录：同源 cookie",
+  "notLoggedIn": "401 → 阻断屏，code auth，helpUrl 指 /login",
+  "timeout": "25 秒；超时归 timeout，不整卡换文案"
+}
+```
+
+宿主侧：
+
+```ts
+routes: {
+  'x/balance': async () => {
+    const result = await data.request<Balance>(DATASOURCE.balance);
+    return result.ok ? { ok: true, ...result.data } : result;
+  },
+}
+```
+
+六种配方：
+
+| 配方 | 什么时候用 | `auth` |
+|---|---|---|
+| 公开 | 不要登录 | `{ kind: 'none' }` |
+| cookie | 同源接口，cookie 就够 | 省略（默认） |
+| cookie + CSRF | 表单类后台 | `source: meta / cookieValue`，`place: header` |
+| bearer-refresh | 页面先换 token（如 `/api/auth/refresh`） | `source: endpoint`，`place: header` |
+| bearer-page | token 在页面初始 state / storage | `source: global / storage`，`place: header` |
+| custom | 签名 / WS / 多步 / 一次性 token | 不写 recipe，写 `custom: { why }`，代码里用旧的 `data.read({ kind: 'browser', script })` |
+
+同一次读要打多条接口时（一个 refresh 换 token，再并发取余额、用量、订阅……），不要拆成 N 条配方
+各调一次：一条配方 + 一格 `calls`，一次换 token、并发打，结果按键回、每格各自成败：
+
+```json
+{
+  "key": "wallet",
+  "recipe": { "origin": "https://x.example.com",
+              "auth": { "source": { "kind": "endpoint", "url": "/api/user/auth/refresh",
+                                    "method": "POST", "body": {}, "path": "data.access_token" },
+                        "place": { "in": "header", "name": "authorization", "prefix": "Bearer " } },
+              "request": { "method": "GET", "path": "/api/subscription/self" } },
+  "calls": {
+    "balance": { "path": "/api/wallet/balance", "response": { "path": "data.balance" } },
+    "usage": { "query": { "days": 7 } }
+  }
+}
+```
+
+`sync` 会多生成一个 `DATASOURCE_CALLS.wallet`；代码里一次调用：
+
+```ts
+const results = await data.requestMany(DATASOURCE.wallet, DATASOURCE_CALLS.wallet);
+```
+
+`calls` 的键就是结果名；配方里的 `path` / `query` / `headers` / `response` 是每条的默认值，
+`calls` 里的同名格覆盖它；一次最多 8 条。`calls` 必须配 `recipe`，`design check` 逐格校验。
+`requestMany` 也只读 GET —— 写仍是一条一条走 `submit`。
+
+配方还有两个可选机器字段：`session`（这条读用哪条 opencli 会话，默认 `workbench-read`；要和屏会话分开时写）
+与 `timeoutMs`（默认 25 秒）。
+
+`custom` 只记"为什么配方盖不住"，脚本仍在代码里；`design check` 会给 warn。
+
+探 DOM（服务端渲染的表格）不在配方里：用 `_find` 探，固化仍走老的 `data.read({ kind: 'browser', script })`
+或 `browserFind`（DOM 读走 `find`，不写 eval 脚本）。
+
+`opencli` 是**侦察兵，不是日常通道**：探明后，日常读必须是一条固定、便宜、可解释的调用
+（配方就是那条调用；`eval` 只在探测和 `custom` 里出现）。
+
+配方的**执行体由壳决定，不写在模块里**：凭据来源是 `cookie` / `cookieValue` 时，壳可能用宿主侧的
+公共通道（Node fetch + 浏览器 cookie jar）而不是页面脚本；两者结果形状、错误码、三态都一样。
+模块不需要知道走的是哪条 —— 照 `data.request(DATASOURCE.<key>)` 写就对了。
 
 ## 三态
 
@@ -87,10 +172,10 @@
 
 | code | 用户看到 |
 |---|---|
-| `auth-required` + `helpUrl` | "需要登录 XX" + 去登录 + 重试（无 `helpUrl` 只剩重试） |
-| `cli-timeout` | 细提示（不换整卡）+ 重试 |
-| `cli-exec-failed` | 整卡"读不到" + 重试；`hint` 写清确认什么 |
-| `permission-denied` + `helpUrl` | "没有权限" + 权限页 + 重试 |
+| `auth` + `helpUrl` | "需要登录 XX" + 去登录 + 重试（无 `helpUrl` 只剩重试） |
+| `timeout` | 细提示（不换整卡）+ 重试 |
+| `command` / `http` / `parse` | 整卡"读不到" + 重试；`hint` 写清确认什么 |
+| `browser` + `helpUrl` | "没有权限" / 页面读失败 + 权限页 + 重试 |
 | 其他 | 整卡显示 `message` + 重试 |
 
 字段位置：`message` 标题、`hint` 可照做的一句、`detail` 折叠的原始输出。

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

@@ -100,7 +100,8 @@ pnpm exec dsh-wb-module design accept    # 逐条走通后打勾
 
 字段：`unit` / `name` / `oneLine` + `panel[]`（这一格 / 结论 / 去哪）+ `states[]`（五态必填，key 固定
 `idle|loading|ready|empty|unreadable`）+ `config[]` + `capabilities[]` + `linkage[]` +
-`datasource{}`（一条读）或 `reads[]`（多条，一条一行）+ `writes[]`（写通道；单条可写 `write{}`；没有就不写）+
+`datasource{}`（一条读）或 `reads[]`（多条，一条一行；每条可带 `key` + `recipe`，见
+[DATASOURCE.md](DATASOURCE.md)「配方」）+ `writes[]`（写通道；单条可写 `write{}`；没有就不写）+
 `acceptance[]`。`config` / `capabilities` 可为空数组；其余空 = 未定。写通道字段见 [WRITES.md](WRITES.md)。
 
 单态不适用时写 `na`：`{ "key": "idle", "na": "读的是账号，不随项目变" }`，不填 `sees` / `canDo` / `agentCan`。

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

@@ -1,72 +1,52 @@
-# DIY 工具族：参数与返回
+# DIY 工具族：怎么选、怎么串
 
-本文件是 agent 在 DIY 会话里实际拿到的工具契约。[TOOLS.md](TOOLS.md) 讲模块自身能力。
+只写工具定义里没有的东西：什么时候用哪把、先后顺序、参数说明之外的坑。
+逐把的参数与返回以调用时拿到的工具定义为准；模块自身的能力见 [TOOLS.md](TOOLS.md)。
 
-## 1 前置
+## 1 选哪把
 
-- 仅在选了 DIY 模式的会话中出现（按模式，不按工作区），且面板已画在屏上。
-- 看 / 动 / 网络 / 日志族需先 `workbench_diy_debug_start`（审批一次）；无约定一律拒，零命令。
-  不看屏 `_debug_pause`；收工 `_debug_stop`（一并收网络与日志钩子）。
-- 固定会话 `workbench`，每条带 `--window background`。`_status` / `_panel` / `_components` / `_recon` / `_spec` /
-  `_install` / `_show` 不碰屏，无需约定；`_find` / `_eval` 带 `read=` 走只读线，也不碰。
-- 录制交接（§4）独立：会话 `workbench-rec`；`_record_prepare` 审批一次，其余不问。
-
-## 2 浏览器 14 把
-
-工具名 → opencli 子命令（前缀 `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'` 仅七把：`_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` 均拒），也不要求工作区有模块。
-  返回字段与屏线相同，另带 `session` / `opened`（`opened` = 曾代开站点：先比 `get url`，不在则 `open <read>` 再跑）。
-  `_eval` 脚本返回 `{ ok: false, code: "not-logged-in" }` 时追加一句"去 <read> 登录"。
-- `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`
-（只读线为 `session` / `opened`）；`_screenshot` 另带 `file` / `cropped` / `cropReason`。
-`ok` 仅表示进程退出；事实在 `stdout`（错误体为 `{"error":{…}}`，`ok` 可能为 true）。不做 JSON 解析、
-不翻译、不归一。参数不明先 `args: ['<verb>', '--help']`。
-"原样"有折损：空串 / 纯空白 / 非字符串参数被丢弃，词前后 trim，stdout / stderr trim ⇒ `_fill` 无法清空、
-`_type` 无法输入空格。
-
-补充用法：`_select` 不存在，下拉两拍（点触发器 → `scope: 'page'` + `--role menuitem` 按名点）；
-刷新用 `eval 'location.reload()'`；视口用 `screenshot --width/--height`。
-
-## 3 边界
-
-- `screenshot` 无 selector：卡图先 `eval` 量盒再 `clip`；不给路径写
-  `~/.dsh/workbench/artifacts/<工作区>/<unit|page>-<时间戳>.png`，否则回 base64；裁剪块不在视口时退回整屏，
-  原因在 `cropReason`。
-- `state` 无 `scope`（卡内用 `find --css '$card …'`）；无右键；ref 仅一次快照内有效；`_dialog` 不校验
-  `accept|dismiss`；`_network --detail` 无 body → 用 `_eval` 的 `fetch`。
-- 录制会话捕获带 body：跟随 `network --follow` 只用于臂上；每 3 秒一次非跟随 `network --all --raw` 排空缓冲，
-  取请求体与响应体。按 URL 去静态资源与 `data:` 后落盘。它覆盖整场，比页面钩子全（钩子只认该页 `fetch` / XHR）。
-  不要换成 opencli 默认过滤（按响应 ct 白名单，会丢"按结束即回包未到"的写）。
-- 其他：`_status` / `_install` / `_show`、`_components`（清单 / 类型面；`name=Button` 取声明）、
-  `_panel`、`_recon`、`_spec`（opencli 命令形状，插件适用）、`_logs_*`、`_debug_*`、`_record_*`（§4）。
-
-## 4 录制交接
-
-| 工具 | 契约 |
+| 要做什么 | 用 |
 |---|---|
-| `_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`。不删行、不回体；钩子与捕获合并，同名只配一条钩子行（缺字段由捕获补）；同 method+url 两次调用都保留。`expect` 仅标 ⭐ 并置顶。可选 `waitMs`（默认 0，上限 15 分钟；超时回 `timedOut` 并发 notice） |
-| `_record_detail` | 参数 `key`（原样，可含 `#2`）或 `index`（仅场次存续时）；同 key 跨轮重名，带 `at` 定位。返回请求体、响应体、请求头（可能含凭据，不写入 `design.json`）。可选 `unit`（收工后读 `shots/rec-<unit>.jsonl.last`）；可选 `maxBody`（默认 60000 字符，0 不限）。取不到时给 DevTools 复制 curl 兜底 |
-| `_record_stop` | 停捕获、收标签、清状态；先读文件，原文另存 `.last`。返回可写入 `design.json` 的 `probeCommand`（仅第一条带 body；无则空串并说明）。先 read / detail，再 stop |
-
-左栏键（`[取消]` / `[停]`）只发消息，不改页面；录完无键。场次 TTL 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

@@ -104,12 +104,14 @@ h(Form<{ branch: string }>, {
 
 ```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.mode'), htmlFor: 'myunit-mode', hint: t('myunit.modeHint') },
+    h(SelectField, { id: 'myunit-mode', value, options, onChange: setMode })))
 ```
 
 - 标签归 `FormRow`（默认左置；`layout: 'stacked'` 堆叠）。进了 `FormRow` 就不再给控件 `label` / `hint`。
   `hint` 与 `problem` 二选一，错误优先。
+- 行是 `<div>`，`<label>` 只包标签文字；要点标签聚焦 / 展开控件，给 `FormRow.htmlFor` 与控件的 `id` 同一个值
+  （`Form` 内部按 `field.key` 自动接成 `wb-form-<key>`）。不给 `htmlFor` 就只是排布，点标签不聚焦。
 - 错误：位置与外观归 `FormRow.problem` + 控件 `invalid`；校验逻辑留在模块（纯函数 + 文案，交给 `validate`）。
   "是否提交过"与首错聚焦归 `Form`。
 - 选择：候选多 / 需搜索 / 需分组 / 可能读不到 → `SelectField`；候选少 / 要全览 / 多选 → `ChoiceGroup`。
@@ -130,7 +132,8 @@ h(FormRows, null,
 ## 7 规则
 
 1. 调用点只给数据与语义；外观类名只允许布局槽（通栏、外边距、网格位置）。
-2. 字号与颜色走 kit 与令牌（`--dsw-*` / `--wb-*`）。重点数字用 `--dsw-font-xl-24` + `tabular-nums`；
+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 / 对齐）。
 

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

@@ -15,7 +15,7 @@
 | 其他窗口 / 会话改动 | 跟随变，无需刷新 |
 
 一次说清变哪一级：整板 / 一张卡 / 一行。"刷新一下"不合格。只动该动的格，粒度落到"某投影 + 最窄参数"
-（`cmdb/builds?env=dev`）；否则会整卡重读。
+（`inventory/builds?env=dev`）；否则会整卡重读。
 
 ## 2 进行中
 

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

@@ -86,10 +86,12 @@ write.send({ ignored, timeoutSeconds, workspace });   // 控件：Field + TextFi
 - 跳整张卡对应的系统 → 卡头 `CardHead.platformHref`；跳具体页面 / 记录 → `Link`；触发动作 → dsh `Button` 或阻断屏 `action`。
 - 标签 + 输入框用 `Field` + `TextField`，不自写 CSS。
 - 组件选型照 [KIT.md](KIT.md)。
-- **字号与重点**：走刻度（`--dsw-font-*`：11 / 12 / 13 / 14 / 16 / 20 / 24），不整卡同字号。
-  最重点的数字用 `--dsw-font-xl-24`（24/32、600），旁注 12；刻度外字面值需在模块 `README.md` 说明。
+- **字号与重点**：走刻度，不整卡同字号 —— 刻度以 `--dsw-font-*` 的定义为准，别背数字
+  （`workbench_diy_components` `scope: 'tokens'`、`bucket=font` 现查）。
+  最重点的数字用最大一档（`--dsw-font-xl-24`），旁注用最小一档；刻度外字面值需在模块 `README.md` 说明。
   成列数字加 `font-variant-numeric: tabular-nums`。
-- 颜色与间距走令牌（`--dsw-*` / `--wb-*`）；自写 CSS 只写布局（flex / grid / gap / 对齐）。
+- 颜色与间距走令牌；名字现查不猜：`workbench_diy_components` 给 `scope: 'tokens'`（`bucket` 按族、`name` 连浅/深值）。
+  写进 CSS 的令牌名由 `check --only style` 对着现读的清单验，拼错判红。自写 CSS 只写布局（flex / grid / gap / 对齐）。
 
 ## 7 状态矩阵