前言¶
寫 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
