用户执行 SQL 时，先经 Druid SQL Parser 本地解析与权限判定，再真正打库； 前端按返回状态决定「展示结果 / 直接报错 / 交给 Agent」。本地解析失败与可诊断执行失败都会走 Agent 纠错。 Agent 对用户无多轮对话；内部可通过 Builtin / Skills / MCP 完成单次诊断。
核心约束：语法错误与权限错误都在打库前拦截； PARSE_ERROR 与可诊断的 EXEC_ERROR 交给 Agent 纠错； PERMISSION_DENIED 只直接展示，不走 Agent。
前端、执行网关、本地门禁（解析 + 权限）、数据库、诊断 Agent。先分清「谁拦截、谁执行、谁建议」。
用一张表看清「谁负责拦截、谁真正打库、谁给建议」，避免把语法校验、权限与 Agent 混在一起。
| 参与方 | 负责什么 | 不负责什么 | 关键产出 |
|---|---|---|---|
| 前端 | 提交 SQL；按状态分流展示结果 / 错误 / Agent 面板 | 本地权限判定、直接连库 | UI 展示；诊断请求组装 |
| 执行接口 | 编排解析 → 鉴权 → 执行；统一状态码回传 | 生成修复 SQL、解释业务语义 | status + payload |
| Druid Parser | 本地语法解析，产出 Parsed SQL Object | 权限判断、真正执行 | AST / 操作对象结构 |
| 权限判定 | 抽取表/列/操作，与用户权限比对 | 语法纠错、SQL 改写建议 | ALLOW / DENY + 明细 |
| 诊断 Agent | 分析 PARSE / 可诊断 EXEC 错误，给建议与修正 SQL | 绕过门禁、代替权限系统放行 | 问题说明 + 修复 SQL |
从提交到前端分流的完整链路。解析失败与执行失败可交给 Agent 纠错；权限失败在打库前结束且直接展示。
这是主流程中最复杂的门禁阶段：从解析对象抽取出「对什么对象做了什么操作」，再逐条与用户权限匹配。
当本地解析失败，或执行失败且前端判定为可诊断错误时，把错误信息与 SQL 上下文喂给 Agent，产出问题说明、建议与修正 SQL。
建议前端提供「一键填入修正 SQL」；再次执行仍走完整主流程（解析 → 权限 → 执行），保证安全边界不被 Agent 绕过。
用时序图核对「谁在什么时候跟谁说话」，以及解析失败、权限失败、执行失败与 Agent 介入时机。
对用户一次请求一次响应；内部允许工具循环。能力抽象：Capability = Builtin | Skill | MCP。
System 定角色与硬约束；User 模板注入本次错误上下文。完整文件见 prompts/。
加载中…
加载中…
关键输出契约：errorCategory、problemSummary、rootCause、
suggestions、fixedSql、confidence、
assumptions、usedCapabilities。详见 docs/io-contract.md。
三类能力可组合。绿色内置、橙色技能、紫色 MCP。完整说明见 docs/capabilities.md。
Builtin Skills MCP
| 类型 | 名称 | 作用 | 约束 |
|---|---|---|---|
| Builtin | classify_db_error |
错误码/消息 → 错误类别 | 不打库 |
| Builtin | validate_sql_syntax |
Druid Parser 本地再解析修正 SQL | 仅本地解析 |
| Builtin | format_sql / diff_sql |
美化与差异对照 | 纯文本处理 |
| Skill | sql-syntax-repair |
PARSE_ERROR 常见语法修复模式 | 按需注入，避免撑爆上下文 |
| Skill | sql-semantic-repair |
表/列/聚合/JOIN 语义修复清单 | 宜配合 schema MCP |
| Skill | dialect-guide-* |
MySQL / Postgres / 通用方言指南 | 按 dialect 选择加载 |
| MCP | schema.get_table_schema |
只读获取列类型 / 主键等 | 尊重用户可见范围 |
| MCP | schema.list_tables |
列出可见表（可过滤） | 只读 |
| MCP | kb.search_error_cases |
检索历史修复案例（可选） | 以当前错误为准 |
执行接口用统一状态驱动 UI。前端只按状态分流，不自行猜测是否该调 Agent。
执行成功。展示结果集 / 影响行数。不调用 Agent。
本地语法解析失败。不打库；前端把 Parser 错误位置/消息 + 原始 SQL 交给 Agent，展示问题说明与修正 SQL。
对象/操作无权限。展示缺失的表、列、操作明细。不打库、不调 Agent。
真实执行失败。若 diagnosable=true，把错误 + SQL 上下文交给 Agent；否则直接展示错误。
建议响应体至少包含：status、message、sql、
parsedSummary（操作类型/表/列）、dbError（码/消息）、
diagnosable、permissionGaps（鉴权失败时）。