# WpsCrashToolCLI

**Repository Path**: abbasspace/wps-crash-tool-cli

## Basic Information

- **Project Name**: WpsCrashToolCLI
- **Description**: wps-crash-tool-cli
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-06
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 顽皮狮Crash助手

面向外部用户的 Windows 控制台采集工具。双击 `顽皮狮Crash助手.exe` 即可在 Android / Android TV 上引导完成缺陷数据采集，并打包为 zip，由用户自行发送给对接人。

| 项 | 说明 |
|----|------|
| 产物 | `顽皮狮Crash助手.exe`（Go 单文件，免安装） |
| 默认目标 App | `com.wpsky.android`（乐视 / 华为等特殊渠道会根据设备与前台应用自动识别） |
| 设备桥接 | 外置 adb；缺失时控制台引导下载官方 platform-tools |
| 报告目录 | `%LOCALAPPDATA%\顽皮狮Crash助手\reports\`（失败时回退 Temp） |

---

## 功能特性

- **一键引导采集**：设备发现 → 打开 App 复现 → 结束录制 → 自动打包
- **USB / 无线调试**：支持 `adb devices` 与 `adb connect IP:端口`（适合 Android TV）
- **多设备选择**：全部命令带 `-s <serial>`，避免串台
- **动态 + 静态数据**：logcat、system trace（Systrace / Perfetto）、dumpsys、getprop、crash buffer
- **运行状态补偿采样**：system trace 不可用时仍采集基线、1s 周期采样、关键事件与复现超时快照
- **跨版本兼容**：Android 4.4+ 按 API 选择 atrace / Perfetto；失败写入摘要，不阻断主流程
- **产物内容校验**：Systrace / Perfetto 不仅检查非空，还会校验格式与有效事件
- **交付友好**：生成 zip 后打开目录，并尽量复制路径到剪贴板

---

## 快速开始

1. 在目标设备上开启 **开发者选项 → USB 调试**（TV 常用无线调试）。
2. 双击运行 `顽皮狮Crash助手.exe`。
3. 若本机无 adb，按控制台提示下载官方 platform-tools。
4. 选择设备 → 打开顽皮狮 App 并准备复现 → 确认开始录制。
5. 复现问题后选择「结束录制」，填写描述（可跳过）。
6. 将生成的 `BugReport_*.zip` 发给对接人。

---

## 使用流程

```mermaid
flowchart TD
  A[启动] --> B{检测 adb}
  B -->|缺失| C[控制台引导下载 platform-tools]
  C --> D
  B -->|可用| D[adb devices]
  D --> E{选择设备}
  E --> F[展示机型 / Android / API 等]
  F --> G[引导打开 App 并确认]
  G --> H[清 logcat + 录制日志 + 启动 trace / 运行状态采样]
  H --> I{复现中}
  I -->|结束录制| J[停止录制 / 静态采集 / 可选描述]
  J --> K[打包 zip 并打开目录]
  K --> L{再收集一次?}
  L -->|是| D
  L -->|否| Z[结束]
  I -->|丢弃| M{再次录制?}
  M -->|是| G
  M -->|否| Z
