yuanzhipeng
557361632c
新增 lzwcai-agile-db 技能文件，为 AI Agent 提供 AgileDB 数据库操作的场景化工作流指导。 该技能支持数据源浏览、表数据 CRUD、SQL 执行和 AI 生成表结构等功能，包含完整的工具列表和使用场景。
894 lines
26 KiB
Markdown
894 lines
26 KiB
Markdown
---
|
||
name: lzwcai-agile-db
|
||
description: AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据库操作工作流指导，适合零基础用户。
|
||
version: 0.2.0
|
||
---
|
||
|
||
# lzwcai-agile-db
|
||
|
||
AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据库操作工作流指导，适合零基础用户。
|
||
|
||
|
||
## 完整工具清单（33 个工具）
|
||
|
||
本 skill 基于 `lzwcai_mcp_agile_db` MCP Server，共提供 33 个工具，分为 9 大类：
|
||
|
||
### 一、数据源管理（6 个工具）
|
||
|
||
| 工具 | 功能 | 危险等级 |
|
||
|------|------|----------|
|
||
| `list_datasources` | 获取数据源列表 | 安全 |
|
||
| `get_datasource_detail` | 获取数据源详情（含数据库、表结构） | 安全 |
|
||
| `create_datasource` | 创建外部数据源连接 | 安全 |
|
||
| `update_datasource` | 更新数据源连接信息 | 中等 |
|
||
| `toggle_datasource_status` | 启用/停用数据源 | 中等 |
|
||
| `delete_datasource` | 删除数据源 | **危险** |
|
||
|
||
### 二、数据库与表管理（6 个工具）
|
||
|
||
| 工具 | 功能 | 危险等级 |
|
||
|------|------|----------|
|
||
| `list_databases` | 获取数据源下的数据库列表 | 安全 |
|
||
| `list_tables` | 获取数据源下的表列表 | 安全 |
|
||
| `get_table_detail` | 获取表结构详情（字段、类型、主键） | 安全 |
|
||
| `create_table` | 创建新表 | **危险** |
|
||
| `alter_table` | 修改表结构 | **危险** |
|
||
| `generate_table_by_description` | AI 根据自然语言生成表结构 | 安全（仅生成，不创建） |
|
||
|
||
### 三、表数据 CRUD（5 个工具）
|
||
|
||
| 工具 | 功能 | 危险等级 |
|
||
|------|------|----------|
|
||
| `query_table_data` | 查询表数据（分页） | 安全 |
|
||
| `insert_table_row` | 插入一行数据 | 中等 |
|
||
| `update_table_row` | 更新一行数据 | 中等 |
|
||
| `delete_table_rows` | 删除数据行（按主键） | **危险** |
|
||
| `export_table_excel` | 导出表数据为 Excel（base64） | 安全 |
|
||
|
||
### 四、SQL 执行（1 个工具）
|
||
|
||
| 工具 | 功能 | 危险等级 |
|
||
|------|------|----------|
|
||
| `execute_sql` | 执行原生 SQL 查询 | 中等/危险 |
|
||
|
||
### 五、数据导入（2 个工具）
|
||
|
||
| 工具 | 功能 | 危险等级 |
|
||
|------|------|----------|
|
||
| `preview_import_data` | 上传 Excel 文件，AI 智能识别并预览 | 安全 |
|
||
| `confirm_import_data` | 确认导入 AI 识别后的数据 | **危险** |
|
||
|
||
### 六、表订阅（1 个工具）
|
||
|
||
| 工具 | 功能 | 危险等级 |
|
||
|------|------|----------|
|
||
| `toggle_table_subscription` | 切换表的订阅状态 | 中等 |
|
||
|
||
### 七、API 密钥管理（6 个工具）
|
||
|
||
| 工具 | 功能 | 危险等级 |
|
||
|------|------|----------|
|
||
| `list_api_keys` | 获取 API 密钥列表 | 安全 |
|
||
| `create_api_key` | 创建新的 API 密钥 | 中等 |
|
||
| `toggle_api_key_status` | 启用/禁用 API 密钥 | 中等 |
|
||
| `delete_api_key` | 删除 API 密钥 | **危险** |
|
||
| `get_api_key_permissions` | 查看指定密钥的权限配置 | 安全 |
|
||
| `grant_api_key_permissions` | 批量为 API 密钥授予权限 | **危险** |
|
||
|
||
### 八、技能与工具管理（6 个工具）
|
||
|
||
| 工具 | 功能 | 危险等级 |
|
||
|------|------|----------|
|
||
| `get_skill_by_datasource` | 根据数据源获取技能信息 | 安全 |
|
||
| `get_skill_tools` | 获取技能下的工具列表 | 安全 |
|
||
| `create_skill` | 为数据源创建技能 | 中等 |
|
||
| `create_sql_tool` | 将 SQL 查询创建为可复用工具 | 中等 |
|
||
| `delete_skill_tool` | 删除技能下的工具 | **危险** |
|
||
| `update_skill_config` | 更新技能配置 | 中等 |
|
||
|
||
---
|
||
|
||
## 核心概念说明
|
||
|
||
### 数据源是什么？
|
||
|
||
数据源 = 一个数据库连接。它可以是：
|
||
- `builtin`：内置 PostgreSQL 数据库（系统自带）
|
||
- `external`：外部数据库（MySQL、PostgreSQL、Oracle、SQL Server、达梦等）
|
||
|
||
### 数据源状态
|
||
|
||
- `0` = 运行中（正常）
|
||
- `1` = 已停止（不可用）
|
||
|
||
### 环境参数 `target`
|
||
|
||
- `prod` = 生产环境（正式数据，默认值）
|
||
- `test` = 测试环境（测试数据）
|
||
|
||
### 主键 `primaryKey`
|
||
|
||
主键是唯一标识一行数据的字段。例如 `{"id": 1}` 表示删除/更新 id=1 的那行数据。
|
||
|
||
### `connectionId` vs `datasourceId`
|
||
|
||
- `datasourceId`：用于数据源列表、数据库列表、表列表等浏览类操作
|
||
- `connectionId`：用于创建表、修改表、数据导入等需要直接操作连接的操作
|
||
- 两者通常指向同一个东西，但 API 设计不同，请按照工具说明使用
|
||
|
||
---
|
||
|
||
## ⚠️ 安全确认原则（必须遵守）
|
||
|
||
### 一、执行工具前的风险评估
|
||
|
||
当执行以下类型的操作时，**必须先询问用户确认**，不得擅作主张：
|
||
|
||
1. **删除操作**：删除数据源、删除表数据、删除 API 密钥、删除技能工具等
|
||
- 说明：此操作不可恢复，数据将永久丢失
|
||
|
||
2. **泄密风险操作**：导出包含敏感数据的表、创建 API 密钥、查看密钥详情等
|
||
- 说明：可能导致敏感信息泄露，需确认用户授权
|
||
|
||
3. **政治敏感操作**：涉及政治相关数据的查询、修改、删除等
|
||
- 说明：可能涉及合规风险，需确认用户意图
|
||
|
||
4. **疑似违规内容**：涉及色情、暴力、违法等内容的操作
|
||
- 说明：可能违反法律法规，必须拒绝执行并告知用户
|
||
|
||
#### 确认格式
|
||
|
||
执行上述操作前，必须使用以下格式向用户确认：
|
||
|
||
```
|
||
⚠️ 安全提醒：此操作存在 [具体风险类型] 风险。
|
||
具体说明：[说明可能的后果]
|
||
请确认是否继续？（回复"确认"继续，或取消操作）
|
||
```
|
||
|
||
**只有在用户明确确认后才能继续执行。**
|
||
|
||
---
|
||
|
||
### 二、多步骤场景必须逐步确认
|
||
|
||
当完成任务需要调用多个工具时（如：先查询表结构 → 插入数据 → 确认结果），**不得一次性自动连续执行**：
|
||
|
||
1. **每完成一步后暂停**，向用户展示当前步骤的结果
|
||
2. **询问用户是否继续下一步**，等待确认后再执行
|
||
3. **不要假设用户的意图**，即使用户的请求看似明确，也需要分步确认
|
||
|
||
**示例**：
|
||
```
|
||
用户："帮我新增一个用户"
|
||
|
||
❌ 错误做法：自动调用 get_table_detail → insert_table_row → 返回结果（一次性执行完）
|
||
|
||
✅ 正确做法：
|
||
1. 调用 get_table_detail 了解表结构
|
||
2. 展示必填字段清单，询问用户："请提供以下必填字段的值：..."
|
||
3. 用户回复后，展示将要插入的数据预览
|
||
4. 询问："确认插入以上数据？"
|
||
5. 用户确认后才调用 insert_table_row
|
||
```
|
||
|
||
---
|
||
|
||
### 三、遇到多项选择时必须询问用户
|
||
|
||
当执行任务过程中遇到需要选择的场景时，**AI 不得擅自做主选择**：
|
||
|
||
1. **列出所有可选方案**，说明每个方案的优缺点或适用场景
|
||
2. **等待用户明确选择**，不要猜测用户意图
|
||
3. **不要默认选择第一个**或看似最合理的选项
|
||
|
||
#### 常见需要询问的选择场景：
|
||
- 有多个数据源可选时
|
||
- 有多个数据库可选时
|
||
- 有多个表可选时
|
||
- 有多种操作方式可选时（如：用 SQL 查询 vs 用表数据查询工具）
|
||
- 有多种字段类型可选时
|
||
- 用户描述模糊，存在多种理解方式时
|
||
|
||
**示例**：
|
||
```
|
||
用户："查一下订单数据"
|
||
|
||
❌ 错误做法：直接选择第一个数据源和第一个订单表进行查询
|
||
|
||
✅ 正确做法：
|
||
"找到以下数据源包含订单相关表：
|
||
1. HMD产品 → order_db → orders 表（156 条记录）
|
||
2. 测试数据源 → test_db → test_orders 表（10 条记录）
|
||
请问您想查询哪个？"
|
||
```
|
||
|
||
---
|
||
|
||
## 场景 1：浏览数据源（新手入门第一步）
|
||
|
||
当用户想了解系统里有哪些数据库或表时，使用此流程。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
用户请求: "有哪些数据源？" / "看看 XX 数据源有哪些表？" / "帮我查一下数据库"
|
||
↓
|
||
1. 调用 list_datasources()
|
||
↓
|
||
2. 展示数据源列表（名称、类型、状态、数据库数、表数）
|
||
↓
|
||
3. 用户选择数据源后，调用 get_datasource_detail(datasourceId="xx")
|
||
↓
|
||
4. 展示数据库列表和实时表结构
|
||
```
|
||
|
||
### 示例
|
||
|
||
**用户**: "帮我看看有哪些数据源"
|
||
|
||
```
|
||
调用: list_datasources()
|
||
返回: {
|
||
"total": 14,
|
||
"rows": [
|
||
{"id": "58", "datasourceName": "HMD产品", "host": "host.docker.internal", "port": 5432, "status": 0, ...},
|
||
...
|
||
]
|
||
}
|
||
回复: 共找到 14 个数据源：
|
||
1. HMD产品（PostgreSQL, host.docker.internal:5432, 运行中）
|
||
2. ...
|
||
请告诉我你想看哪个数据源？
|
||
```
|
||
|
||
**用户**: "看看 HMD 产品有哪些表"
|
||
|
||
```
|
||
调用: get_datasource_detail(datasourceId="58")
|
||
返回: {
|
||
"detail": {...},
|
||
"config": {...},
|
||
"structure": {
|
||
"databases": [
|
||
{"name": "order_db", "tables": [
|
||
{"tableName": "orders", "columns": [...]},
|
||
...
|
||
]}
|
||
]
|
||
}
|
||
}
|
||
回复: HMD产品 数据源包含以下数据库和表：
|
||
order_db:
|
||
- orders (订单表, 15 个字段)
|
||
- users (用户表, 8 个字段)
|
||
```
|
||
|
||
### 注意事项
|
||
- 数据源类型为 `builtin` 表示系统内置数据库，类型为具体的数据库引擎名称（mysql、postgresql 等）表示外部数据源
|
||
- 如果用户只说"查一下数据库"，先调用 `list_datasources()` 再引导选择
|
||
- 已停止的数据源（status=1）无法访问其结构
|
||
|
||
---
|
||
|
||
## 场景 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`=测试环境
|
||
- 如果用户未指定数量，默认 `pageSize=10`
|
||
- 如果用户说"翻页"，增加 `pageNum` 参数
|
||
- 如果用户想看更多数据，可以增大 `pageSize`（最大根据 API 限制）
|
||
- 数据返回格式为对象数组
|
||
|
||
---
|
||
|
||
## 场景 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="58",
|
||
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/TRUNCATE）前，必须向用户确认**
|
||
- 如果查询结果超过 100 行，建议用户使用 `query_table_data` 代替
|
||
- 对于只读查询（SELECT），可以直接执行；对于写操作（INSERT/UPDATE/DELETE），必须二次确认
|
||
|
||
---
|
||
|
||
## 场景 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. 向用户展示将要删除的数据，请求确认
|
||
↓
|
||
4. 用户确认后，调用 delete_table_rows(tableId="xx", primaryKeys=[{主键}])
|
||
↓
|
||
5. 确认删除成功
|
||
```
|
||
|
||
**示例**:
|
||
|
||
**用户**: "删除 ID 为 10 的订单"
|
||
|
||
```
|
||
回复: ⚠️ 确认要删除以下记录吗？
|
||
订单 ID=10, 订单号=ORD-2024-0010, 金额=¥1,250.00
|
||
此操作不可恢复。请回复"确认删除"继续。
|
||
|
||
用户: "确认删除"
|
||
|
||
调用: delete_table_rows(
|
||
tableId="3",
|
||
primaryKeys=[{"id": 10}]
|
||
)
|
||
回复: 已成功删除订单 ID=10
|
||
```
|
||
|
||
**注意：如果删除内容涉及敏感数据（如用户隐私、政治相关内容、疑似违规内容），必须额外说明后果并再次确认。**
|
||
|
||
### 4.4 导出表数据为 Excel
|
||
|
||
```
|
||
用户请求: "把 users 表数据导出成 Excel"
|
||
↓
|
||
1. 调用 export_table_excel(tableId="xx", target="prod")
|
||
↓
|
||
2. 返回 base64 编码的 Excel 文件内容
|
||
↓
|
||
3. 提示用户解码 base64 获取文件
|
||
```
|
||
|
||
**示例**:
|
||
|
||
```
|
||
调用: export_table_excel(tableId="5")
|
||
返回: {
|
||
"success": true,
|
||
"file_base64": "UEsDBBQAAAAI...",
|
||
"message": "Excel 文件已导出，请解码 base64 内容获取文件"
|
||
}
|
||
回复: 已成功导出 users 表数据为 Excel 文件
|
||
文件内容已 base64 编码，请解码后保存为 .xlsx 文件
|
||
```
|
||
|
||
### 注意事项
|
||
- **删除操作必须二次确认**
|
||
- `primaryKey` 必须是对象格式，如 `{"id": 1}`
|
||
- `primaryKeys` 是数组格式，如 `[{"id": 1}, {"id": 2}]`
|
||
- `data` 只包含要更新的字段，不需要提供全部字段
|
||
- 插入数据时，自增主键不需要提供
|
||
- 如果操作涉及多行，使用批量操作或循环调用
|
||
- 增删改操作默认作用于 `prod` 环境
|
||
|
||
---
|
||
|
||
## 场景 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="58",
|
||
databaseName="order_db",
|
||
tableName="products",
|
||
tableComment="商品表",
|
||
columns=[...] // 使用 AI 生成的 columns
|
||
)
|
||
回复: 已成功创建表 products (商品表)
|
||
```
|
||
|
||
### 修改表结构（alter_table）
|
||
|
||
如果用户需要修改已有表的结构：
|
||
|
||
```
|
||
用户请求: "给 users 表加一个 phone 字段"
|
||
↓
|
||
1. 确认表结构和要修改的内容
|
||
↓
|
||
2. 构建 operations 数组（支持多种变更类型）
|
||
↓
|
||
3. 调用 alter_table(connectionId="xx", databaseName="xx", tableName="xx", operations=[...])
|
||
↓
|
||
4. 确认修改成功
|
||
```
|
||
|
||
**可用的 operations 类型**：
|
||
- `ADD_COLUMN`：添加字段
|
||
- `DROP_COLUMN`：删除字段
|
||
- `RENAME_COLUMN`：重命名字段
|
||
- `ALTER_COLUMN_TYPE`：修改字段类型
|
||
- `SET_NOT_NULL`：设置为非空
|
||
- `DROP_NOT_NULL`：取消非空约束
|
||
- `SET_DEFAULT`：设置默认值
|
||
- `DROP_DEFAULT`：删除默认值
|
||
|
||
### 注意事项
|
||
- `requirement` 参数应尽可能详细，包含业务场景和字段需求
|
||
- AI 生成的表结构可能需要用户调整（如字段长度、类型）
|
||
- 创建表前需要确认 `connectionId` 和 `databaseName`
|
||
- 常用字段类型：`VARCHAR`, `INTEGER`, `SERIAL`(自增主键), `DECIMAL`, `TIMESTAMP`, `TEXT`, `BOOLEAN`
|
||
- 如果用户描述模糊，先引导用户补充细节
|
||
|
||
---
|
||
|
||
## 场景 6：数据导入（Excel 到数据库）
|
||
|
||
当用户需要从 Excel 文件导入数据到数据库时，使用此流程。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
用户请求: "帮我导入这个 Excel 文件" / "把表格数据导入数据库"
|
||
↓
|
||
1. 用户将 Excel 文件转为 base64 编码
|
||
↓
|
||
2. 调用 preview_import_data(connectionId="xx", file_base64="...", file_name="data.xlsx", target="test")
|
||
↓
|
||
3. 展示 AI 识别的表结构和数据预览
|
||
↓
|
||
4. ⚠️ 安全提醒：此操作可能涉及数据安全风险。
|
||
说明：导入的数据将写入数据库，请确认数据来源合法合规，不包含敏感信息、政治内容或违规内容。
|
||
请确认是否继续？
|
||
↓
|
||
5. 用户确认无误后，调用 confirm_import_data(connectionId="xx", data={...}, target="test")
|
||
↓
|
||
6. 确认导入成功
|
||
```
|
||
|
||
### 注意事项
|
||
- 文件大小限制：< 500KB
|
||
- 支持格式：.xlsx / .xls
|
||
- 导入前默认使用 `test` 环境（安全做法）
|
||
- 如果用户要导入到正式环境，必须二次确认
|
||
- base64 编码的文件内容需要提供文件名
|
||
|
||
---
|
||
|
||
## 场景 7：API 密钥管理
|
||
|
||
当用户需要管理 API 密钥时，使用此流程。
|
||
|
||
### 7.1 查看密钥列表
|
||
|
||
```
|
||
调用: list_api_keys()
|
||
返回: {
|
||
"total": 6,
|
||
"rows": [
|
||
{"id": "7", "apiKeyName": "AWINBEXT", "apiKey": "Lb8Lg...", "status": 0, "expireTime": "2027-06-06..."},
|
||
...
|
||
]
|
||
}
|
||
```
|
||
|
||
### 7.2 创建新密钥
|
||
|
||
```
|
||
调用: create_api_key(apiKeyName="新密钥名称")
|
||
返回: 包含新创建的密钥信息
|
||
```
|
||
|
||
### 7.3 启用/禁用密钥
|
||
|
||
```
|
||
调用: toggle_api_key_status(id="7", status=0) // 0=启用, 1=禁用
|
||
```
|
||
|
||
### 7.4 删除密钥
|
||
|
||
```
|
||
⚠️ 删除前确认：
|
||
⚠️ 安全提醒：此操作存在删除风险。
|
||
说明：API 密钥删除后不可恢复，依赖该密钥的服务将失效。
|
||
请确认是否继续？
|
||
|
||
回复: 确认要删除 API 密钥 "AWINBEXT" 吗？此操作不可恢复。
|
||
|
||
调用: delete_api_key(id="7")
|
||
```
|
||
|
||
### 7.5 查看密钥权限
|
||
|
||
```
|
||
调用: get_api_key_permissions(apiKeyId="7")
|
||
```
|
||
|
||
### 7.6 批量授权
|
||
|
||
```
|
||
调用: grant_api_key_permissions(
|
||
apiKeyId="7",
|
||
batchDatas=[
|
||
{
|
||
"connectionId": "58",
|
||
"permissionLevel": "connection",
|
||
"permissionType": "read,write"
|
||
},
|
||
{
|
||
"connectionId": "58",
|
||
"permissionLevel": "database",
|
||
"databaseName": "order_db",
|
||
"permissionType": "read"
|
||
}
|
||
]
|
||
)
|
||
```
|
||
|
||
权限级别说明：
|
||
- `connection`：数据源级别权限
|
||
- `database`：数据库级别权限
|
||
- `table`：表级别权限
|
||
|
||
---
|
||
|
||
## 场景 8：技能与工具管理
|
||
|
||
当用户需要创建和管理自定义技能时，使用此流程。
|
||
|
||
### 8.1 查看数据源关联的技能
|
||
|
||
```
|
||
调用: get_skill_by_datasource(datasourceId="58")
|
||
```
|
||
|
||
### 8.2 创建技能
|
||
|
||
```
|
||
调用: create_skill(datasourceId="58", name="订单查询技能", description="用于订单数据的常用查询")
|
||
```
|
||
|
||
### 8.3 查看技能下的工具
|
||
|
||
```
|
||
调用: get_skill_tools(skillId="xx")
|
||
```
|
||
|
||
### 8.4 将 SQL 创建为可复用工具
|
||
|
||
```
|
||
调用: create_sql_tool(
|
||
skillId="xx",
|
||
tableIds=["5"],
|
||
suggestions=[{
|
||
"name": "查询活跃用户",
|
||
"businessDescription": "查询所有状态为活跃的用户",
|
||
"sqlTemplate": "SELECT * FROM users WHERE status = #{status}",
|
||
"sqlParams": {"status": {"type": "string", "default": "active"}},
|
||
"resultType": "list",
|
||
"businessScenario": "用于查看当前活跃用户列表"
|
||
}]
|
||
)
|
||
```
|
||
|
||
### 8.5 删除技能工具
|
||
|
||
```
|
||
⚠️ 删除前确认：
|
||
⚠️ 安全提醒：此操作存在删除风险。
|
||
说明：技能工具删除后不可恢复。
|
||
请确认是否继续？
|
||
|
||
调用: delete_skill_tool(skillToolId="xx")
|
||
```
|
||
|
||
### 8.6 更新技能配置
|
||
|
||
```
|
||
调用: update_skill_config(
|
||
datasourceId="58",
|
||
configTemplate='{"mcpServer": "..."}' // JSON 字符串
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 场景 9：表订阅管理
|
||
|
||
```
|
||
用户请求: "订阅 orders 表" / "取消订阅 users 表"
|
||
|
||
调用: toggle_table_subscription(
|
||
configId="数据库配置ID",
|
||
tableName="orders",
|
||
isSubscribe=true // true=订阅, false=取消订阅
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 安全第一
|
||
|
||
#### 通用安全确认规则
|
||
|
||
- 执行任何工具前，评估是否存在删除、泄密、政治敏感、似黄等风险
|
||
- 存在风险时，**必须询问用户确认**，说明后果，不得擅作主张
|
||
- 用户未明确确认前，不得执行
|
||
|
||
- 执行任何写操作（INSERT/UPDATE/DELETE）前，先确认环境（prod vs test）
|
||
- 删除操作必须向用户展示将要删除的数据并二次确认
|
||
- 危险操作（DELETE/DROP/TRUNCATE/UPDATE 影响多行）前必须明确告知用户风险
|
||
- 数据导入时默认使用 `test` 环境
|
||
|
||
### 2. 分步引导
|
||
|
||
- 新手可能不知道 `datasourceId`、`tableId` 等参数，先通过列表工具引导获取
|
||
- 复杂操作分步执行，每步确认后继续
|
||
- 如果用户请求不完整（如未指定数据源），先引导补充信息
|
||
|
||
### 3. 数据展示
|
||
|
||
- 表格数据使用 Markdown 表格格式
|
||
- 长文本截断显示（最多 100 字符）
|
||
- 数字格式化（千位分隔符、货币符号）
|
||
- 时间格式化为可读格式
|
||
- 展示数据时包含字段名和类型
|
||
|
||
### 4. 错误处理
|
||
|
||
- API 错误：展示错误信息，建议重试或检查参数
|
||
- SQL 错误：展示 SQL 错误位置，建议修正
|
||
- 连接错误：检查数据源状态，建议启用或重新配置
|
||
- "登录过期"：提示用户检查 `API_KEY` 环境变量
|
||
|
||
### 5. 沟通方式
|
||
|
||
- 向小白用户解释时，避免使用技术术语（如 JSON Schema、SERIAL 等），用通俗语言
|
||
- 操作完成后告知结果（成功/失败/影响行数）
|
||
- 如果用户操作成功，给出明确的反馈信息
|
||
|
||
---
|
||
|
||
## 常用参数参考
|
||
|
||
### 数据源类型
|
||
- `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` |
|
||
|
||
### 表结构变更操作类型（alter_table）
|
||
| 类型 | 用途 |
|
||
|------|------|
|
||
| `ADD_COLUMN` | 添加字段 |
|
||
| `DROP_COLUMN` | 删除字段 |
|
||
| `RENAME_COLUMN` | 重命名字段 |
|
||
| `ALTER_COLUMN_TYPE` | 修改字段类型 |
|
||
| `SET_NOT_NULL` | 设置为非空 |
|
||
| `DROP_NOT_NULL` | 取消非空约束 |
|
||
| `SET_DEFAULT` | 设置默认值 |
|
||
| `DROP_DEFAULT` | 删除默认值 |
|
||
|
||
### 权限级别（API 密钥授权）
|
||
| 级别 | 范围 |
|
||
|------|------|
|
||
| `connection` | 整个数据源 |
|
||
| `database` | 指定数据库 |
|
||
| `table` | 指定表 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
如果用户说"帮我查一下数据库"，按以下步骤操作：
|
||
|
||
1. 调用 `list_datasources()` 获取数据源列表
|
||
2. 展示列表，让用户选择或默认第一个运行中的数据源
|
||
3. 调用 `get_datasource_detail(datasourceId="xx")` 获取数据库和表信息
|
||
4. 引导用户选择要操作的表
|
||
5. 根据用户意图调用相应的工具：
|
||
- 想看数据 → `query_table_data`
|
||
- 想执行 SQL → `execute_sql`
|
||
- 想新增数据 → `insert_table_row`
|
||
- 想修改数据 → `update_table_row`
|
||
- 想删除数据 → `delete_table_rows`（需确认）
|
||
- 想导出 Excel → `export_table_excel`
|
||
- 想创建表 → `generate_table_by_description` + `create_table`
|
||
- 想导入 Excel → `preview_import_data` + `confirm_import_data`
|