minecraft-dev

LIMITATIONS

Known limitations

- 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-09 为准；26.x 生态仍在快速变化（**Paper 26.3 只有 `-alpha` 构建、NeoForge 26.3 只有 `-beta`**，26.2 两边都已 stable）。 - **26.3 已真机构建验证，但生态仍是 alpha/beta 期**：2026-09 实跑四组构建全部成功 —— paper 26.2（对照，13s）、paper 26.3（8s，`26.3.build.+` 命中上游 `-alpha` 构建）、fabric 26.3（23s）、neoforge 26.3（6m43s，NeoForge `26.3.0.12-beta` + moddev 2.0.147）。但 **Paper 26.3 目前只有 `-alpha` 构建、NeoForge 26.3 只有 `-beta`**，生产使用前请自行评估；26.2 两边都已 stable。 - **fabric 模板的 toolchain 修复（v0.9.0）**：两个 fabric 模板此前缺 foojay 解析器与 `java.toolchain`，只写 `options.release` + source/targetCompatibility —— 环境 JDK 低于目标时（本机默认 Java 22、26.x 线目标 25）直接报「不支持发行版本 25」且无法自举。现在与 paper/neoforge 一致：`settings.gradle` 带 `org.gradle.toolchains.foojay-resolver-convention:1.0.0`，`build.gradle` 用 `java { toolchain { languageVersion = JavaLanguageVersion.of(N) } }`，由 foojay 自动 provision。**这是 fabric（含 1.20/1.21 线）长期存在的缺陷，本次因真机构建才暴露。** - 市场类型判定：preset 文件（`preset.yml` + `agent.cordis.yml`）必须放在仓库的 `preset/minecraft/` 子目录——放仓库根目录会把市场类型从 cordis-plugin 误判为 agent-preset。 - preset 人设为 2026-09 基线；26.x 生态（NeoForge 26.3 beta）变化时以技能 references 更新为准。 - **两种 preset 形态**（v0.9.0）：`agent.cordis.yml` 是 0.1.5/0.1.6 的目录安装源，`rows.js` 由它生成、供 0.1.7+ 的 `agentPresets.register()` 使用；`test/preset-rows-parity.test.js` 锁死两者一致（行 id/name 顺序、标量配置、所有块标量的逐字节文本）。只有两处刻意不同：`!!js` 平台表达式在 JS 里是真实布尔值，`dsh-workflow-worker-thread` 在 0.1.7 里换成 `dsh-workflow-ptc`。 - **四子代理的角色迁移（v0.10.0，dsh 0.2.1 起）**：`persona` / `toolFilter` 已从 `tool-subagent` 删除（写了两者之一会在挂载时抛错），角色改由 4 个 Agent Preset 承载，宿主行用 `agentPreset` 指过去。由此带来三条限制： - **≤ 0.2.0 没有角色人设**：`agentPreset` 在旧版本上是未知键、被静默忽略，4 行仍能挂载，但子代理退化为"无角色的 spawn 子代理"。旧版本想要角色请直接在预设选择器里选 `mc-plan` / `mc-skeleton` / `mc-content` / `mc-verify`（**0.1.5 例外**：该线只认 `$DSH_HOME/.agent-presets/` 目录形态，插件只提供 `minecraft` / `minecraft-architect` 两个目录，4 个角色仅存在于 0.1.7+ 的注册形态里）。 - **工具范围变成插件粒度**：新模型按整行插件组合，不能只给 `read` 不给 `write`；A 环因此同时拿到 `write` 与 `edit`。全局注册的 `mc_scaffold` / `mc_gradle` 对所有角色可见，靠人设约束谁去跑。 - **4 个角色 preset 会出现在预设选择器里**（`PresetDefinition` 没有 hidden 字段），已用 `order: 91~94` 排到最后，名字带 `minecraft-dev 子代理 X · …` 前缀。 - **委派一律异步**：0.2.1 取消了前台阻塞模式，调用立即返回 id、完成时通知；人设已写明"把最终答复放进最后一条消息"。 - preset 自动安装（v0.6.0，**仅 0.1.5/0.1.6 的目录形态**）发生在 dsh 启动（插件挂载）时——装完插件**必须重启 dsh** 才触发（这同时也是插件生效所需的重启）；只写入、永不覆盖已有 preset（`agent.cordis.yml` 存在即跳过）；关闭开关 `autoInstallPreset: false`（只影响文件拷贝，不影响 0.1.7 的服务注册）；preset 内容更新不会自动传播——需删掉 `$DSH_HOME/.agent-presets/minecraft/` 让下次启动重新安装。**0.1.7+ 是服务注册，没有文件、没有这个陈旧问题：每次启动都按 `rows.js` 重新声明。** - **preset 人设更新（v0.7：铁律 7 信息核对）需重装 preset**：删 `$DSH_HOME/.agent-presets/minecraft/` → 重启 dsh → 自动重装（人设含"信息不足先批量提问"行为规则；不重装则只有技能层生效，行为规则缺失）。**重装会覆盖手改——更新前先备份该目录**。 - 子代理继承宿主进程环境（`JAVA_HOME` 等）：老线（1.7.10/1.12.2/1.16.5）构建失败多为 JDK 8 环境问题而非代码问题，D 环会优先报环境。 - **v0.8.0 架构师预设必须在重启 dsh 后才可用（实测）**：预设行 `minecraft-dev/codex` 是从 profile 目录解析的，而运行中的 dsh 进程已缓存了旧版 `package.json`（无 `./codex` 导出）与旧 `lib/present.js`，于是会报 `Package subpath './codex' is not defined by "exports"` 或 `does not provide an export named 'codexCallView'`。**重装插件后重启 dsh 即可**（新进程读的是磁盘上的新清单）；重启前的挂载失败不代表文件有问题。 - `preset.yml` 用严格 YAML 解析（js-yaml）：`name`/`description` 里出现 `[`、`]`、`: ` 等必须**加引号**，否则整个元数据块被丢弃，预设会显示成无名且没有 roster 顺序（v0.8.0 开发中踩过：未加引号的 `[TODO: Agent B]`）。 - `mc_codex` 的 `filesChanged` 是按 mtime 扫描项目目录得出的（已跳过 `.dsh/.git/node_modules/build/...`），因此可能包含子进程自己产生的临时文件（例如 PowerShell 的 `ModuleAnalysisCache`）——这是如实报告，不是项目文件清单。 - `mc_codex` 用的是**你自己账号的 Codex**，DSH 不会显示这笔消耗（订阅计入用量窗口 / API key 计入余额）；技能因此把委派上限写死为「架构 1 次 + 修复 ≤1 次」，且失败不自动重试。 - `mc_codex` 的 `mode: "app-server"` 走官方 `codex app-server --stdio`（NDJSON JSON-RPC：`initialize` → `initialized` → `thread/start` → `turn/start` → `turn/completed`），*