企业官网建设流程全解析

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 这类重型、正式的代码评审平台。

它的定位是“轻量级、即时性的代码标注与任务跟踪工具”，主要服务于以下场景：

1. 个人开发时的自我评审：在提交代码前，自己快速过一遍，标注出需要优化、有疑问或待完成的部分。
2. 与 AI 结对编程：为 AI 助手创建清晰、上下文明确的修改任务列表，让 AI 按图索骥，批量处理问题。
3. 小团队或结对编程的异步沟通：同事可以在你外出时查看你的分支，直接在代码里添加评论，你回来后一目了然。
4. 代码学习与笔记：阅读开源项目或遗留代码时，在关键处添加自己的理解和疑问，作为学习笔记。

它补充了正式评审流程之前的“草稿”阶段，以及正式流程之外的非正式协作需求。你可以把它想象成代码世界里的“便签贴”，随时贴，随时看，任务完成后就撕掉（标记为解决）。

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-repository

vsce是 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 会弹出提示，你也可以在扩展面板（Ctrl+Shift+X）中看到它。

实操心得：从源码安装时，如果遇到vsce命令未找到，需要先全局安装它：npm install -g @vscode/vsce。另外，在开发过程中，可以使用npm run watch命令启动监听模式，这样你修改src/下的源码后，会自动重新编译，方便调试。

3.2 直接安装发布版（推荐给大多数用户）

对于绝大多数只想使用功能的用户，直接下载预编译的发布包是最快最省事的方式。

1. 访问项目的 Releases 页面 。
2. 找到最新的版本（如v0.0.2），下载附件中的.vsix文件（例如vscode-local-code-review-0.0.2.vsix）。
3. 打开 VS Code，进入扩展视图（Ctrl+Shift+X）。
4. 点击扩展视图右上角的“...”菜单，选择“从 VSIX 安装...”。
5. 在弹出的文件选择器中，找到并选中你下载的.vsix文件，即可完成安装。

或者，你也可以在终端使用命令行安装，前提是你已经下载了该文件：

code --install-extension /path/to/vscode-local-code-review-0.0.2.vsix

3.3 安装后的初步检查与配置

安装完成后，无需复杂配置，扩展即可工作。但为了获得最佳体验，建议进行以下检查：

1. 确认安装：在 VS Code 扩展面板中，搜索 “Local Code Review”，应能看到它并显示“已启用”。
2. 查看状态栏：打开一个 Git 仓库中的项目，VS Code 窗口左下角的状态栏应该会出现一个类似💬 0的图标，显示当前分支的未解决评论数量。这是扩展正常运行的主要标志。
3. 快捷键确认：默认的添加评论快捷键是Cmd+Shift+R（Mac）或Ctrl+Shift+R（Windows/Linux）。你可以在 VS Code 的键盘快捷键设置（Ctrl+K Ctrl+S）中搜索 “Add Comment” 来查看或修改它。

注意事项：该扩展重度依赖 VS Code 的内置 Git 功能来识别当前分支。请确保你打开的是一个 Git 仓库的根目录或子目录，并且 VS Code 的源代码管理视图能正常检测到 Git 信息。如果状态栏不显示评论计数，首先检查当前文件夹是否在 Git 仓库中。

4. 核心功能使用详解与实操技巧

4.1 添加与管理代码评论

添加评论是核心操作，有以下几种方式：

• 快捷键：将光标置于目标行，或选中多行代码，按下Cmd/Ctrl+Shift+R。
• 右键菜单：在编辑器内右键点击，选择上下文菜单中的 “Add Comment”。
• 命令面板：按下Cmd/Ctrl+Shift+P，输入 “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。

操作流程：

1. 使用 Git 命令或 VS Code 源代码管理视图切换分支到hotfix/patch-1。
2. 你会发现，状态栏的评论计数很可能变成了 0，编辑器里feature/login分支的评论高亮也消失了。
3. 这是因为扩展自动过滤了数据，只显示branch字段为hotfix/patch-1的评论。
4. 你在hotfix分支上修复 Bug 时，也可以添加新的评论（这些评论的branch字段会被自动记录为hotfix/patch-1）。
5. 修复完成后，切换回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）接到指令后的理想处理流程：

1. 读取与解析：AI 读取.claude-review.json文件，解析 JSON 数组。
2. 过滤任务：筛选出status: "open"的条目。同时，一个负责任的 AI 可能会检查branch字段是否与当前 Git 分支匹配，以避免修改错误分支的代码（虽然 AI 不一定有分支上下文，但这是一个好习惯）。
3. 顺序处理：通常按文件或行号顺序处理每个条目，避免混乱。
4. 定位与理解：AI 打开file指定的文件，滚动到line（和endLine）指定的位置，阅读周围的代码上下文，精确理解comment的意图。
5. 执行修改：AI 根据评论要求进行代码修改。这可能包括重构、修复 Bug、优化性能、添加注释等。
6. 更新状态：修改完成后，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）。
• 检查3：VS Code 的 Git 功能是否正常？有时 VS Code 的 Git 扩展可能被禁用或出现问题。尝试在 VS Code 的命令面板（Ctrl+Shift+P）中执行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 中，最好在每个子包内部单独使用这个扩展，而不是在根目录使用。