yuanzhipeng
557361632c
新增 lzwcai-agile-db 技能文件，为 AI Agent 提供 AgileDB 数据库操作的场景化工作流指导。 该技能支持数据源浏览、表数据 CRUD、SQL 执行和 AI 生成表结构等功能，包含完整的工具列表和使用场景。
452 lines
13 KiB
Markdown
452 lines
13 KiB
Markdown
# lzwcai-agile-db Skill 实现计划
|
||
|
||
## 目标
|
||
创建一个 Kilo skill 文件，为 AI Agent 提供 AgileDB 数据库操作的场景化工作流指导。
|
||
|
||
## Skill 文件路径
|
||
`.kilo/skills/lzwcai-agile-db/SKILL.md`
|
||
|
||
## Skill 内容
|
||
|
||
以下为完整的 SKILL.md 内容：
|
||
|
||
```markdown
|
||
# lzwcai-agile-db
|
||
|
||
AgileDB 数据库操作技能。为 AI Agent 提供数据源浏览、表数据 CRUD、SQL 执行和 AI 生成表结构的场景化工作流。
|
||
|
||
## 可用 MCP 工具
|
||
|
||
本 skill 基于 `lzwcai_mcp_agile_db` MCP Server，提供以下工具：
|
||
|
||
### 数据源管理
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| `list_datasources` | 获取数据源列表 |
|
||
| `get_datasource_detail` | 获取数据源详情（含数据库、表结构） |
|
||
| `create_datasource` | 创建外部数据源 |
|
||
| `update_datasource` | 更新数据源 |
|
||
| `toggle_datasource_status` | 启用/停用数据源 |
|
||
| `delete_datasource` | 删除数据源 |
|
||
|
||
### 数据库与表管理
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| `list_databases` | 获取数据源下的数据库列表 |
|
||
| `list_tables` | 获取数据库下的表列表 |
|
||
| `get_table_detail` | 获取表结构详情（字段、类型、主键） |
|
||
| `create_table` | 创建新表 |
|
||
| `alter_table` | 修改表结构 |
|
||
| `generate_table_by_description` | AI 根据自然语言生成表结构 |
|
||
|
||
### 表数据操作
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| `query_table_data` | 查询表数据（分页） |
|
||
| `insert_table_row` | 插入一行数据 |
|
||
| `update_table_row` | 更新一行数据 |
|
||
| `delete_table_rows` | 删除数据行（按主键） |
|
||
| `export_table_excel` | 导出表数据为 Excel |
|
||
|
||
### SQL 执行
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| `execute_sql` | 执行原生 SQL 查询 |
|
||
|
||
---
|
||
|
||
## 场景 1：浏览数据源
|
||
|
||
当用户想要了解有哪些数据源、数据库或表时，使用此流程。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
用户请求: "有哪些数据源？" / "看看 XX 数据源有哪些表？"
|
||
↓
|
||
1. 调用 list_datasources()
|
||
↓
|
||
2. 展示数据源列表（名称、类型、状态、数据库数、表数）
|
||
↓
|
||
3. 用户选择数据源后，调用 get_datasource_detail(datasourceId="xx")
|
||
↓
|
||
4. 展示数据库列表和实时表结构
|
||
```
|
||
|
||
### 示例
|
||
|
||
**用户**: "帮我看看有哪些数据源"
|
||
|
||
```
|
||
调用: list_datasources()
|
||
返回: [{id: "1", name: "订单系统", type: "builtin", status: 0, databases: 3, tables: 12}, ...]
|
||
回复: 共找到 3 个数据源：
|
||
- 订单系统（内置，运行中，3 个库，12 张表）
|
||
- 用户中心（外部 MySQL，运行中，1 个库，5 张表）
|
||
- 报表系统（外部 PostgreSQL，已停止）
|
||
```
|
||
|
||
**用户**: "看看订单系统有哪些表"
|
||
|
||
```
|
||
调用: get_datasource_detail(datasourceId="1")
|
||
返回: {datasource: {...}, databases: [{name: "order_db", tables: [...]}]}
|
||
回复: 订单系统包含以下数据库：
|
||
order_db:
|
||
- orders (订单表, 15 个字段)
|
||
- order_items (订单明细, 10 个字段)
|
||
- users (用户表, 8 个字段)
|
||
```
|
||
|
||
### 注意事项
|
||
- 数据源状态：`0`=运行中，`1`=已停止
|
||
- 数据源类型：`builtin`=内置，`external`=外部
|
||
- 如果用户只说"查一下数据库"，先调用 `list_datasources()` 再引导选择
|
||
|
||
---
|
||
|
||
## 场景 2：查询表数据
|
||
|
||
当用户想要查看某张表的具体数据记录时，使用此流程。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
用户请求: "查一下 users 表的数据" / "看看前 20 条订单"
|
||
↓
|
||
1. 如果不知道 tableId，先浏览数据源找到目标表
|
||
↓
|
||
2. 调用 query_table_data(tableId="xx", pageNum=1, pageSize=10, target="prod")
|
||
↓
|
||
3. 展示数据（表格形式，包含字段名和值）
|
||
↓
|
||
4. 如果数据量大，提示用户可翻页或调整 pageSize
|
||
```
|
||
|
||
### 示例
|
||
|
||
**用户**: "查一下 users 表前 10 条数据"
|
||
|
||
```
|
||
调用: query_table_data(tableId="5", pageNum=1, pageSize=10)
|
||
返回: {
|
||
columns: [{name: "id", type: "INTEGER"}, {name: "username", type: "VARCHAR"}, ...],
|
||
data: [{id: 1, username: "admin", email: "admin@test.com"}, ...],
|
||
total: 156
|
||
}
|
||
回复: users 表共 156 条记录，当前显示第 1-10 条：
|
||
| id | username | email | created_at |
|
||
|----|----------|-----------------|---------------------|
|
||
| 1 | admin | admin@test.com | 2024-01-15 10:30:00 |
|
||
| 2 | user1 | user1@test.com | 2024-01-16 14:20:00 |
|
||
...
|
||
```
|
||
|
||
### 注意事项
|
||
- `target` 参数：`prod`=生产环境，`test`=测试环境，默认 `prod`
|
||
- 如果用户未指定数量，默认 `pageSize=10`
|
||
- 数据返回格式为对象数组（已自动转换表头）
|
||
- 如果用户说"翻页"，增加 `pageNum` 参数
|
||
|
||
---
|
||
|
||
## 场景 3：执行 SQL
|
||
|
||
当用户需要执行自定义 SQL 查询时，使用此流程。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
用户请求: "帮我执行 SQL..." / "查一下订单数大于 100 的用户"
|
||
↓
|
||
1. 如果用户直接提供 SQL，直接使用
|
||
如果用户提供自然语言需求，先转换为 SQL
|
||
↓
|
||
2. 调用 execute_sql(datasourceId="xx", executableSql="SELECT ...")
|
||
↓
|
||
3. 展示查询结果
|
||
↓
|
||
4. 如果 SQL 执行失败，展示错误信息并建议修正
|
||
```
|
||
|
||
### 示例
|
||
|
||
**用户**: "统计每个地区的订单数量"
|
||
|
||
```
|
||
转换为 SQL: SELECT region, COUNT(*) as order_count FROM orders GROUP BY region ORDER BY order_count DESC
|
||
|
||
调用: execute_sql(
|
||
datasourceId="1",
|
||
executableSql="SELECT region, COUNT(*) as order_count FROM orders GROUP BY region ORDER BY order_count DESC"
|
||
)
|
||
返回: {
|
||
columns: [{name: "region"}, {name: "order_count"}],
|
||
data: [{region: "华东", order_count: 1250}, {region: "华南", order_count: 980}, ...]
|
||
}
|
||
回复: 各地区订单统计：
|
||
| 地区 | 订单数 |
|
||
|------|--------|
|
||
| 华东 | 1,250 |
|
||
| 华南 | 980 |
|
||
| 华北 | 756 |
|
||
```
|
||
|
||
### 注意事项
|
||
- `datasourceId` 必须提供，如果用户未指定，先询问或使用最近使用的数据源
|
||
- `sqlTemplate` 可选，用于模板化查询
|
||
- `parameters` 可选，用于参数化查询（防止 SQL 注入）
|
||
- 执行危险操作（DELETE/DROP/UPDATE）前，**必须**向用户确认
|
||
- 如果查询结果超过 100 行，建议用户使用 `query_table_data` 代替
|
||
|
||
---
|
||
|
||
## 场景 4：增删改数据
|
||
|
||
当用户需要修改表中的数据时，使用此流程。
|
||
|
||
### 4.1 插入数据
|
||
|
||
```
|
||
用户请求: "新增一个用户，用户名是 test_user"
|
||
↓
|
||
1. 先调用 get_table_detail(tableId="xx") 了解表结构
|
||
↓
|
||
2. 确认必填字段（非空字段、无默认值字段）
|
||
↓
|
||
3. 调用 insert_table_row(tableId="xx", data={...})
|
||
↓
|
||
4. 确认插入成功
|
||
```
|
||
|
||
**示例**:
|
||
|
||
**用户**: "新增一个用户，用户名 test_user，邮箱 test@test.com"
|
||
|
||
```
|
||
调用: get_table_detail(tableId="5")
|
||
返回: {columns: [{name: "id", isPrimaryKey: true, isAutoIncrement: true}, {name: "username", isNullable: false}, ...]}
|
||
|
||
调用: insert_table_row(
|
||
tableId="5",
|
||
data={"username": "test_user", "email": "test@test.com"}
|
||
)
|
||
回复: 已成功插入用户 test_user (ID 自动生成)
|
||
```
|
||
|
||
### 4.2 更新数据
|
||
|
||
```
|
||
用户请求: "把用户 test_user 的邮箱改成 new@test.com"
|
||
↓
|
||
1. 确认主键字段和要更新的值
|
||
↓
|
||
2. 调用 update_table_row(tableId="xx", primaryKey={主键}, data={要更新的字段})
|
||
↓
|
||
3. 确认更新成功
|
||
```
|
||
|
||
**示例**:
|
||
|
||
**用户**: "把 ID 为 5 的用户邮箱改成 new@test.com"
|
||
|
||
```
|
||
调用: update_table_row(
|
||
tableId="5",
|
||
primaryKey={"id": 5},
|
||
data={"email": "new@test.com"}
|
||
)
|
||
回复: 已更新用户 ID=5 的邮箱为 new@test.com
|
||
```
|
||
|
||
### 4.3 删除数据
|
||
|
||
```
|
||
用户请求: "删除用户 test_user"
|
||
↓
|
||
1. ⚠️ 危险操作！先确认删除范围和影响
|
||
↓
|
||
2. 向用户展示将要删除的数据，请求确认
|
||
↓
|
||
3. 用户确认后，调用 delete_table_rows(tableId="xx", primaryKeys=[{主键}])
|
||
↓
|
||
4. 确认删除成功
|
||
```
|
||
|
||
**示例**:
|
||
|
||
**用户**: "删除 ID 为 10 的订单"
|
||
|
||
```
|
||
回复: ⚠️ 确认要删除以下记录吗？
|
||
订单 ID=10, 订单号=ORD-2024-0010, 金额=¥1,250.00
|
||
此操作不可恢复。请回复"确认删除"继续。
|
||
|
||
用户: "确认删除"
|
||
|
||
调用: delete_table_rows(
|
||
tableId="3",
|
||
primaryKeys=[{"id": 10}]
|
||
)
|
||
回复: 已成功删除订单 ID=10
|
||
```
|
||
|
||
### 注意事项
|
||
- **删除操作必须二次确认**
|
||
- `primaryKey` 必须是对象格式，如 `{"id": 1}`
|
||
- `data` 只包含要更新的字段，不需要提供全部字段
|
||
- 插入数据时，自增主键不需要提供
|
||
- 如果操作涉及多行，使用批量操作或循环调用
|
||
|
||
---
|
||
|
||
## 场景 5：AI 生成表结构
|
||
|
||
当用户需要创建新表但不知道如何设计表结构时，使用 AI 辅助生成。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
用户请求: "我需要一个用户表" / "帮我设计一个订单系统的表结构"
|
||
↓
|
||
1. 调用 generate_table_by_description(requirement="用户描述")
|
||
↓
|
||
2. 展示 AI 生成的表结构（表名、字段、类型、注释）
|
||
↓
|
||
3. 用户确认后，调用 create_table(connectionId="xx", databaseName="xx", tableName="xx", columns=[...])
|
||
↓
|
||
4. 确认创建成功
|
||
```
|
||
|
||
### 示例
|
||
|
||
**用户**: "帮我设计一个商品表，包含名称、价格、库存、分类"
|
||
|
||
```
|
||
调用: generate_table_by_description(
|
||
requirement="我需要一个商品表，包含商品名称、价格、库存、分类，用于电商系统"
|
||
)
|
||
返回: {
|
||
tableName: "products",
|
||
tableComment: "商品表",
|
||
columns: [
|
||
{columnName: "id", columnType: "SERIAL", isPrimaryKey: true, isAutoIncrement: true, columnComment: "主键ID"},
|
||
{columnName: "name", columnType: "VARCHAR", columnLength: 200, isNullable: false, columnComment: "商品名称"},
|
||
{columnName: "price", columnType: "DECIMAL", columnLength: 10, columnComment: "价格"},
|
||
{columnName: "stock", columnType: "INTEGER", columnComment: "库存数量"},
|
||
{columnName: "category_id", columnType: "INTEGER", columnComment: "分类ID"},
|
||
{columnName: "created_at", columnType: "TIMESTAMP", defaultValue: "NOW()", columnComment: "创建时间"}
|
||
]
|
||
}
|
||
|
||
回复: AI 已生成表结构设计：
|
||
表名: products (商品表)
|
||
字段:
|
||
- id (SERIAL, 主键, 自增) - 主键ID
|
||
- name (VARCHAR(200), 非空) - 商品名称
|
||
- price (DECIMAL(10)) - 价格
|
||
- stock (INTEGER) - 库存数量
|
||
- category_id (INTEGER) - 分类ID
|
||
- created_at (TIMESTAMP, 默认NOW()) - 创建时间
|
||
|
||
是否需要在此基础上修改或直接创建？
|
||
|
||
用户: "直接创建到 order_db 数据库"
|
||
|
||
调用: create_table(
|
||
connectionId="1",
|
||
databaseName="order_db",
|
||
tableName="products",
|
||
tableComment="商品表",
|
||
columns=[...] // 使用 AI 生成的 columns
|
||
)
|
||
回复: 已成功创建表 products (商品表)
|
||
```
|
||
|
||
### 注意事项
|
||
- `requirement` 参数应尽可能详细，包含业务场景和字段需求
|
||
- AI 生成的表结构可能需要用户调整（如字段长度、类型）
|
||
- 创建表前需要确认 `connectionId` 和 `databaseName`
|
||
- 常用字段类型：`VARCHAR`, `INTEGER`, `SERIAL`(自增主键), `DECIMAL`, `TIMESTAMP`, `TEXT`, `BOOLEAN`
|
||
- 如果用户描述模糊，先引导用户补充细节
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 始终确认环境
|
||
- 默认使用 `prod`（生产环境）
|
||
- 如果用户提到"测试"或"测试环境"，使用 `target="test"`
|
||
- 执行危险操作前，明确告知用户当前环境
|
||
|
||
### 2. 提供上下文
|
||
- 展示数据时，包含字段名和类型
|
||
- 执行操作后，告知影响的行数或具体变化
|
||
- 错误时，提供清晰的错误信息和建议
|
||
|
||
### 3. 分步引导
|
||
- 如果用户请求不完整（如未指定数据源），先引导补充信息
|
||
- 复杂操作分步执行，每步确认后继续
|
||
- 对于多表操作，先展示整体计划
|
||
|
||
### 4. 数据展示
|
||
- 表格数据使用 Markdown 表格格式
|
||
- 长文本截断显示（最多 100 字符）
|
||
- 数字格式化（千位分隔符、货币符号）
|
||
- 时间格式化为可读格式
|
||
|
||
### 5. 错误处理
|
||
- API 错误：展示错误信息，建议重试或检查参数
|
||
- SQL 错误：展示 SQL 错误位置，建议修正
|
||
- 连接错误：检查数据源状态，建议启用或重新配置
|
||
|
||
---
|
||
|
||
## 常用参数参考
|
||
|
||
### 数据源类型
|
||
- `builtin` - 内置 PostgreSQL
|
||
- `external` - 外部数据库（MySQL/PostgreSQL/Oracle/SQL Server 等）
|
||
|
||
### 数据源状态
|
||
- `0` - 运行中
|
||
- `1` - 已停止
|
||
|
||
### 环境
|
||
- `prod` - 生产环境（默认）
|
||
- `test` - 测试环境
|
||
|
||
### 常用字段类型
|
||
| 类型 | 用途 | 示例 |
|
||
|------|------|------|
|
||
| `SERIAL` | 自增主键 | `id SERIAL PRIMARY KEY` |
|
||
| `VARCHAR(n)` | 短文本 | `username VARCHAR(50)` |
|
||
| `TEXT` | 长文本 | `description TEXT` |
|
||
| `INTEGER` | 整数 | `stock INTEGER` |
|
||
| `DECIMAL(m,n)` | 精确小数 | `price DECIMAL(10,2)` |
|
||
| `TIMESTAMP` | 时间戳 | `created_at TIMESTAMP` |
|
||
| `BOOLEAN` | 布尔值 | `is_active BOOLEAN` |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
如果用户说"帮我查一下数据库"，按以下步骤操作：
|
||
|
||
1. 调用 `list_datasources()` 获取数据源列表
|
||
2. 展示列表，让用户选择或默认第一个运行中的数据源
|
||
3. 调用 `get_datasource_detail(datasourceId="xx")` 获取数据库和表信息
|
||
4. 引导用户选择要操作的表
|
||
5. 根据用户意图调用相应的工具（查询/执行 SQL/增删改）
|
||
```
|
||
|
||
## 实施步骤
|
||
|
||
1. 创建目录 `.kilo/skills/lzwcai-agile-db/`
|
||
2. 创建文件 `SKILL.md` 并写入上述内容
|
||
3. 验证 skill 文件格式正确
|
||
|
||
## 验证
|
||
|
||
创建完成后，skill 应该可以被 Kilo 自动识别和加载。
|