@dsh-workbench/core 0.1.0

package/docs/OPERATIONS.md

@@ -0,0 +1,109 @@
+# 操作
+
+装机、起实例、验收、排障。命令本身在 `package.json` 的 `scripts` 里，这里只写**顺序**和**判据**。
+
+## 装一次
+
+一条命令版（②+④ 都在里面，幂等，可重复跑）：
+
+```bash
+./scripts/verify.sh --record     # ① 记录 dsh web 的基线（越早越好）
+./bin/dsh-workbench setup        # ② 建 workbench profile 并把工作台装进 profile
+./bin/dsh-workbench               # ③ 起工作台（另开一个终端）
+```
+
+想拆开做也行：`./scripts/seed-profile.sh` 只建 profile 骨架（继承 + 隔离层），
+装 bundle 则在**工作台进程里**做 —— `plugin_manager` 只作用于当前 profile：
+
+> 在工作台的会话里让 agent 执行 `install_bundle target=<本仓库绝对路径>`
+
+`setup` 与 agent 那条路等价：都走 dsh 的 `runPluginCommand`（兼容性预检、profile 写锁、
+装完把 bundle 登记进清单）。
+
+**完成判据**：`:3081` 的页面出现工作台的左栏；`:3080` 一切照旧。
+
+工作台用的 opencli 是它自己的**隔离运行时**（`~/.dsh/workbench/opencli/toolchain`，版本由
+`OPENCLI_PIN` 锁），但它连的 **daemon 是整机一个** —— 见下面「隔离边界」。
+
+前提：`dsh` 和 `pnpm` 在 PATH 上（`dsh plugin` 是转发给 pnpm 的），
+且 `~/.dsh/profiles/web` 已存在（跑过一次 `dsh web` 即可）。
+
+**给别人用**（发包到内网源、对方要登录内网源 / Coding）见 [`HANDOFF.md`](HANDOFF.md)。
+
+## 日常
+
+| 想做什么 | 怎么做 |
+|---|---|
+| 开工作台 | `./bin/dsh-workbench` |
+| 换端口 | `WORKBENCH_PORT=3091 ./bin/dsh-workbench` |
+| 改工作台设置 | 在 `:3081` 的 Settings 页改，落在 `profiles/workbench/cordis.patch.yml` |
+| 改 web 设置 | 在 `:3080` 改，落在 `profiles/web/cordis.patch.yml`。**两边都要的设置（模型供应商、搜索源、MCP）就在这一份里配** —— 工作台启动时会用 `--patch` 把它叠上来（web → 工作台，单向、实时），所以不必配两遍 |
+| 改只有工作台用的设置 | 在 `:3081` 改，落在 `profiles/workbench/cordis.patch.yml`。这个文件**只剩工作台自己的差异**（会话/存储/附件隔离 + 沙箱）；被 web 覆盖过的行在这里改不动（编辑器会写 `overridden`，那就是"这行由 web 管"的提示） |
+| 重建 profile | `mv ~/.dsh/profiles/workbench ~/.dsh/profiles/workbench.bak` 后重跑 seed |
+| **别在设置里关掉工作台** | Settings → 插件里 `@dsh-workbench/core` 那个开关**不要关**。关掉=把它从 profile 的 `bundles` 里移除 → 我们那份 bundle patch（含"禁用出厂左栏"）**整份不再应用** → 页面退化成**原版 dsh web**（左栏回来、右侧面板消失），**数据一个都不丢**。恢复：插件页把开关打开（左栏的「插件」入口也在；进不去设置就按 `Meta+,`）。实测过这条降级路径，不是推断 |
+
+## 开发循环（改完不用重启）
+
+```bash
+./bin/dsh-workbench        # 终端 A：工作台
+pnpm run dev                # 终端 B：监听 src/**，重建产物
+```
+
+改 `src/**` → 约 1 秒后界面就是新的，**不用重启、不用刷新**。两条链路都是 dsh 自带的：
+
+| 半侧 | 链路 | 代价 |
+|---|---|---|
+| 浏览器 | Vite 重建 `client.js` → `dsh-client-hmr` 每 500ms stat-poll 到 mtime/大小变化 → `/plugins/events` 发 `rebuilt` → 浏览器作废旧模块、预取新包、换 fiber | 插件内的 React 状态会丢；会话 / 工作区 / 连接状态保留 |
+| 宿主 | Vite 重建 `dist/host/index.js` → `dsh-hmr` 按模块 realpath 匹配并重载插件 | 插件重建，进程与其它插件不受影响 |
+
+**只有这两种改动要重启**：`cordis.patch.yml`（组合层）与 `package.json` 的 `dsh.profile.bundles`。
+
+宿主侧监听为什么要环境变量：出厂 `hmr` 的 `root` 默认是 `[]`（不监听），
+而相对路径以 profile 目录为基准 —— 我们的包在 profile 里只是一个指向本仓库的符号链接，
+从 profile 目录出发走不到 `/Volumes/…`，chokidar 收不到事件（实测 `root: ['.']` 无效）。
+所以启动器导出 `DSH_WORKBENCH_ROOT`，补丁里用 `!!js process.env.DSH_WORKBENCH_ROOT ?? '.'`。
+
+## 验收
+
+```bash
+./scripts/verify.sh
+```
+
+五项检查，全部是"外部约束的证据"而不是自证：
+
+0. **代码接线** —— 槽位名 / key / id / locale 是否对得上（语法检查抓不到这类错）
+1. **web 是否被动过** —— 与 `--record` 的哈希逐一比对
+2. **组合树差异** —— `dsh web --dump-config` vs `dsh workbench --dump-config`，
+   差异应恰好是隔离行 + 工作台行 + `ui-sidebar` 被禁用
+3. **数据是否分家** —— `~/.dsh/sessions` 与 `~/.dsh/workbench/sessions` 各自独立
+4. **隔离行是否在位** —— 三个根行都在 `profiles/workbench/cordis.patch.yml` 里
+
+另外两项要 GUI / agent 才能验：
+
+- **槽位注册**：让 agent 执行 `cordis_inspect_query` → `Slots.listSubTree`，
+  看对应 `root` 的 `occupants` 里有没有我们的条目。**这是权威证据**，别靠日志推断。
+- **视觉一致性**：亮色 / 暗色各看一次，确认颜色全部来自 `--dsw-*` 令牌。
+
+## 隔离边界
+
+| 资源 | 是否隔离 | 落在哪 |
+|---|---|---|
+| 会话历史 | ✅ | `~/.dsh/workbench/sessions/` |
+| 工作区 / 会话投影缓存 | ✅ | 走 `storage-domain` → `storage-json` 根 |
+| 附件 | ✅ | `~/.dsh/workbench/attachments/v1/` |
+| 模块配置 | ✅ | `~/.dsh/workbench/workspaces/<工作区>/<模块 id>/`（见 [ADR-0011](../../../docs/adr/0011-module-config-lives-in-its-own-folder.md)） |
+| API 凭据 | ❌ **有意共享** | `~/.dsh/.credentials.yaml`，两边同一把 key |
+| opencli 运行时（CLI + 插件） | ✅ | `~/.dsh/workbench/opencli/`（`HOME` 指到 `…/home`，见 [ADR-0014](../../../docs/adr/0014-opencli-cost-has-one-owner.md) §2.2） |
+| opencli **daemon** | ❌ **整机一个，隔离不了** | 端口 **19825 被扩展写死**（`background.js` 里 `DAEMON_PORT = 19825`；CLI 侧 `OPENCLI_DAEMON_PORT` 设非默认值直接报错）。所以本机的全局 opencli 与工作台的隔离运行时**抢同一个 daemon**：两边版本不一致时，谁的命令后跑谁就把 daemon 重启成自己那版 |
+
+## 排障
+
+| 症状 | 原因 |
+|---|---|
+| 页面白屏、只显示 `Failed to load plugins` | 有插件在 `slots.register` 到未声明的槽（抛错即整个 entry 激活失败）。看控制台里我们打的 `[dsh-workbench] apply failed` |
+| 面板一直空着、`/workbench/api/issues` 返回 `coding-not-logged-in` | opencli 登录态失效：在终端跑 `opencli coding team-current` 完成登录 |
+| 面板显示"这个项目不是 Coding 仓库" | 该工作区的 git `origin` 不指向 `e.coding.net`（或没有 origin） |
+| 打开面板/按刷新要等 5–8 秒 | 正常：opencli 每次调用有**固定约 5 秒**开销（起浏览器会话；接口本身只要 ~260ms）。**没有缓存**——数据一律实时，列表 = 缺陷 + 状态目录两次调用（限并发 2，实测约 7 秒） |
+| 改了源码没变化 | 忘了 `pnpm run build`，或没重启进程（宿主缓存已加载的包） |
+| 体检那屏「检测浏览器通道 · 没连上」，可面板照样能用 | 本机全局 opencli 与隔离运行时版本不一致 ⇒ daemon 被顶成对方那版（`Stale daemon detected: daemon vX != CLI vY`）。下一条浏览器命令会自动把它重启回来，体检也会复检后改回「已连接」（[ADR-0024](../../../docs/adr/0024-warm-the-sites-before-the-panel.md) §3.2.1）。**要彻底不抖**：让两边同版本 —— 把 `OPENCLI_PIN`（`src/shared/config/constants.ts`）对齐到 `opencli --version`，再 `npm i --prefix ~/.dsh/workbench/opencli/toolchain @jackwener/opencli@<那个版本> --cache ~/.dsh/workbench/opencli/npm-cache` |
+| Settings 页报 `overridden by a home patch` | 想在 Settings 里改的行被 `$DSH_HOME/cordis.patch.yml` 或 `--patch` 覆盖了 |

