opencode-idea 0.0.18 → 0.0.19

package/src/ide-guidance.template.md

@@ -23,15 +23,18 @@
 - 下面这些 IDE 工具也是原生工具:直接调用(参数按各工具 schema 传),不要包进 `execute`;它们不在 Code Mode 的工具目录里,`search` 搜不到。
 - **只有 IDE 才有的能力才用它们**:符号级检索、项目模型、检查与构建、重构与格式化、run configuration。
 - **读写与搜索用原生工具**(`read` / `write` / `edit` / `grep` / `glob`):不要为读一个文件、写一个文件、搜一段文本去绕 IDE 工具。
-- **唯一例外**:压缩包内的条目(路径带 `.jar!/`,原生 `read` 打不开)—— 见下面「读压缩包内的东西」。
-- 某条功能下面没有你正要操作的那个项目的命令,就是那个项目没接上:提示用户执行 `/open-in-idea`,不要重试,也不要去别处找。
+- **改完代码自己先查一遍**(`lint_files` / `build_project`,怎么挑见下面「校验」):什么时候查、查几次由你判断,但**别把校验整段省掉** —— 自己查一次,远比让用户替你发现或留到构建 / 测试炸了才暴露要便宜。
+- **要看某个类 / 方法 / 字段在哪定义、内部怎么实现的**(见下面「符号」):`<P>_search_symbol`(`include_external: true`)找到位置 → `<P>_read_file` 原样读它给的路径。
+- 某条功能下面没有你正要操作的那个项目的命令,就是那个项目没接上:提示用户执行 `/open-in-ide`,不要重试,也不要去别处找。
 
 ## 工具(每条第一行是各项目的命令,接着是它的用法)
 
 ### 符号(只有 IDE 的语义索引能给)
 
+**要读任何类 / 方法 / 字段的源码,就两步**:`<P>_search_symbol`(`q` 传名字,**带 `include_external: true`**)找到位置 → `<P>_read_file` 原样读它给的路径。**依赖库 / 三方包 / 平台 jar 里的实现,正是它最该用的场合**,也是 `javap` / `unzip` / 解包 jar / 按 jar 路径 `grep` 唯一的正解:**IDE 索引里那份就是项目编译时真正用的依赖**(自己拼的 jar 路径常常是另一份副本,版本对不上),读出来还是反编译源码 —— 字节码清单要来回十几次才能拼出逻辑,这边一次到位。
+
 - {{cmd_search_symbol}}
-  **按名字找符号的声明位置**(`q` 传查询文本,**固定带上 `include_external: true`**):本插件最不可替代的能力 —— 它搜的是**符号**(类 / 接口 / 方法 / 函数 / 字段 / 类型 / 常量这类**有名字的定义**)的**声明位置**,不是"哪段文本提到过它"(那是 `grep` 的事);带上 `include_external` 才会连**依赖库和标准库**一起搜,于是你能直接定位第三方库里的实现 —— 这是原生 `grep` / `glob` 够不着的地方(IDE 自己的 `search_text` / `search_file` 也只搜项目内)。
+  **`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@...`)
@@ -82,6 +85,19 @@
 - {{cmd_build_project}}
   **构建校验**:`filesToRebuild` 可只构建指定文件;有问题返回在 `problems`,没返回即没问题。
 
+**改完代码,自己先查一遍再收尾。** 这不是流程要求,是你自己的判断 —— 查一次很便宜,而问题一旦漏到用户
+看见、或留到构建 / 测试炸了才暴露,回头纠正的代价就高一个量级了。
+
+- **这次要改一大片**(多文件、跨模块、"顺手把这几处一起对齐")→ 全部改完再 `build_project` 一次。中途不查:
+  半成品状态下的检查结果只会误导你。
+- **这次只改一处,或在同一个文件上反复微调** → 告一段落时,把这轮改过的文件一次 `lint_files` 掉;要看单个
+  文件的细节再上 `get_file_problems`。
+- **改了签名 / 接口 / import / 依赖**这类"别处会跟着坏"的地方 → 走 `build_project`;只动了文件内部的实现 →
+  lint 就够。
+- 查出来的问题**改掉,或说清为什么不改**,别把没处理的问题原样交给用户。
+- 校验走上面这些工具,**不要改用 `shell` 里临时自己编一遍代替**。
+- 也别先猜"索引还没同步 / 那个环境是另一个进程"就绕开 —— 先调一次,它真看不到会明说。
+
 ### 读压缩包内的东西
 
 - {{cmd_read_file}}
@@ -95,7 +111,11 @@
   **跑已有配置**: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 里建**。
+  **新建项目级 Shell 配置**(`configurationName` + `scriptPath` / `scriptText` / `cloneFrom` 三选一;写 `.run/<name>.run.xml`):只支持 Shell 类型。它是**项目资产**,不是"跑命令"的手段 —— 只是要跑一条命令就用原生 `shell`。判据只有一条:**这件事以后会不会以同样的形态再发生?**
+  - **这里只是"建"的一个入口,不是全部**:非 Shell 类型,以及**删 / 改**,都走 `idea-run-config-manager` skill —— 让用户调它(它有逐类型模板;没有模板的类型,它会让用户在 IDE 里配)。
+  - **会 → 该建,而且你要主动提**。典型信号:用户让你做的是**重复性动作**,还会对别的环境 / 别的分支 / 下一次改表再做一遍 —— 例如改完表结构要**同步某个环境的 DDL**、跑数据库迁移或回滚、生成代码、打包、起 dev server、往某个环境部署、按固定步骤清洗数据。这时**别默默每次手搓命令**(下次还得从头猜一遍),也**别自己动手建**:**先问用户**"这个流程以后要反复跑,要不要固化成一个 Shell run configuration?",并把方案摊开:配置名、实际执行的命令(`scriptText`,或它指向的 `scriptPath`)、工作目录、为什么值得留。**同意才建**;用户说这次先这样,就照办,别再追着问。
+  - **不会 → 用原生 `shell` 直接跑,别建**。这就是两者的分界线:原生 `shell` 是**就地执行、用完不留痕**(命令只存在于会话里);`create_shell_run_configuration` 是**把命令落盘成 `.run/<name>.run.xml`、往后反复用**(它产出的是项目文件,IDE 的 Run 窗口里也会多一项)。所以一次性的、探索性的、调试性的、参数每次都不一样的操作(查条数据、看个日志、试一条命令、临时换个路径跑一下)一律走 `shell` 跑完算 —— 这类东西建配置只是给项目留垃圾。确需项目环境的解释器时,在 `shell` 命令里显式指定、或在已有配置上单次覆盖参数,也别为这一次性的事新建配置。
+  - **建之前先查,防泛滥**:先 `get_run_configurations` 看有没有已在做同一件事的配置 —— 有就**复用**(必要时让用户改它),别新建一个几乎一样的;同一件事**不要按参数 / 按文件 / 按环境拆成一堆配置**,变化的入参用 `programArguments` / `envs` 单次覆盖。一个项目通常就那么**几个**(构建、装依赖、起服务、迁移这类固定流程);配置数量明显长起来就是滥用信号 —— 动手前先问自己:这是项目固定流程,还是我只是想省一条 shell 命令?
 {{/if}}
 {{#if canListRunningConfigurations}}
 - {{cmd_list_running_configurations}}
@@ -109,10 +129,37 @@
 - {{cmd_rerun_run_configuration}}
   **改完代码重启无热重载的进程**:在跑就重启、没在跑就启动;读 `started` 判断新进程是否真的起来了。不要用 `pkill` / `kill` / `shell` 代替。
 {{/if}}
+{{#if canListDeploymentServers}}
+
+### 服务器文件同步
+
+往服务器传文件 / 从服务器取文件,走这一组 —— **别用 `ssh` / `rsync` / `scp` 自己拼一份**:IDE 的连接、路径映射、排除规则都在它们后面,自己拼的不是 IDE 在管的那一份。
+
+- {{cmd_list_deployment_servers}}
+  **本项目能用的部署服务器**:名称(后面几条用它当 `serverName`)、项目级还是应用级、协议、host / port、在本项目里的路径映射,以及**项目级**的部署选项与危险组合告警。**只读 IDE 配置、不联网**;动手前先看 `warnings[]`。
+{{#if canUploadToDeployment}}
+- {{cmd_upload_to_deployment}}
+  **把映射到的本地目录传到服务器**(等同 IDE 的 Upload to …)。`mode` 默认 `mirror` —— **会删掉服务器上多出来的文件**,使两边一致;要留住它们就传 `upload`。**破坏性操作**。
+{{/if}}
+{{#if canDownloadFromDeployment}}
+- {{cmd_download_from_deployment}}
+  **把服务器上映射目录的内容拉回本地**(等同 IDE 的 Download from …),**以服务器为准**:两边都有的文件会被远端覆盖(内容相同则不写)。**没有"保留我的版本"这个选项**。
+{{/if}}
+{{#if canGetDeploymentTaskStatus}}
+- {{cmd_get_deployment_task_status}}
+  **查一次传输的状态**:`handle` 用上传 / 下载返回的那个 —— **它自己不启动任何传输**。
+{{/if}}
+
+上传 / 下载都在 IDE 后台跑,单次调用只等到 `waitMs`(默认 10 秒)为止;返回 `in_progress` 是**正常**的,不是失败 —— 拿 `handle` 去查进度,**别用重复调上传 / 下载代替**(那样拿不到进度)。
+{{/if}}
 
 ## 命令执行(所有项目通用)
 
 - 需要项目环境的命令(依赖 IDE 里配好的 JDK / Node / Python 版本等):用该项目前缀的 run configuration 工具,不要用原生 `shell`。
-- run configuration 是**重资产**:一个项目通常只建几个(固定要跑的构建 / 装依赖 / dev server 之类),**不是随手一条命令就建一个**。要新建时先确认它**反复要用、且属于项目固定流程**,再**先告诉用户要建什么、为什么,取得同意才动手**,别自己决定。
-- **配置一律不由你写**:不要手写 `.run/*.run.xml`,也不要手搓启动命令。
+- 写 `.run/*.run.xml` **只走 `idea-run-config-manager` skill**:它有逐类型模板(`assets/types/`),写完还要复查。**平时不要自己手写配置,也不要用一条裸命令代替配置。**
+{{#if canCreateRunConfiguration}}
+- 要固化的固定流程(判据见上:会不会以同样形态重复发生):Shell 类型用上面那个「新建项目级 Shell 配置」建;非 Shell 类型与删 / 改,交给用户调 `idea-run-config-manager` skill。
+{{else}}
+- 要固化的固定流程:把配置名、实际执行的命令、工作目录、为什么值得留讲清楚,**请用户在 IDE 里自己建** —— 当前没有能建它的工具(`idea-run-config-manager` skill 的门就是这个工具,所以它这次也不会出现),不要手写文件凑。
+{{/if}}
 - 不需要项目环境的命令:用原生 `shell`。

package/src/ide-projects.js

@@ -246,7 +246,7 @@ export function parseSubprojectArgument(text) {
 /**
  * 从参数文本里切出 IDE 名。
  *
- * `/open-in-idea pycharm` 是"AI 不配合时的直通逃生口"：正常流程由 AI 向用户提问后
+ * `/open-in-ide pycharm` 是"AI 不配合时的直通逃生口"：正常流程由 AI 向用户提问后
  * 调工具写回，带参只是保险。空串表示"没给"，由调用方决定是提问还是用默认值。
  *
  * @param {unknown} text

package/src/mcp/enhance.js

@@ -8,17 +8,27 @@
 //   * 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.
+// The companion plugin (https://github.com/syllr/idea-mcp-enhance) fills gaps the
+// bundled server leaves in two places:
+//
+//   * run configuration — the bundled server can only START an existing
+//     configuration; it cannot create one, stop one, restart one, or say what is
+//     currently running;
+//   * deployment — the bundled server has nothing at all for the IDE's
+//     Deployment settings or for moving files to/from a server.
+//
+// The two are kept as separate groups everywhere (here, in the capability
+// functions, and in the guidance), because they are NOT the same precondition:
+// deployment additionally needs `com.jetbrains.plugins.webDeployment`, which
+// exists only in Ultimate. One boolean covering both would let a deployment tool
+// answer "are the run-lifecycle tools here?".
 //
 // 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`).
+// has to be gated on the tools really being in the request.
 
 /**
- * The enhance plugin's tool names, as **suffixes**.
+ * The enhance plugin's **run-lifecycle** 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
@@ -45,6 +55,48 @@ export const RUN_LIFECYCLE_SUFFIXES = [
   RERUN_RUN_CONFIGURATION_SUFFIX,
 ];
 
+/**
+ * The enhance plugin's **deployment** tool names, as suffixes — same contract and
+ * same reason for suffixes as {@link RUN_LIFECYCLE_SUFFIXES}.
+ *
+ * Keep in sync with `DeploymentSchemas.kt` in the enhance repository.
+ *
+ * The four are gated together on one plugin (`com.jetbrains.plugins.webDeployment`,
+ * Ultimate only) rather than on version drift, so they usually appear or vanish as
+ * a set — the guidance still names them one by one, because "usually" is not
+ * "always" and a named tool the model cannot call is only a failed call.
+ */
+export const LIST_DEPLOYMENT_SERVERS_SUFFIX = 'list_deployment_servers';
+export const UPLOAD_TO_DEPLOYMENT_SUFFIX = 'upload_to_deployment';
+export const DOWNLOAD_FROM_DEPLOYMENT_SUFFIX = 'download_from_deployment';
+export const GET_DEPLOYMENT_TASK_STATUS_SUFFIX = 'get_deployment_task_status';
+
+/** All of them: look at the servers, upload, download, then poll a transfer. */
+export const DEPLOYMENT_SUFFIXES = [
+  LIST_DEPLOYMENT_SERVERS_SUFFIX,
+  UPLOAD_TO_DEPLOYMENT_SUFFIX,
+  DOWNLOAD_FROM_DEPLOYMENT_SUFFIX,
+  GET_DEPLOYMENT_TASK_STATUS_SUFFIX,
+];
+
+/**
+ * Does this request carry the tool called `suffix` under `prefix`?
+ *
+ * A malformed or missing snapshot answers "no": assuming a tool exists is the one
+ * mistake that cannot be walked back once the model has read the guidance.
+ *
+ * Exported because the guidance asks this twice. The capability flags (below) ask
+ * "does this request have the tool somewhere" (any project will do); the command
+ * list next to each tool asks "under WHICH prefix", and that answer must be exact —
+ * 提示词里点名一个模型调不到的命令,是这个模块唯一要防的失败。
+ *
+ * @param {Record<string, unknown> | undefined} tools
+ * @param {string} prefix 该项目的工具前缀（含下划线）。
+ * @param {string} suffix
+ */
+export const servesTool = (tools, prefix, suffix) =>
+  Boolean(tools) && typeof tools === 'object' && `${prefix}${suffix}` in tools;
+
 /**
  * Which of the enhance plugin's tools **this project's prefix** carries in this
  * request.
@@ -60,12 +112,30 @@ export const RUN_LIFECYCLE_SUFFIXES = [
  * @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),
+    canCreateRunConfiguration: servesTool(tools, prefix, CREATE_SHELL_RUN_CONFIGURATION_SUFFIX),
+    canListRunningConfigurations: servesTool(tools, prefix, LIST_RUNNING_CONFIGURATIONS_SUFFIX),
+    canStopRunConfiguration: servesTool(tools, prefix, STOP_RUN_CONFIGURATION_SUFFIX),
+    canRerunRunConfiguration: servesTool(tools, prefix, RERUN_RUN_CONFIGURATION_SUFFIX),
+  };
+}
+
+/**
+ * Same question for the deployment group, and the same answer shape — see
+ * {@link runLifecycleCapabilities}.
+ *
+ * The names repeat the tool's subject rather than the group (`canUploadToDeployment`,
+ * not `canUpload`): the guidance is one document about two groups, and a flag whose
+ * owner is unclear is how the wrong section gets the wrong text.
+ *
+ * @param {Record<string, unknown> | undefined} tools
+ * @param {string} prefix 该项目的工具前缀（含下划线）。
+ */
+export function deploymentCapabilities(tools, prefix) {
+  return {
+    canListDeploymentServers: servesTool(tools, prefix, LIST_DEPLOYMENT_SERVERS_SUFFIX),
+    canUploadToDeployment: servesTool(tools, prefix, UPLOAD_TO_DEPLOYMENT_SUFFIX),
+    canDownloadFromDeployment: servesTool(tools, prefix, DOWNLOAD_FROM_DEPLOYMENT_SUFFIX),
+    canGetDeploymentTaskStatus: servesTool(tools, prefix, GET_DEPLOYMENT_TASK_STATUS_SUFFIX),
   };
 }

package/src/mcp/idea.js

@@ -13,7 +13,7 @@
 //     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
+//     the user triggers `/open-in-ide` for the project they want, so "server is
 //     up" is the only thing worth knowing.
 
 export const PROJECT_HEADER = 'IJ_MCP_SERVER_PROJECT_PATH';
@@ -127,7 +127,7 @@ export async function callTool(port, projectPath, name, args = {}, options = {})
       params: {
         protocolVersion: PROTOCOL_VERSION,
         capabilities: {},
-        clientInfo: { name: 'opencode-idea', version: '0.0.18' },
+        clientInfo: { name: 'opencode-idea', version: '0.0.19' },
       },
     });
     // The IDE's Streamable-HTTP endpoint binds follow-up requests to the session

package/src/plugin.js

@@ -14,17 +14,18 @@
 //      its own project through the `IJ_MCP_SERVER_PROJECT_PATH` header; injects
 //      per-project direct-call guidance; and hides the IDE tools that must not
 //      reach the model (for every prefix);
-//   2. registers `/open-in-idea` (接入 root 与其全部子项目), `/delete-in-ide`
+//   2. registers `/open-in-ide` (接入 root 与其全部子项目), `/delete-in-ide`
 //      (删掉整个配置) and `/add-sub-module-in-ide <路径>` (登记一个子项目),
 //      plus the `configure_ide_project` tool the MODEL calls to write the IDE a
 //      user picked into the config;
-//   3. registers the `idea-standalone` skill (marked projects only).
+//   3. registers the shipped skills (`skills/<id>/SKILL.md`) — marked projects
+//      only, and each one also gated on the IDE tools it drives.
 //
 // A root that was never configured is left untouched. Everything is manual:
 // setup does NOT probe or connect any IDE. The commands probe, open the IDE, and
 // load the MCP servers + guidance on demand.
 //
-// `/open-in-idea` opens each configured project in ITS OWN IDE, waits until its
+// `/open-in-ide` opens each configured project in ITS OWN IDE, waits until its
 // MCP endpoint is ready, registers it under its prefix, and keeps the config in
 // `ctx.storage`. 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
@@ -38,7 +39,7 @@
 //     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.
+//     session would stay tool-less until the user ran `/open-in-ide` 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 IDE tools no longer does;
@@ -54,7 +55,6 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import { callTool, serverConfig } from './mcp/idea.js';
-import { runLifecycleCapabilities } from './mcp/enhance.js';
 import { applyIdeToolDefaults, hideForcedArguments } from './mcp/idea-tool-defaults.js';
 import { currentProjectPath } from './project.js';
 import {
@@ -405,26 +405,26 @@ export function ideFeedback(result) {
       return list ? `IDE MCP 已连接并接入:${list}。` : 'IDE MCP 已连接。';
     }
     case 'tools-loading':
-      return 'IDE MCP 已连接,但原生 IDE 工具列表尚未完成注册。请稍后再次执行 /open-in-idea。';
+      return 'IDE MCP 已连接,但原生 IDE 工具列表尚未完成注册。请稍后再次执行 /open-in-ide。';
     case 'mcp-unavailable': {
       const where = nameOf(result?.project);
       const ide = appOf(result?.project);
       return result?.opened
-        ? `已请求打开/激活 ${where} 并等待 MCP 服务启动,但未检测到 MCP 服务。请在 ${ide} 中开启 MCP 服务(Settings → MCP Server,需 2026.2+)并启用 Brave Mode,然后再次执行 /open-in-idea。`
-        : `未检测到 ${where} 的 MCP 服务。请确认已打开,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后再次执行 /open-in-idea。`;
+        ? `已请求打开/激活 ${where} 并等待 MCP 服务启动,但未检测到 MCP 服务。请在 ${ide} 中开启 MCP 服务(Settings → MCP Server,需 2026.2+)并启用 Brave Mode,然后再次执行 /open-in-ide。`
+        : `未检测到 ${where} 的 MCP 服务。请确认已打开,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后再次执行 /open-in-ide。`;
     }
     case 'launch-failed':
-      return `无法拉起 ${nameOf(result?.project)}(未找到应用或启动失败)。请确认它已安装 —— 没装的话先装上,再重试 /open-in-idea。`;
+      return `无法拉起 ${nameOf(result?.project)}(未找到应用或启动失败)。请确认它已安装 —— 没装的话先装上,再重试 /open-in-ide。`;
     case 'disabled':
-      return '插件已通过 openInIde: false 关闭 IDE 启动。请手动打开 IDE,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后重试 /open-in-idea。';
+      return '插件已通过 openInIde: false 关闭 IDE 启动。请手动打开 IDE,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后重试 /open-in-ide。';
     case 'manual-launch':
-      return '当前系统不支持自动打开 IDE(仅 macOS 实现了启动)。请手动打开 IDE,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后再次执行 /open-in-idea。';
+      return '当前系统不支持自动打开 IDE(仅 macOS 实现了启动)。请手动打开 IDE,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后再次执行 /open-in-ide。';
     case 'deleted':
-      return '已删除本项目的 IDE 配置:已注销全部 IDE MCP 并清除配置。如需重新接入,请执行 /open-in-idea。';
+      return '已删除本项目的 IDE 配置:已注销全部 IDE MCP 并清除配置。如需重新接入,请执行 /open-in-ide。';
     case 'bad-argument':
       return `命令参数有误:${result?.message ?? ''}`;
     case 'not-configured':
-      return '当前项目还没有 IDE 配置。请先执行 /open-in-idea 接入根项目,再登记子项目。';
+      return '当前项目还没有 IDE 配置。请先执行 /open-in-ide 接入根项目,再登记子项目。';
     case 'invalid-subproject':
       return `无法登记子项目:${result?.message ?? ''}`;
     case 'needs-ide':
@@ -435,7 +435,7 @@ export function ideFeedback(result) {
 }
 
 /**
- * The text the MODEL sees for `/open-in-idea` feedback. It is explicitly a
+ * The text the MODEL sees for `/open-in-ide` feedback. It is explicitly a
  * notification, not a task: the model must only acknowledge it. The user sees
  * the clean notice instead, via `metadata.displayText`.
  */
@@ -850,7 +850,7 @@ export default {
      * `open -a` only requests activation/opening. A cold IDE needs time before
      * its bundled MCP server listens, so poll until the endpoint appears AND
      * answers for THIS project. This is the step that makes a single
-     * `/open-in-idea` enough on a cold start.
+     * `/open-in-ide` enough on a cold start.
      *
      * @param {{ path: string, app: string }} project
      * @returns {Promise<number | undefined>}
@@ -946,7 +946,7 @@ export default {
     };
 
     /**
-     * `/open-in-idea` 的主流程：让每个已登记项目的 IDE 都就绪，然后把它们注册进
+     * `/open-in-ide` 的主流程：让每个已登记项目的 IDE 都就绪，然后把它们注册进
      * OpenCode。
      *
      * 每个项目各自拉起**自己的** IDE —— root 在 IDEA、某子项目在 PyCharm 是常态，
@@ -970,7 +970,7 @@ export default {
       let toolsReady = false;
       try {
         // 重新探测一次并整体注册：ensureProject 只保证 IDE 就绪，注册要按"当前真正
-        // 打开着哪些项目"重来一遍，这样 `/open-in-idea` 每次都是同一套结果。
+        // 打开着哪些项目"重来一遍，这样 `/open-in-ide` 每次都是同一套结果。
         toolsReady = (await reconcile({ probeIde: true })) === true;
       } catch {
         // capability load is best effort; feedback still matters
@@ -987,7 +987,7 @@ export default {
      * 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
+     * until `/open-in-ide` 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.
      *
@@ -1065,20 +1065,21 @@ export default {
     const isSameSkillSet = (skills, ids) =>
       skills.length === ids.length && skills.every((skill, index) => skill.id === ids[index]);
 
-    // The shipped skills are static knowledge (`skills/<id>/SKILL.md`), e.g. the
-    // standalone-mode discipline (every app starts from an IDEA run
-    // configuration, and starting one is the user's call, so the skill has to be
-    // there to write the project's own rules). They pass two independent gates,
+    // The shipped skills are static knowledge (`skills/<id>/SKILL.md`) that write
+    // a project's own rules into its `AGENTS.md`: `idea-standalone` fixes how
+    // resident apps are started, `idea-run-config-manager` fixes which repeated
+    // flows are solidified into configurations. They pass two independent gates,
     // because a skill can be wrong twice over:
     //
     //   * the project config — an unrelated project never sees an IDE skill;
     //   * the tools the IDE actually serves — a skill that teaches a call the
     //     model cannot make is not knowledge, it is a failed call waiting to
-    //     happen. `idea-standalone` drives `rerun_run_configuration`, which only
-    //     the companion plugin `idea-mcp-enhance` serves, so a stock IDE must not
-    //     see it at all. Each skill declares its own dependency in its frontmatter
-    //     (`requires:`), as a SUFFIX — tool names carry a per-project prefix, so
-    //     a hard-coded `idea_...` could only ever match one project.
+    //     happen. Both skills drive tools that only the companion plugin
+    //     `idea-mcp-enhance` serves (rerun for standalone, create for the
+    //     manager), so a stock IDE must not see them at all. Each skill declares
+    //     its own dependency in its frontmatter (`requires:`), as a SUFFIX — tool
+    //     names carry a per-project prefix, so a hard-coded `idea_...` could only
+    //     ever match one project.
     //
     // The catalog is unknown at setup: the config is read from storage offline,
     // before anything has connected to the IDE. So this is a reconcile rather
@@ -1089,7 +1090,7 @@ export default {
     // Deliberately NOT wrapped in a catch: these are core features of the plugin,
     // so a rejected definition must fail loudly. Swallowing it would ship a
     // silently incomplete plugin — which is exactly how 0.0.6 lost
-    // `/open-in-idea` without anyone noticing until the command was gone.
+    // `/open-in-ide` without anyone noticing until the command was gone.
     const syncSkillsOnce = async () => {
       if (typeof ctx.skill?.transform !== 'function') return;
 
@@ -1138,7 +1139,7 @@ export default {
     };
     // A project configured in an earlier run gets its skills as soon as the IDE
     // has answered; a project configured for the first time gets them when
-    // `/open-in-idea` runs (both paths go through `writeConfig` / this setup hook).
+    // `/open-in-ide` runs (both paths go through `writeConfig` / this setup hook).
     await syncSkills();
 
     /**
@@ -1227,7 +1228,7 @@ export default {
         return { content: `已把根项目配置为 ${IDE_LABELS[ide]} 并接入。` };
       }
       if (!current) {
-        return { content: '当前项目还没有 IDE 配置。请先执行 /open-in-idea。' };
+        return { content: '当前项目还没有 IDE 配置。请先执行 /open-in-ide。' };
       }
       const absPath = resolve(projectPath, rawPath);
       if (!existsSync(absPath)) {
@@ -1268,15 +1269,15 @@ export default {
       execute: async (args) => configureIdeProject(args),
     });
 
-    // `/open-in-idea` 接入 root 与其全部子项目；`/add-sub-module-in-ide <路径>` 登记
+    // `/open-in-ide` 接入 root 与其全部子项目；`/add-sub-module-in-ide <路径>` 登记
     // 一个子项目（IDE 由模型问用户后写回）；`/delete-in-ide` 删除整个配置。
     //
-    // 命名说明：命令名里的 `idea` 是历史包袱（工具前缀早已改成与产品无关的 `ide_`），
-    // 保留它是为了不改用户天天敲的名字；它的语义是"接入 IDE"，不是"接入 IntelliJ"。
+    // 三个名字都带 `-ide` 而不是 `-idea`：这里说的是"接入 IDE"，与具体产品无关 —— root 可能是
+    // IDEA、子项目可能是 PyCharm，和工具前缀（`ide_*` / `<目录名>_*`）是同一套口径。
     if (typeof ctx.command?.transform === 'function') {
       commandRegistration = await ctx.command.transform((editor) => {
         editor.add({
-          name: 'open-in-idea',
+          name: 'open-in-ide',
           description: '接入当前项目:root 及其全部已登记子项目,各自用配置好的 IDE 打开',
           execute: async (input) => {
             const parsed = parseIdeArgument(input?.prompt?.text);
@@ -1350,7 +1351,7 @@ export default {
           execute: async (input) => {
             await writeConfig(null);
             // 注销全部 server。走串行化的 reconcile，所以在飞的重建（另一个
-            // `/open-in-idea`、请求期自愈）不会在配置已删之后再注册回来。
+            // `/open-in-ide`、请求期自愈）不会在配置已删之后再注册回来。
             await reconcile({ probeIde: false });
             await sendFeedback(input, { status: 'deleted' });
           },
@@ -1420,8 +1421,8 @@ export default {
         // they are actually in this request.
         if (!serving) return;
         // 逐项目注入：每个项目那一节只写它自己的前缀，模型不需要自己换算。
-        // run-lifecycle 工具（来自配套插件 `idea-mcp-enhance`）也按每个项目分别判断,
-        // 所以一个项目装了 enhance、另一个没装时，两节的内容本来就不一样。
+        // 配套插件 `idea-mcp-enhance` 的两组工具（run-lifecycle / deployment）也按每个项目分别判断,
+        // 所以一个项目装了 enhance、另一个没装时，各节的内容本来就不一样。
         appendIdeGuidance(event?.system, currentProjects(), { tools });
       });
 
@@ -1434,7 +1435,7 @@ export default {
       //   * `registrations.length === 0` — 本插件实例压根没有注册任何 IDE server,这
       //     正是 OpenCode 回收 Location 服务(LayerMap idleTimeToLive = 60 分钟)
       //     或进程重启后新实例的样子。setup 故意不连接,没有这一步会话就会永久
-      //     没有工具,只能靠用户手敲 `/open-in-idea`。
+      //     没有工具,只能靠用户手敲 `/open-in-ide`。
       //
       // 只探测、不启动 IDE:走 `reconcile({ probeIde: true })`,而不是会 `open -a`
       // 的 `reviveIde()` —— 一条用户消息不该把 IDE 拉起来。

package/src/skill/loader.js

@@ -27,6 +27,13 @@
 // and deliberately kept OUT of the registered definition — the caller filters on
 // it instead (see `readSkills`), because a skill whose tools are absent must not
 // be registered at all.
+//
+// The other key is OpenCode's own, written in the portable frontmatter spelling
+// OpenCode documents: a nested `metadata:` block holding
+// `opencode/autoinvoke: false`. It is translated to the definition's
+// `autoinvoke` — the name the registration API uses — which is what makes a
+// skill user-invoked only: OpenCode keeps it registered and loadable on request,
+// but leaves it out of the model's available list.
 
 import { readFileSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -87,11 +94,37 @@ function splitList(value) {
     .filter((entry) => entry !== '');
 }
 
+/**
+ * Read `opencode/autoinvoke` out of the frontmatter, or `undefined` when absent.
+ *
+ * The spelling is OpenCode's portable one — a nested `metadata:` block holding
+ * `opencode/autoinvoke: false`. That shape is exactly what the flat reader above
+ * already produces: the indented line trims to `opencode/autoinvoke: false` and
+ * lands under that namespaced key, while the bare `metadata:` line comes out
+ * empty and is ignored. One nesting level is therefore supported on purpose, not
+ * by accident.
+ *
+ * The value must be `true` or `false`. Anything else throws: a typo that
+ * silently left the skill model-invocable is the failure this whole mechanism
+ * exists to prevent, so it must not pass quietly.
+ *
+ * @param {Record<string, string>} fields
+ * @param {string} source Used in error messages.
+ * @returns {boolean | undefined}
+ */
+export function readAutoinvoke(fields, source) {
+  const raw = fields['opencode/autoinvoke'];
+  if (raw === undefined) return undefined;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  throw new Error(`${source}: "opencode/autoinvoke" must be true or false, got "${raw}"`);
+}
+
 /**
  * Load one skill directory into a `Skill.Info`-shaped definition.
  *
  * @param {string} id Directory name, used as the skill id.
- * @returns {{ id: string, name: string, description: string, path: string, content: string }}
+ * @returns {{ id: string, name: string, description: string, autoinvoke?: boolean, path: string, content: string }}
  */
 export function readSkill(id) {
   return readSkillPackage(id).skill;
@@ -104,8 +137,13 @@ export function readSkill(id) {
  * while `requires` is this package's own metadata and must NOT be registered —
  * it is what the caller filters on.
  *
+ * `autoinvoke` is OpenCode's, so it goes the other way: it ships in the
+ * frontmatter as `opencode/autoinvoke` and is translated onto the definition,
+ * where it picks user-invoked-only over model-invocable. It is only set when the
+ * frontmatter asks for it, so a skill that says nothing keeps the plain shape.
+ *
  * @param {string} id Directory name, used as the skill id.
- * @returns {{ skill: { id: string, name: string, description: string, path: string, content: string }, requires: string[] }}
+ * @returns {{ skill: { id: string, name: string, description: string, autoinvoke?: boolean, path: string, content: string }, requires: string[] }}
  */
 export function readSkillPackage(id) {
   const file = new URL(`${id}/${SKILL_FILE_NAME}`, SKILLS_DIR);
@@ -116,11 +154,13 @@ export function readSkillPackage(id) {
   if (!description) {
     throw new Error(`${source}: frontmatter needs a "description", otherwise the skill is never offered`);
   }
+  const autoinvoke = readAutoinvoke(fields, source);
   return {
     skill: {
       id,
       name: fields.name || id,
       description,
+      ...(autoinvoke === undefined ? {} : { autoinvoke }),
       path: fileURLToPath(file),
       content: text.replace(FRONTMATTER, '').replace(/^\s+/, '').trimEnd(),
     },
@@ -131,7 +171,7 @@ export function readSkillPackage(id) {
 /**
  * Every shipped skill, sorted by id, each with the tools it requires.
  *
- * @returns {Array<{ skill: { id: string, name: string, description: string, path: string, content: string }, requires: string[] }>}
+ * @returns {Array<{ skill: { id: string, name: string, description: string, autoinvoke?: boolean, path: string, content: string }, requires: string[] }>}
  */
 export function readSkills() {
   return readdirSync(SKILLS_DIR, { withFileTypes: true })