aiagent/Android日志获取助手使用指南.md

Android日志获取助手使用指南

📖 简介

Android日志获取助手是一个智能Agent，可以通过自然语言请求获取和分析Android设备日志。它使用ADB（Android Debug Bridge）命令与Android设备通信，支持获取logcat日志、列出设备、执行shell命令等功能。

---

🚀 快速开始

1. 环境准备

必需条件:

• ✅ 已安装 Android SDK Platform Tools
• ✅ adb 命令已添加到系统PATH
• ✅ Android设备已连接或模拟器已启动

验证ADB环境:

# 检查ADB版本
adb version

# 检查设备连接
adb devices

预期输出:

List of devices attached
emulator-5554   device

---

💻 使用方式

方式1: 前端界面使用（推荐）

步骤:

1. 打开平台前端页面: http://101.43.95.130:8038
2. 登录系统
3. 进入 Agent管理 页面
4. 找到 "Android日志获取助手"
5. 点击 "测试" 或 "执行" 按钮
6. 在输入框中输入您的请求（自然语言）
7. 点击 "执行" 按钮
8. 等待执行完成，查看结果

输入格式:

• 直接使用自然语言，例如：
  • "获取最近的错误日志"
  • "列出所有连接的设备"
  • "获取ActivityManager的日志"
  • "adb devices"

---

方式2: 命令行测试工具

使用测试脚本:

cd /home/renjianbo/aiagent

# 基本用法
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "您的请求"}'

常用示例:

# 1. 列出所有连接的设备
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "列出所有连接的设备"}'

# 2. 获取最近的错误日志
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取最近的错误日志"}'

# 3. 获取ActivityManager的日志
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取ActivityManager的日志"}'

# 4. 获取特定级别的日志
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取警告级别的日志"}'

# 5. 执行adb devices命令
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "adb devices"}'

# 6. 获取系统日志
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取系统日志"}'

---

方式3: API调用

使用curl命令:

# 1. 登录获取Token
TOKEN=$(curl -s -X POST http://localhost:8037/api/v1/auth/login \
  -d 'username=admin&password=123456' \
  | python3 -c 'import sys, json; print(json.load(sys.stdin).get("access_token"))')

# 2. 执行Agent
curl -X POST http://localhost:8037/api/v1/agents/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "agent_id": "b68e96d2-da66-4402-86a5-9fae6b5ac092",
    "input_data": {
      "query": "获取最近的错误日志"
    }
  }'

使用Python脚本:

import requests
import json

# 登录
login_response = requests.post(
    "http://localhost:8037/api/v1/auth/login",
    data={"username": "admin", "password": "123456"}
)
token = login_response.json()["access_token"]

# 执行Agent
execute_response = requests.post(
    "http://localhost:8037/api/v1/agents/execute",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json={
        "agent_id": "b68e96d2-da66-4402-86a5-9fae6b5ac092",
        "input_data": {
            "query": "获取最近的错误日志"
        }
    }
)

result = execute_response.json()
print(json.dumps(result, indent=2, ensure_ascii=False))

---

📝 使用示例

示例1: 列出连接的设备

输入:

{
  "query": "列出所有连接的设备"
}

或自然语言:

列出设备
adb devices

预期输出:

已找到1个连接的设备：

1. emulator-5554
   - 状态: device（已连接且正常运行）
   - 类型: Android模拟器

---

示例2: 获取错误日志

输入:

{
  "query": "获取最近的错误日志"
}

或自然语言:

获取错误日志
显示最近的错误

预期输出:

已获取最近的错误日志，共发现X个错误：

1. [时间] 标签: 错误信息
   - 详细信息
   - 建议操作

2. [时间] 标签: 错误信息
   ...

---

示例3: 获取特定标签的日志

输入:

{
  "query": "获取ActivityManager的日志"
}

或自然语言:

获取ActivityManager日志
显示ActivityManager的活动

预期输出:

已获取ActivityManager日志，共100行：

关键活动：
- 应用启动: com.example.app (时间)
- Activity切换: MainActivity → SettingsActivity (时间)
- 应用关闭: com.example.app (时间)

性能指标：
- 平均启动时间: X秒
- Activity切换次数: X次

---

示例4: 获取特定级别的日志

输入:

{
  "query": "获取警告级别的日志"
}

支持的级别:

• V - Verbose（详细）
• D - Debug（调试）
• I - Info（信息）
• W - Warning（警告）
• E - Error（错误）
• F - Fatal（致命）
• S - Silent（静默）

自然语言示例:

获取错误日志
显示警告信息
获取调试日志

---

示例5: 执行Shell命令（受限）

输入:

{
  "query": "获取设备属性"
}

支持的安全命令:

• getprop - 获取系统属性
• dumpsys - 转储系统服务信息
• pm - 包管理器命令
• am - Activity管理器命令
• settings - 设置命令

不支持的危险命令:

