在多个 AI 编程工具之间迁移项目配置的可复用方法

背景

zdq 项目经历了 Trae CN → Claude Code → Kimi Code 三次工具切换,每次迁移都产生一套改写过、互相不同步的配置。本次迁移沉淀出一套可复用的做法。

核心内容

迁移操作顺序

1. 先提交 git 回滚点并推送远程,再动手——大批量改写配置前必须有可回滚快照(git reset --hard <hash>),这是用户明确要求并验证有效的纪律。
2. 三端(或多端)比对再整合:先逐文件 diff 确认差异性质是"同步漂移"还是"有意适配";合理的工具适配(路径引用、工具名)不回改,真正的内容丢失(被精简掉的文档)从旧版恢复。
3. 存档目录只读:旧工具的配置目录定位为国档,只读不反向同步,避免多套配置再次互相污染。
4. 一次迁移只认一个基准端:当两个旧端互相矛盾时,选更新、与目标端更接近的一端为准,不追求"与所有旧端一致"(不可能做到)。

角色智能体的迁移映射

• Kimi Code 不支持自定义子智能体类型(只有 coder/explore/plan),角色 = 技能(SKILL.md):原智能体的"名称 + 何时调用 + prompt"与技能 frontmatter + 正文一一对应。
• 原文一字不改地收录,工具差异另起"本项目适配说明"一节,便于日后核对保真度。
• 恢复云端智能体的途径:本地状态库(state.vscdb)、聊天输入历史只能找回部分;其余让用户从原工具界面复制原文,不要凭记忆重建。
• 新建角色技能前先核对与现有技能是否重复(例:量化质监总监与 strategy-validator 逐项核对后确认是同一角色,不重建)。

多角色并发工作流的最小配置

角色技能齐了不等于能并发干活,必须补调度层:

• 角色↔技能↔执行载体映射表(中文角色名 ↔ 英文技能名 ↔ coder 子智能体),消除派发歧义;
• 派发模板四要素:角色注入、任务与验收标准、边界约束(可读写文件范围)、汇报格式;
• 并发规则:同一文件绝不并发、单轮 2–8 个子任务、有依赖串行无依赖并行、只读任务任意并发;
• 把调度规则挂到入口技能(如 daily-work-start)的最后一步,形成"扫描→计划→确认→并发派发"闭环。

容易漏掉的迁移项(检查清单)

• MCP 服务配置——最大盲区,旧工具的 MCP 不会自动跟过来;每个服务配置后要逐个冒烟验证再写入。
• Windows 环境坑:默认 node 版本可能缺 npm/npx,MCP 配置里用 nvm/uvx 的绝对路径。
• 规则文件里的工具专属内容(shell 方言、IDE 内置命令)要换成新工具等价物或直接废弃。
• 历史遗留的坏模块(从未能启动的 MCP server 之类)标注"未完成",不要假装接入。
• 权限模式(yolo 等)已覆盖的行为,不必再写成项目规则。

原文链接

提炼自 inbox/kimi_code/20260717_bee70a3a.md