opencode-idea 0.0.9 → 0.0.11

package/README.md

@@ -8,39 +8,62 @@ OpenCode 插件,面向 JetBrains 项目 (IntelliJ IDEA / PyCharm / WebStorm 等)
    (正常回退,无需声明)。
 3. **注入 IDE 环境变量** —— 从 IDE 集成终端读取它实际运行的环境,注入每个 OpenCode shell。
 
-非 JetBrains 项目完全不受影响。 **全手动**:插件启动不探测、不连接 IDE,只有跑 `/open-in-idea` 才接入;接入之后也没有
-任何自主动作(环境变量只在 `/open-in-idea` 时刷新)。
+非 JetBrains 项目完全不受影响。 **手动接入**:插件启动不探测、不连接 IDE,只有跑 `/open-in-idea` 才接入。跑过一次后,该**项目**
+被「标记」(持久化在 `ctx.storage`,重启 OpenCode 后仍在):之后插件在后台**每 5s 探活**该 IDE——**掉线就注销 `idea` MCP**(杀掉不会自愈的
+stdio 僵尸桥 + 移除 `idea_*` 工具,让模型调不到、**不会挂起**),并锁存"待重建";**下一条用户消息**读到锁存后**静默重建**(用户无感)。
+`/close-in-idea` 注销 IDE MCP + 删除标记。没跑过 `/open-in-idea` 的项目保持全手动、零自主动作。
 
 ## 工作原理
 
 ```text
-setup(启动):
-  a. 读 IDE 集成终端环境 → 通过 shell create.before 钩子注入每个 shell(null: 未连 IDE 时为空)
-  b. 注册 /open-in-idea 命令 + session context 钩子(注入引导)
+setup(启动, 每项目一次):
+  a. 读项目标记(ctx.storage: project/<项目路径>; OpenCode 重启后仍生效)
+  b. 读 IDE 集成终端环境 → 通过 shell create.before 钩子注入每个 shell(null: 未连 IDE 时为空)
+  c. 注册 /open-in-idea 与 /close-in-idea 命令 + session context 钩子 + tool execute.after 钩子
   不探测、不注册 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. 发一条结果通知(用户看到干净气泡,模型只回"收到")
+/open-in-idea(手动触发, 阻塞到就绪):
+  1. 写项目标记 = true + 同步内存缓存;注册 `idea-run-config` skill
+  2. 探测本地 JetBrains IDE MCP 服务(/stream)
+  3. 未就绪 → open -a "IntelliJ IDEA" <项目目录>(复用已运行实例),然后轮询等到 MCP 就绪(冷启动约数十秒,上限 60s)
+  4. **先注销旧的 idea MCP(杀掉旧的 stdio 桥子进程),再重新注册**
+     (`idea stdioMcpServer`,env 带项目路径 + 端口;每项目一个子进程)
+     —— 每次执行都重建,因为断掉的桥不会自愈、也不能靠 refresh 复活
+  5. 等 `idea_*` 工具进入注册表;读 IDE 终端环境更新 shell 环境;启用引导
+  6. 发结果通知(用户看到干净气泡,模型只回"收到")
+
+/close-in-idea(手动触发):
+  1. 删项目标记 + 同步内存缓存 + 注销 IDE MCP + 清空注入的环境
+  2. 发结果通知
+
+工具失败触发(仅在被标记的项目里;需先 /open-in-idea 过一次):
+  1. `idea_*` 工具调用失败 → tool execute.after 钩子**分类**:
+     - IDE MCP 不可用(掉了)→ 重跑接入流程
+     - IDE 在、但项目没打开("Unable to determine the target project" / "doesn't correspond to any open project")→ 让 IDEA 重新打开该项目
+     - 普通业务错误(File not found 等)→ 不动作
+  2. 触发成功 → 把该错误改写为"已重连 / 已重新打开,请重试",模型同一回合重试;失败 → 保持原错误
+
+后台探活(心跳;仅"已标记 + 桥已注册"的项目):
+  1. 每 5s 探测 IDE 端口(/stream);连续 2 次不通 →
+  2. **注销 `idea` MCP**:杀掉僵尸桥子进程 + 从注册表移除 `idea_*` 工具
+     (→ 模型调不到,也就不会挂起;这一步是"从根上避免挂起"的关键)
+  3. 锁存 `needRebuild = true`(不会因端口恢复而清,因为桥不会自愈)
+  4. 下一条用户消息:纯内存读到锁存 → 自动重跑接入流程(IDE 不在则 `open -a` 拉起),成功后清锁存
+     —— 全程静默,用户无感
+  ※ 这是**每个 Location(项目)各跑一份**探活;IDE 只有一个,所以所有项目的桥几乎同时被注销、再各自重建
 ```
 
 ## 在 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。
+1. 先探测 `/stream`;已就绪 → 直接进入下一步;
+2. 未就绪 → 用 `open -a "IntelliJ IDEA" <项目目录>` 拉起或激活 IDEA —— **复用已运行的实例**(不会重复开新实例),然后
+   **轮询等到 MCP 就绪**(冷启动约数十秒,上限 60s);
+3. 等不到(例如 IDE 里 MCP 服务未开启)→ 提示在 IDEA 的 `Settings → MCP Server` 开启 MCP 服务并启用 **Brave Mode**,用户设置好后
+   再次执行 `/open-in-idea`;
+4. 就绪后 **先注销旧的 `idea` MCP(杀掉旧的 stdio 桥子进程)→ 再重新注册**(每次执行都重建,因为断掉的桥不会自愈),然后重读
+   IDE 环境、启用系统引导,并**等到 `idea_*` 工具进入注册表**才返回。
 
 > **通知不触发 AI 干活**:默认 `feedback: "message"` 把结果作为一条 **标注清楚的通知**发到会话里 —— 用户看到干净的通知气泡
 > (经 `metadata.displayText`),模型只看到"这是通知,请只回复『收到』"的指令,因此不会执行任何操作、不会调用工具。
@@ -53,6 +76,11 @@ Brave Mode 后再次执行 `/open-in-idea` 即可接上。
 **热更新会断开**:插件源码变更会触发 V2 热重载,注册随旧实例一起释放,`activePort` 归零。这是手动模式的预期行为 ——
 **改完插件后重跑一次 `/open-in-idea`** 即可恢复。
 
+## 关闭接入 (`/close-in-idea`)
+
+输入 `/close-in-idea`:**注销当前项目的 IDE MCP** + 删除项目标记(持久化 + 内存缓存一并清),并清空注入的环境变量。
+之后 `idea_*` 工具不再可用,也不会再因失败自动接入。想重新接入,再次执行 `/open-in-idea`。
+
 ## IDE 工具优先 (直接调用引导)
 
 IDE MCP 可用时,插件通过 **系统提示注入**提高模型主动使用 IDEA MCP 的概率;不修改任何工具 (原生或 IDEA)
@@ -78,7 +106,7 @@ IDE MCP 可用时,插件通过 **系统提示注入**提高模型主动使用 ID
 ## Run Configuration 管理 (skill)
 
 IDE MCP 只能 **查**(`get_run_configurations`)和 **执行**(`execute_run_configuration`)run configuration, **没有增删改**
