用 AI 驱动安卓手机的命令行工具 —— 库内无 AI。
mobilecli 是一个 Python 命令行工具，让外部 AI 智能体（Claude Code、Codex CLI、openclaw 等）驱动一台真实的安卓手机。每条命令都是 JSON 进 / JSON 出且无状态；AI 读取 CLI 写到磁盘的截图 / XML dump，再决定下一步做什么。
这个库里没有 AI。 智能存在于调用 mobilecli 的那个工具里。
本项目仅用于学习与安全研究。 这是一个通用的 Android 自动化库，演示 AI 代理如何驱动移动 App。维护者不鼓励、不推荐、不为任何违反第三方平台（包括但不限于抖音、快手、小红书、微信、TikTok）服务条款的使用行为负责。使用者须独立承担行为、账号安全与法律合规责任。使用本项目用于刷量、骚扰、群发、伪造互动、规避平台反作弊机制等行为，明确不在本项目支持范围内。使用本软件即代表接受所有风险，包括但不限于账号封禁、限流、限评、设备级封锁。
关于状态变更操作。 部分动作（
like点赞 /comment评论 /reply回复 / 批量engage/publish发布）在加--commit且设置EM_ALLOW_COMMIT=1环境变量时，会真正改动平台状态。这道双闸是技术防呆，不是授权——它强制操作者做出明确、不可逆的选择。每日上限（governor）与文案检查会被执行，但它们只是为了让你慢下来，并不能让自动化互动变得安全或合规。设置EM_ALLOW_COMMIT=1的一切法律与道德责任由你独自承担。
pipx install -e .
mobilecli devices
mobilecli doctor
mobilecli screenshot -o /tmp/x.png第一次用红米 / MIUI 的话，先看下面的 ADB 调试设置，否则什么都跑不起来。
Redmi / Xiaomi（MIUI / HyperOS）需要做三件事：开发者选项 + USB 调试 + USB 调试（安全设置）。少了「安全设置」那个，本项目的 tap / swipe / input 都会被拒。
- 设置 → 我的设备 → 全部参数与信息 → 连续点击 "OS 版本"（HyperOS）或 "MIUI 版本"（旧版 MIUI）7 次
- 出现「您已处于开发者模式」提示即解锁
- 设置 → 更多设置 → 开发者选项
- 打开 「USB 调试」
- 打开 「USB 调试（安全设置）」 ← 这一项很多教程不提，但这是 Redmi/MIUI 特有的开关，不开就不能执行
input tap等模拟操作。打开时手机会弹窗要求登录小米账号 - 推荐打开 「停用 adb 授权超时」，否则隔几天要重新授权一次
adb devices
# 第一次会列出设备但 state 是 unauthorized手机上会弹窗「允许调试」提示，勾选「始终允许」，确定。
adb devices
# 现在: <serial> devicemobilecli devices
mobilecli doctor
mobilecli screenshot -o /tmp/test.png
ls -la /tmp/test.pngADB 自带的 input text 不支持中文。装一个开源 IME 让 mobilecli type "学到了" 能用：
# 从 https://github.com/senzhk/ADBKeyBoard 下载 ADBKeyboard.apk
adb install ADBKeyboard.apk
adb shell ime enable com.android.adbkeyboard/.AdbIME
# mobilecli 在需要中文时会自动切到这个 IME，结束后切回原 IMEunauthorized：手机上没勾「始终允许」，重新插拔 USB 看弹窗offline：换一根带数据的 USB 线（充电专用线只供电不通信）tap无效但没报错：「USB 调试（安全设置）」没开- 连不上：USB 模式选成「仅充电」了，改成 「文件传输 (MTP)」 或 「PTP」
- MIUI 14+ 上
pm list packages卡住：开发者选项里关掉「MIUI 优化」，重启手机
| 命令 | 用途 | JSON data 关键字段 |
|---|---|---|
mobilecli devices |
列出连接的设备 | devices[] |
mobilecli screenshot [-o PATH] |
截屏到 PNG | path, size, width, height |
mobilecli doctor |
环境自检 + 风控指纹信号 | checks[], summary |
mobilecli douyin <verb> |
抖音 app 操作 | 见下 |
mobilecli kuaishou <verb> |
快手 app 操作 | 见下 |
mobilecli xiaohongshu <verb> |
小红书 app 操作 | 见下 |
设计哲学：CLI 表面只有高层意图（app verb）+ 必要的环境查询（devices/screenshot/doctor）。 低层原语（tap/swipe/type/keyevent/dump 等）是 Layer 2 内部 API，plugin 通过
ExecContext调用，不暴露成 CLI 命令。 这样 AI 驱动者拿到mobilecli douyin search而不是被一堆tap X Y淹没。需要 raw 调试时可以python -c "from mobilecli.core import input as i; ..."直接走 Python API。
douyin / kuaishou / xiaohongshu 共用同一套 9 个核心 verb（下表把 <app> 换成具体 app 名）；小红书另有 engage / publish 两个。
| 命令 | 用途 | 备注 |
|---|---|---|
<app> launch |
启动 app，关动画、清弹窗、回首页 feed | |
<app> search --keyword K [--limit N] |
搜索 | 返回结果列表，不自动点开 |
<app> open --rank N |
点开第 N 个搜索结果 | |
<app> detail |
抓当前内容(视频/笔记)互动数据 | 读后带「阅读停顿」+ 偶发小幅滑动 |
<app> back |
返回上一层 | |
<app> like [--commit] |
给当前内容点赞 | 默认 dry-run；--commit 需 EM_ALLOW_COMMIT=1 |
<app> comment --text T [--commit] |
在当前内容下评论 | 默认 dry-run；同上 |
<app> reply (--rank N | --match KW) --text T [--commit] |
回复某条可见评论(按序号或关键词命中) | 默认 dry-run；同上 |
<app> profile [--avatar-out PATH] |
读登录态；已登录返回头像(裁剪PNG)/昵称/平台号/关注·粉丝·获赞数 | 只读。小红书 / 快手另含简介 |
仅小红书：
| 命令 | 用途 | 备注 |
|---|---|---|
xiaohongshu engage --keyword K [--limit N] [--like] [--comment-text T] [--sleep S] [--commit] |
搜词 + 遍历 top N + 批量点赞/评论 | 复合 verb；默认 dry-run；强烈建议先无 --commit 试跑；用前请重读上方免责 |
xiaohongshu publish --media P... --title T --body B [--tags "a,b"] [--cover N|PATH] [--declare ai|original|...] [--commit] |
发布图文(多图)或视频 | 按扩展名自动判型；默认 dry-run(推素材+走到发布键前截图)；--commit 需 EM_ALLOW_COMMIT=1。需先授予小红书完整 READ_MEDIA 权限 |
profile各端返回字段:小红书nickname/red_id/ip/follow_count/fans_count/fav_count/bio/avatar;抖音nickname/douyin_id/following_count/fans_count/likes_count/avatar;快手nickname/kwai_id/following_count/fans_count/likes_count/bio/avatar。未登录只返回logged_in:false。
| 参数 | 含义 |
|---|---|
--serial SERIAL |
指定设备（多机时必填，单机时可省，读 EM_SERIAL 兜底） |
--pretty |
JSON 缩进打印 |
--verbose |
stderr 调试日志 |
--timeout SEC |
单条命令超时（默认 30s） |
--raw |
关闭人类化（仅调试用；需 EM_ALLOW_RAW=1） |
--account NAME |
SessionGovernor 账号标识（默认 default） |
mobilecli 默认就给所有 tap / swipe / type 加上：
- 时序方差：
tap触屏时长 log-normal(μ=90ms, σ=0.5)，不是input tap那种 duration=0 的指纹 - 坐标抖动：
tap_humanized在元素 bounds 内框 60% 区域随机采样；按坐标点的话 ±8 px 抖动 - 滑动：默认人类化直线（端点 ±4 px + 时长 [0.8, 2.0] s 随机），任何机型都可用；置
EM_CURVED_SWIPE=1可改用沿 bezier 轨迹的 sendevent 连续曲线（需可写/dev/input的 root 设备，否则自动快速回退到直线，永不退化） - 打字：ASCII 每字符 log-normal(μ=120ms, σ=0.6) 间隔
- 操作间延迟（pacing）：
ctx.input.*每个动作前插一次截断高斯延迟（默认 [2, 10] s，均值 6、σ=2），同一序列首个动作不等。慢=像人；可调可关（见下表） - 阅读行为：浏览类 verb（
open/detail等）读取后会随机「阅读停顿」，并偶发小幅来回滑动模拟看内容；填表流程（publish）不加 SessionGovernor：每个--account的每日动作计数持久化到~/.everything-mobile/sessions/<account>.json；超 cap →RATE_LIMITEDenvelopeContentLinter：自动拦截「加微信 / VX / 扫码 / 戳我 / 11 位手机号 / QQ / wx-id」等明显引流文案 →CONTENT_BANNEDenvelope
| 环境变量 | 默认 | 含义 |
|---|---|---|
EM_PACE |
开 | 设 0 关闭操作间高斯延迟（调试 / 批量跑得快时用） |
EM_PACE_MIN |
2 |
pacing 延迟下界（秒） |
EM_PACE_MAX |
10 |
pacing 延迟上界（秒） |
EM_CURVED_SWIPE |
关 | 设 1 启用 sendevent 连续曲线滑动（仅 root 设备生效，否则快速回退直线） |
⚠️ publish 会变慢：默认 pacing 下，publish有 ~15+ 个输入动作，单条发布可能多花 30–150 s（这是风控正向的）。营销 / 批量调用方可按需调小EM_PACE_MIN/MAX或用EM_PACE=0。
完整时序参数、风控研究与平台 cap 表见 docs/anti-risk-control.md。
这一层不能关。 --raw 仅为调试存在，需 EM_ALLOW_RAW=1 环境变量，且会在 stderr 警告。EM_PACE=0 只关「额外的拟人停顿」，tap/swipe/type 本身的方差与抖动始终在。
把这个工具当成你账号的代理人时，可能发生：
- 账号限流 / 限评 / 限关注（平台的「请稍后再试」/ 互动数据冻结）
- 影子封禁（shadowban）：内容不再分发但你看不到提示
- 临时功能限制 24h → 7 天 → 30 天 → 永久（多平台累进逻辑一致）
- 整机风控：同一设备下的所有同平台账号一起被关注
- 法律 / 合规风险：在某些场景被认定为「未经授权的自动化访问」
平台规则随时变。docs/anti-risk-control.md 的数据是 2025–2026 实测 + 官方公约整理的，但请把它当作下限——不是「这样发就一定安全」。
这些用例不在本项目支持范围内，对应 PR 会被关闭：
- ❌ 群发私信 / 群发评论 / 群发关注的「营销工具」
- ❌ 刷赞 / 刷粉 / 刷阅读 / 刷互动 的造数工具
- ❌ 自动批量注册账号 / 养号工具链 / 接码平台对接
- ❌ 绕过人机验证 / 滑块 / 拼图的工具
- ❌ 仿冒登录态 / 撞库 / 凭据填充
- ❌ 任何旨在欺骗平台检测、骚扰其他用户、伪造统计的功能
如果你的场景听起来像上面任何一条 — 请别提 issue，也别开 PR。
如果你是 Claude Code / Codex / openclaw 这类 AI 驱动者，请看 docs/ai-usage.md：里面有完整的调用范式 + 批量场景示例 + 错误码处理。
mobilecli 用 entry_points 机制支持外部插件。pip install mobilecli-tiktok 之类的包可以自动注册到 mobilecli tiktok ... 子命令。
完整指南：docs/plugin-guide.md。
PR 欢迎，但务必先看 CONTRIBUTING.md。新 verb 必须配 fixture 单测 + 真机集成测试。匿名 PR 会被关闭。
MIT。