DevTrack

我构建 DevTrack 是为了解决个人与技术上的需求：测量编程时间、分析我的习惯指标并计算财务收益，但无需依赖手动计时器，没有充满噪音的界面，且无需将我的数据发送到第三方服务器。

本文档详细介绍了项目的架构、模型和内部运作机制。在设计时，我将解决方案分为两个主要部分：直接存在于 Visual Studio Code 内部的“引擎” (vscode-extension)，以及展示门户或宣传网站 (landing-page)。

下面，我将解释该工具的内部运作原理以及我为其构建做出的技术决策。

---

1. 问题与应对方案

大多数时间跟踪工具都需要手动操作（开始/暂停），并呈现充满色彩的复杂界面，这些界面在编辑器内部争夺视觉注意力。

我决定基于三个技术支柱来解决这个问题：

• 事件自动化： 利用 VS Code 的原生 API 静默推断用户活动。
• 本地隐私： 利用 VS Code 的 globalState，使所有数据完全保留在用户的机器上。
• 集成美学： 使用单色 CSS 变量 (--vscode-descriptionForeground)，使控制面板融入编辑器的主题，避免视觉干扰。

---

2. 扩展架构 (VS Code)

为了保证代码的可维护性和可扩展性，我在 领域驱动设计 (DDD) 原则下，使用 Vertical Slicing 组织了 vscode-extension 目录。

核心模型与服务 (src/core/)

共享服务处理扩展的横切基础设施：

• StorageManager：持久化层。它封装了对 VS Code 的 globalState 的访问，保证高效写入和数据隔离，而不是依赖庞大的本地数据库。
• FormattingManager：集中处理日期和货币格式。由于时间跟踪严格依赖于午夜的重置，我使用了带有 en-CA locale 的原生 Intl API 来生成符合用户动态时区的统一日期 (YYYY-MM-DD)。
• SoundPlayer：对于实时收益里程碑，我通过委托给操作系统命令（macOS 上的 afplay，Windows 上的 powershell，Linux 上的 aplay）实现了音频通知（如金币声音）。如果失败，它将使用编辑器的原生 UI 作为 fallback。
• DashboardManager：使用 WebviewPanel 渲染主视图。我通过严格的 Content Security Policy (CSP) 策略保护视图，仅允许特定的 CDN 脚本和 Google 字体 (Space Grotesk, Geist)。

跟踪引擎：Orchestrator (src/features/tracker/)

DevTrack 的技术核心是通过 TrackingOrchestrator 实现的“观察者 (Observer)”模式。

编排器不是让多个循环以混乱的方式监听独立的事件，而是：

1. 订阅 API 的基础事件（例如：onDidChangeActiveTextEditor, onDidChangeTextDocument, onDidChangeWindowState）。
2. 保持 1 秒的内部循环 (“tick”)。
3. 计算空闲时间。如果用户停止交互，它会自主停止循环。
4. 将此 “tick” 广播给实现公共接口的一组独立的 Tracker。

分析模块（习惯与时间）

我实现了专门的模块 (Tracker)，它们以解耦的方式处理编排器的广播：

• TimeActivityTracker：基于费率 (devTrack.hourlyRate) 统计会话并派发财务事件。
• FlowStateTracker：计算纯粹活动的无干扰时段。
• ContextSwitchTracker：统计切换编辑器窗口的次数，以测量注意力的分散程度。
• AIAssistanceTracker：量化完成的代码中有多少比例来自手动打字 vs 自动插入（如 AI 助手生成的代码）。
• CommitTracker 与 LintTracker：分别通过读取 .git/logs/HEAD 记录和消费诊断事件 (onDidChangeDiagnostics) 来监测外部操作。

---

3. 数据可视化 (Dashboard)

对于客户端（在 WebviewPanel 内部），我避免打包像 React 或 Vue 这样的大型框架。我选择了原生 TypeScript 渲染，注入预先计算好的 HTML。

对于指标：

• 我使用了几乎完全专注于灰度 doughnut charts 的 Chart.js。
• 我使用纯 CSS Grid 系统而不是庞大的图表库实现了一个年度 heatmap（类似于 GitHub）。
• 我通过结合 html2canvas 和 jspdf 添加了对生成 PDF/图像报告的支持，在客户端处理 DOM 节点，并通过 Webview 协议向用户返回可下载的 Blob。

---

4. 宣传 Landing Page 的技术栈

为了展示该项目，我开发了一个快速展示网站（位于 landing-page/）。这里的核心考量是性能和 SEO：

• Astro + React： Astro 默认作为“Zero-JS”引擎，生成静态 HTML，而我将复杂的交互封装在 React islands 中。
• Tailwind CSS v4： 我通过 @tailwindcss/postcss 使用了新语法。完整的主题配置（包括通过 @custom-variant dark 变体支持 Dark Mode）直接存在于全局 CSS 中，无需 tailwind.config.js 文件。
• 现代图标集： 实现 lucide-react，以在整个网站的所有图标中保持一致、专业和极简的美学，而不是使用写死在代码中的平面 SVG。
• 优化与 PWA： Landing page 包含 SEO 配置（包括 OpenGraph 标签和图像）以及初始的 manifest.json，以启用 PWA 功能。
• 控制工具： Web 和扩展两个项目都使用 Biome 作为官方 linter 和 formatter，以统一使用 tabs 的代码规范。