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

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

@@ -5,18 +5,18 @@
 | 判据 | 检查 | 修法 |
 |---|---|---|
 | `contracts` | 清单 ↔ 代码 ↔ `design.json` 漂移；dsh 组合期不校验清单 | 按报错改：`unit` 重名换名；`dsh.workbenchFaces` 两个源码入口；六个脚本；`private: true`。`dsh.workbench.tools` 与 `registerTools()` 一致；`design.json` 对键名；生成物过期跑 `sync` |
-| `protocol` | `dsh.workbench` 版本 / 形状 / 多余键（外壳静默忽略生字段） | 补 `"apiVersion": 1`；`unit` / `card` / `tools` / `host` 写全（无卡片 `null`、无工具 `[]`）；删协议外键（`faces` 在 `dsh.workbenchFaces`；不写 `scope`） |
+| `protocol` | `dsh.workbench` 版本 / 形状 / 多余键（外壳静默忽略生字段） | 补 `"apiVersion": 2`；`unit` / `card` / `tools` / `host` 写全（无卡片 `null`、无工具 `[]`）；删协议外键（`faces` 在 `dsh.workbenchFaces`；不写 `scope`） |
 | `bundles` | 运行时互串：浏览器产物含 node 内置 / 宿主产物含 DOM、react | 不 import 对方那侧 |
-| `source` | 非种子 `@deepseek-ai/*`；宿主碰 dsh 浏览器包；`@/` 指外壳；根入口取运行值；客户端引 `/host` | 宿主只用 Node 侧；种子词仅在 client 可达文件；`@/` 只指自己 `src/`；运行值：浏览器 `kit`、宿主 `shared/host` |
+| `source` | 非种子 `@deepseek-ai/*`；宿主碰 dsh 浏览器包；`@/` 指外壳；根入口取运行值；客户端引 `/host`；**手写进程 / PATH / 文件锁 / 状态原子写**（import 首选库放行） | 宿主只用 Node 侧；种子词仅在 client 可达文件；`@/` 只指自己 `src/`；运行值：浏览器 `kit`、宿主 `shared/host`；进程/锁/状态写交给外壳 |
 | `primitives` | 声明 `external` 但产物无物证（原语被内联） | `dsh.client.external` 声明；devDependency 精确版对齐；产物中为 `require(...)` |
 | `kit` | 用了 peer 下限外壳没有的成员（首帧 `Element type is invalid`） | 只用 peer 范围内成员；下限抬到实际使用版 |
 | `cards` | 七种外壳侧输入 × `zh` / `en` 下崩溃 / 空白 / 脏值 | 五态可画；外层 `Card`；`titleKey` 与卡片用到的键双语齐。不断言具体态（归 `plugin.test.ts`） |
 | `standalone` | 依赖工作台源码才能构建 | 不引用工作台源码；`tsconfig.paths` 用相对路径 |
-| `markers` | 内网域名 / 企业名进入公开包 | 不进包；配置落到模块配置面 |
+| `markers` | 私有源 / 私网地址 / 内网域名进入公开包 | 不进包；配置落到模块配置面；组织特有的词表由 `DSH_WB_INTERNAL_MARKERS` 提供 |
 | `alias` | `@/` 指向工作台源码 | `@/` 只指自己 `src/` |
-| `style` | 模块定义 `.wb-*`；手写行 / 操作区 / 表单（F1–F4） | 样式走 `*.module.css`（无 `wb-` 前缀）；借外壳类用 `:global(.wb-…)`；行 / 操作区用 `FormRow(s)` / `FormActions`，表单用 `Form`（[KIT.md](KIT.md) §5）。F4：裸 `<form` 或手写 `wb-formRow` / `wb-formRows` / `wb-field` |
-| `arch` | 结构：巨文件 / 反向依赖 / 跨运行时 / 表外目录 / 模型无测试 | 见「第十二条」 |
-| `lint` | 语法：`as any` / `console` / `debugger` / 颜色字面量 / `!important` / react-hooks | 见「第十三条」 |
+| `style` | 模块定义 `.wb-*`；手写行 / 操作区 / 表单（F1–F4）；`--dsw-*` / `--wb-*` 不在现读的令牌清单 | 样式走 `*.module.css`（无 `wb-` 前缀）；借外壳类用 `:global(.wb-…)`；行 / 操作区用 `FormRow(s)` / `FormActions`，表单用 `Form`（[KIT.md](KIT.md) §5）。F4：裸 `<form` 或手写 `wb-formRow` / `wb-formRows` / `wb-field`。令牌名现查：`workbench_diy_components` `scope: 'tokens'` |
+| `arch` | 结构：巨文件 / 反向依赖 / 跨运行时 / 表外目录 / 模型无测试；依赖白名单（含 execa / which / proper-lockfile / write-file-atomic / dayjs / zod）+ `shell-quote` / `shelljs` / `zx` deny；能力首选 dayjs / structuredClone / URLSearchParams / zod（日期已是硬门禁） | 见「第十二条」 |
+| `lint` | 语法：`as any` / `console` / `debugger` / 颜色字面量 / `!important` / **直接读 `process.platform` / `versions.electron` / `dshDesktop` / `hostOs` / `navigator.userAgent`** / react-hooks | 见「第十三条」 |
 
 ## 第十二条 `arch`
 
