SQL 执行门禁与 Agent 诊断方案

入口预处理（非工具）

• 在 /sql/diagnose/stream 入口根据 status/code/message 做错误归类，注入 Prompt。
• 不注册为 Agent 可调用工具，避免「为调用而调用」。

工具清单（输入 → 输出）

硬约束：与执行门禁同源 Parser、同源权限； Agent「认为可解析」与「再次提交可过解析」一致；元数据不泄露无权对象。

双 SQL

• sql：用户提交（编辑器内容）
• executedSql：改写后实际打库；PARSE_ERROR 时为 null
• rewrite：改写规则说明（如 default_select_limit）

请求

POST /sql/execute
Content-Type: application/json

{
  "sql": "SELECT * FROM user",
  "dialect": "mysql",
  "connectionId": "lab-conn-001"
}

SUCCESS 响应（含改写）

{
  "requestId": "exec-7f3a",
  "status": "SUCCESS",
  "sql": "SELECT * FROM user",
  "executedSql": "SELECT * FROM user LIMIT 10",
  "rewrite": {
    "applied": true,
    "rules": ["default_select_limit"],
    "detail": "未指定 LIMIT，按实验室策略追加 LIMIT 10"
  },
  "diagnosable": false,
  "parsedSummary": { "action": "SELECT", "tables": ["user"], "columns": ["*"] },
  "result": { "columns": ["id", "name"], "rows": [[1, "alice"]], "rowCount": 1 },
  "error": null,
  "permissionGaps": null
}

前端建议展示「实际执行 SQL」。诊断时务必带上 sql + executedSql + rewrite； Agent 的 fixedSql 写回提交态（不含自动 LIMIT）。

请求

POST /sql/diagnose/stream
Content-Type: application/json
Accept: text/event-stream

{
  "requestId": "exec-7f3d",
  "status": "EXEC_ERROR",
  "sql": "SELECT nam FROM user",
  "executedSql": "SELECT nam FROM user LIMIT 10",
  "rewrite": {
    "applied": true,
    "rules": ["default_select_limit"],
    "detail": "未指定 LIMIT，按实验室策略追加 LIMIT 10"
  },
  "dialect": "mysql",
  "connectionId": "lab-conn-001",
  "diagnosable": true,
  "error": {
    "code": "42S22",
    "message": "Unknown column 'nam' in 'field list'"
  }
}

SSE 事件

成功流（节选）

event: meta
data: {"requestId":"diag-9c01","status":"PARSE_ERROR"}

event: phase
data: {"phase":"generate"}

event: tool
data: {"name":"validate_sql_syntax","state":"end","ok":true}

event: result
data: {"errorCategory":"SYNTAX","problemSummary":"SELECT 关键字拼写错误…","rootCause":"…","suggestions":["将 SELEC 改为 SELECT"],"fixedSql":"SELECT id FROM users","confidence":0.92,"assumptions":[],"usedCapabilities":["builtin:validate_sql_syntax"]}

event: done
data: {"ok":true}

result 固定字段

{
  "errorCategory": "SYNTAX",
  "problemSummary": "…",
  "rootCause": "…",
  "suggestions": ["…"],
  "fixedSql": "SELECT id FROM users",
  "confidence": 0.92,
  "assumptions": [],
  "usedCapabilities": ["builtin:validate_sql_syntax"]
}

原则：过程可流式；终态 JSON 必须完整。fixedSql 为提交态，再执行仍会改写。不要把自动 LIMIT 当作用户错误。