前言¶
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 服务。
