@dsh-workbench/core 0.1.6 → 0.1.8

package/README.md

@@ -1,18 +1,8 @@
 # dsh-workbench
 
-基于 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 **Agent 工作台**。
-一个 dsh 插件包：换掉 dsh 的左栏，中列保留 dsh 的对话，右侧加一列工作台自研的数据面板。
-**dsh 本体一行不改**，两个实例同时跑。
-
-> **产品定位：所有事情都是「告诉 agent 去做」。**
-> 工作台不是操作台，是交代任务 + 看 agent 干得怎么样的地方。
-> 加任何功能前，先过 [`DESIGN.md`](../../DESIGN.md) 的四条硬规则与三个评审问题。
-
-```bash
-dsh web                        # :3080 —— 参考基线，原样不动
-pnpm run dev                    # :3081 —— 开发：监听 src/** + 起工作台（已在跑就只监听）
-./bin/dsh-workbench            # 只想起工作台、不需要监听改动时用它
-```
+基于 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 **Agent 工作台**：
+一个 dsh 插件包 —— 换掉 dsh 的左栏，中列保留 dsh 的对话，右侧加一列自研的数据面板。
+**dsh 本体一行不改**，两个实例可以同时开着。
 
 ```
 dsh web (:3080)                       dsh workbench (:3081)
@@ -24,32 +14,95 @@ dsh web (:3080)                       dsh workbench (:3081)
 └────────────┴─────────┘             └────────────┴──────────┴────────────┘
 ```
 
-**当前进度**：宿主半侧（opencli 数据通路 + 只读投影 + agent 工具）已迁到 TypeScript 并跑通；
-左栏已实现并与 dsh 对齐；右侧数据面板列与「缺陷」看板模块正在从旧单文件 JS 迁到
-`src/app/client.tsx` + `src/modules/**`（见 [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)）。
+**所有事情都是「告诉 agent 去做」。** 工作台不是操作台，是交代任务 + 看 agent 干得怎么样的地方；
+所以界面**只读** —— 面板上没有写按钮，写操作一律由 agent 的工具完成。
+
+## 30 秒上手
+
+先决条件（就三条）：
 
-## 装一次
+| 要有 | 为什么 | 怎么有 |
+| --- | --- | --- |
+| `dsh` | 本体。本包在 `0.1.7-rc.2` 上验过 | `npm i -g @deepseek-ai/dsh` |
+| `node` + `pnpm` | dsh 的 `plugin` 子命令是**转发给 pnpm** 的；没有 pnpm 会直接报 `dsh: pnpm was not found` | 各自装 |
+| 跑过一次 `dsh web` | `setup` 拿 `~/.dsh/profiles/web` 当模板（bundle 清单 + 设置快照 + patch 点名的依赖）。没有它会**明确报错**，不会静默建出半个 profile | `dsh web`，起来就行，然后 Ctrl-C |
+
+然后两条命令：
 
 ```bash
-./scripts/verify.sh --record     # 记录 dsh web 的基线（用于事后证明它没被动过）
-./bin/dsh-workbench setup        # 建 workbench profile + 把工作台装进去（幂等，可重复跑）
-./bin/dsh-workbench             # 起工作台
+npx --yes @dsh-workbench/core@latest setup   # ① 建 workbench profile + 把工作台装进去（幂等，可重复跑）
+npx @dsh-workbench/core                       # ② 起工作台，默认 :3081
 ```
 
