Android Logcat 日志分析工具

一个用 Python 编写的 Android 测试辅助工具。输入 adb logcat 日志后，程序会筛选崩溃、ANR、权限、网络和安装相关异常，并生成 Markdown 分析报告。

使用场景

Android 应用或系统测试通常需要重复完成以下步骤：

1. 连接设备；
2. 安装或启动应用；
3. 复现问题；
4. 抓取 Logcat 日志；
5. 查找崩溃、ANR、权限或网络异常；
6. 整理问题反馈。

这个工具负责第 5 步，并为第 6 步生成可以继续补充的问题记录。

功能

• 解析 adb logcat -v threadtime 格式的日志；
• 统计不同日志级别和高频 Tag；
• 识别常见 Android 异常：
  • FATAL EXCEPTION；
  • ANR；
  • Crash / Force finishing；
  • Permission Denial；
  • 网络超时、DNS 和 TLS 错误；
  • 应用安装失败；
  • ActivityManager / WindowManager 相关线索；
• 输出包含问题分类、关键日志和问题单字段的 Markdown 报告；
• 可在本地生成日志复核提示词，不会自动向任何 API 发送日志。

快速运行

python -m venv .venv
.\.venv\Scripts\activate
pip install -e . pytest
python -m logcat_triage.cli examples\sample_logcat.txt -o examples\sample_report.md
pytest -q

运行后可以在 examples/sample_report.md 查看示例分析报告。

连接真实设备

adb devices
adb shell getprop ro.product.model
adb shell getprop ro.build.version.release
adb logcat -c
adb logcat -v threadtime > logcat.txt
python -m logcat_triage.cli logcat.txt -o logcat_report.md

抓取完成后，可以把报告中的关键信息整理到 docs/issue_template.md。

真机验证：以荣耀 Magic7 Pro 为例

本项目已在荣耀 Magic7 Pro（型号 PTP-AN10、Android 16、MagicOS 10.0.0）上完成一次真实设备验证。

验证过程中遇到并处理了两个量产机问题：

1. Windows 能识别手机和 ADB Interface，但 adb devices 无设备。该机使用通用 WinUSB 驱动，设置 ADB_LIBUSB=1 后可正常建立 ADB 连接。
2. 初次执行 adb logcat 只能看到 HKS/HKE 加密头。按照荣耀开发者文档进入工程菜单并开启 AP LOG 后，可以读取正常的 main、system 等日志缓冲区。

$env:ADB_LIBUSB = "1"
adb devices -l
adb shell getprop ro.product.model
adb shell getprop ro.build.version.release
adb logcat -c
adb shell am start -W -a android.settings.SETTINGS
adb logcat -d -v threadtime -t 1000 > magic7pro-settings-logcat.txt
python -m logcat_triage.cli magic7pro-settings-logcat.txt -o magic7pro-settings-report.md

本次共解析 1003 行输出，得到日志级别统计、高频 Tag 和分类线索，并通过现有 3 个 pytest 用例。该案例用于验证从真机连接、场景操作、日志抓取到报告生成的完整流程；报告中的系统级 Error 或 Warning 仍需结合复现步骤判断，不能直接视为应用缺陷。

测试结束后应关闭 AP LOG，避免设备长期记录系统日志。

真机原始日志可能包含设备状态、应用包名等信息，因此不提交到公开仓库；仓库中的 examples/ 仅保留脱敏示例。

项目结构

• src/logcat_triage/parser.py：日志解析和问题分类；
• src/logcat_triage/cli.py：命令行入口；
• src/logcat_triage/ai_prompt.py：可选的本地复核提示词生成器，不会调用外部 API；
• examples/sample_logcat.txt：测试用示例日志；
• examples/sample_report.md：生成的示例报告；
• docs/android_test_sop.md：Android 问题复现流程；
• docs/issue_template.md：问题反馈模板；
• tests/test_parser.py：日志解析、分类和报告生成测试。

输出示例

# Android Logcat Triage Report

- Source: `sample_logcat.txt`
- Total lines: 8
- High risk issue found: yes

## Findings

### fatal_exception

FATAL EXCEPTION: main
java.lang.NullPointerException

当前限制

• 目前只解析 -v threadtime 格式的 Logcat 日志；
• 问题分类基于规则匹配，厂商定制日志可能需要补充规则；
• 仓库中的示例日志用于重复测试，真实设备结果取决于具体复现场景。

测试

pytest -q

当前测试覆盖日志解析、问题分类和 Markdown 报告生成。每次提交代码后，GitHub Actions 会自动运行测试。

License

MIT