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 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 安装（推荐）

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

dsh 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. 先验证再重启，确认插件被正确解析：

   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/打包器依赖），仅 require react 与 slots 服务。
• 宿主对 webServer/tools/systemPrompt 均做惰性绑定（含幂等守卫，避免启动期重复注册）：无 Web 服务器的 profile（如 headless）下插件退化为纯工具/无 UI，不阻塞启动。

许可证

MIT