# minecraft-dev

Minecraft 开发插件 for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`)：让 agent 更擅长写 Minecraft 服务端插件与模组，覆盖 **MC 1.7.10 ~ 26.x 全时代**。

已发布 npm：[`minecraft-dev`](https://www.npmjs.com/package/minecraft-dev)（MIT）｜ 源码：[GitHub](https://github.com/sikadi233-hub/minecraft-dev)

## 功能一览

### 7 个技能（模型按需加载，不占常驻上下文）

| 技能 | 内容 |
|---|---|
| `minecraft-java-build` | 全时代 Java/Gradle 构建知识：JDK 配对表、wrapper、foojay toolchain、依赖仓库、常见坑 |
| `minecraft-paper-plugin` | Paper/Spigot 现代线插件（1.20.x / 1.21.x / 26.x）+ 5 份 API 参考 |
| `minecraft-fabric-mod` | Fabric 模组（loom/loader/fabric-api/yarn 配合）+ 4 份 API 参考 |
| `minecraft-forge-mod` | 传统 Forge 四时代（1.7.10 FG2 / 1.12.2 FG3 / 1.16.5 FG5 / 1.20.1 FG6）+ 3 份时代 API 参考 |
| `minecraft-neoforge-mod` | NeoForge（1.20.1 legacyforge / 1.21.x / 26.2 beta）+ 3 份 API 参考 |
| `minecraft-spigot-legacy` | 1.7.10 / 1.12.2 老线 Bukkit 插件 + Cauldron/Thermos/Mohist 混合服说明 + 2 份老线 API 参考 |
| `minecraft-major-mods` | 大型模组附属开发：28 个模组条目（1.7.10×10 / 1.12.2×8 / 现代×10，含拔刀剑、神秘时代、匠魂、植物魔法、Create、Botania、AE2、Mekanism、Curios、JEI/REI 等），每条含核实过的 curse.maven 坐标与扩展点 |

### 2 个工具

| 工具 | 用途 |
|---|---|
| `mc_scaffold` | 一句话创建完整可构建项目：paper / fabric / forge / neoforge / spigot 五平台，自动配好构建脚本、主类、元数据、**时代对应的 Gradle wrapper** |
| `mc_gradle` | 在项目里跑 `gradlew <task>`：终端卡片显示、超时自动杀进程树、输出头尾截断、非零退出码不报错而是可读呈现 |

### 4 个内置子代理（v0.5.0，四子代理团队）

| 子代理（toolName） | 环节与产出 |
|---|---|
| `subagent_mc_plan` | A 方案：勘察项目 + web_search 联网查证 → 写 `<项目>/PLAN.md` + 5 行摘要 |
| `subagent_mc_skeleton` | B 框架：按 PLAN.md 用 mc_scaffold 搭骨架 + 资源模板 + 测试桩 → 变更清单 |
| `subagent_mc_content` | C 内容：按 PLAN.md 与骨架填充功能代码 → 变更清单 + 不确定点 |
| `subagent_mc_verify` | D 编译审查：mc_gradle 编译/测试、修小错 → 验证报告 |

（注：4 个子代理为宿主层工具，任何 preset 会话可见；使用说明见 Minecraft 专家 preset persona。）

### 1 个 Agent 预设

| 预设 | 内容 |
|---|---|
| `minecraft`（Minecraft 专家） | 一键切换的专精 agent：standard 全工具集（shell / 文件 / 检索 / 技能 / 计划 / 目标 / 子代理 / 工作流）+ 中文专家人设 + 全局可见的 7 个技能与 4 个内置子代理 subagent_mc_plan/skeleton/content/verify（v0.6.0 起装完插件重启 dsh 后**自动安装**到 `$DSH_HOME/.agent-presets/minecraft/`，见下方「Minecraft 专家 agent 的安装」） |

## 安装

### 方式一：npm 安装（推荐）

```sh
dsh plugin --profile web add minecraft-dev
```

> **国内用户注意**：npm 默认源 npmmirror 会在发布后几分钟内同步；若报 `ERR_PNPM_FETCH_404` 说明镜像还没同步，加官方源即可：
> `dsh plugin --profile web add minecraft-dev --registry=https://registry.npmjs.org`

### 方式二：本地 tarball（离线/内网）

```sh
cd minecraft-dev && pnpm pack        # 产出 minecraft-dev-x.y.z.tgz
dsh plugin --profile web add ./minecraft-dev-0.5.0.tgz
```

### 方式三：源码直连（开发迭代，改完即生效）

```sh
dsh plugin --profile web add /path/to/minecraft-dev
```

### ⚠️ 如果你从源码运行 dsh：命令是 `pnpm dsh` 不是 `dsh`

