Photoreal Asset（照片级真实资产生成器）

Photoreal asset（照片级真实资产）

调研简介，执行一次独立构建，与照片比较，并报告结果。 使用已安装的 Blender 和宿主提供的可用 Agent 工具；无需特定的 Agent 提供商、 模型、Blender 安装路径或项目位置。

设置（Setup）

• 将 {SKILL} 解析为包含本文件的目录，{SCRIPTS} 解析为其中的 scripts/ 目录。 将 {PROJECT} 解析为用户选择的项目目录。在命令中引用路径。 示例使用正斜杠，Python 在 Windows、macOS 和 Linux 上均能接受。
• 使用 Python 3 及 numpy 和 Pillow 库（python -m pip install -r "{SKILL}/requirements.txt"）。 SciPy 为可选，可加速 UV 检查。Blender 使用其自带的 Python 运行 bpy 脚本。
• 在 PATH 中查找 blender，或设置 PHOTOREAL_BLENDER 环境变量指向可执行文件的完整路径， 值中不要包含引号。构建脚本和测试工具均使用该可执行文件。 检查其版本并使构建代码适配其支持的 bpy API；不要假定固定的版本。
• Cycles 渲染器会自动选择可用的 GPU 后端，若无则回退到 CPU。设置 PHOTOREAL_CYCLES_DEVICE 为 CPU、OPTIX、CUDA、HIP、METAL 或 ONEAPI 可覆盖自动选择。 顺序执行渲染任务。可通过 PHOTOREAL_GPU_TOOLS 提供可选的外部 gpu_slot.py 队列； 该队列不捆绑提供，也非必需。
• asset.json 中的路径相对于该文件。空的 hdri 值使用程序化日光天空； 否则指向现有的 HDRI 文件。构建开始后，保持光照和摄像机不变。
• 默认交付物为包含打包图像和审查渲染的可编辑 .blend 文件。仅当用户请求时才添加游戏导出内容， 遵循 templates/GAME_READY.md。

项目布局

<project>/
  asset.json          摄像机、光照、集合前缀及审查参考
  BRIEF.md            调研简介及已填充的 RULES.md 模板
  ref/SOURCES.md      照片来源；参考图像不随项目分发
  research/           包含 layout.py、blockout.py、blockout.blend、NOTES.md
  rounds/r01-build/   包含 TASK.md、build.py、NOTES.md、tex/、renders/、final/、DONE.txt
  <Title>.md          轮次表和项目日志

如果用户提供了现有资产库，请使用它。记录外部图像和纹理的源 URL 及许可证。 将未知许可证标记为未知；不要虚构所有权或随交付物分发参考照片。

1. 研究（Research）

1. 将 templates/asset.json 复制到项目中，并调整主体、 collection_prefix、天空和地面。为主视图、侧面/正面、顶部四分之三视角以及最难部分的特写视图 设定画面。为审查器设置 render_as、photo_kind 和 scope_note。
2. 填写 templates/TASK_research.md：{ASSET}、{PROJECT}、{PREFIX}、 {SUBJECT_PLURAL}、{SKILL} 和 {SCRIPTS}。将其保存为 research/TASK.md。 通过宿主提供的 Agent 工具运行一个研究员，或直接执行研究。
3. 交付带有来源信息的参考照片、BRIEF.md、research/layout.py（每个部件一个区域和一个所有者集合）、 遮罩文件，以及 asset.json 中的 owner_refs / overall_refs。
4. 使用宿主的图像查看器检查遮罩渲染结果。调整摄像机直至每个画面正确取景其主体，然后锁定它们。

如果是提供的设计稿，将其原样复制到 ref/ 目录，记录提供的来源信息（未指定则标记为未知）， 并制作细节裁剪图。使用设计稿中的视图作为被评估的摄像机。 当目标是匹配风格化设计而非使其看起来像照片时，设置 critic_goal； 相应调整任务措辞及任何额外交付物。

2. 构建（Build）

1. 从 templates/TASK_build.md 创建 rounds/r01-build/TASK.md。 填写 {ROUND}、{ASSET}、{PROJECT}、{ROUND_DIR}、{FILE} 和 {SCRIPTS}。
2. 对于纯 Blender 资产，将 {GAME_READY} 留空。否则插入已填写的 templates/GAME_READY.md，选择 Godot、Unreal Engine 或两者。
3. 将任务交给一个构建器。除非用户要求，否则使用当前模型。 如果宿主暴露了会话标识符，请保持其会话标识。一个构建器拥有几何体的所有权； 独立的审查器仅对其进行评审。

3. 每轮审查（Review every round）

1. 渲染最终场景：

   python "{SCRIPTS}/run.py" --asset "{PROJECT}/asset.json" --parts "{ROUND_DIR}/final/{FILE}.blend" --out "{ROUND_DIR}/final/renders"
   

