FaceLink

FaceLink 将受限的镜头描述转化为可编辑的 Blender 场景动画。它面向预可视化/白模工作：演员、道具和摄影机仍然是普通的 Blender 对象，带有普通的关键帧，因此艺术家可以拖拽、重新定时并覆盖结果。

FaceLink 不是文本转视频生成器，也不会让 LLM 获得不受限制的 Python 执行权限。模型生成类型化的 ShotSpec；FaceLink 对其进行验证，将其编译为一个小型的补丁操作白名单，在 Blender 中暂存可人工审阅的版本，并且只有在艺术家按下 Apply Staged Patch 之后才会更改场景。

演示

这个四秒的演示由随附的可编辑 .blend 场景渲染而成。该运动是通过 FaceLink 的真实补丁执行器应用的，并且仍然是 24 个普通的可编辑关键帧值——而不是在 Blender 外部烘焙生成的视频。

Related MCP server: blender-mcp

当前 MVP

• 扫描打开的 Blender 场景，并为对象分配稳定的 FaceLink ID；

• 编译 move_to、turn_to、look_at、wait 和 play_clip 节拍；

• 创建/更新可编辑的变换、关键帧、摄影机和跟踪约束；

• 在世界空间中规划变换，并将其转换为适用于带父级 Blender 对象的形式；

• 通过 MCP 服务器向 Codex/ChatGPT 兼容的 MCP 客户端公开工作流；

• 支持使用 OpenAI API 密钥规划，并支持 Structured Outputs；

• 在 MCP 进程与 Blender 之间运行仅限 localhost 的认证桥接；

• 支持 Blender 侧的暂存/审阅/应用/丢弃、持久审计历史以及安全回滚到选定的当前会话修订版。

• 拒绝内部重叠的变换/动作时间线，在覆盖现有关键帧之前发出警告，并拒绝冲突的 FaceLink NLA 片段；

• 直接在 Blender 视口中预览暂存的世界空间运动路径和预测的摄影机视锥，而无需创建场景数据块；

• 扫描显式标记的导航网格和障碍物，规划确定性的多段移动路径，并在演员的扫掠边界与标记障碍物相交时发出警告；

• 对完整的导航环境进行指纹识别，以便新添加的障碍物或编辑过的导航网格会使已暂存的计划失效；

• 盘点骨架骨骼层级和可编辑的 Blender Actions，包括姿态骨骼通道、静止朝向、帧范围和确定性内容指纹；

• 使用确定性名称归一化建议仅审阅的骨骼映射，然后在执行前测量映射的层级、局部静止轴和缩放归一化的骨骼比例；

• 通过开放的 rename_only 骨骼映射配置文件复制兼容的 Actions，重写可编辑的 FCurve 路径，将结果放入 NLA，并在回滚时移除创建的副本；

• 将审阅过的 bake_pose 配置文件采样为普通的可编辑目标 Actions，通过显式的根运动策略和有界工作量修正不同的局部静止轴和骨骼缩放；

• 使用 bake_evaluated_pose 评估现有的自包含源骨架约束和驱动器，然后将最终的变形骨骼姿态烘焙为普通的可编辑 Action；

• 可选地将 Armature 对象的根运动作为保持放置的相对增量传输，并带有源单位或 rig 缩放调整的平移；

• 在不创建场景数据的情况下预测暂存的摄影机画面，在艺术家应用之前测量目标大小、中心偏移、安全区域适配、裁剪和中心点遮挡；

• 当引用的变换、父级链接、锁定或场景时间值在场景扫描后发生变化时，拒绝暂存的计划。

支持的 Blender 版本

• 主要：Blender 4.5 LTS（已使用 4.5.12 测试）

• 最低：Blender 4.2 LTS

• 尽力而为：Blender 5.x

开发机器上发现的 Blender 4.0.2 安装早于扩展基线。FaceLink 的源代码仍可加载到那里进行冒烟测试，但 4.0 不是声明的受支持版本。

安装 alpha 版本

从 FaceLink 0.3.8 Alpha 版本 下载 FaceLink-Setup-0.3.8.exe，打开它，选择 Check setup，然后选择 Install FaceLink。

此 alpha EXE 尚未进行代码签名，因此 Windows SmartScreen 可能会显示未知发布者警告。在选择 More info → Run anyway 之前，请对照发布版的 SHA256SUMS.txt 进行验证，并且只使用从官方 FaceLink 发布页面下载的文件。

