text-to-cad CAD Skill 的快照评审工作流：STEP/STP 工件的强制视觉验证与诊断渲染

text-to-cad CAD Skill 的快照评审工作流：STEP/STP 工件的强制视觉验证与诊断渲染

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad

本文基于 text-to-cad 仓库 CAD skill 的参考文档 snapshot-review.md 展开，系统讲解"快照评审（snapshot review）"这一强制验证环节：如何为新建或可见更新的 STEP/STP 工件选择恰当的 PNG/GIF 评审包、如何编写多视角viewJSON 渲染任务、如何理解输入路径语义与--focus/--hide选择器，以及如何把视觉疑点转化为确定性的几何检查。读完本篇，你可以在 CAD agent 工作流中正确执行python scripts/snapshot，构造出覆盖全部关键面与内部特征的评审图像包，并明确何时必须跳过快照、跳过后如何报告。

为什么快照评审是强制的验证步骤

CAD skill 的主文档 SKILL.md 把快照验证列为"Required workflow"第 9 步，且措辞明确："snapshot validation is mandatory"（快照验证是强制的）。snapshot-review.md 对这一策略的完整表述是：

• 每一个被创建或可见更新的主 STEP/STP 零件或装配，都必须至少经过一张被审阅过的 PNG 快照；确定性检查（deterministic checks）通过不是跳过快照的理由；
• 生成快照应使用 CAD skill 自带的scripts/snapshot，而不是手动打开 CAD Viewer 或驱动 Playwright——文档给出的理由是：快照更快、更轻、更精确，且对 agent 更友好（产出是可直接消费的文件路径）；
• 静态审阅使用PNG，运动/动画审阅使用GIF，后者包括 STEP 模块参数动画（parameter animation）。

仅在以下四类情形可以跳过保存快照，且跳过时必须报告原因，以及仍然运行了哪些确定性检查：

跳过条件	含义
纯格式/导出请求，几何未变化	例如只要求把已有模型转成 STL
源码变更不改变可见几何	如仅改标签、注释
纯检查任务（例如直接询问尺寸测量）	没有创建或更新任何东西
Python 或 STEP 生成失败，尚不存在有效工件	没有可渲染的对象

文档同时明确了一条反循环规则：不要在快照上打转（Do not loop on snapshots）。只有两种情况才值得重新渲染——修复源码后可见几何确实发生了变化，或某个具体的视觉发现需要再次确认。

运行基础：一套被多个 skill 共享的 snapshot CLI

从源码结构看，快照能力在 text-to-cad 中是"单一共享实现 + 各 skill 声明式启用"的架构。CAD skill 的入口 skills/cad/scripts/snapshot/main.py 很短：声明本 skill 接受的输入类型KINDS = ("step", "stp", "3mf", "glb", "stl")，指定自带的无头浏览器运行时目录runtime/（内含 render.html 与 snapshot-render.js），然后把参数解析、任务规范化和浏览器渲染全部委托给共享模块 cadgen/snapshot_cli.py。

该共享实现被仓库中六个渲染类 skill 复用（cad、dxf、implicit-cad、sdf、srdf、urdf）。它按输入后缀分派到不同解析器（见 KIND_RESOLVERS），未启用的输入类型会被按名称拒绝并指明归属的 skill——这与 SKILL.md 的说明一致：本 skill 渲染.step/.step.py、.stp、.3mf、.glb、.stl，而隐式模型与机器人描述分别由implicit-cad和urdf/srdf/sdfskill 渲染，CLI 会拒绝而不是渲染它不该渲染的东西。

任务（job）的输入形式有三种，由 load_job_from_options 处理：单个 job 对象、job 数组或{"jobs": [...]}包裹形式（一次批量渲染多个任务）、--job -从 stdin 读取。若不想写 JSON，还有快捷方式：--input+--output（可配--camera）会被组装成等价 job。常用命令行选项包括--mode、--theme、--display、--camera、--size-profile、--width/--height、--focus/--hide、--view-labels、--params、--params-path、--json（stdout 输出紧凑 JSON 结果）。完整接口以python scripts/snapshot --help为准——help 文本由 help_text() 按本 skill 实际启用的输入类型动态生成。

对 STEP 输入，支持的渲染模式是view（每个输出一张静帧）、orbit（360° 转台 GIF）、section（剖切扫描）、list（以 JSON 输出零件 occurrence refs，不写文件），定义在 STEP_SUPPORTED_RENDER_MODES。注意 STEP没有animate模式：STEP 的参数动画是通过view模式对stepParameters做扫掠实现的，且动画扫掠只允许恰好一个输出；.gif输出只允许出现在orbit模式或参数动画中（normalize_common_job 会拒绝其他模式下的.gif路径，避免产生看起来像坏动画的单帧 GIF）。

评审包规模：一张图够，还是多视角包

文档的 sizing 规则：

