SQL Master

SQL 查询、数据获取智能体。覆盖 SQL 全链路能力：自然语言转生产级 SQL、慢查询诊断与执行计划分析、索引设计与优化、数仓建模、SQL 原理深度科普、查询结果可视化。支持 MySQL / PostgreSQL / Hive / Spark SQL / ClickHouse / BigQuery 多方言。触发...

Security Scan

The skill's code, documentation, and runtime instructions are consistent with a SQL-focused assistant that can generate SQL, connect to databases, load local files, and produce visualizations — nothing in the provided materials indicates deliberate misdirection, but you should review dependencies and avoid giving high‑privilege credentials to untrusted code.

Purpose & Capability

Name/description, SKILL.md, and included scripts (database_connector.py, file_connector.py, pipeline modules and many SQL reference docs) align: the skill implements SQL generation/diagnosis, local file loading, DB connectors and pipeline orchestration for visualization/reporting. The declared capabilities reasonably explain the included files.

Instruction Scope

Runtime instructions focus on installing Python dependencies and using the provided pipeline and connectors. They explicitly enable reading local files (CSV/Excel/SQLite) and connecting to databases when the user supplies connection parameters. The SKILL.md does not instruct the agent to read unrelated system config or to transmit data to unknown external endpoints. Note: the documentation expects the user/agent to provide DB credentials at call time (via function args), so credential handling happens at runtime and is not declared as environment requirements.

Install Mechanism

No formal install spec was declared in the metadata, but SKILL.md tells users to run 'skillhub_install install_skill sql-master' or 'pip install -r requirements.txt'. The code bundle includes a requirements.txt (contents not shown). This is a common pattern; risk is the usual pip dependency risk (third‑party packages may be pulled). There are no obvious download-from-URL or archive-extract instructions in the provided materials.

Credentials

The registry metadata does not request environment variables or credentials. The skill requires credentials only when the user chooses to connect to a DB (credentials are provided as function parameters in examples). This is proportionate to its purpose. Users should avoid supplying production/high-privilege credentials to untrusted skills.

Persistence & Privilege

The skill does not request always:true, does not declare privileged persistence, and does not attempt to modify other skills/configs in the provided docs. It runs as an optional skill and expects explicit invocation or user-supplied actions.

Assessment

This skill appears to do what it says: generate and optimize SQL, connect to databases, load local files, and build charts/reports. Before installing: (1) Inspect requirements.txt to see which Python packages will be installed and whether any network-capable packages are included; (2) Prefer running installation inside an isolated virtualenv/container; (3) Never paste high-privilege production credentials into examples — create a read-only or limited user for testing; (4) If you plan to allow the skill to connect to databases or local files, review the scripts (database_connector.py, file_connector.py, unified_pipeline.py) for any unexpected network calls or uploads; (5) Because the package owner is unknown and there is no formal install spec in the registry metadata, exercise standard caution (sandbox install, review third-party dependencies). If you can share the requirements.txt and the full content of the connector scripts, I can re-check for network endpoints, hard-coded secrets, or suspicious behavior and raise the confidence of this assessment.

SQL Master — SQL 查询、数据获取智能体

⚠️ 使用前必读

本 Skill 需要 Python 依赖。首次使用前必须安装依赖：

skillhub_install install_skill sql-master

工具会自动检测 Python3 环境、pip 可用性，并安装所有依赖。

依赖安装方式

方式	命令	适用场景
自动安装（推荐）	skillhub_install install_skill sql-master	一键安装，自动处理
手动安装	pip install -r requirements.txt	熟悉 Python 环境的用户

无依赖使用（受限模式）

如果无法安装依赖，本 Skill 提供以下降级能力：

✅ 可用功能：

• SQL 语句生成（纯文本输出，无需执行）
• SQL 诊断与优化建议（基于文本分析）
• 索引设计建议（基于规则引擎）
• SQL 原理解释与科普
• 执行计划分析（用户提供 EXPLAIN 结果）

❌ 不可用功能：

• 数据库连接与 SQL 执行
• 数据 Pipeline 处理
• 本地文件数据获取（CSV/Excel 等）
• 与 sql-dataviz / sql-report-generator 联动

