外观

ZCode 配置一键搬进 DSH:我写了个无损迁移工具
ZCode 用久了,切到 DSH Desktop Beta,最烦的不是换界面,而是重新配一遍:provider、模型、API Key、MCP server、代理,一个都不能少。
我这边是二十多个 provider、十几个 Key、两个 MCP,手动搬半小时起步,还容易漏。于是写了 zcode-to-dsh-migrate:
把 ZCode / ZCodium 里能搬的配置,安全地搬进 DSH Desktop Beta,而且随时能退回去。
- 仓库:https://github.com/Dongmingyue-loss/zcode-to-dsh-migrate
- 运行环境:Node.js 18+,零第三方依赖,Windows 解压即用
背景:换客户端,最烦的是重配
ZCode 里已经调好的 provider、模型和密钥,在 DSH 里都要从零再来一遍。手动迁移的问题不只是慢:
- 二十多个 provider,漏一个就要回头排查半天
- Key 散落在各处,容易复制错或粘错
- MCP 的 HTTP / stdio 配置格式不同
- 代理、全局 AGENTS.md 这类“顺手配置”最容易被忘掉
所以这个工具的定位很明确:把可映射的字段无损搬过去,把不可映射的字段逐项报告出来,而不是假装 100% 全量搬迁。
它做什么
会迁移
| 类型 | 去向 |
|---|---|
| provider 与模型 | DSH llm-pi-ai 插件下的路由,含模型名、上下文窗口、最大输出、是否支持图片 |
| API Key | 写入 DSH 凭据库;配置文件只留引用名(如 ZCODE_0624D1CA_API_KEY) |
| MCP server | 转换为 dsh-mcp-client 条目,支持 HTTP 与 stdio |
| 代理 | ZCode 的 httpProxy 写入 DSH 的 .env |
| 全局 AGENTS.md | 原样复制 |
不会迁移(但会逐项报告)
- 会话历史:ZCode 用 SQLite,DSH 用压缩 JSONL,格式不兼容
- ZCode 插件:DSH 是 Cordis 插件模型,两者完全不同
- OAuth 登录态:只搬静态 API Key
- 逐 skill 开关、推理默认等级、最近项目等 UI 设置
这些不会悄悄丢掉,每一项都会写进迁移报告,说明为什么没搬。
五个命令
| 命令 | 作用 | 写文件 |
|---|---|---|
doctor | 体检:DSH 安装位置、配置文件能否解析、凭据格式、DSH 是否在运行 | 否 |
scan | 只读盘点:源端/目标端有多少 provider、模型、MCP,哪些跳过及原因 | 否 |
plan | 预演:列出改动、给出完整 diff、标出冲突 | 否 |
apply | 备份 → 写入 → 校验 → 生成 JSON/HTML 报告;失败自动回滚 | 是 |
restore | 指定备份 ID,把四个目标文件恢复到迁移前的字节内容 | 是 |
日常流程就是:scan 看家底 → plan 看 diff → apply 真正写入。
两个最容易出错的映射细节
1. 协议映射
| ZCode kind | DSH API |
|---|---|
anthropic | anthropic-messages |
openai-compatible | openai-completions |
openai | openai-responses |
注意最后一行:openai 对应的是 Responses API,不是 chat completions。这两个在网关上经常不通用,选错请求直接失败。
2. 模型 ID
ZCode 配置里,模型的键名和真正发给网关的模型名可能不一样。例如配置键是 deepseek-v4.1-flash,但里面 name 字段写的是 deepseek-v4-flash——真正发出去的是后者。
这是翻运行日志里 request body 的 model 字段确认的。所以工具的逻辑是:有 name 就用 name 当实际模型 ID,键名只作显示名。这样迁移过去,请求才能落到正确的模型上。
冲突策略
默认 keep:只新增,不覆盖。DSH 里已有的 provider、凭据引用、代理设置、默认模型全部保留,冲突项逐条列进报告。
--conflict prefer-zcode:让 ZCode 的值优先--conflict fail:遇到冲突直接停,一个文件都不写
凭据还有一个细节:同一个引用名在 DSH 里已存在、但值不同时,keep 不会覆盖,而是创建一个带 _2 后缀的新引用。两个 Key 并存,由你决定用哪个。
安全设计
- 全程不打印明文密钥:
scan、plan、日志、JSON/HTML 报告只显示“已配置”或引用名 - diff 脱敏:
plan的 diff 里凭据段落直接省略,MCP 的Authorization头脱敏 - 原子写入:临时文件 + 原子重命名,写完重新解析校验,失败自动回滚
- 幂等:重复执行不会重复添加;
apply两次,第二次提示“无需改动”
实测结果
源端官方 ZCode:24 个 provider,21 个启用,最终 18 个迁移成功。跳过的 6 个里,3 个没 Key 或没模型,3 个处于禁用状态。
迁移后 DSH:19 个 provider(18 个新增 + 原有 deepseek),19 个凭据引用全部对上,2 个 MCP server 都已添加,代理也已写入。
再跑一次 plan:无文件变化,说明幂等没问题。测试套件 8 个用例全部通过,覆盖 dry-run 不写文件、三种冲突策略、恢复后字节一致、YAML 注释保留、报告不含明文密钥。
已知限制
- 会话历史不迁移:跨产品格式不兼容
- ZCode 插件不迁移:DSH 用的是另一套插件模型
- OAuth 登录态不迁移:只搬静态 API Key
- 逐 skill 开关在 DSH 没有等价配置,相关 skill 仍会出现在共享目录
- 推理默认等级不迁移:默认不写
reasoningEfforts,避免网关不认识
这些都会进入迁移报告,不会静默丢失。
适合谁
适合已经在用 ZCode 或 ZCodium、想试 DSH Desktop Beta、又不想从零配置的人。
如果你只用一个 provider,手动配置可能更快——这点也如实说明。
使用提示
- 迁移前请先关闭 DSH Desktop Beta
- 若 DSH 装在非默认目录,用
--dsh-app指定resources\app - 仓库:https://github.com/Dongmingyue-loss/zcode-to-dsh-migrate,Release 里的 zip 解压即用