MinecraftTrainer

MinecraftTrainer 是一个独立于 MinecraftBot 的持续学习项目。它不会直接操作 Minecraft 协议，而是作为 MCP 主机启动并调用 MinecraftBot，在 Skill 边界采集状态、验证结果、计算反馈、生成训练集、执行 QLoRA/SFT/DPO，并通过独立评测决定是否晋级模型。

项目边界

交互模式：Demiurge -> MinecraftBot -> Minecraft Server
训练模式：MinecraftTrainer -> MinecraftBot -> Minecraft Server
                                |
                                +-> 结构化反馈与轨迹
                                +-> Python QLoRA Worker
                                +-> 候选模型评测/晋级/回滚

• MinecraftBot 保持 TypeScript/Mineflayer 项目，不承载奖励和训练逻辑。
• Rust 核心负责 MCP、课程、反馈、SQLite、评测、调度和本地 API。
• Python Worker 只负责 PyTorch/Transformers/TRL/PEFT 训练。
• 同一个离线用户名不能同时被 Demiurge 和 MinecraftTrainer 启动；两种模式应互斥。

已实现能力

• 原生 MCP stdio 客户端，直接使用 MinecraftBot 现有工具。
• 自动启动、连接等待、技能查询、技能执行和安全关闭。
• 木器、石器、铁器、钻石、下界准备的课程图。
• Skill 级 SMDP 轨迹，不记录 50ms 级动作噪声。
• 前态/后态、背包差分、血量、饥饿、位置、危险与执行证据。
• Potential-Based 目标进度反馈。
• Episode 与 Lifetime 两级科技里程碑。
• 多维奖励向量和可配置权重。
• 重复动作、物品丢弃/捡回循环等防刷分检查。
• 死亡终止与近期高层决策因果归因。
• SQLite WAL 轨迹、Episode、里程碑、模型和评测记录。
• SFT成功/部分成功轨迹导出。
• 相似状态下高低奖励动作的DPO偏好对导出。
• 隔离Python QLoRA/SFT/DPO Worker与严格JSONL协议。
• 候选模型综合指标门禁、晋级目录与回滚副本。
• 只读管理API：健康、状态和轨迹。
• 无人值守“采集→数据门槛→QLoRA候选”循环，可持续运行到手动停止。
• 生存状态抢占科技课程，目标数量阈值由环境事实验证。
• 近期成功率驱动的课程拆分/提速、置信度校准和奖励分布审计。
• HER风格的部分成功目标重标记，避免浪费有效探索轨迹。

前置条件

1. Minecraft Java 独立服务器正在运行。
2. C:\Users\fuqiang\Desktop\mc 中的 MinecraftBot 已执行 pnpm build。
3. MinecraftBot 的离线用户名和真人用户名不同。
4. 本地 OpenAI 兼容模型服务运行在配置的地址，默认 http://127.0.0.1:8080/v1。
5. 真实训练需要 NVIDIA CUDA 环境和 trainer/requirements.txt。

快速验证

cd C:\Users\fuqiang\Desktop\bot
.\scripts\setup.ps1 -SkipTrainingDependencies
cargo test
.\.venv\Scripts\python.exe -m unittest trainer.test_worker
cargo run -- --config configs/default.toml doctor
cargo run -- --config configs/default.toml init-db
cargo run -- --config configs/default.toml analyze

去掉 -SkipTrainingDependencies 会安装真实 QLoRA 所需的 CUDA/PyTorch 组件；只验证项目时无需下载这些大体积依赖。

Python Worker 的 dry-run 不加载任何深度学习依赖，可验证整个作业协议：

cargo run -- --config configs/default.toml train dry-run --allow-small-dataset

自主游戏采集

先修改 configs/default.toml 中的服务器、用户名和模型地址，再运行：

cargo run --release -- --config configs/default.toml run --max-goals 5

Rust 将：

1. 以 MCP 模式启动 MinecraftBot。
2. 等待游戏角色连接。
3. 依据科技树选择当前总体目标。
4. 调用本地8B模型生成 Skill 计划。
5. 逐个执行 Skill，在每一步前后抓取状态。
6. 验证结果、计算奖励并写入 data/feedback.db。
7. 死亡时结束生命 Episode 并归因近期决策。

每次自主运行还会在 logs/model-actions/ 生成一个独立的 JSONL 审计日志。日志记录模型看到的目标与状态、近期反馈、完整原始响应、公开决策摘要、Skill 参数、执行结果和奖励，并在每条事件后立即刷新，便于运行中查看。该目录已被 Git 忽略。

无人值守采集与训练

单轮采集后按门槛训练：

cargo run --release -- --config configs/default.toml autopilot --rounds 1

持续运行到按下 Ctrl+C：

.\scripts\run-autopilot.ps1 -Rounds 0 -MaxGoals 20

每轮先启动 MinecraftBot 自主游戏，结束后统计新增轨迹。只有新增轨迹和可用训练样本都达到配置门槛时才启动训练。训练产物登记为 candidate_pending_evaluation，不会自动覆盖当前模型。16GB显存机器应在 [automation.before_training] 与 [automation.after_training] 配置推理服务的停止/恢复脚本，确保推理与QLoRA不抢显存。

数据集与训练

# 导出成功轨迹
cargo run -- --config configs/default.toml export sft

# 导出偏好对
cargo run -- --config configs/default.toml export dpo

# 8B QLoRA SFT
cargo run --release -- --config configs/default.toml train sft

# 在SFT适配器基础上准备DPO数据；基础模型/适配器路径可在配置中切换
cargo run --release -- --config configs/default.toml train dpo

默认要求至少500条可用样本，防止误用极小数据污染模型。实验时可显式传入 --allow-small-dataset。

16GB显存的默认参数：4-bit NF4、序列长度2048、micro batch 1、梯度累积16、LoRA rank 16。训练期间不同时运行本地8B推理。

反馈公式

每个 Skill 的总反馈由分项组成：

R = milestone + goal + progress + novelty + information
    + survival + efficiency + damage + loss + violation

原始分项和总分同时保存。progress 使用行动前后目标势函数差；重复拾取、重复放置和无进展循环会被标记，相关正奖励被撤销。奖励函数版本写入每条轨迹，未来可以离线重算而不丢失原始事实。

评测和晋级

游戏评测应在固定但未参与训练的世界种子上收集候选与基线指标。指标JSON格式见 configs/baseline-metrics.example.json。

cargo run -- --config configs/default.toml evaluate `
  --candidate-version mc-core-v2 `
  --candidate-metrics data/candidate-metrics.json `
  --baseline-version mc-core-v1 `
  --baseline-metrics configs/baseline-metrics.example.json

cargo run -- --config configs/default.toml promote `
  --version mc-core-v2 `
  --candidate-dir models/candidates/mc-core-v2

门禁会拒绝综合分不足、死亡率回退、无效动作增加或奖励投机增加的候选。晋级前会把当前模型复制到 models/rollback。

管理API

cargo run -- --config configs/default.toml serve

• GET /health
• GET /v1/status
• GET /v1/trajectories?limit=50
• GET /v1/analysis?limit=5000

API只绑定 127.0.0.1，适合后续由Tauri客户端调用。

安全原则

• 环境事实由MinecraftBot状态验证，模型不能自报成功。
• 奖励系统无权执行游戏动作。
• Python Worker无权晋级模型。
• 未通过独立评测的候选不得进入 models/current。
• 训练世界应与真人长期存档分开，并定期备份。
• 自主模式和Demiurge互动模式必须互斥使用同一游戏账号。

反馈、课程和安全门禁的论文依据见 docs/REFERENCES.md。