---

🔗 Skill 协作关系

本 Skill 与 sql-dataviz、sql-report-generator 组成完整的数据分析流水线：

┌─────────────┐     ┌──────────────┐     ┌────────────────────────┐
│ sql-master  │ ──► │ sql-dataviz  │ ──► │ sql-report-generator   │
│  (数据层)   │     │  (可视化层)  │     │  (报告层)              │
└─────────────┘     └──────────────┘     └────────────────────────┘
      │                   │                   │
      ▼                   ▼                   ▼
   SQL 查询           图表生成            HTML 报告
   数据获取           PNG/HTML            AI 洞察
   格式转换           Dashboard           数据表格

协作模式

模式	组合	适用场景
单独使用	sql-master	仅需 SQL 查询/生成/优化
可视化	sql-master + sql-dataviz	SQL 查询 → 图表输出
完整流程	sql-master + sql-dataviz + sql-report-generator	完整数据分析报告

🥇 最优使用方式：三 Skill 串联

from scripts.unified_pipeline import UnifiedPipeline

result = (
    UnifiedPipeline("销售分析")
    .from_file("sales.csv")                                    # sql-master: 数据获取
    .query("SELECT region, SUM(sales) as total FROM data GROUP BY region")
    .interactive_chart("bar", x_col="region", y_col="total")   # sql-dataviz: 可视化
    .insights(value_cols=["total"])                            # AI 洞察
    .report(title="销售报告", output="report.html")            # sql-report-generator: 报告
)

决策指南

你需要什么？
├─ 仅 SQL 查询/优化 → sql-master 单独使用
├─ SQL + 图表 → sql-master + sql-dataviz
├─ 图表 + 报告（无 SQL）→ sql-dataviz + sql-report-generator
└─ 完整分析报告 → sql-master + sql-dataviz + sql-report-generator ✅ 推荐

---

新增功能：统一 Pipeline 编排（三 Skill 端到端）

scripts/unified_pipeline.py

打通 sql-master → sql-dataviz → sql-report-generator 的端到端自动化：

from scripts.unified_pipeline import UnifiedPipeline, analyze_file

# 完整 Pipeline
result = (
    UnifiedPipeline("销售分析")
    .from_file("sales.csv")                        # 数据源
    .query("SELECT region, SUM(sales) as total FROM data GROUP BY region")  # SQL
    .interactive_chart("bar", x_col="region", y_col="total", title="区域销售")  # 交互图
    .chart("line", x_col="region", y_col="total")              # 静态图 (PNG)
    .insights(value_cols=["total"])                            # AI 洞察
    .report(title="销售报告", output="report.html")           # 完整报告
)
print(result.log())

# 一键分析
result = analyze_file("sales.csv", output="report.html")

支持的图表：静态 PNG（60种）+ 交互式 HTML（12种） 支持的洞察：异常检测 / 趋势 / 相关性 / TOP N / 分布 / 季节性 / 对比 支持的报告：完整 HTML（图表 + 洞察 + 数据表格 + KPI 卡片）

新增功能：数据库连接执行层 + 数据 Pipeline

1. 数据库连接（scripts/database_connector.py）

支持 SQLite / MySQL / PostgreSQL / SQL Server / ClickHouse / Oracle

from scripts.database_connector import connect_sqlite, connect_mysql, connect_postgresql

# SQLite（本地文件）
conn = connect_sqlite("data/sales.db")
result = conn.execute("SELECT region, SUM(amount) FROM sales GROUP BY region")
print(result.df)           # DataFrame 访问
print(result.to_dict())   # dict 访问
result.to_csv("output.csv")  # 导出 CSV
result.to_json("output.json") # 导出 JSON

# MySQL
conn = connect_mysql(host="localhost", port=3306, username="root", password="xxx", database="mydb")
result = conn.execute("SELECT * FROM orders WHERE date >= '2024-01-01'")
print(result.summary())   # 可读摘要

# PostgreSQL
conn = connect_postgresql(host="localhost", database="mydb", username="postgres", password="xxx")
tables = conn.get_tables()  # 获取所有表名
schema = conn.get_schema("orders")  # 获取表结构
conn.close()

