MoonTrajectory

MoonTrajectory 是一个面向强化学习训练基础设施的 MoonBit 轨迹与经验回放库。它把 transition、episode、经验回放、优先级采样、序列批处理、离线数据集和训练目标计算组织成可复用 API，可用于 DQN、PPO、行为克隆和离线强化学习原型。

已交付范围

• Transition[S, A]：泛型状态、动作、奖励、下一状态和终止标记。
• Episode[S, A]：顺序存储、总回报、折扣回报、n-step、bootstrap、窗口切分、校验和奖励统计。
• ReplayBuffer[S, A]：固定容量环形缓冲区、覆盖策略、边界访问、确定性均匀采样、序列采样、padding mask 和统计报告。
• PrioritizedReplayBuffer[S, A]：比例优先级采样、priority 更新、重要性采样权重、优先级分布和边界统计。
• TrajectoryDataset[S, A]：完整 episode 的离线数据集、校验拒绝、按 episode 切分、展平、抽样和统计。
• 训练辅助：TD target、GAE、折扣前缀、target batch、奖励缩放、裁剪和批处理操作。
• 评估与基准：回报/长度直方图、成功率、评估报告，以及 4 组确定性基准数据（sparse、dense、long-horizon、short-horizon）。

工程边界

本库负责“轨迹数据层”和“训练批处理层”，不负责神经网络、环境执行器、自动求导、设备后端或 checkpoint。状态和动作保持泛型，可以接入字符串、数值、记录类型或上层张量表示。优先级缓冲区当前采用线性扫描采样，优点是实现透明、易审计；百万级样本场景应替换为 segment tree，同时保持公开数据结构和采样语义。

快速开始

环境要求：MoonBit toolchain 0.10.3 或更高版本。

moon add hmyhmyhmyss/moontrajectory
moon test
moon run cmd/main

import hmyhmyhmyss/moontrajectory as traj

fn main {
  let episode = traj.Episode::new()
    .push(traj.Transition::non_terminal("s0", "left", 1.0, "s1"))
    .push(traj.Transition::terminal("s1", "right", 5.0, "s2"))
  let buffer : traj.ReplayBuffer[String, String] = traj.ReplayBuffer::new(1024)
  let _ = buffer.extend_episode(episode)
  let report = buffer.report()
  println("steps=\{report.size()}, reward=\{report.total_reward()}")
}

完整本地验收命令

moon check --deny-warn
moon test --deny-warn
moon fmt --check
moon info
moon run cmd/main

当前仓库有 26 个测试，覆盖空容器、零容量、负索引、环形覆盖、终止/截断冲突、n-step、bootstrap、序列 padding、优先级归一化、优先级小于 1 的重算、负 priority 归一化、数据集分割、训练 targets、评估报告和确定性基准 fixture。

项目结构

文件	职责
trajectory.mbt	Transition、Episode 和基础回报计算
trajectory_analysis.mbt	校验、统计、bootstrap 与 episode 特征
replay_buffer.mbt	均匀经验回放
prioritized_replay.mbt	优先级经验回放
sequence_sampling.mbt	固定长度序列、padding 和 mask
dataset.mbt	离线轨迹数据集
training_targets.mbt	TD、GAE、折扣 targets 和 batch
evaluation.mbt	评估报告和直方图
episode_windows.mbt	RNN/序列模型窗口
batch_ops.mbt	通用批处理和数值操作
benchmarks.mbt	确定性工作负载 fixture
replay_analytics.mbt	回放统计和优先级诊断
cmd/main	可直接运行的 smoke demo

开源合规

项目采用 Apache-2.0，完整文本见根目录 LICENSE。当前源代码为独立 MoonBit 实现，不包含 vendored 第三方源文件、生成代码、商业代码或未授权测试数据；来源和设计边界见 docs/SOURCE.md。后续引入第三方算法或数据时，必须记录原项目链接、许可证、版权声明、改动范围和再分发说明。

提交信息

• GitHub：https://github.com/hmyhmyhmyss/MoonTrajectory
• GitLink：https://gitlink.org.cn/hmyhmy78/MoonTrajectory
• MoonBit module：hmyhmyhmyss/moontrajectory
• 许可证：Apache-2.0

GitHub、GitLink 和 mooncakes.io 的远端发布状态不能仅由本地工作区证明。推送前请确认两个代码托管平台的默认分支都显示最新提交，并在 mooncakes.io 查询模块版本；本地仓库不会自动推送任何远端。

后续路线

当前版本已覆盖可复用的轨迹和 replay 基础闭环。后续可在不破坏现有 API 的前提下增加 segment tree、序列优先级采样、持久化格式、压缩存储和具体网络库适配层。