SQL Lab · Execute Gate + Agent Diagnose

SQL 执行门禁与 Agent 诊断方案

用户执行 SQL 时,先经 Druid SQL Parser 本地解析与权限判定,再真正打库; 前端按返回状态决定「展示结果 / 直接报错 / 交给 Agent」。本地解析失败与可诊断执行失败都会走 Agent 纠错。 Agent 对用户无多轮对话;内部可通过 Builtin / Skills / MCP 完成单次诊断。

30 秒看懂整体

用户 SQL 执行接口 Parser 解析 权限判定 真实执行 前端分流 Agent 诊断(可选)

核心约束:语法错误与权限错误都在打库前拦截; PARSE_ERROR 与可诊断的 EXEC_ERROR 交给 Agent 纠错; PERMISSION_DENIED 只直接展示,不走 Agent。

STEP 01

有哪些参与方

前端、执行网关、本地门禁(解析 + 权限)、数据库、诊断 Agent。先分清「谁拦截、谁执行、谁建议」。

架构关系图 · Mermaid
100%
下载 .mmd
渲染中…
滚轮缩放 · 拖拽平移
BOUNDARY

职责边界对照

用一张表看清「谁负责拦截、谁真正打库、谁给建议」,避免把语法校验、权限与 Agent 混在一起。

参与方 负责什么 不负责什么 关键产出
前端 提交 SQL;按状态分流展示结果 / 错误 / Agent 面板 本地权限判定、直接连库 UI 展示;诊断请求组装
执行接口 编排解析 → 鉴权 → 执行;统一状态码回传 生成修复 SQL、解释业务语义 status + payload
Druid Parser 本地语法解析,产出 Parsed SQL Object 权限判断、真正执行 AST / 操作对象结构
权限判定 抽取表/列/操作,与用户权限比对 语法纠错、SQL 改写建议 ALLOW / DENY + 明细
诊断 Agent 分析 PARSE / 可诊断 EXEC 错误,给建议与修正 SQL 绕过门禁、代替权限系统放行 问题说明 + 修复 SQL
STEP 02

SQL 执行主流程

从提交到前端分流的完整链路。解析失败与执行失败可交给 Agent 纠错;权限失败在打库前结束且直接展示。

主流程图 · Mermaid
100%
下载 .mmd
渲染中…
滚轮缩放 · 拖拽平移
STEP 03 · SUBFLOW

权限判定子流程

这是主流程中最复杂的门禁阶段:从解析对象抽取出「对什么对象做了什么操作」,再逐条与用户权限匹配。

权限子流程 · Mermaid
100%
下载 .mmd
渲染中…
滚轮缩放 · 拖拽平移
STEP 04 · SUBFLOW

Agent 诊断子流程

当本地解析失败,或执行失败且前端判定为可诊断错误时,把错误信息与 SQL 上下文喂给 Agent,产出问题说明、建议与修正 SQL。

Agent 诊断子流程 · Mermaid
100%
下载 .mmd
渲染中…
滚轮缩放 · 拖拽平移

建议前端提供「一键填入修正 SQL」;再次执行仍走完整主流程(解析 → 权限 → 执行),保证安全边界不被 Agent 绕过。

STEP 06

一次执行的消息时序

用时序图核对「谁在什么时候跟谁说话」,以及解析失败、权限失败、执行失败与 Agent 介入时机。

时序图 · Mermaid
100%
下载 .mmd
渲染中…
滚轮缩放 · 拖拽平移
STEP 05 · AGENT

Agent 如何设计(单次诊断)

对用户一次请求一次响应;内部允许工具循环。能力抽象:Capability = Builtin | Skill | MCP

能力分层 · Mermaid
100%
下载 .mmd
渲染中…
滚轮缩放 · 拖拽平移
单次诊断内部流程 · Mermaid
100%
下载 .mmd
渲染中…
滚轮缩放 · 拖拽平移
PROMPT

提示词工程

System 定角色与硬约束;User 模板注入本次错误上下文。完整文件见 prompts/

System Prompt 下载
加载中…
User Prompt 模板 下载
加载中…

关键输出契约:errorCategoryproblemSummaryrootCausesuggestionsfixedSqlconfidenceassumptionsusedCapabilities。详见 docs/io-contract.md

CAPABILITY

能力层详解:Builtin / Skills / MCP

抽象公式:Capability = Builtin Tool | Skill | MCP Tool。 对用户是单次请求/单次响应;对内可多步组合三类能力。

Builtin 内置工具

进程内确定性能力:错误归类、本地再解析、美化与 diff。不访问外部服务,也不执行业务 SQL。

下载完整目录

