# Install the sidebar account balance plugin on macOS

Package: `dsh-account-balance-badge`  Version: `0.2.0` (requires DSH `>=0.2.1-rc.2 <0.3.0-0`)

This guide explains how to install, use, and verify the plugin on macOS in DeepSeek Harness (DSH).
The plugin is plain JavaScript with **no build step and no npm dependencies**; it is distributed from
GitHub, and the installable bundle is the `dsh-account-balance-badge-0.2.0.tgz` attached to the
release.

- Repository: <https://github.com/NebulaXIX/dsh-account-balance-badge>
- Latest release: <https://github.com/NebulaXIX/dsh-account-balance-badge/releases/latest>
- Chinese guide: [INSTALL-macOS.md](INSTALL-macOS.md)

> The package is **not on npm yet**, so installing by package name does not work. Use the Git address
> or the release tarball described below.

## 0. Install routes

| Route | When to use it | What you need |
|---|---|---|
| A. DSH Plugins UI + Git address | **Recommended**; the only route for the Desktop app | Nothing beyond network access |
| B. DSH Plugins UI + release tarball | GitHub access is unreliable, or you want a pinned version | `dsh-account-balance-badge-0.2.0.tgz` |
| C. `dsh plugin` CLI | You have the `dsh` CLI and `pnpm`, and the target profile is not `desktop` | Nothing / optionally the tarball |
| D. One-shot script (optional) | You want route C as a single command | Tarball + `scripts/install-dsh-account-balance-badge-macos.sh` |

## 1. Before you start

1. DSH starts normally (Desktop app, or `dsh web` with a profile) and is **signed in** to a DeepSeek
   account.
2. Your DSH version is inside the supported range (`>=0.2.1-rc.2 <0.3.0-0`). DSH refuses to install
   or start a bundle whose range does not match.
3. In-app recharge needs the **Desktop app** (it hosts the official top-up page through the
   preload-provided `dshPlatform` bridge). A plain browser Web UI opens the top-up page in a new tab.

> The plugin never reads or stores account credentials: balances are read by the DSH Host account
> service, and the page only receives amounts (currency and decimal strings). The top-up page is a
> Desktop-owned native view that reuses the Desktop's own Platform session.

## 2. Install

### A. DSH Plugins UI + Git address (recommended)

1. Open DSH and select **Plugins** in the left sidebar.
2. Click **Add plugin** (or the arrow → **Install a third-party plugin**).
3. Enter:
   ```
   github:NebulaXIX/dsh-account-balance-badge
   ```
   To pin this version, use `github:NebulaXIX/dsh-account-balance-badge#v0.2.0` instead.
4. Click **Install** (the pnpm output is available under **View installation**).
5. When it finishes, choose **Enable now**. A profile with HMR recomposes immediately; otherwise DSH
   asks for a restart.
6. The balance row appears at the bottom of the left sidebar, above **Settings** (a 42 px row when
   the sidebar is expanded, a 36 px icon in the collapsed rail).

### B. DSH Plugins UI + release tarball

1. Download `dsh-account-balance-badge-0.2.0.tgz` from
   <https://github.com/NebulaXIX/dsh-account-balance-badge/releases/latest> into `~/Downloads`.
2. Print its absolute path in Terminal:
   ```bash
   cd ~/Downloads && echo "$PWD/dsh-account-balance-badge-0.2.0.tgz"
   ```
3. In Plugins → **Add plugin**, paste that **absolute** path (the UI does not expand `~`), click
   **Install**, then **Enable now**.

### C. `dsh` CLI

Requires the `dsh` CLI and `pnpm` on `PATH`; start DSH once first so the target profile exists.
`--profile` is required, and `desktop` belongs to the Desktop app and is rejected by the CLI:

```bash
# Git, tracking main
dsh plugin --profile web add github:NebulaXIX/dsh-account-balance-badge

# Git, pinned to the v0.2.0 release
dsh plugin --profile web add "github:NebulaXIX/dsh-account-balance-badge#v0.2.0"

# the release tarball
dsh plugin --profile web add ~/Downloads/dsh-account-balance-badge-0.2.0.tgz

# optional: confirm the bundle layer is present in the profile
dsh --profile web --dump-config

# then restart DSH (or reload the page on a profile with HMR)
```

`dsh plugin ... add` also appends the bundle to the profile's bundle list, so no manual patch editing
is needed.

### D. One-shot script (optional)

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

The script installs into the `web` profile by default; pass another profile with
`./install-dsh-account-balance-badge-macos.sh --profile myprofile`. It is a thin wrapper around route
C: it verifies the SHA-256, checks `dsh`/`pnpm`, installs, and runs `--dump-config` once.

> ⚠️ The script **cannot** drive the Desktop app's `desktop` profile. If it reports `desktop` is not
> allowed, use route A or B through the Plugins UI instead.

## 3. Usage

- The row shows a wallet icon, the localized label, and the current balance(s). Click the row to
  refresh; it also refreshes on window focus and every 60 seconds while the page is visible.
- Click **Top up** (充值) beside the amount: on the Desktop app the official DeepSeek top-up page
  opens inside the application window under a "Back to DeepSeek Harness" bar, and returning re-reads
  the balance immediately; in a plain browser the same page opens in a new tab. The button is
  disabled while signed out.
- Loading, signed-out, and failed-but-retryable states are rendered in place; the row never fabricates
  a zero balance. If the top-up page fails to load, the return bar stays available with a localized
  error and a Retry action, and Escape also returns.

## 4. Uninstall / upgrade

Third-party plugins have no Update button, so upgrading means uninstall + install the new version:

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

In the Plugins UI, open the bundle page → **Uninstall**, then add the new version again.

## 5. Troubleshooting

| Symptom | Cause and fix |
|---|---|
| The Plugins page shows "unavailable" | The profile is app-managed; install through the Plugins UI (route A or B). |
| `pnpm was not found` | Install pnpm (`npm i -g pnpm`) and make sure it is on `PATH`. |
| `incompatible-version` | The running DSH is outside `>=0.2.1-rc.2 <0.3.0-0`. Upgrade DSH, or add an exact-version exemption for the profile if you accept the risk. |
| Cloning/downloading from GitHub fails | Retry on another network or proxy, or download the release tarball and use route B. |
| Installed, but the sidebar is unchanged | Use **Enable now**, or restart DSH / reload the page. |
| "Top up" does not open inside the app | A plain browser Web UI has no Desktop bridge and opens a new tab; in-app recharge needs the Desktop app. |
| Balance always shows "unavailable" while the account page works | The DSH version or profile is missing account plugins; open Settings → Account once in the browser, or upgrade DSH. |
| It shows "signed out" | Sign in to a DeepSeek account in DSH first. |
| You want a different refresh cadence | Edit `REFRESH_INTERVAL_MS` at the top of `client.js` in a local checkout (default 60000 ms), then install via route C/D. |

The plugin stores no credentials and makes no network requests of its own, so no extra macOS
permissions (such as Full Disk Access) are required.

## 6. Verify the download

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

Expected:

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

The tarball contains 11 files: `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` (inspect with `tar -tzf dsh-account-balance-badge-0.2.0.tgz`). The same file is
attached to the GitHub release; its checksum must match the value above.

For local development, run `npm test` in the project root (zero dependencies, 22 checks).