PrivateFlow — 企微批量群发自动化
> 🏷️ 市场标签: 企业微信 / 自动化 / 群发 / 私域运营 / 跨平台
快速开始（30秒上手）
# 1. 将资料按群名分文件夹
群发资料/
├── 客户群A/ ← 文件夹名=群名
│ ├── 产品手册.pdf
│ └── 内容文字.txt ← 可选，提取文字作消息
└── 客户群B/
└── 报价单.xlsx
# 2. 运行脚本（自动装依赖 + 弹出配置窗口）
python3 scripts/wecom_folder_sender.py --root "/你的/群发/资料"
> ⚠️ 推荐使用方式：本技能最佳运行环境是 WorkBuddy。安装技能后，直接通过 WorkBuddy 对话调用，无需手动处理命令行参数。附带启动器文件（.sh / .bat / .exe）为辅助工具，在不同系统环境下不一定完全有效。
🖥️ 全屏幕尺寸适配
本技能不受屏幕尺寸或分辨率限制。所有 UI 操作坐标通过校准系统动态获取：
- 首次校准：运行
calibrate_gui.py，按弹窗依次点击企微搜索框、搜索结果、输入区 - 坐标持久化：结果保存到
~/.privateflow_coords.json，后续自动加载 - 随时重校准：更换显示器或调整窗口后，点「先校准」即可重新适配
> 13 寸笔记本、27 寸外接屏、4K 显示器，校准一次精准点击，无分辨率限制。
平台兼容性
| 平台 | 状态 | 说明 |
|---|---|---|
| macOS ARM (Apple Silicon) | ✅ 完全可用 | 原生测试通过，校准/群发/停止全流程正常 |
| macOS Intel (x64) | ✅ 支持 | 通过 Rosetta 或原生 Python 运行，流程与 ARM 版一致 |
| Windows 64-bit | ✅ 支持 | pyautogui 实现，自动检测平台切换操作方式 |
> 技能包中包含所有必需文件（calibrate_gui.py、platform_mac.py、platform_win.py），不存在文件缺失问题。校准脚本支持双路径自动查找（同目录 / skill 安装目录），PyInstaller 打包版也能正常运行。
使用注意事项
| 方式 | 说明 |
|---|---|
| WorkBuddy 对话（推荐） | 安装技能后通过对话调用，AI 自动处理路径配置 |
| 命令行直接运行 | python3 wecom_folder_sender.py --root "目录" |
| 启动器文件 | .sh / .bat / .exe 在不同环境下不一定有效 |
双击启动器（零命令行）：
- macOS 用户：双击 PrivateFlow_mac_arm64（Apple Silicon）/ PrivateFlow_run_mac.sh（Intel）
- Windows 用户：双击 PrivateFlow_run_win.bat
核心能力
| 能力 | 说明 |
|---|---|
| 🗂️ 按文件夹群发 | 根目录下每个子文件夹 = 一个目标群，文件夹名 = 群名 |
| 🔍 自动搜索+校验 | OCR 识别搜索结果，精准定位目标群 |
| 📎 文件自动上传 | Finder/资源管理器 → Cmd+A → Cmd+C → Cmd+V |
| ✍️ 自定义消息 | 全局固定文案 / 每个群的「内容文字」文档自动提取 |
| 🛑 随时停止 | 右上角浮窗点停止，当前群发完立即停 |
| 🔧 坐标校准 | 首次使用一键校准，换屏幕也能用 |
| 📊 完整日志 | CSV 日志 + 成功/失败清单 + 每步截图 |
| 🌐 跨平台 | macOS ARM/Intel + Windows 自适应 |
完整执行流程（12步）
[步骤 1] 激活企业微信，移到左上角 → 截图 step01
[步骤 2] 点击搜索框 →
[步骤 3] 清空搜索框 →
[步骤 4] 输入群名 →
[步骤 5] 截图搜索结果区域 → 截图 step05
[步骤 6] OCR 识别，精准定位目标群 →
[步骤 7] 点击进入群聊 → 截图 step07
[步骤 8] 上传文件（Finder复制） →
[步骤 9] 切回企微并粘贴文件 →
[步骤10] 等待上传完成 → 截图 step10
[步骤11] 输入文案 + 按 Enter 发送 → 截图 step12
[步骤12] 截图校验发送结果 → 截图 step13
每步打印 ✅ 状态，失败自动信任模式。
独有特性
📄 内容文档自动提取
文件夹中放任意类型「内容文字」文档（.txt / .md / .docx），自动提取文字作为该群消息，文档本身不发送。
客户群A/
├── 产品手册.pdf
└── 内容文字.txt ← 内容 = "各位客户好，本群最新产品手册已更新"
→ 效果：发送产品手册.pdf + 发送消息「各位客户好，本群最新产品手册已更新」
🛑 随时停止
右上角浮窗随时点「停止」→ 当前群处理完立即停止，不卡死、不残留。
📦 零配置依赖
启动时自动检测缺失依赖（Pillow / pyautogui / pyocr / cliclick），缺什么自动装什么。
🗑️ 自动清理
每轮跑完自动删除临时截图，只保留 CSV 日志。
目录结构
wecom_pc_folder_send/
├── SKILL.md ← 本文档
├── scripts/
│ ├── wecom_folder_sender.py ← 主脚本（跨平台）
│ ├── platform_win.py ← Windows 实现
│ ├── platform_mac.py ← macOS 实现
│ ├── start_gui.py ← 启动配置GUI（含CLI降级）
│ ├── stop_button.py ← 右上角控制面板
│ └── calibrate_gui.py ← 坐标校准向导
├── logs/ ← 日志目录（自动创建）
└── screenshots/ ← 截图目录（自动清理）
配置项
| 配置 | 默认值 | 说明 |
|---|---|---|
| 发送间隔 | 10秒 | 每群完成后等待 |
| 批量暂停 | 每20群停180秒 | 防企微风控 |
| 搜索超时 | 5秒 | 搜索群名等待 |
| 文件上传超时 | 2秒/文件 | 等待文件上传 |
| 文案 | 可空 | 空=只发文件不发文字 |
企微权限要求
- macOS: 系统设置 → 隐私 → 辅助功能 → 勾选「终端」
- Windows: 以管理员身份运行
MCP 集成
本技能配套 MCP Server（private-flow-mcp-server），支持通过对话直接控制：
| MCP 工具 | 功能 |
|---|---|
privateflow_dry_run |
预览目标群清单 |
privateflow_send_batch |
批量群发 |
privateflow_get_status |
查询上次运行日志 |
privateflow_calibrate |
校准UI坐标 |
privateflow_stop |
停止进行中的任务 |
依赖
| 依赖 | 用途 | 安装方式 |
|---|---|---|
| Python 3.10+ | 运行环境 | python.org 下载 |
| Pillow | 图像处理 | pip install Pillow（自动） |
| pyautogui | 鼠标键盘控制 | pip install pyautogui（自动） |
| pyocr | OCR识别 | pip install pyocr（自动） |
| cliclick | macOS点击 | brew install cliclick（自动） |
| tesseract | OCR引擎 | brew install tesseract |
| 企业微信 | 目标应用 | 官网下载 |
能力边界
| 项目 | 限制 | 说明 |
|---|---|---|
| 单文件大小 | ≤ 500MB | 超过可能上传超时或企微拒绝，建议分割大文件 |
| 群数量 | 建议 ≤ 100 | 无限流但过多可能有风控风险；每20群自动暂停 |
| 群名限制 | 不含 <>:"/\|?* |
非法字符会被过滤 |
| 文件夹名=群名 | 必须完全一致 | 支持中文、英文、数字、emoji |
| OCR精度 | 依赖 tesseract | 安装中文语言包可提高识别率 |
常见问题（FAQ）
校准相关
Q: 换了屏幕/外接显示器后怎么办？
A: 在配置窗口点「先校准」重新标定一次坐标即可，30秒搞定。
Q: 校准后坐标没生效？
A: 确认坐标文件 ~/.privateflow_coords.json 存在。若用打包版exe，坐标已迁移到该路径。
Q: 能不能不校准直接用？
A: 不能。首次必须校准，之后永久生效（除非换屏幕/调窗口）。
发送相关
Q: 文件发了两遍？
A: v1.1 已修复此问题。如果仍出现，检查文件夹是否有同名文件。
Q: 企微被限制发送频率了？
A: 修改配置中的发送间隔（默认10秒）和批量暂停间隔（默认每20群停3分钟）。建议加长时间。
Q: 文件太大发不出去？
A: 企微单文件限制约500MB。超过请分割文件，或改用网盘链接。
Q: 能发多少个群？
A: 理论无上限，建议100以内。脚本有自动风控限速防止被封。
错误处理
Q: 弹出英文错误提示？
A: v1.1 已将核心错误信息中文化。如果仍出现英文，是底层系统错误，不影响功能。
Q: 某个群失败了，后续群会继续吗？
A: 会。失败群记录到 error_list.txt，脚本继续处理下一个群，不中断整体流程。
Q: 程序卡住了怎么办？
A: 点右上角浮窗「停止」，当前群处理完立即退出。强制退出可关闭终端窗口。
其他
Q: 能通过对话直接控制吗？
A: 安装 MCP server（private-flow-mcp-server）后，可通过 WorkBuddy 对话调用所有功能。
Q: 用户被限制或验证码怎么办？
A: 目前自动化不处理人机验证。如触发验证码，需要手动通过后再继续。
Q: 能用快捷键替代鼠标点击吗？
A: 所有操作均已使用 Cmd+A/Cmd+C/Cmd+V 快捷键，精确可靠。
版本历史
| 版本 | 日期 | 更新内容 |
|---|---|---|
| v1.1.0 | 2026-06-17 | 跨平台支持(Win/Mac)、内容文档提取、自动依赖安装、启动GUI、停止面板、截图清理、MCP集成、FAQ文档 |
| v1.0.0 | 2026-06-16 | 首版，macOS专用 |
