一个面向 Android 桌面的应用分析与自动分类工具。Python 端通过 UIAutomator2 采集桌面图标，使用规则、本地模型或 OpenAI-compatible API 生成布局计划，并在明确关闭 dry_run 后执行拖拽整理；仓库同时包含一个 vivo Launcher 实验性 Android Helper。
- 采集多页桌面图标、坐标与文件夹信息
- 规则分类、本地 Qwen 推理或 OpenAI-compatible API 分类
- 网格和文件夹两种整理策略
- 计划预览、运行记录与回滚数据
- Android 端应用分区预览和只读 Launcher Provider 探测
app_organizer/ Python 核心逻辑
scripts/ 快照解析、导出和训练数据转换脚本
android-helper/ Android Studio Helper 项目
tests/ 不连接设备的最小单元测试
需要 Python 3.10+、ADB，以及已开启 USB 调试的 Android 设备。
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt复制安全示例并填写本机参数；config.yaml 已被 Git 忽略。
cp config.example.yaml config.yaml
python main.py --config config.yaml planPowerShell 可使用：
Copy-Item config.example.yaml config.yaml
python main.py --config config.yaml plan默认配置使用规则分类且 runtime.dry_run: true。确认计划和设备坐标无误后，才可执行真实操作：
python main.py --config config.yaml run --dry-run false机器标识和密钥建议只通过环境变量注入；环境变量优先于 YAML：
| Variable | Purpose |
|---|---|
ADO_DEVICE_SERIAL |
adb devices 返回的设备序列号 |
ADO_LAUNCHER_PACKAGE |
当前设备 Launcher 包名 |
ADO_MODEL_PROVIDER |
rule、openai_compat 或 qwen_local |
ADO_MODEL_NAME_OR_PATH |
本地模型名称或路径 |
ADO_MODEL_DEVICE |
cpu、cuda 或 auto |
ADO_API_BASE_URL |
OpenAI-compatible API 地址 |
ADO_API_KEY |
API 密钥；本地无鉴权服务可留空 |
ADO_API_MODEL |
API 模型名 |
ADO_RUN_DIR |
本地运行产物目录 |
使用本地 Transformers 模型时安装可选依赖：
pip install -r requirements-ml.txt用 Android Studio 打开 android-helper/。该模块包含普通应用分区 UI，以及 vivo Launcher Provider 的实验性只读探测器。厂商权限可能拒绝查询，这是预期行为；发布副本不申请 Launcher 写权限，也不包含任何设备导出数据。
Android 模拟器访问宿主机服务时可使用 http://10.0.2.2:8000/v1。真机地址和 API 密钥在应用设置中填写，不应提交到仓库。
- 首次运行始终保留
dry_run: true，并先备份桌面布局。 runs/、Helper 输出和训练导出会暴露已安装应用及桌面布局，均已加入.gitignore。- API 模式会把应用名称和包名发送到你配置的服务，请只使用可信端点。
- 本发布副本不包含 APK/DEX、反编译厂商代码、真实设备清单、模型、缓存、崩溃日志或本地配置。
python -m unittest discover -s tests -v
python -m compileall -q main.py app_organizer scripts