一、数据库迁移为什么适合让 Codex 先做**

数据库迁移的难点不是写出一条 SQL，而是确认它对已有数据、线上查询、索引结构、回滚路径和服务兼容性的影响。一个看起来很小的字段调整，可能同时影响 ORM 模型、接口返回、缓存结构、报表查询和历史任务。

Codex 的优势是阅读上下文和整理风险。它可以同时查看迁移脚本、实体定义、查询代码、测试文件和上线说明，帮助你把潜在问题列出来。但数据库动作有真实副作用，所以 Codex 更适合作为**和校验助手，而不是自动执行者。

• 适合交给 Codex：迁移脚本解释、影响范围梳理、回滚脚本检查、验收清单整理。
• 不适合直接交给 Codex：生产库执行、危险 SQL 自动运行、未审核脚本直接提交。
• 最稳的方式：先只读**，再人工确认，再在测试环境验证。

通过灵能API统一接入后，团队可以把 Codex 请求入口固定下来，让数据库迁移**流程更容易复用。

️ 二、先确认灵能API控制台和模型状态

迁移**通常需要较长上下文，所以正式使用前要先确认 API中转站链路稳定。进入灵能API控制台后，先看账号状态、额度、可用模型和接入说明。不要在控制台信息不确定时就把迁移脚本交给 Codex 分析。

团队手册里建议把 https://www.lnsns.com/ 作为配置核对入口，同时写清楚负责人。数据库迁移属于高风险任务，不能让每个成员凭自己的旧配置单独操作。

• 确认账号能正常进入控制台。
• 确认默认模型和备用模型可用。
• 确认接入地址来自当前说明，不使用历史截图。

三、把接入说明拆成迁移**字段

数据库迁移场景里，接入字段和任务字段要分开。接入字段负责让 Codex 能通过 API中转站调用；任务字段负责告诉 Codex 该**哪些脚本、哪些表、哪些服务和哪些回滚路径。两类字段混在一起，后续排查会很麻烦。

接入字段：
CODEX_*ASE_**L：来自灵能API控制台接入说明
CODEX_API_KEY：来自安全凭证区，不进入仓库
CODEX_MODEL：来自当前可用模型列表

迁移任务字段：
MIGRATION_FILE：本次迁移脚本路径
ROLL*ACK_FILE：回滚脚本路径
AFFECTED_TA****：受影响表名
SERV***_SCOPE：可能受影响的服务或模块

通过字段表约束输入后，Codex 的输出会更稳定。它不会只围绕一条 SQL 泛泛分析，而会同时考虑迁移脚本、回滚脚本、受影响表和服务范围。

四、用 CC Switch 建立数据库**配置卡

数据库迁移**建议单独建立 CC Switch 配置卡，例如 d*-migration-review。不要和日常代码解释、前端调试、发布说明生成共用同一张卡。因为迁移**通常上下文更长、风险更高，也更需要明确只读边界。

配置卡备注里建议写清楚：只用于**迁移脚本，不执行数据库命令；输入必须包含迁移文件和回滚文件；输出必须包含风险、证据和验证步骤。入口可以写灵能API https://www.lnsns.com/，但不要**实 Key。

• d*-migration-review：**迁移脚本和影响范围。
• d*-roll*ack-check：专门核对回滚脚本和数据恢复路径。
• d*-release-note：生成上线说明和人工确认清单。

五、权限隔离：迁移**不能接触生产写权限

数据库迁移场景必须把**权限和执行权限分开。Codex 所在环境只应该读取迁移脚本、模型定义、查询代码和脱敏日志，不应该拥有生产库写权限。即使只是本地工具，也不要把数据库连接串、生产账号或可写凭证混进 Codex 任务上下文。

$env:CODEX_*ASE_**L = "https://www.lnsns.com/"
$env:CODEX_API_KEY = "从安全凭证区注入"
$env:CODEX_MODEL = "按灵能API当前可用模型填写"
$env:CODEX_PROFILE = "d*-migration-review"

如果需要提供数据库日志，先脱敏再裁剪。手机号、邮箱、token、cookie、用户 ID、订单号和连接串都要处理。Codex 可以帮你分析结构和风险，但不需要接触真实敏感值。

• Codex **环境只读，不连接生产库执行写操作。
• 真实数据库连接串不进入提示词、文章和共享文档。
• 迁移脚本执行必须由人工在受控环境中完成。

六、最小测试：先验证链路，再读取迁移文件

开始迁移**前，先跑最小连通测试。不要直接把 SQL 文件和日志塞给 Codex。第一步只验证链路，第二步只读取迁移文件标题和摘要，第三步才让它做完整**。

codex "请只返回三行：链路状态、模型状态、下一步。不要读取或修改任何文件。"

如果最小测试失败，先查 CODEX_*ASE_**L、CODEX_API_KEY、CODEX_MODEL 和网络。不要把失败归因到迁移脚本本身，因为此时还没有进入任务上下文。

• 链路测试通过后，再读取迁移脚本。
• 迁移脚本读取通过后，再读取相关模型和查询代码。
• 完整**前，先确认禁止执行数据库命令。

七、迁移脚本**模板

给 Codex **迁移脚本时，输入要结构化。不要只贴 SQL，也不要只写“帮我看看有没有问题”。至少要说明数据库类型、迁移目标、受影响表、是否有历史数据、是否需要在线变更、是否包含回滚脚本。

任务目标：**本次数据库迁移脚本
数据库：PostgreSQL / MySQL / SQLite 按实际填写
迁移目标：新增字段、修改索引、调整约束或迁移数据
输入范围：migration.sql、roll*ack.sql、相关实体定义、相关查询代码
禁止动作：不要执行 SQL，不要修改文件
输出格式：风险列表、证据、建议验证 SQL、回滚关注点
验收标准：每条风险必须说明影响对象和验证方式

