面向 Minecraft 模组项目的本地 AI 开发工作台。当前支持 Minecraft 26.1.2、 NeoForge 26.1.2.84 和 Java 25。
Minecraft Mod Studio 可以导入已有项目，调查问题或规划新功能，在隔离的暂存工作区 （Staging Workspace）中准备候选改动（Candidate）并运行验证。人工审批模式由用户审查 并接受或放弃文件差异；自动审批模式则在需求确认后自动批准方案、继续可恢复的修正， 并在验证通过后自动应用候选改动。
与直接修改项目的编码 Agent 不同，Studio 将模型的调查、规划和编辑能力与主控程序 （Host）的权限、状态、验证和最终写入控制分开。当前提供 Mod Doctor（模组诊断） 和 Feature Workshop（功能开发） 两种任务模式。
无需 API Key、JDK、Gradle 或 Node.js，即可体验从计划审批到变更审查的完整界面：
py -3.11 -m pip install .
mod-studio demo演示不会调用模型服务（Provider）或执行 Gradle，并会在退出后清理临时项目。更多说明见
docs/no-credential-demo.md。
flowchart TB
subgraph PREPARE["01 · 需求准备"]
direction LR
A["导入项目"] --> B{"任务类型"}
B -->|"修复"| C["描述问题与验收目标"]
B -->|"开发"| D["迭代并确认需求草案"]
end
subgraph EXECUTE["02 · 规划与执行"]
direction LR
C --> E["只读调查"]
D --> E
E --> F["生成执行方案"]
F --> G["按审批方式批准"]
G --> H["暂存工作区修改"]
H --> I["确定性验证"]
end
subgraph FINISH["03 · 结果处理"]
direction LR
I -->|"通过"| J["待审查的候选改动"]
J -->|"人工"| K["审查后接受 / 放弃"]
J -->|"自动"| L["自动应用"]
I -->|"普通失败 / 中断"| M["保留候选改动"]
M -->|"同一方案内有限续跑"| H
M -->|"已阻塞 / 达到上限"| N["等待检查或放弃"]
end
classDef intake fill:#f1f5f9,stroke:#64748b,color:#0f172a,stroke-width:1.5px
classDef work fill:#ecfeff,stroke:#0e7490,color:#164e63,stroke-width:1.5px
classDef success fill:#ecfdf5,stroke:#15803d,color:#14532d,stroke-width:1.5px
classDef recovery fill:#fff7ed,stroke:#c2410c,color:#7c2d12,stroke-width:1.5px
class A,B,C,D intake
class E,F,G,H,I work
class J,K,L success
class M,N recovery
- 需求协作：开发新功能时，可先把简短想法生成完整需求草案，通过多轮反馈修订后 人工确认；已确认需求也可复制为新任务继续补全。
- 只读规划：调查阶段只能读取获准的项目文件、依赖源码和知识记录。
- 精确授权：用户批准计划后，模型只能修改计划列出的文件。
- 隔离执行：模型编辑和验证在暂存工作区中进行，不直接修改导入项目。
- 两种审批方式：人工模式逐次确认执行方案和候选改动；自动模式跳过这些确认并在 验证通过后自动应用改动，但开发任务的需求草案仍须人工确认。
- 有界继续修正：普通执行失败或 Studio 中断会保留当前候选改动，可在同一个已批准 执行方案和写入授权下有限续跑；不会重新规划或扩大可写范围。
- 新鲜验证：验证结果与当前候选改动和校验器版本绑定，过期结果不能用于应用。
- 可恢复写入：应用前会检查项目漂移；多文件写入支持中断恢复和安全回滚。
越权写入、受保护路径写入等工作区安全违规不会进入继续修正，而是立即终止并清理暂存 工作区。保留的候选改动或导入工作区发生版本漂移时，主控程序也会拒绝续跑或应用。 自动审批只减少人工点击，不绕过这些主控程序安全与验证边界。
架构、状态机和信任边界见 docs/architecture.md。统一领域术语见
CONTEXT.md，关键设计取舍见 docs/adr/。
需要 Python 3.11。真实任务还需要支持 tool calling 的模型服务、JDK 25，以及可信的 Gradle 环境。
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev,e2e]" build
Copy-Item .env.example .env.local
# 编辑 .env.local，填写模型服务、JDK 和 Gradle 配置
.\.venv\Scripts\mod-studio.exe doctor
.\.venv\Scripts\mod-studio.exe serveserve 会打开带一次性认证信息的本地页面，服务仅监听 127.0.0.1。如不希望自动打开
浏览器，可使用 mod-studio serve --no-open。界面中的模型设置可以更新本地模型服务
地址、模型和 API Key；由进程环境变量固定的字段会保持只读，密钥不会回显。
常用检查：
.\.venv\Scripts\python.exe -m pytest -o addopts= -q
.\.venv\Scripts\python.exe -m ruff check src tests scripts browser_tests
.\.venv\Scripts\python.exe -m mypy前端位于 src/mod_studio/web，使用 Node.js 安装依赖后可运行 npm test 和
npm run build。完整的证据复现方法见
docs/reproducible-evidence.md。
当前仓库包含 Python、React 和真实浏览器流程测试，并维护主控程序安全消融与模型服务
冻结用例报告。最新结果、适用范围和复现方式见
docs/evaluation-summary.md。
当前限制：
- 仅支持 Minecraft 26.1.2、NeoForge 26.1.2.84 和 Java 25。
- 模型服务评测覆盖有限的冻结用例，不代表任意 NeoForge 需求都能完成。
- 暂存工作区隔离模型生成的修改，但不是操作系统沙箱；导入项目的 Gradle 脚本仍须可信。
- 远程模型服务会接收任务所需的描述、源码片段和构建诊断，其数据策略仍然适用。
本地界面、暂存工作区、任务日志和构建日志保存在 .modstudio/ 下。删除该目录会删除
Studio 的任务历史和临时候选，但不会删除导入的模组项目。
Gradle 仅接收运行所需的最小环境配置；完整威胁模型和漏洞报告方式见
SECURITY.md。
项目代码采用 MIT 许可证。第三方测试样例的许可说明见
THIRD_PARTY_NOTICES.md。