# 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  
**状态**: 已完成 ✅