前言¶
在 DeepSeek Harness（DSH）里跑长会话时，官方 API 余额往往要进设置页或另开控制台才能看到。余额变化不及时，容易在联调或批量调用时才发现额度不足。社区插件 dsh-deepseek-balance（维护者 taoyiii112-creator）把查询放到后端、把结果固定显示在每个会话顶栏，并附带 Wallpaper Engine 背景与页内桌宠等「趣味换装」类扩展。下面介绍它的定位、能力与安装用法。
这是什么¶
dsh-deepseek-balance 是面向官方 DeepSeek Harness Desktop 的 DSH 插件，当前源码与 manifest 版本为 1.0.1（MIT 许可证）。它通过 Harness 后端安全读取本机保存的 DEEPSEEK_API_KEY，调用 DeepSeek 官方 HTTPS 余额接口，在前端 conversation.session.header.utilities 插槽渲染紧凑的余额胶囊，打开会话即可看到余额，而不必依赖设置页里的单独面板。
在 SkillHub 目录 中，该插件归类为「趣味换装」；核心仍是 API 余额展示与刷新，壁纸与桌宠为同一插件内的可选外观能力。
核心功能¶
余额展示与刷新¶
- 顶栏常驻余额胶囊，支持多币种摘要；鼠标悬停可查看账户状态、充值余额、赠送余额和最近刷新时间。
- 点击可手动刷新；自动刷新间隔可在 30–300 秒 间配置（默认 60 秒）。页面隐藏时暂停轮询，减少无效请求。
- 余额减少时，主胶囊旁用红色小字显示相对上一次成功查询的精确扣款差额；v0.4.5 起使用约 650ms 的双排滚筒动画。首次加载、请求失败、Key 变更、不可用账户或币种结构变化不会误报扣款。
- 刷新失败时，主胶囊只显示失败状态；历史数值在详情中标注为「上次成功余额」。402、服务不可用、空列表或全零等情况统一显示「没有余额」。
- 余额低于用户在齿轮设置中配置的阈值时，胶囊旁才出现指向 DeepSeek 充值页的链接，需用户点击，不会自动跳转。
API Key 与安全边界¶
- 首次使用可点击顶栏「设置余额」，在向导中粘贴 API Key 并保存，不必改环境变量。
- Key 经 DSH 本机凭据存储 保存，不进入浏览器、日志或安装包；后端查询带超时、响应校验与安全错误映射。
桌宠与本地媒体¶
- 提供离线透明待机桌宠：待机视频结束后显示原静态图 15 秒，再重播待机；媒体失败或开启系统「减少动态效果」时回退透明 PNG，不额外发起余额请求。
- 桌宠可拖到视口四边；显示/隐藏与位置保存在浏览器本地。v0.4.7 起可导入透明 PNG/WebP/APNG 或无音轨 VP9 WebM；除内置方案外最多 3 个本地用户方案，每方案 5 个基础槽位并可再加 5 个自定义槽位。
- 自定义场景可从已接入的余额查询、余额变化、桌宠点击、待机与本地时间等事件中选触发规则；不执行用户脚本，也不接入未验证的聊天事件。
Wallpaper Engine 与页面背景¶
- v1.0.1 延续对 Wallpaper Engine Image、Video、Scene、Web、Application 的支持：Image/Video 使用可验证的项目原图或原视频；Scene 优先读
project.json，清单异常且根目录仅有唯一.pkg与 preview 时可受限回退。 - Scene/Web/Application 由 Wallpaper Engine 具名窗口运行，用户在本机 Chrome/Edge 配对页通过系统窗口选择器授权捕获，经本机 WebRTC 显示；捕获请求设置
cursor: 'never'，浏览器仍可能显示系统鼠标。无需修改官方 DeepSeek Desktop。 - 约 560px 宽的可拖动设置面板；Wallpaper 列表、搜索、候选与应用在独立页面操作。页面与面板选用同一精确背景来源时共用一层并保持动态播放；用户选择的 Wallpaper Engine Video 不受 系统「减少动态效果」开关影响（余额滚动、桌宠与本地导入视频会受该开关影响）。
README 注明：Wallpaper 五类尚未逐项实机验收；1.0.1 安装包需用户在 Desktop 插件页自行确认实际运行版本。
安装与启用¶
插件以 Web 客户端平台（client.platform: web）打包，由官方 Desktop 插件管理器安装到独立的 desktop profile，与内嵌共享 Web 应用一致。不要使用 --profile web 装到另一套 profile；CLI 对 --profile desktop 返回的错误属于预期保护，不代表插件不兼容。
在 Desktop 中安装：
- 左侧栏打开「插件」，点击「添加插件」。
- 输入公开仓库地址并安装：
https://github.com/taoyiii112-creator/dsh-deepseek-balance
- 安装完成后选择「立即启用」；若提示重启 Desktop，重启后进入任一会话，确认顶栏已出现余额胶囊。
也可从 GitHub Release v1.0.1 下载安装 ZIP，或下载源码 ZIP 解压后在「添加插件」中选择本地插件目录。更完整的步骤与失败排查见仓库 INSTALL.md 与 v1.0.1 Desktop 兼容说明。
典型用法¶
配置余额¶
点击余额胶囊旁的齿轮 →「余额」→「设置 DeepSeek API Key」，粘贴 Key 并保存。自动刷新在 30–300 秒 范围内调整；余额阈值仅控制是否显示充值链接。
背景与 Wallpaper Engine¶
- 本地 PNG/JPEG/WebP 图片与 MP4/WebM 视频按原文件作背景；图片按内容签名识别，单文件上限 64 MiB、8192×8192 像素（见 v0.5.7 说明）。
- 在设置中选择 Wallpaper Engine 会进入独立壁纸页，可按名称、Workshop ID 和类型筛选本机已下载壁纸。
- 应用 Scene/Web/Application 时，按配对页提示在窗口选择器中选择页面显示的完整 DSH Balance Wallpaper Engine 窗口名称，并点击「开始共享」；Application 类型每次应用还需在设置中确认信任。
适用场景与注意¶
适合谁： 日常在 DSH Desktop 中使用 DeepSeek 官方 API、希望会话内一眼看到余额并在低余额时手动去充值的用户；若本机已安装 Wallpaper Engine 或希望用本地媒体/桌宠定制界面，可在同一插件内配置，而不必另找纯主题插件。
运行与信任： 插件在 当前 DSH 进程权限 下运行，会访问本机凭据、本机 Web 服务（含 Wallpaper 目录探测）以及在用户授权下的屏幕/窗口捕获。安装前应阅读 源码仓库 与 MIT 许可证，自行评估是否满足环境要求。插件依赖 DSH 提供 webServer、credentials、React 客户端模块加载和顶栏插槽；README 记载曾对照 Desktop 0.1.7-rc.2 检查，具体兼容性以你本机 DSH 版本为准。
生态说明： DSH 奉行「一切皆插件」；SkillHub 为社区目录站点，与 DeepSeek / 幻方无官方从属关系，也不是官方应用商店。
结尾¶
经过上面的步骤，你可以在 Harness 会话顶栏常驻看到 DeepSeek 官方 API 余额，并按需打开齿轮统一管理 Key、刷新间隔、阈值、桌宠与壁纸。目录页：taoyiii112-creator/dsh-deepseek-balance；源码与文档：GitHub。
