SMA AutoUI

智能移动自动化 UI 框架 —— 面向社交媒体平台的 Android 设备自动化，融合 ADB 直达、视觉识别与 LLM 认知自愈能力。

📦 PyPI：https://pypi.org/project/sma-autoui/

🚀 快速开始

# 从 PyPI 安装
pip install sma-autoui

# 或从源码安装
pip install .

🌟 核心特性

特性	说明
✅ 多平台适配	10 个社交平台业务抽象（TikTok / 抖音 / 小红书 / 微博 / X / Threads / Instagram / Facebook / WhatsApp / 酷安）
✅ Session 复用	跨任务会话持久化与保活架构
✅ 视觉匹配	模板匹配下沉 Appium images-plugin（服务端 OpenCV + 自动缩放）+ OCR 文字定位，文字优先、图标兜底
✅ ADB 直达	困难页面（直播间 / SurfaceView）直接注入事件，绕开 W3C 限制
✅ 拟人化行为	点击抖动（jitter）、连点、随机等待、概率化交互
✅ AI 驱动	基于 pydantic-ai 的 Agent 编排 + 结构化输出 + 双通道模型（生成 / 判定）
✅ 自愈能力	UI 异常自动诊断与恢复，规则注册 / 淘汰闭环
✅ 离线诊断回放	回放夹具（ReplayHarness）复现线上 AI 调用 + 调用轨迹汇总（telemetry）

完整项目结构与各层模块职责，详见 🏗️ 系统架构。

📖 文档

全部文档位于 docs/ 目录。

文档	描述	目标读者
🏗️ architecture.md	系统架构、六层模块职责与依赖关系	开发者、架构师
🛣️ roadmap.md	演进路径与未来规划	管理者、开发者
⚠️ pitfalls.md	项目开发中的常见问题与解决方案	开发者
🛠️ appium-setup-guide.md	Appium + ADB 完整环境搭建与验证	新成员、运维
💡 click-mechanisms.md	ADB / Appium / W3C Actions 三种点击机制差异与选型	开发者
🤖 behavior-humanization.md	拟人化行为设计（jitter、随机等待、概率交互）	开发者
📋 scrcpy-server-guide.md	scrcpy-server 服务启动 / 剪贴板获取 / 控制协议中文指南	开发者
📝 changelog/	各版本变更日志与回归测试清单	全体

快速导航

新入门 → 先 🛠️ 环境搭建，再 🏗️ 架构概览
点击机制选型 → 💡 点击机制详解
拟人化 / 反检测 → 🤖 拟人化行为设计
scrcpy 剪贴板 / 控制 → 📋 scrcpy-server 指南
遇到问题 → ⚠️ 常见坑点
未来规划 → 🛣️ 开发路线图
看版本改了什么 → 📝 变更日志

💻 使用示例

from appium.webdriver.common.appiumby import AppiumBy
from sma_autoui.driver import Device, Driver
from sma_autoui.engine import TaskRunner

# 1. 初始化设备（ADB 连接 + 环境准备）
device = Device(device_name="172.25.2.20:5555", adb_port=5002)
device.initialize_env()

# 2. 创建驱动实例（门面，聚合 actions / locator / inspector / vision / browser）
driver = Driver(
    device=device,
    appium_url="http://localhost:4723",
    job_id="example_job",
    desired_caps={...},
    app_name="xhs",
    app_version="1.0.0",
    task_name="example_task",
)

# 3. 使用高级 API
element = driver.smart_find(
    locators=[(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().text("Follow")')],
    timeout=10,
    ai_recovery=True,          # 定位失败时触发 AI 诊断自愈
)
driver.tap_by_adb(x=500, y=800, jitter=8)   # ADB 直达 + 坐标抖动
driver.smart_swipe(direction="UP", degree="MIDDLE")

# 4. 任务重试、异常自愈与保活由 TaskRunner 统一处理
TaskRunner(driver=driver).run(task_func=my_flow, task_name="example_task")

🔧 从源码安装

git clone https://github.com/Fun-Fox/sma_autoui.git
cd sma_autoui
pip install -r requirements.txt
pip install -e .

📄 开源协议

MIT License

Built with ❤️ by FunFox

Metadata

Release files for sma-autoui 0.5.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sma-autoui 0.5.7
File	Size	Uploaded
sma_autoui-0.5.7.tar.gz	3.3 MB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sma-autoui 0.5.7
File	Interpreter	ABI	Platform	Reset
sma_autoui-0.5.7-py3-none-any.whl 3.3 MB Oct 13, 2026	Python 3	none	any	Details

Total release size: 6.6 MB

Release files / sma_autoui-0.5.7.tar.gz

Download URL	sma_autoui-0.5.7.tar.gz
Size	3.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`760361db5c6aafd757c18cf0e4aa5462e0e59f23987a44bb2617aaa2a928585f`
BLAKE2b-256 checksum How to use checksums	`73975c8002c14cf239a8f1b2b6f15e837a0e53b53b7f6d9ddb2ad1d199a2f209`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.9`

Release files / sma_autoui-0.5.7-py3-none-any.whl

Download URL	sma_autoui-0.5.7-py3-none-any.whl
Size	3.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`7361ac040ba2e02d96b3fd3fe3d98de1dfe0ff453a7841e477c4ee53d863bd0c`
BLAKE2b-256 checksum How to use checksums	`30019f93f0934c6b9cee49a0c0198d23812475e33f5be510f73ce4afcdc032d1`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.9`