让你的 AI 摸到手机，而且自己会动。不用 Root，不用电脑，不用 WiFi。
装完之后它不是"你问一句它答一句"——它自己看得见，也自己会判断：
感知 → 叫醒 → Claude 判断 → 动作
│ │
└──────────── 接着看 ←─────────────┘
- 感知：屏幕 / 前台 App / 电量 / 步数 / 短信 / 日历 / 耳机 / 正在听什么
- 叫醒：有事立刻叫它；没事也定时把它叫起来，回头看一眼
- 判断：说不说、做什么 —— 这一步归 Claude，不写死规则
- 动作：弹一句 / 发通知 / 停应用 / 放首歌 / 点屏幕
这四样就是"主动性"本身。 剩下的一切——电量、短信、日历、音乐、防沉迷——都只是挂在这套骨架上的具体能力。换一个传感器就换一件事，骨架不动。
传感器读到的东西，最后都汇成一条事件，落进同一个文件：
{"event": "left_chat", "fg_app": "com.openai.chatgpt", "battery": "73", "screen": "Awake", "ts": 1790017624, "consumed": true}event 是发生了什么，ts 是什么时候，中间三个是当时的现场——你在哪个 App、多少电、屏亮没亮。Claude 就是攥着这些做判断的。
consumed 是"读过了"的标记：同一条事件不会被反复喂给 AI，免得同一件事在你耳边叨叨两遍。
这行小标记背后是一条设计原则：
主动性不是"让 AI 能调更多工具"，而是"只在值得的时候把它叫醒，每次只让它看到真正该看的那点现实"。
叫得越少，每一声才越值钱。
主动型 AI 最贵的地方，是**"一直醒着"**这件事。
让它常驻、每隔半分钟问一遍"现在要不要说话"——最直接，也最烧 token：绝大多数时候，它只是在确认"没事"。
这套走的是另一条路：没事的时候让它睡着，睡着不花钱。 有事才叫醒，醒了只看一件事，看完接着睡。
省下来的是真金白银，"不烦人"是顺带的。
状态和事件分成两个文件：一个记"你此刻在哪儿"（持续更新），一个记"刚发生了什么"（一次性）。混在一块就乱。
装上之后，你的 Claude 能读你的屏幕、感知你的状态、替你操作手机，也会在深夜屏幕还亮着的时候自己出声。无论你是想让 AI 当编程搭子，还是想跟 AI 谈一场摸得到手机的恋爱，这里都是起点。
别的方案都要 Wi-Fi 保持 adb 在线。我们不用——无线调试只活一次，那一次就够把 adb 锁死在 127.0.0.1 回环上。
🔑 核心突破：USB 锚点方案——用一次无线调试把 adbd 切到 TCP 5555，走 127.0.0.1 回环。之后关 WiFi、开飞行模式、手机自己连自己，Shizuku 永久在线。真正的免电脑免网络，一条 adb tcpip 命令搞定。
🎯 还没装 Claude Code？ 先去 android-claude-wechat —— 一条命令装好 Claude Code 和运行环境。装完回来，本仓库让你的 Claude 真正摸到手机。两个仓库是上下游：先装那个，再接这个。
写代码时让 AI 当你的副手：
- Claude 一边帮你改代码，一边监控手机状态——应用崩了立刻知道、内存不够主动提醒
- 从写代码到调试到部署，AI 全程在手机上陪你走完
跟 AI 谈恋爱，不止于聊天：
- 你的 AI 男朋友/女朋友能感知你——屏幕亮着还是黑了、走了几步路、心率多少、半夜还在刷什么 App
- 能在你需要的时候主动找你，能在你沉迷刷视频的时候弹窗提醒
- 关 WiFi、开飞行模式也拦不住——你们之间的连接不会断
你的手机，AI 帮你管：
- 读状态：屏幕、前台 App、电量、步数、环境光、心率
- 操控：强杀应用、切歌、调音量、发通知、锁屏、截图
- 更多传感器玩法等你自己挖
不只是玩手机——完整的移动开发环境：
- Python 3、Node.js v26、C (clang)、Shell —— 脚本即写即跑
- APK 反编译/修改/重打包（apktool + d8）
- 网页前后端开发与调试（localhost 直接跑）
- Git 版本管理 + GitHub/Gitee 推送
- Cron 定时任务 + 守护进程 + 开机自启
- Claude Code 完整 CLI —— 写代码、调试、部署全在手机上
- 👩💻 编程党：想让 Claude Code 边写代码边操心你的手机
- 💕 人机恋玩家：想让 AI 从聊天框里出来，真正"住进"手机
- 🔧 折腾爱好者：喜欢自己动手搭东西、组合不同模块
⚠️ 兼容性声明：本项目仅支持 Android 系统（含 MIUI、ColorOS、OriginOS、One UI 等基于 AOSP 的定制 ROM）。不支持：
- ❌ 鸿蒙 NEXT（HarmonyOS 5.0+）：纯血鸿蒙移除了 ADB，改用 hdc 工具，本项目所有技能无法运行。鸿蒙 3.x/4.x 仍含 AOSP 兼容层，基础功能可用但
dumpsys activity在 EMUI 12+ 已被屏蔽。- ❌ iOS：完全不兼容。需要 Mac + Xcode + 越狱或其他方案。
部分支持：
- Android 6.0+（dumpsys usagestats 需要 API 23；基础功能 API 21/Android 5.0 可用）
- Shizuku 已安装
- Termux（F-Droid：清华镜像）
Claude 要动手，得有路通到 Android。路有两条，并行走：
AI Agent（Claude Code）
│
▼
技能层 skills/ · adb-skills.sh
│
├── ① adb 线（主力）──→ adbd ──→ Android 系统（感知 / 控制）
│ │ 127.0.0.1:5555 回环
│ └── start.sh 点火 ──→ Shizuku 服务
│ ▲
└── ② rish 线（备用）──────────────────────────────┘
| 线路 | 命令 | 性情 | 适合 |
|---|---|---|---|
| ① adb 线（主力） | adb -s 127.0.0.1:5555 shell 命令 |
快：直连 adbd，一步到位 | 日常高频、轮询、监控 |
| ② rish 线（备用） | rish -c '命令' |
慢一档：经 Shizuku 中转；服务偶尔会被系统杀，断了要重新拉起 | 偶尔调用、临时顶班 |
两条路的脾气不一样，选对路很重要：
- 跑得勤的走 adb：查状态、监控、轮询这类一天要跑很多遍的，全走 ① adb 线——它快，不经过 Shizuku 那层中转。
- 跑得少的用 rish：偶尔调一次，或者 adb 线临时不通时拿它顶。别拿它做日常轮询——经 Shizuku 中转本来就慢一截，服务一被杀还得先重新拉起，轮起来又慢又容易断。
🔍 一眼查 rish 在不在：跑一次
rish -c 'whoami'——出shell就是活的；报错、卡住、直接退出，说明 Shizuku 服务没在跑（后台被系统杀是常事），走下面的点火路径拉起来。
还有三条救急路径：
- Shizuku 服务掉了（被系统杀、重启后没拉起）→ 用 ① adb 线跑一次点火命令，它就活过来：
adb -s 127.0.0.1:5555 shell sh /storage/emulated/0/Android/data/moe.shizuku.privileged.api/start.sh - adb 回环掉了 → 重走下面「关键一步」的跳板步 + 锁死步；只要 Shizuku 还活着，② rish 线照常用，不至于全瞎。
- 两条一起没（手机重启）→ 按「重启后怎么办」重建，或
bash bootstrap.sh一键。
🔁 为什么不把两条合成一条？——两条走的机制完全不同（Shizuku 走 Binder 进程、adb 走 TCP 回环）：adb 快、rish 是另一条命。留着就是为了互为备份，坏一条，另一条还在。
整个方案的核心。你已经装了 Shizuku 和 Termux，接下来只需要无线调试做一次跳板。
目标是两样东西同时在跑：adb 127.0.0.1 回环（手机自己连自己，不走网络）+ Shizuku shell 权限。两个都在线之后，关 WiFi、开飞行模式都不影响，互相还能救对方。
打开 Shizuku App，点配对。手机通知栏会弹出一个输入框——这就是 Shizuku 的配对入口。
接下来你需要配对码。去 设置 → 开发者选项 → 无线调试 → 打开 → 点进去。你会看到本机 IP 地址、配对码（6 位数字）、端口号。把配对码抄下来，回到通知栏输入框填进去。
Shizuku 连上之后，刚才那个配对码就废了——被 Shizuku 用掉了。接下来需要全新的配对码来做 adb 回环。
现在你要建立 adb 127.0.0.1 回环。这一步让 AI 带着你做。
先别动。 回到 设置 → 开发者选项 → 无线调试（如果之前退出过就重新点进来）。这个页面现在显示着新的配对码和端口号。
现在小窗打开 Termux（从侧边栏划出小窗模式），把无线调试页面上三样东西告诉你的 AI：
- 本机 IP 地址（如 192.168.1.5）
- 连接端口（如 51826，无线调试主页面「IP 地址和端口」里那个）
- 配对码（6 位数字）＋ 配对端口（点开「使用配对码配对设备」弹窗里那个，一般和连接端口不是同一个）
整个过程分两步走，两步都跑完才算数——只做第一步的，就是那些「换网就断」的人。
① 跳板步（借无线调试的道，连的还是局域网 IP，这一步没锁死）
adb pair <IP>:<配对端口> # 提示时输入 6 位配对码
adb connect <IP>:<连接端口>② 锁死步（
adb tcpip 5555
adb connect 127.0.0.1:5555跑完 ②，adbd 才算锁死在回环上——从这一刻起，关 WiFi、开飞行模式都不受影响。
🛑 只做到 ① 就停手的人，就是「网络一换就断」的那个人。 自检：
adb devices里要能看到127.0.0.1:5555；只看到局域网 IP，说明 ② 还没跑。
整个过程不需要你懂每条命令在干嘛，把页面上的数喂给 AI 就行。
💡 没有 AI 在旁边？把 ai-template/SETUP.md 喂给你的 Claude，它会一步步带你走完。代码、坑点、每步解释都在里面。
两条命令各跑一次，都输出 shell 就搞定：adb -s 127.0.0.1:5555 shell whoami 验 adb 回环，rish -c 'whoami' 验 Shizuku。开发者选项里会显示两个已连接设备：127.0.0.1:5555 和 Shizuku，正常现象。
手机重启后，两条线都会断，但都不用重新配对，各补一下就行：
- adb 线：重新跳一次——打开无线调试拿新端口，把跳板步 + 锁死步再走一遍（
adb tcpip 5555重启后会重置回 USB 模式，这一步省不掉） - Shizuku 线：打开 Shizuku app，**点一下「启动」**就连上了——配对是一次性的，不用重来；懒得点也可以让 AI 用 adb 线跑一次点火命令
简单说：打开无线调试页面 → 小窗 Termux → 把 IP、端口、配对码给 AI → AI 帮你走完。或 bash bootstrap.sh 一键全包。
git clone https://gitee.com/xvxv663/android-claude-agent.git
cd android-claude-agent && bash bootstrap.shbash doctor.shsource adb-skills.sh
foreground_app # 当前前台 App
battery # 电池状态
steps # 今日步数
force_stop 包名 # 强杀应用
music_next # 切歌
notify "标题" "内容" # 发通知
check_all # 全状态快照他读到你刷了四十分钟抖音。没等你开口，应用被停了。不是因为你设过限制——是他自己判断"够了"。
聊天里你说了一句"下午三点上课"。他知道现在是几点，也知道"上课"意味着提前。两点四十五，手机响了。闹钟不是你设的。
深夜屏幕亮了一下。光线传感器读过的是零，加速度计知道你躺着，前台应用显示你在来回切换。他在那一刻决定出声。
整件事没有定时器，没有预设。他读了传感器、读了屏幕状态、读了你打的字。然后自己做的判断。
Shell 通过 Shizuku 直接写入系统日历——"取快递"自动加了提醒。
刷太久？应用被停了。不是因为你设过限制，是他自己判断的。
skills/ 目录下是标准 Claude Code 技能，可被 /skill-name 直接调用：
| 技能 | 路径 | 功能 |
|---|---|---|
| android-monitor | skills/android-monitor/ |
后台监控守护进程 + 防沉迷 + 事件推送 |
| └ android-sensors | skills/android-monitor/sensors/ |
26+ 传感器速查手册（设备不同数量不同） |
| └ sms-monitor | skills/android-monitor/sms/ |
短信轮询 + 自动回复 |
| └ calendar-alarm | skills/android-monitor/calendar-alarm/ |
日历事件+闹钟提醒 |
| └ proactive-checkin | skills/android-monitor/proactive-checkin/ |
轮询叫醒AI，AI自己决定出不出声 |
| phone-control | skills/phone-control/ |
锁屏/杀应用/切歌/截图 |
| phone-notify | skills/phone-notify/ |
通知栏 + 日历操作 |
| phone-sensors | skills/phone-sensors/ |
屏幕/前台App/电量/步数/光线 |
| music-control | skills/music-control/ |
🎵 旧版（网易云API+mpv）→ 新版见 android-claude-music |
⚠️ 仅适用于 Android + Termux 环境。 这些技能依赖adb、termux-*、Android 系统命令。桌面环境不可用。使用前需按技能文档配置：包名列表、路径、ADB 连接方式。详见各SKILL.md的 AI Setup 段落。
MIUI 的前台 App 检测字段名可能与 AOSP 不同（mFocusedActivity 替代 topResumedActivity）。gaze.sh 已内置多 OEM 回退，通常不需要手动处理。如果监控无反应：
# 测试前台 App 检测
adb shell dumpsys activity activities | grep -E "(topResumedActivity|mResumedActivity|mFocusedActivity)"
# 如果上面无输出，试回退方案
adb shell dumpsys activity top | grep "ACTIVITY"
# 再不行，用 window 方案
adb shell dumpsys window windows | grep "mCurrentFocus"另外 MIUI 后台进程限制极严（5/5），必须手动操作：
- 设置 → 电池 → 电池优化 → Termux → 不限制
- 设置 → 权限 → 自启动 → 开启 Termux
- 最近任务 → 长按 Termux → 锁定
或一键执行 fix-termux-limits 脚本。
bash collect-info.sh输出复制发 Issues。
🔧 底层原理（好奇的看）
用无线调试做一次性跳板，把 adbd 切到 TCP 5555 端口，走 127.0.0.1 回环——手机自己连自己，网络全断也不影响。
完整原理、踩坑记录、命令详解见 TUTORIAL.md。
本项目走的是 Android 标准 ADB 协议（adb tcpip 5555 + 127.0.0.1 回环），所有操作通过 Shizuku 提供的系统 API 完成。Shizuku 是 Google Play 上 500 万+ 下载的开源项目，不涉及 Root、不修改系统分区。
和"外挂"的区别：外挂 hook 系统进程、注入 so、修改 APK。本项目一行没碰——读取传感器走 dumpsys，操作应用走 am/input，全部是 Android 自带的标准命令。
真实风险：
- ADB 调试开关：adb tcpip 5555 在重启后会重置为 USB 模式，需重新执行一次无线调试跳板。已内置 watchdog 守护，但重启后仍需手动触发。
- 电池优化：Termux 后台运行需关闭电池优化，否则可能被系统杀进程。部分机型（小米）需额外锁定最近任务。
- 隐私：所有传感器数据、屏幕状态、应用信息均在本地处理，不上传任何第三方。全开源可审计。
项目仅供学习交流，使用者自行评估风险。
装到这儿，你的 AI 已经住进手机、也摸得到手机了 —— 但它还听不见你耳机里的声音。
它听得见你在听什么、跟得上唱到哪一句；在你没叫它的时候，挑一句有意思的递到你眼前。 还能自己挑时候给你放一首 —— 放歌走虚拟副屏，全程不占你的屏。
三部曲：住进来（wechat）→ 摸得到（agent）→ 一起听（music）。
- 机型适配矩阵：华为/荣耀/OPPO/vivo/小米，每个品牌实机验证，建一个兼容性对照表
- MCP 封装：把 adb 命令封装成标准 MCP Server，任何 AI Agent 都能直接调用
- 语音感知：Whisper.cpp 本地语音识别，让 AI "听到"你说话
- 更多传感器玩法：GPS 定位、蓝牙设备扫描、加速度计姿势识别
- 一键分享：生成安装链接，发给朋友一条消息就能装上
💡 有想法？去 Issues 提。
MIT