# 08 桌面客户端（Mac / Windows）

不想敲命令、不想用 AI 工具，用桌面客户端：插上手机，点几下按钮。
客户端调用的是同一套引擎（`tool/`），命令行能做的它都能做。

> **版本说明（2026-10-25）**：当前版本为 **0.2.3**，包含 Windows 页面超时、清单链接、打包任务、通知状态核对及小米入口等修复。旧版不会自动更新，请重新下载；原来的数据与备份目录继续保留。测试范围和兼容性限制见[更新记录](../CHANGELOG.md)。

| 平台 | 安装包 | 状态 |
|---|---|---|
| macOS（Apple 芯片） | `AndroidAdCleaner-<版本>-mac-arm64.dmg` | 已签名、公证；原生界面、图片、JS API 及内置命令行验证通过 |
| macOS（Intel 芯片） | `AndroidAdCleaner-<版本>-mac-intel.dmg` | 已签名、公证；在 Apple 芯片 Mac 的 Rosetta 下测过，Intel 真机待测 |
| Windows 10 / 11（64 位） | `AndroidAdCleaner-<版本>-windows-setup.exe`（安装版）<br>`AndroidAdCleaner-<版本>-windows-portable.zip`（免安装） | GitHub Actions 云端打包，冒烟测试通过（命令行、中文输出、原生 GUI、图片和 JS API）；连接手机及报告者电脑待测 |

## 下载和安装

