Claude Code SDK #14：IDE 集成全解——`--ide` 标志、内置 MCP 服务器、诊断信息流与多目录权限

Claude Code SDK #14：IDE 集成全解——`--ide` 标志、内置 MCP 服务器、诊断信息流与多目录权限

装上 VS Code 扩展或 JetBrains 插件只是开始。本篇完整拆解 `--ide` 标志的自动接线逻辑、内置 IDE MCP 服务器如何把 lint/编译报错实时流入 Claude 上下文（`mcp__ide__getDiagnostics`）、Jupyter 代码执行的安全确认机制、JetBrains WSL2 接线的两种方案，以及 `--add-dir` 多目录权限与「文件访问 ≠ 配置加载」的关键限制，附五条可落地的实践建议。

Claude Code SDK 每日技术拆解
Claude Code SDK 每日技术拆解@wei
2026/6/7 · 9:11
購読 3 件 · コンテンツ 48 件

Claude Code SDK #14：IDE 集成全解——--ide 标志、内置 MCP 服务器、诊断信息流与多目录权限，把 Claude 变成真正感知 IDE 状态的 AI 协作者

多数人用 Claude Code 的方式是：装上 VS Code 扩展，打开侧边面板，开始聊代码。
这没问题，但你可能错过了最有价值的部分：Claude 能看见你的报错面板、知道你光标选中了哪几行、实时感知 lint/编译警告——前提是你理解 IDE 集成背后的机制，而不只是把它当个聊天窗口用。
本篇完整拆解 VS Code 扩展的核心功能、JetBrains 插件的接线方式、--ide 标志的工作原理、内置 IDE MCP 服务器的安全设计，以及 --add-dir 多目录权限体系。

VS Code 扩展：不只是侧边面板

VS Code 扩展是 Anthropic 官方推荐的集成方式，装好后提供：
  • 原生 Diff 视图：Claude 要修改文件时，直接在 VS Code 的并排 Diff 界面展示变更，而不是在终端打印 patch。你可以在 Diff 视图里直接手改 Claude 的提案再接受——扩展会告知 Claude「用户修改过」，Claude 不会误以为文件与它的预期一致。
  • @-mention 选区引用：光标选中代码后，按 Option+K（Mac）或 Alt+K（Windows/Linux），提示框自动插入 @auth.ts#5-10 这样的精确引用。Claude 会自动感知你当前选中的文本；点击提示框底部的眼睛图标可切换是否让 Claude 看见选区——有时候你打开了含密钥的 .env 文件，关掉这个防止泄漏。
  • 多会话并行：用 Command Palette 里的「Open in New Tab」开多个对话，每个维护独立历史和上下文，适合同时在不同任务上让 Claude 推进。
  • Plan 模式：切换到 Plan 模式后，Claude 先生成一份 Markdown 计划文档，你可以加行内注释再让它执行，避免直接跑出意外修改。1

内置 IDE MCP 服务器：诊断信息如何流入 Claude

这是最容易被忽视的机制。
扩展启动后，会在本机 127.0.0.1 的随机高端口起一个本地 MCP 服务器（服务名：ide）。CLI 启动时自动连接，每次你发送 prompt，Claude 就能读到：
  • 当前打开文件的路径
  • 你选中的代码行
而 Claude 还有两个通过 MCP 暴露给它的工具：1
工具名（Hooks 里看到的名字）作用写操作？
mcp__ide__getDiagnostics读取 VS Code Problems 面板的 lint/语法/编译报错，可指定单个文件否
mcp__ide__executeCode在 Jupyter Notebook 激活的 kernel 里执行 Python 代码，每次都需确认是
**诊断信息（Diagnostics）**是关键。这意味着当 TypeScript 报了类型错误、ESLint 标了 lint 警告、Python 扩展检测到语法问题，Claude 可以直接通过 mcp__ide__getDiagnostics 拿到这份报错列表——不需要你复制粘贴错误信息，也不需要 Claude 猜。这才是「实时感知 IDE 状态」的核心。
安全设计：每次扩展启动都生成新的随机 auth token，写入 ~/.claude/ide/ 目录下的锁文件（0600 权限，目录为 0700），只有运行 VS Code 的用户能读。IDE MCP 服务器不对外网开放，不会在 /mcp 里出现（因为没有用户侧配置）。如果你的组织有 PreToolUse Hook 做工具白名单，需要把 mcp__ide__getDiagnostics 手动加进去。
代码编辑器中的暗色主题编程环境
IDE 内置 MCP 服务器通过随机端口绑定本机，让 Claude 实时读取 Problems 面板的诊断信息，无需手动复制报错 1

JetBrains 插件：同一套机制，不同的接线方式

支持的 IDE 覆盖 IntelliJ IDEA、PyCharm、WebStorm、GoLand、PhpStorm、Android Studio。
安装很简单：JetBrains Marketplace 搜索「Claude Code Beta」，安装后重启 IDE。2
功能上和 VS Code 基本对等：
  • 原生 Diff 视图（可在 /config 里把 diff tool 设为 auto 启用）
  • 选区自动上下文共享（Cmd+Option+K / Alt+Ctrl+K 插入文件引用）
  • 诊断信息（lint/语法错误）自动流入 Claude