@@ -71,7 +71,7 @@ export default moduleLint({ rootDir: import.meta.dirname });
 | `no-explicit-any` | `as any` / `: any` | 写真实类型；或在 `moduleLint({ rules })` 放行 |
 | `no-console` | `src/**` 的 `console.log` / `info` / `debug`（`warn` / `error` 放行） | 删除；`scripts/**` 不判 |
 | `no-debugger` | 残留 `debugger` | 删除 |
-| `no-restricted-syntax` | 颜色字面量（`#ff0000` / `rgb(` / `hsl(`）、字符串 `!important` | 用令牌与 `*.module.css` |
+| `no-restricted-syntax` | 颜色字面量（`#ff0000` / `rgb(` / `hsl(`）、字符串 `!important`、平台原始事实（`process.platform` / `versions.electron` / `dshDesktop` / `hostOs` / `navigator.userAgent`） | 用令牌与 `*.module.css`；平台差异走能力面（`HostSurface` / `ClientSurface`），宿主/浏览器面分开写 |
 | `react-hooks/*` | 条件 hook / 渲染期写 ref / 漏依赖 | 提到顶层；副作用进 `useEffect`；补依赖 |
 | `no-unused-vars` | 死代码（`^_` 放行） | 删除或改 `_x` |
 | 其他 `recommended` / `react/*` | 语法规则 | 按 eslint 原文 |

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

@@ -12,11 +12,15 @@ description: 在工作台里把当前面板调明白，或者给它造一块新
 
 调交付"面板现在怎么样"的事实；造交付面板上能点开的一块内容。不交技术方案。
 
+> **Desktop**：屏调试不可用（`debug_*`、`logs_*`、不带 `read` 的看/动都不会出现）；**站点探索用
+> `read=<地址>`**，**录制 `_record_*` 照旧**，`_panel` / `_status` / build / install 照旧。
+> 验收时别调 `_debug_start`；用 `read` 或录制取证。
+
 ## 流程
 
 **0. 认路** —— 跑 `workbench_diy_status`，取 `工作区：<dir>`。
 
-**调** —— 用 [REVIEW.md](REVIEW.md) 的四步取证。动屏前 `workbench_diy_debug_start`（`unit` 可省）。
+**调** —— 用 [REVIEW.md](REVIEW.md) 的四步取证。动屏前 `workbench_diy_debug_start`（`unit` 可省；Desktop 跳过）。
 抓"点了之后发了什么"：`workbench_diy_record_prepare` → 用户操作 → `_record_read`；收工 `_debug_stop` / `_record_stop`。
 不需要源码、工具链、工坊。
 
@@ -27,8 +31,9 @@ description: 在工作台里把当前面板调明白，或者给它造一块新
 1. **判域** —— [DESIGN.md](DESIGN.md) §0。输出一句结论 + 下一步。
 2. **问三张表** —— 问法见 [STEPS.md](STEPS.md)；只问用户能决定的事，实现不问。ASCII 画面 + 三张表当场写进
    `design.json`（[DESIGN.md](DESIGN.md) §5）。
-3. **定数据源** —— [DATASOURCE.md](DATASOURCE.md)：探明后固化成一条读（`browserRead` / `browserFind`），写三态。
-   写操作先读 [WRITES.md](WRITES.md) 四步；有写工具就把审批屏画进 ASCII（[DESIGN.md](DESIGN.md) §3 末节）。
+3. **定数据源** —— [DATASOURCE.md](DATASOURCE.md)：探明后落成一条**配方**（`design.json` 的 `key + recipe`
+   → `dsh-wb-module sync` → `data.request`），配方盖不住的写 `custom: { why }`；写三态。
+   写操作先读 [WRITES.md](WRITES.md) 四步 + 执行体；有写工具就把审批屏画进 ASCII（[DESIGN.md](DESIGN.md) §3 末节）。
 4. **套模板** —— [BUILD.md](BUILD.md) §1–§2：`pnpm exec dsh-wb-module init <unit> --template diy`，
    先把 `design.json` 改成问出来的那份，再改数据源与渲染。init 后 `pnpm install`。不从零写。
    改渲染时文案按 [COPY.md](COPY.md)：先判读者（卡片给人 / 描述给 agent / 原始输出进 detail）。
@@ -37,20 +42,24 @@ description: 在工作台里把当前面板调明白，或者给它造一块新
 6. **装、上板** —— `workbench_diy_install`（`unit=…`）。只装一次；之后 `dsh-wb-module build` 即可。
    状态不明问 `workbench_diy_status`（`unit=…`）；只缺上板用 `workbench_diy_show`。装不问审批。
 7. **验收** —— 对着三张表在真卡片上走「打开哪 → 看什么 → 点什么 → 应该看到什么」。
-   看 / 动屏前 `workbench_diy_debug_start`（否则整族拒）；`_panel` / `_status` / `read=` 档不用。
+   看 / 动屏前 `workbench_diy_debug_start`（否则整族拒；Desktop 跳过，改用 `read=` / 录制）；`_panel` / `_status` / `read=` 档不用。
    工具全表 [FAMILY.md](FAMILY.md)。走通才 `dsh-wb-module design accept`；走不通如实记"未验"。
    审批项标注「要你真用一次」，不打勾。结论只报：已装、在面板哪一格。
