opencode-idea 0.0.18 → 0.0.20

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.
Files changed (20) hide show
  1. package/README.md +215 -51
  2. package/package.json +1 -1
  3. package/skills/idea-run-config-manager/SKILL.md +62 -0
  4. package/skills/idea-run-config-manager/assets/AGENTS.template.md +58 -0
  5. package/skills/idea-run-config-manager/assets/types/go-build.md +44 -0
  6. package/skills/idea-run-config-manager/assets/types/gradle.md +57 -0
  7. package/skills/idea-run-config-manager/assets/types/maven.md +61 -0
  8. package/skills/idea-run-config-manager/assets/types/node.md +30 -0
  9. package/skills/idea-run-config-manager/assets/types/npm.md +58 -0
  10. package/skills/idea-run-config-manager/assets/types/python.md +59 -0
  11. package/skills/idea-run-config-manager/assets/types/shell.md +77 -0
  12. package/skills/idea-standalone/SKILL.md +1 -1
  13. package/skills/idea-standalone/assets/AGENTS.template.md +11 -7
  14. package/src/ide-guidance.js +85 -10
  15. package/src/ide-guidance.template.md +53 -6
  16. package/src/ide-projects.js +1 -1
  17. package/src/mcp/enhance.js +82 -12
  18. package/src/mcp/idea.js +2 -2
  19. package/src/plugin.js +39 -38
  20. package/src/skill/loader.js +43 -3
