KWDB 智能巡检 Skill：把健康检查变成可复用工作流

01 写在前面

上篇我们介绍了 KWDB Agent Skills，讲解了文本转 SQL、部署运维两大核心技能、工作流程及多平台安装方法。本期将围绕新上架的 KWDB 智能巡检 Skill，为大家详细解读这项全新能力。

数据库巡检最怕两件事：一是上来就跑命令，连目标节点、端口和巡检范围都没有确认；二是拿到一堆指标后，只给出"看起来正常"这种无法复核的判断。KWDB 智能巡检 Skill 解决的是这类操作规范问题。

这个 Skill 面向 KaiwuDB/KWDB 的巡检和健康检查任务，覆盖指标采集、慢查询读取、异常规则判断和巡检报告生成。它的定位是一套给 Agent 执行巡检时遵守的作业规程；常驻监控仍然要交给监控系统。

02 巡检被拆成四步

主流程只有四个动作：先确认目标和范围，再采集指标，然后应用异常规则，最后输出报告。

关键约束也很硬：

• 没有确认节点地址、端口和巡检范围之前，不能进入指标采集；

• 调用脚本之前，必须先读对应的 usage 文档，不能猜参数。

这套顺序看起来保守，但数据库巡检本来就应该保守。尤其在生产环境里，Agent 不能把"我猜应该是 localhost:8080"当成执行依据，也不能在用户只想看几个指标时默认跑完整巡检。

03 第一步不是采集，而是确认边界

Skill 把前置确认拆得很细。Agent 需要从用户需求中解析节点地址、数据库端口、Admin Console 端口和巡检范围，其中数据库端口默认是 26257，Admin Console 端口默认是 8080。

随后才是连通性探测。参考文档要求检查数据库端口和 Admin Console 端口，如果端口不可达，需要让用户核对网络、防火墙或服务状态。端口可达后，还要检测 TLS 模式。Skill 明确还指出：暂时不支持启用 TLS 的 KaiwuDB 部署。

这条边界挡住了一个常见误区：把 Agent 写得像"万能巡检员"，实际运行时却卡在登录、证书、验证码或网络权限上。把不支持的条件提前暴露出来，让巡检从一开始就可控。

04 两个脚本负责采集数据

真正采集数据时，Skill 主要使用两个 Python 脚本。

get_kwdb_ts_metrics.py 负责读取时序指标，默认访问 KaiwuDB Admin UI 的 8080 端口。它支持 --host、--port、--start、--end、--sample、--metric 和 --json 参数。默认采样间隔是 60 秒，时间范围默认从一小时前到当前时间。你可以采集全部指标，也可以用多个 --metric 只取指定指标。

get_kwdb_statements.py 负责读取慢查询和 SQL 语句统计。它支持按 service_lat、run_lat、plan_lat 或 count 排序，默认按总服务延迟排序；也可以用 --min-latency-ms 过滤低于某个延迟阈值的语句，用 --limit 控制输出条数。输出字段包括 SQL 文本、应用名、用户、数据库、执行次数、延迟、是否使用 DistSQL、是否失败以及最后一次错误信息。

这两个脚本的定位不同：一个看系统和集群指标，一个看 SQL 层面的慢语句。把它们放在同一个 Skill 里，巡检报告就不只停留在 CPU、磁盘、内存这类资源视角，也能把性能问题落到具体 SQL 行为上。

05 指标覆盖从资源到集群状态

参考文档把巡检报告分成六类：基础指标、系统资源、数据库性能、存储、集群和网络。

• 基础指标关注数据库运行状态和运行时长，例如 cr.node.liveness.livenodes 与 cr.node.sys.uptime。

• 系统资源部分覆盖 CPU、磁盘容量、内存 RSS 和 Go 运行时内存。

• 数据库性能部分关注写入 QPS、查询 QPS、P99 延迟和慢查询。

• 存储部分包含总数据量、存活数据量和已用容量。

• 集群部分会看副本、Raft leader、lease holder、不可用 range、欠副本 range、超副本 range 和 Raft log 落后情况。

• 网络部分则关注节点间延迟和时钟偏移。