+8. **发布** —— 只在用户说「帮我发布」之后。先确认他已经在真卡片上说过「没问题」（`design accept` 已打勾），
+   并把这一版写进 `CHANGELOG.md`：`workbench_diy_changelog`（`unit=…`，`note=…`；
+   没写这一版 `release` 会拦下），再调 `workbench_diy_publish`（`unit=…`）。只问「给团队用、公开发、还是先给你一个安装包」；
+   不展示 `package.json` / npm / 版本字段，也不要问 token。出口与 `needsUser` 处理见 [WIRING.md](WIRING.md) §5。
 
 ## 索引
 
 | 需要 | 读 |
 |---|---|
-| 判域、分工、三张表、ASCII 规则 | [DESIGN.md](DESIGN.md) |
-| 三步的问法、产出、完成判据 | [STEPS.md](STEPS.md) |
+| 判域、三张表、ASCII 规则 | [DESIGN.md](DESIGN.md) |
+| 步骤与完成判据 | [STEPS.md](STEPS.md) |
 | 探测数据源、固化读、错误码 | [DATASOURCE.md](DATASOURCE.md) |
 | 写通道四步、回读、撤销 | [WRITES.md](WRITES.md) |
 | 面板内容、状态矩阵、界面规则 | [PANEL.md](PANEL.md) |
-| 选 kit 组件、表单、hooks | [KIT.md](KIT.md) |
+| 选组件、表单、hooks | [KIT.md](KIT.md) |
 | agent 能力、审批、长任务、外部供给 | [TOOLS.md](TOOLS.md) |
 | 文案：三类读者、主句 / 原文、人 / agent / 开发 | [COPY.md](COPY.md) |
 | DIY 工具族的参数与返回 | [FAMILY.md](FAMILY.md) |
@@ -58,17 +67,17 @@ description: 在工作台里把当前面板调明白，或者给它造一块新
 | 落点、模板文件、命令、两个面 | [BUILD.md](BUILD.md) |
 | 依赖、禁区、安装、热换、发布 | [WIRING.md](WIRING.md) |
 | 门禁报错、卡片故障取证 | [REVIEW.md](REVIEW.md) |
-| 哪些检查已固化成命令 | [TOOLING.md](TOOLING.md) |
 
 ## 查不到时
 
 1. `dsh-wb-module check --only <判据>` 的报错原文。
-2. kit / dsh 原语：`workbench_diy_components`（DIY 会话）；工程域 `check --only kit` / `--only primitives`。
+2. kit / dsh 原语 / CSS 令牌：`workbench_diy_components`（DIY 会话；令牌给 `scope: 'tokens'`，现读现给）；
+   工程域 `check --only kit` / `--only primitives`。
 3. 模板：`node_modules/@dsh-workbench/module-tools/template-diy/` 与 `template/`。
 4. 安装包的类型面：`node_modules/@dsh-workbench/core/dist/types/**`；本指引：`node_modules/@dsh-workbench/core/skills/workbench-module-diy/**`。
 
 ## 硬约束
 
 - dsh 已有的从 `kit` 拿（`@dsh-workbench/core/client`）；不手搓 DOM + CSS，不直接 import dsh 的包。
-- DIY 模块 `private: true`，不发任何源。
-- 源码只许贴导出的 JSDoc；`//`、实现内注释、`.css` 注释都不许。理由写模块 `README.md` 或 spec。
+- DIY 模块默认 `private: true`，不发任何源；用户确认后走 `workbench_diy_publish` 发到团队源 / 公网 / 安装包 / git。
+- 源码零注释（`//`、块注释、`.css` 注释都不许）；说明写模块 `README.md` 或 spec。

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

@@ -87,7 +87,7 @@
 判据：
 
 - 用户对着两张图看过一次真实变化。
-- 每格说清"何时变、哪格变、看到什么"；"哪一格"细到"某投影 + 最窄参数"（`cmdb/builds?env=dev`）。
+- 每格说清"何时变、哪格变、看到什么"；"哪一格"细到"某投影 + 最窄参数"（`inventory/builds?env=dev`）。
 - 面板不停在旧值；允许延迟但要说清。
 - 每个"交给 agent"都说清 agent 收到的内容。
 

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

@@ -88,15 +88,39 @@
 
 ## 8 外部供给
 
