前言：为什么智能问数需要 Skills？
在企业级应用中，"让 AI 直接查数据库" 是一个高频需求：
❓ "上个月销售额最高的产品是什么？"
❓ "系统中有哪些姓李的用户？"
❓ "订单状态为 pending 的记录有多少条？"
但直接让 LLM 生成 SQL 存在三大风险：
-
安全风险：SQL 注入、越权查询、敏感数据泄露
-
准确性风险：表名/字段名幻觉、语法错误
-
可维护性风险：逻辑黑盒、难以调试、无法审计
AI Skills 的爆发，为这些问题提供了完美的解决方案。
什么是 AI Skills？
根据最新的行业标准，AI Skills 是一个开放标准，用于为 AI 智能体扩展专门能力[[4]]。它的核心特点是：
-
Skills = 封装的领域专业知识：将任务执行流程、工具使用方法、异常处理方案打包成模块化能力单元 [[1]]
-
Skills vs Tools：Tools 是"手"（执行动作），Skills 是"大脑培训"（提供专业知识）[[21]]
-
可移植、版本控制：Skills 以文件形式存储，可在代码仓库中追踪变更，支持跨平台复用 [[4]]
**简单来说：Skills 就是"给 AI 准备的标准化工作 SOP 大礼包"**，包含任务流程、工具说明、最佳实践和问题解决方案 [[1]]。
核心设计理念
Function Calling 机制：让 AI"知道能用什么"
List<Tool> tools = Text2SqlTools.builder()
.addDataSourceInfo(dataSource)
.buildTools();
userMessage.addTools(tools);
这本质上是在为 AI 注册 Skills —— 将数据查询的领域知识封装成可调用的技能包。LLM 在生成回复前，会先"看到"可用技能的描述（name + description + parameters），从而决定：
"软失败"原则：让 AI 具备自纠错能力
// DataTools 中所有工具方法遵循统一规范：
// ✅ 成功：返回结构化文本（Markdown/JSON）
// ❌ 失败：返回 "Error: xxx" 格式字符串，而非抛异常
if (dataSourceName == null) {
return ERROR_PREFIX + "dataSourceName cannot be empty...";
}
这是 Skills 的最佳实践 —— AI 收到 Error: 开头的反馈后，可自动分析原因、调整参数、重新调用，大幅提升鲁棒性 [[21]]。
结构化输出：AI 友好 + 人类可读
// 表结构返回 Markdown 表格，AI 易解析，人类易阅读
sb.append("* Field Name * Type * Primary Key * Comment *\n")
.append("*------------*------*----------------*---------*\n");
符合 Skills 的设计理念：将专业知识转化为 AI 可理解的格式，让 AI 不仅"能做事"，还能"把事做好" [[1]]。
代码实战解析
步骤 1：模型配置（支持任意 OpenAI 兼容接口）
OpenAIChatModel chatModel = OpenAIChatConfig.builder()
.provider("GiteeAI")
.endpoint("https://ai.gitee.com")
.apiKey(System.getenv("GITEE_APIKEY"))
.model("Qwen3-32B") // 支持 Qwen、DeepSeek 等国产模型
.logEnabled(false)
.buildModel();
💡 提示：通过 provider + endpoint 灵活切换模型供应商，符合 Skills 的可移植性原则 [[4]]。
步骤 2：数据源注册与元数据预加载
JdbcDataSourceInfo dataSource = new JdbcDataSourceInfo();
dataSource.setJdbcUrl("jdbc:mysql://192.168.2.10:3306/aiflowy-v2?...");
dataSource.setUsername("root");
dataSource.setPassword("123456");
dataSource.setName("aiflowy_v1");
// Builder 中自动调用 buildTables() 预加载表结构
DataTools.builder()
.addDataSourceInfo(dataSource)
.buildTools();
✅ 元数据预加载避免每次查询都访问 information_schema，提升性能
✅ 支持多数据源隔离，满足多租户场景
✅ 这是 Skills 的"参考资料"部分，为 AI 提供领域知识 [[4]]
步骤 3：核心 Skills 实现（以 listTableColumns 为例）
@ToolDef(
name = "listTableColumns",
description = "[Step 2] Get field structure... Must call this tool to confirm column names before writing SQL."
)
public String listTableColumns(
@ToolParam(name = "dataSourceName", description = "...") String dataSourceName,
@ToolParam(name = "tableName", description = "...") String tableName
) {
// 🔍 参数校验 → 查找数据源 → 查找表 → 格式化返回
// 全程"软失败"，错误信息明确可追溯
}
🎯 这就是一个典型的 AI Skill：
-
封装了领域知识：如何查询表结构、如何格式化输出
-
定义了 SOP 流程：参数校验 → 查找资源 → 执行查询 → 格式化结果
-
提供异常处理：清晰的错误信息引导 AI 自我修正 [[1]]
-
注解驱动：@ToolDef + @ToolParam 自动扫描生成技能描述，零 XML 配置
步骤 4：流式响应 + 技能调用闭环
StreamResponseListener listener = new StreamResponseListener() {
@Override
public void onMessage(StreamContext context, AiMessageResponse response) {
// 1. 输出 AI 思考过程（可选）
if (content != null) System.out.print(content);
// 2. 检测到技能调用 → 执行 → 结果回填 → 递归继续生成
if (response.getMessage().isFinalDelta() && response.getMessage().hasToolCalls()) {
prompt.addMessage(response.getMessage()); // 保留历史
for (ToolCall toolCall : response.getMessage().getToolCalls()) {
List<ToolMessage> toolMessages = response.executeToolCallsAndGetToolMessages();
prompt.addMessages(toolMessages); // 技能结果作为新消息
}
chatModel.chatStream(prompt, this); // 递归调用，实现多轮技能协作
}
}
};
这是 Skills 的典型工作流：
-
AI 根据上下文自动判断需要调用哪个技能 [[4]]
-
技能执行后返回结构化结果
-
AI 基于结果继续推理或调用下一个技能
-
最终用自然语言总结返回，全程流式输出，体验丝滑！
生产级最佳实践（Agents-Flex 已内置）
SQL 安全校验（防注入 + 权限控制）
private String validateSqlReadOnly(String sql) {
String[] forbidden = {"INSERT ", "UPDATE ", "DELETE ", "DROP ", ...};
for (String keyword : forbidden) {
if (upperSql.contains(keyword)) {
return "Security restriction: " + keyword.trim() + " operation is prohibited";
}
}
if (!upperSql.startsWith("SELECT") && !upperSql.startsWith("WITH")) {
return "SQL must start with SELECT or WITH";
}
return null;
}
这是 Skills 的"质量门禁" —— 在技能层面强制执行安全规则，而非依赖 Prompt 工程 [[1]]。
参数防注入：强制使用 ? 占位符
// queryDataList 方法要求：
// "If containing dynamic values, must use '?' as placeholder, direct string concatenation is prohibited"
List<Map<String, Object>> result = JdbcQueryUtil.query(dataSource, sql, safeParams(params));
Skills 不仅告诉 AI"做什么"，还规定了"怎么做才安全" [[21]]。
错误信息友好化：引导 AI 自我修正
return ERROR_PREFIX + "Table '" + tableName + "' does not exist, available tables: ['user', 'order', ...]";
💡 AI 收到后可自动重试：*"哦，原来表名叫 user 而不是 users，我重新查一下"*
**这是 Skills 的"异常兜底方案"**，让 AI 具备自纠错能力 [[1]]。
效果演示
用户：系统中有哪些姓李的用户呢？
AI: [思考] 需要查询用户表，先确认数据源和表结构...
[自动调用 listTables 技能]
<<<<< 返回: 📋 Data Source: `aiflowy_v1`
* Table Name * Description *
*------------*-------------*
* `user` * 用户信息表 *
[自动调用 listTableColumns 技能]
<<<<< 返回: 📊 Table Schema: `user`
* Field Name * Type * Comment *
*------------*------*---------*
* `id` * BIGINT * 主键 *
* `name` * VARCHAR * 姓名 *
* `email` * VARCHAR * 邮箱 *
[自动调用 queryDataList 技能]
<<<<< 返回: [
{"name":"李雷","email":"lili@example.com"},
{"name":"李梅","email":"limei@example.com"}
]
AI: 在 aiflowy_v1 数据源中，姓李的用户有以下 2 位：
- **李雷**：lili@example.com
- **李梅**：limei@example.com
> 💡 如需查看更多，可调整 LIMIT 参数或添加其他筛选条件。
>>>>>>> 结束 <<<<<<<<<
🤩 效果：AI 不仅查到了数据，还主动给出优化建议，体验远超传统 BI 工具！
这正是 Skills 的价值 —— 将专业经验转化为 AI 可复用的数字资产 [[1]]。
为什么选择 Agents-Flex？
|
特性
|
传统方案
|
Agents-Flex Skills
|
| 集成成本 |
需自研 Function Calling 框架
|
✅ 注解驱动，5 行代码注册技能
|
| 模型兼容 |
通常绑定单一厂商
|
✅ OpenAI 兼容接口，无缝切换 Qwen/DeepSeek/GLM
|
| 安全控制 |
依赖 Prompt 工程，易绕过
|
✅ Java 层强制校验，SQL 注入零容忍
|
| 可调试性 |
黑盒，难定位问题
|
✅ 技能调用日志 + 参数回溯，问题一目了然
|
| 开源协议 |
商业限制多
|
✅ Apache 2.0，企业可放心商用
|
总结
通过 AI Skills 机制 实现智能问数，本质是 "AI 做决策，代码保底线" 的分工协作：
与行业趋势的契合
2025-2026 年，AI Skills 已成为行业标准 [[1]][[4]]：
Agents-Flex 的 DataTools 正是这一趋势的实践：
-
✅ 封装了数据查询的完整 SOP（查表 → 查结构 → 执行查询）
-
✅ 提供了安全的执行载体（SQL 校验、参数绑定）[[2]]
-
✅ 支持渐进式加载（按需调用技能，节省上下文）[[4]]
未来计划：
-
🔗 集成权限系统：根据用户角色动态过滤可查表/字段
-
📊 增加聚合技能：queryStatistic 支持 COUNT/SUM/AVG 等预置统计
-
🌐 多模态输出：支持返回图表配置（ECharts JSON），前端直接渲染
-
📚 技能市场：将 DataTools 发布为标准 Skill，供其他项目复用 [[1]]
作者简介：Michael Yang（杨福海），Agents-Flex 以及 AIFlowy 等 AI 项目发起人，小码科技创始人。长期致力于推动 Java AI 生态标准化，坚持 Apache Way 开源理念。
AIFlowy，企业级 AI 智能体开发平台 : https://aiflowy.tech
Agents-Flex 一个轻量的 AI 智能体开发框架，Java 生态首选 * 支持 MCP、AI Skills 与智能问数: https://agentsflex.com
参考文献
- [[1]] AI Skills——AI时代的标准化魔法书. 知乎专栏. 2026-01-30.
- [[2]] 一文读懂最近爆火的AI Skills. Binance Square. 2026-01-22.
- [[4]] Agent Skills * Cursor Docs. https://cursor.com/cn/docs/context/skills
- [[19]] Agent vs Workflow vs Skills：AI架构演进与选型指南. 七牛云.
- [[21]] Skills vs Tools for AI Agents: Production Guide. Arcade.dev. 2025-12-09.
- [[23]] AI Agent 入门指南（三）：Tools——从Function Calling 到MCP与Skills. 知乎专栏. 2026-01-19.
