01 前言

Agent 已经不只是一个能聊天的入口了。

真正落到工程现场时，它需要知道什么时候该追问、什么时候该查 schema、什么时候必须让人确认高风险操作。数据库场景尤其如此：自然语言转 SQL、部署集群、排查慢查询，背后都不只是"生成一段文本"，而是一套带有上下文、约束和安全边界的操作流程。

KWDB Agent Skills（https://github.com/KWDB/KaiwuDB-Agent-Skills） 做的就是这件事：把 KWDB / KaiwuDB 相关的数据库经验封装成可安装、可触发、可复用的 Agent Skill，让本地 Agent 在处理 KWDB 查询、AIoT 时序分析和部署任务时，不再只依赖一次性的长提示词。

02 Agent Skill 解决的不是"提示词太短"

我们对 KWDB Agent Skills 的定位很直接：

面向 KWDB 查询、AIoT 时序分析和部署任务的 Agent Skill 集合。

这句话里有两个关键词值得拆开看。

第一个是集合。KWDB Agent Skills 不是一个单一 Prompt，而是围绕 KWDB 常见工程任务建立的一组 Skill。每个 Skill 都声明自己的触发场景、参考资料、执行步骤和风险控制方式。

第二个是任务。数据库 Agent 最容易出问题的地方，不是它不会写 SQL，而是它不知道任务边界。比如用户问"查一下最近一小时温度异常的设备"，Agent 需要先识别这是时序分析；如果可以连接数据库，还应该发现真实库表结构；如果 schema 不可用，就要明确标注假设字段；如果要执行 SQL，则需要区分读写操作并请求确认。

这些步骤写在一个长 Prompt 里当然也能工作，但很难维护，也很难分发。Skill 的价值在于把这些经验沉淀成结构化协议。

03 当前可用的 KWDB Skills

首批公开的 Skills 主要有两个：kwdb-text2sql-aiot 和 kwdb-install-deploy。

kwdb-text2sql-aiot：面向 AIoT 的 Text2SQL

kwdb-text2sql-aiot的目标是把自然语言查询转换成 KWDB SQL，覆盖时序数据、关系数据以及跨模分析。它支持的任务类型包括创建库表、降采样、插值、最新值查询、聚合分析、跨模查询，以及滑动窗口、Session Window、Event Window 等时序分析场景。

它的工作流并不是"用户说什么就直接写 SQL"，而是先做路由和 schema 发现：

• 如果可用，会通过 MCP 执行 SELECT 1 检测连接能力；

• 在用户没有提供数据库名时，询问数据库名称或通过 SHOW DATABASES 列出数据库；

• 通过 SHOW TABLES FROM {database_name} 和 SHOW CREATE TABLE 获取真实表结构；

• 根据自然语言任务路由到对应参考文件，例如降采样、插值、最新值、跨模 JOIN 或关系查询；

• 生成 SQL 后，附带字段映射、假设说明和验证清单；

• 如果需要执行 SQL，还会区分 SELECT、SHOW、EXPLAIN 这类读查询和 INSERT、CREATE、ALTER 等写查询，并在执行前请求用户确认。

这种设计对 AIoT 场景很实用。因为时序数据查询往往不是简单过滤，还涉及时间范围、设备标签、聚合粒度、缺失值填充和最新值语义。把这些规则拆成 Skill 参考资料后，Agent 可以按场景读取更窄的知识，而不是把所有数据库知识混在一次推理里。

kwdb-install-deploy：把部署流程做成可确认的步骤

kwdb-install-deploy 面向 KaiwuDB 的安装和部署，适用于 Linux 环境下的裸金属或容器部署，并覆盖单节点、单副本集群和多副本集群等流程。

这个 Skill 最值得注意的不是命令本身，而是它写进了非常明确的护栏：

• 不允许猜测安装参数，端口、IP、数据目录、安全模式等配置都必须逐项确认；

• 即使用户说"使用默认值"，也需要明确列出默认值并获得确认；

• 安装包路径必须由用户提供，不能由 Agent 自行猜测；

• 安装失败时，必须读取安装脚本同级 log/ 目录下的日志；

• 报告失败原因后退出流程，不允许 Agent 自行反复重试。

这些约束看起来有些"保守"，但对部署类任务很必要。数据库安装涉及主机、端口、目录、证书、安全模式和集群拓扑，任何一个参数被 Agent 擅自猜错，都可能造成排查成本。Skill 把确认点前置，实际上是在让 Agent 更像一个可靠的运维助手，而不是一个会自动执行命令的黑盒。