-`env` 声明能力依赖，外壳隔离运行时按它装、探，状态见 `workbench_modules_list`。
-形状：`env: { command, libs: [{ name, registryEnv, registryDefault, purpose }], plugins: [{ name, commands, installSource }] }`。
-
-- `libs[]` 四项必填：`registryEnv` 让用户源覆盖 `registryDefault`；`purpose` 是给用户的一句用途。
-  `installSource`：`{kind:'npm', package, registryEnv}` / `{kind:'git', url}` / `{kind:'local', env}`。
-- 未装好文案由模块写：`libInstallCommand({ need })`（`@dsh-workbench/shared/host`）拼好源与缓存目录，原样输出；
-  放进失败态。
-- `contracts` 判据：`env` 非空；`libs` 缺 `purpose` / `registryEnv`、`registryDefault` 非 `http(s)://` 或 `file://`、
-  `installSource` 错误都红；声明 `libs` 必须用 `libInstallCommand`。
+`needs` 声明能力依赖，外壳按 `kind` 去探、去装，状态见 `workbench_modules_list`。
+
+四种 `kind`：`bin`（机器上的命令）/ `extension`（运行时插件）/ `lib`（共用 npm 依赖）/ `env`（环境变量）。
+每条必写 `purpose`（给用户看的那半句）；`required: false` 只降级、不挡卡片。
+
+```jsonc
+"needs": [
+  {
+    "kind": "extension",
+    "runtime": "opencli",
+    "name": "acme-workflow",
+    "commands": ["acme-read", "acme-write"],
+    "purpose": "读写工单",
+    "sources": [
+      { "kind": "npm", "package": "opencli-plugin-acme", "registryEnv": "ACME_REGISTRY" },
+      { "kind": "git", "url": "git@internal:plugin-acme.git" },
+      { "kind": "local", "env": "ACME_PLUGIN_PATH" }
+    ]
+  },
+  { "kind": "lib", "name": "opencli-workflow", "purpose": "发布编排" },
+  { "kind": "bin", "name": "acme", "purpose": "平台命令" },
+  { "kind": "env", "name": "ACME_TOKEN", "purpose": "访问令牌", "secret": true }
+]
+```
+
+- `sources` 按顺序试（本地 → 私有 → 公共）。没写 `sources` 就是「我自己装，你只帮我判」——外壳只探不代装。
+- `extension` 的 `sources[].kind` 只有 `npm` / `git` / `local`；`lib` 只认 `npm`。
+  未知 `kind` 或 `source.kind` 判红；need 里未知字段只警告，`x-` 前缀忽略。
+- 未装好文案由模块写：`libInstallCommand({ need, source })`（`@dsh-workbench/shared/host`）拼好源与缓存目录，
+  原样输出；放进失败态。
+- `contracts` 判据：`apiVersion` 必须是 2；`needs` 走同一份 `NEED_KINDS` 注册表校验（`purpose` 必填、
+  `bin`/`env` 不许带 `sources`、`lib` 只认 npm 源）；声明了 `lib` 必须用 `libInstallCommand`。
+  未知 `runtime` 不判红：探针会给「这个运行时工作台还不认识」的 `unchecked`，等运行时 provider 补上。
 
 ## 9 长任务
 

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

@@ -30,11 +30,11 @@
 |---|---|
 | DOM + CSS 重画 dsh 已有控件（按钮、弹窗、输入框、图标） | 第二份材质与交互；先从 `kit` 取 |
 | `import '@deepseek-ai/dsh-client-ui-primitives'` | 允许，需三处齐：仅浏览器侧、`dsh.client.external` 声明、产物中为 `require`（否则被内联，`primitives` 红） |
-| `import '@/shared/…'`、`../../workbench/src/…` | `@/` 只指自己 `src/`；跨包用包名 |
+| `import '@/shared/…'`、`../../core/src/…` | `@/` 只指自己 `src/`；跨包用包名 |
 | 公开包写内网地址 / 域名 / 企业名 | `markers` 红 |
 
 纪律：样式走 `*.module.css`，类名不带 `wb-` 前缀（外壳全局类；借契约类写 `:global(.wb-…)`）；
-`src/**` 只许贴导出的 JSDoc。
+`src/**` 零注释；说明写 `README.md` 或 spec。
 
 ## 3 安装、上板
 
@@ -60,7 +60,19 @@ DIY 族仅在选了 DIY 模式的会话出现（按模式，不按工作区）
 
 ## 5 发布
 
-DIY 模块 `private: true`，不发任何源。
-
-需要发布时：`pnpm exec dsh-wb-module publish`（门禁 + 三张表 + `files` 漏项，仅 dry run）；
-通过后移除 `private`，显式写 `publishConfig.access` 或内网 `publishConfig.registry`。
+默认 `private: true`，不发任何源。用户说「帮我发布」时，**不要手改 `package.json`、不要让他看 npm**，
+走 `workbench_diy_publish`（`unit=…`）：
+
+1. 先确认他已经在真卡片上说过「没问题」，并已跑过 `design accept`（验收 N/N 全勾）。
+   还要把这一版写进 `CHANGELOG.md`：调 `workbench_diy_changelog`（`unit=…`，`note=…`）；
+   没有这一版的记录（或包里没带 `CHANGELOG.md`）时 `release` 会拦下，并给出补的命令。
+2. 工具一次做完预检（登录 / license / git 远端 / 工作区）→ 全门禁 → 按出口发布 → 发后核包。
+   发布审批屏会把这一版的更新日志按 markdown 展示给用户。
+3. 出口只有四种：团队源（配了私源时默认）、公网 npm（必须用户明确说“公开”）、安装包（没私源时默认，
+   零凭据）、git（提交构建产物 + tag + push）。只问「给团队用、公开发、还是先给你一个安装包」；
+   凭据细节由预检接管。
+4. 工具回 `needsUser` 时，照它那句 `text` 对用户说一句，给能照抄的命令，等他说「好了」再跑；
+   **不在对话里要 token / OTP**，不把红字贴给用户。`otp` 交接后用 `workbench_diy_publish` 的 `verify=true`
+   （或 `release --verify`）只核不发。
+5. `dsh-wb-module publish` 仍是**发货前清单**（只 dry run）；`release --dry-run` 只预览；
+   `--verify` 只核已发布的包。公网源必须显式 `--target public` + license，默认只认团队源 / 安装包。

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

@@ -10,11 +10,11 @@
    `读` · `写（可预览）` · `写（无预览档，一次就是真的）`，并给入参签名（`--id --yes=false`）。
    命中即复用（自造会绕过登录、XSRF、错误码处理）。
    只命中写命令时，末句提示：先 `--help` 看入参；带 `--dryRun` / `--yes` 的先走预览；**无预览档不许试写**。