FaceLink 不捆绑 Blender。它会检测现有的官方 Blender 4.2 或更新版本安装，这使发布版保持小巧，并让每位艺术家选择 Blender 4.5 LTS 或更新的兼容版本。如果缺少 Blender，请从官方 Blender LTS 页面安装。

图形化安装程序将 FaceLink 主机、扩展、校验和清单以及安全的 PowerShell 后端打包在一个小型 EXE 中。它会验证嵌入的文件，检测 Python 和 Blender，安装两个 FaceLink 组件，并安全地配置共享的本地 ChatGPT Desktop/Codex MCP 文件。它不需要管理员访问权限，也不存储 API 密钥。

对于手动 Windows 安装，请将四个原始发布文件放在一起，然后运行：

.\install-windows.ps1 `
  -WheelPath .\facelink-0.3.8-py3-none-any.whl `
  -ExtensionZipPath .\facelink-0.3.8.zip `
  -ChecksumsPath .\SHA256SUMS.txt

该脚本会验证发布哈希，找到 Python 3.11+ 和 Blender 4.2+，创建隔离的 FaceLink 主机，安装扩展并配置精确的 facelink-mcp.exe 路径。传递 -PlanOnly 以检查所有解析出的路径而不安装任何东西。当 Blender 是便携式或不在常规路径上时，传递 -BlenderExe C:\path\to\blender.exe。传递 -SkipMcpConfiguration 以保持本地 MCP 配置不变。对于现有的 FaceLink 扩展，请从 Blender 首选项中更新它，或在运行扩展安装步骤之前移除旧版本。

在 Blender 中启动 FaceLink 的桥接后，验证完整设置：

facelink doctor --blender-exe C:\path\to\blender.exe

诊断程序绝不会打印 API 密钥或 Blender 桥接的 bearer token。缺少 API 密钥只是警告，因为 MCP 客户端可以使用自己的模型。

要手动安装这两个组件，请继续阅读下文。

在 Blender 4.2 或更新版本中，打开 Edit → Preferences → Get Extensions → Install from Disk，选择 facelink-0.3.8.zip，启用 FaceLink，打开 3D 视口侧边栏中的 FaceLink 选项卡，然后按 Start Bridge。

在隔离的 Python 3.11 或更新版本环境中安装 Python 主机：

py -3.11 -m venv .venv
.\.venv\Scripts\python -m pip install .\facelink-0.3.8-py3-none-any.whl
.\.venv\Scripts\facelink-mcp

使用发布版中的 SHA256SUMS.txt 验证每个下载的工件。继续阅读下文，了解 MCP 客户端配置以及安全的暂存/审阅/应用工作流。

为开发安装

cd E:\FaceLink
$env:UV_CACHE_DIR='E:\CodexData\Work\FaceLink\uv-cache'
uv sync --extra dev
uv run pytest

对于可复现的多版本验收矩阵，包括真实的扩展安装：

./scripts/run_acceptance.ps1

该测试框架将 JUnit、覆盖率、每个 Blender 的 JSON 和命令日志写入 artifacts/ 目录。有关确切的测试门和已知排除项，请参阅 docs/TESTING.md。

构建 Blender 扩展：

$env:FACELINK_BLENDER_EXE='C:\path\to\Blender\blender.exe' # optional if on PATH
./scripts/build_extension.ps1

然后在 Blender 4.5 中：Edit → Preferences → Get Extensions → Install from Disk，选择 dist/facelink-0.3.8.zip，启用 FaceLink，并打开 3D 视口侧边栏中的 FaceLink 选项卡。按 Start Bridge。

运行 MCP 服务器：

uv run facelink-mcp

安全地创建或更新共享的本地 ChatGPT Desktop/Codex 配置：

uv run facelink configure-mcp `
  --mcp-launcher E:\FaceLink\.venv\Scripts\facelink-mcp.exe `
  --instance-dir E:\CodexData\Work\FaceLink\instances

FaceLink 会备份现有的 ~/.codex/config.toml，保留无关的设置，并且只拥有其明确标记的块。生成的 OpenAI 兼容配置是 TOML：

[mcp_servers.facelink]
command = "E:\\FaceLink\\.venv\\Scripts\\facelink-mcp.exe"
enabled = true

[mcp_servers.facelink.env]
FACELINK_INSTANCE_DIR = "E:\\CodexData\\Work\\FaceLink\\instances"

ChatGPT 桌面应用、Codex CLI 和 Codex IDE 扩展共享此本地配置。Web 上的 ChatGPT 不读取本地 MCP 配置，需要单独托管的插件。请参阅官方 OpenAI MCP 文档。相同的 FACELINK_INSTANCE_DIR 会为未来的 Blender 进程设置；安装后请重启 Blender 和 MCP 客户端。

使用 MCP 客户端时，安全的默认顺序是：

1. scan_scene

2. 将用户的自然语言请求转换为类型化的镜头，并调用 preview_shot

3. 调用 stage_scene_patch

4. 让用户在 Blender 中检查摘要，然后按 Apply Staged Patch 或 Discard

此路径使用 MCP 客户端中已有的模型；FaceLink 本身不需要 API 密钥。apply_scene_patch 仍然作为显式的超级用户绕过方式可用。

BYOK 规划

$env:OPENAI_API_KEY='your-key'
uv run facelink plan --brief "Cube walks to Marker in 2 seconds, camera follows Cube" `
  --snapshot scene.json --out shot.json

