配置迁移与向后兼容策略

配置迁移与向后兼容策略

学习目标

• 理解双名共存的迁移路径设计
• 掌握配置文件自动迁移流程
• 识别新旧配置并存时的优先级问题

前置知识

本章涉及插件系统跨宿主移植的通用原理，建议先阅读：

• 跨宿主可移植性

下文假设你已理解跨宿主移植概念，直接聚焦 Oh-My-OpenAgent 的具体实现。

项目实践

双名共存

Oh-My-OpenAgent 正在从 oh-my-opencode 重命名为 oh-my-openagent，但为了向后兼容，两者同时有效：

维度	旧名	新名
npm 包名	oh-my-opencode	oh-my-openagent（双发布）
CLI 命令	oh-my-opencode	oh-my-openagent（指向同一二进制）
插件入口	"oh-my-opencode"	"oh-my-openagent"
配置文件	oh-my-opencode.json[c]	oh-my-openagent.json[c]

配置文件自动迁移

位于 src/shared/migrate-legacy-config-file.ts：

迁移流程：

1. 扫描配置目录，检测旧文件名（oh-my-opencode.json[c]）
2. 复制到新文件名（oh-my-openagent.json[c]）
3. 保留旧文件但标记为 legacy
4. 启动时发出警告：Legacy config detected: oh-my-opencode.jsonc, migrated to oh-my-openagent.jsonc

插件入口检测

位于 src/shared/plugin-entry-migrator.ts：

// opencode.json 中的 plugin 数组同时接受新旧名称
"plugin": ["oh-my-openagent"]  // 推荐
"plugin": ["oh-my-opencode"]   // 兼容，发出警告

doctor 命令

bunx oh-my-openagent doctor 内置诊断：

• 检测旧包名是否仍在使用
• 检测旧配置文件是否存在
• 检测 OpenCode 版本兼容性
• 检测模型配置是否正确

为什么不完全重命名

• npm 包名已发布：已有用户依赖 oh-my-opencode，无法强制切换
• 用户配置惯性：用户可能已有大量 oh-my-opencode.jsonc 配置
• 渐进式迁移：通过警告提示引导用户逐步切换，而非一次性破坏

问题与规避

新旧配置并存优先级

问题：用户同时存在 oh-my-opencode.jsonc 和 oh-my-openagent.jsonc，不清楚哪个生效。

规避：

• 配置文件层级查找中，新文件名优先级高于旧文件名（同目录内）
• doctor 命令明确告知哪个配置生效
• 启动日志中列出已加载的配置文件路径

迁移过程中的数据丢失

问题：自动迁移可能丢失旧配置中的注释或格式。

规避：

• 使用 JSONC 解析器保留注释和格式
• 迁移是复制而非移动，旧文件保留
• 仅在内容确实变更时才写入新文件

设计取舍

双名共存 vs 强制迁移

方案	优势	代价
双名共存	零破坏性迁移、用户可按需切换	维护两套名称的兼容逻辑
强制迁移	代码简洁、无兼容负担	破坏已有用户配置

Oh-My-OpenAgent 的选择：双名共存，因为用户配置的破坏性变更会导致严重的信任问题。在过渡期结束后（用户大多迁移后）再移除旧名支持。

参考来源

• Oh-My-OpenAgent 配置文档
• 跨宿主可移植性