• 简单的静态零件：一张 PNG 就够；
• 小型多视角包（small multi-view packet）：当形状复杂度或 prompt 意图使"语义错误"（看起来不像要的东西）成为可能时使用。触发信号包括：
  • 装配体，或超过一个 body/part；
  • 多个面或多根轴上的孔；
  • 壳体、内腔、孔腔、通道、开口 enclosure 或对截面敏感的特征；
  • 加强筋、角撑（gusset）、凸台（boss）、垫柱（standoff）、槽、切槽、减重孔、散热片、叶片、重复阵列；
  • 在几何、布尔、选择器或特征失败之后的源码修复；
  • prompt 中"看起来像所请求的物体"本身就是任务的一部分；
  • 确定性检查通过、但可见语义仍然不确定。

标准小型多视角包：一个viewJSON job

文档推荐用单个viewJSON job产出四个输出：

{ "input": "models/part.step", "mode": "view", "outputs": [ { "path": "/tmp/render/iso.png", "camera": "iso" }, { "path": "/tmp/render/iso_opposite.png", "camera": { "direction": [-1, 1, -0.8] } }, { "path": "/tmp/render/top_ortho.png", "camera": "top" }, { "path": "/tmp/render/front_ortho.png", "camera": "front" } ], "render": { "viewLabels": true, "padding": 0.12, "sizeProfile": "diagnostic" } }

四个输出的职责设计有明确的几何覆盖逻辑：两个方向相反的等轴测视图（iso与direction: [-1, 1, -0.8]）保证每一个面至少出现在一张图里——背面、左侧、底部特征默认被覆盖，而不是靠怀疑去补拍；top正交视图是图案/对称性的主检查位；front正交视图是轮廓（profile）检查位。camera字段支持预设名、azimuth:elevation对，或包含preset/position/target/up/zoom的 JSON 对象（见 help_text 中 --camera 的说明），示例中的direction向量即自定义方向写法。

输入路径语义：.step.py与.step不等价

input指向主 STEP/STP 工件，用相对或绝对路径均可；snapshot CLI 会从该输入路径推导内部渲染根目录（resolve_render_job 中 root_path 取输入文件的父目录，渲染资产 URL 据此生成，且要求资产位于该根目录内）。一个易踩坑的细节：

• 输入是<name>.step.py生成器时，永远渲染该生成器的入口包，即使旁边存在同名的已导出<name>.step文件——源码中通过explicit_python标志显式保持生成器入口（ensure_render_job_step_artifact）；
• 只有当你明确想要"导入的 STEP"入口时才显式传.step路径——这可能触发首次较慢的 direct-import 工件构建（导入件没有生成器缓存）。

默认值：snapshot主题、solid显示与尺寸档位

job 默认theme: "snapshot"、display.mode: "solid"。snapshot是一个仅渲染用（render-only）主题：基于 Workbench Light，但去掉了地面网格、原点轴和阴影。源码注释解释了原因（snapshot_core.py）：在静帧中网格与坐标轴是"几何形状的对比线"，读起来更像零件轮廓边而非方位参考；材质、光照与背景则与 Workbench Light 完全一致。snapshot不出现在 CAD Viewer 的主题选择器里；若要与视口完全一致，应显式传theme: "workbench-light"。

尺寸档位方面，文档口径与源码常量一一对应（尺寸常量 与 default_render_size）：

sizeProfile	像素	适用场景
simple	1200x900	简单零件默认
diagnostic	1600x1200	诊断/带标注评审；标注或截面视图在未指定尺寸时默认此档位（viewLabels: true、section模式均落入该分支）
assembly	1800x1200	复杂装配体
assembly-large	1920x1440	更大更复杂的装配体
presentation/presentation-large	2400x1600 / 2800x1800	展示级
orbit	960x640	转台 GIF

对 CAD 评审包，文档建议只使用静帧渲染模式view与section；当显式 CAD 线稿有助于视觉检查时，将display.mode设为solid、transparent、hidden_edges、hidden_lines_removed或wireframe（完整取值与别名见下节）。

--focus与--hide：装配体中的选择性渲染

• --focus '#o1.2' ...强调特定零件或子装配的 occurrence ref：在view/orbit渲染中，被聚焦的 ref 保持完全不透明，其余装配体原地变幽灵（ghosted in place），构图与上下文保留；在section模式中，focus 会完全隔离这些 ref。
• --hide '#o1.2' ...在所有模式中把指定零件从渲染中完全剔除。
• 二者不能在同一条快照命令或 job 中组合——解析器直接报错--focus and --hide cannot be used in the same snapshot command（parse_snapshot_args）。
• 两个过滤只接受 occurrence ref，不接受面、边、顶点或形状选择器。源码层面，选择器会被解析并校验类型（normalize_selection_selector：非 occurrence 类型直接抛错），并且每个 ref 都会对照工件的 selector 索引验证存在性——拼错的#o1.2会得到 "references unknown part/subassembly occurrence selector" 的明确错误，而不是静默渲染整包。

