用途:这是 altinity-expert-clickhouse-* 系列的前置技能,需在其他技能之前运行。它产出后续技能复用的基础事实:连接模式、集群名(或单节点)、ClickHouse 版本、Keeper 是否存在、时间窗口。
连接模式:按顺序检查。其一,MCP 模式:存在名称含 clickhouse 且含 query、execute 或 sql 的工具(如 clickhouse_execute_query、mcp__clickhouse__execute_query),每次调用只发一条 SQL;若有多个 ClickHouse MCP 服务器,需询问用户用哪一个。其二,Exec 模式:有 shell 工具和 clickhouse-client(或 clickhouse client),只用用户提供的连接参数(--host、--port、--user、--password、--secure),不要从环境变量猜测凭据,每次用一个语句加 --query "<statement>",禁止 --queries-file 或 --multiquery。两者都无时停止并询问用户如何连接,不安装软件、不写辅助脚本。
收集事实:运行资料给出的单条 SQL(读取 hostName、version、cluster 宏、candidate_clusters、has_keeper、uptime、OSMemoryTotal)。若因认证或网络错误失败,停止并询问连接信息,不要用猜测的凭据重试。
集群模式判定:cluster 宏非空即集群模式,查询包中的 '{cluster}' 保持原样由服务器展开;宏为空但存在候选集群时,询问用户用哪个集群,再把每个语句中的 '{cluster}' 替换为真实名称;两者皆空则为单节点模式,将 clusterAllReplicas('{cluster}', system.<table>) 替换为 system.<table>。has_keeper = 0 表示无 Keeper/ZooKeeper,跳过所有标记 -- @requires keeper 的语句,并把复制与 ON CLUSTER 检查报告为不适用。
时间窗口:用户给出时间范围则严格使用;否则默认最近 24 小时(event_time >= now() - INTERVAL 24 HOUR),不要未经询问扩大查询包已有的相对窗口。
运行查询包:从技能目录读取包文件,逐条执行而非整文件;语句以 ; 结束并以 -- @check <id> <title> 开头,保留 id。遵守 -- @requires:表缺失、需要 keeper 但 has_keeper = 0、或版本条件不满足时跳过,并列出被跳过的 id 与原因。除已确定的 {cluster} 外,其他 {placeholder} 需先替换为真实值,否则跳过。出错时记录检查 id 与错误首行,继续下一条;仅对 UNKNOWN_IDENTIFIER 执行 DESCRIBE TABLE system.<table> 并去掉缺失列。severity 列即该行结论,直接复制不要再评级。报告开头需列出连接模式、集群、ClickHouse 版本、Keeper、时间窗口。后续:未知问题或健康检查加载 altinity-expert-clickhouse-overview;已知症状加载对应专项技能。