LocalGPT 是一款本地 AI 助手，能"梦见可探索的 3D 世界"。它的 Gen 模块提供了Headless 无头模式和实验队列：不需要打开任何窗口，一条命令就能让 AI 自动建模、保存世界并输出截图，配合实验队列可以在夜间批量跑完上百个生成任务，甚至直接接入 CI 流水线做自动化批量产出。本文手把手带你从零跑通这套"睡一觉，收获100个世界"的完整流程。

为什么需要 Headless 无头模式？

在交互模式下生成世界，你得坐在屏幕前看着 AI 一点点搭建场景——生成一个世界没问题，但专业级的世界设计需要大量变体对比：同一个村庄的 5 种光照、同一片森林的 3 个密度层级……手动逐个跑完全不现实。

Headless 无头模式把这件事变成了"脚本化生产"：

• 🎯不开窗口：Bevy 渲染引擎以primary_window: None启动，专为服务器/CI 设计
• 🔁跑完即退：Agent 生成完毕后通过完成标记自动触发AppExit，退出码直接可用作流水线判断依据
• 📦产物统一：每次运行产出一个完整的 world skill（world.ron+SKILL.md+ 截图），格式与交互模式完全一致
• ⏱️超时看门狗：默认 5 分钟超时保护，防止任务卡死

实现核心在 crates/gen/src/gen3d/headless.rs，整个无头流程（无窗口引导、完成检测、退出码契约）约几十行配置就搭好了，详见 docs/roadmap/headless/TODO-H1-headless-bevy-gen.md。

安装 LocalGPT Gen：两种最快配置方法

方法一：cargo 安装

cargo install localgpt-gen

方法二：Docker 镜像（CI 首选）

仓库根目录的 Dockerfile.gen 专门构建了一个面向无头部署的镜像，运行时默认入口就是mcp-server --headless：

docker pull ghcr.io/localgpt-app/localgpt-gen:latest docker run --rm -i ghcr.io/localgpt-app/localgpt-gen:latest mcp-server --headless

如果想自己跑源码，先克隆仓库：

git clone https://gitcode.com/gh_mirrors/localgp/localgpt

💡 注意：无头模式允许软件渲染回退，所以没有独立显卡的 CI 容器也能跑；GPU 紧张时建议关闭交互式 Gen 窗口，避免抢显存。

一条命令生成一个世界：无头模式快速上手

# 生成单个世界（无窗口） localgpt-gen headless --prompt "Build a cozy cabin in a snowy forest" # 带风格提示 localgpt-gen headless \ --prompt "Medieval village marketplace" \ --style "Studio Ghibli, watercolor feel" # 指定输出目录、覆盖模型与超时 localgpt-gen headless \ --prompt "Underwater coral reef" \ --output skills/reef/ \ --model claude-cli/opus \ --timeout 600

关键参数一览（来自 crates/gen/src/main.rs 的子命令定义）：

退出码契约（CI 流水线判断成败的依据）：0成功、1生成失败（LLM/工具错误/超时）、2参数或配置错误、3GPU 不可用。

实验队列：让100个任务排队过夜

单次命令能跑一个世界，实验队列（Experiment Queue）则能把一堆任务变成流水线。队列状态持久化为追加式 JSONL 文件（<state_dir>/gen-experiments.jsonl），每个实验记录状态流转Pending → Running → Completed/Failed，并保存输出路径、截图、实体数量、耗时与错误信息。数据模型定义在 crates/gen/src/experiment.rs，队列设计文档见 docs/roadmap/headless/TODO-H2-experiment-queue.md。

方法一：HEARTBEAT.md 自然语言排队

在HEARTBEAT.md里用自然语言写任务，心跳（Heartbeat）运行器会自动解析、派发、回写结果：

## Gen Experiments - [ ] Build an enchanted forest — sparse trees, open clearings - [ ] Build an enchanted forest — dense canopy, dark atmosphere - [ ] Medieval village with 3 lighting variations (variation: lighting = dawn, noon, sunset)

两个实用语法：

