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/<你的用户名>/dsh-api-balance.git

dsh plugin 会把包 pnpm 安装进 profile 并自动把它加入 dsh.profile.bundles 层列表。

方式二：本地路径安装

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

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

方式三：手动安装（无 pnpm 时）

1. 把 dsh-api-balance 目录复制到 %DSH_HOME%\profiles\node_modules\dsh-api-balance；
2. 编辑 %DSH_HOME%\profiles\web\package.json：
   • dependencies 增加 "dsh-api-balance": "file:../node_modules/dsh-api-balance"；
   • dsh.profile.bundles 增加 "dsh-api-balance"。

安装后重启 dsh web（插件集变更需重启才生效）：关闭 3080 端口的进程，再运行 start-deepseek-harness.cmd，浏览器刷新页面即可看到侧边栏底部的小组件。

从 git 安装的插件若带构建步骤（本插件没有），pnpm 会要求先在 pnpm-workspace.yaml 的 allowBuilds 里放行对应包，再重跑安装。

配置

通过 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