Claude Code 深度学习手册

主题

IDE 集成（VS Code/JetBrains） ​

Claude Code 通过 VS Code 扩展（原生图形面板）和 JetBrains 插件深度集成进 IDE，提供可视化 diff、选区上下文、@-mention、诊断共享与计划评审等能力。

你的真实情况 ​

从你机器看不到 IDE 集成痕迹（无 ~/.claude/ide/），也就是你目前是纯 CLI 用，没接 VS Code / JetBrains 扩展。

如果哪天想接（不接就跳过本节）：

  • VS Code 系（含 Cursor/Windsurf）：装 anthropic.claude-code 扩展；你前端在 kj-frontend 改 Vue，内联 diff + @文件 会比终端顺。
  • JetBrains 系：装 Claude Code [Beta] 插件后重启 IDE。
  • 接上后会有个内置 ide MCP（本地随机高位端口），扩展和 CLI 共享同一份 ~/.claude 配置——你这套 settings/CLAUDE.md/MCP 不用重配。

没接 IDE 完全不影响——你现在 CLI 这套已经全功能。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

Claude Code 的 IDE 集成有两条路径。VS Code（及 Cursor/Windsurf/Kiro 等 fork）通过 anthropic.claude-code 扩展提供原生图形面板：可评审/编辑 Claude 的计划、自动接受编辑、按行范围 @-mention 文件、查看会话历史、多标签并行会话；扩展同时内置 CLI 可在集成终端调用。JetBrains 系（IntelliJ/PyCharm/WebStorm/PhpStorm/GoLand/Android Studio）通过 Claude Code [Beta] 插件集成，提供交互式 diff、选区/标签上下文共享、文件引用快捷键、诊断自动共享。两条路径背后由一个本地 ide MCP server 把 CLI 与 IDE 打通（diff、选区读取、Jupyter 执行）。注：抓取的官方 /en/ide-integrations 实际重定向到 VS Code 专页，JetBrains 内容在 /en/jetbrains 独立页。

怎么工作 ​

  • VS Code 扩展提供原生图形面板（Spark 图标），可在 Editor Toolbar / Activity Bar / Status Bar / Command Palette 打开；扩展本身内置 CLI，可在集成终端调用。
  • 扩展激活时会本地起一个名为 ide 的内置 MCP server，CLI 自动连接它，用于在 VS Code 原生 diff 查看器打开 diff、读取当前选区做 @-mention、以及在 Jupyter 中执行 cell。该 server 对 /mcp 隐藏（无需配置）。
  • 内置 IDE MCP server 绑定到 127.0.0.1 的随机高位端口，外部机器不可达；每次扩展激活生成全新随机 auth token，写入 ~/.claude/ide/ 下的 lock 文件，权限 0600（目录 0700），仅当前用户可读。
  • MCP server 实际托管约 12 个工具，但只有 2 个对模型可见：mcp__ide__getDiagnostics(读取语言服务器诊断，只读) 和 mcp__ide__executeCode(在活动 Jupyter notebook 的 Python kernel 跑代码，会写)，其余是 CLI 内部 RPC，已在工具列表传给 Claude 前过滤掉。
  • 选区与打开文件上下文：连接期间 CLI 把当前编辑器选区与活动文件路径作为上下文附加到每条 prompt，transcript 显示 ⧉ Selected N lines from <file>；可用 Read deny rule 排除敏感文件（如 .env）。
  • mcp__ide__executeCode 永远先问：每次调用把代码作为新 cell 插到 notebook 末尾、滚动到视图，并弹原生 Quick Pick 让你 Execute 或 Cancel；Esc 取消则返回错误不运行。无活动 notebook、未装 ms-toolsai.jupyter、kernel 非 Python 时直接拒绝。
  • 编辑流程：Claude 要改文件时显示原始与提议改动的并排 diff 并请求许可；若你在接受前直接编辑 diff 内容，Claude 会被告知文件已被你修改。
  • JetBrains 通过专用插件集成，提供交互式 diff、选区上下文共享、文件引用快捷方式、诊断（lint/语法错误）自动共享；/ide 命令把外部终端的 Claude Code 连到 IDE。
  • 扩展与 CLI 共享同一份会话历史：扩展会话可用 claude --resume 在终端续接；反之亦然。

