亲手训练一条会玩贪吃蛇的 AI：调奖励、改参数、边训练边看它玩，并看懂它每一步在想什么。
纯强化学习（没有写死的寻路算法），在一块 RTX 5070 上：
| 棋盘 | 训练时间 | 平均吃到（贪心评估） |
|---|---|---|
| 8×8 | 约 3 分钟 | 约 20 个 |
| 8×8 | 约 15 分钟 | 约 45 个（满分 61），约三分之一的局能填满棋盘 |
| 10×10 | 约 12 分钟 | 约 50 个（满分 97） |
| 6–16 随机 | 约 12–20 分钟 | 训练范围内和没见过的 20×20 都能吃到几十个 |
- 边训练边看：训练中的 AI 实时在网页里玩 1/4/9 局，每一步显示它对「直行 / 左转 / 右转」的把握；旁边是平均得分、死亡原因、探索程度等曲线。
- 训练中途调参：拖动奖励滑块（吃到食物、撞墙、咬自己、靠近食物……）或学习率，点「应用」立刻生效，曲线上会留下标记，方便对比调参前后的变化。进阶里还可以让吃食物的奖励、撞墙/咬自己的惩罚、每步代价随蛇的长度变化。
- AI 在想什么：把一整局录下来逐步回放，热力图显示它当时在关注棋盘哪里，还能一键跳到死亡前几步看它为什么撞了。
- 对比实验：把几次实验的曲线叠在一起，或者让两个模型在同一个开局下并排对战。
- 自己玩：同一套规则的贪吃蛇，手机连同一个局域网就能玩。
每个参数旁边都有大白话说明「调大会怎样、调小会怎样」，常用参数默认展开，进阶参数折叠。
需要 uv 和一块 NVIDIA 显卡（没有显卡也能跑，只是慢很多）。
uv sync
uv run snake-lab浏览器会自动打开 http://127.0.0.1:7860。终端里还会打印局域网地址，手机访问它就能看训练、自己玩。
常用参数：uv run snake-lab --port 8080（换端口）、--no-open（不自动打开浏览器）。
Windows 上 PyPI 的 PyTorch 只有 CPU 版，本项目已把 Windows 指向官方 CUDA 12.8 源，只要显卡驱动支持 CUDA 12.8+ 即可，不需要单独安装 CUDA Toolkit。
- 在「实验室」选 快速入门 · 8×8，直接点开始。
- 进入训练实况，看 AI 从乱撞到会找食物，大约两三分钟平均分就会明显上涨。
- 在「实时调参」里把 撞墙惩罚 或 咬自己惩罚 调到接近 0，或把 每步代价 调得很负，观察它的行为怎么变。展开进阶后，可以把这些奖励设成随蛇长变强或变弱。
- 训练一段时间后点「AI 在想什么」，看热力图和每一步的动作概率。
- 用相同设置再开一个实验，只改一个奖励，到「对比」里看曲线差异。
| 预设 | 适合 | 预期 |
|---|---|---|
| 快速入门 · 8×8 | 第一次上手 | 约 3 分钟平均 20 个，约 15 分钟接近填满 |
| 长训冠军 · 10×10 | 挂机冲高分 | 约 12 分钟平均 50 个（满分 97） |
| 多尺寸通才 · 6–16 | 一个模型玩不同大小的棋盘 | 学得慢一些，约 12–20 分钟后跨尺寸都能吃几十个 |
| DQN 对照组 · 8×8 | 和 PPO 比较两种训练方式 | 起步慢，约 4–5 分钟平均 8 个 |
| 挑战 · 20×20 | 长时间挂机 | 15 分钟通常只有几个，要看到明显进步需要 1 小时以上 |
纯强化学习的天花板在于长蛇后期几乎都死于撞到自己；8×8 能填满，更大的棋盘能吃很多但很难稳定填满。
- GPU 上同时跑几千局：环境用 PyTorch 张量实现，所有对局在显卡上并行推进（单独测环境约每秒 110 万步），训练吞吐主要受神经网络限制。
- 以蛇头为中心的视角：AI 看到的画面以蛇头为中心并旋转到「蛇头朝上」，所以「左转」在画面里就是向左；再加上蛇长、饥饿程度、食物方位等几个数值。网络是卷积 + 自适应池化，与棋盘大小无关。
- 两种训练方式：PPO（主力，稳定、适合边看边调）和 Double Dueling DQN（带 n 步回报，作为对照）。
- 奖励是可拆分的：环境每一步只报告发生了什么（吃到食物、死亡、每走一步、靠近/远离食物、饿死、通关），总奖励 = 这些事件 × 你设置的权重。所以训练中途改奖励会立即生效，DQN 回放池里的旧经验也会按新权重重新计算。
- 每个实验一个独立进程：可以同时跑多个实验做对比；关闭服务或意外退出时训练进程会自动收尾，不会在后台偷跑显卡。
snake_rl/
core/ 环境、网络、PPO / DQN、配置（参数说明与预设的唯一来源）、检查点
lab/ 实验存储、训练进程、实时观战、回放分析与对比
server/ FastAPI 接口、WebSocket 推流、打包好的前端页面（static/）
web/ 前端源码：Vite + Vue 3 + TypeScript
tests/ pytest（core / lab / server）
experiments/ 训练产生的数据（不进 git）
uv sync # 含 dev 依赖（pytest / ruff / pyright）
uv run python -m pytest -m "not slow" # 快速测试；去掉 -m 参数会额外跑 GPU 学习测试
uv run python -m ruff check snake_rl tests
uv run python -m ruff format --check snake_rl tests
uv run python -m pyright snake_rl tests
cd web
npm install
npm run dev # 开发服务器，/api 与 /ws 代理到 127.0.0.1:7860
npm run test
npm run build # 输出到 snake_rl/server/static/（需要提交，运行时不依赖 Node）项目路径含中文时，uv run pytest 这类直接调用可执行文件的写法在 Windows 上可能失败，用 uv run python -m ... 即可。
GitHub Actions 会在 Linux 上跑 lint、类型检查、测试和前端构建。改了前端后记得本地 npm run build 并提交 snake_rl/server/static/。