Web GUI 增强套件bLueriVerLHR/dsh-better-webui

@blueriverlhr/dsh-better-webui

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

组件索引

| 功能 | 目录 · README | 包 | half |
|---|---|---|---|
| 归档会话管理（查看 / 恢复 / 二次确认彻底删除） | packages/archive | @blueriverlhr/dsh-better-webui-archive | host + client |
| 自定义模型推理等级自动补齐 | packages/reasoning | @blueriverlhr/dsh-better-webui-reasoning | host |
| 会话活动提示音（配置卡挂 dsh 原生「插件配置」页） | packages/chime | @blueriverlhr/dsh-better-webui-chime | host + client |
| 免密钥 Exa 网络搜索 | packages/search | @blueriverlhr/dsh-better-webui-search | host |
| 持久化 bash 卡顿卫士 | packages/bashguard | @blueriverlhr/dsh-better-webui-bashguard | host |
| 可配置重试策略（全局默认，设置卡） | packages/retry | @blueriverlhr/dsh-better-webui-retry | host + client |
| 模型复读探测（代码/标签名不计数；思考也检测，截停循环思考） | packages/repeater-detect | @blueriverlhr/dsh-better-webui-repeater-detect | host + client |
| 模型采样参数控制 | packages/modelparams | @blueriverlhr/dsh-better-webui-modelparams | host + client |
| 会话上下文归档（完成目标前压缩上下文为描述 + 全文链接） | packages/context-archive | @blueriverlhr/dsh-better-webui-context-archive | host + client |
| 基石技能随包（discuss-before-begin / document-ahead-coding，宿主全局注册） | packages/skills | @blueriverlhr/dsh-better-webui-skills | host |
| 队长模式预设（Captain Mode：队长交谈分析+维护文档，实现/合并全委派给子智能体） | packages/captain | @blueriverlhr/dsh-better-webui-captain | host |
| 后台错误 toast（shell.overlay 浮层：本页未打开会话的 agent 失败可见） | packages/toast | @blueriverlhr/dsh-better-webui-toast | host + client |

本 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// 是各功能小包。元包的 dependencies 指向小包，
patch 挂载全部功能行。

整包安装（推荐）

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

"dependencies": { "@blueriverlhr/dsh-better-webui": "" },json
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@blueriverlhr/dsh-better-webui"] } }

本地开发务必用 file: 而不是 link:：pnpm 对 link: 依赖只做软链、不安装
其传递依赖，而 file: 会安装元包声明的各（小）包并把它们平铺进
profiles//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：
json
"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 热加载）

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

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

| 测试 | 覆盖 |
|---|---|
| packages/archive/tests/host.mjs | 归档宿主：真实临时目录 + 模拟注册表，验证彻底删除无残留 |
| packages/archive/tests/smoke.mjs | 归档客户端：jsdom 集成测试（真实 React 18.3.1 + 真实点击） |
| packages/reasoning/tests/reasoning.mjs | 推理等级补齐（模拟 settings 服务，验证幂等补齐/不覆盖/监听） |
| packages/chime/tests/smoke.mjs | 提示音客户端：dock 跳变触发 + 插件配置卡（scope 读写，localStorage 仅迁移） |
| packages/search/tests/web-search-exa.mjs | 免密钥 Exa 搜索 provider（匿名 MCP/429/abort） |
| packages/bashguard/tests/stall-guard.mjs | 卡顿卫士（纯决策逻辑 + tools/execute 接线） |
| packages/retry/tests/host.mjs | 重试策略宿主：规划/应用/幂等/不覆盖手写/read 只返回策略 |
| packages/retry/tests/smoke.mjs | 重试策略卡：四字段 + 应用/恢复默认 RPC + 无 provider 列表 |
| packages/modelparams/tests/host.mjs | 采样参数宿主：RPC/apply/reset + agent/request 会话级固定 |
| packages/modelparams/tests/smoke.mjs | 采样参数客户端：输入框（非滑杆）+ 面板 + 暂不支持标注 + RPC/双语 |
| packages/repeater-detect/tests/detector.mjs | 复读探测检测核心：字符向量 + 元素重叠相似度 + 哈希桶窗口 + 围栏跳过 + 思考内容计数 + 标签剥离 |
| packages/repeater-detect/tests/host.mjs | 复读探测宿主：wrapStream 两段式（软停/硬停）+ 误报通知 + RPC + 迁移 + 配置校验 |
| packages/repeater-detect/tests/smoke.mjs | 复读探测设置卡：开关 + 四字段 + 应用/恢复默认 RPC + 双语 |
| packages/context-archive/tests/host.mjs | 上下文归档宿主：范围选择 / 开关状态 / 归档索引 / 合规事件序列 / RPC / 会话删除连带清除 |
| packages/context-archive/tests/smoke.mjs | 上下文归档客户端：工具行开关一眼可辨状态（开启=品牌色+绿点 / 关闭=灰划线 / 加载中无标记）+ 乐观切换 + RPC 落地 |
| packages/captain/tests/sync.test.js | 队长预设同步：整树替换 + retire 旧 id + 绝不触碰他人 preset |
| packages/captain/tests/leader-guard.test.js | 队长守卫：真实随包预设 round-trip + 逐 JS 语法检查 + depth 规则 + .. 穿越拒绝 |
| packages/toast/tests/host.mjs | toast 宿主：agent/error 缓冲（去重/节流/环形/TTL/游标）+ RPC handler + apply 接线 + 无损 JSON |
| packages/toast/tests/smoke.mjs | toast 客户端：空馈不渲染 + toast 行 + 排除打开会话 + 游标推进 + 同屏上限 + 手动关/自动消失 + 失败轮询静默重试 |
| tests/composition.mjs | patch 组合守卫：提交的 cordis.patch.yml 与各包源一致 |
| tests/client-envelope.mjs | 每个 client 包的加载信封 + 插槽注册（参数化） |
| tests/registry.mjs | 注册表一致守卫：磁盘包集 == FEATURES == 根 deps == run-all 接线 == client-envelope 清单（漏接即失败） |
| tests/snippet-consistency.mjs | 跨包样板片段守卫：where/failure/reportError/unwrap/relativeTime 归一化后形态数锁定（防漂移） |

- 改某个小包的 client half → 刷新浏览器即可；改 host half → 重启 dsh web
- 新功能尽量以子模块（独立小包）形式添加：新建 packages//（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 由构建生成，不要手改（会触发组合测试失败）