package/icon.svg

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- 占位图标：插件管理卡片与 bundle 详情页使用。
+     图标以图片形式渲染，因此 currentColor 在这里不生效，
+     需要主题自适应时请按亮/暗两套各出一版或改用中性色。 -->
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="0 0 64 64"
+  width="64"
+  height="64"
+  role="img"
+  aria-label="Workbench"
+>
+  <rect
+    x="8"
+    y="8"
+    width="48"
+    height="48"
+    rx="12"
+    fill="none"
+    stroke="#6b7280"
+    stroke-width="5"
+  />
+  <path
+    d="M21 24h22M21 32h22M21 40h13"
+    stroke="#6b7280"
+    stroke-width="5"
+    stroke-linecap="round"
+  />
+</svg>

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@dsh-workbench/core",
+  "version": "0.1.0",
+  "description": "个人工作台：Agent 工作台外壳（左栏 + 常驻对话 + 自研右侧数据面板）。",
+  "type": "module",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": {
+      "types": "./dist/types/app/host.d.ts",
+      "default": "./dist/host/index.js"
+    },
+    "./client": {
+      "types": "./dist/types/app/client.d.ts",
+      "default": "./client.js"
+    },
+    "./package.json": "./package.json",
+    "./client/esm": {
+      "types": "./dist/types/app/client.d.ts",
+      "default": "./dist/client/index.js"
+    }
+  },
+  "bin": {
+    "dsh-workbench": "./bin/dsh-workbench"
+  },
+  "//files": "npm 的兜底是 .gitignore —— 而 dist/ 在 .gitignore 里，不显式列出就会**漏掉宿主入口**（exports['.'] 指向它）。发出去之前用 npm pack --dry-run 数一遍 dist/ 有几条。",
+  "files": [
+    "dist",
+    "client.js",
+    "cordis.patch.yml",
+    "icon.svg",
+    "bin",
+    "profile",
+    "scripts/seed-profile.sh",
+    "README.md",
+    "docs/HANDOFF.md",
+    "docs/OPERATIONS.md"
+  ],
+  "meta": {
+    "title": "Workbench",
+    "description": "个人工作台"
+  },
+  "//scripts": "包内不跑 check:docs —— 那份文档管理块住在仓库根的 docs/ARCHITECTURE.md，由根 `pnpm run check` 用 --config 指到本包的 arch.config.mjs 校验。prepublishOnly 走 -w 跑根那一整套。",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "react": "*"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arch-guard/core": "^0.10.0",
+    "@types/node": "^24.19.0",
+    "@types/react": "^19.3.0",
+    "@vitest/coverage-v8": "^5.0.2",
+    "esbuild": "^0.28.2",
+    "react": "^19.3.0",
+    "typescript": "5.9",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2"
+  },
+  "//publishConfig": "只影响**发布这个包**，不影响别人解析依赖。内网源地址在这一处（交接文档里写给对方的也是这一条）。",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dsh-workbench/shared": "0.1.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs && node scripts/build-types.mjs",
+    "build:host": "node scripts/build.mjs host",
+    "build:client": "node scripts/build.mjs client",
+    "typecheck": "tsc --noEmit",
+    "arch": "arch-guard",
+    "selfcheck": "node scripts/selfcheck.mjs",
+    "check:host": "node scripts/check-host.mjs",
+    "check:runtimes": "node scripts/check-runtimes.mjs",
+    "check": "npm run typecheck && npm run coverage && npm run arch && npm run check:runtimes && npm run selfcheck",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "dev": "node scripts/dev.mjs",
+    "build:types": "node scripts/build-types.mjs"
+  }
+}