-`setup` 最后那一步等价于"在工作台会话里让 agent 执行 `install_bundle target=<本目录>`"
-—— 两条路都走 dsh 的 `runPluginCommand`，装完都会把 bundle 登记进 profile 清单。
-细节见 [`docs/OPERATIONS.md`](docs/OPERATIONS.md)。
+打开 <http://localhost:3081> 就是工作台。你原来那份 `dsh web` 继续用 `:3080`，两边互不影响。
+
+## 首次打开会自己做什么
+
+- **装 opencli 的隔离运行时**：启动体检自己装，落在 `~/.dsh/workbench/opencli/`，
+  **完全不碰**你本机的 `~/.opencli`（插件目录靠改 `HOME` 分开）。装不上时（没网 / 源不通）
+  失败态里有一条**能直接照抄到终端**的命令 —— 那条得在终端跑，工作台自己发起的命令带文件沙箱。
+- **要面板有数据，得登录 Coding**：卡片上点「去登录 ↗」，登完切回来按那颗「重试」
+  （刻意不做自动重试 —— 登录什么时候完成我们不知道）。
+- 没登录 / 装不上都是**明确的失败态**，不会留一块白屏让你猜。
+
+面板上的具体模块（缺陷看板、构建发布、代码分析…）**按需装**：外壳本身零业务模块，
+在 `:3081` 的「工作台模块市场」里装，也可以让 agent 去装。
+
+## 日常
+
+| 想做什么 | 怎么做 |
+| --- | --- |
+| 起工作台 | `npx @dsh-workbench/core` |
+| 换端口 | `WORKBENCH_PORT=3091 npx @dsh-workbench/core` |
+| 升级 | 重跑一次 `npx --yes @dsh-workbench/core@latest setup`（幂等），再重启工作台进程 |
+| 重建 profile | `mv ~/.dsh/profiles/workbench ~/.dsh/profiles/workbench.bak`，再跑一次 `setup` |
+| 彻底不用了 | 删 `~/.dsh/profiles/workbench` 与 `~/.dsh/workbench` 两个目录（都不影响 `dsh web`） |
+| 改设置 | 只有工作台要的（面板显示哪些模块、会话隔离）在 `:3081` 的 Settings 里改 |
+
+## 和 `dsh web` 的关系
+
+- **另一个 profile、另一个端口、另一个进程**：`workbench` profile 在 `~/.dsh/profiles/workbench`；
+  会话 / 存储 / 附件 / 模块配置全走 `~/.dsh/workbench/**`，与 web **数据分家**。只有一样有意共享：
+  API 凭据（`~/.dsh/.credentials.yaml`，一机一把 key）。
+- **两边都要的设置只在 `dsh web` 里配一次**（模型供应商 / API key / 搜索源 / MCP）：工作台启动时
+  把 web 的 profile patch 叠在自己上面（`--patch`，**单向、实时**）。被 web 管的行在工作台的
+  Settings 页里会显示 `overridden by a home patch or command-line overlay` —— 那是**提示**，不是故障。
+  反向不成立：工作台里配的不会流回 web。
+- ⚠️ **别在 Settings → 插件里把 `@dsh-workbench/core` 关掉**：关掉 = 它那份 bundle patch 整份不再应用
+  （包括里面的"禁用出厂左栏"），界面会**退化成原版 dsh web**（左栏回来、右侧面板消失）。
+  **数据一个都不丢**；把开关拨回来就恢复 —— 进不去设置页就按 `Meta+,`。别当成故障去重建 profile。
+
+## 常见问题
+
+| 症状 | 原因 / 怎么办 |
+| --- | --- |
+| `setup` 报 `scripts/seed-profile.sh: Permission denied` | 0.1.6 的已知缺陷（发出去的包丢了脚本的可执行位）。应急：`chmod +x ~/.npm/_npx/*/node_modules/@dsh-workbench/core/{scripts/seed-profile.sh,bin/opencli-isolated}` 后重跑；0.1.7 起已修 |
+| 页面白屏、只显示 `Failed to load plugins` | 有插件往未声明的槽注册（抛错即整个 entry 激活失败）。看控制台里我们打的 `[dsh-workbench] apply failed` |
+| 面板一直空着 | 多半是没登录 Coding（见上）；或这个工作区的 git `origin` 不指向 `e.coding.net` |
+| 打开面板 / 按刷新要等 5–8 秒 | 正常：opencli 每次调用有**固定约 5 秒**开销（起浏览器会话）。**没有缓存**，数据一律实时 |
+| 体检那屏说「检测浏览器通道 · 没连上」，可面板照样能用 | 本机全局 opencli 与隔离运行时版本不一致，daemon 被顶成对方那版；下一条浏览器命令会自动把它重启回来，体检复检后改回「已连接」 |
+| 一切正常，但左栏是出厂样子、右边没有面板 | 工作台插件在 Settings 里被关了（见上一条 ⚠️） |
+
+排障全表在仓库的 [`docs/OPERATIONS.md`](https://github.com/code-farmer-i/dsh-workbench/blob/main/packages/workbench/docs/OPERATIONS.md)；
+把工作台装到别人机器上的前置清单见 [`docs/HANDOFF.md`](https://github.com/code-farmer-i/dsh-workbench/blob/main/packages/workbench/docs/HANDOFF.md)。
+
+## 从源码跑 / 参与开发
+
+```bash
+git clone git@github.com:code-farmer-i/dsh-workbench.git
+cd dsh-workbench/packages/workbench
+pnpm install
+pnpm run dev     # 监听 src/**（重建产物）+ 起工作台 :3081；改完不用重启、不用刷新页面
+pnpm run check   # 门禁：类型 / 覆盖率 / 架构 / 运行时边界 / 接线自检
+./bin/dsh-workbench   # 只想起工作台、不需要监听改动时用它
+```
 
-**给别人用**（发到内网源、对方的前置条件、Coding 登录）见
-[`docs/HANDOFF.md`](docs/HANDOFF.md)。
+`pnpm run dev` 会先替你把 profile 保障成**本仓这份**（不是源上那份），等首次构建完成再起实例；
+`:3081` 已经有实例在跑时就只监听、不重复起第二个。改界面时开着它就够了：
+浏览器半侧重建 `client.js` 后由 dsh 的 HMR 热换插件（不刷新页面），宿主半侧按模块路径热重载。
 
-## 从这里去哪
+只有两种情况要重启进程：改 `cordis.patch.yml`（组合层）与 `package.json` 的 bundle 清单。
 
-| 触发 | 读 |
-|---|---|
-| 装机、起实例、验收、排障 | [`docs/OPERATIONS.md`](docs/OPERATIONS.md) |
-| 给别人用、发包到内网源、发版 | [`docs/HANDOFF.md`](docs/HANDOFF.md) |
-| 结构、层序、两个运行时、扩展位 | [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) |
-| 该不该做、做成什么形状 | [`DESIGN.md`](../../DESIGN.md) |
-| 术语 | [`CONTEXT.md`](../../CONTEXT.md) |
-| 为什么是这样 | [`docs/adr/`](../../docs/adr/) |
+结构与边界（两个运行时、槽位接线、模块包的门禁）见仓库的
+[`docs/ARCHITECTURE.md`](https://github.com/code-farmer-i/dsh-workbench/blob/main/docs/ARCHITECTURE.md) ·
+[`AGENTS.md`](https://github.com/code-farmer-i/dsh-workbench/blob/main/AGENTS.md)。

package/bin/dsh-workbench

@@ -55,7 +55,13 @@ pkg_version() {
 # profile 写锁、装完把 bundle 登记进 dsh.profile.bundles 全都在里面。
 # 自己拼 pnpm 会漏掉登记，症状是"包装上了但侧边栏不出现"。
 run_setup() {
-  "$REPO_DIR/scripts/seed-profile.sh"
+  # ⚠️ 用 `bash` 呼，不靠文件的 x 位：pnpm publish（release.mjs 走 `pnpm -r publish`）
+  # 只给 `package.json#bin` 点名的那一个文件 755，其余在 tarball 里一律 644
+  # （实测 pnpm pack 的产物：bin/dsh-workbench 是 755，bin/opencli-isolated 与
+  #  scripts/seed-profile.sh 都是 644；npm pack 会保留 x 位，所以这是 pnpm 独有的坑）。
+  # 症状是「本机怎么跑都行、别人机器上 Permission denied」——因为 git 里有 x 位，
+  # 只有装出来的副本会丢。
+  bash "$REPO_DIR/scripts/seed-profile.sh"
 
   if [ -n "$GIT_TOP" ]; then
     SPEC="$REPO_DIR"
@@ -208,7 +214,15 @@ fi
 # 而且从那里跑出来同样是隔离的。指向 profile 里那份，别指 npx 缓存（会回收）。
 OPENCLI_ROOT="$DSH_HOME/workbench/opencli"
 mkdir -p "$OPENCLI_ROOT/bin" "$OPENCLI_ROOT/home"
-ln -sfn "$DSH_WORKBENCH_ROOT/bin/opencli-isolated" "$OPENCLI_ROOT/bin/opencli"
+# 稳定路径不直接软链到随包脚本：同上面那条 —— pnpm publish 之后
+# `bin/opencli-isolated` 是 644，软链过去一执行就是 Permission denied
+# （症状：启动体检永远说"隔离运行时没装好"，而它其实是没权限跑）。
+# 所以这里写一个**我们自己拥有**的转发脚本，x 位由 chmod 当场给。
+# ⚠️ 先 rm -f：旧版本留下的软链还在时，`>` 会顺着软链把真脚本覆盖掉。
+rm -f "$OPENCLI_ROOT/bin/opencli"
+printf '#!/bin/sh\nexec bash %q "$@"\n' "$DSH_WORKBENCH_ROOT/bin/opencli-isolated" \
+  >"$OPENCLI_ROOT/bin/opencli"
+chmod +x "$OPENCLI_ROOT/bin/opencli"
 export DSH_WORKBENCH_OPENCLI="$OPENCLI_ROOT/bin/opencli"
 
 # 软提醒：隔离运行时没装的话，启动体检会**自己装**（沙箱已放行工作台运行时，