-   边界：recon 只覆盖 opencli 自带目录；`cmdb` / `coding` 等插件只回命令名，参数走第 2 步。
+   边界：recon 只覆盖 opencli 自带目录；`inventory` / `demo` 等插件只回命令名，参数走第 2 步。
 
 2. **查入参 / 出参**（按可信度）：
 
-   - `workbench_diy_spec`（`command='<site> <name>'`，`cmdb publish` / `cmdb/publish` 均可）：
+   - `workbench_diy_spec`（`command='<site> <name>'`，`inventory publish` / `inventory/publish` 均可）：
      返回 `opencli <site> <name> --help -f json` 原文；JSON 时另给 `spec`（`access`、`positionals`、
      `command_options[{name, required, help, default}]`、出参列）。不碰屏、不需约定。
    - recon 的 `args`（必填 / 默认值）与 `preview` 标记，仅覆盖自带目录；插件以 `_spec` 为准。
@@ -47,9 +47,30 @@
 
 4. **文档 / 问用户** —— 接口文档、curl 样例都可用于确认需求；问法照 [STEPS.md](STEPS.md)，不问技术细节。
 
+## 执行体（写工具里那一下）
+
+写工具被点头之后，按这个顺序选：
+
+1. **有现成 opencli 写命令** → `opencli <site> <name> …`；`--yes` 只在 `confirm === true` 时加，
+   没有预览档的写不许试写（见上面四步）。
+2. **没有命令、但能落配方** → `data.submit(recipe, { body })`。预览用
+   `describeRecipe(recipe)`（`@dsh-workbench/shared/host`）回 `{ method, url, body }`，
+   凭据只回"放在哪"；真写才调 `submit`。
+3. **都不行**（签名 / WS / 多步 / 一次性 token）→ 旧的 `data.read({ kind: 'browser', script })`，
+   在 `design.json` 里写 `custom: { why }`，脚本留在代码里。
+
+三条都不自动重试：失败先回读，再决定。写完的回读用同一份 `DATASOURCE` 里的读配方（或同族命令）。
+
+第 2 条走的是哪条传输由壳决定（页面脚本 / 宿主侧的公共通道），模块看不见也不该依赖 ——
+`submit` 的返回形状、错误码、审批、回读全都一样。
+
+**录制 → 配方**：`_record_detail` 的原文是取证。method / path / body / contentType 抄进配方；
+`authorization` / `cookie` / `x-csrf-*` 这些头**丢掉**，改写成 `auth.source` + `auth.place`；
+一次性 token / 签名 / 多步 → `custom`。"授权观察一次 ≠ 授权重放"：每次 `submit` 都重新审批。
+
 ## 硬纪律
 
-- **预览**：先确认是否有 `yes` / `dryRun` / `confirm` 档；有则先走预览。`opencli cmdb publish` / `cmdb build`
+- **预览**：先确认是否有 `yes` / `dryRun` / `confirm` 档；有则先走预览。`opencli inventory publish` / `inventory build`
   无预览开关，调用即真发布 / 真构建。**无预览档不许试写。**
 - 要新凭据 / 多步长流程 / 新依赖 → 工程域。
 
@@ -74,7 +95,7 @@
 
 ## design.json：writes[]
 
-字段七个必填、一个可空：
+字段七个必填、三个可空（`probeCommand` / `key + recipe` / `custom`）：
 
 | 字段 | 行名 |
 |---|---|
@@ -86,6 +107,11 @@
 | `undo` | 撤销 / 删除；无则"没有配对，一次就是真的" |
 | `failure` | 失败形态（含"可能已经写了"） |
 | `probeCommand`（可空） | 探明 / 预览调用原文 |
+| `key` + `recipe`（可空，成对） | 调用形状（配方）：写走 `data.submit` 时填，`sync` 把它和读一起生成进 `src/datasource.ts`（`DATASOURCE.<key>`）。`key` 不许和读撞，撞了 `design check` 红 |
+| `custom`（可空） | 只记 `why`：配方盖不住的写（签名 / 多步 / 一次性 token），脚本仍留代码里；与 `recipe` 二选一，`design check` 记 warn |
+
+写了 `key + recipe` 的写，预览用 `describeRecipe(DATASOURCE.<key>)`，执行用
+`data.submit(DATASOURCE.<key>, overrides)`；不再把 origin / path 写进代码。
 
 `design render` 写入 README 的 `### 写通道探明记录`（位于「数据源探明记录」与「验收」之间）。
 `design check` 点名空格；无写通道的模块不写。

package/dist/types/shared/api/bundle-install.d.ts

