个人工作效率助手。WorkPulse 会定时记录当前前台应用、窗口标题和空闲状态，并按分类生成本地日报/周报。
- 每 30 秒采样一次当前前台应用和窗口标题
- 周期性截图并用 OCR 提取可见文本，用于生成屏幕理解线索
- 读取浏览器当前 URL，辅助判断网页活动
- 可配置项目目录，记录 Git 分支、dirty 状态和近期文件改动线索
- 从近期文本文件改动和终端窗口标题提取产出/终端线索
- 按项目和意图归类活动，生成带事实线索的复盘报告
- 记录用户空闲状态并区分活跃时间 / 空闲时间
- 基于 YAML 规则将活动分类为编码、文档、沟通、设计、浏览、娱乐等
- 使用本地 SQLite 存储数据
- 支持生成表格或 Markdown 格式报告
- 支持清理历史数据
- macOS
- Windows
基础依赖：
pip install .macOS:
pip install ".[macos]"Windows:
pip install ".[windows]"Windows 推荐使用 Python 3.10 或 3.11，并优先在 PowerShell 中安装：
py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install ".[windows]"如果要给没有 Python 环境的 Windows 用户分发，可使用 PyInstaller 构建：
.\scripts\build_windows.ps1 -Clean构建后会得到：
dist\workpulse.exedist\artifacts\workpulse-windows-amd64.zipdist\artifacts\workpulse-windows-amd64.sha256
在 macOS 上，首次使用通常需要为终端或 Python 进程授予以下权限：
辅助功能屏幕录制
否则可能无法读取前台窗口标题或获取准确的活动信息。
WorkPulse 不记录原始键盘按键。默认会截图后做 OCR，但不保留原始截图；如需留存截图，可在 ~/.workpulse/settings.yaml 设置 keep_raw_screenshots: true。
查看帮助：
workpulse --help启动后台追踪：
workpulse start查看状态：
workpulse status暂停 / 恢复采集：
workpulse pause 30
workpulse pause
workpulse resume生成报告：
workpulse report
workpulse report yesterday
workpulse report week --format markdown
workpulse report week --format html --with-analysis --output report.html
workpulse report --from-date 2026-03-01 --to-date 2026-03-07生成工作分析：
workpulse analyze
workpulse analyze week --format json
workpulse analyze --from-date 2026-03-01 --to-date 2026-03-07
workpulse analyze --provider llm相关配置在 ~/.workpulse/settings.yaml：
screen_capture_enabled: true
screen_capture_interval_seconds: 60
screen_ocr_enabled: true
keep_raw_screenshots: false
screenshot_retention_days: 7
sensitive_apps:
- 1Password
- Keychain Access
sensitive_title_keywords:
- password
- 密码
- token
sensitive_url_keywords:
- /login
- banking
project_roots:
- ~/Projects/workpulse
project_scan_recent_seconds: 300sensitive_* 命中时会跳过截图和 OCR；project_roots 用于补充文件/Git 产出证据。
生成日报摘要：
workpulse brief
workpulse brief week --format json
workpulse brief --from-date 2026-03-01 --to-date 2026-03-07
workpulse brief --provider llm停止追踪：
workpulse stop管理开机自启动：
workpulse autostart status
workpulse autostart enable
workpulse autostart disable查看当前配置：
workpulse config show检查运行环境：
workpulse doctor
workpulse doctor --format json导出活动明细：
workpulse export --format csv --source active --output activities.csv
workpulse export --format json --source all --from-date 2026-03-01 --to-date 2026-03-07生成结构化日报：
workpulse daily-report
workpulse daily-report --provider llm
workpulse daily-report --from-date 2026-03-01 --to-date 2026-03-07 --output daily-report.md清理旧数据：
workpulse prune --before 2026-01-01首次在 Windows 上使用时，建议先确认以下几点：
- 使用普通桌面会话，不要在远程受限环境里测试前台窗口采集
- PowerShell 或终端不要以会频繁被关闭的临时窗口运行
- 某些安全软件可能会拦截窗口访问或后台进程创建
- 如果你使用的是公司设备，可能会受到系统策略限制
建议先手动验证一遍主流程：
workpulse start
workpulse status
workpulse report
workpulse stop如果 status 显示已运行，但没有数据，优先检查：
- 是否确实在桌面前台切换过应用
- 当前 Python 环境里是否安装了
psutil和pywin32 - 杀毒软件或企业安全策略是否拦截了后台采集
检查 Windows 扩展依赖：
python -c "import psutil, win32gui, win32process; print('ok')"WorkPulse 默认把数据存放在用户目录下：
- 数据库：
~/.workpulse/activity.db - 规则文件：
~/.workpulse/rules.yaml - 配置文件：
~/.workpulse/settings.yaml - 日志文件：
~/.workpulse/workpulse.log - PID 文件：
~/.workpulse/workpulse.pid
默认使用启发式分析。若要启用外部模型分析，可在环境变量中提供 API key，并将 settings.yaml 的 analysis_provider 设为 llm 或命令行传 --provider llm。
默认兼容 OpenAI 风格接口，关键配置：
analysis_providerllm_endpointllm_modelllm_api_key_envllm_timeout_seconds
例如：
export OPENAI_API_KEY=your_key
workpulse analyze --provider llm首次运行时会自动生成 ~/.workpulse/rules.yaml。你可以自行编辑规则，例如：
idle_threshold_minutes: 5
default_category: "其他"
rules:
- app_contains: "Code"
category: "编码"
- app_contains: "WeChat"
category: "沟通"
- title_contains: "YouTube"
category: "娱乐"规则按顺序匹配，命中后立即返回对应分类。
当前支持的时间范围：
todayyesterdayweek
报告内容包括：
- 活跃时间与空闲时间
- 分类统计
- 应用统计
- 活动详情 Top 10
- URL、项目、意图、文本/终端和屏幕理解线索
运行测试：
PYTHONPATH=src python3 -m unittest discover -s tests -v本地直接运行：
PYTHONPATH=src python3 -m workpulse --help设计文档：
- 这是一个本地优先的轻量工具，暂不包含云同步
- 分类准确度依赖用户规则配置
- 浏览器类应用可能覆盖多种活动场景，报告会尽量标记为多分类
- 当前分析模块是启发式分析，还没有接入真实 LLM
- 当前提供的是打包工作流和构建脚本，不是完整安装器
MIT