PufferLib 是一个强化学习框架，上游目前存在两套不兼容的接口，使用时必须明确版本配置，不能混用 3.0 的导入与 4.0 的配置/CLI 示例。
版本与用途
- pufferlib==3.0.0：PyPI 上最新稳定版（2025-06-23 发布），用于 Python/Gymnasium/PettingZoo 仿真、pufferlib.vector 向量化与 Torch PuffeRL 训练，要求 Python >=3.9。
- source 4.0：上游默认分支，并非 PyPI 稳定产物。提供原生 C Ocean 环境、原生 CUDA 训练器及可选 Torch 回退；4.0 重构已从当前包中移除 3.0 的仿真、vector 与 pytorch 模块。当前包声明 Python >=3.10 与 Torch >=2.9。
安装与来源核验
3.0.0 安装：PyPI 只提供 pufferlib-3.0.0.tar.gz，sha256 为 7df3a3e3f5f894d78d2a1f5374097890aec01473183e748abefe4f3faa10eaa9。源码/构建审查后创建锁定项目：
uv venv --python 3.11 uv add --exact --no-sync "pufferlib==3.0.0" uv lock uv sync --frozen
提交 pyproject.toml 与 uv.lock，并核验归档摘要与所有解析依赖。源码构建可能编译原生代码并获取构建资源，应在无凭证、无敏感挂载的沙箱中解析/构建。PyPI 元数据未锁定 Torch 或 CUDA，不应声称存在受支持的 CUDA 矩阵。
4.0 源码应固定提交而非分支：
uv add --no-sync
"pufferlib @ git+https://github.com/PufferAI/PufferLib.git@25647630e1b15330bb3153a5a0d3ff8d234c3acf"
uv lock
PufferTank 使用 Ubuntu 24.04、Python 3.12 与 CUDA 13.0.2/cuDNN 开发镜像及 cu130 Torch 索引，但未锁定确切 Torch wheel 与全部系统包，仅作参考。不要从管道直接执行远程安装器。安装或构建前先阅读 references/training.md。
安全默认做法
从捆绑的合成、仅 CPU、无网络工具开始；不要按点路径导入任意环境，捆绑工具只接受白名单内置项与 slug 标识；不安装或执行未经审查的环境包、原生扩展、ROM、地图、检查点或 pickle 文件；核验官方来源、不可变修订、许可证、校验和或证明及构建钩子，对原生构建与首次执行做沙箱隔离；限制步数、环境数、智能体数、worker 数、线程数、缓冲区、内存、磁盘、渲染尺寸与运行时；训练与评估环境/种子分离；日志默认本地或无，外部日志需显式选择加入、确认披露并单独批准工件上传；凭证仅用指定环境变量名（WANDB_API_KEY、NEPTUNE_API_TOKEN），绝不通过 CLI、INI、JSON、标签、运行名或日志配置传递，也绝不打印；不导出全部环境变量、不递归搜索 .env；信任加载前先哈希检查点字节，元数据检查不构成安全证明。
环境工作流
- 校验契约：Gymnasium reset 返回 (observation, info)；step 返回 (observation, reward, terminated, truncated, info)。校验空间、形状、dtype、有限奖励、布尔值、step 前 reset、结束后 reset、种子与清理。terminated 是 MDP 终止，truncated 是时间限制等外部截断，须在自举与指标中区分。
python3 scripts/env_contract_validator.py
--steps 64 --episodes 8 --seed 42
- 审查后再适配：3.0 使用显式包装 pufferlib.emulation.GymnasiumPufferEnv 与 PettingZooPufferEnv；不存在与旧技能匹配的 pufferlib.emulate(...) 快捷方式。
- 原生环境：3.0 PufferEnv 在 super().init(buf) 前需 single_observation_space、single_action_space、num_agents，使用原地向量缓冲区并返回独立终止/截断数组与 info 字典列表。4.0 使用 C 绑定，从上游 ocean/squared（单智能体）或 ocean/target（多智能体）开始，在本地/净化模式构建一个环境并校验所有缓冲区尺寸/类型/索引后再优化。
向量化
3.0 使用 pufferlib.vector.make(creator, backend=pufferlib.vector.Serial, num_envs=4, seed=42)，串行跟踪通过后才换 Multiprocessing。记录 num_envs、num_workers、batch_size、零拷贝模式、启动方法、智能体数、掩码与实际返回形状；多智能体环境中批长度按智能体槽位计。4.0 配置使用 [vec] 段中的 total_agents、num_buffers、num_threads。固定工作负载基准需预热并至少重复三次，分别报告仿真 SPS 与端到端训练 SPS。
策略、训练与评估
3.0 策略是按 single_observation_space/single_action_space 确定尺寸的 Torch 模块，稳定循环组合使用 encode_observations 与 decode_actions，结构化仿真使用 pufferlib.pytorch.nativize_dtype 与 nativize_tensor。4.0 Torch 回退通过 pufferlib.models.Policy(encoder=, decoder=, network=) 组合，提供 MLP、MinGRU、LSTM、GRU 网络；--slowly 选择该回退。
3.0 训练器：from pufferlib import pufferl; trainer = pufferl.PuffeRL(train_config, vecenv, policy)。4.0 CLI：puffer train ENV_NAME、puffer eval ENV_NAME --load-model-path EXACT_TRUSTED_PATH、puffer sweep ENV_NAME。默认生成计划而非启动：
python3 scripts/train_template.py
--profile pypi-3.0.0
--environment synthetic
--device cpu
--total-timesteps 10000
用 python3 scripts/validate_plan.py --root . --config plan.json 校验严格 JSON 计划，模式拒绝含密钥键、无界资源、点路径环境、非法向量整除、混版本选项与耦合训练/评估种子。可复现评估中绝不使用 latest。
检查点
3.0 与 4.0 Torch 回退使用 Torch 序列化，原生 4.0 写入不透明 .bin 权重；PyTorch 警告不可信模型等同程序、torch.load 使用反序列化。inspect_checkpoint.py 只做哈希与分类，不调用 torch.load、不导入 pickle/Torch、不检查归档成员、不解压文件。沙箱加载前核验来源、许可证、架构、环境修订、附属元数据与校验和。
捆绑文件
脚本：env_template.py（确定性合成 Gymnasium 风格模板）、env_contract_validator.py（有界契约与种子检查）、benchmark_vectorization.py（受限 serial/spawn 合成基准）、train_template.py（非执行的 3.0/4.0 训练计划生成器）、validate_plan.py（严格配置/资源/安全校验）、inspect_checkpoint.py（免反序列化的哈希/元数据检查）、repro_plan.py（分离种子评估与基准计划）。参考文档：environments.md、vectorization.md、policies.md、training.md、integration.md。所有捆绑 CLI 无依赖并输出严格 JSON，默认合成、确定性、有界、本地、仅 CPU、无网络，训练处为 dry-run。