在 [Releases 页面](https://github.com/rddmwmddr/android-ad-cleaner/releases/latest) 下载对应的安装包。

不知道自己的 Mac 是哪种芯片：点屏幕左上角的苹果图标 → 关于本机，「芯片」一栏写 Apple M 开头的是 Apple 芯片，写 Intel 的是 Intel 芯片。

**Mac**

1. 双击 dmg，把「安卓去广告」拖到旁边的「应用程序」文件夹。
2. 打开「安卓去广告」。安装包已经过苹果公证，双击就能打开。

**Windows**

1. 双击 `…-windows-setup.exe` 安装。不想安装，下载 `…-windows-portable.zip`，解压后双击 `AndroidAdCleaner.exe`。
2. 安装程序没有代码签名，Windows 会弹蓝色的「Windows 已保护你的电脑」：点「更多信息」→「仍要运行」。
3. 打开后提示缺少 WebView2：点「确定」去微软官网，下载安装「Evergreen Bootstrapper」，再打开本程序。Windows 11 自带，部分 Windows 10 要装。
4. 插上手机后客户端认不到：这台电脑缺手机的 USB 驱动，见下面「Windows 驱动」。

不需要装 Python，也不需要任何 AI 工具。电脑上没有 adb 的话，第一次打开时客户端会提示从 Google 官网下载（约 10 MB，只下一次）。

## 五步

**1. 连接手机**：插上数据线，客户端会认出手机。还没打开 USB 调试，页面里有图文教程。电脑上没有 adb，客户端会提示从 Google 官网下载。

<p align="center"><img src="../images/gui-1-connect.png" width="640" alt="连接手机"></p>
<p align="center"><img src="../images/gui-2-tutorial.png" width="640" alt="开启 USB 调试的图文教程"></p>

**2. 检测**：读出型号、系统版本、有没有机型脚本、快应用和广告组件的状态。只读，不改东西。手机锁屏、折叠屏展开时会提示。

<p align="center"><img src="../images/gui-3-detect.png" width="640" alt="检测"></p>

**3. 选择要关的**：

| 项目 | 默认 |
|---|---|
| 各 App 里的广告开关（有机型脚本时） | 勾选，可以按 App 取消 |
| 营销通知 | 明确的营销类勾选；服务类、实时活动、护眼、赛事、告警以及「其他 / 普通通知」等含糊类别默认保留 |
| 快应用 | 不勾，你决定 |
| 系统广告组件 | 不勾，你决定 |

<p align="center"><img src="../images/gui-4-choose.png" width="640" alt="选择营销通知"></p>
<p align="center"><img src="../images/gui-5-choose-more.png" width="640" alt="选择快应用和广告组件"></p>

执行前如需排查手机连接，可点「检查读屏连接」。它只检查服务和页面可读性，不点开关；成功不等于已验证所有 App 路径。

**4. 执行**：进度条加实时日志。执行期间不要碰手机。

<p align="center"><img src="../images/gui-6-run.png" width="640" alt="执行"></p>

**5. 完成**：列出每一步的结果。最后一张卡片是「关闭开发者模式」：点「帮我关闭」，客户端从电脑上关掉；或者自己在手机上关。关掉不会撤销这次的改动。

<p align="center"><img src="../images/gui-7-done.png" width="640" alt="完成"></p>

## 反馈

左下角「💬 反馈问题」，或者完成页里的「反馈这个问题」（有步骤失败时出现）。

1. 选类型：遇到问题 / 功能建议 / 适配新机型。
2. 写一句发生了什么。
3. 默认附带诊断信息：客户端版本、电脑系统、手机型号和系统版本（含 HyperOS 版本）、执行结果、最近 60 行日志，以及最近失败的完整原因。错误中的当前用户目录和手机序列号已替换，不含通知正文。展开「查看 / 修改诊断信息」可以删改。
4. 点「提交到 GitHub」，浏览器打开新建 Issue 页面，内容已经填好。登录 GitHub 后点「Submit new issue」。

日志太长时，诊断信息会复制到剪贴板，在打开的页面里粘贴即可。

<p align="center"><img src="../images/gui-8-feedback.png" width="640" alt="反馈"></p>

## 还原

左下角「还原改动」：恢复快应用、恢复挂起的广告组件、重新打开关掉的营销通知。

<p align="center"><img src="../images/gui-9-restore.png" width="640" alt="还原"></p>
还原要连着手机，开发者模式关掉了的话，按 [00-打开开发者模式](00-打开开发者模式.md) 重新打开。

## 数据放在哪

Mac 的数据目录：

| 内容 | 位置 |
|---|---|
| 改动前的快照、营销通知清单、挂起记录 | `~/Library/Application Support/AndroidAdCleaner/backups/` |
| 最近失败的完整诊断（0.2.2 起，含异常开头） | `~/Library/Application Support/AndroidAdCleaner/logs/last-error.txt` |
| 客户端下载的 adb | `~/Library/Application Support/AndroidAdCleaner/platform-tools/` |

Windows 对应目录是 `%APPDATA%\AndroidAdCleaner\`；完整错误在 `logs\last-error.txt`，其中 `backups\` 放快照和记录，`platform-tools\` 放下载的 adb。左下角「打开备份文件夹」可以直接打开。

## 从源码运行和打包

开发或自行构建时，先获取当前源码：

```bash
git clone https://github.com/rddmwmddr/android-ad-cleaner.git
cd android-ad-cleaner
```

已有仓库且工作区干净时，切到 `main` 后执行 `git pull --ff-only`。有自己的改动时先保存，避免覆盖。已有安装包不会自动改用这份源码；需要运行下面的源码入口。

**Mac Apple 芯片**（需先安装 `uv`）：

```bash
uv venv --python cpython-3.12-macos-aarch64 gui/.venv
uv pip install --python gui/.venv/bin/python pywebview pyinstaller uiautomator2 pillow
gui/.venv/bin/python gui/app.py          # 运行
```

**其他平台**可使用已安装的 Python 3.12 创建虚拟环境，安装 `pywebview uiautomator2 pillow` 后运行 `gui/app.py`；Windows 还需要 WebView2。当前 Windows 源码已通过云端打包和原生 GUI 验证，页面启动改为本地文件直读；连接手机、报告者电脑及 Intel Mac 的新版回归仍待完成，见下方已知问题。只需命令行时，按根目录 [README](../README.md#一次完整的流程) 安装 `requirements.txt` 并运行 `tool/run.py` 即可。

本地 Mac 打包：

```bash
gui/build_mac.sh                        # 打包到 gui/dist/
```

带签名和公证的打包（先在钥匙串里准备好 Developer ID Application 证书，并用 `xcrun notarytool store-credentials` 存好公证凭据）：

```bash
SIGN_ID="Developer ID Application: 名字 (TEAMID)" NOTARY_PROFILE=公证配置名 gui/build_mac.sh
```

发布包只包含明确列出的程序、机型脚本和图片资源；不会把本地运行日志、备份或测试机型打进包。Intel 主程序按 [PyObjC 签名文档](https://pyobjc.readthedocs.io/en/latest/notes/codesigning.html)添加回调所需的可执行内存权限；本轮仅启用 `allow-jit` 仍会卡在 libffi，改用专门的 Intel entitlement 后通过 GUI 测试。该权限仅赋给主程序，保留 hardened runtime 与库签名校验。完整发布检查见更新记录。

## Windows 驱动

Mac 不需要驱动。Windows 认不到手机时，按品牌装驱动：

| 品牌 | 驱动 |
|---|---|
| 小米 / Redmi | 小米手机助手或 [Google USB Driver](https://developer.android.com/studio/run/win-usb) |
| OPPO / 一加 / realme | OPPO 手机助手，或 Google USB Driver |
| vivo / iQOO | vivo 手机助手 |
| 荣耀 / 华为 | 华为手机助手 / 荣耀手机助手（装完关掉它，避免占用连接） |
| 其他 | Google USB Driver |

装完重新插线，手机上点「允许 USB 调试」。

## 已知问题

| 现象 | 说明 |
|---|---|
| 窗口在后台时，第一下点击只把窗口切到前台 | macOS 网页窗口的默认行为，再点一次 |
| Windows 弹「Windows 已保护你的电脑」 | 安装程序没有代码签名，点「更多信息」→「仍要运行」 |
| 折叠屏展开时不能跑机型脚本 | 合上用外屏；营销通知、快应用、广告组件不受影响 |
| 0.2.0 点执行后又开一个窗口，或子任务没有开始 | 0.2.1 修复了打包子进程的 `--cli` 入口，请更新安装包 |
| 0.2.0 的 vivo / iQOO 清单链接打不开 | 先打开 [vivo 清单](清单/vivo-OriginOS.md)；0.2.1 已修复品牌跳转及中文路径编码 |
| Windows 打开后显示「127.0.0.1 响应时间太长」 | [Issue #18](https://github.com/rddmwmddr/android-ad-cleaner/issues/18)：0.2.1 改为直接读取本地文件，避开 HTTP 服务；请更新安装包，报告者电脑待复测。暂不能更新时可用下面的旧版命令行入口 |

### Windows 0.2.0 界面打不开时使用内置命令行

解压免安装版，在含有 `aac-cli.exe` 的目录打开 PowerShell，不需要另装 Python：

```powershell
.\aac-cli.exe --cli run.py --help
.\aac-cli.exe --cli run.py devices
.\aac-cli.exe --cli run.py -s <序列号> check
```

这里仍然运行 **0.2.0 引擎**，不会获得最新源码修复。不要照搬含已知问题的渠道批量操作；可先只读检查，再按[清单](清单/)手动处理。需要新版引擎时下载 0.2.3，或按上文从源码运行。

### 验证本地界面

源码可运行 `python gui/app.py --smoke-gui`；打包后运行 `python gui/smoke_test.py <可执行文件> --gui`。此检查验证页面、教程图片、JS API 通信以及没有创建本地 HTTP 服务，不连接手机。Windows 工作流会对打包程序执行这项检查，[2026-10-25 云端验证已通过](https://github.com/rddmwmddr/android-ad-cleaner/actions/runs/40198943037)；通过不等于已覆盖所有 Windows 安全软件和电脑环境。

### 通知扫描出现 QueryController / UiDevice / UiAutomation 堆栈

0.2.1 会在扫描通知前启动手机读屏服务，初始化失败就阻断扫描；界面只显示异常末尾，无法判断具体原因。请更新 0.2.3：扫描和状态复查直接读取 adb，关闭开关仍需要正常读屏。

连接、检测后点「检查读屏连接」。失败时展开「查看完整诊断」或点「复制完整诊断」；即使还没开始执行，左下角「反馈问题」也会附上这次的完整错误。请保留异常开头的 `Exception` / `Caused by`，不要只截最后几行。

命令行的只读检查（Windows 免安装版目录中）：

```powershell
.\aac-cli.exe --cli run.py -s <序列号> ui-check
```

### 提示 AccessibilityServiceAlreadyRegisteredError / already registered

0.2.2 的完整日志已确认：Windows 11、小米 18 Pro Max、OS4.0.27.0.XEOCNXM / Android 17 在实际关闭开关时，手机端 UiAutomation 服务已经注册，新会话被拒绝。App 广告和营销通知点击都需要它，所以可能一起失败；通知扫描本身仍可运行。这不是 `SLF4J` 提示或 PyInstaller 尾部文字造成的错误，也不能据此确定具体占用者。

2026-10-26 补充反馈：同一用户称 0.2.3 仍失败，同时关闭 GKD 和自动记账后可以开始处理。这是排查线索，尚不能确定具体工具或模式；不再使用“无需关闭无障碍服务”的绝对提示。

处理顺序：

1. 退出旧版去广告客户端、Appium、UI 检查器和其他正在操作同一手机的自动化任务，只保留一个客户端。
2. 检查 GKD、自动记账等工具的自动化、读屏或 Shizuku 功能。只暂停你确认可暂停的功能；必要时由本人暂时关闭对应 App 的无障碍服务，保留所依赖的屏幕阅读器与辅助服务。
3. 保持手机解锁，逐项暂停后点「检查读屏连接」。仍提示已注册时，可由机主手动重启，先不启动上述自动化工具再检查。
4. 检查通过后重试未完成项目；仍失败则复制完整诊断。结束后按需恢复暂停的工具，无需清除数据或反复安装客户端。

最新源码会在失败时限时只读检查总开关和服务数量，并在错误摘要及完成页显示排查提示；不会自动停用无障碍。0.2.3 安装包尚不包含这些新提示，但可手动执行上述排查。找机位功能通知的误关恢复及保护范围见[专项说明](11-读屏冲突与功能通知保护.md)。

0.2.3 在本机用设备锁避免多个去广告进程同时读屏；启动失败、操作异常和正常结束都会关闭本次启动的连接，等其退出后再释放锁。已注册错误只重试一次；持续失败就明确退出，不无限等待，不强停其他工具。后续需要读屏的任务会标为「跳过」，首个错误仍可复制，收尾只表示恢复常亮等收尾操作，不代表所有项目成功。若还要排查或重试，先保留 USB 调试，结束后再关闭。

技术依据：[Android 的 UiAutomation 注册逻辑](https://android.googlesource.com/platform/frameworks/base/+/master/services/accessibility/java/com/android/server/accessibility/UiAutomationManager.java)限制同时注册一个服务；[uiautomator2 3.7.1 生命周期代码](https://github.com/openatx/uiautomator2/blob/3.7.1/uiautomator2/core.py)默认在初始化成功后才注册退出清理，并使用不等待退出的方式。项目补上这些清理和衔接处理，不能据此认定反馈手机上的占用一定由旧客户端产生。

### 一加 Ace 2 Pro / ColorOS 14 的源码实测

最新源码已补该机型的有限脚本和独立通知设置页兼容，详情见[实测记录](10-一加旧系统实测.md)。这些更新尚未进入 0.2.3 安装包；从源码运行时按根目录 `requirements.txt` 安装依赖。本机联网后，3 个个性化推荐和 6 个商店推广位已关闭并回读，23 个营销通知已关闭。其他应用仍有入口差异，不能把有限范围写成整机全部去广告完成。