From f4a9955cc3b673a5b690b4578bf7c13c2626c333 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Sun, 4 Oct 2026 11:12:00 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8A=A9=E6=89=8B=E5=86=99=E6=9F=A5=E5=BA=93?= =?UTF-8?q?=20SQL=20=E6=97=B6=E7=BB=99=E7=BB=93=E6=9E=9C=E5=88=97=E8=B5=B7?= =?UTF-8?q?=E4=B8=AD=E6=96=87=E5=88=AB=E5=90=8D=EF=BC=9A=E7=9C=9F=E5=AE=9E?= =?UTF-8?q?=E8=BF=90=E8=A1=8C=E9=87=8C=E6=8A=A5=E5=91=8A=E8=A1=A8=E6=A0=BC?= =?UTF-8?q?=E7=9A=84=E8=A1=A8=E5=A4=B4=E5=85=A8=E6=98=AF=E8=8B=B1=E6=96=87?= =?UTF-8?q?=E7=BC=A9=E5=86=99=E7=9A=84=E5=8E=9F=E5=A7=8B=E5=88=97=E5=90=8D?= =?UTF-8?q?=EF=BC=88[[table:]]=20=E5=8E=9F=E6=A0=B7=E7=94=A8=E6=9F=A5?= =?UTF-8?q?=E8=AF=A2=E7=BB=93=E6=9E=9C=E7=9A=84=E5=88=97=E5=90=8D=EF=BC=89?= =?UTF-8?q?=E3=80=82=E8=8A=82=E7=82=B9=E6=89=8B=E5=86=8C=E9=87=8C=20Agent?= =?UTF-8?q?=20=E6=9F=A5=E5=BA=93=E7=9A=84=E8=AF=B4=E6=98=8E=E5=92=8C?= =?UTF-8?q?=E5=86=99=20SQL=20=E7=9A=84=E7=A1=AC=E6=80=A7=E8=A6=81=E6=B1=82?= =?UTF-8?q?=E9=83=BD=E5=8A=A0=E4=B8=8A=E4=B8=80=E6=9D=A1=EF=BC=9A=E7=BB=93?= =?UTF-8?q?=E6=9E=9C=E5=88=97=E7=94=A8=E4=B8=AD=E6=96=87=E5=88=AB=E5=90=8D?= =?UTF-8?q?=EF=BC=8C=E6=8C=89=E6=96=B9=E8=A8=80=E5=8A=A0=E6=A0=87=E8=AF=86?= =?UTF-8?q?=E7=AC=A6=E5=BC=95=E5=8F=B7=EF=BC=88MySQL=20/=20MariaDB=20?= =?UTF-8?q?=E7=94=A8=E5=8F=8D=E5=BC=95=E5=8F=B7=EF=BC=8CPostgreSQL?= =?UTF-8?q?=E3=80=81Oracle=E3=80=81SQLite=20=E7=94=A8=E5=8F=8C=E5=BC=95?= =?UTF-8?q?=E5=8F=B7=EF=BC=8C=E4=B8=8D=E7=94=A8=E5=8D=95=E5=BC=95=E5=8F=B7?= =?UTF-8?q?=EF=BC=89=EF=BC=8C=E5=8F=AA=E7=BB=99=E6=9C=80=E5=A4=96=E5=B1=82?= =?UTF-8?q?=20SELECT=20=E8=B5=B7=E5=88=AB=E5=90=8D=EF=BC=9B=E8=87=AA?= =?UTF-8?q?=E6=9F=A5=E7=9A=84=E5=88=97=E5=90=8D=E6=A0=B8=E5=AF=B9=E6=8A=8A?= =?UTF-8?q?=E5=B8=A6=E5=BC=95=E5=8F=B7=E7=9A=84=E4=B8=AD=E6=96=87=E6=A0=87?= =?UTF-8?q?=E8=AF=86=E7=AC=A6=E6=8A=B9=E6=8E=89=E5=86=8D=E5=88=A4=EF=BC=8C?= =?UTF-8?q?=E4=B8=8D=E5=86=8D=E5=9B=A0=E4=B8=BA=E6=9C=89=E5=B8=A6=E5=BC=95?= =?UTF-8?q?=E5=8F=B7=E7=9A=84=E4=B8=AD=E6=96=87=E5=88=AB=E5=90=8D=E5=B0=B1?= =?UTF-8?q?=E6=95=B4=E6=9D=A1=E6=94=BE=E5=BC=83=E6=A0=B8=E5=AF=B9=E3=80=81?= =?UTF-8?q?=E6=8A=8A=E7=8C=9C=E9=94=99=E7=9A=84=E8=8B=B1=E6=96=87=E5=88=97?= =?UTF-8?q?=E5=90=8D=E4=B8=80=E8=B5=B7=E6=94=BE=E8=BF=87=E5=8E=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/app/api/copilot.py | 23 ++++++++- backend/app/api/copilot_context.py | 4 ++ backend/tests/test_copilot_sql_alias.py | 67 +++++++++++++++++++++++++ 3 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 backend/tests/test_copilot_sql_alias.py diff --git a/backend/app/api/copilot.py b/backend/app/api/copilot.py index 2c49e468..fe0334c9 100644 --- a/backend/app/api/copilot.py +++ b/backend/app/api/copilot.py @@ -152,6 +152,11 @@ NODE_REFERENCE = """\ 查不到的记空值、不兜底成 0。assign_to 拿到的就是核对过的对象,口径卡直接写 vars..字段。 只写 output_schema 不开 cite_fields 不生效。**不要用 transform 解析 agent / llm 的文字**:模型写的 JSON 常夹着没转义的引号,解析一失败整个节点就失败,也核对不了出处 + **agent 查库时**,prompt 里写明查询结果列用中文别名(AS 月份、AS 曝光量):报告用 [[table:]] 生成的表格表头、 + [[v:]] 引用、口径卡的 cell() 都用这个列名,写成英文缩写的原始列名读的人看不懂。中文别名按数据源的方言 + 加标识符引号:MySQL / MariaDB 用反引号(AS `月份`),PostgreSQL、Oracle、SQLite 用双引号(AS "月份"),不要用 + 单引号(那是字符串)。只给最外层 SELECT 的结果列起别名,WHERE、JOIN、GROUP BY 里照旧写原列名;Oracle 旧版本 + 的标识符最长 30 字节,别名不超过 10 个字 **默认不要写 max_steps、budget_tokens、budget_usd**。平台用的是护栏而不是固定步数: 步数只是很高的兜底(跟随设置,默认 100),重复调用、连续几步没有新信息、预算用完、 上下文快满时,它会按查到的部分收尾。写死一个小数字(见过 8)会让它查完表结构就没额度回答了。 @@ -1463,6 +1468,22 @@ _DATEPART_ARG = re.compile( _WINDOW_NAME = re.compile(r"(?:\bwindow|,)\s*([A-Za-z_][\w$#]*)\s+as\s*\(", re.I) +def _blank_unicode_identifiers(sql: str) -> str: + """带引号、名字里有非 ASCII 字符的标识符(中文别名 AS "月份"、AS `曝光量`)连引号一起换成空格。 + + 这项核对只认 ASCII 的列名,中文名本来就不判;不抹掉的话,SQL 里一出现带引号的标识符就整条放弃核对,照「结果列 + 起中文别名」写的 SQL 会把猜错的英文列名一起放过去。英文的带引号标识符("StatDate")大小写、空格都可能,照旧不判。""" + from app.data.guard import _GENERIC, _tokens + + out = [] + for token in _tokens(sql, _GENERIC): + if token.kind == "ident" and not token.text.isascii(): + out.append(" " * len(token.text)) + else: + out.append(token.text) + return "".join(out) + + def sql_unknown_columns(sql: str, source: Any) -> tuple[list[str], list[str]] | None: """SQL 里用到、数据源结构里查不到的列:(查不到的列, 这几张表的全部列)。判断不了、或者都查得到时返回 None。""" from app.data import introspect as _introspect @@ -1471,7 +1492,7 @@ def sql_unknown_columns(sql: str, source: Any) -> tuple[list[str], list[str]] | cache = getattr(source, "schema_cache", None) or {} if not cache.get("tables") or cache.get("failed") or first_verb(sql) != "select": return None - text = re.sub(r"\{\{.*?\}\}", " 0 ", strip_comments(sql), flags=re.S) + text = _blank_unicode_identifiers(re.sub(r"\{\{.*?\}\}", " 0 ", strip_comments(sql), flags=re.S)) if '"' in text.replace("''", "") and _blank_quoted(text) != _blank_quoted(text, identifiers=False): return None # 引号括起来的标识符:大小写、空格都可能,不猜 text = _blank_quoted(text) diff --git a/backend/app/api/copilot_context.py b/backend/app/api/copilot_context.py index 6c527ebc..5b065047 100644 --- a/backend/app/api/copilot_context.py +++ b/backend/app/api/copilot_context.py @@ -99,6 +99,10 @@ SQL_RULES_PROMPT = ( "去对结构,对不上会打回来让你改\n" "- 比率、增幅、占比这类派生计算进口径卡(metrics 节点);查询结果里原样的数,报告撰写节点(report)" "可以直接用 [[v:Q1.r0.列名]] 引用。别让 llm 节点直接对数字做算术\n" + # 真实运行里报告表格的表头全是英文缩写的原始列名:[[table:]] 原样用查询结果的列名 + "- 结果列用中文别名(AS 月份、AS 曝光量),报告里的表格表头、引用直接可读。按上面标的方言加标识符引号:" + "MySQL / MariaDB 用反引号(AS `月份`),PostgreSQL、Oracle、SQLite 用双引号(AS \"月份\"),不要用单引号" + "(那是字符串);只给最外层 SELECT 的结果列起别名,WHERE、JOIN、GROUP BY 里照旧写原列名\n" ) PICK_SYSTEM = ( diff --git a/backend/tests/test_copilot_sql_alias.py b/backend/tests/test_copilot_sql_alias.py new file mode 100644 index 00000000..59a79893 --- /dev/null +++ b/backend/tests/test_copilot_sql_alias.py @@ -0,0 +1,67 @@ +"""助手写查库 SQL 时给结果列起中文别名,报告里的表格表头直接可读。 + +真实运行里:报告节点用 [[table:…]] 把查询结果原样生成表格,表头就是 Agent 写的 SQL 里的列名——一串英文缩写的 +原始列名,读报告的人得猜。结果列起中文别名(AS 月份、AS 曝光量)以后,表头、单元格引用、口径卡的 +cell() 都直接用中文名。 + +中文别名要按方言加标识符引号:MySQL / MariaDB 用反引号,PostgreSQL、Oracle、SQLite 用双引号;单引号是字符串。 + +这组守的是: +- 节点手册里 Agent 查库的说明、写 SQL 的硬性要求(搭查库节点时的规则)都有这一条,按方言给出示例 +- 加了引号的中文别名不让自查放弃列名核对:以前 SQL 里只要有带引号的标识符就整条不判,照这条规矩写的 SQL + 会把猜错的英文列名一起放过去 +""" +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from app.api.copilot import NODE_REFERENCE, sql_unknown_columns +from app.api.copilot_context import SQL_RULES_PROMPT + + +def _agent_rule() -> str: + start = NODE_REFERENCE.index("- agent:带工具循环的 agent") + return NODE_REFERENCE[start:NODE_REFERENCE.index("\n- supervisor:", start)] + + +@pytest.mark.parametrize("text", [_agent_rule(), SQL_RULES_PROMPT], ids=["agent", "sql-rules"]) +def test_guidance_asks_for_chinese_aliases_with_dialect_quotes(text): + assert "中文别名" in text + assert "AS `月份`" in text and "MySQL" in text # MySQL / MariaDB:反引号 + assert 'AS "月份"' in text and "PostgreSQL" in text and "Oracle" in text and "SQLite" in text + assert "单引号" in text # 单引号是字符串,不是别名 + + +def _source(**tables): + return SimpleNamespace(name="shop", schema_cache={"tables": { + name: {"qualified": name, "columns": [{"name": c} for c in cols]} for name, cols in tables.items()}}) + + +SHOP = _source(daily_stats=["id", "stat_date", "impressions", "clicks", "region"]) + + +@pytest.mark.parametrize("sql", [ + 'SELECT stat_date AS "日期", SUM(impressions) AS "曝光量" FROM daily_stats GROUP BY stat_date ORDER BY "日期"', + "SELECT stat_date AS `日期`, SUM(impressions) AS `曝光量` FROM daily_stats GROUP BY stat_date ORDER BY `曝光量` DESC", + "SELECT stat_date AS 日期, SUM(clicks) AS 点击量 FROM daily_stats GROUP BY stat_date", + 'SELECT region AS "区域", COUNT(*) AS "天数" FROM daily_stats WHERE region = \'华东\' GROUP BY region', +]) +def test_quoted_chinese_aliases_are_fine(sql): + assert sql_unknown_columns(sql, SHOP) is None, sql_unknown_columns(sql, SHOP) + + +@pytest.mark.parametrize("sql, unknown", [ + ('SELECT stat_date AS "日期", SUM(impresions) AS "曝光量" FROM daily_stats GROUP BY stat_date', ["impresions"]), + ("SELECT stat_month AS `月份`, SUM(impressions) AS `曝光量` FROM daily_stats GROUP BY stat_month", + ["stat_month"]), +]) +def test_guessed_columns_next_to_quoted_chinese_aliases_are_still_caught(sql, unknown): + found = sql_unknown_columns(sql, SHOP) + assert found is not None and found[0] == unknown, found + + +def test_quoted_ascii_identifiers_are_still_not_guessed(): + # 带引号的英文标识符:大小写、空格都可能,照旧不判 + assert sql_unknown_columns('SELECT "StatDate", impresions FROM daily_stats', SHOP) is None