怎么配置 / 用法 ​

配置入口分两类：

【VS Code 扩展设置】(VS Code Settings → Extensions → Claude Code，或在 prompt 框输入 / 选 General Config)，全部带 claudeCode. 前缀，常用键：

  • claudeCode.useTerminal (默认 false)：改用终端模式而非图形面板
  • claudeCode.initialPermissionMode (默认 default)：新会话默认权限模式，可选 default / plan / acceptEdits / bypassPermissions
  • claudeCode.preferredLocation (默认 panel)：Claude 打开位置 sidebar(右) / panel(新标签)
  • claudeCode.autosave (默认 true)：读写文件前自动保存
  • claudeCode.useCtrlEnterToSend (默认 false)：用 Ctrl/Cmd+Enter 发送
  • claudeCode.enableNewConversationShortcut (默认 false)：启用 Cmd/Ctrl+N 新建会话
  • claudeCode.enableReopenClosedSessionShortcut (默认 true)：Cmd/Ctrl+Shift+T 重开关闭会话
  • claudeCode.hideOnboarding (默认 false)
  • claudeCode.respectGitIgnore (默认 true)
  • claudeCode.usePythonEnvironment (默认 true，需 Python 扩展)
  • claudeCode.environmentVariables (默认 [])
  • claudeCode.disableLoginPrompt (默认 false，第三方 provider 用)
  • claudeCode.allowDangerouslySkipPermissions (默认 false)
  • claudeCode.claudeProcessWrapper：自定义启动 claude 进程的可执行文件

【共享设置】~/.claude/settings.json（扩展与 CLI 共用，存放 allowed commands / 环境变量 / hooks / MCP）。建议加 "$schema": "https://json.schemastore.org/claude-code-settings.json" 获得自动补全。

【JetBrains 插件设置】Settings → Tools → Claude Code [Beta]：

  • Claude command：自定义启动命令，如 claude / /usr/local/bin/claude / npx @anthropic-ai/claude-code；WSL 用 wsl -d Ubuntu -- bash -lic "claude"
  • Suppress notification for Claude command not found
  • Enable using Option+Enter for multi-line prompts (仅 macOS，改后需重启终端)
  • Enable automatic updates（重启时应用）
  • diff 工具：claude 里运行 /config，diff tool 设 auto(IDE 内显示) 或 terminal

启动命令：

  • VS Code：集成终端跑 claude；外部终端跑 /ide 连接
  • 并行：claude --worktree feature-auth（别名 -w）
  • 从扩展续接 CLI：claude --resume
  • URI 打开新标签：vscode://anthropic.claude-code/open?prompt=review%20my%20changes（参数 prompt 需 URL 编码，session 传 session ID）

什么时候用 ​

  • 在 VS Code 里要图形化、可视化 diff、计划评审与多会话并行 → 用 VS Code 扩展（推荐）。
  • 需要 CLI 独有能力（! bash、Tab 补全、完整命令/skills/MCP 配置）→ 在集成终端跑 claude。
  • 用 JetBrains 系 IDE → 装 Claude Code [Beta] 插件，集成终端跑 claude，外部终端用 /ide 连接。
  • 处理不可信代码 → 关掉 auto-accept、用手动审批、开 Restricted Mode。
  • 并行多任务且要隔离 → claude --worktree。