package/profile/isolation.patch.yml

@@ -0,0 +1,35 @@
+# workbench profile 的会话/存储隔离层（片段）。
+#
+# 这个文件是"补丁层片段"，不是独立补丁文件：seed-profile.sh 会把它
+# 追加进 ~/.dsh/profiles/workbench/cordis.patch.yml。
+#
+# 为什么需要它：dsh-base 把会话与存储的根都挂在 $DSH_HOME 上
+# （dshHomePath('sessions') / dshHomePath('storages')），所以默认情况下
+# 两个 profile 共用同一份会话历史。工作台要提供自己的定制工具，等于一个
+# 独立的 agent 环境，共享会话没有意义 —— 这三行把数据分开。
+#
+# 隔离后：
+#   会话      ~/.dsh/workbench/sessions/
+#   工作区    ~/.dsh/workbench/storages/        （workspace 走 storage-domain）
+#   附件      ~/.dsh/workbench/attachments/v1/
+# 有意不隔离：
+#   凭据      ~/.dsh/.credentials.yaml          （两边共用同一把 API key）
+#
+# 注意：patch 的 config 是整体替换、不深合并。这三行原本各自只声明了
+# root / dshHome，所以只重述这一个字段是安全的；若你给这些行配过别的
+# 字段（例如 session-persistence-jsonl 的 compression），必须一并重述。
+
+- id: session-persistence-jsonl
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: !!js dshHomePath('workbench/sessions')
+
+- id: storage-json
+  name: '@deepseek-ai/dsh-storage-json'
+  config:
+    root: !!js dshHomePath('workbench/storages')
+
+- id: attachment-local
+  name: '@deepseek-ai/dsh-attachment-local'
+  config:
+    dshHome: !!js dshHomePath('workbench')

