pi-x-ide 1.13.1 → 1.15.0

package/README.md

@@ -2,9 +2,10 @@
 
 > Pi extension package for IDE selection context integration.
 
-Automatically attaches the currently opened or selected file and text range from VS Code, Zed, and Neovim to the Pi TUI, submitting them as conversation context to the LLM.
+Automatically attaches the currently opened or selected file and text range from VS Code, Zed, Neovim, and JetBrains IDEs to the Pi TUI, submitting them as conversation context to the LLM.
+
+<img width="3822" height="2010" alt="pi-x-ide-guide" src="https://github.com/user-attachments/assets/70abe40d-e4ac-4c2e-aca7-80d2e7867945" />
 
----
 
 ## Installation & Usage
 
@@ -42,17 +43,8 @@ No extension installation is needed. Pi automatically detects Zed when running i
 
 #### Neovim
 
-Neovim support uses a Lua plugin plus a sidecar process. On first start the
-plugin downloads a standalone binary for your platform (Linux / macOS / Windows,
-x64 or arm64) from GitHub Releases and verifies it against the release asset's
-SHA-256 digest before caching it. If the download or checksum verification fails,
-or no binary matches your platform, the plugin falls back to the bundled Node.js
-sidecar — Node.js is then required on PATH.
-
-Downloaded binaries are cached under `stdpath("cache")/pi-x-ide/` and reused on
-subsequent starts. The optional lazy.nvim build hook uses the bundled binary when
-present; otherwise it checks the release digest on install and update,
-downloading only when the cached binary is missing or stale.
+Neovim support uses a Lua plugin plus a sidecar process. The plugin auto-downloads
+a platform binary on first start and falls back to Node.js if unavailable.
 
 **lazy.nvim:**
 
@@ -73,14 +65,10 @@ downloading only when the cached binary is missing or stale.
 }
 ```
 
-> **Note:** The `init` block manually adds the `ide-plugins/nvim/` subdirectory to the runtime path to avoid a Lua module resolution issue with some lazy.nvim versions. The plugin options are passed through lazy.nvim's recommended `opts` field.
->
-> The optional `build` hook resolves the bundled sidecar binary when present;
-> otherwise it checks the GitHub Release asset digest at install/update time
-> (`:Lazy build pi-x-ide` to re-run) and downloads only when the cached binary is
-> missing or stale. It is safe to omit: the plugin still downloads the binary
-> lazily on first start and falls back to the Node.js sidecar if the download is
-> unavailable.
+> **Note:** The `init` block adds the plugin subdirectory to the runtime path to
+> work around a Lua module resolution issue with some lazy.nvim versions. The
+> optional `build` hook pre-downloads the sidecar binary; it is safe to omit —
+> the plugin downloads it lazily on first start.
 
 **Native package:**
 
@@ -91,6 +79,10 @@ lua require("pi_x_ide").setup({ keymap = "<leader>pa" })
 
 See [Configuration Reference](#neovim-2) for full setup options, commands, and troubleshooting.
 
+#### JetBrains IDEs
+
+Download the latest JetBrains plugin ZIP(pi-x-ide-jetbrains-*.zip) from the [latest GitHub Release](https://github.com/balaenis/pi-x-ide/releases/latest), then install it in your JetBrains IDE via **Settings | Plugins | ⚙ | Install Plugin from Disk...**.
+
 ### Connect Pi & Verify
 
 Start Pi in the **same project directory** as your IDE workspace:
@@ -99,21 +91,26 @@ Start Pi in the **same project directory** as your IDE workspace:
 pi
 ```
 
-Pi auto-loads `pi-x-ide` and connects to your IDE. The TUI should display `IDE: vscode ✓` in the footer and a widget showing the IDE name, workspace, current file, and selection range.
+Pi auto-loads `pi-x-ide` and connects to your IDE. The TUI shows a widget above the
+editor with the current IDE connection and selection state.
 
 **Verify it works:**
 
 Open a file in your IDE and select some text. The widget should update in real time:
 
 ```
-IDE: vscode ✓ src/foo.ts#L10-L20 pending
+⧉ ⇡ foo.ts#L10-L20
 ```
 
-Attach the selection from either side: press `Ctrl+Alt+K` (Linux/Windows) or `Cmd+Alt+K` (macOS) in a VS Code-family IDE, or focus the Pi TUI and press `Ctrl+Alt+K` / run `/ide attach`. The Pi input box should insert `@src/foo.ts#L10-L20`.
+Attach the selection from either side: press `Ctrl+Alt+K` (Linux/Windows) or `Cmd+Alt+K` (macOS) in a VS Code-family IDE, press `Ctrl+Alt+K` or run **Pi x IDE: Attach Selection** in JetBrains, use `:PiXIdeAttach` in Neovim, or focus the Pi TUI and press `Ctrl+Alt+K` / run `/ide attach`. The Pi input box should insert `@src/foo.ts#L10-L20`.
 
