当需要排查历史代码性能隐患或拦截开发阶段的问题 SQL 时，可购买和使用 SQL 事前风险预测智能体，帮助开发者快速修复代码缺陷，从源头发现问题 SQL，有效预防线上故障。
本文为您介绍配置风险 SQL 扫描任务和查看扫描报告的步骤。配置风险 SQL 扫描任务完成后，系统自动规划和执行任务，整个过程无需用户介入，仅需任务执行完成后，通过查看 SQL 事前风险分析概览报告和 SQL 事前风险分析报告获取分析过程、分析结果、风险 SQL 及优化建议。
代码扫描方式说明
风险 SQL 扫描支持两种扫描方式：
全量代码扫描：扫描整个代码库中的所有 SQL 语句，全面评估存量代码存在的 SQL 风险。
增量代码扫描：扫描两次提交之间的增量代码，快速识别新引入的 SQL 风险。
智能体自动规划和执行扫描任务步骤说明
自动规划和执行的步骤 | 子步骤 | 说明 |
代码建模 | 代码建模 | 对代码仓库进行代码建模。 |
| 代码下载 | 获取并下载代码分支下的代码仓库资源。 |
| 代码与数据库关联分析 | 提取数据库实例中的库表信息，用于后续从代码中抽取 SQL 时，进行元数据匹配。 |
| 代码分割 | 对代码文本进行结构化拆分，将整体代码库按逻辑单元（如函数、类、模块）切割为独立分析单元。 |
| 代码调用链提取 | 基于代码调用关系栈，对 ORM 代码块补充完整代码调用链。 |
| 代码建模总结 | 代码建模完成，本次代码建模基于代码结构化拆分与数据库调用关系解析，共拆分出 n 个数据库代码块，下一步将从数据库代码块中抽取 SQL。 |
SQL 抽取 | 第1个代码块 SQL 抽取 | 从代码块的代码文件和代码函数名中抽取 SQL。 |
| 第 n 个代码块 SQL 抽取 | |
| SQL 抽取总结 | 总结从 n 个代码块抽取出 n 条 SQL。 |
SQL 分析与优化 | 第1条 SQL 分析与优化 | 与代码块对应，对抽取到的 SQL 进行分析优化，对 SQL 进行分析与风险判定分析、并对风险 SQL 提供优化建议。 每个 SQL 分析与优化内容包括： SQL 元数据补齐：已查询库表的表统计数据与索引数据。 SQL 风险判别：提示有无风险，若有风险会说明风险类型和风险等级，详细分析风险点。 SQL 建议：风险问题总结，并提供多组优化建议，展示优化后效果和风险，供用户选择最优优化建议。 |
| 第 n 条 SQL 分析与优化 | |
报告整理与总结 | 报告整理与总结 | 统计任务执行信息、任务执行结果风险统计，并整理和生成 SQL 事前风险预测报告。风险预测报告支持预览和下载。风险测试报告包括以下两种： SQL 事前风险分析概览报告（xlsx 格式）：提供从代码中抽取的 SQL 清单，提供两个视图： SQL 按代码文件合并：可按代码文件/函数分组预览 SQL。 SQL 按风险等级排序：可通过风险等级快速筛选。 SQL 事前风险分析详细报告（md 格式）：详细展示每个 SQL 的风险分析内容与结果。 |
使用限制
单个对话窗口同一时间仅允许提交1个单次扫描任务，且仅支持查看近一个月的风险 SQL 扫描报告。
前提条件
已具有 TDAI 相关功能页面的访问权限，具体说明及操作请参见 TDAI 用户权限设置。
请您在待扫描的 GIT 代码仓库添加 aid_code_upload 账号并已设置 Reporter 权限。
操作步骤
配置单次扫描任务、查看执行过程及风险扫描报告
步骤一：购买 SQL 事前风险预测智能体实例
步骤二：为智能体实例配置单次扫描任务
1. 登录 数据库 AI 服务控制台。
2. 在左侧导航栏选择我的实例。
3. 在购买的 SQL 事前风险预测智能体实例对应的操作列单击对话。
4. 在对话窗口，单击单次扫描或配置单次扫描任务。
5. 配置任务参数，配置完成后单击确认任务配置。
参数说明如下表所示。
参数分类 | 参数名 | 说明 |
代码信息 | 代码仓库 | 请输入开发语言为 Go 的 GIT 代码仓库地址。 |
| 代码分支 | 请输入代码分支。 |
| ORM 框架类型 | 请在下拉框中选择框架类型。 |
| 扫描模式 | 扫描模式支持全量代码扫描和增量代码扫描。 全量代码扫描：请输入全量版本 Commit ID。 增量代码扫描：请输入源版本 Commit ID 和增量版本 Commit ID。 |
关联实例信息 | 地域 | 选择要关联的实例所属地域。 如果需要添加多个地域的实例，请单击添加其地域实例。 |
| 实例 ID | 输入实例 ID，示例：cdb-xxxxxxxx。 请确保实例所属账号与当前登录的账号一致。 |
步骤三：智能体自动规划和执行扫描任务（全过程无需人工介入）
智能体系统自动规划和执行任务，最终输出风险报告。
该过程无需您全程停留在对话页面，待执行完成后您只需要查看扫描报告即可。
说明：
任务执行过程中，如果需要暂停任务，可在智能体实例列表页面对应的操作列单击暂停。
步骤四：查看和下载风险 SQL 扫描报告
扫描任务执行完成后，可在智能体实例对话窗口查看和下载风险 SQL 扫描报告。
说明：
如果已在单次扫描任务执行页面，请跳过步骤1～步骤5，直接执行步骤6及后续步骤即可。
1. 在对话窗口查看详细的 SQL 事前风险预测扫描任务的过程输出及诊断结果详情。
2. 可分别单击代码建模、SQL 抽取、SQL 分析与优化、报告整理与总结，在右侧页面查看具体过程。
3. 分别单击 SQL 事前风险分析概览报告和 SQL 事前风险分析报告将风险报告下载至本地。
查看历史扫描任务
1. 登录 数据库 AI 服务控制台。
2. 在左侧导航栏选择我的实例。
3. 在购买的 SQL 事前风险预测智能体实例对应的操作列单击对话。
4. 在对话窗口单击查看历史任务或查看历史扫描任务列表。
5. 在对话窗口单击查看：点击查看任务列表。
6. 查看扫描任务和下载风险扫描报告。
查看扫描任务详情：在右侧任务列表操作列单击详情，可分别单击代码建模、SQL 抽取、SQL 分析与优化、报告整理与总结，在右侧页面查看具体过程。
下载风险扫描报告：在右侧任务列表操作列单击下载，或在任务详情页面分别单击 SQL 事前风险分析概览报告和 SQL 事前风险分析报告，下载 SQL 事前风险分析概览报告（格式为 .xlsx）和 SQL 事前风险分析报告（格式为 .md）。
报告解读
SQL 事前风险分析概览报告
Sheet 页 | 表头（英文） | 表头（中文） | 说明 |
SQL 按照文件合并/SQL 按照风险排序 | code_file | 代码文件 | 代码所属文件。 |
| code_line | 代码行号 | 代码所在行号。 |
| code_func | 函数名称 | 代码函数名称。 |
| code_chain | 代码调用链 | 代码调用链。 |
| code_chain_deep | 调用深度 | 代码调用深度。 |
| code_sql | 提取的 SQL 语句 | 提取的风险 SQL 语句。 |
| code_sql_description | SQL 语句补充说明 | 风险 SQL 语句的补充说明。 |
| code_sql_agree | 代码内提取的 SQL 语句是否正确，用户可标注，Y 为接受，N 为拒绝 | 无。 |
| code_sql_adjust | 代码内可提取的 SQL 语句的校正建议，用户可标注 | 无。 |
| code_sql_comment | 其它代码建议，用户可标注 | 无。 |
| instance_id | 分析使用的数据库实例列表 | 无。 |
| instances | 备选数据库实例列表 | SQL 关联实例对象。 |
| databases | 数据库列表 | SQL 关联数据库对象。 |
| tables | 表列表 | SQL 关联表对象。 |
| table_def_list | 表定义列表 | SQL 关联表的表定义列表。 |
| opt_bdrl | 风险等级 | 优化前诊断判别的风险等级包括： HIGH：高风险，存在索引缺失、索引失效、全表扫描等性能问题且表行数大于10w，或无条件删除等问题。 MEDIUM：中风险，存在索引缺失、索引失效、全表扫描等性能问题且表行数在 1000 - 10w。 LOW：低风险，存在性能问题但表行数较小，提示关注。 NONE：无风险。 UNKNOWN：未知风险，可能因元数据对象不在提供的实例中，或 SQL 抽取异常。 |
| opt_bdrt | 风险类型 | 支持判别的风险类型包括性能问题、DDL 风险和 SQL 风险。 |
| opt_bdrs | 风险说明 | 风险 SQL 的详细说明。 |
| opt_diag_agree | 诊断的判定是否正确，用户可标注，Y 为接受，N 为拒绝 | 无。 |
| opt_diag_comment | 其它诊断判定建议，用户可标注 | 无。 |
| opt_grp_x | 第 x 组优化建议 | 提供风险 SQL 的优化建议。 |
任务信息 | config_key | 配置参数名字 | 风险单次扫描任务中已配置的参数名称。 |
| config_value | 配置参数数值 | 风险单次扫描任务中已配置的参数值。 |
SQL 事前风险分析报告
一级目录 | 二级目录 | 说明 |
代码建模与 SQL 抽取 | 代码建模 | 对代码仓库进行代码建模。 |
| 代码下载 | 获取并下载代码分支下的代码仓库资源。 |
| 代码与数据库关联分析 | 提取数据库实例中的库表信息，用于后续从代码中抽取 SQL 时，进行元数据匹配。 |
| 代码分割 | 对代码文本进行结构化拆分，将整体代码库按逻辑单元（如函数、类、模块）切割为独立分析单元。 |
| 代码调用链提取 | 基于代码调用关系栈，对 ORM 代码块补充完整代码调用链。 |
| 代码建模总结 | 代码建模完成，本次代码建模基于代码结构化拆分与数据库调用关系解析，共拆分出 n 个数据库代码块，下一步将从数据库代码块中抽取 SQL。 |
SQL 抽取 | 第1个代码块 SQL 抽取 | 从代码块的代码文件和代码函数名中抽取 SQL。 |
| 第 n 个代码块 SQL 抽取 | |
| SQL 抽取总结 | 总结从 n 个代码块抽取出 n 条 SQL。 |
SQL 分析与优化 | 第1条 SQL 分析与优化 | 与代码块对应，对抽取到的 SQL 进行分析优化，对 SQL 进行分析与风险判定分析、并对风险 SQL 进行优化。 每个 SQL 分析与优化内容包括： SQL 元数据补齐：已查询库表的表统计数据与索引数据。 SQL 风险判别：提示有无风险，若有风险会说明风险类型和风险等级，详细分析风险点。 SQL 建议：风险问题总结，并提供多组优化建议，展示优化后效果和风险，供用户选择最优优化建议。 |
| 第 n 条 SQL 分析与优化 | |
SQL 分析与优化总结 | - | 总结共抽取了 n 条有效业务 SQL，并对每条 SQL 完成了分析与优化。 |
任务指标统计数字 | - | 统计风险 SQL 数量、OPT、诊断等指标数据。 |
