opencode-idea 0.0.13 → 0.0.15

package/README.md

@@ -12,10 +12,14 @@ OpenCode 插件,面向 JetBrains 项目 (IntelliJ IDEA / PyCharm / WebStorm 等)
 > (含 fnm / SDKMAN 这类靠 shell init 切版本的场景)。详见「项目命令执行」。
 
 非 JetBrains 项目完全不受影响。 **手动接入**:插件启动不探测、不连接 IDE,只有跑 `/open-in-idea` 才接入。跑过一次后,该**项目**
-被「标记」(持久化在 `ctx.storage`,重启 OpenCode 后仍在):之后插件在后台**每 5s 探活**该 IDE——**掉线就注销 `idea` MCP**(杀掉不会自愈的
-stdio 僵尸桥 + 移除 `idea_*` 工具,让模型调不到、**不会挂起**),并锁存"待重建";**下一条用户消息**读到锁存后**静默重建**(用户无感)。
+被「标记」(持久化在 `ctx.storage`,重启 OpenCode 后仍在)。之后**没有任何后台轮询**——恢复完全靠请求驱动:插件发现"该有 `idea_*`
+工具却没有"(新实例)或"`idea_*` 调用失败"(掉线)时,**在下一条消息发出前静默接回**(用户无感)。
 `/close-in-idea` 注销 IDE MCP + 删除标记。没跑过 `/open-in-idea` 的项目保持全手动、零自主动作。
 
+> **为什么改成请求驱动**:OpenCode 把一个 Location(项目)的全部服务缓存在 `LayerMap` 里,空闲 **60 分钟**
+> (`idleTimeToLive`)后整体驱逐——插件实例连同 `idea` MCP 注册一起消失。这一点两种传输都躲不过,所以与其后台探活
+> (永远晚一步、还刷 IDE 日志),不如在请求前发现并把连接接回来。
+
 ## 工作原理
 
 ```text
@@ -30,9 +34,8 @@ setup(启动, 每项目一次):
      - 已就绪 → 再问 IDE「当前项目是否已打开」(`get_project_modules`,带项目路径)
        · 已打开 → 不重复 open;未打开 → open -a 打开
      - 未就绪(冷启动)→ open -a 拉起,再轮询等到就绪(上限 60s)
-  4. **先注销旧的 idea MCP(杀掉旧的 stdio 桥子进程),再重新注册**
-     (`idea stdioMcpServer`,env 带项目路径 + 端口;每项目一个子进程)
-     —— 每次执行都重建,因为断掉的桥不会自愈、也不能靠 refresh 复活
+  4. **先注销旧的 idea MCP,再重新注册**(`type: "remote"` 指向 `http://127.0.0.1:<port>/stream`,项目路径走请求头)
+     —— 每次执行都重建:OpenCode 的 reconcile 会跳过配置未变的 re-`set`,不先拆就换不掉一个已经死掉的注册
   5. 等 `idea_*` 工具进入注册表;读 IDE 终端环境更新 shell 环境;启用引导
   6. 发结果通知(用户看到干净气泡,模型只回"收到")
 
@@ -47,14 +50,14 @@ setup(启动, 每项目一次):
      - 普通业务错误(File not found 等)→ 不动作
   2. 触发成功 → 把该错误改写为"已重连 / 已重新打开,请重试",模型同一回合重试;失败 → 保持原错误
 
-后台探活(心跳;仅"已标记 + 桥已注册"的项目):
-  1. 每 5s 探测 IDE 端口(/stream);连续 2 次不通 →
-  2. **注销 `idea` MCP**:杀掉僵尸桥子进程 + 从注册表移除 `idea_*` 工具
-     (→ 模型调不到,也就不会挂起;这一步是"从根上避免挂起"的关键)
-  3. 锁存 `needRebuild = true`(不会因端口恢复而清,因为桥不会自愈)
-  4. 下一条用户消息:纯内存读到锁存 → 自动重跑接入流程(IDE 不在则 `open -a` 拉起),成功后清锁存
-     —— 全程静默,用户无感
-  ※ 这是**每个 Location(项目)各跑一份**探活;IDE 只有一个,所以所有项目的桥几乎同时被注销、再各自重建
+请求驱动的恢复(没有后台轮询;每个 Location(项目)各一份插件实例):
+  1. `prompt` 钩子(消息进入时,OpenCode 会 await 它)——「已标记 + 本实例没有任何 `idea` 注册」→
+     探测端口,**只注册、绝不 `open -a`**;命中就重建,于是**这条消息本身**就带上了 `idea_*` 工具
+  2. `context` 钩子——某条请求"曾经有 `idea_*`、现在没有" → 立刻锁存并在后台重建(不等下一条消息)
+  3. `execute.after` 钩子——`idea_*` 调用以"不可用"告终(`MCP server "idea" is not available` /
+     `Error POSTing to endpoint`)→ 重跑接入流程,并把错误改写成"已重连,请重试";
+     普通业务错误(文件不存在等)不动作
+  ※ 三者都只在**确实有事发生**时动;没人用这个项目时,插件完全静止
 ```
 
 ## 在 IDE 中打开项目 (`/open-in-idea`)
@@ -68,7 +71,7 @@ setup(启动, 每项目一次):
 3. 未就绪 → 说明 IDEA 是冷启动,继续用 `open -a` 拉起并**轮询等到 MCP 就绪**(冷启动约数十秒,上限 60s);
 4. 等不到(例如 IDE 里 MCP 服务未开启)→ 提示在 IDEA 的 `Settings → MCP Server` 开启 MCP 服务并启用 **Brave Mode**,用户设置好后
    再次执行 `/open-in-idea`;
-5. 就绪后 **先注销旧的 `idea` MCP(杀掉旧的 stdio 桥子进程)→ 再重新注册**(每次执行都重建,因为断掉的桥不会自愈),然后重读
+5. 就绪后 **先注销旧的 `idea` MCP → 再重新注册**(每次执行都重建:配置未变的 re-`set` 会被 reconcile 跳过),然后重读
    IDE 环境、启用系统引导,并**等到 `idea_*` 工具进入注册表**才返回。
 
 > **通知不触发 AI 干活**:默认 `feedback: "message"` 把结果作为一条 **标注清楚的通知**发到会话里 —— 用户看到干净的通知气泡
@@ -124,14 +127,33 @@ IDE MCP 只能 **查**(`get_run_configurations`)和 **执行**(`execute_run_conf
 `setup` 时(读回标记)就会注册。未标记的项目不受影响。文档放在 `skills/<id>/SKILL.md`(每个 skill 一个目录,`name` /
 `description` 走 YAML frontmatter),由 `src/skill/loader.js` 扫描加载 —— **加新 skill 只需加一个目录,不用改代码**。
 