-Type a chat prompt in Pi and submit it. The selected text is injected as LLM context (does not persist in session history). After submission, the widget shows `sent`.
+Type a chat prompt in Pi and submit it. The selected text is injected as LLM context.
+After submission, the widget changes to
+`⧉ ✓ foo.ts#L10-L20`.
 
-For diagnostics in VS Code-family IDEs, connect Pi first, then place the cursor on an error or warning and open Quick Fix. The **Pi: Fix it** and **Pi: Send diagnostic** actions are shown only while at least one Pi client is connected. **Pi: Fix it** sends the diagnostic message, source range, nearby context lines, and related information to one connected Pi client and starts a diagnostic-analysis turn with a configurable prompt template (see [`fix_prompt`](#pi-side-configuration)). **Pi: Send diagnostic** sends the same context to one connected Pi client and pastes it into Pi's input box without starting a turn.
+**Diagnostic Quick Fix (VS Code only):** place the cursor on an error or warning,
+open Quick Fix, and choose **Pi: Fix it** to send the diagnostic to Pi and start an
+analysis turn, or **Pi: Send diagnostic** to paste it into the input box.
 
 **If the connection doesn't appear:**
 
@@ -121,6 +118,20 @@ For diagnostics in VS Code-family IDEs, connect Pi first, then place the cursor
 - If the IDE was started after Pi, reload the IDE window and run `/ide auto` again.
 - Run `/ide` to manually select a connection from the list.
 
+### WSL2
+
+When Pi runs inside WSL2 and your IDE runs on native Windows, Pi automatically
+discovers the IDE connection across the WSL boundary. No extra configuration is
+needed in most cases.
+
+If your WSL networking mode, firewall, or endpoint security blocks the automatic
+discovery, set `PI_X_IDE_HOST_OVERRIDE`:
+
+```bash
+PI_X_IDE_HOST_OVERRIDE=127.0.0.1 pi
+PI_X_IDE_HOST_OVERRIDE=<windows-host-ip> pi
+```
+
 ### `/ide` Command Reference
 
 | Command        | Behavior                                                          |
@@ -156,8 +167,6 @@ Default database paths:
 - **Windows:** `%LOCALAPPDATA%\Zed\db\0-stable\db.sqlite`
 - **WSL with Windows Zed:** `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite`
 
-When Pi runs in WSL and Zed runs as a Windows app, pi-x-ide normalizes Windows paths (`C:\Users\<user>\project`) to `/mnt/c/Users/<user>/project`, and matching WSL UNC paths to `/home/<user>/project`.
-
 #### Neovim
 
 ```lua
@@ -166,14 +175,12 @@ require("pi_x_ide").setup({
   keymap = "<C-A-k>",
   debounce_ms = 150,
   -- sidecar_cmd = { "node", "/absolute/path/to/pi-x-ide-nvim-sidecar.cjs" },
-  -- (defaults to the platform binary; falls back to node + cjs if no binary found)
   -- workspace_folders = { "/path/to/project" },
 })
 ```
 
 If the sidecar does not start, run `:PiXIdeStatus`, or set `sidecar_cmd` to a
-custom command. The plugin prefers the platform binary but falls back to Node.js
-when no binary matches.
+custom command.
 
 **Commands:**
 
@@ -192,6 +199,7 @@ Pi-side variables can be set as real environment variables or in `~/.pi/pi-x-ide
 | ------------------------------- | ------------- | ----------------------------------------------------------------------------------- |
 | `PI_X_IDE_AUTO_INSTALL`         | `1`           | Auto-install VS Code extension on Pi startup                                        |
 | `PI_X_IDE_ATTACH_SHORTCUT`      | `ctrl+alt+k`  | Pi TUI shortcut for `/ide attach`; set to `off`, `none`, `false`, or `0` to disable |
+| `PI_X_IDE_HOST_OVERRIDE`        | (unset)       | Override the host Pi uses for IDE WebSocket lock files; useful for WSL2 networking  |
 | `PI_X_IDE_ZED_DB`               | (auto-detect) | Override path to Zed SQLite database                                                |
 | `PI_X_IDE_ZED_POLL_INTERVAL_MS` | `1000`        | Zed SQLite polling interval, clamped to 100-2000 ms                                 |
 
@@ -205,22 +213,25 @@ See [schemas/config.json](schemas/config.json) for editor schema guidance. A [co
 
 ### Feature Parity
 
-| Feature                                              | VS Code                 | Zed        | Neovim                        |
-| ---------------------------------------------------- | ----------------------- | ---------- | ----------------------------- |
-| Live file tracking                                   | ✅ Real-time push       | ✅ polling | ✅ Real-time push via sidecar |
-| Live selection tracking                              | ✅ Real-time push       | ✅ polling | ✅ Real-time push via sidecar |
-| IDE context attach shortcut                          | ✅ Default `Ctrl+Alt+K` | ❌         | ✅ Custom configured keymap   |
-| Pi TUI context attach shortcut(default `Ctrl+Alt+K`) | ✅                      | ✅         | ✅                            |
-| LLM context injection                                | ✅                      | ✅         | ✅                            |
-| `/ide auto`                                          | ✅                      | ✅         | ✅                            |
+| Feature                                              | VS Code                 | Zed        | Neovim                        | JetBrains               |
+| ---------------------------------------------------- | ----------------------- | ---------- | ----------------------------- | ----------------------- |
+| Live file tracking                                   | ✅ Real-time push       | ✅ polling | ✅ Real-time push via sidecar | ✅ Real-time push       |
+| Live selection tracking                              | ✅ Real-time push       | ✅ polling | ✅ Real-time push via sidecar | ✅ Real-time push       |
+| IDE context attach shortcut                          | ✅ Default `Ctrl+Alt+K` | ❌         | ✅ Custom configured keymap   | ✅ Default `Ctrl+Alt+K` |
+| Pi TUI context attach shortcut(default `Ctrl+Alt+K`) | ✅                      | ✅         | ✅                            | ✅                      |
+| LLM context injection                                | ✅                      | ✅         | ✅                            | ✅                      |
+| `/ide auto`                                          | ✅                      | ✅         | ✅                            | ✅                      |
+| Diagnostic Quick Fix                                 | ✅                      | ❌         | ❌                            | ❌                      |
+| Auto-install                                         | ✅ VS Code-family only  | N/A        | ❌                            | ❌                      |
 
-### Lock File Protocol
+### How Discovery Works
 
-After the IDE WebSocket server starts, connection information is written to `~/.pi/pi-x-ide/lock/`.
+Pi discovers IDE connections via lock files under `~/.pi/pi-x-ide/lock/`. It
+auto-connects when your terminal `cwd` is inside one of the IDE's workspace
+folders. If `cwd` is only a parent directory (e.g. `~/`), run `/ide` to choose a
+connection manually.
 
-Pi uses `ctx.cwd` to find the longest path match against `workspaceFolders` in the lock files, selecting the best-matching and most recent IDE connection. Pi auto-connects only when the current `cwd` is inside or equal to one of the IDE `workspaceFolders`; if `cwd` is only a parent directory such as `~/`, run `/ide` to choose a connection manually.
-
-See [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md) for protocol details.
+See [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md) for the full protocol.
 
 ---
 
@@ -232,6 +243,7 @@ See [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md) for protocol detail
 - bun ≥ 1.3 (`packageManager` declared as `bun@1.3.14`)
 - VS Code ≥ 1.120.0 (VS Code extension only)
 - Neovim ≥ 0.9 (Neovim plugin only)
+- JDK 21 (JetBrains plugin only; Gradle can download the toolchain automatically)
 
 ### Install & Build
 
@@ -240,8 +252,8 @@ Clone the repository, then build:
 ```bash
 git clone https://github.com/balaenis/pi-x-ide.git
 cd pi-x-ide
-bun install
-bun run build
+mise run setup
+mise run build
 ```
 
 To load the local build without installing globally:
@@ -250,15 +262,18 @@ To load the local build without installing globally:
 pi -e ./src/pi/index.ts
 ```
 
-All `bun run` commands have equivalent `mise run` tasks (see `mise.toml`):
+All build and check commands are defined as `mise run` tasks (see `.mise/tasks/`):
 
-| Command                       | Description                                                                                                                |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `bun run build`               | Build Pi-side TypeScript → `dist/` + Neovim sidecar → `ide-plugins/nvim/bin/` + VS Code bundle → `ide-plugins/vscode/out/` |
-| `bun run typecheck`           | Type-check only (no output files)                                                                                          |
-| `bun run test`                | Build + run unit tests                                                                                                     |
-| `bun run package:vsix`        | Package VS Code extension as VSIX                                                                                          |
-| `bun run check:config-schema` | Verify `schemas/config.json` is in sync with the config registry                                                           |
+| Command                        | Description                                                                                                                |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `mise run build`               | Build Pi-side TypeScript → `dist/` + Neovim sidecar → `ide-plugins/nvim/bin/` + VS Code bundle → `ide-plugins/vscode/out/` |
+| `mise run typecheck`           | Type-check only (no output files)                                                                                          |
+| `mise run test`                | Build + run unit tests                                                                                                     |
+| `mise run package:vsix`        | Package VS Code extension as VSIX                                                                                          |
+| `mise run compile:jetbrains`   | Compile and test the JetBrains plugin with Gradle                                                                          |
+| `mise run package:jetbrains`   | Package the JetBrains plugin ZIP under `ide-plugins/jetbrains/build/distributions/`                                        |
+| `mise run verify:jetbrains`    | Run IntelliJ Plugin Verifier for the configured target IDE                                                                 |
+| `mise run check:config-schema` | Verify `schemas/config.json` is in sync with the config registry                                                           |
 
 ### Testing the VS Code Extension Locally
 
@@ -268,13 +283,13 @@ All `bun run` commands have equivalent `mise run` tasks (see `mise.toml`):
 2. Go to the **Run and Debug** panel (`Ctrl+Shift+D`).
 3. Select **Run Pi x IDE VS Code Extension**.
 4. Press **F5**:
-   - The `preLaunchTask` automatically runs `bun run build`.
+   - The `preLaunchTask` automatically runs `mise run build`.
    - A new VS Code window titled `[Extension Development Host]` opens.
 
 #### Option 2: Package VSIX and Install
 
 ```bash
-bun run package:vsix
+mise run package:vsix
 cd ide-plugins/vscode && code --install-extension dist/pi-x-ide-$(node -p "require('./package.json').version").vsix
 ```
 
@@ -288,6 +303,23 @@ ls -l ~/.pi/pi-x-ide/lock
 
 You should see a file like `vscode-12345-48123.lock`. If not, run **Developer: Reload Window** in VS Code.
 
+### Testing the JetBrains Plugin Locally
+
+Run a sandbox IDE:
+
+```bash
+cd ide-plugins/jetbrains
+./gradlew runIde
+```
+
+Build the installable plugin ZIP:
+
+```bash
+mise run package:jetbrains
+```
+
+The ZIP is written under `ide-plugins/jetbrains/build/distributions/`. For a smoke test, open this repository in the sandbox IDE, start `pi` from the same directory, open and select text in a local file, then press `Ctrl+Alt+K` or run **Pi x IDE: Attach Selection**. Pi should receive an `@relative/path#Lx-Ly` mention.
+
 ### Release
 
 This project uses [Release Please](https://github.com/googleapis/release-please) with [Conventional Commits](https://www.conventionalcommits.org/) to automate versioning and publishing.

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 > 用于 IDE 选择上下文集成的 Pi 扩展包。
 
-自动将 VS Code、Zed 和 Neovim 中当前打开或选中的文件与文本范围附加到 Pi TUI，并作为对话上下文提交给 LLM。
+自动将 VS Code、Zed、Neovim 和 JetBrains IDE 中当前打开或选中的文件与文本范围附加到 Pi TUI，并作为对话上下文提交给 LLM。
 
 ---
 
@@ -42,14 +42,8 @@ PI_X_IDE_AUTO_INSTALL=0
 
 #### Neovim
 
-Neovim 支持由一个 Lua 插件和一个 sidecar 进程组成。首次启动时插件会自动从
-GitHub Releases 下载适合当前平台的独立二进制文件（Linux/macOS/Windows，
-x64 或 arm64），并在写入缓存前用 release asset 的 SHA-256 digest 做校验。下载
-或校验失败、或无匹配二进制时，插件降级到内置的 Node.js sidecar — 此时需要
-PATH 中有 Node.js。
-
-下载的二进制文件缓存在 `stdpath("cache")/pi-x-ide/` 目录，后续启动直接复用。可选的
-lazy.nvim build 钩子会优先使用插件包内的 bundled binary；如果不存在，则在安装和更新时检查 release digest，仅在缓存二进制缺失或过期时下载。
+Neovim 支持由一个 Lua 插件和一个 sidecar 进程组成。插件首次启动时自动下载
+平台二进制文件，不可用时回退到 Node.js。
 
 **lazy.nvim：**
 
@@ -70,9 +64,9 @@ lazy.nvim build 钩子会优先使用插件包内的 bundled binary；如果不
 }
 ```
 
-> **注意：** `init` 块手动将 `ide-plugins/nvim/` 子目录加入 runtime path，以规避部分版本 lazy.nvim 的 Lua 模块解析兼容性问题。插件选项通过 lazy.nvim 推荐的 `opts` 字段传入。
->
-> 可选的 `build` 钩子会优先使用插件包内的 bundled sidecar 二进制；如果不存在，则在安装/更新时检查 GitHub Release asset digest（用 `:Lazy build pi-x-ide` 可重新触发），仅在缓存二进制缺失或过期时下载。该钩子可以省略：插件仍会在首次启动时按需下载二进制，下载不可用时回退到 Node.js sidecar。
+> **注意：** `init` 块将插件子目录加入 runtime path，以规避部分版本 lazy.nvim 的
+> Lua 模块解析兼容性问题。可选的 `build` 钩子会预下载 sidecar 二进制；可以省略
+> — 插件会在首次启动时按需下载。
 
 **原生 package：**
 
@@ -83,6 +77,10 @@ lua require("pi_x_ide").setup({ keymap = "<leader>pa" })
 
 完整配置选项、命令和故障排查见 [配置参考](#neovim-2)。
 
+#### JetBrains IDE
+
+从 [GitHub 最新 Release](https://github.com/balaenis/pi-x-ide/releases/latest) 下载 JetBrains 插件 ZIP，然后在 JetBrains IDE 中通过 **Settings | Plugins | ⚙ | Install Plugin from Disk...** 安装。
+
 ### 连接 Pi 并验证
 
 在 IDE workspace **同一项目目录** 启动 Pi：
@@ -91,21 +89,25 @@ lua require("pi_x_ide").setup({ keymap = "<leader>pa" })
 pi
 ```
 
-Pi 自动加载 `pi-x-ide` 并连接 IDE。TUI 底部应显示 `IDE: vscode ✓`，输入框下方 widget 显示 IDE 名称、workspace、当前文件和选区范围。
+Pi 自动加载 `pi-x-ide` 并连接 IDE。TUI 在编辑器上方显示一个 widget，展示当前
+IDE 连接和选区状态。
 
 **验证是否正常：**
 
 在 IDE 中打开文件并选中文本，widget 应实时更新：
 
 ```text
-IDE: vscode ✓ src/foo.ts#L10-L20 pending
+⧉ ⇡ foo.ts#L10-L20
 ```
 
-可以从任一侧附加选区：在 VS Code 系列 IDE 中按 `Ctrl+Alt+K`（Linux/Windows）或 `Cmd+Alt+K`（macOS），或聚焦 Pi TUI 后按 `Ctrl+Alt+K` / 运行 `/ide attach`。Pi 输入框应插入 `@src/foo.ts#L10-L20`。
+可以从任一侧附加选区：在 VS Code 系列 IDE 中按 `Ctrl+Alt+K`（Linux/Windows）或 `Cmd+Alt+K`（macOS），在 JetBrains 中按 `Ctrl+Alt+K` 或运行 **Pi x IDE: Attach Selection**，在 Neovim 中使用 `:PiXIdeAttach`，或聚焦 Pi TUI 后按 `Ctrl+Alt+K` / 运行 `/ide attach`。Pi 输入框应插入 `@src/foo.ts#L10-L20`。
 
-在 Pi 中输入对话提示并提交，选中文本会作为 LLM 上下文注入（不写入 session 历史）。提交后 widget 显示 `sent`。
+在 Pi 中输入对话提示并提交，选中文本会作为 LLM 上下文注入。
+提交后 widget 变为 `⧉ ✓ foo.ts#L10-L20`。
 
-对于 VS Code 系列 IDE 中的诊断信息，先连接 Pi，再把光标放在 error 或 warning 上并打开 Quick Fix。只有至少一个 Pi 客户端已连接时，才会显示 **Pi: Fix it** 和 **Pi: Send diagnostic**。**Pi: Fix it** 会把诊断消息、源码范围、附近上下文行和 related information 发送给一个已连接的 Pi 客户端，并用可自定义的 prompt 模板自动开始诊断分析（参见 [`fix_prompt`](#pi-侧配置)）。**Pi: Send diagnostic** 会把相同上下文发送给一个已连接的 Pi 客户端并粘贴到 Pi 输入框，不会自动开始一轮对话。
+**诊断 Quick Fix（仅 VS Code）：** 将光标放在 error 或 warning 上，打开 Quick Fix，
+选择 **Pi: Fix it** 将诊断信息发送给 Pi 并启动分析对话，或选择 **Pi: Send diagnostic**
+将其粘贴到输入框。
 
 **如果连接未出现：**
 
@@ -113,6 +115,19 @@ IDE: vscode ✓ src/foo.ts#L10-L20 pending
 - 如果 IDE 在 Pi 之后启动，reload IDE 窗口后再次运行 `/ide auto`
 - 运行 `/ide` 手动从列表中选择连接
 
+### WSL2
+
+当 Pi 运行在 WSL2 中、IDE 运行在原生 Windows 上时，Pi 会自动跨 WSL 边界发现
+IDE 连接。大多数情况下无需额外配置。
+
+如果你的 WSL 网络模式、防火墙或终端安全策略阻止自动发现，可设置
+`PI_X_IDE_HOST_OVERRIDE`：
+
+```bash
+PI_X_IDE_HOST_OVERRIDE=127.0.0.1 pi
+PI_X_IDE_HOST_OVERRIDE=<windows-host-ip> pi
+```
+
 ### `/ide` 命令参考
 
 | 命令           | 行为                                              |
@@ -148,8 +163,6 @@ Pi 默认也会在 TUI 中注册 `Ctrl+Alt+K`，作为 `/ide attach` 的快捷
 - **Windows：** `%LOCALAPPDATA%\Zed\db\0-stable\db.sqlite`
 - **WSL + Windows 版 Zed：** `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite`
 
-当 Pi 运行在 WSL 中而 Zed 是 Windows 应用时，pi-x-ide 会将 Windows 路径（`C:\Users\<user>\project`）规范化为 `/mnt/c/Users/<user>/project`，并将 WSL UNC 路径规范化为 `/home/<user>/project`。
-
 #### Neovim
 
 ```lua
@@ -158,13 +171,11 @@ require("pi_x_ide").setup({
   keymap = "<C-A-k>",
   debounce_ms = 150,
   -- sidecar_cmd = { "node", "/absolute/path/to/pi-x-ide-nvim-sidecar.cjs" },
-  -- （默认使用平台二进制文件；找不到时降级到 node + cjs）
   -- workspace_folders = { "/path/to/project" },
 })
 ```
 
-如果 sidecar 无法启动，请运行 `:PiXIdeStatus`，或设置 `sidecar_cmd` 为自定义
-命令。插件优先使用平台二进制文件，找不到匹配项时降级到 Node.js。
+如果 sidecar 无法启动，请运行 `:PiXIdeStatus`，或设置 `sidecar_cmd` 为自定义命令。
 
 **命令：**
 
@@ -183,6 +194,7 @@ Pi 侧变量可设为真实环境变量或写入 `~/.pi/pi-x-ide/config.json`
 | ------------------------------- | ------------ | ------------------------------------------------------------------------- |
 | `PI_X_IDE_AUTO_INSTALL`         | `1`          | Pi 启动时自动安装 VS Code 扩展                                            |
 | `PI_X_IDE_ATTACH_SHORTCUT`      | `ctrl+alt+k` | Pi TUI 的 `/ide attach` 快捷键；设为 `off`、`none`、`false` 或 `0` 可禁用 |
+| `PI_X_IDE_HOST_OVERRIDE`        | （未设置）   | 覆盖 Pi 连接 IDE WebSocket lock file 时使用的 host；适用于 WSL2 网络场景  |
 | `PI_X_IDE_ZED_DB`               | （自动检测） | 覆盖 Zed SQLite 数据库路径                                                |
 | `PI_X_IDE_ZED_POLL_INTERVAL_MS` | `1000`       | Zed SQLite 轮询间隔，会被限制在 100-2000 ms 范围                          |
 
@@ -196,22 +208,24 @@ Pi 侧变量可设为真实环境变量或写入 `~/.pi/pi-x-ide/config.json`
 
 ### 功能对比
 
-| 功能                                             | VS Code              | Zed         | Neovim                   |
-| ------------------------------------------------ | -------------------- | ----------- | ------------------------ |
-| 实时文件追踪                                     | ✅ 实时推送          | ✅ 1 秒轮询 | ✅ 通过 sidecar 实时推送 |
-| 实时选区追踪                                     | ✅ 实时推送          | ✅ 1 秒轮询 | ✅ 通过 sidecar 实时推送 |
-| IDE 上下文 attach 快捷键                         | ✅ 默认 `Ctrl+Alt+K` | ❌          | ✅ 自定义快捷键 keymap   |
-| Pi TUI 上下文 attach 快捷键（默认 `Ctrl+Alt+K`） | ✅                   | ✅          | ✅                       |
-| LLM 上下文注入                                   | ✅                   | ✅          | ✅                       |
-| `/ide auto`                                      | ✅                   | ✅          | ✅                       |
-
-### Lock File 协议
+| 功能                                             | VS Code              | Zed         | Neovim                   | JetBrains            |
+| ------------------------------------------------ | -------------------- | ----------- | ------------------------ | -------------------- |
+| 实时文件追踪                                     | ✅ 实时推送          | ✅ 1 秒轮询 | ✅ 通过 sidecar 实时推送 | ✅ 实时推送          |
+| 实时选区追踪                                     | ✅ 实时推送          | ✅ 1 秒轮询 | ✅ 通过 sidecar 实时推送 | ✅ 实时推送          |
+| IDE 上下文 attach 快捷键                         | ✅ 默认 `Ctrl+Alt+K` | ❌          | ✅ 自定义快捷键 keymap   | ✅ 默认 `Ctrl+Alt+K` |
+| Pi TUI 上下文 attach 快捷键（默认 `Ctrl+Alt+K`） | ✅                   | ✅          | ✅                       | ✅                   |
+| LLM 上下文注入                                   | ✅                   | ✅          | ✅                       | ✅                   |
+| `/ide auto`                                      | ✅                   | ✅          | ✅                       | ✅                   |
+| 诊断 Quick Fix                                   | ✅                   | ❌          | ❌                       | ❌                   |
+| 自动安装                                         | ✅ 仅 VS Code 系列   | N/A         | ❌                       | ❌                   |
 
-IDE WebSocket server 启动后默认将连接信息写入 `~/.pi/pi-x-ide/lock/`。
+### 发现机制
 
-Pi 通过 `ctx.cwd` 与 lock file 中的 `workspaceFolders` 做最长路径匹配，选中最匹配且最新的 IDE 连接。只有当前 `cwd` 位于某个 IDE `workspaceFolders` 内或与其相等时，Pi 才会自动连接；如果 `cwd` 只是父级目录（例如 `~/`），请运行 `/ide` 手动选择连接。
+Pi 通过 `~/.pi/pi-x-ide/lock/` 下的 lock file 发现 IDE 连接。当终端 `cwd`
+位于某个 IDE workspace 目录内时自动连接；如果 `cwd` 只是父级目录（如 `~/`），
+请运行 `/ide` 手动选择连接。
 
-协议详情见 [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md)。
+完整协议见 [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md)。
 
 ---
 
@@ -223,6 +237,7 @@ Pi 通过 `ctx.cwd` 与 lock file 中的 `workspaceFolders` 做最长路径匹
 - bun ≥ 1.3（`packageManager` 声明为 `bun@1.3.14`）
 - VS Code ≥ 1.120.0（仅 VS Code 扩展需要）
 - Neovim ≥ 0.9（仅 Neovim 插件需要）
+- JDK 21（仅 JetBrains 插件需要；Gradle 可自动下载 toolchain）
 
 ### 安装与构建
 
@@ -231,8 +246,8 @@ Clone 仓库后构建：
 ```bash
 git clone https://github.com/balaenis/pi-x-ide.git
 cd pi-x-ide
-bun install
-bun run build
+mise run setup
+mise run build
 ```
 
 加载本地构建（无需全局安装）：
@@ -241,15 +256,18 @@ bun run build
 pi -e ./src/pi/index.ts
 ```
 
-所有 `bun run` 命令都有等效的 `mise run` 任务（见 `mise.toml`）：
+所有构建与检查命令都定义为 `mise run` 任务（见 `.mise/tasks/`）：
 
-| 命令                          | 说明                                                                                                                    |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `bun run build`               | 编译 Pi 侧 TypeScript → `dist/` + Neovim sidecar → `ide-plugins/nvim/bin/` + VS Code bundle → `ide-plugins/vscode/out/` |
-| `bun run typecheck`           | 类型检查（不产出文件）                                                                                                  |
-| `bun run test`                | 编译 + 运行单元测试                                                                                                     |
-| `bun run package:vsix`        | 打包 VS Code 扩展为 VSIX                                                                                                |
-| `bun run check:config-schema` | 验证 `schemas/config.json` 与配置注册表是否同步                                                                         |
+| 命令                           | 说明                                                                                                                    |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `mise run build`               | 编译 Pi 侧 TypeScript → `dist/` + Neovim sidecar → `ide-plugins/nvim/bin/` + VS Code bundle → `ide-plugins/vscode/out/` |
+| `mise run typecheck`           | 类型检查（不产出文件）                                                                                                  |
+| `mise run test`                | 编译 + 运行单元测试                                                                                                     |
+| `mise run package:vsix`        | 打包 VS Code 扩展为 VSIX                                                                                                |
+| `mise run compile:jetbrains`   | 用 Gradle 编译并测试 JetBrains 插件                                                                                     |
+| `mise run package:jetbrains`   | 将 JetBrains 插件打包为 `ide-plugins/jetbrains/build/distributions/` 下的 ZIP                                           |
+| `mise run verify:jetbrains`    | 对配置的目标 IDE 运行 IntelliJ Plugin Verifier                                                                          |
+| `mise run check:config-schema` | 验证 `schemas/config.json` 与配置注册表是否同步                                                                         |
 
 ### 本地测试 VS Code 扩展
 
@@ -259,13 +277,13 @@ pi -e ./src/pi/index.ts
 2. 进入 **Run and Debug** 面板（`Ctrl+Shift+D`）。
 3. 选择 **Run Pi x IDE VS Code Extension**。
 4. 按 **F5**：
-   - preLaunchTask 会自动执行 `bun run build`。
+   - preLaunchTask 会自动执行 `mise run build`。
    - 打开一个标题包含 `[Extension Development Host]` 的新 VS Code 窗口。
 
 #### 方式二：打包 VSIX 后安装
 
 ```bash
-bun run package:vsix
+mise run package:vsix
 cd ide-plugins/vscode && code --install-extension dist/pi-x-ide-$(node -p "require('./package.json').version").vsix
 ```
 
@@ -279,6 +297,23 @@ ls -l ~/.pi/pi-x-ide/lock
 
 应看到类似 `vscode-12345-48123.lock` 的文件。如果没有，在 VS Code 中执行 **Developer: Reload Window**。
 
+### 本地测试 JetBrains 插件
+
+运行 sandbox IDE：
+
+```bash
+cd ide-plugins/jetbrains
+./gradlew runIde
+```
+
+构建可安装的插件 ZIP：
+
+```bash
+mise run package:jetbrains
+```
+
+ZIP 会输出到 `ide-plugins/jetbrains/build/distributions/`。Smoke test：在 sandbox IDE 中打开本仓库，从同一目录启动 `pi`，打开并选择一个本地文件中的文本，然后按 `Ctrl+Alt+K` 或运行 **Pi x IDE: Attach Selection**。Pi 应收到 `@relative/path#Lx-Ly` mention。
+
 ### 发布
 
 本项目使用 [Release Please](https://github.com/googleapis/release-please) 和 [Conventional Commits](https://www.conventionalcommits.org/) 来自动化版本管理和发布流程。

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pi-x-ide",
-    "version": "1.13.1",
+    "version": "1.15.0",
     "description": "Pi extension package for IDE selection context integration.",
     "files": [
         "dist",
@@ -14,7 +14,10 @@
         "vscode",
         "zed",
         "neovim",
-        "nvim"
+        "nvim",
+        "jetbrains",
+        "intellij",
+        "idea"
     ],
     "license": "Apache-2.0",
     "repository": {
@@ -34,24 +37,6 @@
     },
     "type": "commonjs",
     "main": "./dist/src/pi/index.js",
-    "scripts": {
-        "typecheck": "tsc -p tsconfig.json --noEmit && bun run --filter './ide-plugins/vscode' typecheck",
-        "generate:config-schema": "bun run scripts/generate-config-schema.cjs",
-        "check:config-schema": "bun run scripts/generate-config-schema.cjs --check",
-        "test": "bun run check:config-schema && bun run compile && node --test dist/test/*.test.js",
-        "lint": "eslint .",
-        "lint:fix": "eslint . --fix",
-        "format": "prettier --write .",
-        "format:check": "prettier --check .",
-        "compile": "tsc -p tsconfig.json",
-        "compile:vsix": "bun run --filter './ide-plugins/vscode' compile",
-        "sync:vsix-assets": "bun run --filter './ide-plugins/vscode' sync:assets",
-        "package:vsix": "bun run --filter './ide-plugins/vscode' package",
-        "package:nvim-sidecar": "bun run scripts/build-nvim-sidecar.mjs --production",
-        "package:nvim-sidecar:all": "bun run scripts/build-nvim-sidecar.mjs --production --target=all",
-        "build": "bun run compile && bun run compile:vsix && bun run package:nvim-sidecar",
-        "build:all": "bun run compile && bun run compile:vsix && bun run package:nvim-sidecar:all"
-    },
     "dependencies": {
         "ws": "^8.21.0"
     },

package/dist/src/pi/connection.d.ts

@@ -2,7 +2,8 @@ import { type DiagnosticFixRequestedParams, type AtMentionedParams, type EditorS
 export declare const IDE_CONNECT_TIMEOUT_MS = 5000;
 export declare class IdeConnectionTimeoutError extends Error {
     readonly candidate: LockFileCandidate;
-    constructor(candidate: LockFileCandidate);
+    readonly host: string;
+    constructor(candidate: LockFileCandidate, host?: string);
 }
 export interface IdeConnectionCallbacks {
     onConnected?: (server: {
@@ -17,14 +18,19 @@ export interface IdeConnectionCallbacks {
     onDiagnosticFixRequested?: (params: DiagnosticFixRequestedParams) => void;
     onError?: (error: Error) => void;
 }
+export interface IdeConnectionOptions {
+    resolveHost?: (lock: LockFileCandidate["lock"]) => Promise<string>;
+    env?: NodeJS.ProcessEnv;
+}
 export declare class IdeConnection {
     readonly candidate: LockFileCandidate;
     private readonly cwd;
     private readonly callbacks;
+    private readonly options;
     private socket?;
     private nextId;
     private closedByUser;
-    constructor(candidate: LockFileCandidate, cwd: string, callbacks: IdeConnectionCallbacks);
+    constructor(candidate: LockFileCandidate, cwd: string, callbacks: IdeConnectionCallbacks, options?: IdeConnectionOptions);
     get isOpen(): boolean;
     connect(timeoutMs?: number): Promise<void>;
     disconnect(): void;