有一个地方不同：JetBrains 没有内置图形面板，Claude Code 运行在 IDE 的集成终端里。
从外部终端接线：如果你不用 IDE 的集成终端，而是喜欢用外部 terminal，可以在任意 terminal 里跑：
claude
/ide
在 Claude 会话里输入 /ide 命令，Claude Code 会主动连接当前检测到的 JetBrains IDE，激活选区共享和诊断流。
WSL 用户注意：WSL2 的 NAT 网络模式默认会阻断 WSL2 与宿主机 Windows 上 JetBrains IDE 的连接，导致「No available IDEs detected」。两种解法：一是在 Windows Firewall 里为 WSL2 子网添加放行规则；二是在 .wslconfig 设置 networkingMode=mirrored（需 Windows 11 22H2+）。
笔记本电脑屏幕展示代码编辑器中的编程代码
JetBrains 在外部终端中运行 /ide 命令可手动连接 IDE，激活选区共享和诊断流 2

--ide 标志：自动接线的快捷方式

CLI 的 --ide 标志作用很直接：3
claude --ide
当本机只有一个可用的 IDE 连接时，自动连接，等价于手动输入 /ide。适合把 Claude Code 写进启动脚本或 shell 别名的场景——每次开一个新的 Claude 会话，不需要手动输 /ide。
如果本机有多个 IDE 同时打开（比如同时开着 VS Code 和 IntelliJ），--ide 不会自动选择，Claude 会列出可用 IDE 让你选。
对于 VS Code 扩展，--ide 场景很少用到——扩展自己会在 CLI 启动时处理连接。这个标志主要给 JetBrains 用户或在外部终端里直接跑 claude 的用户提供便利。

多目录权限：--add-dir 与 additionalDirectories

Claude Code 默认只能读写启动目录（即工作目录）里的文件。前端 monorepo 跑 claude 的地方是 apps/web/，但 Claude 无法直接读 packages/ui/ 的组件源码——这时候就需要 --add-dir。

三种授权方式

# 单次会话扩展访问：启动时指定
claude --add-dir ../packages/ui ../lib/shared

# 会话中途扩展：输入命令
/add-dir ../packages/ui

# 持久化：写入 settings.json
# ~/.claude/settings.json 或项目 .claude/settings.json
{
  "permissions": {
    "additionalDirectories": ["../packages/ui", "../lib/shared"]
  }
}
额外目录里的文件遵循和主工作目录相同的权限规则：读取默认不需要权限提示，文件编辑跟随当前权限模式。4

重要限制：文件访问 ≠ 配置加载

这是一个容易踩的坑。用 --add-dir 添加额外目录时，只授予文件读写访问，不会加载该目录的大多数 .claude/ 配置。
具体哪些会加载、哪些不会：
配置项能从 --add-dir 目录加载？
.claude/skills/ 里的 Skills✅ 支持，且热重载
.claude/settings.json 里的 enabledPlugins / extraKnownMarketplaces✅ 部分支持
CLAUDE.md / .claude/rules/ / CLAUDE.local.md❌ 需要环境变量 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 才加载
Hooks 和其他 settings.json 配置❌ 只从主工作目录的 .claude/ 和 ~/.claude/settings.json 加载
子代理、命令、输出样式❌ 只从主工作目录及其父目录、~/.claude/ 加载
这意味着：如果你的 monorepo 各子包各有 .claude/settings.json 配置了不同的 Hooks，--add-dir 加进来的子包 Hooks 不会生效。需要整合的 Hooks 必须放在主工作目录的 .claude/ 或用户级 ~/.claude/settings.json 里。
另外，通过 permissions.additionalDirectories（settings 文件持久化）添加的目录比 --add-dir 更严格：只授予文件访问，连上述有限的 Skills 加载也不做。
软件开发者在多目录工作区进行编程工作
--add-dir 授予文件访问权限，但 Hooks/子代理等配置仍只从主工作目录加载——monorepo 场景需要把核心配置集中放在启动目录 4

五条实践建议

1. 关掉 .env 和敏感文件的选区共享 VS Code 里打开 .env 时，点提示框底部的眼睛图标关闭选区传递；或者在权限设置里给 .env 加 Read deny 规则——这同时阻断选区共享和主动读取。
2. 用 mcp__ide__getDiagnostics 触发报错分析 你不需要手动复制错误信息。直接在 Claude 提示框里说「帮我修这个文件的类型错误」，Claude 会自动调用 getDiagnostics 拿到 VS Code Problems 面板的完整报错列表，比粘贴截图精确得多。
3. JetBrains 远程开发记得装在远端 JetBrains Remote Development 场景下，插件必须安装在远端宿主机，不是本地客户端。装错位置会导致 IDE 功能完全不可用，但错误提示不明显。
4. Monorepo 多目录工作流用 --add-dir + 主目录集中 Hooks claude --add-dir ../packages/ui ../packages/api 授予文件访问，所有 Hooks 和权限规则统一放在主工作目录的 .claude/settings.json，不要依赖子目录的配置会被自动加载。
5. --ide 写进 shell alias 让自动接线成默认行为
alias claude-dev='claude --ide --append-system-prompt "项目约定：..."'
每次在 JetBrains 集成终端外跑 Claude 时自动连上 IDE，省去每次手输 /ide。

参考ソース

  1. 1VS Code 集成官方文档
  2. 2JetBrains 集成官方文档
  3. 3CLI 参考文档
  4. 4权限配置文档
Claude Code SDK 每日技术拆解
Claude Code SDK 每日技术拆解

このコンテンツについて、さらに観点や背景を補足しましょう。

  • ログインするとコメントできます。