为什么需要 Builtin

  • 给 Agent 一个稳定、可复现的「收口」能力:修正 SQL 必须能通过本地 Parser。
  • 错误归类先做规则映射,减少纯模型猜测,便于选择后续 Skill / MCP。
  • format / diff 方便前端展示「改了什么」,不依赖模型自己排版。

工具清单(输入 → 输出)

工具名 作用 输入 输出
classify_db_error 错误码/消息映射到错误类别 status, code, message category, hints
validate_sql_syntax Druid SQL Parser 本地再解析 sql, dialect ok / parseError
format_sql SQL 美化,便于对照阅读 sql formattedSql
diff_sql 原 SQL 与修正 SQL 差异 originalSql, fixedSql diff hunks

硬约束:Builtin 不执行业务 SQL; validate_sql_syntax 仅做本地解析,与执行门禁中的 Parser 同源,保证「Agent 认为可解析」与「再次提交可过解析」一致。

Skills 本地技能包

SKILL.md(+ 可选示例)存在的领域知识。按错误类别/方言选择性注入,避免一次塞满上下文。

形态与加载策略

  • 形态:目录下的 SKILL.md,描述何时使用、检查清单、输出期望。
  • 加载:由运行时按 status / errorCategory / dialect 挑选 1~2 个 Skill 注入提示词。
  • 不替代工具:Skill 给「怎么修」的知识;真正校验仍走 Builtin,查表结构仍走 MCP。

技能清单

Skill 触发场景 内容要点
sql-syntax-repair PARSE_ERROR、常见语法残缺 关键字拼写、括号/引号、逗号、别名、子句顺序等修复模式
sql-semantic-repair 表/列不存在、歧义、聚合误用 对象引用、GROUP BY、JOIN 条件检查清单;宜配合 schema MCP
dialect-guide-mysql dialect=mysql 函数/类型/LIMIT/反引号等 MySQL 约定
dialect-guide-postgres dialect=postgres 类型转换、ILIKE、RETURNING 等 PG 约定
dialect-guide-generic 未知方言兜底 优先 ANSI 写法,避免专有函数

仓库样例:skills/sql-syntax-repair/skills/sql-semantic-repair/skills/dialect-guide-generic/

MCP 外部只读能力

通过 MCP Server 拉取实时元数据与历史案例。一律只读,且结果需落在当前用户可见范围内。

Server:schema(元数据)

Tool 作用 典型用途
get_table_schema 列名、类型、可空、主键/外键 列不存在、类型不匹配时核对真实结构
list_tables 列出当前连接/实验室可见表(可过滤) 表名拼写错误时给出相近候选
get_column_stats 可选:列基数/脱敏样例值 辅助枚举/类型猜测(可不开)

Server:kb(错误知识库,可选)

Tool 作用 注意
search_error_cases 按错误码/消息检索历史修复案例 仅作参考;以当前错误与 schema 为准

MCP 约束

  • 只读:禁止通过 MCP 执行写操作或任意业务 SQL。
  • 权限对齐:返回对象必须在当前用户可见范围内,避免泄露无权表/列。
  • 按需调用:仅在语义/对象类错误需要真实结构时调用,避免无关往返。

推荐调用策略

按错误来源选择最短能力路径;最后一律用 validate_sql_syntax 收口。

PARSE_ERROR(语法)
classify(可选) sql-syntax-repair + dialect-guide-* 生成 fixedSql validate_sql_syntax 失败则内部再修一轮
EXEC_ERROR · 对象 / 语义类(diagnosable)
classify_db_error schema.get_table_schema / list_tables sql-semantic-repair 生成 fixedSql validate_sql_syntax
PERMISSION_DENIED / 不可诊断 EXEC_ERROR
不进入 Agent 前端直接展示错误

响应里的 usedCapabilities 应如实记录本次用到的 Builtin / Skill / MCP,便于评测与排障。

能力调用时序 · Mermaid
100%
下载 .mmd
渲染中…
滚轮缩放 · 拖拽平移
CONTRACT

前端状态约定

执行接口用统一状态驱动 UI。前端只按状态分流,不自行猜测是否该调 Agent。

SUCCESS 展示结果

执行成功。展示结果集 / 影响行数。不调用 Agent。

PARSE_ERROR Agent 纠错

本地语法解析失败。不打库;前端把 Parser 错误位置/消息 + 原始 SQL 交给 Agent,展示问题说明与修正 SQL。

PERMISSION_DENIED 直接报错

对象/操作无权限。展示缺失的表、列、操作明细。不打库、不调 Agent。

EXEC_ERROR 条件诊断

真实执行失败。若 diagnosable=true,把错误 + SQL 上下文交给 Agent;否则直接展示错误。

建议响应体至少包含:statusmessagesqlparsedSummary(操作类型/表/列)、dbError(码/消息)、 diagnosablepermissionGaps(鉴权失败时)。