基于Git日志的轻量级代码统计工具开发实践

1. 项目概述：一个为开发者定制的轻量级代码统计工具

如果你和我一样，日常重度依赖 Cursor 这类 AI 驱动的代码编辑器，那你肯定有过这样的体验：看着编辑器里飞速增长的代码行数，心里却有点没底。我到底写了多少行代码？这个项目里，新增、删除、修改的代码量分别是多少？最近一周我的编码活跃度如何？这些数据，对于个人复盘、团队汇报，甚至只是想满足一下“我今天又产出了不少”的成就感，都至关重要。

然而，市面上现成的代码统计工具，要么过于笨重，需要复杂的配置和服务器；要么功能单一，无法与 Cursor 这样的现代编辑器深度结合。于是，我动手开发了darzhang/cursor-stats-lite。这是一个专为 Cursor 编辑器设计的、轻量级的本地代码统计插件。它的核心目标只有一个：在你最熟悉的编码环境里，以最无感的方式，为你提供最直观的代码贡献数据。

它不依赖任何外部服务，所有数据都在你本地生成和处理，确保了隐私和安全。通过简单的命令，你就能快速查看指定时间范围内，你在当前项目中的代码变更统计，包括新增行数、删除行数、净增行数，并能按文件类型进行细分。对于追求效率、注重数据、又不想被复杂工具打扰的开发者来说，这无疑是一个趁手的小工具。接下来，我将详细拆解这个工具从构思到实现的每一个环节，分享其中的技术选型、实现细节以及我踩过的那些坑。

2. 核心设计思路：为什么选择“轻量级”与“本地化”

在决定动手之前，我花了些时间思考这个工具应该长什么样。市面上并非没有类似的方案，比如gitstats、cloc等命令行工具功能强大，GitHub Insights或GitLab自带的统计功能也相当全面。但它们都存在一些让我不太满意的地方：要么需要离开编辑器上下文去另一个终端或网页查看，要么数据聚合的粒度不够细（比如无法区分是我自己写的代码还是 AI 生成的建议），要么就是配置过程让人望而却步。

因此，我为cursor-stats-lite定下了几个核心设计原则，这些原则也直接决定了后续的技术选型和架构。

2.1 原则一：深度集成，无感使用

工具的价值在于提升效率，而不是制造新的负担。我的首要目标是让统计功能成为 Cursor 编辑器工作流的一部分，而不是一个独立的外部应用。这意味着，用户最好能在 Cursor 的命令面板里直接调用统计功能，结果也能直接显示在编辑器内，比如输出到内置终端或者一个漂亮的 Webview 面板里。这种“开箱即用、用完即走”的体验，才是现代开发者工具应该追求的。

为了实现这一点，我自然想到了利用 Cursor 对 VS Code 扩展生态的兼容性。VS Code 拥有庞大而成熟的扩展 API，允许开发者创建命令、菜单、视图等。通过开发一个 VS Code 扩展，就能无缝嵌入到 Cursor 中。用户只需要像安装其他插件一样从市场安装，或者本地加载，之后通过快捷键或命令面板即可唤醒功能，完全不需要切换上下文。

2.2 原则二：数据隐私与计算本地化

代码是开发者的核心资产，代码变更数据同样敏感。我不希望用户的任何代码内容或元数据离开其本地环境。因此，“所有计算在本地完成”是一条不可妥协的红线。这不仅仅是出于隐私考虑，也带来了实实在在的好处：零网络延迟，响应速度极快。无论项目大小，统计都是瞬间完成，体验流畅。

本地化计算也意味着更简单的部署。用户不需要申请 API 密钥，不需要配置数据库，更不用担心服务宕机。工具的唯一依赖就是用户本地的 Git 仓库和 Node.js 运行环境（对于 VS Code 扩展来说，后者是内置的）。这极大地降低了使用门槛。

2.3 原则三：轻量且聚焦

这个工具不是为了替代专业的代码分析平台。它的功能应该非常聚焦：统计指定时间段内，当前用户在当前项目中的代码行变更。不需要复杂的图表渲染，不需要团队对比，不需要代码质量分析。保持轻量，才能保持快速和稳定。

