Laya Snake：本地终端 demo

一个由 Laya MLX 预测在 Apple silicon 上驱动的真实 Snake 游戏，终端布局为可读的社交短片而设计。左侧面板显示棋盘、分数、长度和最高分。右侧面板显示四个方向概率、实际执行的移动、两个模型估计、实测推理时间、决策速率和本地/离线状态。

运行

在这台仓库所在的 Apple silicon Mac 上：

uv run --extra demo laya-snake

默认模型是 aac6fef/laya-multilingual-mlx，使用原始 FP16 权重。demo 会先检查 models/hub/laya-multilingual-mlx 和 models/laya-multilingual，然后是本地 Hugging Face 缓存。它在游戏过程中绝不下载缺失的模型。全新检出时，先下载一次权重：

uv run --extra demo hf download aac6fef/laya-multilingual-mlx \
  --local-dir models/hub/laya-multilingual-mlx
uv run --extra demo laya-snake

使用至少 104 列 × 35 行的终端，等宽字体，并支持 true color。Menlo 在 macOS 上表现很好。更小的终端会让游戏暂停，直到调整尺寸。默认棋盘尺寸是 24 × 16，初始长度是 6，展示目标是每秒 12 次决策。

实时显示会遵循 NO_COLOR。如果你的 shell 设置了它，用 env -u NO_COLOR uv run --extra demo laya-snake 获得彩色展示。基准会显式启用 true color，所以这个环境设置不会悄悄改变它的渲染工作负载。

常用模式：

# Every move waits for a new inference, with no pacing delay.
uv run --extra demo laya-snake --max-speed

# Optional measured compilation + prefix-reuse path.
uv run --extra demo laya-snake --optimize --max-speed

# Use the fixed computation-budget setting validated on the recorded M3 Max.
uv run --extra demo laya-snake --fps 20

# Execute the model's raw first choice without the execution safety shield.
uv run --extra demo laya-snake --unassisted

# A finite run without a terminal display.
uv run --extra demo laya-snake --headless --steps 600 --max-speed

--model 接受本地目录或已缓存的 Hub ID。--width、--height、--seed 和 --initial-length 配置一次运行。棋盘必须至少 4 × 4，且有一个维度为偶数，因为安全规划器使用哈密顿环。速度键只影响节流模式；--max-speed 总是在当前决策完成时立即推进。

录制与导出

录制包含真实的棋盘状态、原始模型概率、执行的移动、计时、模型来源和运行摘要。每个棋盘都与它下一步之前所做的预测配对。

uv run --extra demo laya-snake --fps 12 --duration 100 \
  --record artifacts/snake/run.jsonl

# ffmpeg is required for video export; on macOS: brew install ffmpeg
uv run --extra demo laya-snake export artifacts/snake/run.jsonl \
  --start 65 --seconds 30 --output artifacts/snake/demo.mp4 \
  --gif artifacts/snake/demo.gif

uv run --extra demo laya-snake export artifacts/snake/run.jsonl \
  --start 85 --output artifacts/snake/poster.png

MP4 导出默认 1920 × 1080、每秒 30 视频帧、H.264，并保持原始真实时间速度。它从录制数据渲染出相同的终端单元格；这是一次渲染回放，而不是屏幕录制。屏幕上可见的 RECORDED RUN · 1× 标签和一个 JSON sidecar 标识了这一点。以 30 FPS 导出并不会把每秒 12 次决策的游戏变成每秒 30 次决策的游戏。在每个视频时间戳处，导出器使用最近的真实源帧。较快的录制所含的决策数可能超过所选视频帧率能显示的数量。

在没有连接终端时录制，使用 --headless。每次移动仍会发生模型推理；只是省略了实时终端绘制。输出文件不会被覆盖。改变展示或速度时开始一次新录制，而不是把暂停或重置混进一段简短的社交片段里。

MP4 默认截取 30 秒，而 --gif 以相同的原速导出其前 15 秒。用 --gif-seconds 改变 GIF 时长。随附的社交素材包含两种格式外加一张 PNG 海报。

AI 在做什么

这是一个特征辅助的神经决策 demo，使用现有的 Laya checkpoint，没有做过 Snake 训练。一个确定性规划器描述合法方向、安全的循环进展和当前空格连通性。Laya 接收这些描述，其中包括哪个安全方向进展最大。它返回 UP、DOWN、LEFT 和 RIGHT 上的分布。概率条就是那些原始模型输出。

默认的安全护盾执行模型中概率最高且可接受的方向。如果原始的第一次选择不可接受，UI 会保留那份原始分布，并用 SHIELD 标记实际执行的移动；干预计数器加一。默认运行标为 Laya + cycle safety。--unassisted 关闭那条执行限制；它仍然给模型提供规划器特征。两种模式都不能证明这个 checkpoint 能从未经处理的棋盘推断出 Snake 策略。

每次移动，一次 Agent.predict 调用批处理三个真实问题：

这两个估计是模型输出，不是校准过的 Snake 死亡概率。当前空格可达性也不同于尾巴移动之后的未来可达性。风险可能在很长时间里保持很低，因为规划器提供了一条安全路线。实时游玩中不会替换成随机值或预先录制的预测。

循环护盾保持身体的循环顺序，并且绝不越过尾巴或食物。每一个被允许的动作都朝当前食物取得正进展。对于初始合法的棋盘，这给出一个可用的安全后继和一个有限的吃食进展上界。测试会在可接受动作之间任意选择，直到棋盘被填满。

复现速度测试

uv run --extra demo laya-snake benchmark \
  --rates 10,12,15,18,20,25,30,35,40,45,50,60 \
  --sweep-steps 120 --soak-steps 600 --seeds 101,102,103,104 \
  --output artifacts/snake/benchmark.json

用 --resume --output artifacts/snake/benchmark.json 保留已完成的回合并恢复所记录的配置。每份报告都会标识 checkpoint、提示、环境和源哈希。失败的速率不需要更多种子；通过的速率必须完成每一个所请求的种子。

基准测量模型推理、规划、Rich 组装、写入内存的 ANSI 序列化和游戏更新。它排除模型加载、预热和终端模拟器自身的绘制。不设上限的回合测量实际持续的移动/秒。节流回合在每个种子上分别检查是否至少 99% 的活动 tick 落在所请求的计算预算内。操作系统睡眠超时仍计入所报告达到的速率。

最终的 truecolor M3 Max 运行完成了 8,160 次决策，零死亡，其中包括 2,400 个不设上限的步，整体 63.61 步/秒。它通过测试的最高计算预算设置是 20 FPS，达到的节流速率是 18.69–18.94 步/秒。更高的节流设置没能通过所述截止期标准，而游戏仍然存活。每个种子的结果、干预和局限见完整的 Snake 基准报告。

对于社交短片，默认的 12 FPS 目标给观众留出时间看清被选中的方向和增长的分数。--max-speed 展示实测吞吐。随附的 30 秒视频保留其源运行的原始节奏。