Metadata-Version: 2.4
Name: mm-friend
Version: 0.1.1
Summary: 脉脉自动加好友工具 - 支持命令行和Web界面
Author-email: Chandler <275737875@qq.com>
License-Expression: MIT
Keywords: maimai,automation,browser,selenium
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: browser-dog>=0.0.1
Requires-Dist: selenium>=4.0.0
Requires-Dist: colorama>=0.4.0
Requires-Dist: typer>=0.9.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"

# mm-friend

脉脉自动加好友工具 - 支持命令行和Web界面两种操作方式

## 功能特性

- ✅ **命令行模式**: 使用Typer实现的简洁CLI接口
- ✅ **Web界面**: 基于FastAPI + Tailwind CSS + Alpine.js的现代化Web界面
- ✅ **批量处理**: 支持批量导入URL,自动随机顺序处理
- ✅ **断点续传**: 本地JSON记录已处理URL,避免重复处理
- ✅ **实时监控**: Web界面实时显示进度、日志和统计信息
- ✅ **错误处理**: 失败URL可重试,详细错误日志记录
- ✅ **防反爬**: 随机延迟,降低被封风险

## 安装

### 从PyPI安装（发布后）

```bash
pip install mm-friend
```


## 使用方法

### 命令行模式

#### 1. 准备文件

确保你有以下文件:
- `cookies.json` - 脉脉登录cookies
- `friends.txt` - 用户URL列表,每行一个

#### 2. 基本用法

```bash
# 使用默认配置
mm-friend run friends.txt

# 指定cookies文件
mm-friend run friends.txt --cookies my_cookies.json

# 启用无头模式
mm-friend run friends.txt --headless

# 完整示例
mm-friend run friends.txt --cookies cookies.json --headless
```

#### 3. 其他命令

```bash
# 查看统计
mm-friend stats

# 清空记录
mm-friend clear

# 查看Web模式帮助
mm-friend web --help
```

### Web界面模式

#### 1. 启动服务

```bash
# 默认端口 8000
mm-friend web

# 指定端口
mm-friend web --port 8080

# 开发模式(热重载)
mm-friend web --reload
```

### Web界面模式

1. 启动Web服务:
```bash
mm-friend web -p 9090
```

#### 2. 访问界面

打开浏览器访问: http://localhost:9090

#### 3. 使用Web界面

1. **配置Cookies**: 
   - 点击"配置Cookies"按钮打开模态框
   - 粘贴浏览器导出的Cookies JSON数据
   - 系统自动校验JSON格式并显示预览
   - 点击"保存到文件"完成配置
2. **输入URL**: 点击"输入URL列表"按钮,在模态框中粘贴多个URL,每行一个
3. **配置选项**: 
   - 查看Cookies配置状态(已配置/未配置)
   - 选择是否启用无头模式
4. **开始任务**: 点击"开始任务"按钮
5. **监控进度**: 
   - 查看实时进度条
   - 查看成功/失败统计
   - 查看当前处理的URL
   - 查看实时日志
6. **查看历史**: 滚动到下方查看处理历史记录
7. **失败重试**: 对失败的记录点击"重试"按钮

## 项目结构

```
mm-friend/
├── mm_friend/
│   ├── __init__.py          # 包初始化
│   ├── core.py              # 核心逻辑: MaimaiConnector类
│   ├── cli.py               # 命令行接口: Typer
│   ├── web.py               # Web应用: FastAPI
│   ├── models.py            # 数据管理: RecordManager
│   └── templates/
│       └── index.html       # Web界面: Alpine.js + Tailwind CSS
├── tests/
│   └── test_core.py         # 测试文件
├── pyproject.toml           # PyPI配置
├── requirements.txt         # 依赖列表
└── README.md                # 项目文档
```

## 技术栈

- **后端框架**: FastAPI
- **命令行工具**: Typer
- **浏览器自动化**: Selenium + browser-dog
- **前端框架**: Alpine.js
- **CSS框架**: Tailwind CSS
- **数据持久化**: JSON文件

## 数据管理

### 记录文件

处理记录保存在 `mm_friend_records.json` 文件中,格式如下:

```json
{
  "https://maimai.cn/user/detail/123": {
    "url": "https://maimai.cn/user/detail/123",
    "status": "success",
    "timestamp": "2026-05-30T10:30:00",
    "error": null,
    "retry_count": 0
  }
}
```

### 状态说明

- `success`: 成功发送好友请求
- `failed`: 处理失败,可查看错误信息
- `processing`: 正在处理中

## 开发指南

### 直接运行Python文件

```bash
# 命令行模式
python -m mm_friend.cli run friends.txt

# Web模式
python -m mm_friend.cli web
```

### 调试模式

系统支持详细的调试日志输出，帮助排查问题：

