# 在 macOS 上安装「侧边栏账号余额」插件

插件名：`dsh-account-balance-badge`  版本：`0.2.0`（DSH `>=0.2.1-rc.2 <0.3.0-0`）

本文档说明如何在 macOS 的 DeepSeek Harness（DSH）里安装、使用并验证这个插件。插件本身是纯
JavaScript，**没有构建步骤、没有任何 npm 依赖**；它从 GitHub 仓库分发，安装包是 Release 里附带的
`dsh-account-balance-badge-0.2.0.tgz`。

- 仓库：<https://github.com/NebulaXIX/dsh-account-balance-badge>
- 最新 Release：<https://github.com/NebulaXIX/dsh-account-balance-badge/releases/latest>
- 英文文档：[INSTALL-macOS.en.md](INSTALL-macOS.en.md)

> 目前**尚未发布到 npm**，所以「输入包名安装」的方式暂不可用；请用下面的 Git 地址或 Release tarball。

## 0. 安装方式一览

| 方式 | 适用场景 | 需要的文件 |
|---|---|---|
| A. DSH 插件界面 + Git 地址 | **推荐**；桌面 App 也只能用这种方式 | 无（联网即可） |
| B. DSH 插件界面 + Release tarball | 网络访问 GitHub 不稳，或要固定版本 | `dsh-account-balance-badge-0.2.0.tgz` |
| C. `dsh plugin` 命令行 | 有 `dsh` CLI 与 `pnpm`，且目标 profile 不是 `desktop` | 无 / 可选 tarball |
| D. 一键脚本（可选） | 想把方式 C 合并成一条命令 | tarball + `scripts/install-dsh-account-balance-badge-macos.sh` |

## 1. 安装前的检查

1. DSH 正常启动（桌面版，或由 profile 管理的 `dsh web`），并且**已登录 DeepSeek 账号**。
2. 确认 DSH 版本在支持范围内（`>=0.2.1-rc.2 <0.3.0-0`）；不在范围内，DSH 会在安装和启动时拒绝。
3. 想用「在软件内充值」时，需要桌面版（它用 preload 提供的 `dshPlatform` 桥承载官方充值页）；
   纯浏览器打开的 Web 界面会在新标签页打开充值页。

> 插件不会读写账号凭据：余额由 DSH Host 的账号服务读取，页面只收到金额（币种与十进制字符串）；
> 充值页是桌面端自带的原生视图，复用桌面端自己的 Platform 登录态。

## 2. 安装

### A. 通过 Web 界面 + Git 地址安装（推荐）

1. 打开 DSH，点击左侧边栏的 **插件**（Plugins）。
2. 点击 **添加插件**（也可点箭头 → **安装第三方插件**）。
3. 在输入框里填入：
   ```
   github:NebulaXIX/dsh-account-balance-badge
   ```
   想固定到本版本就填 `github:NebulaXIX/dsh-account-balance-badge#v0.2.0`。
4. 点击 **安装**（可在 **查看安装过程** 里看到 pnpm 输出）。
5. 完成后选择 **立即启用**。开启 HMR 的 profile 立即生效，否则会提示需要**重启 DeepSeek Harness**。
6. 回到主界面，左侧边栏底部、**设置** 上方会出现一行余额（展开时 42px 整行，收起时 36px 图标）。

### B. 通过 Web 界面 + Release tarball 安装

1. 从 <https://github.com/NebulaXIX/dsh-account-balance-badge/releases/latest> 下载
   `dsh-account-balance-badge-0.2.0.tgz`，放到 `~/Downloads`。
2. 在 Terminal 里取绝对路径：
   ```bash
   cd ~/Downloads && echo "$PWD/dsh-account-balance-badge-0.2.0.tgz"
   ```
3. 插件 → **添加插件**，粘贴上一步输出的**绝对路径**（界面里的本地路径不展开 `~`），点 **安装** →
   **立即启用**。

### C. 通过命令行安装

前提：`dsh` CLI 可用、`pnpm` 在 `PATH` 中；先用目标 profile 启动一次 DSH，让该 profile 存在
（`--profile` 必填；`desktop` 由桌面 App 管理，命令行不能使用）。