或者在一个命令中扫描正在运行的 Blender 场景、规划、编译并暂存结果：

$env:OPENAI_API_KEY='your-key'
uv run facelink workflow `
  --brief "Cube walks to Marker in 2 seconds, camera follows Cube"

该命令不会应用任何内容。在 Blender 中审阅并批准暂存的结果。

要使现有的 Action 针对骨骼名称不同的兼容骨架，请传递审阅过的开放配置文件：

uv run facelink validate-profile `
  --profile profiles/mixamo_to_facelink_compact.json

uv run facelink suggest-profile `
  --snapshot scene.json --source-rig source-armature-id `
  --target-rig target-armature-id --action "Mixamo Walk" `
  --name "Reviewed map" --out suggestion.json

uv run facelink analyze-profile `
  --profile profiles/mixamo_to_facelink_compact.json `
  --snapshot scene.json --source-rig source-armature-id `
  --target-rig target-armature-id --out compatibility.json

uv run facelink plan `
  --brief "Apply Mixamo Walk to the target rig for two seconds" `
  --snapshot scene.json `
  --retarget-profile profiles/mixamo_to_facelink_compact.json `
  --out shot.json

建议绝不会自动应用，并且始终带有 review_required: true。兼容性结果为 safe、review、bake_required 或 incompatible。当层级、静止朝向或比例需要烘焙时，编译器会阻止 rename_only。FaceLink 会对两个 Actions 和引用的 rig 进行指纹识别，因此扫描后的曲线或静止姿态编辑会在变更之前失败；它还会阻止跨不同大小 rig 的未缩放姿态骨骼平移通道。生成的 Actions 和 NLA 条带仍然是普通的可编辑 Blender 数据。请参阅 profiles/README.md 和 examples/retargeted_clip_shot.json。

当分析表明 bake_required 是因为局部静止朝向或 rig 比例不同时，请将审阅过的配置文件更改为 adapter: "bake_pose"，设置其显式的 source_rig，并可选地设置 sample_step (1-16) 和 root_motion (scale、preserve 或 drop)。FaceLink 会采样源 Action 的原始帧范围，将线性位置/旋转/缩放关键帧写入普通的目标 Action，并将其放入相同的可编辑 NLA 工作流中。除非 object_motion 是显式的，否则会省略对象级 Action 通道；否则根运动必须位于映射的根姿态骨骼上。此第一个适配器需要等效的映射父级层级和不受约束的源/目标变形骨骼。请参阅 profiles/mixamo_to_facelink_compact_bake.json 和 examples/baked_retargeted_clip_shot.json。

当源 Action 为控制器骨骼或自定义属性设置动画，并且源变形骨骼通过约束/驱动器接收最终运动时，请使用 adapter: "bake_evaluated_pose"。审阅过的 bone_map 将源变形骨骼（而不是控制器通道）映射到目标变形骨骼。版本 1 仅允许依赖同一源 Armature 对象/数据，拒绝外部辅助对象和场景驱动的变量，并且仍然需要等效的映射父级层级以及不受约束/不受驱动的目标骨骼。它不会自动发现控制器或转换 IK/FK 系统。请参阅 profiles/controller_to_deform_evaluated_bake.json 和 examples/evaluated_retargeted_clip_shot.json。

