111|AndrewCode

基于你的需求，我为你设计了一份**企业级技术方案文档大纲**。这是一个完整的架构升级方案，涵盖了技术选型、风险评估、实施路线等所有关键决策点。

---

# SQL 静态分析工具架构升级方案

## 文档信息

- 项目名称: SQL 静态分析工具 (sql-static-analysis) 架构升级

- 版本: v2.0 演进方案

- 编写日期: 2026-01-23

- 适用范围: 百度搜索数据团队

---

## 一、项目背景与现状

### 1.1 项目定位

- 核心职责: CI/CD 流水线中的 SQL 质量门禁

- 核心价值: 防止错误 SQL 入库，提升代码质量

- 使用场景: 开发者提交 .sql 代码时自动触发检查

### 1.2 当前架构分析

#### 1.2.1 技术栈现状

| 组件 | 技术选型 | 版本 |

| :--- | :--- | :--- |

| 开发语言 | Scala | 2.12.8 |

| SQL 解析器 | Spark Catalyst | 3.2.2 |

| 构建工具 | Maven | - |

| 运行环境 | JVM (命令行工具) | 1.8 |

#### 1.2.2 当前功能模块

```

sql-static-analysis/

├── BaseCompileSSA # 基础语法检查

├── XpathLikeSSA # 业务合规检查

├── ClkInfoMaterializedSSA # 性能优化检查

└── InputOutputTableSSA # 表血缘分析

```

#### 1.2.3 评估体系现状

- 划分依据: 四级消息体系 (ERROR/WARN/INFO/DEBUG)

- 阻断机制: ERROR → System.exit(1) → CI 失败

- 评分机制: 无 (当前仅有定性判断，无定量打分)

### 1.3 核心痛点识别

| :--- | :--- | :--- | :--- |

| P1 | 报错信息冷冰冰，缺乏修复指引 | 🔴 高 | "看不懂怎么改" |

| P2 | 无法量化代码质量 (无打分) | 🟡 中 | "不知道写得好不好" |

| P3 | 缺少交互能力，无法解答疑问 | 🟡 中 | "为什么要这么规定？" |

| P4 | 工程化不足 (硬编码路径) | 🟢 低 | 影响部署和扩展 |

---

## 二、升级目标与设计原则

### 2.1 升级目标 (SMART 原则)

| 目标 | 具体指标 | 衡量标准 |

| :--- | :--- | :--- |

| 提升修复效率 | 开发者从"看到报错"到"修复完成"时间缩短 50% | 统计平均修复时长 |

| 引入质量评分 | 为每个 SQL 文件生成 0-100 分质量评分 | 展示在 HTML 报告中 |

| 增强交互体验 | 90% 的 ERROR 自动生成**可执行的修复代码** | 用户满意度调研 |

| 保持零误报 | ERROR 级别判定准确率 100% (不允许误杀) | 回归测试覆盖 |

### 2.2 设计原则

1. 向后兼容: 现有规则引擎保持不变，Agent 作为增强层。

2. 责任分离: 规则引擎负责"判决"，Agent 负责"解释"。

3. 轻量优先: 优先选择不依赖 Spring 容器的方案。

4. 渐进演进: 分阶段上线，每个阶段可独立交付价值。

---

## 三、技术选型与架构设计

### 3.1 核心决策：是否引入 Agent？

#### 决策结论：✅ 引入，但作为**辅助层**而非替代层

#### 理由分析

| 维度 | 不引入 Agent | 引入 Agent (推荐) |

| :--- | :--- | :--- |

| 修复效率 | 开发者需手动查文档 | 自动生成修复代码 |

| 学习成本 | 新人需培训规则含义 | Agent 自动解释 |

| 体验满意度 | 冷冰冰的工具 | 有温度的助手 |

| 技术复杂度 | 低 | 中 (可控) |

| 成本 | 0 | 约 ¥500/月 (Token) |

结论: 投入产出比高，建议引入。

---

### 3.2 Agent 框架选型：LangChain4j vs Spring AI

#### 对比分析

| :--- | :--- | :--- | :--- |

#### ✅ 最终选择：LangChain4j

决策依据：

1. 本项目是 Maven + Scala + 命令行工具，引入 Spring 容器会导致 Jar 包从 ~50MB 膨胀到 ~100MB+，初始化时间增加 2-3 秒。

2. LangChain4j 的 API 设计更符合"工具类"的使用模式（静态调用），而 Spring AI 强依赖 Bean 注入。

3. LangChain4j 对百度千帆、阿里通义等国内模型支持更好。

备选方案：如果未来项目需要重构为 Web 服务，可迁移到 Spring AI。

---

### 3.3 升级后的架构设计

#### 3.3.1 整体架构图