```

交互文案与状态细节见 [MENU_COPY](docs/MENU_COPY.md)、[ARCHITECTURE](docs/ARCHITECTURE.md)。可交互流程图：[flowchart.json](flowchart.json)。

---

## 报告内容

单次采集目录示例：

```
BugReport_<型号>_<Android版本>_<yyyyMMdd_HHmmss>/
├── device_info.txt
├── tool_version.txt
├── collection_summary.txt
├── user_description.txt
├── logcat_full.txt
├── logcat_filtered.txt
├── logcat_crash.txt
├── getprop.txt
├── dumpsys/
│   ├── activity.txt
│   ├── window.txt
│   ├── meminfo.txt
│   ├── cpuinfo.txt
│   ├── gfxinfo.txt
│   └── surfaceflinger.txt
├── systrace.txt / systrace.ctrace / perfetto.trace   # system trace 成功时之一
├── system_trace_failed.txt / perfetto_failed.txt     # 失败说明（如有）
├── trace_probe.txt                                   # atrace/perfetto smoke 探测
├── runtime_baseline.txt                              # 录制前基线
├── runtime_samples.csv                               # 1s 周期采样
├── runtime_final.txt                                 # 结束快照与峰值
├── events.csv                                        # 关键 logcat / 生命周期事件
├── process_lifecycle.txt                             # 目标 PID 出现 / 消失 / 重启
├── runtime_timeout_10s.txt                           # 复现开始后诊断快照
├── runtime_timeout_20s.txt
└── runtime_timeout_30s.txt
```

同目录会生成对应 `BugReport_*.zip`。

### 采集优先级

1. **logcat**（crash 与目标包名相关日志）
2. **system trace**（默认 Systrace/atrace，必要时降级 Perfetto）
3. **运行状态采样**（trace 不可用时的补偿：/proc 采样、事件、复现超时诊断）
4. **设备信息 + dumpsys + getprop**
5. **用户文字描述**（可选）

### 运行状态采样说明

| 产物 | 用途 |
|------|------|
| `runtime_baseline.txt` | 复现前设备 / 进程内存与负载基线 |
| `runtime_samples.csv` | 约 1s 采样 CPU、RSS、PSS、可用内存、前台 Activity 等 |
| `events.csv` | 崩溃 / ANR / Unity / Surface 等关键 logcat 事件 |
| `process_lifecycle.txt` | 目标 PID 与 Activity 变化 |
| `runtime_timeout_*.txt` | 复现开始后 10/20/30s 诊断快照 |
| `runtime_final.txt` | 结束时快照与峰值摘要 |

`runtime_samples.csv` 关键字段：

- `cpu_app` / `rss_kb` / `pss_kb`：对全部目标进程汇总（宿主 + `:game_runtime` 等 secondary）
- `cpu_host` / `cpu_secondary`、`rss_host` / `rss_secondary` / `rss_total`、`pss_*`：宿主与 secondary 分项
- `target_pids` / `target_processes`：本轮采样观察到的 PID 与进程名
- `pss_valid=1`：当前 `pss_kb` 可用（含沿用最近一次有效值）
- `pss_fresh=1`：本轮刚执行并解析 `dumpsys meminfo`
- `mem_available_source=MemAvailable|estimated`：原生字段或 `MemFree+Buffers+Cached` 估算（Android 5.x 常见）
- 未采集到的数值写空，不伪装成 `0`

`events.csv` 字段：`event_type,severity,is_actionable,source,message`。低内存相关类型已拆分为 `LOW_MEMORY_KILL` / `MEMORY_PRESSURE` / `SELINUX_DENIED` / `OOM`，避免把 `avc: denied`（含 lmkd 域）误报为低内存。

停止采样时的 `context canceled` 不会记入摘要；单次采样超时（`deadline exceeded`）会保留，便于发现老设备卡顿。

---

## System Trace 策略

产品默认：**Systrace/atrace → Perfetto → 日志 + 运行状态采样**。降级只发生在**启动阶段**；Stop / 拉取失败不会再切换后端。

trace 不可用时录制状态显示为「录制中（日志 + 运行状态采样）」。失败原因会区分：

- tracing debugfs 不存在
- tracing debugfs 存在但无权限
- atrace 启动失败
- atrace 启动成功但没有真实事件

| Android | API | 行为 |
|---------|-----|------|
| < 4.4 | < 19 | 跳过 system trace |
| 4.4–8.1 | 19–27 | 仅 Systrace/atrace（async → timed） |
| 9–12 | 28–31 | 先 Systrace；启动失败再 Perfetto |
| 13+ | ≥ 33 | 先 Systrace；启动失败再 Perfetto |

产物经内容校验后才视为成功（例如 Systrace 需具备 `TRACE:`、有效 entries、sched 等真实事件）。实现细节见 [ARCHITECTURE](docs/ARCHITECTURE.md)。

---

## 已验证机型

基于 `%LOCALAPPDATA%\顽皮狮Crash助手\reports\` 实机报告（截至 2026-09-07）。  
「Systrace 正常」表示至少一份产物通过内容校验，而非仅文件非空。

| 品牌 | 机型 | Android | API | Systrace |
|------|------|---------|-----|----------|
| 创维 Skyworth | 1AA46_A3F | 9 | 28 | 正常 |
| TCL | ak30a5 | 9 | 28 | 正常 |
| 华为 HUAWEI | KUNL-260Y | 12 | 31 | 正常（亦有成功 Perfetto） |
| 海信 Hisense | VIDAA_TV | 11 | 30 | 正常 |
| 乐视 Letv | X4-40 | 6.0 | 23 | 正常 |
| 海思盒子 HiSTBAndroidV6 | M301H_1U9_GD50 | 4.4.2 | 19 | 未成功（设备无 ftrace debugfs） |
| 小米盒子 MiBOX3_PRO | 无线调试 | 5.1 | 22 | 未成功（有 debugfs，shell 无权写 tracing） |

完整报告中 logcat / dumpsys / getprop / 运行状态采样均可采集；上表仅反映 system trace 有效性。

### MiBOX3_PRO（Android 5.1）说明

该设备上 atrace **确实不可用**：`/sys/kernel/debug/tracing` 存在，但非 root 的 `shell` 无写权限（量产机 `adbd cannot run as root`）。工具会走运行状态采样补偿，并在摘要中归类为「tracing debugfs 存在但无权限」，而不是笼统写成「debugfs 不存在」。

---

## 构建

环境：Go 1.21+（Windows）。

```powershell
# 推荐
.\compile\build.bat
```

或：

```powershell
go build -ldflags "-X wpsky/crashtool/internal/version.Version=x.y.z" -o 顽皮狮Crash助手.exe ./cmd/crashtool
```

---

## 文档

| 文档 | 说明 |
|------|------|
| [ARCHITECTURE](docs/ARCHITECTURE.md) | 全局架构与模块划分 |
| [BUSINESS_REVIEW](docs/BUSINESS_REVIEW.md) | 业务结论与边界 |
| [MENU_COPY](docs/MENU_COPY.md) | 控制台文案与交互 |
| [flowchart.json](flowchart.json) | 可交互业务流程图 |