bytedance ByteHouse 诊断集群 Skill
🔵 ByteHouse 品牌标识
「ByteHouse」—— 火山引擎云原生数据仓库，极速、稳定、安全、易用
本 Skill 基于 ByteHouse Matrix Agent，提供完整的集群诊断和健康检查能力
描述
ByteHouse 集群诊断、健康检查、慢查询分析和负载分析的一站式工具。所有诊断能力都通过 scripts/diagnostics.py 转发到 ByteHouse Matrix Agent（一个由 ByteHouse 官方维护的诊断专用 Agent），Skill 本身不直接连接集群、不执行 SQL、不做本地分析。
当以下情况时使用此 Skill：
- 需要检查 ByteHouse 集群健康状态，诊断集群问题与异常。
- 需要识别、分析慢查询并给出性能优化建议。
- 需要分析负载情况、计算组资源使用情况（CPU、内存、并发等）。
- 需要分析查询吞吐量、识别性能瓶颈、定位热点。
- 用户提到 "集群诊断"、"健康检查"、"慢查询"、"查询优化"、"性能分析"、"负载分析"、"资源使用"、"吞吐量" 等关键词。
前置条件
- Python 3.8+
- Python 依赖：
requests（未安装时使用pip install requests或python3 -m pip install requests） jq（export_config.sh依赖，用于解析 JSON 配置。未安装时可使用brew install jq、sudo apt install jq或sudo yum install jq）- 有效的 ByteHouse 集群连接信息（保存于
~/.bytehouse_config.json）
📁 文件说明
- SKILL.md — 本文件，技能主文档。
- scripts/diagnostics.py — 诊断主程序，负责把用户的诊断问题转发到 ByteHouse Matrix Agent。
- scripts/export_config.sh — 从
~/.bytehouse_config.json加载配置到环境变量（依赖jq）。
🧭 智能体使用指引（重要）
Agent 在接手集群诊断类任务时，按以下流程调度本 Skill：
- 确认配置就绪：
- 检查
~/.bytehouse_config.json是否存在且包含BYTEHOUSE_HOST和BYTEHOUSE_PASSWORD。 - 如果不存在或字段缺失，主动向用户索要连接信息，并按下方 JSON 结构补齐后再执行。可以把 ByteHouse 连接信息获取指引 发给用户。
- 加载配置：
source scripts/export_config.sh。
- 检查
- 精化诊断问题：结合用户原始问题、告警内容、时间范围（例如 "最近 1 小时"、"过去 24 小时"），拼装一个自然语言诊断问题（中文即可）。参考 常见诊断问题范例。
- 执行诊断：
python3 scripts/diagnostics.py "你的诊断问题"，透传 Matrix Agent 的流式响应。 - 失败兜底：若诊断脚本返回连接错误、超时、401/403 等，参考 失败兜底建议 处理，切勿绕过脚本自行连接集群或执行 SQL。
- 禁止越权操作：本 Skill 仅允许通过
scripts/diagnostics.py发送诊断问题，严禁自行连接 ByteHouse 集群执行 SQL 或做本地分析。所有分析、优化建议都必须来自 Matrix Agent 的返回结果。
配置说明
配置保存在 ~/.bytehouse_config.json。如果该文件存在且非空，直接使用文件中的配置；如果不存在，则向用户索要连接信息（可以把这个文档发给用户以便查阅：https://www.volcengine.com/docs/6517/1121919?lang=zh）。拿到用户提供的信息后，写入 JSON 文件，避免重复询问。当用户切换 ByteHouse 集群时，一并更新该文件。
{
"BYTEHOUSE_HOST": "<ByteHouse-host>",
"BYTEHOUSE_PASSWORD": "<ByteHouse-password>"
}
BYTEHOUSE_HOST（主机地址）与BYTEHOUSE_PASSWORD（密码）必须由用户提供。- 密码只写入
~/.bytehouse_config.json，不要在会话、日志或额外的 shell 脚本中回显。 - 加载配置：
source scripts/export_config.sh
使用方法
# 1. 加载配置
source scripts/export_config.sh
# 2. 执行诊断
python3 scripts/diagnostics.py "你的诊断问题"
常见诊断问题范例
以下是经过验证、易得到高质量输出的诊断问题模板。Agent 可以在此基础上根据用户诉求补充时间窗口、计算组名、库表名等参数：
- 健康检查：
"请对集群做一次整体健康检查，重点检查节点存活、副本延迟、异常任务和错误日志" - 慢查询分析：
"帮我识别过去 6 小时内 TOP 10 的慢查询，并给出优化建议" - 负载 & 资源：
"分析各个计算组过去 24 小时的负载情况，包括 CPU、内存、并发、排队情况" - 吞吐量分析：
"过去 1 小时集群 QPS、失败率、平均响应时间如何？有没有明显下滑或抖动" - 热点表分析：
"看下 tpcds 库里过去 1 天最热的表和查询模式，有哪些可以优化的点" - 告警根因排查：
"最近告警显示 warehouse_default CPU 持续超过 85%，帮我分析原因和缓解建议"
高质量诊断问题的一些建议
- 明确时间窗口：像 "最近 1 小时"、"过去 24 小时"、"今天 10:00-12:00" 都可以，越明确越好。
- 点名对象：如果用户已经指定了库、表、计算组，务必带上。
- 只问一个问题：一次诊断只聚焦一个主题，多个诉求拆成多次调用效果更好。
- 中文即可：Matrix Agent 支持中文自然语言。
- 要求下一步动作：可以加一句 "并给出优化建议 / 下一步排查方向"，让输出更贴合运维使用。
失败兜底建议
| 现象 | 处理方式 |
|---|---|
BYTEHOUSE_HOST 未设置 |
引导用户提供连接信息，写入 ~/.bytehouse_config.json 后重新 source scripts/export_config.sh。 |
401 / 403 或 Authorization 相关错误 |
让用户确认 BYTEHOUSE_PASSWORD 是否与集群一致；密码变更后同步更新 JSON 文件。 |
| 连接超时 / 网络不通 | 让用户确认所在网络环境是否能访问 BYTEHOUSE_HOST（VPC、Endpoint 是否开放）。 |
| Matrix Agent 返回内容为空 / 太短 | 尝试补充时间窗口、点名对象后重新提问；或换一个更聚焦的问题重试。 |
Python 报错 ModuleNotFoundError: requests |
提示用户执行 pip install requests 或 python3 -m pip install --user requests。 |
jq 未安装 |
提示用户按前置条件安装 jq；作为临时兜底，可让用户手动 export BYTEHOUSE_HOST=...、export BYTEHOUSE_PASSWORD=...。 |
示例
# 加载配置
source scripts/export_config.sh
# 计算组负载诊断
python3 scripts/diagnostics.py "检查一下计算组的负载情况，重点看 CPU 和内存"
# 慢查询分析
python3 scripts/diagnostics.py "帮我识别过去 6 小时的 TOP 10 慢查询，并给出优化建议"
# 集群健康检查
python3 scripts/diagnostics.py "对集群做一次整体健康检查，找出潜在风险"