aiagent/ADB工具验证方法.md

# ADB工具验证方法

本文档介绍如何验证 `adb_log` 工具是否可以正常调用 ADB 命令。

## 方法一：使用测试脚本（推荐）

### 1. 运行测试脚本

```bash
cd /home/renjianbo/aiagent
python test_adb_tool.py
```

### 2. 测试内容

脚本会自动测试以下功能：

- ✅ **列出设备** (`adb devices`)
- ✅ **获取最近日志** (`adb logcat -d -t 10`)
- ✅ **获取错误级别日志** (`adb logcat -d *:E -t 5`)
- ✅ **执行shell命令** (`adb shell getprop ro.build.version.release`)
- ✅ **错误处理** (验证无效命令的处理)

### 3. 预期结果

如果所有测试通过，说明 ADB 工具工作正常。

## 方法二：通过前端单节点测试

### 1. 准备工作

1. 打开工作流编辑器
2. 找到或创建一个包含 `adb_log` 工具的 LLM 节点
3. 确保节点已启用工具调用并选择了 `adb_log` 工具

### 2. 测试步骤

1. **选中节点**：点击 "执行ADB命令" 节点
2. **输入测试数据**：在测试输入框中输入：
   ```json
   {
     "query": "列出设备"
   }
   ```
   或
   ```json
   {
     "query": "获取最近日志"
   }
   ```
3. **运行测试**：点击 "运行测试" 按钮
4. **查看结果**：检查执行结果中是否包含实际的 ADB 命令输出

### 3. 验证要点

- ✅ LLM 正确识别用户意图
- ✅ LLM 调用了 `adb_log` 工具（不是生成文本）
- ✅ 工具返回了真实的 ADB 命令结果
- ✅ 结果中包含设备信息或日志内容

## 方法三：通过 Agent 测试

### 1. 使用 "Android日志获取助手" Agent

1. 打开 Agent 列表
2. 找到 "Android日志获取助手"
3. 点击运行

### 2. 测试命令

尝试以下输入：

- `列出设备`
- `获取最近日志`
- `获取错误日志`
- `获取最近10条日志`

### 3. 查看执行详情

1. 在 Agent 执行结果页面，点击 "查看详情"
2. 检查执行日志，确认：
   - ✅ 工具调用记录存在
   - ✅ 工具参数正确（command, max_lines 等）
   - ✅ 工具返回了真实结果

## 方法四：直接调用工具函数（开发调试）

### 1. Python 交互式测试

```python
import asyncio
import json
import sys
sys.path.insert(0, 'backend')

from app.services.builtin_tools import adb_log_tool

# 测试列出设备
result = asyncio.run(adb_log_tool(command="devices"))
print(json.loads(result))

# 测试获取日志
result = asyncio.run(adb_log_tool(command="logcat", max_lines=5))
print(json.loads(result))
```

### 2. 验证工具注册

```python
from app.services.tool_registry import tool_registry

# 检查工具是否已注册
schema = tool_registry.get_tool_schema("adb_log")
print(schema)

# 检查工具函数是否存在
func = tool_registry.get_tool_function("adb_log")
print(func)
```

## 常见问题排查

### 问题1：测试脚本报错 "未找到adb命令"

**原因**：ADB 未安装或不在 PATH 中

**解决方案**：
```bash
# 检查 adb 是否安装
which adb

# 如果未安装，安装 Android SDK Platform Tools
# Ubuntu/Debian:
sudo apt-get install android-tools-adb

# 或下载 Platform Tools:
# https://developer.android.com/studio/releases/platform-tools
```

### 问题2：测试返回 "未找到设备"

**原因**：没有连接 Android 设备或模拟器

**解决方案**：
```bash
# 检查设备连接
adb devices

# 如果显示 "no devices"，请：
# 1. 连接 Android 设备并启用 USB 调试
# 2. 或启动 Android 模拟器
```

### 问题3：LLM 不调用工具，返回文本响应

**原因**：LLM 可能误解了用户意图或提示词配置不当

**解决方案**：
1. 检查节点配置中的提示词是否明确要求调用工具
2. 确保工具已正确选择并启用
3. 在单节点测试时，确保输入数据格式正确
4. 查看后端日志，检查工具调用请求

### 问题4：工具调用超时

**原因**：ADB 命令执行时间过长

**解决方案**：
- 减少 `max_lines` 参数（默认100行）
- 增加 `timeout` 参数（默认10秒，最大60秒）
- 使用更具体的过滤条件（filter_tag, level）

## 验证清单

在验证 ADB 工具时，请确认：

- [ ] ADB 已正确安装并在 PATH 中
- [ ] 至少有一个 Android 设备已连接（或模拟器运行中）
- [ ] `adb devices` 命令可以列出设备
- [ ] 测试脚本可以成功执行
- [ ] 单节点测试可以调用工具并返回结果
- [ ] Agent 可以正确使用工具
- [ ] 工具调用可视化功能正常显示工具调用过程

## 快速验证命令

```bash
# 1. 检查 ADB 安装
adb version

# 2. 检查设备连接
adb devices -l

# 3. 测试获取日志（命令行）
adb logcat -d -t 5

# 4. 运行测试脚本
python test_adb_tool.py
```

## 成功标志

✅ **工具工作正常**的标志：

1. 测试脚本所有测试通过
2. 单节点测试返回真实的 ADB 命令结果（不是 LLM 生成的文本）
3. 执行日志中可以看到工具调用记录
4. 工具调用可视化显示工具被正确调用
5. Agent 可以成功获取设备日志

---

**提示**：如果遇到问题，请查看后端日志 (`docker-compose logs backend`) 获取详细错误信息。