opencode-idea 0.0.17 → 0.0.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +408 -183
- package/package.json +5 -1
- package/skills/idea-run-config-manager/SKILL.md +62 -0
- package/skills/idea-run-config-manager/assets/AGENTS.template.md +46 -0
- package/skills/idea-run-config-manager/assets/types/go-build.md +44 -0
- package/skills/idea-run-config-manager/assets/types/gradle.md +57 -0
- package/skills/idea-run-config-manager/assets/types/maven.md +61 -0
- package/skills/idea-run-config-manager/assets/types/node.md +30 -0
- package/skills/idea-run-config-manager/assets/types/npm.md +58 -0
- package/skills/idea-run-config-manager/assets/types/python.md +59 -0
- package/skills/idea-run-config-manager/assets/types/shell.md +77 -0
- package/skills/idea-standalone/SKILL.md +5 -3
- package/skills/idea-standalone/assets/AGENTS.template.md +18 -13
- package/src/ide-guidance.js +183 -38
- package/src/ide-guidance.template.md +131 -37
- package/src/ide-launcher.js +87 -27
- package/src/ide-projects.js +262 -0
- package/src/mcp/enhance.js +111 -29
- package/src/mcp/idea-tool-defaults.js +27 -12
- package/src/mcp/idea.js +9 -75
- package/src/plugin.js +726 -365
- package/src/skill/loader.js +43 -3
package/README.md
CHANGED
|
@@ -2,97 +2,148 @@
|
|
|
2
2
|
|
|
3
3
|
OpenCode 插件,面向 JetBrains 项目 (IntelliJ IDEA / PyCharm / WebStorm 等),做两件事:
|
|
4
4
|
|
|
5
|
-
1. **接入 IDE MCP** ——
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
(
|
|
5
|
+
1. **接入 IDE MCP** —— 把项目在**它自己的 IDE** 里打开,并把这些 IDE 的 MCP 工具注册进 OpenCode。一个 OpenCode 会话可以
|
|
6
|
+
同时接入**多个项目**:root 本身,以及 root 下任意层级的**子项目**;子项目可以用与 root **不同**的 IDE 打开
|
|
7
|
+
(root 在 IDEA、`modelserver` 在 PyCharm 是常态)。每个项目注册成独立的 MCP server,**工具名前缀就是它**:
|
|
8
|
+
root 是 `ide_*`,子项目是 `<目录名>_*`(例如 `modelserver_search_symbol`)。
|
|
9
|
+
2. **优先使用 IDE 工具** —— IDE 可用时,向模型注入**逐项目**的引导:在哪个项目里工作,就用哪个项目前缀的工具;IDE 不可用时
|
|
10
|
+
回退原生工具(正常回退,无需声明)。
|
|
9
11
|
|
|
10
12
|
> **需要项目环境的命令走 Run Configuration**:跑 `java` / `python` / `npm` 这类依赖项目配好的 JDK / Node / Python 版本的
|
|
11
|
-
> 命令时,引导模型用 `
|
|
12
|
-
> 环境的命令照常走原生 shell。**IDE 内置终端 (`
|
|
13
|
+
> 命令时,引导模型用 `ide_execute_run_configuration`(配置**由用户**先在 IDE 里建好),而不是原生 shell;不需要项目
|
|
14
|
+
> 环境的命令照常走原生 shell。**IDE 内置终端 (`ide_execute_terminal_command`) 已被隐藏** —— 实测它并不继承项目环境,
|
|
13
15
|
> 对原生 shell 没有任何优势。详见「项目命令执行」。
|
|
14
16
|
|
|
15
|
-
非 JetBrains
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
非 JetBrains 项目完全不受影响。**手动接入**:插件启动不探测、不连接任何 IDE。三个命令管全部:
|
|
18
|
+
|
|
19
|
+
| 命令 | 作用 |
|
|
20
|
+
| ------------------------------- | ------------------------------------------------------------------------------- |
|
|
21
|
+
| `/open-in-ide [ide]` | 接入 root 及其全部已登记子项目;第一次**没有配置**时由 AI 问用户 root 用哪个 IDE |
|
|
22
|
+
| `/add-sub-module-in-ide <路径>` | 登记一个子项目(相对 root 的路径);随后由 AI 问用户它用哪个 IDE |
|
|
23
|
+
| `/delete-in-ide` | 删掉**整个**配置(root + 全部子项目)并注销全部 IDE MCP |
|
|
24
|
+
|
|
25
|
+
配置持久化在 `ctx.storage`(`project/<root 路径>`),重启 OpenCode 后仍在。之后**没有任何后台轮询**——恢复完全靠请求驱动:插件发现"该有
|
|
26
|
+
IDE 工具却没有"(新实例)或"IDE 工具调用失败"(掉线)时,**在下一条消息发出前静默接回**(用户无感)。没跑过 `/open-in-ide` 的 root
|
|
27
|
+
保持全手动、零自主动作。
|
|
19
28
|
|
|
20
29
|
> **为什么改成请求驱动**:OpenCode 把一个 Location(项目)的全部服务缓存在 `LayerMap` 里,空闲 **60 分钟**
|
|
21
|
-
> (`idleTimeToLive`)
|
|
30
|
+
> (`idleTimeToLive`)后整体驱逐——插件实例连同全部 IDE MCP 注册一起消失。这一点两种传输都躲不过,所以与其后台探活
|
|
22
31
|
> (永远晚一步、还刷 IDE 日志),不如在请求前发现并把连接接回来。
|
|
23
32
|
|
|
24
33
|
## 工作原理
|
|
25
34
|
|
|
26
35
|
```text
|
|
27
|
-
setup(启动,
|
|
28
|
-
a.
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
36
|
+
setup(启动, 每 root 一次):
|
|
37
|
+
a. 读配置(ctx.storage: project/<root 路径>; OpenCode 重启后仍生效)
|
|
38
|
+
—— root 用哪个 IDE,登记了哪些子项目、各自用哪个 IDE
|
|
39
|
+
b. 注册 3 个命令 + session context/prompt 钩子 + tool 钩子 + configure_ide_project 工具
|
|
40
|
+
不探测、不注册任何 MCP
|
|
41
|
+
|
|
42
|
+
/open-in-ide(手动触发, 阻塞到就绪):
|
|
43
|
+
1. 还没有配置时:
|
|
44
|
+
- 带了 ide 参数 → 直接写入 root 的 IDE(直通逃生口,不经过模型)
|
|
45
|
+
- 没带参数 → 发给模型一条**任务**:请它问用户 root 用 IDEA 还是 PyCharm,拿到答复后调用
|
|
46
|
+
configure_ide_project 回写;本次到此为止。**只有第一次要问**
|
|
47
|
+
2. 有配置时,对**每个**已登记项目:
|
|
48
|
+
- 在**该项目自己 IDE 的固定端口**上问「你认得这个项目吗」(`get_project_modules`,带项目路径)
|
|
49
|
+
· 认得 → 就用那个端口(这就是"哪个 IDE 打开着它"的判定)
|
|
50
|
+
· 不认得 → `open -a <该项目自己的 IDE> <项目目录>`,再轮询等到认得(上限 60s)
|
|
51
|
+
3. **先注销全部旧注册,再按项目各注册一个 MCP server**
|
|
52
|
+
(server 名 = 工具前缀:root 是 `ide`,子项目是目录名;`type: "remote"` 指向
|
|
53
|
+
`http://127.0.0.1:<port>/stream`,项目路径走请求头)
|
|
54
|
+
4. 等 IDE 工具进入注册表;按每个项目实际提供的工具同步 skill;启用逐项目引导
|
|
55
|
+
5. 发结果通知(用户看到干净气泡,模型只回"收到")
|
|
56
|
+
|
|
57
|
+
/add-sub-module-in-ide <路径>(手动触发):
|
|
58
|
+
1. 没有配置 → 直接报错,提示先执行 /open-in-ide(不提问、不写任何东西)
|
|
59
|
+
2. 有配置 → 校验路径:必须在 root 下、目录存在、目录名合法、前缀不与已登记项目重名、不占用保留名
|
|
60
|
+
3. 通过 → 发给模型一条**任务**:请它问用户这个子项目用哪个 IDE,答复后调用
|
|
61
|
+
configure_ide_project 回写。(带多个参数 = 报错,不猜)
|
|
62
|
+
|
|
63
|
+
/delete-in-ide(手动触发):
|
|
64
|
+
1. 删除**整个**配置(root + 全部子项目) + 注销全部 IDE MCP + 清空注入的环境
|
|
45
65
|
2. 发结果通知
|
|
46
66
|
|
|
47
|
-
工具失败触发(
|
|
48
|
-
1.
|
|
67
|
+
工具失败触发(仅在有配置的 root 里):
|
|
68
|
+
1. IDE 工具调用失败 → tool execute.after 钩子**分类**:
|
|
49
69
|
- IDE MCP 不可用(掉了)→ 重跑接入流程
|
|
50
|
-
- IDE 在、但项目没打开("Unable to determine the target project" / "doesn't correspond to any open project")
|
|
70
|
+
- IDE 在、但项目没打开("Unable to determine the target project" / "doesn't correspond to any open project")
|
|
71
|
+
→ 让**这个工具所属项目**的 IDE 重新打开它(不会去动别的项目)
|
|
51
72
|
- 普通业务错误(File not found 等)→ 不动作
|
|
52
73
|
2. 触发成功 → 把该错误改写为"已重连 / 已重新打开,请重试",模型同一回合重试;失败 → 保持原错误
|
|
53
74
|
|
|
54
75
|
请求驱动的恢复(没有后台轮询;每个 Location(项目)各一份插件实例):
|
|
55
|
-
1. `prompt` 钩子(消息进入时,OpenCode 会 await 它)
|
|
56
|
-
探测端口,**只注册、绝不 `open -a`**;命中就重建,于是**这条消息本身**就带上了
|
|
57
|
-
2. `context` 钩子——某条请求"曾经有
|
|
58
|
-
3. `execute.after`
|
|
76
|
+
1. `prompt` 钩子(消息进入时,OpenCode 会 await 它)——「已配置 + 本实例没有任何 MCP 注册」→
|
|
77
|
+
探测端口,**只注册、绝不 `open -a`**;命中就重建,于是**这条消息本身**就带上了 IDE 工具
|
|
78
|
+
2. `context` 钩子——某条请求"曾经有 IDE 工具、现在没有" → 立刻锁存并在后台重建(不等下一条消息)
|
|
79
|
+
3. `execute.after` 钩子——IDE 工具调用以"不可用"告终(`MCP server "<名>" is not available` /
|
|
59
80
|
`Error POSTing to endpoint`)→ 重跑接入流程,并把错误改写成"已重连,请重试";
|
|
60
81
|
普通业务错误(文件不存在等)不动作
|
|
61
82
|
※ 三者都只在**确实有事发生**时动;没人用这个项目时,插件完全静止
|
|
62
83
|
```
|
|
63
84
|
|
|
64
|
-
##
|
|
85
|
+
## 接入 (`/open-in-ide` 与 `/add-sub-module-in-ide`)
|
|
86
|
+
|
|
87
|
+
### `/open-in-ide [ide]`
|
|
65
88
|
|
|
66
|
-
|
|
89
|
+
输入 `/open-in-ide`,把 root 及其**全部已登记子项目**接入。每个项目都用**它自己配置的 IDE** 打开:
|
|
67
90
|
|
|
68
|
-
|
|
69
|
-
|
|
91
|
+
1. **第一次(还没有配置)** —— 插件不猜:
|
|
92
|
+
- 不带参数 → 插件先按**安装目录**探一次本机装了哪些 IDE(macOS 是 `/Applications` 与 `~/Applications`,
|
|
93
|
+
Windows / Linux 按各自的常见位置),把结论写进任务文本,再让模型问用户。**不让模型自己去翻进程** ——
|
|
94
|
+
`ps aux | grep` 只看得见**正在运行**的 IDE,装了没开就漏(实测踩过:PyCharm 明明装着,却被报成"未发现"),
|
|
95
|
+
而且慢。**只有这一次**需要用户回答;
|
|
96
|
+
- 带参数(`/open-in-ide pycharm`)→ 直通写入,不经过模型(模型不配合时的逃生口)。
|
|
70
97
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
2.
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
98
|
+
探测结果只用来"帮用户做选择",不决定"哪个 IDE 正开着这个项目" —— 后者始终由用户回答。探不到时
|
|
99
|
+
(非 mac、或路径未知)那句提示干脆不出现,照常问用户。
|
|
100
|
+
|
|
101
|
+
2. **有配置后** —— 对每个已登记项目,在**它自己 IDE 的固定端口**上问「你认得这个项目吗」(`get_project_modules`,带项目路径 header):
|
|
102
|
+
- 认得 → 用那个端口。这同时就是"这个项目被哪个 IDE 打开着"的判定(IDEA 与 PyCharm 是两个进程、两个端口);
|
|
103
|
+
- 不认得 → `open -a "<该项目自己的 IDE>" <项目目录>`(**复用已运行实例**),再轮询等到认得(冷启动数十秒,上限 60s)。
|
|
104
|
+
3. 就绪后 **先注销全部旧注册 → 再按项目各注册一个 MCP server**(server 名 = 工具前缀),然后重读 IDE 环境、启用逐项目引导,
|
|
105
|
+
并**等到 IDE 工具进入注册表**才返回。
|
|
106
|
+
|
|
107
|
+
> **非 macOS**:第 2 步的自动打开被跳过(没有对应的启动命令),请**先手动打开 IDE 和项目**,再执行本命令 ——
|
|
108
|
+
> 端口在监听、项目被认得就会正常接入。
|
|
80
109
|
|
|
81
110
|
> **通知不触发 AI 干活**:默认 `feedback: "message"` 把结果作为一条 **标注清楚的通知**发到会话里 —— 用户看到干净的通知气泡
|
|
82
111
|
> (经 `metadata.displayText`),模型只看到"这是通知,请只回复『收到』"的指令,因此不会执行任何操作、不会调用工具。
|
|
83
|
-
> `feedback: false`
|
|
112
|
+
> `feedback: false` 则完全静默。**唯一例外**是上面"问用户用哪个 IDE"那条:它是**任务不是通知**,模型必须问完并调用工具才算完成。
|
|
113
|
+
|
|
114
|
+
**可重入 / 启动保护**:IDE 冷启动、索引或等待「Trust and Open Project」弹窗期间探测会失败。命令只发一次 MCP/Brave Mode 提示并
|
|
115
|
+
fast-fail,不会在后台轮询;重复触发共享同一次打开请求,**每个项目各自维护** `lastSpawnAt` / `attempts`,避免重复 spawn。
|
|
116
|
+
|
|
117
|
+
### `/add-sub-module-in-ide <路径>`
|
|
118
|
+
|
|
119
|
+
把一个子项目登记进配置。参数是**相对 root 的路径**(例如 `modelserver`),而且**只接受一个参数**:
|
|
120
|
+
|
|
121
|
+
1. 没有配置 → 直接报错,提示先执行 `/open-in-ide`(不提问、不写任何东西);
|
|
122
|
+
2. 校验:必须位于 root 之下、目录真实存在、**目录名合法**、前缀不与已登记项目重名、不占用保留名 `ide`;
|
|
123
|
+
3. 通过后发给模型一条**任务**:请它问用户这个子项目用哪个 IDE,答复后调用 `configure_ide_project` 回写。
|
|
124
|
+
|
|
125
|
+
**目录名的硬规则**(它就是工具前缀,所以不给猜的余地):必须匹配 `^[a-z0-9][a-z0-9_-]*$` —— 小写字母或数字开头,
|
|
126
|
+
只含小写字母、数字、`-`、`_`。不合规(大写、点号、空格、中文……)或与已登记项目重名,插件**一律拒绝**并说明原因,
|
|
127
|
+
由用户改目录名。插件**绝不**自动改名或自动消歧。
|
|
128
|
+
|
|
129
|
+
### 让模型回写:`configure_ide_project`
|
|
130
|
+
|
|
131
|
+
插件注册的一个**自己的**工具,是"用户选的 IDE"回到配置里的**唯一通道**(插件不能弹选择框,也不能挂起等回答):
|
|
84
132
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
133
|
+
```text
|
|
134
|
+
configure_ide_project({ ide: "<idea|pycharm>" }) // 配置 root
|
|
135
|
+
configure_ide_project({ path: "modelserver", ide: "pycharm" }) // 配置一个子项目
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
它常驻在工具列表里(一个工具的 schema 只有几百 token,不值得为它做一套注册/撤销的状态机);
|
|
139
|
+
该不该被调用由工具描述约束 —— "仅当用户明确回答了用哪个 IDE 之后调用"。
|
|
88
140
|
|
|
89
|
-
|
|
90
|
-
**改完插件后重跑一次 `/open-in-idea`** 即可恢复。
|
|
141
|
+
## 删除接入 (`/delete-in-ide`)
|
|
91
142
|
|
|
92
|
-
|
|
143
|
+
输入 `/delete-in-ide`:**注销全部 IDE MCP** + 删除**整个**配置(root 与全部子项目,持久化 + 内存缓存一并清),
|
|
144
|
+
并清空注入的环境变量。之后 IDE 工具不再可用,也不会再因失败自动接入。想重新接入,再次执行 `/open-in-ide`。
|
|
93
145
|
|
|
94
|
-
|
|
95
|
-
之后 `idea_*` 工具不再可用,也不会再因失败自动接入。想重新接入,再次执行 `/open-in-idea`。
|
|
146
|
+
**热更新会断开**:插件源码变更会触发 V2 热重载,注册随旧实例一起释放。**改完插件后重跑一次 `/open-in-ide`** 即可恢复。
|
|
96
147
|
|
|
97
148
|
## 按能力选工具 (直接调用引导)
|
|
98
149
|
|
|
@@ -102,26 +153,47 @@ IDE MCP 可用时,插件通过 **系统提示注入**告诉模型**哪些事该
|
|
|
102
153
|
1. **系统提示注入**:通过 `ctx.session.hook("context", …)` 往每次请求的 system 里追加一段引导 + 能力映射表。**文本本身在
|
|
103
154
|
`src/ide-guidance.template.md`**——它是一份要给人 review 的提示词文档,条件直接用 `{{#if …}}` 写在那几行外面,所以打开模板
|
|
104
155
|
就能看到最终渲染成什么样;`src/template.js` 是渲染器(支持 `{{var}}` / `{{#if}}` / `{{else}}`,**不做 HTML 转义**——
|
|
105
|
-
输出是 Markdown,`<jar>!/<entry>` 和反引号必须原样过)。含工具名 (
|
|
156
|
+
输出是 Markdown,`<jar>!/<entry>` 和反引号必须原样过)。含工具名 (`<项目前缀>_<name>`;root 是 `ide_*`,
|
|
157
|
+
子项目是 `<目录名>_*`)与关键参数名:
|
|
106
158
|
- **只有 IDE 才有的能力才写进去** —— 符号级检索、项目模型、检查与构建、重构与格式化、运行配置:
|
|
107
|
-
- 符号 → `
|
|
108
|
-
- 项目与编辑器 → `
|
|
109
|
-
`
|
|
110
|
-
- 重构/格式化 → `
|
|
111
|
-
- 校验 → `
|
|
112
|
-
- 运行配置 → `
|
|
159
|
+
- 符号 → `ide_search_symbol` / `ide_get_symbol_info` / `ide_analyze_calls`
|
|
160
|
+
- 项目与编辑器 → `ide_get_project_modules` / `ide_get_project_dependencies` / `ide_list_directory_tree` /
|
|
161
|
+
`ide_get_all_open_file_paths` / `ide_open_file_in_editor`
|
|
162
|
+
- 重构/格式化 → `ide_rename_refactoring` / `ide_reformat_file`
|
|
163
|
+
- 校验 → `ide_lint_files` / `ide_get_file_problems` / `ide_build_project`
|
|
164
|
+
- 运行配置 → `ide_get_run_configurations` / `ide_execute_run_configuration`(+ 配套插件的启停工具)
|
|
165
|
+
- 部署(**仅配套插件 + Ultimate**)→ `ide_list_deployment_servers` / `ide_upload_to_deployment` /
|
|
166
|
+
`ide_download_from_deployment` / `ide_get_deployment_task_status`
|
|
113
167
|
- **读、写、找文本、找文件用原生工具**(`read` / `write` / `edit` / `grep` / `glob`)—— 这几件事走 IDE 只是多一跳,
|
|
114
|
-
所以映射表里**不出现** `
|
|
115
|
-
`
|
|
116
|
-
- **唯一例外是 `
|
|
168
|
+
所以映射表里**不出现** `ide_search_text` / `ide_search_regex` / `ide_search_file` / `ide_apply_patch` /
|
|
169
|
+
`ide_create_new_file`,也不再禁止它们的原生对应物。
|
|
170
|
+
- **唯一例外是 `ide_read_file`**:它是读**包内文件**的唯一手段(`<jar>!/<entry>` 的依赖 jar 内文件、`jrt://` 的
|
|
117
171
|
JDK 镜像),引导只在这个用途上点名它,并写明普通文件一律用 `read`。
|
|
118
172
|
|
|
173
|
+
**有两处不只写"工具能干什么",还写了"什么时候走它 / 不要走哪条替代路"**:
|
|
174
|
+
一是「校验」,lint / build 在清单里等于没提醒 —— 实测模型绕开工具、自己去 `shell` 里临时编译一遍就宣布
|
|
175
|
+
完成(它还为此给了一套自洽的理由:沙箱 IDE 是另一个进程)。这一节**先讲"改完自己先查一遍",再把判断权
|
|
176
|
+
交回模型**:大片改动 → 全部改完一次 `build_project`(中途不查,半成品的检查结果只会误导);单点改动 /
|
|
177
|
+
同一文件反复微调 → 告一段落时对这轮改过的文件一次 `lint_files`;改了签名 / 接口 / import / 依赖走 build,
|
|
178
|
+
只动文件内部实现走 lint 就够。**两个失效方向都点名**——每敲一次编辑就查一次,和压根不查一样是错的,而
|
|
179
|
+
"这一轮属于哪一种"只有模型自己知道,提示词只能给判据、不能替它决定。末两条是收口:查出来的问题要改掉或
|
|
180
|
+
说明为什么不改;别用 `shell` 里临时编译代替 IDE 工具,也别先猜"索引还没同步 / 那是另一个进程"就绕开
|
|
181
|
+
(实测两次绕开都是这句猜测,而工具其实一次就答了)。
|
|
182
|
+
二是「符号」,而且它是被实测打回来的:**一个 IntelliJ 插件会话里 398 次 `shell`、模型自己 reasoning 里
|
|
183
|
+
`javap` 出现 175 次,`search_symbol` 只出现 3 次(两次还是用户开口之后)**。老文案把这件事写成"找符号
|
|
184
|
+
声明位置的技巧",而模型当时的动因是"这个平台方法到底怎么实现的"——两边对不上,触发点就永远不 fire。
|
|
185
|
+
所以现在**先把动因写在节标题下面第一句**("要读任何类 / 方法 / 字段的源码,就两步"),把"依赖库 / 三方包 /
|
|
186
|
+
平台 jar 里的实现"点明为**这套用得最多的地方**,并显式禁掉它真正的默认手艺:自己拼 jar 路径 + `javap` /
|
|
187
|
+
`unzip` / 解包看字节码。理由给的是能赢过直觉的那条:**IDE 索引里那份就是项目编译时真正用的依赖**(自己
|
|
188
|
+
拼的常常是另一份副本,版本对不上),而且读出来是反编译源码,不是要来回十几次才拼得出逻辑的字节码清单。
|
|
189
|
+
总则里各有同义的一句,因为**总则才是每条路由规则都会路过的地方**,而这两类失败恰恰都是"整段跳过"。
|
|
190
|
+
|
|
119
191
|
不会把整份工具目录重复塞进 system prompt,也不要求模型先写编排代码。IDEA MCP 工具自身的
|
|
120
192
|
description/schema 仍是参数使用的权威来源;工具返回业务错误时先修正参数,不要误判成工具不可用。MCP 不可用时立即
|
|
121
|
-
提示用户执行 `/open-in-
|
|
193
|
+
提示用户执行 `/open-in-ide`,不重复探测或等待。
|
|
122
194
|
|
|
123
|
-
**总则里最靠前的两条是 Code Mode 规则**,而且第一条是**通用**的,不是 `
|
|
124
|
-
直接调用,不需要也不应该用 Code Mode 的 `search` 去找`;第二条才落到 `
|
|
195
|
+
**总则里最靠前的两条是 Code Mode 规则**,而且第一条是**通用**的,不是 `ide_*` 特例:`工具列表里已经直接列出的原生工具,
|
|
196
|
+
直接调用,不需要也不应该用 Code Mode 的 `search` 去找`;第二条才落到 `ide_*`(它就是原生工具,且不在 Code Mode 目录里)。
|
|
125
197
|
放在所有路由规则之前,因为它们是前提 —— 模型拿不到工具,后面写什么都没用。理由是实测过的失效:工具明明在原生工具
|
|
126
198
|
列表里,模型却进 Code Mode 跑了一次工具搜索(Code Mode 自己的指令「用 `search` 找工具」读起来像是访问任何东西的通用
|
|
127
199
|
姿势,而原文没有任何一句说明这些工具在哪),白绕一圈之后还可能得出"工具不可用"的错误结论。同一条约束也写在
|
|
@@ -130,9 +202,18 @@ IDE MCP 可用时,插件通过 **系统提示注入**告诉模型**哪些事该
|
|
|
130
202
|
引导只在 **IDE MCP 可用**时生效;MCP 不可用时仅保留 fast-fail 恢复提示。`injectGuidance: false` 可关闭系统提示注入。
|
|
131
203
|
|
|
132
204
|
**条件注入**:映射表里只有内置 MCP Server 自带的那批工具是「永远写死」的。如果 IDE 里另外装了配套的
|
|
133
|
-
[`idea-mcp-enhance`](https://github.com/syllr/idea-mcp-enhance)
|
|
134
|
-
|
|
135
|
-
|
|
205
|
+
[`idea-mcp-enhance`](https://github.com/syllr/idea-mcp-enhance) 插件,它提供的**两组**工具会各自被加进下面的段落 ——
|
|
206
|
+
run configuration 的启停工具进「运行配置」段,部署工具进「服务器文件同步」段。判据都是**这次请求的工具快照里真的有这些工具**:
|
|
207
|
+
装不上的 IDE 上对应内容一个字都不会出现,模型不会去调一个不存在的工具。
|
|
208
|
+
|
|
209
|
+
两组的前提不同,所以是两组、两条独立的判据:启停工具只要有配套插件就有;部署工具**还要求
|
|
210
|
+
`com.jetbrains.plugins.webDeployment`(FTP/SFTP/WebDAV Connectivity)—— 它只在 Ultimate 里存在**。
|
|
211
|
+
用一个布尔覆盖两者,部署工具就会替"启停工具在不在"作答。
|
|
212
|
+
|
|
213
|
+
**逐项目核对到命令名一级**:配套插件的工具是**按项目分别存在**的,所以每条工具后面列出的命令名只包含
|
|
214
|
+
**真的提供它**的那些项目(`src/ide-guidance.js` 的 `ENHANCE_SUFFIXES` + `servesTool`)——
|
|
215
|
+
"根项目在 IDEA Ultimate、子项目在 PyCharm Community"时,部署那几条只会写根项目的命令名,不会顺手把子项目也写上去。
|
|
216
|
+
内置工具不受影响:它们每个项目都有一份,照旧全部列出。
|
|
136
217
|
|
|
137
218
|
## 工具参数 (schema 收敛 + `execute.before`)
|
|
138
219
|
|
|
@@ -145,9 +226,9 @@ IDE MCP 可用时,插件通过 **系统提示注入**告诉模型**哪些事该
|
|
|
145
226
|
|
|
146
227
|
两半由 `src/mcp/idea-tool-defaults.js` 的**同一张表** `FORCED_ARGUMENTS` 驱动,所以不会漂移。目前一条:
|
|
147
228
|
|
|
148
|
-
| 工具
|
|
149
|
-
|
|
|
150
|
-
| `
|
|
229
|
+
| 工具 | 参数 | 值 | 为什么 |
|
|
230
|
+
| ------------------- | --------- | ------ | -------------------------------------------------------------------------------------------------------------- |
|
|
231
|
+
| `ide_build_project` | `rebuild` | `true` | 增量构建比对的是 **IDE 自己那份文件新鲜度**;IDE 外部改的代码可能被判成"没有脏文件",构建于是变成 no-op 并报成功 |
|
|
151
232
|
|
|
152
233
|
- **强制**而不是"缺省才补":`rebuild: false` 请求的正是那个可能出错的答案,而且调用方从结果里分辨不出来;`rebuild: true`
|
|
153
234
|
唯一的代价是时间。
|
|
@@ -165,7 +246,7 @@ IDE MCP 可用时,插件通过 **系统提示注入**告诉模型**哪些事该
|
|
|
165
246
|
IDE 自己的 `build_project` 工具描述本来就没提这个参数(只有属性级描述提),所以删掉属性之后 schema 依然自洽、也依然完全是
|
|
166
247
|
IDE 的。schema 变换**绝不能**用来加建议 —— 那是引导文本的职责。
|
|
167
248
|
|
|
168
|
-
|
|
249
|
+
两半都**不依赖项目配置**:它们修的是工具调用本身,与"这个项目是否接入 IDE"无关。
|
|
169
250
|
|
|
170
251
|
## Run Configuration 全套 (配套插件 `idea-mcp-enhance`)
|
|
171
252
|
|
|
@@ -173,62 +254,87 @@ IDE 内置的 MCP Server 只能 **启动已有**的 run configuration(`execute_r
|
|
|
173
254
|
也查不到运行状态**。配套的 IDEA 插件 [`idea-mcp-enhance`](https://github.com/syllr/idea-mcp-enhance)(IDEA 2026.2+,另装)
|
|
174
255
|
补齐这四件事 —— 正好是「建 → 看 → 停 → 重启」一条链:
|
|
175
256
|
|
|
176
|
-
| 工具 (OpenCode 里叫 `
|
|
177
|
-
|
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
257
|
+
| 工具 (OpenCode 里叫 `ide_*`) | 作用 |
|
|
258
|
+
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
259
|
+
| `ide_create_shell_run_configuration` | 新建**项目级** Shell 配置(写 `.run/<name>.run.xml`);只支持 Shell 类型。**项目资产 —— 只给会重复发生的流程建,且必须先征得用户同意** |
|
|
260
|
+
| `ide_list_running_configurations` | **当前真正在跑**的配置:几个实例 / 各自 pid / 退出码。`>1` 个实例就是端口漂移的信号 |
|
|
261
|
+
| `ide_stop_run_configuration` | 停掉该配置的**全部**实例并等它们退出;没在跑也返回成功(幂等) |
|
|
262
|
+
| `ide_rerun_run_configuration` | 等同 IDE 的 **Rerun** 按钮:在跑就重启、没在跑就启动,读 `started` 判断是否真起来了 |
|
|
182
263
|
|
|
183
264
|
opencode-idea 对这一组工具做三件事:
|
|
184
265
|
|
|
185
|
-
1. **透传**:IDE MCP server 以 `codemode: false` 注册,工具目录整体转发,所以这四个工具自动以 `
|
|
266
|
+
1. **透传**:IDE MCP server 以 `codemode: false` 注册,工具目录整体转发,所以这四个工具自动以 `ide_*` 出现在模型的
|
|
186
267
|
工具表里 —— 插件侧不需要单独声明(也因此**装不装这个 IDEA 插件,插件侧的代码都不用改**);
|
|
187
268
|
2. **条件引导**:只有这次请求的工具快照里真的有它们,才在「运行配置(配套插件 … 提供,装了才有)」**自己那一节**里逐个点名 ——
|
|
188
269
|
和 IDE 自带的 `### 运行配置` 分开:两个来源,两节,读者要能分清"IDE 给我的"和"我额外装的"。没装插件时**整节连同标题一起消失**。
|
|
189
270
|
两个地方会跟着变:
|
|
190
|
-
- 「运行配置」段写明**改完代码要重启无热重载的进程就用 `
|
|
271
|
+
- 「运行配置」段写明**改完代码要重启无热重载的进程就用 `ide_rerun_run_configuration`,不要用 `pkill` / `kill` / shell**
|
|
191
272
|
—— 这正是它要解决的问题:外部杀掉的进程 IDE 并不知道,Run 窗口仍显示运行中,下次启动就会撞端口;
|
|
192
|
-
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
273
|
+
- 「运行配置」段的**新建那条**把 run configuration 定性成**项目资产**:一个项目通常只建几个(固定要跑的构建 / 装依赖 / dev server / 迁移),
|
|
274
|
+
**不是随手一条命令就建一个**;判据是**这件事以后会不会以同样形态再发生** —— 会就该建、模型必须**主动**向用户提议(摊开配置名 /
|
|
275
|
+
实际命令 / 工作目录 / 理由),用户同意才动手;不会就裸 `shell` 跑完算(那条里写明了这层区分:`shell` 就地执行不留痕、
|
|
276
|
+
建配置是落盘成 `.run/*.run.xml` 供反复用)。判据只写在这一处,**「命令执行」段不重复**,只留
|
|
277
|
+
「配置一律不由你写」这条无条件的,以及"该建的用哪条路建"那一条按工具是否存在分流:有工具时指向上面那条、
|
|
278
|
+
并说明非 Shell 类型与删 / 改交给用户调 `idea-run-config-manager` skill;
|
|
279
|
+
没有工具时换成「讲清楚配置名 / 命令 / 工作目录 / 理由,请用户在 IDE 里自己建」—— 那时**连那个 skill 也不会出现**
|
|
280
|
+
(它的门就是这个工具),所以引导里顺手把这一点说明了,免得以后有人把它当成漏写而"补"上一句调不到的指令。**没装插件时绝不会提到那个工具。**
|
|
196
281
|
3. **工具名清单**写在 `src/mcp/enhance.js`(与原生 IDE 的 `src/mcp/idea.js` 分开放:原生走原生,插件的走插件的),
|
|
197
282
|
与该仓库的 `RunLifecycleSchemas.kt` 保持同步。工具按**存在的子集**逐个点名(而不是「有就全写」),这样旧版本的配套
|
|
198
|
-
|
|
283
|
+
插件少给一两个工具时,引导也不会提到它们。同理,**每条命令名只列真的提供它的项目**(逐项目核对,见「条件注入」)——
|
|
284
|
+
一个项目装了配套插件、另一个没装是可能的。
|
|
199
285
|
|
|
200
286
|
> 没装 `idea-mcp-enhance` 的 IDE 一切照旧:工具不存在,引导也不提,模型继续按原来的方式工作。
|
|
201
287
|
|
|
202
|
-
## Run Configuration
|
|
288
|
+
## Run Configuration:增删改的入口只有一个 skill
|
|
203
289
|
|
|
204
290
|
内置 MCP 只能 **查**(`get_run_configurations`)和 **执行**(`execute_run_configuration`)run configuration;新建靠配套插件的
|
|
205
|
-
`
|
|
291
|
+
`ide_create_shell_run_configuration`(只有 Shell 类型,见上面的「Run Configuration 全套」);**修改和删除永远没有工具**。
|
|
206
292
|
|
|
207
293
|
所以插件的立场是:
|
|
208
294
|
|
|
209
|
-
-
|
|
210
|
-
-
|
|
211
|
-
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
295
|
+
- **配置由 AI 动手,但只在一个地方、按模板动手** —— `.run/*.run.xml` 只有 `idea-run-config-manager` skill 会写,而且照
|
|
296
|
+
`skills/idea-run-config-manager/assets/types/` 里那个类型的模板写;**平时**(引导文本里)仍然禁止随手手写配置、或用一条裸命令代替配置;
|
|
297
|
+
- **Shell 类型**且装了配套插件 → 新建用 `ide_create_shell_run_configuration`(新建是项目资产:**会重复发生的流程才建**,且**必须先征得用户同意**);
|
|
298
|
+
- **有类型模板的其它类型**(Maven / Gradle / npm / Python / Go Build / Node.js)→ 直接写 `.run/<名字>.run.xml`;
|
|
299
|
+
**改和删**对所有类型都是直接编辑 / 删掉那个文件;
|
|
300
|
+
- **没有模板的类型**(Application、JAR 以及 JUnit / Docker / Spring Boot / Flyway …)→ **交给用户在 IDE 里配**,skill 只负责把档案补上;
|
|
301
|
+
- 无论哪条路,**写完都要用 `get_run_configurations` 复查** —— `type` 写错 IDE 会静默忽略整个文件,这是唯一的判据;
|
|
302
|
+
- 这些事**不再散着说"让用户自己去 IDE 里搞"**,而是统一指向那个 skill:**让用户调它**(`@idea-run-config-manager`)—— 它是本项目 run
|
|
303
|
+
configuration 增 / 删 / 改的唯一流程入口,**只能由用户触发**(理由见下面的「而且只能用户调」);
|
|
304
|
+
- **没装配套插件** → 那个 skill 也不存在(它的门就是 create 工具),此时才直接请用户自己在 IDE 里建。
|
|
305
|
+
|
|
306
|
+
> **曾经有一个 `idea-run-config` skill 教模型凭记忆手写 `.run/*.run.xml`,已经删掉。** 理由不是"不许写",而是**不许凭空写**:`type` 写错 IDE 会
|
|
307
|
+
> **静默忽略整个文件、日志里也不报**,凭记忆猜 option 名就是这么错的。现在这件事由 `idea-run-config-manager` 接手 —— 但**每个类型都得有一份实测模板**
|
|
308
|
+
> (`assets/types/`,字段名全部来自真实文件),没模板的类型宁可交给用户。
|
|
216
309
|
|
|
217
310
|
**skill 的生命周期跟随两道门,缺一不可**:
|
|
218
311
|
|
|
219
|
-
1.
|
|
220
|
-
|
|
221
|
-
2. **IDE 真的在提供这个 skill 依赖的工具** —— skill 在自己的 frontmatter 里用 `requires:`
|
|
222
|
-
`idea-standalone` 声明 `
|
|
312
|
+
1. **项目配置** —— `/open-in-ide` 写入配置时注册、`/delete-in-ide` 删配置时注销;以前配置过的 root 在 `setup` 时(读回配置)
|
|
313
|
+
也会走这一步。未配置的 root 不受影响。
|
|
314
|
+
2. **IDE 真的在提供这个 skill 依赖的工具** —— skill 在自己的 frontmatter 里用 `requires:` 声明它绕着哪个工具写,而且写的是**后缀**
|
|
315
|
+
(例如 `idea-standalone` 声明 `rerun_run_configuration`、`idea-run-config-manager` 声明 `create_shell_run_configuration`,真实工具名是
|
|
316
|
+
`<项目前缀>rerun_run_configuration` / `<项目前缀>create_shell_run_configuration`)。**没这个工具就不注册这个 skill**:
|
|
223
317
|
一个教模型去调"它根本看不到的工具"的 skill,不是知识,是一次注定的失败调用。工具的可见性是双向跟随的 —— `setup` 时还没
|
|
224
|
-
连过 IDE、目录未知,所以那时**不注册**;等 IDE 应答(`/open-in-
|
|
318
|
+
连过 IDE、目录未知,所以那时**不注册**;等 IDE 应答(`/open-in-ide` 或重连)后目录才算已知,该出现的才出现;反过来,某个
|
|
225
319
|
请求里工具没了,skill 也跟着撤(不需要等重连)。
|
|
226
|
-
`requires` 必须写 **OpenCode 侧的名字**(IDE 工具带 `
|
|
320
|
+
`requires` 必须写 **OpenCode 侧的名字**(IDE 工具带 `ide_` 服务器前缀),因为门就是拿它跟 `ctx.tool.list()` 比;
|
|
227
321
|
写成 IDE 的原始名(`rerun_run_configuration`)会让这个 skill 在任何机器上都不出现,而且没有任何报错。
|
|
228
322
|
|
|
229
323
|
文档放在 `skills/<id>/SKILL.md`(每个 skill 一个目录,`name` / `description` / `requires` 走 YAML frontmatter,`requires` 由
|
|
230
324
|
loader 消费、**不会进入注册给 OpenCode 的定义**),由 `src/skill/loader.js` 扫描加载 —— **加新 skill 只需加一个目录,不用改代码**。
|
|
231
325
|
|
|
326
|
+
还可以用 OpenCode 官方的 frontmatter 写法**关掉模型主动调用**:
|
|
327
|
+
|
|
328
|
+
```yaml
|
|
329
|
+
metadata:
|
|
330
|
+
opencode/autoinvoke: false
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
意思是这个 skill 仍会注册、仍能按 ID 加载,但**不进模型的可选列表** —— 只能由用户显式指定(`@<skill-id>`)触发。
|
|
334
|
+
loader 读的是 OpenCode 文档里的那个嵌套写法(它自己的读取器是扁平的,缩进行落地成 `opencode/autoinvoke` 这个带命名空间的键,
|
|
335
|
+
`metadata:` 那行则为空 —— **这一层嵌套是刻意支持的**),再翻译成注册定义的 `autoinvoke`(注册 API 用的名字);
|
|
336
|
+
值只接受 `true` / `false`,写错直接报错 —— 一个拼错的开关若被静默忽略,技能就仍然会被模型自动调用,那正是这个开关要防的事。
|
|
337
|
+
|
|
232
338
|
## Standalone 模式纪律 (skill)
|
|
233
339
|
|
|
234
340
|
本机直跑应用的**项目级纪律**由 `idea-standalone` skill 固化:它把这份纪律写进**项目根 `AGENTS.md`** 里由
|
|
@@ -238,38 +344,136 @@ loader 消费、**不会进入注册给 OpenCode 的定义**),由 `src/skill/loa
|
|
|
238
344
|
|
|
239
345
|
1. **什么是 standalone 模式**:**standalone = 启动收口只有 IDEA run configuration**(每个应用的启动入口是 run configuration,不是手搓命令行;
|
|
240
346
|
至于配置内部怎么起 —— 本机进程 / 容器 / 部署到远端 —— 由它自己决定,本段不预设),只启动其中一部分是常态;
|
|
241
|
-
**跑应用只用 `
|
|
347
|
+
**跑应用只用 `ide_rerun_run_configuration`**(在跑就重启、没在跑就启动)
|
|
242
348
|
—— 不必分辨启动还是重启,直接 rerun 就完事,常驻进程化 / 服务化的配置一律走这条;
|
|
243
|
-
**`
|
|
349
|
+
**`ide_execute_run_configuration` 不用于这里**(它是给命令 / Job 类型的配置跑的,对常驻进程只会起重复实例);也不绕开 IDEA 用
|
|
244
350
|
`go run` / `pnpm dev` 这类裸命令或 `kill` / `pkill`;**重启不必先问** —— 改完代码要重启就直接 rerun,这条链是无人化的;
|
|
245
|
-
2. **启动哪些应用**:一行一个应用,启动路径**只能是 IDEA run configuration**(配置名必须能在 `
|
|
246
|
-
|
|
351
|
+
2. **启动哪些应用**:一行一个应用,启动路径**只能是 IDEA run configuration**(配置名必须能在 `ide_get_run_configurations`
|
|
352
|
+
里查到;**缺配置就交给用户** —— 让他调 `idea-run-config-manager` skill 去建),端口与被依赖的先后顺序一并写明;
|
|
247
353
|
3. **热重载矩阵**:逐应用标"是 / 否" —— 带 HMR 的 dev server 改动后**不用**提示重启;`go run .` 这类无热重载的进程改动后
|
|
248
354
|
**必须**显式点名「需要重启 <应用>」,不得在未提示的情况下宣称"改完可验证";
|
|
249
355
|
4. **项目补充条款**:文件写入位置、测试纪律、访问归属、dev 模式特有限制等,按用户给的条款逐条续写、保留原意。
|
|
250
356
|
|
|
251
|
-
事实一律先查后写:配置名来自 `
|
|
357
|
+
事实一律先查后写:配置名来自 `ide_get_run_configurations`,热重载列来自运行方式,端口读不到就问用户 —— 不猜。
|
|
252
358
|
**只动自己的标记块**:根 `AGENTS.md` 是共享文件(`project-scaffold` 的宪法、项目自己的内容都在里面),标记之外一字不改。
|
|
253
359
|
|
|
360
|
+
## run configuration 增删改 + 档案 (skill)
|
|
361
|
+
|
|
362
|
+
`idea-run-config-manager` skill 做三件事:
|
|
363
|
+
|
|
364
|
+
1. **建 / 改 / 删**(直接动手):Shell 类型走 `ide_create_shell_run_configuration`,其余类型直接写 / 改 / 删 `.run/<名字>.run.xml`,
|
|
365
|
+
**每种类型照自己的模板写**,写完用 `get_run_configurations` 复查;
|
|
366
|
+
2. **建档**:过滤之后剩下的每个 run configuration 在**项目根 `AGENTS.md`** 的标记块(`<!-- idea-run-config-manager:begin -->` /
|
|
367
|
+
`<!-- idea-run-config-manager:end -->`)里占一行 —— `项目 | run configuration | 怎么跑 | 何时跑 | 跑前做 | 说明`,
|
|
368
|
+
**按操作系统分成两张表**(macOS / Linux、Windows,与 `idea-standalone` 的两张应用表同一种拆法:同一条流程在两个平台上常常不是同一条命令);
|
|
369
|
+
**与 `idea-standalone` 块的表共享同一套公共列并同序同宽**(谁 / `run configuration` / `怎么跑` / `何时跑` / `跑前做` / `说明`),
|
|
370
|
+
但**各自特有的列留在自己的语义位置**:standalone 的应用表多一格 `端口`(服务化应用一定有),固定流程表没有;
|
|
371
|
+
列宽按同一约定(中文两字 = 四个 dash),所以**不需要补空格**,`edit` 之类的工具重写文件也不会破坏对齐;
|
|
372
|
+
**热重载矩阵只有 3 列,不参与这套对齐** —— 它答的是"改动后要不要重启";
|
|
373
|
+
**目录 / 端口 / 干什么都不单开一格**(standalone 的端口除外):前两个配置里本来就有,抄进表只会过时,第三个与 `说明` 重复;
|
|
374
|
+
3. **过滤**:服务化(长驻应用)的配置归 `idea-standalone` 的块,这里先读那个块把它排除,**两个块永不重叠**。
|
|
375
|
+
|
|
376
|
+
**SKILL.md 只有一份五步流程**(读 → 枚举 → 建 / 删 / 改 → 同步 → 核对),外加**支持矩阵**与**硬性契约**(落地位置、固定信封、复查、
|
|
377
|
+
路径宏、不要写模板外的字段)——**它自己就带着规矩**;两类内容另放在两个地方,各管一段:
|
|
378
|
+
|
|
379
|
+
| 模板 | 装什么 |
|
|
380
|
+
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
381
|
+
| `skills/idea-run-config-manager/assets/types/<类型>.md` | **一个类型一份**:那个类型的实测样本 + 字段表 + 坑(索引就是 SKILL.md 里的**支持矩阵**) |
|
|
382
|
+
| `skills/idea-run-config-manager/assets/AGENTS.template.md` | 产物(档案)的骨架:表格列、每一列写什么、枚举与过滤的要求,都在它的生成提示里 |
|
|
383
|
+
|
|
384
|
+
**支持矩阵(7 份已落、2 份待实物)**:
|
|
385
|
+
|
|
386
|
+
| 类型 | `type` id | 验证 |
|
|
387
|
+
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
388
|
+
| Shell Script | `ShConfigurationType` | ✅ 本机 6 例(含 Windows) |
|
|
389
|
+
| Maven / Gradle / npm / Python / Go Build | `MavenRunConfiguration` / `GradleRunConfiguration` / `js.build_tools.npm` / `PythonConfigurationType` / `GoApplicationRunConfiguration` | ✅ 实物 |
|
|
390
|
+
| Node.js | `NodeJSConfigurationType` | ⚠️ 三个属性已验证,其余字段未验证 |
|
|
391
|
+
| Application / JAR | `Application` / `JarApplication` | ⏳ type 已验证,**字段层无实物 → 暂不写模板,交给用户** |
|
|
392
|
+
|
|
393
|
+
矩阵之外(JUnit / TestNG / Kotlin / Docker / Spring Boot / Tomcat / Flyway / Liquibase / HTTP Request …)一律**没有模板** → 交给用户在 IDE 里配。
|
|
394
|
+
|
|
395
|
+
**给某个类型补模板的流程**:在 IDE 里建一个最简配置 → 勾 Store as project file → 读生成的 `.run/*.run.xml` 照抄结构 → 标清哪些字段实测 →
|
|
396
|
+
把矩阵里那个类型从 ⏳ 改成 ✅。**每个字段名都来自真实文件,不靠猜** —— `js.build_tools.npm`(属性 + 自定义元素)、`ShConfigurationType`
|
|
397
|
+
(`<option>` 子元素)、`NodeJSConfigurationType`(全属性)三种写法并存,套错就是静默失效。
|
|
398
|
+
|
|
399
|
+
**先过滤,再建档**:**服务化的配置不进这张表** —— 它们已经登记在 `AGENTS.md` 的 `idea-standalone` 块里(端口 / 热重载也写在那里),
|
|
400
|
+
所以建档第一步是读那个块、把它的表里出现过的名字记下来并排除,**剩下的**才是本表内容。
|
|
401
|
+
|
|
402
|
+
这张表**以带前缀的工具为准**,不围绕 IDE 界面说话:各项目各有自己的前缀(root 是 `ide`,子项目是它的目录名),枚举与执行都用**它自己那个前缀**的
|
|
403
|
+
`<前缀>_get_run_configurations` / `<前缀>_execute_run_configuration` …;`项目` 列写的就是这个前缀,一条配置属于谁、该用哪套工具跑由它决定。
|
|
404
|
+
|
|
405
|
+
这张表的用途是**能被下次读到**:要办同类事情时先查它,有现成的就用,不再重复建 —— 所以**联动是硬要求**:配置被**新建 / 删除 / 修改**
|
|
406
|
+
(无论谁做的:工具建的、用户自己建的、用户删掉的)都要在文档里同步**加行 / 删行 / 改行**,否则表就开始骗人。
|
|
407
|
+
|
|
408
|
+
**别的文档都指向这里**:引导文本与 `idea-standalone` skill 碰到"要建 / 删 / 改一个配置",不再让用户自己去 IDE 里摸,而是让用户调本 skill ——
|
|
409
|
+
增 / 删 / 改的流程入口只有这一个,而它只由用户触发。
|
|
410
|
+
|
|
411
|
+
**它比 `idea-standalone` 多一道门**:frontmatter 里 `requires: create_shell_run_configuration` —— 它绕着"新建配置"这件事写,而新建只有
|
|
412
|
+
配套插件 `idea-mcp-enhance` 能做,所以**没装插件的 IDE 看不到它**(`idea-standalone` 只要 `rerun_run_configuration`,门更松)。这是刻意的:
|
|
413
|
+
一个只教模型"去建配置"、却没给建配置工具的 skill,只会把用户拖进一次注定失败的调用。
|
|
414
|
+
|
|
415
|
+
**而且只能用户调**:它的 frontmatter 带 `metadata: opencode/autoinvoke: false`,loader 翻成定义的 `autoinvoke: false` ——
|
|
416
|
+
skill 照常注册,但**不进模型的可选列表**,模型不会自己挑上它,只有用户显式指定(`@idea-run-config-manager`)才会加载。
|
|
417
|
+
理由是它**直接动手改项目文件与项目资产**:`.run/*.run.xml` 与 `AGENTS.md` 都由用户自己按这个 skill 的流程来改,模型不主动挑上它。
|
|
418
|
+
「该不该建」的时机判断仍在引导文本的判据里(那是模型该管的事),**动手权**留给人。
|
|
419
|
+
|
|
420
|
+
## Deployment 全套 (配套插件 `idea-mcp-enhance`)
|
|
421
|
+
|
|
422
|
+
IDE 内置的 MCP Server **完全不碰部署** —— 既不报 IDE 里配了哪些 Deployment 服务器,也不能把文件传上去 / 拉下来。
|
|
423
|
+
配套插件 [`idea-mcp-enhance`](https://github.com/syllr/idea-mcp-enhance)(IDEA 2026.2+,另装)补齐这四个:
|
|
424
|
+
|
|
425
|
+
| 工具 (OpenCode 里叫 `ide_*`) | 作用 |
|
|
426
|
+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
427
|
+
| `ide_list_deployment_servers` | 本项目可用的服务器(名称 / 项目级还是应用级 / 协议 / host / port / **本项目里的路径映射**),以及**项目级**的部署选项与危险组合告警。**只读 IDE 配置,不联网** |
|
|
428
|
+
| `ide_upload_to_deployment` | 把映射到的**本地目录**传到服务器(等同 IDE 的 Upload to …)。`mode` 默认 `mirror` —— **会删掉服务器上多出来的文件**;`upload` 则保留远端多余文件。**破坏性** |
|
|
429
|
+
| `ide_download_from_deployment` | 把服务器上映射目录的内容拉回本地(等同 IDE 的 Download from …),**以服务器为准**:两边都有的文件被远端覆盖(相同则不写)。**没有"保留我的版本"这个选项** |
|
|
430
|
+
| `ide_get_deployment_task_status` | 用 `handle` 查一次传输的状态与计数;**永不启动任何传输** |
|
|
431
|
+
|
|
432
|
+
opencode-idea 对它做三件事,和上面那组是同一套:
|
|
433
|
+
|
|
434
|
+
1. **透传** —— 工具目录整体转发(见「按能力选工具」),所以四个工具自动以 `ide_*` 出现在模型的工具表里;
|
|
435
|
+
2. **条件引导** —— 只有这次请求的工具快照里真的有它们,才出现「服务器文件同步」这一节。**这一节整节(含标题)都由配套插件提供**,
|
|
436
|
+
所以一个工具都没有时它**完全消失** —— 不能像「运行配置」那样留一个空标题(那一节还有内置的 `get_run_configurations` /
|
|
437
|
+
`execute_run_configuration` 撑着)。整节**锚在一个工具上**(模板里 `{{#if canListDeploymentServers}}` 直接包住标题):
|
|
438
|
+
这四个由同一道前提注册、同进同出,拿其中一个当判据就够,不需要再造一个"四个里任一个"的聚合标志。触发条件也因此比
|
|
439
|
+
上面那组更严:部署工具**还要求 `com.jetbrains.plugins.webDeployment`**,而它只在 **Ultimate** 里存在,
|
|
440
|
+
所以 Community IDE 上这一节永远不出现;
|
|
441
|
+
3. **工具名清单**写在 `src/mcp/enhance.js`(`DEPLOYMENT_SUFFIXES` + `deploymentCapabilities`),与该仓库的
|
|
442
|
+
`DeploymentSchemas.kt` 保持同步。**四个工具逐个点名**(而不是"有就全写"),而且每条命令名只列**真的提供它**的项目
|
|
443
|
+
(见「条件注入」的逐项目核对):它们通常同进同出(同一道插件前提),但"通常"不是"总是" —— 点名一个模型调不到的工具
|
|
444
|
+
就是一次注定失败的调用。
|
|
445
|
+
|
|
446
|
+
这节存在的理由是**一条路由规则**:往服务器传 / 取文件要走这些工具,**不要自己拼 `ssh` / `rsync` / `scp`** ——
|
|
447
|
+
IDE 的连接、路径映射、排除规则都在它后面,自己拼的那份与 IDE 看到、管理的不是同一份。文案里同时点明两件容易读错的事:
|
|
448
|
+
`mirror` 是**默认值**且**会删远端文件**(而 MCP 路径上没有确认步骤),下载**以远端为准**、没有"保留我的版本"。
|
|
449
|
+
|
|
450
|
+
还有一个语义必须写明,否则模型会把正常的中间态当失败去重试:上传 / 下载都在 IDE 后台跑,单次调用只等到 `waitMs`
|
|
451
|
+
(默认 10 秒)为止,返回 `state: "in_progress"` 是**正常**的 —— 拿 `handle` 调 `get_deployment_task_status` 接着看,
|
|
452
|
+
**不要用重复调上传 / 下载来代替**(那样拿不到进度)。
|
|
453
|
+
|
|
454
|
+
> **这一组没有 skill,和 run configuration 不同。** run configuration 要 skill 是因为"某种类型怎么写"是一批得逐类型实测的
|
|
455
|
+
> 模板(`assets/types/`);部署没有这层知识 —— 四个工具的 schema 已经说清 `serverName` / `mode` 怎么填,而"该不该传、传给谁"
|
|
456
|
+
> 是模型当场看 `list_deployment_servers` 的判断。再加一个 skill 只是把同一段话抄第二遍。
|
|
457
|
+
|
|
254
458
|
## 项目命令执行 (Run Configuration)
|
|
255
459
|
|
|
256
|
-
需要**项目环境**的命令(依赖用户在 IDE 里配好的 JDK / Node / Python 版本等),模型使用 **`
|
|
460
|
+
需要**项目环境**的命令(依赖用户在 IDE 里配好的 JDK / Node / Python 版本等),模型使用 **`ide_execute_run_configuration`**
|
|
257
461
|
执行 —— 走 run configuration,不用原生 shell。
|
|
258
462
|
|
|
259
463
|
- 判据是:这条命令**依赖项目的运行时版本**。是 → run configuration;不是(看文件、git、临时脚本)→ 原生 shell。
|
|
260
464
|
- run configuration 会继承开发时具体配的那套运行时,或者干脆是你那个应用配好的运行时,所以这就是个应用。
|
|
261
465
|
- 配置必须**先在 IDEA 里存在**(项目级 `.run/*.run.xml`,**由用户建**)。没有就请用户建一个,再跑;
|
|
262
466
|
|
|
263
|
-
> 为什么不再用 IDE 终端:`
|
|
467
|
+
> 为什么不再用 IDE 终端:`ide_execute_terminal_command` 之前被当成"自动继承 IDE 项目环境"的通道而保留暴露,但实测
|
|
264
468
|
> **它拿不到项目配好的 JDK / Node / Python 版本**,和原生 shell 没有区别。既然没有优势,就把它从模型可见的工具表里
|
|
265
|
-
> 隐藏掉(`
|
|
469
|
+
> 隐藏掉(`HIDDEN_IDE_TOOL_SUFFIXES`),命令执行的路由改由 run configuration 承担。
|
|
266
470
|
|
|
267
471
|
引导文本由 `src/ide-guidance.js` 注入(`### 命令执行` 段),只在 IDE MCP 可用时生效。
|
|
268
472
|
|
|
269
473
|
## 前置条件
|
|
270
474
|
|
|
271
475
|
- JetBrains IDE 已开启 MCP 服务 (IDE 设置里的 MCP Server / AI Assistant MCP),版本需 **2026.2+**(提供 Streamable HTTP 端点
|
|
272
|
-
`/stream`);若关闭,`/open-in-
|
|
476
|
+
`/stream`);若关闭,`/open-in-ide` 会立即提示如何重新开启。
|
|
273
477
|
- IDE 侧需开启 **Brave Mode**(否则需要确认的 MCP 工具调用会停下来等用户确认);MCP 未就绪时通知会同时提醒开启它。
|
|
274
478
|
- 插件注册给 OpenCode 的 MCP 配置(**只支持 Streamable HTTP**):
|
|
275
479
|
|
|
@@ -289,9 +493,11 @@ loader 消费、**不会进入注册给 OpenCode 的定义**),由 `src/skill/loa
|
|
|
289
493
|
> HTTP 至少把"端点没了"变成一次普通的调用错误,插件能分类并自愈。OpenCode 2.0.19+ 也已无 SSE 客户端传输,当初选 stdio 的理由不再成立。
|
|
290
494
|
>
|
|
291
495
|
> **为什么不用 `/sse`**:OpenCode V2 的远程 MCP 客户端**只支持 Streamable HTTP**,没有旧版 SSE 传输。IDE 的 `/sse` 是旧版
|
|
292
|
-
> SSE (POST 返回 405),V2 连不上。插件对 IDE
|
|
496
|
+
> SSE (POST 返回 405),V2 连不上。插件对 IDE 的**探测**也走 `/stream`(一次项目作用域的 `get_project_modules` 调用),
|
|
497
|
+
> 用来确认"这个 IDE 里打开着这个项目"。
|
|
293
498
|
|
|
294
|
-
|
|
499
|
+
**端口是产品常量,不开放配置**:IDEA 的 MCP 在 **64342**,PyCharm 在 **64462**(见 `src/ide-projects.js` 的 `IDE_PORTS`)。
|
|
500
|
+
"哪个 IDE 在哪个端口"跨版本不变,所以插件不需要扫描候选端口 —— 探哪个端口,由项目的 IDE 唯一决定,用户不需要填任何东西。
|
|
295
501
|
|
|
296
502
|
## 安装
|
|
297
503
|
|
|
@@ -331,7 +537,7 @@ opencode plugin list
|
|
|
331
537
|
```
|
|
332
538
|
|
|
333
539
|
配置保存后 V2 会监听并自动重载 (日志里能看到它开始 watch `index.js` / `src/*.js`),无需重启。改插件源码也会触发重载 (此时需重跑
|
|
334
|
-
`/open-in-
|
|
540
|
+
`/open-in-ide`)。
|
|
335
541
|
|
|
336
542
|
另一种零配置方式:在 `~/.config/opencode/plugins/` 放一个转发文件 (自动发现,但不能传 options):
|
|
337
543
|
|
|
@@ -350,13 +556,12 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
|
|
|
350
556
|
{
|
|
351
557
|
"package": "opencode-idea",
|
|
352
558
|
"options": {
|
|
353
|
-
"
|
|
354
|
-
"
|
|
355
|
-
"
|
|
356
|
-
"launchCooldownMs": 120000, // 启动保护冷却
|
|
559
|
+
"injectGuidance": true, // IDE 可用时注入逐项目的「优先使用 IDE 工具」引导
|
|
560
|
+
"openInIde": true, // 是否允许自动拉起 IDE;false 只连已运行的端点
|
|
561
|
+
"launchCooldownMs": 120000, // 启动保护冷却(按项目各自计)
|
|
357
562
|
"launchMaxAttempts": 5,
|
|
358
|
-
"mcpProbeTimeoutMs": 1000, //
|
|
359
|
-
"executionTimeoutMs": 600000, // 单次
|
|
563
|
+
"mcpProbeTimeoutMs": 1000, // 单次「这个 IDE 里打开着这个项目吗」探测的超时
|
|
564
|
+
"executionTimeoutMs": 600000, // 单次 IDE 工具调用硬上限;默认 10 分钟(OpenCode 默认 12 小时)
|
|
360
565
|
"feedback": "message", // "message"(默认,会话通知,AI 只回"收到")| false(静默)
|
|
361
566
|
},
|
|
362
567
|
},
|
|
@@ -366,46 +571,46 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
|
|
|
366
571
|
|
|
367
572
|
不传 options 时全部使用下表默认值。
|
|
368
573
|
|
|
369
|
-
| 选项 | 类型 | 默认 | 说明
|
|
370
|
-
| -------------------- | -------------------- | ----------- |
|
|
371
|
-
| `
|
|
372
|
-
| `
|
|
373
|
-
| `
|
|
374
|
-
| `
|
|
375
|
-
| `
|
|
376
|
-
| `
|
|
377
|
-
| `
|
|
378
|
-
| `feedback` | `"message" \| false` | `"message"` | 结果反馈:`message` 会话通知(用户可见,AI 只回"收到");`false` 静默 |
|
|
574
|
+
| 选项 | 类型 | 默认 | 说明 |
|
|
575
|
+
| -------------------- | -------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
|
|
576
|
+
| `injectGuidance` | `boolean` | `true` | IDE 可用时是否注入逐项目的「优先使用 IDE 工具」引导 |
|
|
577
|
+
| `openInIde` | `boolean` | `true` | 是否允许自动拉起 IDE;`false` 时仍会连接**已经运行**的端点。**用哪个 IDE 由每个项目的配置决定** |
|
|
578
|
+
| `launchCooldownMs` | `number` | `120000` | 启动保护冷却:冷却期内不重复 spawn(每个项目各算各的) |
|
|
579
|
+
| `launchMaxAttempts` | `number` | `5` | 单次会话内最多 spawn 次数,超出后停止重试(每个项目各算各的) |
|
|
580
|
+
| `mcpProbeTimeoutMs` | `number` | `1000` | 单个 MCP 端口的短探测超时 |
|
|
581
|
+
| `executionTimeoutMs` | `number` | `600000` | 单次 IDE 工具调用的硬上限(毫秒);防止端点卡住后无限等待(OpenCode 默认 12 小时) |
|
|
582
|
+
| `feedback` | `"message" \| false` | `"message"` | 结果反馈:`message` 会话通知(用户可见,AI 只回"收到");`false` 静默 |
|
|
379
583
|
|
|
380
584
|
## 行为
|
|
381
585
|
|
|
382
|
-
-
|
|
383
|
-
|
|
384
|
-
-
|
|
385
|
-
- **手动接入 + 就绪即返回**:`/open-in-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
- **`context` 钩子是请求的纯函数**:按「每次模型调用」触发 (含工具续跑),只看本次请求自带的工具快照 ——
|
|
389
|
-
|
|
586
|
+
- **已配置的 root**:启动读回配置后挂上 shell 环境钩子 (环境值待接入后填充)、按 IDE 实际提供的工具同步 skill
|
|
587
|
+
(IDE 还没应答时依赖配套工具的 skill 不注册);全部 IDE MCP 由 `/open-in-ide` 注册。
|
|
588
|
+
- **未配置的 root**:不改环境、不注册、不注入任何 IDE 提示 (每请求零开销;setup 时只做一次配置读取)。
|
|
589
|
+
- **手动接入 + 就绪即返回**:`/open-in-ide` 会按**每个项目自己的 IDE** 分别 `open -a` 拉起并**等 IDE MCP 就绪**(冷启动数十秒,
|
|
590
|
+
上限 60s);就绪后 **先注销全部旧注册 → 再按项目各注册一个 server**(远程 Streamable HTTP),等 IDE 工具就绪,最后才通知。
|
|
591
|
+
**每次执行都重建**。命令返回即可用;`/delete-in-ide` 注销全部注册 + 删配置 + 清环境。
|
|
592
|
+
- **`context` 钩子是请求的纯函数**:按「每次模型调用」触发 (含工具续跑),只看本次请求自带的工具快照 —— 有任一项目前缀的工具就
|
|
593
|
+
**按每个前缀**剥离隐藏工具并注入**逐项目**引导;没有则只在已配置时给恢复提示。该钩子本身**不做任何 I/O**(只看内存缓存)。
|
|
390
594
|
- **请求驱动的恢复(没有后台轮询)**:
|
|
391
|
-
- **`prompt`
|
|
392
|
-
await `prompt` 才构建请求,所以**触发它的那条消息本身**就带上了
|
|
595
|
+
- **`prompt` 钩子**:「已配置 + 本实例没有任何 MCP 注册」时**探测端口并重新注册**(只探测、绝不 `open -a`)。OpenCode 会
|
|
596
|
+
await `prompt` 才构建请求,所以**触发它的那条消息本身**就带上了 IDE 工具,没有空窗。这正是 Location 被空闲驱逐
|
|
393
597
|
(60 分钟 `idleTimeToLive`)或 OpenCode 重启后,新实例自动接回连接的路径。
|
|
394
|
-
- **`context` 钩子**:发现「本会话见过
|
|
395
|
-
|
|
396
|
-
`No tool named ... available`)。
|
|
598
|
+
- **`context` 钩子**:发现「本会话见过 IDE 工具、本请求却没有」→ 立刻锁存并在后台重建(不等下一条消息)。工具缺失时注入的
|
|
599
|
+
恢复引导会**明确禁止**调用任何 IDE 工具(此前复用"重试一次"的文案,反而诱导模型去调一个不在工具表里的工具,
|
|
600
|
+
得到 `No tool named ... available`)。
|
|
397
601
|
- **`execute.after` 钩子**:见下一条。
|
|
398
602
|
恢复是**每个 Location(项目)各一份**;没有任何定时器,插件在不使用时完全静止。
|
|
399
|
-
- **失败触发的自动接入(
|
|
400
|
-
- IDE MCP 不可用(掉了)→ 重跑 `/open-in-
|
|
401
|
-
- IDE 在、但项目没打开(`Unable to determine the target project` / `doesn't correspond to any open project`)→
|
|
402
|
-
|
|
603
|
+
- **失败触发的自动接入(仅已配置的 root)**:`tool.execute.after` 钩子监听 IDE 工具报错并**分类**:
|
|
604
|
+
- IDE MCP 不可用(掉了)→ 重跑 `/open-in-ide` 的接入流程;
|
|
605
|
+
- IDE 在、但项目没打开(`Unable to determine the target project` / `doesn't correspond to any open project`)→ 让**这个工具
|
|
606
|
+
所属项目**的 IDE 重新打开它(**不会**去动别的项目);
|
|
607
|
+
- 普通业务错误(`File not found` 等)→ **不动作**。判定只认**传输层专有标记**(`MCP server "<名>" is not available` /
|
|
403
608
|
`MCP server is not connected` / `Error POSTing to endpoint`),**不认**工具输出里出现的通用串
|
|
404
609
|
(例如 SQL 工具报的 `Connection refused`) —— MCP 工具错误的 message 就是工具自己的输出,认通用串会把正常业务失败误判成掉线并重建。
|
|
405
|
-
触发成功会把该工具错误改写为"已重连 / 已重新打开,请重试",模型在同一回合内重试;失败则保持原错误。非
|
|
406
|
-
|
|
407
|
-
- **`/open-in-
|
|
408
|
-
|
|
610
|
+
触发成功会把该工具错误改写为"已重连 / 已重新打开,请重试",模型在同一回合内重试;失败则保持原错误。非 IDE 工具、未配置
|
|
611
|
+
的 root 都不受影响。启动保护 (`launchCooldownMs` / `launchMaxAttempts`) 限制重复拉起 IDE,**按项目各自计**。
|
|
612
|
+
- **`/open-in-ide`**:手动接入 root 与全部子项目;**等每个项目的 IDE 就绪 → 先注销全部旧注册 → 再按项目各注册一个 server →
|
|
613
|
+
等 IDE 工具就绪**才返回。**`/delete-in-ide`**:注销全部 IDE MCP + 删整个配置 + 清空注入的环境。
|
|
409
614
|
|
|
410
615
|
## 限制
|
|
411
616
|
|
|
@@ -414,47 +619,67 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
|
|
|
414
619
|
- IDE MCP 注册需要 IDE **2026.2+** 的 Streamable HTTP 端点 `/stream`;更早版本只有 `/sse`,OpenCode V2 无法连接。
|
|
415
620
|
- skill 定义的字段名**以 schema 为准**,不要照官方文档:`Skill.Info` 需要 `path` (AbsolutePath),文档里写的 `location`
|
|
416
621
|
不存在 —— 用错会让 `ctx.skill.transform` 抛 `SchemaError`,而**任何 transform 失败都会禁用整个插件**(0.0.6 就是这样丢了
|
|
417
|
-
`/open-in-
|
|
418
|
-
- 需要项目环境的命令走 `
|
|
419
|
-
- 一批用不到的
|
|
420
|
-
`
|
|
421
|
-
(全部 `
|
|
422
|
-
(`
|
|
423
|
-
|
|
424
|
-
(`
|
|
622
|
+
`/open-in-ide`)。同理,`Skill.Info` 的完整字段是 `id` / `name` / `description?` / `autoinvoke?` / `path` / `content`。
|
|
623
|
+
- 需要项目环境的命令走 `ide_execute_run_configuration`(run configuration 要先在 IDEA 里配好),不用原生 shell。
|
|
624
|
+
- 一批用不到的 IDE MCP 工具被硬编码隐藏 (`src/plugin.js` 的 `HIDDEN_IDE_TOOL_SUFFIXES`,**共 48 个后缀**):
|
|
625
|
+
VCS (`git_status` / `get_repositories`,版本控制走原生 `git`)、Router 派发工具 (`execute_tool`,未启用 router-only 时冗余)、
|
|
626
|
+
Debugger (全部 `xdebug_*`)、Dev Kit MCP、Inspection KTS MCP、解释器环境 MCP、**IDE 内置终端
|
|
627
|
+
(`execute_terminal_command`:实测不继承项目环境,对原生 shell 没有优势)**、**整个 Database 组**(数据源由用户在
|
|
628
|
+
IDE 里配置,而 IDE 也不是本插件设想的数据库客户端),以及**有原生对应的文件读写**
|
|
629
|
+
(`search_text` / `search_regex` / `search_file` / `apply_patch` / `create_new_file`
|
|
425
630
|
分别对应 `grep` / `grep -E` / `glob` / `edit` / `write`)。
|
|
426
631
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
632
|
+
存的是**后缀**,清洗时按当前每个项目前缀**各删一遍** —— 只处理 `ide_` 会让子项目那几份原样送到模型面前。
|
|
633
|
+
实测数字(拿运行中的 IDE MCP 拉 `tools/list`,单个项目):IDE 暴露 **64** 个 → 隐藏 48 → **模型可见 16 个**,
|
|
634
|
+
而且这 16 个**恰好等于引导里点名的 16 个** —— 没有"能看见但没人告诉它用途"的残留。多项目就是 N × 16:
|
|
635
|
+
暴露面完全由插件决定,不需要 OpenCode 提供任何白名单能力,也不需要惰性注册。
|
|
636
|
+
|
|
637
|
+
- **部署工具只在 Ultimate 上出现**:`ide_list_deployment_servers` / `ide_upload_to_deployment` /
|
|
638
|
+
`ide_download_from_deployment` / `ide_get_deployment_task_status` 来自配套插件(`idea-mcp-enhance`),而且额外要求
|
|
639
|
+
`com.jetbrains.plugins.webDeployment`(**仅 Ultimate 有**)—— 少了任何一个前提,四个工具都不在,引导里的「服务器文件同步」一节
|
|
640
|
+
也整节消失,模型照旧用原生手段处理文件传输。详见「Deployment 全套」。
|
|
641
|
+
|
|
642
|
+
- **端口是产品常量,不开放配置**:IDEA 的 MCP 在 **64342**,PyCharm 在 **64462**(`src/ide-projects.js` 的 `IDE_PORTS`),
|
|
643
|
+
跨版本不变。所以"探哪个端口"由项目的 IDE 唯一决定,不需要扫描候选端口,也不需要用户填任何东西。
|
|
644
|
+
- 探测只回答一个问题:**「这个 IDE 里打开着这个项目吗」** —— 一次项目作用域的 MCP 调用
|
|
645
|
+
(`get_project_modules`,带 `IJ_MCP_SERVER_PROJECT_PATH`):返回模块 = 认得 → 绑定;报
|
|
646
|
+
`Unable to determine the target project` = 不认得 → `open -a` 打开它并继续轮询到认得(上限 60s)。
|
|
647
|
+
项目刚打开时的短暂"未就绪"由工具失败分类兜底(「IDE 在、但项目没打开」→ 重新打开并让模型重试)。
|
|
648
|
+
- **IDE 的「目录包含」语义(实测)**:请求路径落在某个**已打开项目的目录树内**时,IDE 会把它解析到
|
|
649
|
+
那个项目,而不是报错。所以「子项目与 root 配同一个 IDE」时,只要那个 IDE 打开了 root,子项目就被判成
|
|
650
|
+
"已打开" —— 它确实是 root 项目的一部分,工具能操作它的文件,但语言支持按 **root 项目**走(例如
|
|
651
|
+
Python 子项目被 root 的 Web 模块解析,符号检索与检查会不准)。这是 IDE 的语义,绕过不了;要让子项目
|
|
652
|
+
按自己的模块解析,就得让它在那个 IDE 里**单独打开**成一个项目,或者(正常做法)给它配它真正被打开的
|
|
653
|
+
那个 IDE。完全不在任何已打开项目下的路径(`/tmp`、不存在的路径)两个 IDE 都会正确报错。
|
|
434
654
|
- **项目路径按 IDE 的写法归一化**:IDE 收的是系统无关形式(正斜杠),其自带配置示例在 Windows 上也是
|
|
435
655
|
`"E:/gitea/secondev-demo"`。OpenCode 的 `location` 在 Windows 上是原生反斜杠,所以 `src/mcp/idea.js` 的
|
|
436
656
|
`ideProjectPath()` 把它转成正斜杠,**注册与探测走同一个函数**,两者必须一致,否则会用一种写法注册、又用另一种
|
|
437
657
|
写法去问,永远匹配不上。macOS 上是原样透传。
|
|
438
658
|
- IDE **2026.2+** 提供 Streamable HTTP 端点 `/stream`,这是插件**唯一**使用的传输(`type: "remote"`)。注册本身不启动任何子进程,
|
|
439
|
-
所以没有"桥进程被 IDE 拖死后变成僵尸"这一类问题。`/open-in-
|
|
659
|
+
所以没有"桥进程被 IDE 拖死后变成僵尸"这一类问题。`/open-in-ide` 仍要求 IDE MCP 已在监听(冷启动约数十秒),因此会先等就绪再注册。
|
|
440
660
|
- **空闲驱逐(已实测)**:OpenCode 把一个 Location 的服务缓存在 `LayerMap` 里,`idleTimeToLive` = **60 分钟**;空闲到期即整体驱逐,
|
|
441
|
-
|
|
661
|
+
插件实例连同**全部** IDE MCP 注册一起消失。**两种传输都躲不过**,所以对策不是换传输,而是请求驱动的恢复(见「行为」):
|
|
442
662
|
- 新实例上第一条用户消息的 `prompt` 钩子会把连接接回来 —— 常态下**不需要用户手动做什么**;
|
|
443
|
-
- 手动重建仍可用:执行 `/open-in-
|
|
444
|
-
-
|
|
445
|
-
- "IDE 被关掉"这一类会被下一次
|
|
663
|
+
- 手动重建仍可用:执行 `/open-in-ide`(先注销全部旧注册、再重新注册);
|
|
664
|
+
- 插件给每个 server 配 `executionTimeoutMs`(默认 **10 分钟**)作为硬上限:兜住端点卡住时的单次调用,不再沿用 OpenCode 默认的 12 小时;
|
|
665
|
+
- "IDE 被关掉"这一类会被下一次 IDE 工具调用暴露(HTTP 直接报错),由 `execute.after` 钩子分类后自愈;不产生 error 的场景(例如
|
|
446
666
|
IDE 进程还在但项目没打开)由「IDE 在、项目没打开」分支处理。
|
|
447
|
-
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
-
|
|
451
|
-
|
|
667
|
+
- 配置存在插件名下 KV (`plugin:opencode-idea:project/<root 路径>`),内容是
|
|
668
|
+
`{ root: { path, app }, children: [{ path, app }] }` —— root 与每个子项目**各自的 IDE** 都记在里面。插件实例按
|
|
669
|
+
**Location**(项目/打开目录)创建,配置按 **root 路径**共享;旧版存过的布尔 `true` 会按"root 用 idea 的 v1 配置"读入。
|
|
670
|
+
- `/delete-in-ide` 会**注销全部 IDE MCP** 并删**整个**配置 + 清空注入的环境。
|
|
671
|
+
- **目录名就是工具前缀,不合规一律拒绝**:必须匹配 `^[a-z0-9][a-z0-9_-]*$`(小写字母或数字开头,只含小写字母、数字、`-`、`_`)、
|
|
672
|
+
不与已登记项目重名、不占用保留名 `ide`。插件**绝不**自动改名或自动消歧 —— 静默改一个名字,等于用户的目录和模型看到的工具名
|
|
673
|
+
对不上,而且没人会发现。
|
|
674
|
+
- 插件**完全不再检查 `.idea` 目录**:是不是 IDE 项目只由配置(`/open-in-ide` 设置、`/delete-in-ide` 清除)决定。
|
|
675
|
+
(`/open-in-ide` 会让对应 IDE 打开并导入该项目,`.idea` 由 IDE 自己生成,插件无需也不应据此判断。)
|
|
452
676
|
- **自动拉起 IDE 仅实现 macOS** (`open -a`)。其他平台(包括 Windows)没有对应的启动命令,**请手动打开 IDE 和项目**,再执行
|
|
453
|
-
`/open-in-
|
|
677
|
+
`/open-in-ide` —— 端口在监听、项目被认得就会正常接入,其余能力(注册、探测、自愈、工具暴露)与 macOS 完全一致。
|
|
454
678
|
IDE 里打开 MCP 服务(2026.2+)并启用 Brave Mode;首次打开若弹 Trust 对话框,需确认后重试。
|
|
455
679
|
- IDE MCP 没有「打开项目」工具,因此打开动作走 OS/CLI,而非 MCP。
|
|
456
|
-
- 插件热重载会断开 IDE 连接,需重跑 `/open-in-
|
|
457
|
-
-
|
|
680
|
+
- 插件热重载会断开 IDE 连接,需重跑 `/open-in-ide`。
|
|
681
|
+
- 插件不修改任何**它不接管**的工具定义或描述;IDE 工具以 `<项目前缀>_*` 直接暴露给模型 (`codemode: false`),不用 `execute` 包裹。
|
|
682
|
+
唯一的例外是 `rebuild` 参数(见「工具参数」),它对每个项目前缀各处理一遍。
|
|
458
683
|
|
|
459
684
|
## License
|
|
460
685
|
|