为 FastGPT 新增、修改或审查自动系统升级脚本及其注册信息。涉及系统迁移、升级任务、启动迁移、migration registry、checkpoint、全量重跑、独立模式、进度或失败数据时使用;普通业务更新和未接入自动升级框架的一次性手工清洗不使用。
90%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
系统升级任务属于 App 部署生命周期能力。框架负责顺序、状态、每任务 lease 互斥、启动依赖链、后台普通队列与独立任务调度、重试入口和最终状态;脚本只负责可重复执行的业务迁移、进度、checkpoint,以及结构化错误报告。
开始前先查看当前实现,不能凭本 Skill 猜测已经变化的 Context 或目录结构:
projects/app/src/migration/registry.tsprojects/app/src/migration/runner.tsprojects/app/src/migration/plan.tsprojects/app/src/migration/startup.tspackages/global/migration/constants.tspackages/global/migration/schema.tsprojects/app/src/migration/tasks/README.md如果这些路径正在迁移,以仓库中 systemMigrations 和 SystemMigrationContext 的实际定义为准。迁移执行框架和任务实现收敛到 projects/app/src/migration;需要被 App 前后端共同使用的状态枚举、Zod Schema 和 API 类型放在 packages/global/migration。
先明确以下契约;存在会改变数据安全或启动行为的缺失信息时,向用户确认后再编码:
YYYYMMDD_short_semantic_name,以及首次发布版本(对应版本目录去除点号,例如版本 4.17.0 对应目录 4170,4.17.1 对应 4171)。$setOnInsert、compare-and-set 或事务性全量重建。不要用“目标表存在”“目标表非空”或当前数据形态替代任务状态。是否需要执行只能由静态注册表和迁移状态决定。
| 状态 | 谁负责写入 | 触发条件 |
|---|---|---|
pending | 框架 | 首次初始化,或管理员将失败任务恢复为待执行 |
running | Runner | 原子获得 lease,并生成新的 runId |
failed | Runner / context.fail | 脚本明确报告失败,或普通异常被 Runner 捕获 |
succeeded | Runner | 脚本正常返回且当前 runId 仍持有有效 lease |
脚本禁止直接操作迁移状态表和错误数据表,也不得主动设置 pending、running、failed 或 succeeded。所有运行状态写入必须经过 Context,让框架统一执行 runId fencing 和输入校验。
context.reportProgress(...):按注册表声明的阶段 key 更新该阶段快照。进入阶段时上报 running,完成后上报 succeeded;分批任务按合理频率更新 current/total,不要每条数据写一次。脚本不得主动上报 failed。context.getCheckpoint(schema):读取并用任务自有 Zod Schema 校验断点。仅分批任务使用。context.getFailedRecords():读取上次失败留下的坏数据。若任务曾跳过坏数据并把 checkpoint 推进到其后,重试时必须先处理这些记录。context.reportFailedRecords(records):按批替换“当前完整未解决错误快照”。业务批次提交后应先上报错误快照,再推进 checkpoint;替换语义保证批次重放不会重复追加同一错误。context.saveCheckpoint(value):只在一个幂等批次的业务事务完整提交、错误快照成功持久化并校验后保存。禁止先保存 checkpoint 再写业务数据或上报该批错误。context.assertActive():确认当前 runId 仍持有 lease。每个业务写入批次前必须调用;全量任务至少在关键事务前及事务后的后续阶段前调用。context.fail(...):保存可预期的结构化错误及最终错误快照,并终止本次执行。供需要在管理页面排障和重试的任务使用;不要在调用后继续业务逻辑。context.logger:记录诊断信息,框架会附加 migrationId、runId 和 runnerId。日志不能替代进度或结构化失败。context.signal:长计算或可取消 I/O 应响应中止信号。正常返回表示脚本认为业务迁移和完成校验均已成功,由 Runner 标记 succeeded 并清理该任务的错误明细。任务可以返回有限标量的业务参数对象;Runner 校验后把参数与 succeeded 原子写入,列表接口再从静态注册表取得 resultKey 组装展示结果。nameKey、descriptionKey、resultKey 和阶段 labelKey 必须在注册表中使用 i18nT(...) 声明,禁止把 i18n key 写入 Mongo。不要自行调用完成状态更新,也不要用最后一条 progress 代替最终结果。
普通 throw 也会进入 failed,Runner 会把错误归属到当前 running 阶段,并保留任务之前通过 reportFailedRecords 上报的最新快照。只有 context.fail 显式携带 failedRecords(包括空数组)时才替换或清空旧快照。任务的已知数据问题应维护完整未解决错误快照:处理中按批调用 context.reportFailedRecords,扫描结束仍有异常时再调用 context.fail 写入相同最终快照。错误对象只保存原始 message,不得携带 i18n key 或模板参数;每条错误数据必须包含已声明的 stageKey,只保存必要 ID 和原因,不复制原文档。框架按阶段记录异常数量,管理员从对应阶段按需打开详情。后台任务失败后停止 heartbeat,管理员修复后通过页面重试。启动链失败后持续续租,页面不可用,通过日志定位并修复,重启 lease owner 后等待过期接管;独立前置提升为启动任务后同样遵守此规则。
任务一旦获得新 runId,无论入口是管理员重置还是过期 lease 接管,都使用同一恢复策略:保留 checkpoint、progress 和最近错误;任务还会保留供修复使用的错误明细。但触发条件不同:后台只有 running 的 lease 过期可自动接管,failed 必须由管理员重置为 pending。启动链的 failed 由存活 owner 持续续租;修复并重启该 owner 后,过期 failed 允许原子接管,不允许在线重置。脚本如何恢复由发布时选定的策略决定。
适用于数据量较大、执行时间不可控、无法在一个短事务内完成,或需要跳过坏数据继续扫描的任务。
每次执行必须覆盖三种输入状态:
推荐循环:
读取并校验 checkpoint
读取 failedRecords,建立完整未解决错误快照并优先重试
while 还有数据:
assertActive
按稳定游标读取下一批
在业务事务中执行幂等写入
校验该批结果并提交事务
如果错误快照变化,reportFailedRecords(完整未解决错误快照)
saveCheckpoint
reportProgress
执行全局完成校验
如果仍有错误,fail(包含相同最终错误快照)
reportProgress(completed)
return关键约束:
_id 或其他不可变、唯一且有索引的游标;不要使用 offset。reportFailedRecords 接收的是完整快照而不是新增项;不得逐条 append,也不得只上报当前批次,否则会覆盖之前仍未解决的错误。context.fail({ failedRecords }),其中 failedRecords 与最近一次上报的完整快照一致。仅适用于数据量确定较小、资源消耗有上界、结果由权威源确定,且整次写入可以保持原子或安全幂等的任务。
推荐流程:
reportProgress(started)
读取完整权威源
在修改目标前完成全部转换、去重和校验
assertActive
原子写入或确定性覆盖完整结果
assertActive
刷新缓存并执行完成校验
reportProgress(completed)
return关键约束:
plan.ts 校验注册表,递归收集所有 blockStartup: true 根任务与其 dependsOn 闭包。依赖只允许引用更早注册的任务,闭包按原注册顺序串行执行,跳过无关任务;独立前置被提升后不竞争后台 Redis 名额。启动链不得包含 manual 或 delay,根任务不能同时声明 independent。
所有节点等待完整启动链持久化为 succeeded,缺失、读取异常、pending、running、failed 都不放行。随后每个节点重载本地模型缓存、启动业务消费者,最后启用后台迁移。共享状态成功不能代替跟随节点的缓存重载;App 屏障不停止旧版本节点或独立 Pro 服务,仍需证明滚动升级兼容。
blockStartup: true,自身及递归前置成功前阻塞 App readiness。当前仅旧系统模型迁移声明该模式。delay: true,获得 lease 后等待 SYSTEM_MIGRATION_DELAY_SECONDS 秒,默认 0,期间占用后台普通队列。manual: true,初始 waiting;管理员确认前提后入队,随后使用后台普通队列。不能与 delay 或 independent 同时启用,也不能出现在启动闭包中。independent: true,启动链完成后每个任务单独调度,不受后台普通队列顺序约束;所有节点通过 Redis LeaseCache.withConcurrency 共享 3 个名额,先取得名额再竞争任务 Mongo lease。不能与 blockStartup、manual、delay 或非空 dependsOn 同时启用。dependsOn 只能引用更早注册的任务。普通任务可依赖独立任务;所有前置成功前不得执行。被启动链引用的前置统一提升,列表 DTO 返回有效 blockStartup=true、independent=false。迁移执行框架、静态注册表、Mongo Schema、服务端执行逻辑和任务集中在 App;前后端公共契约位于 global:
packages/global/migration/
├── constants.ts
└── schema.ts
projects/app/src/migration/
├── constants.ts
├── registry.ts
├── plan.ts
├── startup.ts
├── runner.ts
├── entity.ts
├── service.ts
├── mongoSchema.ts
├── utils.ts
└── tasks/
├── README.md
└── <version>/
└── <migration-id>/
├── index.ts
├── service.ts
└── utils.tsindex.ts 只负责任务编排、Context 调用和进度阶段。tasks/<version>/<migration-id>/ 目录规范定义,严禁在 tasks/ 根目录下平铺存放迁移脚本。其中 <version> 对应发布版本(无点号,如 4.17.0 对应 4170,4.17.1 对应 4171),<migration-id> 为具体迁移任务 ID。tasks/<version>/<shared_helper_dir>/),严禁在 tasks/ 根目录下平铺。packages/global/migration 只保存前后端共享的状态枚举、有限输入 Schema 和 API 类型,不放任务实现、Mongo Model 或 Runner。progressSteps: [{ key, labelKey }];key 是永久稳定的机器标识,labelKey 放在 client-only system_migration i18n namespace,不写入 Mongo。packages/global 或 packages/service。pages/api、pages/admin,但必须是调用 migration service 的薄入口,不承载迁移逻辑。i18nT(...) 保存稳定的 name、description、result 和 progress label key。message。projects/app/test/migration/ 下并严格镜像源码子路径(即 projects/app/test/migration/tasks/<version>/<migration-id>/)。新增任务至少验证与其恢复策略相关的真实不变量,不写只匹配文案的测试。
通用场景:
首次执行成功,完成条件真实成立。
重复执行不会产生重复、覆盖错误数据或改变不应变化的结果。
源数据无效时不会留下部分目标数据,并能给出可定位错误。
业务写入或完成校验失败时不会被标记成功。
进度阶段、失败记录和日志不包含敏感或无界数据。
每个阶段均按 running -> succeeded 上报;任务返回前所有声明阶段都已成功,阶段异常和错误数据使用正确的 stageKey。
最终结果只在任务成功后存在;Mongo 只含参数,列表接口从注册表补入 key 后能渲染出预期业务结果。
任务注册在数组尾部,ID 唯一,调度模式与显式前置依赖符合业务要求。
启动依赖闭包优先执行、共享前置不重复、独立前置提升、手动/延迟前置拒绝;每个节点先等待再重载模型,之后才启用业务与后台任务。
启动链 throw/context.fail 均持续续租并保持未就绪;owner 停止且 lease 过期后多节点只能一个接管,恢复数据保留;管理接口拒绝在线重试启动链。
分批任务额外验证:
全量任务额外验证:
只运行覆盖改动范围的局部测试、App typecheck、相关 ESLint 和 git diff --check。用户最终验收前不主动运行全量测试。若修改 API 路由或入参,继续遵守 api-development Skill;若新增单元测试,继续遵守 test-case Skill。
labring/FastGPT
3b0ad50
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.