Metadata-Version: 2.4
Name: sma-autoui
Version: 0.3.1
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.7.16
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: loguru>=0.7.0
Requires-Dist: pytz>=2020.4
Requires-Dist: appium-python-client>=2.1.4
Requires-Dist: pillow>=9.5.0
Requires-Dist: lxml==5.1.0
Requires-Dist: opencv-contrib-python==4.13.0.90
Requires-Dist: ddddocr>=1.5.6
Requires-Dist: requests>=2.27.1
Requires-Dist: jinja2>=3.0.3
Requires-Dist: openai>=1.39.0
Requires-Dist: paramiko>=3.5.1
Requires-Dist: filelock>=3.12.2
Requires-Dist: python-dotenv>=0.21.1
Requires-Dist: pymysql>=1.0.2
Dynamic: license-file

# SMA AutoUI

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

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

---

## 🚀 快速开始

```bash
# 从 PyPI 安装
pip install sma-autoui

# 或从源码安装
pip install .
```

---

## 🌟 核心特性

| 特性 | 说明 |
|------|------|
| ✅ **多平台适配** | 多个社交平台业务抽象（TikTok / 小红书 / 微博 等） |
| ✅ **Session 复用** | 跨任务会话持久化与保活架构 |
| ✅ **视觉匹配** | SIFT 特征 + 模板匹配 + OCR 多模式识别 |
| ✅ **ADB 直达** | 困难页面（直播间 / SurfaceView）直接注入事件，绕开 W3C 限制 |
| ✅ **AI 驱动** | LLM 接口封装 + 认知工作流（Flow）编排 |
| ✅ **自愈能力** | UI 异常自动诊断与恢复，规则评分反馈闭环 |

> 完整项目结构与各层模块职责，详见 [🏗️ 系统架构](./docs/ARCHITECTURE.md)。

---

## 📖 文档

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

| 文档 | 描述 | 目标读者 |
|------|------|----------|
| [🛠️ APPIUM_SETUP_GUIDE.md](./docs/APPIUM_SETUP_GUIDE.md) | Appium + ADB 完整环境搭建与验证 | 新成员、运维 |
| [🏗️ ARCHITECTURE.md](./docs/ARCHITECTURE.md) | 系统架构、模块职责与依赖关系 | 开发者、架构师 |
| [💡 CLICK_MECHANISMS.md](./docs/CLICK_MECHANISMS.md) | ADB / Appium / W3C Actions 三种点击机制差异与选型 | 开发者 |
| [📋 SCRCPY_SERVER_GUIDE.md](./docs/SCRCPY_SERVER_GUIDE.md) | scrcpy-server 服务启动 / 剪贴板获取 / 控制协议中文指南 | 开发者 |
| [⚠️ PITFALLS.md](./docs/PITFALLS.md) | 项目开发中的常见问题与解决方案 | 开发者 |
| [🛣️ ROADMAP.md](./docs/ROADMAP.md) | 六层架构实现路径与未来规划 | 管理者、开发者 |

### 快速导航

- **新入门** → 先 [🛠️ 环境搭建](./docs/APPIUM_SETUP_GUIDE.md)，再 [🏗️ 架构概览](./docs/ARCHITECTURE.md)
- **点击机制选型** → [💡 点击机制详解](./docs/CLICK_MECHANISMS.md)
- **scrcpy 剪贴板 / 控制** → [📋 scrcpy-server 指南](./docs/SCRCPY_SERVER_GUIDE.md)
- **遇到问题** → [⚠️ 常见坑点](./docs/PITFALLS.md)
- **未来规划** → [🛣️ 开发路线图](./docs/ROADMAP.md)

---

## 💻 使用示例

```python
from sma_autoui.driver import Driver, Device

# 1. 初始化设备
device = Device(device_name="172.25.2.20:5555", adb_port=5002)

# 2. 创建驱动实例
driver = Driver(
    device=device,
    appium_url="http://localhost:4723/wd/hub",
    task_name="example_task"
)

# 3. 使用高级 API
driver.smart_find(locators=[...], timeout=10)
driver.tap_by_adb(x=500, y=800)

# 4. 任务自动重试与保活由 TaskRunner 处理
```

---

## 🔧 从源码安装

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