package/profile/sandbox.patch.yml

@@ -0,0 +1,26 @@
+# 工作台运行时的**可写根**声明 —— 由启动器每次启动叠加（`--patch`）。
+#
+# 为什么必须有它：工作台自己要跑命令（启动体检自动装 opencli、模块市场装/升插件、
+# 查源上有没有新版），而这些命令走 dsh 的**执行缝**，执行缝带**文件沙箱**。
+# 插件发起的调用**没有会话**，于是回落到部署策略；dsh-base 出厂那一条写的是
+# `workspaceRoot: !!js process.cwd()` —— 而安装目标是 `$DSH_HOME/workbench/...`，
+# 不在启动目录下面，沙箱拒写（实测 EPERM：mkdir ~/.npm/_cacache、mkdir
+# $DSH_HOME/workbench/...，见 .scratch/agent-issues/spec.md 第 10.3 节）。
+# 症状：自动安装死在第一步，界面只能退化成"让用户去终端抄一条命令" ——
+# 终端没有沙箱，抄过去反而能跑，于是这个缺口一直看不出来。
+#
+# 指到 `$DSH_HOME/workbench` 之后，沙箱放行的是**同一棵树**：
+#   隔离运行时的工具链 + npm 缓存（opencli-runtime.ts）、
+#   模块专属文件夹（ADR-0011 的 workspaces/）、模块市场的 plugins-npm。
+# 也就是 ADR-0011 说的"启动器给插件声明的可写根"。
+#
+# 为什么用 `--patch` 叠加、而不是写进 profile 的 cordis.patch.yml：
+# profile 可能是**早就建好**的（交接出去的机器尤其如此），没人会回头重跑
+# seed-profile.sh —— 叠加层每次启动都生效，对新旧 profile 一视同仁。
+#
+# mode 与 base 出厂值**一致**（只重述，不改变语义）：patch 的 config 是**整体替换**、
+# 不深合并，所以两个字段都得写全，否则 workspaceRoot 会被替换掉 mode 丢失。
+- id: sandbox-policy
+  config:
+    mode: !!js process.env.DSH_PERMISSION_MODE ?? 'workspace-write'
+    workspaceRoot: !!js dshHomePath('workbench')