```

┌─────────────────────────────────────────────┐

│ CI/CD Pipeline (GitLab/iCode) │

└─────────────────┬───────────────────────────┘

│ 触发

↓

┌─────────────────────────────────────────────┐

│ SSARunner (主入口) │

│ 1. 读取 diff.log │

│ 2. 调用规则引擎 │

│ 3. 判断阻断 (ERROR → exit(1)) │

└─────────────────┬───────────────────────────┘

│

┌────────┴────────┐

↓ ↓

┌──────────────┐ ┌──────────────────┐

│ 规则引擎 │ │ Agent 增强层 (新) │

│ (现有逻辑) │ │ (LangChain4j) │

│ - BaseCompile │ │ - 生成修复代码 │

│ - XpathLike │ │ - 解释规则原因 │

│ - ClkInfo │ │ - 质量打分计算 │

└──────┬───────┘ └──────┬───────────┘

│ │

└──────┬───────────┘

↓

┌─────────────────────────────────────────────┐

│ ReportContext (报告生成) │

│ - HTML 报告 (增强版) │

│ - 展示：错误 + 修复建议 + 质量分数 │

└─────────────────────────────────────────────┘

```

#### 3.3.2 Agent 调用流程

```

规则引擎执行完毕

↓

获取所有 Message (ERROR/WARN/DEBUG)

↓

筛选出 ERROR 和 WARN

↓

对每条问题：

├─ 构造 Prompt: "SQL: {原始代码}\nError: {错误信息}\n请生成修复代码"

├─ 调用 LangChain4j → OpenAI/千帆

├─ 解析 Agent 响应

└─ 附加到 Message 的 suggestion 字段

↓

生成增强版 HTML 报告 (显示修复建议)

```

---

## 四、质量评分体系设计

### 4.1 评分模型：扣分制 (满分 100)

#### 基础分：100 分

#### 扣分规则

| 问题类型 | 扣分值 | 示例 |

| :--- | :--- | :--- |

| ERROR (致命) | -30 分/条 | 语法错误、UGI 明文 |

| WARN (警告) | -10 分/条 | xpath 没加括号、未用物化列 |

| INFO/DEBUG | 不扣分 | 表血缘分析结果 |

#### 评级标准

| 分数区间 | 等级 | 说明 |

| :--- | :--- | :--- |

| 100 分 | 🟢 优秀 (Excellent) | 零问题 |

| 90-99 分 | 🟡 良好 (Good) | 仅有少量 WARN |

| 60-89 分 | 🟠 待优化 (Fair) | 多个 WARN 或 1个 ERROR |

| < 60 分 | 🔴 不合格 (Poor) | 多个 ERROR |

注意: 即使得分 >60，只要有 ERROR，依然会阻断合入。评分仅用于"度量代码质量"，不影响阻断逻辑。

---

### 4.2 准确率保证机制

#### 4.2.1 核心原则：**规则引擎的判决必须 100% 可靠**

| 层级 | 准确率要求 | 保证措施 |

| :--- | :--- | :--- |

| 规则引擎 (ERROR判定) | 100% | 1. 基于 AST 静态分析 (确定性) 2. 充分的回归测试 3. 白名单机制 (允许人工覆盖) |

| Agent (修复建议) | 80-90% | 1. 允许不准确 (仅供参考) 2. 人工最终决策 3. 标注"AI生成，请审核" |

#### 4.2.2 具体措施

1. 规则引擎部分：

* 使用 Spark Catalyst (官方解析器)，准确率有保证。

* 每个新规则必须附带至少 10 个单元测试用例。

* 建立规则回归测试集 (已有 SQL 样本)。

2. Agent 部分：

* 在 HTML 报告中明确标注："以下为 AI 建议，请人工审核"。

* Agent 生成的代码不会自动应用，仅作为参考。

* 允许用户反馈 (点赞/点踩)，持续优化 Prompt。

---

## 五、开发模式与实施路线

### 5.1 开发模式选择：**敏捷迭代 (Agile)** + MVP 优先

#### 为什么不选瀑布模式？

- 需求可能在实施中调整 (例如 Agent 的 Prompt 需要多次优化)。

- 用户反馈至关重要 (打分机制是否合理需验证)。

#### 为什么选敏捷？

- 快速验证: 2 周交付 MVP，快速获取用户反馈。

- 风险可控: 每个迭代独立可用，失败也不影响现有系统。

- 持续改进: 根据用户使用数据优化 Agent Prompt。

---

### 5.2 三阶段实施路线

#### 📅 阶段一：工程化重构 + 打分体系 (2 周)

目标: 修复现有痛点，引入质量评分。

| 任务 | 工作量 (人日) | 优先级 |

| :--- | :--- | :--- |

