Evidence-driven 3D asset inspection and controlled repair with a Manager and four specialized Agents.
面向 GLB 资产的质量检测、受控修复与独立验收系统。将“发现问题 → 制定方案 → 人工批准 → 修改副本 → 独立复核 → 发布或回退”串成可追溯任务，回答：资产哪里有问题、改了什么、凭什么验收、什么情况下不能自动改。
快速开始 · 架构与角色 · 案例与能力边界 · 验证记录 · 故障与恢复 · English
版本口径：本仓库整理自 2026-09-18 决赛 R2 代码，公开源码整理日期为 2026-09-28。图中包含事先制作的参考/拒绝样本，它们不是实时 Agent 修复结果。项目是有限范围的研究与演示原型，不是通用工业 CAD 修复软件。
- 验收先于修复：Quality Profile 声明用途、预算、目标区域和保护约束；模型不能自行降低阈值。
- 按权限执行：Manager 协调四个 Worker；修复方案绑定输入哈希、规则和操作范围，人工审批后才能执行需要批准的动作。
- 独立复核：执行成功不代表质量合格。通过原始 GLB 检查与 Blender 导入后的第二种方法验证，检查几何、关键特征及声明的材质/关系约束。
- 失败决定下一步：复核失败可退回、在已有授权范围内重新规划或转人工；无法确定开口用途时停止自动补洞。
- 证据与恢复：保留原件、副本、checkpoint、规则/Skill 版本、计划、批准、Agent 上下文和最终检查结果。恢复操作不重复执行结果不确定的步骤。
| 角色 | 实际职责 | 权限边界 |
|---|---|---|
Manager / scene-guard-leader |
分派任务、读取结果、选择下一步与恢复分支 | 不替人批准，不把失败改成通过 |
Auditor / asset-auditor |
建立任务，定位问题并产出检测证据 | 不执行修复 |
Planner / repair-planner |
结合需求、问题与白名单制定修复方案 | 不修改原件 |
Executor / repair-executor |
执行已授权计划，保存修复副本和 checkpoint | 不批准，不自行验收 |
Verifier / regression-verifier |
独立验证并给出发布、回退或人工审核结果 | 必检 UNKNOWN 不能当 PASS |
五个角色使用独立容器、上下文和工具权限，可共享同一份本地 qwen3.5:9b 权重。Element 是 Matrix 协作房间的客户端，用来观察消息与协作；权限和状态约束由 SceneGuard 执行。编排拓扑和状态机有固定约束，模型在许可动作集合中决策；不宣称无约束自主编排。
| 案例 | 问题与影响 | 要验证的行为 |
|---|---|---|
| 设备外壳 | 局部面朝向错误，背面剔除下出现缺面；同时检查退化面与其他要求 | 提案、人工批准、修复副本、独立复核；保护非目标几何 |
| 安装支架 | 减面达到预算，但安装孔或结构可能损坏 | 预算与特征约束同时验收；失败回退，受约束地换策略 |
| 通风面板 | 有边界，但破损与设计开口不能仅靠几何确定 | 保留疑点，停止自动补洞，交给人工确认设计意图 |
另有隔离实验覆盖声明参考下的 UV 恢复、已确认局部孔洞、局部拓扑替换及关系损坏拒绝，详见能力边界。
Python 3.11，安装锁定的 Pillow 依赖后：
python -m pip install -e .
python scripts/run_cli.py serve --host 127.0.0.1 --port 18096 --asset-root samples --profile-root profiles --jobs-root .semifinal-demo-jobs浏览器打开 http://127.0.0.1:18096/ 。这一步用于查看当前界面、资产和配置；真实修复与独立复核需 Blender 4.5.9，真实 Agent 模式还需 Docker / HiClaw / Ollama。界面中的“仅验证工具流程”不代表发生了模型推理。
$env:SCENEGUARD_BLENDER = 'C:\tools\blender-4.5.9-windows-x64\blender.exe'
python scripts/finals_demo.py start --mode tools
# 准备好本地五角色运行环境后：
python scripts/finals_demo.py start --mode agents不要同时启动两个入口占用同一端口。新设备完整步骤、运行依赖及数据边界见 快速开始。本仓库不包含 Python/Blender 二进制、Docker 镜像、模型权重、账号令牌或私人任务数据库。
python scripts/check_release_core_isolated.py
# 完整优化检查需要配置 Blender：
python scripts/check_optimization_release.pyR2 归档结果为 46 项核心检查 + 104 项优化检查，另有 10 个隔离算法案例。这些是有限合成案例的技术验证，自动测试中的批准不等于真人批准。归档时最新真人主案例仍为 WAITING_APPROVAL，目标演示笔记本也未完成实机验收；不能据此声称全部真实部署闭环已通过。公开整理版的复验结果单独记录在 验证说明。
| 路径 | 内容 |
|---|---|
src/sceneguard/ |
GLB 解析、审计、需求匹配、计划、执行、独立验证、工作区、HTTP 与 UI |
profiles/、schemas/、skills/ |
版本化质量要求、数据契约与 Skill 规则 |
scripts/ |
Agent 桥接、Blender worker、启动和回归入口 |
samples/ |
三份正式合成输入及隔离的建模参考 |
tests/ |
安全门禁、几何与恢复回归测试 |
docs/ |
部署、架构、边界、验证及评委要求对应 |
tools/asset-casebook/ |
合成资产生成脚本；重新生成不覆盖正式样本 |
团队成员应分别描述自己的实际贡献；仓库不代填姓名、分工或比赛名次。可引用的项目介绍：
SceneGuard：面向 GLB 的多 Agent 质量检测与受控修复系统，集成 Manager + 四类 Worker、人工审批、独立复核、版本回退及任务证据链，使用 Python、Blender、Docker、Ollama 与 Matrix/Element。
开发方式见 CONTRIBUTING.md。公开版材质观察器与私有 R2 有实现差异，见 公开版变更。原项目代码沿用 Apache-2.0，外部依赖与素材各自遵循原许可，见 第三方说明。