前言¶
在 DeepSeek Harness（dsh）里，deepseek-official 是单一路由：PROVIDER 写死，一个路由只能挂一把 API Key。个人账号、公司账号、备用号想轮换使用，只能反复改凭据或环境变量，既麻烦也看不到每把 key 还剩多少额度。
社区插件 dsh-key-switch（维护者 luzhenqian，分类为模型推理）把多把 DeepSeek key 放进一个池子：侧边栏看当前 key 余额，点开列表即可切换，下一次模型调用生效，无需重启 dsh web。下面介绍它的能力、安装方式与使用时的注意点。
这是什么¶
dsh-key-switch 是面向 DSH Web profile 的宿主插件：维护 API Key 池、改写当前生效凭据、向 api.deepseek.com/user/balance 查各 key 余额，并在界面里展示趋势与可选的自动切换策略。它不替代官方按天账单，而是回答「现在还剩多少、还能撑多久、会话里 token 花在哪」这类本地可见的问题。
核心功能¶
侧边栏与弹层切换¶
- 侧边栏余额入口：位于「设置」上方一行，显示当前生效 key 的余额，约 60 秒自动刷新。
- 点开即切换：弹层中每把 key 一行，带备注、掩码（仅后四位）、余额；点哪行切哪把，不用重启。
- 管理页：设置 → API Key 管理，可添加、删除、切换，并填备注（如「个人账号」「公司账号」）。趋势与自动策略在页面底部 高级设置，默认折叠。
余额查询¶
宿主进程直接向官方接口查余额，60 秒缓存；「刷新余额」可强制重查，并自动识别 CNY / USD。余额查询失败不影响切换和正常对话。
余额趋势¶
在每次查余额时记录样本，绘制 24 小时 / 7 天 / 30 天阶梯图，并给出：
| 指标 | 含义 |
|---|---|
| 今日已花 | 当天第一个样本与最后一个样本的差（按该账号币种） |
| 日均消耗 | 最近 7 天实际消耗 ÷ 观测天数；无消耗时为 0 |
| 预计可用 | 当前余额 ÷ 日均消耗；日均为 0 时显示 —，不编造天数 |
样本写入 $DSH_HOME/dsh-key-switch/balances.jsonl（权限 0600），不存 key 明文，只记池内稳定 id。DSH 未运行期间不会采样，曲线会出现断档。
会话消耗归因¶
从本地会话日志 $DSH_HOME/sessions/<工作区>/<会话>/session.*.jsonl.zstd 读取每条 assistant/message 的 usage（含 inputTokens、outputTokens、cacheReadTokens、reasoningTokens 等），按 8 小时时段与今天 / 7 天 / 30 天聚合。默认只显示 token；在管理页底部填写某模型的峰谷单价（元/百万 token，峰谷按北京时间工作日 9–12、14–18 判定）后，表格才显示金额。单价保存在 $DSH_HOME/dsh-key-switch/prices.json（0600）。
自动策略（默认关闭）¶
关着时插件只读不写，不会自动改 key。
- 余额不足时自动切换：当前 key 低于阈值时，切到同币种里余额最高且仍高于阈值的 key；不跨币种比较；冷却 30 分钟。
- 按权重均衡消耗：比较各账号「窗口内花掉 ÷ (当前余额 + 花掉)」相对权重的得分，当前 key 得分过高时切到得分最低的那把；窗口默认 7 天。
策略与上次动作记录在 $DSH_HOME/dsh-key-switch/policy.json（0600）。
切换机制与安全¶
切换不是改路由配置，而是把值原子写入 $DSH_HOME/.credentials.yaml 里 deepseek-official 引用的凭据项（默认 DEEPSEEK_API_KEY），写完回读校验；失败会报错。若环境变量里已有同名 DEEPSEEK_API_KEY，会盖住文件，界面会提示，此时界面切换不生效。
Key 池存在 $DSH_HOME/dsh-key-switch/keys.json（0600，明文存储以便切换）；浏览器侧只见掩码后四位。写接口要求同源会话 cookie。插件不采集、不上传使用行为，无第三方请求。
界面样式使用 dsh 的 --dsw-* 设计令牌，浅深色跟随宿主。插件注册 zh、en、zh-Hant、ja、ko、ru 等文案；宿主外壳在非中英语言时可能回落英文，插件分区仍用各自语言。
安装与启用¶
安装命令（来自项目 README）：
dsh plugin --profile web add dsh-key-switch
宿主插件层仅在启动时加载，装完后需重启一次 dsh web。
启用步骤：
- 设置 → API Key 管理 → 逐个粘贴 key 并填写备注。
- 侧边栏底部出现余额入口，点开即可切换。
卸载：
dsh plugin --profile web remove dsh-key-switch
卸载后 ~/.dsh/dsh-key-switch/ 可能仍保留 key 池与样本文件，需要时请手动删除。
典型用法¶
经过上面的安装与重启，日常流程通常是：
- 在 API Key 管理 里维护多把 key 和备注。
- 对话前在侧边栏余额入口或弹层里点选要用的账号；下一次 LLM 调用即走新 key。
- 需要估消耗时打开高级设置看趋势；若要按会话看 token（或填单价后看金额），使用会话归因相关视图。
- 仅在明确需要时打开自动策略，并设置阈值、权重与冷却相关选项。
适用场景与注意¶
适合谁：经常在 DSH Web 里用 DeepSeek 官方接口、且持有多把 API Key（多账号、主备、个人与公司分离）的开发者。
兼容性：README 写明在 DSH 0.1.5-rc.3 + Web profile 上实测（macOS / Chrome）。依赖宿主 webServer，以及 settings / llm 等软依赖；Node >=22。package.json 当前版本为 0.4.0，许可证 MIT。
已知限制（摘自 README）：
- 余额查询仅针对 DeepSeek 官方接口；其它厂商未支持。
- dsh 本身「一个 provider 一把 key」，多账号只能切换，不能并行挂多把。
- 同一浏览器多开 dsh 标签时，连接数受限可能导致余额入口显示不可用，关掉多余标签即可。
- 设置导航图标依赖 DOM 替换，宿主改结构后可能退回齿轮，不影响功能。
安装前建议：插件以当前 dsh 进程权限读写 $DSH_HOME 下的凭据与 key 池；安装前应自行查看 GitHub 源码 与 MIT 许可证，确认符合你的安全与合规要求。DeepSeek Harness 社区插件目录（如 SkillHub 上的条目）为独立生态站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-key-switch 把「多 key 轮换」和「每把 key 还剩多少」收进 DSH Web 侧边栏与管理页，切换走凭据热重载，并可选趋势、会话归因与自动策略。若你已在用 DSH 且 key 不止一把，可按官方命令安装并在 API Key 管理 里配池。
- 目录页：https://www.skillhub.cn/plugins/luzhenqian/dsh-key-switch
- 仓库：https://github.com/luzhenqian/dsh-key-switch