| 配置文件解耦 (移除硬编码路径) | 2 | P0 |

| 异常处理增强 (记录堆栈日志) | 1 | P0 |

| 实现打分模型 (扣分制) | 3 | P0 |

| 优化 HTML 报告 (展示分数) | 2 | P1 |

| 单元测试补充 | 2 | P1 |

交付物:

- ✅ 配置文件 application.conf

- ✅ HTML 报告展示质量评分

- ✅ 回归测试覆盖率 > 80%

验收标准: 现有功能不受影响，新增评分展示。

---

#### 📅 阶段二：Agent 集成 (MVP) (3 周)

目标: 引入 LangChain4j，实现自动修复建议。

| 任务 | 工作量 (人日) | 优先级 |

| :--- | :--- | :--- |

| 集成 LangChain4j 依赖 | 1 | P0 |

| 实现 Agent 调用封装类 AgentHelper | 3 | P0 |

| 设计 Prompt 模板 (针对 4 种规则) | 3 | P0 |

| Agent 结果解析与格式化 | 2 | P0 |

| 将建议附加到 HTML 报告 | 2 | P1 |

| 模型选型测试 (OpenAI vs 千帆) | 2 | P1 |

| 成本评估与限流机制 | 2 | P2 |

交付物:

- ✅ 对 ERROR 级别问题生成修复建议

- ✅ HTML 报告展示"AI 建议"区块

验收标准:

- Agent 调用成功率 > 95%。

- 修复建议可读性通过人工评审。

---

#### 📅 阶段三：优化与推广 (2 周)

目标: 根据用户反馈迭代，全量推广。

| 任务 | 工作量 (人日) | 优先级 |

| :--- | :--- | :--- |

| 收集用户反馈 (问卷 + 访谈) | 2 | P0 |

| 优化 Prompt (提升建议准确率) | 3 | P0 |

| 增加交互功能 (IDE 插件探索) | 5 | P2 |

| 性能优化 (Agent 调用并发化) | 2 | P2 |

| 编写用户文档 | 2 | P1 |

交付物:

- ✅ 用户满意度 > 80%

- ✅ 完整的使用文档

---

## 六、效率、时间与技术复杂度的平衡

### 6.1 权衡分析

| 维度 | 阶段一 | 阶段二 | 阶段三 |

| :--- | :--- | :--- | :--- |

| 开发时间 | 2 周 | 3 周 | 2 周 |

| 风险 | 🟢 低 | 🟡 中 (Agent 稳定性) | 🟢 低 |

### 6.2 最优策略

建议：优先完成阶段一和阶段二前半部分 (MVP)，快速验证 Agent 价值后再决定是否全量投入阶段三。

理由：

- 阶段一是"还技术债"，必须做。

- 阶段二的 Agent 是"核心亮点"，尽快验证可行性。

- 阶段三可根据用户反馈灵活调整。

---

## 七、风险评估与应对

| 风险项 | 概率 | 影响 | 应对措施 |

| :--- | :--- | :--- | :--- |

| Agent 响应超时/不稳定 | 🟡 中 | 🟡 中 | 1. 设置 5 秒超时 2. 失败时降级为"无建议" |

| Token 成本超预算 | 🟢 低 | 🟡 中 | 1. 限流 (每文件最多调用 3 次) 2. 缓存相似 SQL 的建议 |

| Agent 建议不准确/误导 | 🟡 中 | 🟡 中 | 1. 明确标注"AI 生成" 2. 允许人工反馈 |

| 团队对 Scala 不熟悉 | 🟢 低 | 🟢 低 | 1. LangChain4j 使用 Java API 2. 提供代码模板 |

---

## 八、成功标准与验收指标

| :--- | :--- | :--- | :--- |

| 用户满意度 | 未统计 | > 80% | 问卷调研 (5 分制) |

| 误报率 (ERROR) | 0% | 0% | 回归测试 |

| Agent 建议采纳率 | - | > 60% | 统计实际修复代码与建议的相似度 |

| 系统稳定性 | 99% | > 99% | CI 流水线成功率 |

---

## 九、总结与建议

### 9.1 核心结论

1. 必须引入 Agent：可将工具从"冷冰冰的警察"变为"有温度的助手"。

2. 选择 LangChain4j：轻量、适配当前架构。

3. 采用敏捷开发：分阶段交付，快速验证。

4. 保持规则引擎 100% 准确率：Agent 仅作为辅助，不影响门禁判决。

### 9.2 下一步行动

1. 本周: 完成方案评审，获得团队共识。

2. 下周: 启动阶段一开发 (工程化重构)。

3. 3 周后: 发布 MVP 版本，邀请 5-10 名核心用户内测。

---

方案编写者签名: ___________

评审日期: 2026-01-__

Command line is too long

Andrew