跳转到正文

zcode-to-dsh-migrate 封面

ZCode 配置一键搬进 DSH:我写了个无损迁移工具 ​

ZCode 用久了,切到 DSH Desktop Beta,最烦的不是换界面,而是重新配一遍:provider、模型、API Key、MCP server、代理,一个都不能少。

我这边是二十多个 provider、十几个 Key、两个 MCP,手动搬半小时起步,还容易漏。于是写了 zcode-to-dsh-migrate:

把 ZCode / ZCodium 里能搬的配置,安全地搬进 DSH Desktop Beta,而且随时能退回去。

背景:换客户端,最烦的是重配 ​

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 kindDSH API
anthropicanthropic-messages
openai-compatibleopenai-completions
openaiopenai-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 并存,由你决定用哪个。

安全设计 ​

  1. 全程不打印明文密钥:scan、plan、日志、JSON/HTML 报告只显示“已配置”或引用名
  2. diff 脱敏:plan 的 diff 里凭据段落直接省略,MCP 的 Authorization 头脱敏
  3. 原子写入:临时文件 + 原子重命名,写完重新解析校验,失败自动回滚
  4. 幂等:重复执行不会重复添加;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,手动配置可能更快——这点也如实说明。

使用提示 ​

把知道的留下,把不懂的写下来。