• 变体扩展(variation: <axis> = <v1>, <v2>, ...)：一条任务自动展开为 N 个实验，各产出独立世界（上限 50 个变体，见 crates/gen/src/mcp/experiment_tools.rs）
• 记忆引用(style: from memory)：让 Agent 先从记忆里找指定风格再生成

调度策略是每次心跳只派发一个实验，配合基于文件的 GPU 独占锁（gen-gpu.lock，进程崩溃时由操作系统自动释放）保证实验之间永不重叠、不抢 GPU。

方法二：MCP 工具程序化排队

在 CI 中更常用的是 MCP 接口。mcp-server --headless模式下注册了三个队列工具：

流水线里只需提交一次变体批次即可：

{ "name": "gen_queue_experiment", "arguments": { "prompt": "Medieval village", "name": "village", "variations": { "axis": "lighting", "values": ["dawn", "noon", "sunset"] } } }

MCP 无头模式的设计与验收标准见 docs/roadmap/headless/TODO-H5-mcp-headless.md。

CI 流水线实战：夜间批量生成 + 自动验收

把上面的能力串起来，一个典型的 CI 夜间任务长这样：

1. 排队：任务文件里写满待生成世界（或用 MCP 一次性提交变体批次）
2. 逐条执行：每个任务运行localgpt-gen headless --prompt "..." --output workspace/skills/<name>/ --timeout 600
3. 自动验收：流水线读取退出码——0通过，1/2/3触发重试或告警
4. 收集产物：从workspace/skills/打包 world skill 与截图，推送为流水线 artifact

# CI 批量脚本示例：逐条执行，按退出码统计 for name in "${WORLD_NAMES[@]}"; do if localgpt-gen headless --prompt "$name" --output "workspace/skills/${name%-*}/" --timeout 600; then echo "PASS: $name" else echo "FAIL: $name (exit=$?)" fi done

几个实战要点：

• ✅单实例串行：GPU 锁保证了同一时刻只有一个无头实例占用 GPU，CI 多 job 场景下请勿并发跑无头任务
• ✅截图即验收：--screenshot默认开启，每张缩略图都存进产物，晨起直接对比
• ✅结果可追溯：gen-experiments.jsonl记录每个实验的耗时、实体数、模型，方便统计"哪个 prompt 最容易失败"
• ✅记忆越用越懂你：生成前 Agent 会用memory_search检索你保存的风格偏好，生成后把场景摘要写回记忆——批量生成不再是"一次性抽卡"，而是持续演进的创作实践

早上查看结果：画廊与记忆

任务跑完后，在 Gen 窗口按G键打开画廊（或终端输入/gallery），所有世界以卡片形式展示：名称、实体数、生成来源（headless/experiment/mcp）、风格标签与缩略图，点 Load 即可加载进当前场景。画廊直接读取workspace/skills/目录，无需任何数据库。

官方使用文档：website/content/docs/gen/headless.md

核心文件索引

• 无头模式设计：docs/roadmap/headless/TODO-H1-headless-bevy-gen.md
• 实验队列规格：docs/roadmap/headless/TODO-H2-experiment-queue.md
• MCP 无头模式：docs/roadmap/headless/TODO-H5-mcp-headless.md
• 全阶段进度总览：docs/roadmap/headless/TODO-START.md
• 无头生成实现：crates/gen/src/gen3d/headless.rs
• 实验跟踪实现：crates/gen/src/experiment.rs
• CI 镜像定义：Dockerfile.gen
• 官方 Headless 文档：website/content/docs/gen/headless.md

总结

LocalGPT 的 Headless 无头模式 + 实验队列，把"AI 生成 3D 世界"从一次性的演示变成了可脚本化、可验收、可并批的自动化能力：localgpt-gen headless一条命令开箱即用，gen_queue_experiment与 HEARTBEAT.md 排队让你睡一觉跑完 100 个世界，退出码与 JSONL 跟踪记录则天然适配 CI 流水线的失败重试与产物归档。今晚就把你的 prompt 清单排进队列，明早收获一整个画廊吧 🌌