草图转照片级渲染

将建筑图纸——手绘草图、立面图、SketchUp或Revit导出图、彩色场地平面图、PDF图纸——转化为一张看起来像是用全画幅DSLR拍摄的照片，且设计完全按原样保留。Gemini生成像素（gemini-3-pro-image，旧版generateContent）。你的工作是围绕该调用的所有其他事宜：读取图纸、撰写渲染指令、控制成本，并在交付前对照源文件逐一检查每个结果。

scripts/render.py负责机械化操作，每轮一次模型调用：它将源图像边缘扩展到模型提供的十种纵横比中最接近的一种（因此绝不要求模型重新构图），以该比例渲染，再将源图像自身的矩形区域裁剪回来，标记任何重新构图行为，并生成一张前后对比检查图。以下路径均相对于本技能文件夹；请使用脚本的绝对路径调用它，并确保该Python环境能通过 render.py check 检查。

运行环境

实时渲染需要在用户自己的机器上运行Claude Code，且必须设置GOOGLE_API_KEY环境变量。如果你没有本地Shell或文件系统——例如在claude.ai聊天中、或在Claude API技能容器中——请明确告知：你可以读取图纸、撰写渲染指令，并且如果存在Python和Pillow库，可以展示一个--prompt-only的提示，但你不能执行渲染。切勿主动索要API密钥。

既定策略——请直接引用，切勿转述

用户于2026年8月28日给出的渲染策略：

任务：首先以1K质量渲染输入图像以降低成本。

保持100%准确的几何、比例和宽高比。

不得产生幻觉，不得添加/移除元素，除非明确指示。

将材料替换为真实饰面（例如陶土屋顶、逼真的树木、泳池、景观）。

输出必须看起来像高端DSLR建筑摄影。

所有编辑和修改应保持在1K质量，直到确认。

一旦批准，将同一图像升阶到4K质量：

提供清晰、精确的细节，无模糊或污迹。

放大查看时，每个元素都必须看起来真实且照片级。

精确保留参考图像的几何和细节保真度。

最终规则：始终先以1K渲染修改，然后在得到明确确认后，再增强到4K。

用户于2026年8月31日给出的对比检查图要求：

在未来的所有渲染中，每次渲染后我都需要对比检查图进行交叉验证。请更新所有相关设置。

如果你需要复述其中任何一条，请直接引用原文。成本数据和背景信息：references/policy.md。

硬性检查点

花钱前必须先询问。 在任何付费调用之前，告知用户图像数量、质量档次和成本，并等待明确的“是”。然后才能添加--spend-ok参数。脚本会强制此检查：没有--spend-ok参数，它会打印估算费用并以退出码3结束，不会读取API密钥。用户的“是”只涵盖你刚才报价的那次调用；后续每一次修改、补丁或重试失败通道，都是一次新的花费，因此要重新报价（一张图像，1K，最高约0.268美元）并再次征得同意。你可以将计划和价格放在一条消息里（例如：“下一步：修改视图02以修复屋顶颜色——1张图片，1K质量，最高0.268美元。继续吗？”）。报价基于图像费用；Google还会对每次尝试的输入图像（约0.0011美元）、提示文本和模型的思考令牌收费，因此实际费用会略高于报价。
4K升阶是针对单张图像的，且必须在批准后进行。 仅在用户已看过某张图像的对比检查图并点名批准后，才运行upscale --confirmed。用户说“看起来不错”并不代表批准整套图都升到4K，而“让它更清晰”也不等于批准重新渲染4K——你应该询问具体是哪一张图像。像任何花费一样报价：文件名称，1张图像，4K，最多2次尝试，最高0.48美元（每次尝试0.24美元）。
绝不进行4K迭代。 先在1K下修复所有问题；4K通道会忠实复现所有缺陷。4K文件是最终版本，绝不修改。
每轮渲染必须附带其检查图，且你先审查它。 每次渲染后，使用“读取”工具打开检查图，并对照references/review-checklist.md进行审查。基于你发现的问题，做出判断（匹配/轻微/重大），然后将渲染结果、检查图以及检查图所显示的内容一并交付给用户。没有检查图的渲染不算完成。
绝不覆盖，也绝不写入此技能文件夹。 脚本从不重用文件名，并且禁止输出文件夹位于技能文件夹内部；你自己也不得移动、重命名或替换已交付的文件或源文件。
绝不在聊天中处理API密钥。 不要索要、接收、打印或将其写入文件。如果用户粘贴了一个密钥，请告知它现在已暴露在聊天中，用户应删除该密钥并在AI Studio中重新创建，然后可将其设置为环境变量。优先使用用户的环境变量，而不是.env文件，且绝不将.env文件放在会被复制、压缩或上传的技能文件夹中。
在项目首次进行实时调用之前，告知用户图纸将被发送到Google的Gemini API（generativelanguage.googleapis.com）进行渲染。客户图纸是保密的；获得用户许可。
每次重试都会计费，包括那些未返回图像的尝试。应修改提示词；不要为了提高--attempts来挽救一个糟糕的提示词（脚本上限为3次）。

