dsh-deepseek-balance-widget 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dsh-deepseek-balance-widget 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

@@ -0,0 +1,118 @@
+# dsh-deepseek-balance-widget
+
+在 DeepSeek Harness（dsh）Web 侧边栏显示 DeepSeek 余额的小插件：实时展示**余额 / 今日消费 / 今日Token**，点击弹出详情（累计消费、本月消耗、API 请求次数、Tokens），每 30 秒自动刷新。
+
+> 本插件完全运行在你自己的机器上：余额和用量由 **dsh 宿主端**用**你本机的凭据**（`~/.dsh/.credentials.yaml` 或环境变量）向 DeepSeek 官方接口实时查询。代码中**不内置任何 API Key / Token / 个人数据**，所以**每个人看到的都是自己的余额**，互不可见。
+
+## 功能
+
+- 侧边栏常驻按钮：`余额`、`今日消费`、`今日Token` 三个数值，30 秒自动刷新
+- 点击弹出详情卡片：
+  - 余额（`$`，来自 `api.deepseek.com/user/balance`）
+  - 累计消费（全部时间，来自平台用量接口按月累加）
+  - 今日消费 / 今日Token（平台实时接口，按 GMT+8 当日统计）
+  - 本月消耗：本月消费、API 请求次数、Tokens
+- 未配置平台 Token 时，余额照常显示，用量区域显示中性提示（不展示任何人的历史快照）
+- 深色主题，跟随 dsh 侧边栏样式；自动适配官方皮肤与 Maid-atelier 等第三方皮肤
+
+## 工作原理（隐私说明）
+
+```
+浏览器 (dsh web 前端)  ──GET /deepseek-balance──▶  dsh 宿主端（你自己的机器）
+                                                    │
+                                                    ├─ 读取本机 ~/.dsh/.credentials.yaml 的
+                                                    │   DEEPSEEK_API_KEY / DEEPSEEK_PLATFORM_TOKEN
+                                                    │   （或环境变量），绝不硬编码
+                                                    ▼
+                                          api.deepseek.com / platform.deepseek.com
+                                                    │
+                                                    ◀── 返回「你这个账号」的余额与用量
+```
+
+- 余额数据来自 DeepSeek 官方余额接口 `GET https://api.deepseek.com/user/balance`
+- 用量统计来自平台接口（需要 `userToken`），见下方配置说明
+- 请求全部由宿主端发起（服务端到服务端），浏览器端不接触任何密钥
+
+## 环境要求
+
+- DeepSeek Harness（`dsh`）已安装并可用 `dsh web`
+- Node.js ≥ 18（全局 `fetch`）
+- pnpm（`dsh plugin` 内部转发给 pnpm）
+
+## 安装
+
+插件托管在 GitHub，包名 **`dsh-deepseek-balance-widget`**。一条命令安装（GitHub 直装）：
+
+```bash
+dsh plugin --profile web add github:crazy-L118/dsh-deepseek-balance-widget
+```
+
+安装成功后 dsh 会**自动把该包注册进 `dsh.profile.bundles`**（已实测验证），**无需手动改任何配置文件**。本包**没有构建脚本**，pnpm 不会拦截（无需在 `pnpm-workspace.yaml` 的 `allowBuilds` 里批准）。
+
+完成后**重启 `dsh web`**，侧边栏出现余额按钮即可。
+
+> 旧版 dsh（不含自动注册机制）或绕过 `dsh plugin` 直接 `pnpm/npm install` 时，才需要手动在 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 末尾加入 `"dsh-deepseek-balance-widget"`。
+
+### 🤖 让 AI 帮你装（GitHub 版）
+
+2026年了，你有 Agent，让它自己装。打开 DeepSeek Harness，把下面这句丢给它：
+
+> 帮我安装 dsh-deepseek-balance-widget 插件：https://github.com/crazy-L118/dsh-deepseek-balance-widget
+
+AI 会自动完成：获取仓库（git clone，git 不可用时用系统下载工具取 zip）→ 运行仓库里的安装脚本（自动装插件 + 注册 bundles）→ 提醒你重启。
+
+## 配置凭据（关键一步）
+
+编辑 `~/.dsh/.credentials.yaml`：
+
+```yaml
+DEEPSEEK_API_KEY: sk-xxxxxxxxxxxxxxxx
+DEEPSEEK_PLATFORM_TOKEN: xxxxxxxxxxxxxxxx   # 可选，见下
+```
+
+> 如果你本来就在用 DeepSeek API（dsh 里已经能跑对话），`DEEPSEEK_API_KEY` 通常已经配置好了，余额部分**开箱即用**。
+
+| 凭据 | 必填 | 用途 | 获取方式 |
+|---|---|---|---|
+| `DEEPSEEK_API_KEY` | ✅ | 余额 | [platform.deepseek.com](https://platform.deepseek.com) → API Keys |
+| `DEEPSEEK_PLATFORM_TOKEN` | ⭕ 可选 | 用量统计（累计/本月/今日消费、请求次数、Tokens） | 登录 [platform.deepseek.com](https://platform.deepseek.com) → 按 `F12` → `Application` → `Cookies` → 复制 `userToken` 的值 |
+
+未配置 `DEEPSEEK_PLATFORM_TOKEN` 时：余额正常显示，今日消费 / 今日Token 显示 `—`，用量区块显示配置提示。
+
+> ⚠️ `userToken` 等同于你的平台登录会话，请勿提交到 Git 或分享给他人。
+
+## 使用
+
+1. 重启 `dsh web`。
+2. 左侧边栏（或底部设置栏旁）会出现余额按钮，显示 `余额 / 今日消费 / 今日Token`。
+3. 点击按钮查看详情卡片，卡片右下角有「刷新」按钮，或等待 30 秒自动刷新。
+
+## 卸载
+
+```bash
+dsh plugin --profile web rm dsh-deepseek-balance-widget
+```
+
+dsh 会自动从 `dsh.profile.bundles` 移除该层；若还残留（旧版 dsh），手动删除 `~/.dsh/profiles/web/package.json` 中 `dependencies` 与 `dsh.profile.bundles` 里的同名条目。
+
+## 常见问题
+
+- **侧边栏没出现按钮？** 确认 `dsh web` 已重启；不同皮肤下按钮会出现在侧边栏或底部工具栏，插件会自动寻找合适位置。
+- **余额显示「失败」？** 检查 `DEEPSEEK_API_KEY` 是否有效、机器能否访问 `api.deepseek.com`；在弹窗的错误行能看到原因。
+- **用量一直显示提示？** `DEEPSEEK_PLATFORM_TOKEN` 未配置或已过期（平台会话有时效，过期后重新登录复制新值）。
+
+## 开发
+
+- 宿主端：`lib/index.js`（cordis 插件，注册 `/deepseek-balance`、`/deepseek-usage` 两个路由）
+- 客户端：`lib/client.js`（注入 web 前端，挂载侧边栏小组件）
+- 修改后重新执行安装命令并重启 `dsh web` 生效（或本地调试时用 `dsh plugin --profile web add "file:<仓库路径>"`）
+
+## 免责声明
+
+- 本项目与 DeepSeek 官方无任何关联，非官方产品。
+- 用量统计使用 DeepSeek 平台的内部接口，可能随平台改版而失效，属尽力而为。
+- 请遵守 [DeepSeek 平台服务条款](https://platform.deepseek.com/terms) 与 API 使用政策。
+
+## License
+
+[MIT](LICENSE)

package/README_EN.md

@@ -0,0 +1,118 @@
+# dsh-deepseek-balance-widget
+
+A small plugin that shows your DeepSeek balance in the DeepSeek Harness (dsh) web sidebar: live **balance / today spend / today tokens**, click to open a detail card (cumulative spend, monthly usage, request count, tokens), auto-refreshed every 30 seconds.
+
+> This plugin runs entirely on your own machine: the dsh host resolves **your local credentials** (`~/.dsh/.credentials.yaml` or environment variables) and queries the official DeepSeek APIs server-side. No API key / token / personal data is bundled in the code, so **every user sees only their own balance**.
+
+## Features
+
+- Persistent sidebar widget: `余额` (balance), `今日消费` (today spend), `今日Token` (today tokens), auto-refresh every 30 s
+- Click for a detail card:
+  - Balance (`$`, from `api.deepseek.com/user/balance`)
+  - Cumulative spend (all time, summed per month from the platform usage API)
+  - Today spend / today tokens (platform realtime API, GMT+8 day buckets)
+  - Current-month usage: spend, API request count, tokens
+- When the platform token is not configured, the balance still works and the usage area shows a neutral hint (never anyone's historical snapshot)
+- Dark theme matching the dsh sidebar; adapts to official skins and third-party skins like Maid-atelier
+
+## How it works (privacy)
+
+```
+Browser (dsh web frontend)  ──GET /deepseek-balance──▶  dsh host (your machine)
+                                                       │
+                                                       ├─ reads DEEPSEEK_API_KEY / DEEPSEEK_PLATFORM_TOKEN
+                                                       │   from local ~/.dsh/.credentials.yaml (or env),
+                                                       │   never hardcoded
+                                                       ▼
+                                             api.deepseek.com / platform.deepseek.com
+                                                       │
+                                                       ◀── returns balance & usage of YOUR account
+```
+
+- Balance comes from the official endpoint `GET https://api.deepseek.com/user/balance`
+- Usage stats come from the platform endpoints (requires `userToken`), see configuration below
+- All requests are made by the host (server-to-server); the browser never touches any secret
+
+## Requirements
+
+- DeepSeek Harness (`dsh`) with `dsh web` working
+- Node.js ≥ 18 (global `fetch`)
+- pnpm (`dsh plugin` forwards to pnpm internally)
+
+## Install
+
+The plugin is hosted on GitHub as **`dsh-deepseek-balance-widget`**. Install with a single command (GitHub):
+
+```bash
+dsh plugin --profile web add github:crazy-L118/dsh-deepseek-balance-widget
+```
+
+After a successful `dsh plugin` install, dsh **automatically registers the package in `dsh.profile.bundles`** (verified end-to-end), so **no manual config editing is needed**. This package has **no build script**, so pnpm does not block it (no `allowBuilds` approval needed).
+
+Then **restart `dsh web`** — the balance button appears in the sidebar.
+
+> Only for older dsh versions (without the auto-registration mechanism) or when bypassing `dsh plugin` with raw `pnpm/npm install`: manually append `"dsh-deepseek-balance-widget"` to the `dsh.profile.bundles` array in `~/.dsh/profiles/web/package.json`.
+
+### 🤖 Let the AI install it (GitHub)
+
+You have an Agent — let it install itself. Open DeepSeek Harness and drop this sentence in:
+
+> Install the dsh-deepseek-balance-widget plugin for me: https://github.com/crazy-L118/dsh-deepseek-balance-widget
+
+The agent will fetch the repo (git clone; fall back to a zip download if git is missing), run the repo's install script (installs the plugin and registers bundles), then tell you to restart.
+
+## Configure credentials (important)
+
+Edit `~/.dsh/.credentials.yaml`:
+
+```yaml
+DEEPSEEK_API_KEY: sk-xxxxxxxxxxxxxxxx
+DEEPSEEK_PLATFORM_TOKEN: xxxxxxxxxxxxxxxx   # optional, see below
+```
+
+> If you already use the DeepSeek API in dsh, `DEEPSEEK_API_KEY` is usually already configured and the balance part works out of the box.
+
+| Credential | Required | Purpose | How to get it |
+|---|---|---|---|
+| `DEEPSEEK_API_KEY` | ✅ | Balance | [platform.deepseek.com](https://platform.deepseek.com) → API Keys |
+| `DEEPSEEK_PLATFORM_TOKEN` | ⭕ optional | Usage stats (cumulative/month/today spend, requests, tokens) | Log in to [platform.deepseek.com](https://platform.deepseek.com) → press `F12` → `Application` → `Cookies` → copy the value of `userToken` |
+
+Without `DEEPSEEK_PLATFORM_TOKEN`, the balance still shows; today spend / tokens show `—` and the usage block shows a configuration hint.
+
+> ⚠️ `userToken` is your platform login session. Never commit it to Git or share it.
+
+## Usage
+
+1. Restart `dsh web`.
+2. A balance button appears in the left sidebar (or next to the bottom Settings row) showing `余额 / 今日消费 / 今日Token`.
+3. Click it for the detail card; use the "刷新" (refresh) button or wait 30 s for auto-refresh.
+
+## Uninstall
+
+```bash
+dsh plugin --profile web rm dsh-deepseek-balance-widget
+```
+
+dsh removes the layer from `dsh.profile.bundles` automatically; if anything remains (older dsh), delete the `dsh-deepseek-balance-widget` entries from `dependencies` and `dsh.profile.bundles` in `~/.dsh/profiles/web/package.json`.
+
+## FAQ
+
+- **No button in the sidebar?** Make sure `dsh web` was restarted. On different skins the button appears in the sidebar or the bottom toolbar; the plugin finds a spot automatically.
+- **Balance shows "失败" (failed)?** Check that `DEEPSEEK_API_KEY` is valid and your machine can reach `api.deepseek.com`; the error line in the popover explains why.
+- **Usage always shows the hint?** `DEEPSEEK_PLATFORM_TOKEN` is missing or expired (platform sessions expire; log in again and copy a fresh `userToken`).
+
+## Development
+
+- Host half: `lib/index.js` (cordis plugin registering `/deepseek-balance` and `/deepseek-usage`)
+- Client half: `lib/client.js` (injected into the web frontend, mounts the sidebar widget)
+- After changes, re-run the install command and restart `dsh web` (or use `dsh plugin --profile web add "file:<repo path>"` for local iteration)
+
+## Disclaimer
+
+- Not affiliated with or endorsed by DeepSeek.
+- Usage stats rely on DeepSeek platform internal endpoints that may change at any time; best effort only.
+- Please follow the [DeepSeek Platform Terms](https://platform.deepseek.com/terms) and API usage policy.
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-deepseek-balance-widget bundle patch: inserts the balance viewer plugin
+# row into the web profile roster. Applied as a profile bundle layer (the
+# `dsh.bundle.patch` manifest field).
+- insert:
+    - id: deepseek-balance-widget
+      name: 'dsh-deepseek-balance-widget'