19 · 升级与迁移指南

版本：0.1.0。所有持久化格式都带 version 字段；不兼容变更升 major。

19.1 版本矩阵

19.2 兼容策略

• 新增可选字段 → minor；运行时忽略未知字段（serde default）。
• 改变字段语义/删除字段 → major；旧运行时拒绝。
• Trace/Checkpoint 的 state_hash 包含 schema 字段；加字段会改变 hash，需要重新生成 golden/fixtures。
• 协议：新 coordinator 对旧 worker 的未知请求会得到 error；灰度时先升级 worker。

19.3 从 0.1.0 升级

0.1.0 是首个版本。未来升级步骤：

1. 读 CHANGELOG.md 的 Breaking changes。
2. 备份 WAL/trace/checkpoint。
3. 先升级 worker（向后兼容期），再升级 coordinator。
4. 跑 ain check + cargo test --workspace + pnpm check。
5. 用旧 trace 跑 ain flow replay，确认 state_hash；如 schema 变更，按迁移脚本重放。

19.4 迁移示例（未来大版本）

# 1) 导出旧 FlowSpec
ain flow compile old.flow > old.json

# 2) 用新版本重新编译（推荐）
ain flow compile old.flow > new.json

# 3) 对比
diff <(jq -S . old.json) <(jq -S . new.json)

# 4) 重放旧 trace（若 schema 兼容）
ain flow replay new.json old-trace.json

19.5 不兼容变更检查表

• NetJson.version / FlowSpec.version
• Trace.version / Checkpoint.version
• state_hash golden 更新
• specs/* 更新
• CHANGELOG.md 写 Breaking changes
• 示例/fixtures 重新生成
• docs/ 迁移说明

在 GitHub 编辑本文