Metadata-Version: 2.4
Name: mm-auto
Version: 0.1.0
Summary: 基于 DrissionPage 的脉脉(maimai.cn)自动化工具包：企业搜索、加好友、发消息
Author: Chandler
License: MIT
Keywords: maimai,automation,drissionpage,browser,cli,typer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: DrissionPage>=4.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: requests>=2.28.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# mm-auto

> 基于 [DrissionPage](https://github.com/g1879/DrissionPage) 的脉脉（maimai.cn）自动化工具包。

`mm-auto` 把「打开浏览器 → 人工登录 → 企业搜索 → 加好友 → 发消息」这一整套重复劳动，封装成了一个 **既能命令行调用、也能当作 Python 库导入** 的工具包。它最大的特点是：**复用同一个 Chrome 浏览器**，登录一次、长期有效，后续脚本直接"接管"而不必反复扫码/输验证码。

---

## 目录

- [它能做什么](#它能做什么)
- [安装](#安装)
- [30 秒快速开始](#30-秒快速开始)
- [命令行用法](#命令行用法)
- [Python 函数用法](#python-函数用法)
- [示例脚本](#示例脚本)
- [配置说明](#配置说明)
- [项目结构](#项目结构)
- [如何扩展](#如何扩展)
- [核心原理解释](#核心原理解释)
- [常见问题](#常见问题)
- [许可证](#许可证)

---

## 它能做什么

| 能力 | 说明 |
| --- | --- |
| **浏览器复用** | 首次启动 Chrome，之后直接接管，登录态、标签页全保留 |
| **人工登录** | 打开登录页挂起，等你扫码/输验证码，登录后回车继续 |
| **登录校验** | 自动访问需要登录的页面，判断是否被弹回登录页 |
| **企业搜索** | 按关键词搜索公司，收集公司主页链接，保存为 `companies.json` |
| **人才搜索** | 人才银行自定义搜索：关键词 + 城市/学历/年限/性别/年龄/月薪等 12 个筛选器，收集人才卡片，保存为 `talents.json` |
| **员工收集** | 打开公司主页，自动展开员工列表，收集用户主页链接 |
| **加好友** | 打开用户主页 → 点「加好友」→ 自动填验证消息 → 提交 |
| **发消息** | 两种姿势：用户主页「打招呼」；网页聊天里按联系人名字发送 |
| **一键流水线** | 搜索企业 → 取员工 → 逐个加好友+发消息，支持断点续跑 |
| **频率控制** | 每次操作之间可配置间隔秒数，降低风控风险 |

---

## 安装

直接使用 pip 安装：

```bash
pip install mm-auto
```

> 依赖会自动安装：`DrissionPage`、`typer`、`requests`。安装完成后，`mm-auto` 命令即可在终端使用。

---

## 30 秒快速开始

**第一步：登录一次（只需做一次）**

```bash
mm-auto login
```

程序会自动启动一个 Chrome 浏览器，停在脉脉登录页。你在浏览器里完成登录（扫码或手机号验证码），页面跳转后，回到终端按 **回车**。

> 关掉终端也没关系——浏览器会保留，登录态也在。

**第二步：搜索企业（看看能找到谁）**

```bash
mm-auto search --keyword 字节跳动
```

它会自动：搜索 → 切到「公司」筛选 → 打印公司列表 → 保存到 `output/companies.json`。

**第三步：一键任务（搜索 → 加好友 → 发消息）**

```bash
mm-auto run --keyword 字节跳动 --max-members 10 --delay 10
```

它会自动：搜索企业 → 进入公司页收集员工 → 逐个打开员工主页加好友+打招呼 → 每人之间歇 10 秒。中途断了？重新跑同一条命令即可，**已处理过的人会自动跳过**（断点续跑）。

就这么简单。

---

## 命令行用法

所有命令都带 `--help`，随时查看：

```bash
mm-auto --help
mm-auto login --help
```

### `login` — 登录

```bash
mm-auto login
mm-auto login --no-verify        # 登录后不做自动校验
```

### `verify` — 校验登录态

```bash
mm-auto verify
```

成功（未被弹回登录页）退出码为 `0`，失败为 `1`，方便写脚本判断。

### `search` — 企业搜索

```bash
mm-auto search --keyword 字节跳动
mm-auto search --keyword 字节跳动 --limit 30 --no-save
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--keyword / -k` | 公司关键词（必填） | — |
| `--limit` | 最多收集多少家公司 | `20` |
| `--save/--no-save` | 是否保存 `companies.json` | 保存 |

### `talents-search` — 人才银行搜索（自定义条件找人）

在企业版「人才银行」页面按**关键词 + 多个筛选条件**搜索人才，收集姓名和主页链接，保存为 `talents.json`。**前提：企业招聘账号且已开通人才银行功能。**

```bash
# 关键词 + 城市多选 + 性别 + 年龄区间 + 月薪区间
mm-auto talents-search -k Python --city 广东 --city 深圳 --gender 女 --age-min 25 --age-max 35 --salary-min 20

# 智能筛选：搜索结果出来后勾选左侧栏复选项（可多次传）
mm-auto talents-search -k Python --smart 公开求职意向 --smart 有附件简历

# JSON 配置方式（字段见 examples/talent_config.json，命令行参数可覆盖同名字段）
mm-auto talents-search --config talent_config.json
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--keyword / -k` | 搜索关键词（如「Python」） | 空 |
| `--config` | JSON 配置文件，优先级低于命令行参数 | 空 |
| `--city` | 城市地区，可多次传（cascade 多选） | 空 |
| `--degree` | 学历要求（如 `本科及以上`/`硕士及以上`/`博士`） | 空 |
| `--experience` | 工作年限（如 `3-5年`/`在校`/`应届`） | 空 |
| `--company` | 就职公司，可多次传（面板内搜索匹配） | 空 |
| `--position` | 职位名称（如 `后端开发`） | 空 |
| `--ai-type` | AI 人才类型 | 空 |
| `--school` | 毕业学校 | 空 |
| `--major` | 专业 | 空 |
| `--gender` | 性别（`男`/`女`） | 空 |
| `--age-min / --age-max` | 年龄区间 | 空 |
| `--salary-min / --salary-max` | 期望月薪区间（单位 k，如 `20` = 20K） | 空 |
| `--hometown` | 家乡，可多次传 | 空 |
| `--smart` | 智能筛选（结果左侧栏复选项，可多次传）：`公开求职意向`/`近期有动向`/`有附件简历`/`有过意向`/`企业号互动`/`近期未查看`/`近期未沟通` | 空 |
| `--limit` | 最多收集多少条结果 | `30` |
| `--save/--no-save` | 是否保存 `talents.json` | 保存 |

筛选值必须是页面上真实存在的选项文案（比如学历传「本科及以上」，而不是「本科」），拿不准时先在浏览器里手动点开筛选面板看一眼。**注意：「行业方向」筛选器是特殊组件，暂不支持。**

关键词的工作方式：输入到筛选区 placeholder 为「搜索提示：输入带双引号的完整词组…」的输入框，**输入后自动按回车提交**，然后再叠加筛选条件、点击「搜索」。页面顶部的「搜人才」框是另一套搜索 UI，与本命令无关。关键词失效时用 `python scripts/debug_talents.py --keyword Python` 排查。

智能筛选（`--smart`）的工作方式：**先有搜索结果**，页面才会渲染左侧栏「智能筛选」勾选区，所以 `--smart` 必须与 `-k` 或其他筛选条件搭配使用（无结果时勾选项不存在）。勾选直接触发异步搜索，无需再点搜索按钮。链路失效时用 `python scripts/debug_talents.py --smart 公开求职意向` 排查（见 FAQ Q8）。

### `members` — 获取某公司的员工列表

```bash
mm-auto members --keyword 字节跳动                  # 先搜索取第一家
mm-auto members --company-url https://maimai.cn/web/company/xxx
```

结果会打印并保存为 `members.json`（姓名 + 用户主页地址）。

### `add-friend` — 加好友

```bash
# 给单个用户加好友
mm-auto add-friend --profile-url https://maimai.cn/u/xxx --note "你好，希望认识一下"

# 按公司批量：先搜索「字节跳动」取第一家，给前 10 位员工发申请，每人间隔 8 秒
mm-auto add-friend --keyword 字节跳动 --limit 10 --delay 8
mm-auto add-friend --company-url https://maimai.cn/web/company/xxx --limit 10
```

返回状态说明：`sent`（已提交）/ `already`（已是好友或已申请过，自动跳过）/ `not_found`（页面上没有加好友按钮）/ `failed`（提交失败）。

### `greet` — 发消息（打招呼）

```bash
# 给单个用户打招呼
mm-auto greet --profile-url https://maimai.cn/u/xxx --message "你好，想和你交流一下"

# 按公司批量打招呼
mm-auto greet --keyword 字节跳动 --message "你好，想和你交流一下" --delay 8
```

不传 `--message` 时使用默认招呼语（见配置说明）。

### `message` — 在网页聊天里给联系人发消息

```bash
mm-auto message --contact 张三 --text "在吗？方便聊聊吗"
```

适合给**已是好友 / 已有会话**的人发消息：打开 `maimai.cn/chat` → 搜索联系人 → 打开会话 → 发送。

### `identify` — 调试：识别页面元素

页面改版导致定位不到元素时，用它看看当前页面有哪些输入框（placeholder）、按钮（文案）、用户/公司链接：

```bash
mm-auto identify                                # 分析当前浏览器停留的页面
mm-auto identify --url https://maimai.cn/web/company/xxx
```

### `run` — 一键任务

```bash
# 方式一：直接传参
mm-auto run --keyword 字节跳动 --max-members 20 --delay 10

# 方式二：JSON 配置
mm-auto run --config ./mm_config.json
```

`mm_config.json` 字段（与 `examples/mm_config.json` 相同，值留空则用默认）：

```json
{
  "keyword": "字节跳动",
  "note": "好友申请的验证消息",
  "message": "打招呼的消息内容",
  "max_members": 10,
  "company_index": 0,
  "delay": 10
}
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--skip-friend` | 只发消息，不重复加好友 | 关 |
| `--skip-message` | 只加好友，不发消息 | 关 |
| `--reset` | 清空断点记录，从头处理 | 关 |

### 公共参数

以下参数对所有命令生效：

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--port` | Chrome 调试端口 | `46518` |
| `--chrome` | Chrome 可执行文件路径 | 系统默认路径 |
| `--user-data` | Chrome 用户数据目录 | `~/.mm_auto/chrome_profile` |
| `--save-dir` | 输出/进度目录 | `~/.mm_auto/output` |

---

## Python 函数用法

### 最简示例

```python
from mm_auto import AppConfig, BrowserManager, CompanySearch

cfg = AppConfig(save_dir="./output")          # 可选，覆盖默认配置
page = BrowserManager(cfg).get_page()         # 接管浏览器
tab = CompanySearch(cfg).search(page, "字节跳动")
for c in CompanySearch(cfg).get_company_links(tab, limit=10):
    print(c.name, c.url)
```

### 完整业务流程

```python
from mm_auto import (
    AppConfig, BrowserManager, LoginFlow,
    CompanySearch, FriendFlow, Messenger, ProgressStore,
)

cfg = AppConfig(save_dir="./output")
manager = BrowserManager(cfg)

# 1. 登录（首次需要人工扫码）
page = manager.get_page()
flow = LoginFlow()
if not flow.verify(page):
    page = flow.open_login(manager)
    flow.wait_manual_login(page)

# 2. 企业搜索，取第一家
searcher = CompanySearch(cfg)
tab = searcher.search(page, "字节跳动")
companies = searcher.get_company_links(tab, limit=5)
company = companies[0]
print(f"选定公司: {company.name} {company.url}")

# 3. 收集员工 → 逐个加好友 + 打招呼（断点续跑）
members = searcher.get_member_links(page, company.url, limit=10)
friend_flow = FriendFlow(cfg)
messenger = Messenger(cfg)
store = ProgressStore(cfg.progress_file)

for m in members:
    if store.has(m.url):
        continue
    print(m.name, friend_flow.add_friend(page, m.url, note="你好，希望认识一下"))
    print(m.name, messenger.greet(page, m.url, text="你好，想和你交流一下"))
    store.mark(m.url, "done")
```

### 人才搜索（关键词 + 筛选器 + 收集结果）

```python
from mm_auto import AppConfig, BrowserManager, LoginFlow, TalentQuery, TalentSearch

cfg = AppConfig(save_dir="./output")
page = BrowserManager(cfg).get_page()
if not LoginFlow().verify(page):
    raise SystemExit("登录态无效，请先执行 mm-auto login")

query = TalentQuery(
    keyword="Python",
    filters={
        "city": ["广东", "深圳"],          # cascade 型：可多选
        "gender": "女",                    # select 型：单选文案
        "age": {"min": 25, "max": 35},     # range 型：区间
        "salary": {"min": 20},             # 期望月薪下限 20K
        "degree": "本科及以上",
        "company": ["字节跳动"],           # search_pick 型：面板内搜索
    },
)

ts = TalentSearch(cfg)
result = ts.search(page, query)        # 打开页面 → 填条件 → 点搜索
print(result["url"])                   # 搜索后的 URL（带 query 参数）
print(result["filters"])               # 各筛选器是否设置成功
print(result["conditions"])            # 各筛选器标题当前显示的文本

from mm_auto import SearchResultFilter

srf = SearchResultFilter(cfg)
print(srf.get_states(page))                    # 7 个勾选项的当前状态
srf.apply(page, ["job_intention", "有附件简历"])  # 勾选（英文标识或中文文案均可）
for p in ts.collect_profiles(page, limit=20):
    print(p.name, p.url, p.raw_text[:50])
```

### 给好友发会话消息

```python
from mm_auto import AppConfig, BrowserManager, Messenger

cfg = AppConfig()
page = BrowserManager(cfg).get_page()
ok = Messenger(cfg).send_in_chat(page, contact="张三", text="在吗？")
print("发送成功" if ok else "发送失败")
```

### 异常处理

所有异常继承自 `mm_auto.exceptions.MmAutoError`，可以统一捕获：

```python
from mm_auto import BrowserManager, AppConfig
from mm_auto.exceptions import BrowserLaunchError, LoginExpiredError

try:
    page = BrowserManager(AppConfig()).get_page()
except BrowserLaunchError:
    print("Chrome 启动失败，检查路径配置")
except LoginExpiredError:
    print("登录态失效，请重新登录")
```

---

## 示例脚本

`examples/` 目录下提供了可直接运行的示例：

| 脚本 | 说明 | 运行 |
| --- | --- | --- |
| `quickstart.py` | 接管浏览器，搜索企业并打印前 10 家 | `python examples/quickstart.py` |
| `login_demo.py` | 打开登录页 → 人工登录 → 校验 | `python examples/login_demo.py` |
| `run_pipeline.py` | 完整流水线（搜索→加好友→发消息） | `python examples/run_pipeline.py` |
| `talent_search_demo.py` | 人才银行自定义搜索（关键词+筛选器+收集） | `python examples/talent_search_demo.py` |
| `mm_config.json` | `run --config` 的配置示例 | — |
| `talent_config.json` | `talents-search --config` 的配置示例 | — |

所有示例都假设你已安装 mm-auto，并（如需登录）先用 `mm-auto login` 完成过一次登录。

---

## 配置说明

三种配置方式，优先级从高到低：

### 1. 代码里直接传参

```python
cfg = AppConfig(
    debug_port=46518,
    chrome_exe=r"D:\Chrome\chrome.exe",
    user_data=r"D:\chrome_profile\mm",
    save_dir="./output",
    default_note="你好，希望认识一下！",
    action_timeout=8.0,
)
```

### 2. 环境变量（前缀 `MM_AUTO_`）

```powershell
# Windows (PowerShell)
$env:MM_AUTO_CHROME_EXE = "D:\Chrome\chrome.exe"
$env:MM_AUTO_DEBUG_PORT = "46518"
$env:MM_AUTO_SAVE_DIR = "D:\mm_output"
```

```python
cfg = AppConfig.from_env()   # 自动读取上述环境变量
```

支持的环境变量：`MM_AUTO_DEBUG_PORT`、`MM_AUTO_USER_DATA`、`MM_AUTO_CHROME_EXE`、`MM_AUTO_DATA_DIR`、`MM_AUTO_SAVE_DIR`、`MM_AUTO_DEFAULT_NOTE`、`MM_AUTO_ACTION_TIMEOUT`、`MM_AUTO_PAGE_SETTLE`。

### 3. 命令行参数

```bash
mm-auto search --chrome "D:\Chrome\chrome.exe" --save-dir ./output --keyword 字节跳动
```

### 配置文件位置

| 文件 | 路径 |
| --- | --- |
| 会话记录（自动生成） | `~/.mm_auto/mm_session.json` |
| 公司清单 | `~/.mm_auto/output/companies.json` |
| 员工清单 | `~/.mm_auto/output/members.json` |
| 人才清单 | `~/.mm_auto/output/talents.json` |
| 断点进度 | `~/.mm_auto/output/progress.json` |

---

## 项目结构

采用 **src 布局**，把"易变的选择器/URL"和"稳定的业务逻辑"分离开来：

```
mm-auto/
├── pyproject.toml              # 打包与依赖配置
├── README.md
├── LICENSE
├── examples/                   # 可运行的示例脚本
│   ├── quickstart.py
│   ├── login_demo.py
│   ├── run_pipeline.py
│   ├── talent_search_demo.py
│   ├── mm_config.json
│   └── talent_config.json
├── scripts/
│   └── debug_talents.py        # 人才搜索页排查工具（筛选器失效时用）
├── tests/                      # 单元测试
│   ├── test_config.py
│   ├── test_constants.py
│   ├── test_store.py
│   ├── test_talent_search.py
│   └── test_cli_talents.py
└── src/
    └── mm_auto/
        ├── __init__.py         # 导出公共 API
        ├── __main__.py         # 支持 python -m mm_auto
        ├── cli.py              # Typer 命令入口（只做分发，无业务逻辑）
        ├── config.py           # 统一配置 AppConfig
        ├── constants.py        # URL、选择器、按钮文案等常量
        ├── exceptions.py       # 异常体系
        └── core/
            ├── browser.py      # 浏览器复用管理器
            ├── login.py        # 人工登录与校验
            ├── locator.py      # 共享的元素定位工具
            ├── search.py       # 企业搜索与员工收集
            ├── talent_search.py # 人才银行搜索（4 种筛选器交互）
            ├── friend.py       # 加好友
            ├── messenger.py    # 发消息
            └── store.py        # 断点续跑存储
```

**分层原则（高内聚、低耦合）：**

- `core/` 每个模块只做一件事，彼此**不相互 import**，只共享 `config`、`constants` 和 `locator`。
- 业务逻辑都通过 `page` 对象参数传递，而不是在模块内部偷偷创建浏览器。
- 选择器、URL、按钮文案集中放在 `constants.py`；页面改版时**只改这一处**。
- `cli.py` 只是一层薄薄的"翻译"，把命令行参数转成对 `core` 的调用。

---

## 如何扩展

### 场景 1：页面改版，选择器失效

打开 `src/mm_auto/constants.py`，修改对应的候选列表即可。例如「加好友」按钮文案变了，改 `ADD_FRIEND_TEXTS`：

```python
ADD_FRIEND_TEXTS = ["加好友", "加为好友", "认识一下", "交换名片", "新按钮文案"]
```

多个候选会按顺序尝试，第一个命中且可见的生效。拿不准页面上有什么时，先跑：

```bash
mm-auto identify --url <出问题的页面地址>
```

它会打印当前页所有输入框的 placeholder、按钮文案、能匹配到的用户/公司链接，照着补进 constants.py 即可。

人才搜索页的筛选器失效（`talents-search` 输出里某项 `[FAILED]`）时，用专门排查工具 `scripts/debug_talents.py` 逐步打印交互过程：

```bash
python scripts/debug_talents.py --list                          # 列出 12 个筛选器当前状态
python scripts/debug_talents.py --panel 城市地区                # dump 某筛选器的面板选项结构
python scripts/debug_talents.py --pick 性别 女                  # 尝试设置一个值看结果
python scripts/debug_talents.py --range 年龄 --min 25 --max 35  # 排查 range 型虚拟列表选值
python scripts/debug_talents.py --keyword Python                # 排查关键词输入+回车链路
python scripts/debug_talents.py --smart 公开求职意向            # 排查智能筛选勾选链路
```

### 场景 2：公司/用户链接的正则匹配不上

`mm-auto identify` 的输出里会列出页面上能匹配到的链接示例。如果链接格式变了（比如用户主页不再是 `/u/xxx`），在 `constants.py` 里加一条正则：

```python
USER_LINK_PATTERNS = [
    re.compile(r"maimai\.cn/u/([\w-]+)"),
    re.compile(r"maimai\.cn/web/profile/([\w-]+)"),
    re.compile(r"maimai\.cn/web/新路径/([\w-]+)"),   # 新增候选
]
```

### 场景 3：新增一条命令

在 `cli.py` 里用 `@app.command()` 加一个函数，内部调用 `core` 即可：

```python
@app.command()
def export_all(
    keyword: str = typer.Option(..., "--keyword", "-k"),
    max_members: int = typer.Option(50, "--max-members"),
):
    """导出某公司全部员工。"""
    cfg = _build_config(...)
    page = BrowserManager(cfg).get_page()
    searcher = CompanySearch(cfg)
    tab = searcher.search(page, keyword)
    # ... 调用 core 完成逻辑
```

### 场景 4：把流程接进更大的系统

不要用 CLI，直接 `import mm_auto`，像「Python 函数用法」里那样组装 `BrowserManager` / `CompanySearch` / `FriendFlow` / `Messenger`，完全自由。

---

## 核心原理解释

> 这一节用大白话讲清楚「为什么这样设计」，方便你判断和二次开发。

### 1. 为什么要"复用浏览器"而不是每次都开新的？

常规自动化（比如 Selenium）每次运行都开一个"干净"的新浏览器，没有登录、没有历史，于是每次都得重新登录。脉脉登录很麻烦（要扫码或手机验证码）。

`mm-auto` 的做法是：**用一个固定的 Chrome + 固定的调试端口（46518）启动一次**。以后再运行，先去这个端口"敲门"（发个 HTTP 请求探测），如果浏览器还活着，就直接**接管**它——相当于你回到之前那个已经登录好的浏览器继续操作。于是登录一次，长期有效。

### 2. 什么是"接管"？它和"打开"有什么区别？

- **打开**：`subprocess` 拉起 Chrome 进程，带 `--remote-debugging-port=46518` 参数，告诉 Chrome「给我留一个 46518 端口的遥控接口」。
- **接管**：DrissionPage 通过 `set_local_port(46518)` 连上这个已经存在的遥控接口，而不是新建浏览器。

两者的差别就像：

> 「打开」= 买一台新手机并开机；「接管」= 拿起你桌子上那台已经登录好的手机继续用。

### 3. 为什么按钮用"文字"定位，而不是 id / class？

脉脉是 React 单页应用，前端框架自动生成的 `id`（如 `rc_select_1`）和带哈希后缀的 class，产品一改版就变。而「加好友」「打招呼」「发送」这些是产品经理写死的文案，相对稳定得多。所以所有按钮都按**文案候选列表**查找，输入框按 **placeholder 模糊匹配**查找——都比 class 抗改版。

### 4. 为什么每个"要找的东西"都配一串候选？

就像开门时兜里揣了好几把钥匙，一把一把试：第一个能找到且可见的就用。页面改版时只需要往候选列表里加新钥匙，老用户不受影响。

### 5. 为什么每次操作之间要 sleep，还要 `--delay`？

脉脉对陌生人「打招呼 / 加好友」有**每日次数限制**（普通账号每天只有几次，会员更多），操作过快、过密会触发风控，轻则限流、重则封号。所以：

1. 打开新页面后等 SPA 渲染完（`page_settle`）；
2. 找元素带超时轮询，而不是点击后立刻断言；
3. 每处理一个人之间强制休息（`--delay`，默认 8~10 秒）。

这不是"慢"，这是"活得更久"。建议每天总量控制在个位数到两位数，把它当"助理"而不是"机器"。

### 6. 断点续跑是怎么实现的？

每处理完一个人，就把 TA 的主页地址写进 `progress.json`（状态 + 时间戳）。下次运行时先读这个文件，**已处理过的直接跳过**。中途断电、报错、登录失效都不怕——重新跑同一条命令，会从断点继续。想从头再来？加 `--reset`，或删掉 `output/progress.json`。

---

## 常见问题

**Q1：提示 `Chrome 启动失败`？**

检查 `--chrome` 和 `--user-data` 两个路径。`chrome_exe` 默认是 `C:\Program Files\Google\Chrome\Application\chrome.exe`（不存在时会自动探测常见安装位置），`user_data` 默认是 `~/.mm_auto/chrome_profile`。注意：`user_data` 目录不能被另一个 Chrome 实例占用，且必须位于真实存在的磁盘上（比如机器没有 D 盘就别指定 `D:\...`）。

**Q2：运行时把浏览器也一起关了？**

不要调用页面的 `quit()`。本包所有接口都不会主动关闭浏览器，接管只是"借用"，退出脚本后浏览器仍然保留。

**Q3：登录态失效怎么办？**

重新 `mm-auto login` 登录一次即可。也可以 `mm-auto verify` 先探测一下当前是否还生效。

**Q4：加好友返回 `not_found`？**

说明用户主页上没有出现候选文案里的「加好友」按钮：可能是按钮文案改版、该用户不开放申请、或者账号无权限（部分功能需要脉脉会员）。先跑 `mm-auto identify --url <该用户主页>`，看看页面上实际的按钮文案，补进 `constants.ADD_FRIEND_TEXTS`。

**Q5：搜到 0 家公司 / 0 位员工？**

大概率是链接正则与最新页面不匹配。跑 `mm-auto identify`，把输出里「用户链接 / 公司链接」一节的实际 URL 格式对照 `constants.py` 里的正则，补一条新候选即可。

**Q6：怎么自定义打招呼的话术？**

- 命令行：`--note`（好友申请附言）、`--message`（打招呼内容）；
- 配置：`AppConfig(default_note=...)` 或环境变量 `MM_AUTO_DEFAULT_NOTE`；
- 一键任务：写在 `mm_config.json` 的 `note` / `message` 字段。

**Q7：`talents-search` 里某个筛选器显示 `[FAILED]`？**

常见原因：① 筛选值文案与页面选项不一致（如学历传「本科」而页面选项是「本科及以上」）；② 页面改版导致筛选器 DOM 结构变化。排查方法：命令行输出里 `[FAILED]` 之外还会打印各筛选器标题的当前文本（如 `city: 城市地区`），对照浏览器里手动点开该筛选器看到的真实选项文案。若确认文案没问题，则可能是改版，参照 `constants.py` 里 `TALENT_FILTERS` 和 `TALENT_*` 系列常量调整选择器。

**Q8：智能筛选（`--smart`）勾选了但结果数没变化？**

按顺序排查：

1. **先确认有搜索结果**——智能筛选区只在有结果后才渲染，`--smart` 必须与 `-k` 或其他筛选条件搭配；否则会报「找不到智能筛选项」。
2. **勾选是否成功**——看命令行输出里该项是 `OK` 还是 `FAILED`；`OK` 说明复选框状态已切换（勾选本身生效），勾选会自动触发异步搜索、无需点搜索按钮。
3. **该筛选对当前结果本来就可能无影响**——比如候选人都没被查看过，「近期未查看」勾选前后结果数不变是正常的（此时全部保留）。
4. **可能触发了反自动化风控**——勾选触发的搜索请求走 `anti_automation` 接口，同一天高频自动化操作后，服务端可能返回未过滤结果（现象：勾选 `OK` 但任何项的结果数都不变）。这是服务端行为而非工具缺陷，降低频率或隔一段时间再用即可恢复。

链路排查用 `python scripts/debug_talents.py --smart 公开求职意向`，它会逐步打印勾选前后的 7 项状态和真实卡片数（已排除侧栏「立即沟通券」的干扰）。

**Q9：人才搜索需要什么账号？**

人才银行（`maimai.cn/ent/v41/recruit/talents`）是脉脉企业招聘功能，需要**企业招聘账号**且开通了人才银行权限。普通账号访问会被重定向到登录页/无权限页。

**Q10：每天最多能加多少人？**

取决于你的账号等级，工具不做硬限制。请自行控制 `--limit` 与 `--delay`，并遵守脉脉平台规则。**宁可少而慢，不要多而快。**

---

## 许可证

[MIT](./LICENSE)

---

## 免责声明

> 在使用本项目（下称「本工具」）之前，请务必仔细阅读并充分理解本声明的全部内容。一旦下载、安装、运行或以任何方式使用本工具，即视为你已同意并接受本声明的全部条款。

### 一、使用目的

本工具仅供**学习、研究及技术交流**使用，旨在演示浏览器自动化、页面元素定位等编程技术。本工具**不提供、不鼓励、不协助**任何针对脉脉平台（maimai.cn）或其他任何网站进行的批量营销、垃圾消息、数据采集、账号滥用或规避反爬/风控机制等行为。

### 二、合规与授权

1. 使用本工具不得违反《中华人民共和国网络安全法》《中华人民共和国数据安全法》《中华人民共和国个人信息保护法》以及目标网站所在地的其他适用法律法规。
2. 你应当自行查阅并严格遵守脉脉平台的服务条款、用户协议、隐私政策及 robots 协议等平台规定，并**自行取得**使用相关数据的合法授权与许可。
3. 本工具不用于：批量加好友、群发消息、采集或存储他人个人信息、绕过验证码或登录保护、干扰平台正常服务，或其他任何可能损害第三方合法权益的用途。
4. 脉脉对陌生人打招呼 / 好友申请有严格的频率与配额限制，请自觉控制使用频率与总量。

### 三、风险自负

1. **账号风险**：高频使用可能导致你的脉脉账号被限流、限制功能、封禁，或在法律层面被追究责任。此类风险及后果**完全由使用者自行承担**。
2. **法律风险**：因使用本工具产生的任何民事、行政、刑事责任，均由使用者自行承担。
3. **数据风险**：本工具生成或导出的数据可能存在不准确、不完整、过期等情况，作者不对数据的真实性、准确性与可用性作出任何保证。

### 四、责任免除

本项目按「现状（AS IS）」提供，作者**不作任何明示或暗示的保证**，包括但不限于对适销性、特定用途适用性、不侵权及持续可用性的保证。在适用法律允许的最大范围内，因安装、使用或无法使用本工具而造成的任何直接、间接、偶然、附带、特殊或后果性损失（包括但不限于数据丢失、账号封禁、利润损失、业务中断、行政处罚、诉讼及赔偿责任），作者及贡献者**均不承担任何责任**，即使已被告知发生此类损失的可能性。

### 五、其他

使用者应独立判断本工具的适用性，并对其使用行为负全部责任。若本声明的任何条款被认定无效或不可执行，不影响其余条款的效力。本声明的解释权及适用以中华人民共和国法律为准。
