doris-debug-apache-doris-skills

1. 基本信息

项目	内容	数据来源
名称	doris-debug-apache-doris-skills	—
项目自述名称	Doris Debug Router（SKILL.md 自身标题）	SKILL.md 实测
作者/维护者	Apache Software Foundation（Apache Doris 项目组，官方 GitHub 组织账号 apache）	GitHub API 实测
来源链接	https://github.com/apache/doris-skills/tree/main/skills/doris-debug	—
许可证	Apache-2.0	GitHub API 实测
GitHub Stars / Forks	24 / 6（`apache/doris-skills` 仓库整体口径；该仓库是 Apache Doris 官方配套技能仓库，共含 3 个技能，数字不代表本技能独立热度）	GitHub API 实测（2026-08-04）
最新版本	0.3.0（SKILL.md 自身 metadata 字段）	SKILL.md 实测
安装方式	`npx skills add apache/doris-skills`，或手动 `cp -r skills/doris-debug ~/.claude/skills/`	官方 README 实测

2. 功能介绍与亮点

一个面向 Apache Doris（列式 OLAP 分析数据库）生产环境的故障诊断路由器：把慢查询、导入失败、Compaction 报 -235 错误、节点 OOM/崩溃、物化视图不改写、副本/Tablet 异常等 10 类常见症状，逐一路由到对应的领域子技能与决策树。

症状优先路由：正文开篇即是“症状 → 子技能”对照表，覆盖查询、导入、Compaction、节点、物化视图、Tablet、部署、数据湖联邦查询、资源隔离、存算分离云模式共 10 个诊断域
可追溯到源码：shared/references/02-source-map.md 把症状直接映射到 Apache Doris 源码位置，并标注版本适用范围，而非停留在“猜可能是哪里出问题”
45 个真实生产案例：shared/references/03-case-index.md 收录 45 条已归档的生产故障案例，诊断时可直接比对症状模式
不依赖专用工具即可用：诊断命令默认走标准 MySQL 协议 SQL 与 FE HTTP API；可选配套官方 CLI 工具 doriscli 获得结构化 JSON 输出，未安装时自动降级不影响使用
可验证：与姊妹技能共享同一套三层回归测试（对照真实集群校验 DDL/诊断结论、校验命令行工具契约、端到端行为测试），内容持续跑测而非纸面文档

3. 适用场景

固定分类：DevOps 与基础设施

Apache Doris 生产环境出现慢查询、导入失败或超时、Compaction 报错、节点 OOM/崩溃、Tablet 副本异常等故障时，需要快速定位根因并给出修复路径的数据库运维、SRE 与值班工程师；尤其适合面对陌生症状、缺乏 Doris 源码级排障经验的团队。

4. 跨 Agent 兼容性

Claude Code：原生支持——README 提供 npx skills add 命令与手动复制到 ~/.claude/skills/ 两种路径
Codex：原生支持——README 明确将 skills CLI 描述为“适用于 Claude Code、Cursor、Codex、Cline、Amp 等 agent 工具”，点名列出 Codex
OpenClaw：未验证——抓取材料未提及
Hermes Agent：未验证——抓取材料未提及

5. 推荐理由

生产环境数据库故障往往留给工程师的排查窗口很短，而 Apache Doris 官方把内部积累的 45 个真实故障案例与源码级症状映射编码成一份可被 agent 直接调用的诊断路由器——不用先啃透 Doris 内核就能把“慢查询/导入失败/节点崩溃”这类症状快速收敛到对应的原因表和处置步骤，比让 agent 凭通用数据库排障直觉临场发挥更可靠，对刚接手 Doris 集群运维的团队帮助尤其明显。

6. 评分

维度	分数	说明
受欢迎程度	7	Apache 官方组织出品，但配套技能仓库整体规模不大（24 stars/6 forks），未见独立第三方讨论；与同仓库姊妹技能 doris-best-practices 的官方但星数中等定级保持一致
可用性	8	一条命令或手动复制即可用；参考文档结构清晰、覆盖 10 个诊断域；仓库最近一次提交距今约 10 天，维护活跃；无需付费账号；诊断命令默认走标准 SQL/HTTP，`doriscli` 为可选增强而非必需
安全性	9	见下方安全检查清单
综合	8.67	三项均值

