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、--jsonstdout 输出紧凑 JSON 结果。完整接口以python scripts/snapshot --help为准——help 文本由 help_text() 按本 skill 实际启用的输入类型动态生成。对 STEP 输入支持的渲染模式是view每个输出一张静帧、orbit360° 转台 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_sizesizeProfile像素适用场景simple1200x900简单零件默认diagnostic1600x1200诊断/带标注评审标注或截面视图在未指定尺寸时默认此档位viewLabels: true、section模式均落入该分支assembly1800x1200复杂装配体assembly-large1920x1440更大更复杂的装配体presentation/presentation-large2400x1600 / 2800x1800展示级orbit960x640转台 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 commandparse_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 评审链接两个易误解的点爆炸图/标注评审是意图不是渲染模式。文档原文Exploded or labeled review is an intent, not a render mode——应通过 CAD Viewer 支持的机制、支持的 JSON job 设置display 设置中的exploded滑杆与edges线稿样式见 Display 选项说明或 GUI 链接来满足而不是期待一个叫exploded的--mode。display 模式带别名容错。源码维护一张别名表DISPLAY_MODE_ALIASES例如shaded/with_edges归一到solidxray/see_through归一到transparentwire归一到wireframe不在别名表中的模式名会直接报错并列出全部支持值而不是静默回退到默认渲染。诊断评审把视觉疑点翻译成几何检查文档的核心立场视觉评审是诊断性的diagnostic不是权威性的authoritative。任何视觉担忧必须先转化为后续几何检查才能被当作验证结论使用。文档给出的映射表视觉疑点应执行的确定性检查孔阵列看起来不对称测量各孔中心比较偏移量盖子、子零件或 occurrence 看起来偏移检查坐标系frames与配合差mating deltasgusset、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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考