[Python] 基于Python与MediaPipe的办公防偷窥工具：自动检测多人人脸并切换工作窗口

Moyu 是一款轻量级、跨平台（支持 Windows 和 macOS）的桌面应用，旨在为开放式办公环境提供隐私保护。它能实时监测摄像头画面，一旦检测到多张人脸（默认2人及以上），便会自动切换到您预设的工作软件（如 IDE），并抓拍当前画面留证，有效防范来自背后的“屏幕窥视”。

核心功能

• 高精度多人脸检测：核心基于 Google MediaPipe 实现稳定、高效的人脸识别，支持多帧连续判断以减少误报，默认仅在检测到多人同屏时触发警报。
• 实时预览与提示：提供可自由移动、缩放的前置预览窗口，当检测到符合条件的人脸时，窗口会显示醒目的提示文字。
• 自动切换工作应用：触发后，程序会根据您的配置，自动激活并前置如 VSCode、IntelliJ IDEA 等指定的工作软件窗口，营造“正在专注工作”的假象。
• 现场抓拍留证：警报触发瞬间，自动保存当前摄像头画面到指定目录，为可能的纠纷提供证据。
• 托盘静默运行：支持最小化到系统托盘后台运行，触发时通过托盘气泡进行通知（默认显示8秒，支持5-10秒范围设置后自动收起），兼顾提醒与低调。

快速开始

环境准备

该项目使用Python进行开发，请确保已安装 Python 3.9 或更高版本。

• Windows：建议从 Python 官网下载安装包。
• macOS：可通过 Homebrew 命令 brew install python 安装。

完成Python环境配置后，克隆项目并安装依赖：

git clone https://github.com/x7722/moyu.git
cd moyu
python -m pip install -r requirements.txt

（在 macOS 上，请使用 python3 命令）。

运行与调试

在项目根目录下执行以下命令即可启动：

python main.py

• 首次运行时，请根据系统提示允许应用访问摄像头权限。
• 默认情况下，关闭或最小化主窗口将隐藏至系统托盘（双击托盘图标可恢复窗口，右键选择退出）；若在配置中关闭了托盘功能，则关闭窗口即完全退出程序。

灵活的配置管理

程序采用“内置默认配置 + 外部覆盖配置”的模式，易于定制且无需修改源码。

• 加载顺序：启动时，先加载打包在程序内部的默认 config.yml，再尝试读取与可执行文件（moyu.exe 或 moyu）同目录下的外部 config.yml（或 config.yaml）文件。外部配置文件只需包含您希望修改的字段，其余未配置项将自动沿用内置默认值。
• 路径格式：在配置文件中，Windows 路径可使用正斜杠 / 或单反斜杠 \（如 C:/Users/you/Pictures 或 C:\Users\you\Pictures），无需使用双反斜杠转义。

关键配置项说明

• min_faces_for_alert：触发警报所需的最少人脸数量，默认为 2。若希望检测到单人即触发，可修改为 1。
• alert_cooldown_seconds：两次连续触发之间的冷却时间（秒），防止短时间内频繁报警。
• snapshot.enabled：是否启用抓拍功能；snapshot.directory：抓拍图片的保存目录（若不存在会自动创建）。
• work_app.active：指定当前生效的目标应用别名；work_app.targets.<别名>.windows_command / macos_command：分别配置在 Windows 或 macOS 系统下用于启动/激活该应用的命令。
• ui.enable_system_tray / ui.minimize_to_tray / ui.start_minimized：分别控制是否启用系统托盘、关闭/最小化时是否隐藏到托盘、是否启动后直接最小化到托盘。
• ui.tray_notification_seconds：托盘气泡通知的显示时长，可设置在 5 到 10 秒之间。

最小化覆盖配置示例

在与可执行文件同目录下创建 config.yml 文件，内容如下：

min_faces_for_alert: 1
work_app:
  active: idea
  targets:
    idea:
      windows_command: “C:/Program Files/JetBrains/IntelliJ IDEA/bin/idea64.exe”
snapshot:
  enabled: true
  directory: snapshots

此配置将触发条件改为单人检测，并指定触发时激活 IDEA，同时开启抓拍功能并将图片保存在 snapshots 文件夹中。其他所有参数均保持程序内置默认值。

项目打包分发

您可以将项目打包为独立的可执行文件，方便在没有Python环境的机器上使用。

Windows 平台打包

1. 安装打包工具 PyInstaller（建议在项目虚拟环境中操作）：

   python -m pip install pyinstaller

2. 使用项目提供的 spec 文件进行打包（该 spec 文件已配置好包含内置配置及 MediaPipe 模型数据，并隐藏控制台窗口）：

   pyinstaller main.spec

3. 打包产物位于 dist 目录下的 moyu.exe。将您自定义的外部配置文件 config.yml 与此 moyu.exe 放置于同一目录即可生效。

macOS 平台打包

在 macOS 系统上执行以下命令（无法在 Windows 上交叉编译）：

python3 -m pip install pyinstaller
python3 -m PyInstaller --onefile --noconsole --name moyu --add-data “config.yml:.” --collect-data mediapipe main.py

通过PyInstaller打包后，产物为 dist/moyu。首次在 macOS 上运行时若被 Gatekeeper 拦截，可在 Finder 中右键点击该文件并选择“打开”，或自行进行代码签名与公证。