如果整体角色运动承载于源 Armature 对象上，请向任一烘焙适配器添加 object_motion: "preserve" 或 "scale"。FaceLink 使用源对象相对于其首个采样帧的变换，在目标当前世界变换之后应用该增量，并将普通的对象位置/旋转/缩放 FCurve 写入同一个生成的 Action。scale 将增量平移乘以映射绑定的中位长度比；preserve 保持源单位。版本 1 要求源/目标 Armature 均未设置父级，并且没有对象约束或受驱动的目标对象变换。参见 profiles/object_motion_bake.json 和 examples/object_motion_clip_shot.json。

从命令行检查或回滚 FaceLink 修订版本：

uv run facelink history
uv run facelink rollback --revision rev-0123456789abcdef

修订版本元数据存储在 .blend 文件中。可执行的回滚快照有意仅保留在会话中，因为它们包含实时的 Blender 数据块引用。回滚到较早的修订版本也会回滚所有较新的 FaceLink 修订版本，以保持线性的场景状态。

当 MCP 客户端自行执行语言模型规划时，API 密钥是可选的。ChatGPT 订阅与 OpenAI API 计费是分开的；ChatGPT 会员资格不是 API 密钥。关于信任边界，请参见 docs/ARCHITECTURE.md。

导航工作流

选择一个可行走的网格，并使用 FaceLink → Navigation → Navmesh。选择墙壁、道具或其他阻挡对象，并将它们标记为 Obstacle。move_to 节拍默认保持传统的直线路径；将 path_mode 设置为 navmesh，即可经由相连的导航三角形进行路由。编译器按路径距离分配普通的可编辑位置关键帧，并强制使用线性插值，从而使曲线控制柄无法离开可行走通道。

导航是刻意显式的。FaceLink 不会根据对象名称进行猜测，也不会默默地将每个网格都视为障碍物。当前的 v0.3.0 规划投影到 XY 平面，面向单层预可视化楼层；堆叠楼层、实时移动障碍物和人群路由尚不受支持。参见 examples/navmesh_walk_shot.json。

摄影机构图预检

带有目标的摄影机镜头会在暂存阶段接受检查。FaceLink 将目标的世界空间边界投影到预测的摄影机画面中，并报告裁剪、不安全边距、主体大小和中心偏移。只读的 Blender 射线投射会在另一个对象阻挡目标中心时发出报告。dolly_in 会同时检查其起始位置和结束位置。阈值在 camera.composition 中声明，在 ShotSpec 中保持可见，并且可以显式禁用。参见 examples/composition_checked_shot.json。

这是一个确定性的预检，而不是艺术质量评分。它不会渲染、使用视觉模型、判断光照，也不保证复杂主体的每个部分都未被遮挡。版本 0.3.3 评估不带镜头位移的透视摄影机，并将其他投影类型报告为不受支持，而不是返回误导性指标。

仓库结构

src/facelink/          Core schemas, compiler, bridge client, providers, CLI and MCP server
blender_extension/    Zero-dependency Blender extension and local bridge
schemas/              Portable JSON Schema for integrations
examples/             Example editable shot specifications
tests/                 Unit tests and a Blender headless smoke test
scripts/               Build and verification scripts
docs/                  Architecture, protocol and development notes

项目状态

版本 0.3.8 是面向创作者审阅的 alpha 版本，还不是生产级动画系统。它可以针对已审阅的映射执行限定范围的、感知变换的姿势烘焙，并且当所有依赖项都停留在显式源 Armature 上时，可以评估现有的约束和驱动器。它还可以在保持目标起始位置不变的情况下，传递未设置父级、无约束的 Armature 对象运动。它不会推断控制器、转换 IK/FK 系统、跟随外部辅助对象、求解不同的映射父级层级、处理已设置父级/受约束的对象根、合成缺失的运动，也不会评判视觉结果。多层级导航、多镜头排序和视觉差异叠加仍是后续工作。

Windows 版本现在拥有单文件图形化安装程序、安全的本地 MCP 配置、密钥安全的环境诊断工具，以及可复现的真实 Blender 演示。在更广泛地推广此 alpha 之前，请让非开发者用户测试安装，并完成 Linux/macOS 的安装覆盖。

许可证

FaceLink 是自由软件，采用 GNU GPL 版本 3 或任何更高版本 许可。Blender 扩展发行版包含相同的许可文本。