opencode-idea 0.0.10 → 0.0.11

package/README.md

@@ -9,8 +9,9 @@ OpenCode 插件,面向 JetBrains 项目 (IntelliJ IDEA / PyCharm / WebStorm 等)
 3. **注入 IDE 环境变量** —— 从 IDE 集成终端读取它实际运行的环境,注入每个 OpenCode shell。
 
 非 JetBrains 项目完全不受影响。 **手动接入**:插件启动不探测、不连接 IDE,只有跑 `/open-in-idea` 才接入。跑过一次后,该**项目**
-被「标记」(持久化在 `ctx.storage`,重启 OpenCode 后仍在):之后每条用户消息都默认 IDE 仍在,一旦发现 IDE MCP 未连接,插件会在
-构建本次请求前自动重跑一遍接入流程并按需补一条通知。`/close-in-idea` 删除该标记。没跑过 `/open-in-idea` 的项目保持全手动、零自主动作。
+被「标记」(持久化在 `ctx.storage`,重启 OpenCode 后仍在):之后插件在后台**每 5s 探活**该 IDE——**掉线就注销 `idea` MCP**(杀掉不会自愈的
+stdio 僵尸桥 + 移除 `idea_*` 工具,让模型调不到、**不会挂起**),并锁存"待重建";**下一条用户消息**读到锁存后**静默重建**(用户无感)。
+`/close-in-idea` 注销 IDE MCP + 删除标记。没跑过 `/open-in-idea` 的项目保持全手动、零自主动作。
 
 ## 工作原理
 
@@ -18,42 +19,51 @@ OpenCode 插件,面向 JetBrains 项目 (IntelliJ IDEA / PyCharm / WebStorm 等)
 setup(启动, 每项目一次):
   a. 读项目标记(ctx.storage: project/<项目路径>; OpenCode 重启后仍生效)
   b. 读 IDE 集成终端环境 → 通过 shell create.before 钩子注入每个 shell(null: 未连 IDE 时为空)
-  c. 注册 /open-in-idea 与 /close-in-idea 命令 + session context/prompt 钩子
+  c. 注册 /open-in-idea 与 /close-in-idea 命令 + session context 钩子 + tool execute.after 钩子
   不探测、不注册 MCP
 
-/open-in-idea(手动触发):
-  0. 写项目标记 = true(持久化)+ 清内存缓存(下次读取者回源)
-  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. 删项目标记 + 清内存缓存
-  2. 发一条结果通知(不改动已建立的连接)
-
-后续用户消息(仅在被标记的项目里):
-  1. 项目已标记 → 默认 IDE 仍在线
-  2. 查 OpenCode 里 `idea` MCP server 状态;不是 connected/pending(真断了)→ 在 prompt 钩子里同步重跑上面的接入流程
-  3. 成功 → 本条消息即可用 `idea_*` 工具,并补一条"已自动重新连接"通知(排在用户消息之后)
-  4. 失败 → 静默,沿用 fast-fail 恢复提示(不会每条消息都重复拉起 IDE)
+  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`),模型只看到"这是通知,请只回复『收到』"的指令,因此不会执行任何操作、不会调用工具。
@@ -68,8 +78,8 @@ Brave Mode 后再次执行 `/open-in-idea` 即可接上。
 
 ## 关闭接入 (`/close-in-idea`)
 
-输入 `/close-in-idea`:删除当前项目的接入标记(持久化 + 内存缓存一并清),之后 IDE MCP 即使断开也**不再自动重连**。命令只删标记,
-**不主动断开已建立的连接**——当前已注册的工具会保留到连接自然中断为止。想重新接入,再次执行 `/open-in-idea`。
+输入 `/close-in-idea`:**注销当前项目的 IDE MCP** + 删除项目标记(持久化 + 内存缓存一并清),并清空注入的环境变量。
+之后 `idea_*` 工具不再可用,也不会再因失败自动接入。想重新接入,再次执行 `/open-in-idea`。
 
 ## IDE 工具优先 (直接调用引导)
 
@@ -128,19 +138,39 @@ IDE MCP 只能 **查**(`get_run_configurations`)和 **执行**(`execute_run_conf
 - 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]`。
 
@@ -205,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(静默)
       },
     },
@@ -217,36 +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` 静默                        |
 
 ## 行为
 