• ❌ rm - 删除文件
• ❌ reboot - 重启设备
• ❌ su - 超级用户
• ❌ 其他可能破坏系统的命令

---

🎯 支持的请求类型

1. 设备管理

• ✅ "列出所有连接的设备"
• ✅ "检查设备连接状态"
• ✅ "adb devices"

2. 日志获取

• ✅ "获取最近的日志"
• ✅ "获取错误日志"
• ✅ "获取警告日志"
• ✅ "获取ActivityManager的日志"
• ✅ "获取系统日志"
• ✅ "获取特定标签的日志"

3. 日志过滤

• ✅ 按标签过滤（如 ActivityManager、SystemServer）
• ✅ 按级别过滤（V/D/I/W/E/F/S）
• ✅ 限制返回行数（默认100行）

4. Shell命令（受限）

• ✅ 获取设备属性
• ✅ 查询包信息
• ✅ 查询系统服务

---

⚙️ 工作流程

Agent的工作流程如下：

用户输入
  ↓
意图识别节点（LLM）
  - 分析用户请求
  - 提取ADB命令参数
  ↓
JSON解析节点
  - 解析意图识别结果
  - 提取命令参数
  ↓
LLM工具调用节点
  - 调用adb_log工具
  - 执行ADB命令
  - 分析日志内容
  ↓
结束节点
  - 返回最终结果

---

📊 查看执行详情

在前端查看

1. 执行Agent后，点击 "查看详情" 按钮

2. 在 执行详情 页面中：

   • 查看整体执行状态
   • 查看每个节点的执行情况
   • 查看工具调用可视化
   • 查看输入和输出数据

3. 点击 "执行ADB命令" 节点，查看：

   • 节点执行详情
   • 工具调用时间线
   • 工具调用参数和结果
   • 执行日志

工具调用可视化

在节点执行详情中，可以看到：

• ✅ 工具调用时间线
• ✅ 工具名称和状态
• ✅ 工具调用参数
• ✅ 工具执行结果
• ✅ 执行耗时

---

⚠️ 注意事项

1. ADB环境要求

• ✅ 必须安装 Android SDK Platform Tools
• ✅ 必须将 adb 命令添加到 PATH
• ✅ 必须连接 Android 设备或启动模拟器
• ✅ 设备必须启用USB调试（物理设备）

2. 安全限制

• ✅ Shell命令只允许执行安全命令
• ✅ 不允许执行危险命令（如 rm、reboot 等）
• ✅ 超时控制防止长时间执行（默认10秒）
• ✅ 行数限制防止输出过长（默认100行）

3. 性能优化

• ✅ 默认限制返回100行日志
• ✅ 支持超时控制（默认10秒）
• ✅ 异步执行避免阻塞

4. 错误处理

• ✅ 处理ADB命令执行失败
• ✅ 处理设备未连接情况
• ✅ 处理超时情况
• ✅ 详细的错误信息返回

---

🔍 常见问题

Q1: 提示"设备未连接"怎么办？

A: 请检查：

1. 设备是否已连接（adb devices）
2. USB调试是否已启用（物理设备）
3. ADB服务是否正常运行（adb kill-server && adb start-server）

Q2: 执行超时怎么办？

A:

• 默认超时时间为10秒
• 如果日志量很大，可能需要更长时间
• 可以尝试限制返回行数或使用更具体的过滤条件

Q3: 如何获取更多日志？

A:

• Agent默认返回100行日志
• 可以通过更具体的过滤条件获取相关日志
• 例如："获取ActivityManager最近200行的日志"

Q4: 工具调用没有执行？

A:

• 检查Agent配置中是否启用了工具调用
• 检查是否选中了 adb_log 工具
• 尝试使用更明确的输入，例如："请使用adb_log工具执行adb devices命令"

Q5: 如何查看工具调用详情？

A:

• 在前端执行详情页面，点击 "执行ADB命令" 节点
• 查看 "工具调用" 卡片
• 查看工具调用时间线、参数和结果

---

🎓 最佳实践

1. 使用明确的请求

• ✅ "获取最近的错误日志"
• ❌ "日志"

2. 指定具体的标签或级别

• ✅ "获取ActivityManager的错误日志"
• ❌ "获取日志"

3. 限制返回行数

• ✅ "获取最近的50行错误日志"
• ❌ "获取所有错误日志"

4. 使用自然语言

• ✅ "列出所有连接的设备"
• ✅ "显示最近的警告信息"
• ✅ "获取系统日志"

---

📞 技术支持

如果遇到问题，请：

1. 检查ADB环境是否正确配置
2. 检查设备是否已连接
3. 查看执行详情页面的错误信息
4. 查看后端日志：docker-compose -f docker-compose.dev.yml logs backend

---

📚 相关文档

• ADB工具和Android日志Agent搭建总结
• Agent搭建通用方法指南
• 工具调用可视化实现总结

---

最后更新: 2026-01-23
文档版本: v1.0
Agent状态: ✅ 已发布，可正常使用