架构文档

深入了解 TimeLens 的系统架构、模块划分、数据流设计及关键技术决策。

系统概览

TimeLens 是一款基于 Tauri 2.x 构建的桌面应用，采用 Rust + React 双层架构。Rust 层负责系统级交互（窗口监控、数据库、系统托盘），React 层负责所有用户界面。

核心设计原则

数据主权：所有使用数据存储在本地 SQLite，不上传云端。
零运行时依赖：除操作系统自带组件外，不需要额外安装任何服务。
模块化 Command：每个功能域拥有独立的 Rust command 模块，便于维护和扩展。
状态集中管理：前端使用 Zustand 进行全局状态管理，避免 props drilling。

Rust 后端层

lib.rs — 应用生命周期

src-tauri/src/lib.rs 是整个 Rust 层的入口，负责以下初始化流程：

初始化 env_logger 日志系统。
注册 Tauri 插件（shell、global-shortcut、notification、updater、dialog）。
setup 回调中：
- 打开/创建 SQLite 数据库
- 将数据库连接注册为共享状态（DbState）
- 恢复上次会话的小组件窗口
- 创建系统托盘图标和菜单
- 启动后台监控任务（tokio）

monitor/ — 前台窗口监控

后台 tokio 任务，以固定间隔（默认 1 秒）轮询当前前台窗口信息。

平台	实现方式
Windows	Win32 API（`GetForegroundWindow`、`GetWindowThreadProcessId`、`GetModuleBaseName`）
macOS	AppleScript / Accessibility API

监控模块检测到窗口切换时，将旧窗口的使用时长写入数据库，并开始记录新窗口。同时通过 Tauri 事件通道向前端广播 active-window-changed 事件。

db/ — SQLite 数据层

所有数据库操作集中在 db/mod.rs，包含以下核心表：

表名	用途
`app_usage`	每条记录 = 一个应用在某日的一个使用片段（含窗口标题、活跃秒数）
`app_categories`	应用 → 分类映射规则
`usage_goals`	用户设置的使用目标（每日/每周、至少/至多）
`focus_sessions`	专注模式会话记录
`todos`	待办事项数据
`widget_configs`	小组件窗口位置、尺寸、透明度等配置
`settings`	应用级设置（启动项、快捷键、语言等）
`browser_sessions`	浏览器扩展同步的网页访问记录
`browser_domain_limits`	网页域名使用限额
`llm_conversations`	AI Insights 会话记录（消息、归档、置顶、摘要）

commands/ — IPC 接口层

Rust command 模块按功能域拆分：

文件	职责
`monitor_cmd.rs`	监控状态查询、暂停/恢复追踪
`storage_cmd.rs`	所有数据查询、统计计算、导入导出
`widget_cmd.rs`	创建/打开/关闭小组件窗口
`app_cmd.rs`	应用设置、系统通知、安装渠道检测
`browser_cmd.rs`	浏览器扩展数据、域名统计与限额
`productivity_cmd.rs`	生产力评分、中断时段分析
`llm_cmd.rs`	LLM Provider 配置读取与保存
`llm_conversation_cmd.rs`	AI Insights 会话的增删改查、归档、置顶
`widget_permissions.rs`	第三方小组件权限管理

React 前端层

窗口路由

TimeLens 不是单页应用，而是多窗口应用。src/App.tsx 根据 Tauri 窗口标签决定渲染内容：

窗口标签	渲染组件	说明
`main`	`MainApp`	主仪表盘，包含 HashRouter
`clock-*`	`WidgetWindow`	时钟小组件
`todo-*`	`WidgetWindow`	待办小组件
`timer-*`	`WidgetWindow`	计时器小组件
`note-*`	`WidgetWindow`	笔记小组件
`status-*`	`WidgetWindow`	状态小组件

页面结构

主应用（MainApp）使用 HashRouter，包含以下页面：

Dashboard — 今日概览、应用排行、热力图、生产力评分、目标进度
HomeCustomize — 仪表盘布局自定义（拖拽排序卡片）
WidgetCenter — 小组件管理中心（创建、配置、权限）
Limits — 应用使用限额设置
BrowserUsage — 浏览器使用统计（需配合浏览器扩展）
Categories — 应用分类管理与智能推荐
Goals — 使用目标设定与追踪
FocusMode — 专注模式开关与历史
LlmInsights — AI Insights 屏幕时间分析对话
Settings — 全局设置（语言、主题、快捷键、AI 助手等）

状态管理

使用 Zustand 创建了 6 个全局 store：

Store	数据	持久化
`statsStore`	今日/本周/历史使用数据、监控状态	否（实时从 Rust 获取）
`widgetStore`	小组件配置列表、可见性状态	Rust DB
`settingsStore`	主题、语言、监控设置等	Rust DB + localStorage 缓存
`dashboardLayoutStore`	仪表盘卡片顺序、显隐	localStorage
`llmStore`	LLM Provider、数据共享、默认分析范围	本地 TOML 配置文件
`llmConversationStore`	会话列表、当前会话、消息持久化	Rust DB + localStorage（活跃会话缓存）