-- **被标记的项目**:启动读回标记后挂上 shell 环境钩子 (环境值待接入后填充)、注册 `idea-run-config` skill;
-  `/open-in-idea` 接入 IDE MCP + 启用引导。
+- **被标记的项目**:启动读回标记后挂上 shell 环境钩子 (环境值待接入后填充)、注册 `idea-run-config` skill;IDE MCP 由
+  `/open-in-idea` 注册。
 - **未标记的项目**:不改环境、不注册、不注入任何 IDEA 提示 (每请求零开销;setup 时只做一次项目标记读取)。
-- **手动接入**:启动 **不探测、不连接 IDE MCP**;注册、**环境重读**、引导注入全部由 `/open-in-idea` 触发。
-  `context` 钩子按「每次模型调用」触发 (含工具续跑),是**请求的纯函数**:它只看本次请求自带的工具快照 ——
-  有 `idea_*` 就剥离隐藏工具并注入引导;没有则只在项目被标记时给恢复提示。**不做任何 I/O(get 只看内存缓存),没有定时器,
-  没有事件订阅**。一次失败的调用不会触发探测或注销。
-- **项目标记自动重连**:`/open-in-idea` 会持久化一个**项目级**标记(插件名下 KV,key 为 `project/<项目根路径>`,重启 OpenCode 后
-  仍在),并在内存缓存。之后每条用户消息经 `prompt` 钩子处理时,先查 OpenCode 里 `idea` MCP server 的状态:不是
-  `connected`/`pending`(真断了)才同步重跑一遍完整接入流程 (探测 → `open -a` → 等 MCP → 注册 + `tool.reload`),让**这条消息
-  本身**就能用上 IDEA 工具;恢复成功后补一条会话通知。`/close-in-idea` 删标记后即不再自愈。失败时沿用启动保护的冷却与次数上限
-  (`launchCooldownMs` / `launchMaxAttempts`),不会每条消息都重复拉起 IDE。
-- **判定只看 MCP 状态,不看工具报错**:是否重连只取决于 `idea` MCP server 的连接状态(`ctx.mcp.list()`)。工具调用的业务报错
-  (如 `File not found`)只可能发生在 server 仍 `connected` 时,所以**永远不会**被误判成断开;插件也不注册 `tool.execute.after`
-  钩子,一次失败的调用不会触发探测或注销。
-- **`/open-in-idea`**:手动打开当前项目并即时加载能力 (已在 IDE 打开时则只重新加载);MCP 未开启时只发一次提示并
-  fast-fail,用户手动开启 MCP + Brave Mode 后重试。**`/close-in-idea`**:删项目标记,不改动已建立的连接。
+- **手动接入 + 就绪即返回**:`/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 + 删项目标记 + 清空注入的环境。
 
 ## 限制
 
@@ -263,14 +308,20 @@ 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` 并移除工具,**不会自动重连**。**被标记的项目**由插件在 `prompt` 钩子里查 MCP 状态并按需重跑接入
-  流程补这个缺口;未标记的项目仍走手动 `/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(例如项目根与某子目录)各有自己的内存缓存 —— 在其中一个执行 open/close 命令,另一个
-  实例要等它下次回源(目前只在 setup 读一次)才会看到。单目录打开项目的常见用法不受影响。
-- `/close-in-idea` **只删标记,不断开已建立的连接**:已注册的 IDEA 工具会保留到连接自然中断,期间标记与实际连接可能短暂不一致。
+  **项目根路径**共享;但两个不同 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 对话框,需确认后重试。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-idea",
-  "version": "0.0.10",
+  "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.10' },
+          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.10' },
+        clientInfo: { name: 'opencode-idea', version: '0.0.11' },
       },
     });
     const response = await post({

package/src/plugin.js

@@ -3,9 +3,10 @@
 // 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), loads the IDE
 //      capabilities immediately, and marks the project as an IDEA project;
@@ -19,13 +20,17 @@
 // when a probe is requested). `/open-in-idea` probes, opens the IDE, and loads
 // the IDE MCP + guidance on demand.
 //
-// Once the user runs `/open-in-idea` in a project, that project is marked as an
-// IDEA project. The mark is persisted through `ctx.storage` (durable across
-// restarts) and cleared by `/close-in-idea`. While a project is marked, every
-// user message assumes the IDE is still up: the plugin asks OpenCode for the
-// `idea` MCP server's status and, when it is not connected, re-runs the open
-// flow before the request is built. Detection is by MCP status, never by tool
-// errors, so a normal business error can never look like a dropped connection.
+// `/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
@@ -36,14 +41,17 @@ import {
   IDEA_SERVER_NAME,
   findIdePort,
   serverConfig,
+  stdioServerConfig,
 } from './mcp/idea.js';
 import { readIdeTerminalEnv } from './mcp/ide-env.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,
