# dsh-deepseek-balance-widget

[English](README_EN.md) | 中文

在 dsh Web 侧边栏显示 AI 余额的多平台插件：内置 **DeepSeek**，可添加 **MiMo（小米）**，每 30 秒自动刷新。

## 功能

![AI 余额侧边栏展示](assets/screenshot.png)

**侧边栏入口**
- 实时显示当前平台的余额 / 今日消费 / 今日 Token，每 30 秒自动刷新
- 数值随弹窗内切换的平台联动

**详情弹窗**
- 顶部显示当前平台，点「**更换**」下拉在已添加平台间切换，点「**×**」移除（带确认）
- 右上角「**+ 添加**」：加入 MiMo 或 DeepSeek
- DeepSeek 详情：余额、累计消费、今日消费、今日 Token、本月消耗（本月消费 / Tokens）
- MiMo 详情：余额、累计消费、今日消费 / 今日 Token、本月消耗、**每日消耗表**（日期 / Token / 请求 / 消费）
- DeepSeek 显示时段徽章（繁忙 / 空闲，GMT+8：工作日 09-12 / 14-18 为繁忙时段，周末全天空闲）

**用量统计**
- DeepSeek：需可选配置 `DEEPSEEK_PLATFORM_TOKEN`（对 AI 说「帮我配置用量统计」即可）；未配置时仅显示余额
- MiMo：余额与用量均用登录 Cookie 查询，自动推算消费金额（按官方单价）

**AI 帮我配置**
- 弹窗内一键复制提示语，发给智能体后 AI 读取本机教程文件、一步步引导你抓取凭证并写入插件
- MiMo 支持两种方式：AI 引导向导（打开余额页 → 复制提示语），或手动粘贴 Cookie / cURL（自动提取 Cookie）
- 数据仅存本机，不上传

**版本与更新**
- 弹窗底部显示当前版本，有新版本时显示 `vX → vY 更新`，一键自动更新
- 更新失败时显示错误详情面板（可复制错误信息），并引导前往 GitHub 自行安装
- 界面语言随 dsh 设置自动切换中 / EN

**皮肤与第三方插件兼容（v2.4.3 起）**
- 与 maid-atelier 等会重建侧栏 DOM 的皮肤插件共存时，余额入口依然稳定显示
- 插入采用「安全插入」策略：锚点被皮肤 / React 搬走时自动退化为追加，绝不抛异常、绝不中断重试
- 放置成功后下一帧自动复查，被搬走会在下一轮变化时自动归位
- 识别常见皮肤标记（如 `[data-maid-sidebar-footer]`）作为侧栏兜底锚点

## 安装

需要：已安装 dsh（可用 `dsh web`）。

```bash
dsh plugin --profile web add dsh-deepseek-balance-widget@2.4.3
```

从 npm 拉取安装，dsh 自动注册到 `dsh.profile.bundles`，完成后**重启 `dsh web`** 即可。

> **务必写死版本号 `@2.4.3`**（当前最新稳定版）。不要用 `@latest`——它会被本地 pnpm/npm 缓存或镜像源解析成旧版本，导致装到老版。如果未来发布了更高版本，把这里的版本号换成最新的即可。

也可以直接对 AI 说：

> 帮我用 npm 安装 dsh-deepseek-balance-widget 插件，执行 `dsh plugin --profile web add dsh-deepseek-balance-widget@2.4.3`。

## 配置

插件首次使用会自动创建 DeepSeek 条目，读取你本机的 `DEEPSEEK_API_KEY`。

要加入 MiMo，打开弹窗点右上角「+ 添加」，再点「AI 帮我配置」，把提示语发给智能体；也可以直接对 AI 说：

> 帮我配置 dsh-deepseek-balance-widget。

AI 会接管全部：问 API Key / 引导获取平台 Cookie → 读取本机教程写入配置 → 提醒重启 `dsh web`。

| 平台 | 凭据 | 备注 |
| --- | --- | --- |
| DeepSeek | `DEEPSEEK_API_KEY` | 必填，余额 |
| DeepSeek 用量 | `DEEPSEEK_PLATFORM_TOKEN` | 可选，统计累计 / 本月 / 今日 |
| MiMo（小米） | 登录 Cookie | AI 引导获取 |

凭据保存在你本机的 `~/.dsh/ai-balances.json`，不随插件分发、不上传。

## 更新

无论你当前是哪个旧版本，都推荐升级到 npm 上的最新稳定版。

### 方式一：弹窗一键更新（推荐，已装用户）

1. 打开余额弹窗，底部会显示版本号；有新版本时显示 `vX → vY 更新`（`vY` 为 npm 上 semver 最高的版本）。
2. 点击「**更新**」，插件会自动从 npm 拉取并安装最高版本。
3. 安装完成后**必须彻底重启 `dsh web`**（关掉 `dsh web` 进程 / 退出桌面端再重开，**仅刷新浏览器页面无效**）才能加载新版本。

> 弹窗的「更新」会跳过 `latest` tag，直接安装 npm 上 semver 最高的版本，所以即使有人把 `latest` 改低了也能升到最新。

### 方式二：命令行强制更新（最稳妥，适合卡住或装不上的情况）

```bash
dsh plugin --profile web add dsh-deepseek-balance-widget@2.4.3
```

**写死版本号 `@2.4.3`** 可绕过本地缓存 / 镜像源不同步 / `latest` 解析成旧版的问题，一步到位。装完**彻底重启 `dsh web`**。

### 方式三：手动更新（命令行更新失败时兜底）

```bash
cd ~/.dsh/profiles/web
npm install dsh-deepseek-balance-widget@2.4.3   # 若目录内有 pnpm-lock.yaml 则用 pnpm add
# 验证磁盘上确实变了
cat node_modules/dsh-deepseek-balance-widget/package.json | grep '"version"'
```

确认输出 `2.4.3` 后，**彻底重启 `dsh web`** 即可。

> 如果你的环境里弹窗/命令行的更新一直失败（提示版本没变），通常是 Agent 主机（如 WorkBuddy）通过 `NODE_OPTIONS` 注入了文件删除拦截导致 pnpm/npm 更新中断。此时在**普通终端**（不通过 Agent 运行）里执行上面的命令即可成功；或先执行 `set NODE_OPTIONS=`（PowerShell）再重试。

## 更新日志

### v2.4.3

- **修复**：与 maid-atelier 等皮肤插件共存时，余额卡片完全不显示、控制台持续抛 `Uncaught NotFoundError: insertBefore` 的问题
- 侧栏 / 底栏插入统一改用安全插入 helper：插入前校验锚点是否仍为目标容器的已连接子节点，否则退化为 `appendChild`，永不抛异常
- `tryPlace()` 整体容错，单次失败不再中断后续重试；放置成功后在下一帧复查，自动纠正被皮肤 / React 同帧搬走的入口
- `sidebarRoot()` 增加 `[data-maid-sidebar-footer]` 皮肤标记兜底
- 感谢用户「朱鹭咲泽」提交的详细根因分析与修复补丁

### v2.4.2 及更早

见 [GitHub Releases](https://github.com/crazy-L118/dsh-deepseek-balance-widget/releases)。

## 卸载

```bash
dsh plugin --profile web rm dsh-deepseek-balance-widget
```

或者直接对 AI 说：

> 帮我用 npm 卸载 dsh-deepseek-balance-widget 插件。

## 联系

有问题或建议，欢迎联系：

- 邮箱：crazy_l118@icloud.com

## 赞助

如果这个插件对你有帮助，可以给我的晚餐加一根火腿肠 🍗

![赞赏码](assets/sponsor.jpg)

## License

[MIT](LICENSE)