数据流设计

监控数据流

OS 前台窗口
    ↓ (每秒轮询)
monitor/mod.rs
    ↓ (聚合 + 写入)
SQLite (app_usage 表)
    ↓ (前端主动查询 / 事件推送)
React Frontend
    ↓ (Zustand store)
Dashboard Charts & Lists

事件流

Tauri 提供了两种前后端通信方式：

invoke — 前端调用 Rust command，同步/异步请求-响应模式。
emit / listen — 事件广播模式，用于监控状态变更、窗口切换通知等实时推送。

小组件是 TimeLens 的特色功能。每个小组件都是一个独立的 Tauri 窗口，拥有独立的 WebView 实例。

官方内置小组件

类型	功能
Clock	模拟/数字时钟，支持自定义格式
Todo	待办列表，支持拖拽排序、完成标记
Timer	多模式计时器（番茄钟 / 倒计时 / 正计时）
Note	便签小组件，支持文本编辑
Status	系统状态展示（当前应用、今日总时长）

第三方小组件

TimeLens 支持加载第三方 JavaScript 小组件。详细开发指南参见小组件开发指南。

AI Assistant / LLM

TimeLens 内置 AI 助手（AI Insights），用于基于本地屏幕时间数据生成可对话的分析。所有配置与数据均保存在本地，对话历史不会上传云端。

后端模块

src-tauri/src/llm/config.rs — Provider 配置模型，包括 LlmProvider（name / nickname / base_url / model / api_key / builtin / referral_url）、LlmDataSharing（total_time / top_apps / categories / focus_time / goals / interruptions）和 AnalysisRange（today / yesterday / last_7_days / last_30_days / this_week / last_week / custom）。
src-tauri/src/llm/mod.rs — 解析本地 TOML 配置文件路径（llm_config.toml），提供原子化读写与文件变更轮询，并通过 llm-config-changed 事件通知前端刷新。
src-tauri/src/commands/llm_cmd.rs — get_llm_config / set_llm_config / get_llm_config_path。
src-tauri/src/commands/llm_conversation_cmd.rs — list_llm_conversations / get_llm_conversation / save_llm_conversation / delete_llm_conversation / archive_llm_conversation / pin_llm_conversation。
src-tauri/src/db/llm_conversations.rs — 会话的 SQLite CRUD 与 message_count 汇总查询。

数据表 `llm_conversations`

字段	类型	说明
`id`	TEXT	主键，会话唯一标识
`title`	TEXT	会话标题
`created_at`	TEXT	创建时间
`updated_at`	TEXT	最后更新时间
`archived`	INTEGER	是否归档
`pinned`	INTEGER	是否置顶
`messages`	TEXT	JSON 消息数组
`summary`	TEXT	可选摘要文本

前端实现

src/pages/LlmInsights/index.tsx — AI Insights 页面，左侧会话列表支持归档 / 置顶 / 删除，右侧对话区支持时间范围选择、Provider 选择、基于屏幕时间上下文的 analyze 与追问，以及对话历史 summarize 压缩。
src/stores/llmStore.ts — 管理 Provider 选择、数据共享开关、默认分析范围，监听 llm-config-changed 以同步外部 TOML 修改。
src/stores/llmConversationStore.ts — 管理会话列表、当前会话、消息追加与摘要替换；活跃会话 ID 通过 Zustand persist 缓存在 localStorage。
src/services/llmApi.ts — 封装所有 LLM 相关 invoke，并提供 streamChatCompletion 实现 OpenAI 兼容的 SSE 流式请求。

隐私与数据共享

用户在 Settings → AI Assistant（设置页第 3 个入口）中可逐条控制 AI 可见的数据维度：总时长、Top 应用、分类、专注时间、目标、中断次数。分析请求仅将用户授权的数据作为 system 上下文发送给选中的 OpenAI 兼容端点，API key 与配置保存在本地 TOML 文件中。

国际化架构

使用 i18next + react-i18next 实现多语言支持。

翻译文件位于 src/i18n/locales/{lang}/
按功能域拆分 JSON 文件：common.json、dashboard.json、widgets.json、settings.json 等
新增语言仅需翻译 JSON 并在 config.ts 注册即可

安全模型

TimeLens 使用 Tauri v2 的 Capability 系统进行权限控制：

capabilities/default.json 定义了主窗口和各类小组件窗口的权限集合。
第三方小组件通过权限系统（widget_permissions.rs）进行沙箱隔离，按需授予 screen-time:read 等权限。
所有 Rust command 参数均经过类型校验，SQL 查询使用参数化防止注入。

最后更新：2026-07-18 · TimeLens v2.0.1