基于这个原则，我决定核心统计逻辑直接基于git log命令进行解析。Git 本身已经完美记录了每一次提交的变更详情（通过git log --numstat可以获取每个文件增加和删除的行数）。我们只需要巧妙地过滤和聚合这些数据即可。这避免了引入重量级的代码分析库，让整个扩展的体积可以控制在极小的范围。

2.4 原则四：结果清晰直观

输出的数据必须一目了然。一个简单的表格，包含总新增、总删除、净增行数，以及按文件后缀（如.js，.ts，.py）分类的统计，就足够了。过于复杂的数据可视化反而会分散注意力。清晰文本格式的输出，既可以直接阅读，也方便用户复制到报告或笔记中。

综合以上四点，cursor-stats-lite的形态就清晰了：它是一个 VS Code 扩展，通过调用本地 Git 命令获取数据，在内存中完成聚合计算，最后将结果以纯文本或简单格式输出到编辑器的输出通道或终端里。整个过程中，用户的代码数据不会以任何形式发送到网络。

3. 技术实现拆解：从 Git 日志到可读统计

明确了设计思路，接下来就是动手实现。整个流程可以分解为几个关键步骤：获取用户输入（时间范围）、执行 Git 命令、解析日志数据、聚合统计、格式化输出。下面我们来逐一拆解。

3.1 环境准备与项目初始化

首先，我们需要创建一个标准的 VS Code 扩展项目。使用 Yeoman 生成器和 VS Code 扩展生成器是最快的方式：

npm install -g yo generator-code yo code

在生成器的交互界面中，选择“New Extension (TypeScript)”。TypeScript 能提供更好的类型安全和开发体验，对于即使这样的小项目也值得使用。项目生成后，核心文件是src/extension.ts，这是我们功能的入口点。

我们需要在package.json中声明扩展的激活事件和提供的命令。这是扩展与编辑器通信的契约。

{ "activationEvents": [ "onStartupFinished" ], "contributes": { "commands": [ { "command": "cursor-stats-lite.showStats", "title": "Cursor Stats: Show My Code Statistics" } ] } }

这里，onStartupFinished让扩展在编辑器启动完成后就加载好，但不会立即执行代码，保持轻量。我们定义了一个命令cursor-stats-lite.showStats，用户可以在命令面板中搜索并执行它。

3.2 核心统计逻辑：解析 Git Numstat

统计的核心在于如何从 Git 历史中提取出“我”在“某个时间段”的代码变更。这里用到了 Git 一个强大但不太常用的参数：--numstat。

git log --numstat的输出格式大致如下：

commit abcdef123456... Author: Your Name <your.email@example.com> Date: Mon Apr 1 12:00:00 2024 +0800 feat: add new function 2 1 src/foo.js 0 5 docs/readme.md

每一行文件变更包含三列，以制表符分隔：增加的行数、删除的行数、文件路径。这正是我们需要的原始数据。

我们需要对这个命令进行加工，添加过滤条件：

1. 作者过滤：--author=“Your Name”。确保只统计当前用户的提交。这里有个细节，如何动态获取当前 Git 配置的用户名？一种方法是读取.git/config文件，但更可靠的方式是在扩展启动时，尝试执行git config user.name来获取。
2. 时间范围过滤：--since=“2024-03-25” --until=“2024-04-01”。支持用户输入起始和结束日期。
3. 格式化：--pretty=format:“”。我们不需要完整的提交信息，用空格式来简化输出，让后续解析更专注在--numstat的数据上。

因此，最终构建的 Git 命令类似：

git log --since="2024-03-25" --until="2024-04-01" --author="$(git config user.name)" --pretty=format:"" --numstat

注意：这里有一个潜在的坑。如果用户名包含空格或特殊字符，需要正确处理引号。在 Node.js 的child_process中执行命令时，使用参数数组形式[‘git’， ‘log’， ‘--since=...’， ...]比拼接字符串更安全，可以避免 shell 转义问题。

3.3 在扩展中执行命令与处理数据

在extension.ts中，我们需要做以下几件事：