+## Standalone 模式纪律 (skill)
+
+本机直跑应用的**项目级纪律**由 `idea-standalone` skill 固化:它为项目生成/维护一份 rule,落在项目根
+**`.opencode/rules/idea-standalone.md`**,四段结构固定 ——
+
+1. **什么是 standalone 模式**:**standalone = 通过 IDEA 启动**(每个应用的入口是 IDEA run configuration),应用在本机进程
+   直跑(不容器化、不部署),只启动其中一部分是常态;启停一律由用户在 IDEA 里手动完成,AI 不得代为启停(含经
+   `idea_execute_run_configuration`),判断需要重启时先取得用户明确授权;
+2. **启动哪些应用**:一行一个应用,启动路径**只能是 IDEA run configuration**(配置名必须能在 `idea_get_run_configurations`
+   里查到;缺配置先走 `idea-run-config` skill 建 `.run/*.run.xml`),端口与被依赖的先后顺序一并写明;
+3. **热重载矩阵**:逐应用标"是 / 否" —— 带 HMR 的 dev server 改动后**不用**提示重启;`go run .` 这类无热重载的进程改动后
+   **必须**显式点名「需要重启 <应用>」,不得在未提示的情况下宣称"改完可验证";
+4. **项目补充条款**:文件写入位置、测试纪律、访问归属、dev 模式特有限制等,按用户给的条款逐条续写、保留原意。
+
+事实一律先查后写:配置名来自 `idea_get_run_configurations`,热重载列来自运行方式,端口读不到就问用户 —— 不猜。
+
 ## 项目命令执行 (IDE 终端)
 
-跑项目相关的命令时,模型使用 **`idea_execute_terminal_command`**,而不是 OpenCode 原生 shell。判据是**命令是否依赖项目的
-工具链 / 运行时 / 依赖环境**,而不是语言或工具名:
+跑项目相关的命令时,模型使用 **`idea_execute_terminal_command`**,而不是 OpenCode 原生 shell。判据是**白名单**:命令用于本项目
+自身的构建 / 测试 / 运行,且首个可执行文件命中下表,才走 IDE 终端;其余一律走原生 shell。
 
-- **走 IDE 终端**:任何会调用项目工具链的命令 —— Java / Python / Node / Go 的运行时,以及 Maven / Gradle、uv / pip /
-  poetry、cargo、bundler、make / cmake、包管理器、构建、测试、代码生成等。
-- **走原生 shell**:纯操作系统级的通用命令(`ls` / `cat` / `cp` / `mkdir` / `git` 等)。
+- **Node / 前端**(`package.json`):`node` / `npm` / `npx` / `pnpm` / `yarn` / `vite` / `webpack` / `esbuild` / `tsc` /
+  `jest` / `vitest`。
+- **Java**(`pom.xml` / `build.gradle`):`java` / `javac` / `mvn` / `mvnw` / `gradle` / `gradlew`。
+- **Python**(`pyproject.toml` / `requirements.txt`):`python` / `python3` / `pip` / `pip3` / `uv` / `poetry` / `pytest`。
+- **Go**(`go.mod`):`go` / `gofmt` / `golangci-lint`。
+- 白名单未覆盖的语言暂走原生 shell,遇到后再补进上表。
 
 原因:
 
@@ -150,36 +172,22 @@ 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 配置。默认用 **stdio 桥**:
+- 插件注册给 OpenCode 的 MCP 配置(**只支持 Streamable HTTP**):
 
 ```jsonc
 {
-  "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",
-  },
+  "type": "remote",
+  "url": "http://127.0.0.1:64342/stream",
+  "headers": { "IJ_MCP_SERVER_PROJECT_PATH": "<项目路径>" },
+  "codemode": false,
 }
 ```
 
-`idea stdioMcpServer` 是 IDE 自带的桥:OpenCode 通过 **stdin/stdout 子进程管道**跟它通信,它在后端连 IDE 的 MCP。
-**客户端侧是持久管道,不存在 HTTP 空闲断流**——这正是默认选它的原因。每个项目一个插件实例、各带自己的
-`IJ_MCP_SERVER_PROJECT_PATH`,所以每个项目会起一个独立的 stdio 客户端进程。
+项目通过 `IJ_MCP_SERVER_PROJECT_PATH` 头选择,所以一个 IDE 能同时服务多个项目,而**不需要为每个项目起一个子进程**。
 
-> **为什么不用远程 `/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": "<项目路径>" },
-> }
-> ```
+> **为什么不用 IDE 的 stdio 桥**(`idea stdioMcpServer`,子进程管道):它的故障是"沉默"的——IDE 连接断掉后子进程只挂起、
+> 不回任何错误,只能靠后台心跳兜;而 Location 空闲 60 分钟被驱逐时,桥进程与注册一起消失——**两种传输都躲不过**。
+> HTTP 至少把"端点没了"变成一次普通的调用错误,插件能分类并自愈。OpenCode 2.0.19+ 也已无 SSE 客户端传输,当初选 stdio 的理由不再成立。
 >
 > **为什么不用 `/sse`**:OpenCode V2 的远程 MCP 客户端**只支持 Streamable HTTP**,没有旧版 SSE 传输。IDE 的 `/sse` 是旧版
 > SSE (POST 返回 405),V2 连不上。插件对 IDE 的**探测**仍走 `/stream`(一次 `initialize`),用来确认 IDE MCP 已就绪并拿到端口。
@@ -246,14 +254,10 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
         "ports": [64342], // IDE MCP 端口;默认 [64342]
         "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(静默)
       },
     },
