TimeLens 帮助文档

常见原因与排查步骤：

1. 确认 TimeLens 已启动并在后台运行。最小化后主窗口会隐藏到系统托盘，监控仍在继续。
2. 检查 Settings → Tracking 中监控是否被暂停；托盘右键菜单也可恢复。
3. 确认 Settings → Data 中没有将当前应用加入忽略列表。
4. 如果刚安装，可能需要等待几分钟后刷新 Dashboard（今日视图会自动轮询）。
5. 如果使用的是从源码构建版本，请确保以正常方式运行 npm run tauri:dev 或打包后的安装程序。

扩展通过本地 HTTP API（默认 http://127.0.0.1:49152）与桌面端通信，并使用 Extension Bridge Key 对请求签名。

1. 打开 TimeLens 桌面端 → Settings → Local API / Extension Bridge，复制桥接密钥。
2. 在扩展弹窗/命令面板中粘贴并保存密钥。
3. 确认 Local API 已启用。

详细步骤参见 浏览器扩展文档 与 VS Code 扩展文档。

TimeLens v2.0.2 已内置端口回退机制：

• 桌面端启动时若 49152 被 Windows 保留或安全软件拦截，会自动扫描 49152–50151 并绑定第一个可用端口。
• 桌面端的 Browser Usage / VS Code Insights 页面会显示当前实际绑定的本地 API 端口。
• 浏览器扩展和 VS Code 扩展也支持自动扫描备用端口；可在设置中留空 API Port 或设为 0 来启用扫描。

v2.0.x 默认使用与 v1.x 相同的低版本数据库路径。当默认 Profile 为空且检测到旧版数据库时，Settings 会显示一次性导入提示：

1. 打开 Settings → Profiles / Data。
2. 点击“导入旧数据”并按提示重启应用。
3. 也可以通过 Settings → Backup & Restore 导入之前导出的 JSON 备份。

导入过程会合并原始使用记录并重建 daily_app_usage 等派生表，确保今日统计正确。

Settings → Backup & Restore 提供两种备份方式：

• 普通备份：打包当前 Profile 的 SQLite 数据库与元数据。
• 密码保护备份：使用 AES-256-GCM 加密，密码通过 Argon2id 派生密钥。

恢复时可选择覆盖当前 Profile 或新建 Profile。恢复前会先验证备份包完整性，避免数据损坏。

TimeLens 提供多种官方浮动小组件：

• 点击主窗口侧边栏“小组件”或托盘菜单中的“新建时钟/待办/计时器”。
• 在 Widget Center 可查看已创建的小组件、调整透明度/置顶、设置开机自启。
• 支持导入第三方小组件，需先授予对应的数据访问权限。详见 中文小组件开发指南。

• 应用限额：前往 Limits 页面，选择应用并设置每日上限。达到 80%、90%、100% 时会触发原生通知。
• 生产力目标：前往 Goals 页面，创建针对单个应用或分类的目标（每日/每周、至少/至多），Dashboard 会显示目标进度。
• v2.0.0 新增 Goal Risk 提醒：当目标进度明显落后时，系统会发出 goal-risk-alert 通知。

• 所有使用数据存储在本地 SQLite，不上传云端。
• 浏览器扩展和 VS Code 扩展仅向本机 127.0.0.1 API 发送数据，不收集网页内容或源代码。
• 本地 API 通过 Extension Bridge Key、scoped token、allowlist 和速率限制进行访问控制。
• 可选 AES-256-GCM 数据库静态加密，退出时擦除运行时明文。

完整说明请查看 Privacy Policy。

• Windows: %APPDATA%\com.timelens.app\timelens.db
• macOS: ~/Library/Application Support/com.timelens.app/timelens.db

如果启用了数据库静态加密，原始数据库文件会被加密存储，运行时通过内存解密访问。建议定期使用 Settings → Backup & Restore 导出备份。

TimeLens 是 MIT 许可的开源项目：

• 在 GitHub 上提交 Issue 或 Pull Request。
• 开发前请阅读 CONTRIBUTING.md。
• 查看 开发指南 和 架构文档 了解如何搭建环境。