1. 获取工作区信息：通过vscode.workspace.workspaceFolders判断是否打开了文件夹（即项目），并获取其路径。
2. 获取用户输入：使用vscode.window.showInputBox弹出输入框，让用户输入起始和结束日期。为了提高易用性，可以提供默认值，比如过去7天。
3. 执行 Git 命令：使用 Node.js 的child_process.execFile或exec，在项目根目录下执行构建好的 Git 命令。
4. 解析输出：将命令返回的文本按行分割。跳过空行。每一行数据行解析出新增数、删除数和文件路径。这里需要处理可能存在的重命名文件（Git 会显示为{old => new}），我们通常只关心最终的文件名，可以进行简单处理，提取=>后面的部分，或者直接忽略这种复杂情况，专注于简单统计。
5. 聚合数据：
   • 累加所有文件的增加行数、删除行数。
   • 根据文件路径的后缀名（通过path.extname获取），将变更行数累加到对应的文件类型分类中。对于没有后缀或后缀不常见的文件，可以归到 “Other” 类别。
6. 输出结果：将聚合好的数据，格式化为一个清晰的 ASCII 表格。我们可以使用console.table的替代方案，或者直接用字符串拼接一个简单的表格。然后，通过vscode.window.createOutputChannel创建一个专属的输出面板，将结果打印进去，这样用户就可以在一个固定的面板里查看多次统计的结果，而不会打扰到终端。

3.4 错误处理与边界情况

一个健壮的工具必须考虑各种边界情况：

• 非 Git 仓库：如果当前打开的不是 Git 仓库，应该友好提示，而不是让命令执行失败后抛出晦涩的错误。
• 无符合条件的提交：在指定时间范围和作者下，可能没有提交。此时应输出“未发现变更”之类的提示，而不是一个空表格或报错。
• Git 命令未安装：虽然 Cursor/VS Code 用户大概率有 Git，但仍需检查。可以尝试执行git --version来探测。
• 用户取消输入：当弹出输入框时，用户按了 ESC。此时应安静地退出，不执行任何操作。
• 大仓库性能：对于提交历史非常庞大的仓库，git log可能会稍慢。可以考虑在 UI 上显示一个进度提示（vscode.window.withProgress），提升用户体验。

4. 关键代码解析与实操要点

让我们深入到部分关键代码，看看具体是如何实现的，并讨论一些实现细节和选择。

4.1 命令注册与激活

在extension.ts的activate函数中，我们注册命令：

import * as vscode from ‘vscode’; import { showStats } from ‘./statsCalculator’; export function activate(context: vscode.ExtensionContext) { const disposable = vscode.commands.registerCommand(‘cursor-stats-lite.showStats’， () => { showStats(); }); context.subscriptions.push(disposable); }

showStats函数是我们实现的核心功能入口。将核心逻辑分离到statsCalculator.ts这样的模块中，有助于保持extension.ts的简洁和可测试性。

4.2 构建安全的 Git 命令

在statsCalculator.ts中，构建命令参数需要格外小心：

