慢查询诊断师
本技能封装了 slow_query_analyzer——一个支持 MySQL 与 Oracle 的慢查询日志分析工具。
用户输入慢查询日志文件，技能自动解析、诊断 SQL 问题、给出索引建议，并生成可在浏览器打开的交互式 HTML 报告。
可选连接数据库做索引验证 / EXPLAIN，或调用 AI（Claude / OpenAI）做智能诊断，或接入 CI/CD 流水线做门禁检查。
何时使用
当用户出现以下意图时，立即调用本技能：
- 用户提供慢查询日志文件，或说「分析慢查询」「帮我看看这个慢日志」
- 用户提到「慢 SQL 优化」「索引建议」「EXPLAIN 分析」「数据库性能诊断」
- 用户提到 slow query / slow log / MySQL tuning / index advisor
- 用户希望在 CI 流程里对 SQL 做门禁检查（命中阈值即非零退出）
使用方式
步骤 0：定位技能脚本与准备环境
技能代码位于：<skill_root>/slow-query-doctor/scripts/slow_query_analyzer/
（<skill_root> 为本技能的安装根目录；使用其中的 main.py 作为入口。）
首次使用需安装依赖（在 Bash 中执行）：
python -m pip install -r <skill_root>/slow-query-doctor/scripts/slow_query_analyzer/requirements.txt
- 基础分析只需
pymysql+jinja2； - 启用 AI 诊断需
openai或anthropic；启用 REST API 需fastapi+uvicorn；邮件报告需requests。
如需连接数据库做索引验证 / EXPLAIN，复制配置模板并填写：
cp <skill_root>/slow-query-doctor/scripts/slow_query_analyzer/config.template.ini \
<skill_root>/slow-query-doctor/scripts/slow_query_analyzer/config.ini
# 然后编辑 config.ini 填写 [database] 段的主机 / 端口 / 账号 / 库名
步骤 1：基础分析并生成 HTML 报告（最常用）
python <skill_root>/slow-query-doctor/scripts/slow_query_analyzer/main.py \
-f <用户提供的慢日志路径> -o <输出报告路径>.html
- 工具会自动检测日志是 MySQL 还是 Oracle 格式（
--db-type mysql|oracle|auto，默认 auto）。 - 报告生成后，用
present_files把.html打开给用户查看。
步骤 2：进阶分析（按需组合）
- 连库验证索引 + EXPLAIN 执行计划：
bash
python <skill_root>/slow-query-doctor/scripts/slow_query_analyzer/main.py \
-f <log> --verify-index --explain \
--db-host <host> --db-port 3306 --db-user <user> --db-pass <pw> --db-name <db>
- AI 智能诊断（需先在 config.ini 的
[ai]配好 api_key，或用--ai-api-key）：
bash
python <skill_root>/slow-query-doctor/scripts/slow_query_analyzer/main.py \
-f <log> --ai-analyze --ai-provider claude --repo-path <代码仓库路径>
- CI/CD 门禁（输出 JSON，命中阈值则 exit code = 1）：
bash
python <skill_root>/slow-query-doctor/scripts/slow_query_analyzer/main.py \
-f <log> --ci --fail-on MEDIUM --json-output result.json
- 启动 REST API 服务（FastAPI，自带
/docs交互文档）：
bash
python <skill_root>/slow-query-doctor/scripts/slow_query_analyzer/main.py --serve --port 8000
步骤 3：交付结果
把生成的 HTML 报告（及可选的 *_ai.html、result.json）通过 present_files 呈现给用户，并口头总结：
- 最慢的 N 条 SQL 及其耗时；
- 主要问题类型（全表扫描 / 缺失索引 / 锁等待 / 临时表等）；
- 索引建议条数，以及是否经过数据库实体验证。
注意事项
- 不要打包或读取含真实密码的
config.ini；只用config.template.ini作为模板。 - AI 分析涉及外部 API 调用与密钥，确认用户已授权后再启用；密钥优先走 config.ini 或环境变量，避免明文出现在命令参数里被记录。
- 详细 CLI 参数、配置字段、AI 接入与排错，见
@references/usage.md。
