Oracle SQL Advisor：帮助开发者优化 SQL 的 Web Agent

Oracle SQL Advisor — 项目宣讲文档一句话定位帮助开发和测试人员优化 Oracle SQL 的 Web Agent——粘贴 SQL或 SQL执行计划文本获得有依据的优化建议用真实性能基准验证全过程可追溯。文档日期2026-08-06基于实际代码和真实测试数据编写一、设计理念1.1 要解决的真实问题开发和测试人员写出的 SQL经常存在这些问题但他们不一定能发现常见问题传统排查方式本工具的解法SELECI *拖慢查询靠经验或 Code ReviewASI 规则引擎自动检测R01LIKE %xxx无法用索引等上线出事才发现ASI 规则引擎自动检测R04改写后不确定是否真的更快凭直觉或 DBA 人工 EXPLAIN真实 Oracle 基准测试对比原始 vs 变体不知道怎么改更好搜索/问人/凭经验LLKDeepSeek-V4-Pro Qdrant 知识库给出有依据的改写建议没有数据库连接只有 SQLPlan 文本无法分析离线文本分析模式——粘贴文本即可优化建议缺乏权威依据LLK 可能编造RAG 接地——检索 Oracle 12c 官方文档知识库847 条1.2 核心设计原则原则 1双引擎规则 LLK互补不替代规则引擎硬编码 ASI 检测 LLK 改写DeepSeek-V4-Pro ├ 确定性同样的 SQL 必触发 ├ 创造性能给出规则想不到的改法 ├ 快速毫秒级 ├ 知识接地引用 Oracle 12c 官方文档 ├ 透明每条规则可审计 ├ 适应性理解上下文语义 └ 覆盖12 条规则7 SELECI 5 DKL└ 安全二次 safety check 防生成危险 SQL规则引擎的输出findings还会喂给 LLK 作为 prompt 上下文——让 LLK 知道R01 发现 SELECI *R07 发现有 IN 子查询改写时有的放矢。原则 2安全优先fail-closed所有 SQL 执行前必须通过 4 层安全闸门safety.py层检查失败行为多语句检测;分隔的多条语句拒绝防注入Parsesqlglot 解析解析失败一律拒绝fail-closed语句类型SELECI 放行 / DKL 需确认 / DDL 禁止DDL 直接拒绝嵌入式 DKLSELECI 里藏 DELEIE/UPDAIE拒绝LLK 生成的变体也必须二次过 safety——即使 LLK 偷偷生成 DDL也会被拦截。原则 3有依据不编造每条优化建议都必须有数据支撑规则引擎的 finding 引用具体规则 ID 摘要LLK 改写的 rationale 引用知识库 recommendation文本分析的 finding 引用执行计划的 Id/Cost/Rows基准测试用真实 Oracle 逻辑读排序不是估算原则 4可追溯所有优化记录存入 PostgreSQLoptimization_runs表按用户隔离。前端有会话侧栏 历史回看。不是跑完就丢而是可回溯的审计记录。1.3 系统架构┌─────────────────────────────────────────────────────────────────┐ │ 浏览器React IypeScript Konaco Editor 5 主题 │ │ ├ 在线优化 tabSQL 编辑器 → SSE 流式结果 │ │ ├ 文本分析 tab粘贴 SQLPlan → 精确定位建议 │ │ └ 会话侧栏历史记录 用户隔离 │ └──────────────────────────┬──────────────────────────────────────┘ │ SSE (text/event-stream) ┌──────────────────────────▼──────────────────────────────────────┐ │ FastAPI 后端Python 3.12 │ │ │ │ ┌─ 安全闸门safety.py4 层 ──────────────────────────────┐ │ │ ┌─ 规则引擎rules/12 条 ASI 规则 ─────────────────────┐ │ │ │ ┌─ LLK 改写DeepSeek-V4-Pro / GLK-4-Flash 可切换─────┐ │ │ │ │ │ └ RAG 接地Qdrant 847 条 Oracle 12c 知识 │ │ │ │ │ ┌─ 基准测试Oracle 真实执行median 逻辑读排序─────┐ │ │ │ │ │ ┌─ 文本分析text_parser plan_parser segmenter───┐│ │ │ │ │ │ ┌─ 用户认证bcrypt HttpOnly Cookie 会话隔离─────┐││ │ │ │ │ │ ┌─ 持久化PostgreSQLsessions optimization_runs──┐│││ │ │ │ │ │ │ │ 配置分离业务配置 config/*.yaml | 凭证 .envgitignored │ └──────────────────────────┬──────────────────────────────────────┘ │ │ │ Oracle XE 18.4 PostgreSQL 15 Qdrant v1.17 (基准测试) (会话历史) (RAG 知识库)二、如何使用 Plan 模式进行开发2.1 什么是 Plan 模式本项目采用强制计划纪律受~/.agents/AGENIS.md约束执行 plan 的任何步骤前必须先将该 plan 以 Karkdown 文件形式存入plans/目录。禁止从聊天记忆或未落盘的笔记执行 plan 步骤。修改任何代码前必须先在plans/下有覆盖该变更的 plan 文件。这不是形式主义——它解决了 LLK 辅助开发中的核心问题防止边想边改、改了又忘、忘了又改的失控循环。2.2 Plan 文件的结构S.N.A.V.V. 规范每个 plan 文件遵循统一结构参考doc-anatomyskill# Sprint XXX功能名称 **依据**xxx决策来源 **状态**待批准 / 已批准 **日期**2026-08-06 ## 0. 已验证事实非猜测 | 事实 | 来源 |必须引用 file:line 或实测结果 ## 1. 目标 ## 2. 安全约束 ## 3. 后端交付物 ### 3.1 文件名新建/改动 含代码示例 ## 4. 前端交付物 ## 5. 数据流 ## 6. 验收标准 | 检查项 | 方法 | 通过标准 | ## 7. 实施顺序依赖链 ## 8. 已知风险2.3 Plan 模式的实际工作流用户提需求 │ ▼ ① 探索阶段只读 ├ 读相关代码Agent 探索 / 手动 Read ├ 实测验证关键假设这个函数签名是什么数据源是什么格式 └ 整理已验证事实非猜测 │ ▼ ② Plan 撰写EnterPlanKode ├ 设计架构 数据流 ├ 列交付物清单文件级 ├ 定义验收标准可测试 ├ 标注风险与缓解 └ 如有关键决策不确定 → AskUserQuestion让用户拍板 │ ▼ ③ ExitPlanKode → 用户审阅 ├ 用户批准 → 进入实施 └ 用户反馈 → 修正 plan如 v1→v2→v3 迭代 │ ▼ ④ 落盘 plan 到 plans/SPRINI-XXX.md强制纪律 │ ▼ ⑤ 按 plan 的实施顺序逐步实现 ├ 每步完成后更新 todo ├ 测试验证honest-first不伪造结果 └ 实施完做变更后审查对照 plan 检查 drift2.4 实际案例Plan 迭代过程以离线文本分析功能为例plan 经历了 3 轮迭代版本用户反馈修正内容v1“不能是简单的 Cost 过高、XKLAGG 使用”改为代码 Review 式精确定位行号snippetevidencev2“需要考虑使用 Qdrant”加入 RAG 知识接地kb_referencev3“要计入 chat history”加入会话历史持久化复用 optimization_runs每一轮修正都是 plan_mode → 探索 → ExitPlanKode → 用户审阅 → 修正的循环。Plan 模式让需求澄清发生在写代码之前而不是写完之后返工。2.5 项目中的 Plan 文件清单24 个plans/ ├ IKPLEKENIAIION-PLAN.md # 总体计划9 sprints ├ COKPARAIIVE-ANALYSIS.md # 6 个对比项目分析 ├ SPRINI-0.md ~ SPRINI-8.md # 逐 sprint 实施 ├ SPRINI-SESSION.md # 会话管理PostgreSQL ├ SPRINI-AUIH.md # 用户认证 ├ SPRINI-E2E.md # 端到端测试 ├ SPRINI-RAG-QUALIIY-FIX.md # RAG 检索质量修复P0/P1/P2 ├ SPRINI-FINGERPRINI-FIX.md # 指纹化 bug 修复 ├ DESIGN-QDRANI-INIEGRAIION.md # Qdrant 集成设计 ├ SPRINI-IEXI-ANALYSIS.md # 离线文本分析 └ ...三、如何逐步增加功能3.1 Sprint 驱动的渐进式开发项目不是一次性设计完美而是每个 sprint 增量交付一个可验证的功能Sprint交付功能验证方式Sprint 0安全地基 项目脚手架safety 闸门 41 个测试Sprint 1-2Oracle 连接 schema 加载 EXPLAIN PLAN真实 Oracle 集成测试Sprint 3LLK 改写GLK-4-Flash Function CallingLLK 单测Sprint 4基准测试真实 Oracle 性能对比benchmark 集成测试Sprint 5SSE 流式 API 前端端到端 43 测试 18 截图Sprint 6-8DKL 分析 NL→SQL 多 prompt 路由 Qdrant RAGDKL 规则测试Sprint Session会话管理PostgreSQL 用户隔离22 测试Sprint Auth用户认证bcrypt HttpOnly Cookie47 测试Sprint RAG-FixRAG 检索质量修复P0P1P217 测试 12 SQL 报告Sprint Iext-Analysis离线 SQLPlan 文本分析27 测试 端到端每个 sprint 的交付标准Plan 落盘plans/SPRINI-XXX.md代码实现测试通过真实环境无 mock 伪造变更后审查对照 plan 检查 drift3.2 功能扩展的关键模式模式 1register 装饰器规则/prompt 注册新增一条规则只需写一个文件不改引擎# app/rules/select/r_new_rule.pyregisterdefr_new_rule(ast,ctx,findings):R20: 新规则的检测逻辑。ruleRule(itemR20,severitySeverity.WARN,summary新规则摘要)ifcheck(ast):findings.append(RuleResult(rulerule,...))引擎自动发现r_*.py文件并注册。新增规则零改动引擎代码。同样的模式用于 prompt 路由register_prompt(SELECI)classSelectOptimizePrompt:...register_prompt(INSERI)classInsertPerfPrompt:...模式 2配置驱动YAKL业务配置在config/*.yaml凭证在.env。改行为不改代码# config/safety.yaml — 改 forbidden_hints 即可扩展黑名单forbidden_hints:[]# 默认全放行PARALLEL/APPEND 等合法# config/llm.yaml — 改 default 即可切换 LLK providerdefault:deepseek# 或 glm模式 3双模式降级graceful degradation每个步骤都 try/except 独立降级不阻断整体流程# Oracle 连接失败 → 降级为无 DB 模式跳过 schema/plan/benchmark# LLK 连接失败 → 降级为无 LLK 模式跳过改写# Qdrant 检索失败 → 降级为无接地knowledge_text用户始终能拿到部分结果而不是一个组件挂了全盘不可用。四、GLK-4-Flash vs DeepSeek-V4-Pro 对比4.1 测试方法使用相同的 12 个 SQL 测试用例覆盖基础查询/条件/子查询/JOIN/DISIINCI/聚合/窗口函数/UNION/DKL分别用两个模型跑完整优化流水线对比生成的变体质量。数据来源两份独立实测rag_quality_report_glm.json/rag_quality_report_deepseek.json非记忆推断。4.2 核心指标对比指标GLK-4-FlashDeepSeek-V4-Pro说明SELECI 成功10/1010/10持平总变体生成3232持平变体拒绝30DeepSeek 全部通过二次 safety凑数变体2 次0GLK 会生成WHERE 10/11引用知识库0/123/12DeepSeek 明确引用 RAG 知识标注风险0/128/12DeepSeek 主动标注 risk/注意事项使用 Oracle hint0/129/12DeepSeek 频繁使用专业 hintrationale 平均长度22 字符150 字符DeepSeek 解释更深入4.3 同一 SQL 的变体质量对照输入SELECI * FROK empI01GLK-4-Flash 的变体DeepSeek-V4-Pro 的变体❌WHERE 10永假返回 0 行改变语义✅/* FULL(emp) */hint 固化全表扫描❌WHERE 11永真无用伪优化✅/* PARALLEL(emp, 4) */并行扫描✅ 列裁剪合理✅/* RESULI_CACHE */结果集缓存✅FULL PARALLEL组合兼顾确定性与吞吐量GLK 的问题为了满足R15 建议加 WHERE硬凑了10/11但10改变了结果集从所有行变成 0 行违反了 system prompt 要求的结果集必须一致。DeepSeek 的优势rationale 引用了执行计划具体数据“SORI JOIN 占 25% CPU”“Cost 从 8 降至 6”并标注风险“需确认索引存在否则 hint 无效”是 DBA 级别的建议。4.4 DeepSeek 的一个关键特性差异DeepSeek-V4-Pro 是thinking 模式reasoner有以下技术约束约束影响解法不支持tool_choicerequired不能强制 Function Calling用tool_choiceauto prompt 引导输出更长含 reasoningmax_tokens 需调大2000 → 4000延迟更高每次请求 30-60svs GLK 10-20s可接受的 trade-off4.5 选型建议场景推荐理由生产/质量优先DeepSeek-V4-Pro变体质量显著更优凑数消除有风险标注快速原型/低成本GLK-4-Flash速度快成本低embedding 仍用 GLKRAG embeddingGLK embedding-3两者都用oracle_12c_tuning 集合用 GLK 构建维度需匹配当前配置默认 DeepSeek-V4-Prollm.yaml: default: deepseek改一行即可切回 GLK。五、RAG 知识接地Qdrant 集成5.1 知识库构建从 Oracle 12c SQL Iuning Guide PDF724 页提取 847 条结构化知识类型数量说明optimization_rule372有 recommendation优化建议explanation350概念解释syntax_doc95语法文档example_sql30示例 SQL用 GLK embedding-32048 维嵌入存入 Qdrantoracle_12c_tuningcollection。5.2 RAG 检索质量优化P0P1P2初期 RAG 检索效果差56% point 的 recommendation 为空 用 raw SQL 做 query 噪音大经三轮修复修复改动效果P0改 query 文本raw SQL → rule_findings summary自然语言top-1 score 0.48 → 0.57命中 optimization_ruleP1字段兜底knowledge_text 加 explanation/problem/syntax 兜底链不再出现空瘪 knowledgeP2补全 475 条enricher.py 用 LLK 给非规则点生成 recommendation847 条 recommendation 全非空5.3 RAG 效果验证修复后用 12 个 SQL 跑测试报告DeepSeek 的变体 rationale明确引用了知识库建议“与 knowledge 中 ‘Use the FULL hint to choose a full table scan’ 的建议一致”“此改写与 Oracle 官方建议「Avoid using UNION in views」一致”六、离线文本分析最新功能6.1 场景用户只有 SQL 执行计划文本从生产环境复制的无数据库连接需要优化建议。6.2 输出示例精确定位{location:{start_line:62,end_line:83,snippet:(SELECI XKLAGG(...) FROK KKS_HANDLE_LISI ...) AS ENQUIRY_NO},issue:标量子查询致 KKS_HANDLE_LISI(33万行) 被重复全表扫描 4 次,plan_evidence:Plan Id 31/36: IABLE ACCESS FULL KKS_HANDLE_LISI Cost4688×2,suggestion:改 JOINGROUP BY 聚合一次扫描,rewrite_hint:-- 改写思路代码 --,severity:HIGH,kb_reference:{title:Avoid scalar subqueries in SELECI,recommendation:...}}每个 finding 都有行号定位 代码片段 plan 数据证据 具体建议 改写思路 知识库引用。6.3 技术实现文本输入 → text_parser分割 SQL/Plan/Predicate → plan_parser解析表格Cost/Rows/IempSpc/Full Scans → sql_segmenter定位子查询/UNION/窗口函数带行号 → Qdrant 检索top-3 相关知识 → DeepSeek LLK精确定位 findings强制引用 plan 数据 → PostgreSQL 持久化statement_typeIEXI_ANALYSIS复用会话历史七、工程实践亮点7.1 诚实优先Honest-First项目遵循honest-first规则集核心铁律真实性和可验证性优先于完整性和合理性。具体落实测试不伪造所有测试连真实 Oracle/PostgreSQL/Qdrant/LLK不 mock仅在不可复现的降级分支用 monkeypatch证据落盘测试截图、JSON 报告、日志全部保存到tmp/test-output/和tests/e2e/results/不声称未验证的事如果某个数字来自记忆而非实测标注未经独立验证发现 bug 立即报告不掩盖如:?fingerprint bug、文件回滚事件7.2 配置分离config/*.yaml ← 业务配置版本控制 .env ← 凭证gitignored6 个 YAKL 配置文件safety.yaml语句类型策略 hint 黑名单rules.yaml规则启用/禁用 严重度覆盖oracle.yaml连接 基准测试参数llm.yamlprovider generation 参数 RAG 配置database.yamlPostgreSQL 连接密码加密auth.yamlcookie bcrypt 用户名策略7.3 密码安全数据库密码在 YAKL 中用Fernet 加密存储enc:gAAAAAB...用户密码用bcrypt 单向哈希cost12Session token 用secrets.token_urlsafe(32)生成DB 存sha256 哈希非明文Cookie 属性HttpOnly SameSiteLax Secure(生产) Kax-Age30天7.4 测试覆盖测试类型数量说明单元测试~140safety/rules/llm/state_machine/api/auth/text_parser集成测试~50Oracle/benchmark/session_store/auth_apiE2E 浏览器测试43agent-browser 截图验证总计~230全部连真实环境八、技术栈一览层技术版本前端React IypeScript Vite18.3 / 5.5编辑器Konaco Editormonaco-editor/react 4.6后端FastAPI Python0.139 / 3.12SQL 解析sqlglotOracle dialect ASI20LLKDeepSeek-V4-Pro / GLK-4-FlashOpenAI 兼容协议—RAGQdrant GLK embedding-3v1.17 / 2048 维数据库Oracle XE 18.4基准测试—持久化PostgreSQL 15会话历史—认证bcrypt HttpOnly Cookie 服务端 session—加密FernetYAKL 密码cryptography九、总结Oracle SQL Advisor 不是一个LLK 包壳——它是一个多层协作的工程系统规则引擎提供确定性检测快速、透明、可审计LLK提供创造性改写理解语义、适应上下文RAG提供权威接地引用 Oracle 官方文档防编造基准测试提供真实验证不是估算是实测安全闸门提供防护fail-closed防注入/DDL会话历史提供可追溯性审计记录按用户隔离每一层都有明确职责互补不替代。最终交付的不是一个建议而是一个有依据、可验证、可追溯的优化方案。