MoonGridWorld: 纯 MoonBit 原生强化学习环境与基准任务套件

MoonGridWorld 是专为 2026 MoonBit 国产基础软件开源大赛 (OSC 2026) 精心打造的纯 MoonBit 原生强化学习（Reinforcement Learning, RL）环境套件与算法评估基准框架。

项目的设计灵感源自经典的 OpenAI Gym / Gymnasium 以及 Sutton & Barto 的强化学习圣经《Reinforcement Learning: An Introduction》，填补了当前 MoonBit 生态在智能决策模拟、离散动态控制与算法评测环境领域的空白。通过高度抽象的类型擦除接口设计、确定性的 PCG32 随机数生成器、支持 BFS 可解性验证的程序化地图生成器以及表格型基础智能体，MoonGridWorld 为 MoonBit 开发者与研究人员提供了成熟、稳定且具备极强扩展性的仿真实验平台。

🌟 为什么选择强化学习环境作为 OSC 2026 选题？

成熟交叉领域，避免重复造轮子：通过 mooncakes.io 广泛调研，目前生态中已存在基础的数学库与简单的桌游示例，但缺乏系统化、模块化的标准强化学习基准框架。本项目结合了数值计算、随机仿真、空间图搜索算法（BFS/DFS）以及智能控制决策，具有极高的工程价值和学科交叉深度。
完全解耦与极高可扩展性：基于闭包包装器 AnyDiscreteEnv，无需受限的 trait 虚函数分发即可对任意异构环境进行统一调用。未来可轻松拓展连续状态空间（Box Space）、深度强化学习接口（如接入神经网络库）、以及 WebAssembly 前端实时交互渲染器。
高质量工程落地：全库包含 27 个纯 MoonBit 核心源文件、约 2,760 行原生代码、28 个高质量自动化单元测试，确保零警告 (0 warning) 与标准规范。

🏗️ 系统架构与模块全景

moongridworld/
├── core/            # 核心抽象层：环境接口定义与状态/动作空间规范
├── utils/           # 底层工具：PCG32 确定性随机数生成器与统计学/距离计算工具
├── envs/            # 强化学习标准环境库 (6大核心套件)
│   ├── gridworld/   # 经典网格世界：支持障碍物、陷阱、终点及随机滑移风向阻力
│   ├── cliffwalking/# Sutton 悬崖行走：4x12 悬崖惩罚与即时起点重置逻辑
│   ├── frozenlake/  # 冰湖环境：4x4 / 8x8 标准地图，包含 0.66 侧向滑移概率动力学
│   ├── bandit/      # 多臂老虎机：包含伯努利、高斯及非平稳随机游走均值老虎机
│   ├── maze/        # 钥匙-门子目标迷宫：分层强化学习经典测试任务
│   └── multiagent/  # 多智能体环境：支持零和博弈（竞争竞速）与协同合作动力学
├── generator/       # 程序化环境生成器：基于 BFS 连通性校验与递归回溯 DFS 算法
├── solvers/         # 基础决策算法库：Tabular Q-Learning、Tabular SARSA 与随机基线
├── trajectory/      # 轨迹记录与导出模块：支持折扣回报计算及 JSON/CSV 格式化导出
├── evaluator/       # 自动化基准引擎：自动运行训练轮次并生成标准 Markdown 对比表
└── top/             # 顶级执行入口 (main.mbt)：一键执行全套环境评估基准流程

核心设计特性

类型擦除的统一闭包接口 (core::AnyDiscreteEnv)
在 MoonBit 当前的版本中，由于结构体默认只读属性及 trait 方法对局部状态更改的约束，本库设计了基于函数闭包包覆的 AnyDiscreteEnv。各个环境只需实现具体的 reset、step、render，随后借助 .to_any() 即可自动转换为标准统一接口，支持各类解耦的 Solver 和 Evaluator 调用。
确定性 PCG32 随机数引擎 (utils::RNG)
内置纯 MoonBit 实现的 PCG（Permuted Congruential Generator）64-bit 状态转 32-bit 输出随机引擎，支持均匀分布、伯努利分布、正态分布（基于 12-Uniform 中心极限定理极速采样），确保训练轨迹与评测实验跨平台 100% 可复现。
BFS 可解性校验的程序化地图生成 (generator)
在随机生成含有高密度障碍物与陷阱的 GridWorld 时，通过 Breadth-First Search (BFS) 自动校验起点至终点的图连通性。如果生成的地图不可达，自动回溯重采样，确保任意程序化生成的迷宫与网格关卡始终可解。
支持离线数据与前端可视化的轨迹导出 (trajectory)
EpisodeRecorder 不仅支持动态计算累积折扣回报 $\sum_{t=0}^{T} \gamma^t R_t$ ，更能直接导出符合 CSV 表格标准（适用于 Python NumPy / Pandas 离线 RL 训练分析）和 JSON 序列化标准（适用于 Web 前端回放引擎渲染）的完整轨迹。

⚡ 快速开始与使用指南

1. 环境准备

确保已安装 MoonBit 原生开发工具链（建议版本 0.1.20260703 及以上）：

moon version

2. 获取代码与编译

git clone https://github.com/bins-c-language/moongridworld.git
cd moongridworld
moon check

3. 执行全套基准自动化测试

通过 moon test 自动运行所有包的 28 个自动化单元测试，覆盖全部环境动力学、极值竞争争夺、随机分布与状态转换：

moon test

执行输出结果：

Total tests: 28, passed: 28, failed: 0.

4. 运行全能基准评估套件 (`main` 入口)

