前言¶
写 SQL、调慢查询、补索引、画数仓分层，往往要翻文档、贴 EXPLAIN、再在本地跑一遍验证。通用对话模型能生成语句，但对方言差异、执行计划与可复现测试数据常常一笔带过。下面介绍 SkillHub 上的 SQL Master：用标准 SKILL.md 把生成、优化、建模、原理说明和（可选的）数据执行串成一条工作流，让 Agent 按场景加载参考文档并遵守统一输出规范。
这是什么¶
SQL Master（包名 sql-master）是 SkillHub 上的数据分析类 Skill，维护标识为 @indiv-yaoyao/sql-master。官方条目：https://api.skillhub.cn/user_64e5b706/sql-master；社区页：https://skillhub.cn/skills/sql-master。
定位是「SQL 查询、数据获取智能体」：自然语言转生产级 SQL，慢查询与执行计划分析，索引与数仓建模，SQL 原理讲解，以及查询结果可视化。支持多方言，包括 MySQL、PostgreSQL、Hive、Spark SQL、ClickHouse、BigQuery。SkillHub 页面标注分类为数据分析，当前展示版本为 v1.0.0。
核心功能¶
以下能力均来自 SkillHub / 360 安全技能中心公开的 Skill 说明。
意图与参考文档¶
收到请求后，Skill 要求先判断场景：生成、优化、设计（表结构/索引/数仓）、科普、报错诊断、可视化等，再按需读取 references/ 下的专题文件，例如：
| 场景 | 参考文件 |
|---|---|
| 自然语言 → SQL | references/sql-generation.md |
| 慢查询与执行计划 | references/query-optimization.md |
| 索引设计 | references/index-design.md |
| 数仓建模 | references/data-warehouse.md |
| SQL 原理（事务/锁/MVCC/Join 等） | references/sql-internals.md |
| 多方言差异 | references/dialect-guide.md |
| DDL 与安全（注入防护等） | references/ddl-design.md、references/sql-security.md |
输出与工程约束¶
Skill 内置「生产级」输出要求：SQL 需带业务说明、数据库方言与版本、性能预期与边界说明；优化类问题按诊断 → 多方案（含 trade-off）→ 预期收益 → 可复现 DDL/数据 的结构回答。并列出 MUST DO / MUST NOT（例如优化前先看 EXPLAIN、禁止字符串拼接 SQL、避免大偏移 OFFSET 分页等）。
Python 脚本（需安装依赖）¶
安装 Python 依赖后，可使用附带的连接器与流水线（文档中的模块名如下）：
scripts/database_connector.py：连接 SQLite、MySQL、PostgreSQL、SQL Server、ClickHouse、Oracle，执行查询并导出结果。scripts/file_connector.py：读取 CSV、Excel、JSON、Parquet 等，在内存表上跑 SQL，或做格式转换。scripts/pipeline.py：从文件、数据库或 DataFrame 起步的SQLPipeline链式查询与导出。scripts/unified_pipeline.py：与sql-dataviz、sql-report-generator串联的端到端分析（可选组合）。
未安装依赖时进入「受限模式」：仍可生成 SQL、基于文本做优化与索引建议、解读用户提供的 EXPLAIN；不能连库执行、不能做本地 CSV/Excel 管道或与可视化/报告 Skill 联动。
安装与启用¶
Skill 基于通用 Agent Skill 格式（SKILL.md）。SkillHub 与 360 技能中心给出的安装方式略有不同，按你使用的入口选择即可。
通过 secure-skills-cli（360 技能中心推荐话术）¶
复制给 Agent 或在本机执行：
npx secure-skills-cli add sql-master
通过 SkillHub 安装指引¶
按 SkillHub 安装文档（https://skillhub.cn/install/skillhub.md），让 Agent 安装：
@indiv-yaoyao/sql-master
社区页提供的提示词为：「请根据 https://skillhub.cn/install/skillhub.md，安装 @indiv-yaoyao/sql-master。」
Python 依赖（完整能力）¶
首次使用需要 Python 3 与 pip。推荐一键安装：
skillhub_install install_skill sql-master
也可在 Skill 目录内手动执行：
pip install -r requirements.txt
Cursor、Codex CLI、Claude Code 等客户端的具体挂载路径以各自对 Skill 目录的约定为准；公开资料未单独区分各客户端差异，统一做法是安装 Skill 包后，在对话中按 Skill 描述触发（写 SQL、优化、EXPLAIN、建索引等）。
典型用法¶
1. 仅生成或优化 SQL（无需连库）¶
在对话中描述业务需求或粘贴慢 SQL / EXPLAIN 输出即可。Agent 会按 Skill 模板输出带注释的 SQL 或优化报告。此路径不依赖 Python 依赖。
2. 连接数据库执行查询¶
安装依赖后，文档示例从 database_connector 导入并按方言连接：
from scripts.database_connector import connect_sqlite, connect_mysql, connect_postgresql
conn = connect_sqlite("data/sales.db")
result = conn.execute("SELECT region, SUM(amount) FROM sales GROUP BY region")
print(result.df)
MySQL、PostgreSQL 等需传入 host、database、用户名密码等参数，用法见 Skill 公开说明中的同类示例。
3. 本地文件 + SQL¶
对 CSV 等文件加载后在内存表上查询：
from scripts.file_connector import load_file
fc = load_file("data/sales.csv")
result = fc.query(
"SELECT region, SUM(amount) as total FROM data GROUP BY region ORDER BY total DESC"
)
4. Pipeline 与三 Skill 串联（可选）¶
需要图表或 HTML 报告时，可组合 sql-dataviz、sql-report-generator。文档示例：
from scripts.unified_pipeline import UnifiedPipeline
result = (
UnifiedPipeline("销售分析")
.from_file("sales.csv")
.query("SELECT region, SUM(sales) as total FROM data GROUP BY region")
.interactive_chart("bar", x_col="region", y_col="total")
.insights(value_cols=["total"])
.report(title="销售报告", output="report.html")
)
print(result.log())
适用场景与注意¶
适合谁
- 需要把「写查询、看计划、改索引、讲原理」交给 Agent 统一处理的开发者或数据分析同学。
- 已在用 SkillHub 生态、并希望与可视化/报告 Skill 衔接的团队。
使用注意
- 完整执行与文件处理能力依赖 Python 环境；受限模式下能力会明显收缩，安装前应阅读 Skill 内「使用前必读」。
- 生成或优化 SQL 前，Skill 要求尽量确认库类型与版本、表结构、数据量级与性能目标；信息不足时结论会偏保守。
- 涉及生产库时，文档强调 EXPLAIN 验证、参数化查询与禁止未审复杂查询直接上线；执行权限与脱敏需自行把控。
- SkillHub 页面显示科恩实验室、云鼎实验室等安全扫描为「安全，无风险」，具体报告以平台链接为准；敏感环境仍建议内网审阅 Skill 脚本后再启用。
结尾¶
SQL Master 把 SQL 全链路任务写成可复用的 Agent 指令与参考文档，并在可选依赖下提供连库与本地文件执行。若你主要做查询生成与调优，可单独启用；若要做图表和 HTML 报告，再按文档串联同系列的 dataviz / report Skill。
官方条目：https://api.skillhub.cn/user_64e5b706/sql-master
社区与安装说明：https://skillhub.cn/skills/sql-master
