Focuslog

FocusLog：桌面活动 MCP 服务

一个在后台运行的服务，用于记录你的桌面活动、计算每分钟操作数（APM），并按需提供简洁、匿名化的工作时间线。它旨在为个人分析或 AI 助手提供数据源。

此服务使用 FastMCP 进行通信，使用 Ollama 实现 AI 驱动的匿名化，并使用标准 Linux 工具跟踪活动。

功能

• 活动记录：定期记录当前获得焦点的窗口标题。
• APM 跟踪：根据键盘和鼠标活动计算每分钟操作数（APM）。
• 时间线汇总：将连续活动分组，生成精简易读的时间线。
• 两阶段匿名化：
  1. 硬编码过滤器：确保删除用户定义的敏感关键词。
  2. 大模型匿名化：使用本地 Ollama 模型智能删除其他个人身份信息（PII）。
• 标题清理：清理并缩短过长的窗口标题。
• 可靠且可配置：支持日志轮转、平稳关闭，所有设置都在单独的 config.py 文件中管理。
• Systemd 服务：可作为持久的后台服务运行，以实现最高可靠性。

要求

系统依赖项

重要

兼容性说明： 此服务专为运行于 X11 显示服务器上的 Linux 桌面环境设计。它依赖 X11 生态系统中的工具，因此无法在 Windows、macOS 或原生 Wayland 会话中运行。

你必须安装以下命令行工具和库：

• xdotool：用于获取活动窗口标题。
• xprintidle：用于检查用户空闲时间。
• ollama：用于运行本地大模型。
• PyGObject：用于 D-Bus 通信（用于检测屏幕锁定状态）。

在 Debian/Ubuntu/Linux Mint 上，你可以使用以下命令安装所有依赖项：

sudo apt update
sudo apt install xdotool xprintidle python3-gi python3-gi-cairo gir1.2-gtk-3.0

对于 Ollama，请按照 ollama.com 上的官方安装说明进行安装。安装后，请确保已拉取一个模型：

ollama pull gemma3

Python 依赖项

此项目需要 Python 3.8+，并使用虚拟环境管理其软件包。

安装与设置

1. 克隆仓库：

   git clone https://github.com/your-username/focuslog.git
   cd focuslog
   

2. 创建虚拟环境： 我们需要创建一个能够访问系统 PyGObject 库的虚拟环境。

   python3 -m venv venv --system-site-packages
   

3. 激活环境并安装软件包：

   source venv/bin/activate
   pip install -r requirements.txt
   deactivate
   

   (输入 deactivate 即可退出环境)。

4. 创建配置文件：

   cp config.py.example config.py
   

5. 编辑配置： 使用文本编辑器打开 config.py。

   • 务必在 FORBIDDEN_KEYWORDS 列表中填写你希望始终删除的个人数据。
   • 可以根据需要调整 OLLAMA_MODEL 或 MCP_PORT 等其他设置。

使用方法

手动启动（用于测试）

要手动启动服务进行测试，请先激活虚拟环境：

source venv/bin/activate
python focuslog.py

服务启动后会在控制台中显示日志。按 Ctrl+C 停止服务。

作为服务运行（推荐）

为实现持续、可靠的后台运行，最好将 FocusLog 作为 systemd 用户服务运行。这样，服务器会在你登录时自动启动，并在崩溃时自动重启。

1. 准备服务文件：

   cp focuslog.service.example focuslog.service
   

2. 编辑 focuslog.service： 打开文件，将占位路径替换为实际路径。

   • WorkingDirectory=/home/your_username/path/to/focuslog -> 例如，WorkingDirectory=/home/dw/projects/focuslog
   • ExecStart=... -> 同样更新 venv/bin/python 和 focuslog.py 的路径。
   • 重要：不要添加 User= 或 Group= 行。systemd --user 会自动处理。

3. 安装并启用服务：

   mkdir -p ~/.config/systemd/user
   cp focuslog.service ~/.config/systemd/user/
   systemctl --user daemon-reload
   systemctl --user enable --now focuslog.service
   

   --now 标志不仅会启用服务，使其在之后登录时启动，还会立即启动服务。

4. 管理服务：

   • 检查状态： systemctl --user status focuslog.service
   • 查看日志： journalctl --user -u focuslog.service -f（-f 用于实时跟踪）
   • 停止： systemctl --user stop focuslog.service
   • 启动： systemctl --user start focuslog.service

工作原理

服务器运行两个主要的后台线程：

1. APM 传感器：每半秒检查一次用户输入，以更新活动“tick”计数器。
2. 日志记录器：每 10 秒执行以下操作：
   • 获取当前活动窗口的标题。
   • 清理标题（缩短标题并应用自定义规则）。
   • 根据上一分钟内的 tick 数计算当前 APM。
   • 将清理后的标题和 APM 保存到 SQLite 数据库。

通过 MCP 客户端调用 get_activity_log 工具时，它会：

1. 从数据库获取原始数据。
2. 对所有不重复的窗口标题进行两阶段匿名化，并缓存结果以提升性能。
3. 将数据汇总为清晰的时间线。
4. 以字符串形式返回时间线。

许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。