# DSH 侧边栏余额徽章

<img src="icon.svg" width="64" height="64" alt="余额徽章图标">

一个常驻 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）Web 界面
**左侧边栏**的账号余额插件，并带一个「充值」按钮：在软件内直接打开 DeepSeek 官方充值页。

[English](README.md)

## 功能

- **左侧常驻显示**：在侧边栏底部、Settings 上方（内置 Cordis 插件行之下）显示一整行余额，
  首页、设置页、会话页都能看到，不必再进入「设置 → 账号」查看。
- **充值与赠送钱包**：按 Platform 的货币格式显示账号服务返回的每个钱包（CNY `¥`、USD `$`；
  两位小数并带千分位；不足一分显示为 `<¥0.01`），有赠送余额时以小字追加 `赠送 ¥x.xx`。
- **在软件内充值**：金额旁的「充值」按钮会在桌面版里以原生 Platform 页面打开 DeepSeek 官方充值页
  （顶部只有一条「返回 DeepSeek Harness」栏，不离开软件即可完成支付），返回后自动重新读取余额；
  纯浏览器打开的 Web 界面则在新标签页打开同一充值页。未登录时按钮禁用并给出提示。
- **合理刷新**：打开时读取一次；页面可见时每 60 秒刷新；窗口重新聚焦、点击该行、从充值页返回
  也会刷新；同时只会有一个读取请求在途。
- **中英双语、跟随主题**：文案跟随界面语言切换；颜色只使用宿主主题 token，明暗主题与收起的
  36px 轨道都能正常显示。
- **凭据不进入浏览器**：余额通过 Host 账号服务经 Client Remote `account.getBalance` 读取；
  充值页由桌面端自带的原生视图承载、复用桌面端自己的 Platform 登录态，页面不会接触账号原始 token。

## 环境要求

- DSH `>=0.2.1-rc.2 <0.3.0-0`（已在 DSH 0.2.1-rc.2 验证）。
- 由 profile 管理的 DSH 安装（桌面版，或带 profile 启动的 `dsh web`），且 Web 应用随附的
  sidebar、locale、账号控制器插件处于启用状态（标准 Web 应用默认满足）。
- 需要登录 DeepSeek 账号才能显示金额；未登录时会显示「未登录」状态而不是金额，充值按钮保持禁用。
- **软件内充值**需要桌面版：它通过 preload 暴露的 `dshPlatform` 桥把官方充值页放进应用窗口内的
  原生视图。纯浏览器版本会在新标签页打开部署方的充值地址。

## 安装

