opencode-idea 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.0.1
+
+首个版本（包名 `opencode-idea`，从 `opencode-jetbrains-mcp` 重命名而来）。
+
+**接入 IDE MCP**
+
+- **`/open-in-idea` 命令**:用 IntelliJ IDEA 打开当前项目(复用已运行实例),并即时加载 IDE MCP。命令可重入,重复触发共享同一次启动,不会重复 spawn。
+- **IDE 启动器** (`src/ide-launcher.js`):`open -a "IntelliJ IDEA" <dir>` 复用已运行实例(Toolbox CLI 的 `open -na` 会新开实例,故不使用)。
+- **启动保护 (launch guard)**:每目录记录 `lastSpawnAt` / `attempts`;冷却 `launchCooldownMs`(默认 120s)、上限 `launchMaxAttempts`(默认 5)。
+- **MCP 未开启时 fast-fail**:`/open-in-idea` 先短探测,未检测到 MCP 就立即返回并提示在 IDEA 中开启 MCP 服务和 Brave Mode,不轮询、不等待超时;用户开启后重试命令即可。
+- **Streamable HTTP 端点**:注册给 OpenCode 的 URL 使用 `/stream`(IntelliJ 2026.2+)。OpenCode V2 的远程 MCP 客户端只支持 Streamable HTTP,旧版 `/sse`(POST 返回 405)不可用;插件探测同样走 `/stream`。
+- **结果通知**(`feedback: "message"`,默认):命令结束后发一条标注清楚的通知,用户看到干净气泡(`metadata.displayText`),模型只看到"这是通知,请只回复『收到』";`false` 静默。
+
+**IDE 工具优先**
+
+- **系统提示直接调用引导** (`src/ide-guidance.js`):IDE 可用时,通过 `ctx.session.hook("context", …)` 往每次请求的 system 追加「项目内操作优先使用 IDEA MCP」引导 + 能力映射表,要求模型直接调用 `idea_*` 工具。`injectGuidance: false` 可关闭。
+- **IDEA 工具描述增强** (`src/idea-tool-descriptions.js`):通过 `ctx.tool.transform` 只更新 `idea_*` / `idea.*` 工具的 description,强调直接调用、按当前 schema 传参。原生 `edit` / `write` / `patch` / `shell` 的定义、描述和可用性保持不变。
+- **失败恢复指引**:IDEA MCP 工具缺失、连接被拒或超时时,提示用户执行 `/open-in-idea`,不反复探测或长时间等待。
+
+**IDE 环境注入**
+
+- **环境变量只来自 IDE 集成终端**:用 `execute_terminal_command printenv` 读取 IDE 实际运行环境(版本化 Node、goenv Go、SDKMAN Java、Maven 等),通过 V2 `shell` 的 `create.before` 钩子注入每个 shell;只补 SDK 变量并前置 PATH,不覆盖原有 PATH。需要 IDE MCP 可达 + Brave Mode。
+- **抽取值** (`src/ide-env.js` 的 `SDK_ENV_KEYS`):`JAVA_HOME` / `JRE_HOME` / `JDK_HOME` / `VIRTUAL_ENV` / `PYTHONPATH` / `PYTHONHOME` / `GOROOT` / `GOPATH` / `GOBIN` / `NODE_PATH` / `NVM_BIN` / `NVM_DIR` / `MAVEN_HOME` / `M2_HOME` / `GRADLE_HOME` / `SDKMAN_DIR` / `CONDA_PREFIX`。
+
+**其他**
+
+- **纯手动**:启动不探测、不连接 IDE MCP;IDE MCP 注册、环境重读、引导注入全部由 `/open-in-idea` 触发。
+- **根级 `index.js` 转发入口**:使仓库可作为 V2 本地目录插件直接加载(`plugins: [{ "package": "<repo>" }]`)。
+- **配置项**:`ports` / `injectEnv` / `injectGuidance` / `openInIde` / `launchCooldownMs` / `launchMaxAttempts` / `mcpProbeTimeoutMs` / `feedback`。
+- 仅支持 **OpenCode V2**;非 JetBrains 项目完全不受影响。

package/README.md

