deepseek-balance-dsh 0.0.0-stage → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+Notable changes to the plugin. The repository is `DSH-DeepSeek-Balance`; the package
+is published on npm as [`deepseek-balance-dsh`](https://www.npmjs.com/package/deepseek-balance-dsh)
+(the npm name `dsh-deepseek-balance` belongs to an unrelated project). Git tags mark
+releases; installation goes through the harness plugin manager or a local checkout
+(see the README).
+
+## 0.2.1 — 2026-10-22
+
+**First npm publication.** No behaviour changes; the distribution identity changed.
+
+- Renamed the package to `deepseek-balance-dsh` so it can be published: the npm name
+  `dsh-deepseek-balance` is held by an unrelated project (published 2026-08-14).
+  The repository, the state file (`~/.deepseek-balance.json`) and the agent tool
+  (`deepseek_balance`) keep their names, so existing configuration and model usage
+  are unaffected.
+- Everything that must match the package name follows it: the client artifact's
+  `__ModuleLoader__` id and the `insert` row in the bundled `cordis.patch.yml`.
+  **Upgrading requires reinstalling the plugin** (the installed directory name is
+  the package name) and restarting the profile — a 0.2.0 install will not load
+  `deepseek-balance-dsh` by itself.
+- Added npm metadata (`repository`, `homepage`, `bugs`, `keywords`).
+
+## 0.2.0 — 2026-09-30
+
+Security, structure and usability pass driven by an architecture review of the
+0.1.x code. Verified on deepseek-harness 0.2.0-rc.2 (web and desktop profiles).
+
+### Security
+
+- **Every `/dsbal/*` route now passes the host's own request gate**
+  (`ctx.connection.admit()`): the same Host/Origin trust fence and browser-cookie
+  authentication the `/api` channel uses. Unauthenticated reads answer `401`,
+  cross-site requests `403`, a wrong method `405`, and a malformed body `400`
+  without touching any state. In 0.1.x the routes were registered bare on the web
+  server, so anything that could reach the port could read account data **and
+  replace the stored API key** with a cross-site "simple" POST.
+- Credential writes remain user-only: the new agent tool can only *project* state
+  through `getState()`, so `setConfig()` is unreachable from a model by
+  construction rather than by policy.
+- Input bounds: `fromMs` may not be in the future nor older than 90 days (an
+  unbounded value could drive up to 24 upstream usage requests per call),
+  credential fields are length-capped, and an API key is shape-checked (`sk-…`)
+  when the user saves one — never for values already in the state file.
+
+### Added
+
+- **`config:` support** — `pollIntervalMs`, `historyDays`, `usageTtlMs`,
+  `usageErrorTtlMs`, `maxSnapshots`, `requestTimeoutMs` and the three endpoint URLs
+  are validated at activation and overridable from the profile patch. An invalid
+  value fails loudly, naming the field.
+- **Bilingual widget** — ~70 user-visible strings moved into a zh/en table; the
+  language follows the host's settings preference, else the browser's, with an
+  explicit choice in the panel (remembered locally). Statutory-holiday and pricing
+  copy is phrased client-side from structured phase facts.
+- **Plugin metadata** — `icon.svg`, `locale/zh.json`, `locale/en.json` and the
+  matching manifest fields, so the plugin manager card has a title, a description
+  and artwork instead of falling back to the package name.
+- **Read-only agent tool `deepseek_balance`** — reports the price phase, balance,
+  period spend and token counters; `window` (and `fromMs` for `custom`) projects a
+  period *without* persisting it. Registered through an optional injection and
+  guarded: if the runtime ever stops accepting the definition, or the model-facing
+  schema projection drops it, the tool withdraws itself and logs why.
+- **`storageError` in the state payload**, reported separately from upstream API
+  failures so the panel can distinguish "the local file is unusable" from "the
+  platform API failed".
+
+### Changed
+
+- The host half is now an assembly layer over focused modules — `lib/phase.js`
+  (pricing phases + holiday calendar), `lib/window.js` (range, snapshot estimate,
+  monthly aggregation), `lib/deepseek.js` (HTTP client + parsing), `lib/validate.js`,
+  `lib/config.js`, `lib/store.js`, `lib/i18n.js`, `lib/service.js`, `lib/tool.js`.
+  `lib/index.js` went from 648 to 154 lines.
+- The test suites import the real modules; they no longer slice source text out of
+  `lib/index.js`, so refactors stop failing on "source shape" assertions.
+- The state file carries a `schemaVersion` envelope and is written atomically
+  (temp file + rename) by a serialised writer; 0.1.x files load unchanged and are
+  upgraded in place.
+- The panel polls at the host-reported `pollIntervalMs` instead of a hard-coded
+  30 s, pauses while the tab is hidden, and derives the countdown from a local
+  clock offset-corrected against the host.
+
+### Fixed
+
+- A corrupt or future-versioned state file is **quarantined** as
+  `….corrupt-<timestamp>` and reported, instead of being silently overwritten by
+  the first poll (which also made the old "fresh state" path look like data loss).
+- The panel header no longer wraps in English: the key mask and the language
+  choice moved into the settings block, and the header can no longer wrap.
+- The token card no longer claims "add a userToken" when the period's total is
+  simply `0` (which is what "today" reads just past Beijing midnight); a failing
+  usage endpoint now reports its error instead.
+
+### Tests
+
+- 42 → **123 cases** in 9 suites (phase, window, config, store, i18n, service,
+  tool, routes, package), all dependency-free Node assertions; CI runs
+  `npm run check && npm test` on a Node 20/24 matrix.
+
+## 0.1.0 — 2026-08-22 … 2026-09-29
+
+Initial plugin: total/topped-up balance from the official endpoint, period spend
+with a per-model split and the three token counters from the platform's private
+usage endpoints (account-wide, with a balance-snapshot estimate as fallback), the
+peak/off-peak (梁文峰 / 梁文谷) price reminder with Chinese statutory holidays, and a
+draggable bottom-right widget. Along the way: strict `/dsbal/*` request validation,
+a GitHub Actions test workflow, and the `dsh.bundle` declaration that lets the
+plugin manager install the package as a profile layer.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-deepseek-balance contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,267 @@
-# Temporary Holding Version
+# dsh-deepseek-balance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![test](https://github.com/OwlNjust/DSH-DeepSeek-Balance/actions/workflows/test.yml/badge.svg)](https://github.com/OwlNjust/DSH-DeepSeek-Balance/actions/workflows/test.yml)
+
+npm package: [`deepseek-balance-dsh`](https://www.npmjs.com/package/deepseek-balance-dsh) — the repository is `DSH-DeepSeek-Balance`; the unrelated npm name `dsh-deepseek-balance` belongs to a different project.
+
+Topics: [`dsh-plugin`](https://github.com/topics/dsh-plugin) · [`deepseek-harness`](https://github.com/topics/deepseek-harness) · [`deepseek`](https://github.com/topics/deepseek)
+
+> DeepSeek balance & usage monitor for **DeepSeek Harness** — a floating widget at the
+> bottom-right corner with a peak/off-peak (梁文峰 / 梁文谷) price reminder.
+>
+> **[中文](README.zh.md) · English**
+
+---
+
+**Installation is one step:** send `https://github.com/OwlNjust/DSH-DeepSeek-Balance`
+to your agent — it knows how to install this plugin. Manual steps are below.
+
+## Installation
+
+The plugin has **zero runtime dependencies** and is published on npm as
+[`deepseek-balance-dsh`](https://www.npmjs.com/package/deepseek-balance-dsh). There are two routes — a **bundle-layer** install (npm name or this
+repository) and a **manual patch-layer** install for a local checkout. **Pick exactly one per
+profile**: using both inserts the plugin id twice (see "Agent notes").
+
+### Route A (recommended): install it as a profile *bundle* (deepseek-harness ≥ 0.2.0)
+
+The package declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, so the harness
+plugin manager can install and activate it as a profile layer — **no file editing at all**.
+Either install spec works:
+
+- **npm name** (published package):
+
+  ```sh
+  dsh plugin --profile <profile> add deepseek-balance-dsh
+  ```
+
+- **Git repository** (source of truth):
+
+  ```sh
+  dsh plugin --profile <profile> add https://github.com/OwlNjust/DSH-DeepSeek-Balance
+  ```
+
+- **Desktop app**: menu bar → “Manage plugins” → enter either
+  `deepseek-balance-dsh` or `https://github.com/OwlNjust/DSH-DeepSeek-Balance`
+
+The manager adds the package to the profile's `dsh.profile.bundles`, and the `cordis.patch.yml`
+shipped inside the package (it carries the `insert` row that activates the plugin) is applied as
+a bundle layer. After a reload/restart the bottom-right widget appears.
+
+### Route B: local checkout + the profile's patch layer (offline / source debugging)
+
+```sh
+# 1. Clone or copy the repository anywhere
+git clone https://github.com/OwlNjust/DSH-DeepSeek-Balance.git /tmp/dsh-deepseek-balance
+
+# 2. Install it into the web profile (file: = snapshot; link: = live symlink)
+cd ~/.dsh/profiles/web
+dsh plugin --profile web add link:/tmp/dsh-deepseek-balance
+```
+
+3. Append this block to `~/.dsh/profiles/web/cordis.patch.yml` (the profile's
+   user patch layer):
+
+```yaml
+- insert:
+    - id: deepseek-balance-dsh
+      name: deepseek-balance-dsh
+```
+
+4. Restart the profile:
+
+```sh
+dsh web
+```
+
+5. Verify (optional): check that the web server answers
+
+```sh
+curl -s http://127.0.0.1:3080/dsbal/state
+```
+
+and that the bottom-right widget appears after a hard page refresh
+(Ctrl+Shift+R). Have the user click the widget → **配置** → paste their
+DeepSeek **API key** (and, optionally, the platform **userToken**) → **保存**.
+
+### Agent notes
+
+- The npm package is **`deepseek-balance-dsh`**. Do not publish under the repository name
+  `dsh-deepseek-balance`: that name is held by an unrelated project on npm.
+- **Do not mix the routes**: route A already inserts the plugin row from the bundle layer, so
+  also appending the same `insert` row by hand inserts the plugin id twice (cordis collapses
+  rows that share an id into one, so this **fails silently** — it only leaves a duplicate row
+  in the composed tree, which is easy to misread later). When switching, make sure only
+  `dsh.profile.bundles` or the profile's `cordis.patch.yml` carries it. One-line self-check —
+  the result must be `1`:
+
+  ```sh
+  dsh --profile web --dump-config | grep -c 'id: deepseek-balance-dsh'
+  ```
+
+  If it prints `2`, delete the hand-written block from `cordis.patch.yml` (keep the package in
+  `dsh.profile.bundles`, the bundle layer is maintained by the plugin manager) and restart
+  `dsh web`. To switch the other way, remove the package from `dsh.profile.bundles` first.
+- Configuration and balance history are stored in `~/.deepseek-balance.json`
+  (mode 0600) — never echo its contents.
+- Uninstall: remove the row from `cordis.patch.yml`, delete
+  `~/.dsh/profiles/web/node_modules/deepseek-balance-dsh`, restart `dsh web`.
+
+## Requirements
+
+- A DeepSeek Harness deployment with the **web profile** (`dsh web`); Node.js ≥ 20
+  (adapted and verified on **v0.1.2-rc.1**, re-checked up to **v0.2.0-rc.2** — it has
+  worked unchanged across all four versions).
+- A DeepSeek **API key** (platform.deepseek.com → API keys).
+- Optional: platform **userToken** (platform.deepseek.com → DevTools → Application →
+  Local Storage) for exact cost/token stats. Without it, consumption falls back
+  to balance-snapshot estimates.
+
+## Features
+
+- **Balance** — total and topped-up balance via the official `GET /user/balance`, polled every 5 min.
+- **Period consumption** — today / 24h / 7d / custom start date, with per-model breakdown (`/usage/cost`).
+- **Token usage** — cache-hit input / cache-miss input / output, identical to the platform dashboard (`/usage/amount`).
+- **Price window reminder** — 🔴 **梁文峰** (peak: Beijing Mon–Fri 09:00–12:00 & 14:00–18:00,
+  **excluding Chinese statutory holidays**, ×2 price) vs 🟢 **梁文谷** (off-peak: everything else,
+  **including weekends and statutory holidays all day**, 50% price), live countdown,
+  red highlight during peak and a 🎉 badge on holidays. The price windows follow the
+  [official pricing docs](https://api-docs.deepseek.com/zh-cn/quick_start/pricing).
+- **Draggable placement** — **right-click press-and-drag** the pill to move it anywhere;
+  the position is remembered automatically (left click simply expands the panel).
+  Right-clicking the pill never opens the browser menu (the pill is a drag handle by design).
+  The expanded panel auto-fits the viewport edges, and the pill is clamped back into view
+  after window resizes. A「重置位置（右下角）」button at the panel bottom restores the
+  default bottom-right position.
+
+## Usage
+
+| Thing | Where |
+| --- | --- |
+| API key / userToken | widget → 配置 |
+| Time window | widget chips (今天 / 24h / 7天 / custom) |
+| Refresh | 刷新 button (or automatic, at the configured `pollIntervalMs` — 5 min by default; paused while the tab is hidden) |
+| Language | follows the host's preference, else the browser's; the `EN/中` button in the panel header switches manually (remembered locally) |
+| Pill summary | bottom-right: current price window + balance + period spend |
+
+## Architecture
+
+```
+host lib/index.js       assembly only: validate config → build store/service → register four
+                        authenticated routes → poll on a timer
+  ├─ lib/service.js     the operations (getState / refresh / setConfig / setWindow / poll)
+  ├─ lib/config.js      tunables + DEFAULTS validation (a profile `config:` replaces wholesale)
+  ├─ lib/store.js       state file: atomic write (temp file + rename), serialised, schemaVersion
+  │                     envelope, quarantines a corrupt file instead of losing it
+  ├─ lib/deepseek.js    balance/usage HTTP client (browser-ish headers, 15 s timeout) + parsing
+  ├─ lib/phase.js       peak/off-peak phases + the statutory-holiday calendar
+  ├─ lib/window.js      window range, snapshot estimation, daily cost/token aggregation
+  ├─ lib/validate.js    /dsbal/* request validation (fromMs bounds, credential length/shape)
+  └─ lib/i18n.js        reads the host's language preference
+client lib/client.js   window.__ModuleLoader__ artifact: the shell.overlay widget + zh/en copy
+```
+
+**Authentication**: all four `/dsbal/*` routes pass the host's own gate first —
+`ctx.connection.admit(req)`, the same Host/Origin trust fence and browser-cookie
+authentication the `/api` channel uses. A request without a session cookie gets
+**401**, a cross-site request **403**, a wrong method **405**, and a malformed body
+**400 with no state change**. The credential-writing route is reachable only from the
+authenticated local browser.
+
+## Configuration
+
+Override fields per entry id in the profile's patch layer (`config:` replaces the whole
+object, so unlisted fields fall back to the defaults):
+
+```yaml
+- id: deepseek-balance-dsh
+  config:
+    pollIntervalMs: 900000     # poll cadence, 30s .. 24h, default 5 min
+    historyDays: 180           # snapshot retention / custom-window cap, 1 .. 400, default 90
+    usageTtlMs: 1800000        # successful usage-response cache, 1min .. 24h, default 1 h
+    usageErrorTtlMs: 600000    # failed usage-response cache, 1min .. 24h, default 10 min
+    maxSnapshots: 5000         # snapshot cap, 100 .. 100000
+    requestTimeoutMs: 15000    # per-request timeout, 1s .. 120s
+```
+
+The endpoints (`balanceUrl` / `usageCostUrl` / `usageAmountUrl`) are overridable too and
+must be https. An invalid value **fails activation naming the field** instead of falling
+back silently.
+
+## Model access (read-only agent tool)
+
+The plugin registers one read-only tool through an optional injection, so a profile
+without a tool runtime still activates the widget:
+
+| Tool | Parameters | Returns |
+| --- | --- | --- |
+| `deepseek_balance` | `window` (`today`\|`24h`\|`7d`\|`custom`, optional), `fromMs` (epoch ms, only with `custom`) | current price phase, balance, the period's spend and token counters, configuration state and the last error |
+
+It is **read-only by construction**: the tool can only reach `service.getState({ window })`,
+which projects a window without persisting it — asking for `7d` does not change the
+widget's selection, and the credential-writing `setConfig()` is not reachable from it
+at all. Tool output is English (it is a model interface, not UI copy) while the panel
+stays bilingual.
+
+`defineTool()` lives in `@deepseek-ai/dsh-tools`, which a zero-dependency package — and
+this profile — cannot resolve, so the definition is hand-built from what a raw
+registration is consumed for (`name`, `description`, a full JSON-Schema `parameters`,
+`output.schema`/`output.render`, `execute`). Registration runs inside a try/catch with an
+activation self-check: if the definition no longer satisfies the runtime (registration
+throws) or no longer reaches the model-facing projection (`tools.schemas()` omits it), the
+tool withdraws itself and logs why — it can never break the widget or prompt assembly.
+Verified on an isolated instance: `read-only agent tool deepseek_balance ready
+(visible=true, projected=true)`. A live model turn invoking it is the one step that needs
+an agent session (and therefore a provider credential), so it is not covered by the
+automated checks.
+
+## Notes
+
+- `/usage/cost` and `/usage/amount` are **private** platform-dashboard endpoints
+  (not in the public docs) and may change; the plugin degrades to estimates
+  automatically. Usage figures are **account-wide** — the platform API does not
+  filter by API key.
+- A `userToken` expires naturally; usage may lag by up to 1 hour (memory cache);
+  the 刷新 button clears it.
+- Keys are stored unencrypted in `~/.deepseek-balance.json` (0600) — never share it.
+- The state file carries a `schemaVersion` envelope and is written **atomically**
+  (temp file + rename) with serialised writers. A corrupt or future-versioned file is
+  **renamed aside** to `….corrupt-<timestamp>`, the plugin starts from empty state, and
+  the panel shows why — nothing is silently discarded.
+- Statutory holidays come from the **annual State Council notice** and are currently
+  bundled for **2026**. After the new year the plugin must be updated to know the next
+  year's holidays; an unlisted year is flagged「节假日数据待更新」and judged as plain
+  Mon–Fri until then.
+
+## Contributing
+
+Issues and PRs welcome (peak-hour threshold alerts, per-model filtering, more locales…).
+Keep `lib/client.js` in the `window.__ModuleLoader__` artifact format.
+
+Run `npm test` (**123 cases**, zero-dependency Node assertions) after touching any module:
+
+| Suite | Cases | Covers |
+| --- | --- | --- |
+| `test/phase.test.mjs` | 28 | weekday/weekend/holiday phases, merged holiday runs, unlisted-year fallback |
+| `test/window.test.mjs` | 14 | Beijing midnight boundaries, snapshot estimate (top-ups excluded), multi-month/year ranges, per-model and token totals |
+| `test/config.test.mjs` | 6 | defaults, wholesale-replacement semantics, unknown fields, range and https validation |
+| `test/store.test.mjs` | 9 | atomic write, serialised writers, mode 0600, corrupt/foreign-file quarantine, diagnosable save failure |
+| `test/i18n.test.mjs` | 5 | BCP 47 normalisation, `settings.describe()` read, safe degradation |
+| `test/service.test.mjs` | 13 | poll/refresh/setConfig/setWindow/getState with an injected HTTP layer (no network) |
+| `test/tool.test.mjs` | 9 | tool definition shape, read-only guarantee (no write call, no key fragment), schema-valid output, argument bounds, English render |
+| `test/routes.test.mjs` | 18 | validation bounds: bad id, non-JSON, wrong type, `fromMs` range, length, key shape |
+| `test/package.test.mjs` | 21 | name/exports, a single `insert` row, client artifact and copy table, non-regression of the auth gate |
+
+CI (`.github/workflows/test.yml`) runs `npm run check` + `npm test` on a Node 20/24 matrix.
+Changing the **client artifact format** (`window.__ModuleLoader__.load` + `exports.inject`),
+the **auth gate**, the **state-file format**, the **tool definition** or the **phase
+algorithm** means updating the matching suite; the phase algorithm and the copy table both have structural guards
+(no Chinese literal outside the table, one-to-one zh/en keys).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) — current **plugin** release **0.2.0** (not to be confused with the harness version mentioned above).
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,237 @@
+# dsh-deepseek-balance
+
+[![test](https://github.com/OwlNjust/DSH-DeepSeek-Balance/actions/workflows/test.yml/badge.svg)](https://github.com/OwlNjust/DSH-DeepSeek-Balance/actions/workflows/test.yml)
+
+npm 包名：[`deepseek-balance-dsh`](https://www.npmjs.com/package/deepseek-balance-dsh) —— 仓库名为 `DSH-DeepSeek-Balance`；
+npm 上的 `dsh-deepseek-balance` 是**另一个无关项目**，与本插件无关。
+
+主题：[`dsh-plugin`](https://github.com/topics/dsh-plugin) · [`deepseek-harness`](https://github.com/topics/deepseek-harness) · [`deepseek`](https://github.com/topics/deepseek)
+
+> DeepSeek Harness 的 DeepSeek 余额与用量实时监控插件 —— 右下角悬浮小组件，
+> 附高峰/空闲时段（梁文峰 / 梁文谷）价格提醒。
+>
+> 中文 · **[English](README.md)**
+
+---
+
+**安装只需一步：** 把 `https://github.com/OwlNjust/DSH-DeepSeek-Balance`
+发给您的 agent，它就知道如何自动安装本插件。手动安装步骤如下。
+
+## 安装
+
+本插件**零运行时依赖**，已发布到 npm：[`deepseek-balance-dsh`](https://www.npmjs.com/package/deepseek-balance-dsh)。
+提供两条安装路线——**组合层安装**（npm 包名或本仓库）与**补丁层安装**（本地克隆，改源码调试用）。
+**同一 profile 只能选一条**：两条都用会让插件 id 被插入两次（见「agent 注意事项」）。
+
+### 路线 A（推荐）：作为「组合包」安装（deepseek-harness ≥ 0.2.0）
+
+本包声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`，所以 harness 的插件管理器
+可以直接把它当作组合包（profile 层）安装并自动激活——**无需手改任何文件**。两种装法等价：
+
+- **npm 包名**（已发布）：
+
+  ```sh
+  dsh plugin --profile <profile> add deepseek-balance-dsh
+  ```
+
+- **Git 仓库**（源码为准）：
+
+  ```sh
+  dsh plugin --profile <profile> add https://github.com/OwlNjust/DSH-DeepSeek-Balance
+  ```
+
+- **桌面端**：菜单栏 →「管理插件 / Manage plugins」→ 填入
+  `deepseek-balance-dsh` 或 `https://github.com/OwlNjust/DSH-DeepSeek-Balance`
+
+管理器会把包加入 profile 的 `dsh.profile.bundles`，包内的 `cordis.patch.yml`（含激活插件的
+`insert` 行）随之作为组合层生效。重载/重启 profile 后右下角即出现小组件。
+
+### 路线 B：本地克隆 + 用户补丁层（离线 / 改源码调试用）
+
+```sh
+# 1. 克隆/复制仓库到任意可访问路径
+git clone https://github.com/OwlNjust/DSH-DeepSeek-Balance.git /tmp/dsh-deepseek-balance
+
+# 2. 安装到 web profile（file: = 快照；link: = 源码符号链接，改代码即生效）
+cd ~/.dsh/profiles/web
+dsh plugin --profile web add link:/tmp/dsh-deepseek-balance
+```
+
+3. 把下面这段**追加**到 `~/.dsh/profiles/web/cordis.patch.yml`（profile 的用户补丁层）：
+
+```yaml
+- insert:
+    - id: deepseek-balance-dsh
+      name: deepseek-balance-dsh
+```
+
+4. 重启 profile：
+
+```sh
+dsh web
+```
+
+5. 可选验证：确认 web 服务器响应
+
+```sh
+curl -s http://127.0.0.1:3080/dsbal/state
+```
+
+强制刷新页面（Ctrl+Shift+R）后右下角出现小组件。让用户点击小组件 → 「配置」→
+粘贴 DeepSeek **API key**（可选再填平台 **userToken**）→「保存」。
+
+### agent 注意事项
+
+- npm 包名是 **`deepseek-balance-dsh`**；**不要**用仓库名 `dsh-deepseek-balance` 发布——该名字在 npm 上属于一个无关项目。
+- **两条路线别混用**：路线 A 已由组合层插入插件行，若再手工追加同一 `insert` 行，插件 id 会被
+  插入两次（cordis 按 id 折叠成一份，所以**不会报错**，只是组合树里多出一行、日后极易误判）。
+  切换路线时先确认 `dsh.profile.bundles` 与 profile 的 `cordis.patch.yml` 只有一边生效；
+  一条命令自检，结果必须是 `1`：
+
+  ```sh
+  dsh --profile web --dump-config | grep -c 'id: deepseek-balance-dsh'
+  ```
+
+  若输出 `2`：删掉 `cordis.patch.yml` 里手写的那段（保留 `dsh.profile.bundles` 里的包，
+  组合层交给插件管理器维护），重启 `dsh web` 生效。反向切换（改回手写行）则先从
+  `dsh.profile.bundles` 移除本包。
+- 配置与余额历史保存在 `~/.deepseek-balance.json`（0600），**切勿回显其内容**。
+- 卸载：删除 `cordis.patch.yml` 中的行、删除
+  `~/.dsh/profiles/web/node_modules/deepseek-balance-dsh`，重启 `dsh web`。
+
+## 前置条件
+
+- deepseek-harness 的 **web profile**（`dsh web`）；Node.js ≥ 20
+  （本插件在 **v0.1.2-rc.1** 上适配验证，并已复检至 **v0.2.0-rc.2**，四个版本零改动可用）。
+- DeepSeek **API Key**（platform.deepseek.com → API keys）。
+- 可选：平台 **userToken**（platform.deepseek.com → F12 → Application → Local Storage），
+  用于精确统计消耗/Token；未配置时自动回退为余额快照估算。
+
+## 功能
+
+- **余额** —— 总余额 / 充值余额，官方 `GET /user/balance`，每 5 分钟刷新。
+- **时间段消耗** —— 今天 / 近24小时 / 近7天 / 自定义起始日期，含按模型明细（`/usage/cost`）。
+- **Token 消耗** —— 输入（命中缓存）/ 输入（未命中缓存）/ 输出，与平台用量页一致（`/usage/amount`）。
+- **价格时段提醒** —— 🔴 **梁文峰**（高峰：北京时间周一至周五 09:00–12:00 与 14:00–18:00，
+  **不含中国法定节假日**，价格 ×2）与 🟢 **梁文谷**（空闲：其余时段，**含周末与法定节假日全天**，半价），
+  实时倒计时，高峰红色高亮，法定节假日显示 🎉 标识。
+  时段依据[官方定价文档](https://api-docs.deepseek.com/zh-cn/quick_start/pricing)。
+- **中英双语** —— 界面文案集中于 `lib/client.js` 的文案表；语言跟随宿主设置 → 浏览器语言，
+  面板内可一键切换；插件卡片标题/描述见 `locale/zh.json`、`locale/en.json`，图标 `icon.svg`。
+- **可拖动定位** —— **右键**按住药丸拖动即可移到任意位置，位置自动记忆；左键只负责点击展开面板。
+  药丸上右键不弹浏览器菜单（药丸即拖拽手柄）；展开面板时自动避让屏幕边缘，
+  窗口缩放后药丸也会自动夹回可视区域。面板底部提供「重置位置（右下角）」按钮，
+  一键恢复默认位置。
+
+## 使用
+
+| 项目 | 位置 |
+| --- | --- |
+| API Key / userToken | 小组件 → 配置 |
+| 时间窗口 | 小组件按钮（今天 / 24h / 7天 / 自定义） |
+| 刷新 | 「刷新」按钮（或自动：按配置的 `pollIntervalMs`，默认 5 分钟；标签页隐藏时暂停） |
+| 语言 | 跟随宿主设置的语言 → 否则浏览器语言；面板标题栏的 `EN/中` 按钮可手动切换（记忆在本机） |
+| 药丸摘要 | 右下角：当前价格时段 + 余额 + 时段消耗 |
+
+## 架构
+
+```
+宿主 lib/index.js      仅装配：config 校验 → 建 store/service → 注册四条已认证路由 → 定时轮询
+  ├─ lib/service.js    操作实现（getState / refresh / setConfig / setWindow / poll）
+  ├─ lib/config.js     可调项 DEFAULTS + 校验（profile 的 config: 覆盖，整体替换语义）
+  ├─ lib/store.js      状态文件：原子写（临时文件 + rename）、串行化、schemaVersion 信封、损坏隔离
+  ├─ lib/deepseek.js   余额/用量 HTTP 客户端（浏览器头 + 15s 超时）与载荷解析
+  ├─ lib/phase.js      时段/法定节假日算法（梁文峰/梁文谷）
+  ├─ lib/window.js     窗口区间、快照估算、按天聚合计费与 Token
+  ├─ lib/validate.js   /dsbal/* 请求校验（含 fromMs 范围、凭据长度与 key 形态）
+  └─ lib/i18n.js       读取宿主语言偏好
+客户端 lib/client.js   window.__ModuleLoader__ 产物：shell.overlay 悬浮小组件 + 文案表（zh/en）
+```
+
+**认证**：四条 `/dsbal/*` 路由都先过宿主自己的门禁 `ctx.connection.admit(req)`
+（与 `/api` 通道同一套 Host/Origin 信任栅栏 + 浏览器 cookie 认证）。
+未携带会话 cookie 的请求返回 **401**，跨源请求返回 **403**，方法不符返回 **405**，
+非法请求体返回 **400 且不改动任何状态**。写入凭据的接口只对已登录的本机浏览器开放。
+
+## 配置
+
+在 profile 的补丁层按 entry id 覆盖（`config:` 是**整体替换**，未写的字段回落默认值）：
+
+```yaml
+- id: deepseek-balance-dsh
+  config:
+    pollIntervalMs: 900000     # 轮询周期，30s ~ 24h，默认 5 分钟
+    historyDays: 180           # 余额快照保留天数 / 自定义窗口上限，1 ~ 400，默认 90
+    usageTtlMs: 1800000        # 用量接口成功缓存，1min ~ 24h，默认 1 小时
+    usageErrorTtlMs: 600000    # 用量接口失败缓存，1min ~ 24h，默认 10 分钟
+    maxSnapshots: 5000         # 快照条数上限，100 ~ 100000
+    requestTimeoutMs: 15000    # 单次请求超时，1s ~ 120s
+```
+
+后端地址（`balanceUrl` / `usageCostUrl` / `usageAmountUrl`）也可覆盖，必须是 https。
+任何非法值都会**让插件激活失败并打印字段名**，而不是静默用默认值。
+
+## 模型访问（只读 agent tool）
+
+插件通过**可选注入**注册一个只读工具（没有 tool 运行时的 profile 仍能正常激活小组件）：
+
+| 工具 | 参数 | 返回 |
+| --- | --- | --- |
+| `deepseek_balance` | `window`（`today`/`24h`/`7d`/`custom`，可选）、`fromMs`（毫秒时间戳，仅 `custom` 用） | 当前价格时段、余额、该时段消耗与 Token 三类计数、配置状态、最近一次错误 |
+
+**只读是结构保证**：工具只能触达 `service.getState({ window })`——它按参数**投影**一个窗口，
+不落盘、不改动界面当前选择；写入凭据的 `setConfig()` 从工具里根本不可达。
+工具输出为英文（面向模型，不是 UI 文案），面板保持中英双语。
+
+`defineTool()` 位于 `@deepseek-ai/dsh-tools`，零依赖插件（以及本 profile）解析不到，
+因此该定义是**按裸注册真正被消费的字段**手写的（`name`/`description`/完整 JSON Schema 的
+`parameters`/`output.schema`+`output.render`/`execute`，参数校验在 `execute` 内自行完成）。
+注册包在 try/catch 里并带**启动自检**：若定义不再满足运行时（注册抛错），或不再进入
+模型侧 schema 投影（`tools.schemas()` 里没有它），工具会自我撤下并打印原因——
+它永远不会拖垮小组件或系统提示的组装。已在隔离实例实测：
+`read-only agent tool deepseek_balance ready (visible=true, projected=true)`。
+**唯一未覆盖的一步**是"真实模型回合实际调用它"（需要带凭据的 agent 会话），故不在自动化检查内。
+
+## 注意事项
+
+- `/usage/cost` 与 `/usage/amount` 是**平台私有**控制台接口（不在公开文档中），可能变化；
+  不可用时自动回退估算。数据为**账号整体**统计——平台接口不支持按 API Key 筛选。
+- userToken 会自然过期；用量数据最多滞后 1 小时（内存缓存），点「刷新」立即更新。
+- 密钥明文保存于 `~/.deepseek-balance.json`（0600），请勿泄露。
+- 状态文件带 `schemaVersion` 信封并**原子写入**（临时文件 + rename），写入串行化；
+  若文件损坏或版本高于插件，插件会把它**改名隔离**为 `…​.corrupt-<时间戳>`、
+  从空状态启动，并在面板上显示原因——不会静默丢数据。
+- 法定节假日按**国务院办公厅年度通知**内置（当前收录 **2026 年**）。跨年后需更新插件才能
+  识别次年节假日；未收录的年份会标注「节假日数据待更新」并暂按普通周一至周五判定。
+
+## 贡献
+
+欢迎 Issue / PR（高峰阈值提醒、按模型筛选、多语言等）。
+请保持 `lib/client.js` 的 `window.__ModuleLoader__` 产物格式。
+
+改动任何模块后请跑 `npm test`（**123 项**，全部是零依赖的 Node 内置断言）：
+
+| 套件 | 项数 | 覆盖 |
+| --- | --- | --- |
+| `test/phase.test.mjs` | 28 | 时段算法：工作日/周末/法定节假日/跨节日合并段/未收录年份回退 |
+| `test/window.test.mjs` | 14 | 北京日界、快照估算（充值不计消耗）、跨月/跨年区间、按模型与 Token 汇总 |
+| `test/config.test.mjs` | 6 | 默认值、整体替换语义、未知字段、范围与 https 校验 |
+| `test/store.test.mjs` | 9 | 原子写、串行写者、权限 0600、损坏/未来版本隔离、写失败可诊断 |
+| `test/i18n.test.mjs` | 5 | BCP 47 归一化、settings.describe() 读取与安全退化 |
+| `test/service.test.mjs` | 13 | poll/refresh/setConfig/setWindow/getState（注入假 HTTP，无网络） |
+| `test/tool.test.mjs` | 9 | 工具定义形状、只读保证（无写调用、不含 key 片段）、结果满足自身 schema、参数边界、英文渲染 |
+| `test/routes.test.mjs` | 18 | 请求校验与边界（非法 id/非 JSON/类型错/fromMs 范围/长度/key 形态） |
+| `test/package.test.mjs` | 21 | 包名与导出、组合层只有一行 insert、客户端产物与文案表、认证门禁不可回归 |
+
+CI（`.github/workflows/test.yml`）在 Node 20/24 矩阵上跑 `npm run check` + `npm test`。
+改动**客户端产物格式**（`window.__ModuleLoader__.load` + `exports.inject`）、
+**认证门禁**、**状态文件格式**、**工具定义**或**时段算法**时，必须同步更新对应套件；
+时段算法与客户端文案表都有结构性断言兜底（表外中文字面量、zh/en 键一一对应）。
+
+## 变更记录
+
+见 [CHANGELOG.md](CHANGELOG.md)（当前**插件**版本 **0.2.0**，与上文提到的 harness 版本无关）。
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# deepseek-balance-dsh composition rows.
+#
+# This file is the package's own BUNDLE PATCH: package.json declares
+#   "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
+# so a harness that manages this package as a profile bundle (plugin manager UI,
+# desktop app, or `dsh plugin --profile <p> add <git-url>`) applies the block
+# below automatically — no hand editing.
+#
+# Manual install (local checkout / development, no bundle management):
+#   cd ~/.dsh/profiles/<p>
+#   dsh plugin --profile <p> add file:../<path-to>/<checkout>   # or: add deepseek-balance-dsh
+# then append the `insert` block below to ~/.dsh/profiles/<p>/cordis.patch.yml
+# (the profile's user patch layer) and restart the profile.
+# Pick ONE route per profile: bundle management already applies this file, so
+# also appending the row by hand would insert the plugin id twice.
+#
+# A single row activates both halves: the host plugin (polling, state file,
+# /dsbal/* routes) and, because the package declares `dsh.client`, the browser
+# roster entry (the bottom-right widget).
+- insert:
+    - id: deepseek-balance-dsh
+      name: deepseek-balance-dsh