@blueriverlhr/dsh-better-webui

DeepSeek Harness Web GUI 增强插件 —— monorepo 元包：一个"大包"聚合多个解耦的
功能小包。安装这个包 = 全部功能挂上；每个功能也都可以单独安装
（见 按需安装）。

组件索引

本 README 只是索引；每个功能小包的详细说明（功能细节、实现要点、生效方式）见其
目录下的 README.md。拆分动机与架构见 docs/manual/monorepo.md；
设计裁决记录见 docs/discussion/design.md；开发笔记见
docs/manual/dev-notes.md。docs/ 目录布局约定见
docs/README.md。

设置中心（v0.23）：better-webui 不再自带设置面板承载页（settings 包已删除）。
每个需要配置的插件（chime / retry / repeater-detect）把自己的配置卡挂进 dsh 原生
「设置 → 插件 → 插件配置」页（settings.plugin.item 键控插槽，key = 该插件宿主
已服务的 settings 命名空间）。详见 docs/manual/monorepo.md §4。

安装

本仓库是 monorepo：根目录是元包 @blueriverlhr/dsh-better-webui（无自身代码，
只聚合），packages/<feature>/ 是各功能小包。元包的 dependencies 指向小包，
patch 挂载全部功能行。

整包安装（推荐）

在 dsh 的 profile 里把元包装成 bundle（@deepseek-ai/dsh-web-app 对应的
profile）。以默认 web profile 为例，编辑 ~/.dsh/profiles/web/package.json：

"dependencies": { "@blueriverlhr/dsh-better-webui": "<指向本仓库的路径，或 git/npm 依赖>" },
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@blueriverlhr/dsh-better-webui"] } }

本地开发务必用 file: 而不是 link:：pnpm 对 link: 依赖只做软链、不安装
其传递依赖，而 file: 会安装元包声明的各（小）包并把它们平铺进
profiles/<name>/node_modules（Loader 与 client-modules registry 都从 profile
baseUrl 解析行名）。发布到 npm 后改回版本号依赖即可，pnpm 会自动拉齐小包。
改完在 profile 目录 pnpm install（如无 TTY 加 CI=true --no-frozen-lockfile），
再 dsh web 重启生效。

按需安装（只装部分功能）

元包装齐所有功能；若只想装一部分，把对应小包直接加进 dsh.profile.bundles，
并把它们的依赖（或 file: 路径）写进 profile 的 dependencies：

"dependencies": {
  "@blueriverlhr/dsh-better-webui-chime": "file:/path/to/this/repo/packages/chime",
  "@blueriverlhr/dsh-better-webui-archive": "file:/path/to/this/repo/packages/archive"
},
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@blueriverlhr/dsh-better-webui-chime", "@blueriverlhr/dsh-better-webui-archive"] } }

不要同时安装元包和某个小包：元包的聚合 patch 与单个小包的 patch 会插入
同一个行 id，导致同一插件被挂载两次（通道/插槽重复注册冲突）。装元包或装
小包，二选一。元包的 cordis.patch.yml 是 npm run build 生成的聚合产物，
源在各小包的 cordis.patch.js。

生效方式

• 宿主 half（小包的 host 侧改动）→ 重启 dsh web
• client bundle 改动 → 刷新浏览器即可（webserver stat-poll 热加载）

开发

npm run build   # 构建全部小包的 lib/ + 重新生成全部 cordis.patch.yml
npm test        # 构建 + 运行全部测试（见下）
npm run dsh     # 一键启动隔离的本地 dsh 实例做手工测试（不动全局安装）

本地实例（npm run dsh）：以 DSH_HOME=<repo>/.dsh-home 启动一个私有 dsh web
（默认 http://127.0.0.1:3081），构建 → 把最新产物镜像进该 home 的 profile 安装 →
拉起服务，全程不读写全局 ~/.dsh。首次运行会自动写好 profile 清单并跑一次
pnpm install 装齐基础 bundle；之后每次都直接镜像增量产物，无需重装。常用旗标：

npm run dsh -- --port 3099     # 换端口（默认 3081，避开 3080 的全局 GUI）
npm run dsh -- --reinstall     # 强制重跑一次 pnpm install
npm run dsh -- --skip-build    # 跳过构建，直接用现有 lib/
npm run dsh -- --sync-only     # 只构建 + 镜像安装，不启动服务

测试（每个都是独立 node 脚本，tests/run-all.mjs 依次执行；各小包的测试见
packages/<feature>/tests/）：

• 改某个小包的 client half → 刷新浏览器即可；改 host half → 重启 dsh web
• 新功能尽量以子模块（独立小包）形式添加：新建 packages/<name>/（package.json +
  src + cordis.patch.js + tests），在 scripts/compose-patch.mjs 的 FEATURES 加名字，
  然后 npm run build。不要把新功能塞进现有小包的 apply()。详见
  docs/manual/monorepo.md §7 维护规则。
• 提交前跑 npm test；cordis.patch.yml 由构建生成，不要手改（会触发组合测试失败）