Convex Migration Helper 是用于在 Convex 中进行 schema 与数据迁移的 agent skill。它面向需要对既有数据做破坏性变更的场景，帮助规划和执行迁移，尽量保持应用在迁移期间可运行。
用途 当 schema 变更会影响已有数据时使用，包括：向已有表添加新的必填字段；修改字段类型或结构；拆分或合并表；重命名字段；从嵌套数据迁移为关系型数据。Convex 不会自动迁移数据，因此这些变更需要显式迁移代码。
迁移原则 Convex 不会自动迁移数据。新增可选字段或新表属于安全的加法变更；必填字段和类型变更需要迁移代码；迁移应设计为零停机，使应用在迁移过程中继续运行。
安全变更（无需迁移） 新增可选字段，例如从只有 name 的 users 表增加 bio: v.optional(v.string())；新增完全独立的表，例如 posts 表；新增索引，例如为 users 增加 by_email 索引，这些都可直接进行。
破坏性变更（需要迁移） 添加必填字段：先以可选字段加入，再回填数据，最后改为必填。示例迁移使用 internalMutation，通过 ctx.db.query("users").collect() 遍历，对缺失 email 的用户用 ctx.db.patch 写入默认值，随后通过 npm 命令 npx convex run migrations:backfillEmails 运行，最后在 schema 中把字段设为必填。 修改字段类型：以 tags 从 v.array(v.string()) 改为独立表为例，先新增 tags 与 postTags 表及索引，保留旧字段为可选；再编写 migrateTags，分批处理，按名称查找或创建 tag，并建立 post 与 tag 的关系，最后移除旧字段。迁移可通过 cron 或手动多次运行。 重命名字段：先添加新的可选字段 displayName，再用迁移把 name 的值复制到 displayName，随后更新 schema 移除旧字段，并更新所有使用新字段名的代码。
迁移模式 批量处理：对大型表使用分批迁移，返回 processed 与 hasMore，配合游标或 take(batchSize) 分批执行。 定时迁移：通过 convex/crons.ts 配置 cronJobs，例如每 5 分钟运行 internal.migrations.migrateBatch，batchSize 为 100。 双写模式：迁移期间同时写入旧结构与新结构，迁移完成后再移除旧写入。
测试与验证 可编写 verifyMigration 查询，统计总数、已迁移数量、剩余数量与完成百分比，以确认所有记录都已更新。
迁移清单 识别破坏性变更；以可选或附加方式添加新结构；编写内部 mutation 迁移函数；在样本数据上测试；大数据集分批运行；验证所有记录完成迁移；更新应用代码使用新结构；部署新代码；从 schema 移除旧字段；清理迁移代码。
常见陷阱 不要立即把字段设为必填；不要用单个事务迁移大数据；不要忘记更新查询；不要过早删除旧字段；先在生产环境之外的开发环境充分测试。
完整示例流程 从 users 只有 name 的 schema 开始，添加可选 role 字段，编写 addDefaultRoles 为缺失 role 的用户补默认值，运行 npx convex run migrations:addDefaultRoles，验证后把 role 改为必填联合类型。
限制与暂未提供信息 该技能聚焦 Convex schema 与数据迁移；关于收费、价格、平台支持范围、性能数据、具体版本要求等，资料暂未提供。