本文面向开发工程师、DBA、AI 应用开发者，讲解 KaiwuDB Agent Skill 能力、部署安装、调用方式、自定义开发，帮助开发者把数据库运维、时序分析能力封装为大模型可直接调用的技能，摆脱冗长复杂的 Prompt。

什么是 KaiwuDB Skill

在大模型 Agent 开发场景中，单纯依靠 Prompt 实现数据库运维、SQL 生成、时序数据分析，可能会或多或少存在这些问题：

• 提示词冗长，需要把全部数据库知识塞进上下文；
• 版本、参数、语法容易出错，大模型幻觉严重；
• 运维命令、最佳实践无法沉淀复用，每个项目都要重新写提示词。

KaiwuDB Skill（Agent‑Skills） 是一套可复用的数据库技能组件库，将 KaiwuDB 部署运维、SQL 编写、故障排查、时序分析、迁移方案等知识库封装成标准化技能。大模型 Agent 可以直接加载调用，不需要写超长 Prompt，即可完成数据库相关任务。今天我们我们重点给大家分享如何使用智能巡检 Skill。

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

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

巡检被拆成四步

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

关键约束也很硬：

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

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

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

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

=================

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

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

常见问题 FAQ

Q1：KaiwuDB Skill 和直接写 Prompt 有什么区别？
A1：Skill 是结构化封装的能力单元，有固定输入输出、版本管理，不需要每次把全部知识库写入提示词，减少上下文消耗，降低幻觉；同时技能可以复用、迭代更新。

Q2：Skill 是否必须要有运行中的 KaiwuDB 数据库？
A2：不需要。Skill 可以只输出脚本、方案、SQL 文本；如果需要真实执行 SQL，再配置数据库连接参数。

总结

KaiwuDB Agent‑Skill 把数据库领域知识封装成标准化组件，给 Agent 应用提供专业的数据库能力。不管是做私有知识库助手、开发运维助手，还是业务系统内嵌 AI 能力，都可以直接复用这套技能库，也可以基于它扩展自己业务场景的专属技能。

相关文章

KaiwuDB Agent Skills 使用指南：数据库查询、部署与智能运维工作流
KaiwuDB Agent Skills 使用指南：用 performance-review Skill 解读执行计划
KaiwuDB 开发者社区

最后更新时间：2026-08-07