Claude Code SDK #27：VS Code Extension 全解——@mentions × diff review × IDE MCP，把上下文和回滚放进编辑器

你把 Claude Code 当终端工具用，往往会卡在两件事：上下文要手动贴，改动要离开编辑器再检查。VS Code Extension 的价值就在这里：它把「选中代码 → 传上下文 → 审计划 → 看 diff → 回滚」这条链路放进 IDE 里，而不是让你在终端和编辑器之间来回搬运。官方文档也把 VS Code 里的原生图形界面称为推荐使用方式之一；它支持审阅并编辑计划、自动接受编辑、用 @ mention 引用带行号的文件、访问会话历史，并在多个标签页或窗口里开多条对话。1

这期不重复 #14 的 --ide 总览，专门拆 VS Code Extension：它到底帮你传了什么上下文，哪些能力仍然要回到 CLI，权限和回滚该怎么配。

1. 先把边界说清楚：Extension 不是 CLI 的皮肤

安装前有两个硬条件：VS Code 需要 1.98.0 或更高版本；账号侧可以用付费 Claude 订阅或 Claude Console 登录，首次打开扩展时不需要自己填 API key。1

更容易踩坑的是 CLI 边界：扩展的聊天面板自带一份 CLI，但如果你想在 VS Code 集成终端里直接敲 claude，仍然要单独安装 standalone CLI。换句话说，面板能用，不代表 shell 里的 claude 已经在 PATH 里。1

VS Code 编辑器右上角的 Claude Spark 图标 — *文件打开后，Spark 图标会出现在编辑器工具栏；也可以从 Activity Bar、Command Palette 或 Status Bar 打开 Claude Code。1*

我建议把 Extension 当成「日常交互入口」，把 CLI 当成「低层能力入口」。需要图形化 diff、选中代码、会话标签页时用面板；需要完整命令、skills、MCP server 配置、! bash shortcut 或 tab completion 时，直接回到终端。官方的对比表也明确写了：Extension 的命令和 skills 是子集，MCP server 配置是部分支持，而 ! bash shortcut 和 tab completion 只在 CLI 里有。1

2. 上下文入口：别再整段复制代码

Extension 最顺手的地方，是它默认知道你在编辑器里选中了什么。你选中一段代码后，Claude 可以看到这段选区；再按 Option+K（Mac）或 Alt+K（Windows/Linux），还能把它插入成类似 @file.ts#5-10 的引用。1

这和手动复制代码有两个差异。

第一，它保留文件路径和行号。你问「这段鉴权逻辑为什么会漏掉 token refresh」时，Claude 不只看到代码片段，还知道它来自哪个文件的哪几行。

第二，它可以按文件或文件夹补上下文。文档里写到，输入 @ 后接文件或文件夹名可以做 fuzzy matching；引用文件夹时，路径末尾加 /。大 PDF 也可以只让 Claude 读取指定页码或页码范围，而不是一口气塞完整文件。1

在 VS Code 中选中代码并插入 @ mention — *选区可以自动进入上下文，`Option+K` / `Alt+K` 会把当前文件和行号插入 prompt。1*

安全上也别偷懒。选区指示器可以切换是否让 Claude 看到高亮内容；如果某类文件永远不该进上下文，比如 .env，后面要配 Read deny rule。VS Code 文档在内置 IDE MCP 章节里明确说，匹配的 deny rule 会阻止选中文本和打开文件提示进入 Claude。1

3. 修改链路：Plan、diff、permission mode 要一起看

在 VS Code 面板里，prompt 输入框底部可以切换 permission mode。普通模式下，Claude 每次行动前会请求确认；Plan mode 会先描述计划并等待批准，VS Code 还会把计划打开成完整 Markdown 文档，方便你加 inline comments；auto-accept mode 则会让 Claude 直接改文件。默认模式可以用 claudeCode.initialPermissionMode 配。1

如果只看模式名，很容易误会。权限文档把几个模式的取舍写得更直白：default 默认只自动读；acceptEdits 可以自动读、编辑文件和跑常见文件系统命令；plan 仍然只读，适合先摸清代码库；auto 会减少 routine prompts，但要经过后台安全检查；bypassPermissions 只适合隔离容器或 VM。2

我的默认配置是：陌生仓库用 Plan mode；熟悉模块用 acceptEdits；涉及 .github/、部署脚本、数据库迁移、密钥文件时回到 default。不要为了少点几次确认，把生产仓库开到 bypass。

