@sugan01/dsh-web-ui-balance

English | 中文

DeepSeek Harness Web 的账户余额插件。在侧边栏「设置」按钮右侧显示 DeepSeek 账户余额徽标，并在设置页提供「自动查询」「刷新频率」「显示位置」配置。

不需要单独填写 Key：插件直接复用 DSH 已配置的 DEEPSEEK_API_KEY。插件不做任何写操作。

功能

• 侧边栏「设置」按钮右侧的余额徽标：状态点 + 余额 ¥xx，悬停显示赠送/充值明细
• 按配置的频率自动刷新（默认 300 秒），也可在设置页手动「立即刷新」
• 设置页「DeepSeek 余额」分区：自动查询开关、刷新频率（秒）、显示位置（上方/右侧）
• 配置保存在浏览器 localStorage，重启 DSH 后保留
• 界面文案跟随 DSH 界面语言（中文 / English）
• 侧边栏收起为窄栏时，徽标自动切换为「上方」紧凑布局

效果展示

安装

前置条件：已安装 DeepSeek Harness（Web profile），且已配置 DEEPSEEK_API_KEY（~/.dsh/.credentials.yaml 或环境变量）。

npm 安装（推荐）

dsh plugin --profile web add @sugan01/dsh-web-ui-balance

若 dsh 不在 PATH（例如从源码启动 Harness），使用 pnpm dsh plugin --profile web add ...。

本地文件夹 / tarball

dsh plugin --profile web add file:/path/to/dsh-web-ui-balance
dsh plugin --profile web add file:/path/to/dsh-web-ui-balance-0.1.3.tgz

安装后需要重启 DSH 进程。升级版本时建议带精确版本号（如 @0.1.3），避免 pnpm 复用旧版缓存。

使用

1. 重启 DSH 后打开 Web 界面，侧边栏「设置」按钮右侧出现余额徽标。
2. 悬停徽标查看赠送/充值明细。
3. 在设置 →「DeepSeek 余额」中调整自动查询、刷新频率与显示位置。

配置与持久化

| 配置 | 说明 | 默认 | |---|---|---| | 自动查询 | 关闭后不再自动刷新余额 | 开 | | 刷新频率 | 自动刷新间隔（秒） | 300 | | 显示位置 | 徽标布局：右侧 / 上方 | 右侧 |

配置保存在浏览器 localStorage，按浏览器记忆：正常关闭标签页、重启 DSH 都会保留；清空站点数据、更换浏览器或机器后会回到默认值。

安全说明

• Key 不离开宿主进程：DEEPSEEK_API_KEY 仅在 DSH 宿主进程内通过凭据服务读取，唯一去向是 Authorization: Bearer <key> 请求 DeepSeek 官方接口 https://api.deepseek.com/user/balance（HTTPS，URL 固定）。
• 浏览器永远看不到 Key：宿主只返回余额数字（isAvailable 与 balances[]），响应带 Cache-Control: no-store；客户端 localStorage 只保存上述三个配置项。
• 不写日志：错误信息只包含 HTTP 状态码或网络错误文案，不包含 Key。
• 跨域站点读不到：DSH Web 服务器不发送 CORS 头，第三方网页发起的请求会被浏览器拦截读取响应。
• 请保持 127.0.0.1 绑定：本插件未加 Origin 校验（有意为之，依赖本地绑定保证安全）。若以 --host 0.0.0.0 暴露到局域网，局域网内任何设备都能查到余额数字（仍拿不到 Key）。

与其他 UI 插件的兼容性

本插件只注册进 DSH 宿主已声明的列表槽（list kind），从不重新声明槽位，也不注册 root，因此与绝大多数 UI 插件共存：

| 槽位 | 注册 id | order | 说明 | |---|---|---|---| | sidebar.footer.action | deepseek-balance | 0 | 侧边栏底部动作区（设置按钮右侧） | | settings.section | deepseek-balance | 30 | 设置页分区列表 |

DSH 的 slot 系统规则：

1. 列表槽是累加式的：多个插件向同一槽位注册的条目全部渲染，按 order 升序排列（数值小靠前）。其他插件向 sidebar.footer.action 或 settings.section 添加自己的按钮/分区时，与本插件并排共存，不会覆盖。DSH 自带的通用、模型、插件等设置分区就是多插件共存于 settings.section 的实例。
2. 冲突情况一（注册 id 相同）：同一槽位内出现相同注册 id 且相同 priority 会加载报错。本插件使用的 id deepseek-balance 全局唯一。
3. 冲突情况二（重复声明）：任何插件重新声明已被声明的槽位（sidebar.footer.action、settings.section、root 等）会加载报错。
4. root 是单槽：向 root 注册会把整个界面顶掉（动态注册的条目优先级更高会胜出）。本插件从不注册 root。任何"全屏替换"型插件都会与所有基于 slot 的插件互斥，这是该类插件的设计选择。
5. 样式隔离：CSS Modules 类名带构建哈希，样式按 <style data-plugin> 注入/卸载，跨插件类名冲突基本不可能。

结论：与"向界面添加内容"的插件（按钮、徽标、分区、面板）无冲突；与"换肤"类插件（只改 CSS 变量/主题 token）无冲突；与"抢占"型插件（注册 root、重写容器、重新声明槽位）冲突由抢占方引起，无法共存。

工作原理

• 宿主半：通过 webServer 注册 GET /api/deepseek-balance。查询时用进程内 fetch 直接请求官方余额接口（不经过 shell 子进程，Windows/Linux 行为一致，20 秒超时），响应归一化为 { ok, data: { isAvailable, balances: [...] } }。
• 浏览器半：用 fetch('/api/deepseek-balance') 拉取并渲染，不依赖 @Remote（这是它可作为第三方 bundle 一条命令安装的前提）。
• 版本说明：0.1.2 起改为进程内 fetch（修复 Linux 上的 PowerShell 语法错误）；0.1.3 起配置持久化到 localStorage。

常见问题

• 查询报 bash: syntax error near unexpected token '('：版本低于 0.1.2（旧版使用 PowerShell 子进程，Linux 不兼容）。请升级到 0.1.2 或更高。
• 重启后设置恢复默认：确认安装版本为 0.1.3 或更高（旧版配置只存内存）。若已是 0.1.3 仍丢失，通常是更换了浏览器、使用无痕模式或清除了站点数据（localStorage 按浏览器记忆）。
• 提示「未检测到 DEEPSEEK_API_KEY」：在 DSH 中配置 DEEPSEEK_API_KEY 后重启。

License

MIT