aiagent/工具调用可视化实现总结.md

工具调用可视化实现总结

✅ 完成状态

任务: 工具调用可视化
状态: ✅ 已完成
完成时间: 2026-01-23

---

📋 实现功能

1. 后端工具调用日志记录 ✅

修改文件: backend/app/services/llm_service.py

实现内容:

• 在 call_openai_with_tools 方法中添加 execution_logger 参数
• 记录工具调用请求（工具名称、参数、状态）
• 记录工具执行成功（结果、耗时）
• 记录工具执行失败（错误信息、耗时）
• 记录工具调用迭代次数

核心代码:

# 记录工具调用请求
if execution_logger:
    execution_logger.info(
        f"调用工具: {tool_name}",
        data={
            "tool_name": tool_name,
            "tool_call_id": tool_call_id,
            "tool_args": tool_args,
            "status": "requested"
        }
    )

# 记录工具执行成功
if execution_logger:
    execution_logger.info(
        f"工具 {tool_name} 执行成功",
        data={
            "tool_name": tool_name,
            "tool_call_id": tool_call_id,
            "tool_args": tool_args,
            "tool_result": result_preview,
            "tool_result_length": len(tool_result),
            "status": "success",
            "duration": tool_duration
        },
        duration=tool_duration
    )

修改文件: backend/app/services/workflow_engine.py

实现内容:

• 在调用 llm_service.call_llm_with_tools 时传递 execution_logger
• 确保工具调用信息被记录到执行日志中

---

2. 前端NodeExecutionDetail组件 ✅

修改文件: frontend/src/components/WorkflowEditor/NodeExecutionDetail.vue

实现内容:

• 添加工具调用可视化卡片
• 从执行日志中提取工具调用信息
• 显示工具调用时间线
• 显示工具名称、参数、结果、状态、耗时

核心功能:

• ✅ 工具调用时间线展示
• ✅ 工具名称和状态标签
• ✅ 工具参数折叠显示
• ✅ 工具结果折叠显示（支持长结果截断）
• ✅ 错误信息显示
• ✅ 耗时统计

UI特点:

• 使用时间线组件展示工具调用顺序
• 不同状态使用不同颜色标签（成功/失败/请求中）
• 支持JSON格式化显示
• 长结果自动截断并显示长度

---

3. 前端ExecutionDetail组件 ✅

修改文件: frontend/src/views/ExecutionDetail.vue

实现内容:

• 在日志列表中增强工具调用日志显示
• 识别工具调用相关日志
• 特殊样式展示工具调用信息
• 显示工具参数和结果

核心功能:

• ✅ 自动识别工具调用日志
• ✅ 工具调用信息高亮显示
• ✅ 工具参数和结果折叠展示
• ✅ 状态标签和耗时显示
• ✅ 错误信息告警显示

UI特点:

• 工具调用日志使用特殊背景色和边框
• 工具名称使用标签显示
• 参数和结果支持折叠查看
• 错误信息使用告警组件显示

---

🎨 UI展示效果

NodeExecutionDetail组件

┌─────────────────────────────────────┐
│ 🔧 工具调用                   3 个工具调用 │
├─────────────────────────────────────┤
│                                     │
│ 时间线:                              │
│  ● http_request  ✅ 成功  耗时: 234ms │
│     📥 参数: [折叠]                   │
│     ✅ 结果: [折叠]                   │
│                                     │
│  ● file_read     ✅ 成功  耗时: 12ms  │
│     📥 参数: [折叠]                   │
│     ✅ 结果: [折叠]                   │
│                                     │
│  ● database_query ❌ 失败  耗时: 5ms   │
│     📥 参数: [折叠]                   │
│     ❌ 错误: [告警显示]                │
│                                     │
└─────────────────────────────────────┘

ExecutionDetail组件

日志列表:
┌─────────────────────────────────────┐
│ 2026-01-23 10:30:15  INFO  [节点ID]  │
│ 调用工具: http_request                │
│ 🔧 http_request  ✅ 成功  耗时: 234ms │
│ 📥 参数: [查看参数]                   │
│ ✅ 结果: [查看结果]                   │
└─────────────────────────────────────┘

---

📊 数据结构

工具调用日志数据结构

{
  "level": "INFO",
  "message": "工具 http_request 执行成功",
  "data": {
    "tool_name": "http_request",
    "tool_call_id": "call_abc123",
    "tool_args": {
      "url": "https://api.example.com",
      "method": "GET"
    },
    "tool_result": "{\"status_code\": 200, ...}",
    "tool_result_length": 1024,
    "status": "success",
    "duration": 234
  },
  "timestamp": "2026-01-23T10:30:15.123Z",
  "duration": 234
}

---

🔧 技术实现细节

1. 后端日志记录

• 位置: llm_service.py 的 call_openai_with_tools 方法
• 时机:
  • 工具调用请求时
  • 工具执行成功时
  • 工具执行失败时
• 数据: 工具名称、参数、结果、状态、耗时

2. 前端数据提取

• 位置: NodeExecutionDetail.vue 的 toolCalls computed属性
• 逻辑:
  • 遍历执行日志
  • 识别包含 tool_name 和 status 的日志
  • 合并请求和结果日志
  • 按时间排序

3. 前端UI展示

• 组件: Element Plus Timeline、Card、Collapse
• 样式: 自定义CSS样式，支持状态颜色区分
• 交互: 折叠展开查看详情

---

🎯 功能特点

1. 完整的工具调用追踪

   • 从请求到结果的全流程记录
   • 支持多轮工具调用迭代

2. 清晰的可视化展示

   • 时间线展示调用顺序
   • 状态标签清晰标识
   • 参数和结果可折叠查看

3. 详细的执行信息

   • 工具名称
   • 调用参数
   • 执行结果
   • 执行耗时
   • 错误信息（如有）

4. 友好的用户体验

   • JSON格式化显示
   • 长结果自动截断
   • 错误信息告警提示
   • 支持复制功能

---

📝 使用说明

查看工具调用信息

1. 在节点执行详情中查看:

   • 打开工作流编辑器
   • 点击节点查看执行详情
   • 在"工具调用"卡片中查看所有工具调用

2. 在执行详情页面查看:

   • 打开执行详情页面
   • 切换到"执行日志"标签
   • 工具调用日志会以特殊样式显示

工具调用信息包含

• 工具名称: 调用的工具名称（如 http_request、file_read）
• 调用参数: 传递给工具的参数（JSON格式）
• 执行结果: 工具返回的结果（JSON格式）
• 执行状态: 成功/失败/请求中
• 执行耗时: 工具执行的时间（毫秒）

---

🧪 测试建议

1. 创建测试工作流:

   • 添加LLM节点
   • 启用工具调用
   • 选择工具（如 http_request、file_read）

2. 执行工作流:

   • 输入测试数据
   • 执行工作流
   • 观察工具调用过程

3. 查看可视化:

   • 打开节点执行详情
   • 查看工具调用卡片
   • 验证工具调用信息是否正确显示

---

📊 统计

• 代码行数: 约300行（后端+前端）
• 修改文件数: 3个
• 新增功能: 工具调用可视化
• UI组件: Timeline、Card、Collapse、Alert

---

🎉 完成的功能

✅ 后端工具调用日志记录
✅ 前端NodeExecutionDetail组件工具调用可视化
✅ 前端ExecutionDetail组件工具调用信息显示
✅ 工具调用时间线展示
✅ 工具参数和结果展示
✅ 工具调用状态和耗时显示
✅ 错误信息展示

---

最后更新: 2026-01-23
文档版本: v1.0
状态: 已完成 ✅