迁移指南
通用升级步骤
1
阅读破坏性变更通知
查看 破坏性变更页面，了解每个项目版本中影响 API 契约的变更。
2
检查依赖版本
确认当前使用的版本号，使用 --version 或查看 VERSION 文件。对于 npm 包使用 npm outdated 检查。
3
更新代码适配
根据迁移指南修改代码中涉及的 API 调用、配置格式和数据结构。优先在非生产环境测试变更。
4
运行测试验证
执行项目自带的测试套件（pnpm test / uv run pytest），确保所有功能正常。
各项目迁移示例
Orchidea Code
从
0.26.x（.coderules 格式） → 0.27.0+（.orchidearc.yaml 格式） 1. 运行 `orchidea migrate config` 自动迁移配置文件
2. 检查生成的 `.orchidearc.yaml` 确认所有配置项正确
3. 删除旧的 `.coderules` 文件
4. 重新执行 `orchidea check` 验证环境正常
Orchidea Platform
从
1.x（REST API v1） → 2.0.0+（GraphQL API v2） 1. 将所有 REST API 调用迁移至 `/api/v2/graphql` GraphQL 端点
2. 更新 DocType 引用为 ISA95* 前缀（Enterprise → ISA95Enterprise）
3. 数据库迁移脚本自动执行，无需手动操作
4. 运行集成测试套件确认所有查询正常
Orchidea LLoT
从
0.9.x（旧配置结构） → 1.0.0+（新 Helm values 结构） 1. 更新 Helm values 中 OPC UA 连接器配置：endpoint → host/port/path
2. 更新 Sparkplug B Topic 命名空间：spBv1.0/ → orchidea/v2/
3. 对比新版 values.yaml 模板，确认所有键名一致
4. 在测试集群中 dry-run 后执行 `helm upgrade`
Orchidea Director
从
0.x（REST Agent 注册） → 1.0.0+（ACP 协议注册） 1. 将 Agent 适配为 ACP (Agent Client Protocol)
2. 更新 Agent 注册端点为 ACP 握手端点
3. 参考 `/docs/director/acp-migration` 中的完整示例
4. 在开发环境验证 Agent 成功注册并接收任务
Orchidea Desktop
从
0.0.x（CommonJS 插件） → 0.1.0+（ESM 插件） 1. 将插件入口文件改为 `.mjs` 扩展名
2. 将 `require/module.exports` 语法改为 `import/export`
3. 更新插件的 `package.json` 中 `type` 字段为 `module`
4. 重新加载插件并验证功能正常
暂无迁移需求的项目
以下项目当前 API 契约稳定，未发布破坏性变更，无需迁移操作。
✓
Orchidea Plex 本体知识图谱，架构稳定暂无破坏性变更
✓
Orchidea Archive 知识档案服务，API 保持向后兼容
✓
Orchidea Protocol 协议定义库，semver 严格遵循主版本兼容策略
✓
Orchidea Watch 可观测性平台，遥测 API 保持稳定
✓
Tian-Vision 文档理解服务，API 向后兼容
版本锁定建议
npm 包：使用波浪号或脱字符精确锁定版本，如 npm install @orchidea/protocol@~1.0.0
Python 包：在 requirements.txt 中固定版本，如 orchidea-telemetry==1.0.0
Docker 镜像：使用具体版本标签而非 latest，如 ghcr.io/orchideaai/platform:2.0.0
桌面应用：关闭自动更新（如需要），在设置中锁定到特定版本通道。