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 秒影片保留其源執行的原始節奏。