admin/aiagent

Fork 0

Files

rjb 9d3198f6bc 知你客服

2026-03-06 22:31:41 +08:00

13 KiB

Raw Permalink Blame History

ADB工具和Android日志Agent搭建总结

✅ 完成状态

任务: 创建ADB工具和Android日志获取Agent
状态: ✅ 已完成
完成时间: 2026-01-23

📋 实现内容

1. ADB日志工具（adb_log）✅

文件位置: backend/app/services/builtin_tools.py

功能描述:

通过ADB命令获取Android设备日志
支持多种ADB命令类型
支持日志过滤和级别控制
支持超时和行数限制

支持的命令类型:

logcat - 获取日志
- 获取Android设备的logcat日志
- 支持按标签过滤（如 ActivityManager、SystemServer）
- 支持按级别过滤（V/D/I/W/E/F/S）
- 支持限制返回行数
devices - 列出设备
- 列出所有连接的Android设备
- 显示设备详细信息
shell - 执行shell命令（受限）
- 只允许执行安全命令
- 支持的命令：getprop、dumpsys、pm、am、settings
- 不允许执行危险命令（如 rm、reboot 等）

工具参数:

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:

{
  "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
        }
      }
    }
  }
}

返回格式:

{
  "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

注册代码:

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工具调用 → 结束

节点详情:

开始节点 (start)
- 接收用户输入
- 输入格式: {"query": "用户请求"}

意图识别节点 (intent-recognize)

类型: LLM节点
模型: deepseek-chat
功能: 分析用户请求，提取ADB命令参数
输出格式: JSON

{
  "command": "logcat|devices|shell",
  "filter_tag": "标签或shell命令（可选）",
  "level": "V|D|I|W|E|F|S（可选）",
  "max_lines": 100
}

JSON解析节点 (json-parse)
- 类型: JSON节点
- 功能: 解析意图识别的结果
- 操作: parse
LLM工具调用节点 (llm-with-tools)
- 类型: LLM节点（启用工具调用）
- 模型: deepseek-chat
- 启用工具: adb_log
- 功能: 根据解析的参数调用adb_log工具，分析日志内容
结束节点 (end)
- 返回最终结果

工作流配置:

{
  "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环境:

adb version
adb devices

2. 测试Agent

使用测试工具:

# 获取最近的错误日志
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调用:

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. 在前端使用

打开 Agent 管理页面
找到 "Android日志获取助手"
点击"测试"或"执行"
输入查询请求，例如：
- "获取最近的错误日志"
- "列出所有连接的设备"
- "获取ActivityManager的日志"

📊 功能特点

1. 智能意图识别

自动分析用户请求
提取ADB命令参数
支持自然语言输入

2. 灵活的日志过滤

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

3. 安全控制

Shell命令白名单
超时控制
行数限制
错误处理

4. 智能分析

自动分析日志内容
提取关键信息
生成总结报告

🔧 技术实现

1. 工具实现

核心技术:

subprocess - 执行系统命令
asyncio - 异步执行和超时控制
json - 结果格式化

关键代码:

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: 获取错误日志

输入:

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

处理流程:

意图识别: 提取 command=logcat, level=E
JSON解析: 解析参数
工具调用: adb_log(command="logcat", level="E", max_lines=100)
结果分析: 分析错误日志，提取关键信息

输出:

已获取最近的错误日志，共发现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: 列出设备

输入:

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

处理流程:

意图识别: 提取 command=devices
JSON解析: 解析参数
工具调用: adb_log(command="devices")
结果分析: 格式化设备列表

输出:

已找到2个连接的设备：

1. emulator-5554
   - 状态: device
   - 型号: Android SDK built for x86

2. 192.168.1.100:5555
   - 状态: device
   - 型号: SM-G991B

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

输入:

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

处理流程:

意图识别: 提取 command=logcat, filter_tag=ActivityManager
JSON解析: 解析参数
工具调用: adb_log(command="logcat", filter_tag="ActivityManager", max_lines=100)
结果分析: 分析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，包括：

✅ ADB日志工具 - 功能完整、安全可靠
✅ 工具注册 - 已集成到工具注册表
✅ Agent工作流 - 智能意图识别和工具调用
✅ 文档完善 - 使用说明和示例齐全

Agent已经可以正常使用，支持通过自然语言请求获取Android设备日志，并自动分析和总结结果。

最后更新: 2026-01-23
文档版本: v1.0
状态: 已完成 ✅

13 KiB Raw Permalink Blame History Unescape Escape

ADB工具和Android日志Agent搭建总结

✅ 完成状态

📋 实现内容

1. ADB日志工具（adb_log）✅

2. 工具注册 ✅

3. Android日志获取助手Agent ✅

🎯 使用说明

1. 环境要求

2. 测试Agent

3. 在前端使用

📊 功能特点

1. 智能意图识别

2. 灵活的日志过滤

3. 安全控制

4. 智能分析

🔧 技术实现

1. 工具实现

2. Agent工作流

📝 使用示例

示例1: 获取错误日志

示例2: 列出设备

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

⚠️ 注意事项

1. ADB环境要求

2. 安全限制

3. 性能优化

4. 错误处理

🚀 扩展建议

1. 功能扩展

2. 安全增强

3. 性能优化

📊 统计信息

🎉 总结

13 KiB

Raw Permalink Blame History