2. 阅读 NOTES.md 和最新的 critique.md。检查照片旁边困难部分的全分辨率裁剪图， 包括必要时变亮的裁剪图。严重程度计数仅供参考；根据实际视觉差异判断进展。
3. 如果存在上一轮，与上一轮进行比较：

   python "{SCRIPTS}/compare_rounds.py" --asset "{PROJECT}/asset.json" --rounds <上一轮> <当前轮> --focus <区域ID列表> --refs "<照片路径>:x0,y0,x1,y1" --out "{PROJECT}/compare_rounds"
   

   检查生成的 _all.jpg 和 _focus.jpg 对比图。使用 compare_rounds.py --help 所期望的轮次目录路径。
4. 对于游戏导出内容，运行 GAME_READY.md 中针对目标平台的验证。 不要将通过 Godot GLB 检查器的 Unreal 导入验证描述为有效。
5. 如果有支持的转录日志，可运行：

   python "{SCRIPTS}/audit_round.py" "{ROUND_DIR}" --root "{PROJECT}"
   

   该审计工具能理解 Antigravity 和 Claude Code 日志，并非所有宿主。传递 --session 指定 Antigravity 对话，传递 --allow 添加额外允许的工具目录。 其文件路径扫描能识别 Windows 驱动器路径；其他路径格式需单独检查。 可通过 PHOTOREAL_ANTIGRAVITY_LOGS 和 PHOTOREAL_CLAUDE_LOGS 覆盖日志根目录。
6. 记录该轮次并报告图像、改进点、回归问题、验证结果及一条建议。仅在实际测量时报告成本。 在请求的轮次结束后停止；仅在用户要求时开始新一轮精修。仅在用户明确要求时才复制或导入到外部库。

4. 按需精修（Refine on request）

1. 从相关视角（坐姿、空载、侧面及评估摄像机的角度）获取命名部件的更好照片。 在 ref/SOURCES.md 中记录来源。
2. 将最强的参考图放在所有者的 owner_refs 列表最前面；每组最多六张。
3. 将上一轮的构建脚本、tex/ 和 final/{FILE}.blend 复制到新的 rounds/rNN-<focus>/ 文件夹中。保留其笔记为 NOTES_<previous>.md，上一次检查结果为 renders/<previous>_check/， 最终渲染结果为 renders/<previous>_final/。
4. 填写 templates/TASK_refine.md，包括部件、区域 ID 和 新的参考信息。将更改限制在这些部件内，除非其他地方存在严重程度为 3 的缺陷。保持 规则：当照片与冲突的位置和角度（包括连接的部件）矛盾时，以照片为准。
5. 运行一个构建器，按上述方式审查，并在照片旁边展示上一轮和当前轮的结果。

Agent 交接与独立审查（Agent handoff and independent critique）

使用宿主的原生 Agent 接口，而不是假定工具名称或模型别名。 为研究员或构建器提供其工作目录和完整的任务文件。写入操作限于 指定的项目或轮次目录内。任务结束时写入 DONE.txt。 如果无法委派构建器，则直接构建，同时保持相同的任务边界。

规则 11 的审查器必须独立于构建器。photo_check.py 准备提示和 critic_jobs.json 清单。将每个提示发送给一个全新的审查器，仅提供图像/文件读取权限， 无网络或编辑工具，然后将其 JSON 回复保存到清单的 response_file 中并合并。 仅在宿主支持时并发运行审查器，并遵守 critic.parallel 设置。 当提示涉及图像/文件读取时，使用宿主的图像查看器。

如果无法使用独立的子 Agent，则 --runner claude 可使用已安装且已验证的 Claude Code CLI。否则交付渲染结果和准备好的审查作业，并报告独立审查 未完成。不要用构建器自己的审查来替代并声称其为独立审查。

检查脚本（Checks）

脚本	用途
run.py / render.py	在锁定的 Cycles 场景中渲染与指定前缀匹配的集合；输出摄像机视角 PNG 和 sheet.jpg。
photo_check.py	裁剪布局区域，准备独立审查器作业，并将 JSON 响应合并为 critique.md。--from 复用已有渲染；--groups 选择所有者。
game_check.py / game_check_bl.py	验证 Godot LOD 网格、UV、凸碰撞体及嵌入的 GLB 纹理；生成 LOD 转盘渲染。Unreal 验证请参见 GAME_READY.md。
compare_rounds.py	比较不同轮次及重点关注区域的裁剪图，并显示参考行。
audit_round.py	可选地检查支持的日志，分析文件访问、相邻轮次、网络调用及测量的 token 使用量。

审查原则（Review principles）

• 获取弱项部件的更好照片通常比在简介中添加更多规则更有帮助。
• 将每次精修与上一轮比较：一个修复可能抹去之前的改进。
• 在更改几何体之前，使用比例匹配的叠加层检查比例问题。
• 暗腔需要可见的边缘高光、壁厚和内部衰减。变亮仅用于检查；保持被评估的光照不变。当变亮会裁剪高调图像时，跳过变亮。
• 将审查意见视为一轮内的修复清单，而不是轮次之间的数值分数。