@@ -0,0 +1,197 @@
+# opencode-idea
+
+OpenCode 插件,面向 JetBrains 项目(IntelliJ IDEA / PyCharm / WebStorm 等),做三件事:
+
+1. **接入 IDE MCP** —— 用 `/open-in-idea` 把当前项目在 IntelliJ IDEA 中打开,并把这个 IDE 的 MCP 服务(60 个工具:检索、读、改、构建、重构、调试、数据库……)注册进 OpenCode。
+2. **优先使用 IDE 工具** —— IDE 可用时,向模型注入"项目内操作默认走 IDE MCP"的系统提示引导 + 能力映射;IDE 不可用时回退原生工具(正常回退,无需声明)。
+3. **注入 IDE 环境变量** —— 从 IDE 集成终端读取它实际运行的环境(版本化管理的 Node、goenv 的 Go、SDKMAN 的 Java、Maven……)注入每个 OpenCode shell。
+
+非 JetBrains 项目完全不受影响。**全部手动**:插件启动不探测、不连接 IDE,只有跑 `/open-in-idea` 时才连接。
+
+## 工作原理
+
+```text
+setup(启动):
+  a. 读 IDE 集成终端环境 → 通过 shell create.before 钩子注入每个 shell(null: 未连 IDE 时为空)
+  b. 注册 /open-in-idea 命令 + session context 钩子(注入引导)
+  不探测、不注册 MCP
+
+/open-in-idea(手动触发):
+  1. 探测本地 JetBrains IDE MCP 服务(/stream)
+  2. 已就绪 → 直接连接
+  3. 未就绪 → open -a "IntelliJ IDEA" <项目目录>(复用已运行实例),然后立即提示:
+     在 IDEA 中开启 MCP 服务 + Brave Mode
+  4. 本次命令 fast-fail 返回;用户手动开启后再次执行 `/open-in-idea`
+  5. MCP 就绪时:
+       a. 注册 IDE MCP(url /stream,header IJ_MCP_SERVER_PROJECT_PATH 锁定当前项目)
+       b. 读 IDE 终端环境 → 更新注入每个 shell 的环境变量
+       c. 启用系统提示引导(直接调用 `idea_*` 工具)+ IDEA MCP 工具描述前缀
+  6. 发一条结果通知(用户看到干净气泡,模型只回"收到")
+```
+
+## 在 IDE 中打开项目(`/open-in-idea`)
+
+在会话里输入 `/open-in-idea`:
+
+1. 先探测 `/stream`;已就绪 → 直接加载能力;
+2. 未就绪 → 用 `open -a "IntelliJ IDEA" <项目目录>` 拉起或激活 IDEA —— **复用已运行的实例**(不会重复开新实例);
+3. 如果 MCP 仍未就绪,命令会**立即 fast-fail**,提示在 IDEA 的 `Settings → MCP Server` 开启 MCP 服务并启用 **Brave Mode**;
+4. 用户手动完成设置后,再次执行 `/open-in-idea`;探测成功后才注册 IDE MCP、重读 IDE 环境并启用系统引导与 live tool catalog。
+
+> **通知不触发 AI 干活**:默认 `feedback: "message"` 把结果作为一条**标注清楚的通知**发到会话里 —— 用户看到干净的通知气泡(经 `metadata.displayText`),模型只看到"这是通知,请只回复『收到』"的指令,因此不会执行任何操作、不会调用工具。`feedback: false` 则完全静默。
+
+**可重入 / 启动保护**:IDEA 冷启动、索引或等待「Trust and Open Project」弹窗期间探测会失败。命令只发一次 MCP/Brave Mode 提示并 fast-fail,不会在后台轮询;重复触发共享同一次打开请求,按目录维护 `lastSpawnAt` / `attempts`,避免重复 spawn。开启 MCP + Brave Mode 后再次执行 `/open-in-idea` 即可接上。
+
+**热更新会断开**:插件源码变更会触发 V2 热重载,注册随旧实例一起释放,`activePort` 归零。这是手动模式的预期行为 —— **改完插件后重跑一次 `/open-in-idea`** 即可恢复。
+
+## IDE 工具优先(直接调用引导)
+
+IDE MCP 可用时,插件通过两层轻量引导提高模型主动使用 IDEA MCP 的概率;不会修改原生工具的定义、描述或可用性:
+
+1. **系统提示注入**(主):通过 `ctx.session.hook("context", …)` 往每次请求的 system 里追加一段「项目内操作优先使用 IDEA MCP」的直接调用引导 + 能力映射表(`src/ide-guidance.js`),含工具名(`idea_<name>`)与关键参数名:
+   - 检索 → `idea_search_text` / `idea_search_regex` / `idea_search_file`(参数 `q`,可带 `paths` 收窄)
+   - 读文件 → `idea_read_file`(`file_path` / `offset` / `limit`);目录 → `idea_list_directory_tree`
+   - 改文件 → `idea_apply_patch`(`input`);新建 → `idea_create_new_file`(`pathInProject`)
+   - 校验 → `idea_lint_files` / `idea_get_file_problems` / `idea_build_project`
+   - 重构/格式化 → `idea_rename_refactoring` / `idea_reformat_file`;版本 → `idea_git_status`
+   - 例外(直接用原生):IDE 不索引的目录、`git diff/log/blame`、MCP 无等价能力、IDE MCP 未连接/未注册
+
+   连接成功后,插件只对 `idea_*` IDEA MCP 工具追加一段简短描述,要求模型直接调用、严格按当前 schema 传参;不会把整份工具目录重复塞进 system prompt,也不要求模型额外包一层 JavaScript 编排代码。
+
+   IDEA MCP 工具自身的 description/schema 仍是参数使用的权威来源;工具返回业务错误时先修正参数,不要误判成工具不可用。MCP 不可用时立即提示用户执行 `/open-in-idea`,不重复探测或等待。
+
+2. **IDEA MCP 工具描述增强**:插件通过 `ctx.tool.transform` 只更新 `idea_*` / `idea.*` 工具的 description,强调直接调用和按 schema 传参;原生 `edit` / `write` / `patch` / `shell` 完全不变。
+
+引导只在 **IDE MCP 可用**时生效;MCP 不可用时仅保留 fast-fail 恢复提示。`injectGuidance: false` 可关闭系统提示注入。
+
+## 环境变量注入
+
+**唯一来源:IDE 集成终端**(`execute_terminal_command printenv`)。它反映 IDE 实际运行的环境 —— 版本化管理的 Node(如 fnm v14)、goenv 的 Go、SDKMAN 的 Java 等 —— 这些 .idea 配置里往往读不到。
+
+抽取的变量(`src/ide-env.js` 的 `SDK_ENV_KEYS`):`JAVA_HOME` / `JRE_HOME` / `JDK_HOME` / `VIRTUAL_ENV` / `PYTHONPATH` / `PYTHONHOME` / `GOROOT` / `GOPATH` / `GOBIN` / `NODE_PATH` / `NVM_BIN` / `NVM_DIR` / `MAVEN_HOME` / `M2_HOME` / `GRADLE_HOME` / `SDKMAN_DIR` / `CONDA_PREFIX`。
+
+- 注入通过 V2 的 `shell` `create.before` 钩子:只补这些变量 + 前置 PATH,不覆盖你原有的 PATH。
+- 需要 IDE MCP 可达 + **Brave Mode**;拿不到时环境为空(不影响其他功能)。
+
+> 与 [opencode-env-loader](https://github.com/syllr/opencode-env-loader) 的关系:两者独立。env-loader 负责 `.opencode/env-loader/*` 的**人工** KEY=VALUE 覆盖;本插件负责从 **IDE 实际环境**推导。可以同时使用。
+
+## 前置条件
+
+- JetBrains IDE 已开启 MCP 服务(IDE 设置里的 MCP Server / AI Assistant MCP),版本需 **2026.2+**(提供 Streamable HTTP 端点 `/stream`);若关闭,`/open-in-idea` 会立即提示如何重新开启。
+- 要读 IDE 终端环境,需要在 IDE 里开启 **Brave Mode**(否则 `execute_terminal_command` 会等确认);MCP 未就绪时通知会同时提醒开启它。
+- 插件注册给 OpenCode 的 MCP 配置形如:
+
+```jsonc
+{
+  "type": "remote",
+  "url": "http://127.0.0.1:64342/stream",
+  "headers": { "IJ_MCP_SERVER_PROJECT_PATH": "<项目路径>" },
+}
+```
+
+> **为什么是 `/stream` 而不是 `/sse`**:OpenCode V2 的远程 MCP 客户端**只支持 Streamable HTTP**,没有旧版 SSE 传输。IDE 的 `/sse` 是旧版 SSE(POST 会返回 405),V2 连不上(报 `Error POSTing to endpoint`)。IDE 2026.2 起额外提供 `/stream` 这个 Streamable HTTP 端点。**插件的探测也走 `/stream`**(一次 `initialize`),协议统一。
+
+插件按 `ports` 顺序选择第一个可用端口,但会并发探测以避免多个端口的超时叠加;默认 `[64342, 6420, 6421, 63342]`。
+
+## 安装
+
+```json
+{
+  "plugin": ["opencode-idea"]
+}
+```
+
+> 仅支持 **OpenCode V2**。若你日常跑的是 1.x 的 `opencode-ai`,它用的是旧插件 API,本插件不会生效;真机验证请用 V2 运行时。
+
+### 本地开发 / 真机验证
+
+插件未发布时,可以直接指向本地仓库目录。V2 解析**目录**插件时找的是 `<dir>/index.*`(或 `<dir>/server.*`),不会读 `package.json#main`,所以仓库根目录提供了 `index.js` 转发到 `src/index.js`。
+
+全局配置 `~/.config/opencode/opencode.json`(V2 桌面端/CLI 共用):
+
+```jsonc
+{
+  "plugins": [{ "package": "/Users/yutao/Projects/opencode-idea" }],
+}
+```
+
+也可以沿用旧键 `plugin` 的元组写法:
+
+```jsonc
+{
+  "plugin": [["/Users/yutao/Projects/opencode-idea", {}]],
+}
+```
+
+配置保存后 V2 会监听并自动重载(日志里能看到它开始 watch `index.js` / `src/*.js`),无需重启。改插件源码也会触发重载(此时需重跑 `/open-in-idea`)。
+
+另一种零配置方式:在 `~/.config/opencode/plugins/` 放一个转发文件(自动发现,但不能传 options):
+
+```js
+// ~/.config/opencode/plugins/opencode-idea.js
+export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
+```
+
+## 配置
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-idea",
+      {
+        "ports": [64342, 6420, 6421, 63342],
+        "injectEnv": true,
+        "injectGuidance": true, // IDE 可用时向系统提示注入「默认走 IDE MCP」引导
+        "openInIde": "idea", // false 关闭;或任意 macOS 应用名(如 "IntelliJ IDEA")
+        "launchCooldownMs": 120000, // 启动保护冷却
+        "launchMaxAttempts": 5,
+        "mcpProbeTimeoutMs": 1000, // 单个 MCP 端口的短探测超时
+        "feedback": "message", // "message"(默认,会话通知,AI 只回"收到")| false(静默)
+      },
+    ],
+  ],
+}
+```
+
+| 选项                | 类型                 | 默认                         | 说明                                                             |
+| ------------------- | -------------------- | ---------------------------- | ---------------------------------------------------------------- |
+| `ports`             | `number[]`           | `[64342, 6420, 6421, 63342]` | 依次探测的 IDE MCP 端口                                          |
+| `injectEnv`         | `boolean`            | `true`                       | 是否注入 IDE 终端环境变量                                        |
+| `injectGuidance`    | `boolean`            | `true`                       | IDE 可用时是否向系统提示注入「默认走 IDE MCP」引导               |
+| `openInIde`         | `boolean \| string`  | `"idea"`                     | 拉起哪个 IDE;`false` 关闭,`"idea"` 映射到 IntelliJ IDEA          |
+| `launchCooldownMs`  | `number`             | `120000`                     | 启动保护冷却:冷却期内不重复 spawn                                |
+| `launchMaxAttempts` | `number`             | `5`                          | 单次会话内最多 spawn 次数,超出后停止重试                         |
+| `mcpProbeTimeoutMs` | `number`             | `1000`                       | 单个 MCP 端口的短探测超时                                        |
+| `feedback`          | `"message" \| false` | `"message"`                  | 结果反馈:`message` 会话通知(用户可见,AI 只回"收到");`false` 静默 |
+
+## 行为
+
+- **JetBrains 项目**:启动即注入 IDE 终端环境(若此前已连过 IDE);`/open-in-idea` 接入 IDE MCP + 启用引导。
+- **非 JetBrains 项目**:不改环境、不注册、不改描述。
+- **纯手动**:启动**不探测、不连接 IDE MCP**;IDE MCP 注册、环境重读、系统提示引导全部由 `/open-in-idea` 触发。IDE 中途关闭不会自动撤销,需再执行一次 `/open-in-idea` 重新同步。
+- **`/open-in-idea`**:手动打开当前项目并即时加载能力(已在 IDE 打开时则只重新加载);MCP 未开启时只发一次提示并 fast-fail,用户手动开启 MCP + Brave Mode 后重试。
+- **IDEA 工具增强**:通过 `ctx.tool.transform` 只更新 `idea_*` / `idea.*` 工具 description,原生 `edit` / `write` / `patch` / `shell` 的定义、描述和可用性均不变。
+
+## 限制
+
+- 仅支持 **OpenCode V2** 插件 API(`ctx.tool` / `ctx.mcp` / `ctx.shell` / `ctx.command` / `ctx.session` / `ctx.location`)。
+- IDE MCP 注册需要 IDE **2026.2+** 的 Streamable HTTP 端点 `/stream`;更早版本只有 `/sse`,OpenCode V2 无法连接。
+- 环境变量依赖 `execute_terminal_command` + Brave Mode;拿不到时环境为空。
+- 探测只确认「MCP 服务是否在监听」,不校验「当前项目是否已在 IDE 打开」;MCP 关闭时会用一次短探测并立即给出设置提示。
+- 打开 IDE 仅实现 macOS(`open -a`);首次打开若弹 Trust 对话框,需确认后重试。
+- IDE MCP 没有「打开项目」工具,因此打开动作走 OS/CLI,而非 MCP。
+- 插件热重载会断开 IDE 连接,需重跑 `/open-in-idea`。
+- 插件只修改 IDEA MCP 工具 description,不修改原生工具定义、描述或可用性;默认调用方式为直接 `idea_*` 工具调用。
+
+## 测试
+
+```bash
+npm test
+```
+
+使用 [Vitest](https://vitest.dev/),含纯函数测试、IDE 环境解析、环境合并、启动保护状态机、IDE 启动器、引导文本,以及「假 IDE MCP 服务」的端到端探测与插件集成测试。
+
+## License
+
+MIT

package/UPGRADING.md

@@ -0,0 +1,8 @@
+# 升级指南
+
+## 0.0.1
+
+初始版本,暂无迁移路径。
+
+> 从旧包名 `opencode-jetbrains-mcp` 迁移:把 OpenCode 配置里的
+> `opencode-jetbrains-mcp` 改为 `opencode-idea`,其余配置项不变。

package/index.js

@@ -0,0 +1,11 @@
+// Local-development entrypoint.
+//
+// OpenCode V2 resolves a *directory* plugin by looking for `<dir>/server.*` or
+// `<dir>/index.*` (it does not read `package.json#main` for local directories).
+// Published consumers resolve the package by name through `main` (./src/index.js).
+// This file lets the repository be loaded directly as a local plugin:
+//
+//   "plugins": [{ "package": "/path/to/opencode-idea", "options": { ... } }]
+//
+// See README.md § "本地开发 / 真机验证".
+export { default } from './src/index.js';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "opencode-idea",
+  "version": "0.0.1",
+  "description": "OpenCode plugin that connects to JetBrains IDE MCP servers and prefers IDE tools when the current project is open in the IDE",
+  "main": "src/index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "src/index.js",
+    "src/plugin.js",
+    "src/idea-mcp.js",
+    "src/ide-env.js",
+    "src/project.js",
+    "src/env.js",
+    "src/ide-launcher.js",
+    "src/ide-guidance.js",
+    "src/idea-tool-descriptions.js",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "UPGRADING.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "jetbrains",
+    "intellij",
+    "idea",
+    "mcp",
+    "ide"
+  ],
+  "author": "yutao",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/syllr/opencode-idea.git"
+  },
+  "devDependencies": {
+    "vitest": "^2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/jetbrains-mcp-setup/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: jetbrains-mcp-setup
+description: 配置并验证 opencode-idea 插件:开启 JetBrains IDE 的 MCP 服务、找到端口、写入 opencode.json、验证 OpenCode 能连上并优先使用 IDE 工具。当用户要「接入 IDEA/JetBrains 的 MCP」「让 OpenCode 用 IDE 工具编辑/构建」或排查插件不生效时使用。
+---
+
+# JetBrains MCP 接入配置
+
+## 步骤
+
+1. **确认 IDE 侧已开启 MCP 服务**
+   - 在 JetBrains IDE 中打开 Settings → Tools → MCP Server(或 AI Assistant 的 MCP 设置),启用。
+   - 让用户在 IDE 里打开要操作的项目。
+
+2. **拿到 MCP 端口**
+   - IDE 通常显示形如 `http://127.0.0.1:<port>/sse` 的地址;记录 `<port>`。
+   - 若用户不确定,可用 `ports` 默认列表让插件自动探测。
+
+3. **在项目 `opencode.json` 注册插件**
+
+   ```jsonc
+   {
+     "plugin": [
+       ["opencode-idea", { "ports": [<port>] }]
+     ]
+   }
+   ```
+
+4. **验证**
+   - 重启 OpenCode(或触发插件重载)。
+   - 让用户确认:当前项目在 IDE 中打开时,OpenCode 是否优先用 IDE 工具;关闭项目后是否回退原生。
+
+## 排查
+
+- 插件不生效:确认 OpenCode 是 **V2**(需要 `ctx.tool` / `ctx.mcp`)。
+- 一直探测失败:确认 IDE MCP 在跑、端口正确、当前项目确实在 IDE 中打开。
+- 判断依据:IDE MCP 的 `tools/call get_project_modules` 在项目打开时成功、未打开时返回 `isError`。

package/src/env.js

@@ -0,0 +1,39 @@
+// Merges environment sources and applies them to a shell `create.before`
+// invocation.
+
+import path from 'node:path';
+
+/**
+ * Merge env sources. Later sources win. `prependPath` entries are collected in
+ * order and applied ahead of the existing PATH.
+ *
+ * @param {Array<{ env?: Record<string, string>, prependPath?: string[] }>} sources
+ * @returns {{ env: Record<string, string>, prependPath: string[] }}
+ */
+export function mergeEnv(sources) {
+  const env = {};
+  const prependPath = [];
+  for (const source of sources) {
+    Object.assign(env, source.env ?? {});
+    prependPath.push(...(source.prependPath ?? []));
+  }
+  return { env, prependPath: [...new Set(prependPath)] };
+}
+
+/**
+ * Apply a merged env to a shell invocation's `env` in place.
+ *
+ * @param {{ env: Record<string, string | undefined> }} input
+ * @param {{ env: Record<string, string>, prependPath: string[] }} merged
+ * @param {{ pathKey?: string }} [options]
+ */
+export function applyEnv(input, merged, options = {}) {
+  const pathKey = options.pathKey ?? 'PATH';
+  for (const [key, value] of Object.entries(merged.env)) {
+    if (value !== undefined) input.env[key] = value;
+  }
+  if (merged.prependPath.length === 0) return;
+  const current = input.env[pathKey] ?? process.env[pathKey] ?? '';
+  const parts = [...merged.prependPath, ...current.split(path.delimiter).filter(Boolean)];
+  input.env[pathKey] = [...new Set(parts)].join(path.delimiter);
+}

package/src/ide-env.js

@@ -0,0 +1,101 @@
+// Reads the IDE terminal environment over MCP and extracts the SDK-related
+// variables. The IDE terminal is the single source of truth for the environment
+// the IDE actually runs with (version-managed Node, goenv Go, SDKMAN Java, ...).
+
+import { callTool } from './idea-mcp.js';
+
+/** SDK-related variables worth mirroring into OpenCode's shell environment. */
+export const SDK_ENV_KEYS = [
+  'JAVA_HOME',
+  'JRE_HOME',
+  'JDK_HOME',
+  'VIRTUAL_ENV',
+  'PYTHONPATH',
+  'PYTHONHOME',
+  'GOROOT',
+  'GOPATH',
+  'GOBIN',
+  'NODE_PATH',
+  'NVM_BIN',
+  'NVM_DIR',
+  'MAVEN_HOME',
+  'M2_HOME',
+  'GRADLE_HOME',
+  'SDKMAN_DIR',
+  'CONDA_PREFIX',
+];
+
+/**
+ * Read SDK env from the IDE integrated terminal via `execute_terminal_command`.
+ * Requires the IDE MCP to be reachable and Brave Mode enabled (else the IDE
+ * waits for a confirmation and this returns `{}`).
+ *
+ * @param {number} port
+ * @param {string} projectPath
+ * @param {typeof fetch} [fetchImpl]
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function readIdeTerminalEnv(port, projectPath, fetchImpl = fetch) {
+  const result = await callTool(
+    port,
+    projectPath,
+    'execute_terminal_command',
+    { command: 'printenv', executeInShell: true, timeout: 8000, maxLinesCount: 800 },
+    { fetchImpl, timeoutMs: 15000 },
+  ).catch(() => undefined);
+  if (!result || result.isError) return {};
+  const text = (result.content ?? [])
+    .filter((part) => part.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('\n');
+  return extractSdkEnv(parseCommandOutput(text));
+}
+
+/**
+ * Parse the `execute_terminal_command` payload. It is JSON with a
+ * `command_output` field; fall back to treating the text as raw env output.
+ *
+ * @param {string} text
+ * @returns {Record<string, string>}
+ */
+export function parseCommandOutput(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed.command_output === 'string') return parsePrintenv(parsed.command_output);
+  } catch {
+    // not JSON — treat as raw printenv output
+  }
+  return parsePrintenv(text);
+}
+
+/**
+ * Parse `KEY=VALUE` lines (printenv output) into an object.
+ *
+ * @param {string} text
+ * @returns {Record<string, string>}
+ */
+export function parsePrintenv(text) {
+  const env = {};
+  for (const line of text.split('\n')) {
+    const index = line.indexOf('=');
+    if (index <= 0) continue;
+    const key = line.slice(0, index).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    env[key] = line.slice(index + 1);
+  }
+  return env;
+}
+
+/**
+ * Keep only the SDK-related variables.
+ *
+ * @param {Record<string, string>} env
+ * @returns {Record<string, string>}
+ */
+export function extractSdkEnv(env) {
+  const out = {};
+  for (const key of SDK_ENV_KEYS) {
+    if (env[key]) out[key] = env[key];
+  }
+  return out;
+}

