dsh-api-balance
DeepSeek Harness 插件：在 DSH Web 界面左侧边栏底部显示你的 DeepSeek API 账户余额（实时小组件），并把余额查询暴露为 api_balance 工具供模型在对话中汇报。
!效果示意
功能
- Web 侧边栏小组件（
sidebar.footer.action槽位，列表式追加，不影响其他条目）：
- 展开侧边栏：显示 API 余额 ¥110.00（取第一个币种），悬停可看明细（充值 + 赠金、更新时间），点击立即刷新； - 收起为窄轨：只显示一个钱包图标按钮，悬停提示明细； - 每 20 秒自动轮询，由宿主端 60 秒缓存兜底，不会高频打 DeepSeek API。
api_balance工具：模型可在对话中查询并汇报余额（币种、总额、充值、赠金、更新时间）。- 系统提示词小节：告知模型余额小组件与工具的存在。
环境要求
- DeepSeek Harness
webprofile（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 安装（推荐）
dsh plugin --profile web add git+https://github.com/neltharion11/dsh-api-balance.gitdsh plugin 会把包 pnpm 安装进 profile 并自动把它加入 dsh.profile.bundles 层列表。前提：机器上已安装 pnpm（dsh plugin 依赖 pnpm）。
方式二：本地路径安装
在 DSH 安装目录（如 F:\deepseek-harness）下执行：
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）：
- id: api-balance
config:
apiKeyEnv: DEEPSEEK_API_KEY # 凭据引用名
baseURL: https://api.deepseek.com
timeoutMs: 15000 # 单次上游请求超时
cacheMs: 60000 # 宿主缓存余额快照的时长
enabled: true开发与测试
克隆后无需构建（客户端 bundle 为手写，无打包步骤）：
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 解析）：
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/打包器依赖），仅 requirereact与slots服务。 - 宿主对
webServer/tools/systemPrompt均做惰性绑定（含幂等守卫，避免启动期重复注册）：无 Web 服务器的 profile（如 headless）下插件退化为纯工具/无 UI，不阻塞启动。
许可证
[MIT](LICENSE)