@@ -1,136 +0,0 @@
-export declare const BUNDLE_REGISTRIES_ROUTE = "bundle-registries";
-export declare const BUNDLE_INSPECT_ROUTE = "bundle-inspect";
-export declare const BUNDLE_REGISTRY_DEFAULT = "default";
-export declare const MODULE_VERSIONS_ROUTE = "module-versions";
-export type BundleRegistry = string | null;
-export interface BundleRegistries {
-    readonly registry: BundleRegistry;
-    readonly fallbackRegistries: readonly BundleRegistry[];
-    readonly resolved: string | null;
-}
-export type BundleInspectProblem = 'invalid-spec' | 'already-installed' | 'not-found' | 'not-a-package' | 'not-a-bundle' | 'not-a-workbench-module' | 'not-a-module-or-plugin' | 'network' | 'unknown';
-export type BundleSpecKind = 'registry' | 'path' | 'git' | 'tarball';
-export interface BundleInspectionAccepted {
-    readonly status: 'accepted';
-    readonly kind: BundleSpecKind;
-    readonly name?: string;
-    readonly version?: string;
-    readonly description?: string;
-    readonly bundle: boolean | null;
-    readonly registry: BundleRegistry;
-    readonly host?: string;
-}
-export interface BundleInspectionRefused {
-    readonly status: 'refused';
-    readonly problem: BundleInspectProblem;
-    readonly reason: string;
-    readonly registries?: readonly BundleRegistry[];
-}
-export interface BundleInspectionPlugin {
-    readonly status: 'plugin';
-    readonly pkg: string;
-    readonly registry: BundleRegistry;
-    readonly pluginName?: string;
-    readonly version?: string;
-}
-export type BundleInspection = BundleInspectionAccepted | BundleInspectionRefused | BundleInspectionPlugin;
-export interface BundleRegistriesPayload {
-    readonly available: boolean;
-    readonly registries: BundleRegistries | null;
-}
-export interface BundleInspectionPayload {
-    readonly inspection: BundleInspection;
-}
-export type BundleApplication = 'applied' | 'restart-required' | 'overridden' | 'failed' | 'cancelled';
-export declare const SELF_UPDATE_STATES: readonly ["running", "ok", "rolled-back", "failed"];
-export type SelfUpdateState = (typeof SELF_UPDATE_STATES)[number];
-export interface WorkbenchSelfUpdate {
-    readonly state: SelfUpdateState;
-    readonly profile?: string;
-    readonly from?: string;
-    readonly to?: string;
-    readonly version?: string;
-    readonly at?: string;
-    readonly tail?: string;
-}
-export declare const RESTART_REASONS: readonly ["no-hmr", "package-moved", "host-module", "unmanaged-plugin", "module-comparison"];
-export type RestartReason = (typeof RESTART_REASONS)[number];
-export type BundleChangeStage = 'install' | 'enable' | 'remove';
-export type BundleFailureKind = 'pnpm-missing' | 'timeout' | 'not-found' | 'no-matching-version' | 'network' | 'disk-full' | 'permission' | 'build-blocked' | 'integrity' | 'unknown';
-export interface BundlePackageResult {
-    readonly exitCode: number;
-    readonly output: string;
-    readonly truncated: boolean;
-    readonly logPath: string;
-    readonly kind?: BundleFailureKind;
-}
-export interface BundleChange {
-    readonly application: BundleApplication;
-    readonly stage: BundleChangeStage;
-    readonly changed: boolean;
-    readonly target: string;
-    readonly bundle?: string;
-    readonly version?: string;
-    readonly errorCode?: string;
-    readonly errorDetail?: string;
-    readonly packageResult?: BundlePackageResult;
-    readonly pendingBuilds?: readonly string[];
-    readonly restartReason?: RestartReason;
-    readonly failedAt?: 'registry' | 'spec-host';
-}
-export interface BundleInstallRequest {
-    readonly spec: string;
-    readonly registry?: BundleRegistry;
-    readonly requestId?: string;
-    readonly approvedBuilds?: readonly string[];
-}
-export type BundleCancellation = 'cancelled' | 'too-late' | 'not-running';
-export type BundleSupplyState = 'not-a-module' | 'no-needs' | 'installed' | 'failed' | 'pending-restart';
-export interface BundleModulePayload {
-    readonly kind: 'module' | 'not-module' | 'unknown';
-    readonly pkg: string;
-    readonly unit?: string;
-    readonly version?: string;
-}
-export interface BundleSupplyPayload {
-    readonly state: BundleSupplyState;
-    readonly reason?: string;
-}
-export interface BundleInstalledPlugin {
-    readonly kind: 'opencli-plugin';
-    readonly pkg: string;
-    readonly name?: string;
-}
-export interface BundleInstallPayload {
-    readonly change: BundleChange;
-    readonly module: BundleModulePayload;
-    readonly supply: BundleSupplyPayload;
-    readonly plugin?: BundleInstalledPlugin;
-}
-export interface BundleRemovePayload {
-    readonly change: BundleChange;
-    readonly keptFor: readonly string[];
-}
-export interface BundleCancellationPayload {
-    readonly cancellation: BundleCancellation | null;
-}
-export interface ModuleVersion {
-    readonly unit: string;
-    readonly pkg: string;
-    readonly installed: string;
-    readonly latest?: string;
-    readonly local?: boolean;
-    readonly refused?: readonly string[];
-}
-export interface WorkbenchVersion {
-    readonly pkg: string;
-    readonly installed: string;
-    readonly latest?: string;
-    readonly running?: string;
-    readonly local?: boolean;
-}
-export interface ModuleVersionsPayload {
-    readonly modules: readonly ModuleVersion[];
-    readonly workbench?: WorkbenchVersion;
-    readonly selfUpdate?: WorkbenchSelfUpdate;
-}

package/dist/types/shared/api/config-sync.d.ts

