dsh(DeepSeek Harness)是 DeepSeek 官方开源的 Agent Harness,原生走 OpenAI Chat Completions 接口,配置集中在 ~/.dsh/ 目录。a4agent 自 0.1.4 起支持 dsh 目标、0.5.1 起停止代管:dsh 自带完整的模型与供应商配置界面,服务商请直接在 dsh 内配置。本文章说明这次移交的原因与边界、0.5.1 自动清理做了什么、在 dsh 里的配置步骤,并保留历史版本的写入内容供老用户核对与回滚。

1. 现状:dsh 的服务商请在 dsh 内配置

自 0.5.1 起,配置方案的应用目标只剩 Claude Code 与 Codex 两端(见配置方案与一键切换第 3.1 节)。判定标准只有一条:目标应用是否自带完整的供应商配置界面。dsh 属于「自带」的一类:

dsh 自带能力 说明
Settings → Models → Add a custom provider 可添加任意自定义供应商
三种 API 协议可选 openai-completions / openai-responses / anthropic-messages
Fetch available models 自动从上游拉取可用模型清单
会话内换模型 右下角直接切换,无需重启

外部代管 dsh 配置既不省事(用户点几下更快),又有额外风险——界面上的能力开关、上下文窗口、启用状态等外部写文件时无从得知,只能填保守默认值。

需要注意的是,停止代管 API 配置不等于不再支持 dsh。a4agent 对 dsh 的其余能力全部保留且仍在扩展:

能力 dsh 是否覆盖
技能管理(发现 / 迁移 / 回收站) 覆盖,见技能管理
MCP 管理(发现 / 安装 / 迁移) 覆盖,见MCP管理
无头任务下发 覆盖(dsh --profile headless),见任务下发
会话通知(手机推送 / 桌面横幅) 覆盖,通过挂载内置 Cordis 插件实现,见通知提醒

2. 0.5.1 的自动清理做了什么

升级到 0.5.1 后,历史版本写入 dsh 配置的托管条目会被自动移除。涉及改用户文件的动作守三条红线:

  1. 只删自己写的东西:识别依据是 dsh 的 llm-deepseek 段,且仅在确认其 baseURL 指向本工具的本地代理端口(17890–17899)时才删;用户在 dsh 界面配置的其他命名空间(如 llm-pi-ai)任何情况下都不碰。
  2. 每次动作前强制永久快照:快照存 <数据目录>/backups/pre-switch-removal/,永不滚动清理——这是唯一的兜底;快照失败即中止清理,不留半完成状态。
  3. 判定依据不足时不动:宁可留下一条无害的旧配置,也不猜用户的键名。

两个容易忽略的细节:

  • dsh 配置有两个候选落点:settings.yaml 与 settings.yaml.imported。后者来源未能确证(可能是旧版写入的残留),但既然可能指向已不启动的代理,快照与清理都一并覆盖,避免留下断链。
  • 卡片上会看到灰色「已移交」标记:提示你这条方案曾经配过 dsh、现在归 dsh 自管。老数据里残留的 dsh 目标值在读入时被静默丢弃,不需要你做任何操作。

3. 在 dsh 里配置服务商

在 dsh 界面里按以下步骤配一次即可长期生效:

graph LR A[dsh Settings
→ Models] --> B[Add a custom provider] B --> C[填 Provider ID
如 deepseek] C --> D[填 Base URL 与
API protocol] D --> E[填 API Key] E --> F[Fetch available models
拉取模型清单] F --> G[选定默认模型
新会话即生效] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style D fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style E fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style F fill:#fdebd0,stroke:#b7950b,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
字段 填写要点
Provider ID 自定义标识,如 deepseek、zhipu
Base URL 上游地址,注意是否需要带 /v1(各家不同,以 dsh 的连通性校验结果为准)
API protocol openai-completions(多数国产上游)、openai-responses(原生 Responses 上游)、anthropic-messages(Anthropic 端点,如智谱的 /api/anthropic)
API Key 上游密钥,只存在 dsh 自己的凭证文件里

dsh 的配置文件被 watcher 热加载,切换后新会话即生效,无需重启。

各端字段对照与已知坑位收录在仓库文档 docs/迁移对照表-三端API配置.md(含 dsh / ZCode / pi 三端),可在项目总览与快速开始给出的仓库地址查阅。

4. 历史写入内容(0.1.4 至 0.5.0)

以下内容仅在 0.5.0 及更早版本生效,保留供老用户核对备份与回滚:

4.1 settings.yaml 的两段

llm-deepseek:
  baseURL: http://127.0.0.1:17890
  apiKeyEnv: DEEPSEEK_API_KEY
  maxTokens: 131072
agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash
字段 说明
llm-deepseek.baseURL 指向本地翻译代理的地址(dsh 经代理的 /chat/completions 透传端点连接上游)
llm-deepseek.apiKeyEnv 固定为 DEEPSEEK_API_KEY,即凭证文件中的键名
llm-deepseek.maxTokens 单次输出上限,取值策略见 4.3
agent-default-model.provider 固定为 deepseek-official——dsh 只注册这一个 provider 路由
agent-default-model.model 配置方案中的模型名

settings.yaml 中其他段落(如 ui-onboarding)原样保留,切换只重写上述两段。

4.2 .credentials.yaml 的凭证

version: 1
refs:
  DEEPSEEK_API_KEY: 本地代理鉴权token

由于 dsh 统一经本地代理连接,这里写入的是代理鉴权 token而非真实 API Key——真实 Key 由代理从加密数据库解密持有在转发时使用,不落盘明文。dsh 要求该文件遵循 version-1 布局:顶层仅允许 version / refs / records 三个键,任何未知顶层键都会让 dsh 拒绝启动(此修复自 0.2.1 起生效)。

4.3 maxTokens 输出上限(历史策略)

dsh 适配器默认的单次输出上限是 256000,而多数上游(如智谱、Console Go)的上限是 131072,超限请求会被直接打回。历史版本按三级优先确定写入值:

graph LR A[确定 maxTokens] --> B{方案中显式
填写了 max_tokens?} B -->|是| C[使用显式值] B -->|否| D{既有值
是否为适配器默认 256000?} D -->|否| E[保留手动值] D -->|是| F{既有值
是否存在?} F -->|是| G[视为历史遗留
回落安全值] F -->|否| F2[兜底安全值
131072] G --> F2 style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style D fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style F fill:#ffecd6,stroke:#e67e22,stroke-width:2px style F2 fill:#fdebd0,stroke:#b7950b,stroke-width:2px

配置方案的 max_tokens 字段随 dsh 目标一同退役:界面不再暴露,库中的旧数据保留不做破坏性迁移。

4.4 为什么历史上必须经本地代理透传

部分上游(如 opencode zen)会在流式分片的 tool_calls 里用 null 填充后续分片缺失的字段,dsh 的适配器会把工具名与 ID 覆盖为空,表现为 unknown tool "" 报错、工具调用失效。0.1.5 起 a4agent 让 dsh 统一经本地代理的 /chat/completions 透传端点连接上游,透传时把 null 字段归一为省略键,从根上规避该问题。移交之后这条链路不再有主动使用者,但代理的该端点仍然保留,详见本地翻译代理。

5. 备份与回滚

备份位置 说明
backups/pre-switch-removal/ 0.5.1 清理前的永久快照,永不自动清理,是这次变更唯一的兜底
backups/dsh.settings.<时间戳>.yaml.bak 历史版本每次切换前的滚动备份(保留最近 5 份)
backups/dsh.credentials.<时间戳>.yaml.bak 凭证文件的历史滚动备份

需要回滚时把对应文件复制回 ~/.dsh/ 即可;备份目录的实际位置见数据目录与日志说明。

6. 常见问题

问:升级到 0.5.1 之后,我在 dsh 里配的供应商会被删掉吗?

答:不会。清理只针对 a4agent 自己写入的 llm-deepseek 段(且仅在它指向本地代理端口时),你在 dsh 界面配置的其它命名空间、以及 .credentials.yaml 里的所有 Key 都原样保留。

问:为什么不再支持给 dsh 一键切换服务商?

答:因为 dsh 自带完整的供应商配置界面,用户自己点几下更快、也更准。a4agent 现在的定位是为没有图形界面的 CLI(Claude Code、Codex)提供图形化配置面板;对 dsh 则继续提供技能管理、MCP 管理、无头任务下发与会话通知。

问:我还想用 a4agent 管 dsh 的模型和 API,有别的办法吗?

答:没有开关可以退回旧行为。dsh 的模型请在 dsh 内配置;a4agent 的「任务下发」会直接使用你在 dsh 内配好的配置跑无头任务,并在下发前做一次真实连通验证——配置怎么配都由你决定,验证的是「能不能真跑」。

问:dsh 的无头任务还需要本地翻译代理吗?

答:不需要,也不再使用。无头任务直接读 dsh 自己的配置连接上游;下发前会真实跑一次最小调用来验证连通性。dsh 的 headless profile 里若被其他工具(如 a4phone)插入了外部插件,a4agent 会生成 --patch 覆盖层屏蔽它们(headless profile 缺少这些插件依赖的 host 服务,不屏蔽会在启动阶段直接失败),不改 profile 本身。

问:我的 dsh 装在自定义目录怎么办?

答:设置环境变量 DSH_HOME 指向你的 dsh 数据目录即可,a4agent 的技能 / MCP / 任务 / 通知能力都会跟随它定位;也可以用更细粒度的路径变量覆盖单个文件。完整清单见数据目录与日志说明。