sgk-ctrl/mac-activity-tracker

# mac-activity-tracker **一个 100% 本地化的 macOS 活动追踪器 —— 读取原生屏幕使用时间、浏览器和 CLI 日志，为您提供私密的每两周一次的生产力回顾。没有云端，没有遥测，没有常驻进程。**     它回答了这些问题：*我的 Mac 时间究竟花在了哪里？其中有多少是深度专注，又有多少是分心？我在多大程度上依赖于 agentic 工具（Claude、Codex、Hermes...），以及哪些工具或工作流的改变能放大我的工作效率？* —— 然后每两周重新评估一次。  ## 它能告诉你什么（以及该怎么做） 每次运行都会回答五个问题，每个问题都对应一个行动： | 仪表板显示内容 | 它回答的问题 | 你可以采取的行动 | |---|---|---| | **深度专注百分比**（编程 + AI 时间） | 我是否把最好的时光花在了真正的工作上？ | 在评估中显示的巅峰时段内，避免安排会议。 | | **Agentic 工具占比**及各工具细分 | 我实际上在多大程度上利用了 AI 工具 —— 具体是哪些？ | 整合那些发挥重要作用的工具；将它们串联起来，而不是在它们之间复制粘贴。 | | **每日应用切换次数** | 我的注意力有多分散？ | 将沟通集中到 2-3 个固定时间段内；该数字会在一个周期内下降。 | | **分心时间** + 主要罪魁祸首 | 时间漏洞集中在哪里？ | 一个有针对性的屏幕使用时间限制胜过全面的拦截器。 | | **按小时统计的活跃时段** | 我什么时候是真正在线的？ | 在该时间段内安排深度工作，在其之外处理行政事务。 | **每两周的评估** 会将这些转化为 3-4 条具体建议。使其发挥作用的循环是：运行它 → 挑选**一条**建议 → 改变一个习惯 → 两周后重新运行 → 进行比较。当你的目标数字朝着你期望的方向移动时，这个工具的任务就完成了。 ## 适用人群 - **注重隐私的知识工作者**（开发者、研究员、作家），他们想要量化的自我洞察，但不想将浏览/应用历史发送到云端服务。 - **重度 AI / agentic 工具用户**，他们希望看到并优化 Claude、Codex、Hermes、Cursor 等工具如何融入他们的日常。 - **自由职业者和独立运营者**，他们自我管理专注力和效率，没有管理者，也没有企业监控。 - **本地优先 / 量化自我的极客**，他们想要一个小巧、可审计、零依赖的工具，可以阅读和修改 —— 而不是一个不透明的 SaaS。 ## 不适用人群 - **想要监控他人的管理者或团队。** 这是一个单用户、设备端工具，没有中央报告或同步功能。在别人的机器上安装它来监视他们超出了其设计范围，也违背了其初衷。 - **需要秒表级精度或按计费时间工时跟踪的人。** 持续时间是方向性的估计值（参见*关于准确性的说明*），而不是计费时间钟。 - **Windows 或 Linux 用户。** 它读取 macOS 特定的数据（屏幕使用时间、macOS 浏览器路径）；在设计上它是 macOS 专属的。 - **想要零终端 GUI 应用的人。** 设置只需几个命令行步骤和一个“完全磁盘访问”授权。目前还没有安装程序或菜单栏应用。 - **想要共享云仪表板的团队。** 它刻意没有服务器、账户或同步功能 —— 这正是它的核心目的。 ## 为什么你可以信任它 - **可审计** —— 几百行零依赖的 Python 代码。只需几分钟就能从头到尾阅读 [`tracker.py`](tracker.py)。 - **无网络出站流量** —— 检查源代码：没有 HTTP 客户端、套接字或上传操作。Chart.js 是**本地打包的**（`vendor/`），不是从 CDN 获取的，因此仪表板是完全离线的。 - **只读** —— 源数据库以只读模式打开（或通过私有的、自动删除的临时副本打开）。永远不会修改原始文件。 - **无守护进程** —— 按需运行，或者由*你*控制的 `launchd` 定时器运行。没有常驻进程，也没有屏幕录制。 - **默认隐私保护** —— 只存储**域名**（绝不存储完整的 URL 或页面标题）；`--redact` 模式会完全隐去名称。 ## 隐私与数据 此工具完全在你的机器上运行。**无遥测，无分析，无网络请求。** ### 读取了什么，以及数据去了哪里 | 来源 | 读取的内容 | 方式 | 去向 | |---|---|---|---| | 屏幕使用时间 (`knowledgeC.db`) | 每个应用的前台时间 | 只读 | `my_activity_data.json`（本地） | | 浏览器历史记录 (Chrome / Arc / Safari) | 访问过的**域名** + 访问时间 | 只读 | `my_activity_data.json`（本地） | | Shell 历史记录 (`.zsh_history` / `.bash_history`) | **仅** agentic CLI 的调用（例如 `claude`、`codex`）；忽略参数 | 只读 | `my_activity_data.json`（本地） | - 输出文件（`my_activity_data.json`、`dashboard.html`）保留在仓库文件夹中，并且被 **git 忽略**，因此你不会意外发布它们。 - 生成的 `dashboard.html` **嵌入了你的数据** —— 请像对待私密文档一样对待它；不要分享它。 ## 环境要求 macOS 12+ 和 Python 3.9+（现代 Mac 均已预装）。运行无需 pip 包。 ## 快速开始 **最简单的方法** —— 一行命令，首先向你展示样本仪表板，然后引导你完成设置： ``` curl -fsSL https://raw.githubusercontent.com/sgk-ctrl/mac-activity-tracker/main/scripts/install.sh | bash ``` （如果你愿意，可以先阅读 [`scripts/install.sh`](scripts/install.sh) —— 它会克隆此仓库、构建样本并打印说明。不需要 sudo，任何数据都不会离开你的机器。） **手动** —— 手动执行相同的操作： ``` git clone https://github.com/sgk-ctrl/mac-activity-tracker.git cd mac-activity-tracker # 1) 查看示例 dashboard（无需设置，无真实数据） python3 build_dashboard.py --data sample/sample_data.json --out dashboard.sample.html open dashboard.sample.html # 2) 切换到你的数据（需要 Full Disk Access — 见下文） python3 tracker.py # -> my_activity_data.json python3 build_dashboard.py --data my_activity_data.json open dashboard.html ``` 或者直接：`make review`。 ## 作为 Mac 应用安装 比起输入命令，更喜欢双击操作？构建启动器应用（使用 macOS 自带的 `osacompile` —— 无需 Xcode，无需下载）： ``` make app # builds "Activity Review.app" into ~/Applications ``` 该应用是一个普通的 AppleScript 小程序 —— 阅读 [`packaging/applet.applescript.tmpl`](packaging/applet.applescript.tmpl) 以 审计它能做的一切。双击它会弹出一个菜单： - **运行双周回顾** —— 收集、构建并打开你的仪表板 - **运行回顾 + 记录实验笔记** —— 同上，外加一条你下次回顾时会检查的笔记 - **专注模式：60 分钟 / 关闭** —— 屏蔽你的分心网站（会询问你的密码 —— 因为它需要编辑 `/etc/hosts`） - **预览专注屏蔽列表** —— 查看哪些内容会被屏蔽 **最棒的一点：** 将“完全磁盘访问”授权给*该应用*，而不是你的终端 —— 这是一个范围窄得多的授权（系统设置 ▸ 隐私与安全性 ▸ 完全磁盘访问 ▸ + ▸ `~/Applications/Activity Review.app`）。它启动、做一件事，然后 退出 —— 依然没有常驻进程。如果你移动了仓库文件夹，请使用 `make app` 重新构建。 ### 授予完全磁盘访问权限 读取屏幕使用时间和浏览器数据库需要为你运行此命令的终端授予**完全磁盘访问**权限： **系统设置 ▸ 隐私与安全性 ▸ 完全磁盘访问** → 添加 Terminal（或 iTerm）。 ⚠️ 这是一个广泛且持久的授权：它允许在该终端中运行的*任何东西*读取敏感文件。建议将其授予专用的终端配置文件，并在**运行结束后撤销授权**。如果没有它，应用使用和浏览器历史记录将被跳过（你会收到明确的警告），其余部分仍能正常工作。 ## 收集选项 ``` python3 tracker.py --days 14 # lookback window (default 14) python3 tracker.py --no-browser # app usage + CLI only python3 tracker.py --no-shell # skip shell history python3 tracker.py --redact # category + time only; drop all names ``` ## 深度专注块与专注模式 仪表板的 **深度专注块** 部分会衡量你不受打扰的编程/AI 工作时段 （≥25 分钟，允许短暂暂停）：每天的块数、最长时长、 中位数，以及最实用的 —— **是哪个应用或网站打断了你的专注块**。 建议会根据你的数据自适应：对于沟通工具会给出“集中处理”的计划，对于分心 网站会启用专注模式。 **专注会话（应用内）** —— 最完整的版本，来自 *Activity Review.app*： 1. 询问该会话的**目标**及时长。 2. 显示你正在运行的应用，并询问**哪些是关键的** —— 保留这些应用。 3. **要求所有其他应用退出**（优雅退出 —— 它们可以提示保存； Finder、你的终端和本追踪器始终会被保留）。 4. 在此期间**屏蔽你的分心网站**。 5. 一个轻量级的守护进程会阻止非关键应用重新打开，直到 会话结束 —— 然后一切都会自动释放。 **专注模式（仅限网站，CLI）** —— 仅屏蔽网站，不控制应用。屏蔽 列表来自于*你自己*记录的分心域名以及常见的 嫌疑对象： ``` scripts/focus.sh list # preview what would be blocked (no sudo) sudo scripts/focus.sh 60 # block for 60 min, auto-restores after sudo scripts/focus.sh on # block until further notice sudo scripts/focus.sh off # restore immediately ``` **应用控制（CLI）** —— 退出非关键应用并保护白名单，而无需 触碰网站。使用 `DRY_RUN=1` 安全预览（打印出它*将要*退出的内容）： ``` DRY_RUN=1 scripts/focus_session.sh start "Xcode,Safari" 60 "ship the release" scripts/focus_session.sh start "Xcode,Safari" 60 "ship the release" # for real scripts/focus_session.sh stop # end early ``` 该守护进程是本工具包**唯一**的后台进程，并且仅在 会话期间存在 —— 在其他情况下依然遵循“无常驻进程”的承诺。 应用是被要求退出的，绝不强制杀死；保护列表始终会保留 Finder、你的终端、本追踪器以及系统 UI。 诚恳说明：这是该工具包中**唯一**在仓库文件夹之外写入内容的 部分 —— 它会在 `/etc/hosts` 中添加一个标记清晰的部分（因此需要 `sudo`）， 而 `off` 会精确移除该部分。它是你控制的减速带，而不是 家长控制。两个真实的限制：已打开的标签页在重新加载之前可能会继续工作； 并且启用了 **Secure DNS / DoH** 的浏览器会通过 HTTPS 解析域名， 从而完全绕过 `/etc/hosts`（Chrome：设置 ▸ 隐私 ▸ 安全性 ▸ 关闭“使用安全 DNS”；Safari 使用系统解析器，因此 会如预期般受到屏蔽影响）。 ## 跨回顾的趋势（改变习惯的关键部分） 每次收集运行时，还会向 `history/` 写入一份**仅包含聚合数据的快照** （类别总和和 KPI —— 绝不含应用、网站或命令名称；像你的其他所有文件一样被 git 忽略）。只要存在两份快照，仪表板就会增加一个 **跨回顾的趋势** 部分：包含深度专注 %、agentic %、 分心 % 和应用切换次数/天的差异标签，以及随时间变化的折线图。 在每次运行时记录一个实验： ``` python3 tracker.py --note "batch Slack into two windows" ``` 该笔记本地存储在快照中，并在你**下一次**回顾的顶部展示给你 —— 这样每次回顾都会先检查上次的实验是否奏效。使用 `--no-history` 可完全跳过快照。 ## 自定义类别 编辑 [`categories.py`](categories.py) —— 纯数据映射，将应用/域名映射到各个类别，并标记哪些算作专注、分心或 agentic。欢迎提交添加常用应用的 PR。 ## 自动化双周回顾 ``` FOLDER="$(pwd)" LABEL="com.$(whoami).activityreview" sed -e "s|__PATH__|$FOLDER|g" -e "s|__LABEL__|$LABEL|g" \ packaging/com.example.activityreview.plist > ~/Library/LaunchAgents/$LABEL.plist launchctl load ~/Library/LaunchAgents/$LABEL.plist ``` 它大约每 14 天重新构建一次仪表板，并将日志记录到 `review.log`。执行频率是近似值（如果 Mac 处于睡眠状态而错过了任务，它会在唤醒时运行）。想要固定的节奏？改用 [`packaging/com.example.activityreview.calendar.plist`](packaging/com.example.activityreview.calendar.plist) —— 它会在**每月 1 号和 15 号的 09:00** 运行（安装命令行相同，只需指向该文件即可）。 **卸载：** `launchctl unload ~/Library/LaunchAgents/$LABEL.plist && rm ~/Library/LaunchAgents/$LABEL.plist`，然后删除 `my_activity_data.json`、`dashboard.html` 和 `review.log`。 ## 工作原理 `tracker.py` 读取三个原生数据源，将其转换为统一的 JSON schema → `build_dashboard.py` 将该 JSON 渲染成一个自包含的 HTML 仪表板 （数据以无活性的 JSON 嵌入，Chart.js 来自 `vendor/`）。仪表板计算 KPI（专注 %、agentic 工具占比、每日上下文切换次数、分心时间）、 多张图表，以及带有工具/工作流建议的、基于规则周评估。 ## 关于准确性的说明 持续时间是**估算值**。应用使用情况来自屏幕使用时间（它可能只 保留最近几天的数据，并且可能被禁用）；重叠的屏幕使用时间记录会 进行去重处理，因此一天的总时间绝不会超过 24 小时。网络“时间”将来自 **所有**浏览器的访问记录归组到一条时间轴中，在空闲 15 分钟处将其分割为不同的浏览会话，并将到下一次访问的（上限）间隔归因于本次访问 —— 这只是一个替代指标，而非 真正的专注信号。CLI 持续时间使用你的 shell 记录的实际流逝时间 （zsh `EXTENDED_HISTORY`）；没有记录时间的条目将获得极少的名义积分。请将 这些数字视为**方向性趋势**，而非秒表级别的精确值。 ## 贡献 / 安全 / 许可证 - [CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - 发现了漏洞？请参阅 [SECURITY.md](SECURITY.md)（请私下报告）。 - 完整的数据处理细节：[PRIVACY.md](PRIVACY.md) - 范围与成功标准：[DEFINITION_OF_DONE.md](DEFINITION_OF_DONE.md) - 采用 [MIT](LICENSE) 授权。在 `vendor/` 中内置了 Chart.js (MIT)。

标签：Cutter, Python, 效率分析, 无后门, 本地部署, 生产力, 调试辅助, 逆向工具