@@ -1,35 +0,0 @@
-export declare const CONFIG_SYNC_ROUTE = "config-sync";
-export declare const CONFIG_SYNC_RESOURCE = "configSync";
-export type ConfigSyncState = 'new' | 'differs';
-export interface ConfigSyncRow {
-    readonly key: string;
-    readonly id: string;
-    readonly insert: boolean;
-    readonly state: ConfigSyncState;
-    readonly body: string;
-    readonly ownBody: string | null;
-    readonly missing: readonly string[];
-}
-export interface ConfigSyncProfile {
-    readonly name: string;
-    readonly readable: boolean;
-    readonly candidates: number;
-}
-export interface ConfigSyncSnapshot {
-    readonly self: string;
-    readonly home: string;
-    readonly source: string;
-    readonly profiles: readonly ConfigSyncProfile[];
-    readonly rows: readonly ConfigSyncRow[];
-    readonly emptyProviders: boolean;
-    readonly reason?: string;
-}
-export interface ConfigSyncApplied {
-    readonly written: readonly string[];
-    readonly skipped: readonly string[];
-}
-export interface ConfigSyncRequest {
-    readonly source: string;
-    readonly keys: readonly string[];
-    readonly overwrite: readonly string[];
-}

package/dist/types/shared/api/dsh-plugins.d.ts

@@ -1,11 +0,0 @@
-export declare const DSH_PLUGINS_ROUTE = "dsh-plugins";
-export interface DshPluginRow {
-    readonly name: string;
-    readonly version: string;
-    readonly enabled: boolean;
-}
-export interface DshPluginsSnapshot {
-    readonly available: boolean;
-    readonly bundles: readonly DshPluginRow[];
-    readonly plugins: readonly DshPluginRow[];
-}

package/dist/types/shared/api/host/bundle-manager.d.ts

@@ -1,11 +0,0 @@
-import type { DshHostContext } from '@dsh-workbench/shared';
-import type { BundleCancellation, BundleChange, BundleInspection, BundleInstallRequest, BundleRegistries, BundleRegistry } from '../bundle-install.js';
-export interface BundleManager {
-    registries(): Promise<BundleRegistries | null>;
-    inspect(spec: string, registry?: BundleRegistry): Promise<BundleInspection | null>;
-    install(request: BundleInstallRequest): Promise<BundleChange | null>;
-    remove(name: string): Promise<BundleChange | null>;
-    setEnabled?(name: string, enabled: boolean): Promise<BundleChange | null>;
-    cancel(requestId: string): Promise<BundleCancellation | null>;
-}
-export declare function readBundleManager(ctx: DshHostContext): BundleManager | undefined;

package/dist/types/shared/api/host/config-sync.d.ts

@@ -1,46 +0,0 @@
-import type { PostResource, RouteHandler } from '@dsh-workbench/shared/host';
-import type { ConfigSyncRow, ConfigSyncSnapshot } from '../config-sync.js';
-export interface PatchBlock {
-    readonly key: string;
-    readonly id: string;
-    readonly insert: boolean;
-    readonly body: string;
-    readonly names: readonly string[];
-}
-export declare function patchBlocks(text: string): PatchBlock[];
-export declare function normalizeBlock(body: string): string;
-export declare function syncRows(source: readonly PatchBlock[], own: readonly PatchBlock[], missing: (block: PatchBlock) => readonly string[]): ConfigSyncRow[];
-export declare function mergeBlocks(ownText: string, incoming: readonly PatchBlock[], overwrite: ReadonlySet<string>): {
-    ok: true;
-    text: string;
-    written: string[];
-    skipped: string[];
-} | {
-    ok: false;
-    reason: string;
-};
-export declare function readPatchBlocks(path: string): {
-    ok: true;
-    text: string;
-    blocks: PatchBlock[];
-} | {
-    ok: false;
-    reason: string;
-};
-export declare function writePatchFile(path: string, text: string): void;
-export interface ConfigSyncDeps {
-    readonly home: string;
-    readonly self: string;
-    readonly profileDir: string | null;
-}
-export declare function configSyncHandler(deps: ConfigSyncDeps): RouteHandler;
-export declare function configSyncSnapshot(deps: ConfigSyncDeps, asked?: string): ConfigSyncSnapshot;
-export declare function configSyncApply(deps: ConfigSyncDeps, payload: unknown): {
-    ok: true;
-    written: string[];
-    skipped: string[];
-} | {
-    ok: false;
-    text: string;
-};
-export declare function configSyncAction(deps: ConfigSyncDeps): PostResource;

package/dist/types/shared/api/host/diy-preset-health.d.ts

