feat(.kilo): 新增 AgileDB 数据库操作技能
新增 lzwcai-agile-db 技能文件，为 AI Agent 提供 AgileDB 数据库操作的场景化工作流指导。 该技能支持数据源浏览、表数据 CRUD、SQL 执行和 AI 生成表结构等功能，包含完整的工具列表和使用场景。
This commit is contained in:
356
.kilo/skills/mcp-tool-testing/SKILL.md
Normal file
356
.kilo/skills/mcp-tool-testing/SKILL.md
Normal file
@@ -0,0 +1,356 @@
|
||||
---
|
||||
name: mcp-tool-testing
|
||||
description: MCP 工具通用测试技能。自动发现、执行和组合测试任何 MCP 服务器中的工具，支持场景自动创造和风险前置询问。
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
# MCP Tool Testing Skill
|
||||
|
||||
这是一个通用的 MCP（Model Context Protocol）工具测试技能。适用于任何 MCP 环境，无论是自研的还是第三方的。
|
||||
|
||||
## 核心原则
|
||||
|
||||
1. **通用性**：不假设任何具体的服务器名称、工具名称或项目结构
|
||||
2. **自动发现**：通过 MCP 协议本身获取当前环境中可用的所有工具
|
||||
3. **智能执行**：能判断的入参自动执行，不能判断的询问用户
|
||||
4. **场景自动创造**：根据工具自动匹配并创造测试场景，无需用户指定
|
||||
5. **风险前置**：有风险的操作必须询问用户确认，绝不擅作主张
|
||||
6. **结果汇总**：最终只返回执行工具的入参、出参和理解
|
||||
|
||||
## 执行流程
|
||||
|
||||
### 第一步：发现可用工具
|
||||
|
||||
通过 MCP 的 `tools/list` 方法获取当前环境中所有可用的工具。
|
||||
|
||||
**获取每个工具的信息：**
|
||||
- 工具名称（name）
|
||||
- 工具描述（description）
|
||||
- 入参 schema（inputSchema）：
|
||||
- 参数名称
|
||||
- 参数类型（string, integer, boolean, object, array, enum 等）
|
||||
- 是否必填（required）
|
||||
- 默认值（default）
|
||||
- 枚举值（enum）
|
||||
- 参数描述（description）
|
||||
|
||||
### 第二步：分析工具并分类
|
||||
|
||||
根据工具名称和描述，自动对工具进行分类：
|
||||
|
||||
1. **查询类**：list_xxx, get_xxx, query_xxx, search_xxx, find_xxx
|
||||
2. **创建类**：create_xxx, add_xxx, insert_xxx, new_xxx
|
||||
3. **更新类**：update_xxx, edit_xxx, modify_xxx, alter_xxx
|
||||
4. **删除类**：delete_xxx, remove_xxx, drop_xxx
|
||||
5. **执行类**：execute_xxx, run_xxx, call_xxx, invoke_xxx
|
||||
6. **状态类**：toggle_xxx, enable_xxx, disable_xxx, start_xxx, stop_xxx
|
||||
7. **其他**：无法归类的工具
|
||||
|
||||
### 第三步：执行单个工具
|
||||
|
||||
对每个工具，按以下策略执行：
|
||||
|
||||
#### 入参判断逻辑
|
||||
|
||||
```
|
||||
对于每个必填参数（required 中的参数）：
|
||||
1. schema 有 default 值 → 使用该默认值
|
||||
2. schema 有 enum 且只有一个值 → 使用该值
|
||||
3. schema 有 enum 且有多个值 → 使用第一个，或询问用户
|
||||
4. 参数名是常见的通用类型：
|
||||
- pageNum, page, offset → 使用 1
|
||||
- pageSize, limit, size → 使用 10
|
||||
- target, environment → 使用 "prod" 或第一个 enum 值
|
||||
- status, enabled → 使用 0 或 true
|
||||
- name, title → 使用测试名称如 "test_item"
|
||||
- id, xxxId → 需要从其他工具查询获取，或询问用户
|
||||
5. 可以从之前执行的工具结果中获取 → 使用前一个工具的输出
|
||||
6. 以上都不满足 → 询问用户
|
||||
|
||||
对于非必填参数：
|
||||
- 一般不传，使用服务器默认值
|
||||
- 如果需要测试特定功能，可以传一个合理值
|
||||
```
|
||||
|
||||
#### 询问用户的标准
|
||||
|
||||
当遇到以下情况时必须询问：
|
||||
|
||||
**1. 参数不明确**
|
||||
- 参数是必填的，且值完全不明确
|
||||
- 例如：某个特定的业务 ID、密钥、路径等
|
||||
|
||||
**2. 参数有多个合理选项且无法自动判断**
|
||||
- 例如：enum 有 ["mysql", "postgresql", "oracle"]，不知道测试用哪个
|
||||
|
||||
**3. 参数涉及敏感信息**
|
||||
- 例如：password, token, apiKey, secret 等
|
||||
|
||||
**4. 高风险操作必须询问（绝不擅作主张）**
|
||||
|
||||
以下类型的工具/操作在执行前必须先询问用户确认：
|
||||
|
||||
- **删除类**：delete_xxx, remove_xxx, drop_xxx, destroy_xxx
|
||||
- 风险：数据丢失，不可恢复
|
||||
- 询问内容：确认是否要执行删除操作，指定删除目标或使用测试数据
|
||||
|
||||
- **泄密风险类**：export_xxx, dump_xxx, download_xxx, get_all_xxx（大量数据）
|
||||
- 风险：可能导出敏感业务数据、用户信息、密钥等
|
||||
- 询问内容：确认是否要导出数据，是否使用脱敏测试数据
|
||||
|
||||
- **政治敏感类**：涉及政府、政策、领导人等相关内容的工具
|
||||
- 风险：可能触及政治敏感话题
|
||||
- 询问内容：确认测试方向和范围
|
||||
|
||||
- **似黄/色情风险类**：涉及用户生成内容、图片、文本审核等相关工具
|
||||
- 风险：可能接触到不当内容
|
||||
- 询问内容：确认是否使用安全的测试数据
|
||||
|
||||
- **生产环境操作类**：影响生产环境数据的工具
|
||||
- 风险：可能影响真实业务
|
||||
- 询问内容：确认是否在测试环境执行，或使用只读模式
|
||||
|
||||
**5. 更新/修改类操作需要确认**
|
||||
- 例如：update_xxx, modify_xxx 可能改变真实数据
|
||||
|
||||
**高风险操作询问格式：**
|
||||
|
||||
```
|
||||
⚠️ 高风险操作提醒
|
||||
|
||||
工具：[工具名]
|
||||
风险类型：[删除/泄密/政治敏感/似黄/生产环境影响]
|
||||
具体风险：[描述可能的风险]
|
||||
|
||||
请选择：
|
||||
1. 确认执行，使用测试数据
|
||||
2. 确认执行，使用真实数据（我知道风险）
|
||||
3. 跳过此工具
|
||||
4. 其他指示
|
||||
```
|
||||
|
||||
**普通询问格式：**
|
||||
|
||||
```
|
||||
工具：[工具名]
|
||||
参数：[参数名]（类型：[类型]，必填：是/否）
|
||||
用途：[从 description 中提取]
|
||||
|
||||
请选择：
|
||||
1. [建议选项1，如果有]
|
||||
2. [建议选项2，如果有]
|
||||
3. 提供自定义值
|
||||
|
||||
或者告诉我使用什么值。
|
||||
```
|
||||
|
||||
#### 执行顺序策略
|
||||
|
||||
1. **先执行无参数或少参数的查询工具**
|
||||
- 如 list_xxx、get_all_xxx 等
|
||||
- 这些工具通常不需要太多参数，可以直接执行
|
||||
- 执行结果可以为后续工具提供 ID 等参数
|
||||
|
||||
2. **利用查询结果作为后续工具的入参**
|
||||
- 例如：list_datasources 返回的 id 用于 get_datasource_detail
|
||||
- 例如：list_tables 返回的 tableId 用于 query_table_data
|
||||
|
||||
3. **最后执行创建/修改/删除类工具**
|
||||
- 这些通常需要更多上下文参数
|
||||
- 删除操作要特别小心，确认是测试数据
|
||||
|
||||
### 第四步：场景自动创造与搭配测试
|
||||
|
||||
这是本技能的核心能力：根据当前所有可用工具，自动创造有意义的测试场景，无需用户指定。
|
||||
|
||||
#### 场景识别规则
|
||||
|
||||
根据工具的名称、描述和参数，自动匹配以下 8 种场景模式：
|
||||
|
||||
**1. 查询链路场景**
|
||||
- 匹配规则：存在 list_xxx + get_xxx_detail/xxx_detail + query/get_data 类工具
|
||||
- 创造方式：list 获取列表 → 取第一条的 ID → get detail 获取详情 → 用详情中的 ID 查询关联数据
|
||||
- 示例：list_datasources → get_datasource_detail(id) → list_tables(datasourceId) → get_table_detail(tableId)
|
||||
|
||||
**2. 完整 CRUD 场景**
|
||||
- 匹配规则：存在 create_xxx + list/query_xxx + update_xxx + delete_xxx 类工具
|
||||
- 创造方式：create 创建测试数据 → list 确认存在 → update 修改 → list 确认修改 → delete 删除 → list 确认删除
|
||||
- 示例：create_api_key → list_api_keys → toggle_api_key_status → list_api_keys → delete_api_key → list_api_keys
|
||||
|
||||
**3. 状态变更验证场景**
|
||||
- 匹配规则：存在 get/list_xxx + toggle/enable/disable/start/stop_xxx 类工具
|
||||
- 创造方式：get 初始状态 → toggle 变更状态 → get 验证状态已变更 → toggle 恢复 → get 验证恢复
|
||||
- 示例：get_datasource_detail → toggle_datasource_status(status=1) → get_datasource_detail → toggle_datasource_status(status=0) → get_datasource_detail
|
||||
|
||||
**4. 参数传递链路场景**
|
||||
- 匹配规则：工具 A 的输出字段与工具 B 的输入参数名匹配或语义相关
|
||||
- 创造方式：执行 A → 从结果提取字段 → 作为 B 的输入 → 执行 B → 继续传递给 C
|
||||
- 示例：list_datasources 返回 datasourceId → get_datasource_detail(datasourceId) 返回 connectionId → execute_sql(connectionId, sql)
|
||||
|
||||
**5. 批量操作场景**
|
||||
- 匹配规则：存在接受 array 类型参数的工具（如批量删除、批量授权）
|
||||
- 创造方式：list 获取多条记录 → 提取 IDs 数组 → 传递给批量操作工具 → 验证结果
|
||||
- 示例：list_api_keys → 提取 ids → grant_api_key_permissions(batchDatas=[{...}])
|
||||
|
||||
**6. 条件分支场景**
|
||||
- 匹配规则：工具支持不同枚举参数或可选参数，产生不同行为
|
||||
- 创造方式：同一工具传不同参数 → 对比输出差异
|
||||
- 示例：query_table_data(tableId, target="prod") vs query_table_data(tableId, target="test")
|
||||
|
||||
**7. 异常处理场景**
|
||||
- 匹配规则：任何工具
|
||||
- 创造方式：传入无效 ID、空参数、错误类型 → 验证错误处理是否合理
|
||||
- 示例：get_datasource_detail(datasourceId="invalid") → 验证返回错误信息
|
||||
|
||||
**8. 跨服务器场景**（当有多个 MCP 服务器时）
|
||||
- 匹配规则：不同服务器的工具之间存在业务关联
|
||||
- 创造方式：服务器A的输出 → 作为服务器B的输入
|
||||
- 示例：IoT 获取设备列表 → Dify workflow 处理设备数据 → SQL 执行存储结果
|
||||
|
||||
#### 场景自动创造流程
|
||||
|
||||
```
|
||||
1. 收集所有工具，建立工具字典
|
||||
- key: 工具名
|
||||
- value: {description, inputSchema, outputSample, category}
|
||||
|
||||
2. 构建参数依赖图
|
||||
- 分析每个工具的输入参数名（如 datasourceId, tableId, apiKeyId）
|
||||
- 分析每个工具的输出字段（从执行结果中提取）
|
||||
- 建立 "输出字段 → 输入参数" 的映射关系
|
||||
|
||||
3. 匹配场景模式
|
||||
- 遍历上述 8 种场景规则
|
||||
- 对每种规则，检查当前工具集是否满足匹配条件
|
||||
- 满足则创造具体场景实例
|
||||
|
||||
4. 场景优先级排序
|
||||
- P0: 查询链路（最基础，最先执行）
|
||||
- P1: CRUD 完整链路（验证完整生命周期）
|
||||
- P2: 状态变更验证（验证状态管理）
|
||||
- P3: 参数传递链路（验证工具间协作）
|
||||
- P4: 批量操作、条件分支、异常处理
|
||||
- P5: 跨服务器场景（最复杂，最后执行）
|
||||
|
||||
5. 执行场景
|
||||
- 按优先级依次执行
|
||||
- 前一步的输出自动传递给下一步
|
||||
- 任何一步失败则标记场景失败，继续下一个场景
|
||||
- 场景中包含高风险操作时，执行前询问用户
|
||||
```
|
||||
|
||||
#### 场景执行记录格式
|
||||
|
||||
```markdown
|
||||
### 场景：[场景名称]
|
||||
- **触发规则**：[匹配的场景模式，如 "查询链路场景"]
|
||||
- **涉及工具**：工具A → 工具B → 工具C
|
||||
- **执行过程**：
|
||||
| 步骤 | 工具 | 入参 | 出参摘要 | 状态 |
|
||||
|------|------|------|---------|------|
|
||||
| 1 | list_xxx | {} | 返回 5 条记录 | ✅ |
|
||||
| 2 | get_xxx | {id: "从步骤1获取"} | 返回详情 | ✅ |
|
||||
| 3 | query_xxx | {xxxId: "从步骤2获取"} | 返回结果 | ✅ |
|
||||
- **数据流**：步骤1.id → 步骤2.id → 步骤2.connectionId → 步骤3.connectionId
|
||||
- **场景结果**：✅ 全部成功 / ❌ 步骤N失败（原因：...）
|
||||
- **理解**：[对这个场景的整体理解，工具间如何协作]
|
||||
```
|
||||
|
||||
**场景测试要点：**
|
||||
- 记录完整的数据流转过程
|
||||
- 验证工具之间的兼容性
|
||||
- 检查数据格式是否一致
|
||||
- 场景创造过程不需要用户干预，自动完成
|
||||
- 只在遇到无法判断的参数或高风险操作时才询问用户
|
||||
|
||||
### 第五步：生成报告
|
||||
|
||||
最终只返回以下内容：
|
||||
|
||||
```markdown
|
||||
# MCP 工具测试报告
|
||||
|
||||
## 工具列表
|
||||
|
||||
共发现 [N] 个工具：
|
||||
|
||||
| 序号 | 工具名 | 描述 | 必填参数 | 分类 |
|
||||
|------|--------|------|---------|------|
|
||||
|
||||
## 工具执行结果
|
||||
|
||||
### 1. [工具名]
|
||||
- **描述**：[工具描述]
|
||||
- **入参**：`{JSON}`
|
||||
- **出参**：`{JSON 摘要}`
|
||||
- **状态**：✅ 成功 / ❌ 失败 / ⚠️ 跳过（原因：...）
|
||||
- **理解**：[你对这个工具功能的简要理解]
|
||||
|
||||
### 2. [工具名]
|
||||
...
|
||||
|
||||
## 场景测试
|
||||
|
||||
### 场景1：[场景名称]
|
||||
- **流程**：工具A → 工具B → 工具C
|
||||
- **数据流**：[描述数据如何在工具间传递]
|
||||
- **结果**：[最终结果摘要]
|
||||
- **状态**：✅ 成功 / ❌ 失败
|
||||
|
||||
## 总结
|
||||
|
||||
| 指标 | 数量 |
|
||||
|------|------|
|
||||
| 发现工具总数 | N |
|
||||
| 成功执行 | N |
|
||||
| 执行失败 | N |
|
||||
| 跳过（需用户提供信息） | N |
|
||||
| 高风险操作（已询问用户） | N |
|
||||
| 场景测试数 | N |
|
||||
|
||||
## 待确认事项
|
||||
|
||||
列出需要用户提供的参数或信息：
|
||||
1. [工具名] 的 [参数名]：[说明]
|
||||
2. ...
|
||||
```
|
||||
|
||||
## 特殊处理
|
||||
|
||||
### 动态工具
|
||||
|
||||
有些服务器启动时从外部加载工具定义（如从 API、配置文件、工作流引擎等）：
|
||||
1. 通过 MCP 协议获取实际可用的工具列表
|
||||
2. 对动态获取的工具同样按照上述流程测试
|
||||
3. 记录工具的来源信息（如果有）
|
||||
|
||||
### 需要认证/配置的服务器
|
||||
|
||||
某些 MCP 服务器需要特定的环境变量、API Key、Token 等：
|
||||
1. 检查服务器是否正常运行
|
||||
2. 如果启动失败，记录错误信息并跳过
|
||||
3. 如果运行正常但工具调用失败（如 401），询问用户提供认证信息
|
||||
|
||||
### 失败处理
|
||||
|
||||
- **网络超时**：记录错误，标记为失败，继续下一个
|
||||
- **参数错误**：检查是否需要补充参数，或询问用户
|
||||
- **服务器未运行**：记录原因，跳过该服务器的所有工具
|
||||
- **工具不存在**：可能工具定义已变更，重新获取工具列表
|
||||
|
||||
### 输出处理
|
||||
|
||||
- 输出过长时适当截断（如超过 2000 字符）
|
||||
- 保留关键信息：状态码、主要数据、错误信息
|
||||
- 对于列表类输出，显示前几条和总数
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **保持参数一致性**：同一个 ID 在多个工具中保持相同
|
||||
2. **风险前置**：高风险操作必须先询问用户，绝不擅作主张
|
||||
3. **记录完整**：每个工具的入参、出参都要记录
|
||||
4. **及时询问**：遇到不明确的参数不要猜测，询问用户
|
||||
5. **场景优先**：优先测试有意义的场景组合，而不是孤立地测试每个工具
|
||||
6. **自动创造**：场景不需要用户指定，根据工具自动匹配和创造
|
||||
7. **最终输出**：只返回入参、出参和理解，不需要冗长的过程描述
|
||||
8. **五类风险**：删除、泄密、政治、似黄、生产环境影响——必须询问用户
|
||||
Reference in New Issue
Block a user