aiagent/ADB工具验证方法.md

ADB工具验证方法

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

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

1. 运行测试脚本

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. 输入测试数据：在测试输入框中输入：

   {
     "query": "列出设备"
   }
   

   或

   {
     "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 交互式测试

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. 验证工具注册

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 中

解决方案：

# 检查 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 设备或模拟器

解决方案：

# 检查设备连接
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 可以正确使用工具
• 工具调用可视化功能正常显示工具调用过程

快速验证命令

# 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) 获取详细错误信息。