# System Migration Development

为 FastGPT 新增、修改或审查自动系统升级脚本及其注册信息。涉及系统迁移、升级任务、启动迁移、migration...

- Repository: https://github.com/labring/FastGPT (29968 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add labring/FastGPT --skill system-migration-development -g -a claude-code -y`
Codex: `npx skills add labring/FastGPT --skill system-migration-development -g -a codex -y`
Cursor: `npx skills add labring/FastGPT --skill system-migration-development -g -a cursor -y`
Gemini CLI: `npx skills add labring/FastGPT --skill system-migration-development -g -a gemini-cli -y`

## Description

为 FastGPT 新增、修改或审查自动系统升级脚本及其注册信息。涉及系统迁移、升级任务、启动迁移、migration registry、checkpoint、全量重跑、独立模式、进度或失败数据时使用；普通业务更新和未接入自动升级框架的一次性手工清洗不使用。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

### 状态所有权

The rest: https://github.com/labring/FastGPT/blob/HEAD/.agents/skills/system/system-migration-development/SKILL.md