限制 / 坑 ​

  • VS Code 扩展是 CLI 功能的子集：! bash 快捷不支持、Tab 补全不支持、命令与 skills 只有部分（输入 / 看可用）；MCP 只能部分管理（用 CLI claude mcp add 加，扩展内用 /mcp 管理已有）。
  • 扩展对后台/长运行任务的可见性弱于 CLI，建议让 Claude 输出命令到集成终端自行运行以便观察。
  • 需 VS Code 1.98.0 或更高；低于此版本 Spark 图标不显示、扩展可能装不上。
  • Spark 图标只有在打开了文件时才出现在 Editor Toolbar（仅开文件夹不够）；Restricted Mode 下扩展不工作。
  • macOS Tahoe 及以后系统 Game Overlay 默认占用 Cmd+Esc，会拦截导致快捷键失效，需在系统设置里清掉或在 VS Code 重绑。
  • 若 shell 设了 ANTHROPIC_API_KEY 但仍弹登录，多半是 VS Code 没继承 shell 环境，需从终端用 code . 启动。
  • claude.ai 远程会话只有用 GitHub repo 启动的 web session 才出现在 Remote 标签；resume 只把对话历史下载到本地，改动不回同步到 claude.ai。需以 Claude.ai Subscription 登录（非 Anthropic Console）。
  • allowDangerouslySkipPermissions 只应在无网络的 sandbox 中使用。
  • auto-edit 权限下 Claude 可改 VS Code/JetBrains 会被自动执行的配置文件（如 settings.json、tasks.json），可能绕过 bash 执行的权限提示，存在风险。
  • JetBrains：Remote Development 必须把插件装在 remote host（Settings → Plugin (Host)），不是本地客户端。
  • JetBrains 插件当前是 [Beta]（设置项名 Claude Code [Beta]）。
  • WSL2 下 JetBrains 可能报 'No available IDEs detected'，因 WSL2 NAT 网络或 Windows 防火墙阻断；WSL1 不受影响。mirrored 网络模式需 Windows 11 22H2 或更高。

