助手写查库 SQL 时给结果列起中文别名:真实运行里报告表格的表头全是英文缩写的原始列名([[table:]] 原样用查询结果的列名)。节点手册里 Agent 查库的说明和写 SQL 的硬性要求都加上一条:结果列用中文别名,按方言加标识符引号(MySQL / MariaDB 用反引号,PostgreSQL、Oracle、SQLite 用双引号,不用单引号),只给最外层 SELECT 起别名;自查的列名核对把带引号的中文标识符抹掉再判,不再因为有带引号的中文别名就整条放弃核对、把猜错的英文列名一起放过去

This commit is contained in:
ThearchyHelios
2026-10-04 11:12:00 +08:00
parent a46bad0592
commit f4a9955cc3
3 changed files with 93 additions and 1 deletions
+22 -1
View File
@@ -152,6 +152,11 @@ NODE_REFERENCE = """\
查不到的记空值、不兜底成 0。assign_to 拿到的就是核对过的对象,口径卡直接写 vars.<assign_to>.字段。
只写 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)
+4
View File
@@ -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 = (
+67
View File
@@ -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