Q993/token-balance-plugin

dsh-token-balance · DeepSeek Token 余额查看器

面向 DeepSeek Harness (DSH) 的动态 Cordis 插件：在会话输入框下方常驻显示你的 DeepSeek 账户 API 余额（总余额 / 赠送余额 / 充值余额 / 可用状态），点击即可刷新。密钥全程只存在于 Host 进程，绝不进入浏览器。

license
platform
endpoint

目录

- 功能特性
- 效果预览
- 架构总览
- 快速开始
- 凭据配置
- API 响应格式
- 目录结构
- 常见问题
- 安全声明
- 许可证

功能特性

| 特性 | 说明 |
|---|---|
| 🪙 常驻显示 | 会话输入框下方（conversation.composer.dock 插槽）常驻余额读数条，随时可见 |
| 🔄 点击刷新 | 点击读数条即时重新查询，无需重启插件 |
| 💰 余额明细 | 悬停显示总余额、赠送余额、充值余额与可用状态 |
| 🌗 主题适配 | 使用 DSH 主题 CSS 变量（--dsw-alias-*），自动适配明暗模式 |
| 🔐 密钥安全 | API Key 只经 Host 环境变量传给本地子进程，不回显、不进浏览器、不落库 |
| 🧩 即插即用 | 读取 DSH 凭据库中已配置的 DEEPSEEK_API_KEY，无需额外设置界面 |

效果预览

在任意会话的输入框下方会出现类似这样的常驻读数条：

┌─────────────────────────────────────────────────────────┐
│  ⌨ 输入框                                                │
└─────────────────────────────────────────────────────────┘
余额 ¥110.00        ← 点击刷新；悬停显示：余额 ¥110.00 · 可用 · 赠送 ¥10.00 · 充值 ¥100.00

- 加载中：余额查询中…
- 成功：余额 ¥110.00（不可用时追加红色 不可用 标记）
- 失败：余额获取失败，点击重试（悬停可查看错误原因，如未配置凭据 / 网络错误）

架构总览

┌─────────────────────────── 浏览器（Client 半区）───────────────────────────┐
│  conversation.composer.dock（输入框下方读数条）                              │
│  └─ host.call('token-balance/query') ──┐                                    │
└────────────────────────────────────────┼───────────────────────────────────┘
▼
┌─────────────────────────── Host 半区（Node 进程）──────────────────────────┐
│  credentials.resolve('DEEPSEEK_API_KEY')  读取本机凭据库（~/.dsh/.credentials.yaml） │
│  subprocess.spawn(node)                   子进程发起 HTTPS 请求                │
│    └─ env: DSH_BALANCE_KEY（密钥仅此一处，不外泄）                             │
└────────────────────────────────────────┼───────────────────────────────────┘
▼
GET https://api.deepseek.com/user/balance
Authorization: Bearer

传输通道说明：DSH 的 web.fetch 只接受裸 URL（WebFetchRequest = { url }），无法携带 Authorization 请求头，因此本插件改走 subprocess + Node fetch：API Key 通过子进程环境变量传入，命令行参数不含任何密钥，输出仅余额数值。

快速开始

前置：DeepSeek Harness 环境（动态 Cordis 插件机制）。src/host.js 与 src/client.js 即插件的两个半区源码，将其内容分别作为 cordis_define 的 code.host / code.client 提交。

1. 在会话中向 AI 提出：创建 token 余额查看插件（引用本仓库 src 代码）
2. AI 调用 cordis_define 定义插件 → cordis_run 激活（客户端 UI 需批准）
3. 输入框下方即出现余额读数条，点击可刷新

或手动方式：

1. 将 src/host.js 内容作为 cordis_define 的 code.host
2. 将 src/client.js 内容作为 cordis_define 的 code.client
3. 调用 cordis_run 激活

凭据配置

插件读取 DSH 凭据库中名为 DEEPSEEK_API_KEY 的凭据（存放于 ~/.dsh/.credentials.yaml）：

DEEPSEEK_API_KEY: sk-xxxxxxxxxxxxxxxxxxxxxxxx

在 DSH 中配置凭据（让 AI 代为配置或手工编辑 ~/.dsh/.credentials.yaml）：

帮我配置凭据 DEEPSEEK_API_KEY 为 sk-xxxx

- 未配置凭据时，读数条显示「余额获取失败」，悬停提示 no-credential。
- 配置完成后点击读数条刷新即可。

API 响应格式

DeepSeek 官方余额接口 GET https://api.deepseek.com/user/balance（需要 Authorization: Bearer ）返回：

{
"is_available": true,
"balance_infos": [
{
"currency": "CNY",
"total_balance": "110.00",
"granted_balance": "10.00",
"topped_up_balance": "100.00"
}
]
}

插件取 balance_infos[0] 展示：currency、total_balance（总余额）、granted_balance（赠送余额）、topped_up_balance（充值余额），并以 is_available 标记账户可用状态。详见 DeepSeek API 文档。

目录结构

token-balance-plugin/
├── README.md                     # 本文件
├── LICENSE                       # MIT
├── package.json                  # 项目元信息
├── .gitignore                    # 排除凭据/依赖等
├── src/
│   ├── host.js                   # Host 半区源码（凭据解析 / subprocess 调用余额 API / RPC）
│   └── client.js                 # Client 半区源码（composer.dock 常驻余额读数条）
└── docs/

常见问题

| 问题 | 排查 |
|---|---|
| 显示「余额获取失败」且悬停提示 no-credential | 未在 DSH 凭据库配置 DEEPSEEK_API_KEY，见凭据配置 |
| 提示 no-node | 当前环境未解析到 node 可执行文件，确认 DSH 宿主具备 Node 运行时 |
| 提示 api-error / bad-response | 余额 API 返回异常（如 Key 失效、网络受限），悬停提示会给出具体信息 |
| 提示网络类错误 | DSH 宿主进程需可访问 api.deepseek.com（模型调用本身就走该域名，通常无碍） |

安全声明

- API Key 仅在本机 DSH 宿主进程内使用：经 subprocess 环境变量传给本地 Node 子进程，不进入浏览器、不出现在命令行、不写入日志、不持久化。
- 插件只向 Client 返回余额数值与可用状态等脱敏数据。
- 余额查询仅用于查看本账户配额，请遵守 DeepSeek 平台服务条款。

许可证

MIT