dsh-api-balance

Readme

# dsh-api-balance

DeepSeek Harness 插件：在 DSH Web 界面左侧边栏底部显示你的 DeepSeek API 账户余额（实时小组件），并把余额查询暴露为 `api_balance` 工具供模型在对话中汇报。

![效果示意](https://img.shields.io/badge/dsh-web--plugin-0.1.1-blue)

## 功能

- **Web 侧边栏小组件**（`sidebar.footer.action` 槽位，列表式追加，不影响其他条目）：
  - 展开侧边栏：显示 `API 余额 ¥110.00`（取第一个币种），悬停可看明细（充值 + 赠金、更新时间），点击立即刷新；
  - 收起为窄轨：只显示一个钱包图标按钮，悬停提示明细；
  - 每 20 秒自动轮询，由宿主端 60 秒缓存兜底，不会高频打 DeepSeek API。
- **`api_balance` 工具**：模型可在对话中查询并汇报余额（币种、总额、充值、赠金、更新时间）。
- **系统提示词小节**：告知模型余额小组件与工具的存在。

## 环境要求

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) `web` profile（Node.js ≥ 22.19）
- 一个可用的 DeepSeek API 密钥（见下节）

## API 密钥来源（与官方 `deepseek-official` 适配器一致）

按以下优先级解析 `DEEPSEEK_API_KEY`（可通过配置 `apiKeyEnv` 改名）：

1. `ctx.credentials` 凭据 seam —— `$DSH_HOME/.credentials.yaml`（Models 页面写入的位置）；
2. 启动环境快照（launch environment，含项目/用户 `.env`）；
3. 进程环境变量 `process.env`（Windows 下大小写不敏感）。

密钥**永不**出现在 HTTP 响应、工具结果或日志里——只存在于宿主内存中用于 `Authorization: Bearer` 头。

## 安装

### 方式一：从 GitHub 安装（推荐）

```bat
dsh plugin --profile web add git+https://github.com/neltharion11/dsh-api-balance.git
```

`dsh plugin` 会把包 pnpm 安装进 profile 并自动把它加入 `dsh.profile.bundles` 层列表。前提：机器上已安装 [pnpm](https://pnpm.io/installation)（`dsh plugin` 依赖 pnpm）。

### 方式二：本地路径安装

在 DSH 安装目录（如 `F:\deepseek-harness`）下执行：

```bat
dsh plugin --profile web add file:F:\path\to\dsh-api-balance
```

### 方式三：手动安装（无 pnpm 时，请严格按此执行）

> **最常见的翻车点**：从 GitHub 下载 ZIP 解压出的文件夹叫 `dsh-api-balance-main`（默认分支会带 `-main` 后缀）。
> **文件夹名必须与包名完全一致：`dsh-api-balance`**，否则 dsh 启动时会报
> `cannot resolve profile bundle "dsh-api-balance"` 并拒绝启动。

1. 下载并解压仓库（或用 `git clone https://github.com/neltharion11/dsh-api-balance.git`，clone 出来的文件夹名就是正确的），**把文件夹重命名为 `dsh-api-balance`**；
2. 把整个 `dsh-api-balance` 文件夹复制到 `%DSH_HOME%\profiles\node_modules\dsh-api-balance`（注意是 `profiles` 下，不是 `profiles\web` 下）；
3. 编辑 `%DSH_HOME%\profiles\web\package.json`（**用 VS Code / 记事本另存为 UTF-8 无 BOM**）：
   - `dependencies` 增加 `"dsh-api-balance": "file:../node_modules/dsh-api-balance"`；
   - `dsh.profile.bundles` 增加 `"dsh-api-balance"`；
4. **先验证再重启**，确认插件被正确解析：
   ```bat
   dsh --profile web --dump-config | findstr api-balance
   ```
   能看到 `- id: api-balance` 才算成功；若报 `cannot resolve profile bundle`，说明第 2/3 步的路径或名字不对。

> 安装后**重启 dsh web**（插件集变更需重启才生效）：关闭 3080 端口的进程，再运行 `start-deepseek-harness.cmd`，浏览器刷新页面即可看到侧边栏底部的小组件。
>
> 从 git 安装的插件若带构建步骤（本插件没有），pnpm 会要求先在 `pnpm-workspace.yaml` 的 `allowBuilds` 里放行对应包，再重跑安装。

## 故障排查

| 现象 | 原因与处理 |
|---|---|
| 启动报 `cannot resolve profile bundle "dsh-api-balance"` | 插件包没有被正确安装到 profile 可解析的位置。检查 `%DSH_HOME%\profiles\node_modules\dsh-api-balance\package.json` 是否存在、文件夹名是否精确为 `dsh-api-balance`、`web\package.json` 的 bundles 列表是否包含它 |
| 启动报 `pnpm not found` | 机器没装 pnpm。安装 pnpm，或改用「方式三」手动安装 |
| 启动报重复注册 / `already has` / tool 相关错误 | 装到了旧版本。重新从仓库拉最新代码（`git pull` 或重新 clone），旧版有启动期重复注册缺陷，已在仓库修复 |
| 插件能启动但侧边栏没有小组件 | 版本过旧或浏览器缓存：刷新页面；确认 `dsh --profile web --dump-config` 中能看到 `api-balance` 行；仍不行则升级 dsh 后重装 |


## 配置

通过 profile 的 `cordis.patch.yml` 覆盖（行 id：`api-balance`）：

```yaml
- id: api-balance
  config:
    apiKeyEnv: DEEPSEEK_API_KEY   # 凭据引用名
    baseURL: https://api.deepseek.com
    timeoutMs: 15000              # 单次上游请求超时
    cacheMs: 60000                # 宿主缓存余额快照的时长
    enabled: true
```

## 开发与测试

克隆后无需构建（客户端 bundle 为手写，无打包步骤）：

```bat
git clone https://github.com/<你的用户名>/dsh-api-balance.git
cd dsh-api-balance
node --check lib/index.js && node --check lib/client.js
```

冒烟测试需要 `react`/`react-dom` 与 `@deepseek-ai/*` peer 依赖（可从 DSH 安装的 node_modules 解析）：

```bat
set NODE_PATH=%DSH_HOME%\profiles\node_modules
node test\smoke-host.mjs
node test\smoke-client.cjs
```

## 布局

```
dsh-api-balance/
├── package.json         # dsh.bundle.patch + dsh.client（web 平台）
├── cordis.patch.yml     # 把宿主插件行插入组合树
├── lib/index.js         # 宿主：密钥解析、余额查询、HTTP 路由、api_balance 工具
├── lib/client.js        # 客户端 bundle：侧边栏余额小组件
├── test/                # 宿主逻辑 + 客户端渲染冒烟测试
└── README.md
```

## 说明

- 客户端 bundle 为手写的 `window.__ModuleLoader__.load({ id, factory })` 格式（纯 `React.createElement`，无 JSX/打包器依赖），仅 require `react` 与 `slots` 服务。
- 宿主对 `webServer`/`tools`/`systemPrompt` 均做惰性绑定（含幂等守卫，避免启动期重复注册）：无 Web 服务器的 profile（如 headless）下插件退化为纯工具/无 UI，不阻塞启动。

## 许可证

[MIT](LICENSE)