前言¶

在 DeepSeek Harness（DSH）里选模型，通常要在「设置 → 模型」里为每家供应商手写 @deepseek-ai/dsh-llm-pi-ai 的 provider 路由，并把 API Key 放进 harness 凭据存储。若你本机已经在用 cc-switch 管理多家第三方模型，再在 DSH 里重复录入同一套端点与密钥，既费时也容易两边不一致。

dsh-cc-switch（维护者 LightingHa，社区分类为模型推理）读取 cc-switch 的 SQLite 数据库，把已配置的供应商「翻译」成 DSH 内置 pi-ai 适配器能用的路由，并可选地把密钥写入凭据；协议实现仍由 DSH 自带适配器完成，插件本身不注册第二个 LLM 适配器。下面介绍它的定位、安装方式与日常用法。

这是什么¶

一句话：把 ~/.cc-switch/cc-switch.db 里 cc-switch 配好的 providers，同步进 profile 里 llm-pi-ai 的 providers 配置（路由名默认带 ccswitch- 前缀），使「设置 → 模型」里的模型选择器与 cc-switch 侧可见的模型对齐。

数据流可以概括为：读 providers 表 → convert.js 做协议/端点/模型映射 → plan.js 只增删本插件曾写入的路由 → 通过 settings.mutate('llm-pi-ai') 持久化到 profile 的 cordis.patch.yml 并热加载；API Key 经 credentials.set('CCSWITCH_…_API_KEY', …) 写入凭据存储。代理日志还可用来补全模型清单。

核心功能¶

自动同步与监听¶

插件加载后默认执行一次同步（syncOnLoad），之后按 watchSeconds（默认 30 秒）轮询 cc-switch 数据库是否变化，有变更则自动跟上。首次同步会写入凭据并更新 llm-pi-ai 的 providers。

多类 cc-switch 应用的映射¶

README 中列出的 app 类型包括 claude、claude-desktop、codex、openclaw、mcode、pi、gemini，以及 opencode、hermes、grokbuild 等；各类型按 cc-switch 里的配置形状映射到 pi-ai 的 api（如 anthropic-messages、openai-completions、openai-responses）。gemini 若仅为原生 generateContent 且 pi-ai 不支持，默认跳过并说明原因；若配置了 OpenAI 兼容或 meta.apiFormat，则按兼容协议导入。认不出的条目会进入 skip-list 并给出原因。

元信息（apiFormat、apiKeyField、isFullUrl、requestHeaders、model_catalog_json 等）会参与协议选择与请求头转换。模型列表优先用配置声明，再合并代理日志里真实用过的模型名，最后用 model_catalog_json；三者皆无则跳过该供应商。

工具 cc_switch¶

插件注册工具 cc_switch，用于手动查看状态、触发同步或体检：

常用参数 app_types、include、exclude 仅影响单次调用，不改插件持久配置。

安全与幂等¶

插件只写入 routePrefix（默认 ccswitch）前缀的路由，只删除自己记录在 $DSH_HOME/cc-switch-state.json 中的路由与凭据；路由名冲突时默认 onConflict: skip。内容无变化时不写配置。凭据若已由环境变量提供则不会覆盖。输出中对密钥做掩码。

安装与启用¶

环境要求¶

• DSH >= 0.2.0-rc.1（文档写明在 0.2.0-rc.2 上验证，并针对其插件契约与 settings/credentials 服务编写）
• Node.js >= 22.13（读取 SQLite 使用 node:sqlite）
• 本机已安装 cc-switch，并至少配置一家第三方供应商

安装命令¶

已安装 dsh-market 时，可在「设置 → 插件」市场中搜索 cc-switch 安装。

CLI 安装（来自官方 README）：

dsh plugin add dsh-cc-switch                       # 默认 profile
dsh plugin --profile desktop add dsh-cc-switch     # 指定 profile

安装会修改 ~/.dsh/profiles/<profile>/package.json（dependencies 与 dsh.profile.bundles），并在 profile 目录执行依赖安装。重启 DSH 后 bundle 列表生效；也可在「设置 → 插件」中启用，由插件管理器热挂载。

基础配置¶

配置写在 profile 的 cordis.patch.yml（或通过「设置 → 插件」写入），例如：

- id: cc-switch
  name: dsh-cc-switch
  config:
    mode: apply
    watchSeconds: 30

mode: apply 表示写入配置与凭据；mode: plan 只计算并打日志，不自动写入。更多字段见仓库 README 配置表（dbPath、appTypes、include/exclude、pruneOwnedRoutes、probeTimeoutMs 等）。

装完后打开「设置 → 模型」，应能看到 ccswitch-* 开头的供应商，设为默认即可使用。

典型用法¶

预演同步¶

在智能体或工具调用中执行 cc_switch，action=sync 且 dry_run=true，可查看将新增、更新、删除的路由与凭据数量，确认后再正式 sync。

路由体检¶

action=probe 会按 pi-ai 实际请求的 URL 发送最小流式请求。README 示例中，结论包括「可用」（2xx 且流正常结束）、「可用但很慢」（首字节超过 probeSlowFirstByteMs）、流未正常结束、超时或不可用等；体检只读，不写配置与凭据。

排查未导入项¶

action=skip-list 查看被跳过的供应商及原因；action=list 查看已识别全集。需要收窄范围时可在单次调用里传 include / exclude 或 app_types。

适用场景与注意¶

适合谁：已在 cc-switch 里集中管理 Claude、Codex、OpenClaw、自定义 OpenAI 兼容端点等，并希望 DSH 的模型页与密钥存储与之一致、且不想维护两套手写路由的开发者。

权限与安全：插件以当前 DSH 进程权限运行，会读取 cc-switch 数据库并写入 profile 配置与 harness 凭据。安装前请查看 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。

与生态的关系：DSH 采用「一切皆插件」的扩展方式；SkillHub 目录页 等为社区收录站点，与 DeepSeek / 幻方无官方从属关系。npm 包版本为 1.0.0（见 package.json）。

撤销：在 cc-switch 中删除供应商后，下次同步会按 pruneOwnedRoutes 清理本插件曾写入的对应路由与凭据（详见 README「撤销」一节）。

结尾¶

dsh-cc-switch 做的是配置翻译与写入：cc-switch 里有什么模型，DSH 模型选择器里就能选到什么，并附带 probe 等连通性检查。需要条目说明或 issue 时，可访问目录页 lightingha/dsh-cc-switch 与仓库 LightingHa/dsh-cc-switch。