FastGPT 系统升级脚本开发规范

目标与边界

系统升级任务属于 App 部署生命周期能力。框架负责顺序、状态、每任务 lease 互斥、启动依赖链、后台普通队列与独立任务调度、重试入口和最终状态；脚本只负责可重复执行的业务迁移、进度、checkpoint，以及结构化错误报告。

开始前先查看当前实现，不能凭本 Skill 猜测已经变化的 Context 或目录结构：

• projects/app/src/migration/registry.ts
• projects/app/src/migration/runner.ts
• projects/app/src/migration/plan.ts
• projects/app/src/migration/startup.ts
• packages/global/migration/constants.ts
• packages/global/migration/schema.ts
• projects/app/src/migration/tasks/README.md
• 注册表中最近一个任务及其测试

如果这些路径正在迁移，以仓库中 systemMigrations 和 SystemMigrationContext 的实际定义为准。迁移执行框架和任务实现收敛到 projects/app/src/migration；需要被 App 前后端共同使用的状态枚举、Zod Schema 和 API 类型放在 packages/global/migration。

编写前必须确认

先明确以下契约；存在会改变数据安全或启动行为的缺失信息时，向用户确认后再编码：

1. 永久稳定的任务 ID，格式为 YYYYMMDD_short_semantic_name，以及首次发布版本（对应版本目录去除点号，例如版本 4.17.0 对应目录 4170，4.17.1 对应 4171）。
2. 源数据、目标数据、权威数据源和迁移完成条件。
3. 该任务为什么必须排在当前注册表末尾，以及它依赖哪些前置任务。
4. 选择启动阻塞、普通自动、延迟自动、手动触发或独立模式；显式声明所有真实的成功前置。启动阻塞任务及其完整依赖链必须在 App 业务启动前成功；后台失败只影响自身与依赖它的任务，后台独立任务必须不依赖其他迁移且允许并发执行。
5. 恢复策略是“分批断点续跑”还是“幂等全量重跑”。该策略发布后不能切换。
6. 重复执行的幂等依据：唯一键、确定性覆盖、$setOnInsert、compare-and-set 或事务性全量重建。
7. 数据规模、预期耗时、批次大小和内存上界。
8. 坏数据是立即终止，还是跳过、汇总后由管理员修复再重试。
9. 滚动升级期间，旧版本节点是否仍能安全读写迁移中的结构。
10. 成功校验、失败回滚方式，以及需要展示给管理员的进度和错误定位数据。

不要用“目标表存在”“目标表非空”或当前数据形态替代任务状态。是否需要执行只能由静态注册表和迁移状态决定。

基本要求

• 注册表只允许在数组尾部追加。已发布任务的 ID、顺序、调度模式、依赖和函数语义不得修改、删除或复用；修复已发布迁移时追加新任务。
• 完整任务及其可能重放的最小单元必须幂等。Lease 只保证同一时刻的执行权，不提供 exactly-once。
• 默认追加或回填，不删除旧字段、旧集合、回滚依据或用户数据。破坏性清理应放到后续兼容窗口结束后的独立任务。
• 自动迁移必须兼容滚动升级；要求全站停机或会立即破坏旧版本的变更不能直接进入该注册表。
• 禁止不可重放的外部副作用，例如无幂等键的消息、扣费或第三方写入。
• 所有业务写入必须有确定性，不能根据不稳定排序、offset 分页或随机值决定结果。
• 修改目标前验证源数据；返回前校验完成条件。不能仅因函数没有抛错就假设迁移完成。
• 日志、进度、最终结果、checkpoint 和错误数据不得包含凭证、完整业务正文、超大对象或完整错误栈。
• 迁移专属实现不得放入业务 DDD 模块。业务模块可以被迁移单向依赖，但不能反向依赖迁移目录。

状态与 Context

状态所有权