dsh-deepseek-quota
> DeepSeek Harness Web 侧边栏的 DeepSeek API 剩余额度卡片 + 充值面板 插件。
> 实时展示官方余额（总余额 / 充值构成 / 赠送余额 / 期间已用 / 更新时间），每 60 秒自动刷新；
> 卡片内提供「充值」入口，弹出居中充值面板（金额档位与支付方式与 DeepSeek 官网一致），
> 扫码打开官方充值页完成支付。数据来自 DeepSeek 官方 /user/balance 接口，API Key 全程不出 Host 进程。
目录
功能特性
| # | 能力 | 实现 |
|---|---|---|
| 1 | 实时余额展示 | 对接 DeepSeek 官方 GET /user/balance，展示总余额、充值/赠送构成、期间已用、更新时间 |
| 2 | 自动刷新 | 每 60 秒自动刷新 + 手动刷新按钮；刷新失败保留旧值（stale-while-error） |
| 3 | 低余额警示 | 余额 ≤ 0 时主数字变红；侧边栏收起态显示 ! |
| 4 | 充值入口 | 卡片头部「充值」按钮 → 居中充值面板（金额档位/支付方式与官网一致） |
| 5 | 官方支付二维码 | 面板生成官方充值页二维码（https://platform.deepseek.com/top_up）供扫码支付 |
| 6 | 密钥安全 | API Key 只在 Host 进程内使用，浏览器侧经同源路由取数，Key 不落浏览器 |
| 7 | 视觉一致 | 复用侧边栏「设置」同源设计令牌（字体/颜色/间距/圆角/悬停态），宽度像素级对齐 |
| 8 | 宽/窄自适应 | 侧边栏展开显示完整卡片，收起退化为 32px 圆形按钮，点击展开侧边栏 |
适用平台
| 项 | 要求 |
|---|---|
| 宿主 | DeepSeek Harness Web（桌面端 / Web profile） |
| 运行环境 | Node 18+（DSH 内嵌 Node 或系统 Node 均可） |
| 操作系统 | Windows（Git Bash / WSL）/ macOS / Linux |
| 数据源 | DeepSeek 官方 GET /user/balance（需有效 DEEPSEEK_API_KEY） |
安装
方式 A：一键安装（推荐）
git clone https://github.com/cn-scuo-oo/dsh-deepseek-quota.git
cd dsh-deepseek-quota
bash install.sh
脚本自动完成：检测 DSH profile 与 Node 版本（缺失给出修复指引）→ 复制插件文件到
~/.dsh/profiles/web/vendor/dsh-deepseek-quota/ → 更新 profile package.json
（dependencies + bundles 声明）→ 建立 node_modules 符号链接。
安装完成后 重启 DeepSeek Harness（或页面按 Cmd+R 刷新），侧边栏底部「设置」上方即出现额度卡片。
> 自定义 profile 名 / 卸载：
> bash
> bash install.sh --profile myprofile # 安装到指定 profile
> bash install.sh --uninstall # 卸载（移除文件、声明与符号链接）
>
方式 B：手动安装（等价）
- 把
lib/、package.json、cordis.patch.yml复制到~/.dsh/profiles/web/vendor/dsh-deepseek-quota/； - 编辑
~/.dsh/profiles/web/package.json：
-dependencies增加"dsh-deepseek-quota": "file:./vendor/dsh-deepseek-quota"；
-dsh.profile.bundles追加"dsh-deepseek-quota"； - 建立符号链接：
ln -s "$PWD/vendor/dsh-deepseek-quota" ~/.dsh/profiles/web/node_modules/dsh-deepseek-quota； - 重启 DSH。
配置 API Key
无需编辑任何配置文件。在 DSH 应用内：
> 设置 → 模型 → 填入 DEEPSEEK_API_KEY（与调用 DeepSeek 模型的 Key 是同一把）
插件经 DSH 的凭据服务（~/.dsh/.credentials.yaml）读取，Key 只在 Host 进程内使用，
通过同源只读路由 GET /dsh-quota/balance 把归一化后的余额数据交给浏览器，
API Key 永远不进入浏览器 / 前端代码 / 命令字符串。
> 高级：可用环境变量 DEEPSEEK_BASE_URL 覆盖官方接口地址（联调本地 Mock / 公司代理）。
使用指南
- 查看额度：侧边栏底部「DeepSeek 额度」卡片显示
¥余额大字 + 「充值 X · 赠送 Y」+ 「更新于 HH:MM:SS」； - 刷新：点击卡片右上角刷新图标立即取数（加载中图标旋转）；
- 充值：点击卡片头部「充值」按钮 → 弹出居中面板：
- 选择金额（¥10/20/50/100/300/500 或自定义，美元账户自动切换 $ 档位）；
- 选择支付方式（支付宝 / 微信 / 银行卡，与官网一致）；
- 点击「去支付」→ 中央展示官方充值页二维码 + 金额/方式摘要；
- 手机扫码打开 DeepSeek 官方充值页完成支付，或点「在浏览器中打开官方充值页」直达； - 充值到账后：回到侧边栏点击刷新图标（或等 60 秒自动刷新）即可看到最新余额。
充值说明（重要）
如实说明：DeepSeek 没有公开的「按订单生成支付二维码」API，官方充值页也禁止内嵌
（content-security-policy: frame-ancestors 'none'）。真正的按订单官方支付码只能在登录
平台后于官网生成。因此本插件面板展示的是官方充值入口二维码——即官网自己复制的
「充值链接」同一个地址（https://platform.deepseek.com/top_up）：
- 扫码后在手机端打开本人账号的官方充值页，按面板已选金额与支付方式完成支付；
- 面板提供金额/方式摘要与提示文案，避免误扫错金额；
- 支付完成后回到应用点击刷新，官方
GET /user/balance立即返回最新余额。
> 安全合规：本插件只对接 DeepSeek 官方公开 API 与官方充值页，不涉及任何爬虫、
> 绕过官方计费或代收资金逻辑。
演示截图
> 截图来自真实运行实例（开发验证环境）。
| 侧边栏额度卡片（展开态） | 卡片区域放大 | 侧边栏底部（充值入口 + 设置对齐） |
|---|---|---|
| 充值面板（金额档位 + 支付方式） | 二维码视图（扫码支付，二维码已打码） |
|---|---|
项目结构
dsh-deepseek-quota/
├── lib/
│ ├── index.js # Host 半：凭据解析 → 官方余额接口 → 同源路由 /dsh-quota/balance
│ └── client.js # Client 半：侧边栏卡片 + 充值面板 + 内联 QR 编码器
├── package.json # 插件清单（入口 / dsh bundle / client 注入声明）
├── cordis.patch.yml # profile 组合层补丁（以一行插入 bundles）
├── install.sh # 一键安装脚本（检测 + 复制 + 改写 profile + 符号链接）
├── scripts/
│ └── patch-profile.mjs # install.sh 依赖：安全改写 profile package.json（幂等）
├── tests/
│ └── smoke.test.mjs # 冒烟测试（模块加载 / Host 路由行为 / 归一化逻辑）
├── docs/
│ └── screenshots/ # 功能截图
├── .env.example .gitignore
├── README.md LICENSE CONTRIBUTING.md SECURITY.md CHANGELOG.md
└── .github/ # Issue 模板 + PR 模板
工作原理
浏览器 (Client 半)
QuotaCard 组件 ──fetch──▶ GET /dsh-quota/balance（同源，无 CORS）
│
Host 半 (lib/index.js)
1. ctx.credentials.resolve('DEEPSEEK_API_KEY')
2. fetch {baseURL}/user/balance (Bearer, 15s 超时)
3. 归一化 → { totalBalance, grantedBalance,
toppedUpBalance, updatedAt, … }
│
DeepSeek 官方 API（Key 只在这一层出现）
- 数据流：官方余额接口 → Host 归一化 → 同源只读路由 → 浏览器卡片；每 60 秒自动刷新；
- 状态机：
loading → ready / error；已有数据时刷新失败保留旧值并标注「更新失败」； - 期间已用 = 组件加载以来余额的减少量（官方为预付费余额制，无“总配额/已用”字段，如实映射）；
- 充值面板：注册于
shell.overlay全屏浮层，居中模态，支持遮罩 / × / Esc 关闭。
常见问题
Q：卡片不显示 / 一直转圈？
先确认已在 设置 → 模型 填入 DEEPSEEK_API_KEY；然后看页面控制台是否有 GET /dsh-quota/balance 报错。插件默认挂在侧边栏底部「设置」上方，收起态是 32px 圆形按钮。
Q：提示「未配置 DEEPSEEK_API_KEY」？
在 设置 → 模型 中填写并保存后，点击卡片刷新按钮即可；无需重启。
Q：余额显示不准 / 是负数？
余额来自官方 GET /user/balance，为账户实时值（同一 Key 所有客户端合计）。面板中的
「期间已用」是从组件加载起的余额差分，不是账户历史总消耗。
Q：充值后余额没变？
官方到账可能有秒级延迟；回到应用点击刷新图标，或等 60 秒自动刷新。若仍不变，确认充值与 API Key 属于同一平台账号。
Q：安装脚本报错？
按脚本提示操作：未检测到 DSH 时先运行一次 DeepSeek Harness 生成 ~/.dsh；profile 名不同时用 --profile 指定；Node 过旧按提示升级。
开发与测试
# 语法检查
node --check lib/index.js
node --check lib/client.js
# 冒烟测试（模块加载 / Host 路由行为 / 余额归一化）
node --test tests/smoke.test.mjs
# 端到端测试（模拟他人从零安装 → 启动 → 取数，覆盖成功/无Key/无效Key/超时）
node scripts/mock-deepseek.mjs & # 本地 mock 上游（:8899，无真实 Key 也能联调）
node --test tests/e2e-install-test.mjs # 会临时创建干净 DSH_HOME 执行 install.sh
> 无真实 Key 联调：DEEPSEEK_BASE_URL=http://127.0.0.1:8899 时插件会走本地 mock 上游，
> 可完整体验「余额展示 → 刷新 → 充值面板 → 二维码」全流程，无需任何真实凭据。
我如何确认「别人装上就能用」？
安装后按此清单快速自检（1 分钟）：
- 安装成功：
bash install.sh输出安装完成，且~/.dsh/profiles/web/package.json
的dependencies与dsh.profile.bundles中均出现dsh-deepseek-quota； - 重启 DSH（或页面 Cmd+R），侧边栏底部「设置」上方出现额度卡片（收起态为 32px 圆形
¥按钮）； - 配置 Key：设置 → 模型 → 填入
DEEPSEEK_API_KEY（与调用模型的 Key 同一把）； - 看到余额：卡片显示
¥XX.XX大字 + 「充值 ¥X · 赠送 ¥X」+「更新于 HH:MM:SS」； - 刷新：点右上角刷新图标立即更新；充值：点「充值」弹出面板，选金额/支付方式 → 「去支付」出二维码；
- 无 Key 联调：
node scripts/mock-deepseek.mjs+DEEPSEEK_BASE_URL=http://127.0.0.1:8899
启动，无需真实凭据即可跑通全流程（CI 的端到端测试即按此路径验证）。
> 常见问题与排查见下方「常见问题」；测试全绿（冒烟 6 例 + 端到端 5 例）是发布的硬性门槛。
许可证与贡献
- 基于 MIT License 开源，可自由使用、修改、商用；
- 欢迎提 Issue / PR，流程见 CONTRIBUTING.md；
- 安全反馈请走 SECURITY.md；
- 更新记录见 CHANGELOG.md。
