前言¶
DeepSeek Harness (DSH) 採用模塊化設計，插件是擴展其功能的主要方式。在智能體開發中，模型路由、故障切換以及多模型管理是常見需求。dsh-cpa 插件旨在解決這些需求，它將 CLI Proxy API（CPA）整合進 DSH 生態，通過註冊 cpa provider，讓 DSH 能夠直接消費 CPA 的模型能力、上下文窗口、認證賬號數據以及模型列表。
插件簡介¶
dsh-cpa 是 CLI Proxy API（CPA）的 dsh bundle 插件。
- 定位：註冊 cpa provider，請求走 CPA 的
/v1/chat/completions，同步/v1/models模型列表。 - 維護者：Moraxyc
- 許可證：MIT
安裝與啓用¶
安裝前請確保已安裝 DSH，且版本不低於 0.2.0-rc.2。
快速安裝（Web 服務）：
npx @deepseek-ai/dsh plugin --profile web add dsh-cpa
從源碼安裝：
npx @deepseek-ai/dsh plugin --profile web add .
Headless Profile 安裝：
npx @deepseek-ai/dsh plugin --profile headless add dsh-cpa
安裝完成後，Web 服務重啓後，管理路由依然可用。
核心功能¶
該插件提供以下核心能力：
- Provider 註冊與路由：註冊 cpa provider，Agent 請求會自動路由到 CPA 的
/v1/chat/completions接口。 - 模型同步：自動從
/v1/models同步模型列表，每 5 分鐘刷新一次。 - 雙模式支持：支持外部 CPA（連接已有服務）和內部 CPA（插件自動啓動）。
- 智能路由與故障切換：
- 用戶指定的模型始終是第一候選。
- 僅在請求尚未產生流內容，且 CPA 返回額度耗盡、限流、服務端錯誤、傳輸錯誤或空響應時，纔會按候選順序重試。
- 流已經開始後不會重放請求。
- 管理面板：提供設置面板，支持配置外部 CPA 的 URL、API Key、Management Key，或內部 CPA 的路徑。
- 使用狀態監控：解析
x-cpa-trace-id，記錄執行鏈路，提供使用狀態和摘要。 - 賬號管理隔離：賬號憑據和切換由 CPA 管理，插件僅消費脫敏後的賬號/quota 數據。
典型用法¶
使用已有 CPA¶
如果已有運行中的 CPA 服務，可以在 DSH 的設置面板中切換到“外部 CPA”模式。填寫 CPA 的 URL、API key 和 management key 後點擊“應用”。
自動啓動內部 CPA¶
默認情況下，插件會生成 $DSH_HOME/cpa/config.yaml 並自動啓動 cli-proxy-api 進程。啓動前會先在 PATH 中解析可執行文件；若二進制不在 PATH 中，需在 CPA 設置頁的“內部 CPA 路徑”中填寫絕對路徑。
智能故障切換¶
在 Agent 配置中使用 cpa provider 時，系統會根據已同步的模型能力、上下文窗口、賬號健康度和 quota 快照生成候選順序。當 CPA 返回額度不足或服務異常時，插件會嘗試切換到下一個候選模型（除非流已經開始）。
注意事項¶
- 版本要求：DSH 需要安裝 0.2.0-rc.2 或更高版本。
- 數據安全：插件只消費 CPA 脫敏後的賬號和額度數據，不復制 CPA 的賬號管理能力。CPA 管理 API 不會暴露 token 彙總。
- 重放機制：一旦流式響應開始，不會重放請求，避免 Agent 收到重複內容或副作用。
- 設置保存：設置會保存到當前 active profile 的
dsh-cpa配置中。 - 權限：插件以當前 DSH 進程的權限運行，請確保安裝前檢查源碼與許可證。
總結¶
dsh-cpa 將 CPA 的能力無縫集成到 DSH 的智能體路由體系中。它通過自動同步模型列表、智能故障切換以及統一的使用狀態監控，簡化了多模型管理和代理開發流程。通過設置面板，用戶可以靈活配置內部或外部的 CPA 服務。