这些指标不算花哨，胜在贴近一次数据库健康检查里最常见的问题定位路径：服务是否活着，资源是否紧张，SQL 是否慢，存储是否接近上限，副本和 range 是否健康，节点之间是否存在同步或网络问题。

06 异常判断不会默认乱报警

anomaly-rules.md 里有一个很实用的约束：异常规则由用户需求驱动。用户没有要求告警时，Agent 不应该主动输出告警结论；用户要求告警但没有给出自定义阈值时，才使用默认规则。

默认规则覆盖几类明确状态：数据库宕机，26257 或 8080 端口未监听，一天内重启超过一次，副本同步延迟超过 5 秒，不可用 range 大于 0。CPU、内存、QPS、写入延迟和查询延迟属于可配置规则，需要用户给出阈值或采样窗口。文档还特别提醒：QPS 和延迟异常不能从单个快照里武断判断，需要采样窗口支撑。

很多"智能巡检"容易把阈值写死，最后变成另一套噪声源。KWDB 这个 Skill 把判断条件放在规则文档里，并区分默认规则和用户阈值，降低了误报风险。

07 报告要能追溯数据来源

巡检报告需要像审计材料一样可复核。output-rules.md 和 report-template.md 要求报告包含指标值、异常判断和数据来源说明。报告也需要说明哪些数据来自端口探测，哪些来自时序指标脚本，哪些来自慢查询接口。

这会让读者更容易判断结论是否可信。例如"Admin UI 端口不可达"和"慢查询接口没有返回失败语句"不是同一种证据；前者来自连通性探测，后者来自 /_status/statements API。把来源写清楚，后续排查的人才知道该继续查网络、权限、服务状态，还是 SQL 执行本身。

08 使用时要记住它的边界

它更适合由人发起、目标明确的巡检任务。

• 临时健康检查时，你想快速了解某个 KaiwuDB 集群当前状态，又不想手工拼指标接口和报告模板，可以让 Agent 按这个 Skill 的流程执行。

• 故障初筛时，服务变慢、SQL 延迟升高、range 状态异常，它能把资源、SQL、存储和集群指标放到同一份报告里，帮助你缩小方向。

• 做巡检标准化时，团队可以把"先确认目标、再采集、再判断、最后落报告"固化下来。和一段临时 prompt 相比，这个 Skill 更稳定。

同时，它也有清晰限制：不支持 Windows，不支持 TLS 模式巡检；它依赖 KaiwuDB Admin UI 端口和相关状态接口可访问；它承担一次性巡检，不承担 Prometheus、告警平台或正式 SRE 值班流程的职责。更合理的用法，是把它放在"人工发起的一次性巡检"或"Agent 辅助排查"的位置上。

09 简单用一下

安装

推荐使用 skills.sh 来安装，几乎市面上所有的 AI Agent 工具它都支持，安装也仅需一行命令：

npx skills add KWDB/KaiwuDB-Agent-Skills --skill kwdb-intelligent-inspection

开始巡检

直接调用 Skill：

/kwdb-intelligent-inspection

期间会有多次确认操作，确认节点地址、端口等信息，最终会输出一份巡检报告，测试效果如下:

10 结语

如果我要在团队里引入 KWDB 智能巡检 Skill，会先把它当成巡检 runbook 使用。我会要求使用者在发起任务时给出节点地址、端口、巡检范围和是否启用告警判断；如果要判断 CPU、内存、QPS 或延迟异常，还要给出阈值和采样窗口。Agent 执行后，产物只接受 Markdown 报告，不接受一句话结论。报告里必须列出数据来源、采样时间、异常规则和无法采集的项目。

落到团队流程里，它的价值很明确：把一次数据库巡检里最容易漏掉的确认动作、脚本参数、指标清单和报告格式固定下来，让 Agent 少凭感觉，多按规程做事。

后续还会有新的 Skill 持续更新，更多信息可查阅：

• KWDB Agent Skill 官网：https://kwdb.tech/agent-skills

• 开源仓库：https://github.com/kwdb/kaiwudb-agent-skills

欢迎在社区微信群、Gitee/GitHub Issue 提出反馈与建议，期待与您共同完善项目。