安全检查清单：

检查项	结果
① Shell 命令执行	参考文档给出的诊断命令以只读 SQL（`SHOW`/`ADMIN SHOW` 等）与只读 HTTP API 为主，另有个别范围明确的运维操作（如重置 RPC 通道），均需用户在自己的数据库客户端执行，技能本身不含自动执行的脚本
② 联网外发	无默认外联；技能不会自行连接任何网络服务，诊断均针对用户自己的集群
③ API key/凭据	不涉及任何凭据；读取集群状态走用户自己配置的数据库连接，技能本身不存储或索取密钥
④ 可疑指令	SKILL.md 与全部参考文档中未发现要求执行特权操作或数据外发的可疑指令
⑤ 作者信誉	Apache Software Foundation 官方组织账号，全部改动经 PR 流程合入
⑥ License	Apache-2.0，明确
⑦ 维护时间	仓库最近一次提交距报告发布约 10 天，活跃维护

7. 跟同类 Skills 相比的优势

同为“数据库厂商官方生产诊断/排障”类型的技能，与本技能的定位差异：

技能	厂商	覆盖范围	是否需付费账号	独有特点
Doris Debug Router（本次推荐）	Apache Doris	10 个诊断域、45 个生产案例、症状直连源码位置	否，开源自建即可用	唯一把“症状 → 子技能 → 源码位置 → 案例库”串成一条可执行诊断链路的同类技能
Redis Observability	Redis 官方	Redis 集群可观测性与告警配置	否	面向缓存/内存数据库，聚焦持续监控而非事后症状路由
K8s Investigation	Elastic	Kubernetes 集群故障排查	否	面向容器编排层，不涉及具体数据库内核症状
同仓库姊妹技能 doris-best-practices / doris-architecture-advisor	Apache Doris	分别聚焦建表调优、架构选型	否	与本技能互补而非竞争，三者合起来覆盖“选型-建表-排障”全链路

核心差异化：在同类“数据库生产诊断”技能里，本技能是目前唯一同时具备症状路由表 + 源码级映射 + 案例库三层结构、且全套内容持续跑真实集群回归测试的一款。

8. 用户评价

该技能目前在第三方平台尚无具名用户评价：仓库内该子技能新增仅约 10 天，公开渠道未见独立博客、论坛或社交媒体讨论。

9. 其他补充

仓库同时含 doris-best-practices（建表调优规则库）、doris-architecture-advisor（架构选型，8 条决策规则+10 个行业案例）两个姊妹技能，可按需单独安装。本技能可选搭配官方 CLI 工具 doriscli（npm install -g @apache-doris/doriscli）获得结构化 JSON 诊断输出，未安装时会自动回退到标准 MySQL 协议 SQL + FE HTTP API，不影响核心诊断路由功能。

10. 安装使用方式

推荐方式：npx skills add apache/doris-skills（会自动发现仓库内全部技能并一并打包其 references/ 目录）
手动方式：克隆仓库后执行 cp -r skills/doris-debug ~/.claude/skills/
安装后无需重启；agent 在诊断慢查询、导入失败、Compaction 报错、节点崩溃、Tablet 异常等场景时会按 SKILL.md 的症状路由表自动触发
如需结构化诊断真实集群（读取 profile、tablet 分布的 JSON 输出），可额外安装 doriscli 命令行工具

11. 注意事项

技能面向 Apache Doris 通用生产诊断设计，正文明确不涉及托管服务的集群生命周期、计费、网络等运维操作，这类操作需使用对应平台自己的管理控制台
本技能是仓库 apache/doris-skills 中的一个子目录，仓库同时含另外 2 个技能，只需生产故障诊断时装本子目录即可
Codex 之外的 OpenClaw、Hermes Agent 兼容性未获官方明确声明，跨 agent 使用前建议自行验证 SKILL.md 能否被目标 agent 正确加载
结构化诊断真实集群的 profile/tablet 信息需额外安装 doriscli 或自行配置数据库连接，症状路由与决策树本身不需要