KaiwuDB Skill 使用指南： 智能巡检 Skill，把健康检查变成可复用工作流

本文面向开发工程师、DBA、AI 应用开发者讲解 KaiwuDB Agent Skill 能力、部署安装、调用方式、自定义开发帮助开发者把数据库运维、时序分析能力封装为大模型可直接调用的技能摆脱冗长复杂的 Prompt。什么是 KaiwuDB Skill在大模型 Agent 开发场景中单纯依靠 Prompt 实现数据库运维、SQL 生成、时序数据分析可能会或多或少存在这些问题提示词冗长需要把全部数据库知识塞进上下文版本、参数、语法容易出错大模型幻觉严重运维命令、最佳实践无法沉淀复用每个项目都要重新写提示词。KaiwuDB SkillAgent‑Skills 是一套可复用的数据库技能组件库将 KaiwuDB 部署运维、SQL 编写、故障排查、时序分析、迁移方案等知识库封装成标准化技能。大模型 Agent 可以直接加载调用不需要写超长 Prompt即可完成数据库相关任务。今天我们我们重点给大家分享如何使用智能巡检 Skill。数据库巡检最怕两件事一是上来就跑命令连目标节点、端口和巡检范围都没有确认二是拿到一堆指标后只给出看起来正常这种无法复核的判断。KWDB 智能巡检 Skill 解决的是这类操作规范问题。这个 Skill 面向 KaiwuDB/KWDB 的巡检和健康检查任务覆盖指标采集、慢查询读取、异常规则判断和巡检报告生成。它的定位是一套给 Agent 执行巡检时遵守的作业规程常驻监控仍然要交给监控系统。巡检被拆成四步主流程只有四个动作先确认目标和范围再采集指标然后应用异常规则最后输出报告。关键约束也很硬•没有确认节点地址、端口和巡检范围之前不能进入指标采集•调用脚本之前必须先读对应的 usage 文档不能猜参数。这套顺序看起来保守但数据库巡检本来就应该保守。尤其在生产环境里Agent 不能把我猜应该是 localhost:8080当成执行依据也不能在用户只想看几个指标时默认跑完整巡检。第一步不是采集而是确认边界Skill 把前置确认拆得很细。Agent 需要从用户需求中解析节点地址、数据库端口、Admin Console 端口和巡检范围其中数据库端口默认是26257Admin Console 端口默认是8080。随后才是连通性探测。参考文档要求检查数据库端口和 Admin Console 端口如果端口不可达需要让用户核对网络、防火墙或服务状态。端口可达后还要检测 TLS 模式。Skill 明确还指出暂时不支持启用 TLS 的 KaiwuDB 部署。这条边界挡住了一个常见误区把 Agent 写得像万能巡检员实际运行时却卡在登录、证书、验证码或网络权限上。把不支持的条件提前暴露出来让巡检从一开始就可控。两个脚本负责采集数据真正采集数据时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 行为上。指标覆盖从资源到集群状态参考文档把巡检报告分成六类基础指标、系统资源、数据库性能、存储、集群和网络。•基础指标关注数据库运行状态和运行时长例如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 是否健康节点之间是否存在同步或网络问题。异常判断不会默认乱报警anomaly-rules.md里有一个很实用的约束异常规则由用户需求驱动。用户没有要求告警时Agent 不应该主动输出告警结论用户要求告警但没有给出自定义阈值时才使用默认规则。默认规则覆盖几类明确状态数据库宕机26257或8080端口未监听一天内重启超过一次副本同步延迟超过 5 秒不可用 range 大于 0。CPU、内存、QPS、写入延迟和查询延迟属于可配置规则需要用户给出阈值或采样窗口。文档还特别提醒QPS 和延迟异常不能从单个快照里武断判断需要采样窗口支撑。很多智能巡检容易把阈值写死最后变成另一套噪声源。KWDB 这个 Skill 把判断条件放在规则文档里并区分默认规则和用户阈值降低了误报风险。报告要能追溯数据来源巡检报告需要像审计材料一样可复核。output-rules.md和report-template.md要求报告包含指标值、异常判断和数据来源说明。报告也需要说明哪些数据来自端口探测哪些来自时序指标脚本哪些来自慢查询接口。这会让读者更容易判断结论是否可信。例如Admin UI 端口不可达和慢查询接口没有返回失败语句不是同一种证据前者来自连通性探测后者来自/_status/statementsAPI。把来源写清楚后续排查的人才知道该继续查网络、权限、服务状态还是 SQL 执行本身。使用时要记住它的边界它更适合由人发起、目标明确的巡检任务。•临时健康检查时你想快速了解某个 KaiwuDB 集群当前状态又不想手工拼指标接口和报告模板可以让 Agent 按这个 Skill 的流程执行。•故障初筛时服务变慢、SQL 延迟升高、range 状态异常它能把资源、SQL、存储和集群指标放到同一份报告里帮助你缩小方向。•做巡检标准化时团队可以把先确认目标、再采集、再判断、最后落报告固化下来。和一段临时 prompt 相比这个 Skill 更稳定。同时它也有清晰限制不支持 Windows不支持 TLS 模式巡检它依赖 KaiwuDB Admin UI 端口和相关状态接口可访问它承担一次性巡检不承担 Prometheus、告警平台或正式 SRE 值班流程的职责。更合理的用法是把它放在人工发起的一次性巡检或Agent 辅助排查的位置上。简单用一下安装推荐使用skills.sh来安装几乎市面上所有的 AI Agent 工具它都支持安装也仅需一行命令npx skills add KWDB/KaiwuDB-Agent-Skills --skill kwdb-intelligent-inspection开始巡检直接调用 Skill/kwdb-intelligent-inspection期间会有多次确认操作确认节点地址、端口等信息最终会输出一份巡检报告测试效果如下:常见问题 FAQQ1KaiwuDB Skill 和直接写 Prompt 有什么区别A1Skill 是结构化封装的能力单元有固定输入输出、版本管理不需要每次把全部知识库写入提示词减少上下文消耗降低幻觉同时技能可以复用、迭代更新。Q2Skill 是否必须要有运行中的 KaiwuDB 数据库A2不需要。Skill 可以只输出脚本、方案、SQL 文本如果需要真实执行 SQL再配置数据库连接参数。总结KaiwuDB Agent‑Skill 把数据库领域知识封装成标准化组件给 Agent 应用提供专业的数据库能力。不管是做私有知识库助手、开发运维助手还是业务系统内嵌 AI 能力都可以直接复用这套技能库也可以基于它扩展自己业务场景的专属技能。相关文章KaiwuDB Agent Skills 使用指南数据库查询、部署与智能运维工作流KaiwuDB Agent Skills 使用指南用 performance-review Skill 解读执行计划KaiwuDB 开发者社区最后更新时间2026-08-07