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 配置的托管条目会被自动移除。涉及改用户文件的动作守三条红线:
- 只删自己写的东西:识别依据是 dsh 的
llm-deepseek段,且仅在确认其baseURL指向本工具的本地代理端口(17890–17899)时才删;用户在 dsh 界面配置的其他命名空间(如llm-pi-ai)任何情况下都不碰。 - 每次动作前强制永久快照:快照存
<数据目录>/backups/pre-switch-removal/,永不滚动清理——这是唯一的兜底;快照失败即中止清理,不留半完成状态。 - 判定依据不足时不动:宁可留下一条无害的旧配置,也不猜用户的键名。
两个容易忽略的细节:
- dsh 配置有两个候选落点:
settings.yaml与settings.yaml.imported。后者来源未能确证(可能是旧版写入的残留),但既然可能指向已不启动的代理,快照与清理都一并覆盖,避免留下断链。 - 卡片上会看到灰色「已移交」标记:提示你这条方案曾经配过 dsh、现在归 dsh 自管。老数据里残留的
dsh目标值在读入时被静默丢弃,不需要你做任何操作。
3. 在 dsh 里配置服务商
在 dsh 界面里按以下步骤配一次即可长期生效:
→ 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,超限请求会被直接打回。历史版本按三级优先确定写入值:
填写了 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 / 任务 / 通知能力都会跟随它定位;也可以用更细粒度的路径变量覆盖单个文件。完整清单见数据目录与日志说明。
评论