-。插件在 **JetBrains 项目**(存在 `.idea`)里注册一个 `idea-run-config` skill 来补上这块:
+。插件在**被标记的项目**里注册一个 `idea-run-config` skill 来补上这块:
 
 - 只操作 **项目级** `.run/<name>.run.xml`(可提交 git、团队共享), **不碰** `.idea/workspace.xml`;
 - 不内置任何按类型的模板 —— 先找项目里的 **真实样本**(`**/*.run.xml`,或让用户在 IDEA 里勾 "Store as project file"
@@ -86,9 +114,9 @@ IDE MCP 只能 **查**(`get_run_configurations`)和 **执行**(`execute_run_conf
 - 写完必须用 `idea_get_run_configurations` **校验它能被列出**、并用 `idea_execute_run_configuration` **实跑确认**;
 - 改配置用 `idea_apply_patch` **定向改 option**,不整文件重写。
 
-skill 由 `ctx.skill.transform` 在插件 `setup` 时注册, **与 `/open-in-idea` 无关**;非 JetBrains 项目不受影响。文档放在
-`skills/<id>/SKILL.md`(每个 skill 一个目录,`name` / `description` 走 YAML frontmatter),由 `src/skill/loader.js` 扫描加载 ——
-**加新 skill 只需加一个目录,不用改代码**。
+**skill 的生命周期跟随项目标记**:`/open-in-idea` 打标记时注册、`/close-in-idea` 清标记时注销;曾被标记过的项目在
+`setup` 时(读回标记)就会注册。未标记的项目不受影响。文档放在 `skills/<id>/SKILL.md`(每个 skill 一个目录,`name` /
+`description` 走 YAML frontmatter),由 `src/skill/loader.js` 扫描加载 —— **加新 skill 只需加一个目录,不用改代码**。
 
 ## 环境变量注入
 
@@ -110,19 +138,39 @@ skill 由 `ctx.skill.transform` 在插件 `setup` 时注册, **与 `/open-in-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 配置形如:
+- 插件注册给 OpenCode 的 MCP 配置。默认用 **stdio 桥**:
 
 ```jsonc
 {
-  "type": "remote",
-  "url": "http://127.0.0.1:64342/stream",
-  "headers": { "IJ_MCP_SERVER_PROJECT_PATH": "<项目路径>" },
+  "type": "local",
+  // OpenCode 的 `LocalConfig.command` 是【字符串数组】:可执行文件 + 参数
+  // (源码 `client.ts` 里 `const [command, ...args] = config.command`)。没有单独的 `args` 字段。
+  "command": ["/Applications/IntelliJ IDEA.app/Contents/MacOS/idea", "stdioMcpServer"],
+  "environment": {
+    "IJ_MCP_SERVER_PROJECT_PATH": "<项目路径>",
+    "IJ_MCP_SERVER_PORT": "64342",
+  },
 }
 ```
 
-> **为什么是 `/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`),协议统一。
+`idea stdioMcpServer` 是 IDE 自带的桥:OpenCode 通过 **stdin/stdout 子进程管道**跟它通信,它在后端连 IDE 的 MCP。
+**客户端侧是持久管道,不存在 HTTP 空闲断流**——这正是默认选它的原因。每个项目一个插件实例、各带自己的
+`IJ_MCP_SERVER_PROJECT_PATH`,所以每个项目会起一个独立的 stdio 客户端进程。
+
+> **为什么不用远程 `/stream`**:Streamable HTTP 的客户端会挂一条用于 server→client 通知的 SSE 流;这条流**空闲一段时间会
+> 被关**,而**远程传输在客户端侧不重连**(OpenCode 只为 legacy session 过期重连)。于是"闲置一会儿"就会掉。stdio 桥没有这个
+> 问题。`transport: "http"` 可切回远程模式:
+>
+> ```jsonc
+> {
+>   "type": "remote",
+>   "url": "http://127.0.0.1:64342/stream",
+>   "headers": { "IJ_MCP_SERVER_PROJECT_PATH": "<项目路径>" },
+> }
+> ```
+>
+> **为什么不用 `/sse`**:OpenCode V2 的远程 MCP 客户端**只支持 Streamable HTTP**,没有旧版 SSE 传输。IDE 的 `/sse` 是旧版
+> SSE (POST 返回 405),V2 连不上。插件对 IDE 的**探测**仍走 `/stream`(一次 `initialize`),用来确认 IDE MCP 已就绪并拿到端口。
 
 插件按 `ports` 顺序选择第一个可用端口,但会并发探测以避免多个端口的超时叠加;默认 `[64342]`。
 
@@ -187,9 +235,14 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
         "injectEnv": true,
         "injectGuidance": true, // IDE 可用时向系统提示注入「优先使用 IDEA MCP」引导
         "openInIde": "idea", // false 关闭;或任意 macOS 应用名(如 "IntelliJ IDEA")
+        "transport": "stdio", // "stdio"(默认,本地桥,不会空闲断流)| "http"(远程 Streamable HTTP)
+        "ideExecutable": undefined, // 可显式指定 IDE 可执行文件;默认从 .app 里推断
         "launchCooldownMs": 120000, // 启动保护冷却
         "launchMaxAttempts": 5,
         "mcpProbeTimeoutMs": 1000, // 单个 MCP 端口的短探测超时
+        "executionTimeoutMs": 600000, // 单次 idea_* 工具调用硬上限;默认 10 分钟(OpenCode 默认 12 小时)
+        "heartbeatIntervalMs": 5000, // 后台端口探活间隔
+        "heartbeatFailures": 2, // 连续失败几次后注销 idea MCP
         "feedback": "message", // "message"(默认,会话通知,AI 只回"收到")| false(静默)
       },
     },
@@ -199,29 +252,46 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
 
 不传 options 时全部使用下表默认值。
 