```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"

# Release 里的 tarball
dsh plugin --profile web add ~/Downloads/dsh-account-balance-badge-0.2.0.tgz

# 可选：确认 profile 里出现了本插件的 bundle 层
dsh --profile web --dump-config

# 之后重启 DSH（或刷新页面，若 profile 开启了 HMR）
```

`dsh plugin ... add` 会自动把插件 bundle 追加进 profile 的 `bundles` 列表，不需要手改 patch。

### D. 使用一键脚本（可选）

```bash
cd ~/Downloads
chmod +x install-dsh-account-balance-badge-macos.sh
./install-dsh-account-balance-badge-macos.sh
```

脚本默认安装到 `web` profile；也可传其他 profile：
`./install-dsh-account-balance-badge-macos.sh --profile myprofile`。
它只是对方式 C 的封装：校验 SHA-256、检查 `dsh`/`pnpm`、执行安装并做一次 `--dump-config`。

> ⚠️ 脚本**不能**操作桌面 App 的 `desktop` profile；若提示 `desktop` 不可用，请改用方式 A/B。

## 3. 使用说明

- 该行显示钱包图标、本地化标签与当前余额；点击整行可立即刷新，窗口重新聚焦、页面可见时每 60 秒
  自动刷新。
- 点击金额旁的 **充值** 按钮即可充值：桌面版在应用窗口内打开官方充值页（顶部是「返回 DeepSeek
  Harness」栏），返回后立即重新读取余额；纯浏览器版本则在新标签页打开官方充值页。未登录时按钮禁用。
- 加载中、未登录、读取失败（可点击重试）都有对应状态，**不会伪装成 0 余额**。充值页加载失败时
  返回栏仍可用，并显示本地化错误与「重试」；按 Esc 也可返回。

## 4. 卸载 / 升级

第三方插件没有「更新」按钮，升级 = 卸载旧版 + 安装新版。

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

Web 界面：进入该插件的组合包页面 → **卸载** → 重新 **添加插件** 安装新版本。

## 5. 排障

| 现象 | 可能原因与处理 |
|---|---|
| 插件页显示「不可用」 | profile 由桌面 App 管理；请用方式 A/B 的 Web 界面安装。 |
| 提示 `pnpm was not found` | 安装 pnpm（`npm i -g pnpm`）并确认在 `PATH` 中。 |
| 提示 `incompatible-version` | 当前 DSH 版本不在 `>=0.2.1-rc.2 <0.3.0-0` 内。升级 DSH，或在明确知晓风险的前提下为 profile 添加精确版本豁免。 |
| Clone/下载 GitHub 失败 | 换网络或代理后重试；也可下载 Release tarball 用方式 B 离线安装。 |
| 安装完成但侧边栏没有变化 | 使用 **立即启用**，或重启 DSH / 刷新页面。 |
| 点「充值」没有在软件内打开 | 纯浏览器打开的 Web 界面没有桌面桥，会在新标签页打开；软件内充值需要桌面版。 |
| 金额一直「读取失败」，但账号页能看到余额 | 该 DSH 版本或 profile 缺少账号相关内置插件；先正常打开一次设置 → 账号，或升级 DSH。 |
| 显示「未登录」 | 先在 DSH 里登录 DeepSeek 账号。 |
| 想换刷新间隔 | 在本地 checkout 修改 `client.js` 顶部的 `REFRESH_INTERVAL_MS`（默认 60000 毫秒）后按方式 C/D 安装。 |

本插件不写入任何凭据、也不直接发起网络请求，因此不需要额外授予「完全磁盘访问」等系统权限。

## 6. 安装包校验

```bash
cd ~/Downloads
shasum -a 256 dsh-account-balance-badge-0.2.0.tgz
```

应为：

```
83aae9ea8710a0b9a23f7f9cf3363c548d2fad02a52ae90b7d4a48690f8c5433  dsh-account-balance-badge-0.2.0.tgz
```

包内应有 11 个文件：`package.json`、`index.js`、`client.js`、`cordis.patch.yml`、`icon.svg`、
`locale/en.json`、`locale/zh.json`、`README.md`、`README.zh.md`、`LICENSE`、`CHANGELOG.md`
（可用 `tar -tzf dsh-account-balance-badge-0.2.0.tgz` 查看）。GitHub Release 页也会给出该文件，
下载后校验值应与上面一致。

本地开发时可在项目根目录运行 `npm test`（零依赖，22 项检查）。