dsh-api-key-switch

DeepSeek Harness（DSH）Web 插件：在设置面板里保存多把 API Key，一键切换当前生效的那把。 下一次模型请求就生效，不需要重启 DSH。

Save multiple API keys in DSH Settings and switch the active one. The change applies to the next model request - no restart needed. Keys are stored in the local DSH credential store and never travel back to the browser in plaintext.

---

功能

• 设置面板左侧导航新增一页「API Key 切换」。
• 在本机保存多把 API Key（名称 + Key），列表里点「使用」即可切换。
• 切换把选中的 Key 写进当前 LLM 路由引用的凭据（默认 DEEPSEEK_API_KEY）；凭据库按请求解析， 所以下一次模型请求就生效。
• 列表只显示掩码（如 sk-a…599c），明文除了你自己输入的那一刻，不会回到浏览器。
• 原生「设置 → 模型」页照常可用，两边看到的是同一份凭据事实。

环境要求

• DSH 0.2.x（Web 端；客户端槽位契约 settings.section 与 Connection RPC 信封）
• Node.js >= 20（插件本身无运行时依赖、无构建步骤）

安装

dsh plugin --profile web add github:my-0228/dsh-api-key-switch

安装命令会在 profile 里建立依赖并追加到 dsh.profile.bundles（本包声明了 dsh.bundle.patch）。 完成后刷新 DSH 页面；若设置面板没有出现新页，重启一次 DSH。

开发时也可以从本地目录安装：

dsh plugin --profile web add /path/to/dsh-api-key-switch

使用

1. 打开设置，左侧导航选「API Key 切换」。
2. 填「名称」和「API Key」，勾选「保存后立即启用」→ 保存。
3. 以后在列表里点「使用」切换；生效中的那行带「使用中」标记，删除它会被拒绝。

「当前生效」显示 外部设置 时，说明凭据是别处写入的（例如官方「模型」页）， 点「收录到列表」即可纳入管理。

规则：同一把 Key 只允许保存一次（否则会出现一条显示未生效、却删不掉的重复条目）； 改「生效中」那行的 Key 时，新 Key 会自动接替生效，不会留下"旧 Key 还在用"的状态。

配置

本包自己的 Cordis patch 里有一条 Host 行：

- insert:
    - id: dsh-api-key-switch
      name: dsh-api-key-switch
      config:
        ref: DEEPSEEK_API_KEY   # 要切换的凭据引用；换成别的 apiKeyEnv 也成立

• ref：POSIX 标识符形式的凭据引用名，默认 DEEPSEEK_API_KEY。
• RPC 路由 /api/dsh-api-key-switch 与浏览器半硬编码在同一条约定上；要改就得同时改 lib/index.js 与 lib/client.js 的常量。
• 改 ref 时请改 profile 侧的覆盖层（cordis.patch.yml 的 id 定向覆盖），不要直接改本包的 patch：patch 是整段替换 config，不是合并。

存储与安全

• 保存的 Key 放在 DSH 凭据库的记录区：$DSH_HOME/.credentials.yaml

  records:
    dsh-api-key-switch/<id>:
      kind: grant
      payload:
        label: 主力
        apiKey: sk-…
        createdAt: 2026-11-03T02:41:59.797Z
  

  id 形如 k-<uuid>，必须以小写字母开头——凭据库要求记录键的每一段都匹配 [a-z][a-z0-9-]*，否则下次启动整份凭据文件解析失败（连带所有 LLM 路由）。
• 「当前生效」不额外存指针，等于 refs[ref] 的值；手改凭据文件也不会让两边说法不一致。
• 切换走凭据服务的 set()：原子写 + 跨进程锁。
• 校验：名称 1–64 字符、禁止控制字符；Key 8–512 个可见 ASCII 字符、禁止空白； 最多 50 把；Key 不允许重复；删除生效中的 Key 会被拒绝。
• 凭据库只读时（describe().writable === false），本页禁用所有写操作并说明原因。
• Windows 上凭据文件的保护取决于目录 ACL（与 DSH 自身凭据库一致）。
• 插件不联网、不做 Key 有效性校验，也不把 Key 写入日志或前端以外的位置。

卸载与清理

dsh plugin --profile web remove dsh-api-key-switch

已保存的 Key 记录仍在 .credentials.yaml 的 records 里，refs 保持最后一次切换的结果。 清理请只删除条目（不要手写或改动记录内容）：把 records 下 dsh-api-key-switch/ 开头的 整段删掉即可；写错形状（例如缺少 kind: grant/payload）会让下次启动解析失败。

应急：修复凭据库里的非法记录键

如果 .credentials.yaml 里出现了非法的记录键（症状：DSH 启动后所有模型请求都报凭据错误， 或日志里出现 invalid document），用附带的脚本一键改名（默认只修本插件 scope、默认 dry-run）：

node scripts/repair-credentials.mjs            # 预演，只打印
node scripts/repair-credentials.mjs --apply    # 真正修复（写前备份 .credentials.yaml.bak-<时间>）

脚本只改记录键的拼写（补 k- 前缀），payload、refs、注释和其它 scope 原样保留； 修完重启 DSH 或等它重新加载凭据库。

开发与测试

node --check lib/index.js
node --check lib/client.js
npm test        # host.test.mjs（24 用例）+ manifest.test.mjs（8 用例）

node --test test/ 在受限沙箱里会因 spawn EPERM 失败，直接 node <文件> 即可。

Host 半是普通 ESM Cordis 插件（lib/index.js），浏览器半是手写的 window.__ModuleLoader__.load({id, factory}) 包裹的 CJS（lib/client.js），不需要构建步骤。

已知边界

• 只处理「同一接口地址、多把 Key」的轮换；切换 baseURL / 模型不在范围内。
• 不校验 Key 是否可用（按需求不做网络验证）；Key 无效时由 DSH 原生报错。
• 没有导出 Config（schemastery）：ref 在 apply 里手写校验，插件检查器里看不到表单。
• 浏览器半依赖 DSH 0.2.x 的客户端槽位契约（settings.section）与 Connection RPC 信封； DSH 大版本升级后需按新契约复核。

License

MIT