1. 项目概述一个纯粹本地的代码评审伴侣如果你和我一样日常重度依赖 VS Code并且经常需要处理代码评审任务——无论是和同事异步协作还是借助 AI 助手如 Claude、GitHub Copilot、Cursor来审查自己的代码——那你一定遇到过类似的痛点。把需要修改的行号、文件名和意见一条条复制粘贴到聊天框里或者手动整理成文档这个过程不仅繁琐还容易出错。更别提当你切换分支后之前针对某个分支的评审意见就“消失”了或者需要反复向 AI 解释上下文。今天要聊的这个 VS Code 扩展vscode-local-code-review就是为了解决这些具体问题而生的。它的核心思路极其简单却又非常巧妙将代码评审意见以结构化的 JSON 格式直接存储在项目仓库的本地文件中。这个文件默认是.claude-review.json会像你的.gitignore一样成为项目的一部分随代码一起提交、分支、合并。它不依赖任何云端服务、不需要注册账号、没有任何网络请求完完全全运行在你的本地环境里。这意味着什么首先隐私和安全性得到了最大程度的保障你的代码评审内容不会离开你的机器。其次离线可用性在没有网络的环境下比如在飞机上、或者网络受限的区域你依然可以高效地进行代码标注和回顾。最重要的是它为AI 编码助手提供了一个完美的、可编程的“待办事项”接口。你可以直接告诉 AI“去读.claude-review.json文件把里面所有状态为open的评论都处理掉。” AI 可以精准地定位到文件的具体行理解你的修改意图并在修复后自动将状态标记为resolved。这个扩展完美地填补了轻量级、本地化代码评审工具的空白。它不适合需要复杂工作流、权限管理和正式审批流程的大型团队但对于个人开发者、小型团队或者任何希望将 AI 深度融入日常代码修改流程的人来说它是一个提升效率的利器。接下来我会从设计思路、安装配置、核心使用技巧到如何与 AI 高效协同为你完整拆解这个工具。2. 核心设计思路与方案选型解析2.1 为什么选择本地 JSON 文件作为存储介质这是整个扩展最核心的设计决策值得我们深入探讨。开发者没有选择将评论存储在 VS Code 的工作区状态、全局配置或者某个数据库中而是选择了一个纯文本的 JSON 文件这背后有非常务实的考量。首要原因是“可移植性”和“版本控制友好”。代码评审意见本质上是与特定代码版本commit强相关的元数据。将它们保存在一个受版本控制如 Git管理的文件中确保了评审历史与代码变更历史的同步。当你回退到某个历史提交时对应的评审文件也会被还原你能看到当时所有的评审意见。这对于追踪问题、回顾决策过程非常有价值。其次是极致的“简洁性”和“零依赖”。JSON 是一种几乎被所有编程语言和工具原生支持的、人类可读的数据格式。AI 模型能轻松解析它开发者用任何文本编辑器都能查看和修改它命令行工具如jq可以方便地查询和操作它。这避免了引入复杂的数据库或序列化库让扩展本身保持轻量启动和运行几乎无感。再者是为了实现“分支感知”能力。Git 分支是现代开发的核心。这个扩展在每条评论中都记录了branch字段。当你切换 Git 分支时扩展会自动过滤只显示当前分支下的评论。这个功能的实现正是因为数据存储在本地扩展可以实时读取.claude-review.json结合git branch --show-current这类命令快速完成过滤。如果数据在云端实现实时、低延迟的分支切换体验会复杂得多。最后是面向 AI 的“接口标准化”。AI 助手LLM在处理结构化数据方面表现出色。一个格式固定的 JSON 文件对于 AI 来说就是一个清晰明确的指令集。AI 可以像处理普通配置文件一样读取它理解每个字段的含义file指向文件line指向具体行comment是修改要求然后执行修改。这比让 AI 去理解非结构化的聊天历史或复杂的 IDE 插件 API 要直接和可靠得多。当然这个方案也有其权衡。例如当多人协作且同时修改评审文件时可能会产生合并冲突。但这恰恰是 Git 所擅长解决的问题团队可以通过约定如按模块或文件分配评审职责或简单的沟通来规避其收益远大于这点不便。2.2 功能定位是替代品还是补充剂理解一个工具的正确位置比盲目使用它更重要。vscode-local-code-review并非要取代 GitHub Pull Requests、GitLab Merge Requests 或 Phabricator 这类重型、正式的代码评审平台。它的定位是“轻量级、即时性的代码标注与任务跟踪工具”主要服务于以下场景个人开发时的自我评审在提交代码前自己快速过一遍标注出需要优化、有疑问或待完成的部分。与 AI 结对编程为 AI 助手创建清晰、上下文明确的修改任务列表让 AI 按图索骥批量处理问题。小团队或结对编程的异步沟通同事可以在你外出时查看你的分支直接在代码里添加评论你回来后一目了然。代码学习与笔记阅读开源项目或遗留代码时在关键处添加自己的理解和疑问作为学习笔记。它补充了正式评审流程之前的“草稿”阶段以及正式流程之外的非正式协作需求。你可以把它想象成代码世界里的“便签贴”随时贴随时看任务完成后就撕掉标记为解决。3. 详细安装与配置指南3.1 从源码构建安装推荐给开发者虽然项目提供了编译好的.vsix安装包但从源码安装能让你更了解其构成也便于后续可能进行的自定义修改或调试。整个过程需要 Node.js 和 npm 环境。# 1. 克隆仓库到本地 git clone https://github.com/aashutosh-sahni/vscode-local-code-review.git cd vscode-local-code-review # 2. 安装项目依赖 npm install这一步会安装所有必要的开发依赖包括 TypeScript 编译器、VS Code 扩展 API 类型定义等。如果网络较慢可以考虑配置 npm 镜像源。# 3. 编译 TypeScript 源码 npm run compile这个命令会执行tsc -p ./将src/目录下的.ts文件编译成.js文件输出到out/目录。这是 VS Code 扩展的标准构建流程。如果编译失败请检查 Node.js 版本建议使用 LTS 版本和 TypeScript 的全局/局部版本是否兼容。# 4. 打包成 VSIX 扩展安装包 npx vsce package --allow-missing-repositoryvsce是 VS Code 扩展的打包命令行工具。--allow-missing-repository参数是因为我们直接从源码克隆可能缺少某些发布元数据此参数可忽略相关警告。执行成功后会在当前目录生成一个类似vscode-local-code-review-0.0.2.vsix的文件。# 5. 在 VS Code 中安装此扩展包 code --install-extension ./vscode-local-code-review-*.vsix请确保code命令在终端可用即 VS Code 已添加到系统 PATH。安装成功后VS Code 会弹出提示你也可以在扩展面板CtrlShiftX中看到它。实操心得从源码安装时如果遇到vsce命令未找到需要先全局安装它npm install -g vscode/vsce。另外在开发过程中可以使用npm run watch命令启动监听模式这样你修改src/下的源码后会自动重新编译方便调试。3.2 直接安装发布版推荐给大多数用户对于绝大多数只想使用功能的用户直接下载预编译的发布包是最快最省事的方式。访问项目的 Releases 页面 。找到最新的版本如v0.0.2下载附件中的.vsix文件例如vscode-local-code-review-0.0.2.vsix。打开 VS Code进入扩展视图CtrlShiftX。点击扩展视图右上角的“...”菜单选择“从 VSIX 安装...”。在弹出的文件选择器中找到并选中你下载的.vsix文件即可完成安装。或者你也可以在终端使用命令行安装前提是你已经下载了该文件code --install-extension /path/to/vscode-local-code-review-0.0.2.vsix3.3 安装后的初步检查与配置安装完成后无需复杂配置扩展即可工作。但为了获得最佳体验建议进行以下检查确认安装在 VS Code 扩展面板中搜索 “Local Code Review”应能看到它并显示“已启用”。查看状态栏打开一个 Git 仓库中的项目VS Code 窗口左下角的状态栏应该会出现一个类似 0的图标显示当前分支的未解决评论数量。这是扩展正常运行的主要标志。快捷键确认默认的添加评论快捷键是CmdShiftRMac或CtrlShiftRWindows/Linux。你可以在 VS Code 的键盘快捷键设置CtrlK CtrlS中搜索 “Add Comment” 来查看或修改它。注意事项该扩展重度依赖 VS Code 的内置 Git 功能来识别当前分支。请确保你打开的是一个 Git 仓库的根目录或子目录并且 VS Code 的源代码管理视图能正常检测到 Git 信息。如果状态栏不显示评论计数首先检查当前文件夹是否在 Git 仓库中。4. 核心功能使用详解与实操技巧4.1 添加与管理代码评论添加评论是核心操作有以下几种方式快捷键将光标置于目标行或选中多行代码按下Cmd/CtrlShiftR。右键菜单在编辑器内右键点击选择上下文菜单中的 “Add Comment”。命令面板按下Cmd/CtrlShiftP输入 “Add Comment” 并执行。执行后当前行或选中区域的首行的左侧装订线gutter会出现一个评论图标并且该行会有浅色背景高亮。同时一个输入框会弹出让你输入评论内容。输入完成后按Enter保存按Esc取消。高级技巧精准定位与多行评论跨行评论如果你想对一段连续的代码如一个函数体添加一个总体评论可以先在编辑器中选择这段代码鼠标拖动或Shift方向键然后再使用添加评论命令。这样生成的 JSON 中会包含line起始行和endLine结束行两个字段评论图标会显示在起始行但高亮会覆盖整个区域。查看与导航所有评论会以一个列表形式展示在 VS Code 的“问题”Problems面板旁边的一个专属 “Code Review” 面板中。点击列表中的任意一条评论编辑器会立即跳转到对应的文件和行。将鼠标悬停在编辑器中的评论图标或高亮行上会以悬浮提示Hover的方式显示评论内容非常方便。4.2 理解与操作.claude-review.json文件扩展的所有评论数据都存储在你项目根目录下的.claude-review.json文件中。理解它的结构对高级使用和排查问题至关重要。文件是一个 JSON 数组每个元素是一条评论记录。一个典型的条目如下{ file: src/utils/validator.js, line: 28, endLine: 30, comment: 这里进行空值判断时建议使用 if (!value value ! 0) 以兼容数字0的情况。, status: open, branch: feat/add-validation, createdAt: 2023-10-27T08:15:30.120Z }file: 相对于项目根目录的文件路径。line: 评论所指向的起始行号从1开始计数。endLine: 可选评论所指向的结束行号。如果评论只针对单行则此字段可能不存在或等于line。comment: 评论的文本内容。status: 评论状态只能是open未解决或resolved已解决。branch: 创建评论时所在的分支名称。这是实现分支感知的关键。createdAt: 评论创建的时间戳ISO 8601 格式。手动操作与维护 你可以直接编辑这个 JSON 文件来批量修改评论状态、修复错误的文件路径或行号、甚至手动添加评论。这在某些自动化脚本场景下很有用。例如你可以写一个脚本在 CI 流程中如果发现某些编码规范问题就自动向这个文件追加评论条目。重要提示手动编辑 JSON 文件时务必保证格式正确尤其是逗号和括号否则会导致扩展无法读取文件所有评论会“消失”。建议在保存前使用 JSON 验证工具检查一下。4.3 分支感知工作流实战这是该扩展区别于许多云评审计工具的特色功能。假设你正在feature/login分支上开发登录功能你添加了一些关于输入验证的评论。然后你需要紧急切换到hotfix/patch-1分支去修复一个生产环境 Bug。操作流程使用 Git 命令或 VS Code 源代码管理视图切换分支到hotfix/patch-1。你会发现状态栏的评论计数很可能变成了 0编辑器里feature/login分支的评论高亮也消失了。这是因为扩展自动过滤了数据只显示branch字段为hotfix/patch-1的评论。你在hotfix分支上修复 Bug 时也可以添加新的评论这些评论的branch字段会被自动记录为hotfix/patch-1。修复完成后切换回feature/login分支之前的所有评论和它们的高亮显示又会重新出现。这个机制带来的最大好处是“上下文隔离”。不同功能、不同任务的评审意见互不干扰保持了工作区的整洁和专注度。当你需要处理某个特定分支的评论时你不会被其他分支的评论分散注意力。通过命令面板管理分支评论View All Comments: 查看当前分支的所有评论这是默认视图。View All Branches: 查看所有分支的所有评论。这个视图适合项目负责人或想全局了解所有待办事项的情况。Clear Resolved (Current Branch):一键清除当前分支下所有状态为resolved的评论条目。这是一个非常实用的清理功能。因为已解决的评论在 JSON 文件里只是状态改变并没有被删除。定期清理可以保持文件精简。执行此命令后扩展会重写.claude-review.json文件只保留status不为resolved的条目。5. 与 AI 编码助手的高效协同策略这是该扩展设计的精髓所在。它本质上为 AI 助手创建了一个标准化、可执行的“工单系统”。5.1 如何向 AI 助手下达指令你不再需要费力地向 AI 描述“在src/api/user.js文件的第 56 行附近有一个函数需要错误处理……” 现在你只需要确保你的评论已经添加在代码中然后对 AI 助手在 Claude、Cursor 的聊天框或 Copilot Chat 中说“请阅读本项目根目录下的.claude-review.json文件。找到所有status为open的评论并根据comment字段的描述对指定file的line行进行代码修改。修改完成后请将对应条目的status更新为resolved。”或者更简洁的指令“Fix all open review comments in.claude-review.jsonand mark them as resolved.”一个结构良好的comment是成功的关键。你的评论应该是指令性的、清晰的。例如不佳“这里好像有点问题。”良好“将var改为const。”优秀“这个函数缺少对input参数为null的边界情况处理。请添加一个早期返回early return或抛出错误。”5.2 AI 处理流程模拟与最佳实践让我们模拟一下一个足够智能的 AI如 Claude 3 Opus, GPT-4接到指令后的理想处理流程读取与解析AI 读取.claude-review.json文件解析 JSON 数组。过滤任务筛选出status: open的条目。同时一个负责任的 AI 可能会检查branch字段是否与当前 Git 分支匹配以避免修改错误分支的代码虽然 AI 不一定有分支上下文但这是一个好习惯。顺序处理通常按文件或行号顺序处理每个条目避免混乱。定位与理解AI 打开file指定的文件滚动到line和endLine指定的位置阅读周围的代码上下文精确理解comment的意图。执行修改AI 根据评论要求进行代码修改。这可能包括重构、修复 Bug、优化性能、添加注释等。更新状态修改完成后AI 需要更新源 JSON 文件将刚处理完的条目的status改为resolved。这里有一个关键点AI 必须原地修改这个文件而不是生成一个新的、修改后的版本让你去复制粘贴。在对话式 AI 中这意味着它应该输出一个完整的、已更新的 JSON 内容让你替换原文件。给 AI 提供更多上下文有时仅凭一行评论可能信息不足。你可以在评论中引用相关的函数名、变量名或者添加简短的代码片段。例如“在calculateTotal函数里循环的效率可以优化。考虑使用reduce方法替代for循环。”最佳实践分批处理不要一次性让 AI 处理几十条评论。可以按模块或文件分组每次处理 5-10 条这样更容易验证 AI 的修改是否正确。审查 AI 的修改AI 修改后务必进行人工审查。特别是对于复杂的逻辑变更要运行测试以确保功能正常。利用版本控制在让 AI 批量修改前先提交一次代码。这样如果 AI 的修改不理想你可以轻松地使用git reset或git checkout回退。5.3 扩展工作流与自动化脚本结合.claude-review.json作为一个纯数据文件可以很容易地被其他脚本集成创造出更强大的工作流。场景一每日待办清单你可以写一个简单的 Shell 脚本或 Node.js 脚本在每天工作开始时运行它读取 JSON 文件统计每个文件或每个分支的未解决评论数生成一份简洁的日报。场景二与代码检查工具Linter集成假设你使用 ESLint 进行代码检查你可以配置一个自定义规则当发现某些特定类型的错误例如“禁止使用”时不仅输出错误信息还自动向.claude-review.json文件追加一条评论。这样代码风格问题就自动转化为了可跟踪的评审项。场景三预提交钩子Pre-commit Hook在 Git 的pre-commit钩子中加入一个检查如果当前分支的.claude-review.json中还存在status为open的评论则阻止提交并提示开发者先处理完这些评审意见。这可以作为代码质量的一道强制关卡。6. 常见问题排查与实战经验分享即使工具设计得很简洁在实际使用中也可能遇到一些小问题。这里汇总了一些常见情况及解决方法。6.1 评论不显示或状态栏异常问题现象打开了项目但状态栏没有显示评论图标和计数或者评论面板是空的。检查1项目是否为 Git 仓库这是最常见的原因。扩展依赖 VS Code 的 Git API 来获取当前分支信息。请确保当前打开的文件夹是 Git 仓库的根目录包含.git文件夹。你可以在终端输入git status确认。检查2.claude-review.json文件是否存在且格式正确在项目根目录检查该文件是否存在。如果存在尝试用 VS Code 打开它看右下角是否有 JSON 语法错误提示如红色的波浪线。格式错误的 JSON 会导致扩展无法读取。你可以尝试暂时重命名该文件看看扩展是否会新建一个空的这时状态栏应显示 0。检查3VS Code 的 Git 功能是否正常有时 VS Code 的 Git 扩展可能被禁用或出现问题。尝试在 VS Code 的命令面板CtrlShiftP中执行Git: Initialize Repository或重启 VS Code。检查4扩展是否被禁用去扩展面板确认 “Local Code Review” 扩展处于启用状态。6.2 分支切换后评论“消失”问题现象在 A 分支添加了评论切换到 B 分支后看不到了再切回 A 分支又出现了。这是正常现象不是 Bug。这正是“分支感知”功能在起作用。扩展默认只显示当前分支的评论。如果你想查看所有分支的评论请使用命令面板中的View All Branches命令。确认当前分支查看 VS Code 窗口左下角的状态栏通常会显示当前 Git 分支名。确保你切换到了你期望的分支。6.3 与 AI 协作时的问题问题现象AI 无法理解指令或修改了错误的文件。指令清晰度确保你的指令明确提到了文件名.claude-review.json和操作要求读取、修改、更新状态。对于能力较弱的 AI 模型可能需要更详细的步骤说明。评论内容质量检查你的comment字段是否足够清晰、无歧义。模糊的评论会导致 AI 产生不可预知的修改。文件路径确保file字段的路径是相对于项目根目录的并且是有效的。AI 需要能根据这个路径找到文件。JSON 更新AI 在输出更新后的 JSON 时必须提供完整的文件内容而不是一个 diff 片段。你需要用 AI 提供的完整内容替换原有的.claude-review.json文件。6.4 性能与文件管理问题现象当.claude-review.json文件变得非常大有上千条历史评论时VS Code 可能会感到卡顿。定期清理养成使用Clear Resolved (Current Branch)命令的习惯及时移除已解决的评论。对于历史久远、已合并分支的评论可以考虑手动编辑 JSON 文件进行归档或删除。.gitignore考量通常.claude-review.json文件是应该被提交到版本库的因为它记录了与代码相关的评审历史。但是如果你的团队认为它属于个人工作区临时文件也可以将其加入.gitignore。这取决于团队的协作模式。如果选择忽略那么每个开发者将拥有自己独立的评论文件无法共享。6.5 与其他扩展或工具的冲突目前该扩展功能相对独立冲突可能性较小。但如果你安装了其他也在编辑器装订线gutter添加图标或高亮的扩展如 GitLens、Error Lens 等可能会出现图标重叠。这通常只是视觉上的小问题不影响功能。可以通过调整扩展的加载顺序或禁用某些装饰功能来解决。一个真实的踩坑经历有一次我在一个大型 Monorepo 项目中使用了该扩展。这个 Monorepo 有多个子包每个子包都是一个独立的 Git 仓库使用 git submodule 或类似工具管理。当我打开 Monorepo 的根目录时VS Code 的 Git 扩展有时会识别到某个子包作为“活动仓库”导致vscode-local-code-review扩展读取到的分支信息是错误的评论文件也可能会被错误地创建在子包目录下。解决方案是在 Monorepo 中最好在每个子包内部单独使用这个扩展而不是在根目录使用。