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

# 工具调用可视化实现总结

## ✅ 完成状态

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

---

## 📋 实现功能

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

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

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

**核心代码**:
```python
# 记录工具调用请求
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 │
│ 📥 参数: [查看参数]                   │
│ ✅ 结果: [查看结果]                   │
└─────────────────────────────────────┘
```

---

## 📊 数据结构

### 工具调用日志数据结构

```json
{
  "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  
**状态**: 已完成 ✅