mm-friend 0.1.1

脉脉自动加好友工具 - 支持命令行和Web界面

mm-friend

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

功能特性

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

安装

从PyPI安装（发布后）

pip install mm-friend

使用方法

命令行模式

1. 准备文件

确保你有以下文件:

• cookies.json - 脉脉登录cookies
• friends.txt - 用户URL列表,每行一个

2. 基本用法

# 使用默认配置
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. 其他命令

# 查看统计
mm-friend stats

# 清空记录
mm-friend clear

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

Web界面模式

1. 启动服务

# 默认端口 8000
mm-friend web

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

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

Web界面模式

1. 启动Web服务:

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 文件中,格式如下:

{
  "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文件

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

# Web模式
python -m mm_friend.cli web

调试模式

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

# 正常模式（默认）
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: 完整日志文件，毫秒级时间戳

运行测试

pytest tests/ -v

代码格式化

black mm_friend/

代码检查

flake8 mm_friend/

发布到PyPI

# 安装构建工具
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: 启用调试模式查看详细日志:

MM_FRIEND_DEBUG=true uvicorn mm_friend.web:app --reload

然后查看log.txt文件定位问题:

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界面
• ✨ 实现批量处理和断点续传
• ✨ 添加实时监控和日志功能