硬事实速查（38 条） ​

  • 官方原 URL https://code.claude.com/docs/en/ide-integrations 实际重定向到 VS Code 页（标题 'Use Claude Code in VS Code'）；JetBrains 内容在独立页 /en/jetbrains。
  • VS Code 前置要求：VS Code 1.98.0 或更高 + Anthropic 账号。
  • 扩展 ID：anthropic.claude-code；安装链接 vscode:extension/anthropic.claude-code，Cursor 用 cursor:extension/anthropic.claude-code。
  • 可在 Windsurf/Kiro 等 VS Code fork 安装，或从 Open VSX 注册表 https://open-vsx.org/extension/Anthropic/claude-code 安装。
  • 打开扩展视图：Cmd+Shift+X (Mac) / Ctrl+Shift+X (Win/Linux)，搜 'Claude Code'。
  • Spark 图标出现在 Editor Toolbar（需打开文件）；Activity Bar 左栏图标常驻显示会话列表；Status Bar 右下角 '✱ Claude Code' 即使没开文件也可用。
  • 快捷键 Focus Input：Cmd+Esc (Mac) / Ctrl+Esc (Win/Linux)，在编辑器与 Claude 间切焦点。
  • Open in New Tab：Cmd+Shift+Esc / Ctrl+Shift+Esc。
  • New Conversation：Cmd+N / Ctrl+N（需 Claude 聚焦且 enableNewConversationShortcut=true）。
  • Reopen Closed Session：Cmd+Shift+T / Ctrl+Shift+T（由 enableReopenClosedSessionShortcut 控制，默认 true）。
  • Insert @-Mention Reference：Option+K (Mac) / Alt+K (Win/Linux)，插入如 @app.ts#5-10（需编辑器聚焦）。
  • 多行输入：Shift+Enter 加新行不发送。
  • 展开/折叠所有 thinking block：Ctrl+O。
  • 命令菜单（输入 /）含：附加文件、切模型、切 extended thinking、/usage 看用量、/remote-control 启 Remote Control、/compact 手动压缩、Customize 区访问 MCP/hooks/memory/permissions/plugins。
  • @-mention 支持模糊匹配；文件夹要带结尾斜杠（如 @src/components/）；大 PDF 可让 Claude 读指定页/页范围。
  • 选区指示器：footer 显示选中行数；点击可切换 Claude 是否可见高亮文本，eye-slash 图标表示对 Claude 隐藏。
  • 拖文件入 prompt 框时按住 Shift 作为附件添加；点附件上的 X 移除。
  • URI handler：vscode://anthropic.claude-code/open，可带 query 参数 prompt（需 URL 编码，预填不自动提交）与 session（session ID，须属于当前 workspace）。
  • macOS 打开 URI：open '...'；Linux：xdg-open '...'；Windows PowerShell：Start-Process '...'，cmd.exe：start "" '...'（空标题占位）。
  • 终端模式：勾选 Use Terminal setting (vscode://settings/claudeCode.useTerminal)。
  • 插件管理：prompt 框输入 /plugins 开 Manage plugins，含 Plugins 与 Marketplaces 两标签；安装作用域 Install for you(user) / Install for this project(project) / Install locally(local)。
  • Chrome 自动化：需 Claude in Chrome 扩展 1.0.36 或更高，prompt 用 @browser。
  • 终端输出引用：@terminal:name（name 为终端标题）。
  • 内置 IDE MCP server 名为 ide，绑 127.0.0.1 随机高位端口；auth token 写 ~/.claude/ide/ 下 lock 文件，文件 0600、目录 0700。
  • 对模型可见的 IDE 工具仅 2 个：mcp__ide__getDiagnostics（只读，返回 Problems 面板诊断）与 mcp__ide__executeCode（写，跑 Jupyter Python cell）。
  • mcp__ide__executeCode 每次弹原生 Quick Pick 要 Execute/Cancel，独立于 PreToolUse hook；无 notebook / 未装 ms-toolsai.jupyter / kernel 非 Python 时拒绝。
  • 排除敏感文件选区上下文：对其路径加 Read deny rule（同时屏蔽选中文本与 open-file 提示）。
  • CLI vs 扩展差异表：Checkpoints 两者都有；! bash 快捷与 Tab 补全仅 CLI；命令/skills 扩展为子集；MCP 扩展为部分。
  • Checkpoints：悬停消息显 rewind 按钮，3 选项 Fork conversation from here / Rewind code to here / Fork conversation and rewind code。
  • Git worktree：claude --worktree <name>（-w）。
  • JetBrains 支持 IDE：IntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、GoLand。
  • JetBrains 插件：Claude Code [Beta]，市场地址 https://plugins.jetbrains.com/plugin/27310-claude-code-beta- ，装后需重启 IDE（可能要多次）。
  • JetBrains 快捷键：Cmd+Esc / Ctrl+Esc 快速启动；文件引用 Cmd+Option+K (Mac) / Alt+Ctrl+K (Linux/Win) 插入如 @src/auth.ts#L1-99。
  • JetBrains diff 配置：/config 里 diff tool 设 auto(IDE 内) 或 terminal。
  • JetBrains 插件设置路径：Settings → Tools → Claude Code [Beta]；ESC 中断问题在 Settings → Tools → Terminal 取消 'Move focus to the editor with Escape' 或删 'Switch focus to Editor' 快捷键。
  • WSL2 防火墙修复：hostname -I 取子网，PowerShell(管理员) 跑 New-NetFirewallRule ... -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16；或 .wslconfig 加 [wsl2] networkingMode=mirrored（需 Win11 22H2+），再 wsl --shutdown。
  • 卸载并清数据：rm -rf ~/.vscode/globalStorage/anthropic.claude-code。
  • 添加 MCP：claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"。

官方出处：[https://code.claude.com/docs/en/ide-integrations （重定向至 https://code.claude.com/docs/en/vs-code「Use Claude Code in VS Code」）；JetBrains 部分来自 https://code.claude.com/docs/en/jetbrains](https://code.claude.com/docs/en/ide-integrations （重定向至 https://code.claude.com/docs/en/vs-code「Use Claude Code in VS Code」）；JetBrains 部分来自 https://code.claude.com/docs/en/jetbrains)