此技能不能做什么

管线会保留图纸本身的摄影机位。它无法展示建筑的另一个侧面、新的角度、缩放、裁剪或不同的宽高比，也无法将平面图转化为透视图或视平线视图：在知识树中，一张以图片形式提交的平面图被渲染成了一栋不同的房子，而仅通过提示词移动摄影机位的尝试也每次都给出不同的别墅（references/art-direction.md第13节）。当用户提出上述任何要求时，不要花钱：解释原因，并要求用户从3D模型导出该视图的新版本，然后将该导出图作为一个新任务来渲染。切勿在revise或patch注释中加入摄影机或构图变化；脚本如果检测到你这么做，会输出!! CAMERA / FRAMING WORDS。

它也不能擦除标签、对齐图幅、拼接陡峭的航拍图像或合成背景底图——这些在知识树中曾经是围绕渲染进行的配套工作（references/failure-modes.md）。如果这些是解决某个问题的关键，在花钱之前警告用户，单靠文字提示可能不够。

环境检查（每台机器执行一次）

运行 python scripts/render.py check。它会输出Python、Pillow和PyMuPDF的版本，检查图字体，模型ID，以及API密钥的来源位置（仅显示来源，绝不显示值）；如果没有密钥，它会显示设置步骤。如果导入失败，请使用那个Python运行 python -m pip install -r scripts/requirements.txt。如果密钥已就位，运行 check --online 会执行一次免费的 models.get 元数据调用，以证明密钥和模型工作正常；此调用不收费。

单个视图的工作流程

1. 输入

从用户处获取：作为磁盘路径的文件（粘贴的图像没有路径——询问文件在哪），一个视图名称，以及四个字段的备注——材料、光照、环境、其他（每项可选）。询问任何图纸中未明确但会影响最终效果的问题（这块平地是草坪还是铺装？阳光从哪边来？）而不是猜测。对输入进行分类：

一张包含多个图版（楼层平面、立面图）的图纸，或一个视图不在第一页的PDF：请用户导出一个图版或一页，或你自己将其裁剪成一个新文件，放在... Input文件夹中，每个视图一个任务。告知用户对比检查图会将那个图版与其渲染结果配对。在知识树中，密集的家具布局在生成时失败；在花钱之前说明这一点。
管线无法处理的要求（见上文）：在花钱之前停止并解释。
包含标题栏、面积统计表、标签或法定边界线的图纸：这些必须完全按原样保留，而模型无法保留文字（指令中禁止这么做）。请用户先将其裁剪掉再进行渲染，然后在最终图纸上将其原封不动地放回渲染区域之外；在任何警告中明确命名法定边界线，以防被误当作墙壁或误擦除。
与图纸相矛盾的要求（例如图纸画的是坡屋顶，用户却要求平屋顶）：指出来并询问。除非用户明确指示，否则策略要求保持图纸中的几何形态。

2. 读取图纸并撰写指令

首先，总是运行一次免费的--prompt-only通道，并始终带上--out（输出到此技能文件夹之外；对于 assets/test_sketch.png，使用一个临时文件夹）：它会将PDF的第一页栅格化，并将填充后的输入写入<out>/_work/prompt-only/<view>_<tier>_padded.jpg（最长边2400像素），这是最容易查看的文件。使用“读取”工具打开它并仔细研究。然后，根据references/art-direction.md指导文件撰写指令JSON：

{"elements": ["两层体块，坡屋顶，位于画面左半部分", "..."],
 "finishes": ["暖白色石灰抹灰墙", "..."],
 "cautions": ["构图：建筑主体占画面宽度的20-78%，屋檐高度37%；如果建筑变大、画面重新居中或出现天空，则结果失败", "..."]}

elements：每个建筑元素、开口、屋顶形式、楼层、栏杆、泳池、铺装区域、种植体量和家具项，附带其位置和数量（最多30项，每项160字符）。
finishes：真实材料（最多15项，每项120字符）。
cautions：首先写可测量的构图锚点，附带“如果...则结果失败”的测试；然后是层数、不是对象的制图痕迹、以及本帧特有的否定项（最多10项，每项160字符）。

保持指令简短——在过去实践中，过长的指令导致构图丢失。将指令文件保存在任务旁边，例如 <out>/_briefs/<view>.json。更长的材料或环境描述文本属于--materials / --environment 参数（备注总计最多4000字符）。

3. 选择参数标志