04 安装方式

为了适配不同用户的需求，我们提供了多种安装方式。

Skills.sh

最通用的安装方式，几乎市面上所有的 AI Agent 工具它都支持，安装也仅需一行命令：

npx skills add KWDB/KaiwuDB-Agent-Skills

OpenClaw

如果您是 OpenClaw 的用户，我们也提供了 clawhub 的安装方式：

clawhub install <skill-slug>

或者直接和 OpenClaw 说："安装 kwdb-install-deploy"

Claude Code

对于 Claude Code 用户，则直接在 Claude Code 中的 /plugin -> Marketplace -> +Add Marketplace ->搜索https://github.com/KWDB/KaiwuDB-Agent-Skills 即可看到：

选择 Skill 安装即可，或者直接使用命令行进行安装：

claude plugin marketplace add https://github.com/KWDB/KaiwuDB-Agent-Skills

手动安装

也可以使用手动方式安装：

git clone https://github.com/KWDB/KaiwuDB-Agent-Skills.git

05 为什么它适合数据库任务

数据库任务有三个特点，决定了它特别适合 Skill 化。

第一，上下文依赖强 。同一句"查询最近一小时平均温度"，在不同表结构下生成的 SQL 完全不同。kwdb-text2sql-aiot 把 schema discovery 放在工作流前面，可以降低字段名、表名和时间列猜错的概率。

第二，语法细节多 。时序数据库查询会涉及 time_bucket、time_bucket_gapfill、interpolate、last、窗口函数和跨模 JOIN。把这些内容放进按场景拆分的参考文件，Agent 每次只需要读取当前任务相关的语法片段。

第三，执行风险不能忽略。SQL 执行、部署安装、集群初始化都可能改变系统状态。Skill 把"确认执行""失败后读日志""不擅自重试"等规则写进协议，能让 Agent 在自动化和可控性之间保持边界。

这也是 KWDB Agent Skills 比普通示例 Prompt 更有价值的地方：它不是教模型"怎么回答"，而是约束 Agent "怎么做事"。

06 Roadmap：从查询到巡检

除了当前 Ready 的 Text2SQL 与安装部署 Skill，我们在近期还会陆续放出以下 Skill：

• kwdb-schema-design：为关系、时序、混合 workload 设计 KWDB schema 和最小可执行 DDL；

•kwdb-performance-review：分析慢 SQL、schema 问题、执行计划和调优选项；

•kwdb-troubleshooting：诊断 KWDB 报错、连接问题、稳定性问题和常见故障；

•kwdb-data-migration：规划 KWDB 导入导出、迁移、升级和同步工作流；

•kwdb-ts-anomaly-detection：为 KWDB 时序数据生成异常检测 SQL；

•kwdb-intelligent-inspection：基于 KWDB 监控指标和系统视图执行健康检查与巡检流程。

可以看到，路线图基本沿着数据库生命周期展开：先解决查询和部署，再扩展到建模、性能、故障、迁移、异常检测和巡检。随着这些 Skill 逐步成熟，KWDB 的 Agent 使用体验会从"帮我写一段 SQL"扩展到"帮我完成一类数据库工作流"。

07 结语

Agent 进入数据库场景后，最重要的能力不是更会聊天，而是更懂边界。

KWDB Agent Skills 给出的方向很务实：把 KWDB SQL、AIoT 时序分析和部署经验拆成可安装的 Skill，并把 schema 发现、场景路由、执行确认、日志读取这些关键步骤固化下来。对开发者来说，它降低了把 KWDB 接入本地 Agent 的门槛；对数据库运维任务来说，它也让自动化多了一层可审计的操作协议。

如果你已经在使用 Codex、Claude Code 或其他支持 Skill / Plugin 机制的本地 Agent，可以先从 kwdb-text2sql-aiot 试起。它最能体现这类 Skill 的价值：把一句自然语言问题，稳妥地落到可检查、可修正、可执行的 KWDB SQL。

更多信息可查阅 KWDB Agent Skill 官网：https://kwdb.tech/agent-skills 及开源仓库：https://github.com/kwdb/kaiwudb-agent-skills 。欢迎在社区微信群、Gitee/GitHub Issue 提出反馈与建议，期待与您共同完善项目。