```bash
# 正常模式（默认）
uvicorn mm_friend.web:app --reload

# 调试模式（详细日志）
MM_FRIEND_DEBUG=true uvicorn mm_friend.web:app --reload
```

**调试模式特性**：
- ✅ 毫秒级时间戳（`15:32:45.123`）
- ✅ 分类标识（ℹ️ INFO / ✅ SUCCESS / ❌ ERROR / 🔍 DEBUG）
- ✅ 处理耗时统计（每个URL的处理时间）
- ✅ 内部状态信息（Cookies验证、WebDriver初始化等）
- ✅ 异常完整堆栈追踪

**日志示例**：
```
15:32:45.123 - INFO - 🚀 开始初始化 MaimaiConnector
15:32:45.125 - INFO - 📋 参数: cookies_file=cookies.json, base_url=https://maimai.cn/, headless=False
15:32:45.130 - INFO - ✅ Cookies文件验证通过: 2048 bytes
15:32:45.135 - INFO - 🔧 创建 BrowserDog 实例...
15:32:47.250 - INFO - ✅ MaimaiConnector 初始化完成 (耗时: 2.12s)
```

**日志位置**：
- **控制台**: 实时显示，带分类标识
- **log.txt**: 完整日志文件，毫秒级时间戳

### 运行测试

```bash
pytest tests/ -v
```

### 代码格式化

```bash
black mm_friend/
```

### 代码检查

```bash
flake8 mm_friend/
```

## 发布到PyPI

```bash
# 安装构建工具
pip install build twine

# 构建包
python -m build

# 上传到PyPI
twine upload dist/*
```

## 常见问题

### Q: cookies文件在哪里?
A: 需要从浏览器导出脉脉的登录cookies,保存为JSON格式。

### Q: URL文件格式?
A: 每行一个完整的脉脉用户URL,例如:
```
https://maimai.cn/user/detail/123456
https://maimai.cn/user/detail/789012
```

### Q: 如何避免被封?
A: 
- 使用随机延迟(已内置)
- 控制每日发送数量
- 不要过于频繁使用

### Q: 断点续传怎么用?
A: 自动生效!处理记录保存在`mm_friend_records.json`,再次运行会自动跳过已成功的URL。

### Q: 启动任务后无响应怎么办?
A: 启用调试模式查看详细日志:
```bash
MM_FRIEND_DEBUG=true uvicorn mm_friend.web:app --reload
```
然后查看`log.txt`文件定位问题:
```bash
tail -f log.txt
```
常见原因:
- Cookies文件不存在 → 检查cookies.json
- WebDriver获取失败 → 安装ChromeDriver
- BrowserDog创建失败 → 重装browser-dog

### Q: 如何查看详细的处理日志?
A: 系统提供两种日志:
- **控制台日志**: 带分类标识（ℹ️ INFO / ✅ SUCCESS / ❌ ERROR）
- **log.txt文件**: 毫秒级时间戳，包含完整处理流程和耗时统计

## 文件说明

- `mm_friend_records.json` - 处理记录(自动生成)
- `log_email.txt` - 运行日志(自动生成)
- `mm_friend/` - 核心代码
  - `core.py` - 浏览器自动化逻辑
  - `cli.py` - 命令行接口
  - `web.py` - Web服务
  - `models.py` - 数据管理
  - `templates/index.html` - Web界面

## 免责声明

⚠️ **重要声明**: 

1. **仅供学习参考**: 本项目仅用于技术学习和研究目的,旨在演示浏览器自动化、Web开发等相关技术
2. **使用者责任**: 使用本工具所产生的任何后果由使用者自行承担,项目开发者不承担任何连带责任
3. **遵守平台规则**: 使用者必须严格遵守脉脉平台的使用条款、服务协议及相关法律法规
4. **禁止滥用**: 严禁将本工具用于任何违法违规活动,包括但不限于:
   - 发送垃圾信息
   - 恶意骚扰他人
   - 窃取用户数据
   - 破坏平台正常秩序
5. **风险提示**: 使用自动化工具可能违反平台服务条款,存在账号被封禁的风险,使用者需自行评估和承担相关风险
6. **合法使用**: 如将本工具用于商业用途或其他用途,请确保已获得相关授权和许可

**使用本工具即表示您已阅读、理解并同意遵守以上所有条款。**

## 注意事项

⚠️ **使用建议**:

1. 请合理使用,遵守脉脉平台的使用条款
2. 建议控制发送频率,避免触发反爬机制
3. 确保cookies文件有效且未过期
4. 无头模式适合服务器环境,调试时建议关闭无头模式
5. 建议在测试环境中先验证功能,再用于生产环境

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request!

## 更新日志

### v0.1.0 (2026-05-30)

- ✨ 初始版本发布
- ✨ 支持命令行和Web界面
- ✨ 实现批量处理和断点续传
- ✨ 添加实时监控和日志功能