2. 本地文件数据获取（scripts/file_connector.py）

支持 CSV / Excel / JSON / Parquet / SQLite 等所有主流格式，自动 SQL 查询 + 格式转换

from scripts.file_connector import load_file, load_directory

# 加载本地文件
fc = load_file("data/sales.csv")        # 单个文件
fc = load_directory("data/reports/")     # 目录下所有文件
fc = load_file("data/*.csv")            # 通配符匹配

print(fc.shape)           # (10000, 12)
print(fc.columns)         # ['date', 'region', 'amount', ...]
print(fc.df.head())       # DataFrame

# 用途一：SQL 查询（自动建 SQLite 内存表）
result = fc.query("SELECT region, SUM(amount) as total FROM data GROUP BY region ORDER BY total DESC")

# 用途二：格式转换
fc.to_csv("output/sales_report.csv")
fc.to_excel("output/sales_report.xlsx")
fc.to_json("output/sales_report.json")
fc.to_parquet("output/sales_report.parquet")
fc.to_sqlite("output/sales.db", table_name="sales")

# 用途三：传给 sql-dataviz 画图
b64 = fc.to_dataviz("line", x_col="month", y_col="sales", title="月度销售趋势")

3. SQL Pipeline 流水线（scripts/pipeline.py）

三大用途一气呵成：数据获取 → SQL 查询 → 格式转换 → 可视化 → HTML 报告

from scripts.pipeline import SQLPipeline

# 方式一：从文件开始
p = (
    SQLPipeline()
    .from_file("data/sales.csv")
    .query("SELECT region, SUM(amount) as total FROM data GROUP BY region")
    .to_csv("output/regional_sales.csv")
    .to_excel("output/regional_sales.xlsx")
)

# 方式二：从数据库开始
p = SQLPipeline().from_db(dialect="sqlite", database="data.db")
p.query("SELECT * FROM sales WHERE amount > 1000")
p.query("SELECT region, COUNT(*) FROM data GROUP BY region")

# 方式三：从 DataFrame 开始
import pandas as pd
df = pd.read_csv("data.csv")
p = SQLPipeline().from_dataframe(df)

# 管道操作
p.query("SELECT region, SUM(amount) as total FROM data GROUP BY region")
p.transform(lambda df: df[df["total"] > 1000])  # 过滤
p.to_dataviz("bar", x_col="region", y_col="total", title="区域销售排行")
p.to_report(title="销售分析报告", output="output/report.html")
p.log()   # 打印执行日志

Pipeline 完整流程示例：

(
    SQLPipeline()
    .from_file("sales_2024.csv")                        # 加载数据
    .query("SELECT * FROM data WHERE region = '华东'")  # SQL 筛选
    .to_csv("output/east_sales.csv")                   # 导出 CSV
    .to_json("output/east_sales.json")                 # 导出 JSON
    .to_dataviz("line", x_col="month", y_col="sales") # 生成折线图
    .to_dataviz("pie", x_col="product", y_col="amount") # 生成饼图
    .to_report(title="华东区域销售报告", output="output/report.html")  # HTML 报告
)

核心原则

生产级标准：所有输出的 SQL 必须满足：

• 注释完整（业务背景 + 性能预期 + 适用数据量级）
• 明确标注数据库版本和方言
• 主动提示 NULL 处理、空集合、边界条件
• 给出多方案时说明各自 trade-off

分层回答：同一问题，先给结论，再给原理，最后给深入扩展。自动识别用户水平（初学者/开发者/DBA），调整解释深度。

可复现：生成的 SQL 必须附带最小可复现测试数据（DDL + INSERT），确保用户能直接验证。

---

功能模块导航

