For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /features/ai-precheck.md.
  • 简体中文
  • 提单、大批量导入与 AI 预审实战

    本手册面向研发工程师,带你一步步完成一次标准的 DDL/DML 变更工单提交、大批量 .sql 文件导入、看懂 AI 预审报告与处理门禁阻断。

    AI SQL 预审弹窗:实时展示阶段进度、折叠指纹组数、风险发现详情与提交审批入口
    AI SQL 预审弹窗:实时展示阶段进度、折叠指纹组数、风险发现详情与提交审批入口

    1. 创建变更工单操作步骤(/changes/new)

    1. 在左侧菜单点击 工单提交(/changes/new)。
    2. 依次填写表单:
      • 标题:简要说明变更目的(例如 订单表新增结算状态索引)。
      • 审批流程:从你的权限组已获授的 change_review 流程中选择(注意:多阶段流程会同时列出预发和生产两个目标库,提交前系统会对每个阶段分别预审)。
      • 期望执行时间(可选):如希望审批通过后在指定窗口自动由执行人预约,可提前预填。
      • 启用回滚保护:建议对 INSERT / UPDATE / DELETE 与可逆 DDL 保持开启,执行期自动捕获事务内前像生成回滚 SQL(详见 回滚工单实战)。
    3. 输入或导入 SQL:
      • 直接在编辑器粘贴纯 DML 或纯 DDL 语句(严禁在同一工单混写 DML 与 DDL,否则报 2001;SELECT 查询请移步 /query)。
      • 若是大批量数据订正,可直接将本地 .sql / .txt 文件拖入右侧导入区(单工单最高支持 32 MiB / 100,000 条语句,单条上限 512 KiB;超过 512 KiB 或 1,000 条时界面自动切换为虚拟化语句浏览器防卡顿)。
      • 如果暂时不提交,可点击 保存并返回 存为草稿(随时在 /changes/mine 继续编辑)。

    2. 运行 AI SQL 预审并读懂结果

    点击 运行 AI 预审 后,预审弹窗自动打开并实时推进进度条:

    1. 阶段 1(词法解析与双指纹折叠):
      • 若存在语法错误,弹窗立即返回 2003 SQL_PARSE_FAILED 并指出精确行号、列号、语句序号与方言错误原因,直接按行号修改即可。
      • 若批量脚本里有 50,000 条同构 UPDATE 语句,系统按 Canonical + Dialect 双指纹自动折叠为 1 个指纹组(单工单硬上限 1,000 组不同模板,超限报 2006 需拆单)。
    2. 阶段 2(规则校验 + 5 项只读元数据工具探测):
      • 系统通过目标库只读账号自动探测真实表结构、索引列顺序、表行数与 EXPLAIN 预估扫描行数。
      • 在 风险发现 标签页中,你将看到已经自动还原为真实表名/列名的排查说明(模型侧与持久化证据始终保持匿名)。

    如何判断能不能提交?(3 类发现一眼分辨)

    发现类型页面显示级别能否提交你该怎么处理
    强制规则命中(policy_finding)Critical(红)阻断(2008)违反了团队启用的内置/自定义规则或表级内部经验(如缺 WHERE、缺主键、超过 max_affect_rows),必须修改 SQL 后重跑预审
    运行时证明无效(proven_invalid_execution)Critical(红)阻断(2008)目标库里不存在该表/该列,或重复建已有索引/列,核实目标库表结构并修正 SQL
    模型观察建议(agent_observation)最高 Medium(黄/蓝)放行AI 结合执行计划给出的优化参考,无需强改,审批人也可在工单中看到
    元数据不完整(partial)Partial(黄)阻断目标库只读账号缺表权限、网络超时或 PG search_path 异常,联系 DBA 检查数据源

    真实踩坑示例:被门禁拦截后如何修正

    假设提交了如下语句:

    -- ❌ 触发两项阻断:1) 无 WHERE/索引全表扫描超过 max_affect_rows;2) 混合了 DDL
    UPDATE orders SET status = 'archived' WHERE created_at < '2024-01-01';
    ALTER TABLE orders ADD INDEX idx_created_at (created_at);

    修正做法:

    1. 拆分为两笔工单:先提交纯 DDL 工单为 created_at 建索引,待上线生效后再提交纯 DML 工单。
    2. 若单批 DML 预估影响行数过大,按主键 ID 区间或日期分批拆单,确保每批在 max_affect_rows 阈值与 100,000 行回滚保护上限之内。
    3. 改完任意一个字符后必须重新点击「运行 AI 预审」:因为 run_id 与 SQL 内容加密绑定,未重跑直接提交会返回 2001 REVIEW_OUTDATED。

    3. 提交审批、退回修改与复用草稿

    • 全部阶段预审状态变为 通过(ready) 后,在 30 分钟有效期 内点击弹窗右下角 提交审批。
    • 被审批人「退回修改(changes_requested)」时:无需新建工单,进入 /changes/mine 打开该工单直接修改 SQL,重新通过 AI 预审后点击 重新提交,或点击 作废 关闭。
    • 需要再次执行类似变更时:打开任意历史工单,点击 复制为新草稿 一键带入 SQL 与标题。