前言¶
用 DSH 跑智能體，常見一類需求是同一個接口地址、多把 API Key：主力 Key 限流了切備用，或者按配額輪換。原生做法是改配置或環境變量裏的憑據引用，保存後重啓 DSH 才生效。切換一次成本不高，但排障時反覆重啓會打斷正在跑的請求。
下面介紹 my-0228 維護的 Web 插件 dsh-api-key-switch。它在設置面板裏新增一頁，把多把 Key 存到本機憑據庫，列表裏點「使用」即可切換，下一次模型請求就生效，不需要重啓 DSH。插件屬於 admin-security 分類，無運行時依賴、無構建步驟。
這是什麼¶
一句話定位：一個 DSH Web 插件，在設置面板保存多把 API Key 並切換當前生效的那把。
- 維護者：my-0228（package.json 裏 author 爲 mayue，郵箱 1771826962@qq.com）
- 許可證：MIT
- 版本：1.0.0
- 運行要求：DSH 0.2.x（Web 端）、Node.js >= 20
- 路徑：
dsh-api-key-switch（包名與插件 id 同名）
它不改動 DSH 本身的模型配置界面，只在設置左側導航掛一頁，複用 DSH 已有的客戶端槽位契約（settings.section）與 Connection RPC 信封。原生「設置 → 模型」頁照常可用，兩邊讀到的是同一份憑據事實。
核心功能¶
- 設置面板左側導航新增一頁「API Key 切換」。
- 在本機保存多把 API Key（名稱 + Key），列表裏點「使用」切換。
- 切換把選中的 Key 寫進當前 LLM 路由引用的憑據（默認
DEEPSEEK_API_KEY）；憑據庫按請求解析，所以下一次模型請求就生效。 - 列表只顯示掩碼（如
sk-a…599c）；明文只在輸入那一刻存在，不會回到瀏覽器。
「當前生效」這一列有兩種顯示：顯示插件內的 Key 名稱，或者顯示 外部設置。後者說明憑據是別處寫入的（例如官方「模型」頁），點「收錄到列表」即可納入管理。
安裝與啓用¶
安裝命令來自 README，用 profile 方式安裝並進入 web 平臺：
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
開發模式下兩個半件都是純源碼：Host 半是普通 ESM Cordis 插件 lib/index.js，瀏覽器半是手寫 window.__ModuleLoader__.load({id, factory}) 包裹的 CJS lib/client.js，不需要構建步驟。
典型用法¶
先準備一個 profile 裏的憑據引用。插件默認寫 DEEPSEEK_API_KEY，只要你的 LLM 路由引用了這個名稱即可直接用。也可以用profile 側覆蓋層改 ref，見下一節。
- 打開設置，左側導航選「API Key 切換」。
- 填「名稱」和「API Key」，勾選「保存後立即啓用」，保存。
- 以後在列表裏點「使用」切換；生效中的那行帶「使用中」標記。
三條規則需要提前知道：
- 同一把 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
這裏有幾個容易踩的坑，README 都寫明瞭：
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 記錄。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 或等它重新加載憑據庫。
適用場景與注意¶
適合的人：一個 LLM 路由對應多個同源 Key，需要按限流、配額或成本手動輪換，且不想爲每次切換重啓 DSH 的開發者。如果你的需求是切換 baseURL 或切換模型，這個插件不在範圍內。
注意以下幾點：
- 插件以當前 DSH 進程權限運行，寫入能力等同 DSH 進程的憑據庫訪問權限。安裝前應檢查源碼與許可證（MIT），確認它存取的憑據引用名與你的配置一致。
- 插件不做 Key 有效性校驗，也不聯網。Key 無效時由 DSH 原生報錯。
- 沒有導出
Config（schemastery），ref在apply裏手寫校驗，插件檢查器裏看不到表單。 - 瀏覽器半依賴 DSH 0.2.x 的客戶端槽位契約與 Connection RPC 信封，DSH 大版本升級後需按新契約複覈。
- 生態背景：DSH 理念是「一切皆插件」；目錄站點是社區獨立站點，與 DeepSeek / 幻方無官方從屬關係。
小結¶
dsh-api-key-switch 解決的是「同一接口多把 Key」的輪換問題：面板管理、本機存儲、按請求生效、不重啓。它只做這一件事，邊界很清楚。目錄頁與源碼如下：
- 目錄頁：https://www.skillhub.cn/plugins/my-0228/dsh-api-key-switch
- GitHub：https://github.com/my-0228/dsh-api-key-switch
