opencode-idea 0.0.16 → 0.0.18

package/src/ide-guidance.template.md

@@ -0,0 +1,118 @@
+# IDE MCP:只有非 IDE 不可的能力才走 IDE
+
+本会话接入了 {{projectCount}} 个 JetBrains 项目。**每个功能在所有项目下都各有一份工具**,命令名就是
+`<项目前缀>_<工具名>`;下面每条功能后面直接列出它在各项目里的命令名。
+
+## 本会话接入的项目与各自的 MCP 工具
+
+{{routeTable}}
+
+**子项目就是根目录下的目录**,只是被另一个 IDE 单独打开、配了另一套工具。所以这里说的"根项目",指的是
+**根目录中扣掉这些子项目之后的部分** —— 操作某个子项目里的文件,就用那个子项目的命令,不要因为它"在根目录下"
+就用根项目的工具。
+
+**规则:操作哪个目录下的文件/代码,就用那个目录对应的命令。** IDE 是按项目解析的 —— 跨项目调用要么直接报错,
+要么被解析到另一个项目上、作用在错误的代码上。
+
+按需读文件:要了解某个子项目自己的约定,读它的 `<子项目目录>/AGENTS.md`(它不会自动进入本会话的上下文,
+本会话是 root 打开的那一个)。
+
+## 总则(所有项目通用)
+
+- 原生工具(当前工具列表里直接列出的那些)**直接调用**;不需要、也不应该用 Code Mode 的 `search` 去找。
+- 下面这些 IDE 工具也是原生工具:直接调用(参数按各工具 schema 传),不要包进 `execute`;它们不在 Code Mode 的工具目录里,`search` 搜不到。
+- **只有 IDE 才有的能力才用它们**:符号级检索、项目模型、检查与构建、重构与格式化、run configuration。
+- **读写与搜索用原生工具**(`read` / `write` / `edit` / `grep` / `glob`):不要为读一个文件、写一个文件、搜一段文本去绕 IDE 工具。
+- **唯一例外**:压缩包内的条目(路径带 `.jar!/`,原生 `read` 打不开)—— 见下面「读压缩包内的东西」。
+- 某条功能下面没有你正要操作的那个项目的命令,就是那个项目没接上:提示用户执行 `/open-in-idea`,不要重试,也不要去别处找。
+
+## 工具(每条第一行是各项目的命令,接着是它的用法)
+
+### 符号(只有 IDE 的语义索引能给)
+
+- {{cmd_search_symbol}}
+  **按名字找符号的声明位置**(`q` 传查询文本,**固定带上 `include_external: true`**):本插件最不可替代的能力 —— 它搜的是**符号**(类 / 接口 / 方法 / 函数 / 字段 / 类型 / 常量这类**有名字的定义**)的**声明位置**,不是"哪段文本提到过它"(那是 `grep` 的事);带上 `include_external` 才会连**依赖库和标准库**一起搜,于是你能直接定位第三方库里的实现 —— 这是原生 `grep` / `glob` 够不着的地方(IDE 自己的 `search_text` / `search_file` 也只搜项目内)。
+  - **典型用法 ①:代码里引用了某个库的 API(最常见)** —— 读代码时看到 `from fastapi import FastAPI`、`import org.apache.poi...FormulaParser`、`gorm.DeletedAt`、`from 'vue'` 这类引用时,**包名就在代码里**,直接**用「包名+符号名」当 `q` 搜**,一次定位到它的实现:
+    - **Java**:全限定名 —— `com.nimbusds.jose.util.Base64`(实测 1 条命中 `~/.m2/.../poi-5.3.0-sources.jar!/...`)
+    - **Go**:包名.符号 —— `gorm.DeletedAt`(实测 2 条,全在 `go/pkg/mod/gorm.io/gorm@...`)
+    - **Python**:模块路径给得越全越准 —— `torch.nn.modules.module.Module`(目标全在最前);`torch.nn.Module` 也能把目标排进前 2
+    - **Node/TS**:用 **import 的那层包名**(不是子模块路径)—— `vue.Teleport` 有效,`@vue/runtime-core.TeleportProps` 搜不到
+  - **典型用法 ②:调研一个库有哪些 API** —— 包名从依赖清单里拿(pom.xml / package.json / go.mod / requirements.txt),**直接拿包名当 `q` 搜**,结果基本就落在这个库里,再读入口:
+    - **Python**:`fastapi` → `fastapi/applications.py`、`fastapi/__init__.py`(**入口就是导出清单**:直接看到 `FastAPI`、`HTTPException` 这些公开名字)
+    - **Java**:`poi` → `~/.m2/.../poi-5.3.0-sources.jar!/org/apache/poi/...`;读该库的入口类
+    - **Go**:`gorm` → `go/pkg/mod/gorm.io/gorm@v1.31.0/...`
+    - **Node/TS 例外**:包名当 `q` 搜不到(实测 `element-plus` → 0 条)。要用**代码里 import 的符号名**;包名是简单标识符时可以「包名.符号」(`vue.Teleport` 有效),但**带 `-` 或 `@scope/` 的这么拼是 0 条**(`element-plus.ElMessage`、`@vue/runtime-core.TeleportProps` 都搜不到)。而裸符号名会跨多个子项目(`ElMessage` 命中 user / admin / vcop 三处),这时用 `paths` 圈到那个 `node_modules` —— `paths: ['frontend/user/**']` 就收敛到一处。
+  - **它只覆盖「项目已经引入」的依赖**:搜不到某个库,基本就是这个库还没进依赖 —— 别反复试:要么先把它加进依赖(pom / requirements / package.json),要么改用 web 搜索 / GitHub 看它的源码。
+  - **同名符号往往有多处定义**(标准库一份、几个依赖各一份,还有测试和示例),所以**按代码上下文选**:看调用处 import 的是哪个包、传参是什么类型、返回路径属于哪个库 —— 别把第一行当答案。
+  - **它返回的路径,原样交给同一个项目的 `<P>_read_file` 就是源码**:两者同属一个项目、相对路径的基准一致,所以不用拼绝对路径、不用管是什么语言 —— 压缩包里的条目它也照样读(`.class` 还会反编译)。
+    例:`<P>_search_symbol({ q: "UvicornWorker", include_external: true })` 给出 `../../../Library/.../uvicorn/workers.py` → `<P>_read_file({ file_path: "那个字符串" })`。
+  - **依赖索引是按项目的**:任何依赖都用**它所在项目**的那个 MCP 工具去搜 —— 根项目的依赖用根项目的命令,子项目的依赖用子项目的命令。拿一个项目的工具去搜另一个项目的依赖,只会在那个项目自己的文件里找,**拿不到库**。
+  - **别把这条路径交给原生 `read`**:原生 read 的基准是本会话的工作目录(根项目),拿子项目的相对路径去读会落到错误的位置。
+- {{cmd_get_symbol_info}}
+  **一个符号的签名 / 文档 / 声明位置**:`filePath` + `line` + `column`。
+- {{cmd_analyze_calls}}
+  **调用关系**:`symbolFqn` 传符号名,`analysisKind` 取 `INCOMING_CALLS` / `OUTGOING_CALLS`;`depth` 控层数,`childOffset` 翻页。
+
+### 项目与编辑器
+
+- {{cmd_list_directory_tree}}
+  **项目视角的目录树**(尊重内容根与排除项):`maxDepth` 控深度。
+- {{cmd_get_project_modules}}
+  **项目模块及类型**。
+- {{cmd_get_project_dependencies}}
+  **项目直接声明的依赖**。
+- {{cmd_get_all_open_file_paths}}
+  **用户在 IDE 里打开了哪些文件**(含当前激活的那个)。
+- {{cmd_open_file_in_editor}}
+  **把文件在 IDE 里打开并激活**,给用户看。
+
+### 重构与格式化
+
+- {{cmd_rename_refactoring}}
+  **按符号改名**,项目内的引用一并更新。
+- {{cmd_reformat_file}}
+  **按 IDE 的代码风格重排**。
+
+### 校验
+
+- {{cmd_lint_files}}
+  **批量检查**:`files` 传数组;只列有问题的文件。
+- {{cmd_get_file_problems}}
+  **单文件检查**:`filePath`;结果在 `errors`。
+- {{cmd_build_project}}
+  **构建校验**:`filesToRebuild` 可只构建指定文件;有问题返回在 `problems`,没返回即没问题。
+
+### 读压缩包内的东西
+
+- {{cmd_read_file}}
+  **压缩包内的条目**(路径形如 `libs/foo.jar!/com/x/Bar.class` 或 `jar://` URL)只有它能读 —— 原生 `read` 打不开压缩包,而它还能把 `.class` **反编译成源码**;「符号」那条搜出来的路径也用它(原样传即可)。
+
+### 运行配置
+
+- {{cmd_get_run_configurations}}
+  **项目里有哪些运行配置**:传 `filePath` 可列该文件的运行入口。**不要翻 `.run/` 目录** —— 存在 `.idea/` 里的那些看不到。
+- {{cmd_execute_run_configuration}}
+  **跑已有配置**:Shell Script 要 `EXECUTE_IN_TERMINAL: false`;覆盖参数(`programArguments` / `workingDirectory` / `envs`)需配置支持 `supportsDynamicLaunchOverrides`。
+{{#if canCreateRunConfiguration}}
+- {{cmd_create_shell_run_configuration}}
+  **新建项目级 Shell 配置**(`configurationName` + `scriptPath` / `scriptText` / `cloneFrom` 三选一;写 `.run/<name>.run.xml`):**重操作** —— 只给固定要跑、反复要用的流程建,**且建之前必须先取得用户同意**;只支持 Shell 类型,**其他类型请用户在 IDE 里建**。
+{{/if}}
+{{#if canListRunningConfigurations}}
+- {{cmd_list_running_configurations}}
+  **当前真正在跑的配置**(几个实例 / 各自 pid / 退出码):停 / 重启前后都先用它看状态。
+{{/if}}
+{{#if canStopRunConfiguration}}
+- {{cmd_stop_run_configuration}}
+  **停掉该配置的全部实例并等它们退出**:没在跑也返回成功。
+{{/if}}
+{{#if canRerunRunConfiguration}}
+- {{cmd_rerun_run_configuration}}
+  **改完代码重启无热重载的进程**:在跑就重启、没在跑就启动;读 `started` 判断新进程是否真的起来了。不要用 `pkill` / `kill` / `shell` 代替。
+{{/if}}
+
+## 命令执行(所有项目通用)
+
+- 需要项目环境的命令(依赖 IDE 里配好的 JDK / Node / Python 版本等):用该项目前缀的 run configuration 工具,不要用原生 `shell`。
+- run configuration 是**重资产**:一个项目通常只建几个(固定要跑的构建 / 装依赖 / dev server 之类),**不是随手一条命令就建一个**。要新建时先确认它**反复要用、且属于项目固定流程**,再**先告诉用户要建什么、为什么,取得同意才动手**,别自己决定。
+- **配置一律不由你写**:不要手写 `.run/*.run.xml`,也不要手搓启动命令。
+- 不需要项目环境的命令:用原生 `shell`。

package/src/ide-launcher.js

@@ -12,50 +12,110 @@
 // unavailable; this module only requests opening/activating the project.
 
 import { spawn } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 
-/** Default macOS app name for IntelliJ IDEA. */
+/** 兜底 macOS 应用名：调用方没给 app 时用它。 */
 export const DEFAULT_IDE_APP = 'IntelliJ IDEA';
 
 /**
- * Can this platform launch the IDE at all?
+ * 每个 IDE 选项值对应的 macOS 应用名。
  *
- * Launching goes through macOS `open -a`, which is the only launcher this
- * plugin implements. On Windows there is no `open` command, so a spawn there
- * fails with ENOENT — silently, as a rejected promise that resolves `false`.
- * Rather than pretend, other platforms resolve no app at all and the caller
- * asks the user to open the IDE by hand.
- *
- * A function, not a constant: the answer is read when a command runs, so tests
- * can simulate another platform by replacing it. A constant would be bound at
- * import time and never re-read.
+ * 只包含受支持的 IDE（见 `ide-projects.js` 的 `SUPPORTED_IDES`）—— 应用名由项目
+ * 配置决定，不再由用户在 `openInIde` 里自由指定，所以这里是一张封闭的表。
  */
-export function autoLaunchSupported() {
-  return process.platform === 'darwin';
-}
-
-/** Aliases accepted by the `openInIde` option. */
 export const IDE_APPS = {
   idea: 'IntelliJ IDEA',
-  intellij: 'IntelliJ IDEA',
-  'intellij-idea': 'IntelliJ IDEA',
+  pycharm: 'PyCharm',
 };
 
 /**
- * Resolve the `openInIde` option to a macOS app name, or `undefined` to disable.
+ * 该 IDE 的 macOS 应用名，`undefined` 表示"不能自动拉起"。
  *
- * `undefined` covers two distinct reasons, and the caller tells them apart via
- * `autoLaunchSupported()`: the user turned launching off, or this platform has
- * no launcher. They deserve different user-facing wording.
+ * `undefined` 有两种原因，调用方用 `autoLaunchSupported()` 区分：这个平台没有
+ * 启动器，或这个 IDE 不在支持列表里。两者给用户的建议不同，不能混为一谈。
  *
- * @param {boolean | string | undefined} value
+ * @param {string} app
  * @param {{ platform?: string }} [options]
  * @returns {string | undefined}
  */
-export function resolveIdeApp(value, { platform = process.platform } = {}) {
+export function appNameFor(app, { platform = process.platform } = {}) {
   if (platform !== 'darwin') return undefined;
-  if (value === false) return undefined;
-  if (typeof value !== 'string') return DEFAULT_IDE_APP;
-  return IDE_APPS[value.toLowerCase()] ?? value;
+  return IDE_APPS[app];
+}
+
+/**
+ * 各平台上看"装了哪些 IDE"的目录。
+ *
+ * macOS 那两个位置是**实测**的（这台机器上就是这么装的）；Windows / Linux 列的是各自最
+ * 常见的安装位置（Toolbox 默认 + 系统级目录），**未在真机上验证过** —— 探错的后果只是少一
+ * 行提示、让模型照常问用户，不会挡住任何选择，所以先按常见值给出来。
+ */
+function ideInstallDirs(platform = process.platform) {
+  const home = homedir();
+  if (platform === 'darwin') return ['/Applications', join(home, 'Applications')];
+  if (platform === 'win32') {
+    const local = process.env.LOCALAPPDATA ?? join(home, 'AppData', 'Local');
+    return [
+      join(local, 'Programs', 'JetBrains'),
+      join(local, 'JetBrains', 'Toolbox', 'apps'),
+      'C:\\Program Files\\JetBrains',
+    ];
+  }
+  return [join(home, '.local', 'share', 'JetBrains', 'Toolbox', 'apps'), '/opt', '/usr/local'];
+}
+
+/**
+ * 本机装了哪些受支持的 IDE（`IDE_APPS` 的键）。
+ *
+ * 按**安装目录**判断，不看进程 —— 用 `ps aux` 之类探进程只能发现"正在运行"的 IDE，装了
+ * 但没打开就会漏（实测踩过：PyCharm 明明装着，进程探测报"未发现"）。一次目录读取就够，
+ * 比模型自己去跑命令快几个数量级。
+ *
+ * 返回空数组表示"**没探测出来**"，不能当成"没装"：调用方要么照常问用户，要么在提示里说明
+ * 是"没找到"。
+ *
+ * @param {{ platform?: string, dirs?: string[] }} [options] 仅供测试注入。
+ * @returns {string[]}
+ */
+export function detectInstalledIdes(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const dirs = options.dirs ?? ideInstallDirs(platform);
+  /** @type {Set<string>} */
+  const found = new Set();
+  for (const dir of dirs) {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      // 目录不存在（例如没有 ~/Applications）就是没装，继续看下一个。
+      continue;
+    }
+    for (const entry of entries) {
+      const bundle = entry.endsWith('.app') ? entry.slice(0, -'.app'.length) : entry;
+      for (const [app, label] of Object.entries(IDE_APPS)) {
+        // `IntelliJ IDEA.app` 精确匹配；`PyCharm CE.app`、`PyCharm 2026.2`、Toolbox 的
+        // `PyCharm` 目录都是产品名开头，按前缀匹配。
+        if (bundle === label || bundle.startsWith(label)) found.add(app);
+      }
+    }
+  }
+  return [...found];
+}
+
+/**
+ * 这个平台有没有自动拉起 IDE 的能力？
+ *
+ * 只有 macOS 实现了启动（`open -a`）。Windows 上没有 `open` 命令，spawn 会以
+ * ENOENT 失败——表现为一个静默 resolve 成 `false` 的 promise。与其假装能启动，
+ * 不如让调用方直接告诉用户手动打开 IDE。
+ *
+ * 写成函数而不是常量：答案在命令真正执行时读取，测试才能用替换它的方式模拟
+ * 其它平台；常量会在 import 时定死，之后再也不重读。
+ */
+export function autoLaunchSupported() {
+  return process.platform === 'darwin';
 }
 
 /**

package/src/ide-projects.js

@@ -0,0 +1,262 @@
+// IDE 项目集合：一个 OpenCode 会话（root 项目）可以接入多个 JetBrains 项目 ——
+// root 本身，加上 root 下任意层级的子目录；每个项目可以被**不同的** IDE 打开
+// （root 用 IDEA、modelserver 用 PyCharm 是常态）。
+//
+// 这个模块只做纯数据：持久化标记的解析/序列化、工具前缀（= MCP server 名）的派生、
+// 以及新增子项目前的校验。所有 I/O、探测、注册都留在 plugin.js，所以这里全部是
+// 可以直接测的纯函数。
+//
+// ## 命名规则
+//
+// 工具前缀就是 MCP server 名，由项目的**层级**决定，与 IDE 产品无关：
+//
+//   * root  → `ide`        root 用 IDEA 还是 PyCharm，它都叫 `ide_*`
+//   * 子项目 → 目录名       `modelserver` → `modelserver_*`
+//
+// 为什么不叫 `idea_*`：那会把"root 项目"和"IntelliJ IDEA 这个产品"绑死，而
+// 「root 用 PyCharm 打开、子项目用 IDEA 打开」是完全合理的组合。
+//
+// ## 为什么前缀必须严格控制字符集
+//
+// 前缀会变成工具名的一部分（`modelserver_search_symbol`），模型要照着调。目录名
+// 里但凡有空格、点、大写或非 ASCII，工具名就会变得难写、难赌 —— 跨平台还可能
+// 产生"同名不同目录"。所以不规范的目录名**一律拒绝**（见 validateSubproject），
+// 由用户改目录名，插件绝不自动改名或消歧。
+
+import { basename, sep } from 'node:path';
+
+/** root 项目的 MCP server 名。与 IDE 产品解耦，见文件头。 */
+export const ROOT_SERVER_NAME = 'ide';
+
+/** `ctx.options.ides` 允许的取值；未知值会被忽略。 */
+export const SUPPORTED_IDES = ['idea', 'pycharm'];
+
+/** 每个 IDE 选项值对应的显示名（提示词里写给模型看）。 */
+export const IDE_LABELS = {
+  idea: 'IntelliJ IDEA',
+  pycharm: 'PyCharm',
+};
+
+/**
+ * 每个 IDE 的 MCP 端口。
+ *
+ * **固定值,不开放配置**:JetBrains 给内置 MCP server 分配的就是这个端口,跨版本、
+ * 跨项目都不变(IDEA 的 MCP 在 64342,它的内置服务是 63342;PyCharm 的 MCP 在 64462,
+ * 内置服务是 63343)。既然"哪个 IDE 在哪个端口"是产品常量,插件就不需要"扫描候选端口
+ * 找归属":探哪个端口由项目的 IDE 唯一决定,不经过任何用户配置。
+ *
+ * 导出成**可变对象**而不是冻结字面量:测试要把它们指到假端口上(见
+ * `tests/plugin.test.js` 的 `fakeCtx`),运行时没有任何人写它。
+ */
+export const IDE_PORTS = {
+  idea: 64342,
+  pycharm: 64462,
+};
+
+/**
+ * 子项目目录名（= 工具前缀）必须匹配的形状。
+ *
+ * 小写字母或数字开头，其后只允许小写字母、数字、`-`、`_`。上限 48 是硬约束之一
+ * 的保守取值：工具名要在模型提示里反复出现，越短越好。
+ */
+export const SUBPROJECT_PREFIX = /^[a-z0-9][a-z0-9_-]{0,47}$/;
+
+/** 持久化标记里存的版本号，用于将来识别旧结构。 */
+export const MARK_VERSION = 2;
+
+/**
+ * @typedef {{ path: string, app: string }} IdeProject
+ * @typedef {{ root: IdeProject, children: IdeProject[] }} IdeConfig
+ */
+
+/** 这个 root 的持久化标记 key。 */
+export function markKeyFor(rootPath) {
+  return `project/${rootPath}`;
+}
+
+/** @param {unknown} entry @returns {boolean} */
+function isProjectEntry(entry) {
+  return (
+    entry !== null &&
+    typeof entry === 'object' &&
+    typeof (/** @type {IdeProject} */ (entry).path) === 'string' &&
+    typeof (/** @type {IdeProject} */ (entry).app) === 'string'
+  );
+}
+
+/**
+ * 解析持久化的标记值。
+ *
+ * 兼容 v1：旧版本存的是布尔 `true`（只表示"root 已接入"，没有 IDE 与子项目信息），
+ * 这里把它读成"root 用 idea 的 v1 配置"。任何无法识别的形状都当作**未配置**
+ * （`undefined`），因为一个读不懂的配置比没有配置更危险。
+ *
+ * @param {unknown} raw 从 `ctx.storage` 读到的原始值
+ * @param {string} rootPath
+ * @returns {IdeConfig | undefined}
+ */
+export function parseMark(raw, rootPath) {
+  if (raw === true) return { root: { path: rootPath, app: 'idea' }, children: [] };
+  if (raw === null || typeof raw !== 'object') return undefined;
+  const record = /** @type {{ root?: unknown, children?: unknown }} */ (raw);
+  if (!isProjectEntry(record.root)) return undefined;
+  const root = /** @type {IdeProject} */ (record.root);
+  const children = Array.isArray(record.children)
+    ? record.children.filter(isProjectEntry).map((entry) => {
+        const child = /** @type {IdeProject} */ (entry);
+        return { path: child.path, app: child.app };
+      })
+    : [];
+  return { root: { path: root.path, app: root.app }, children };
+}
+
+/** @param {IdeConfig} config @returns {Record<string, unknown>} */
+export function serializeMark(config) {
+  return {
+    version: MARK_VERSION,
+    root: { path: config.root.path, app: config.root.app },
+    children: config.children.map((child) => ({ path: child.path, app: child.app })),
+  };
+}
+
+/**
+ * 一个项目对应的 MCP server 名（= 工具前缀）。
+ *
+ * @param {string} path
+ * @param {string} rootPath
+ */
+export function serverNameFor(path, rootPath) {
+  return path === rootPath ? ROOT_SERVER_NAME : basename(path);
+}
+
+/**
+ * 展开成"项目 + 前缀"的平铺列表，顺序固定：root 在最前，子项目按登记顺序。
+ *
+ * @param {IdeConfig} config
+ * @returns {Array<{ path: string, app: string, server: string, isRoot: boolean }>}
+ */
+export function listProjects(config) {
+  const root = {
+    path: config.root.path,
+    app: config.root.app,
+    server: ROOT_SERVER_NAME,
+    isRoot: true,
+  };
+  const children = config.children.map((child) => ({
+    path: child.path,
+    app: child.app,
+    server: serverNameFor(child.path, config.root.path),
+    isRoot: false,
+  }));
+  return [root, ...children];
+}
+
+/** 当前配置里所有项目的工具前缀（带下划线），例如 `["ide_", "modelserver_"]`。 */
+export function toolPrefixes(config) {
+  return listProjects(config).map((project) => `${project.server}_`);
+}
+
+/**
+ * 校验：把 `absPath` 登记为 root 的子项目是否合法。
+ *
+ * 全部规则都是**拒绝**，不做任何自动修正 —— 与插件其它地方一致：静默改一个名字，
+ * 等于把用户的目录和模型看到的工具名对不上，而且没人会发现。
+ *
+ * @param {IdeConfig} config
+ * @param {string} absPath 待登记的绝对路径
+ * @returns {{ ok: true } | { ok: false, code: string, message: string }}
+ */
+export function validateSubproject(config, absPath) {
+  const rootPath = config.root.path;
+  const prefix = rootPath.endsWith(sep) ? rootPath : `${rootPath}${sep}`;
+  if (!absPath.startsWith(prefix)) {
+    return {
+      ok: false,
+      code: 'outside-root',
+      message: `必须位于 root 项目（${rootPath}）之下`,
+    };
+  }
+  const name = basename(absPath);
+  if (!SUBPROJECT_PREFIX.test(name)) {
+    return {
+      ok: false,
+      code: 'invalid-name',
+      message: `目录名 \`${name}\` 不能作为工具前缀:要求 ^[a-z0-9][a-z0-9_-]{0,47}$,即以小写字母或数字开头,只含小写字母、数字、- 和 _`,
+    };
+  }
+  if (name === ROOT_SERVER_NAME) {
+    return {
+      ok: false,
+      code: 'reserved',
+      message: `\`${ROOT_SERVER_NAME}\` 是 root 项目保留的工具前缀,请在别处使用这个目录名`,
+    };
+  }
+  const existing = config.children.find((child) => child.path === absPath);
+  if (existing) {
+    return { ok: false, code: 'already-registered', message: `\`${name}\` 已经登记过了` };
+  }
+  const clash = config.children.find((child) => basename(child.path) === name);
+  if (clash) {
+    return {
+      ok: false,
+      code: 'duplicate-prefix',
+      message: `工具前缀 \`${name}\` 已被 ${clash.path} 占用;两个子项目不能同名,请重命名其中一个目录`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * 加入一个子项目，返回新配置（不改入参）。
+ *
+ * @param {IdeConfig} config
+ * @param {string} absPath
+ * @param {string} app
+ * @returns {IdeConfig}
+ */
+export function withSubproject(config, absPath, app) {
+  return {
+    root: { ...config.root },
+    children: [...config.children.map((child) => ({ ...child })), { path: absPath, app }],
+  };
+}
+
+/**
+ * 从参数文本里切出子项目路径。
+ *
+ * 斜杠命令的参数是**整串**（`input.prompt.text`），不分词，所以这里自己切：
+ * 取第一个空白分隔的片段。多给的部分是错的，宁可报错也不要猜。
+ *
+ * @param {unknown} text
+ * @returns {{ ok: true, path: string } | { ok: false, message: string }}
+ */
+export function parseSubprojectArgument(text) {
+  const raw = typeof text === 'string' ? text.trim() : '';
+  if (raw === '') return { ok: false, message: '缺少子项目路径参数' };
+  const parts = raw.split(/\s+/);
+  if (parts.length > 1) {
+    return {
+      ok: false,
+      message: `只接受一个参数(子项目路径),收到 ${parts.length} 个:\`${raw}\``,
+    };
+  }
+  return { ok: true, path: parts[0] };
+}
+
+/**
+ * 从参数文本里切出 IDE 名。
+ *
+ * `/open-in-idea pycharm` 是"AI 不配合时的直通逃生口"：正常流程由 AI 向用户提问后
+ * 调工具写回，带参只是保险。空串表示"没给"，由调用方决定是提问还是用默认值。
+ *
+ * @param {unknown} text
+ * @returns {{ ok: true, app: string | undefined } | { ok: false, message: string }}
+ */
+export function parseIdeArgument(text) {
+  const raw = typeof text === 'string' ? text.trim().toLowerCase() : '';
+  if (raw === '') return { ok: true, app: undefined };
+  if (!SUPPORTED_IDES.includes(raw)) {
+    return { ok: false, message: `不支持的 IDE \`${raw}\`,可选:${SUPPORTED_IDES.join(' / ')}` };
+  }
+  return { ok: true, app: raw };
+}

package/src/mcp/enhance.js

@@ -0,0 +1,71 @@
+// MCP surface added by the companion IDEA plugin `idea-mcp-enhance`.
+//
+// Kept apart from `idea.js` on purpose. `idea.js` describes ONE thing: the MCP
+// server IntelliJ itself bundles, which every supported IDE has. Everything in
+// this file describes a SECOND, optional source of tools — a plugin the user may
+// or may not have installed. Two different origins, two files:
+//
+//   * native  -> `idea.js`      (always present; the IDE owns the catalog)
+//   * plugin  -> this file      (present only if the user installed the plugin)
+//
+// The companion plugin (https://github.com/syllr/idea-mcp-enhance) fills the gaps
+// the bundled server leaves in run configuration handling: the bundled server can
+// only START an existing configuration — it cannot create one, stop one, restart
+// one, or say what is currently running.
+//
+// Consequence of the split, and the reason it matters: a stock IDE serves a
+// SHORTER catalog than an enhanced one. Nothing here may be assumed — every use
+// has to be gated on the tools really being in the request (`servingRunLifecycleTools`).
+
+/**
+ * The enhance plugin's tool names, as **suffixes**.
+ *
+ * OpenCode namespaces an MCP server's tools with the server name, and each
+ * project is registered under its own prefix (root = `ide`, a subproject = its
+ * directory name). So the wire name is `<prefix><suffix>` — for example
+ * `ide_rerun_run_configuration` or `modelserver_rerun_run_configuration`.
+ *
+ * 存后缀而不是完整名字：同一个工具在每个项目前缀下各有一份，写死任何一个前缀都会
+ * 让别的项目查不到它。
+ *
+ * Keep in sync with `RunLifecycleSchemas.kt` in the enhance repository — the
+ * suffixes are its contract, and there is no runtime way to discover "which
+ * plugin provided this tool": MCP carries no such marker.
+ */
+export const CREATE_SHELL_RUN_CONFIGURATION_SUFFIX = 'create_shell_run_configuration';
+export const LIST_RUNNING_CONFIGURATIONS_SUFFIX = 'list_running_configurations';
+export const STOP_RUN_CONFIGURATION_SUFFIX = 'stop_run_configuration';
+export const RERUN_RUN_CONFIGURATION_SUFFIX = 'rerun_run_configuration';
+
+/** All of them, in the order the guidance lists them: create, see, stop, restart. */
+export const RUN_LIFECYCLE_SUFFIXES = [
+  CREATE_SHELL_RUN_CONFIGURATION_SUFFIX,
+  LIST_RUNNING_CONFIGURATIONS_SUFFIX,
+  STOP_RUN_CONFIGURATION_SUFFIX,
+  RERUN_RUN_CONFIGURATION_SUFFIX,
+];
+
+/**
+ * Which of the enhance plugin's tools **this project's prefix** carries in this
+ * request.
+ *
+ * 返回布尔组合而不是名字列表：提示词要的是"这段能不能写",而且每个项目各算各的
+ * —— 一个项目装了 enhance、另一个没装是可能的。
+ *
+ * 客户端版本差异同理：enhance 版本独立发布，旧版可能少几个工具，所以逐个判断,
+ * 提示词绝不能点名一个模型调不到的工具。
+ *
+ * @param {Record<string, unknown> | undefined} tools This request's tool record
+ *   (`event.tools` from the `context` hook).
+ * @param {string} prefix 该项目的工具前缀（含下划线）。
+ */
+export function runLifecycleCapabilities(tools, prefix) {
+  const has = (suffix) =>
+    Boolean(tools) && typeof tools === 'object' && `${prefix}${suffix}` in tools;
+  return {
+    canCreateRunConfiguration: has(CREATE_SHELL_RUN_CONFIGURATION_SUFFIX),
+    canListRunningConfigurations: has(LIST_RUNNING_CONFIGURATIONS_SUFFIX),
+    canStopRunConfiguration: has(STOP_RUN_CONFIGURATION_SUFFIX),
+    canRerunRunConfiguration: has(RERUN_RUN_CONFIGURATION_SUFFIX),
+  };
+}