package/src/ide-guidance.js

@@ -0,0 +1,52 @@
+// Direct IDEA MCP usage guidance injected into the model's system prompt.
+// The plugin does not modify native OpenCode tools.
+
+/** The guidance text appended to the system prompt. */
+export const IDE_GUIDANCE = [
+  '## 项目内操作优先使用 IDEA MCP 工具',
+  '当前项目已在 JetBrains IDE 中打开。普通工具调用名称是 `idea_<name>`,例如 `idea_search_text`、`idea_read_file`、`idea_apply_patch`;项目内检索、读文件、改文件、校验和目录浏览优先直接调用这些 IDEA MCP 工具。',
+  '直接调用工具本身,不要为了调用 IDEA MCP 工具再包一层额外的 JavaScript 编排代码。',
+  '',
+  '常用工具与关键参数:',
+  '- 文本 / 正则 / 文件名检索:`idea_search_text` / `idea_search_regex` / `idea_search_file` —— 参数 `q`(不是 `query`),可带 `paths` 收窄。',
+  '- 符号 / 语义:`idea_search_symbol` / `idea_get_symbol_info` / `idea_analyze_calls`(只用 `depth=1`)。',
+  '- 读文件:`idea_read_file`(`file_path` / `offset` / `limit`)。',
+  '- 目录浏览:`idea_list_directory_tree`(代替 `ls` / `find`,`maxDepth` ≥ 2)。',
+  '- 修改已有文件:`idea_apply_patch`(参数 `input`,传 patch 文本)。',
+  '- 新建文件:`idea_create_new_file`(参数 `pathInProject`,可选 `text` / `overwrite`)。',
+  '- 校验:`idea_lint_files` / `idea_get_file_problems` / `idea_build_project`。',
+  '- 重构 / 格式化:`idea_rename_refactoring` / `idea_reformat_file`。',
+  '- 结构 / 依赖:`idea_get_project_modules` / `idea_get_project_dependencies`。',
+  '- 版本状态:`idea_git_status`;终端命令:`idea_execute_terminal_command`。',
+  '',
+  '调用纪律:',
+  '- 直接调用当前工具 schema 中声明的参数,不要猜参数名;工具自身的 description 是参数使用的权威来源。',
+  '- 工具返回 `File already exists` 等业务错误时,先修正调用参数,不要判断成工具不存在。',
+  '- 如果 IDEA MCP 未连接、工具缺失、连接被拒绝或超时,立即提示用户执行 `/open-in-idea`,不要反复探测或长时间等待。',
+  '',
+  '例外(直接使用原生工具):`node_modules/`、`target/` 等 IDE 不索引的目录;`git diff` / `log` / `blame` 等 git 独有语义;`lsof` / `nc` / `ping` 等 MCP 无等价能力;IDE MCP 未连接 / 未注册;项目根之外的文件。',
+].join('\n');
+
+export const MCP_RECOVERY_GUIDANCE = [
+  '### IDEA MCP failure recovery',
+  'If an idea.* / idea_* tool is missing, MCP is disconnected, the connection is refused, or a tool times out: stop retrying immediately; do not run extra probes or wait in tool calls. Tell the user that IDEA MCP is unavailable and ask them to run /open-in-idea to reconnect.',
+].join('\n');
+
+/**
+ * Push the guidance onto a session `system` array. Called for every primary
+ * model request, so it stays idempotent per request.
+ *
+ * @param {unknown} system
+ */
+export function appendIdeGuidance(system) {
+  if (!Array.isArray(system)) return;
+  if (system.some((part) => part?.text === IDE_GUIDANCE)) return;
+  system.push({ type: 'text', text: IDE_GUIDANCE });
+}
+
+/** @param {unknown} system */
+export function appendIdeRecoveryGuidance(system) {
+  if (!Array.isArray(system)) return;
+  if (system.some((part) => part?.text === MCP_RECOVERY_GUIDANCE)) return;
+  system.push({ type: 'text', text: MCP_RECOVERY_GUIDANCE });
+}