**只有通过 npm 安装的 dsh**（`npx @deepseek-ai/dsh` 或 `npm i -g`）才有 `dsh` 命令。
如果你是从仓库源码跑的（比如 `C:\Users\...\deepseek-harness-master`），必须：

1. 先 `cd` 到 dsh 仓库根目录
2. 用 `pnpm dsh` 代替 `dsh`：

```sh
cd C:\Users\YX-ASUS\Desktop\deepseek-harness-master
pnpm dsh plugin --profile web add minecraft-dev --registry=https://registry.npmjs.org
```

### ⚠️ 安装后必须重启 dsh 服务

**正在运行的 dsh 不会自动加载新装的插件**。装完后：

1. 在跑 `pnpm dsh web` 的窗口按 `Ctrl+C` 停掉
2. 重新启动 `pnpm dsh web`
3. 新会话里插件生效

### 验证安装

```sh
pnpm dsh --profile web --dump-config     # 应出现 "# == minecraft-dev" 层与七行插件（skills/tools/preset + 4 个 subagent 实例）
```

### 卸载

```sh
dsh plugin --profile web remove minecraft-dev
```

### 安装 Minecraft 专家 agent（v0.6.0 起自动）

**装完插件重启 dsh 后自动安装，无需手动复制**：插件每次启动（挂载）时把自带的 `preset/minecraft/` 复制到 preset 扫描根：

- 目标：`$DSH_HOME/.agent-presets/minecraft/`（默认 `C:\Users\<用户>\.dsh\.agent-presets\minecraft\`；设了 `DSH_HOME` 时以 `$DSH_HOME` 为准）。
- 幂等：目标已有 `agent.cordis.yml` 就跳过，**绝不覆盖本地修改**；目录存在但缺 composition 文件时视为损坏并自动修复。
- 关闭：在 `$DSH_HOME/cordis.patch.yml`（或 profile 的 `cordis.patch.yml`）追加：

```yaml
- id: minecraft-preset
  config:
    autoInstallPreset: false
```

- 老版本（<0.6.0）或关闭自动安装时，手动复制：

```sh
# 1. 建用户 preset 根（dsh 自动把 ~/.dsh/.agent-presets 追加为 user 根，
#    但目录不存在时发现为空，需先创建）
mkdir -p ~/.dsh/.agent-presets

