插件识别当前工作区中的 Minecraft 模组与插件工程，在会话标题栏提供运行目标的选择与启动、停止操作，并将运行日志输出到侧边栏标签页。
面板服务于人，工具服务于模型，两者共用同一份运行状态和同一把锁：同一工程同时只有一个实例，谁先起的，另一方都看得见，也不会把对方的进程踩掉。
运行目标分两类，生命周期不同。runClient / runServer 是常驻进程，启动后一直运行到人关闭窗口；runData / runGameTestServer 会跑完，插件在它们结束时给出通过或失败的结论。模型因此可以自己完成"改代码 → 跑一遍 → 看结论"这一环，而不必让窗口里的画面承担它判断不了的事情。
截图
 | |
 |
 |
功能
- 工程识别：支持 Fabric、Forge、NeoForge、Architectury、Paper 与 Spigot，覆盖 Minecraft 1.7.10 至 26.x。支持单模块、多模块与聚合仓库；loader 声明位于子模块时同样可以识别。
- 运行目标：从 Gradle 配置中提取 Client、Server、Data、GameTestServer 等任务，并区分常驻（
daemon）与会跑完（oneshot）两类。按 loader 惯例推测的目标会标记为未验证，不影响选择与启动。 - 托管启动：通过 Gradle Wrapper 启动任务。常驻目标依据日志标记判定是否进入运行状态，而非仅依据进程存活；一次性目标跑完即给出结论，成功、失败、被停止、起不来分别可辨。停止时终止 Gradle 及其全部子进程。
- JDK 选择：按 MC 版本与
toolchain推断所需 JDK 大版本，在面板里列出本机探测到的 JDK 供选择，也可以直接填入 JDK 根目录把它加进列表。指定结果只存本机（~/.dsh/mc-dev-starter/jdk.json），不写进gradle.properties；启动时以-Dorg.gradle.java.home与JAVA_HOME传给 Gradle，因此面板显示的就是实际使用的。自动挑选只在"大版本完全匹配且 Gradle 跑得动"时接管，避免把本来能跑的工程换成不兼容的 JVM。 - 声明依赖：解析
dependencies { }块、gradle/libs.versions.toml与元数据里的depends，按配置、坐标、文件:行号列出，用来核对某个依赖是不是真的加进去了。只显示声明；Gradle 解析后的传递依赖需要跑一次 Gradle 才能拿到。 - 状态保持：运行记录持久化到本地，并按 profile 分目录（
~/.dsh/mc-dev-starter/profiles/<name>/），不同 profile 的实例互不干扰。宿主重启后按进程 ID 校验：确认存活则继续跟踪，无法确认则记为未知，不推测退出原因。 - 运行日志：独立侧边栏标签页或 better-sidebar 底部工作台，按工程展示启动历史，支持跟随输出。日志按级别着色：WARN 与 ERROR 高亮，堆栈帧与 Gradle 任务行区分显示，时间、线程与 logger 弱化；可按级别过滤（全部 / INFO+ / WARN+ / ERROR），选择会被记住。异常退出时给出可能原因，覆盖依赖解析失败、JDK 版本不匹配、端口占用、认证失败等情况。
- 工作区跟随：以当前会话的工作目录作为工作区，切换会话时自动重新扫描，无需手动刷新。工作区里没有可运行的工程时不显示标题栏胶囊，避免在非 Minecraft 项目里占位；面板标签仍可打开。
- 模型工具（可选）：提供六个工具，与面板共用同一套服务——
mc_projects（列出工程与目标）、mc_project_detail（loader 依据、模块、JDK、声明依赖、各目标是常驻还是会跑完）、mc_launch（启动；常驻目标默认等到运行态，一次性目标默认等到结束并返回verdict与失败行）、mc_launch_logs（读日志，异常退出时附带结构化归因与建议）、mc_launch_list（历史实例与状态，含验证结论）、mc_launch_stop（停止整棵进程树）。 - 扩展集成：安装 dsh-better-sidebar 后，面板与日志可在其侧边栏中作为带图标的标签页打开。
安装
要求 DSH 桌面版 0.2.1 或更高版本，或对应的 dsh CLI。
# 从 npm 安装
dsh plugin --profile desktop add minecraft-dev-starter
# 本地仓库（修改后即时生效）
dsh plugin --profile desktop add link:C:/Projects/minecraft-dev-starter
# 使用打包文件
dsh plugin --profile desktop add file:./minecraft-dev-starter-0.1.10.tgz
安装完成后需重启 DSH 生效。卸载：
dsh plugin --profile desktop remove minecraft-dev-starter
dsh plugin 是 pnpm 的封装：将插件加入 profile 的依赖，并把声明了 dsh.bundle 的包加入 dsh.profile.bundles 列表。直接编辑 profile 的 package.json 后执行 pnpm install，效果相同。
使用
- 打开包含 Minecraft 工程的工作区会话。
- 标题栏显示当前选中的运行目标。点击目标名称打开浮层，从中选择工程与任务。
- 需要换 JDK 时，在右侧栏「Mod Dev」面板的「构建环境」里选择：下拉列出本机 JDK，也可以在下方输入 JDK 根目录并添加。
- 点击启动按钮开始构建并运行。启动后自动打开「运行日志」标签页，该行为可通过配置关闭。
- 运行期间按钮切换为停止；点击后终止 Gradle 及其子进程。
浮层布局随工程数量变化：单工程工作区不显示工程列表，表头直接呈现工程名称、loader 与版本、路径；多工程工作区显示固定高度的列表，切换工程时仅更新下方目标区域，页面不会跳动。
验证改动
对会跑完的目标，模型可以直接拿到结论，不需要人盯着窗口：
mc_project_detail看哪些目标是oneshot，即runData、runGameTestServer，以及工程里自建的runGametest；mc_launch启动它。这类目标默认等到结束，返回verdict：passed/failed/aborted/error；- 失败时
summary是第一处失败特征行，failures是命中的若干行；需要全文用mc_launch_logs。
常驻目标（runClient）能自动断言的只有「是否进入运行状态」与日志里的异常。画面、手感这类判断仍由人完成：模型把客户端起起来，人看一眼，再让模型回去读日志。
配置
在 profile 的 cordis.patch.yml 中为该插件条目添加 config 字段：
- id: mcdev-host
name: minecraft-dev-starter
config:
autoOpenLogTab: true
# logDock: right # 默认：装了 dsh-better-sidebar 落底部工作台，没有则落右侧栏
readyTimeoutMs: 90000
logRingLines: 2000
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
autoOpenLogTab | boolean | true | 启动后自动打开运行日志标签页 |
logDock | right | bottom | 自动 | 日志打开位置。未配置时安装 dsh-better-sidebar 则落其底部工作台，否则落原生右侧栏；写入 right 可强制回到右侧栏 |
readyTimeoutMs | number | 90000 | 等待进入运行状态的超时时间；超时不计为失败 |
logRingLines | number | 2000 | 内存中保留的日志行数；磁盘上的日志始终完整 |
logDock 只影响「自动打开」与面板里的「打开日志」按钮；无论配置为何，两个标签页都同时存在于原生右侧栏与 better-sidebar 的页签列表中，可随时手动打开。
兼容范围
| 平台 | 版本范围 | 说明 |
|---|---|---|
| Fabric | 1.14 – 26.x | loom 提供的 runClient 等任务 |
| Forge | 1.7.10 / 1.12.2 / 1.16.5 / 1.20.1 | 包含 legacyforge |
| NeoForge | 1.20.1 – 26.x | moddev 插件 |
| Architectury | 1.16 – 26.x | 按子模块拆分任务 |
| Paper / Spigot | 1.7.10 – 26.x | 服务端插件工程 |
JDK 版本按 Minecraft 版本推断：1.7.10 与 1.12.2 需要 Java 8，1.18 至 1.20.4 需要 Java 17，1.20.5 及以上需要 Java 21，26.x 需要 Java 25。插件将需求与已安装的 JDK 比对，缺失或版本不符时在面板中提示。
支持多模块工程：每个子模块各自算一个工程，运行目标带 Gradle 模块前缀（:modules/core:runClient），并在 wrapper 所在的聚合根目录执行。工程里有 IntelliJ 的 .idea 时，会额外读取它的 Gradle 模块清单、minecraft facet 平台、工程 JDK 与运行配置，但只作为兜底证据——构建脚本优先，已判定的结论不会被推翻。
已在 dsh 0.2.1-rc.4（DSH NEXT 2.0.21-next）+ Windows 11 上验证。宿主侧的变化记在 CHANGELOG；上调支持范围按破坏性变更处理。
开发
npm install
npm run build # 构建客户端到 lib/client.js；修改 src/client 后必须执行
npm test # 135 个测试
npm run check:pack # 校验 npm 包里真的有客户端产物与源码
npm run build -- --watch
lib/client.js 被 .gitignore 忽略，只在打包时通过 package.json 的 files 进入 npm 包。因此新 clone 的仓库要先执行一次 npm run build，否则 link: 安装的插件拿不到客户端产物。prepack 会在 npm pack / npm publish 之前自动构建；test/bundle.test.js 按宿主的加载协议真跑一遍产物，客户端坏掉会在测试里失败，而不是等用户装完才发现。
CI 在 ubuntu、windows、macOS 三个平台与 Node 20/22/24 上跑测试，另有一个打包内容校验任务。
仓库结构、已知坑与历次验证结论见 AGENTS.md。设计文档：策划、DSH 插件机制调研。
发布
DSH 插件以 npm 包形式分发，不需要独立注册流程。
-
清单：
package.json声明dsh.bundle.patch（指向cordis.patch.yml）；提供浏览器界面时同时声明dsh.client.platform。宿主依据这两项识别插件。 -
产物：执行
npm run build生成lib/client.js。该文件被.gitignore忽略，通过package.json的files字段进入 npm 包。运行时直接读取产物，不安装依赖，也不执行构建。 -
校验：执行
npm test与npm run check:pack（直接问 npm 实际会打包哪些文件：缺lib/client.js、源码或 README，或多带了test/，都会失败）。 -
发布：
npm publish --access public。若使用仅允许暂存的 granular token，改为以下流程：npm stage publish # 提交到暂存区 npm stage list # 等待校验结束 npm stage approve <stage-id> # 人工完成 2FA 确认暂存后由人工批准是 npm 的设计：机器提交、人工确认，即使 token 泄露也无法直接发布正式版本。批准后
latest标签自动指向新版本。 -
兼容性：宿主 API 会持续演进。发布前将
@deepseek-ai/dsh-tools与@deepseek-ai/cordis的版本范围对齐目标运行时；跨大版本时应分别发布版本，而非放宽范围强行兼容。 -
安装：用户执行
dsh plugin --profile <name> add <包名>后重启，或在 Plugins 面板中安装。
在本地验证发布形态时，可先 npm pack，再通过 dsh plugin add file:<tarball> 安装；该路径与 npm 安装完全一致。
安全
报告渠道、支持范围与完整威胁模型见 SECURITY.md。
- 会执行什么：启动目标时会在工程目录里运行该工程自带的 Gradle wrapper（
gradlew.bat/gradlew），环境变量继承自 DSH 宿主。也就是说工作区的构建脚本以你的用户权限运行——这与你自行执行gradle是同一种信任。插件只提供工作区内识别到的目标。 - 会写什么：运行记录与日志写在
~/.dsh/mc-dev-starter（按 profile 分目录），JDK 选择记在同目录的jdk.json。除 Gradle 自身产物外，不改动工程目录。 - 会发送什么：不向外发送任何数据。
/mcdev/api由本机 DSH Web 服务提供并受其鉴权保护，客户端产物只向这些路由上报自身诊断。 - 子进程：同一工程同时只有一个目标；停止时杀掉整棵进程树（Windows
taskkill /T，POSIX 进程组），不留孤儿java进程。不做隐含的clean，不删除构建目录。 - 包内容：不声明任何依赖；用户机器上不执行安装脚本或 postinstall——
prepack只在发布者的工作区运行。
npm 页面上的两条告警来自宿主运行时，不是本包代码：
zod（GHSA-mrhx-c7xc-m3w5）经@deepseek-ai/dsh-tools→@deepseek-ai/dsh-llm传导。本包不声明依赖，无法锁定它。- 「Uses eval」是误报：命中的是
@deepseek-ai/dsh-ptc-runtime保留字表里的一个字符串常量。本仓库与构建产物中都不出现eval。
已知限制
- 原生右侧栏的标签类型不提供图标字段，图标仅支持
dsh-better-sidebar中的标签。 - 子模块各自成工程后，聚合工程的根目录不再单列；根目录自己挂的 run 目标不会出现在列表里。
.idea只是兜底证据：既不在settings.gradle、也不在 IDE 模块清单里的模块不会被发现；facet 平台也不会推翻已判定的 loader。- 一次性目标的结论由退出码与日志特征共同判定：退出码非零必为失败；退出码为零但日志里出现测试失败特征（如
N required tests failed）同样判为失败，以免把「测试挂了但进程退了 0」当成通过。两者都缺失时记为未知，不猜。 - 在 Windows 上首次构建需要下载 Gradle 与项目依赖，耗时可能达到数分钟；后续构建可使用 Gradle daemon。
License
MIT