# deepseek-harness-wallet

> 为 DSH Web 提供官方 DeepSeek 余额、每会话成本与三方 Token 用量面板，支持多账号热切换、24h 峰谷时钟和防钓鱼充值入口。

## Metadata

- Author: [@feibi-mochi](https://github.com/feibi-mochi)
- Repo: <https://github.com/feibi-mochi/deepseek-harness-wallet.git>
- GitHub: [feibi-mochi/deepseek-harness-control-center](https://github.com/feibi-mochi/deepseek-harness-control-center)
- Stars: 58
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `account-monitoring`, `agentic-ai`, `balance-monitor`, `cost-tracking`, `deepseek`, `deepseek-harness`, `dsh-plugin`, `javascript`, `llm`, `notifications`, `plugin`, `recharge`, `session-management`, `token-tracking`, `wallet`
- Forks: 3
- Open Issues: 1
- Last push: 2026-08-20T09:16:00.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:feibi-mochi/deepseek-harness-wallet
```

## Wiki

## 一句话定位
在 DSH Web 的输入框旁常驻一个迷你"钱包"标签，显示 DeepSeek 官方账户余额、本会话成本与三方 Token 用量，提供多账号一键切换、低余额提醒与官方充值入口。

## 核心能力
- 实时显示官方 DeepSeek 余额：60 秒自动刷新，启动时附加 2 / 6 / 15 / 30 秒梯次重试，未配置 API Key 时给出友好错误而非崩溃（index.js:35 / index.js:737-749）
- 本会话成本与 Token 分桶：监听宿主 `llm/stream` 事件，把输入 / 缓存读 / 缓存写 / 输出 / 推理 token 分别按官方 provider 和其它 provider 入账，每次用量锁定当时价，避免跨档位串台（index.js:710-731 / index.js:481-498）
- 24h 峰 / 谷计费分时钟：侧边栏底部环形钟实时展示北京时区高峰（09:00–12:00、14:00–18:00）与低谷半价时段，含切换倒计时与可选的桌面系统通知（index.js:41-43 / CHANGELOG.md:7-10）
- 多账号管理与热切换：在面板「账户管理」添加多个 DeepSeek 账号（名称 + API Key），切换后无需重启，下一次 LLM 请求即按新账号计费；UI 只显示掩码后的 Key（index.js:435-451 / README.md:39-44）
- 防钓鱼的官方充值入口：标签右侧"↗充"按钮直接打开 `https://platform.deepseek.com/top_up`，URL 在代码里硬编码不可改，首次点击会弹窗确认域名（index.js:28 / README.md:138）
- 标签支持拖拽停靠、缩放与浮动窗口：可在输入框旁、悬浮、侧边停靠三种模式间拖动，停靠位置与缩放比例会持久化；面板可剥离为可拖动浮动窗，进一步最小化为可移动的圆点（lib/client.js:1965-2099 / CHANGELOG.md:38-44）
- 完成提醒与峰 / 谷切换桌面通知：对话完成时通过宿主通知通道弹窗，可选常驻或定时关闭；不支持系统通知时降级为页内通知（lib/client.js:715-755 / README.md:31）

## 技术实现
- **语言**: JavaScript（ESM）：`index.js` 是 host half，`lib/client.js` 是 client half（package.json:5 / package.json:6-11）
- **关键依赖**: 零第三方运行时依赖；仅使用 Node 内置 `node:crypto` / `node:fs` / `node:os`，浏览器侧通过 React（由 DSH Web 注入）渲染，CSS 变量全部走 `--dsw-alias-*` 主题（package.json:0 / index.js:19-22 / lib/client.js:262-310）
- **架构模式**: 双半包宿主插件（dual half）。host half 通过 `ctx.on('llm/stream', usageTap, { global: true })` 包裹模型流拦截 usage 块，按 provider 入账；`ctx.webServer.register` 暴露 `/api/wallet/{snapshot,threshold,refresh,clear-session,accounts,accounts/activate,accounts/remove,official-providers}` 共 8 个 JSON 路由；client half 通过 `window.__ModuleLoader__.load({ id: 'deepseek-harness-wallet', factory })` 把自己注册进页面，适配层 `createCompatibilityAdapter()` 统一抽象通知 / 存储 / 权限 / 外部链接 4 类宿主编配点（index.js:697-903 / lib/client.js:6-11 / lib/client.js:45-240）
- **入口文件**: 服务端入口 `index.js`（`apply` / `name = 'wallet'`）；客户端入口 `lib/client.js`；挂载声明 `cordis.patch.yml`（在 web profile 插入 id=`wallet`，name=`deepseek-harness-wallet`）（cordis.patch.yml:1-4 / package.json:49-61）

## 适用场景
适合已经把 DeepSeek 作为主力模型、需要在每次会话时一眼看到官方余额、本场花费和三方 Token 消耗的人。它把原本散落在官方开放平台控制台、DSH 模型设置与会话详情里的费用信号统一收口到一个可拖动的小标签里，多人共用一台机器或多账号轮换计费时尤其有用。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness (DSH) | `0.1.0-rc.6+`（`0.1.0-rc.7` 实测） | README 徽章钉 `0.1.0--rc.6`，RELEASE-NOTES-v0.2.2 报告实测 `0.1.0-rc.7`（README.md:6 / RELEASE-NOTES-v0.2.2.md:12-27） |
| Node.js（仅宿主导入时） | `^22.19.0 \|\| >=24` | `package.json#engines.node` 强制要求（package.json:46-48） |
| 平台 | 跨平台 | 实测 Windows + Edge；CI 三平台（Ubuntu / macOS / Windows）× Node 22 / 24 全绿；不引入原生模块，零 OS 特定分支（README.md:99-105 / RELEASE-NOTES-v0.2.2.md:12-27） |
| API Key | `DEEPSEEK_API_KEY` 用于余额查询 | 无 key 仍可统计 Token / 成本，但余额显示错误状态（AGENTS.md:13） |
| 原生模块 | 无 | 零第三方依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:feibi-mochi/deepseek-harness-wallet
```

## 配置项
本插件不读取宿主配置文件；所有用户级设置都通过面板内 UI 调整并即时落盘。下方为各设置的实际键名、作用与默认值（lib/client.js:18-35 / lib/client.js:1043-1140）：

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 标签布局 | enum | 标签停靠位置：输入框内 / 悬浮 / 侧边 | `home`（输入框内） |
| 标签比例 | number(0.75–1.25) | 标签缩放；输入框内上限 120%，悬浮 / 侧边可至 125% | `1.00` |
| 面板显示内容 | two flags | 是否在标签里展示官方 / 三方两路数据；二者至少保留一项 | `{ official: true, third: true }` |
| 完成提醒 | enum | `off` / `5s` / `10s` / `30s` / `60s` / `keep` | `off` |
| 低余额闪烁 | boolean | 余额低于阈值时标签是否红色脉冲 | `true` |
| 低余额阈值（CNY / USD 分货币） | number(0–100000) | 余额低于此线即告警；CNY / USD 各自独立，按 active 账号自动套用 | CNY `5` |
| 峰 / 谷环形钟（侧边栏底部） | boolean | 是否显示 24h 计费分时盘 | `true` |
| 峰 / 谷切换系统通知 | boolean | 进入高峰 / 谷时是否弹一次桌面通知 | `false` |
| 永久删除会话（仅当宿主支持） | boolean | 在会话菜单暴露永久删除入口；无能力的宿主开关恒灰 | 由宿主能力决定 |
| 账号（多账号） | list | 名称 + API Key，存于 `$DSH_HOME/storages/accounts.json`；首条添加自动设为 active | 空 |
| 第三方 provider 归入官方桶 | string[] | 设置页勾选把哪些 wrapper provider 路由算成官方价（便于按官方价结算走代理的视觉模型） | 仅内置 `deepseek-official` |

## 常见问题

**Q: 安装后标签（chip）不出现怎么办？**

A: 必须先 `dsh plugin --profile web add deepseek-harness-wallet`，再 `restart dsh web`，最后在浏览器里硬刷新页面。客户端半包通过 `window.__ModuleLoader__.load({ id: 'deepseek-harness-wallet' })` 注入，硬刷新是触发装载的必要条件。

**Q: 余额为什么显示错误 / 没有数字？**

A: 余额依赖 `DEEPSEEK_API_KEY`，没有或 key 失效时直接对官方 `/user/balance` 端点查询，key 只作为 `Authorization` 头离开本机。Token / 成本会计不依赖 key，仍可正常工作；只要在 DSH 模型设置里配上 key 或让账号管理添加，余额就会恢复。

**Q: 三方模型会话为什么没有余额和成本，只有 Token？**

A: 余额与官方价表只对接官方接口，三方 provider 没有官方价表也没有余额端点，所以只统计输入 / 缓存读 / 输出的 Token 量，不估算花费和余额。

**Q: 怎么在多个 DeepSeek 账号之间切换？下次计费跟着谁？**

A: 在面板"账户管理"里添加账号（名称 + API key），切换会写入凭据通道 `credentials.set('DEEPSEEK_API_KEY', ...)`。llm-deepseek 路由按请求解析该凭据，所以下一次 LLM 调用即按新账号计费，不需重启。如果环境变量里也设了 `DEEPSEEK_API_KEY`，凭据通道会拒绝覆写，切换会失败并提示。

**Q: 充值链接地址可以换吗？**

A: 不能。`RECHARGE_URL = 'https://platform.deepseek.com/top_up'` 在宿主侧硬编码，不可配置——这是有意做的防钓鱼措施。首次点击会弹窗确认域名。

**Q: "永久删除会话"开关是灰的，怎么开？**

A: 这是宿主能力，非插件可独立实现。它要求宿主 DSH 真正实现了会话删除路径并向客户端广播 `data-dshw-capability-permanent-delete='true'`；当前官方发行版没有此能力，所以开关保持禁用。如果你是宿主开发者，参考 `integrations/dsh-session-delete/` 套件把能力接上即可。

**Q: 数据存到哪里？清除本会话数据会不会删掉对话？**

A: 钱包数据存到 `$DSH_HOME/storages/wallet.json`，账号存到 `$DSH_HOME/storages/accounts.json`，UI 内显示内容 / 缩放 / 布局等存在浏览器 localStorage。"清除本会话数据"只清掉当前会话的 token / 成本计数，不会删聊天和会话本身。

**Q: 机器上装了旧版 `dsh-wallet`，怎么清理？**

A: `dsh-wallet` 在 0.1.1 改名为 `deepseek-harness-wallet`，老包不卸载会和新包重复占同一行 UI。执行 `dsh plugin --profile web remove dsh-wallet` 后重启 `dsh web` 即可。

**Q: 会话成本（¥/$）看起来不太准？**

A: 成本是按每次用量事件落到价格表时的"当时价"逐次估价的：v4 模型自带峰 / 谷两档（北京时间 09:00–12:00 与 14:00–18:00 为高峰，谷价为高峰一半），历史调用的计费不会被新价覆盖。官方接口返回的余额是权威值，估价仅作参考。

## 上手难度
入门 — 一条 `dsh plugin add` + 重启 `dsh web` + 硬刷新即在输入框旁看到标签；想用多账号或自定义阈值时进入面板"账户管理"。

## 已知问题与限制
- 必须硬刷新：客户端半包在 `window.__ModuleLoader__.load` 里注册，装载发生在页面加载时；安装 / 更新后未硬刷新页面标签不会出来（AGENTS.md:23-25）
- 多账号与环境变量冲突：若 Shell 已 `export DEEPSEEK_API_KEY`，凭据提供方会拒绝覆写，切换按钮直接报错——临时 unset 后再切（README.md:43-44）
- 永久删除取决于宿主能力：当前官方 DSH 发行版未提供 `permanentDelete` 能力，UI 开关保持禁用；不可通过改配置伪装；接入步骤在 `integrations/dsh-session-delete/` 单独说明（AGENTS.md:54-57）
- 旧包名残留：早于 0.1.1 的 `dsh-wallet` 不会自动卸载，需手动 `dsh plugin --profile web remove dsh-wallet` 避免两个包抢同一行（README.md:93）
- USD 账户成本为估算：CNY 价格表按官方长期固定汇率换算，标签明确写为「本约 $x」；汇率非实时，官方余额为权威值（README.md:42-43）
- 充值 URL 不可配置：`https://platform.deepseek.com/top_up` 硬编码为防钓鱼设计（README.md:138）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [deepseek-harness-wallet](https://deepseek-plugin.org/plugins/feibi-mochi/deepseek-harness-wallet)
Wiki generated by AI (model: `MiniMax-M3`)