blender-asset-validation

Blender 资产验证

每项任务开始时，阅读一次共享执行指南，了解自主决策、证据采集频率和长任务连续性。

验证所提供的资产以及任何要求导出的交付物。对于仅供检查或仅需渲染的任务，不要创建导出文件。导出干净或三角形数量较低，并不能证明视觉或功能质量。

执行确定性检查

如果可用，优先使用 blender_inspect_asset MCP 工具。否则运行：

$env:BLENDER_EXECUTABLE = "C:\path\to\Blender\blender.exe"
& $env:BLENDER_EXECUTABLE `
  --background --factory-startup `
  --python "<skill-root>\scripts\inspect_asset.py" -- `
  --input "<asset-path>" --output "<output-dir>\metrics.json"

检查：

• 求值后的顶点、边、多边形和三角形；
• 编写时与求值后的几何密度和细分修改器；
• 平滑着色与平面着色多边形的比例；
• 带 UV 的网格、基于节点的材质、图像纹理和编写时的灯光；
• 网格对象、材质、动作、帧范围和层级；
• 尺寸和世界边界；
• 无效坐标、退化面、松散元素、边界边和非流形边；
• 每个网格的连通分量；
• 非默认变换和缺失的材质分配。

使用 references/quality-gates.md 解读指标。不要将仅适用于打印的拓扑规则应用于所有游戏资产。

如果检查发现退化面或零长度边，请调用 blender_diagnose_topology，并提供 assetPath、新的 outputJson，以及可选的 objectName 和 limit。它会报告完整计数和有限数量的世界空间位置。 索引对应求值后的几何：定位区域、修复持久源文件，然后重新检查导出结果。仅有开放边界并不构成缺陷。

诊断修复前了解场景

配置 Rust 运行时后，使用 blender_describe_scene 获取求值后的 世界边界、编写时的 bas_role 标签、父子关系和分页对象摘要。 使用精确的 objectId 和 includeDescendants 聚焦；对于大型选集，请跟进 next_offset。装配关系由对象父子关系决定，而非集合名称。

仅根据简报，在 blender_quality_report 中使用 triangleBudget、 requireClosedMesh 或具名的 groundObjects，并显式指定 groundZ。 距离单位为 Blender 世界单位。约束检查完整选集； 空间候选项只比较当前返回页。AABB 重叠和邻近关系只是待审核的候选项， 不能证明网格相交、接触或支撑。 请阅读提取限制，尤其注意未展开的实例和非网格形式。

该报告不会替代视觉审核：review_required 不代表通过。打开下方固定视图， 并回答关于主体形态、参考和表面效果的问题。 如果缺少运行时，请按照其设置提示操作，或继续使用现有检查器和视觉证据；不要声称进行了未测量的分析。

修复后，对保留的候选版本和重新生成的结果使用 blender_compare_scenes。 声明 requiredObjects，且只声明合约规定的不变量。使用 invariantObjects，将有意编辑的部分排除在移动、尺寸、层级、角色或拓扑保留检查之外。即使没有任何已声明的不变量失败，也要审核所有实际变化。空的回归列表并不能证明视觉效果有所改善；保留修复前，请使用相同相机和设置渲染两个版本。

对于预期的物理接缝，在质量报告中将 contactPairs 声明为应当接触的精确网格对象对。根据构造合约选择对象对，而不是任意选择名称相近的对象。即使对象不在当前返回页中，若边界间隙大于 tolerance，也能证明它们分离，并产生 expected_contact_gap。contact_unverified 表示包围盒接近或重叠；这不能证明表面接触。对于带有中间连接件的接缝，应检查每处实际连接，而不是要求两个相距较远的端点相互接触。从多个视图审核接缝，修复持久源文件，并使用相同的已声明对象对重新运行检查，然后再保留修复。

检查特定连接点

检查动画姿势时，在 SceneIR 描述、质量和比较工具中提供 frame。前后对比证据使用相同的显式帧；配对资产比较会拒绝保存帧和单位比例不同的情况。在每个必需的运动状态下重复合同中的检查。设置帧不会烘焙模拟，也不能证明采样点之间的行为。

对于缆线端子、铰链枢轴或管道端部，当整个对象的边界框重叠时，contactPairs 可能无法发现错误的端点。向 blender_quality_report 添加 connectionPoints，其中包含稳定名称、精确的 objectA/objectB、对象局部坐标 pointA/pointB XYZ，以及以世界单位表示的 maxDistance。根据与真实端点相同的源参数放置的空物体可用作锚点。两个对象都必须属于所选装配体；分页不会隐藏检查项。

connection_checks 会返回世界坐标位置、距离和 delta_world_b_minus_a。即使边界框重叠，connection_point_gap 也能识别出声明的锚点位置不当。将修正应用到持久化几何源；编辑局部坐标时，将世界空间偏移转换到该对象的局部空间。锚点应从几何体派生，并验证渲染后的关节；仅移动标记并不能修复问题。within_tolerance 只能证明锚点一致，不能证明网格接触、封闭性或机械有效性。

检查评估后的运动

使用 blender_inspect_motion，提供 assetPath、新的 outputJson、2-12 个互不相同且递增的 frames，以及 1-8 个精确的网格 objectNames。该工具会报告局部评估几何哈希、世界变换和原生修改器／烘焙元数据。它需要 Blender，而不是 Rust，并且绝不会烘焙或保存源文件。检查流体／布料的现有缓存；需要导出动画时，也要对导出的文件重复检查。

局部哈希发生变化，可以证明采样到的形变，而不只是根节点移动；但这不能证明形变良好。空样本或未变化的样本、缺失的缓存文件以及未烘焙的修改器都需要调查。烘焙标记不能证明缓存覆盖完整。使用该领域的工作流检查接触、碰撞、时序、外观和连续播放。CLI 备用方案：通过 Blender 运行 scripts/inspect_motion.py，并使用 --input、--output、--frames 1,12,24 和 --targets Body。

渲染证据

进行参考图驱动的比例检查时，使用与参考图相匹配的自定义相机调用 blender_compare_reference。它会以内嵌形式返回参考图／剪影／叠加对比板。在几何编辑期间保持相机、裁剪范围和姿势固定。只有提供白色前景、黑色背景的 maskPath 时，才会计算剪影 IoU 和缺失／超出覆盖率；普通照片只会生成视觉叠加，不会计算数值相似度。这可补充最终的多视角和材质检查。

如果朝向看起来合理，但取景不同，请使用 blender_fit_reference_camera，并提供 3-32 个空间上彼此分离的已知标志点、referenceWidth/referenceHeight，以及新的 outputDir。每个标志点包含 name、objectName、localPoint（XYZ）和 referenceUv（以图像左上角为原点归一化的 XY 坐标）。该工具会在候选 .blend 文件中拟合比例／焦距和镜头偏移，不会改变姿势或网格。使用 blender_compare_reference 检查该候选文件；将接受的参数复制到持久化源文件中，然后固定相机以进行几何比较。较低的标志点误差表示取景拟合更好，并不代表几何有所改善。较大的残差可能意味着姿势或对应关系有误；不要为了降低残差而扭曲网格。 进行针对性修复时，使用 views: ["perspective", "front"]（或两个有用的固定角度）和 resolution: 256，以便快速查看效果。CLI 接受 --views perspective,front。清单将其标记为 partial_preview；它不满足最终的六视图门槛。前后检查时，保持相同的视图选择、分辨率和明确的呈现设置。确认保留修复后，再渲染完整视图集，而不是每次小改动后都渲染。

对于底部关节，在 views 中添加 bottom（CLI 使用 --views bottom）。这只会移除该视图中生成的摄影棚地面，并添加底部补光；不会移除创作的几何体。若要在不遮挡周围环境的情况下为小关节取景，请将 focusObjects 设为精确的对象名称（CLI 使用 --focus-objects '["Leg_FL","Seat"]'）。聚焦证据会标记为 detail_preview，作为完整资产视图的补充。遮挡几何体仍会显示；仅靠近距离裁剪或边界框重叠，不能证明两者接触。

默认的 presentation: "auto" 会根据恒定材质的亮度提示选择摄影棚背景：明亮资产使用深色背景，非常暗的资产使用浅色背景，其他情况使用中性石板色。CLI 中对应的选项是 --presentation auto。使用 neutral、dark 或 light 可覆盖此设置。灯光功率和摄像机取景会随资产尺寸调整；工具会重置创作时设置的灯光和色彩分级。如果原始灯光是请求结果的一部分，请另外保留一张创作时的精美渲染图。

接受呈现效果前，先打开首张主视觉图。如果材质颜色泛白、阴影遮住形体，或轮廓与背景融为一体，请使用更合适的预设重新渲染。自动选择只是起点；它无法推断由纹理决定的颜色、透明效果或艺术指导方向。如果不同目标需要不同效果，请提供两个实用选项，例如深色摄影棚和浅色目录风格。不要例行生成所有预设。先展示一张精心打磨的主视觉图，并提供多视图证据供检查。

对于基准测试和修复前后对比，请为所有比较资产指定相同的明确预设和渲染器版本；不要针对每种条件分别调整。evidence.json 会记录请求的／解析后的预设、功率、取景、色彩管理、引擎和设置版本。版本 2 会改变灯光和取景；在进行受控视觉比较前，必须重新渲染旧证据。

优先使用 blender_render_evidence。否则，运行 scripts/render_evidence.py 并指定输出目录。要求包含：

• 透视主视觉图；
• 正面、背面、左侧、右侧和顶部视图；
• 一张联系表；
• 适用时，包含动画中具有关键意义的帧。

使用图像查看工具打开主视觉图和联系表。检查：

• 轮廓和比例；
• 必需部件及其空间关系；
• 朝向；
• 悬浮或缺乏支撑的元素；
• 相交和意外间隙；
• 材质的可辨识度；
• 明显的刻面、刀锋般的边缘、粗模残留，以及缺失或损坏的纹理；
• 细节在预期比例下是否仍清晰可辨。

对于人形角色，请按照角色工作流检查形体和适配度：全身比例，以及鞋履、腰部／裆部、肩部、手部／拇指和面部／鼻子／耳朵／颈部的特写。检查运动时计算后的皮肤表面；骨骼相连或使用单个网格对象，并不能证明服装表面连续。还应在中性灯光和目标呈现效果下检查肤色及纹理接缝。若形体与需求说明不符，应将块状或过大的形体、无法解释的重叠以及肤色不连续视为视觉缺陷，而非成功的低多边形优化。应根据参考对象进行相对判断，而不是套用通用比例。

验证导出的产物

在请求或提供导出文件时使用此检查关卡。对于仅涉及 .blend 文件的任务，请重新打开并检查该场景。

1. 生成所请求格式的导出文件，或使用提供的导出产物。
2. 启动一个全新的 Blender 进程。
3. 独立导入、检查并渲染实际导出的文件。
4. 将必要的名称、材质、尺寸、动作和关键帧与创作场景进行比较。
5. 分别报告创作场景和重新导入后的指标。

报告

将每项发现归类为：

• gate：交付物无效或无法使用；
• defect：明确的请求、几何、呈现或动作缺陷；
• warning：需要审核的潜在风险；
• observation：中性测量结果；
• not_applicable：根据任务语义有意排除的检查。

附上确切的证据路径。除非确实打开查看过图像或视频，否则绝不要声称已检查过。