# 2. 复制 preset 目录（含 preset.yml + agent.cordis.yml）
cp -r <minecraft-dev 仓库>/preset/minecraft ~/.dsh/.agent-presets/
```

- 最终落盘：`~/.dsh/.agent-presets/minecraft/preset.yml` 与 `agent.cordis.yml`（本机默认 `C:\Users\YX-ASUS\.dsh\.agent-presets\minecraft\`；设了 `DSH_HOME` 时以 `$DSH_HOME` 为准）。
- **禁止**改内置安装目录（dsh 仓库 `apps/cli/config/agent-presets/`）：升级会被覆盖；卸载 = 删 `~/.dsh/.agent-presets/minecraft/`。
- 发现是**热扫描**：运行中的 dsh 无需重启即可看到新 preset；但**新会话**才生效。
- Windows 用户：可用 PowerShell `Copy-Item -Recurse` 等价命令。
- 切换位置：Web UI **新建会话**的 preset 选择器选「Minecraft 专家」。
- 验证：新建会话选该 preset，问「列出你能用的技能」，应返回 7 个 minecraft-* 技能 + mc_scaffold/mc_gradle + 4 个内置子代理 subagent_mc_* + subagent/subagent_fork/tool-workflow/ralph 工具；问「你是什么模型、工作目录在哪」，应回答本会话模型与目录（`{{model}}` / `{{cwd}}` 解析）。

## 使用

### 技能：模型自动加载，也可手动注入

- 发 MC 相关任务时，模型会自动调 `skill` 工具加载对应技能（会话中可见加载卡片）
- 手动注入：在输入框直接发 `/minecraft-paper-plugin`（或其它技能名）
- 查看全部：问 agent「列出你可以用的技能」

### 对话示例

```
创建一个 Paper 插件 my-plugin，包名 com.example.myplugin，MC 1.21.8
创建一个 Forge 1.12.2 模组 mymod，包名 com.example.mymod
写一个植物魔法 1.12.2 附属，注册一种新的花
用 mc_gradle 跑一下当前项目的 build
```

完整流程：模型加载技能 → 调 `mc_scaffold` 生成项目（含 wrapper）→ `mc_gradle build`（或 `cmd /c "gradlew.bat build"`）→ 产出 `build/libs/*.jar`。

### 四子代理团队委派（v0.5.0）

3+ 工作项的新插件/模组任务可用内置四子代理团队（A→B→C→D 委派链）；小改动建议 agent 内联完成。示例对话：

```
用四子代理团队帮我做一个 Paper 插件 my-plugin，包名 com.example.myplugin，MC 1.21.8
```

- 委派链严格 A → B → C → D 串行：A（方案）勘察项目并联网查证，写 `<项目>/PLAN.md` + 5 行摘要；B（框架）按 PLAN.md 用 `mc_scaffold` 搭骨架；C（内容）填充功能代码；D（编译审查）用 `mc_gradle` 构建/测试并出验证报告。前一环未返回不得调下一环。
- `<项目>/PLAN.md` 是唯一共享工件：B/C/D 每次重读；宿主改需求 = 先改 PLAN.md 再继续。
- 某环失败：附上失败报告重委派同一环，或宿主小修后继续；不要静默跳过 D。
- 每个子代理独立上下文、看不到宿主对话，委派 prompt 必须带绝对路径；最终回复有行数上限（A=5 行摘要、B/C≤30 行变更清单、D≤40 行验证报告）。

### 平台 × 版本支持矩阵（mc_scaffold）

| 平台 | 支持版本 | Java |
|---|---|---|
| paper | 1.20.x / 1.21.x / 26.x | 17 / 21 / 25 |
| fabric | 1.20.1 / 1.21.x / 26.2 | 17 / 21 / 25 |
| forge | 1.7.10 / 1.12.2 / 1.16.5 / 1.20.1 | 8 / 8 / 8 / 17 |
| neoforge | 1.20.1 / 1.21.x / 26.2 beta | 17 / 21 / 25 |
| spigot | 1.7.10 / 1.12.2 | 8 |

## 前置要求

- dsh 本体（Node ^22.19 || >=24，pnpm）
- **JDK**：现代线（1.18.2+）模板内置 foojay toolchain，缺 JDK 时 Gradle 自动下载（首次联网）；老线（1.7.10/1.12.2/1.16.5）需手动装 JDK 8 并设 `JAVA_HOME`
- spigot 1.7.10 模板构建前需按项目内 `libs/README.txt` 放置 spigot-api jar（该版本无公共 maven）
- 首次构建下载依赖需 5~15 分钟

## 开发

```sh
npm run test         # node --test 单测（纯函数，无 dsh 依赖）
npm run check-links  # 核对文档链接与 curse.maven projectId（联网；BROKEN=0 为通过）
```

## Known Limitations and Deferred Work

- API 参考为精选高频签名（非全量 Javadoc），每份标注核对日期；`npm run check-links` 校验 http(s) 链接与 curse.maven projectId（经 api.cfwidget.com；403 限流等归 UNVERIFIABLE），**fileId 仍须以 CurseForge 文件页「Curse Maven 代码」为准**。API 更新流程：改 references → `npm run check-links` → 人工复核 UNVERIFIABLE 项。
- `mc_gradle` 依赖目标机存在 taskkill（win32）；输出截断为头尾内联标记，不做 spill 文件。
- 用户本地同名技能（`~/.dsh/skills/` 等，rank 低于 600）会覆盖本包 bundled 技能——预期行为，冲突时删本地同名目录。
- 版本信息以 2026-08 为准；26.x 生态仍在快速变化（NeoForge 26.2 为 beta）。
- 市场类型判定：preset 文件（`preset.yml` + `agent.cordis.yml`）必须放在仓库的 `preset/minecraft/` 子目录——放仓库根目录会把市场类型从 cordis-plugin 误判为 agent-preset。
- preset 人设为 2026-08 基线；26.x 生态（NeoForge 26.2 beta）变化时以技能 references 更新为准。
- 4 个子代理的 toolFilter 白名单不含 `web_fetch`：宿主默认 `fetch: false` 未注册该工具（A 环只用 `web_search`）；若部署自定义开启 `fetch: true`，可把 `web_fetch` 加回 A 的 allow 名单。
- toolFilter 名单在子代理启动时校验（`tools.restrict()`），未知工具名直接报错——部署裁剪工具集（如禁用 tool-fs/tool-web）时需同步改 `cordis.patch.yml` 的 allow 名单（报错信息会列出已知全局工具名，可据此调整）。
- preset 自动安装（v0.6.0）发生在 dsh 启动（插件挂载）时——装完插件**必须重启 dsh** 才触发（这同时也是插件生效所需的重启）；只写入、永不覆盖已有 preset（`agent.cordis.yml` 存在即跳过）；关闭开关 `autoInstallPreset: false`；preset 内容更新不会自动传播——需删掉 `$DSH_HOME/.agent-presets/minecraft/` 让下次启动重新安装。
- 子代理继承宿主进程环境（`JAVA_HOME` 等）：老线（1.7.10/1.12.2/1.16.5）构建失败多为 JDK 8 环境问题而非代码问题，D 环会优先报环境。