package/src/ide-launcher.js

@@ -0,0 +1,96 @@
+// Launching the JetBrains IDE for a project.
+//
+// RE-ENTRANCY: the Toolbox CLI scripts in /usr/local/bin (`idea`, `webstorm`,
+// ...) run `open -na "<app>" --args <dir>` — `-n` forces a NEW IDE instance, so
+// repeated calls spawn duplicates. We instead run `open -a "<app>" <dir>`,
+// which hands the directory to an already-running instance (macOS "open
+// documents" event) and only launches the app when none is running. Verified on
+// macOS: `open -a "IntelliJ IDEA"` while IDEA is up leaves the process count
+// unchanged.
+//
+// The caller performs the MCP availability check and fast-fails when it is
+// unavailable; this module only requests opening/activating the project.
+
+import { spawn } from 'node:child_process';
+
+/** Default macOS app name for IntelliJ IDEA. */
+export const DEFAULT_IDE_APP = 'IntelliJ IDEA';
+
+/** Aliases accepted by the `openInIde` option. */
+export const IDE_APPS = {
+  idea: 'IntelliJ IDEA',
+  intellij: 'IntelliJ IDEA',
+  'intellij-idea': 'IntelliJ IDEA',
+};
+
+/**
+ * Resolve the `openInIde` option to a macOS app name, or `undefined` to disable.
+ *
+ * @param {boolean | string | undefined} value
+ * @returns {string | undefined}
+ */
+export function resolveIdeApp(value) {
+  if (value === false) return undefined;
+  if (typeof value !== 'string') return DEFAULT_IDE_APP;
+  return IDE_APPS[value.toLowerCase()] ?? value;
+}
+
+/**
+ * Open `directory` in the IDE, reusing a running instance when possible.
+ * Never throws; resolves `true` when `open` reported success.
+ *
+ * @param {string} directory
+ * @param {{ app?: string, spawnImpl?: typeof spawn }} [options]
+ * @returns {Promise<boolean>}
+ */
+export function openInIde(directory, options = {}) {
+  const app = options.app || DEFAULT_IDE_APP;
+  const spawnImpl = options.spawnImpl || spawn;
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl('open', ['-a', app, directory], { stdio: 'ignore' });
+    } catch {
+      resolve(false);
+      return;
+    }
+    child.once('error', () => resolve(false));
+    child.once('close', (code) => resolve(code === 0));
+  });
+}
+
+/**
+ * Per-directory launch guard. Prevents a cold IDE (indexing / waiting for the
+ * Trust dialog) from being spawned repeatedly by overlapping reconciles or
+ * command invocations.
+ *
+ * @param {{ cooldownMs?: number, maxAttempts?: number, now?: () => number }} [options]
+ */
+export function createLaunchGuard(options = {}) {
+  const cooldownMs = options.cooldownMs ?? 120000;
+  const maxAttempts = options.maxAttempts ?? 5;
+  const now = options.now ?? Date.now;
+  let lastSpawnAt = 0;
+  let attempts = 0;
+  const coolingDown = () => attempts > 0 && now() - lastSpawnAt < cooldownMs;
+  return {
+    /** True once the attempt budget is spent; callers should stop retrying. */
+    exhausted: () => attempts >= maxAttempts,
+    /** True while a recent spawn is still expected to come up. */
+    coolingDown,
+    /** True when it is safe to spawn a new instance now. */
+    canSpawn: () => attempts < maxAttempts && !coolingDown(),
+    /** Record a spawn attempt. */
+    markSpawn() {
+      lastSpawnAt = now();
+      attempts += 1;
+    },
+    /** Clear the guard after the IDE is confirmed serving. */
+    reset() {
+      lastSpawnAt = 0;
+      attempts = 0;
+    },
+    /** Current state, for diagnostics/tests. */
+    state: () => ({ lastSpawnAt, attempts }),
+  };
+}

