# 启动排查（遇到"打不开 / 白屏 / 连接失败"看这里）

按顺序试，多数问题能自己解决。仍不行再开 Issue（附文末信息）。

---

## 现象 1：安装后点开就闪退/秒退

- 确认装的是 **v1.1.1 或更新**版本（v1.3.1 最佳）。v1.0.0 / v1.2.0 是坏版本，必须换。
- 换版本前先卸载旧的，再装新的。

## 现象 2：一直"正在启动" / 转圈 / 白屏

- **首次启动要解压运行时（1-3 分钟）**：2 万+ 个文件，进度条走完前**别切后台、别锁屏**。解压被打断 = 启动失败。
- 解压后若仍失败，**彻底杀掉 App 再重开**（后台任务里划掉）。看门狗每 5 秒检查引擎，会自动重试拉起。

## 现象 3：页面显示"无法访问此网站 / ERR_CONNECTION_REFUSED"

这是**引擎（node）没起来**，最常见原因：

1. **电池优化没设"不限制"** → App 切后台被系统杀，引擎跟着死。设置：系统设置 → 电池/应用管理 → DeepSeek Harness → 电池优化 → **不限制**（Shizuku 也同样设置）
2. **解压不完整** → 设置 → 应用 → DeepSeek Harness → 清除数据，重新打开完整解压（会重置设置，需重新填 API Key）
3. **旧版本 bug** → 升级到最新版（见上）
4. 等待 10-30 秒自动重试（WebView 每 2.5s 重试，最多 120 次）

## 现象 4：可以打开，但 AI 不回复

- 检查 API Key：App 内设置页填写是否正确、是否过期（DeepSeek 平台可查看/重置）
- 与"启动失败"无关，走外网；**不需要挂梯子**（页面是本地 127.0.0.1 服务，与网络无关）

---

## 需要提交的排查信息（开 Issue 时附上）

用 [Bug 模板](https://github.com/woaiys3/deepseek-harness-android-app/issues/new?template=bug_report.md) 或直接提供：

1. **App 版本**：v1.x.x（Release 页 / 设置页可见）
2. **手机型号 + Android 版本**：如 ColorOS 14 / MIUI 15 / 原生 14
3. **Shizuku**：服务是否在运行（授权 ≠ 运行，打开 Shizuku App 看）
4. **页面显示什么**：截图或文字（白屏 / 转圈 / "无法访问" / 闪退）
5. **崩溃日志**：文件管理器打开 `/sdcard/DeepSeekHarness/crash.log`，把内容贴出来
6. **引擎日志**（可选，需 adb）：`adb shell cat /data/user/0/com.deepseek.harness/files/dsh-web.log`

---

## 维护者排查顺序（内部参考）

1. logcat `ClassNotFoundException: MainActivity` → dex 坏包 → 重新全量打包
2. 引擎自测：抽 APK payload 实测 HTTP 200（交接文档第四节）
3. `dsh-web.log`：node 是否起来、报什么错
4. 补丁完整性：`files/payload/dshhome/cordis.patch.yml` 是否存在且含 `llm-pi-ai/sandbox: disabled`（首次解压不完整会缺）
5. 确认启动命令**没有** `--patch`（补丁自动加载，加了 duplicate 崩溃）
6. 外部运行目录 `/sdcard/DeepSeekHarness/dshroot/` 是否与 APK 同步（layout `gridColumn: 2` 是否在）