@@ -263,20 +267,16 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
 
 不传 options 时全部使用下表默认值。
 
-| 选项                  | 类型                 | 默认        | 说明                                                                                    |
-| --------------------- | -------------------- | ----------- | --------------------------------------------------------------------------------------- |
-| `ports`               | `number[]`           | `[64342]`   | 依次探测的 IDE MCP 端口                                                                 |
-| `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` 静默                        |
+| 选项                 | 类型                 | 默认        | 说明                                                                               |
+| -------------------- | -------------------- | ----------- | ---------------------------------------------------------------------------------- |
+| `ports`              | `number[]`           | `[64342]`   | 依次探测的 IDE MCP 端口                                                            |
+| `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 端口的短探测超时                                                          |
+| `executionTimeoutMs` | `number`             | `600000`    | 单次 `idea_*` 工具调用的硬上限(毫秒);防止端点卡住后无限等待(OpenCode 默认 12 小时) |
+| `feedback`           | `"message" \| false` | `"message"` | 结果反馈:`message` 会话通知(用户可见,AI 只回"收到");`false` 静默                   |
 
 ## 行为
 
@@ -284,23 +284,28 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
   `/open-in-idea` 注册。
 - **未标记的项目**:不改环境、不注册、不注入任何 IDEA 提示 (每请求零开销;setup 时只做一次项目标记读取)。
 - **手动接入 + 就绪即返回**:`/open-in-idea` 会 `open -a` 拉起 IDEA 并**等 IDE MCP 就绪**(冷启动数十秒,上限 60s);就绪后
-  **先注销旧的 `idea`(杀掉旧 stdio 桥)→ 再以 stdio 重新注册**,等 `idea_*` 工具就绪,最后才通知。**每次执行都重建**,所以断掉的
-  僵尸桥只要重跑一次命令就能恢复。命令返回即可用;`/close-in-idea` 注销 `idea` + 删标记 + 清环境。
+  **先注销旧的 `idea` → 再重新注册**(远程 Streamable HTTP),等 `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 一挂、所有项目的桥几乎同时被注销,再由各自的消息触发重建。
+- **请求驱动的恢复(没有后台轮询)**:
+  - **`prompt` 钩子**:「已标记 + 本实例没有任何 `idea` 注册」时**探测端口并重新注册**(只探测、绝不 `open -a`)。OpenCode 会
+    await `prompt` 才构建请求,所以**触发它的那条消息本身**就带上了 `idea_*` 工具,没有空窗。这正是 Location 被空闲驱逐
+    (60 分钟 `idleTimeToLive`)或 OpenCode 重启后,新实例自动接回连接的路径。
+  - **`context` 钩子**:发现「本会话见过 `idea_*` 工具、本请求却没有」→ 立刻锁存并在后台重建(不等下一条消息)。工具缺失时注入的
+    恢复引导会**明确禁止**调用 `idea_*`(此前复用"重试一次"的文案,反而诱导模型去调一个不在工具表里的工具,得到
+    `No tool named ... available`)。
+  - **`execute.after` 钩子**:见下一条。
+  恢复是**每个 Location(项目)各一份**;没有任何定时器,插件在不使用时完全静止。
 - **失败触发的自动接入(仅被标记项目)**:`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`),**不认**工具输出里出现的通用串
+    `MCP server is not connected` / `Error POSTing to endpoint`),**不认**工具输出里出现的通用串
     (例如 SQL 工具报的 `Connection refused`) —— MCP 工具错误的 message 就是工具自己的输出,认通用串会把正常业务失败误判成掉线并重建。
     触发成功会把该工具错误改写为"已重连 / 已重新打开,请重试",模型在同一回合内重试;失败则保持原错误。非 `idea_*` 工具、未标记
     项目都不受影响。启动保护 (`launchCooldownMs` / `launchMaxAttempts`) 限制重复拉起 IDE。
-- **`/open-in-idea`**:手动打开当前项目;**等 IDE MCP 就绪 → 先注销旧的 `idea`(杀旧桥)→ 再重新注册 → 等 `idea_*` 工具就绪**才返回。
+- **`/open-in-idea`**:手动打开当前项目;**等 IDE MCP 就绪 → 先注销旧的 `idea` → 再重新注册 → 等 `idea_*` 工具就绪**才返回。
   **`/close-in-idea`**:注销 IDE MCP + 删项目标记 + 清空注入的环境。
 
 ## 限制
@@ -320,17 +325,15 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
   (`get_project_modules`,带 `IJ_MCP_SERVER_PROJECT_PATH`):返回模块 = 已打开 → 跳过 `open -a`;报
   `Unable to determine the target project` = 未打开 → `open -a` 打开。MCP 关闭时会用一次短探测并立即给出设置提示。
   项目刚打开时的短暂"项目未就绪"由工具失败分类兜底(「IDE 在、但项目没打开」→ 重新打开并让模型重试)。
-- 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 掉了(启动即失败)"。
+- IDE **2026.2+** 提供 Streamable HTTP 端点 `/stream`,这是插件**唯一**使用的传输(`type: "remote"`)。注册本身不启动任何子进程,
+  所以没有"桥进程被 IDE 拖死后变成僵尸"这一类问题。`/open-in-idea` 仍要求 IDE MCP 已在监听(冷启动约数十秒),因此会先等就绪再注册。
+- **空闲驱逐(已实测)**:OpenCode 把一个 Location 的服务缓存在 `LayerMap` 里,`idleTimeToLive` = **60 分钟**;空闲到期即整体驱逐,
+  插件实例连同 `idea` MCP 注册一起消失。**两种传输都躲不过**,所以对策不是换传输,而是请求驱动的恢复(见「行为」):
+  - 新实例上第一条用户消息的 `prompt` 钩子会把连接接回来 —— 常态下**不需要用户手动做什么**;
+  - 手动重建仍可用:执行 `/open-in-idea`(先注销旧 `idea`、再重新注册);
+  - 插件给 `idea` server 配 `executionTimeoutMs`(默认 **10 分钟**)作为硬上限:兜住端点卡住时的单次调用,不再沿用 OpenCode 默认的 12 小时;
+  - "IDE 被关掉"这一类会被下一次 `idea_*` 调用暴露(HTTP 直接报错),由 `execute.after` 钩子分类后自愈;不产生 error 的场景(例如
+    IDE 进程还在但项目没打开)由「IDE 在、项目没打开」分支处理。
 - 项目标记存在插件名下 KV (`plugin:opencode-idea:project/<项目根路径>`)。插件实例按 **Location**(项目/打开目录)创建,标记按
   **项目根路径**共享;但两个不同 Location(例如项目根与某子目录)各有自己的内存缓存 —— 单目录打开项目的常见用法不受影响。
 - `/close-in-idea` 会**注销 IDE MCP** 并删标记 + 清空注入的环境。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-idea",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "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/skills/idea-standalone/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: idea-standalone
