DB Migration Helper 是一个根据模型或 schema 变更生成数据库迁移 SQL 的工具技能，主要用于分析 model 变更并生成安全的数据库迁移 SQL。
用途 该工具用于对比代码中的实体/模型定义与当前数据库 schema，检测结构变更（如新增表、增删列、改类型），并生成向前兼容的迁移 SQL，同时输出可回滚的 Down 迁移与风险评估。它支持 MySQL、PostgreSQL 和 SQLite。
适用时机 当用户想要创建数据库迁移、修改了 model/entity 定义、提到 migration、schema change 或 sync、说出“生成迁移” / “create migration”，或输入 /db-migration-helper 时使用。 不适用：用户只想查看数据库结构、想要数据迁移（非 schema）、使用 ORM 自动迁移、想要生成种子数据，或想要备份/恢复数据库。
主要能力与工作模式
- 检测项目类型和 ORM：根据检测文件识别 ORM/框架与迁移方式。例如 prisma/schema.prisma 对应 Prisma（生成 SQL diff）；alembic/ 对应 SQLAlchemy + Alembic（生成 Alembic migration）；migrations/ 对应通用（扫描已有迁移推断）；*.entity.ts / *.model.ts 对应 TypeORM / Sequelize（从装饰器提取）；schema.rb / db/migrate/ 对应 Rails（Rails migration）。
- 提取当前 Schema：可通过 npx prisma db pull 从 Prisma 提取（v2.18+，旧命令 introspect 已更名为 db pull），或从代码中提取表名和列定义、列类型、约束（NOT NULL、DEFAULT、UNIQUE）、索引和外键。
- 对比变更：对比代码中的 model 定义与已有 schema（或上一次迁移），检测变更类型并标注风险等级。变更类型包括：新增表（低风险，直接 CREATE TABLE）、新增列（有 DEFAULT 低风险，ALTER TABLE ADD COLUMN；无 DEFAULT 中风险，需要处理已有数据）、删除列（高风险，可能丢失数据，需要确认）、修改列类型（高风险，可能不兼容）、新增索引（低风险，CREATE INDEX）、删除索引（低风险，DROP INDEX）。
- 生成迁移文件：使用 templates/migration.sql 模板，生成 Up 迁移（正向变更 SQL）、Down 回滚（反向回滚 SQL）以及风险评估（标注高风险操作）。示例： -- Migration: 20260603_add_user_avatar -- Risk: LOW
-- Up ALTER TABLE users ADD COLUMN avatar_url VARCHAR(500); CREATE INDEX idx_users_email ON users(email);
-- Down DROP INDEX idx_users_email; ALTER TABLE users DROP COLUMN avatar_url;
使用方式 命令示例： /db-migration-helper # 检测变更，生成迁移 /db-migration-helper --dry-run # 只预览 SQL 不执行 /db-migration-helper --name add_user # 指定迁移名称
参数说明： --dry-run：只预览不执行，默认 false --name：迁移文件名，默认自动生成 --output：输出目录，默认 ./migrations/
适用场景 适用于需要从模型变更生成结构化迁移 SQL 的场景，例如项目使用 Prisma、SQLAlchemy + Alembic、TypeORM、Sequelize 或 Rails，且需要生成向前兼容、可回滚的迁移。
限制与注意事项 不适用于仅查看数据库结构、数据迁移（非 schema）、ORM 自动迁移、生成种子数据或备份/恢复数据库。常见错误包括：不生成 down 回滚（应始终生成回滚 SQL）；删除列不备份（应先备份数据再删列）；改类型用 ALTER COLUMN（PostgreSQL 可直接 ALTER COLUMN ... TYPE ... USING ...，MySQL 用新建列 → 迁移数据 → 删旧列，因为 MySQL 直接改类型可能丢数据，PG 的 USING 是原子转换）；不加索引（应为查询字段加索引）；迁移文件没有名字（应用描述性命名）；不检查外键依赖（应先检查表间关系，删除被引用的列会失败）。