package/skills/idea-run-config-manager/assets/AGENTS.template.md ADDED
@@ -0,0 +1,58 @@
1
+ <!-- idea-run-config-manager:begin -->
2
+
3
+ # run configuration 档案
4
+
5
+ <!-- 生成提示:begin -->
6
+
7
+ 标记之外是项目自己在 `AGENTS.md` 里维护的内容,本 skill 一律不动;也只写这个项目 —— 不写全局配置目录,不另建规则文件。
8
+ `{...}` 是待替换的元变量,不留进产物。未涉及的条目与小节整块删掉,不留空标题。
9
+ **`<!-- 生成提示:… -->` 是给生成过程的说明,产物里整块删掉** —— 产物是给 AI 当规则读的,里面不该留指令。
10
+ <!-- 生成提示:end -->
11
+
12
+ 本项目里**除服务化应用之外**的 run configuration:每个配置**是什么、怎么跑、什么时候跑**;服务化(长驻应用)的配置登记在 `idea-standalone` 块里,不在这里。
13
+
14
+ 一条配置一个条目 —— 标题是**配置名**(括号里写它属于哪个项目),下面四项固定:`怎么跑`(走哪条工具去跑)/ `何时跑`(**谁能起它**:只由用户触发,还是 AI 判断到某个场景就自动跑)/ `跑前做`(跑之前要先做的事,多数没有)/ `说明`(它是什么、有什么坑)。
15
+
16
+ ## run configuration 一览
17
+
18
+ <!-- 生成提示:begin -->
19
+
20
+ **先过滤**:动手前读 `<项目根>/AGENTS.md` 里 `idea-standalone` 的标记块,把它登记过的 run configuration 名字收集起来 —— **这些一律不进本块**(它们服务化 / 长驻,端口与热重载已在那边写清)。剩下的才是本块内容;没有那个块就不过滤。
21
+ **枚举以工具为准**:各项目各有自己的工具前缀(root 是 `ide`,子项目是它的目录名),看哪个项目就用**它自己那个前缀**的工具 —— `<前缀>_get_run_configurations` 直接调用,不传参数,它给出 IDE 真正认的配置(含存在 `.idea/` 里的那些,单翻 `.run/` 目录看不到)。**项目与各子项目里真正存在的、过滤后剩下的都要有。**
22
+ **项目写在标题的括号里**(那套工具的前缀:root 写 `ide`,子项目写它的目录名):一条配置属于谁、该用哪套工具去看和跑,由它决定。
23
+ 标题里的配置名必须是该前缀下**真实存在的名字**,不凭印象写;块里有、项目里已经没有的**整个条目删掉**。
24
+ **按操作系统分成两节**:macOS / Linux 一节,Windows 一节。同一份流程在两个平台上常常不是同一条命令(解释器不同、脚本后缀不同、路径写法不同),所以**按这个配置真正能跑的那个平台归节**,不要把 Windows 上才成立的命令写进 macOS 那一节。判断依据看配置里的解释器路径与脚本内容(例如 `INTERPRETER_PATH` 指向 PowerShell、命令里有 `\` 路径的,就是 Windows);**判断不了就问用户**,不猜。只在一个平台成立的流程就只写那一节。
25
+
26
+ **怎么跑**写走哪条工具:跑完即退的用 `<前缀>_execute_run_configuration`;长驻进程用 `<前缀>_rerun_run_configuration`(在跑就重启、没在跑就启动)。**不要**用 `execute` 跑长驻进程 —— 它是 Run 路径,对常驻进程**它会起出重复实例**。
27
+ **何时跑**写**谁能起它、什么场景起它** —— 二选一,必须写明:
28
+
29
+ - **只由用户触发**:AI **不自己跑**,等用户开口;后面写用户通常在什么情况下会要它跑(发版前 / 出安装包 / 回归)。
30
+ - **AI 可自动触发**:AI 判断到这个场景就自己跑;后面**必须把场景写具体**(改完某类代码要生成代码 / 改了依赖要装依赖 / 改了 schema 要同步某个环境的 DDL),不写"需要时""合适时"。
31
+
32
+ 判断不了就问用户。**有副作用的流程(改远端、动数据、出产物)说不清场景就别标成 AI 可自动触发** —— 归第一种。
33
+ **跑前做**写**跑之前要先做的事**(先装依赖 / 先构建 / 先起某个服务):**多数没有,整项不写**。确实得先做点什么才写,而且**按顺序写清第 1 步、第 2 步**。前置事项往往**不是**一个 run configuration(没有对应配置),所以只能写在这里 —— 漏了它,照着本块跑的人会直接跑出一个起不来的流程。
34
+ **说明**是这个条目唯一的自由文本项:**它是什么、干什么的**(同步某个环境的 DDL / 生成代码 / 跑迁移 …),以及有什么坑(必须先备份 / 只对某个环境生效 / 幂等与否 …)。
35
+ 分两件事都往这里写,**不要再开新项**。写清它到底跑什么命令,就读它所在项目的落地文件 `.run/<name>.run.xml` 看里面的内容,拿不准就**问用户**,不猜。
36
+ 本块的**主要价值**就在**说明**与**跑前做**:下次要办同类事情先在这里搜关键词,找得到就直接用,**不要再建一个重复的**。
37
+ **目录、端口这类"配置里本来就有"的字段不要抄进来** —— 它们会跟配置变旧而对不上;确实要交代依赖关系,就写进 `说明` 或 `跑前做`。
38
+ **四项的项名与顺序不要改**(`怎么跑` / `何时跑` / `跑前做` / `说明`),并且**与 `idea-standalone` 应用表的列对得上**:三项同名同序(`怎么跑` / `跑前做` / `说明`),本块**多一项 `何时跑`**、那边**多一列 `端口`**(服务化应用就是"改完代码要起它来测"的时候起,不用单列时机)—— 两个块住在同一份 `AGENTS.md` 里,名字与顺序对上了,才看得出哪几条是服务、哪几条是固定流程。某一项确实没有内容就**整项不写**,不要写 `-` / `无` / `N/A`。
39
+
40
+ <!-- 生成提示:end -->
41
+
42
+ ### macOS / Linux
43
+
44
+ - {配置名}(项目 {前缀})
45
+ - 怎么跑:{<前缀>_execute_run_configuration}
46
+ - 何时跑:{只由用户触发 / AI 可自动触发} —— {什么场景}
47
+ - 跑前做:{第 1 步 / 第 2 步}
48
+ - 说明:{它是什么 + 有什么坑}
49
+
50
+ ### Windows
51
+
52
+ - {配置名}(项目 {前缀})
53
+ - 怎么跑:{<前缀>_execute_run_configuration}
54
+ - 何时跑:{只由用户触发 / AI 可自动触发} —— {什么场景}
55
+ - 跑前做:{第 1 步 / 第 2 步}
56
+ - 说明:{它是什么 + 有什么坑}
57
+
58
+ <!-- idea-run-config-manager:end -->
package/skills/idea-run-config-manager/assets/types/go-build.md ADDED
@@ -0,0 +1,44 @@
1
+ # Go Build(`GoApplicationRunConfiguration`)
2
+
3
+ **用途**:跑一个 Go 程序(`go run` 那条路)。测试是另一个类型(`GoTestRunConfiguration`),**不在本模板范围**。
4
+
5
+ ## 模板
6
+
7
+ ```xml
8
+ <component name="ProjectRunConfigurationManager">
9
+ <configuration default="false" name="Server" type="GoApplicationRunConfiguration" factoryName="Go Application">
10
+ <module name="my-project" />
11
+ <working_directory value="$PROJECT_DIR$" />
12
+ <parameters value="--config ./_local/server/config.yaml" />
13
+ <envs>
14
+ <env name="ARMADA_LOG_CONFIG" value="config/logging-dev.yaml" />
15
+ </envs>
16
+ <kind value="FILE" />
17
+ <package value="github.com/owner/my-project" />
18
+ <directory value="$PROJECT_DIR$" />
19
+ <filePath value="$PROJECT_DIR$/cmd/server/main.go" />
20
+ <method v="2" />
21
+ </configuration>
22
+ </component>
23
+ ```
24
+
25
+ ## 字段
26
+
27
+ | 字段 | 含义 | 怎么填 |
28
+ | --------------------------- | ------------------- | ----------------------------------------------------------------------- |
29
+ | `module name` | Go 模块 | 本项目真实的模块名 |
30
+ | `kind` | 跑什么 | `FILE`(文件)/ `DIRECTORY`(目录)/ `PACKAGE`(包)—— **和下面三个字段配套** |
31
+ | `filePath` | `kind=FILE` 时 | 入口文件路径 |
32
+ | `directory` | `kind=DIRECTORY` 时 | 目录 |
33
+ | `package` | `kind=PACKAGE` 时 | 包路径(实测样本里同时填了 `package`,可留) |
34
+ | `working_directory` | 工作目录 | `$PROJECT_DIR$` |
35
+ | `parameters` | 传给程序的参数 | 例如 `--config ./_local/server/config.yaml` |
36
+ | `envs` → `<env name value>` | 环境变量 | 没有就整块删掉 |
37
+
38
+ ## 坑
39
+
40
+ - **字段写法和其他类型不一样**:这里是 `<working_directory value=…>` 这种**自定义元素名**,不是 `<option name=…>`;照别的类型的写法套会被静默忽略。
41
+ - **`kind` 与 `filePath`/`directory`/`package` 必须一致**:填了 `kind=FILE` 又给 `directory`,行为不可预期 —— 只填对应的那一个。
42
+ - `parameters` 里是**给程序**的参数,不是 `go build` 的参数;构建参数走 IDE 的 Go 配置项,别塞这里。
43
+ - 实测样本的 `envs` 里塞了本机路径(`localhost:6379` 之类)—— 共享出去对别人不一定适用,这类值考虑换成读本地配置文件。
44
+ - Go 服务通常是常驻进程:启停走 `rerun` / `stop`,不要 `pkill`(规则见 `idea-standalone`)。
package/skills/idea-run-config-manager/assets/types/gradle.md ADDED
@@ -0,0 +1,57 @@
1
+ # Gradle(`GradleRunConfiguration`)
2
+
3
+ **用途**:跑 Gradle 任务(`build`、`test`、`detekt`、`wasmJsBrowserDevelopmentRun` …)。
4
+
5
+ ## 模板
6
+
7
+ ```xml
8
+ <component name="ProjectRunConfigurationManager">
9
+ <configuration default="false" name="Build" type="GradleRunConfiguration" factoryName="Gradle">
10
+ <ExternalSystemSettings>
11
+ <option name="env">
12
+ <map>
13
+ <entry key="DEVELOPER_DIR" value="/Applications/Xcode.app/Contents/Developer" />
14
+ </map>
15
+ </option>
16
+ <option name="executionName" />
17
+ <option name="externalProjectPath" value="$PROJECT_DIR$" />
18
+ <option name="externalSystemIdString" value="GRADLE" />
19
+ <option name="scriptParameters" value="" />
20
+ <option name="taskDescriptions">
21
+ <list />
22
+ </option>
23
+ <option name="taskNames">
24
+ <list>
25
+ <option value="build" />
26
+ </option>
27
+ </option>
28
+ <option name="vmOptions" />
29
+ </ExternalSystemSettings>
30
+ <ExternalSystemDebugServerProcess>true</ExternalSystemDebugServerProcess>
31
+ <ExternalSystemReattachDebugProcess>true</ExternalSystemReattachDebugProcess>
32
+ <DebugAllEnabled>false</DebugAllEnabled>
33
+ <RunAsTest>false</RunAsTest>
34
+ <method v="2" />
35
+ </configuration>
36
+ </component>
37
+ ```
38
+
39
+ ## 字段
40
+
41
+ | 字段 | 含义 | 怎么填 |
42
+ | -------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------- |
43
+ | `taskNames` → `<list>` | 要跑的任务 | 每个任务一个 `<option value="…" />`;`:module:task` 形式可跨模块 |
44
+ | `scriptParameters` | 参数 | 例如 `--stacktrace`;没有就留空 |
45
+ | `externalProjectPath` | Gradle 项目路径 | `$PROJECT_DIR$` |
46
+ | `externalSystemIdString` | 固定 | **`GRADLE`**,别改 |
47
+ | `env` → `<map>` | 环境变量 | `<entry key="K" value="V" />`;没有就整个 `<option name="env" />` 去掉(实测两个文件都有保留) |
48
+ | `executionName` / `taskDescriptions` / `vmOptions` | — | 没有就留空 / `<list />` |
49
+ | `RunAsTest` | 是否当测试跑 | 一般 `false` |
50
+ | `DebugAllEnabled` | — | `false` |
51
+
52
+ ## 坑
53
+
54
+ - **`externalSystemIdString` 必须是 `GRADLE`** —— 写别的值文件会被忽略(而且没有报错)。
55
+ - 参数(`--info`、`-Pxxx`)放 `scriptParameters`,**不是** `taskNames`。
56
+ - `env` 里像 `DEVELOPER_DIR` 这种本机特定路径,共享出去对别人无效 —— 换个不带绝对路径的做法(写进 `gradle.properties`)。
57
+ - 多模块里跑别的模块的任务用 `:module:task`;`externalProjectPath` 仍指 Gradle 根。
package/skills/idea-run-config-manager/assets/types/maven.md ADDED
@@ -0,0 +1,61 @@
1
+ # Maven(`MavenRunConfiguration`)
2
+
3
+ **用途**:跑 Maven 目标(`clean package`、`test`、`spring-boot:run` …)。
4
+
5
+ ## 模板
6
+
7
+ ```xml
8
+ <component name="ProjectRunConfigurationManager">
9
+ <configuration default="false" name="maven-package" type="MavenRunConfiguration" factoryName="Maven">
10
+ <MavenSettings>
11
+ <option name="myGeneralSettings" />
12
+ <option name="myRunnerSettings" />
13
+ <option name="myRunnerParameters">
14
+ <MavenRunnerParameters>
15
+ <option name="cmdOptions" />
16
+ <option name="profiles">
17
+ <set />
18
+ </option>
19
+ <option name="goals">
20
+ <list>
21
+ <option value="clean" />
22
+ <option value="package" />
23
+ </option>
24
+ </option>
25
+ <option name="multimoduleDir" />
26
+ <option name="pomFileName" value="pom.xml" />
27
+ <option name="profilesMap">
28
+ <map />
29
+ </option>
30
+ <option name="projectsCmdOptionValues">
31
+ <list />
32
+ </option>
33
+ <option name="resolveToWorkspace" value="false" />
34
+ <option name="workingDirPath" value="$PROJECT_DIR$" />
35
+ </MavenRunnerParameters>
36
+ </option>
37
+ </MavenSettings>
38
+ <method v="2" />
39
+ </configuration>
40
+ </component>
41
+ ```
42
+
43
+ ## 字段
44
+
45
+ | 字段 | 含义 | 怎么填 |
46
+ | -------------------------- | -------------- | ------------------------------------------------------ |
47
+ | `goals` → `<list>` | 要跑的目标 | 每个目标一个 `<option value="…" />`,顺序就是命令行顺序 |
48
+ | `pomFileName` | 哪个 pom | 根项目 `pom.xml`;子模块填它自己的 pom 文件名 |
49
+ | `workingDirPath` | 工作目录 | `$PROJECT_DIR$` 或其子目录(实测有直接指向子模块目录的) |
50
+ | `profiles` / `profilesMap` | Maven profile | 不指定就保持 `<set />` / `<map />` |
51
+ | `cmdOptions` | 额外命令行参数 | 例如 `-DskipTests`;没有就留空 |
52
+ | `multimoduleDir` | 多模块根目录 | 单模块留空 |
53
+ | `projectsCmdOptionValues` | 项目级参数列表 | 一般 `<list />` |
54
+ | `resolveToWorkspace` | — | 保持 `false` |
55
+
56
+ ## 坑
57
+
58
+ - **嵌套层级别少**:`MavenSettings` → `myRunnerParameters` → `MavenRunnerParameters`,三层都在才认;空的 `<set />` / `<map />` / `<list />` **不要删**(实测文件里都有)。
59
+ - `pomFileName` 只写**文件名**,不要写相对路径。
60
+ - 多模块项目:要么 `pomFileName` 指子模块,要么用 `multimoduleDir` 指根 —— 二选一,别都填。
61
+ - 跑测试类目标(`-Dtest=…`)时 `cmdOptions` 里带 `-D`,不要放进 `goals`。
package/skills/idea-run-config-manager/assets/types/node.md ADDED
@@ -0,0 +1,30 @@
1
+ # Node.js(`NodeJSConfigurationType`)
2
+
3
+ **用途**:直接跑一个 `.js` / `.mjs` 入口。**跑 `package.json` 脚本请用 [npm.md](npm.md)** —— 那是另一回事。
4
+
5
+ ⚠️ **本模板验证程度有限**:`type` 与下面三个属性已由实物确认;**环境变量、Node 解释器等字段没有实物样本**,照抄本项目里已有配置的写法,或让用户在 IDE 里补,不要凭名字猜。
6
+
7
+ ## 模板(已验证的最小形态)
8
+
9
+ ```xml
10
+ <component name="ProjectRunConfigurationManager">
11
+ <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">
12
+ <method v="2" />
13
+ </configuration>
14
+ </component>
15
+ ```
16
+
17
+ ## 字段(已验证)
18
+
19
+ | 字段 | 形态 | 含义 |
20
+ | ------------------------ | -------- | ----------------------------------- |
21
+ | `path-to-js-file` | **属性** | 入口 JS 文件,`$PROJECT_DIR$/…` |
22
+ | `working-dir` | **属性** | 工作目录 |
23
+ | `application-parameters` | **属性** | 传给脚本的参数(实物里是 `dev` 这种) |
24
+ | `factoryName` | 属性 | `Node.js`(实测有写、也有省略) |
25
+
26
+ ## 坑
27
+
28
+ - **这个类型用属性写法,不是 `<option>` 子元素** —— 照别的类型套会静默失效。
29
+ - **能不用它就不用**:绝大多数"跑前端/跑服务"的场景,`js.build_tools.npm`(`<command value="run">` + 脚本名)才是团队共享配置的主流写法,也更好懂。
30
+ - 需要环境变量(`dotenv`)或指定 Node 版本时,本模板没有可用字段 —— **照项目里已有的 Node.js 配置抄**,或让用户在 IDE 里配好再让你同步文档。
package/skills/idea-run-config-manager/assets/types/npm.md ADDED
@@ -0,0 +1,58 @@
1
+ # npm / yarn / pnpm(`js.build_tools.npm`)
2
+
3
+ **用途**:跑 `package.json` 里的脚本(dev / build / test)。三种包管理器**共用同一个 `type`**,靠 `<package-manager>` 区分。
4
+
5
+ ## 模板
6
+
7
+ ```xml
8
+ <component name="ProjectRunConfigurationManager">
9
+ <configuration default="false" name="frontend" type="js.build_tools.npm">
10
+ <package-json value="$PROJECT_DIR$/frontend/package.json" />
11
+ <command value="run" />
12
+ <scripts>
13
+ <script value="dev" />
14
+ </scripts>
15
+ <node-interpreter value="project" />
16
+ <package-manager value="npm" />
17
+ <envs />
18
+ <method v="2" />
19
+ </configuration>
20
+ </component>
21
+ ```
22
+
23
+ ## 字段
24
+
25
+ | 字段 | 含义 | 怎么填 |
26
+ | ---------------------------- | ----------------- | ----------------------------------------------------------------- |
27
+ | `package-json` | 哪个 package.json | `$PROJECT_DIR$/子目录/package.json` |
28
+ | `command` | npm 子命令 | 跑脚本用 `run` |
29
+ | `scripts` → `<script value>` | 脚本名 | `package.json` 里 `scripts` 的 key(`dev` / `build` / `test:unit`) |
30
+ | `package-manager` | 用哪个包管理器 | `npm` / `yarn` / `pnpm`(实测值就是这三个) |
31
+ | `node-interpreter` | Node 来源 | `project`(用项目里配的);用系统就填绝对路径 |
32
+ | `envs` | 环境变量 | 空就 `<envs />` |
33
+ | `method` | 前置任务 | 默认空 `<method v="2" />`;需要"先跑别的再跑这个"才填(见下) |
34
+
35
+ ## 跑之前先跑别的(build → dev)
36
+
37
+ `<method v="2">` 里可以带前置任务:
38
+
39
+ ```xml
40
+ <method v="2">
41
+ <option name="NpmBeforeRunTask" enabled="true">
42
+ <package-json value="$PROJECT_DIR$/package.json" />
43
+ <command value="run" />
44
+ <scripts>
45
+ <script value="build" />
46
+ </scripts>
47
+ <node-interpreter value="project" />
48
+ <envs />
49
+ </option>
50
+ </method>
51
+ ```
52
+
53
+ ## 坑
54
+
55
+ - **`<package-manager>` 决定实际用哪个包管理器跑**:项目用 pnpm 而这里写 `npm`,脚本里 `pnpm xxx` 的调用会跟外层打架。
56
+ - 实测文件里还出现过两个 `<EXTENSION>`(better_direnv、StartBrowser)—— 那是别人本机插件加的,**别抄**,它们依赖本机插件,别人机器上没有。
57
+ - 单仓多包(pnpm workspace / npm workspaces):`package-json` 指到**具体那个包**,不要指根再靠 scripts 转发。
58
+ - `scripts` 里写多个脚本 = 按顺序跑同一个命令,不等于"先 A 后 B";顺序依赖要用上面的前置任务。
package/skills/idea-run-config-manager/assets/types/python.md ADDED
@@ -0,0 +1,59 @@
1
+ # Python(`PythonConfigurationType`)
2
+
3
+ **用途**:跑一个 Python 脚本(通常是服务入口)。**这个类型来自 Python 插件**(PyCharm 一定有,IDEA 装了 Python 插件也有)。
4
+
5
+ ## 模板
6
+
7
+ ```xml
8
+ <component name="ProjectRunConfigurationManager">
9
+ <configuration default="false" name="backend" type="PythonConfigurationType" factoryName="Python">
10
+ <module name="my-project" />
11
+ <option name="ENV_FILES" value="" />
12
+ <option name="INTERPRETER_OPTIONS" value="" />
13
+ <option name="PARENT_ENVS" value="true" />
14
+ <envs>
15
+ <env name="PYTHONUNBUFFERED" value="1" />
16
+ </envs>
17
+ <option name="SDK_HOME" value="" />
18
+ <option name="SDK_NAME" value="my-project" />
19
+ <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/backend/app" />
20
+ <option name="IS_MODULE_SDK" value="false" />
21
+ <option name="ADD_CONTENT_ROOTS" value="true" />
22
+ <option name="ADD_SOURCE_ROOTS" value="true" />
23
+ <option name="DEBUG_JUST_MY_CODE" value="false" />
24
+ <option name="RUN_TOOL" value="" />
25
+ <option name="SCRIPT_NAME" value="$PROJECT_DIR$/backend/app/main.py" />
26
+ <option name="PARAMETERS" value="" />
27
+ <option name="SHOW_COMMAND_LINE" value="false" />
28
+ <option name="EMULATE_TERMINAL" value="false" />
29
+ <option name="MODULE_MODE" value="false" />
30
+ <option name="REDIRECT_INPUT" value="false" />
31
+ <option name="INPUT_FILE" value="" />
32
+ <method v="2" />
33
+ </configuration>
34
+ </component>
35
+ ```
36
+
37
+ ## 字段
38
+
39
+ | 字段 | 含义 | 怎么填 |
40
+ | --------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- |
41
+ | `module name` | 用哪个模块 | **必须是这个项目里真实存在的模块名**,拿不准就问用户 |
42
+ | `SCRIPT_NAME` | 入口脚本 | `$PROJECT_DIR$/…/main.py` |
43
+ | `PARAMETERS` | 传给脚本的参数 | 没有就空 |
44
+ | `WORKING_DIRECTORY` | 工作目录 | `$PROJECT_DIR$/…`(实测指向 `backend/app` 这种应用目录) |
45
+ | `SDK_NAME` / `IS_MODULE_SDK` / `SDK_HOME` | 用哪个解释器 | `IS_MODULE_SDK=false` + `SDK_NAME` 填项目里配好的解释器名;本机路径写 `SDK_HOME` |
46
+ | `ENV_FILES` | dotenv 文件 | 没有就空 |
47
+ | `PARENT_ENVS` | 继承父环境变量 | `true` |
48
+ | `envs` → `<env name value>` | 额外环境变量 | 例如 `PYTHONUNBUFFERED=1`(让日志实时) |
49
+ | `ADD_CONTENT_ROOTS` / `ADD_SOURCE_ROOTS` | 把项目根 / 源码根加进 `PYTHONPATH` | `true` |
50
+ | `DEBUG_JUST_MY_CODE` | 只断自己的代码 | `false` |
51
+ | `MODULE_MODE` | 当模块跑(`python -m`) | 一般 `false` |
52
+ | `SHOW_COMMAND_LINE` / `EMULATE_TERMINAL` / `REDIRECT_INPUT` / `INPUT_FILE` / `INTERPRETER_OPTIONS` / `RUN_TOOL` | — | 按实测默认值留空 / `false` |
53
+
54
+ ## 坑
55
+
56
+ - **`module name` 与 `SDK_NAME` 必须是本项目真实的模块 / 解释器名** —— 写错 IDE 会用不了,但不一定立刻报错。**先查项目里已有的 Python 配置照抄**,查不到就问用户。
57
+ - 实测样本里带一个 `<EXTENSION ID="PythonCoverageRunConfigurationExtension" …/>`(覆盖率插件加的),**别抄**。
58
+ - 依赖装在哪决定能不能跑:走项目解释器 + `ADD_SOURCE_ROOTS`,不要指向本机某个 venv 的绝对路径。
59
+ - 服务类进程改代码后要重启才生效(没有热重载)—— 这条属于 `idea-standalone` 的纪律。
package/skills/idea-run-config-manager/assets/types/shell.md ADDED
@@ -0,0 +1,77 @@
1
+ # Shell Script(`ShConfigurationType`)
2
+
3
+ **用途**:一条固定命令或一个脚本文件 —— 构建、打包、生成代码、跑迁移、同步某个环境的 DDL、起服务。**绝大多数"反复要跑的固定流程"都归它,先别换类型。**
4
+
5
+ ## 二选一:脚本文本 / 脚本文件
6
+
7
+ | 形态 | 关键字段 | 用在什么时候 |
8
+ | ------------------ | --------------------------------------------------------------------- | --------------------------------------- |
9
+ | **脚本文本**(默认) | `EXECUTE_SCRIPT_FILE="false"` + `SCRIPT_TEXT` 有值 + `SCRIPT_PATH` 空 | 就一条命令,不需要单独脚本文件 |
10
+ | **脚本文件** | `EXECUTE_SCRIPT_FILE="true"` + `SCRIPT_PATH` 有值 + `SCRIPT_TEXT` 空 | 命令已经写成仓库里的 `.sh`,或脚本比较长 |
11
+
12
+ ## 模板:脚本文本形态
13
+
14
+ ```xml
15
+ <component name="ProjectRunConfigurationManager">
16
+ <configuration default="false" name="db-migrate" type="ShConfigurationType" factoryName="Shell Script">
17
+ <option name="SCRIPT_TEXT" value="pnpm -C packages/db generate&#10;pnpm -C packages/db migrate:deploy" />
18
+ <option name="INDEPENDENT_SCRIPT_PATH" value="true" />
19
+ <option name="SCRIPT_PATH" value="" />
20
+ <option name="SCRIPT_OPTIONS" value="" />
21
+ <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="true" />
22
+ <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
23
+ <option name="INDEPENDENT_INTERPRETER_PATH" value="true" />
24
+ <option name="INTERPRETER_PATH" value="" />
25
+ <option name="INTERPRETER_OPTIONS" value="" />
26
+ <option name="EXECUTE_IN_TERMINAL" value="false" />
27
+ <option name="EXECUTE_SCRIPT_FILE" value="false" />
28
+ <envs />
29
+ <method v="2" />
30
+ </configuration>
31
+ </component>
32
+ ```
33
+
34
+ ## 模板:脚本文件形态
35
+
36
+ ```xml
37
+ <component name="ProjectRunConfigurationManager">
38
+ <configuration default="false" name="go-server" type="ShConfigurationType" factoryName="Shell Script">
39
+ <option name="SCRIPT_TEXT" value="" />
40
+ <option name="INDEPENDENT_SCRIPT_PATH" value="true" />
41
+ <option name="SCRIPT_PATH" value="$PROJECT_DIR$/go/run.sh" />
42
+ <option name="SCRIPT_OPTIONS" value="" />
43
+ <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="true" />
44
+ <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$/go" />
45
+ <option name="INDEPENDENT_INTERPRETER_PATH" value="true" />
46
+ <option name="INTERPRETER_PATH" value="/bin/zsh" />
47
+ <option name="INTERPRETER_OPTIONS" value="" />
48
+ <option name="EXECUTE_IN_TERMINAL" value="false" />
49
+ <option name="EXECUTE_SCRIPT_FILE" value="true" />
50
+ <envs />
51
+ <method v="2" />
52
+ </configuration>
53
+ </component>
54
+ ```
55
+
56
+ ## 字段
57
+
58
+ | 字段 | 含义 | 怎么填 |
59
+ | --------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
60
+ | `SCRIPT_TEXT` | 要执行的命令 | **多行用 `&#10;` 分隔**(实测这么存的),不要塞真实换行 |
61
+ | `EXECUTE_SCRIPT_FILE` | `false` 跑文本 / `true` 跑文件 | 决定上面两个字段谁生效 |
62
+ | `SCRIPT_PATH` | 脚本路径 | `$PROJECT_DIR$/...` |
63
+ | `SCRIPT_OPTIONS` | 传给脚本的参数 | 没有就留空 |
64
+ | `SCRIPT_WORKING_DIRECTORY` | 工作目录 | `$PROJECT_DIR$` 或其子目录;留空 = 项目根 |
65
+ | `INDEPENDENT_SCRIPT_PATH` / `INDEPENDENT_SCRIPT_WORKING_DIRECTORY` / `INDEPENDENT_INTERPRETER_PATH` | 三处"各自独立"开关 | **保持实测值 `true`,别改** |
66
+ | `INTERPRETER_PATH` | 解释器 | macOS/Linux:`/bin/zsh`、`/bin/bash`,或**留空用 IDE 默认**(实测留空也能跑);Windows:`C:/Windows/System32/WindowsPowerShell/v1.0/powershell.exe` |
67
+ | `INTERPRETER_OPTIONS` | 解释器参数 | 一般空 |
68
+ | `EXECUTE_IN_TERMINAL` | 是否开终端跑 | **`false`** —— 共享出去的配置不要依赖本机终端 |
69
+ | `envs` | 环境变量 | 没有就 `<envs />`;有就 `<env name="K" value="V" />` |
70
+
71
+ ## 坑
72
+
73
+ - **`EXECUTE_IN_TERMINAL` 必须是 `false`**:引导文本里"执行 Shell 配置要 `EXECUTE_IN_TERMINAL: false`"说的就是它,开成 true 的配置到了别人机器上行为不一样。
74
+ - **`INDEPENDENT_INTERPRETER_PATH` 实测有两种**:解释器填了绝对路径的用 `true`(老写法),Windows 相对写法的那两个文件是 `false`。**照抄同项目里已有的那个**,别自己换。
75
+ - Windows 解释器两种斜杠都实测出现过,`C:/...` 更稳(反斜杠在 XML 里要转义)。
76
+ - `factoryName` 可以省略(实测有省略也能被认),但同一项目里**跟着已有文件的写法**更一致。
77
+ - 文件里可以有 XML 注释说明这条配置实际跑的是什么(实测项目就这么写的),有助于后来的人看懂。
package/skills/idea-standalone/SKILL.md CHANGED
@@ -27,7 +27,7 @@ description: "为项目生成/维护 standalone(启动收口只有 IDEA run conf
27
27
  第二段的 `run configuration` 列、以及端口,**只能来自这里** —— 不需要再去逐个翻 `.run/*.run.xml`,那份列表已经是配置的结果。
28
28
  - 项目类型(`package.json` / `pom.xml` / `go.mod` / `pyproject.toml` / `Cargo.toml`)→ 决定第三段的热重载列。
29
29
  - 端口:先看上面那份启动细节里有没有;项目自身配置里也读不到就**问用户**,不要编。
30
- - `run configuration` 列表里缺某个应用:**交给用户** —— 请他在 IDEA 里自己建一个,然后**重新查一次**。不要手搓启动命令,也不要自己写 `.run/*.run.xml`。
30
+ - `run configuration` 列表里缺某个应用:**交给用户** —— 让他调 `idea-run-config-manager` skill 去建(那个 skill 管这个项目 run configuration 的增 / 删 / 改;工具列表里没有它时,请用户自己建一个),建完**重新查一次**。不要手搓启动命令,也不要自己写 `.run/*.run.xml`。
31
31
  - 补齐缺口:哪些应用进 standalone、哪些配置名对不上、端口与热重载不确定 —— **逐条向用户确认**,不猜。
32
32
  - 生成或更新前先读 [assets/AGENTS.template.md](assets/AGENTS.template.md),确认三段与各段生成提示。
33
33
 
package/skills/idea-standalone/assets/AGENTS.template.md CHANGED
@@ -33,24 +33,28 @@
33
33
  一行一个应用,**按操作系统分成两张表**:macOS / Linux 一张,Windows 一张。同一份项目在不同平台上的启动方式往往不一样(解释器路径、脚本、
34
34
  甚至该用哪个配置都不同 —— 比如某个配置的 `INTERPRETER_PATH` 指向 Windows PowerShell,在 macOS 上根本起不来),
35
35
  所以**每张表里的 `run configuration` 必须是该平台上真正存在、真正能跑的那个名字**,不要把 Windows 上能用的配置写进 macOS 那张表。
36
- 某个应用在某平台上起不来,就在该表里注明(或干脆不列),别让 AI 在一个平台上去跑另一个平台的配置。
36
+ 某个应用在某平台上起不来,就在该表里注明(或干脆不列),别让 AI 在一个平台上去跑另一个平台的配置。哪个平台用哪张表,不要自己猜。
37
37
 
38
38
  `run configuration` 列**必须是 `<前缀>_get_run_configurations` 里真实存在的名字**,不凭印象写;缺配置就**交给用户**:
39
- 请他在 IDEA 里自己建一个,不要手搓启动命令,也不要自己写 `.run/*.run.xml`。端口写清"固定 / 默认 / 被占用即启动失败",读不到就**问用户**,不要编。
40
- **启动前流程**列:**多数应用留空**。只有确实"得先做点什么才能起"时才写,而且**按顺序写清第 1 步、第 2 步、第 3 步**(例如 `1. 装依赖 2. 构建 3. 起前置服务`);
39
+ 让他调 `idea-run-config-manager` skill 去建(那个 skill 管这个项目 run configuration 的增 / 删 / 改),不要手搓启动命令,也不要自己写 `.run/*.run.xml`。
40
+ **怎么跑**写走哪条工具:常驻 / 服务化的配置一律 `rerun`(在跑就重启、没在跑就启动),**不要**用 `execute` —— 它是 Run 路径,对常驻进程会起出重复实例;细节见「跑应用只用 rerun」那条。
41
+ **端口**写清"固定 / 默认 / 被占用即启动失败";读不到就**问用户**,不要编。**服务化的应用一定有端口**,这一格是它区别于固定流程的地方。
42
+ **跑前做**列写**跑之前要先做的事**:**多数应用留空**。只有确实"得先做点什么才能起"时才写,而且**按顺序写清第 1 步、第 2 步、第 3 步**(例如 `1. 装依赖 2. 构建 3. 起前置服务`);
41
43
  这些事**用文字写出来**(AI 照这段文本自己按序去做)。这类前置事项往往没被写成 run configuration,所以必须在这里说明,否则 AI 直接 rerun 会拿到一个起不来的进程。
42
44
  **哪个应用必须先起来**也要写明(例如前端 dev server 的 proxy 指向本机后端)。与本项目无关的应用不写。
45
+ **说明**写剩下的坑与依赖关系(依赖谁、跟别的应用什么先后),以及例外(**只在联调 / 某个流程之前才需要起**之类)。**目录**这类配置里本来就有的字段不要单开一格 —— 会跟配置变旧而对不上。
46
+ **列宽按同一约定**(中文两字 = 四个 dash,英文按字符数),**两张应用表的公共列一一对位、宽度一致**(同一份 `AGENTS.md` 里两张表才像一家人)。**列名与顺序要和 `idea-run-config-manager` 的条目项对得上**(`怎么跑` / `跑前做` / `说明` 三项同名;**本表多一列 `端口`**(服务化应用一定有端口),**少一项 `何时跑`** —— 服务化应用就是"改完代码要起它来测"的时候起,没有别的时机可写)—— 两个块住在同一份 `AGENTS.md` 里,名字与顺序对上了才看得出哪些是服务、哪些是固定流程。**本块保持表格形式**(那边改成条目式了,这边不跟:应用有端口这样的短列,表格更好扫)。**某格不适用就留空,不要写 `-`;填行时别去改表头的空格。**
43
47
  <!-- 生成提示:end -->
44
48
 
45
49
  ### macOS / Linux
46
50
 
47
- | 应用 | run configuration | 目录 | 端口 | 启动前流程 | 说明 |
48
- | ---- | ----------------- | ---- | ---- | ---------- | ---- |
51
+ | 应用 | run configuration | 怎么跑 | 端口 | 跑前做 | 说明 |
52
+ | ---- | ----------------- | ------ | ---- | ------ | ---- |
49
53
 
50
54
  ### Windows
51
55
 
52
- | 应用 | run configuration | 目录 | 端口 | 启动前流程 | 说明 |
53
- | ---- | ----------------- | ---- | ---- | ---------- | ---- |
56
+ | 应用 | run configuration | 怎么跑 | 端口 | 跑前做 | 说明 |
57
+ | ---- | ----------------- | ------ | ---- | ------ | ---- |
54
58
 
55
59
  ## 三、热重载矩阵:改代码后要不要提醒重启
56
60