皮肤与用量面板 Smith-yue/harness-plugin

dsh-skin-token-dashboard

面向 DeepSeek Harness Desktop/Web 的 TypeScript 插件工程，提供：

- 两套可切换桌面皮肤：深海夜航（暗色）与暖纸日光（亮色）。
- 五套随包发布的内置摄影背景，以及可递归读取子文件夹的本地图片轮播。
- 可展示扫描到的子文件夹，并将轮播范围限制为全部目录、仅根目录或指定子文件夹（包含其更深层目录）。
- 可设置轮播分钟间隔、暂停/继续和立即切换下一张；优先使用 Electron 兼容目录输入，通过相对路径递归遍历。
- 保留两套完整皮肤，另支持自定义 CSS 背景色、图片透明度和背景色/渐变覆盖透明度。
- “设置 → 通用”中的皮肤与背景选择器，可即时切换；皮肤、颜色、透明度、文件夹、子目录范围、当前图片和轮播参数在重启后自动恢复。
- “设置 → Token 用量”详细面板，实时展示当前会话的总量、计费输入、输出、缓存命中率及四类 Token 构成。
- 基于官方 tokenUsage 会话投影的 Token 汇总读取 API。
- 同时保留 Harness 原生聊天统计条；不复制消息内容，不另建统计数据库。

为什么复用官方 Token 统计

标准 DeepSeek Harness base profile 已装载 @deepseek-ai/dsh-token-meter。它从持久会话日志回放并去重，能覆盖普通请求、失败请求、分页历史和上下文压缩。插件只读取其最终投影：

- uncachedInputTokens：未命中缓存的输入。
- cacheReadTokens：缓存读取。
- cacheWriteTokens：缓存写入。
- outputTokens：输出，已经包含 reasoning token，不能重复相加。
- billedInputTokens：前三个输入桶之和。
- totalTokens：计费输入加输出。

安装

要求 Node.js ^22.19.0 || >=24.0.0。把已发布版本安装到标准 Web profile：

npx -y @deepseek-ai/dsh plugin --profile web add dsh-skin-token-dashboard

安装完成后重启 Harness。使用 DSH Desktop 插件市场时，也可以搜索 dsh-skin-token-dashboard 并安装到 Web profile。

从源码开发

Windows 使用 nvm 时先安装并切换版本：

nvm install 22.19.0
nvm use 22.19.0
node --version

安装依赖并验证工程：

npm install
npm run check

安装到官方 DSH Desktop：

npm run install:desktop

官方 DSH Desktop 会设置独立的 DSH_HOME，Windows 默认位于 %APPDATA%\dsh-desktop\harness，并以 web profile 加桌面补丁启动。install:desktop 会自动定位这个目录，不会误装到 %USERPROFILE%\.dsh。

若某个自定义发行版明确使用标准 DSH_HOME 下名为 desktop 的 profile，可执行：

npm run install:profile-desktop

安装脚本按以下顺序寻找 CLI：

1. PATH 中已有的 dsh。
2. 本机 DSH Desktop 自带的官方 CLI。
3. 最后才通过 npx 下载 CLI。

安装桌面端时，脚本会优先使用 DSH_HOME\.desktop-bin 中由桌面端提供的 pnpm shim，避免系统 pnpm 与桌面端 store 版本不一致。标准 profile 安装才会在需要时通过 corepack 准备 pnpm。

安装成功后完全退出并重新打开 DSH Desktop，再进入“设置 → 通用 → 桌面皮肤”切换主题或 Harness 背景。插件在 Host 端注册 skin-token-dashboard 设置命名空间，皮肤 ID、内置背景、背景颜色、两个透明度、本地文件夹路径、轮播间隔、播放状态、子目录筛选和当前图片相对路径都会写入 $DSH_HOME/settings.yaml；升级后的首次启动会把已有浏览器本地设置迁移到该分节。旧版本通过浏览器临时文件输入选择的目录没有可迁移的绝对路径，升级后需重新选择一次，此后 DSH Desktop 重启会由 Host 自动恢复并重新扫描。插件递归查找所选目录及子目录中的 AVIF、BMP、GIF、JPEG、PNG 和 WebP 图片（最多 2000 张），按相对路径自然排序；可设置 1–1440 分钟的切换间隔，也可暂停或点击“下一张”立即切换。图片切换使用 900ms 交叉淡入，并遵循系统“减少动态效果”设置。背景图片透明度与背景色/渐变覆盖透明度可分别调节，并可叠加皮肤原色或自定义 CSS 背景色；也可以随时恢复纯色背景。“设置 → Token 用量”会展示当前会话的详细汇总；Harness 原生统计条仍位于聊天输入框下方。

不同桌面发行版可能把插件安装入口封装在图形界面中。此时选择本目录，或先 npm pack 后安装生成的包即可。

Host API

插件注册 ctx.skinTokenUsage 服务：

const usage = ctx.skinTokenUsage.read(session)

if (usage) {
console.log(usage.billedInputTokens)
console.log(usage.outputTokens)
console.log(usage.totalTokens)
console.log(usage.cacheHitRate)
}

read() 是同步一致性读取，只返回汇总计数，不返回 prompt、response 或工具内容。

常用命令

npm run typecheck # TypeScript 静态检查
npm test # Vitest 单元测试
npm run build # 生成 Host ESM 与 Client bundle
npm run check # 类型检查 + 测试 + 构建
npm run install:desktop # 安装到官方 DSH Desktop 使用的 web profile
npm run install:profile-desktop # 安装到显式命名的 desktop profile

常见安装错误

无法将“dsh”识别为 cmdlet

这是 CLI 没有全局安装或不在 PATH，不是插件构建失败。请执行 npm run install:desktop；脚本会自动寻找 DSH Desktop 内置 CLI。

执行后只有旋转光标

旧脚本使用 npx 临时解析完整 DSH 依赖树，首次运行可能长时间没有输出。新版安装脚本优先使用桌面端内置 CLI，不再走这条慢路径。

安装成功但桌面端看不到

确认安装输出中包含 DSH Desktop home：...\AppData\Roaming\dsh-desktop\harness。若显示 .dsh\profiles，说明装到了标准 CLI profile，请重新执行 npm run install:desktop。安装完成后需完全退出并重新打开 DSH Desktop。

Unsupported engine / Node 版本不满足

执行 node --version。本项目与当前 Harness 要求 Node.js ^22.19.0 || >=24.0.0；例如 v22.4.0 不满足要求，需要先升级。

文档

- 工程结构
- 架构与数据流
- 开发、调试与发布

兼容性说明

本工程按 DeepSeek Harness 0.1.x 当前公开契约实现：

- 插件模块导出 apply(ctx)。
- npm 清单用 dsh.bundle.patch 激活配置层。
- 浏览器半部由 dsh.client 与 ./client 导出加载。
- 主题通过 ctx.theme.register() 注册，只覆盖 --dsw-* 语义 Token。
- Token 数据读取官方 sessionProjections.snapshot(session).values.tokenUsage。

如果未来 Harness 修改预发布 API，优先更新 peer dependency 范围和 src/index.ts 的投影适配层，皮肤定义本身通常无需修改。

隐私

插件不发起外部网络请求，不保存会话内容。皮肤偏好与用户明确选择的本地背景文件夹路径通过 DSH 官方 Settings API 写入本机 $DSH_HOME/settings.yaml 的 skin-token-dashboard 分节；图片内容不会复制到设置或数据库中。Host 文件读取 RPC 仅接受本机回环连接，只读取已由原生选择器授权并保存的目录，拒绝路径越界和符号链接穿透；Token 统计来自本机 Harness 已有的持久会话投影。