@@ -62,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']);
 
 /**
@@ -156,13 +178,97 @@ 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' | 'closed',
  *   port?: number,
  *   opened?: boolean,
- *   unavailableNoticeSent?: boolean,
- *   autoRecovered?: boolean
+ *   unavailableNoticeSent?: boolean
  * }} IdeCommandResult
  */
 
@@ -182,9 +288,6 @@ const asPositiveNumber = (value, fallback) =>
 /** User-facing status text for a `/open-in-idea` result. */
 /** @param {IdeCommandResult} result */
 export function ideFeedback(result) {
-  if (result?.autoRecovered) {
-    return '检测到 IDE MCP 连接已断开,已自动重新连接并恢复 IDEA 原生工具。';
-  }
   switch (result?.status) {
     case 'connected':
       return 'IDE MCP 已连接;IDEA 原生工具已注册并可用于后续请求。';
@@ -199,7 +302,7 @@ export function ideFeedback(result) {
     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。';
+      return '已关闭当前项目的 IDEA 接入:已注销 IDE MCP 并清除项目标记。如需重新接入,请再次执行 /open-in-idea。';
     default:
       return '已处理 /open-in-idea。';
   }
@@ -210,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. */
@@ -234,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?: {
@@ -260,13 +371,17 @@ export default {
    *       agent?: string,
    *       system?: unknown[],
    *       tools?: Record<string, unknown>,
-   *       prompt?: { text?: string },
-   *       metadata?: Record<string, unknown>,
    *     }) => void | Promise<void>) => Promise<{ dispose: () => Promise<void> | void }>,
    *   },
    *   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 }>,
