# 🔧 故障排查指南

> 工作手机Agent常见问题解决方案

---

## 📋 目录

1. [连接问题](#连接问题)
2. [语音识别问题](#语音识别问题)
3. [命令执行问题](#命令执行问题)
4. [性能问题](#性能问题)
5. [权限问题](#权限问题)

---

## 🔌 连接问题

### 问题1：无法连接服务器

**症状：**
- 状态显示"未连接"
- 红色圆点

**排查步骤：**

1. **检查服务器地址**
   ```
   格式：ws://服务器地址:端口/ws/device
   示例：ws://sdk.quwanzhi.com:8899/ws/device
   ```

2. **检查网络连接**
   - 确保手机能上网
   - 尝试访问其他网站
   - 检查WiFi/移动数据

3. **检查防火墙**
   - 确保端口8899未被阻止
   - 检查企业网络限制

4. **检查服务器状态**
   - 联系管理员确认服务器运行状态
   - 检查服务器日志

**解决方案：**
```bash
# 测试连接
ping 服务器地址

# 测试端口
telnet 服务器地址 8899
```

---

### 问题2：连接后频繁断开

**症状：**
- 连接成功但很快断开
- 状态在"已连接"和"未连接"之间切换

**排查步骤：**

1. **检查网络稳定性**
   - WiFi信号强度
   - 移动数据信号
   - 网络波动

2. **检查电池优化**
   - 设置 → 电池 → 电池优化
   - 找到"工作手机Agent"
   - 选择"不优化"

3. **检查后台限制**
   - 设置 → 应用 → 工作手机Agent
   - 确保"后台活动"开启

**解决方案：**
- 关闭电池优化
- 允许后台运行
- 使用稳定的WiFi网络

---

## 🎤 语音识别问题

### 问题1：无法识别语音

**症状：**
- 点击麦克风无反应
- 显示"设备不支持语音识别"

**排查步骤：**

1. **检查麦克风权限**
   ```
   设置 → 应用 → 工作手机Agent → 权限
   确保"麦克风"权限已开启
   ```

2. **检查设备支持**
   - Android 5.0+
   - 确保设备有麦克风

3. **检查其他应用占用**
   - 关闭其他使用麦克风的应用
   - 重启APP

**解决方案：**
- 授予麦克风权限
- 重启APP
- 重启手机

---

### 问题2：识别不准确

**症状：**
- 识别结果错误
- 识别为空

**排查步骤：**

1. **环境因素**
   - 环境噪音
   - 距离麦克风太远
   - 说话声音太小

2. **说话方式**
   - 语速过快
   - 口齿不清
   - 方言太重

3. **网络问题**
   - 语音识别需要网络（部分设备）
   - 检查网络连接

**解决方案：**
- 在安静环境中使用
- 说话清晰，语速适中
- 靠近手机麦克风
- 使用标准普通话

---

## ⚙️ 命令执行问题

### 问题1：命令执行失败

**症状：**
- 显示"执行失败"
- 应用未打开
- 操作无效果

**排查步骤：**

1. **检查无障碍服务**
   ```
   设置 → 无障碍 → 工作手机Agent
   确保服务已开启
   ```

2. **检查应用安装**
   - 确保目标应用已安装
   - 检查应用名称是否正确

3. **检查权限**
   - ADB调试权限（如果使用Shell方式）
   - Root权限（如果使用SU方式）

**解决方案：**

**方案1：开启无障碍服务（推荐）**
```
设置 → 无障碍 → 工作手机Agent → 开启
```

**方案2：使用ADB方式**
```bash
# 开启USB调试
设置 → 关于手机 → 连续点击版本号7次
设置 → 开发者选项 → USB调试

# 连接电脑，执行
adb devices
```

**方案3：使用Root方式**
- 需要Root权限
- 使用Magisk等工具

---

### 问题2：搜索功能不工作

**症状：**
- 搜索命令执行但无效果
- 搜索框未找到

**排查步骤：**

1. **检查应用界面**
   - 确保应用已完全加载
   - 检查搜索框是否存在

2. **检查无障碍服务**
   - 无障碍服务可以更准确地找到搜索框
   - 建议开启

3. **检查输入法**
   - 确保输入法支持中文
   - 尝试手动输入测试

**解决方案：**
- 开启无障碍服务
- 等待应用完全加载后再搜索
- 使用更具体的搜索命令

---

## ⚡ 性能问题

### 问题1：APP运行缓慢

**症状：**
- 响应延迟
- 卡顿
- 内存占用高

**排查步骤：**

1. **检查内存使用**
   ```
   设置 → 应用 → 工作手机Agent → 存储
   查看内存使用情况
   ```

2. **检查后台应用**
   - 关闭不必要的后台应用
   - 清理内存

3. **检查日志**
   ```
   /sdcard/workphone_agent/logs/
   查看是否有性能警告
   ```

**解决方案：**
- 清理后台应用
- 重启APP
- 重启手机
- 查看日志中的性能警告

---

### 问题2：电池消耗快

**症状：**
- 电池快速消耗
- 手机发热

**排查步骤：**

1. **检查后台活动**
   - WebSocket连接会持续运行
   - 这是正常现象

2. **检查网络使用**
   - 心跳包每30秒一次
   - 数据量很小

3. **检查CPU使用**
   - 查看系统监控
   - 检查是否有异常

**解决方案：**
- 关闭不必要的功能
- 降低心跳频率（需要修改代码）
- 使用WiFi而非移动数据

---

## 🔐 权限问题

### 问题1：权限被拒绝

**症状：**
- 提示权限不足
- 功能无法使用

**排查步骤：**

1. **检查权限列表**
   ```
   设置 → 应用 → 工作手机Agent → 权限
   检查所有权限状态
   ```

2. **必需权限**
   - ✅ 麦克风
   - ✅ 相机
   - ✅ 通知
   - ✅ 网络

3. **推荐权限**
   - ✅ 无障碍服务
   - ✅ 后台运行
   - ✅ 自启动

**解决方案：**
- 手动授予所有权限
- 重启APP
- 如果仍不行，卸载重装

---

### 问题2：无障碍服务无法开启

**症状：**
- 设置中找不到服务
- 开启后立即关闭

**排查步骤：**

1. **检查系统版本**
   - 需要Android 5.0+
   - 检查系统更新

2. **检查其他服务冲突**
   - 关闭其他无障碍服务
   - 重启手机

3. **检查系统限制**
   - 某些定制系统有限制
   - 检查系统设置

**解决方案：**
- 更新系统
- 关闭其他无障碍服务
- 重启手机
- 如果仍不行，使用Shell命令方式

---

## 📊 日志分析

### 查看日志

**位置：**
```
/sdcard/workphone_agent/logs/agent_YYYY-MM-DD.log
```

**查看方法：**
1. 使用文件管理器
2. 或使用ADB：
   ```bash
   adb pull /sdcard/workphone_agent/logs/agent_2026-01-27.log
   ```

### 日志级别

- **DEBUG** - 调试信息
- **INFO** - 一般信息
- **WARN** - 警告信息
- **ERROR** - 错误信息

### 常见错误

**错误1：Permission denied**
```
原因：权限不足
解决：授予相应权限
```

**错误2：Connection refused**
```
原因：无法连接服务器
解决：检查服务器地址和网络
```

**错误3：Element not found**
```
原因：UI元素未找到
解决：开启无障碍服务或检查应用界面
```

---

## 🆘 无法解决？

如果以上方法都无法解决问题：

1. **收集信息**
   - 日志文件
   - 设备信息
   - 问题描述
   - 操作步骤

2. **联系支持**
   - 微信：28533368
   - 电话：15880802661
   - 邮箱：zhiqun@qq.com

3. **提供信息**
   - 设备型号
   - Android版本
   - APP版本
   - 错误日志
   - 问题截图

---

**最后更新：** 2026-01-27
