dsh-toolkit

Readme

# 🧰 dsh-toolkit — DeepSeek Harness 实用工具箱

[English](README.en.md) | 简体中文

一组**纯增量**的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 原生插件合集：**便签**、**API 余额与费用**、**推理等级**、**删除会话**、**对话节点导航条**、**轻拟物皮肤**。

六个插件遵循同一原则：**不改动 Harness 核心**——全部通过官方插槽（slot）与独立 API 路由注入（`dsh-session-nav` 为纯客户端插件，只读官方 DOM 契约，无宿主路由），卸载即完全还原。全部插件严格按官方插件规则实现：bundle manifest（`dsh.bundle.patch`）+ 客户端清单（`dsh.client`）、官方 Cordis 插件形态（`name/inject/apply` + `ctx.effect` 生命周期）、官方客户端模块形态（`__ModuleLoader__` + `exports.inject/apply`）、官方插槽；宿主可调参数全部经 Schemastery `Config` 配置（profile 的 `cordis.yml`），详见各插件 README 的「配置（Config）」章节。

## 插件一览

| 插件 | 功能 | 界面位置 |
| --- | --- | --- |
| :memo: **dsh-note** | 原生便签：新建 / 历史 / 拖拽窗口 / 历史条目双击编辑自动保存 | 输入框工具行（Full access 选择器右侧） |
| :moneybag: **dsh-api-balance** | API 余额 + 本轮费用 + 今日消耗（¥ / token，峰谷计价，官方路由合并统计） | 会话头部操作行 + 每条回复操作行 |
| :brain: **dsh-reasoning-levels** | 第三方模型五档推理等级（low / medium / high / xhigh / max） | 官方模型选择器 |
| :wastebasket: **dsh-session-delete** | 「删除会话」，彻底清理会话数据 | 会话列表 ⋮ 菜单 |
| :dna: **dsh-session-nav** | 对话节点导航条：每条提问一轮次一短横条，悬停预览 / 单击跳转并置顶 / 双击钉住 | 文字列与滚动条之间（右缘常驻） |
| :art: **dsh-softui-skin** | 轻拟物（Soft-UI）皮肤：系统原生开关，浅色/深色跟随系统原生外观，状态持久化（[修改自 Lhy723/dsh-neu-theme](https://github.com/Lhy723/dsh-neu-theme)） | 设置 → 通用设置 → 外观 |

## 界面预览

![插件界面预览](docs/screenshots/screenshot-toolkit.jpg)

### :memo: dsh-note — 原生便签

- 输入框工具行一个与周边图标同款的小圆钮（28×28，随主题自动变色）
- 打开即**新建便签**，点击「保存」归档进历史（上限 30 条）；关闭时未保存内容自动存**草稿**防丢
- 「历史便签」弹出**独立窗口**：可自由拖拽、缩放，并**记住最近一次的位置和大小**；条目点击展开显示**复制**按钮，可单独删除
- **历史条目双击即可编辑**：展开内容后双击进入行内编辑，停止输入约 0.6 秒自动保存（显示「已自动保存」），不改变条目位置、不会丢字；编辑中按 ESC 结束
- 文本上限 16,000 字符；数据落盘 `$DSH_HOME/storages/dsh-note.json`（原子写入、并发写串行化）

### :moneybag: dsh-api-balance — API 余额与费用

- **余额徽章**：会话头部操作行。显示当前模型所属供应商的余额——DeepSeek 官方余额接口（**高峰 / 闲时**按北京时间自动标注，与官网峰谷窗口对齐：周一至周五 9:00–12:00、14:00–18:00 高峰，周末全天闲时）、第三方余额接口或本地记账（总金额 − 已扣）
- **供应商管理**：双击徽章打开「模型计费管理」——可配置多个供应商、每个供应商挂多个模型并共用同一余额池；第三方模型可设置独立的输入 / 输出 / 缓存读 / 缓存写费率
- **本轮费用**：每条 assistant 回复旁显示 `本轮 ¥x.xxxx`，按官方峰谷价或自定义费率精确计价；悬停显示**缓存命中率**与消耗 token（K/M tok）
- **今日消耗**：悬停徽章显示**当日（北京时间）当前供应商的全部消耗**——DeepSeek 官方路由与其派生通道（如 vision-toolkit）合并为同一供应商统计，与官网用量页数字一致；第三方供应商各自独立、切换时联动
- **切换联动**：切换会话或切换供应商模型时，徽章立即切换为该供应商的余额；同供应商内切换模型则保持不变
- API Key 复用 Harness 凭据服务（`~/.dsh/.credentials.yaml` 的 `DEEPSEEK_API_KEY`），**Key 不进入浏览器**

### :brain: dsh-reasoning-levels — 第三方模型推理等级

- 为第三方模型（pi-ai 供应商）在**官方模型选择器**中提供五档推理等级：**low / medium / high / xhigh / max**；支持五档的模型默认档位为 **Max**（选中即高亮，未手动选择时按 Max 发送）
- 启动时自动为未声明的第三方模型写入五档声明（幂等）；同一供应商内可**混排**支持与不支持档位的模型——`reasoningEfforts: false` 的模型不显示档位、请求不带档位参数、保持供应商默认
- 官方模型保持官方三档（low / high / max），永不触碰
- 附带宿主接口 `getSessionModel` / `setReasoning` / `setModel` / `levels`（模型选择、档位诊断与切换）

### :wastebasket: dsh-session-delete — 删除会话

- 会话列表 ⋮ 菜单新增「删除会话」，**彻底删除**：JSONL 会话日志、工作区登记、归档集合全部清理
- 拒绝删除**运行中**的会话（先停止/关闭再重试）；会话 ID 严格校验，目录路径与核心编码逐字符一致，删除范围精确限定在存储根内（含符号链接防护）
- 删除前弹窗确认并展示会话 ID；重名会话拒绝猜测，避免误删

### :dna: dsh-session-nav — 对话节点导航条

- 会话窗口内、**文字列与滚动条之间**的右缘节点串：**每条 user 提问一轮次一短横条**（9×3 全圆角胶囊，深色模式白色、浅色模式黑色，随主题），**最多同时显示 6 条**，超出部分在节点串上**滚轮链条式翻看**
- **悬停**：短横条平滑加长 + 弹出预览卡（该轮**全部内容**，超高内部滚动）；**单击**：平滑跳转到该轮 + **置顶框**显示该轮全部内容；**双击**：**钉住/取消钉住**（仅高亮、无蓝点，**个数不限**，localStorage 持久化）；激活条（DeepSeek 蓝）跟随阅读位置并自动滚入可视区
- **常驻跟随会话**：切换会话自动显示该会话轮次数；未压缩内容立即显示，压缩历史**后台缓慢预载**（每 2.8s 一页，空闲才点、绝不堆积），点击未加载轮次时按需快速补页
- **置顶框**：磨砂透明玻璃（`blur(24px)` + 主题底色 40%），宽度 = 文字列宽 + **左右各加长 2.5cm**，高度随内容伸展（上限 70vh），滚动时保持磨砂
- 纯客户端插件：只读官方 DOM 契约（`data-chat-flow` / `data-conversation-scroll` 等）+ `sessions` 服务，**无宿主 API 路由、不修改任何核心状态**，卸载完全还原

### :art: dsh-softui-skin — 轻拟物皮肤

> **修改自 [Lhy723/dsh-neu-theme](https://github.com/Lhy723/dsh-neu-theme)（MIT）**：皮肤样式与配色沿用原项目，本插件将其三选一选择器改为**系统原生开关**，并做了健壮性修复。

- **系统原生开关**位于 **设置 → 通用设置 → 外观**（内置「外观」行正下方），与 Harness 设计令牌一致（`role="switch"`，浅/深色主题下自动适配）
- **打开开关**：启用轻拟物皮肤，**浅色（奶油暖白）/ 深色（墨蓝夜）跟随系统原生外观**——原生为深色即皮肤深色；原生「跟随系统」时操作系统切换深浅色，皮肤自动跟随
- **关闭开关**：页面与 Harness 原生完全一致——不注入样式、不打 body 标记、不残留任何令牌覆盖
- **持久化**：开关状态存于 localStorage（`dsh-softui:enabled`，旧键自动迁移并清理），刷新、关闭浏览器、重启 dsh 都不会还原回原生外观
- **不碰 Harness 核心**：颜色通过内置 ThemeRuntime `overrideTokens()` 叠加为令牌覆盖层（不写入 `ui-theme` 偏好、不修改 `settings.yaml`）；阴影/磨砂/噪点为插件自有 `<style>`，以 `body[data-dsh-softui]` 为作用域；多标签页 `storage` 事件同步；构建期校验全部 103 个主题令牌

## 仓库结构

```
dsh-toolkit/
├── packages/
│   ├── dsh-note/                # 便签插件
│   ├── dsh-api-balance/         # 余额与费用插件
│   ├── dsh-reasoning-levels/    # 第三方模型推理等级插件
│   ├── dsh-session-delete/      # 删除会话插件
│   ├── dsh-session-nav/         # 对话节点导航条插件
│   └── dsh-softui-skin/         # 轻拟物皮肤插件
├── pnpm-workspace.yaml          # pnpm monorepo 聚合
└── README.md
```

六个包相互独立：可**单独安装、单独更新、单独卸载**，互不依赖。仓库根本身也是一个可安装的 **bundle**（`dsh.bundle` 声明），可一键装齐全部六个插件。

## 安装

要求：DeepSeek Harness v0.1.0-rc.7+（Web 界面，Windows 实测）；pnpm ≥ 9（支持 git 子目录语法）。

**方式一（推荐）：一键安装全家桶**——仓库根 `package.json` 已声明 `dsh.bundle`，整个仓库就是一个可安装的插件包：

```bash
# 直接从 GitHub 安装（无需 clone）
dsh plugin --profile web add "github:Vast-Unhurried/dsh-toolkit"

# 或 clone 后本地安装（在仓库根目录执行）
git clone https://github.com/Vast-Unhurried/dsh-toolkit.git
cd dsh-toolkit
dsh plugin --profile web add file:.
```

装齐 6 个插件后，`dsh.profile.bundles` 中会出现一个 `dsh-toolkit` 层（内含 6 行插件装配）。**装了全家桶就不要再单独装子包**，避免同一插件的行重复装配。

**方式二：按需单独安装**

```bash
# 直接从 GitHub 安装（无需 clone）
dsh plugin --profile web add "github:Vast-Unhurried/dsh-toolkit#path:packages/dsh-session-nav"
dsh plugin --profile web add "github:Vast-Unhurried/dsh-toolkit#path:packages/dsh-note"
dsh plugin --profile web add "github:Vast-Unhurried/dsh-toolkit#path:packages/dsh-api-balance"
dsh plugin --profile web add "github:Vast-Unhurried/dsh-toolkit#path:packages/dsh-reasoning-levels"
dsh plugin --profile web add "github:Vast-Unhurried/dsh-toolkit#path:packages/dsh-session-delete"
dsh plugin --profile web add "github:Vast-Unhurried/dsh-toolkit#path:packages/dsh-softui-skin"

# 或 clone 后本地安装（在仓库根目录执行）
git clone https://github.com/Vast-Unhurried/dsh-toolkit.git
cd dsh-toolkit

# 2. 安装插件（可只装需要的）
dsh plugin --profile web add file:./packages/dsh-note
dsh plugin --profile web add file:./packages/dsh-api-balance
dsh plugin --profile web add file:./packages/dsh-reasoning-levels
dsh plugin --profile web add file:./packages/dsh-session-delete
dsh plugin --profile web add file:./packages/dsh-session-nav
dsh plugin --profile web add file:./packages/dsh-softui-skin
```

> `--profile web` 按你的实际 profile 名调整；`file:` 支持相对路径，从仓库根目录执行即可。

安装后需**重启 dsh 服务**（宿主路由 + 客户端 bundle 都需要重新加载），浏览器 **Ctrl+Shift+R** 硬刷新。

## 卸载

```bash
# 全家桶安装的：一次移除整个 bundle
dsh plugin --profile web remove dsh-toolkit

# 单独安装的：逐个移除
dsh plugin --profile web remove dsh-note
dsh plugin --profile web remove dsh-api-balance
dsh plugin --profile web remove dsh-reasoning-levels
dsh plugin --profile web remove dsh-session-delete
dsh plugin --profile web remove dsh-session-nav
dsh plugin --profile web remove dsh-softui-skin
```

卸载即完全还原。便签数据文件（`$DSH_HOME/storages/dsh-note.json`）默认保留，如需彻底清除手动删除该文件；`dsh-reasoning-levels` 卸载后可按需清理 `settings.yaml` 中 `llm-pi-ai` 下插件写入的 `reasoningEfforts` / `reasoning` / `compat.supportsReasoningEffort` 字段。

## 兼容性与安全边界

- 客户端只读官方插槽：`conversation.input.left`、`conversation.session.header.actions`、`conversation.chat.assistant-actions`、`settings.general.item` 等（`dsh-session-nav` 为纯客户端，只读 DOM 契约与 `sessions` 服务，不挂任何插槽；`dsh-softui-skin` 为纯客户端，只读 `settings.general.item` 插槽与主题服务，不挂任何宿主路由）
- 宿主侧仅新增独立 API 路由（`/plugins/dsh-note/api`、`/plugins/api-balance/api`、`/plugins/reasoning-levels/api`、`/plugins/session-delete/api`），不修改、不订阅任何核心状态
- 所有 API 路由做同源校验（要求 Host 为回环地址且 Origin 与 Host 精确一致），拒绝跨站与 DNS rebinding 请求
- 不收集任何遥测；不读取凭据以外的敏感信息；不向第三方发送数据

## License

[MIT](./LICENSE)