内容
# 代码游览
在 IDE 中托管一个小型 MCP 服务器，以便 [Claude 代码](https://docs.anthropic.com/claude/code) 驱动引导式代码游览：预先填充一个有序的项目列表 — 每个项目包含一个文件 + 行内提示解释 + 可选的区域高亮 — 用户从 IDE 中的工具窗口导航。
## 安装插件
两种方法：
- **从发布 ZIP（推荐）**：从 [Releases](https://github.com/h0tk3y/ide-tour-plugin/releases) 下载最新的 `ide-tour-plugin-<version>.zip`。在 IntelliJ 中：**设置 → 插件 → ⚙ → 从磁盘安装插件…** → 选择 ZIP → 重启 IDE。
- **从源码**：`./gradlew buildPlugin`，然后从 `build/distributions/` 安装 ZIP。
针对 IntelliJ 平台 2025.1 进行编译；未声明上限，因此它也可以在较新的 EAP 中加载。
## 连接到 Claude 代码
两个单行命令，每个机器一次。从任意目录：
```sh
# 1. 在用户级 Claude 代码配置中注册 MCP 服务器（-s user）。
claude mcp add -s user --transport http intellij-tour http://127.0.0.1:64343/mcp
# 2. 安装配套技能，以便 Claude 知道如何使用工具。
mkdir -p ~/.claude/skills/intellij-mcp-code-tour && \
curl -sSL https://github.com/h0tk3y/ide-tour-plugin/releases/latest/download/intellij-mcp-code-tour.md \
-o ~/.claude/skills/intellij-mcp-code-tour/SKILL.md
```
这两个步骤都针对用户级配置，因此游览技能在您用 Claude 代码打开的每个项目中都可用。（`claude mcp add` 默认采用 `local`/项目范围，因此 `-s user` 使服务器全局化。）对于项目范围的连接，请在第一个命令中将 `-s user` 替换为 `-s project`（在运行命令的旁边写入 `.mcp.json`），并将技能放在 `<repo>/.claude/skills/intellij-mcp-code-tour/SKILL.md`。
如果 `mcp__intellij-tour__*` 未出现在工具列表中，或者 `/intellij-mcp-code-tour` 未被识别为技能，请重启 Claude 代码。
## 工作原理
当您在 IntelliJ 中打开一个项目时，插件会在 `127.0.0.1:64343/mcp` 启动一个 HTTP MCP 服务器。Claude 连接并使用这些工具：
| 工具 | 用途 |
|---|---|
| `start_tour` / `end_tour` | 分配（可选地在一次调用中填充项目）/ 释放游览 |
| `add_items` / `set_items` |追加更多项目 / 替换项目列表 |
| `update_item` / `remove_item` / `list_items` | 精确编辑和检查 |
| `goto_item` / `next_item` / `prev_item` / `get_current_item` | 导航（和轮询）|
| `navigate` | 无状态的 `file:line` 跳转，无需游览 |
每个项目都表现为：
- 文件顶部/底部/末尾的 **行内提示**，带有状态前缀（✓ 已通过 / ▶ 当前 / ○ 未来）。
- 标记相关代码区域的 **范围高亮器**。
**代码游览** 工具窗口（右侧）显示活动游览的项目列表，带有“上一项”/“下一项”/“停止”图标按钮；单击项目即可跳转。**状态栏小部件** 显示当前位置。同一时间只能看到一个游览 — 切换游览会隐藏前一个并显示新的。
## 烟雾测试
安装 + 连接完成后，在 IntelliJ 中打开一个项目：
```sh
curl -sS -X POST http://127.0.0.1:64343/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 200
```
返回一个 JSON 信封，列出工具。
## 开发
```sh
./gradlew runIde # 带有预安装插件的沙盒 IDE
./gradlew buildPlugin # 生成可侧载的 ZIP
```
在沙盒中启用自动重新加载（`-Didea.auto.reload.plugins=true`）；在另一个 shell 中重新编译会热交换插件，无需重启沙盒。插件是卸载安全的 — `DynamicPluginListener` 在类加载器释放之前干净地停止 HTTP 服务器 + 其线程池。
## 布局
```
src/main/
├── kotlin/com/gradle/idetour/
│ ├── PluginStartupActivity.kt # 在首次打开项目时启动 MCP 服务器
│ ├── PluginUnloadListener.kt # 在类加载器卸载前停止服务器
│ ├── mcp/ # MCP HTTP 服务器 + JSON-RPC 帧
│ │ ├── McpServerService.kt
│ │ ├── McpHttpHandler.kt
│ │ ├── McpProtocol.kt
│ │ ├── ToolRegistry.kt
│ │ └── tools/ # 每个 MCP 工具一个文件
│ ├── tours/ # 游览状态、行内渲染、物化
│ └── ui/ # 工具窗口面板 + 状态栏小部件
└── resources/META-INF/plugin.xml # 插件描述符
skill/
└── intellij-mcp-code-tour.md # 配套 Claude 代码技能；与每个版本一起发布
```
## 版本发布
基于标签驱动。推送一个 `v*` 标签（例如 `v0.1.0`），`.github/workflows/release.yml` 构建插件并将 ZIP 附件到 GitHub 发布中，附带自动生成的注释。
