Metadata-Version: 2.4
Name: sma-autoui
Version: 0.7.5
Summary: Smart Mobile Automation UI Framework
Home-page: https://github.com/Fun-Fox
Author: FunFox
Author-email: FunFox@example.com
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: loguru>=0.7.0
Requires-Dist: pytz>=2026.5
Requires-Dist: appium-python-client>=6.0.5
Requires-Dist: pillow>=10.0.0
Requires-Dist: lxml>=5.1.0
Requires-Dist: rapidocr>=3.0
Requires-Dist: onnxruntime>=1.20
Requires-Dist: requests>=2.27.1
Requires-Dist: jinja2>=3.0.3
Requires-Dist: pydantic>=2.14.1
Requires-Dist: pydantic-ai-slim[logfire,openai,typesafe]>=2.54.0
Requires-Dist: paramiko>=3.5.1
Requires-Dist: filelock>=3.12.2
Requires-Dist: python-dotenv>=1.2.4
Requires-Dist: pymysql>=1.2.3
Requires-Dist: redis>=8.1.0
Requires-Dist: selenium>=4.37.0
Requires-Dist: numpy>=2.5.4
Requires-Dist: setuptools>=69.0.3
Dynamic: license-file

# SMA AutoUI

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

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

---

## 🚀 快速开始

```bash
# 从 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)。

---

## 📖 文档

全部文档位于 [docs/](./docs/) 目录。

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

### 快速导航

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

---

## 💻 使用示例

```python
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")
```

---

## 🔧 从源码安装

```bash
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