-| 选项                | 类型                 | 默认        | 说明                                                             |
-| ------------------- | -------------------- | ----------- | ---------------------------------------------------------------- |
-| `ports`             | `number[]`           | `[64342]`   | 依次探测的 IDE MCP 端口                                          |
-| `injectEnv`         | `boolean`            | `true`      | 是否注入 IDE 终端环境变量                                        |
-| `injectGuidance`    | `boolean`            | `true`      | IDE 可用时是否向系统提示注入「优先使用 IDEA 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` 静默 |
+| 选项                  | 类型                 | 默认        | 说明                                                                                    |
+| --------------------- | -------------------- | ----------- | --------------------------------------------------------------------------------------- |
+| `ports`               | `number[]`           | `[64342]`   | 依次探测的 IDE MCP 端口                                                                 |
+| `injectEnv`           | `boolean`            | `true`      | 是否注入 IDE 终端环境变量                                                               |
+| `injectGuidance`      | `boolean`            | `true`      | IDE 可用时是否向系统提示注入「优先使用 IDEA MCP」引导                                   |
+| `openInIde`           | `boolean \| string`  | `"idea"`    | 拉起哪个 IDE;`false` 关闭,`"idea"` 映射到 IntelliJ IDEA                                 |
+| `transport`           | `"stdio" \| "http"`  | `"stdio"`   | `stdio` 注册 IDE 自带的 stdio 桥(本地子进程,不会空闲断流);`http` 用远程 Streamable HTTP |
+| `ideExecutable`       | `string`             | (推断)      | IDE 可执行文件绝对路径;默认从 `<App>.app/Contents/MacOS/` 推断                          |
+| `launchCooldownMs`    | `number`             | `120000`    | 启动保护冷却:冷却期内不重复 spawn                                                       |
+| `launchMaxAttempts`   | `number`             | `5`         | 单次会话内最多 spawn 次数,超出后停止重试                                                |
+| `mcpProbeTimeoutMs`   | `number`             | `1000`      | 单个 MCP 端口的短探测超时                                                               |
+| `executionTimeoutMs`  | `number`             | `600000`    | 单次 `idea_*` 工具调用的硬上限(毫秒);防止桥挂起后无限等待(OpenCode 默认 12 小时)        |
+| `heartbeatIntervalMs` | `number`             | `5000`      | 后台 IDE 端口探活间隔(毫秒);仅"已标记 + 桥已注册"的项目有效                             |
+| `heartbeatFailures`   | `number`             | `2`         | 连续探活失败几次后注销 `idea` MCP(杀僵尸桥 + 移除工具),下一条消息自动重建               |
+| `feedback`            | `"message" \| false` | `"message"` | 结果反馈:`message` 会话通知(用户可见,AI 只回"收到");`false` 静默                        |
 
 ## 行为
 
-- **JetBrains 项目**:启动即注入 IDE 终端环境 (若此前已连过 IDE);`/open-in-idea` 接入 IDE MCP + 启用引导。
-- **非 JetBrains 项目**:不改环境、不注册、不注入任何 IDEA 提示 (每请求零开销)。
-- **手动接入 + 零自主动作**:启动 **不探测、不连接 IDE MCP**;注册、**环境重读**、引导注入全部由 `/open-in-idea` 触发。
-  `context` 钩子按「每次模型调用」触发 (含工具续跑),是**请求的纯函数**:它只看本次请求自带的工具快照 ——
-  有 `idea_*` 就剥离隐藏工具并注入引导,没有就只给恢复提示。**不做任何 I/O,没有缓存状态,没有定时器,没有事件订阅**。
-  一次失败的调用不会触发探测或注销,断开的连接也不会被自动重连 —— **恢复的唯一方式是用户再次执行 `/open-in-idea`**。
-- **`/open-in-idea`**:手动打开当前项目并即时加载能力 (已在 IDE 打开时则只重新加载);MCP 未开启时只发一次提示并
-  fast-fail,用户手动开启 MCP + Brave Mode 后重试。
-- **不响应工具报错**:插件**不注册** `tool.execute.after` 钩子。一次 `idea_*` 调用失败 (业务错误如 `File not found`、
-  或偶发传输抖动) 不会触发任何探测、注销或重连 —— 连接状态只由 `/open-in-idea` 决定。
+- **被标记的项目**:启动读回标记后挂上 shell 环境钩子 (环境值待接入后填充)、注册 `idea-run-config` skill;IDE MCP 由
+  `/open-in-idea` 注册。
+- **未标记的项目**:不改环境、不注册、不注入任何 IDEA 提示 (每请求零开销;setup 时只做一次项目标记读取)。
+- **手动接入 + 就绪即返回**:`/open-in-idea` 会 `open -a` 拉起 IDEA 并**等 IDE MCP 就绪**(冷启动数十秒,上限 60s);就绪后
+  **先注销旧的 `idea`(杀掉旧 stdio 桥)→ 再以 stdio 重新注册**,等 `idea_*` 工具就绪,最后才通知。**每次执行都重建**,所以断掉的
+  僵尸桥只要重跑一次命令就能恢复。命令返回即可用;`/close-in-idea` 注销 `idea` + 删标记 + 清环境。
+- **`context` 钩子是请求的纯函数**:按「每次模型调用」触发 (含工具续跑),只看本次请求自带的工具快照 —— 有 `idea_*` 就剥离隐藏
+  工具并注入引导;没有则只在项目被标记时给恢复提示。该钩子本身**不做任何 I/O**(只看内存缓存),也不订阅任何事件。
+- **后台心跳(仅"已标记 + 桥已注册"的项目)**:每 `heartbeatIntervalMs`(默认 5s)探一次 IDE 端口;连续 `heartbeatFailures`
+  (默认 2)次不通就**注销 `idea` MCP** —— 杀掉僵尸桥子进程 + 移除 `idea_*` 工具,于是模型**调不到、也就不会挂起** —— 并锁存
+  `needRebuild`。下一条用户消息在 `prompt` 钩子里读到锁存 → 自动重跑接入流程(IDE 不在则 `open -a` 拉起),成功后清锁存。**全程静默**。
+  探活是**每个 Location(项目)各一份**;IDE 只有一个,所以 IDE 一挂、所有项目的桥几乎同时被注销,再由各自的消息触发重建。
+- **失败触发的自动接入(仅被标记项目)**:`tool.execute.after` 钩子监听 `idea_*` 工具报错并**分类**:
+  - IDE MCP 不可用(掉了)→ 重跑 `/open-in-idea` 的接入流程;
+  - IDE 在、但项目没打开(`Unable to determine the target project` / `doesn't correspond to any open project`)→ 让 IDEA 重新打开该项目;
+  - 普通业务错误(`File not found` 等)→ **不动作**。判定只认**传输层专有标记**(`MCP server "idea" is not available` /
+    `MCP server is not connected` / `Error POSTing to endpoint` / `SseClientTransport is closed`),**不认**工具输出里出现的通用串
+    (例如 SQL 工具报的 `Connection refused`) —— MCP 工具错误的 message 就是工具自己的输出,认通用串会把正常业务失败误判成掉线并重建。
+    触发成功会把该工具错误改写为"已重连 / 已重新打开,请重试",模型在同一回合内重试;失败则保持原错误。非 `idea_*` 工具、未标记
+    项目都不受影响。启动保护 (`launchCooldownMs` / `launchMaxAttempts`) 限制重复拉起 IDE。
+- **`/open-in-idea`**:手动打开当前项目;**等 IDE MCP 就绪 → 先注销旧的 `idea`(杀旧桥)→ 再重新注册 → 等 `idea_*` 工具就绪**才返回。
+  **`/close-in-idea`**:注销 IDE MCP + 删项目标记 + 清空注入的环境。
 
 ## 限制
 
@@ -238,9 +308,22 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
   IDEA 里配置,AI 只读和查询)。`idea_execute_terminal_command` 也不暴露给模型 —— 它只由插件内部读取 IDE 环境,而那是插件直接调
   MCP,不经过模型工具表。
 - 探测只确认「MCP 服务是否在监听」,不校验「当前项目是否已在 IDE 打开」;MCP 关闭时会用一次短探测并立即给出设置提示。
-- OpenCode 的 MCP 自动重连**只覆盖 legacy Streamable HTTP 的 session 过期**(`SessionExpiredError`:有 session id + 404 /
-  "Server not initialized" → `recover()` + 重试该次调用);modern 端点 (IDE 2026.2,protocol 2025-06-18,不带 session id)
-  的连接被关只会置 `failed` 并移除工具,**不会自动重连**。插件刻意不补这个缺口:恢复一律走手动 `/open-in-idea`。
+- IDE **2026.2+** 提供官方 stdio 桥 (`idea stdioMcpServer`),插件默认用它注册。stdio 是子进程管道,不像 Streamable HTTP 那样
+  会空闲断流;但它**启动时要求 IDE MCP 已在监听**,所以 `/open-in-idea` 必须先等就绪再注册(冷启动约数十秒)。`transport: "http"`
+  可切回远程 Streamable HTTP(OpenCode 会因连接关闭把 server 置 failed 并移除工具,不自动重连)。
+- **stdio 的边界(已实测)**:IDE 中途退出后,桥进程会变成"僵尸"——进程还在、调用挂起、**不回任何错误**。两种情况都实测过:**调用之后**IDE 挂、
+  以及**调用进行中**IDE 挂(在 IDE 里跑 `sleep 120` 时 `kill` 掉 IDEA),桥都只在 stderr 打一行错误(`SseClientTransport is closed!` /
+  `Request timeout has expired`),**stdout 一个字节都不回**。而且**重开 IDEA 也不会自愈**(实测:重开 IDEA 后连续探测 5 分钟仍全部 TIMEOUT);
+  OpenCode 依旧显示 connected,`refresh`/`reload` 只会 `reconcile`,配置没变就跳过,不会重启它。所以:
+  - **后台心跳(见上)自动兜底**:5s 探活、连续 2 次不通就注销 `idea`(杀僵尸桥 + 移除工具),下一条消息自动重建 —— 常态下**不需要用户手动做什么**;
+  - 手动重建仍可用:重开 IDEA 后再执行一次 `/open-in-idea`(先注销旧 `idea`、再重新注册);
+  - 插件给 `idea` server 配 `executionTimeoutMs`(默认 **10 分钟**)作为硬上限:兜住"心跳尚未触发、工具已在途"的那次挂起,不再沿用 OpenCode 默认的 12 小时;
+  - "IDE 被关掉 → 工具挂起"这类**不会**走工具失败分类(没有 error);能自动分类处理的是"IDE 在、项目没打开"和"server 掉了(启动即失败)"。
+- 项目标记存在插件名下 KV (`plugin:opencode-idea:project/<项目根路径>`)。插件实例按 **Location**(项目/打开目录)创建,标记按
+  **项目根路径**共享;但两个不同 Location(例如项目根与某子目录)各有自己的内存缓存 —— 单目录打开项目的常见用法不受影响。
+- `/close-in-idea` 会**注销 IDE MCP** 并删标记 + 清空注入的环境。
+- 插件**完全不再检查 `.idea` 目录**:是否是 IDEA 项目只由项目标记(`/open-in-idea` 设置、`/close-in-idea` 清除)决定。
+  (`/open-in-idea` 会让 IDEA 打开并导入该项目,`.idea` 由 IDEA 自己生成,插件无需也不应据此判断。)
 - 打开 IDE 仅实现 macOS (`open -a`);首次打开若弹 Trust 对话框,需确认后重试。
 - IDE MCP 没有「打开项目」工具,因此打开动作走 OS/CLI,而非 MCP。
 - 插件热重载会断开 IDE 连接,需重跑 `/open-in-idea`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-idea",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "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",