@@ -1,35 +0,0 @@
-import type { DshAgentPresetRow, DshHostContext } from '@dsh-workbench/shared';
-/**
- * DIY 模式挂不起来时给用户的那条修法：升级 dsh，再重启一次工作台（启动器那道拒绝用的是同一条）。
- */
-export declare const DIY_UPGRADE_COMMAND = "npm i -g @deepseek-ai/dsh@latest";
-/**
- * 一次 DIY 模式体检的结论：`ok` 为真 = 名册里有那一行且挂着；为假时 `rows` 是挂不起来的行名、`detail` 是 dsh 给的原文。
- */
-export interface DiyPresetVerdict {
-    readonly ok: boolean;
-    readonly rows: readonly string[];
-    readonly detail: string;
-}
-/**
- * 把 dsh 名册里那句 `broken` 原文拆成一项一个行名。
- * @param detail - registry 给的原文，一行一项，形如 `tool-schedule (@deepseek-ai/dsh-tool-schedule): never started`。
- * @returns 每行 `(` 之前那一段；空原文给空数组。
- */
-export declare function brokenRowsOf(detail: string): readonly string[];
-/**
- * 从 preset 名册判 DIY 模式挂不挂得起来。
- * @param presets - `agentPresets.list()` 的回值。
- * @returns 名册还空着（preset 行还没登记完）给 `undefined` —— 那是"还不知道"，不是故障；否则给结论。
- */
-export declare function diyPresetVerdictOf(presets: readonly DshAgentPresetRow[]): DiyPresetVerdict | undefined;
-/**
- * 造一个读 preset 名册的探针：名册还没登记完就每 `everyMs` 重读，到 `deadlineMs` 还没读到就放弃。
- * @param ctx - 宿主上下文（取 `agentPresets` 服务；那个服务不在时给一个恒回 `undefined` 的探针）。
- * @param options - 两个时间旋钮（测试用）：多久放弃、隔多久重读。
- * @returns 探针：调一次读一轮，`undefined` 表示"这次没读到"。
- */
-export declare function createDiyPresetProbe(ctx: DshHostContext, options?: {
-    deadlineMs?: number;
-    everyMs?: number;
-}): () => Promise<DiyPresetVerdict | undefined>;

package/dist/types/shared/api/host/dsh-plugins.d.ts

@@ -1,5 +0,0 @@
-import type { DshHostContext } from '@dsh-workbench/shared';
-import type { RouteHandler } from '@dsh-workbench/shared/host';
-import type { DshPluginsSnapshot } from '../dsh-plugins.js';
-export declare function readDshPlugins(ctx: DshHostContext): Promise<DshPluginsSnapshot>;
-export declare function dshPluginsHandler(ctx: DshHostContext): RouteHandler;

package/dist/types/shared/api/host/installed-module.d.ts

@@ -1,54 +0,0 @@
-import type { DshHostContext } from '@dsh-workbench/shared';
-import type { UnitDeclarationSource } from './unit-registry';
-export type InstalledModule = {
-    readonly kind: 'module';
-    readonly pkg: string;
-    readonly unit: string;
-    readonly version: string;
-    readonly registry?: string;
-    readonly local?: boolean;
-} | {
-    readonly kind: 'not-module';
-    readonly pkg: string;
-} | {
-    readonly kind: 'unknown';
-    readonly pkg: string;
-};
-export declare function isPackageName(value: string): boolean;
-export declare function profileDirOf(ctx: DshHostContext): string | null;
-export interface ProfileModule {
-    readonly pkg: string;
-    readonly unit: string;
-    readonly version: string;
-    readonly registry?: string;
-    readonly local?: boolean;
-}
-export declare function profileManifestOf(profileDir: string | null): Readonly<Record<string, unknown>> | undefined;
-export declare function profileModules(profileDir: string | null): readonly ProfileModule[];
-export declare function createDeclarationLookup(profileDir: string | null): (unit: string) => UnitDeclarationSource | undefined;
-export declare function moduleDeclarationOf(profileDir: string | null, pkg: string): unknown;
-export interface DeclarationGap {
-    readonly pkg: string;
-    readonly problems: readonly string[];
-}
-export declare function declarationGaps(profileDir: string | null): readonly DeclarationGap[] | undefined;
-export declare function declaredPluginCommands(profileDir: string | null): ReadonlyMap<string, ReadonlySet<string>>;
-export declare function readInstalledModule(profileDir: string | null, pkg: string): InstalledModule;
-/**
- * 这份依赖是不是"从一个**打好的包**装的"（`file:/tmp/dsh-workbench-core-0.3.8.tgz`、
- * `./x-0.3.8.tgz`）。它跟 `link:` / 目录装的**不是**一回事：那是工作树（改了立刻生效，
- * 也不可能跟源上比出个新旧），而 tgz 是打包产物 —— 包名与版本就是源上那一套，能比、
- * 也该让人更新。混在一起会把"从文件装的发布产物"说成"本仓正在开发的那一份"，
- * 顺带把版本比对与更新一起关掉。
- */
-export declare function isPackedArtifactSpec(spec: string): boolean;
-/** 这份依赖是不是"本仓那份"（`link:` / 目录 / 相对或绝对路径）—— 只有工作树才算。 */
-export declare function isLocalDependencySpec(spec: string): boolean;
-export interface ProfilePackage {
-    readonly pkg: string;
-    readonly version: string;
-    readonly registry?: string;
-    readonly local?: boolean;
-}
-export declare function readProfilePackage(profileDir: string | null, pkg: string): ProfilePackage | undefined;
-export declare function packageVersionAt(packageRoot: string): string | undefined;

package/dist/types/shared/api/host/installed-module.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/shared/api/host/opencli-command.d.ts

@@ -1,10 +0,0 @@
-import type { DshHostContext } from '@dsh-workbench/shared';
-export type OpencliSource = 'env' | 'isolated' | 'path';
-export interface OpencliResolution {
-    readonly command: string;
-    readonly source: OpencliSource;
-    readonly isolated: string | null;
-}
-export declare const OPENCLI_PATH_FALLBACK = "opencli";
-export declare function isolatedOpencliPathOf(ctx: DshHostContext): string | null;
-export declare function opencliCommandOf(ctx: DshHostContext): OpencliResolution;