import { exec } from ‘child_process’; import { promisify } from ‘util’; const execAsync = promisify(exec); async function getGitUserName(workspacePath: string): Promise<string> { try { const { stdout } = await execAsync(‘git config user.name’， { cwd: workspacePath }); return stdout.trim(); } catch (error) { // 如果获取失败，可以抛错或返回空字符串，由上层处理 throw new Error(‘无法获取 Git 用户名，请检查 Git 配置。’); } } async function buildGitLogCommand(workspacePath: string， since: string， until: string， author: string): Promise<string[]> { // 使用参数数组，避免 shell 注入风险 const cmd = [ ‘git’， ‘log’， `--since=“${since}”`， `--until=“${until}”`， `--author=“${author}”`， ‘--pretty=format:“”’， // 注意：这里使用空格式 ‘--numstat’ ]; // 注意：如果日期或作者名可能包含引号，需要更复杂的转义处理。 // 一个更稳妥的做法是不在参数值外加引号，而是依赖 exec 的参数数组机制。 // 修正版： const cmdSafe = [ ‘git’， ‘log’， `--since=${since}`， // 值本身不应包含引号 `--until=${until}`， `--author=${author}`， ‘--pretty=format:’， ‘--numstat’ ]; return cmdSafe; }

实操心得：在拼接命令行参数时，永远优先使用参数数组[‘git’， ‘log’， ‘--since=...’]而不是字符串git log --since=“...”。前者由 Node.js 直接处理，能安全地传递各种特殊字符；后者需要经过系统 shell 解析，如果用户输入包含;，&，|等 shell 元字符，可能导致命令注入，执行非预期的命令，这是严重的安全漏洞。

4.3 解析与聚合 Numstat 输出

解析git log --numstat的输出需要处理一些细节：

interface FileStats { additions: number; deletions: number; } interface StatsResult { total: FileStats; byExtension: { [ext: string]: FileStats }; } async function parseNumstatOutput(output: string): Promise<StatsResult> { const lines = output.split(‘\n’); const result: StatsResult = { total: { additions: 0， deletions: 0 }， byExtension: {} }; for (const line of lines) { // 跳过空行和可能残留的空白行 if (!line.trim()) continue; // Numstat 行格式： “添加数\t删除数\t文件路径” const parts = line.split(‘\t’); if (parts.length < 3) continue; // 不是有效的 numstat 行 const [addStr， delStr， filePath] = parts; const additions = parseInt(addStr， 10); const deletions = parseInt(delStr， 10); // Git 对二进制文件用 “-” 表示，parseInt 会得到 NaN if (isNaN(additions) || isNaN(deletions)) { continue; // 跳过二进制文件变更 } // 累加总计 result.total.additions += additions; result.total.deletions += deletions; // 按文件扩展名分类 const ext = path.extname(filePath).toLowerCase() || ‘.no_extension’; if (!result.byExtension[ext]) { result.byExtension[ext] = { additions: 0， deletions: 0 }; } result.byExtension[ext].additions += additions; result.byExtension[ext].deletions += deletions; } return result; }

注意事项：git log --numstat对于二进制文件（如图片）的变更，会在增加和删除列显示-。我们的parseInt会得到NaN，所以必须检查并跳过。同时，文件路径可能因为重命名而显示为“old/path => new/path”。上述简单实现只取了filePath的最终值，对于重命名，它会取=>之后的部分作为路径。如果你需要更精确地处理重命名（例如，将变更同时计入新旧文件类型），则需要更复杂的解析，但这通常不是轻量统计的核心需求。

4.4 格式化输出与展示

将统计结果以友好方式呈现：

function formatStats(result: StatsResult): string { const { total， byExtension } = result; const netChange = total.additions - total.deletions; let output = `=== 代码统计结果 ===\n`; output += `时间范围: ${since} 至 ${until}\n`; output += `作者: ${author}\n\n`; output += `汇总:\n`; output += ` 新增行数: ${total.additions}\n`; output += ` 删除行数: ${total.deletions}\n`; output += ` 净增行数: ${netChange}\n\n`; output += `按文件类型细分:\n`; // 为了美观，可以计算一下最大扩展名长度来对齐 const extensions = Object.keys(byExtension).sort(); if (extensions.length === 0) { output += ` (无)\n`; } else { for (const ext of extensions) { const stat = byExtension[ext]; const extDisplay = ext === ‘.no_extension’ ? ‘(无扩展名)’ : ext; output += ` ${extDisplay.padEnd(12)}: +${stat.additions} / -${stat.deletions} (净${stat.additions - stat.deletions})\n`; } } return output; } // 在 showStats 函数中 const outputChannel = vscode.window.createOutputChannel(‘Cursor Stats Lite’); outputChannel.show(); // 显示输出面板 outputChannel.appendLine(formatStats(result));

这样，一个清晰、本地的代码统计功能就实现了。用户只需要在 Cursor 中按下Cmd+Shift+P(Mac) 或Ctrl+Shift+P(Windows/Linux)，输入 “Cursor Stats”，选择命令，输入日期范围，就能立刻看到自己的编码产出。

5. 开发中的常见问题与排查实录

即使是一个小工具，开发过程中也难免遇到各种问题。这里记录了几个典型问题及其解决方法，希望能帮你避开这些坑。

5.1 Git 命令在扩展环境中执行失败

问题现象：在终端里手动运行git log一切正常，但在扩展中通过child_process.exec执行时，返回错误“fatal: not a git repository”或命令未找到。

排查思路：

1. 工作目录问题：exec默认不在项目根目录运行。你必须通过{ cwd: workspaceFolder.uri.fsPath }选项明确指定命令执行的工作目录。
2. PATH 环境变量：VS Code/Cursor 扩展的运行时环境可能与你的终端环境不同，可能找不到git命令。可以使用process.env.PATH打印检查，或者考虑使用vscode.env.shell来获取系统 shell，但更简单的方法是使用which git(Unix) 或where git(Windows) 的绝对路径。不过，通常 VS Code 会继承系统的 PATH。
3. Git 未安装：极少数情况下用户可能没装 Git。可以在激活扩展时做一次检测，并给出友好提示。

解决方案：

async function executeGitCommand(args: string[]， workspacePath: string): Promise<string> { return new Promise((resolve， reject) => { const child = execFile(‘git’， args， { cwd: workspacePath }， (error， stdout， stderr) => { if (error) { // 处理特定的错误，如非Git仓库 if (stderr.includes(‘not a git repository’)) { reject(new Error(‘当前文件夹不是 Git 仓库。’)); } else { reject(error); } return; } resolve(stdout); }); }); }

5.2 时间范围过滤的时区陷阱

问题现象：用户输入 “2024-04-01” 作为--until日期，期望统计包含这一整天的提交，但发现当天晚些时候的提交没有被计入。

原因分析：git log --until=“2024-04-01”默认解释为 “2024-04-01 00:00:00”，即那一天的开始。因此，4月1日白天发生的提交都在这个时间点之后，不会被包含。

解决方案：为了包含截止日期当天的全部提交，我们需要将--until日期向后推一天。即，如果用户想看到截止到4月1日的提交，我们应该传入--until=“2024-04-02”。在 UI 上，我们需要向用户明确说明时间范围是“包含起始日，不包含结束日”（左闭右开区间），或者在前端处理时自动为结束日期加一天。

// 假设用户输入了 since=‘2024-03-25’， until=‘2024-04-01’ // 我们想让统计包含 4月1日 全天的提交 const effectiveUntil = new Date(until); effectiveUntil.setDate(effectiveUntil.getDate() + 1); const formattedUntil = effectiveUntil.toISOString().split(‘T’)[0]; // 得到 ‘2024-04-02’ // 然后将 formattedUntil 用于 git log --until

5.3 处理大型仓库的性能考量

问题现象：在拥有数万次提交的巨型仓库中执行git log，扩展会“卡住”一段时间，UI 无响应，用户体验差。

优化策略：

1. 进度反馈：使用vscode.window.withProgressAPI 显示一个进度条或旋转图标，告知用户操作正在进行中，避免误以为程序崩溃。

   await vscode.window.withProgress({ location: vscode.ProgressLocation.Notification， title: “正在分析 Git 历史...”， cancellable: false // 如果统计时间可能很长，可以考虑设为 true }， async (progress) => { // 执行统计逻辑 const result = await calculateStats(); return result; });

2. 限制历史范围：在 UI 上引导用户输入合理的时间范围，避免默认查询全部历史。可以提供“最近一周”、“最近一个月”等快捷选项。
3. 异步与非阻塞：确保所有耗时的操作（如exec）都使用异步函数，并且不阻塞 VS Code 的主线程。我们的实现本身就在异步函数中，这一点是满足的。

5.4 扩展的打包与发布

问题描述：本地测试一切正常，但如何分享给其他 Cursor 用户使用？

解决方案：遵循 VS Code 扩展的发布流程。

1. 安装 vsce：npm install -g @vscode/vsce
2. 创建发布账号：在 Azure DevOps 创建组织，获取 Personal Access Token (PAT)。
3. 打包：在项目根目录运行vsce package。这会生成一个.vsix文件，可以直接分发给其他用户，让他们通过 Cursor 的“从 VSIX 安装”功能来安装。
4. 发布到市场：运行vsce publish可以将扩展发布到 VS Code 扩展市场。由于 Cursor 兼容 VS Code 市场，发布后，用户就可以直接在 Cursor 的扩展商店里搜索 “cursor stats lite” 并安装了。

实操心得：在package.json中，engines.vscode字段非常重要，它指定了扩展兼容的 VS Code 版本最低要求。Cursor 基于特定版本的 VS Code，确保这个版本号兼容是关键。例如，“^1.85.0”表示兼容 1.85.0 及以上版本。发布前，务必在 Cursor 中完整测试打包后的.vsix文件。

6. 功能扩展与进阶玩法

基础功能实现后，这个工具还有很大的想象空间。这里分享几个我实践过或认为有价值的扩展方向，你可以根据自己的需求进行定制。

6.1 支持更灵活的过滤条件

目前的过滤只支持作者和时间。可以很容易地扩展：

• 按提交信息过滤：--grep=“feat”只统计包含 “feat” 关键词的提交。
• 排除合并提交：--no-merges可以过滤掉合并提交产生的行数变更，这些变更通常不是直接编码产出。
• 按文件路径过滤：-- “src/”可以只统计src/目录下的文件，忽略文档、配置文件等。

在 UI 上，可以设计一个更高级的表单，让用户勾选或输入这些过滤条件，让统计维度更加精准。

6.2 输出格式的多样化

除了简单的文本输出，还可以考虑：

• JSON 输出：将统计结果以 JSON 格式输出，方便被其他脚本或工具（如自动化报告生成器）消费。可以在命令中增加一个--output-format json的选项。
• 图表预览：虽然我们追求轻量，但利用 VS Code 的 Webview API，可以创建一个简单的 HTML 页面，用轻量图表库（如 Chart.js）渲染一个柱状图，直观展示不同文件类型的贡献比例。这对于快速可视化很有吸引力。
• 导出到文件：提供一个命令，将本次统计结果追加到一个本地的 Markdown 或 CSV 文件中，形成个人的编码日志。

6.3 定时自动统计与提醒

我们可以利用 VS Code 扩展的setInterval或cron表达式（通过 node-schedule 包），在后台定期（比如每天下班时）自动运行统计，并将结果以信息通知的形式推送给用户。

// 在扩展激活时，启动一个定时任务（注意控制频率，避免性能影响） const dailyJob = schedule.scheduleJob(‘0 18 * * *’， () => { // 每天下午6点 const stats = await calculateStatsForLastDay(); vscode.window.showInformationMessage(`今日编码报告：新增 ${stats.total.additions} 行， 删除 ${stats.total.deletions} 行。`); }); context.subscriptions.push({ dispose: () => dailyJob.cancel() }); // 扩展停用时取消任务

这个功能可以很好地帮助开发者培养每日复盘的习惯。

6.4 与 Cursor AI 活动的结合（设想）

一个更有趣的方向是尝试区分“人工编写”和“AI 生成”的代码。Cursor 的 AI 功能（如Chat和Composer）在生成代码时，是否会留下特殊的元数据或标记？目前公开的 API 可能没有直接暴露这一点。但我们可以做一个近似统计：通过分析提交信息中是否包含“Cursor:”或“Composer:”等前缀（如果 Cursor 的自动提交信息包含这些），来粗略估计 AI 辅助生成的代码量。这需要进一步研究 Cursor 的行为。

7. 总结与个人体会

开发cursor-stats-lite的过程，是一次典型的“工具驱动效率”的实践。它源于一个非常具体且未被很好满足的需求，然后用相对简单的技术组合将其实现。整个项目没有用到什么高深的技术，核心就是git log命令的灵活运用和 VS Code 扩展 API 的基本操作。

但正是这种“简单”，让它变得有用。它不试图解决所有问题，只专注做好一件事：快速、私密地告诉你，你在项目中写了多少代码。对于独立开发者、小型团队，或者只是希望量化自己工作进度的个人来说，这种轻量级的工具往往比功能庞杂的系统更受欢迎。

我个人在几个项目中持续使用这个工具，它让我对每周的代码产出有了更清晰的认识。有时看着净增行数为负（删除多于新增），我会反思是不是在做大量的重构和优化；有时看到某种文件类型的变更特别活跃，我会意识到项目的技术重心正在发生变化。这些数据点，成了我复盘和规划的小小依据。

最后，这个小工具也完全开源。如果你有类似的需求，或者对其中某些实现有更好的想法，非常欢迎你基于它进行修改和扩展。毕竟，最好的工具，永远是那个最适合自己工作流的工具。希望我的这次分享和这个简单的工具，能给你的开发日常带来一点点不一样的视角和便利。