Metadata-Version: 2.4
Name: mumdad
Version: 0.1.4
Summary: Multi-platform disguise automation — ADB gesture disguise & WeChat scroll navigation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# mum — Multi-platform disguise automation

Android / iOS / HarmonyOS / Web disguise automation toolkit. Built for mobile APP data collection with anti-detection gestures and device-adaptive scroll navigation.

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

---

## 一、项目介绍

mum 是一个多平台自动化伪装工具包，核心解决移动端 APP 自动化采集中的防风控和手势兼容性问题。

### 核心模块

| 模块 | 说明 |
|------|------|
| `adb` | ADB 伪装客户端 + scroll_down/up 手势翻页（Android 版本自适应） |
| `wechat` | 微信主界面会话列表归位（from×L 随机采样 + 不限次数 + dHash 冷启动兜底） |

---

## 二、安装

```bash
pip install mum
```

或从 GitHub：

```bash
pip install git+https://github.com/yuyidream/mum.git
```

---

## 三、核心特性

### 3.1 DisguiseAdbClient — ADB 伪装客户端

自动注入人类操作模拟，防止 APP 风控检测：

- **随机延迟**：每次操作前注入 80~350ms 随机 sleep
- **坐标微偏移**：tap 坐标 ±5px 随机 jitter
- **duration 随机化**：swipe 时长 + 0~80ms 随机
- **key_event 专门延迟**：BACK/HOME 键注入 80~200ms 专用延迟

```python
from mum.android.base.adb import DisguiseAdbClient

adb = DisguiseAdbClient("device_serial")
adb.click(540, 1200)  # 自动注入延迟 + jitter
adb.swipe(540, 2000, 540, 500, duration_ms=400)  # duration 自动加 0~80ms
```

### 3.2 session_list_content_scroll_down/up — 会话列表手势翻页

基于 from×L 模型，Android 版本自适应：

| Android 版本 | L 参数 | 适用设备 |
|---|---|---|
| < 13 | [66%, 68%] | D1 (MI 8 UD, Android 10) |
| ≥ 13 | [51%, 53%] | D2 (HyperOS 16) / D3 (Harmony 13) |

关键约束：velocity ≤ 1.0 px/ms（防 Android fling 惯性）。

```python
from mum.android.base.adb import session_list_content_scroll_down, session_list_content_scroll_up

adb = DisguiseAdbClient("device_serial")
w, h = adb.wm_size()

# 翻下一页
session_list_content_scroll_down(adb, screen_w=w, screen_h=h)

# 回翻上一页
session_list_content_scroll_up(adb, screen_w=w, screen_h=h)
```

### 3.3 reposition_wechat_to_list_top — 微信会话列表归位

从任意 WeChat 状态归位到主界面会话列表最顶端。

**两阶段流程**：
1. **导航**：截图 → 层级检测 → 导航到 L1 chat_list (A/B/C)
2. **锚点下拉**：from×L 随机采样 → 触发「最近」→ 点击「微信」→ 回到列表顶

**重试策略（v0.1.4）**：**不限次数**下拉，仅 deadline（默认 60s）停止；连续两帧 dHash Hamming ≤ 3 且不在「最近」页面时，触发 `layer_model.back_recover()` 冷启动恢复（HOME → 冷启动微信 → 回到 L1 会话列表）后继续下拉。

```python
from mum.android.wechat.reposition import reposition_wechat_to_list_top

result = reposition_wechat_to_list_top(
    adb, scale_w=1.0, screen_w=1080, screen_h=2248,
    deadline_s=60.0,
)
print(f"归位: {'OK' if result.ok else 'FAIL'} ({result.reason})")
```

---

## 四、目录结构

```
mum/
├── android/
│   ├── adb/                      ← ADB 伪装 + scroll_down/up
│   │   ├── coordinate.py         ← 坐标 jitter (±5px)
│   │   ├── random_delay.py       ← 随机延迟 (80~350ms)
│   │   ├── disguise_client.py    ← DisguiseAdbClient + Debug
│   │   ├── scroll.py             ← session_list_content_scroll_down/up
│   │   └── _raw_adb.py           ← 原生 ADB 包装器
│   └── wechat/
│       └── reposition.py         ← 微信会话列表归位
├── docs/
│   └── adr/
│       └── disguise_android_feasibility.md  ← 技术可行性评估
├── harmonyos/                    ← 占位
├── ios/                          ← 占位
├── web/                          ← 占位
├── pyproject.toml
├── README.md
└── LICENSE
```

---

## 五、设备验证

| 设备 | Android | 分辨率 | 微信版本 | 验证结果 |
|------|---------|--------|----------|----------|
| D1 (MI 8 UD) | 10 | 1080×2248 | 8.0.71 | ✅ 10 轮 100% |
| D2 (25113PN0EC) | 16 | 1220×2656 | 8.0.71 | ✅ 10 轮 100% |
| D3 (WDY-AN00) | 13 | 720×1612 | 8.0.72 | ✅ 10 轮 100% |

---

## 六、相关文档

- [技术可行性评估报告](docs/adr/disguise_android_feasibility.md) — 贝塞尔曲线拒绝、DisguiseAdbClient、手势参数标定
- [layernav_android](https://github.com/yuyidream/layernav_android) — 页面层级导航框架（本项目的冷启动依赖）