package/src/idea-mcp.js

@@ -0,0 +1,195 @@
+// JetBrains IDE MCP server: endpoint config and availability probe.
+//
+// HOW THE IDE MCP SERVER WORKS (verified against a real IntelliJ IDEA 2026.2
+// server):
+//
+//   * The IDE exposes a local MCP server. IntelliJ 2026.2+ exposes the modern
+//     Streamable-HTTP endpoint at `http://127.0.0.1:<port>/stream`; older builds
+//     only had the legacy SSE endpoint at `/sse`.
+//   * OpenCode V2's remote MCP client speaks ONLY Streamable HTTP, so the plugin
+//     registers `/stream` (see `serverConfig`). The legacy `/sse` endpoint is
+//     unusable from OpenCode (POST returns 405 → "Error POSTing to endpoint").
+//   * The project a call targets is selected by the HTTP header
+//     `IJ_MCP_SERVER_PROJECT_PATH`.
+//   * Availability probe: a single `initialize` POST to `/stream` succeeds when
+//     the MCP server is up. We do NOT check whether a specific project is open —
+//     the user triggers `/open-in-idea` for the project they want, so "server is
+//     up" is the only thing worth knowing.
+
+export const PROJECT_HEADER = 'IJ_MCP_SERVER_PROJECT_PATH';
+
+/** OpenCode MCP server name registered for the IDE. */
+export const IDEA_SERVER_NAME = 'idea';
+
+/** Streamable-HTTP endpoint exposed by the IDE MCP server (IntelliJ 2026.2+). */
+export const MCP_STREAM_PATH = '/stream';
+
+/** Ports to try when the IDE MCP port is not configured explicitly. */
+export const DEFAULT_PORTS = [64342, 6420, 6421, 63342];
+
+const PROTOCOL_VERSION = '2025-06-18';
+// A probe is only a local availability check. Keep it short: a disabled IDE
+// MCP endpoint must not make the user wait for the launch timeout before the
+// actionable notification is sent.
+const PROBE_TIMEOUT_MS = 1000;
+const CALL_TIMEOUT_MS = 15000;
+
+/**
+ * Build the OpenCode MCP server config for a given IDE port + project.
+ *
+ * @param {number} port
+ * @param {string} projectPath
+ */
+export function serverConfig(port, projectPath) {
+  return {
+    type: 'remote',
+    url: `http://127.0.0.1:${port}${MCP_STREAM_PATH}`,
+    headers: { [PROJECT_HEADER]: projectPath },
+  };
+}
+
+/**
+ * Is an IDE MCP server listening on `port`? One Streamable-HTTP `initialize`
+ * POST decides it: any 2xx JSON reply means the server is up.
+ *
+ * @param {number} port
+ * @param {{ fetchImpl?: typeof fetch, timeoutMs?: number }} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function probePort(port, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? PROBE_TIMEOUT_MS);
+  try {
+    const response = await fetchImpl(`http://127.0.0.1:${port}${MCP_STREAM_PATH}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
+      // Do not follow redirects. IntelliJ can keep its normal HTTP port open
+      // while MCP is disabled and redirect `/stream` to an HTML 404 page;
+      // following that redirect only adds latency and still means unavailable.
+      redirect: 'manual',
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: {},
+          clientInfo: { name: 'opencode-idea', version: '0.0.1' },
+        },
+      }),
+      signal: controller.signal,
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+}
+
+/**
+ * Find the first port whose IDE MCP server responds. Returns the port, or
+ * `undefined` when none is available.
+ *
+ * @param {number[]} ports
+ * @param {{ fetchImpl?: typeof fetch, timeoutMs?: number }} [options]
+ * @returns {Promise<number | undefined>}
+ */
+export async function findIdePort(ports, options = {}) {
+  // Probe all candidate ports concurrently. These are fallback locations for
+  // one IDE MCP endpoint, not several active MCP servers. Sequential probes
+  // multiply the timeout by the number of candidates and made a disabled MCP
+  // look like a hang.
+  const results = await Promise.all(
+    ports.map(async (port) => [port, await probePort(port, options)]),
+  );
+  return results.find(([, available]) => available)?.[0];
+}
+
+/**
+ * Call one MCP tool over the Streamable-HTTP endpoint. Returns the raw tool
+ * result (with `isError`), or `undefined` on transport/connect failure.
+ *
+ * The IDE server answers each POST with a single JSON-RPC response (it does not
+ * stream for these calls), so this is a plain request/response.
+ *
+ * @param {number} port
+ * @param {string} projectPath
+ * @param {string} name
+ * @param {object} [args]
+ * @param {{ fetchImpl?: typeof fetch, timeoutMs?: number }} [options]
+ * @returns {Promise<{ isError?: boolean, content?: Array<{ type: string, text?: string }> } | undefined>}
+ */
+export async function callTool(port, projectPath, name, args = {}, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? CALL_TIMEOUT_MS);
+  const post = (payload) =>
+    fetchImpl(`http://127.0.0.1:${port}${MCP_STREAM_PATH}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+        [PROJECT_HEADER]: projectPath,
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+  try {
+    await post({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: 'opencode-idea', version: '0.0.1' },
+      },
+    });
+    const response = await post({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: { name, arguments: args },
+    });
+    if (!response.ok) return undefined;
+    const message = await parseToolResponse(response);
+    if (!message || message.error) return undefined;
+    return message.result;
+  } catch {
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+}
+
+/** Read a JSON-RPC reply that may arrive as plain JSON or as an SSE `message`. */
+async function parseToolResponse(response) {
+  const text = await response.text();
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.includes('text/event-stream')) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return undefined;
+    }
+  }
+  for (const block of text.split('\n\n')) {
+    const data = block
+      .split('\n')
+      .filter((line) => line.startsWith('data:'))
+      .map((line) => line.slice('data:'.length).trim())
+      .join('\n');
+    if (!data) continue;
+    try {
+      const message = JSON.parse(data);
+      if (message.id === 2) return message;
+    } catch {
+      // ignore malformed frame
+    }
+  }
+  return undefined;
+}

package/src/idea-tool-descriptions.js

@@ -0,0 +1,39 @@
+// Adds concise, direct-call guidance to IDEA MCP tool descriptions.
+//
+// This transform only targets tools whose effective IDs belong to the IDEA MCP
+// namespace. Native OpenCode tools are intentionally left untouched.
+
+const IDEA_TOOL_PREFIX = /^(idea_|idea\.)/;
+const IDEA_EDITING_TOOLS = new Set(['idea_apply_patch', 'idea_create_new_file']);
+
+export const IDEA_DIRECT_NOTE =
+  '【IDEA MCP】项目内操作请直接调用本工具;参数严格按当前工具 schema,不要猜测参数名。';
+
+export const IDEA_EDIT_NOTE =
+  '【IDEA MCP 编辑】项目内文件编辑请直接调用本工具;已有文件使用 idea_apply_patch,新文件使用 idea_create_new_file;不要用 shell 写项目文件。';
+
+const isIdeaTool = (id) => typeof id === 'string' && IDEA_TOOL_PREFIX.test(id);
+
+const noteFor = (id) => IDEA_EDITING_TOOLS.has(id) ? IDEA_EDIT_NOTE : IDEA_DIRECT_NOTE;
+
+/**
+ * Prepend direct-call guidance to IDEA MCP tool descriptions only.
+ * The transform is idempotent and ignores missing descriptions.
+ *
+ * @param {{
+ *   list: () => ReadonlyArray<{ id?: string }>,
+ *   update: (id: string, update: (tool: { description?: string }) => void) => void,
+ * }} editor
+ */
+export function applyIdeaToolGuidance(editor) {
+  for (const tool of editor.list()) {
+    const id = tool?.id;
+    if (!isIdeaTool(id)) continue;
+    editor.update(id, (draft) => {
+      if (typeof draft.description !== 'string') return;
+      const note = noteFor(id);
+      if (draft.description.startsWith(note)) return;
+      draft.description = note + draft.description;
+    });
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export { default } from './plugin.js';

package/src/plugin.js

@@ -0,0 +1,389 @@
+// opencode-idea — OpenCode plugin entry.
+//
+// For a JetBrains project this plugin:
+//   1. injects the IDE integrated-terminal environment (JAVA_HOME / GOROOT /
+//      Node / Maven / ...) into every OpenCode shell;
+//   2. registers the IDE MCP server with OpenCode (scoped to the project via the
+//      IJ_MCP_SERVER_PROJECT_PATH header), injects direct-call guidance for
+//      IDEA MCP tools, and updates only IDEA MCP tool descriptions;
+//   3. registers the `/open-in-idea` command, which opens the current project
+//      in IntelliJ IDEA (reusing a running instance) and then loads the IDE
+//      capabilities immediately.
+//
+// Non-JetBrains projects are left untouched. Everything is manual: setup does
+// NOT probe or connect the IDE (only the IDE-terminal env is read when a probe
+// is requested). `/open-in-idea` probes, opens the IDE, and loads the IDE MCP +
+// guidance on demand.
+//
+// `Plugin.define` from `@opencode/plugin` is an identity function, so a plain
+// `{ id, setup }` object is the whole plugin contract. Exporting it directly
+// keeps this package dependency-free at runtime.
+
+import {
+  DEFAULT_PORTS,
+  IDEA_SERVER_NAME,
+  findIdePort,
+  serverConfig,
+} from './idea-mcp.js';
+import { readIdeTerminalEnv } from './ide-env.js';
+import { currentProjectPath, hasIdeaDirectory } from './project.js';
+import { applyEnv, mergeEnv } from './env.js';
+import { applyIdeaToolGuidance } from './idea-tool-descriptions.js';
+import {
+  createLaunchGuard,
+  openInIde,
+  resolveIdeApp,
+} from './ide-launcher.js';
+import {
+  appendIdeGuidance,
+  appendIdeRecoveryGuidance,
+} from './ide-guidance.js';
+
+const DEFAULT_LAUNCH_COOLDOWN_MS = 120000;
+const DEFAULT_LAUNCH_MAX_ATTEMPTS = 5;
+// MCP availability is a fast preflight. If it is not ready, fail fast and let
+// the user enable MCP + Brave Mode in IDEA before retrying the command.
+const DEFAULT_MCP_PROBE_TIMEOUT_MS = 1000;
+
+/**
+ * @typedef {{
+ *   status: 'connected' | 'mcp-unavailable' | 'launch-failed' | 'disabled',
+ *   port?: number,
+ *   opened?: boolean,
+ *   unavailableNoticeSent?: boolean
+ * }} IdeCommandResult
+ */
+
+/**
+ * @param {unknown} value
+ * @param {unknown} fallback
+ */
+const asArray = (value, fallback) => (Array.isArray(value) && value.length > 0 ? value : fallback);
+
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ */
+const asPositiveNumber = (value, fallback) =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+
+/** User-facing status text for a `/open-in-idea` result. */
+/** @param {IdeCommandResult} result */
+export function ideFeedback(result) {
+  switch (result?.status) {
+    case 'connected':
+      return 'IDE MCP 已连接;IDE MCP 与项目环境已即时加载。';
+    case 'mcp-unavailable':
+      return result?.opened
+        ? '已请求打开/激活 IntelliJ IDEA,但未检测到 MCP 服务。请在 IDEA 中开启 MCP 服务(Settings → MCP Server,需 2026.2+)并启用 Brave Mode,然后再次执行 /open-in-idea。'
+        : '未检测到 IntelliJ IDEA 的 MCP 服务。请确认 IDEA 已打开,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后再次执行 /open-in-idea。';
+    case 'launch-failed':
+      return '无法拉起 IntelliJ IDEA(未找到应用或启动失败)。请确认已安装 IDEA,或手动打开后重试 /open-in-idea。';
+    case 'disabled':
+      return '插件已通过 openInIde: false 关闭 IDE 启动。请手动打开 IntelliJ IDEA,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后重试 /open-in-idea。';
+    default:
+      return '已处理 /open-in-idea。';
+  }
+}
+
+/**
+ * The text the MODEL sees for `/open-in-idea` feedback. It is explicitly a
+ * notification, not a task: the model must only acknowledge it. The user sees
+ * the clean notice instead, via `metadata.displayText`.
+ */
+export function idePromptText(result) {
+  return [`【插件通知】${ideFeedback(result)}`, '这是发给用户的通知,你无需处理。请只回复"收到"。'].join('\n\n');
+}
+
+/** `metadata` so the UI shows the clean notice while the model sees the instruction. */
+export function idePromptMetadata(result) {
+  return { displayText: ideFeedback(result), comments: [] };
+}
+
+export default {
+  id: 'opencode-idea',
+
+  /**
+   * @param {{
+   *   location?: unknown,
+   *   options?: {
+   *     ports?: number[],
+   *     injectEnv?: boolean,
+   *     openInIde?: boolean | string,
+   *     launchCooldownMs?: number,
+   *     launchMaxAttempts?: number,
+   *     mcpProbeTimeoutMs?: number,
+   *     feedback?: false | 'message',
+   *   },
+   *   command?: {
+   *     transform: (cb: (editor: { add: (definition: {
+   *       name: string,
+   *       description?: string,
+   *       execute: (input: { sessionID: string, prompt: { text: string }, delivery: unknown }) => Promise<void>,
+   *     }) => void }) => void) => Promise<{ dispose: () => Promise<void> | void }>,
+   *   },
+   *   session?: {
+   *     prompt: (input: { sessionID: string, text: string, delivery: unknown }) => Promise<unknown>,
+   *     hook: (name: string, cb: (event: { system?: unknown[] }) => void) => Promise<{ dispose: () => Promise<void> | void }>,
+   *   },
+   *   tool: {
+   *     transform: (cb: (editor: {
+   *       list: () => ReadonlyArray<{ id?: string }>,
+   *       update: (id: string, update: (tool: { description?: string }) => void) => void,
+   *     }) => void) => Promise<{ dispose: () => Promise<void> | void }>,
+   *   },
+   *   mcp: {
+   *     transform: (cb: (editor: { set: (name: string, config: unknown) => void }) => void) => Promise<{ dispose: () => Promise<void> | void }>,
+   *     reload?: () => Promise<void>,
+   *   },
+   *   shell: { hook: (name: string, cb: (input: { env: Record<string, string | undefined> }) => void) => Promise<{ dispose: () => Promise<void> | void }> },
+   * }} ctx
+   */
+  async setup(ctx) {
+    const projectPath = currentProjectPath(ctx.location);
+    if (!projectPath) return;
+
+    const options = ctx.options || {};
+    const ports = asArray(options.ports, DEFAULT_PORTS);
+    const injectEnv = options.injectEnv !== false;
+    const injectGuidance = options.injectGuidance !== false;
+    const ideApp = resolveIdeApp(options.openInIde);
+    const mcpProbeTimeoutMs = asPositiveNumber(options.mcpProbeTimeoutMs, DEFAULT_MCP_PROBE_TIMEOUT_MS);
+    // "message" (default) injects a clearly-labelled notification that the
+    // model only acknowledges ("收到"); the user sees the clean notice via
+    // metadata.displayText. false is silent.
+    const feedback = options.feedback === false ? false : 'message';
+    const guard = createLaunchGuard({
+      cooldownMs: asPositiveNumber(options.launchCooldownMs, DEFAULT_LAUNCH_COOLDOWN_MS),
+      maxAttempts: asPositiveNumber(options.launchMaxAttempts, DEFAULT_LAUNCH_MAX_ATTEMPTS),
+    });
+
+    /** @type {number | undefined} */
+    let activePort;
+    let currentEnv = { env: {}, prependPath: [] };
+
+    /** @type {Array<{ dispose: () => Promise<void> | void }>} */
+    let registrations = [];
+    /** @type {{ dispose: () => Promise<void> | void } | undefined} */
+    let shellRegistration;
+    /** @type {{ dispose: () => Promise<void> | void } | undefined} */
+    let sessionRegistration;
+    /** @type {{ dispose: () => Promise<void> | void } | undefined} */
+    let commandRegistration;
+    let disposed = false;
+
+    const deactivateIde = async () => {
+      activePort = undefined;
+      const current = registrations.slice();
+      registrations.length = 0;
+      if (current.length === 0) return;
+      for (const registration of current) {
+        try {
+          await registration.dispose();
+        } catch {
+          // best effort
+        }
+      }
+    };
+
+    const activateIde = async (port) => {
+      const toolRegistration = await ctx.tool.transform((editor) => {
+        applyIdeaToolGuidance(editor);
+      });
+      const mcpRegistration = await ctx.mcp.transform((editor) => {
+        editor.set(IDEA_SERVER_NAME, serverConfig(port, projectPath));
+      });
+      registrations = [toolRegistration, mcpRegistration];
+      activePort = port;
+      if (typeof ctx.mcp.reload === 'function') await ctx.mcp.reload();
+    };
+
+    const reconcileOnce = async ({ probeIde = true } = {}) => {
+      if (disposed) return;
+
+      // Manual: only `/open-in-idea` probes the IDE. Setup calls this with
+      // `probeIde: false` so it never connects until the command asks.
+      const port = probeIde ? await findIdePort(ports, { timeoutMs: mcpProbeTimeoutMs }) : undefined;
+      const isJetBrains = hasIdeaDirectory(projectPath) || port !== undefined;
+      if (!isJetBrains) {
+        currentEnv = { env: {}, prependPath: [] };
+        await deactivateIde();
+        return;
+      }
+
+      // Environment: read from the IDE integrated terminal, the single source
+      // of truth for the environment the IDE actually runs with (version-managed
+      // Node, goenv Go, SDKMAN Java, Maven, ...). Only available once the IDE is
+      // connected, which is why the manual `/open-in-idea` drives it.
+      const terminal = port === undefined ? {} : await readIdeTerminalEnv(port, projectPath);
+      currentEnv = mergeEnv([{ env: terminal }]);
+
+      if (injectEnv && !shellRegistration) {
+        shellRegistration = await ctx.shell.hook('create.before', (input) => applyEnv(input, currentEnv));
+      }
+
+      if (port === activePort) return;
+      await deactivateIde();
+      if (port !== undefined) await activateIde(port);
+    };
+
+    // Serialize reconciles so overlapping callers can never register/activate
+    // the IDE concurrently (which would leak registrations).
+    let reconcileChain = Promise.resolve();
+    const reconcile = (options) => {
+      const next = reconcileChain.then(() => reconcileOnce(options));
+      reconcileChain = next.then(
+        () => {},
+        () => {},
+      );
+      return next;
+    };
+
+    // Re-entrant: repeat invocations share one open request so the IDE is not
+    // spawned twice while the application is starting.
+    /** @type {Promise<IdeCommandResult> | undefined} */
+    let launchInFlight;
+    let launchNoticeSent = false;
+    /**
+     * @param {{ onUnavailable?: (result: IdeCommandResult) => Promise<boolean> }} [options]
+     * @returns {Promise<IdeCommandResult>}
+     */
+    const ensureIde = ({ onUnavailable } = {}) => {
+      if (launchInFlight) return launchInFlight;
+      launchNoticeSent = false;
+      const reportUnavailable = async (opened) => {
+        if (launchNoticeSent || typeof onUnavailable !== 'function') return;
+        // Fast-fail: notify as soon as the endpoint is known to be missing so
+        // the user can enable MCP + Brave Mode and retry the command.
+        const delivered = await onUnavailable({ status: 'mcp-unavailable', opened });
+        if (delivered) launchNoticeSent = true;
+      };
+      const run = (async () => {
+        const serving = await findIdePort(ports, { timeoutMs: mcpProbeTimeoutMs }).catch(() => undefined);
+        if (serving !== undefined) {
+          guard.reset();
+          launchNoticeSent = false;
+          return { status: 'connected', port: serving, unavailableNoticeSent: false };
+        }
+        if (!ideApp) return { status: 'disabled' };
+        if (guard.exhausted()) {
+          await reportUnavailable(false);
+          return { status: 'mcp-unavailable', opened: false, unavailableNoticeSent: launchNoticeSent };
+        }
+        if (guard.coolingDown()) {
+          // There is no reason to wait here: MCP is disabled/not ready, and
+          // the user must enable it in IDEA before retrying the command.
+          await reportUnavailable(false);
+          return { status: 'mcp-unavailable', opened: false, unavailableNoticeSent: launchNoticeSent };
+        }
+        guard.markSpawn();
+        const launched = await openInIde(projectPath, { app: ideApp });
+        if (!launched) return { status: 'launch-failed' };
+        // `open -a` only requests activation/opening. Fast-fail if the MCP
+        // endpoint is not already available; the user can enable it in IDEA
+        // and run `/open-in-idea` again instead of waiting on a timer.
+        await reportUnavailable(true);
+        return { status: 'mcp-unavailable', opened: true, unavailableNoticeSent: launchNoticeSent };
+      })();
+      launchInFlight = run;
+      void run
+        .catch(() => {})
+        .then(() => {
+          if (launchInFlight === run) launchInFlight = undefined;
+        });
+      return run;
+    };
+
+    // Setup never probes or connects the IDE — everything is on `/open-in-idea`.
+    await reconcile({ probeIde: false });
+
+    const sendFeedback = async (input, result) => {
+      if (feedback !== 'message' || typeof ctx.session?.prompt !== 'function') return false;
+      try {
+        await ctx.session.prompt({
+          ...input.prompt,
+          sessionID: input.sessionID,
+          text: idePromptText(result),
+          metadata: idePromptMetadata(result),
+          delivery: input.delivery,
+        });
+        return true;
+      } catch {
+        // feedback is best effort
+        return false;
+      }
+    };
+
+    // `/open-in-idea`: manual, re-entrant trigger that also loads the IDE
+    // capabilities immediately.
+    if (typeof ctx.command?.transform === 'function') {
+      commandRegistration = await ctx.command.transform((editor) => {
+        editor.add({
+          name: 'open-in-idea',
+          description: '用 IntelliJ IDEA 打开当前项目,并即时加载 IDE MCP 与项目 SDK 环境',
+          execute: async (input) => {
+            /** @type {boolean} */
+            let unavailableNoticeSent = false;
+            const result = await ensureIde({
+              onUnavailable: async (notice) => {
+                unavailableNoticeSent = await sendFeedback(input, notice);
+                return unavailableNoticeSent;
+              },
+            });
+            const { port, status, unavailableNoticeSent: resultNoticeSent } = result;
+            try {
+              // Do not repeat the expensive probe when the preflight already
+              // found no MCP endpoint. The command will retry after the user
+              // enables MCP + Brave Mode.
+              await reconcile({ probeIde: port !== undefined });
+            } catch {
+              // capability load is best effort; feedback still matters
+            }
+            // The unavailable notice is the final result for this command. If
+            // it was already delivered, do not show the same warning twice.
+            const unavailableAlreadySent = unavailableNoticeSent || resultNoticeSent;
+            if (!unavailableAlreadySent || status !== 'mcp-unavailable') {
+              await sendFeedback(input, result);
+            }
+          },
+        });
+      });
+    }
+
+    // Direct-call guidance: while the IDEA MCP is available, append concise
+    // routing rules to every primary request. Native tools are left untouched.
+    if (injectGuidance && typeof ctx.session?.hook === 'function') {
+      sessionRegistration = await ctx.session.hook('context', (event) => {
+        appendIdeRecoveryGuidance(event?.system);
+        if (activePort === undefined) return;
+        appendIdeGuidance(event?.system);
+      });
+    }
+
+    return async () => {
+      disposed = true;
+      if (shellRegistration) {
+        try {
+          await shellRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
+      if (sessionRegistration) {
+        try {
+          await sessionRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
+      if (commandRegistration) {
+        try {
+          await commandRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
+      await deactivateIde();
+    };
+  },
+};

package/src/project.js

@@ -0,0 +1,29 @@
+// Pure helpers for locating the current OpenCode project.
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Resolve the absolute project root for the current plugin location.
+ * OpenCode exposes a `Location.Info` on the plugin context.
+ *
+ * @param {{ directory?: string, project?: { directory?: string } } | undefined} location
+ * @returns {string | undefined}
+ */
+export function currentProjectPath(location) {
+  if (!location) return undefined;
+  const projectDirectory = location.project && location.project.directory;
+  return projectDirectory || location.directory || undefined;
+}
+
+/**
+ * True when the directory looks like a JetBrains project (has a `.idea` folder).
+ * This is a convenience signal only; the plugin does not require it, because an
+ * IDE may have created the project entry without writing `.idea` yet.
+ *
+ * @param {string | undefined} directory
+ * @returns {boolean}
+ */
+export function hasIdeaDirectory(directory) {
+  return typeof directory === 'string' && existsSync(path.join(directory, '.idea'));
+}