1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | query-starrocks-starrocks-debug-skills |
| 作者/维护者 | StarRocks（Linux Foundation 旗下开源 OLAP 数据库项目官方团队） |
| 来源链接 | https://github.com/StarRocks/starrocks-debug-skills/tree/main/query |
| 许可证 | Apache License 2.0（GitHub API 确认） |
| GitHub Stars | 仓库整体 72（GitHub API；本技能为合集仓库中的独立子技能，此数字为仓库整体热度参考，非本模块单独热度，详见“评分”一节说明） |
| Forks | 12（GitHub API） |
| 最新版本 | SKILL.md 内声明 version 2.0.0；仓库最近一次提交 2026-05-26（GitHub API） |
| 安装方式 | 官方 install.sh 一键安装（全部模块），或手动复制 query/ 目录 |
2. 功能介绍与亮点
query 是一份专注于 StarRocks 查询性能与正确性故障的调查手册，覆盖查询挂起、慢查询、结果错误三类问题，把根因归纳为五种：网络/连接层问题、FE 锁竞争或 GC 停顿、扫描瓶颈（数据倾斜、rowset 堆积）、Join 瓶颈（广播 Join 内存溢出）、结果错误的 Bug 定位。
内容按四阶段组织：先判断问题大类，再读取查询 Profile 定位瓶颈算子，然后按根因给出确认信号与修复命令（强制 Shuffle Join、重新设计分桶键、ANALYZE TABLE 补统计、Session 变量二分排除法定位 Bug），最后给出恢复验证步骤。附带 5 条完整因果链推导范例、一个可直接运行的日志分析脚本 analyze_logs.py，以及 3 个可追溯编号的真实生产案例。
主要亮点：官方团队出品并配发工程博客文章；文档明确标注为“查询性能问题的入口”；开源、Apache-2.0、无付费依赖；仓库设有 CI lint 工作流校验内容格式。
3. 适用场景
所属分类：工程效率与代码质量
面向负责 StarRocks 数据库开发与调优的工程师、DBA，在业务查询挂起、耗时异常升高、或返回结果与预期不符时，按判定树定位根因并采取修复措施，属诊断查询性能问题并给出修复方案的调试类工作。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——仓库提供
install.sh --tool claude-code --target ~/.claude/skills/官方安装命令 - Codex：❓ 未验证——官方安装脚本未列 Codex 为目标平台
- OpenClaw：❓ 未验证——官方材料未提及
- Hermes Agent：❓ 未验证——官方材料未提及
（官方脚本另支持 Cursor 与 JetBrains IDE，不在本报告追踪范围内。）
5. 推荐理由
官方 StarRocks 团队把分散的查询性能排障经验系统化为结构化调查手册，覆盖从网络层到执行器层的完整根因谱系并配发可运行的日志分析脚本，专门覆盖“查询本身出问题”这一最高频场景，同类数据库诊断技能中少见。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 官方 StarRocks（Linux Foundation 旗下项目）团队出品，配发专门工程博客文章；但仓库创建于 2026 年 4 月，尚属年轻项目，子技能级别独立热度证据有限 |
| 可用性 | 8 | 提供清晰四阶段判定树、5 条因果链推导范例，附带可运行的日志分析脚本与 3 个可追溯案例；但需要用户对目标集群具备访问权限、能读取 Profile，非纯粹复制即用 |
| 安全性 | 9 | 检查清单见下 |
安全检查清单：
① shell 命令权限范围：均为只读诊断（jstack、netstat、grep 读日志、curl 访问 BE 本地监控端口）或标准数据库运维操作（KILL QUERY、ANALYZE TABLE、ALTER TABLE、SET 会话变量），均需用户自身具备对应集群权限，未见绕权限或破坏性操作
② 联网外发：无，全部诊断在用户自有集群本地执行
③ API key/凭据：不涉及
④ 可疑指令：未发现提示词注入迹象；仓库设有 CI 关键词过滤工作流
⑤ 作者/组织信誉：StarRocks 官方项目团队，与主数据库仓库同属一个 GitHub 组织
⑥ License：明确，Apache License 2.0
⑦ 最近维护：最近一次提交 2026-05-26，距今约两个月，未见 archived 标记
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| query-starrocks-starrocks-debug-skills | StarRocks 查询挂起/慢查询/结果错误的根因诊断与修复 | — |
| mongodb-query-optimizer（MongoDB 官方） | 诊断 MongoDB 慢查询并给出复合索引建议 | 聚焦索引层面的查询优化建议，不覆盖 Join 内存溢出、FE 锁竞争、TCP 连接层等分布式 OLAP 架构特有的故障场景 |
| clickhouse-best-practices（ClickHouse 官方） | ClickHouse 建表、查询编写、集群配置的综合最佳实践指南 | 是覆盖面更广的通用最佳实践参考，慢查询只是其中一个话题，不提供本技能这类按症状分流的结构化根因判定树 |
| node-starrocks-starrocks-debug-skills（同仓库姊妹技能） | StarRocks 服务进程级故障（OOM/崩溃/死锁/GC）排查 | 聚焦“数据库服务本身宕机”这一基础设施运维场景，与本技能聚焦“查询本身执行异常”是同一数据库不同层面的问题域，两者互补但不重叠 |
同类数据库诊断技能要么聚焦索引/建表类通用优化建议，要么是覆盖面很广的最佳实践合集，本技能差异化在于针对“查询挂起/变慢/结果错误”具体故障场景，提供从网络层到执行器层的完整分层判定树。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。StarRocks 官方工程博客（Towards Data Engineering，Medium，2026 年 5 月）介绍了整套调查手册系统的诞生背景，文中未单独展开 query 模块案例，但列为覆盖的 12 个技能领域之一；官方同期在 X（Twitter）发布公告介绍该项目。
9. 其他补充
同仓库还有其他姊妹模块，分别覆盖节点故障、数据导入、Compaction、集群均衡、数据湖外表、物化视图、Tablet 健康、部署启动等不同症状域，构成一套完整的 StarRocks 故障排查体系；guides/ 目录下还有跨模块级联案例，把多个模块的判定树串联处理复合型故障。
10. 安装使用方式
方式一（官方脚本，一次安装全部模块）：
git clone https://github.com/StarRocks/starrocks-debug-skills
cd starrocks-debug-skills
./scripts/install.sh --tool claude-code --target ~/.claude/skills/方式二（仅安装本模块）：手动将仓库内 query/ 目录（含 SKILL.md、references/ 与 scripts/analyze_logs.py）复制到 ~/.claude/skills/query/。
安装后注意事项：Claude Code 重启会话后自动加载新技能，按 description 字段中的症状关键词自动匹配触发，无需手动调用；执行诊断命令需要用户对目标集群具备 SQL 访问权限或 FE/BE 日志、监控端口访问权限。
11. 注意事项
- 仓库创建于 2026 年 4 月，最近一次实质性提交在 2026 年 5 月，属早期项目
- 部分修复动作（如在线重新分桶）需 StarRocks 3.3 及以上版本，低版本需改用文档中的替代方案
- 官方一键安装脚本会同时装全部模块，没有“仅装单个模块”的参数，需手动筛选目录
- 仅覆盖 StarRocks 这一特定数据库的内部机制，不适用于其他数据库系统