@@ -290,9 +405,28 @@ export default {
     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.
@@ -310,6 +444,8 @@ 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;
@@ -318,6 +454,15 @@ export default {
     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.
@@ -328,9 +473,6 @@ export default {
     const markKey = `project/${projectPath}`;
     /** @type {boolean | undefined} undefined = a storage read is due */
     let markCache;
-    // One auto-recovery run per project at a time; overlapping prompts share it.
-    /** @type {Promise<void> | undefined} */
-    let autoRecovering;
 
     /** Read the durable mark into the cache; at most one storage read per invalidation. */
     const readMark = async () => {
@@ -361,7 +503,9 @@ export default {
       } catch {
         // best effort
       }
-      markCache = undefined;
+      // 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.
@@ -411,29 +555,16 @@ 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;
 
@@ -458,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);
@@ -587,6 +723,48 @@ export default {
     // 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 {
@@ -604,71 +782,6 @@ export default {
       }
     };
 
-    /**
-     * Is the plugin's `idea` MCP server connected right now? OpenCode tracks
-     * every server's status in memory, and this is the authoritative "the IDE
-     * MCP is down" signal: it reflects the transport, not the result of any
-     * single tool call, so a business error can never look like a disconnect.
-     * `pending` means "still connecting" and is treated as healthy, so a server
-     * that is merely starting up is left alone.
-     *
-     * @returns {Promise<boolean>}
-     */
-    const isIdeaConnected = async () => {
-      if (typeof ctx.mcp?.list !== 'function') return false;
-      try {
-        const result = await ctx.mcp.list();
-        const servers = Array.isArray(result) ? result : (result?.data ?? []);
-        return servers.some((server) => {
-          const status = server?.status?.status;
-          return server?.name === IDEA_SERVER_NAME && (status === 'connected' || status === 'pending');
-        });
-      } catch {
-        return false;
-      }
-    };
-
-    /**
-     * Marked-project recovery: while the project is marked (the user ran
-     * `/open-in-idea`), treat the IDE as expected and rebuild the connection
-     * whenever its MCP server is not connected. Runs before the prompt's request
-     * is built, so a successful recovery makes its `idea_*` tools available to
-     * that very message.
-     *
-     * Only a confirmed reconnect is announced. A failed recovery stays silent:
-     * the per-request recovery guidance already tells the model what to say, and
-     * a notice per failed message would be noise (the launch guard, shared with
-     * the command, keeps it from re-spawning on every message).
-     *
-     * @param {string} sessionID the notice target; the mark itself is per-project
-     */
-    const autoReconnect = (sessionID) => {
-      if (autoRecovering) return autoRecovering;
-      const run = (async () => {
-        try {
-          if (disposed) return;
-          if (await isIdeaConnected()) return;
-          const result = await runOpenInIdea();
-          // A found endpoint is what counts as recovered, even if its tool
-          // catalog is still registering (`tools-loading`).
-          if (result.port === undefined) return;
-          // Queue the notice so it is delivered after the user's own message,
-          // never mixed into the same model turn as it.
-          await sendFeedback(
-            { sessionID, prompt: { text: '' }, delivery: 'queue' },
-            { status: 'connected', autoRecovered: true },
-          );
-        } catch {
-          // auto-recovery is best effort
-        }
-      })();
-      autoRecovering = run;
-      void run.finally(() => {
-        if (autoRecovering === run) autoRecovering = undefined;
-      });
-      return run;
-    };
-
     // 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. Registered only for
@@ -738,9 +851,14 @@ export default {
         });
         editor.add({
           name: 'close-in-idea',
-          description: '取消当前项目的 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' });
           },
         });
@@ -762,7 +880,7 @@ 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 (markCache === true || 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.
@@ -770,32 +888,55 @@ export default {
         appendIdeGuidance(event?.system, projectPath);
       });
 
-      // Project-level auto-recovery. The only self-initiated action in the
-      // plugin, and only for a marked project. It belongs to the `prompt` hook
-      // (not `context`) because the tool catalog for a request is already fixed
-      // by the time `context` runs: a `prompt`-time reconnect is what lets the
-      // message that triggered it use `idea_*` tools.
-      //
-      // The returned promise is awaited by OpenCode before the request is built,
-      // so a slow cold start delays that message — the accepted cost of treating
-      // a marked project's IDE as always up.
+      // 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) => {
-        const sessionID = event?.sessionID;
-        if (typeof sessionID !== 'string') return;
-        // Never react to the plugin's own notices, or auto-recovery would feed
-        // on itself. Notices carry `metadata.displayText`; the prefix guards
-        // against an older notice shape.
-        const displayText = event?.metadata?.displayText;
-        if (typeof displayText === 'string') return;
+        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('【插件通知】')) return;
-        if (!(await readMark())) return;
-        return autoReconnect(sessionID);
+        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();
@@ -810,6 +951,13 @@ export default {
           // best effort
         }
       }
+      if (toolRegistration) {
+        try {
+          await toolRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
       if (promptRegistration) {
         try {
           await promptRegistration.dispose();