571 lines
13 KiB
Markdown
571 lines
13 KiB
Markdown
# ADB工具和Android日志Agent搭建总结
|
||
|
||
## ✅ 完成状态
|
||
|
||
**任务**: 创建ADB工具和Android日志获取Agent
|
||
**状态**: ✅ 已完成
|
||
**完成时间**: 2026-01-23
|
||
|
||
---
|
||
|
||
## 📋 实现内容
|
||
|
||
### 1. ADB日志工具（adb_log）✅
|
||
|
||
**文件位置**: `backend/app/services/builtin_tools.py`
|
||
|
||
**功能描述**:
|
||
- 通过ADB命令获取Android设备日志
|
||
- 支持多种ADB命令类型
|
||
- 支持日志过滤和级别控制
|
||
- 支持超时和行数限制
|
||
|
||
**支持的命令类型**:
|
||
|
||
1. **logcat** - 获取日志
|
||
- 获取Android设备的logcat日志
|
||
- 支持按标签过滤（如 `ActivityManager`、`SystemServer`）
|
||
- 支持按级别过滤（V/D/I/W/E/F/S）
|
||
- 支持限制返回行数
|
||
|
||
2. **devices** - 列出设备
|
||
- 列出所有连接的Android设备
|
||
- 显示设备详细信息
|
||
|
||
3. **shell** - 执行shell命令（受限）
|
||
- 只允许执行安全命令
|
||
- 支持的命令：`getprop`、`dumpsys`、`pm`、`am`、`settings`
|
||
- 不允许执行危险命令（如 `rm`、`reboot` 等）
|
||
|
||
**工具参数**:
|
||
|
||
```python
|
||
async def adb_log_tool(
|
||
command: str = "logcat", # 命令类型：logcat/devices/shell
|
||
filter_tag: Optional[str] = None, # 日志标签过滤或shell命令
|
||
level: Optional[str] = None, # 日志级别：V/D/I/W/E/F/S
|
||
max_lines: int = 100, # 最大返回行数（1-10000）
|
||
timeout: int = 10 # 超时时间（秒，1-60）
|
||
) -> str
|
||
```
|
||
|
||
**工具Schema**:
|
||
|
||
```json
|
||
{
|
||
"type": "function",
|
||
"function": {
|
||
"name": "adb_log",
|
||
"description": "执行ADB命令获取Android设备日志。支持logcat（获取日志）、devices（列出设备）、shell（执行shell命令）。可以过滤日志标签和级别。",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"command": {
|
||
"type": "string",
|
||
"enum": ["logcat", "devices", "shell"],
|
||
"description": "ADB命令类型",
|
||
"default": "logcat"
|
||
},
|
||
"filter_tag": {
|
||
"type": "string",
|
||
"description": "日志标签过滤或shell命令"
|
||
},
|
||
"level": {
|
||
"type": "string",
|
||
"enum": ["V", "D", "I", "W", "E", "F", "S"],
|
||
"description": "日志级别过滤"
|
||
},
|
||
"max_lines": {
|
||
"type": "integer",
|
||
"description": "最大返回行数",
|
||
"default": 100
|
||
},
|
||
"timeout": {
|
||
"type": "integer",
|
||
"description": "命令执行超时时间（秒）",
|
||
"default": 10
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**返回格式**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"command": "adb logcat -d -t 100",
|
||
"return_code": 0,
|
||
"output": "日志内容...",
|
||
"output_lines": 100,
|
||
"error": null,
|
||
"timestamp": "2026-01-23T11:00:00"
|
||
}
|
||
```
|
||
|
||
**安全特性**:
|
||
- ✅ 超时控制（防止长时间执行）
|
||
- ✅ 行数限制（防止输出过长）
|
||
- ✅ Shell命令白名单（只允许安全命令）
|
||
- ✅ 错误处理和日志记录
|
||
|
||
---
|
||
|
||
### 2. 工具注册 ✅
|
||
|
||
**文件位置**: `backend/app/main.py`
|
||
|
||
**注册代码**:
|
||
|
||
```python
|
||
from app.services.builtin_tools import (
|
||
adb_log_tool,
|
||
ADB_LOG_SCHEMA
|
||
)
|
||
|
||
tool_registry.register_builtin_tool("adb_log", adb_log_tool, ADB_LOG_SCHEMA)
|
||
```
|
||
|
||
**注册状态**: ✅ 已注册（共10个内置工具）
|
||
|
||
---
|
||
|
||
### 3. Android日志获取助手Agent ✅
|
||
|
||
**文件位置**: `backend/scripts/generate_android_log_agent.py`
|
||
|
||
**Agent信息**:
|
||
- **Agent ID**: `b68e96d2-da66-4402-86a5-9fae6b5ac092`
|
||
- **Agent名称**: `Android日志获取助手`
|
||
- **工作流ID**: `4df28591-7d47-403e-b7dc-9fc298b79527`
|
||
- **描述**: 通过ADB命令获取和分析Android设备日志的智能助手。支持获取logcat日志、列出设备、执行shell命令等功能。
|
||
|
||
**工作流结构**:
|
||
|
||
```
|
||
开始 → 意图识别 → JSON解析 → LLM工具调用 → 结束
|
||
```
|
||
|
||
**节点详情**:
|
||
|
||
1. **开始节点** (`start`)
|
||
- 接收用户输入
|
||
- 输入格式: `{"query": "用户请求"}`
|
||
|
||
2. **意图识别节点** (`intent-recognize`)
|
||
- 类型: LLM节点
|
||
- 模型: deepseek-chat
|
||
- 功能: 分析用户请求，提取ADB命令参数
|
||
- 输出格式: JSON
|
||
```json
|
||
{
|
||
"command": "logcat|devices|shell",
|
||
"filter_tag": "标签或shell命令（可选）",
|
||
"level": "V|D|I|W|E|F|S（可选）",
|
||
"max_lines": 100
|
||
}
|
||
```
|
||
|
||
3. **JSON解析节点** (`json-parse`)
|
||
- 类型: JSON节点
|
||
- 功能: 解析意图识别的结果
|
||
- 操作: parse
|
||
|
||
4. **LLM工具调用节点** (`llm-with-tools`)
|
||
- 类型: LLM节点（启用工具调用）
|
||
- 模型: deepseek-chat
|
||
- 启用工具: `adb_log`
|
||
- 功能: 根据解析的参数调用adb_log工具，分析日志内容
|
||
|
||
5. **结束节点** (`end`)
|
||
- 返回最终结果
|
||
|
||
**工作流配置**:
|
||
|
||
```json
|
||
{
|
||
"nodes": [
|
||
{
|
||
"id": "start",
|
||
"type": "start",
|
||
"position": {"x": 100, "y": 200},
|
||
"data": {"label": "开始"}
|
||
},
|
||
{
|
||
"id": "intent-recognize",
|
||
"type": "llm",
|
||
"position": {"x": 400, "y": 200},
|
||
"data": {
|
||
"label": "意图识别",
|
||
"provider": "deepseek",
|
||
"model": "deepseek-chat",
|
||
"temperature": 0.3,
|
||
"max_tokens": 200,
|
||
"prompt": "分析用户请求，提取ADB命令参数..."
|
||
}
|
||
},
|
||
{
|
||
"id": "json-parse",
|
||
"type": "json",
|
||
"position": {"x": 700, "y": 200},
|
||
"data": {
|
||
"label": "解析参数",
|
||
"operation": "parse",
|
||
"json_path": "$"
|
||
}
|
||
},
|
||
{
|
||
"id": "llm-with-tools",
|
||
"type": "llm",
|
||
"position": {"x": 1000, "y": 200},
|
||
"data": {
|
||
"label": "执行ADB命令",
|
||
"provider": "deepseek",
|
||
"model": "deepseek-chat",
|
||
"temperature": 0.7,
|
||
"max_tokens": 2000,
|
||
"enable_tools": true,
|
||
"selected_tools": ["adb_log"],
|
||
"prompt": "根据解析的参数，使用adb_log工具获取Android设备日志..."
|
||
}
|
||
},
|
||
{
|
||
"id": "end",
|
||
"type": "end",
|
||
"position": {"x": 1300, "y": 200},
|
||
"data": {"label": "结束"}
|
||
}
|
||
],
|
||
"edges": [
|
||
{
|
||
"id": "e1",
|
||
"source": "start",
|
||
"target": "intent-recognize"
|
||
},
|
||
{
|
||
"id": "e2",
|
||
"source": "intent-recognize",
|
||
"target": "json-parse"
|
||
},
|
||
{
|
||
"id": "e3",
|
||
"source": "json-parse",
|
||
"target": "llm-with-tools"
|
||
},
|
||
{
|
||
"id": "e4",
|
||
"source": "llm-with-tools",
|
||
"target": "end"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 使用说明
|
||
|
||
### 1. 环境要求
|
||
|
||
**ADB环境**:
|
||
- 需要安装 Android SDK Platform Tools
|
||
- 需要将 `adb` 命令添加到 PATH
|
||
- 需要连接 Android 设备或启动模拟器
|
||
|
||
**验证ADB环境**:
|
||
```bash
|
||
adb version
|
||
adb devices
|
||
```
|
||
|
||
### 2. 测试Agent
|
||
|
||
**使用测试工具**:
|
||
```bash
|
||
# 获取最近的错误日志
|
||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取最近的错误日志"}'
|
||
|
||
# 列出所有连接的设备
|
||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "列出所有连接的设备"}'
|
||
|
||
# 获取ActivityManager的日志
|
||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取ActivityManager的日志"}'
|
||
|
||
# 获取特定级别的日志
|
||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取错误级别的日志"}'
|
||
```
|
||
|
||
**通过API调用**:
|
||
```bash
|
||
curl -X POST http://localhost:8037/api/v1/agents/execute \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
-d '{
|
||
"agent_id": "b68e96d2-da66-4402-86a5-9fae6b5ac092",
|
||
"input_data": {
|
||
"query": "获取最近的错误日志"
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 3. 在前端使用
|
||
|
||
1. 打开 Agent 管理页面
|
||
2. 找到 "Android日志获取助手"
|
||
3. 点击"测试"或"执行"
|
||
4. 输入查询请求，例如：
|
||
- "获取最近的错误日志"
|
||
- "列出所有连接的设备"
|
||
- "获取ActivityManager的日志"
|
||
|
||
---
|
||
|
||
## 📊 功能特点
|
||
|
||
### 1. 智能意图识别
|
||
- 自动分析用户请求
|
||
- 提取ADB命令参数
|
||
- 支持自然语言输入
|
||
|
||
### 2. 灵活的日志过滤
|
||
- 按标签过滤（如 `ActivityManager`、`SystemServer`）
|
||
- 按级别过滤（V/D/I/W/E/F/S）
|
||
- 可限制返回行数
|
||
|
||
### 3. 安全控制
|
||
- Shell命令白名单
|
||
- 超时控制
|
||
- 行数限制
|
||
- 错误处理
|
||
|
||
### 4. 智能分析
|
||
- 自动分析日志内容
|
||
- 提取关键信息
|
||
- 生成总结报告
|
||
|
||
---
|
||
|
||
## 🔧 技术实现
|
||
|
||
### 1. 工具实现
|
||
|
||
**核心技术**:
|
||
- `subprocess` - 执行系统命令
|
||
- `asyncio` - 异步执行和超时控制
|
||
- `json` - 结果格式化
|
||
|
||
**关键代码**:
|
||
```python
|
||
async def adb_log_tool(
|
||
command: str = "logcat",
|
||
filter_tag: Optional[str] = None,
|
||
level: Optional[str] = None,
|
||
max_lines: int = 100,
|
||
timeout: int = 10
|
||
) -> str:
|
||
# 构建adb命令
|
||
if command == "logcat":
|
||
adb_cmd = ["adb", "logcat", "-d"]
|
||
if level:
|
||
adb_cmd.extend([f"*:{level}"])
|
||
if filter_tag:
|
||
adb_cmd.append(filter_tag)
|
||
adb_cmd.extend(["-t", str(max_lines)])
|
||
# ...
|
||
|
||
# 异步执行命令
|
||
result = await asyncio.wait_for(
|
||
asyncio.to_thread(_execute_adb),
|
||
timeout=timeout + 2
|
||
)
|
||
|
||
# 返回JSON格式结果
|
||
return json.dumps({...}, ensure_ascii=False)
|
||
```
|
||
|
||
### 2. Agent工作流
|
||
|
||
**工作流设计**:
|
||
- 使用LLM进行意图识别
|
||
- 使用JSON节点解析参数
|
||
- 使用LLM工具调用执行ADB命令
|
||
- 自动分析和总结结果
|
||
|
||
**数据流**:
|
||
```
|
||
用户输入 → 意图识别 → JSON解析 → 工具调用 → 结果分析 → 输出
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 使用示例
|
||
|
||
### 示例1: 获取错误日志
|
||
|
||
**输入**:
|
||
```json
|
||
{
|
||
"query": "获取最近的错误日志"
|
||
}
|
||
```
|
||
|
||
**处理流程**:
|
||
1. 意图识别: 提取 `command=logcat`, `level=E`
|
||
2. JSON解析: 解析参数
|
||
3. 工具调用: `adb_log(command="logcat", level="E", max_lines=100)`
|
||
4. 结果分析: 分析错误日志，提取关键信息
|
||
|
||
**输出**:
|
||
```
|
||
已获取最近的错误日志，共发现3个错误：
|
||
|
||
1. [2026-01-23 10:30:15] ActivityManager: 应用崩溃
|
||
- 包名: com.example.app
|
||
- 错误类型: NullPointerException
|
||
|
||
2. [2026-01-23 10:31:20] SystemServer: 服务启动失败
|
||
- 服务名: MediaService
|
||
- 错误原因: 权限不足
|
||
|
||
3. [2026-01-23 10:32:05] NetworkManager: 网络连接失败
|
||
- 错误类型: ConnectionTimeout
|
||
- 建议: 检查网络配置
|
||
```
|
||
|
||
### 示例2: 列出设备
|
||
|
||
**输入**:
|
||
```json
|
||
{
|
||
"query": "列出所有连接的设备"
|
||
}
|
||
```
|
||
|
||
**处理流程**:
|
||
1. 意图识别: 提取 `command=devices`
|
||
2. JSON解析: 解析参数
|
||
3. 工具调用: `adb_log(command="devices")`
|
||
4. 结果分析: 格式化设备列表
|
||
|
||
**输出**:
|
||
```
|
||
已找到2个连接的设备：
|
||
|
||
1. emulator-5554
|
||
- 状态: device
|
||
- 型号: Android SDK built for x86
|
||
|
||
2. 192.168.1.100:5555
|
||
- 状态: device
|
||
- 型号: SM-G991B
|
||
```
|
||
|
||
### 示例3: 获取特定标签日志
|
||
|
||
**输入**:
|
||
```json
|
||
{
|
||
"query": "获取ActivityManager的日志"
|
||
}
|
||
```
|
||
|
||
**处理流程**:
|
||
1. 意图识别: 提取 `command=logcat`, `filter_tag=ActivityManager`
|
||
2. JSON解析: 解析参数
|
||
3. 工具调用: `adb_log(command="logcat", filter_tag="ActivityManager", max_lines=100)`
|
||
4. 结果分析: 分析ActivityManager日志
|
||
|
||
**输出**:
|
||
```
|
||
已获取ActivityManager日志，共100行：
|
||
|
||
关键活动：
|
||
- 应用启动: com.example.app (10:30:15)
|
||
- Activity切换: MainActivity → SettingsActivity (10:31:20)
|
||
- 应用关闭: com.example.app (10:32:05)
|
||
|
||
性能指标：
|
||
- 平均启动时间: 1.2秒
|
||
- Activity切换次数: 15次
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. ADB环境要求
|
||
- ✅ 必须安装 Android SDK Platform Tools
|
||
- ✅ 必须将 `adb` 命令添加到 PATH
|
||
- ✅ 必须连接 Android 设备或启动模拟器
|
||
|
||
### 2. 安全限制
|
||
- ✅ Shell命令只允许执行安全命令
|
||
- ✅ 不允许执行危险命令（如 `rm`、`reboot` 等）
|
||
- ✅ 超时控制防止长时间执行
|
||
- ✅ 行数限制防止输出过长
|
||
|
||
### 3. 性能优化
|
||
- ✅ 默认限制返回100行日志
|
||
- ✅ 支持超时控制（默认10秒）
|
||
- ✅ 异步执行避免阻塞
|
||
|
||
### 4. 错误处理
|
||
- ✅ 处理ADB命令执行失败
|
||
- ✅ 处理设备未连接情况
|
||
- ✅ 处理超时情况
|
||
- ✅ 详细的错误信息返回
|
||
|
||
---
|
||
|
||
## 🚀 扩展建议
|
||
|
||
### 1. 功能扩展
|
||
- [ ] 支持实时日志监控（logcat -c）
|
||
- [ ] 支持日志保存到文件
|
||
- [ ] 支持日志搜索和过滤
|
||
- [ ] 支持多设备管理
|
||
- [ ] 支持日志分析和统计
|
||
|
||
### 2. 安全增强
|
||
- [ ] 添加用户权限控制
|
||
- [ ] 添加命令执行审计
|
||
- [ ] 添加设备访问控制
|
||
- [ ] 添加日志访问记录
|
||
|
||
### 3. 性能优化
|
||
- [ ] 支持日志缓存
|
||
- [ ] 支持增量获取
|
||
- [ ] 支持并行处理
|
||
- [ ] 支持结果压缩
|
||
|
||
---
|
||
|
||
## 📊 统计信息
|
||
|
||
- **工具数量**: 1个（adb_log）
|
||
- **Agent数量**: 1个（Android日志获取助手）
|
||
- **工作流节点数**: 5个
|
||
- **代码行数**: 约200行（工具实现）+ 约150行（Agent脚本）
|
||
- **完成时间**: 2026-01-23
|
||
|
||
---
|
||
|
||
## 🎉 总结
|
||
|
||
本次实现了完整的ADB工具和Android日志获取Agent，包括：
|
||
|
||
1. ✅ **ADB日志工具** - 功能完整、安全可靠
|
||
2. ✅ **工具注册** - 已集成到工具注册表
|
||
3. ✅ **Agent工作流** - 智能意图识别和工具调用
|
||
4. ✅ **文档完善** - 使用说明和示例齐全
|
||
|
||
Agent已经可以正常使用，支持通过自然语言请求获取Android设备日志，并自动分析和总结结果。
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-01-23
|
||
**文档版本**: v1.0
|
||
**状态**: 已完成 ✅
|