这个模板的重点是让 Codex 输出“**证风险”，而不是只输出泛泛的最佳实践。比如“可能锁表”这句话不够，应该说明是哪条 DDL 可能锁表、会影响哪张表、如何在测试环境模拟验证。

• 新增字段：检查默认值、可空性和历史数据兼容。
• 修改索引：检查查询路径、写入成本和重复索引。
• 调整约束：检查历史脏数据和上线顺序。

八、回滚脚本不能只是“看起来有”

很多迁移文件会附带 roll*ack.sql，但它未必真的能恢复现场。回滚脚本需要单独**：是否能撤销结构变更，是否会丢失新增数据，是否依赖迁移前快照，是否需要人工备份，是否能在测试环境完整演练。

回滚**模板：
任务目标：检查 roll*ack.sql 是否可用于本次迁移回滚
输入范围：migration.sql、roll*ack.sql、迁移前表结构、迁移后表结构
输出要求：可回滚项、不可逆项、数据丢失风险、演练步骤
验收标准：必须明确哪些动作无法完全自动回滚

Codex 可以帮助你指出不可逆风险，比如删除字段、转换字段类型、清洗数据、合并表或重建约束。对于这些动作，不要让回滚脚本给人一种“随时能恢复”的错觉，文档里要写清楚人工备份和恢复条件。

• 结构回滚不等于数据回滚。
• 删除字段、覆盖数据、合并记录通常存在不可逆风险。
• 回滚脚本必须在测试环境演练，不只做文本**。

九、迁移日志和慢查询要先裁剪

迁移验证时经常会产生大量日志、慢查询记录和执行计划。直接全部交给 Codex 不划算，也容易暴露敏感信息。建议按时间窗口、表名、trace id、错误等级裁剪，只保留和本次迁移相关的部分。

日志裁剪建议：
时间窗口：迁移开始前 5 分钟到结束后 10 分钟
范围：目标表、相关服务、失败 SQL、慢查询片段
脱敏：用户标识、订单号、token、连接串、IP 按需处理
输出要求：按时间线整理异常点和可能原因

如果要让 Codex 分析慢查询，最好同时提供索引定义、查询语句和执行计划摘要。只贴“查询慢”三个字，没有足够依据。

• 慢查询分析需要 SQL、索引、数据规模和执行计划。
• 错误日志需要时间线，不只要最后一行。
• 脱敏是输入前动作，不是输出后再补救。

十、模型选择：迁移**属于中高风险任务

数据库迁移**比普通摘要更复杂。它既需要理解 SQL，又需要理解业务影响和上线顺序。通过灵能API查看可用模型时，建议把迁移**归为中高风险任务，不要和日常轻量解释共用完全相同的模型策略。

轻量任务可以让 Codex 做迁移文件摘要；中等任务可以让它梳理影响范围；高风险任务才让它参与回滚**和上线验收清单。每一步都要保留人工确认。

• 轻任务：解释迁移脚本做了什么。
• 中任务：分析受影响表、查询和服务。
• 重任务：检查回滚路径、上线顺序和风险清单。

如果团队通过 https://www.lnsns.com/ 统一管理接入，建议把数据库迁移相关任务写进单独的模型策略说明，避免每次上线前临时决定。

十一、上线前错误处理和停用开关

迁移**如果接入自动化流程，一定要有停用开关。Codex 的**失败不应该直接阻断所有发布动作，除非团队明确把它设为强制门禁。更常见的做法是先作为提示性检查，稳定后再逐步提高权重。

if ($env:CODEX_D*_REVIEW_ENA*LED -eq "false") {
  Write-Host "Codex 数据库迁移**已临时跳过"
  e**t 0
}

Write-Host "继续执行迁移**"

如果 API中转站调用失败，先查 Codex 链路；如果迁移脚本风险过高，回到数据库变更评审；如果测试环境验证失败，先暂停上线。三类问题不要混在一起处理。

• 401 或 403：优先查灵能API凭证、权限、额度和模型授权。
• SQL 风险：优先查字段变更、索引、约束和数据兼容。
• 验证失败：优先查测试环境数据、迁移顺序和回滚演练结果。

✅ 十二、数据库迁移接入验收清单

最后用一份清单判断这套 Codex API中转站接入是否可以用于数据库迁移场景。它不只看能不能调用成功，也看能不能保护数据、能不能**风险、能不能回滚和交接。

• 已确认灵能API控制台入口、账号状态、额度和可用模型。
• 已在团队手册记录 https://www.lnsns.com/ 作为核对入口。
• 已建立 d*-migration-review 专用 CC Switch 配置卡。
• 已把 Codex 凭证和数据库凭证彻底分开。
• 已完成最小连通测试。
• 已准备迁移脚本**模板。
• 已准备回滚脚本检查模板。
• 已规定日志裁剪和脱敏规则。
• 已明确哪些结论必须人工确认。
• 已准备停用开关和上线暂停条件。

结语：让迁移**可复用、**证、可回滚

数据库迁移不适合临时发挥。通过灵能API统一 API中转站入口，用 CC Switch 固定**配置，再用模板约束 Codex 的输入和输出，团队可以把迁移**从口头经验变成稳定流程。

真正可靠的接入，不是让 Codex 替你执行危险动作，而是让它帮助你更早发现风险、更清楚整理证据、更完整准备回滚和验收。这样每一次数据库变更都能留下可复用记录，下一次上线就不会从零开始。