package/src/ide-guidance.js

@@ -82,6 +82,16 @@ export const MCP_RECOVERY_GUIDANCE = [
   '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');
 
+/**
+ * Recovery instruction for a marked project, where the plugin reconnects the
+ * IDE MCP on its own. The model must not fall back to "ask the user" when a
+ * single connection error is all it saw — the reconnect is already happening.
+ */
+export const MCP_RECOVERY_GUIDANCE_MARKED = [
+  '### IDEA MCP failure recovery',
+  'This project is IDEA-connected and the plugin reconnects the IDE MCP automatically. When an idea_* call fails with a connection error (for example `MCP server "idea" is not available`), do not run extra probes or wait in tool calls: the reconnect is already under way, so retry the operation once. Only if it still fails, tell the user that IDEA MCP is unavailable and to run /open-in-idea.',
+].join('\n');
+
 /**
  * Push the guidance onto a session `system` array. Called for every primary
  * model request, so it stays idempotent per request.
@@ -97,9 +107,13 @@ export function appendIdeGuidance(system, projectPath) {
   system.push({ type: 'text', text });
 }
 
-/** @param {unknown} system */
-export function appendIdeRecoveryGuidance(system) {
+/**
+ * @param {unknown} system
+ * @param {{ marked?: boolean }} [options] `marked` picks the auto-reconnect variant
+ */
+export function appendIdeRecoveryGuidance(system, { marked = false } = {}) {
   if (!Array.isArray(system)) return;
-  if (system.some((part) => part?.text === MCP_RECOVERY_GUIDANCE)) return;
-  system.push({ type: 'text', text: MCP_RECOVERY_GUIDANCE });
+  const text = marked ? MCP_RECOVERY_GUIDANCE_MARKED : MCP_RECOVERY_GUIDANCE;
+  if (system.some((part) => part?.text === text)) return;
+  system.push({ type: 'text', text });
 }

package/src/ide-launcher.js

@@ -12,6 +12,8 @@
 // unavailable; this module only requests opening/activating the project.
 
 import { spawn } from 'node:child_process';
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
 
 /** Default macOS app name for IntelliJ IDEA. */
 export const DEFAULT_IDE_APP = 'IntelliJ IDEA';
@@ -35,6 +37,62 @@ export function resolveIdeApp(value) {
   return IDE_APPS[value.toLowerCase()] ?? value;
 }
 
+/** Preferred launcher binary name per app, used when `Contents/MacOS` has several. */
+const IDE_EXECUTABLES = {
+  'IntelliJ IDEA': 'idea',
+  PyCharm: 'pycharm',
+  'PyCharm Community': 'pycharm',
+  WebStorm: 'webstorm',
+  GoLand: 'goland',
+  CLion: 'clion',
+  PhpStorm: 'phpstorm',
+  RubyMine: 'rubymine',
+  Rider: 'rider',
+  DataGrip: 'datagrip',
+  'Android Studio': 'studio',
+};
+
+/**
+ * Absolute path to the IDE launcher binary (`<App>.app/Contents/MacOS/<bin>`).
+ * The stdio bridge is started by running this binary with `stdioMcpServer`.
+ *
+ * Returns undefined when the app bundle cannot be found — the caller then falls
+ * back to the remote transport.
+ *
+ * @param {string | undefined} app macOS app name, e.g. "IntelliJ IDEA"
+ * @param {{ dirs?: string[] }} [options] search roots (defaults to the two
+ *   standard Applications folders); tests pass their own.
+ * @returns {string | undefined}
+ */
+export function resolveIdeExecutable(app, options = {}) {
+  if (typeof app !== 'string' || app.length === 0) return undefined;
+  const home = process.env.HOME;
+  const dirs = options.dirs ?? [home ? path.join(home, 'Applications') : undefined, '/Applications'].filter(
+    (value) => typeof value === 'string',
+  );
+  const preferred = IDE_EXECUTABLES[app];
+  for (const dir of dirs) {
+    const macos = path.join(dir, `${app}.app`, 'Contents', 'MacOS');
+    let entries;
+    try {
+      entries = readdirSync(macos);
+    } catch {
+      continue;
+    }
+    const executable = (name) => {
+      try {
+        const stats = statSync(path.join(macos, name));
+        return stats.isFile() && (stats.mode & 0o111) !== 0;
+      } catch {
+        return false;
+      }
+    };
+    const chosen = (preferred && entries.includes(preferred) && preferred) || entries.find(executable);
+    if (chosen) return path.join(macos, chosen);
+  }
+  return undefined;
+}
+
 /**
  * Open `directory` in the IDE, reusing a running instance when possible.
  * Never throws; resolves `true` when `open` reported success.

package/src/mcp/idea.js

@@ -6,11 +6,10 @@
 //   * 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`.
+//   * The project a call targets is selected by the project path: the HTTP
+//     header `IJ_MCP_SERVER_PROJECT_PATH` for the remote transport, or the
+//     `IJ_MCP_SERVER_PROJECT_PATH` environment variable for the stdio bridge
+//     (see `serverConfig` / `stdioServerConfig`).
 //   * 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
@@ -18,6 +17,15 @@
 
 export const PROJECT_HEADER = 'IJ_MCP_SERVER_PROJECT_PATH';
 
+/** Environment variable the IDE's stdio bridge uses to select the project. */
+export const PROJECT_ENV = 'IJ_MCP_SERVER_PROJECT_PATH';
+
+/** Environment variable the IDE's stdio bridge uses to reach the running server. */
+export const PORT_ENV = 'IJ_MCP_SERVER_PORT';
+
+/** Argument that puts the IDE launcher into its stdio MCP bridge mode. */
+export const STDIO_ARG = 'stdioMcpServer';
+
 /** OpenCode MCP server name registered for the IDE. */
 export const IDEA_SERVER_NAME = 'idea';
 
@@ -44,16 +52,73 @@ const CALL_TIMEOUT_MS = 15000;
  *
  * @param {number} port
  * @param {string} projectPath
+ * @param {{ executionTimeoutMs?: number }} [options]
  */
-export function serverConfig(port, projectPath) {
-  return {
+export function serverConfig(port, projectPath, options = {}) {
+  /** @type {Record<string, unknown>} */
+  const config = {
     type: 'remote',
     url: `http://127.0.0.1:${port}${MCP_STREAM_PATH}`,
     headers: { [PROJECT_HEADER]: projectPath },
     codemode: false,
   };
+  return withExecutionTimeout(config, options);
 }
 
+/**
+ * Build the OpenCode MCP server config for the IDE's **stdio bridge**.
+ *
+ * The IDE launcher (`<App>.app/Contents/MacOS/<binary>`) with the
+ * `stdioMcpServer` argument runs a small proxy that speaks MCP over
+ * stdin/stdout and connects to the running IDE MCP server selected by the
+ * environment. That makes the client side a child-process pipe instead of a
+ * Streamable-HTTP stream, so it does not suffer the idle-close that the remote
+ * transport does. The project and port are carried in the environment, matching
+ * what the remote config carries in a header and URL.
+ *
+ * @param {string} executable absolute path to the IDE launcher
+ * @param {number} port IDE MCP port to bridge to
+ * @param {string} projectPath project root the bridge should target
+ * @param {{ executionTimeoutMs?: number }} [options]
+ */
+export function stdioServerConfig(executable, port, projectPath, options = {}) {
+  /** @type {Record<string, unknown>} */
+  const config = {
+    type: 'local',
+    // OpenCode's `LocalConfig.command` is a STRING ARRAY holding the executable
+    // followed by its arguments (`client.ts` does `const [command, ...args] =
+    // config.command`). There is no separate `args` field — passing one, or a
+    // bare string command, fails schema validation and the server never spawns.
+    command: [executable, STDIO_ARG],
+    environment: {
+      [PROJECT_ENV]: projectPath,
+      [PORT_ENV]: String(port),
+    },
+    codemode: false,
+  };
+  return withExecutionTimeout(config, options);
+}
+
+/**
+ * Attach OpenCode's per-server execution timeout to an MCP config.
+ *
+ * OpenCode defaults this to **12 hours**. The IDE's stdio bridge never answers a
+ * call whose upstream IDE connection has dropped (it logs on stderr but sends no
+ * JSON-RPC response), so without a cap a call made after the IDE died would sit
+ * unresolved for the whole default. A finite cap turns that permanent hang into
+ * an ordinary timeout error.
+ *
+ * @param {Record<string, unknown>} config
+ * @param {{ executionTimeoutMs?: number }} options
+ */
+function withExecutionTimeout(config, options) {
+  if (typeof options.executionTimeoutMs === 'number') {
+    return { ...config, timeout: { execution: options.executionTimeoutMs } };
+  }
+  return config;
+}
+
+
 /**
  * Is an IDE MCP server listening on `port`? One Streamable-HTTP `initialize`
  * POST decides it: any 2xx JSON reply means the server is up.
@@ -81,7 +146,7 @@ export async function probePort(port, options = {}) {
         params: {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: {},
-          clientInfo: { name: 'opencode-idea', version: '0.0.9' },
+          clientInfo: { name: 'opencode-idea', version: '0.0.11' },
         },
       }),
       signal: controller.signal,
@@ -151,7 +216,7 @@ export async function callTool(port, projectPath, name, args = {}, options = {})
       params: {
         protocolVersion: PROTOCOL_VERSION,
         capabilities: {},
-        clientInfo: { name: 'opencode-idea', version: '0.0.9' },
+        clientInfo: { name: 'opencode-idea', version: '0.0.11' },
       },
     });
     const response = await post({

package/src/plugin.js

@@ -1,22 +1,36 @@
 // opencode-idea — OpenCode plugin entry.
 //
-// For a JetBrains project this plugin:
+// For a project the user opted into IDEA 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;
+//   2. registers the IDE MCP server with OpenCode — by default as the IDE's
+//      stdio bridge (`idea stdioMcpServer`), scoped to the project through
+//      `IJ_MCP_SERVER_PROJECT_PATH` — 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;
-//   4. registers the `idea-run-config` skill (JetBrains projects only),
-//      which teaches the model how to manage `.run/*.run.xml` run
-//      configurations — a capability the IDE MCP server does not expose.
+//      in IntelliJ IDEA (reusing a running instance), loads the IDE
+//      capabilities immediately, and marks the project as an IDEA project;
+//      `/close-in-idea` clears that mark;
+//   4. registers the `idea-run-config` skill (marked projects only), which
+//      teaches the model how to manage `.run/*.run.xml` run configurations — a
+//      capability the IDE MCP server does not expose.
 //
-// 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.
+// A project that was never marked is 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.
+//
+// `/open-in-idea` opens the project in the IDE, waits until its MCP endpoint is
+// ready, registers `idea` (stdio, project-scoped) and marks the project in
+// `ctx.storage`; `/close-in-idea` unregisters the server and clears the mark.
+// The mark gates the IDEA skills and the failure-driven recovery. After a manual
+// open, an `idea_*` call that fails because the IDE MCP is not usable (the server
+// dropped, or the project is not open in the IDE) re-runs the open flow; a plain
+// business error is classified apart and left alone. Because a stdio bridge whose
+// IDE connection drops never reports it (it hangs), a background heartbeat probes
+// the IDE endpoint and, once it is clearly gone, deactivates the server — killing
+// the zombie bridge and removing the tools so a call cannot hang — and the next
+// user message rebuilds it.
 //
 // `Plugin.define` from `@opencode/plugin` is an identity function, so a plain
 // `{ id, setup }` object is the whole plugin contract. Exporting it directly
@@ -27,14 +41,17 @@ import {
   IDEA_SERVER_NAME,
   findIdePort,
   serverConfig,
+  stdioServerConfig,
 } from './mcp/idea.js';
 import { readIdeTerminalEnv } from './mcp/ide-env.js';
-import { currentProjectPath, hasIdeaDirectory } from './project.js';
+import { currentProjectPath } from './project.js';
 import { applyEnv, mergeEnv } from './env.js';
 import {
   createLaunchGuard,
+  DEFAULT_IDE_APP,
   openInIde,
   resolveIdeApp,
+  resolveIdeExecutable,
 } from './ide-launcher.js';
 import {
   appendIdeGuidance,
@@ -53,6 +70,20 @@ const DEFAULT_MCP_START_TIMEOUT_MS = 60000;
 const MCP_START_POLL_MS = 1000;
 const DEFAULT_TOOL_REFRESH_TIMEOUT_MS = 5000;
 const TOOL_REFRESH_POLL_MS = 25;
+// Hard cap on ONE IDE MCP tool call. OpenCode's own default is 12 hours, and the
+// IDE's stdio bridge NEVER answers a call once its upstream IDE connection has
+// dropped (it logs on stderr but sends no JSON-RPC response) — so a call made
+// after the IDE died would otherwise sit unresolved for 12h. 10 minutes is far
+// beyond any normal IDE tool and turns that permanent hang into a normal error.
+const DEFAULT_EXECUTION_TIMEOUT_MS = 600000;
+// Background IDE liveness probe. The stdio bridge NEVER reports a dropped IDE
+// connection (it just hangs), so the plugin watches the IDE endpoint itself.
+// After HEARTBEAT_FAILURES consecutive misses it deactivates the `idea` server
+// — which kills the zombie bridge child AND removes the `idea_*` tools, so the
+// model can never call into a dead pipe — and latches a rebuild for the next
+// user message (the bridge never heals on its own).
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+const DEFAULT_HEARTBEAT_FAILURES = 2;
 const IDEA_READY_TOOL_IDS = new Set(['idea_read_file', 'idea_apply_patch']);
 
 /**
@@ -147,9 +178,94 @@ function toolIds(tools) {
   return (tools ?? []).map((tool) => tool.id).filter((id) => typeof id === 'string').sort();
 }
 
+/**
+ * Classify an `idea_*` tool failure for the reconnect decision.
+ *
+ * It must never mistake a plain business error (a bad path, a missing file) for
+ * a broken connection, so only two shapes trigger action:
+ *
+ * - `project`: the IDE is up but the requested project is not open in it, e.g.
+ *   "`projectPath`=... doesn't correspond to any open project." Re-opening the
+ *   project fixes it.
+ * - `mcp`: the IDE MCP server itself is gone (dropped / transport closed).
+ *
+ * Everything else is `none`.
+ *
+ * @param {{ message?: unknown } | undefined} error
+ * @returns {'project' | 'mcp' | 'none'}
+ */
+function classifyIdeaFailure(error) {
+  const message = typeof error?.message === 'string' ? error.message : '';
+  // "Project not open in the IDE" comes in two shapes, both meaning the same
+  // thing and both fixed by opening the project again:
+  //   - the called tool carried no `projectPath`, so the server could not pick
+  //     one: "Unable to determine the target project for the current MCP tool
+  //     call." (this is what the plugin's stdio registration produces, since it
+  //     sets the project through env, not through the call)
+  //   - an explicit `projectPath` was passed but is not open: "`projectPath`=...
+  //     doesn't correspond to any open project."
+  if (
+    message.includes('Unable to determine the target project') ||
+    message.includes('correspond to any open project')
+  ) {
+    return 'project';
+  }
+  // Only transport-level markers, which OpenCode / the IDE bridge emit
+  // themselves. The message of an MCP *tool error* is the tool's own content
+  // (`tool/mcp.ts` turns `result.isError` into `ToolFailure({ message: <text> })`),
+  // so a generic string such as "Connection refused" from a SQL or run-config
+  // tool would otherwise be misread as a dropped connection and rebuild a
+  // healthy bridge.
+  if (
+    message.includes(`MCP server "${IDEA_SERVER_NAME}" is not available`) ||
+    message.includes('MCP server is not connected') ||
+    message.includes('Error POSTing to endpoint') ||
+    message.includes('SseClientTransport is closed')
+  ) {
+    return 'mcp';
+  }
+  return 'none';
+}
+
+/**
+ * Replace a tool error's message, so the model sees the replacement. OpenCode
+ * returns `event.error` after the `execute.after` hook resolves, so rewriting it
+ * is how the plugin steers the model after an automatic reconnect.
+ *
+ * The error is a `Tool.Error` instance (`ToolFailure` extends it). It is rebuilt
+ * through its own constructor — no runtime dependency on `@opencode/ai` — with a
+ * direct field mutation as a fallback.
+ *
+ * @param {{ error?: unknown }} event
+ * @param {string} message
+ * @returns {boolean}
+ */
+function rewriteToolError(event, message) {
+  const current = event?.error;
+  if (!current || typeof current !== 'object') return false;
+  try {
+    const Ctor = current.constructor;
+    if (typeof Ctor === 'function') {
+      const next = { message };
+      if (current.error !== undefined) next.error = current.error;
+      if (current.metadata !== undefined) next.metadata = current.metadata;
+      event.error = new Ctor(next);
+      return true;
+    }
+  } catch {
+    // fall through to mutation
+  }
+  try {
+    current.message = message;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @typedef {{
- *   status: 'connected' | 'tools-loading' | 'mcp-unavailable' | 'launch-failed' | 'disabled',
+ *   status: 'connected' | 'tools-loading' | 'mcp-unavailable' | 'launch-failed' | 'disabled' | 'closed',
  *   port?: number,
  *   opened?: boolean,
  *   unavailableNoticeSent?: boolean
@@ -185,6 +301,8 @@ export function ideFeedback(result) {
       return '无法拉起 IntelliJ IDEA(未找到应用或启动失败)。请确认已安装 IDEA,或手动打开后重试 /open-in-idea。';
     case 'disabled':
       return '插件已通过 openInIde: false 关闭 IDE 启动。请手动打开 IntelliJ IDEA,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后重试 /open-in-idea。';
+    case 'closed':
+      return '已关闭当前项目的 IDEA 接入:已注销 IDE MCP 并清除项目标记。如需重新接入,请再次执行 /open-in-idea。';
     default:
       return '已处理 /open-in-idea。';
   }
@@ -195,8 +313,11 @@ export function ideFeedback(result) {
  * notification, not a task: the model must only acknowledge it. The user sees
  * the clean notice instead, via `metadata.displayText`.
  */
+/** Marks the plugin's own session notices, so recovery never reacts to them. */
+export const NOTICE_PREFIX = '【插件通知】';
+
 export function idePromptText(result) {
-  return [`【插件通知】${ideFeedback(result)}`, '这是发给用户的通知,你无需处理。请只回复"收到"。'].join('\n\n');
+  return [`${NOTICE_PREFIX}${ideFeedback(result)}`, '这是发给用户的通知,你无需处理。请只回复"收到"。'].join('\n\n');
 }
 
 /** `metadata` so the UI shows the clean notice while the model sees the instruction. */
@@ -219,6 +340,11 @@ export default {
    *     mcpProbeTimeoutMs?: number,
    *     mcpStartTimeoutMs?: number,
    *     toolRefreshTimeoutMs?: number,
+   *     executionTimeoutMs?: number,
+   *     heartbeatIntervalMs?: number,
+   *     heartbeatFailures?: number,
+   *     transport?: 'stdio' | 'http',
+   *     ideExecutable?: string,
    *     feedback?: false | 'message',
    *   },
    *   command?: {
@@ -250,31 +376,57 @@ export default {
    *   tool?: {
    *     list?: () => Promise<ReadonlyArray<{ id?: string }>>,
    *     reload?: () => Promise<void>,
+   *     hook?: (name: string, cb: (event: {
+   *       tool?: string,
+   *       sessionID?: string,
+   *       status?: string,
+   *       error?: unknown,
+   *     }) => void | Promise<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>,
+   *     list?: () => Promise<{ data?: ReadonlyArray<{ name?: string, status?: { status?: string } }> }>,
    *   },
    *   shell: { hook: (name: string, cb: (input: { env: Record<string, string | undefined> }) => void) => Promise<{ dispose: () => Promise<void> | void }> },
+   *   storage?: {
+   *     get: (key: string) => Promise<unknown>,
+   *     set: (key: string, value: unknown) => Promise<void>,
+   *     remove: (key: string) => Promise<void>,
+   *   },
    * }} ctx
    */
   async setup(ctx) {
     const projectPath = currentProjectPath(ctx.location);
     if (!projectPath) return;
-    // Where IDEA tools can exist at all. Computed once: the recovery guidance is
-    // injected per model request, so it must not cost a filesystem check each
-    // time, and unrelated projects must not receive IDEA prompts they can never
-    // use.
-    const isIdeaProject = hasIdeaDirectory(projectPath);
 
     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);
+    // Transport for the IDE MCP server. `stdio` (default) registers the IDE's
+    // stdio bridge as a local server: the client side is a child-process pipe,
+    // which — unlike the remote Streamable-HTTP stream — does not get closed
+    // while idle and never reconnected. `http` keeps the older remote config.
+    const transport = options.transport === 'http' ? 'http' : 'stdio';
+    const ideExecutable = typeof options.ideExecutable === 'string'
+      ? options.ideExecutable
+      // Resolve independently of `openInIde`: that option only controls whether
+      // the plugin may LAUNCH the IDE, not which transport the MCP server uses.
+      // Falling back to the default app when launching is disabled keeps stdio
+      // the default there too (otherwise `openInIde: false` silently registered
+      // the remote HTTP transport).
+      : resolveIdeExecutable(ideApp ?? DEFAULT_IDE_APP);
+    const useStdio = transport === 'stdio' && typeof ideExecutable === 'string';
     const mcpProbeTimeoutMs = asPositiveNumber(options.mcpProbeTimeoutMs, DEFAULT_MCP_PROBE_TIMEOUT_MS);
     const mcpStartTimeoutMs = asPositiveNumber(options.mcpStartTimeoutMs, DEFAULT_MCP_START_TIMEOUT_MS);
     const toolRefreshTimeoutMs = asPositiveNumber(options.toolRefreshTimeoutMs, DEFAULT_TOOL_REFRESH_TIMEOUT_MS);
+    // Cap on a single IDE tool call, so a bridge that hangs (IDE died) fails in
+    // finite time instead of OpenCode's 12h default. See DEFAULT_EXECUTION_TIMEOUT_MS.
+    const executionTimeoutMs = asPositiveNumber(options.executionTimeoutMs, DEFAULT_EXECUTION_TIMEOUT_MS);
+    const heartbeatIntervalMs = asPositiveNumber(options.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS);
+    const heartbeatFailures = asPositiveNumber(options.heartbeatFailures, DEFAULT_HEARTBEAT_FAILURES);
     // "message" (default) injects a clearly-labelled notification that the
     // model only acknowledges ("收到"); the user sees the clean notice via
     // metadata.displayText. false is silent.
@@ -292,11 +444,78 @@ export default {
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let sessionRegistration;
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
+    let toolRegistration;
+    /** @type {{ dispose: () => Promise<void> | void } | undefined} */
+    let promptRegistration;
+    /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let commandRegistration;
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let skillRegistration;
+    let skillsRegistered = false;
     let disposed = false;
 
+    // Background heartbeat state (see DEFAULT_HEARTBEAT_INTERVAL_MS).
+    /** @type {ReturnType<typeof setInterval> | undefined} */
+    let heartbeatTimer;
+    let heartbeatMisses = 0;
+    // Latches when the IDE was seen down and the server was deactivated. It is
+    // cleared ONLY by a successful rebuild — never by the endpoint coming back —
+    // because the bridge does not heal on its own.
+    let needsRebuild = false;
+
+    // Project-level mark: has the user opted this project into IDEA via
+    // `/open-in-idea`? One plugin instance serves one project (OpenCode
+    // activates plugins per Location), so a single boolean is the whole cache.
+    // The durable copy lives in `ctx.storage` under `project/<projectPath>`.
+    // The commands are the only writers: they persist first, then invalidate
+    // this cache so the next read comes back from storage.
+    const storage = ctx.storage;
+    const markKey = `project/${projectPath}`;
+    /** @type {boolean | undefined} undefined = a storage read is due */
+    let markCache;
+
+    /** Read the durable mark into the cache; at most one storage read per invalidation. */
+    const readMark = async () => {
+      if (markCache !== undefined) return markCache;
+      if (!storage || typeof storage.get !== 'function') {
+        markCache = false;
+        return markCache;
+      }
+      try {
+        markCache = (await storage.get(markKey)) === true;
+      } catch {
+        // storage is best effort; fall back to unmarked
+        markCache = false;
+      }
+      return markCache;
+    };
+
+    /**
+     * Persist the mark, then invalidate the cache so the next reader re-reads
+     * storage. Best effort: an in-memory invalidation still applies if the write
+     * fails.
+     * @param {boolean} marked
+     */
+    const setMark = async (marked) => {
+      try {
+        if (marked) await storage?.set?.(markKey, true);
+        else await storage?.remove?.(markKey);
+      } catch {
+        // best effort
+      }
+      // Keep the in-memory cache in sync with the write (write-through), so any
+      // later synchronous reader sees the new value immediately.
+      markCache = marked;
+      // The skill lifecycle follows the mark: marking the project registers the
+      // IDEA skills, clearing the mark removes them again. Same semantics as the
+      // reconnect behavior, so the two can never disagree.
+      if (marked) await ensureSkills();
+      else await removeSkills();
+    };
+
+    // Resolve the mark once, so the request hooks can read it synchronously.
+    await readMark();
+
     const deactivateIde = async () => {
       const current = registrations.slice();
       registrations.length = 0;
@@ -336,36 +555,23 @@ export default {
     };
 
     const activateIde = async (port) => {
+      const config = useStdio
+        ? stdioServerConfig(ideExecutable, port, projectPath, { executionTimeoutMs })
+        : serverConfig(port, projectPath, { executionTimeoutMs });
       const mcpRegistration = await ctx.mcp.transform((editor) => {
-        editor.set(IDEA_SERVER_NAME, serverConfig(port, projectPath));
+        editor.set(IDEA_SERVER_NAME, config);
       });
       registrations = [mcpRegistration];
       return refreshIdeTools();
     };
 
-    /**
-     * Is the IDE MCP server contributing tools right now? OpenCode's registry is
-     * the source of truth: it adds the tools when a server connects and drops
-     * them when the connection stops (`stopServer` publishes `mcp.tools.changed`
-     * and the registry reloads). No probe of our own is involved, and only
-     * `/open-in-idea` asks, so the read is user-initiated.
-     */
-    const ideaToolsRegistered = async () => {
-      if (typeof ctx.tool?.list !== 'function') return false;
-      try {
-        return toolIds(await ctx.tool.list()).some((id) => id.startsWith('idea_'));
-      } catch {
-        return false;
-      }
-    };
-
     const reconcileOnce = async ({ probeIde = true } = {}) => {
       if (disposed) return false;
 
       // 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 = isIdeaProject || port !== undefined;
+      const isJetBrains = markCache === true || port !== undefined;
       if (!isJetBrains) {
         currentEnv = { env: {}, prependPath: [] };
         await deactivateIde();
@@ -383,10 +589,15 @@ export default {
         shellRegistration = await ctx.shell.hook('create.before', (input) => applyEnv(input, currentEnv));
       }
 
-      // A live server is only refreshed; a dead one must be replaced, because
-      // `reconcile()` skips an unchanged config and would never reconnect it.
-      // The registry says which case this is.
-      if (port !== undefined && (await ideaToolsRegistered())) return refreshIdeTools();
+      // Always tear the server down and register it again. A stdio bridge whose
+      // IDE connection dropped becomes a permanent zombie: the child process is
+      // still alive, so OpenCode keeps reporting it as connected, never restarts
+      // it, and SKIPS a re-`set` whose config is unchanged (`reconcile()` compares
+      // the config). Disposing the registration removes the server from the
+      // reconciled config, which is what actually kills the child process — so a
+      // full rebuild is the only reliable way back to a working bridge.
+      // `/open-in-idea` is manual and rare; rebuilding an already-healthy bridge
+      // costs one restart, which is the right trade for never leaving a zombie.
       await deactivateIde();
       if (port === undefined) return false;
       return activateIde(port);
@@ -485,9 +696,75 @@ export default {
       return run;
     };
 
+    /**
+     * The whole `/open-in-idea` flow, shared by the command and the auto-recovery
+     * path: ensure an IDE MCP endpoint, then register it and load capabilities.
+     *
+     * @param {{ onUnavailable?: (result: IdeCommandResult) => Promise<boolean> }} [options]
+     * @returns {Promise<IdeCommandResult>}
+     */
+    const runOpenInIdea = async ({ onUnavailable } = {}) => {
+      const result = await ensureIde({ onUnavailable });
+      const { port } = result;
+      let toolsReady = false;
+      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.
+        toolsReady = (await reconcile({ probeIde: port !== undefined })) === true;
+      } catch {
+        // capability load is best effort; feedback still matters
+      }
+      return result.status === 'connected' && !toolsReady
+        ? { ...result, status: 'tools-loading' }
+        : result;
+    };
+
     // Setup never probes or connects the IDE — everything is on `/open-in-idea`.
     await reconcile({ probeIde: false });
 
+    /**
+     * One heartbeat tick. Only marked projects are watched, and it only acts
+     * when an `idea` server is actually registered: the point is to protect an
+     * ESTABLISHED connection. A project that never connected has no zombie to
+     * kill, and must not have IDEA launched on its behalf. The deactivation
+     * runs under the reconcile chain, so a tick cannot race `/open-in-idea`.
+     */
+    let heartbeatBusy = false;
+    const heartbeatTick = async () => {
+      if (disposed || heartbeatBusy) return;
+      if (markCache !== true || registrations.length === 0) {
+        heartbeatMisses = 0;
+        return;
+      }
+      heartbeatBusy = true;
+      try {
+        const port = await findIdePort(ports, { timeoutMs: mcpProbeTimeoutMs }).catch(() => undefined);
+        if (port !== undefined) {
+          heartbeatMisses = 0;
+          return;
+        }
+        heartbeatMisses += 1;
+        if (heartbeatMisses < heartbeatFailures) return;
+        // The IDE is gone. Deactivating kills the zombie bridge child and
+        // removes the `idea_*` tools, so the model cannot call into a dead
+        // pipe. Latch a rebuild for the next user message.
+        const kicked = await enqueue(async () => {
+          if (disposed || registrations.length === 0) return false;
+          await deactivateIde();
+          return true;
+        });
+        if (kicked) needsRebuild = true;
+      } finally {
+        heartbeatBusy = false;
+      }
+    };
+    heartbeatTimer = setInterval(() => {
+      heartbeatTick().catch(() => {});
+    }, heartbeatIntervalMs);
+    // Never keep the host process alive just to probe (also keeps tests from hanging).
+    if (typeof heartbeatTimer?.unref === 'function') heartbeatTimer.unref();
+
     const sendFeedback = async (input, result) => {
       if (feedback !== 'message' || typeof ctx.session?.prompt !== 'function') return false;
       try {
@@ -507,65 +784,91 @@ export default {
 
     // The shipped skills are static knowledge (`skills/<id>/SKILL.md`), e.g. the
     // run-configuration workflow: where `.run/*.run.xml` live, how to bootstrap a
-    // schema from a real example, and how to verify a write. JetBrains projects
-    // only, and independent of `/open-in-idea`.
+    // schema from a real example, and how to verify a write. Registered only for
+    // a project that has been marked as an IDEA project, so unrelated projects
+    // never see an IDEA-specific skill.
     //
     // Deliberately NOT wrapped in a catch: these are core features of the plugin,
     // so a rejected definition must fail loudly. Swallowing it would ship a
     // silently incomplete plugin — which is exactly how 0.0.6 lost
     // `/open-in-idea` without anyone noticing until the command was gone.
-    if (isIdeaProject && typeof ctx.skill?.transform === 'function') {
+    const ensureSkills = async () => {
+      if (skillsRegistered || typeof ctx.skill?.transform !== 'function') return;
+      skillsRegistered = true;
       // Read the documents before the transform: callbacks must stay synchronous.
       const skills = readSkills();
       skillRegistration = await ctx.skill.transform((editor) => {
         for (const skill of skills) editor.add(skill);
       });
-    }
+    };
+    /** Remove the IDEA skills again when the project is unmarked. */
+    const removeSkills = async () => {
+      if (!skillsRegistered || !skillRegistration) return;
+      skillsRegistered = false;
+      const registration = skillRegistration;
+      skillRegistration = undefined;
+      try {
+        await registration.dispose();
+      } catch {
+        // best effort
+      }
+    };
+    // A project marked in an earlier run gets its skills at setup; a project
+    // marked for the first time gets them when `/open-in-idea` runs (both paths
+    // go through `setMark` / this setup hook).
+    if (markCache === true) await ensureSkills();
 
     // `/open-in-idea`: manual, re-entrant trigger that also loads the IDE
-    // capabilities immediately.
+    // capabilities immediately, and marks the project so later messages keep the
+    // IDE alive. `/close-in-idea` removes that mark. Both persist through
+    // `ctx.storage` and invalidate the in-memory cache.
     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) => {
+            // Mark the project before running: the mark means "this is an IDEA
+            // project", so it is persisted as soon as the user asks, whether or
+            // not the IDE happens to be reachable right now. `setMark` also
+            // registers the IDEA skills.
+            await setMark(true);
             /** @type {boolean} */
             let unavailableNoticeSent = false;
-            const result = await ensureIde({
+            const result = await runOpenInIdea({
               onUnavailable: async (notice) => {
                 unavailableNoticeSent = await sendFeedback(input, notice);
                 return unavailableNoticeSent;
               },
             });
-            const { port } = result;
-            let toolsReady = false;
-            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.
-              toolsReady = (await reconcile({ probeIde: port !== undefined })) === true;
-            } catch {
-              // capability load is best effort; feedback still matters
-            }
-            const finalResult = result.status === 'connected' && !toolsReady
-              ? { ...result, status: 'tools-loading' }
-              : result;
             // 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 || result.unavailableNoticeSent;
-            if (!unavailableAlreadySent || finalResult.status !== 'mcp-unavailable') {
-              await sendFeedback(input, finalResult);
+            if (!unavailableAlreadySent || result.status !== 'mcp-unavailable') {
+              await sendFeedback(input, result);
             }
           },
         });
+        editor.add({
+          name: 'close-in-idea',
+          description: '取消当前项目的 IDEA 接入:注销 IDE MCP 并清除项目标记',
+          execute: async (input) => {
+            await setMark(false);
+            // Unregister the IDE MCP server and clear the injected env. Reuses
+            // the serialized reconcile, so a concurrent rebuild (an in-flight
+            // `/open-in-idea`, or a heartbeat tick) cannot re-register the
+            // server after the mark is gone.
+            await reconcile({ probeIde: false });
+            await sendFeedback(input, { status: 'closed' });
+          },
+        });
       });
     }
 
     // Hide the tools the model must not see, and point it at the rest. This hook
     // runs for every agent-loop step (including tool-driven continuations), so
-    // it is deliberately a pure function of the request: no I/O, no cached
-    // connection state, and no action of its own.
+    // it stays a cheap, I/O-free function of the request: it checks the cached
+    // project mark and this request's own tool snapshot, and takes no action.
     //
     // `event.tools` is this request's tool snapshot, and OpenCode's own registry
     // adds IDEA tools when the server connects and drops them when it stops
@@ -577,17 +880,63 @@ export default {
         const tools = event?.tools;
         const serving = tools !== undefined && Object.keys(tools).some((name) => name.startsWith('idea_'));
         if (serving) removeIdeaToolDefinitions(tools, HIDDEN_IDEA_TOOLS);
-        if (isIdeaProject || serving) appendIdeRecoveryGuidance(event?.system);
+        if (markCache === true || serving) appendIdeRecoveryGuidance(event?.system, { marked: markCache === true });
         if (!injectGuidance) return;
         // Guidance promises tools the model can call, so it only goes out when
         // they are actually in this request.
         if (!serving) return;
         appendIdeGuidance(event?.system, projectPath);
       });
+
+      // Rebuild after a heartbeat-detected drop. It reads only the in-memory
+      // `needsRebuild` latch, so it is a cheap no-op on every other message.
+      // OpenCode awaits `prompt` before the request is built, so when the IDE is
+      // back, the message that triggers this already carries working tools.
+      promptRegistration = await ctx.session.hook('prompt', async (event) => {
+        if (disposed || !needsRebuild || markCache !== true) return;
+        // Never react to the plugin's own notices, or recovery would feed on
+        // itself. Match the notice TEXT, never `metadata.displayText`: OpenCode
+        // also sets `displayText` on ordinary user messages (it is the message
+        // text itself), so a displayText guard silently skips every real message
+        // — verified live, and it made this rebuild never run.
+        const text = event?.prompt?.text;
+        if (typeof text === 'string' && text.startsWith(NOTICE_PREFIX)) return;
+        const result = await runOpenInIdea();
+        if (result.port !== undefined) {
+          needsRebuild = false;
+          heartbeatMisses = 0;
+        }
+      });
+
+      // The only self-initiated action: when an `idea_*` call fails in a way
+      // that means the IDE MCP is not usable, run the open flow again. The
+      // failure is classified — a plain business error (a bad path, a missing
+      // file) never triggers a reconnect, only "the MCP is not available" or
+      // "the project is not open in the IDE" do.
+      if (typeof ctx.tool?.hook === 'function') {
+        toolRegistration = await ctx.tool.hook('execute.after', async (event) => {
+          if (event?.status !== 'error') return;
+          if (typeof event?.tool !== 'string' || !event.tool.startsWith('idea_')) return;
+          if (!(await readMark())) return;
+          const kind = classifyIdeaFailure(event.error);
+          if (kind === 'none') return;
+          if (kind === 'project' && ideApp) {
+            // The IDE is up; the project simply is not open in it. Ask the IDE
+            // to open the project again, and tell the model to retry.
+            await openInIde(projectPath, { app: ideApp });
+            rewriteToolError(event, '该项目已在 IDEA 中重新打开,请重试刚才的操作。');
+            return;
+          }
+          const result = await runOpenInIdea();
+          if (result.port === undefined) return;
+          rewriteToolError(event, 'IDE MCP 已重新连接,请重试刚才的操作。');
+        });
+      }
     }
 
     return async () => {
       disposed = true;
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
       if (shellRegistration) {
         try {
           await shellRegistration.dispose();
@@ -602,6 +951,20 @@ export default {
           // best effort
         }
       }
+      if (toolRegistration) {
+        try {
+          await toolRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
+      if (promptRegistration) {
+        try {
+          await promptRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
       if (commandRegistration) {
         try {
           await commandRegistration.dispose();

package/src/project.js

@@ -1,8 +1,5 @@
 // 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.
@@ -15,15 +12,3 @@ export function currentProjectPath(location) {
   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'));
-}