MCP 调试工具
概述
MCP（Model Context Protocol）调试工具是专门为 AI 助手设计的工具集，用于在帮助用户开发 ApiFlow 工作流时进行调试、错误定位和验证。这些工具通过 MCP 协议与 ApiFlow 引擎通信，提供实时的状态查询和日志分析能力。
重要：这些工具是给 AI 助手使用的，不是给用户在工作流 DSL 中调用的。
工作流程要求
当帮助用户开发 ApiFlow 工作流时，必须遵循以下流程：
- 修改工作流文件后 → 立即调用
reload_engine验证修改 - 遇到错误或问题时 → 使用
query_system_logs查询日志定位问题 - 反复迭代直到成功 → 确保
reload_engine返回 "succeed" 状态
工具列表
1. reload_engine - 重新加载引擎
功能描述
重新加载和初始化 ApiFlow 开发流程引擎。此工具会重新扫描工作流目录，重新编译和加载所有工作流文件和配置文件。
使用时机（必须遵守）
- 必须调用：每次修改工作流文件（
.groovy）后 - 必须调用：每次修改配置文件（
config.groovy）后 - 必须调用：每次添加新的工作流文件后
- 必须调用：每次删除工作流文件后
- 验证修改：确认修改是否成功生效
- 错误检查：检查是否存在语法错误、配置错误
输入参数
无需参数。
返回结果
返回一个包含以下字段的对象：
status(String): 加载状态"succeed": 加载成功，所有文件都正确编译和加载"failed": 加载失败，存在错误文件或编译失败
errorFiles(Map<String, String>): 错误文件映射（仅在 status 为 "failed" 时有值）- Key: 文件路径
- Value: 错误详细信息
errorMsg(String): 整体错误消息（可选）
返回示例
成功案例：
Engine Reload Result:
━━━━━━━━━━━━━━━━━━━━
Status: succeed失败案例：
Engine Reload Result:
━━━━━━━━━━━━━━━━━━━━
Status: failed
Error Files:
[/path/to/workflow/test.groovy]
Syntax error at line 10: expecting '}', found 'EOF'
[/path/to/workflow/another.groovy]
Variable 'unknownVar' is not defined最佳实践
标准工作流程：
1. 修改工作流文件（例如：添加新任务、修改配置等）
2. 立即调用 reload_engine
3. 检查返回的 status 字段
- 如果是 "succeed"：告知用户修改成功，可以继续
- 如果是 "failed"：
a. 仔细分析 errorFiles 中的错误信息
b. 根据错误信息修正文件内容
c. 再次调用 reload_engine
d. 重复直到 status 为 "succeed"常见错误类型
语法错误
- Groovy 语法不正确
- 缺少闭合括号、引号等
- 示例：
expecting '}', found 'EOF'
变量未定义
- 引用了不存在的变量或任务
- 示例：
Variable 'taskName' is not defined
类型错误
- 属性类型不匹配
- 示例：
Cannot cast String to Integer
配置错误
- config.groovy 配置错误
- app 配置缺少必需字段
使用示例
场景1：用户要求添加一个新的 HTTP 任务
AI助手：
1. 读取现有工作流文件
2. 添加新的 HTTP 任务代码
3. 保存文件
4. [必须] 调用 reload_engine
5. 检查结果：
- 成功 → 告知用户："已成功添加 HTTP 任务并重新加载引擎"
- 失败 → 分析错误，修正代码，再次 reload_engine
场景2：用户修改了 config.groovy
AI助手：
1. 修改 config.groovy
2. [必须] 调用 reload_engine
3. 验证配置是否正确加载
场景3：用户报告工作流不工作
AI助手：
1. [首先] 调用 reload_engine 查看是否有加载错误
2. 如果有错误，修正后再次加载
3. 如果没有加载错误，使用 query_system_logs 查看运行时日志2. query_system_logs - 查询系统日志
功能描述
查询 ApiFlow 系统运行日志，支持按时间范围、日志级别、关键字、Logger 名称等条件过滤。用于定位工作流执行错误、调试任务执行问题。
使用时机
- 定位错误：工作流执行失败，需要查看错误日志
- 调试任务：某个任务执行不符合预期，查看执行日志
- 查看状态：查看引擎运行状态和健康情况
- 追踪行为：追踪特定时间段的系统行为
- 验证修改：修改后查看日志确认新代码是否执行
输入参数
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|---|---|---|---|---|
startTime | String | 是 | - | 开始时间，格式：yyyy-MM-dd HH:mm:ss |
endTime | String | 否 | null | 结束时间，格式：yyyy-MM-dd HH:mm:ss |
level | String | 否 | null | 日志级别：DEBUG, INFO, WARN, ERROR |
keyword | String | 否 | null | 关键字搜索（在日志消息中搜索） |
loggerName | String | 否 | null | Logger 名称过滤 |
page | Integer | 否 | 0 | 页码（从 0 开始） |
size | Integer | 否 | 100 | 每页大小（最大 1000） |
返回结果
返回格式化的日志条目列表，每条日志包含：
- 时间戳
- 日志级别
- Logger 名称
- 日志消息
如果没有找到匹配的日志，返回 "No logs found matching the criteria."
返回示例
Found 3 log entries (page 0, size 100):
2025-12-12 10:15:23 [ERROR] org.apiflow.core.FlowEngine - Failed to execute task 'httpTask': Connection timeout
2025-12-12 10:15:20 [INFO] org.apiflow.core.FlowEngine - Starting workflow execution: test_workflow
2025-12-12 10:15:18 [DEBUG] org.apiflow.core.TaskExecutor - Initializing task: httpTask典型使用场景
场景 1：查看最近的错误日志
参数：
startTime: "2025-12-12 10:00:00"
level: "ERROR"
用途：快速定位最近发生的错误场景 2：搜索特定任务的执行日志
参数：
startTime: "2025-12-12 09:00:00"
keyword: "httpTask"
用途：追踪某个任务的完整执行过程场景 3：定位 reload_engine 失败原因
参数：
startTime: "2025-12-12 10:00:00"
keyword: "reload"
level: "ERROR"
用途：查看引擎重新加载时的错误信息场景 4：查看特定工作流的执行日志
参数：
startTime: "2025-12-12 08:00:00"
endTime: "2025-12-12 12:00:00"
keyword: "workflow_name"
用途：查看某个工作流在特定时间段的执行情况场景 5：调试数据库操作
参数：
startTime: "2025-12-12 10:00:00"
keyword: "mysql"
level: "WARN"
用途：查看数据库相关的警告和错误最佳实践
时间范围选择
- 优先使用最近的时间范围（如最近 1 小时）
- 如果不确定问题发生时间，可以逐步扩大时间范围
- 时间格式必须严格遵守：
yyyy-MM-dd HH:mm:ss
日志级别使用
ERROR: 查看错误和异常（最常用）WARN: 查看警告信息INFO: 查看一般信息和执行流程DEBUG: 查看详细的调试信息（信息量大）
关键字搜索
- 使用任务名称搜索任务相关日志
- 使用工作流名称搜索工作流执行日志
- 使用异常类名搜索特定错误
分页使用
- 默认每页 100 条，适合大多数场景
- 如果日志很多，使用分页逐步查看
- 注意页码从 0 开始
使用示例
场景：用户报告 HTTP 任务执行失败
AI助手调试流程：
1. 确定问题发生的大致时间（如最近 1 小时）
2. 调用 query_system_logs：
- startTime: "2025-12-12 10:00:00" (1小时前)
- level: "ERROR"
3. 查看返回的错误日志
4. 如果找到相关错误：
- 分析错误原因
- 提供解决方案
5. 如果没找到错误：
- 扩大时间范围或移除 level 过滤
- 或者添加 keyword 搜索任务名称
场景：用户修改了工作流，想确认是否执行
AI助手验证流程：
1. 用户修改代码
2. 调用 reload_engine 验证加载成功
3. 用户触发工作流执行
4. 调用 query_system_logs：
- startTime: "2025-12-12 10:30:00" (触发时间)
- keyword: "workflow_name"
5. 查看日志确认工作流是否执行，执行了哪些任务3. get_log_stats - 获取日志统计
功能描述
获取系统日志的统计信息，包括日志总数、最大容量、各级别日志的数量分布。
使用时机
- 了解系统日志整体情况
- 检查日志系统是否正常工作
- 查看各级别日志分布，评估系统健康状况
- 确认是否有大量错误日志
输入参数
无需参数。
返回结果
返回统计信息，包含：
total: 日志总数maxSize: 日志最大容量levelCounts: 各级别日志数量DEBUG: DEBUG 级别日志数量INFO: INFO 级别日志数量WARN: WARN 级别日志数量ERROR: ERROR 级别日志数量
返回示例
System Log Statistics:
━━━━━━━━━━━━━━━━━━━━
Total Logs: 1523
Max Capacity: 10000
Level Distribution:
DEBUG: 845
INFO: 521
WARN: 98
ERROR: 59使用场景
快速健康检查
- 调用 get_log_stats 查看整体情况
- 如果 ERROR 数量很高，说明系统可能有问题
日志容量监控
- 检查 total 是否接近 maxSize
- 如果接近上限，旧日志会被覆盖
问题判断
- 如果 ERROR 数量异常多，需要调用 query_system_logs 详细查看
综合调试案例
案例 1：用户报告工作流执行失败
AI 助手调试流程：
步骤 1：检查引擎加载状态
→ 调用 reload_engine
→ 结果：status = "succeed"（引擎加载正常）
步骤 2：查看整体日志情况
→ 调用 get_log_stats
→ 结果：ERROR: 15（有错误日志）
步骤 3：查询错误日志
→ 调用 query_system_logs
参数：startTime="2025-12-12 09:00:00", level="ERROR"
→ 结果：发现 "Connection timeout" 错误
步骤 4：定位具体任务
→ 调用 query_system_logs
参数：startTime="2025-12-12 09:00:00", keyword="httpTask"
→ 结果：发现 httpTask 连接超时
步骤 5：提供解决方案
→ 建议用户增加超时时间或检查网络连接案例 2：修改工作流后验证
AI 助手操作流程：
步骤 1：用户请求添加新任务
→ AI 修改工作流文件，添加新的 CODE 任务
步骤 2：重新加载引擎
→ 调用 reload_engine
→ 结果：status = "failed"
→ errorFiles: {"test.groovy": "Syntax error at line 25"}
步骤 3：修正错误
→ AI 分析错误，发现缺少闭合括号
→ 修正代码
步骤 4：再次加载
→ 调用 reload_engine
→ 结果：status = "succeed"
步骤 5：验证执行
→ 用户触发工作流
→ 调用 query_system_logs
参数：startTime="2025-12-12 10:00:00", keyword="newTask"
→ 结果：看到新任务成功执行的日志
步骤 6：告知用户
→ "新任务已成功添加并验证执行正常"案例 3：性能问题调试
AI 助手调试流程：
步骤 1：用户报告工作流执行缓慢
→ 调用 query_system_logs
参数：startTime="2025-12-12 09:00:00", keyword="workflow_name", level="WARN"
→ 结果：发现大量 "Slow query" 警告
步骤 2：定位慢查询
→ 调用 query_system_logs
参数：startTime="2025-12-12 09:00:00", keyword="mysql"
→ 结果：发现某个 SQL 查询耗时很长
步骤 3：提供优化建议
→ 建议用户优化 SQL 查询或添加索引重要提醒
必须遵守的规则
修改文件后必须 reload_engine
- 每次修改工作流文件后
- 每次修改配置文件后
- 确保修改生效且没有错误
验证 reload_engine 结果
- 检查 status 字段
- 如果失败，必须修正错误并重新加载
- 不要在引擎加载失败的状态下继续操作
使用 query_system_logs 定位问题
- 遇到错误时，先查看日志
- 使用合适的时间范围和过滤条件
- 从 ERROR 级别开始，逐步扩大范围
提供清晰的反馈
- 告知用户 reload_engine 的结果
- 如果有错误，解释错误原因
- 说明已经采取的调试步骤
常见错误避免
不要忽略 reload_engine
- ❌ 错误：修改文件后直接告诉用户"已完成"
- ✅ 正确：修改文件 → reload_engine → 验证成功 → 告知用户
不要忽略加载错误
- ❌ 错误：看到 reload_engine 返回 failed 就放弃
- ✅ 正确：分析错误信息 → 修正问题 → 再次加载
查询日志时注意时间
- ❌ 错误：使用很久以前的时间查询当前问题
- ✅ 正确：使用问题发生前后的时间范围
不要遗漏关键信息
- ❌ 错误：只告诉用户"有错误"
- ✅ 正确：说明具体的错误信息和位置