SQL 至 BI 构建器概述
使用此技能将 sql.md 查询集合转换为基于服务的 BI 原型。该技能必须从 SQL 派生的工件生成后端和前端服务。
工作流
解析 markdown SQL 块到规范化的查询目录。
推断查询语义（指标、维度、时间列、粒度提示）。
从 SQL DSL（WHERE 谓词）提取 P0 过滤器候选项到结构化过滤器元数据（dsl_ast 首先，正则表达式回退）。
根据推断的语义推荐图表类型。
构建带有布局坐标的仪表板规范。
生成渲染仪表板结构的 UI 脚手架。
生成服务包（services/backend + services/frontend），它依赖于生成的 SQL 工件。
输入合同
期望一个 markdown 文件，其中包含一个或多个 SQL 围栏块。
使用此模式以获得最佳结果：
# 销售仪表板
卡片：每日 GMV
- id：daily_gmv
- 数据源：mysql_prod
- 刷新：5m
- 图表：自动
- 过滤器：日期、地区
``
sql
SELECT DATE(pay_time) AS dt, SUM(amount) AS gmv FROM orders WHERE pay_status = 'paid' GROUP BY 1 ORDER BY 1;
规则：
- 保持每个逻辑查询为一个 SQL 围栏块。
在可能的情况下提供稳定的 id 元数据。
保持别名显式（AS alias）以提高语义推断。
Python 环境设置（必需）
从技能文件夹运行。
确保 python3.11 已安装并在 PATH 中可用。如果缺失，请按照 references/install_python311.md 进行操作。
- 创建虚拟环境：
``bash
bash scripts/setup_venv.sh
激活并验证：
source .venv/bin/activate
python --version
预期版本：Python 3.11.x。
当需要开发依赖项时使用 --with-dev：
bash scripts/setup_venv.sh --with-dev
运行命令
激活 .venv 后，运行管道和服务生成：
python scripts/run_pipeline.py \
--input /abs/path/sql.md \
--out /abs/path/out \
--with-services
单独运行每个步骤进行调试：
python scripts/parse_sql_md.py --input /abs/path/sql.md --output /abs/path/out/query_catalog.json
python scripts/infer_semantics.py --input /abs/path/out/query_catalog.json --output /abs/path/out/semantic_catalog.json
python scripts/recommend_chart.py --input /abs/path/out/semantic_catalog.json --output /abs/path/out/chart_plan.json
python scripts/build_dashboard_spec.py --queries /abs/path/out/query_catalog.json --semantics /abs/path/out/semantic_catalog.json --charts /abs/path/out/chart_plan.json --output /abs/path/out/dashboard.json
python scripts/generate_ui_scaffold.py --dashboard /abs/path/out/dashboard.json --out /abs/path/out/ui
python scripts/generate_service_bundle.py --artifacts /abs/path/out --output /abs/path/out/services
启动生成的服务：
bash /abs/path/out/services/start_backend.sh
bash /abs/path/out/services/start_frontend.sh
运行时和版本控制
仅使用 Python 3.11.x。
保持 .python-version 为 3.11。
保持 pyproject.toml requires-python = ">=3.11,<3.12"。
在运行上游验证器之前安装开发依赖项：
pip install -r requirements-dev.txt。
按范围提交更改：解析器、语义、图表规则、布局规则、脚手架。
使用语义版本标签（如 v0.1.0、v0.2.0）标记稳定里程碑。
输出
query_catalog.json：解析的查询单元和元数据。
semantic_catalog.json：从 SQL 条件中提取的字段角色、粒度提示和 dsl_filters。
dsl_filters 包括值类型和值格式，支持日期：yyyy-mm-dd、yyyy/mm/dd、yyyymmdd、yyyy-mm-dd hh:mm:ss、ISO-8601、yyyymmdd_int、unix 秒/毫秒整数。
chart_plan.json：每个查询的推荐图表类型。
dashboard.json：最终仪表板定义，用于渲染，包括页面级全局过滤器。
ui/：静态 UI 脚手架（index.html、app.js、style.css）。
services/backend：使用生成的工件的 FastAPI 后端服务。
services/frontend：消费后端 API 的前端服务。
services/start_backend.sh 和 services/start_frontend.sh：服务启动脚本。
UI 升级说明（2026-03）
使用存储库级服务 UI（services/frontend）时，升级的体验包括：
KPI 摘要条（点击聚焦小部件）
布局切换（经典/焦点）
新的午夜运营主题预设
更强的视觉层次结构，用于演示
启发式参考
仅加载当前问题所需的文件：
SQL 解析和命名约束：references/sql_style.md
图表映射规则：references/chart_rules.md
BI 布局和小部件大小：references/layout_rules.md
Python 3.11 安装和 venv 设置：references/install_python311.md
限制和升级
将当前脚本视为启发式 MVP。
当 SQL 包含嵌套 CTE 链、窗口密集的排名逻辑或具有不兼容列语义的联合时，升级为手动审查。
当图表置信度低时，回退到表格可视化。
by