借助 moon run top 命令，可以一键驱动多套智能体（Q-Learning, SARSA, Random Baseline）在各大标准环境中展开自动化测评，并在控制台实时渲染对齐的 Markdown 对比数据表：

moon run top

📊 基准测评结果与算法对比

通过对 GridWorld、Sutton CliffWalking、OpenAI FrozenLake、10-Arm Multi-Armed Bandit、Key-Door Maze 以及 6x6 Procedural Grid 的多轮测评，经典表格型强化学习算法在短轮次探索后明显超过随机策略：

Environment	Solver	Mean Return +- Std	Success Rate	Avg Steps
GridWorld-v0	Tabular Q-Learning	-7.99 +- 8.52	28.00%	44.82
GridWorld-v0	Tabular SARSA	-8.27 +- 8.55	28.00%	51.62
GridWorld-v0	Random Baseline	-9.06 +- 9.86	25.00%	56.45
CliffWalking-v0	Tabular Q-Learning	-2105.33 +- 1641.38	65.00%	287.69
CliffWalking-v0	Tabular SARSA	-1306.58 +- 1257.36	61.00%	331.43
CliffWalking-v0	Random Baseline	-4036.75 +- 1168.66	15.00%	467.80
FrozenLake-v0	Tabular Q-Learning	0.01 +- 0.10	1.00%	8.22
FrozenLake-v0	Tabular SARSA	0.01 +- 0.10	1.00%	7.28
FrozenLake-v0	Random Baseline	0.00 +- 0.00	0.00%	8.20
MultiArmedBandit-10Arm	Tabular Q-Learning	325.55 +- 158.44	N/A	1000.00
MultiArmedBandit-10Arm	Random Baseline	31.88 +- 40.70	N/A	1000.00
MazeKeyDoor-v0	Tabular Q-Learning	5.22 +- 7.77	91.25%	88.68
MazeKeyDoor-v0	Random Baseline	-8.86 +- 9.71	40.00%	171.60
ProceduralGrid-6x6	Tabular Q-Learning	-12.05 +- 7.54	13.33%	58.05
ProceduralGrid-6x6	Random Baseline	-16.59 +- 3.36	0.00%	86.70

[!NOTE] 说明：CliffWalking-v0 中 Q-Learning 虽偶尔探入悬崖导致方差偏大，但到达终点胜率（65%）和寻找最短路径平均步数（287步 vs 随机467步）展现了 off-policy 控制的优势；在分层导航任务 MazeKeyDoor-v0 中，Q-Learning 在 80 轮训练后胜率达到惊人的 91.25%，完全学会了“先取钥匙、开启门锁、抵达终点”的连贯策略。

🛠️ 代码开发与 API 使用示例

自定义并训练一个网格智能体

fn demo_training() -> Unit {
  // 1. 初始化 5x5 网格世界并转换为 AnyDiscreteEnv
  let cfg = @gridworld.GridWorldConfig::default()
  let env = @gridworld.GridWorldEnv::new(cfg).to_any()

  // 2. 初始化 Q-Learning 智能体 (状态空间: 25, 动作空间: 4)
  let agent_cfg = @solvers.TabularConfig::default(25, 4)
  let agent = @solvers.TabularQLearning::new(agent_cfg)

  // 3. 执行单回合训练并记录轨迹
  let mut state = env.reset()
  let mut done = false
  let recorder = @trajectory.EpisodeRecorder::new(1, "GridWorld-v0")

  let mut step_count = 0
  while !done && step_count < 100 {
    step_count = step_count + 1
    let action = agent.select_action(state)
    let res = env.step(action)
    
    // 更新 Q 表
    let _ = agent.update(state, action, res.reward, res.obs, res.is_done())
    
    // 记录轨迹步骤
    recorder.record_step(step_count, res.obs, action, res.reward, res.is_done(), res.info)
    
    state = res.obs
    if res.is_done() {
      done = true
    }
  }

  // 4. 导出为 CSV 或 JSON 供数据工程及前端回放
  let json_trajectory = recorder.to_json()
  let csv_data = recorder.to_csv()
}

📋 OSC 2026 参赛项目自查与开源规范

本项目严格遵照 moonbit-agent-guide 与 osc2026-guide 规范完成自查自纠与多轮重构完善：

仓库结构规范：
- 根目录下拥有清晰的 moon.mod.json，且包含完备的 LICENSE、README.md、.gitignore。
- 所有子包（core, utils, envs/*, generator, solvers, trajectory, evaluator, top）相互依赖解耦清晰，不产生任何循环依赖。
开源开源协议与来源声明：
- 全库代码采用完全开源的 Apache-2.0 License。
- 本项目为团队在 MoonBit 语言环境下的原创架构研发，无任何直接复制或依赖第三方未开源/商业代码库的行为。
**提交历史记录 (Git Commit History)**：
- 仓库经过 13 次渐进式原子化提交（Progressive Atomic Commits），采用标准的 feat(...), test(...), refactor(...) 前缀提交日志，清晰记录了从工具类、核心接口、多环境实现到测试评估完整生命周期。
编译与自动化测试指标：
- moon check 检查项：0 Errors, 0 Warnings。
- moon test 自动化指标：**28/28 tests PASSED (100% 通过率)**。
- 纯 .mbt 代码行数规模：2,760 行 原生代码（满足并超越大赛高质量基础库规模要求）。

📄 许可证 (License)

本项目采用 Apache License 2.0 开源协议。欢迎广大开源爱好者提 Issue、PR 与建议！