文档

快速上手

Facetion 从应用文件夹在你自己的电脑上本地运行。本指南将带你完成安装，并开始第一轮竞技场对比。

命令和环境变量仍使用内部名称 facet / FACET_。

01运行要求

Bun 1.4
Blender 5.2（实测使用 5.2.2 LTS）
兼容 OpenAI 的 AI 服务商 URL 和 API 密钥
可选：用于 AI 图像的 ima2-gen、用于 TouchDesigner 的 TDMCP 桥接，以及配有 Unreal MCP 的 Unreal Engine 5.8

02安装与运行

在检出源码的应用文件夹中安装依赖并启动服务器，然后在浏览器中打开界面。

cd <checkout>/app
bun install --frozen-lockfile
bun run start
# open http://127.0.0.1:5178

03连接服务商与 Blender

打开设置，输入兼容 OpenAI 的服务商地址和 API 密钥。默认地址为 http://127.0.0.1:8318/v1。密钥存储在服务器端，API 响应只显示经过遮蔽的值。在设置中或通过 FACET_BLENDER 指定 Blender 路径。

04运行第一轮

创建新会话，选择 Blender，用一句话描述目标，也可添加参考图。运行本轮，即可并排查看多个模型生成的真实 Blender 渲染。

05选择、继续与分支

选中你喜欢的结果。这会更新该程序的创作手册，以及模型和策略的 Elo 评分。你可以从该结果继续，也可以点击演进谱系中的早期结果，从那里创建分支。

06使用 ima2 生成 AI 图像

AI 图像面板使用同一台电脑上运行的 ima2-gen 服务器。Facetion 不会替你启动它，因此请先运行 ima2 start。默认地址为 http://127.0.0.1:3333，可通过 FACET_IMA2_URL 或在面板中修改。仅接受 127.0.0.1 和 localhost。

07其他程序

TouchDesigner 需要 TDMCP 桥接及其配置文件；未连接时会显示相应状态，并阻止运行轮次。Unreal、Cinema 4D、After Effects 和 ComfyUI 均需要在本机安装并准备好相应程序、插件或桥接工具。

08通过 AI 智能体使用 Facetion（MCP）

先启动 Facetion 服务器，再在 MCP 宿主中注册此进程。可用工具包括 facet_status、facet_create_session、facet_start_round、facet_wait_round、facet_pick 和 facet_get_render。

{
  "command": "bun",
  "args": [
    "<checkout>/app/src/mcp/stdio.ts"
  ],
  "env": {
    "FACET_URL": "http://127.0.0.1:5178"
  }
}

09环境变量

FACET_PORT：服务器端口（默认 5178）
FACET_DATA_DIR：数据目录（默认为检出源码中的 .facet-data）
FACET_BLENDER：Blender 路径
FACET_IMA2_URL：ima2 服务器地址

10使用须知

生成的 Blender 代码在独立进程中运行，设有超时和静态代码防护。静态防护不是操作系统沙箱。
模型输出质量因结果而异。请查看视觉评分，并亲自检查渲染图。
界面与程序在你的电脑上运行，但 AI 请求会发送至你配置的服务商。
模型错误会记录在台账及结果卡片中。