android-ad-cleaner
AGENTS.md7.1k starsChanged 19 days agoMITView on GitHub
读者：能在用户电脑上执行命令的 AI 智能体（WorkBuddy、Claude Code、Codex、Trae、Cursor 等）。 任务：通过 adb 关掉用户安卓手机里的广告、热搜、资讯推荐和营销推送。 沟通语言：跟用户的语言一致。 违反任何一条都要停下来，向用户说明。 adb 查找顺序：环境变量 ADB → PATH → ~/Library/Android/sdk/platform-tools/adb。找不到时，照 docs/01-准备工作.md 帮用户装。 想给这台机型攒一份脚本时，先查词库：找词库先看 tool/vocab.py，生成物是 docs/清单/词库.md，按家族和分组列词条与同页保留项，只是线索，要真机核对。之后用 adapt 五段流水线。五段都由人把关，工具不自动决定关哪些开关： 写完脚本用 python3 tool/vocab.py gaps <目录名> 查漏：列出同家族别的机型关过、这份脚本没写的词条。 自检通过也不等于适配完成：转正式机型脚本前，必须人工在手机上核对每一步，并补上 BUILD 录制版本。
Adopted by
Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data
Who's talking about rddmwmddr/android-ad-cleaner
- @metasprojects.bsky.social“Python script cleans vendor adware off Android devices without root, fully reversible, with AI agent …”Bluesky · Oct 27, 2026 · 3 likes
- BLACKIELF/qingjing-aigoodbro“清静 AiGoodBro：Mac 与 Android 品牌适配及可下载构建”GitHub · Nov 8, 2026
- mrxcode-debug/pdt-github-hot-radar“[GitHub Radar] 2026-11-01: 3 repo đáng xem”GitHub · Nov 1, 2026
- ultrametricai/ultrametric“vendor-radar: daily scan 2026-10-28”GitHub · Oct 28, 2026
The biggest 4 of 4 mentions linking to the repository that our crawl found. Each line is their own headline.
In this repositoryOne other file it gives its agents.
- CLAUDE.mdCLAUDE.md
The file
Files
AGENTS.md —— 给 AI 智能体的操作规范
读者：能在用户电脑上执行命令的 AI 智能体（WorkBuddy、Claude Code、Codex、Trae、Cursor 等）。 任务：通过 adb 关掉用户安卓手机里的广告、热搜、资讯推荐和营销推送。 沟通语言：跟用户的语言一致。
1. 硬规则
违反任何一条都要停下来，向用户说明。
- 每条 adb 命令都带
-s <序列号>。 电脑上可能连着多台设备（电视、模拟器）。<!-- rule:product.adb.device-serial --> - 正常功能不能坏。 下拉搜索、负一屏卡片、应用商店的安装和更新、浏览器、天气预警、快递和更新提醒要保留。
<!-- rule:product.feature.preserve --> - 优先用 App 内的开关。 动包只用
pm suspend，并且要用户同意。不用pm uninstall，不用pm disable-user。<!-- rule:product.package.suspend-only --> - 不碰系统更新。 不 root，不解 BL，不刷模块，不改 system 分区。
<!-- rule:product.system.no-root --> - 改之前说清楚，改完能还原。 每一段动手之前，告诉用户这一段要关哪些开关。
<!-- rule:product.change.explain-and-restore --> - 不替用户同意协议。 遇到用户协议、隐私政策、权限申请，点「取消」「以后再说」「不允许」「禁止」。不点「同意」「允许」。
<!-- rule:product.consent.never-agree --> - 不绕过锁屏。
run.py check显示锁屏时，请用户解锁。<!-- rule:product.lockscreen.wait-for-owner --> - 不截账号页。 「我的」页、账号页、手机号页不截图；截到了要删除。
<!-- rule:product.account.no-screenshot --> - 收尾还原插电常亮，提醒关闭开发者模式。 结束时跑
run.py finish，然后提醒用户关闭开发者模式（§3 第 11 步）。<!-- rule:product.finish.restore-and-remind --> - 保护类开关要打开，不要关。 「限制广告跟踪」「防止广告追踪」「阻止广告跟踪」「关闭个性化推荐」「减少广告」这类以「限制 / 防止 / 阻止 / 禁止 / 关闭 / 减少」开头的开关，打开才是保护。上面的词只是举例，判据是
tool/polarity.py的NEG_PREFIX（配合广告词一起认）。引擎的off()会把它们拨到「开」；手动操作时同样处理。<!-- rule:product.switch.polarity --> - 不挂这些包：
com.heytap.quicksearchbox（下拉搜索）、com.coloros.assistantscreen（负一屏）、各品牌应用商店。挂了功能会坏，run.py会拒绝。<!-- rule:product.package.never-suspend -->
2. 环境准备
pip3 install -r requirements.txt # uiautomator2adb 查找顺序：环境变量 ADB → PATH → ~/Library/Android/sdk/platform-tools/adb。找不到时，照 docs/01-准备工作.md 帮用户装。
3. 标准流程
python3 tool/run.py devices- 列表为空：请用户检查数据线、USB 调试，见
docs/01-准备工作.md。 - 状态
unauthorized：请用户在手机弹窗上勾「始终允许」并点「允许」。 - 有多台设备：问用户处理哪一台。
拿到序列号 S 之后：
| 步 | 命令 | 说明 |
| 1 | run.py -s S check | 只读。看锁屏、机型脚本匹配、广告包状态 |
| 2 | run.py -s S backup | 改动前快照，存到 backups/ |
| 3 | run.py -s S recipe | 有机型脚本时跑机型脚本。可以只跑某几段：recipe 浏览器 主题。只有同品牌参考脚本时，问过用户再加 --ref |
| 4 | run.py -s S chan-scan | 只读。列出开着的营销通知渠道 |
| 5 | 编辑 channels.tsv | 删掉服务类渠道（见 §5），给用户看清单。第四列是手机上显示的应用名（读不到时为空），给用户看时用它，不要只给包名 |
| 6 | run.py -s S chan-off <清单> | 关掉清单里的渠道；结尾会复查，「仍开着: 0 个」为成功 |
| 7 | run.py -s S quickapp | 只读。检测快应用组件：装没装、挂没挂、在不在跑、用户用没用过 |
| 8 | 问用户 | 列出 check 里的广告包和快应用，问要不要关 |
| 9 | run.py -s S suspend <包…>、run.py -s S quickapp off | 用户同意后执行。quickapp off 自动保留快应用平台（负一屏快递卡片依赖它） |
| 10 | run.py -s S finish | 收尾。开发者模式开着时会打印提醒 |
| 11 | 提醒用户关闭开发者模式 | 把 finish 打印的提醒转述给用户；用户要你代关，执行 run.py -s S dev-off --yes（执行后连接断开，放在最后；执行完请用户在手机上核对开发者选项总开关是关的） |
没有机型脚本的机型：
- 跑通用部分（第 4 到 9 步）。
- 打开
docs/清单/里同品牌的清单，用fast.py的单步命令照着做（§4）。 - 做完问用户要不要把路径存成机型脚本，写法见
docs/04-给新机型写脚本.md。
新机型适配辅助（adapt）
想给这台机型攒一份脚本时，先查词库：找词库先看 tool/vocab.py，生成物是 docs/清单/词库.md，按家族和分组列词条与同页保留项，只是线索，要真机核对。之后用 adapt 五段流水线。五段都由人把关，工具不自动决定关哪些开关：
| 步 | 命令 | 说明 |
| 1 | run.py -s S adapt survey | 只读试入口：同家族的直达页面逐条打开，报打不开 / 落在别处 / 落在这一页但没看到判据文字、命中的同组词条、同族用过的 App 装了哪些。不点任何开关 |
| 2 | run.py -s S adapt explore [包名 …] | 只读探路，输出 探路-<型号>.tsv（末列「人工勾选」留给人工） |
| 3 | 编辑 TSV | 在末列写「关」挑出要关的开关；拿不准的问用户 |
| 4 | run.py adapt gen 探路-<型号>.tsv | 生成 recipe 草稿（不碰手机）。草稿是待验证的，不是适配成果 |
| 5 | run.py -s S adapt check 草稿.py | 安全模式自检，输出适配报告：关成几个/没找到几个/待人工确认几个 |
写完脚本用 python3 tool/vocab.py gaps <目录名> 查漏：列出同家族别的机型关过、这份脚本没写的词条。
自检通过也不等于适配完成：转正式机型脚本前，必须人工在手机上核对每一步，并补上 BUILD 录制版本。
4. 单步命令（fast.py）
| 命令 | 作用 |
python3 tool/fast.py -s S ls | 列出当前屏幕的文字、开关状态、坐标 |
python3 tool/fast.py -s S tap 隐私 广告 | 依次找到并点击这些文字，找不到会上下翻页 |
python3 tool/fast.py -s S scan | 翻完整页，列出所有开关和状态 |
python3 tool/fast.py -s S only 个性化推荐,开屏广告 | 当前页只关标题含这些词的开关 |
python3 tool/fast.py -s S off 帮助,安全 | 当前页关掉所有开关，标题含这些词的保留 |
- 打开系统设置首页：
adb -s S shell am start -f 0x10008000 -a android.settings.SETTINGS（-f 0x10008000防止回到上次停留的子页）。 - 一次读屏约 0.1 秒。不需要截图就能读到文字。
- 截图看画面：
adb -s S exec-out screencap -p > shot.png。多屏手机（折叠屏、带背屏）加-d <display id>。
5. 营销通知渠道怎么挑
chan-scan 按渠道名里的关键词挑候选，会混进服务类渠道。厂商固定的营销分类号（如 vivo VPushChannel_0/4/6）按 ID 直接列入清单，不受名字里的跳过词影响；渠道 ID 带广告网络名（TencentAdNetCH1、ADroiUnion 一类）的渠道本身就按营销处理，同样直接列入。删掉下面这些再关：
| 删掉（服务类） | 例子 |
| 网络 | 热点和网络共享状态、智能热点 |
| 系统功能 | 红包助手、权限建议、驾驶状态识别、盗窃防护 |
| 拍摄辅助功能 | 找机位、机位推荐、推荐机位：即使带“推荐 / 活动”也保留，旧清单执行同样保护 |
| 订阅内容 | 直播提醒（用户关注的人开播） |
| 告警与服务 | 警告、告警、实时活动、赛事资讯、护眼推荐；「其他 / 普通通知 / 推送通知」等含糊类别也不要默认批量关闭 |
| 保留在清单里（营销类） | 例子 |
| 厂商推送分类 | push_oplus_category_content（内容与营销）、vivo VPushChannel_0/4/6、广告网络 ID（TencentAdNetCH1、ADroiUnion 一类） |
| 活动 | 活动优惠、福利通知、专享优惠、权益福利、流量套餐优惠 |
| 资讯 | 热门资讯、突发新闻、热点推荐、精彩推荐、推荐内容 |
不确定时问用户。
6. 已知的坑
| 现象 | 原因 | 对策 |
| 机型脚本大量「没找到」 | 系统版本和机型脚本录制版本不同 | 看 check 的版本提示；按清单单步做，做完更新机型脚本 |
| 折叠屏展开时什么都找不到 | 展开后是左右分栏，底部有任务栏 | 请用户合上手机，用外屏 |
| 点击没反应 | 部分 App 吞掉 input tap | 引擎用 80 毫秒短按，已处理 |
| 开关点完又开回来 | ColorOS 开关旁有「关闭」状态字，被当成确认按钮 | 引擎优先点 Button 类按钮；一个都没命中时只认可点击、按钮级尺寸的 TextView，已处理 |
| 打开 App 先弹全屏广告，读不到字 | 纯图片弹窗 | 引擎只点可识别的关闭图标；空白最多等 8 秒，仍不可读就停止，不盲按返回 |
| 渠道页打开的是上一个渠道 | 系统复用旧页面 | am start 加 -f 0x10008000，已处理 |
| 截图后下一次点击失灵 | 手机上的截图工具弹到前台 | 自动化期间少截图，用 fast.py ls 读屏 |
| 无线调试断开 | 息屏太久 | 请用户关开一次无线调试，报新端口 |
| ColorOS 14 一加通知渠道全被跳过 | 通知页位于独立的 com.oplus.notificationmanager 包 | 当前源码只接受已实测的 Channel / AppNotificationSettingsActivity，仍须核对渠道标题；AppNotification 总页不拨开关 |
| ColorOS 11/12（Android 10–12）通知渠道全被跳过 | 通知页宿主是 com.coloros.notificationmanager，ColorOS 14 起才改叫 com.oplus.notificationmanager，两个包都要认 | 当前源码两代都在白名单里，活动名要求与 oplus 同构；遇到第三种写法照旧跳过，把整句「未确认…停在 …」的日志报上来（Issue #415） |
| 应用通知页打不开，日志只说「应用通知页没有打开」 | 这句话以前混了三种情况：页面真没开、宿主不在白名单、前台被别的应用占着（GKD、MaaFramework 这类自动化工具最常见） | 当前源码在跳过时点名前台包名，按文案分别处置：写「不是通知设置页」时先在手机上退出那个应用再重跑；写「是这个应用自己」时系统没跳到通知设置页而是把应用打开了，手动进「设置 → 通知管理 → 选该应用」后重跑；写「是系统设置但不是通知页」或「是通知设置页但这个 Activity 没认出来」时把日志报上来——后者多半是没适配过的新系统（Issue #422） |
| vivo 渠道直达参数无效 | systemuiplugin 页可能只有应用级总开关 | 当前源码直接跳过，不冒关闭整应用通知的风险（PR #20） |
vivo 旧系统（Funtouch 13）chan-off 全部跳过 | 渠道页顶栏没有固定 resource-id；渠道行在应用通知页「类别」分组下面，首屏读不到 | 当前源码在拿不到 toolbar id 时按几何认顶栏（顶部、几乎整屏宽的那段文字），并在「类别」以下翻页找行；认不出照旧跳过，不点页面上的第一个开关（Issue #336） |
| 小米 msa 挂起后仍被拉起 | 系统 App 启动时 bind 广告服务 | 当前源码的 run.py suspend 挂起时一起尝试断网；安装包状态见 归档记录 |
| 没有本型号的机型脚本 | — | check 会列出同品牌参考脚本，recipe --ref 用安全模式试跑：只关点名的开关，不做整页全关 |
| 机型脚本版本对不上 | 系统小版本不同 | 自动进安全模式，同上 |
| 折叠屏合上后点击落空 | dump 里留着内屏那份节点，坐标在外屏之外 | 当前源码丢掉屏幕外的节点（Issue #2）；安装包状态见 归档记录 |
| 小米热榜横屏后漏掉右侧开关 | 引擎缓存连接时的竖屏尺寸 | 0.2.1 每次读屏刷新尺寸；读屏后旋转则拒绝旧坐标（Issue #21） |
| 旧小米系统 msa 挂起成功但广告还在 | 系统缺少断网接口，仅挂起仍可能被拉起 | 0.2.1 检查接口并回读网络规则；不支持时报告部分完成，不能写成广告已全部关闭 |
| vivo 快应用挂不起 | 系统拒绝挂起 com.vivo.hybrid | 当前源码检测系统快应用服务开关，保存原值后关闭并回读验证；无原值备份不默认开启 |
| 荣耀等机型截图取样越界 | 截图分辨率与 UI 坐标不符，或节点只有一部分在屏内 | 检查截图实际尺寸；未知状态跳过，不猜开关方向（Issue #16） |
| 小米设置搜索框卡住、一直打「%」 | 搜索页没打开就开始输入，或输入调用超时；不同版本表现不同 | 小米脚本走菜单；通用搜索确认输入框后限时输入并核对，结果匹配排除输入框，不留后台输入线程 |
| 扫描显示 QueryController / UiDevice 初始化堆栈 | 旧扫描依赖读屏；already registered 代表 UiAutomation 被占用；用户反馈暂停 GKD 和自动记账后可继续，尚未确定单一占用者 | 扫描 / 复查保持 adb 只读；保留清理本次会话、同机互斥和有限重试。失败时只读检查无障碍状态，提示本人逐项暂停可暂停的自动化 / Shizuku 功能后检查；保留依赖的辅助服务，结束后按需恢复。不能自动停用服务、误杀其他工具或自动重启手机。见 排查与保护说明 |
| 打开 App 后仍停在上一页 | 部分系统 App 没有 LAUNCHER，或直达 Activity 复用了旧任务 | start() 检查启动结果和前台包；少量文字不能当空白广告；空白限时等待，读取 / 处理弹窗前后核对前台。手机管家、全局搜索用已验证的 Activity |
| 一加旧版商店短暂打开后退出 | 直达启动及复用旧任务与本机商店行为不匹配；也可能被系统权限页挡住 | 商店沿用先停止再从桌面启动；浏览器使用实测 Activity 并清理旧任务。权限页只拒绝，前台仍不对就停止，不能把每次失败都判断成崩溃 |
| ColorOS 14 挂起后后台进程再次出现 | 实测运行应用后广告服务、乐划、快应用平台被重新拉起，具体机制未定位 | 分别回读挂起和进程状态；只能报告实际结果，不能把挂起写成永久停止。不升级为卸载、disable-user 或 root |
ColorOS / realme 挂起 com.oplus.appdetail 后，所有第三方安装永久卡在「正在安装」，卸载也一样 | 它承载安装与卸载的收尾页（appdetail.intent.action.INSTALL_FINISH → InstallFinishActivity，另有 UNINSTALL_COMPONENT、InstallGuideActivity），挂起后安装完成广播没有接收者 | 不挂。run.py suspend 已把它列进 NEVER 直接拒绝；已经被别的工具挂起的，用 run.py -s S unsuspend com.oplus.appdetail 还原（RMX3700 / ColorOS 16 实测，解冻后立刻恢复） |
backup 快照里 sys.txt / user.txt / disabled.txt 是 0 字节 | 部分 ROM（HyperOS 4）上 pm list packages 任何参数都无输出且 exit 0 | pkg_list() 读不到包名时回退 cmd package list packages；backup 先用不带参数的完整清单探活，都读不到就报失败、不留半成品快照（Issue #192） |
| 关掉手机助手 / 投屏类工具后整轮中断，后面几段都报「本机没有安装 xxx」 | 复用了对方在 5037 上起的 adb server，对方退出后连接消失；断开时 pm path 也没输出，被当成没装 | 首次确认断连时报「adb 连接断开」，本轮剩余段快速跳过；按提示退出手机助手类软件、拔插数据线后重跑（Issue #293） |
| 游戏中心报「未找到入口「设置」」，日志里没有更多线索 | 游戏中心 14.43.3 把「设置」做成「我的」页右上角没有文字的齿轮图标，只有切到「我的」tab 才显示 | 文字优先、失败后用 tap_icon() 在右上角找没有文字的可点图标，点完要求精确出现「隐私开关设置」/「隐私」才算成功，等 2.4 秒页面仍不对就退回换下一个，全失败打印当前页文字；「我的」用会校验的 p.tap()，不用 d(text=).click()（Issue #292） |
华为应用通知页上渠道名和分组名同名，inline_switch 报「同名 2 行」后整段跳过 | 分组名也写在列表里、位置在 0.22H 以下，和渠道行一样被当成候选 | 逐个候选判定「行里恰有一个开关、行高不超过 20%、行内没有应用总开关」，只留合格行；恰有一行合格才用，两行都合格放弃并带控件链（Issue #287） |
| 进入子页后读到空树 | 页面切换动画尚未完成 | 等待非空页面稳定后再找入口 |
| 负一屏/天气设置面板被退出 | 单屏面板不能翻页，或面板的「取消」被当作弹窗按钮 | 只滑动可滚动容器；滑动离开当前 Activity 就停止本段；带开关/列表的页面不按短弹窗处理 |
| OPPO / 一加 / realme 关了快应用后，负一屏快递卡片能显示、点「全部」打不开详情页 | com.nearme.instant.platform 承载快递详情页，挂起它就弹「快应用服务框架目前无法使用。该应用是由Shell所管理。」 | quickapp off 已保留该组件，只挂 local.service 和 card；手动 suspend 平台才会复现，用 unsuspend 恢复（Issue #335） |
代码回归见仓库根的 CLAUDE.md「开发」一节——这里只放操作手机的步骤。前端行为用例在 tests/js/（node --test + jsdom），由同一条回归命令带跑，需要有 node；单跑先 npm ci，再 npm test。
社区问题最新处理范围见 docs/09-社区问题处理.md。新渠道关闭流程必须确认渠道标题和明确的通知开关，回读渠道状态；不允许回退为关闭 App 全部通知。挂起成功不保证已经运行的进程退出或图标消失，快应用挂起成功后再 force-stop。
7. 收尾汇报
用户的语言，大白话，分六块：
- 关掉了什么（按 App 列）。
- 没关掉的和原因（找不到入口、开关点不动、要同意协议才能进）。
- 挂起了哪些包、关了哪些快应用，怎么还原（
run.py -s S unsuspend、quickapp on）。 - 插电常亮是否已还原。
- 有没关掉的项或报错：问用户要不要反馈。同意后整理型号、系统版本、出错的段和日志（序列号替换成
<序列号>），用gh issue create --repo rddmwmddr/android-ad-cleaner提交，或者给用户一个https://github.com/rddmwmddr/android-ad-cleaner/issues/new?template=bug_report.md&title=…&body=…链接。 - 提醒关闭开发者模式：手机上「设置 → 搜索开发者选项 → 关掉总开关」，或由你执行
dev-off --yes。说明关掉开发者模式不会撤销这次的改动。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.