输出文件名的 UTC 时间戳

保存 packet 时，snapshot CLI 会在每个输出文件的扩展名前追加一个全 packet 共享的 UTC 秒级时间戳，使iso_solid.png这样的可读路径变成iso_solid_20260527T163012Z.png。实现见 snapshot_timestamp / timestamp_output_path：时间戳格式%Y%m%dT%H%M%SZ，在 packet 解析时生成一次（resolve_render_job_packet），因此同一批输出共享同一时间戳，既不会互相覆盖，也可按批归档。

定向增补视图：section 与 display 模式

"只在 brief 或失败模式要求时才加视图"。文档列出的定向增补项：

场景	手段
参考图复现	从参考图的 viewpoints 各拍一张快照，用于并排对比
壳体、孔腔、内腔、通道、盲孔、enclosure、墙/地关系	section模式（剖切扫描）
带显式边线的着色 CAD 视图	display.mode: "solid"
无边线叠加的材质着色视图	display.mode: "rendered"
透明加信息量、线框太噪时的重叠/碰撞/隐藏接触检查	display.mode: "transparent"
实体着色背景下透出隐藏/被遮挡 CAD 边	display.mode: "hidden_edges"
隐藏边应被抑制的线稿式评审	display.mode: "hidden_lines_removed"
需要完整三角线时的内部重叠、隐藏干涉、装配碰撞怀疑	display.mode: "wireframe"
带标注/注释的评审	使用 CAD Viewer 支持的 refs、选择、截图或 GUI 评审链接

两个易误解的点：

1. 爆炸图/标注评审是"意图"，不是渲染模式。文档原文："Exploded or labeled review is an intent, not a render mode"——应通过 CAD Viewer 支持的机制、支持的 JSON job 设置（display 设置中的exploded滑杆与edges线稿样式，见 Display 选项说明）或 GUI 链接来满足，而不是期待一个叫exploded的--mode。
2. display 模式带别名容错。源码维护一张别名表（DISPLAY_MODE_ALIASES），例如shaded/with_edges归一到solid，xray/see_through归一到transparent，wire归一到wireframe；不在别名表中的模式名会直接报错并列出全部支持值，而不是静默回退到默认渲染。

诊断评审：把视觉疑点翻译成几何检查

文档的核心立场：视觉评审是诊断性的（diagnostic），不是权威性的（authoritative）。任何视觉担忧，必须先转化为后续几何检查，才能被当作验证结论使用。文档给出的映射表：

视觉疑点	应执行的确定性检查
孔阵列看起来不对称	测量各孔中心，比较偏移量
盖子、子零件或 occurrence 看起来偏移	检查坐标系（frames）与配合差（mating deltas）
gusset、boss、standoff、rib 或板件疑似悬空	检查 solid 数量、标签、连通性、接触或相关距离
腔体、孔腔或盲孔看起来不对	先做section评审，再测量壁厚、深度或贯通条件
重复阵列看起来不均	测量阵列中心、角间距或 occurrence frames

这些检查在 CAD skill 中对应scripts/inspect的measure、align、frame、diff等子命令（见 SKILL.md 的 Required workflow 第 8 步：以refs --facts --planes --positioning为基线，再对用户规格点名到的尺寸与关系做定向检查）。也就是说，快照回答"哪里可能不对"，inspect的度量结果才回答"确实不对、偏了多少"。

报告与交接：快照评审的最终形态

评审完成后，最终报告必须满足（与 SKILL.md 的 Handoff 一节一致）：

• 包含本次生成的快照 PNG/GIF，或给出有据可查的跳过原因（上述四类情形之一）；
• 明确说明哪些确定性检查支撑了每一个视觉发现——不要只说"截图显示孔阵列对称"，而要说"section 快照 +measure孔心距测量共同确认对称"。

配套的交接规则：完成 CAD 工作并产出/更新.step、.stp、.stl、.3mf或原生.glb后，若安装了$cad-viewerskill，必须把显式文件路径交给它并回传活链接；viewer 不可用或启动失败时要如实报告，并回退到"CLI 检查 + 快照"作为证据。验证快照生成失败时同样要说明原因，并报告仍运行了的确定性验证。最后一条 Non-negotiables 规则收束全文：只报告实际运行过、或有工具输出直接支撑的检查。

小结

snapshot-review 文档在 text-to-cad 的 CAD 工作流中扮演"视觉闸门"角色：它以强制策略保证每个新工件至少经过一次被审阅的静帧检查，以 sizing 规则和多视角包设计控制评审成本，以view/section加 display 模式组合覆盖从轮廓、图案到内腔的各类语义风险，并以"诊断非权威"原则把一切视觉结论锚定回inspect的确定性度量。配合共享 CLI 的选择器存在性校验、按 skill 的输入类型门禁和带时间戳的输出命名，这套机制对人（可读的iso_*.png）和对 agent（可解析的 JSON 结果与文件路径）都是可消费、可审计的。

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad