opencode-idea 0.0.17 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-idea",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "OpenCode plugin that connects to JetBrains IDE MCP servers and prefers IDE tools when the current project is open in the IDE",
   "main": "src/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
     "src/plugin.js",
     "src/template.js",
     "src/ide-guidance.template.md",
+    "src/ide-projects.js",
     "src/mcp/idea.js",
     "src/mcp/enhance.js",
     "src/mcp/idea-tool-defaults.js",
@@ -39,6 +40,9 @@
   ],
   "author": "yutao",
   "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/syllr/opencode-idea.git"

package/skills/idea-run-config-manager/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: idea-run-config-manager
+requires: create_shell_run_configuration
+description: "管理本项目的 run configuration:直接增 / 删 / 改(新建走工具,改和删直接编辑 `.run/<配置名>.run.xml` —— 都照 `assets/types/` 里**逐类型实测模板**写,没有模板的类型交给用户在 IDE 里配),并把配置档案同步进**项目根 `AGENTS.md`** 里由 `<!-- idea-run-config-manager:begin -->` 与 `<!-- idea-run-config-manager:end -->` 包裹的标记块 —— 每个 run configuration 一行,写清它干什么、怎么跑、什么时候跑;服务化的那些不在这里,它们归 `idea-standalone` 的块。当用户要建 / 删 / 改 run configuration,或要一份"这个项目有哪些配置、各自干什么"的说明时使用。"
+metadata:
+  opencode/autoinvoke: false
+---
+
+# idea-run-config-manager — 增删改 run configuration + 维护配置档案
+
+**联动是硬要求**:配置被**新建 / 删除 / 修改**,文档就跟着**加行 / 删行 / 改行** —— 无论那次改动是谁做的(你做的、用户自己做的、用户删掉的,都算)。改了配置却忘了同步这张表,等于这张表在骗下一个读者。
+
+## 流程
+
+1. **读**:项目根 `AGENTS.md` —— 有没有 `<!-- idea-run-config-manager:begin -->` … `<!-- idea-run-config-manager:end -->` 标记块(有则更新,没有就在文件末尾追加);同时读同文件里 `idea-standalone` 的标记块,它登记过的配置不进本表。
+2. **枚举**:逐个项目用**它自己那个前缀**的 `<前缀>_get_run_configurations` 直接调用,不传参数 —— 本项目的工具前缀跟着接入时的名字走(root 是 `ide`,子项目是它的目录名)。
+3. **建 / 删 / 改**(**直接动手**):
+   1. **先查重**:已经在做同一件事的配置直接复用,不要新建一个几乎一样的。
+   2. **按类型找模板** —— 查下面的支持矩阵:
+      - **有模板** → 照 [assets/types/](assets/types/) 里那份 `.md` 写文件。**Shell Script 类型**用 `<前缀>_create_shell_run_configuration` 新建;**其余类型**直接写 `.run/<配置名>.run.xml`;**改和删**就是编辑 / 删掉那个文件。
+      - **没有模板**(⏳ 或矩阵之外)→ **交给用户**:讲清要配什么(配置名、干什么、什么时候跑),请他在 IDE 里配好,你只负责把档案补上。
+   3. **写完必须复查**:`<前缀>_get_run_configurations` 里要能看到它。**看不到就是文件没被 IDE 认** —— `type` 写错会被静默忽略且不报错,回去查 `type` / 文件位置 / 信封。
+   4. **不要手搓启动命令**代替配置,也**不要写模板里没有的字段**(多余字段被忽略、名字写错静默用默认值,都不会报错)。
+4. **同步文档**:按 [assets/AGENTS.template.md](assets/AGENTS.template.md) 逐段填,写在标记块内 —— **表格列、每一列写什么、枚举与过滤的要求,都在那份模板的生成提示里**,动手前先读它;生成提示是给生成过程的说明,**产物里整块删掉**,块外一字不动(尤其**不要触碰**其他 skill 的标记块)。
+5. **核对**:表里每个名字项目里都还在,项目里每个配置表里都有。
+
+## 支持矩阵(一个类型一份模板)
+
+| 类型              | `type` id                       | 模板                                 | 验证程度                                  |
+| ----------------- | ------------------------------- | ------------------------------------ | ----------------------------------------- |
+| Shell Script      | `ShConfigurationType`           | [shell](assets/types/shell.md)       | ✅ 实物(本机 6 例,含 Windows)             |
+| Maven             | `MavenRunConfiguration`         | [maven](assets/types/maven.md)       | ✅ 实物                                   |
+| Gradle            | `GradleRunConfiguration`        | [gradle](assets/types/gradle.md)     | ✅ 实物                                   |
+| npm / yarn / pnpm | `js.build_tools.npm`            | [npm](assets/types/npm.md)           | ✅ 实物                                   |
+| Python            | `PythonConfigurationType`       | [python](assets/types/python.md)     | ✅ 实物                                   |
+| Go Build          | `GoApplicationRunConfiguration` | [go-build](assets/types/go-build.md) | ✅ 实物                                   |
+| Node.js           | `NodeJSConfigurationType`       | [node](assets/types/node.md)         | ⚠️ `type` 与三个属性已验证,其余字段未验证 |
+| Application       | `Application`                   | —                                    | ⏳ `type` 已验证,**字段层无实物**         |
+| JAR               | `JarApplication`                | —                                    | ⏳ 同上                                   |
+
+**矩阵之外一律没有模板** —— JUnit / TestNG / Kotlin / Docker / Spring Boot / Tomcat / Flyway / Liquibase / HTTP Request 等等。**没有模板的类型交给用户在 IDE 里自己新建、自己维护**,模板由我们后续按需补上。
+
+## 硬性契约(所有类型都一样)
+
+1. **落地位置**:项目根的 `.run/<配置名>.run.xml`(配置名带空格就原样用,例如 `Hello World.run.xml`)。子项目的配置写在**子项目自己的** `.run/` 下,并用**子项目前缀**的工具复查。
+2. **信封固定**:
+
+   ```xml
+   <component name="ProjectRunConfigurationManager">
+     <configuration default="false" name="<配置名>" type="<类型ID>">
+       …该类型自己的字段…
+       <method v="2" />
+     </configuration>
+   </component>
+   ```
+
+   `factoryName="<类型名>"` **可写可不写** —— 实物里两种都有,IDE 认的是 `type`。
+
+3. **`type` 写错 = 整个文件被静默忽略,日志里也不报任何东西。** 每种类型都得有一份实测模板,就是为了不靠猜。
+4. **写完必须复查**(见流程第 3 步):`get_run_configurations` 里看不到,就是文件没被认。
+5. **路径宏**:`$PROJECT_DIR$` = 该项目根。同一台机器上的多个项目靠它区分,别写绝对路径。
+6. **不要加本类型没有的字段**:多余的字段被忽略,名字写错则静默用默认值 —— 两种都不会报错,但会得到一个"看起来配好了其实没生效"的配置。

package/skills/idea-run-config-manager/assets/AGENTS.template.md

@@ -0,0 +1,46 @@
+<!-- idea-run-config-manager:begin -->
+
+# run configuration 档案
+
+<!-- 生成提示:begin -->
+
+本块由 `idea-run-config-manager` skill 生成与维护:它是**项目里每个 run configuration 的说明书**。标记之外是项目自己在 `AGENTS.md` 里维护的内容,本 skill 一律不动;也只写这个项目 —— 不写全局配置目录,不另建规则文件。
+`{...}` 是待替换的元变量,不留进产物。未涉及的表格行整块删掉,不留空标题。
+**`<!-- 生成提示:… -->` 是给生成过程的说明,产物里整块删掉** —— 产物是给 AI 当规则读的,里面不该留指令。
+<!-- 生成提示:end -->
+
+这张表由 `idea-run-config-manager` 维护:配置被**新建 / 删除 / 修改**时,对应的行要跟着**加 / 删 / 改**。
+配置本身可以由 AI 直接增删改 —— 照 `assets/types/` 里那个类型的模板写 `.run/<配置名>.run.xml`;**没有模板的类型交给用户在 IDE 里配**。
+**服务化的配置不在本表** —— 它们已经登记在 `AGENTS.md` 的 `idea-standalone` 块里;本表收的是**其余**的 run configuration。
+
+## run configuration 一览
+
+<!-- 生成提示:begin -->
+
+**先过滤**:动手前读 `<项目根>/AGENTS.md` 里 `idea-standalone` 的标记块,把它的表里出现过的 run configuration 名字收集起来 —— **这些一律不进本表**(它们服务化 / 长驻,端口与热重载已在那边写清)。剩下的才是本表内容;没有那个块就不过滤。
+**枚举以工具为准**:各项目各有自己的工具前缀(root 是 `ide`,子项目是它的目录名),看哪个项目就用**它自己那个前缀**的工具 —— `<前缀>_get_run_configurations` 直接调用,不传参数,它给出 IDE 真正认的配置(含存在 `.idea/` 里的那些,单翻 `.run/` 目录看不到)。**项目与各子项目里真正存在的、过滤后剩下的都要有。**
+**项目**列写那套工具的前缀(root 写 `ide`,子项目写它的目录名):一条配置属于谁、该用哪套工具去看和跑,由这一列决定。
+`run configuration` 列必须是该前缀下**真实存在的名字**,不凭印象写;表里有、项目里已经没有的**整行删掉**。
+**按操作系统分成两张表**:macOS / Linux 一张,Windows 一张。同一份流程在两个平台上常常不是同一条命令(解释器不同、脚本后缀不同、路径写法不同),所以**按这个配置真正能跑的那个平台归表**,不要把 Windows 上才成立的命令写进 macOS 那张表。判断依据看配置里的解释器路径与脚本内容(例如 `INTERPRETER_PATH` 指向 PowerShell、命令里有 `\` 路径的,就是 Windows);**判断不了就问用户**,不猜。只在一个平台成立的流程就只写那一张表。
+
+**怎么跑**写走哪条工具:跑完即退的用 `<前缀>_execute_run_configuration`;长驻进程用 `<前缀>_rerun_run_configuration`(在跑就重启、没在跑就启动)。**不要**用 `execute` 跑长驻进程 —— 它是 Run 路径,对常驻进程**它会起出重复实例**。
+**何时跑**写触发场景(改完表结构 / 发版前 / 换分支后 / 只在联调时 …)。
+**跑前做**写**跑之前要先做的事**(先装依赖 / 先构建 / 先起某个服务):**多数留空**。确实得先做点什么才写,而且**按顺序写清第 1 步、第 2 步**。前置事项往往**不是**一个 run configuration(没有对应配置),所以只能写在这里 —— 漏了它,照着表跑的人会直接跑出一个起不来的流程。
+**说明**是这个配置唯一的自由文本格:**它是什么、干什么的**(同步某个环境的 DDL / 生成代码 / 跑迁移 …),以及有什么坑(必须先备份 / 只对某个环境生效 / 幂等与否 …)。
+分两件事都往这里写,**不要再单开一列**。写清它到底跑什么命令,就读它所在项目的落地文件 `.run/<name>.run.xml` 看里面的内容,拿不准就**问用户**,不猜。
+这张表的**主要价值**就在这一格:下次要办同类事情先在这里搜关键词,找得到就直接用,**不要再建一个重复的**。
+**目录、端口这类"配置里本来就有"的字段不要抄进来** —— 它们会跟配置变旧而对不上;确实要交代依赖关系,就写进 `说明` 或 `跑前做`。
+**列宽按同一约定**(中文两字 = 四个 dash,英文按字符数),**与 `idea-standalone` 的两张应用表公共列一一对位、宽度一致**(谁 / `run configuration` / `怎么跑` / `何时跑` / `跑前做` / `说明`);**各自的特有列插在自己的语义位置上** —— 那边的应用表多一格 `端口`(服务化应用一定有),本表没有,固定流程不是服务。**某格不适用就留空,不要写 `-`;填行时别去改表头的空格。**
+<!-- 生成提示:end -->
+
+### macOS / Linux
+
+| 项目 | run configuration | 怎么跑 | 何时跑 | 跑前做 | 说明 |
+| ---- | ----------------- | ------ | ------ | ------ | ---- |
+
+### Windows
+
+| 项目 | run configuration | 怎么跑 | 何时跑 | 跑前做 | 说明 |
+| ---- | ----------------- | ------ | ------ | ------ | ---- |
+
+<!-- idea-run-config-manager:end -->

package/skills/idea-run-config-manager/assets/types/go-build.md

@@ -0,0 +1,44 @@
+# Go Build(`GoApplicationRunConfiguration`)
+
+**用途**:跑一个 Go 程序(`go run` 那条路)。测试是另一个类型(`GoTestRunConfiguration`),**不在本模板范围**。
+
+## 模板
+
+```xml
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Server" type="GoApplicationRunConfiguration" factoryName="Go Application">
+    <module name="my-project" />
+    <working_directory value="$PROJECT_DIR$" />
+    <parameters value="--config ./_local/server/config.yaml" />
+    <envs>
+      <env name="ARMADA_LOG_CONFIG" value="config/logging-dev.yaml" />
+    </envs>
+    <kind value="FILE" />
+    <package value="github.com/owner/my-project" />
+    <directory value="$PROJECT_DIR$" />
+    <filePath value="$PROJECT_DIR$/cmd/server/main.go" />
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+## 字段
+
+| 字段                        | 含义                | 怎么填                                                                  |
+| --------------------------- | ------------------- | ----------------------------------------------------------------------- |
+| `module name`               | Go 模块             | 本项目真实的模块名                                                      |
+| `kind`                      | 跑什么              | `FILE`(文件)/ `DIRECTORY`(目录)/ `PACKAGE`(包)—— **和下面三个字段配套** |
+| `filePath`                  | `kind=FILE` 时      | 入口文件路径                                                            |
+| `directory`                 | `kind=DIRECTORY` 时 | 目录                                                                    |
+| `package`                   | `kind=PACKAGE` 时   | 包路径(实测样本里同时填了 `package`,可留)                               |
+| `working_directory`         | 工作目录            | `$PROJECT_DIR$`                                                         |
+| `parameters`                | 传给程序的参数      | 例如 `--config ./_local/server/config.yaml`                             |
+| `envs` → `<env name value>` | 环境变量            | 没有就整块删掉                                                          |
+
+## 坑
+
+- **字段写法和其他类型不一样**:这里是 `<working_directory value=…>` 这种**自定义元素名**,不是 `<option name=…>`;照别的类型的写法套会被静默忽略。
+- **`kind` 与 `filePath`/`directory`/`package` 必须一致**:填了 `kind=FILE` 又给 `directory`,行为不可预期 —— 只填对应的那一个。
+- `parameters` 里是**给程序**的参数,不是 `go build` 的参数;构建参数走 IDE 的 Go 配置项,别塞这里。
+- 实测样本的 `envs` 里塞了本机路径(`localhost:6379` 之类)—— 共享出去对别人不一定适用,这类值考虑换成读本地配置文件。
+- Go 服务通常是常驻进程:启停走 `rerun` / `stop`,不要 `pkill`(规则见 `idea-standalone`)。

package/skills/idea-run-config-manager/assets/types/gradle.md

@@ -0,0 +1,57 @@
+# Gradle(`GradleRunConfiguration`)
+
+**用途**:跑 Gradle 任务(`build`、`test`、`detekt`、`wasmJsBrowserDevelopmentRun` …)。
+
+## 模板
+
+```xml
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Build" type="GradleRunConfiguration" factoryName="Gradle">
+    <ExternalSystemSettings>
+      <option name="env">
+        <map>
+          <entry key="DEVELOPER_DIR" value="/Applications/Xcode.app/Contents/Developer" />
+        </map>
+      </option>
+      <option name="executionName" />
+      <option name="externalProjectPath" value="$PROJECT_DIR$" />
+      <option name="externalSystemIdString" value="GRADLE" />
+      <option name="scriptParameters" value="" />
+      <option name="taskDescriptions">
+        <list />
+      </option>
+      <option name="taskNames">
+        <list>
+          <option value="build" />
+        </option>
+      </option>
+      <option name="vmOptions" />
+    </ExternalSystemSettings>
+    <ExternalSystemDebugServerProcess>true</ExternalSystemDebugServerProcess>
+    <ExternalSystemReattachDebugProcess>true</ExternalSystemReattachDebugProcess>
+    <DebugAllEnabled>false</DebugAllEnabled>
+    <RunAsTest>false</RunAsTest>
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+## 字段
+
+| 字段                                               | 含义            | 怎么填                                                                                      |
+| -------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------- |
+| `taskNames` → `<list>`                             | 要跑的任务      | 每个任务一个 `<option value="…" />`;`:module:task` 形式可跨模块                             |
+| `scriptParameters`                                 | 参数            | 例如 `--stacktrace`;没有就留空                                                              |
+| `externalProjectPath`                              | Gradle 项目路径 | `$PROJECT_DIR$`                                                                             |
+| `externalSystemIdString`                           | 固定            | **`GRADLE`**,别改                                                                           |
+| `env` → `<map>`                                    | 环境变量        | `<entry key="K" value="V" />`;没有就整个 `<option name="env" />` 去掉(实测两个文件都有保留) |
+| `executionName` / `taskDescriptions` / `vmOptions` | —               | 没有就留空 / `<list />`                                                                     |
+| `RunAsTest`                                        | 是否当测试跑    | 一般 `false`                                                                                |
+| `DebugAllEnabled`                                  | —               | `false`                                                                                     |
+
+## 坑
+
+- **`externalSystemIdString` 必须是 `GRADLE`** —— 写别的值文件会被忽略(而且没有报错)。
+- 参数(`--info`、`-Pxxx`)放 `scriptParameters`,**不是** `taskNames`。
+- `env` 里像 `DEVELOPER_DIR` 这种本机特定路径,共享出去对别人无效 —— 换个不带绝对路径的做法(写进 `gradle.properties`)。
+- 多模块里跑别的模块的任务用 `:module:task`;`externalProjectPath` 仍指 Gradle 根。

package/skills/idea-run-config-manager/assets/types/maven.md

@@ -0,0 +1,61 @@
+# Maven(`MavenRunConfiguration`)
+
+**用途**:跑 Maven 目标(`clean package`、`test`、`spring-boot:run` …)。
+
+## 模板
+
+```xml
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="maven-package" type="MavenRunConfiguration" factoryName="Maven">
+    <MavenSettings>
+      <option name="myGeneralSettings" />
+      <option name="myRunnerSettings" />
+      <option name="myRunnerParameters">
+        <MavenRunnerParameters>
+          <option name="cmdOptions" />
+          <option name="profiles">
+            <set />
+          </option>
+          <option name="goals">
+            <list>
+              <option value="clean" />
+              <option value="package" />
+            </option>
+          </option>
+          <option name="multimoduleDir" />
+          <option name="pomFileName" value="pom.xml" />
+          <option name="profilesMap">
+            <map />
+          </option>
+          <option name="projectsCmdOptionValues">
+            <list />
+          </option>
+          <option name="resolveToWorkspace" value="false" />
+          <option name="workingDirPath" value="$PROJECT_DIR$" />
+        </MavenRunnerParameters>
+      </option>
+    </MavenSettings>
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+## 字段
+
+| 字段                       | 含义           | 怎么填                                                 |
+| -------------------------- | -------------- | ------------------------------------------------------ |
+| `goals` → `<list>`         | 要跑的目标     | 每个目标一个 `<option value="…" />`,顺序就是命令行顺序 |
+| `pomFileName`              | 哪个 pom       | 根项目 `pom.xml`;子模块填它自己的 pom 文件名           |
+| `workingDirPath`           | 工作目录       | `$PROJECT_DIR$` 或其子目录(实测有直接指向子模块目录的) |
+| `profiles` / `profilesMap` | Maven profile  | 不指定就保持 `<set />` / `<map />`                     |
+| `cmdOptions`               | 额外命令行参数 | 例如 `-DskipTests`;没有就留空                          |
+| `multimoduleDir`           | 多模块根目录   | 单模块留空                                             |
+| `projectsCmdOptionValues`  | 项目级参数列表 | 一般 `<list />`                                        |
+| `resolveToWorkspace`       | —              | 保持 `false`                                           |
+
+## 坑
+
+- **嵌套层级别少**:`MavenSettings` → `myRunnerParameters` → `MavenRunnerParameters`,三层都在才认;空的 `<set />` / `<map />` / `<list />` **不要删**(实测文件里都有)。
+- `pomFileName` 只写**文件名**,不要写相对路径。
+- 多模块项目:要么 `pomFileName` 指子模块,要么用 `multimoduleDir` 指根 —— 二选一,别都填。
+- 跑测试类目标(`-Dtest=…`)时 `cmdOptions` 里带 `-D`,不要放进 `goals`。

package/skills/idea-run-config-manager/assets/types/node.md

@@ -0,0 +1,30 @@
+# Node.js(`NodeJSConfigurationType`)
+
+**用途**:直接跑一个 `.js` / `.mjs` 入口。**跑 `package.json` 脚本请用 [npm.md](npm.md)** —— 那是另一回事。
+
+⚠️ **本模板验证程度有限**:`type` 与下面三个属性已由实物确认;**环境变量、Node 解释器等字段没有实物样本**,照抄本项目里已有配置的写法,或让用户在 IDE 里补,不要凭名字猜。
+
+## 模板(已验证的最小形态)
+
+```xml
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Drop metadb" type="NodeJSConfigurationType" path-to-js-file="$PROJECT_DIR$/packages/nocodb-legacy/src/run/deleteMetaDb.js" working-dir="$PROJECT_DIR$/packages/nocodb-legacy/src/run">
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+## 字段(已验证)
+
+| 字段                     | 形态     | 含义                                |
+| ------------------------ | -------- | ----------------------------------- |
+| `path-to-js-file`        | **属性** | 入口 JS 文件,`$PROJECT_DIR$/…`      |
+| `working-dir`            | **属性** | 工作目录                            |
+| `application-parameters` | **属性** | 传给脚本的参数(实物里是 `dev` 这种) |
+| `factoryName`            | 属性     | `Node.js`(实测有写、也有省略)       |
+
+## 坑
+
+- **这个类型用属性写法,不是 `<option>` 子元素** —— 照别的类型套会静默失效。
+- **能不用它就不用**:绝大多数"跑前端/跑服务"的场景,`js.build_tools.npm`(`<command value="run">` + 脚本名)才是团队共享配置的主流写法,也更好懂。
+- 需要环境变量(`dotenv`)或指定 Node 版本时,本模板没有可用字段 —— **照项目里已有的 Node.js 配置抄**,或让用户在 IDE 里配好再让你同步文档。

package/skills/idea-run-config-manager/assets/types/npm.md

@@ -0,0 +1,58 @@
+# npm / yarn / pnpm(`js.build_tools.npm`)
+
+**用途**:跑 `package.json` 里的脚本(dev / build / test)。三种包管理器**共用同一个 `type`**,靠 `<package-manager>` 区分。
+
+## 模板
+
+```xml
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="frontend" type="js.build_tools.npm">
+    <package-json value="$PROJECT_DIR$/frontend/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="dev" />
+    </scripts>
+    <node-interpreter value="project" />
+    <package-manager value="npm" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+## 字段
+
+| 字段                         | 含义              | 怎么填                                                            |
+| ---------------------------- | ----------------- | ----------------------------------------------------------------- |
+| `package-json`               | 哪个 package.json | `$PROJECT_DIR$/子目录/package.json`                               |
+| `command`                    | npm 子命令        | 跑脚本用 `run`                                                    |
+| `scripts` → `<script value>` | 脚本名            | `package.json` 里 `scripts` 的 key(`dev` / `build` / `test:unit`) |
+| `package-manager`            | 用哪个包管理器    | `npm` / `yarn` / `pnpm`(实测值就是这三个)                         |
+| `node-interpreter`           | Node 来源         | `project`(用项目里配的);用系统就填绝对路径                        |
+| `envs`                       | 环境变量          | 空就 `<envs />`                                                   |
+| `method`                     | 前置任务          | 默认空 `<method v="2" />`;需要"先跑别的再跑这个"才填(见下)        |
+
+## 跑之前先跑别的(build → dev)
+
+`<method v="2">` 里可以带前置任务:
+
+```xml
+    <method v="2">
+      <option name="NpmBeforeRunTask" enabled="true">
+        <package-json value="$PROJECT_DIR$/package.json" />
+        <command value="run" />
+        <scripts>
+          <script value="build" />
+        </scripts>
+        <node-interpreter value="project" />
+        <envs />
+      </option>
+    </method>
+```
+
+## 坑
+
+- **`<package-manager>` 决定实际用哪个包管理器跑**:项目用 pnpm 而这里写 `npm`,脚本里 `pnpm xxx` 的调用会跟外层打架。
+- 实测文件里还出现过两个 `<EXTENSION>`(better_direnv、StartBrowser)—— 那是别人本机插件加的,**别抄**,它们依赖本机插件,别人机器上没有。
+- 单仓多包(pnpm workspace / npm workspaces):`package-json` 指到**具体那个包**,不要指根再靠 scripts 转发。
+- `scripts` 里写多个脚本 = 按顺序跑同一个命令,不等于"先 A 后 B";顺序依赖要用上面的前置任务。

package/skills/idea-run-config-manager/assets/types/python.md

@@ -0,0 +1,59 @@
+# Python(`PythonConfigurationType`)
+
+**用途**:跑一个 Python 脚本(通常是服务入口)。**这个类型来自 Python 插件**(PyCharm 一定有,IDEA 装了 Python 插件也有)。
+
+## 模板
+
+```xml
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="backend" type="PythonConfigurationType" factoryName="Python">
+    <module name="my-project" />
+    <option name="ENV_FILES" value="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHONUNBUFFERED" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="SDK_NAME" value="my-project" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/backend/app" />
+    <option name="IS_MODULE_SDK" value="false" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <option name="DEBUG_JUST_MY_CODE" value="false" />
+    <option name="RUN_TOOL" value="" />
+    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/backend/app/main.py" />
+    <option name="PARAMETERS" value="" />
+    <option name="SHOW_COMMAND_LINE" value="false" />
+    <option name="EMULATE_TERMINAL" value="false" />
+    <option name="MODULE_MODE" value="false" />
+    <option name="REDIRECT_INPUT" value="false" />
+    <option name="INPUT_FILE" value="" />
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+## 字段
+
+| 字段                                                                                                            | 含义                               | 怎么填                                                                          |
+| --------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- |
+| `module name`                                                                                                   | 用哪个模块                         | **必须是这个项目里真实存在的模块名**,拿不准就问用户                             |
+| `SCRIPT_NAME`                                                                                                   | 入口脚本                           | `$PROJECT_DIR$/…/main.py`                                                       |
+| `PARAMETERS`                                                                                                    | 传给脚本的参数                     | 没有就空                                                                        |
+| `WORKING_DIRECTORY`                                                                                             | 工作目录                           | `$PROJECT_DIR$/…`(实测指向 `backend/app` 这种应用目录)                          |
+| `SDK_NAME` / `IS_MODULE_SDK` / `SDK_HOME`                                                                       | 用哪个解释器                       | `IS_MODULE_SDK=false` + `SDK_NAME` 填项目里配好的解释器名;本机路径写 `SDK_HOME` |
+| `ENV_FILES`                                                                                                     | dotenv 文件                        | 没有就空                                                                        |
+| `PARENT_ENVS`                                                                                                   | 继承父环境变量                     | `true`                                                                          |
+| `envs` → `<env name value>`                                                                                     | 额外环境变量                       | 例如 `PYTHONUNBUFFERED=1`(让日志实时)                                           |
+| `ADD_CONTENT_ROOTS` / `ADD_SOURCE_ROOTS`                                                                        | 把项目根 / 源码根加进 `PYTHONPATH` | `true`                                                                          |
+| `DEBUG_JUST_MY_CODE`                                                                                            | 只断自己的代码                     | `false`                                                                         |
+| `MODULE_MODE`                                                                                                   | 当模块跑(`python -m`)              | 一般 `false`                                                                    |
+| `SHOW_COMMAND_LINE` / `EMULATE_TERMINAL` / `REDIRECT_INPUT` / `INPUT_FILE` / `INTERPRETER_OPTIONS` / `RUN_TOOL` | —                                  | 按实测默认值留空 / `false`                                                      |
+
+## 坑
+
+- **`module name` 与 `SDK_NAME` 必须是本项目真实的模块 / 解释器名** —— 写错 IDE 会用不了,但不一定立刻报错。**先查项目里已有的 Python 配置照抄**,查不到就问用户。
+- 实测样本里带一个 `<EXTENSION ID="PythonCoverageRunConfigurationExtension" …/>`(覆盖率插件加的),**别抄**。
+- 依赖装在哪决定能不能跑:走项目解释器 + `ADD_SOURCE_ROOTS`,不要指向本机某个 venv 的绝对路径。
+- 服务类进程改代码后要重启才生效(没有热重载)—— 这条属于 `idea-standalone` 的纪律。

package/skills/idea-run-config-manager/assets/types/shell.md

@@ -0,0 +1,77 @@
+# Shell Script(`ShConfigurationType`)
+
+**用途**:一条固定命令或一个脚本文件 —— 构建、打包、生成代码、跑迁移、同步某个环境的 DDL、起服务。**绝大多数"反复要跑的固定流程"都归它,先别换类型。**
+
+## 二选一:脚本文本 / 脚本文件
+
+| 形态               | 关键字段                                                              | 用在什么时候                            |
+| ------------------ | --------------------------------------------------------------------- | --------------------------------------- |
+| **脚本文本**(默认) | `EXECUTE_SCRIPT_FILE="false"` + `SCRIPT_TEXT` 有值 + `SCRIPT_PATH` 空 | 就一条命令,不需要单独脚本文件           |
+| **脚本文件**       | `EXECUTE_SCRIPT_FILE="true"` + `SCRIPT_PATH` 有值 + `SCRIPT_TEXT` 空  | 命令已经写成仓库里的 `.sh`,或脚本比较长 |
+
+## 模板:脚本文本形态
+
+```xml
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="db-migrate" type="ShConfigurationType" factoryName="Shell Script">
+    <option name="SCRIPT_TEXT" value="pnpm -C packages/db generate&#10;pnpm -C packages/db migrate:deploy" />
+    <option name="INDEPENDENT_SCRIPT_PATH" value="true" />
+    <option name="SCRIPT_PATH" value="" />
+    <option name="SCRIPT_OPTIONS" value="" />
+    <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="true" />
+    <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="INDEPENDENT_INTERPRETER_PATH" value="true" />
+    <option name="INTERPRETER_PATH" value="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="EXECUTE_IN_TERMINAL" value="false" />
+    <option name="EXECUTE_SCRIPT_FILE" value="false" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+## 模板:脚本文件形态
+
+```xml
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="go-server" type="ShConfigurationType" factoryName="Shell Script">
+    <option name="SCRIPT_TEXT" value="" />
+    <option name="INDEPENDENT_SCRIPT_PATH" value="true" />
+    <option name="SCRIPT_PATH" value="$PROJECT_DIR$/go/run.sh" />
+    <option name="SCRIPT_OPTIONS" value="" />
+    <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="true" />
+    <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$/go" />
+    <option name="INDEPENDENT_INTERPRETER_PATH" value="true" />
+    <option name="INTERPRETER_PATH" value="/bin/zsh" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="EXECUTE_IN_TERMINAL" value="false" />
+    <option name="EXECUTE_SCRIPT_FILE" value="true" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+## 字段
+
+| 字段                                                                                                | 含义                           | 怎么填                                                                                                                                        |
+| --------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SCRIPT_TEXT`                                                                                       | 要执行的命令                   | **多行用 `&#10;` 分隔**(实测这么存的),不要塞真实换行                                                                                          |
+| `EXECUTE_SCRIPT_FILE`                                                                               | `false` 跑文本 / `true` 跑文件 | 决定上面两个字段谁生效                                                                                                                        |
+| `SCRIPT_PATH`                                                                                       | 脚本路径                       | `$PROJECT_DIR$/...`                                                                                                                           |
+| `SCRIPT_OPTIONS`                                                                                    | 传给脚本的参数                 | 没有就留空                                                                                                                                    |
+| `SCRIPT_WORKING_DIRECTORY`                                                                          | 工作目录                       | `$PROJECT_DIR$` 或其子目录;留空 = 项目根                                                                                                      |
+| `INDEPENDENT_SCRIPT_PATH` / `INDEPENDENT_SCRIPT_WORKING_DIRECTORY` / `INDEPENDENT_INTERPRETER_PATH` | 三处"各自独立"开关             | **保持实测值 `true`,别改**                                                                                                                    |
+| `INTERPRETER_PATH`                                                                                  | 解释器                         | macOS/Linux:`/bin/zsh`、`/bin/bash`,或**留空用 IDE 默认**(实测留空也能跑);Windows:`C:/Windows/System32/WindowsPowerShell/v1.0/powershell.exe` |
+| `INTERPRETER_OPTIONS`                                                                               | 解释器参数                     | 一般空                                                                                                                                        |
+| `EXECUTE_IN_TERMINAL`                                                                               | 是否开终端跑                   | **`false`** —— 共享出去的配置不要依赖本机终端                                                                                                 |
+| `envs`                                                                                              | 环境变量                       | 没有就 `<envs />`;有就 `<env name="K" value="V" />`                                                                                           |
+
+## 坑
+
+- **`EXECUTE_IN_TERMINAL` 必须是 `false`**:引导文本里"执行 Shell 配置要 `EXECUTE_IN_TERMINAL: false`"说的就是它,开成 true 的配置到了别人机器上行为不一样。
+- **`INDEPENDENT_INTERPRETER_PATH` 实测有两种**:解释器填了绝对路径的用 `true`(老写法),Windows 相对写法的那两个文件是 `false`。**照抄同项目里已有的那个**,别自己换。
+- Windows 解释器两种斜杠都实测出现过,`C:/...` 更稳(反斜杠在 XML 里要转义)。
+- `factoryName` 可以省略(实测有省略也能被认),但同一项目里**跟着已有文件的写法**更一致。
+- 文件里可以有 XML 注释说明这条配置实际跑的是什么(实测项目就这么写的),有助于后来的人看懂。

package/skills/idea-standalone/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: idea-standalone
-requires: idea_rerun_run_configuration
+requires: rerun_run_configuration
 description: "为项目生成/维护 standalone(启动收口只有 IDEA run configuration)模式的纪律,写进**项目根 `AGENTS.md`** 里由 `<!-- idea-standalone:begin -->` 与 `<!-- idea-standalone:end -->` 包裹的标记块。当用户要做 standalone 规范、要固化「本机跑哪几个应用」「哪些应用热重载、哪些改了必须重启」「启停走哪个工具」这类项目级纪律时使用。产物固定三段:standalone 是什么、经 IDEA run configuration 启动哪些应用、逐应用的热重载与重启提示纪律。"
 ---
 
@@ -19,13 +19,15 @@ description: "为项目生成/维护 standalone(启动收口只有 IDEA run conf
 
 ## 读取
 
+- **工具名前缀跟着项目走**:本项目的工具前缀由它接入时的名字决定 —— root 是 `ide`,子项目是它的目录名。下文的
+  `<前缀>_` 就是它(例如 `ide_get_run_configurations` 或 `modelserver_get_run_configurations`)。
 - 读 `<项目根>/AGENTS.md`,确认是否已存在 `idea-standalone` 标记块(更新)或需要在文件末尾追加(新增)。
-- **`idea_get_run_configurations` 直接调用,不传任何参数** → 项目里已有的 run configuration 就是**用户已经在 IDEA 里配好的那些**,
+- **该项目的 `<前缀>_get_run_configurations` 直接调用,不传任何参数** → 项目里已有的 run configuration 就是**用户已经在 IDEA 里配好的那些**,
   这一次调用会把它们的名字连同启动细节(程序参数、工作目录、环境变量、是否支持启动时覆盖)一并给出。
   第二段的 `run configuration` 列、以及端口,**只能来自这里** —— 不需要再去逐个翻 `.run/*.run.xml`,那份列表已经是配置的结果。
 - 项目类型(`package.json` / `pom.xml` / `go.mod` / `pyproject.toml` / `Cargo.toml`)→ 决定第三段的热重载列。
 - 端口:先看上面那份启动细节里有没有;项目自身配置里也读不到就**问用户**,不要编。
-- `run configuration` 列表里缺某个应用:**交给用户** —— 请他在 IDEA 里自己建一个,然后**重新查一次**。不要手搓启动命令,也不要自己写 `.run/*.run.xml`。
+- `run configuration` 列表里缺某个应用:**交给用户** —— 让他调 `idea-run-config-manager` skill 去建(那个 skill 管这个项目 run configuration 的增 / 删 / 改;工具列表里没有它时,请用户自己建一个),建完**重新查一次**。不要手搓启动命令,也不要自己写 `.run/*.run.xml`。
 - 补齐缺口:哪些应用进 standalone、哪些配置名对不上、端口与热重载不确定 —— **逐条向用户确认**,不猜。
 - 生成或更新前先读 [assets/AGENTS.template.md](assets/AGENTS.template.md),确认三段与各段生成提示。