用途:检测 Maestro 工作流当前版本,预览迁移计划,并执行版本升级与 schema 迁移。版本来源为 .workflow/state.json 的 version 字段;工作流更新文档位于 ~/.maestro/workflows/updates/。
主要能力与用法:
- 版本检测:读取 .workflow/state.json 提取 version,缺失时默认 1.0;缺失或不可读报 E001,需先运行 /maestro-init。
- 检查更新:执行 maestro update --migrate "$(pwd)" --dry-run --json 解析 JSON;已是最新则提示并退出。
- 执行升级:显示迁移 diff,确认后备份 cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp},再运行 maestro update --migrate "$(pwd)" --json 自动处理中间版本;失败显示恢复命令并退出。
- 版本专属 setup:读取 ~/.maestro/workflows/updates/update-v{target}-setup.md 并完整执行;不存在则仅 schema 迁移(W001)。
- 参数:--dry-run 仅预览不执行;--force 跳过确认但仍显示迁移 diff;--setup-only 跳过 schema 迁移,仅执行当前版本 setup(无脚本则 W002)。
阶段门:检测→检查需读取到版本,否则阻塞;检查→执行需完成 dry-run 且用户确认(除 --force);执行→总结需先备份、迁移成功并遵循 setup 文档。
写入边界:所有文件写入只能针对 .workflow/state.json(版本提升)、.workflow/state.json.backup-*(备份)以及版本专属 setup 涉及的 .workflow/ 配置文件;绝不修改源代码或 src/migrations/ 文件。
适用场景:需升级 Maestro 工作流并自动完成 schema 迁移的开发者环境。限制:涉及强制改动的自动化需谨慎;有活动 worktrees 时会警告(W003),迁移可能导致合并不兼容,建议先合并。错误码:E001 需先运行 /maestro-init;E002 迁移失败显示备份恢复命令 cp .workflow/state.json.backup-* .workflow/state.json;E003 setup 文档执行失败需手动执行。输出上限和错误码之外的细节暂未提供。