Claude 准备改文件时，Extension 会在 VS Code 里展示 side-by-side diff，并请求许可。你可以接受、拒绝，或告诉 Claude 换一种做法；如果你在 diff view 里先手动改了 proposed content 再接受，Claude 会知道你改过它的原提案，不会假设文件仍等于它最初生成的版本。1

Claude Code 在 VS Code 中展示 side-by-side diff — *diff review 是 Extension 的核心优势，适合逐行检查 Claude 准备写入的改动。1*

4. 内置 IDE MCP：Extension 真正接通编辑器的地方

这一层最容易被忽略。Extension 激活时，会启动一个本地 MCP server，CLI 会自动连接它。这个 server 负责让 CLI 打开 VS Code 原生 diff、读取当前选区，并在 Jupyter notebook 场景里请求 VS Code 执行 cell。它的名字是 ide，但会从 /mcp 里隐藏，因为没有需要你手动配置的东西。1

安全模型也比「本地开个服务」四个字复杂一点：文档写到，这个 server 绑定在 127.0.0.1 的随机高端口，其他机器访问不到；每次扩展激活都会生成新的随机 auth token，CLI 连接时必须带上它；token 写在 ~/.claude/ide/ 下的 lock file，目录权限是 0700，文件权限是 0600。1

暴露给模型的工具只有两个：mcp__ide__getDiagnostics 返回 VS Code Problems 面板里的语言服务器诊断，且不写文件；mcp__ide__executeCode 会在当前 Jupyter Python kernel 里运行代码，属于写操作。后者每次都要 VS Code Quick Pick 确认，取消或按 Esc 都不会执行。1

这说明 Extension 的能力不是「让 Claude 随便操控 IDE」，而是把几个高价值、边界清楚的 IDE 能力变成受控工具：诊断、选区、diff、Jupyter 执行。

5. 会话、检查点和回滚：别把它当 Git 替代品

VS Code 面板有 Session history，可以按关键词或时间浏览会话，也能从 Claude.ai 恢复 web sessions，但远端会话需要用 Claude.ai Subscription 登录；只有从 GitHub repository 启动的 web sessions 会出现在 Remote tab。1

多任务时，Extension 可以从 Command Palette 打开新 tab 或新 window。每条对话维护自己的历史和上下文，标签上的小圆点还会提示状态：蓝色表示有 permission request，橙色表示 Claude 在隐藏标签页里完成了任务。1

Checkpoint 负责兜底。VS Code 文档说，Extension 支持 checkpoint：你可以从某条消息 fork conversation、只回滚代码、或 fork conversation 并回滚代码。1 更完整的 checkpoint 文档补充了边界：Claude 的文件编辑工具会被跟踪，每个用户 prompt 会创建一个 checkpoint；但 Bash 命令改出来的文件不在 checkpoint 回滚范围内，手动改动和其他并发会话的改动也通常不会被捕获。3

所以我的用法很简单：小步快跑靠 checkpoint，真正要留下历史靠 Git。Claude 改完一轮后先看 diff，再跑测试，最后自己决定是否 commit。

6. 今天就能照做的配置顺序

如果你准备把 VS Code Extension 纳入日常开发，我建议按这个顺序来，不要一上来就开自动化最大档：

安装扩展并确认 VS Code 版本不低于 1.98.0；如果 Spark 图标不出现，先打开一个文件，再检查版本、重载窗口和 workspace trust。1
在 VS Code 里先用默认权限模式跑一次「解释当前选区」任务，确认选区、Option+K / Alt+K 和 @ mention 都工作正常。1
给敏感文件加 Read deny rule，至少覆盖 .env、本地密钥和不该被模型读取的配置文件。1
把新仓库的默认工作流设成 Plan mode：先让 Claude 读代码、写计划、等你批注后再改。Plan mode 的目标就是先分析再编辑。2
熟悉的局部重构再切到 acceptEdits，但每轮结束都要看 VS Code diff，并用测试或类型检查验证。acceptEdits 会自动批准工作目录内的文件编辑和常见文件系统命令，别在高风险路径上偷省确认。2
需要 CLI-only 能力时别硬在面板里找：打开集成终端，确认 standalone CLI 已安装，再用 claude、claude mcp add 或 claude --resume 接管。1

一句话收尾：VS Code Extension 不是让 Claude「更会写代码」，它让上下文输入、权限确认、diff 审阅和回滚这四件事少掉摩擦。真正的收益来自流程变短，而不是把安全阀全关掉。