MoonGridWorld: MoonBit 强化学习环境与基准任务套件 (Reinforcement Learning Environment & Benchmark Suite)

MoonGridWorld (moongridworld/moongridworld) 是专为 MoonBit 语言设计与实现的纯原生强化学习（Reinforcement Learning）环境与算法评测基准套件。本项目受 Python Ecosystem 中著名的 Gymnasium / OpenAI Gym 启发，旨在为 MoonBit 生态补齐智能体仿真、经典强化学习控制、动态规划理论验证与自动化基准测试（Benchmark）的核心基础设施。

无论是进行算法教学演示、智能体强化学习研究，还是构建复杂的仿真互动游戏，MoonGridWorld 均能提供统一、高效、内存安全且高度可拓展的接口支持。

---

✨ 核心特性 (Key Features)

1. 🚀 纯 MoonBit 原生构建，零第三方依赖

   • 仅依赖官方核心库 moonbitlang/core，无需绑定 C/C++ 或 Python 运行时。
   • 内置 *64位 XorShift 伪随机数发生器 (@core.Rng)**，确保在 WASM、Native 及 JS 多后端环境下每次评测都能获得精准相同的确定性轨迹（Deterministic Replayability）。

2. 🔌 规范的 Gymnasium 抽象接口设计 (@core.Env)

   • 提供了完备的观测与动作空间规范 (Discrete, Box, MultiDiscrete, TupleSpace)。
   • 统一的交互范式：reset(seed) -> (SpaceValue, Map[String, String]) 与 step(action) -> StepResult (observation, reward, terminated, truncated, info)。

3. 🗺️ 丰富的经典环境库 (5大环境范式)

   • GridWorld (@gridworld): 带有墙壁 (Wall)、机关门 (Door)、钥匙拾取 (Key)、陷阱 (Trap) 与冰面滑行 (Ice) 的丰富 2D 网格世界。
   • CliffWalking (@cliffwalking): Sutton & Barto 经典悬崖行走基准（4x12 网格），用于严谨检验在线与离线策略控制算法的风险偏好差异。
   • FrozenLake (@frozenlake): 4x4 / 8x8 随机滑动冰面迷宫，首创支持**精确状态转移概率查询 (get_transition_prob)**，打通了蒙特卡洛采样与精确动态规划求解之间的壁垒。
   • MultiArmedBandit (@bandit): 多臂老虎机基准（包括 BernoulliArm、GaussianArm、UniformArm 与非平稳漂移 NonStationaryGaussianArm）。内置 Sutton & Barto 10臂高斯基准测试平台 (10-Armed Gaussian Testbed) 并实时记录即时遗憾值 (Regret)。
   • Maze (@maze): 具备 DFS 随机图深度优先生成 (generate_dfs_maze) 算法的随机迷宫生成器，为强化学习提供源源不断的多样化拓扑挑战。

4. 🧠 完备的经典算法库 (@tabular)

   • QTable & Epsilon-Greedy: 高效的一维连续数组展平 Q 表存储与 $ϵ\backslash epsilon$-贪心探索策略。
   • Q-Learning (Off-Policy TD Control): 经典的异策略时序差分学习智能体。
   • SARSA (On-Policy TD Control): 同策略时序差分学习智能体。
   • Value Iteration (Dynamic Programming): 基于精确状态转移矩阵的动态规划最优值函数求解器，实现对 FrozenLake 等复杂随机环境的数学理论最优解验证。

5. 📊 自动化评测引擎与 Markdown 报告输出 (@benchmark)

   • 内置自动化评估引擎，批量运行多个回合的智能体探索过程，计算**平均回报率 (Mean Return)、成功率 (Success Rate)、平均耗时步数 (Mean Steps)**。
   • 提供 BenchmarkReport::to_markdown() 方法，可直接输出符合学术报告与 GitHub/GitLink 文档规范的 Markdown 表格，极大便利了实验结果展示。

---

🏗️ 仓库结构与包概览 (Architecture)

