Android 광고 클리너 — 이 프로젝트가 하는 일

중국 안드로이드 폰(OPPO, Xiaomi, Honor, vivo, OnePlus 등)에 내장된 광고, 인기 검색어, 뉴스 피드, 마케팅 알림을 끄는 도구입니다.

핵심 접근 방식

• 루트 불필요, 부트로더 잠금 해제 불필요, 플래싱 불필요 — 시스템 업데이트는 정상적으로 작동합니다.
• 시스템과 앱이 자체 설정에서 이미 노출하는 스위치만 전환합니다.
• 광고 패키지 일시 중지(예: com.opos.ads 또는 com.miui.systemAdSolution)는 명시적 확인이 필요하며 한 명령으로 되돌릴 수 있습니다.
• 유용한 기능 유지: 검색, 홈 화면 카드, 앱 스토어 설치/업데이트, 날씨 알림, 배송 알림.

대상

카테고리	예시	처리 방법
시스템 광고	개인화 광고, 광고 추적(OAID), 스마트 추천 서비스	시스템 설정의 스위치
인기 검색어 및 뉴스	검색 페이지 인기 목록, 네거티브 스크린 뉴스, 브라우저 피드	각 앱 설정의 스위치; 브라우저는 간단한 홈페이지로 전환
프로모션 슬롯	스토어 캐러셀, 스플래시 화면, 플로팅 활동, 출석 체크 보상	스토어의 "서비스 관리" 스위치
마케팅 알림	"콘텐츠 및 마케팅", "프로모션" 알림	채널별로 끔 — 같은 앱의 주문, 배송, 업데이트 알림은 켜짐 유지
광고 구성 요소	com.opos.ads, com.miui.systemAdSolution	pm suspend로 일시 중지(동의 필요)
퀵 앱	광고를 탭할 때 실행되는 미니 앱	quickapp off로 감지 및 비활성화

거부하는 작업

• 시스템 앱을 제거하거나 비활성화하지 않습니다(pm uninstall, pm disable-user 사용 안 함).
• 시스템 파티션을 수정하거나 모듈을 설치하지 않습니다.
• 사용자를 대신하여 앱의 사용자 동의를 수락하지 않습니다 — 동의 페이지가 나타나면 취소하거나 연기합니다.
• 계정 페이지나 전화번호 페이지의 스크린샷을 캡처하지 않습니다.

네 가지 사용 방법

1. AI 에이전트가 실행 — 컴퓨터, USB 케이블, 명령을 실행할 수 있는 AI 도구 필요.
2. 채팅 AI가 안내 — 휴대폰만; DeepSeek, Doubao, ChatGPT에서 작동.
3. 수동 체크리스트 — 휴대폰만; 브랜드별 단계별 목록을 따름.
4. 데스크톱 클라이언트 — Mac(Apple 또는 Intel 칩) 또는 Windows 10/11; 휴대폰을 연결하고 버튼을 클릭. Python이나 AI 도구 불필요.

데스크톱 클라이언트(v0.2.3)

• Mac(Apple Silicon 및 Intel 모두)용 서명·공증된 DMG, Windows용 설치 프로그램 또는 휴대용 ZIP으로 제공.
• 워크플로: 휴대폰 연결 → 감지(모델, OS 버전, 스크립트, 퀵 앱, 광고 구성 요소) → 끌 항목 선택(채널별 마케팅 알림; 서비스 알림은 기본적으로 선택 해제) → 진행률 표시줄과 실시간 로그로 실행 → 결과 확인 및 개발자 모드 비활성화 알림.
• 피드백 버튼은 진단 정보(클라이언트 버전, 휴대폰 모델, OS 버전, 최근 로그 — 일련 번호 대체, 앱 목록이나 알림 내용 없음)를 자동 첨부하고 GitHub 이슈를 엽니다.
• 알려진 제한: adb로 연결된 Android 기기만 지원; HarmonyOS NEXT(HDC)는 지원하지 않습니다.

테스트된 기기

프로젝트는 기기 스크립트를 유지합니다 — 특정 휴대폰 모델에 대한 자동화된 단계별 지침으로, 열 앱, 탭할 메뉴 항목, 전환할 스위치, 그대로 둘 스위치를 기록합니다. 설정 페이지가 모델과 OS 버전에 따라 다르기 때문에 필요합니다.

지금까지 테스트됨: Honor PNM-AN10(MagicOS 10), OnePlus Ace 2 Pro(ColorOS 14), OPPO Find N6 / Find X10 Pro Max / Find X9 Ultra / Find N3(ColorOS 16/17), Xiaomi 18 Pro Max(HyperOS 4.0), vivo X300 Ultra(OriginOS 6). 일부는 완전히 검증되었고 일부는 부분적으로 검증됨 — README에 각 상태가 표시됩니다.

휴대폰이 목록에 없으면 가이드에 따라 스크립트를 작성하고 풀 리퀘스트를 제출할 수 있습니다.

명령줄 흐름

터미널에 익숙한 사용자를 위한 전체 파이프라인은 다음과 같습니다:

pip3 install -r requirements.txt
python3 tool/run.py devices                 # 연결된 휴대폰 나열, 스크립트 확인
python3 tool/run.py -s <serial> check        # 읽기 전용 확인
python3 tool/run.py -s <serial> backup       # 변경 전 스냅샷
python3 tool/run.py -s <serial> recipe       # 기기 스크립트 실행
python3 tool/run.py -s <serial> chan-scan    # 마케팅 알림 채널 나열
python3 tool/run.py -s <serial> chan-off backups/<model>-<time>/channels.tsv
python3 tool/run.py -s <serial> quickapp     # 퀵 앱 감지; `quickapp off`로 비활성화
python3 tool/run.py -s <serial> finish       # 마무리, 개발자 모드 비활성화 알림
python3 tool/run.py -s <serial> dev-off --yes  # PC에서 개발자 모드 비활성화(마지막 단계)

안전 및 복구

• 변경 전에 백업 스냅샷이 생성됩니다.
• 일시 중지된 패키지와 알림 채널은 각각 한 명령으로 복원할 수 있습니다.
• 앱 내 스위치는 체크리스트 경로를 따라 수동으로 복원합니다.
• 도구는 찾을 수 없는 단계를 건너뛰며 맹목적으로 클릭하지 않습니다.
• 화면 읽기 서비스가 충돌하는 경우(예: GKD 또는 자동 회계 앱), 도구는 이를 감지하고 한 번 재시도하며, 여전히 차단되면 복구 단계를 제공하고 건너뜁니다.

라이선스

MIT. 프로젝트는 Android 및 벤더 앱이 공개적으로 노출한 설정만 사용한다고 명시합니다. 사용자는 사용 전에 백업하고 결과에 대한 책임을 수락해야 합니다.

프로젝트 구조(주요 부분)

• tool/run.py — 메인 진입점
• tool/fast.py — 화면 읽기, 메뉴 항목 찾기, 스위치 전환 엔진(uiautomator2 사용)
• recipes/<brand>-<model>/recipe.py — 기기별 자동화 스크립트
• gui/ — 데스크톱 클라이언트(pywebview + PyInstaller)
• docs/ — 튜토리얼, 문제 해결, 복구 가이드, 퀵 앱 설명
• prompts/ — 채팅 AI용 기성 프롬프트
• AGENTS.md — AI 에이전트 운영 규칙