@blueriverlhr/dsh-better-webui

Readme

# @blueriverlhr/dsh-better-webui

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

## 组件索引

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

> 本 README 只是索引；每个功能小包的详细说明（功能细节、实现要点、生效方式）见其
> 目录下的 `README.md`。拆分动机与架构见 [docs/manual/monorepo.md](docs/manual/monorepo.md)；
> 设计裁决记录见 [docs/discussion/design.md](docs/discussion/design.md)；开发笔记见
> [docs/manual/dev-notes.md](docs/manual/dev-notes.md)。docs/ 目录布局约定见
> [docs/README.md](docs/README.md)。
>
> **设置中心（v0.23）**：better-webui 不再自带设置面板承载页（`settings` 包已删除）。
> 每个需要配置的插件（chime / retry / repeater-detect）把自己的配置卡挂进 **dsh 原生
> 「设置 → 插件 → 插件配置」页**（`settings.plugin.item` 键控插槽，key = 该插件宿主
> 已服务的 settings 命名空间）。详见 [docs/manual/monorepo.md](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`：

```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`：

```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=<repo>/.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/<feature>/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/<name>/`（package.json +
  src + cordis.patch.js + tests），在 `scripts/compose-patch.mjs` 的 `FEATURES` 加名字，
  然后 `npm run build`。不要把新功能塞进现有小包的 `apply()`。详见
  [docs/manual/monorepo.md](docs/manual/monorepo.md) §7 维护规则。
- 提交前跑 `npm test`；`cordis.patch.yml` 由构建生成，不要手改（会触发组合测试失败）