package/scripts/seed-profile.sh

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+#
+# 一次性引导：从 shipped 的 web 模板创建 workbench profile，
+# 继承 web 的配置（bundle 清单 + 设置快照 + 设置引用到的依赖），
+# 再加上会话 / 存储 / 附件的隔离层。
+#
+# 幂等 / 可续跑：profile 已存在就跳过创建，patch 已非空就跳过继承，
+# 隔离层已存在就跳过追加，依赖已在 node_modules 就跳过安装
+# —— 重复运行不会覆盖任何东西。
+# 安全：全程只**读** web 的 profile 目录，只**写** workbench 自己的目录。
+#
+# 用法:
+#   ./scripts/seed-profile.sh
+#   WORKBENCH_PROFILE=wb2 ./scripts/seed-profile.sh   # 建到别的 profile 名下（试装用）
+
+set -euo pipefail
+
+DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+PROFILE="${WORKBENCH_PROFILE:-workbench}"
+SRC_PROFILE="$DSH_HOME/profiles/web"
+DST_PROFILE="$DSH_HOME/profiles/$PROFILE"
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+GIT_TOP="$(git -C "$REPO_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+ISOLATION="$REPO_DIR/profile/isolation.patch.yml"
+
+# `verify.sh` 留在**仓库根**（它证明的是"dsh web 未被动过 / 组合树差异 / 数据分家"，
+# 与包边界无关），所以不能按 $REPO_DIR 拼。装成安装包（没有 git 工作树）时它不存在，
+# 那就只说"见仓库的 scripts/verify.sh"。
+VERIFY_DIR="${GIT_TOP:-$REPO_DIR}/scripts"
+
+die() {
+  echo "seed-profile: $*" >&2
+  exit 1
+}
+
+[ -f "$SRC_PROFILE/package.json" ] ||
+  die "找不到 $SRC_PROFILE —— 请先跑一次 'dsh web'，让 web profile 落地。"
+[ -f "$ISOLATION" ] || die "找不到 $ISOLATION"
+
+DST_PATCH="$DST_PROFILE/cordis.patch.yml"
+
+# dsh 生成的 patch 文件带一段注释头，所以"是否还是空层"不能直接和 [] 比。
+is_pristine_patch() {
+  [ "$(grep -v '^[[:space:]]*#' "$1" | tr -d '[:space:]')" = "[]" ]
+}
+
+# ── 第 1 步：创建 profile ────────────────────────────────────────────────
+# --from-default-profile web 只复制 web 模板的 bundle 列表
+# （dsh-base + dsh-web-app），**不**复制 web 的 cordis.patch.yml。
+# 用 --dump-config 而不是直接启动：走同一条初始化路径，但只打印
+# 组合树，不挂载、不监听端口。
+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
+fi
+
+[ -f "$DST_PATCH" ] || die "profile 缺少 $DST_PATCH"
+
+# ── 第 2 步：继承 web 的 profile 清单 ───────────────────────────────────
+# --from-default-profile 只复制**出厂模板**的 bundle 列表（dsh-base +
+# dsh-web-app），而 web 的清单可能后来被 install_bundle / plugin_manager
+# 改过（例如启用了某个可选 bundle）。所以这里把 web 清单里的 bundles
+# 并进来，同时保留 workbench 自己已有的额外项（例如 @dsh-workbench/core），
+# 使脚本可重复运行。
+WB_MANIFEST="$DST_PROFILE/package.json" \
+  WEB_MANIFEST="$SRC_PROFILE/package.json" \
+  node -e '
+const fs = require("node:fs");
+const read = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
+const wb = read(process.env.WB_MANIFEST);
+const web = read(process.env.WEB_MANIFEST);
+const webProfile = (web.dsh && web.dsh.profile) || {};
+const wbProfile = (wb.dsh && wb.dsh.profile) || {};
+const webBundles = webProfile.bundles || [];
+const wbBundles = wbProfile.bundles || [];
+const merged = webBundles.concat(
+  wbBundles.filter((b) => webBundles.indexOf(b) === -1),
+);
+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(", "));
+'
+
+# ── 第 3 步：把 web 的设置文档复制过来，作为「继承」的起点 ──────────────
+# profiles/<name>/cordis.patch.yml 就是 Settings 页的活文档
+# （config-editor.documentPath === profileContext.patchPath）。
+# 复制一份快照，两边之后各自独立演进 —— 这正是「互不干扰」的实现方式。
+if is_pristine_patch "$DST_PATCH"; then
+  cp "$SRC_PROFILE/cordis.patch.yml" "$DST_PATCH"
+  echo "→ 已继承 web 的配置快照"
+else
+  echo "→ profile 的 patch 已非空，跳过继承（避免覆盖你自己的改动）"
+fi
+
+# ── 第 4 步：追加会话 / 存储 / 附件隔离层 ───────────────────────────────
+if grep -q 'id: session-persistence-jsonl' "$DST_PATCH"; then
+  echo "→ 隔离层已存在，跳过"
+else
+  printf '\n' >>"$DST_PATCH"
+  cat "$ISOLATION" >>"$DST_PATCH"
+  echo "→ 已追加隔离层（sessions / storages / attachments 分家）"
+fi
+
+# ── 第 5 步：继承「被 patch 点名」的依赖 ────────────────────────────────
+# 第 3 步把 web 的设置文档整份复制了过来，而那份文档是**按 name: 点名**插件的。
+# 出厂 @deepseek-ai/* 由 dsh 安装本体解析，不必装；但自己装的第三方包
+# （例如 @deepseek-ai/dsh-web-search-exa）只住在 profile 的 node_modules 里
+# —— 不跟着继承的话，那一行会以 "failed to import" 静默不激活，功能凭空少一块。
+#
+# 只继承**被 patch 引用**的那些：web 的 dependencies 里可能有装了却没有任何行
+# 引用的包（本机就有 @aipanel/dsh-client 与 @aipanel/dsh-plugin），整份搬过来
+# 只是死重量。反过来说，**不能只写进 package.json** —— node_modules 得跟上，
+# 否则症状一模一样。
+WANTED="$(
+  WB_MANIFEST="$DST_PROFILE/package.json" \
+    WEB_MANIFEST="$SRC_PROFILE/package.json" \
+    PATCH="$DST_PATCH" \
+    node -e '
+const fs = require("node:fs");
+const read = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
+const wb = read(process.env.WB_MANIFEST);
+const web = read(process.env.WEB_MANIFEST);
+
+// patch 里非注释行的 `name:` —— 注释掉的条目（# 开头）不算引用。
+const referenced = new Set();
+for (const line of fs.readFileSync(process.env.PATCH, "utf8").split("\n")) {
+  if (/^\s*#/.test(line)) continue;
+  const m = /^\s*-?\s*name:\s*"?([^"\s#]+)/.exec(line);
+  if (m) referenced.add(m[1]);
+}
+
+// workbench 自己已有的声明优先 —— 重复 seed 不会覆盖你钉住的版本。
+const own = wb.dependencies || {};
+const missing = {};
+for (const [name, version] of Object.entries(web.dependencies || {})) {
+  if (referenced.has(name) && !(name in own)) missing[name] = version;
+}
+if (Object.keys(missing).length > 0) {
+  wb.dependencies = Object.assign({}, missing, own);
+  fs.writeFileSync(process.env.WB_MANIFEST, JSON.stringify(wb, null, 2) + "\n");
+}
+
+// 报出全部「被点名」的依赖（不只是这次新加的）：node_modules 也可能被清过。
+console.log(
+  Object.keys(web.dependencies || {})
+    .filter((name) => referenced.has(name))
+    .join(" "),
+);
+'
+)"
+
+WANTED_MISSING=0
+if [ -n "$WANTED" ]; then
+  echo "→ patch 引用的依赖（须在 profile 内可解析）: $WANTED"
+  for dep in $WANTED; do
+    [ -d "$DST_PROFILE/node_modules/$dep" ] || WANTED_MISSING=1
+  done
+fi
+
+if [ "$WANTED_MISSING" = "1" ]; then
+  echo "→ node_modules 缺这些依赖，装进 profile（走 dsh 的包管理器）"
+  dsh plugin --profile "$(basename "$DST_PROFILE")" install
+else
+  echo "→ 依赖已齐备，跳过安装"
+fi
+
+# 装 bundle 的目标：开发态是这个仓库（link），安装包态是源上那个包。
+# 判据是「git 顶层在不在」—— npm pack 的产物里不含 .git（见 package.json 的 files）。
+# ⚠️ 不能判 `$REPO_DIR/.git`：workspace 之后 .git 在仓库根（同 bin/dsh-workbench）。
+if [ -n "$GIT_TOP" ]; then
+  BUNDLE_TARGET="$REPO_DIR"
+else
+  BUNDLE_TARGET="@dsh-workbench/core@^$(node -p "require('$REPO_DIR/package.json').version" 2>/dev/null || echo 0)"
+fi
+
+cat <<EOF
+
+profile '$DST_PROFILE' 的骨架好了（bundle 清单 + 设置快照 + 隔离层）。
+
+装 bundle —— 两条**等价**的路，任选一条（都走 dsh 的 runPluginCommand，装完会
+把 bundle 登记进 profile 清单）：
+
+  ① 一条命令（建 profile + 装 bundle，幂等，可重复跑）
+       $REPO_DIR/bin/dsh-workbench setup
+
+  ② 在**工作台进程**的会话里让 agent 做（plugin_manager 只作用于当前 profile）
+       启动: $REPO_DIR/bin/dsh-workbench
+       让 agent 执行: install_bundle target=$BUNDLE_TARGET
+
+然后验收（工作台占另一个端口，dsh web 继续用 3080，可同时开）：
+
+  ${VERIFY_DIR}/verify.sh --record   # 先记录基线（可选，越早越好）
+  ${VERIFY_DIR}/verify.sh
+
+EOF