VRChat Avatar FBX Optimizer（内部工作流标识为 Avatar Opt V2）用于把从 VRChat 或 Unity 导出的 Avatar FBX/Blend 文件整理成经过独立验证的单骨架 Blender/FBX 交付物。仓库同时保留完整的 Agent skill；当一键流程遇到新模型兼容性问题时，Agent 可以读取失败证据、修复流程并重新通过同一套验证，而不是绕过失败门槛。
这是非官方社区工具。请保留源文件备份，并在 Blender 与 Unity 中复核最终结果。
本仓库就是 BlenderSafeAvatarFbxExporter README 中提到的配套 FBX 后处理工具。两个仓库负责同一工作流中的不同阶段：
BlenderSafeAvatarFbxExporter在 Unity 中把 Modular Avatar Manual Bake 结果安全导出为 Blender 兼容 FBX，重点保留 Rest Pose、BlendShape、蒙皮权重与贴图。- 本工具接收导出的 FBX（也支持普通 FBX/Blend），继续执行安全拓扑清理、重复骨架与蒙皮权重合并，并可选择保留原 UV 或构建和重烘焙语义 Atlas。
推荐流程为 Unity / Modular Avatar -> BlenderSafeAvatarFbxExporter -> VRChatAvatarFBXOptimizer -> Blender / FBX。本工具也可以独立处理其他来源的 VRChat Avatar FBX/Blend。
| 模式 | Windows 拖放入口 | 处理范围 | 默认输出目录 |
|---|---|---|---|
| 不做 Atlas | Drop_Avatar_Here_NO_ATLAS.cmd |
安全拓扑清理、骨架合并、导出与独立验证；保留原有 UV/材质布局，不运行任何 Atlas 打包或贴图重烘焙业务。 | <名称>_AvatarOptV2_NoAtlas |
| 完整 Atlas | Drop_Avatar_Here_WITH_ATLAS.cmd |
在相同的几何与骨架流程之后，修复有证据的 UV 问题、构建语义 Atlas、重烘焙 PBR 通道、导出并验证。 | <名称>_AvatarOptV2_Atlas |
两个模式都不会修改源文件，也不会覆盖非空输出目录。默认目录已经存在时，会自动创建带时间戳的新目录。
不做 Atlas 模式会保留源材质和图片引用，但不会把外部源贴图自动复制成自包含交付物。完整 Atlas 模式会在输出目录中生成协调一致的 ColorAlpha、Normal、ORM 与 Emission 贴图。
- 拖放入口与自动便携 Blender 安装支持 Windows 10/11 x64。
- Blender 4.2 LTS 或更新版本。工具会先查找
--blender、BLENDER_BIN、旁置便携版、PATH和标准安装目录，全部找不到时才下载。 - 直接运行 Python 脚本需要 Python 3.10 或更新版本。Windows 启动器在独立 Python 也不存在时，可以先安装 Blender，再使用 Blender 自带 Python。
- 完整 Atlas 模式需要足够空间保存临时 Blend、渲染、FBX 与 4096 分辨率贴图页。
不需要安装第三方 Python 包；bpy 与 FBX 导入导出器由 Blender 提供。
Windows x64 找不到任何 Blender 时，会从 https://download.blender.org 自动下载固定的 Blender 4.2.23 LTS 便携 ZIP。压缩包大小为 383,193,007 字节，安装至少需要 2 GB 可用空间，最终放在工具旁的 runtime/blender-4.2.23-windows-x64/；整个 runtime/ 不会进入 Git。
下载器只接受 blender-runtime.json 中固定的 HTTPS 主机、文件名、字节数与 SHA-256，并限制 ZIP 文件数量和解压总体积，拒绝路径穿越与符号链接，要求存在预期可执行文件，在临时目录完成检查后才安装。中断或失败的下载不会被下次误认为可用 Blender。
使用 --no-blender-download 或设置 AVATAR_OPT_DISABLE_BLENDER_DOWNLOAD=1 可以禁止联网；AVATAR_OPT_RUNTIME_DIR 可以更改便携版位置。其他操作系统仍需自行提供 Blender。
- 下载或克隆仓库。
- 将一个或多个
.fbx/.blend文件拖到两个模式入口中的一个。 - 第一次运行且没有 Blender 时，等待官方下载与解压完成。
- 等待处理与独立验证完成。
- 只有当
validation-report.json中的accepted为true时才接受结果。
完整 Atlas 模式需要执行 UV 搜索、贴图烘焙、渲染、FBX 导出、FBX 回读与视觉比较，复杂模型可能耗时较长。
# 只分析，不修改源文件
.\avatar-opt.cmd analyze avatar.fbx
# 保留原 UV/材质，不做 Atlas
.\avatar-opt.cmd process avatar.fbx --no-atlas
# 进行 4096 Atlas 重烘焙
.\avatar-opt.cmd process avatar.fbx --resolution 4096
# 使用交付目录中冻结的配置重新验证
.\avatar-opt.cmd validate avatar.fbx --delivery avatar_AvatarOptV2_Atlas
# 必须使用已有 Blender，禁止联网下载
.\avatar-opt.cmd analyze avatar.fbx --no-blender-download旧参数 --rig-only 继续作为 --no-atlas 的兼容别名。需要覆盖默认配置时使用 --config；最终生效的合并配置会写入每个输出目录。
完整 skill 位于 skill/optimize-vrchat-avatar-v2，其中包含主机 CLI、Blender worker、几何/骨架/UV/烘焙/验证代码、策略参考与 Agent 元数据。
安装或更新 Codex 使用的本地副本：
powershell -ExecutionPolicy Bypass -File .\scripts\install-agent-skill.ps1
# 更新时会先把旧副本改名为带时间戳的备份：
powershell -ExecutionPolicy Bypass -File .\scripts\install-agent-skill.ps1 -Update然后新建一个 Codex 任务，调用 $optimize-vrchat-avatar-v2，并提供源模型路径与失败输出目录。Agent 必须保持原来的 Atlas/No-Atlas 模式，不能通过降低验证标准来制造“成功”。详细流程见 失败接管说明。
- 根据素体躯干与双侧四肢的实际蒙皮证据选择主骨架，而不是仅凭标准命名或衣物权重数量。
- 保留独有的衣物、饰品、头发、裙子、袖子、挂点和物理骨骼。
- 在删除重复骨骼或辅助节点前完成权重、修改器、父子关系、约束和动作路径的迁移。
- 只焊接经过完整等价证明的顶点，并拒绝任何恶化拓扑的结果。
- No-Atlas 模式不进入 UV/Atlas 流程；Atlas 模式只修复有直接证据的无效区域，并执行重叠、退化、碎片化与纹素密度门槛。
- 对保存后的 Blend 和重新导入的 FBX 比较拓扑、权重、层级、静止变换、姿态、保留 Empty 语义与外观。
- 每次运行记录源文件 SHA-256、生效配置、分析、处理、验证和日志。
v2.8.0 在私有兼容性语料中发现并接受了全部 16 个 FBX/Blend 用例，覆盖几何清理、骨架合并、完整 Atlas 构建、Blend 保存与独立 Atlas 验证。该轮使用 atlas-only 阶段，因此没有把全部 16 个用例宣称为已经完成贴图烘焙、视觉比较、FBX 导出与 FBX 回读。具体范围和测试方式见 兼容性与测试。
python scripts/check_release.py
python tests/test_config_validation.py
python tests/test_public_entrypoints.py
python tests/test_blender_runtime_bootstrap.py
pwsh -NoProfile -File tests/test_blender_bootstrap.ps1
python -m compileall -q skill tests scripts发布检查读取 Git 的候选文件集合，所以本地被忽略的模型和历史输出可以继续留在目录中。首次提交前仍应执行 git status --short 并确认没有任何受版权保护的模型、网格、贴图、交付目录或包含私人绝对路径的报告。
MIT，见 LICENSE。