插件从 GitHub 分发——
[仓库](https://github.com/NebulaXIX/dsh-account-balance-badge) ·
[最新 Release](https://github.com/NebulaXIX/dsh-account-balance-badge/releases/latest)。
目前尚未发布到 npm，请用 Git 地址或 Release 中的 tarball 安装。
macOS 的分步安装说明见 [docs/INSTALL-macOS.md](docs/INSTALL-macOS.md)（中文）与
[docs/INSTALL-macOS.en.md](docs/INSTALL-macOS.en.md)（English）。

### 在 DSH Web 界面安装（推荐）

1. 在 DSH 中点击左侧边栏的 **插件**。
2. 点击 **添加插件**（或点击箭头选择 **安装第三方插件**）。
3. 输入以下任一形式：
   - Git 地址：`github:NebulaXIX/dsh-account-balance-badge`（跟随 `main`），或
     `github:NebulaXIX/dsh-account-balance-badge#v0.2.0`（锁定 Release 版本）
   - Release 中的 tarball：`dsh-account-balance-badge-0.2.0.tgz` 的绝对路径
   - 本地 checkout 的绝对路径
4. 点击 **安装**。
5. 安装完成后选择 **立即启用**。启用了 HMR 的 profile 会立即生效，否则重启 DeepSeek Harness。
   余额行会出现在左侧边栏底部。

桌面版应用自行管理 `desktop` profile，因此在桌面端只能通过插件界面安装。

### 使用 `dsh` CLI

需要 `dsh` CLI 且 `pnpm` 在 `PATH` 中；先启动一次 DSH 让目标 profile 存在。`--profile` 为必填项，
`desktop` 由桌面应用管理、不能用于 CLI：

```bash
# Git，跟随 main
dsh plugin --profile web add github:NebulaXIX/dsh-account-balance-badge

# Git，锁定 v0.2.0 Release
dsh plugin --profile web add "github:NebulaXIX/dsh-account-balance-badge#v0.2.0"

# GitHub Release 中附带的 tarball
dsh plugin --profile web add ./dsh-account-balance-badge-0.2.0.tgz

# 本地目录（界面中要求绝对路径；CLI 的相对路径按执行目录解析）
dsh plugin --profile web add ./path/to/dsh-account-balance-badge
```

本包是纯 JavaScript、无依赖、无构建脚本，Git 安装不需要批准 pnpm 构建。
`dsh plugin ... add` 会把该 bundle 追加进 profile 的 bundles 列表，无需手动改 patch。

> **目前未发布到 npm。** 用包名安装（`dsh plugin ... add dsh-account-balance-badge`）要等 npm 发布
> 之后才可用；在此之前请使用上面的 Git 地址或 Release tarball。

### 升级 / 卸载

第三方插件通过「卸载旧版 + 安装新版」升级——在 Web 界面中进入组合包页面（**卸载** 后重新安装），
或使用命令行：

```bash
dsh plugin --profile web remove dsh-account-balance-badge
dsh plugin --profile web add "github:NebulaXIX/dsh-account-balance-badge#v<new-version>"
```

## 使用说明

- 该行显示钱包图标、本地化标签与当前余额。
- 点击整行可立即刷新；窗口重新聚焦、页面可见时每 60 秒自动刷新。
- 点击金额旁的 **充值** 按钮即可充值：桌面版在应用窗口内打开官方充值页（顶部是「返回
  DeepSeek Harness」栏），返回后立即重新读取余额；纯浏览器版本则在新标签页打开官方充值页。
- 加载中、未登录、读取失败（可点击重试）都有对应状态，失败时不会伪装成 0 余额。充值页加载失败
  时返回栏仍然可用，并显示本地化的错误说明与「重试」；按 Esc 也可返回。
- 侧边栏展开时为 42px 整行，收起为 36px 图标（无障碍名称与悬停提示中含金额）。Windows 桌面版
  在侧边栏收起时，宿主会隐藏整个侧边栏底部区域，此时该行与 Settings、Cordis 行一样不可见。

## 实现方式

| 半边 | 文件 | 作用 |
|---|---|---|
| Host | `index.js` | 空的 bundle 半边：只承载 Loader 行，不新增 Host 能力、工具或提示词。 |
| Client | `client.js` | 在 `sidebar.footer.action` 注册余额行、在 `shell.overlay` 注册唯一的充值页宿主；通过 `ctx.remote.account.getBalance` 读取余额；通过桌面端 preload 桥（`globalThis.dshPlatform`）承载官方充值页，并渲染整行、返回栏与组件内样式。 |
| Loader patch | `cordis.patch.yml` | 插入以本包名命名的 `account-balance-badge` 行。 |
| 展示元数据 | `locale/en.json`、`locale/zh.json`、`icon.svg` | 插件管理页的标题、描述与图标。 |

余额读取由 Host 的账号服务完成；浏览器只收到钱包金额（币种与十进制字符串）。充值页本身不由本插件
渲染：原生 `WebContentsView` 及其 Platform 凭据由桌面端持有，插件只提供 48px 返回栏，并把实测的
视口矩形通过 preload 桥的 `open` / `setBounds` / `close` 交给桌面端。

## 开发

插件是纯 JavaScript，**无构建步骤、无依赖**：

- `index.js` 是导出 `apply()` 的 ES module。
- `client.js` 是 `window.__ModuleLoader__.load({ id, factory })` 形式的惰性浏览器模块，由宿主
  原样下发给页面，因此必须保持为合法纯 JavaScript（不要使用 JSX/TypeScript/`import`）。它的
  factory 只从页面的冻结模块表里取 `react` 与 `react-dom`（没有 npm 依赖）；`react-dom` 仅用于
  把充值覆盖层 portal 出 `shell.overlay` 层，与随附的账号页面做法一致。

```bash
git clone https://github.com/NebulaXIX/dsh-account-balance-badge.git
cd dsh-account-balance-badge
npm test          # 零依赖的清单/结构检查
```

在插件对话框中使用本地路径安装你的 checkout（或 `dsh plugin --profile web add /absolute/path/to/checkout`）。
bundle 以链接方式安装时，Web UI 会通过 HMR 加载 client 改动；如果 HMR 不可用，刷新一次页面即可。

### 刷新间隔

后台刷新周期是 `client.js` 顶部的常量 `REFRESH_INTERVAL_MS`（默认 `60000` 毫秒）。在本地
checkout 中可自行调整；点击该行与窗口聚焦仍会立即刷新。

## 发布本插件（维护者）

公开仓库：<https://github.com/NebulaXIX/dsh-account-balance-badge>。Release 以 `vX.Y.Z` 打 tag，
并附带 `npm pack` 生成的 tarball，用户安装的就是它。

1. 提升 `package.json` 的 `version`，并在 `CHANGELOG.md` 中补一条记录。
2. 运行 `npm test`（`scripts/check.mjs`，零依赖）与 `npm pack --dry-run`；tarball 中必须包含
   `index.js`、`client.js`、`cordis.patch.yml`、`icon.svg`、`locale/en.json`、`locale/zh.json`
   （README/LICENSE/CHANGELOG 由 npm 自动包含；`scripts/`、`docs/`、`.github/` 按设计不随包发布）。
3. 在 `dev/<任务>` 分支提交、再次运行 `npm test`，然后合并回 `main`。
4. 打 tag 并推送：`git tag v<version> && git push origin main --tags`。
5. 打包并发布 Release（附上 tarball）：
   `npm pack --pack-destination dist`，然后
   `gh release create v<version> dist/dsh-account-balance-badge-<version>.tgz --title "v<version>" --notes-file <说明>`。
6. 可选：发布到 npm 后「用包名安装」才可用，命令为 `npm publish --access public`——包名
   `dsh-account-balance-badge` 目前在 registry 上仍空闲，但发布需要已登录的 npm 账号。
7. 如果将来改名，需要同时修改三处且保持一致：`package.json` 的 `name`、
   `cordis.patch.yml` 行的 `name`、`client.js` 中 `window.__ModuleLoader__.load(...)` 的 `id`。

## 许可证

[MIT](LICENSE)