数据目录阶段 2B:助手自查接上 SQL 检查——工具节点里写死的 SQL 查出 error 进修正轮,warning 和 info 留在交付的问题清单

This commit is contained in:
ThearchyHelios
2026-10-03 10:19:48 +08:00
parent 0e689c1b18
commit 8d31164a8b
3 changed files with 367 additions and 8 deletions
+32 -7
View File
@@ -16,6 +16,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.api.coded import DATASOURCE_SCOPE_EMPTY, CodedHTTPException
# 起别名:本文件底下有个叫 explain 的接口,generate 里又有个局部变量叫 raw,同名会互相盖掉
from app.core.errors import explain as explain_error, graph_error, not_configured, raw as raw_error
from app.data.sqlcheck import CHECK_CODES
from app.db.base import get_session
from app.db.models import Workflow
from app.engine.layout import CORRIDOR_MIN, MIN_ROW_GAP, NODE_W, _height, auto_layout
@@ -1081,6 +1082,7 @@ def _blocking_issues(
nodes: dict[str, dict[str, Any]], edges: list[dict[str, Any]], scope: set[str] | None = None,
*, sources: list[Any] | None = None, baseline: list[dict[str, Any]] | None = None,
level: str | None = None, defaults: dict[str, Any] | None = None,
checkers: dict[str, Any] | None = None,
) -> list[dict[str, Any]] | None:
"""按运行时同一套校验,挑出会挡住运行的问题。图本身不成形时返回 None。
@@ -1098,6 +1100,9 @@ def _blocking_issues(
defaults 是全图默认(graph.defaults):报告撰写节点的 numbers / claims、审批策略都跟随它,不带上的话
自查看到的问题和真正的门禁对不上。
checkers 是各数据源基于数据目录的 SQL 检查器(data/sqlcheck.load_checkers):调用工具节点里写死的 SQL
查出 error 级的问题(一对多关联后重复计算、存量跨期求和)也算挡住,交回模型改;warning、info 不挡。
"""
try:
spec = GraphSpec.model_validate({"nodes": list(nodes.values()), "edges": edges,
@@ -1106,7 +1111,7 @@ def _blocking_issues(
return None
out = ([i.model_dump() for i in validate_graph(spec).issues if i.level == "error"]
+ _issue_dicts(scope_issues(list(nodes.values()), scope), "datasource_out_of_scope")
+ authored_issues(spec, sources or [], baseline))
+ [i for i in authored_issues(spec, sources or [], baseline, checkers=checkers) if i["level"] == "error"])
if level:
from app.engine.governance import lint_for_publish
@@ -1181,7 +1186,7 @@ def _unsourced_reports(spec: GraphSpec, changed: set[str]) -> list[dict[str, Any
def authored_issues(spec: GraphSpec, sources: list[Any], baseline: list[dict[str, Any]] | None = None,
) -> list[dict[str, Any]]:
*, checkers: dict[str, Any] | None = None) -> list[dict[str, Any]]:
"""助手搭图时要打回、运行时却不挡的写法,按 error 交回模型改:
- sql_unknown_column:调用工具节点的 SQL 里有数据源结构(schema_cache)里查不到的列——凭空
@@ -1189,6 +1194,11 @@ def authored_issues(spec: GraphSpec, sources: list[Any], baseline: list[dict[str
- parse_model_text:整形节点按 JSON 解析 agent / llm 写的文字(validate 里只是 warning:旧图照跑)
- report_no_source:报告撰写节点的上游没有任何证据来源(运行时只给一条警告,报告里的数全没有出处)。
metrics_from 指向不是口径卡的节点,validate 本来就报 error,自查照样交回去
另外,给了 checkers(各数据源基于数据目录的 SQL 检查器)时,调用工具节点里写死的 SQL 再对照目录查一遍
(code 是 data/sqlcheck.CHECK_CODES 里的规则编号),级别照检查结果:error 交回模型改,warning、info
由调用方放进交付的问题清单。列名都对不上的 SQL 先改列名,这一轮不叠加目录检查。Agent 节点的 SQL 要到
运行时才写出来,这里拿不到,由数据源查询工具在执行后检查。
"""
changed = _changed(spec, baseline)
out: list[dict[str, Any]] = []
@@ -1212,6 +1222,7 @@ def authored_issues(spec: GraphSpec, sources: list[Any], baseline: list[dict[str
continue
found = sql_unknown_columns(sql, source)
if not found:
out += _catalog_issues(node.id, sql, (checkers or {}).get(source.name))
continue
unknown, known = found
listed = "、".join(known[:20]) + (f" 等 {len(known)} 列" if len(known) > 20 else "")
@@ -1225,6 +1236,14 @@ def authored_issues(spec: GraphSpec, sources: list[Any], baseline: list[dict[str
return out
def _catalog_issues(node_id: str, sql: str, checker: Any) -> list[dict[str, Any]]:
"""一个调用工具节点的 SQL 对照数据目录查出来的问题,形状和别的自查问题一样(node_id、field 都在),
另带 table、column、relation_id、sql_excerpt 给界面定位。"""
if checker is None:
return []
return [{**check, "node_id": node_id, "edge_id": None, "field": "args.sql"} for check in checker.check_dicts(sql)]
# --------------------------------------------------------------------------
# SQL 里的列名对照数据源结构
#
@@ -1599,10 +1618,14 @@ async def generate_stream(payload: GenerateIn, session: AsyncSession = Depends(g
"""
from fastapi.responses import StreamingResponse
from app.data.sqlcheck import load_checkers
sources = await _sources(session, payload.datasource_ids)
scope = {r.name for r in sources} if payload.datasource_ids else None
tool_list = _tool_catalog(sources)
datasources = _datasource_section(sources) + _scope_note(sources, scope is not None)
# 基于数据目录的 SQL 检查器:在开流之前读好目录(流里不再碰这个会话),自查和收尾共用
checkers = await load_checkers(session, sources)
system = (
"你是一个 agent 工作流编排专家。根据用户需求,以操作流的方式逐步搭出一张可执行的工作流图。\n\n"
f"{NODE_REFERENCE}\n\n可用工具:\n{tool_list}{datasources}\n\n"
@@ -1721,7 +1744,7 @@ async def generate_stream(payload: GenerateIn, session: AsyncSession = Depends(g
# 循环 / 分支条件里套了 {{ }}),前面的步骤白跑,报错还停在半路
repaired = 0
for round_no in range(1, _SELF_CHECK_ROUNDS + 1):
errors = _blocking_issues(nodes, edges, scope, sources=sources, baseline=baseline)
errors = _blocking_issues(nodes, edges, scope, sources=sources, baseline=baseline, checkers=checkers)
if not errors:
break
yield _sse({"op": "check", "status": "repairing", "round": round_no, "issues": errors})
@@ -1739,7 +1762,7 @@ async def generate_stream(payload: GenerateIn, session: AsyncSession = Depends(g
"message": f"自查修正失败:{explain_error(e)[0]}", "detail": raw_error(e)})
break
repaired = round_no
remaining = _blocking_issues(nodes, edges, scope, sources=sources, baseline=baseline)
remaining = _blocking_issues(nodes, edges, scope, sources=sources, baseline=baseline, checkers=checkers)
# 工具绑定变化不挡运行,但要在自查这一步就说出来:工具被改没了的图照样
# 能跑,只是跑出来的是模型「假设」查过库的答案
changes = tool_changes(baseline, list(nodes.values()))
@@ -1763,9 +1786,11 @@ async def generate_stream(payload: GenerateIn, session: AsyncSession = Depends(g
issues = [i.model_dump() for i in validate_graph(spec).issues if i.level != "info"]
issues += _issue_dicts(scope_issues(list(nodes.values()), scope),
"datasource_out_of_scope")
# 自查没改好的猜列名留在画布上:运行时不挡(结构缓存可能旧了),但要看得见
issues += [{**i, "level": "warning"} for i in authored_issues(spec, sources, baseline)
if i["code"] == "sql_unknown_column"]
# 自查没改好的猜列名留在画布上:运行时不挡(结构缓存可能旧了),但要看得见。
# 对照数据目录的 SQL 检查照原级别列出:warning、info 本来就不返工,改不好的 error 也在这里看得见
authored = authored_issues(spec, sources, baseline, checkers=checkers)
issues += [{**i, "level": "warning"} for i in authored if i["code"] == "sql_unknown_column"]
issues += [i for i in authored if i["code"] in CHECK_CODES]
# 跳过的节点要说出来,不能安静地少一步。code 给前端认:这一类要单独
# 提示「少了一步」,不能和普通校验警告混在一起
issues += [
+90 -1
View File
@@ -955,5 +955,94 @@ def _known_code(literal: tuple[str, bool], codes: Mapping[str, Any]) -> bool:
return number is not None and any(_number(k) == number for k in keys)
# ==========================================================================
# 工作流里写死的 SQL、从库里读目录
# ==========================================================================
def tool_query(node: Any) -> tuple[str, str] | None:
"""调用工具节点里写死的查询:(数据源名, SQL)。不是数据源查询工具、SQL 不是字符串的返回 None。
Agent 节点的 SQL 要到运行时才由模型写出来,静态拿不到,这里不管;它们由数据源查询工具在执行后检查。
"""
from app.tools.datasource import QUERY_PREFIX
if str(getattr(node, "type", "")) != "tool":
return None
config = getattr(node, "config", None) or {}
tool = str(config.get("tool") or "")
args = config.get("args")
sql = args.get("sql") if isinstance(args, Mapping) else None
if not tool.startswith(QUERY_PREFIX) or not isinstance(sql, str) or not sql.strip():
return None
return tool[len(QUERY_PREFIX):], sql
def graph_sources(nodes: Iterable[Any]) -> set[str]:
"""一张图里调用工具节点写死查询用到的数据源名。"""
return {found[0] for node in nodes if (found := tool_query(node))}
def graph_checks(nodes: Iterable[Any], checkers: Mapping[str, SqlChecker], *,
only: set[str] | None = None) -> list[tuple[Any, SqlCheck]]:
"""一张图里调用工具节点写死的 SQL 逐个检查:[(节点, 结果)]。only 给了就只查这些节点。"""
out: list[tuple[Any, SqlCheck]] = []
for node in nodes:
if only is not None and getattr(node, "id", None) not in only:
continue
found = tool_query(node)
checker = checkers.get(found[0]) if found else None
if checker is not None:
out += [(node, check) for check in checker.check(found[1])]
return out
async def load_checkers(session: Any, sources: Iterable[Any]) -> dict[str, SqlChecker]:
"""给一批数据源(DataSource 行)各建一个检查器:{源名: SqlChecker}。没有目录的源不建。
一次查询读出这些源的全部目录。读不到就当没有目录(返回空 dict):检查是附加的,不能挡住自查和发布本身。
"""
from sqlalchemy import select
from app.db.models import CatalogNote
rows = [s for s in sources if getattr(s, "id", None) and dialect_of(getattr(s, "kind", None))]
if not rows:
return {}
try:
notes = (await session.execute(
select(CatalogNote.source_id, CatalogNote.table_name, CatalogNote.notes)
.where(CatalogNote.source_id.in_([r.id for r in rows]))
)).all()
except Exception: # noqa: BLE001
logger.exception("读取数据目录失败,本次不做基于目录的 SQL 检查")
return {}
by_source: dict[str, dict[str, Any]] = {}
for source_id, table, value in notes:
if isinstance(value, dict) and value:
by_source.setdefault(source_id, {})[table] = value
return {r.name: SqlChecker(kind=r.kind, schema_cache=r.schema_cache, notes=by_source[r.id], source_name=r.name)
for r in rows if r.id in by_source}
async def load_checkers_by_name(session: Any, names: Iterable[str]) -> dict[str, SqlChecker]:
"""按数据源名建检查器(只看启用着的源)。发布门禁用:图里写的是源名。"""
from sqlalchemy import select
from app.db.models import DataSource
wanted = sorted({n for n in names if n})
if not wanted:
return {}
try:
rows = list((await session.execute(
select(DataSource).where(DataSource.name.in_(wanted), DataSource.enabled.is_(True))
)).scalars())
except Exception: # noqa: BLE001
logger.exception("读取数据源失败,本次不做基于目录的 SQL 检查")
return {}
return await load_checkers(session, rows)
__all__ = ["CHECK_CODES", "LEVELS", "MAX_CHECKS", "MAX_SQL_CHARS", "SqlCheck", "SqlChecker", "check_sql",
"dialect_of"]
"dialect_of", "graph_checks", "graph_sources", "load_checkers", "load_checkers_by_name", "tool_query"]
+245
View File
@@ -0,0 +1,245 @@
"""助手搭完图的自查接上基于数据目录的 SQL 检查(data/sqlcheck.py)。
- 调用工具节点里写死的 SQL 走现有的自查:error 级(一对多关联后重复计算、存量跨期求和)交回模型改,进修正轮;
warning、info 不返工,放进 final 的问题清单。
- Agent 节点的 SQL 要到运行时才由模型写出来,静态拿不到,不查(运行时由数据源查询工具检查)。
- 这一轮没碰的节点不查:用户自己写的 SQL 不替他改(和列名核对同一个规矩)。
- 没有目录的数据源什么都不查。
"""
from __future__ import annotations
import json
import uuid
from types import SimpleNamespace
import pytest
from httpx import ASGITransport, AsyncClient
from app.data import catalog
from app.data.engine import engines
from app.data.introspect import introspect
from app.data.sqlcheck import SqlChecker
from tests.fixtures.catalog import scenic_notes
FANOUT_SQL = ("SELECT SUM(o.total_amount) AS gmv FROM orders o JOIN order_items i ON i.order_id = o.id "
"WHERE o.status = 1")
#: 改好的:对明细求和;没按订单状态筛,留一条 warning
FIXED_SQL = "SELECT SUM(i.amount) AS gmv FROM orders o JOIN order_items i ON i.order_id = o.id"
CLEAN_SQL = "SELECT SUM(i.amount) AS gmv FROM orders o JOIN order_items i ON i.order_id = o.id WHERE o.status = 1"
_CACHE: dict[str, dict] = {}
async def _schema(path: str) -> dict:
if path not in _CACHE:
probe = SimpleNamespace(id=f"probe-{uuid.uuid4().hex[:6]}", name="scenic", kind="sqlite", database=path,
host=None, port=None, username=None, password=None, options={}, readonly=True,
description="", schema_cache={}, origin="manual")
try:
_CACHE[path] = await introspect(probe)
finally:
await engines.invalidate(probe.id)
return _CACHE[path]
def _spec(*nodes):
from app.engine.schema import GraphSpec
return GraphSpec.model_validate({"nodes": list(nodes), "edges": [
{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])]})
def _node(nid, ntype, **config):
return {"id": nid, "type": ntype, "data": {"label": nid, "config": config}}
def _fetch(sql, source="scenic"):
return _node("fetch", "tool", tool=f"db_query__{source}", args={"sql": sql})
async def _checkers(scenic_db, status="confirmed"):
cache = await _schema(scenic_db)
source = SimpleNamespace(id="s1", name="scenic", kind="sqlite", schema_cache=cache)
checker = SqlChecker(kind="sqlite", schema_cache=cache, notes=scenic_notes.notes(status), source_name="scenic")
return source, {"scenic": checker}
# --------------------------------------------------------------------------
# authored_issues / _blocking_issues
# --------------------------------------------------------------------------
async def test_sql_check_errors_block_and_warnings_do_not(scenic_db):
from app.api.copilot import _blocking_issues, authored_issues
source, checkers = await _checkers(scenic_db)
spec = _spec(_node("start", "input"), _fetch(FANOUT_SQL), _node("out", "output", fields=[]))
[issue] = authored_issues(spec, [source], checkers=checkers)
assert issue["code"] == "fanout_sum" and issue["level"] == "error"
assert issue["node_id"] == "fetch" and issue["field"] == "args.sql"
assert issue["table"] == "orders" and issue["column"] == "total_amount" and issue["sql_excerpt"]
assert issue["message"].startswith("「订单」关联「订单明细」是一对多") and "order_items" in issue["for_model"]
nodes = {n.id: n.model_dump(mode="json") for n in spec.nodes}
assert [i["code"] for i in _blocking_issues(nodes, [], sources=[source], checkers=checkers)] == ["fanout_sum"]
# 只有 warning:不挡(不返工),但 authored_issues 照样带出来,收尾时放进 final
warn = _spec(_node("start", "input"), _fetch(FIXED_SQL), _node("out", "output", fields=[]))
[w] = authored_issues(warn, [source], checkers=checkers)
assert (w["code"], w["level"]) == ("missing_valid_filter", "warning")
nodes = {n.id: n.model_dump(mode="json") for n in warn.nodes}
assert _blocking_issues(nodes, [], sources=[source], checkers=checkers) == []
# 依据只是推断:降为 info,也不挡
_, proposed = await _checkers(scenic_db, "proposed")
assert {i["level"] for i in authored_issues(spec, [source], checkers=proposed)} == {"info"}
# 不给检查器(没有目录):和以前一样什么都不查
assert authored_issues(spec, [source]) == []
async def test_unknown_columns_come_first(scenic_db):
"""列名都对不上的 SQL 先改列名:这时不再叠加目录检查的结果,免得一轮里塞给模型两套说法。"""
from app.api.copilot import authored_issues
source, checkers = await _checkers(scenic_db)
bad = ("SELECT SUM(o.total_amt) AS gmv FROM orders o JOIN order_items i ON i.order_id = o.id "
"WHERE o.status = 1")
spec = _spec(_node("start", "input"), _fetch(bad), _node("out", "output", fields=[]))
assert [i["code"] for i in authored_issues(spec, [source], checkers=checkers)] == ["sql_unknown_column"]
async def test_agent_prompts_and_untouched_nodes_are_not_checked(scenic_db):
from app.api.copilot import authored_issues
source, checkers = await _checkers(scenic_db)
agent = _node("ask", "agent", prompt=f"用这条 SQL 查:{FANOUT_SQL}", tools=["db_query__scenic"])
spec = _spec(_node("start", "input"), agent, _node("out", "output", fields=[]))
assert authored_issues(spec, [source], checkers=checkers) == []
# 用户自己写的、这一轮没改的 SQL 不替他改
fetch = _fetch(FANOUT_SQL)
untouched = _spec(_node("start", "input"), fetch, _node("out", "output", fields=[]))
assert authored_issues(untouched, [source], baseline=[fetch], checkers=checkers) == []
# 模板占位照常检查其余部分
templated = _fetch("SELECT SUM(o.total_amount) FROM orders o JOIN order_items i ON i.order_id = o.id "
"WHERE o.status = 1 AND o.ordered_at >= '{{ input.since }}'")
out = authored_issues(_spec(_node("start", "input"), templated, _node("out", "output", fields=[])), [source],
checkers=checkers)
assert [i["code"] for i in out] == ["fanout_sum"]
# --------------------------------------------------------------------------
# 端到端:假模型搭图,error 进修正轮,warning 留在 final
# --------------------------------------------------------------------------
class _Scripted:
"""第一轮吐 first;收到自查请求(human 里有「上线前自查」)时吐 fix。"""
def __init__(self, first, fix):
self.first, self.fix = first, fix
self.calls: list[str] = []
async def astream(self, messages):
from langchain_core.messages import AIMessageChunk
human = next(text for role, text in messages if role == "human")
self.calls.append(human)
for op in (self.fix if "上线前自查" in human else self.first):
yield AIMessageChunk(content=json.dumps(op, ensure_ascii=False) + "\n")
def _ops(source, sql):
return [
{"op": "plan", "summary": "查订单金额"},
{"op": "add_node", "node": {"id": "start", "type": "input", "label": "输入", "config": {}}},
{"op": "add_node", "node": {"id": "fetch", "type": "tool", "label": "取数",
"config": {"tool": f"db_query__{source}", "args": {"sql": sql}}}},
{"op": "add_edge", "edge": {"source": "start", "target": "fetch"}},
{"op": "add_node", "node": {"id": "out", "type": "output", "label": "成果",
"config": {"fields": [{"name": "r", "value": "{{ nodes.fetch }}"}]}}},
{"op": "add_edge", "edge": {"source": "fetch", "target": "out"}},
{"op": "done", "explanation": "查一下", "run": True},
]
@pytest.fixture
async def scenic_source(scenic_db):
"""库里一个带目录的景区数据源:表结构真实探查,目录按 scenic_notes 写进 catalog_notes。"""
from app.db.base import SessionLocal
from app.db.models import DataSource
name = f"scenic_{uuid.uuid4().hex[:8]}"
async with SessionLocal() as session:
row = DataSource(name=name, kind="sqlite", database=scenic_db, readonly=True)
row.schema_cache = await _schema(scenic_db)
session.add(row)
await session.commit()
for table, notes in scenic_notes.notes().items():
await catalog.write_entry(session, row.id, table, notes, if_version=0, actor="王敏")
source_id = row.id
yield name
async with SessionLocal() as session:
row = await session.get(DataSource, source_id)
row.enabled = False
await session.commit()
async def _stream(monkeypatch, model, source):
import app.api.copilot as copilot
from app.main import app
async def _model(*_a, **_k):
return model, "mock-fast"
monkeypatch.setattr(copilot, "get_chat_model", _model)
events: list[dict] = []
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
async with client.stream("POST", "/api/copilot/generate-stream",
json={"instruction": "上周订单金额多少", "intent": "answer",
"datasource_ids": [source]}) as r:
async for line in r.aiter_lines():
if line.startswith("data: "):
events.append(json.loads(line[6:]))
return events
async def test_fanout_is_sent_back_and_fixed_before_running(scenic_source, monkeypatch):
model = _Scripted(_ops(scenic_source, FANOUT_SQL),
[{"op": "update_node", "id": "fetch", "config": {"args": {"sql": FIXED_SQL}}},
{"op": "done", "explanation": "改好了"}])
events = await _stream(monkeypatch, model, scenic_source)
checks = [e for e in events if e["op"] == "check"]
assert [c["status"] for c in checks] == ["repairing", "passed"], checks
[issue] = checks[0]["issues"]
assert issue["code"] == "fanout_sum" and issue["node_id"] == "fetch"
# 交回模型的是 for_model:写 SQL 里的真名和改法
assert "orders 关联 order_items 是一对多" in model.calls[1] and "「fetch」" in model.calls[1]
final = events[-1]
assert final["op"] == "final" and final["autorun"] is True
sql = next(n for n in final["graph"]["nodes"] if n["id"] == "fetch")["data"]["config"]["args"]["sql"]
assert sql == FIXED_SQL
# 剩下的 warning 不返工,留在 final 里看得见
[warn] = [i for i in final["issues"] if i.get("code") == "missing_valid_filter"]
assert warn["level"] == "warning" and warn["node_id"] == "fetch" and "status = 1" in warn["message"]
assert not [i for i in final["issues"] if i["level"] == "error"]
async def test_a_fanout_that_is_not_fixed_stops_autorun(scenic_source, monkeypatch):
model = _Scripted(_ops(scenic_source, FANOUT_SQL),
[{"op": "update_node", "id": "fetch", "config": {"args": {"sql": FANOUT_SQL + " "}}},
{"op": "done", "explanation": "改了"}])
events = await _stream(monkeypatch, model, scenic_source)
checks = [e for e in events if e["op"] == "check"]
assert [c["status"] for c in checks] == ["repairing", "repairing", "failed"], checks
final = events[-1]
assert final["autorun"] is False
assert [i["code"] for i in final["issues"] if i["level"] == "error"] == ["fanout_sum"]
async def test_clean_sql_costs_no_extra_call(scenic_source, monkeypatch):
model = _Scripted(_ops(scenic_source, CLEAN_SQL), [])
events = await _stream(monkeypatch, model, scenic_source)
assert len(model.calls) == 1
assert [e["status"] for e in events if e["op"] == "check"] == ["passed"]
final = events[-1]
assert final["autorun"] is True
assert not [i for i in final["issues"] if i.get("code") in ("fanout_sum", "missing_valid_filter")]