场景	参考文件
自然语言 → SQL 生成	references/sql-generation.md
慢查询诊断 & 执行计划分析	references/query-optimization.md
索引设计策略	references/index-design.md
数仓建模 & 分层架构	references/data-warehouse.md
Hive 数据倾斜深度（引擎原理/量化模型/极端场景）	references/hive-skew-advanced.md
SQL 原理深度（事务/锁/MVCC/Join）	references/sql-internals.md
多方言差异速查	references/dialect-guide.md
DDL 设计规范	references/ddl-design.md
SQL 安全规范（注入防护/参数化查询）	references/sql-security.md
CLI 实操速查（sqlite3/psql/mysql 连接与导入导出）	references/cli-quickref.md
查询结果可视化（图表选型/Python 代码/设计原则）	references/visualization-guide.md

---

工作流程

1. 意图识别

收到请求后，先判断属于哪个场景：

• 生成类：用户描述业务需求，需要输出 SQL
• 优化类：用户提供现有 SQL 或 EXPLAIN，需要诊断和改写
• 设计类：表结构、索引、数仓架构设计
• 科普类：原理解释、概念问答
• 诊断类：报错信息分析
• 可视化类：将查询结果转化为图表 → 加载 references/visualization-guide.md

2. 上下文收集

生成或优化 SQL 前，主动确认（如未提供）：

• 数据库类型和版本
• 关键表的 schema（列名、类型、索引）
• 数据量级（行数、数据大小）
• 查询频率和性能目标（P99 < Xms？）

3. 输出规范

SQL 输出模板：

-- ============================================================
-- 业务说明：[描述这段 SQL 解决什么业务问题]
-- 数据库：MySQL 8.0 / PostgreSQL 15 / ...
-- 性能预期：[预计执行时间，适用数据量级]
-- 注意事项：[NULL 处理、边界条件、已知限制]
-- ============================================================

SELECT ...
FROM ...
WHERE ...

优化报告模板：

## 问题诊断
[执行计划中发现的问题，按严重程度排序]

## 优化方案
### 方案 A（推荐）
[改写后的 SQL + 原因]

### 方案 B（备选）
[另一种思路 + 适用场景]

## 预期收益
[优化前 vs 优化后的性能对比估算]

## 可复现测试
[最小 DDL + 数据 + 验证步骤]

4. 加载参考文件

根据意图识别结果，读取对应的 references/ 文件获取详细指导。

---

快速参考

常见性能陷阱（立即识别）

• SELECT * → 明确列名，避免回表
• WHERE 列上有函数 → 索引失效
• OR 连接不同列 → 考虑 UNION ALL
• != / NOT IN → 无法走索引
• 隐式类型转换 → 索引失效
• LIMIT 大偏移量 → 延迟关联优化
• COUNT(*) vs COUNT(col) → NULL 语义差异

Join 算法选择直觉

• 小表 JOIN 大表 → Nested Loop（小表驱动）
• 两个大表等值 JOIN → Hash Join
• 有序数据等值 JOIN → Merge Join
• 数据倾斜 → 广播小表 / 加盐打散

索引设计口诀

最左前缀、区分度高、覆盖查询、避免冗余

---

强制规范（MUST DO / MUST NOT）

借鉴 sql-pro 的约束清单，以下规则在任何情况下都必须遵守：

✅ MUST DO

• 优化前必须先分析执行计划（EXPLAIN / EXPLAIN ANALYZE）
• 优先使用集合操作，避免逐行处理（游标/循环）
• 尽早过滤：WHERE 条件尽量前置，减少中间结果集
• 存在性检查用 EXISTS，不用 COUNT(*) > 0
• 显式处理 NULL：IS NULL / IS NOT NULL / COALESCE / NULLIF
• 为高频查询创建覆盖索引
• 涉及安全场景时，必须使用参数化查询，详见 references/sql-security.md
• 跨数据库迁移时，必须标注方言差异，详见 references/dialect-guide.md

❌ MUST NOT

• 不在 WHERE / JOIN 条件列上使用函数（导致索引失效）
• 不用 SELECT *（回表开销 + 隐式依赖）
• 不用字符串拼接构造 SQL（SQL 注入风险）
• 不在大表上做无索引的全表扫描
• 不用 OFFSET 大偏移量分页（改用游标/keyset 分页）
• 不忽略隐式类型转换（导致索引失效 + 数据截断）
• 不在生产环境直接运行未经 EXPLAIN 验证的复杂查询