屋顶不是陶土材质（平板、膜材、石板、金属、绿色屋顶）？添加--no-terracotta-example，在指令中加入屋顶警示（“所有屋顶都是平的——无瓦片、无坡度、无陶土”，或“翼楼屋顶是平板——无瓦片、无坡度”），并说明真实的屋顶饰面。共享的保真度指令使用陶土作为示例饰面，并曾为平顶别墅添加了红色瓦片屋顶；此标志移除该正面示例。警示中仍可将陶土作为否定项。
默认质量为1K。仅当关键元素在1K下可能小于约20像素时（例如广阔的庄园航拍图），才建议使用--size 2K（同一标价）,并且只能在用户同意后使用；4K绝不是草稿质量。
输入是经过预处理的副本（轴线已清理、标签已擦除、白色空白已预先填充）？请将未修改的导出图作为--original FILE传入，以便检查图能配对真正的原始图。
当输入位于... Input文件夹中时，--out默认使用同级目录的03 Output文件夹，否则使用<input folder>/03 Output；它绝不能位于本技能文件夹内部。

4. 审核提示词（免费）

使用指令和备注，并带上--prompt-only重新运行，读取打印出的提示词，检查其中是否要求了图纸中没有的元素。

5. 估算、询问、渲染

先运行不带任何门控标志的命令以获取估算费用（退出码3），向用户报价，并等待“是”。然后带上--spend-ok重新运行。一次实时调用通常需要20-60秒，但一次尝试可能等待长达15分钟，超过了前台Bash调用能等待的时间：在后台运行实时通道（run_in_background）并等待它们完成。如果实时命令被中断，运行render.py status，报告该中断通道可能已被计费，并在任何重新运行前询问用户。多个视图：报出批次总价（视图数量 × 1K × 最多2次尝试），为整个批次征得一次同意，然后逐个运行视图。

6. 审查检查图

使用“读取”工具打开<out>/_Before After - <view>_1K.jpg。按照references/review-checklist.md进行审查：构图和比例、数量、开口、屋顶形式、楼层、新增或缺失的对象、文字、材料、真实感。一个橙色的“纵横比 a -> b（构图已更改）”注释，或来自脚本的WARNING行，意味着模型重新构图了：该渲染结果无法被修改或批准，因此应使用更强的构图锚点和一条警示（明确命名失败通道的具体问题）从源头重新渲染（例如“PREVIOUS ATTEMPT FAILED: ...”）。如果一个视图的两个1K渲染都重新构图，停止并报告，而不是重新生成。当检查图太小而无法判断细节时，打开渲染结果本身查看。

7. 报告

向用户提供：渲染结果路径、检查图路径、你的判断（附上发现的问题）、费用（render.py status显示）、以及选择——批准此图像升4K、修改一项内容、修补一个区域、或从源头重新渲染。

修改循环（保持在1K）

revise "<当前渲染结果>" --notes "<一项修改>"。规则：

每次修改只改一项。一项编辑中包含多个改动往往会导致整个画面被重新生成。
描述对象的最终状态，而非修正动作（例如：“入户门是暖青铜色实木，带两个竖向拉手”，而不是“修门”）。在写备注前放大渲染结果仔细观察：改色不是添加。
“修改前”的图像即是正在被修改的图像；检查图将其与新文件配对（BEFORE · <view>_1K / AFTER · <view>_1K_rev02）。
只有当前文件（任务中最新的非4K通道结果）才能被修改；如果你选择了其他文件，脚本会指出。对2K渲染结果的修改将在1K下进行，并命名为_1K_revNN。
当构图本身错误时（摄影机移动、主体变大、重新构图警告），不要修改：使用更好的指令从源头再次运行render。

修补（局部修复，保持在1K）

patch "<当前渲染结果>" --box x0,y0,x1,y1 --notes "<修改内容>"，其中框的坐标是相对于画面左上方(0,0)的比例。该框会被裁剪出来，在全1K分辨率下编辑，然后缩放回去，并在画面内部以36像素羽化边缘粘贴；框外部的每个像素保持字节级一致。用于单个对象或单个区域（一个发明出来的墙、错误的植物、一扇门）。说明什么必须改变，以及它必须清晰可见；不要告诉它保留你恰恰想要改变的东西。框的每一边至少72像素。

4K（单张批准的图像）

当用户批准一张图后：

在对比检查图上确认用户批准的是哪张图及哪个版本
运行 upscale --confirmed <render_path> （例如 upscale --confirmed /path/to/_work/renders/view_1K.jpg）
脚本会加载原始大小，以2倍分辨率（2K）提示，最多尝试2次，然后输出4K版本和更新的对比检查图
4K输出是不言自明的最终交付；无需再审查或修改
如果4K生成质量不可接受（模糊、染色、伪影），在报告中说明缺陷，然后返回1K链修复问题，再重新升4K

Sketch-to-Photoreal-Render（草图转照片级渲染）