+description: "为项目生成/维护 standalone(经 IDEA 启动、本机进程直跑)模式的纪律 rule,写在项目根 `.opencode/rules/idea-standalone.md`。当用户要做 standalone 规范、要固化「本机跑哪几个应用」「哪些应用热重载、哪些改了必须重启」「AI 能不能启停本机进程」这类项目级纪律时使用。产出必须写清四段:standalone 是什么、standalone 下经 IDEA run configuration 启动哪些应用、逐应用的热重载与重启提示纪律、以及用户补充的其它条款。"
+---
+
+# Standalone 模式纪律 rule 生成器
+
+## 产出物
+
+一份 **项目级 rule**:`<项目根>/.opencode/rules/idea-standalone.md`,把这个项目在 **本机 standalone 模式**下怎么跑、AI
+能做什么不能做什么固化下来。
+
+- 位置固定:`.opencode/rules/`(项目级规则目录),文件名 `idea-standalone.md`。
+- frontmatter 照抄项目里既有 rule 的格式 (`description` + `alwaysApply: true`)。
+- 只对这个项目生效; **不写**全局规则目录 (`~/.config/opencode/rules/`)。
+
+## 四段结构 (缺一不可)
+
+### 第一段:什么是 standalone 模式
+
+**standalone = 通过 IDEA 启动** —— 应用在本机进程直跑,不容器化、不部署到远端。给"本项目在本机的运行形态"下定义,至少覆盖:
+
+- **通过 IDEA 启动**:每个应用的启动入口就是 IDEA 的 run configuration(Run / Debug),不是手搓命令行。
+- **应用在本机进程直跑**:不容器化、不部署到远端。本机 **不跑**什么也要写明 (例如需要 GPU 的服务、或本机直连的远端数据库)。
+- **只启动其中一部分是常态** —— standalone 不要求所有应用都起来,用户可能只开一两个。
+- **启停一律由用户在 IDEA 手动完成**:AI 不得代为启停本机进程 —— 包括 `go run` / `pnpm dev` / `uvicorn` /
+  `python -m ...` 这类起进程、`kill` / `pkill` 业务进程,以及经 `idea_execute_run_configuration` 启停。AI 若判断需要重启,
+  **先向用户说明并取得明确授权**,绝不自行执行。
+- **与部署链纪律互不构成许可**:standalone 的禁令不适用于部署流程,部署链的步骤也不构成"可以动本机进程"的许可 —— 两阶段纪律互相独立。
+
+### 第二段:standalone 下启动哪些应用 (必须经 IDEA run configuration)
+
+表格,一行一个应用:
+
+| 应用 | run configuration | 目录 | 端口 | 说明 |
+|------|-------------------|------|------|------|
+
+要点:
+
+- `run configuration` 列 **必须是 `idea_get_run_configurations` 里真实存在的名字**(不凭印象写);缺配置时先用
+  `idea-run-config` skill 建项目级 `.run/*.run.xml`,不要手搓启动命令。
+- **启动路径只能是 IDEA run configuration**:不写 `pnpm dev &`、`nohup ... &` 这类后台命令,也不建议用户这么干。
+- 端口写清"固定 / 默认 / 被占用即启动失败"; **哪个应用必须先起来**也要写 (例如前端 dev server 的 proxy 指向本机后端)。
+- 端口读不到 (配置里没有、也没写在项目配置里)就 **问用户**,不要编。
+
+### 第三段:热重载矩阵 + 改代码后要不要提醒重启
+
+逐应用写清 **是 / 不是**热重载,以及对应的提醒纪律:
+
+| 应用                                                  | 热重载 | AI 改代码后                                           |
+|-------------------------------------------------------|--------|-------------------------------------------------------|
+| 带 HMR 的 dev server(如 Vite)                         | 是     | 不提醒重启                                            |
+| 编译型 / 无热重载进程(如 `go run .`、`python -m ...`) | 否     | **必须**在回复里显式点名「需要重启 <应用>」并说明原因 |
+| 只能跑在远端、本机起不来的服务                        | 不适用 | 本机无法验证,按部署链部署后再验证                     |
+
+铁律:
+
+- 非热重载的应用改动后, **不得**在没有提示的情况下宣称"改动完成 / 可以去验证了";重启动作由用户手动做。
+- 热重载列必须有依据 (运行方式 → 有没有 HMR),不确定就问用户,不猜。
+- `go run .` 这类 **没有热重载**的写法要写进 rule,别让 AI 以为改了代码就自动生效。
+
+### 第四段起:项目补充条款
+
+用户针对这个项目给的其它纪律, **按顺序续写在后面**(第四段、第五段……),例如:
+
+- 文件写入位置 (禁止写哪些目录、跑测/调试产物必须落在哪儿)
+- 测试纪律 (用例归属、什么时候才允许新增 UT、端到端测试在哪台机器上跑)
+- 访问归属 (数据库 / 第三方接口只经哪个工具,不旁路直连)
+- dev 模式特有限制 (会真实计费的操作、凭据存储方式等)
+
+处理方式:用户给的条款 **逐条保留原意**、编号连续, **不合并不改写语义**。
+
+## 流程
+
+1. **收集事实 (不猜)**:
+    - `idea_get_run_configurations` → 真实存在的配置名 (第二段"run configuration"列只能来自这里)。
+    - `idea_search_file` 传 `q="*.run.xml"` + `paths: [".run"]` → 每个配置实际干什么 (命令 / 脚本 / npm script)。
+    - `package.json` / `pom.xml` / `go.mod` / `pyproject.toml` / `Cargo.toml` → 项目类型 → 决定第三段的热重载列。
+    - 端口:从 run configuration 的 option 或项目自身配置里读。
+2. **补齐缺口**:哪些应用进 standalone、哪些配置名对不上、端口与热重载不确定 —— 逐条向用户确认,不编。
+3. **写文件**:首次用 `idea_create_new_file` 写 `.opencode/rules/idea-standalone.md`;后续更新用 `idea_apply_patch`
+   **定向改**,不整文件重写。
+4. **校验**:第二段表格里每个配置名都能在 `idea_get_run_configurations` 里查到 —— **查不到就是错的**,不许用
+   "应该生效了"结案。
+
+## 铁律 (汇总)
+
+1. 四段结构不能缺:standalone 定义 → 应用与 run configuration → 热重载与重启提醒 → 用户补充条款。
+2. 第二段的启动方式 **只能是 IDEA run configuration**;不写手搓启动命令。
+3. AI 不启停本机进程 (含 `idea_execute_run_configuration`);判断需要重启时先取得用户明确授权。
+4. 配置名、端口、热重载三项都必须有依据;不确定就问用户。
+5. 用户补充条款保留原意、编号连续,不合并不改写。
+6. rule 只写项目级 `.opencode/rules/idea-standalone.md`,不写全局规则目录。