moongridworld/moongridworld/
├── core/                # [@core] 核心原语: 随机数生成器 (Rng)、强化学习空间 (Space)、环境 Trait 接口 (Env)、轨迹缓冲
├── envs/                # 环境合集 (Environment Suites)
│   ├── gridworld/       # [@gridworld] 2D 多道具互动网格世界与程序化生成
│   ├── cliffwalking/    # [@cliffwalking] Sutton & Barto 悬崖行走环境
│   ├── frozenlake/      # [@frozenlake] 随机滑动冰湖环境与转移概率查询
│   ├── bandit/          # [@bandit] 10臂高斯老虎机与非平稳漂移环境
│   └── maze/            # [@maze] 随机 DFS 迷宫生成与探索环境
├── algo/
│   └── tabular/         # [@tabular] Q-Learning、SARSA、QTable 与 Value Iteration 动态规划求解器
├── eval/
│   └── benchmark/       # [@benchmark] 多环境自动化基准评测引擎与 Markdown 报告生成
└── cmd/
    └── main/            # [@main] 命令行交互主程序与全局评测展示样例

---

⚡ 快速开始 (Quick Start)

1. 构建与检查

本项目采用 MoonBit 官方构建工具 moon 进行包管理与构建：

# 检查整个项目的静态类型与语义语法
moon check

# 运行所有环境与算法包的单元测试 (WASM-GC 目标)
moon test --target wasm-gc

2. 运行命令行全局评测样例

通过运行主程序 @main，实时观看所有环境的仿真演示与 Q-Learning 自动化训练生成的 Markdown 报告：

moon run cmd/main --target wasm-gc

---

💡 代码示例 (Code Examples)

1. 创建网格环境并进行 Q-Learning 强化学习训练

import {
  "moongridworld/moongridworld/envs/gridworld",
  "moongridworld/moongridworld/algo/tabular",
}

fn main {
  // 1. 初始化 5x5 网格世界环境
  let env = @gridworld.GridWorldEnv::new(width=5, height=5, max_steps=100)
  
  // 2. 初始化 Q-Learning 智能体 (25个状态, 8个动作)
  let agent = @tabular.QLearningAgent::new(
    num_states=25,
    num_actions=8,
    alpha=0.2,
    gamma=0.99,
    epsilon=1.0,
    epsilon_decay=0.98,
    min_epsilon=0.05
  )
  
  let rng = @core.Rng::new(42UL)
  
  // 3. 执行单回合训练交互
  let (obs, _) = env.reset()
  let mut state = match obs {
    DiscreteVal(s) => s
    _ => 0
  }
  let mut done = false
  while !done {
    let action = agent.choose_action(state, rng)
    let res = env.step(DiscreteVal(action))
    let next_state = match res.observation {
      DiscreteVal(s) => s
      _ => 0
    }
    // 时序差分更新 Q 表
    let _ = agent.step_update(state, action, res.reward, next_state, res.terminated)
    state = next_state
    done = res.terminated || res.truncated
  }
  agent.decay_epsilon()
}

2. 对随机冰湖进行精确值迭代 (Exact Value Iteration)

import {
  "moongridworld/moongridworld/envs/frozenlake",
  "moongridworld/moongridworld/algo/tabular",
}

fn main {
  // 创建标准 4x4 随机滑动冰面环境
  let env = @frozenlake.FrozenLakeEnv::new(map_name="4x4", is_slippery=true)
  
  // 执行动态规划精确值函数求解 (Sutton & Barto 4.4)
  let result = @tabular.solve_frozenlake_value_iteration(env, gamma=0.99)
  
  println("精确收敛迭代次数: " + result.iterations.to_string())
  println("初始状态最优期望价值 V*(s0): " + result.value_table[0].to_string())
}

---

🏆 OSC 2026 参赛项目说明 (OSC 2026 Declaration)

本项目为 MoonBit 国产开源生态大赛（OSC 2026）Track 1: 核心类库与应用生态开发 的高标准参赛作品。

• 原创性与工程规范：全库所有包（包括 @core、@gridworld、@cliffwalking、@frozenlake、@bandit、@maze、@tabular、@benchmark、@main）均采用规范的 MoonBit 包命名与 ///| 现代化的文档块排版，通过了严格的静态类型验证与单元测试覆盖。
• 拓展性与长远价值：不仅为经典的算法对比提供了现成工具，其模块化的 @core.Env Trait 设计也为未来拓展多智能体强化学习（MARL）、深层连续控制环境（如 CartPole、Pendulum）以及 WASM 前端图形化展示打下了坚实基础。

---

📄 开源协议 (License)

Licensed under the Apache License, Version 2.0.