altinity-expert-clickhouse-connection

连接、集群和时间窗口

在运行任何其他 altinity-expert-clickhouse-* 技能之前，先运行此技能。它会收集后续每项技能都会复用的信息：连接模式、集群名称（或单节点）、ClickHouse 版本、Keeper 是否存在，以及时间窗口。

第 1 步：选择连接模式

按以下顺序检查可用工具，并在找到第一个匹配项时停止：

1. MCP 模式：名称中包含 clickhouse，且包含 query、execute、sql 其中之一的工具（例如 clickhouse_execute_query、mcp__clickhouse__execute_query）。每次调用恰好发送一条 SQL 语句。如果有多个 ClickHouse MCP 服务，请询问用户要使用哪一个。
2. Exec 模式：Shell 工具和 clickhouse-client（或 clickhouse client）。仅使用用户提供的连接标志（--host、--port、--user、--password、--secure）；不要从环境变量中猜测凭据。每次调用仅运行一条语句，并使用 --query "<statement>"。绝不要使用 --queries-file 或 --multiquery。
3. 两者都没有：停止并询问用户如何连接 ClickHouse。不要安装软件，也不要编写辅助脚本。

第 2 步：验证连接并收集头部信息

运行以下一条语句。它适用于独立服务器（无宏、无 Keeper）和集群：

SELECT
    hostName() AS hostname,
    version() AS version,
    (SELECT substitution FROM system.macros WHERE macro = 'cluster') AS cluster_macro,
    (SELECT groupUniqArray(cluster) FROM system.clusters WHERE NOT is_local) AS candidate_clusters,
    (SELECT count() FROM system.tables WHERE database = 'system' AND name = 'zookeeper_connection') AS has_keeper,
    formatReadableTimeDelta(uptime()) AS uptime,
    formatReadableSize((SELECT value FROM system.asynchronous_metrics WHERE metric = 'OSMemoryTotal')) AS os_memory_total

如果遇到身份验证或网络错误，请停止并询问连接详情。不要使用猜测的凭据重试。

第 3 步：确定集群模式

• cluster_macro 不为空 → 集群模式。在每个查询包中保持 '{cluster}' 原样；服务器会展开此宏。
• cluster_macro 为空且 candidate_clusters 不为空 → 询问用户要使用哪个集群，然后在运行每条语句前，将 '{cluster}' 替换为该集群名称。
• 两者都为空 → 单节点模式。在每条语句中将 clusterAllReplicas('{cluster}', system.<table>) 替换为 system.<table>。

has_keeper = 0 表示没有 Keeper/ZooKeeper：跳过所有标记为 -- @requires keeper 的语句，并将复制和 ON CLUSTER 检查报告为不适用。

第 4 步：确定时间窗口

• 如果用户提供了时间范围，按原样使用。
• 否则使用最近 24 小时（event_time >= now() - INTERVAL 24 HOUR）。查询包已使用相对时间窗口；未经询问，不要扩大范围。

如何运行查询包（适用于每项技能）

1. 从技能目录中读取每个查询包文件（技能加载器会打印目录路径）。
2. 每次只运行一条语句，绝不要运行整个文件。语句以 ; 结尾，并以 -- @check <id> <title> 标头开头；将 id 与结果一同保留。
3. 遵循 -- @requires：如果缺少指定表、需要 keeper 但 has_keeper = 0，或版本条件不满足，则跳过该语句。列出跳过的 id 及原因。
4. 按第 3 步的决定保留 {cluster}。其他任何 {placeholder} 都是模板变量：先替换为实际值，否则跳过该语句。
5. 遇到错误时，记录检查 id 和错误的第一行，然后继续运行下一条语句。仅当出现 UNKNOWN_IDENTIFIER 时，运行 DESCRIBE TABLE system.<table> 并移除缺少的列。
6. severity 列就是该行的判定结果。照录即可；不要重新评级。

报告标头

每份报告都以此表格开头，并根据第 2 步填写：

连接模式	集群	ClickHouse 版本	Keeper	时间窗口
MCP 或 clickhouse-client	宏值、所选集群或“单节点”	版本	是/否	使用的窗口

后续技能

• 问题领域未知或需要常规健康检查 → 加载技能 altinity-expert-clickhouse-overview
• 症状明确 → 加载匹配的专业技能（内存、合并、复制、摄取、报告、存储……）