package/src/ide-guidance.js

@@ -61,13 +61,12 @@ export function buildIdeGuidance(projectPath) {
     `- \`idea_execute_run_configuration\`:跑已有配置;Shell Script 要 \`EXECUTE_IN_TERMINAL: false\`;覆盖参数(\`programArguments\` / \`workingDirectory\` / \`envs\`)需配置支持 \`supportsDynamicLaunchOverrides\`。`,
     ``,
     `### 终端`,
-    `- \`idea_execute_terminal_command\` 用于项目的开发语言与开发工具链;原生 \`shell\` 用于操作系统级的杂活。`,
-    `  - 走 IDE 终端:执行本项目开发语言的运行时与开发工具,语言按项目类型认定 ——`,
-    `    \`pom.xml\` / \`build.gradle\` → \`java\` / \`mvn\` / \`gradle\`;\`package.json\` → \`node\` / \`npm\` / \`pnpm\` / \`yarn\` / \`npx\`;`,
-    `    \`pyproject.toml\` / \`requirements.txt\` → \`python\` / \`pip\` / \`uv\` / \`poetry\` / \`pytest\`;\`go.mod\` → \`go\`;\`Cargo.toml\` → \`cargo\`;\`composer.json\` → \`php\` / \`composer\`;`,
-    `    前端项目 → \`vite\` / \`webpack\` / \`esbuild\` / \`tsc\` 等构建与测试命令。`,
-    `  - 走原生 \`shell\`:\`ls\` / \`cd\` / \`cp\` / \`rm\` / \`git\` / \`grep\` / \`jq\` / \`ps\` / \`curl\` / \`wc\` 等操作系统级通用命令;`,
-    `    以及把语言当一次性脚本干非开发任务的杂活(如 \`python3 -c\` 改一个文件、\`node -e\` 打印一段内容)。`,
+    `- 白名单制:命令用于本项目自身的构建 / 测试 / 运行,且首个可执行文件命中下表,才用 \`idea_execute_terminal_command\`;其余一律走原生 \`shell\`。`,
+    `- 白名单(按本项目类型取对应一行) ——`,
+    `  - Node / 前端(\`package.json\`):\`node\` / \`npm\` / \`npx\` / \`pnpm\` / \`yarn\` / \`vite\` / \`webpack\` / \`esbuild\` / \`tsc\` / \`jest\` / \`vitest\`。`,
+    `  - Java(\`pom.xml\` / \`build.gradle\`):\`java\` / \`javac\` / \`mvn\` / \`mvnw\` / \`gradle\` / \`gradlew\`。`,
+    `  - Python(\`pyproject.toml\` / \`requirements.txt\`):\`python\` / \`python3\` / \`pip\` / \`pip3\` / \`uv\` / \`poetry\` / \`pytest\`。`,
+    `  - Go(\`go.mod\`):\`go\` / \`gofmt\` / \`golangci-lint\`。`,
     `  - \`executeInShell: true\`:在用户真实 shell 里执行,继承 IDE 配好的运行时环境;原生 shell 可能用错版本。`,
     `  - 按预期耗时传 \`timeout\`(毫秒),长任务给足;必要时传 \`maxLinesCount\` 控制返回行数。`,
     `  - 连续命令传 \`reuseExistingTerminalWindow: true\`;结果带 \`command_exit_code\` 与 \`command_output\`,\`cd\` 不跨调用保留,多步用 \`&&\`。`,
@@ -104,6 +103,19 @@ export const MCP_RECOVERY_GUIDANCE_MARKED = [
   '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');
 
+/**
+ * Recovery instruction for a marked project whose idea_* tools are NOT in this
+ * request's tool list. The connection dropped and the plugin is already
+ * reconnecting, but the reconnect only lands on a LATER request — so within this
+ * one a call can only fail with `No tool named "..." is currently available`.
+ * Saying "retry" here (as the MARKED variant does) is what makes the model fire
+ * exactly that doomed call.
+ */
+export const MCP_RECOVERY_GUIDANCE_RECONNECTING = [
+  '### IDEA MCP failure recovery',
+  'No idea_* tool is in this request: the IDE connection dropped and the plugin is reconnecting in the background. Do NOT call any idea_* tool now — it will fail with `No tool named "..." is currently available` — and do not fall back to shell/read/write for in-project work. Continue with what you can, or tell the user the IDE is reconnecting; if idea_* tools are still missing on a later message, ask the user 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.
@@ -121,11 +133,17 @@ export function appendIdeGuidance(system, projectPath) {
 
 /**
  * @param {unknown} system
- * @param {{ marked?: boolean }} [options] `marked` picks the auto-reconnect variant
+ * @param {{ marked?: boolean, serving?: boolean }} [options] `marked` picks the
+ *   auto-reconnect variant; `serving: false` additionally picks the variant for
+ *   a request that has no idea_* tools at all, where a call can only fail.
  */
-export function appendIdeRecoveryGuidance(system, { marked = false } = {}) {
+export function appendIdeRecoveryGuidance(system, { marked = false, serving = true } = {}) {
   if (!Array.isArray(system)) return;
-  const text = marked ? MCP_RECOVERY_GUIDANCE_MARKED : MCP_RECOVERY_GUIDANCE;
+  const text = marked
+    ? serving
+      ? MCP_RECOVERY_GUIDANCE_MARKED
+      : MCP_RECOVERY_GUIDANCE_RECONNECTING
+    : MCP_RECOVERY_GUIDANCE;
   if (system.some((part) => part?.text === text)) return;
   system.push({ type: 'text', text });
 }

package/src/ide-launcher.js

@@ -12,8 +12,6 @@
 // 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';
@@ -37,62 +35,6 @@ 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

@@ -3,13 +3,14 @@
 // HOW THE IDE MCP SERVER WORKS (verified against a real IntelliJ IDEA 2026.2
 // server):
 //
-//   * The IDE exposes a local MCP server. IntelliJ 2026.2+ exposes the modern
-//     Streamable-HTTP endpoint at `http://127.0.0.1:<port>/stream`; older builds
-//     only had the legacy SSE endpoint at `/sse`.
-//   * 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`).
+//   * The IDE exposes a local MCP server at the Streamable-HTTP endpoint
+//     `http://127.0.0.1:<port>/stream` (IntelliJ 2026.2+). That is the only
+//     transport this plugin supports. The IDE's `stdioMcpServer` bridge was
+//     dropped: both transports die with the project's Location services, and the
+//     HTTP one at least reports a dead endpoint as an ordinary tool error
+//     (which the plugin then heals) instead of hanging silently.
+//   * The project a call targets is selected by the project path, carried in the
+//     HTTP header `IJ_MCP_SERVER_PROJECT_PATH` (see `serverConfig`).
 //   * 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
@@ -17,15 +18,6 @@
 
 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';
 
@@ -65,48 +57,13 @@ export function serverConfig(port, projectPath, options = {}) {
   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.
+ * OpenCode defaults this to **12 hours**. A wedged IDE MCP server can accept the
+ * POST and never answer it, so without a cap a call made after the IDE died
+ * would sit unresolved for the whole default. A finite cap turns that hang into
+ * an ordinary timeout error the plugin can classify and heal from.
  *
  * @param {Record<string, unknown>} config
  * @param {{ executionTimeoutMs?: number }} options
@@ -146,7 +103,7 @@ export async function probePort(port, options = {}) {
         params: {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: {},
-          clientInfo: { name: 'opencode-idea', version: '0.0.13' },
+          clientInfo: { name: 'opencode-idea', version: '0.0.15' },
         },
       }),
       signal: controller.signal,
@@ -217,7 +174,7 @@ export async function callTool(port, projectPath, name, args = {}, options = {})
       params: {
         protocolVersion: PROTOCOL_VERSION,
         capabilities: {},
-        clientInfo: { name: 'opencode-idea', version: '0.0.13' },
+        clientInfo: { name: 'opencode-idea', version: '0.0.15' },
       },
     });
     // The IDE's Streamable-HTTP endpoint binds follow-up requests to the session

package/src/plugin.js

@@ -1,10 +1,10 @@
 // opencode-idea — OpenCode plugin entry.
 //
 // For a project the user opted into IDEA this plugin:
-//   1. 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;
+//   1. registers the IDE MCP server with OpenCode as the IDE's Streamable-HTTP
+//      endpoint, scoped to the project through 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 `/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;
@@ -18,20 +18,27 @@
 // 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
+// ready, registers `idea` (remote, project-scoped) and marks the project in
 // `ctx.storage`; `/close-in-idea` unregisters the server and clears the mark.
 // A live endpoint alone does NOT mean our project is open there (the running IDE
 // may have a different project open), so the open flow asks the IDE directly —
 // one project-scoped MCP call — and runs `open -a` only when the project is not
 // open yet.
-// 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.
+//
+// Recovery is request-driven: there is NO background polling. The mark gates it,
+// and it fires from three places, each observing a real fact:
+//   * the `prompt` hook, when the project is marked but this plugin instance has
+//     no `idea` server at all. That is exactly what a fresh instance looks like
+//     after OpenCode evicted the project's Location services (the Location's
+//     LayerMap uses `idleTimeToLive: "60 minutes"`) or after the process
+//     restarted — setup deliberately does not connect, so without this the
+//     session would stay tool-less until the user ran `/open-in-idea` by hand.
+//     `prompt` is awaited before the request is built, so the message that
+//     triggers it already carries the tools;
+//   * the `context` hook, when a request that HAD `idea_*` tools no longer does;
+//   * the `execute.after` hook, when an `idea_*` call fails in a way that means
+//     the IDE MCP is not usable (the server dropped, or the project is not open
+//     in the IDE). A plain business error is classified apart and left alone.
 //
 // `Plugin.define` from `@opencode/plugin` is an identity function, so a plain
 // `{ id, setup }` object is the whole plugin contract. Exporting it directly
@@ -43,15 +50,12 @@ import {
   callTool,
   findIdePort,
   serverConfig,
-  stdioServerConfig,
 } from './mcp/idea.js';
 import { currentProjectPath } from './project.js';
 import {
   createLaunchGuard,
-  DEFAULT_IDE_APP,
   openInIde,
   resolveIdeApp,
-  resolveIdeExecutable,
 } from './ide-launcher.js';
 import {
   appendIdeGuidance,
@@ -69,22 +73,28 @@ const DEFAULT_MCP_PROBE_TIMEOUT_MS = 1000;
 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
+// 等工具目录落地时的轮询间隔。这是一次**有界等待**(见 waitForIdeaTools),不是
+// 状态轮询:100ms 足够快,又不会在 5s 上限内空转几十次。
+const TOOL_REFRESH_POLL_MS = 100;
+// Hard cap on ONE IDE MCP tool call. OpenCode's own default is 12 hours, and a
+// wedged IDE MCP server can accept a POST and never answer it — 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.
+// beyond any normal IDE tool and turns that hang into a normal error the failure
+// classifier can act on.
 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']);
+// Every IDE tool comes from the MCP server the plugin registers as `idea`, and
+// OpenCode namespaces a server's tools with its name — so `idea_*` IS the whole
+// set, the same predicate the request hooks use. "Ready" means at least one of
+// them is listed: OpenCode publishes an MCP catalog wholesale (one reload), so
+// one tool means the batch landed.
+//
+// This used to be a hard-coded pair (`idea_read_file` + `idea_apply_patch`),
+// which is not a property the plugin may assume: the IDE can rename a tool, and
+// the user can switch one off on the IDE's Exposed Tools page. Either one made
+// the wait unsatisfiable, so every `/open-in-idea` and every auto-rebuild burned
+// the full `toolRefreshTimeoutMs` and still reported `tools-loading` — telling
+// the user to re-run a command that could never succeed.
+const IDEA_TOOL_PREFIX = 'idea_';
 
 /**
  * IDEA MCP tools that must never reach the model.
@@ -191,7 +201,10 @@ function toolIds(tools) {
  * - `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).
+ * - `mcp`: the IDE MCP server itself is gone — the endpoint stopped answering,
+ *   the transport closed, or the connection was refused. See the marker list in
+ *   the body; it includes the connect failure OpenCode's own MCP client emits
+ *   (`Unable to connect…`, and the structural `code: "ConnectionRefused"`).
  *
  * Everything else is `none`.
  *
@@ -202,11 +215,10 @@ 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`=...
+  //   - the server could not pick a project for the call: "Unable to determine
+  //     the target project for the current MCP tool call." (the project path in
+  //     the request header did not resolve — the IDE may still be opening it)
+  //   - the project was resolved but is not open: "`projectPath`=...
   //     doesn't correspond to any open project."
   if (
     message.includes('Unable to determine the target project') ||
@@ -214,20 +226,35 @@ function classifyIdeaFailure(error) {
   ) {
     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.
+  // Only transport-level markers, which OpenCode's own MCP client emits. 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
+  // server.
+  //
+  // MEASURED (2026-09-30, OpenCode 2.0.19, IDE process killed): a dead remote
+  // MCP endpoint does NOT produce any of the shapes above. OpenCode's client
+  // reports its own connect failure instead:
+  //
+  //   level=WARN message="mcp http request failed"
+  //     errors="[{\"type\":\"TypeError\",
+  //               \"message\":\"Unable to connect. Is the computer able to access the url?\",
+  //               \"code\":\"ConnectionRefused\",\"errno\":0}]"
+  //
+  // so the text is matched on its stable prefix, and the underlying `code` is
+  // accepted as a structural signal too (a wording change must not silently
+  // disable the heal).
   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')
+    message.includes('Unable to connect')
   ) {
     return 'mcp';
   }
+  const causeCode = error?.error?.code ?? error?.cause?.code ?? error?.code;
+  if (causeCode === 'ConnectionRefused' || causeCode === 'ECONNREFUSED') return 'mcp';
   return 'none';
 }
 
@@ -344,10 +371,6 @@ export default {
    *     mcpStartTimeoutMs?: number,
    *     toolRefreshTimeoutMs?: number,
    *     executionTimeoutMs?: number,
-   *     heartbeatIntervalMs?: number,
-   *     heartbeatFailures?: number,
-   *     transport?: 'stdio' | 'http',
-   *     ideExecutable?: string,
    *     feedback?: false | 'message',
    *   },
    *   command?: {
@@ -407,28 +430,12 @@ export default {
     const ports = asArray(options.ports, DEFAULT_PORTS);
     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.
+    // Cap on a single IDE tool call, so a wedged server 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.
@@ -453,14 +460,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.
+    // Latches when a request showed the `idea_*` tools are gone. It is cleared
+    // only by a successful rebuild. It is set from the `context` hook (a request
+    // that HAD the tools no longer does); the `prompt` hook also heals without
+    // this latch when the instance has no registration at all.
     let needsRebuild = false;
+    // Set once a request in this session actually carried `idea_*` tools, so a
+    // later request without them is a DROP of this session's own connection —
+    // not a project that simply never connected.
+    let wasServing = false;
 
     // Project-level mark: has the user opted this project into IDEA via
     // `/open-in-idea`? One plugin instance serves one project (OpenCode
@@ -534,7 +542,7 @@ export default {
       while (Date.now() < deadline) {
         try {
           const ids = toolIds(await ctx.tool.list());
-          if ([...IDEA_READY_TOOL_IDS].every((id) => ids.includes(id))) return true;
+          if (ids.some((id) => id.startsWith(IDEA_TOOL_PREFIX))) return true;
         } catch {
           // The MCP catalog may still be settling; retry within the bounded wait.
         }
@@ -554,9 +562,7 @@ export default {
     };
 
     const activateIde = async (port) => {
-      const config = useStdio
-        ? stdioServerConfig(ideExecutable, port, projectPath, { executionTimeoutMs })
-        : serverConfig(port, projectPath, { executionTimeoutMs });
+      const config = serverConfig(port, projectPath, { executionTimeoutMs });
       const mcpRegistration = await ctx.mcp.transform((editor) => {
         editor.set(IDEA_SERVER_NAME, config);
       });
@@ -576,15 +582,11 @@ export default {
         return false;
       }
 
-      // 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.
+      // Always tear the server down and register it again. OpenCode's reconcile
+      // SKIPS a re-`set` whose config is unchanged, so re-registering without a
+      // teardown would leave a dropped server in place forever. `/open-in-idea`
+      // and the request hooks are rare; rebuilding costs one restart, which is
+      // the right trade for never leaving a dead registration behind.
       await deactivateIde();
       if (port === undefined) return false;
       return activateIde(port);
@@ -593,13 +595,18 @@ export default {
     // Serialize reconciles so overlapping callers can never register/activate
     // the IDE concurrently (which would leak registrations).
     let reconcileChain = Promise.resolve();
+    // Non-zero while a reconcile is queued or running.
+    let reconcileBusy = 0;
     const enqueue = (task) => {
+      reconcileBusy += 1;
       const next = reconcileChain.then(task);
       reconcileChain = next.then(
         () => {},
         () => {},
       );
-      return next;
+      return next.finally(() => {
+        reconcileBusy -= 1;
+      });
     };
     const reconcile = (options) => enqueue(() => reconcileOnce(options));
 
@@ -744,50 +751,50 @@ export default {
         : 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`.
+     * Coalesced background reconnect.
+     *
+     * The `context` hook latches the rebuild the moment a request shows the tools
+     * are gone, but a latch alone only fires on the NEXT user message — one whole
+     * turn later, which is exactly the gap that made a dead session sit there
+     * until `/open-in-idea` was run by hand. This runs out of band (it never
+     * blocks the request) so the next request — the following agent-loop step, or
+     * any later message — already carries the tools again.
+     *
+     * @returns {Promise<void>}
      */
-    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;
+    /** @type {Promise<void> | undefined} */
+    let reviveInFlight;
+    const reviveIde = () => {
+      // The mark gates EVERY reconnect, not just the ones started from a user
+      // message: a background attempt must never resurrect the IDE for a project
+      // the user closed with `/close-in-idea`.
+      if (disposed || markCache !== true) return Promise.resolve();
+      if (reviveInFlight) return reviveInFlight;
+      const run = (async () => {
+        try {
+          const result = await runOpenInIdea();
+          // `/close-in-idea` can land while this was in flight; it wins.
+          if (markCache !== true) {
+            await deactivateIde();
+            return;
+          }
+          if (result.port !== undefined) {
+            needsRebuild = false;
+          }
+        } catch {
+          // best effort: the latch stays set, and the prompt hook retries
         }
-        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;
-      }
+      })();
+      reviveInFlight = run;
+      void run.then(() => {
+        if (reviveInFlight === run) reviveInFlight = undefined;
+      });
+      return run;
     };
-    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();
+
+    // Setup never probes or connects the IDE — everything is on `/open-in-idea`.
+    await reconcile({ probeIde: false });
 
     const sendFeedback = async (input, result) => {
       if (feedback !== 'message' || typeof ctx.session?.prompt !== 'function') return false;
@@ -878,10 +885,10 @@ export default {
           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.
+            // Unregister the IDE MCP server. Reuses the serialized reconcile, so
+            // a concurrent rebuild (an in-flight `/open-in-idea`, or a
+            // request-time heal) cannot re-register the server after the mark is
+            // gone.
             await reconcile({ probeIde: false });
             await sendFeedback(input, { status: 'closed' });
           },
@@ -902,9 +909,29 @@ export default {
     if (typeof ctx.session?.hook === 'function') {
       sessionRegistration = await ctx.session.hook('context', (event) => {
         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, { marked: markCache === true });
+        const serving = tools !== undefined && Object.keys(tools).some((name) => name.startsWith(IDEA_TOOL_PREFIX));
+        if (serving) {
+          wasServing = true;
+          removeIdeaToolDefinitions(tools, HIDDEN_IDEA_TOOLS);
+        } else if (wasServing && tools !== undefined && markCache === true) {
+          // This session HAD the tools and this request does not. Latch a
+          // rebuild here, where "is the IDE serving THIS request?" is a fact: a
+          // failed reconnect can tear the registration down without anything else
+          // noticing. `wasServing` keeps this from firing for a project that
+          // never connected in this session — the `prompt` hook covers that case
+          // (a fresh instance has no registration at all) and setup deliberately
+          // does not connect on its own.
+          needsRebuild = true;
+          wasServing = false;
+          // Do not wait for the next user message. The latch is read by the
+          // `prompt` hook, which has ALREADY run for this request — so without
+          // this the session would stay tool-less for the rest of the turn and
+          // need one more message before anything happened.
+          void reviveIde();
+        }
+        if (markCache === true || serving) {
+          appendIdeRecoveryGuidance(event?.system, { marked: markCache === true, serving });
+        }
         if (!injectGuidance) return;
         // Guidance promises tools the model can call, so it only goes out when
         // they are actually in this request.
@@ -912,12 +939,23 @@ export default {
         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.
+      // 自愈入口(钩子型)。OpenCode 会 await `prompt`,所以在这里修好的连接会在
+      // **本次请求**里就带上 `idea_*` 工具,没有"先回一句正在重连、下一条才行"
+      // 的空窗。
+      //
+      // 两种"需要重连"的形状都从这里进:
+      //   * `needsRebuild` — 之前的请求已经证明工具没了;
+      //   * `registrations.length === 0` — 本插件实例压根没有 `idea` 服务器,这
+      //     正是 OpenCode 回收 Location 服务(LayerMap idleTimeToLive = 60 分钟)
+      //     或进程重启后新实例的样子。setup 故意不连接,没有这一步会话就会永久
+      //     没有工具,只能靠用户手敲 `/open-in-idea`。
+      //
+      // 只探测、不启动 IDE:走 `reconcile({ probeIde: true })`,而不是会 `open -a`
+      // 的 `reviveIde()` —— 一条用户消息不该把 IDEA 拉起来。
       promptRegistration = await ctx.session.hook('prompt', async (event) => {
-        if (disposed || !needsRebuild || markCache !== true) return;
+        if (disposed || markCache !== true) return;
+        const fresh = registrations.length === 0;
+        if (!needsRebuild && !fresh) 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
@@ -925,11 +963,12 @@ export default {
         // — 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;
+        try {
+          await reconcile({ probeIde: true });
+        } catch {
+          // best effort: the latch stays set and the next message retries
         }
+        if (registrations.length > 0) needsRebuild = false;
       });
 
       // The only self-initiated action: when an `idea_*` call fails in a way
@@ -960,7 +999,6 @@ export default {
 
     return async () => {
       disposed = true;
-      if (heartbeatTimer) clearInterval(heartbeatTimer);
       if (sessionRegistration) {
         try {
           await sessionRegistration.dispose();