前言¶

DeepSeek Harness (DSH) 默認使用一個全局憑證引用（通常爲 DEEPSEEK_API_KEY），這導致所有會話和所有工作區共享同一個 API Key，難以將 API 調用成本與特定的開發或測試任務對應起來。dsh-workspace-api-key 插件通過在層級結構中爲不同範圍分配獨立的密鑰，解決了這一成本歸屬與密鑰管理問題。

插件簡介¶

這是一個由 COH2357 維護的 DeepSeek Harness 插件，用於綁定單獨的 DeepSeek API Key 到每個工作區或單個會話。它通過攔截憑證解析流程，實現從“系統默認”到“工作區”再到“會話”的層級密鑰覆蓋，確保每一層沒有自定義密鑰時會自動繼承上一層的配置。

核心功能¶

層級密鑰管理
插件支持三層密鑰配置：會話級、工作區級和系統默認級。配置邏輯遵循 session key → workspace key → system default 的優先級。
側邊欄界面
在 DSH 側邊欄中新增 API Key 分配 行，直接位於主機插件行下方。該行展開後顯示所有工作區及其會話，每個層級都有獨立的密鑰輸入框。
系統默認卡片
顯示當前生效的全局默認引用（DEEPSEEK_API_KEY）、其來源（文件、環境變量等）以及掩碼後的值。
連接測試
針對綁定的密鑰發起真實的 POST <baseURL>/messages 請求（設置 max_tokens: 1），返回 ok、invalid、quota、rate-limit 或 unreachable 狀態，成功測試可清除過期標記。
過期與不匹配警告
當綁定的密鑰返回 401/403 時標記爲 invalid，402 標記爲 quota，429 標記爲 rate-limit。若密鑰與當前使用的 Provider 不匹配，也會在進入會話時通過遮罩層警告，但不會自動切換密鑰。
安全與控制
插件不會靜默替換密鑰，決策權始終在用戶手中。響應中絕不會包含明文密鑰，僅顯示掩碼。API 訪問僅限 Loopback 調用（127.0.0.1, ::1 等）。
一鍵還原
清除會話或工作區的密鑰配置，即可回退到上一級配置（會話回退到工作區，工作區回退到系統默認）。

安裝與啓用¶

安裝方式爲通過包管理器直接添加 GitHub 倉庫。請在 DSH 的配置目錄（例如 ~/.dsh/profiles/desktop）中執行以下命令：

pnpm add "dsh-workspace-api-key@github:COH2357/dsh-workspace-api

安裝完成後，插件會自動註冊到 credentials.resolve 流程中，並在側邊欄生成對應的入口。

工作原理¶

插件通過兩個部分協作實現功能：Host 端（lib/index.js）處理憑證解析，Browser 端（lib/client.js）處理 UI 渲染與交互。

Host 端通過 ctx.effect 包裝 credentials.resolve，在每次憑證解析時讀取當前會話的目錄和 ID。它將目錄與 workspaceRegistry.list() 進行匹配（規範化路徑大小寫和後綴），爲匹配的工作區生成唯一的引用名：
- 工作區引用：DEEPSEEK_API_KEY_WS_<first 16 hex chars of sha1(normalized path), upper-cased>
- 會話引用：DEEPSEEK_API_KEY_SS_<first 16 hex chars of sha1(session id), upper-cased>

插件僅重寫 Provider 實際讀取的引用（默認引用、適配器的 apiKeyEnv 配置及生成的引用），其他引用保持原樣。它會記錄無效標記、Provider 不匹配等信息到本地存儲文件 $DSH_HOME/storages/dsh-workspace-api-key.json。

Browser 端通過 React 註冊到 sidebar.panellist 和 shell.overlay 等插槽，渲染密鑰分配面板。它會從 sessionController 或 sessions 服務獲取會話列表，並過濾掉子代理會話和空白會話，確保面板顯示的內容與側邊欄一致。

HTTP API¶

插件提供一組 REST API 接口，僅允許 Loopback 調用，且響應不包含明文密鑰。

方法	路徑	說明
GET	`/wsk-api/state`	獲取默認引用狀態、工作區及會話列表、無效標記、插件版本及會話探針信息
GET	`/wsk-api/resolve`	查詢當前會話正在解析的層級和引用
GET	`/wsk-api/check`	查詢指定會話的只讀狀態（有效層級、密鑰、過期標記、不匹配情況）
POST	`/wsk-api/set`	綁定密鑰（`{scope: 'workspace' \\| 'session', path \\| sessionId, key, provider?}`），或使用 `{useDefault: true}` 清除
POST	`/wsk-api/test`	使用指定密鑰進行真實連接測試並返回結果
POST	`/wsk-api/clear-flag`	清除指定引用的無效或配額標記

注意事項¶

插件以當前 DSH 進程的權限運行，安裝前建議檢查源碼。
僅接受 Loopback 調用，且響應不包含明文密鑰。
插件不執行靜默替換，不會因爲警告而自動切換密鑰，這符合“將花費歸屬給特定會話”的設計初衷。
部分功能依賴於 workspaceRegistry 和 sessionController 服務，如果這些服務不可用或報錯，面板可能無法正常顯示會話列表。

總結¶

dsh-workspace-api-key 提供了一種精細化的 DeepSeek API Key 管理方案，通過層級覆蓋機制和明確的警告反饋，幫助開發者在不改變 DSH 核心邏輯的前提下，實現按工作區或按會話的獨立計費與密鑰管理。

dsh-workspace-api-key

前言¶