text-to-cad CAD 修复闭环STEP 建模失败的诊断分类与最小修复方法【免费下载链接】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技能中从 build123d Python 源码生成 STEP、执行几何检查refs/measure/align/diff、审查快照到 CAD Viewer 交付任何一个环节失败都不意味着推倒重来。本篇以 repair-loop.md 为主体完整展开这套“读输出 → 分类 → 最小修改 → 重跑 → 复核 → 上报”的修复闭环并结合仓库中 CLI 错误上报、inspect校验等源码实现帮助读者建立一套可复制、可验证的 CAD 模型故障排查方法论。修复闭环的六步流程SKILL.md 的 Required workflow 第 10 步明确写道“If a check fails, change the smallest responsible source section, regenerate, and rerun the failed validation.” 这正是 repair-loop 文档的核心立场修复是对源码的最小责任性修改而不是对产物的人工修补。完整循环如下读取失败命令的输出Read the failing command output。先看工具实际说了什么不靠猜测。对失败进行分类Classify the failure。把现象归入下文的失败类别之一。做最小的责任性修改Make the smallest responsible source or command change。只改“肇事”的源码段或命令参数。重跑失败的命令Rerun the failed command。重跑所有依赖的验证检查Rerun any dependent validation checks。修改可能波及其他断言。报告剩余风险或有意的偏差Report remaining risk or deliberate deviations。这条循环适用于所有失败场景generation、export、inspection、positioning、snapshot review、CAD Viewer setup 或 documentation validation。失败分类一多截面 Loft 失败典型报错是Failed to create valid loft/Recovery failed——注意这类消息既不指出哪个 station 出错也不说明原因。文档给出的排查顺序是固定的两步用递增前缀做括号定位以faces[:5]、[:10]、[:20]、… 逐段扩大截面集合去 loft同时观察报告的体积而不只是异常——一个“成功”但体积荒谬的 loft 同样已经是失败。对每一对相邻截面adjacent pair单独 loft。若所有相邻对都能成功而全集失败说明每个截面单独看都正常问题是全局性的——几乎总是截面之间采样点数不一致。修复方式是保证每个截面使用固定的采样点数。在动手做上述两步之前还有两个“静默原因”值得先排除某个截面本身就是断开的两个闭合区域例如某个 station 同时切到了两个独立的机身或穿过了一条开口槽会生成一个不抛异常、面积还“看起来合理”的Face只有Face.is_valid为False。此时 loft 会在几十个 station 之后才炸掉。修复策略是在最后一个连通的 station 处结束 loft或者在截面里桥接这段空隙、之后再把它切回来。一个极易踩的坑Face.is_valid是属性而非方法——写f.is_valid()会抛出TypeError: bool object is not callable看起来像对象损坏实际只是调用方式错了。组件不存在处的采样被丢弃当某个 station 上某组件尚不存在时如果直接丢掉样本点数就会逐站漂移。正确做法是带值通过carry a value而不是丢弃样本。失败分类二对大型 Loft 表面做布尔永远不返回这是对单个大 B 样条曲面做 subtract 的经典陷阱。成本是每把刀具一次全表面分类per-tool full-surface classification并随刀具数量超线性增长。文档给出了同一模型上的实测数据约 4900 个控制点的 skin刀具数耗时124 s470 s4115 分钟内未完成44运行 7 小时以上仍未完成一个关键判断依据把刀具批量放进一个 list operand 并不会帮忙因为成本是 per-tool 而非 per-accumulation。确认而非猜测的方法进程持续 ~100% CPU进度文件冻结在第一个 phase做栈采样会看到Extrema_ExtPS::Perform且BSplSLib_Cache::BuildCache在几乎每次求值时都在重建缓存。修复思路是干脆不要切浅装饰性凹槽根本不需要布尔。文档给了一个具体的换算示例——19 m 的模型渲染到 1920 px 时1 px ≈ 10 mm那么一条 4 mm 的凹槽是亚像素的它之所以“看得见”只是因为边线叠加层edge overlay会画出特征边。结论是只保留那些改变轮廓silhouette的开口的布尔其余特征改为加性构造。失败分类三源码导入或语法失败可能原因Python 语法错误缺少 import用错了 build123d 的符号名函数没有命名为gen_step()意图函数之外存在有副作用的可执行代码。修复动作修正 import 与语法确保gen_step()返回 STEP-ready 的 shape 或 compound输出路径放在 CLI 命令里而不是写在gen_step()内部。这一点在源码层有直接支撑。scripts/gen的入口 cli.py 在解析阶段就拒绝了非法目标形态带的SOURCEOUTPUT对已不支持须改用--write后缀为.step/.stp的目标会被明确报错“scripts/gen builds gen_step() Python sources only”非.py目标同样被拒。也就是说很多“目标写错”类的失败会在运行前就被命令行校验拦截。失败发生时错误输出的形态也由源码决定cli_errors.py 实现了紧凑失败上报——它从完整 traceback 中只保留调用方自己 CAD 源码的帧通过is_first_party_source_file谓词区分模型代码与 stdlib、site-packages、运行时最多显示 6 帧_MAX_FRAMES 6并附源码行内容。这正是 SKILL.md 中展示的失败样式[scripts/gen] FAILED: ValueError: bad radius [scripts/gen] models/step/parts/widget.step.py:9 in gen_step [scripts/gen] return _profile(radius) [scripts/gen] re-run with --verbose for the full traceback其模块文档字符串解释了设计动机未捕获异常曾产生 62 行、4.2 KB 的 traceback唯一有用的一行异常本身在最后面。因此做“读失败输出”这一步时默认输出已经帮你过滤掉了运行时噪声只有当故障真的出在 cadgen 内部时才需要加--verbose查看完整 traceback。失败分类四几何无效或缺失可能原因未闭合的 sketchopen sketch减材轮廓落在目标之外厚度为零布尔操作失败把构造几何construction geometry当作导出几何。修复动作将意图成为面的轮廓闭合校验所有尺寸为正值意图为通孔through-cut时让减材刀具贯穿目标简化失败特征增量式重建。这里有一个值得记住的底层事实来自 inspection-and-validation.mdrefs --facts的ok字段只是“ref 全部可解析”的命令成功标志不构成几何有效性声明——五面的开口盒子会报ok: true法向反转的实体渲染出来是“世界上的一个洞”同样报ok: true。几何健全性问题要交给validate子命令它按 occurrence 报告invalidTopology、openShell、nonPositiveVolume、noSolid、selfIntersecting等失败并在任一 occurrence 失败时以非零退出码结束。文档还补充了两条细枝末节BRepCheck_Analyzer对反转实体会返回true所以拓扑有效性本身抓不住倒置实体只有体积的符号能抓到且体积按单个 solid 计量、从不聚合计——同一个 compound 里1000与-1000相加为零读 compound 总体积的检查什么都发现不了。失败分类五圆角或倒角失败可能原因半径/长度超出局部几何尺度选中的边包含极小或非预期边布尔操作生成了复杂边拓扑。修复动作减小半径/长度用更严格的条件过滤选中边把圆角放到建模后期应用按特征意图把边分组拆开处理。失败分类六比例或包围盒错误可能原因单位不一致把直径当成了半径拉伸方向或长度错误部件没有按假设居中直接导入的 STEP 使用了非预期单位。修复动作检查参数取值用 facts 和 planes 检查测量关键尺寸critical extents修正源码尺寸或导入处理逻辑。失败分类七特征缺失可能原因Mode.ADD/Mode.SUBTRACT用反特征轮廓不在目标内部盲孔切得不够深先前的操作改变了拓扑导致选择器失效。修复动作确认特征模式mode通孔加大切割长度检查拓扑或平面重新生成并测量/检查特征专属的 refs。失败分类八选择器脆弱可能原因用任意下标选择圆角或布尔之后拓扑已经变化相似的面/边无法区分。修复动作改为按轴、平面、位置、法向或经过检查的引用inspected reference选择使用refs --facts --planes --positioning重新发现稳定引用必要时添加构造基准construction datums或简化操作。失败分类九定位或关节失配可能原因原文为完整一段全部继承错误的零件局部原点或基准、AssemblyHelper的 fixed/moving 顺序颠倒、.connect_to()移动了错误的零件、关节轴反向、对称布置中的符号错误、参数变更后没有重算显式Location、或者本该在零件局部基准上定义却定义在世界坐标系中的关节。修复动作先检查refs --positioning再对相关选择器跑frame和align核对源码层AssemblyHelper的目标顺序、关节标签与joint_location定义应用 positioning.md 中 “Source-level positioning corrections” 列表里的最小源码修正从 Python 源码重新生成装配并重跑失败的检查。positioning.md是$cad技能中关于AssemblyHelper、build123d joints、显式Location变换与对齐验证的权威参考定位类问题应回到该文档执行。失败分类十CAD Viewer 启动或链接失败可能原因Node/npm 不可用CAD Viewer 应用未构建或无法启动Viewer URL 的路径不是项目模型目录的绝对路径返回的链接缺少?file或其file值不是相对于该目录的路径。修复动作把每个链接重构为viewer-originabsolute-model-directory?filepath relative to it的形式每个请求的文件返回一个文档化规范的 Viewer 链接若仍无法解决报告启动失败转而依赖 CLI facts/measurements 加快照来完成验证而不是静默省略交接。失败分类十一scripts/snapshot失败可能原因目标输入路径错误、缺失或不是 STEP/STP 文件/同干名same-stemPython 生成器相邻的 CAD Viewer GLB/topology 产物缺失渲染参数flags非法。修复动作先生成 STEP再对主.step/.stp产物做快照只用更简单的受支持快照任务重试从单个view输出开始再考虑 wireframe 显示或section模式选择与 packet 大小按 snapshot-review.md 执行。修复后的回归验证inspect diff当修复可能影响了无关几何时用 diff 对比修复前后的产物python scripts/inspect diff path/to/before.step path/to/after.step --planes这与 SKILL.md 的 Non-negotiables 保持一致不要把git status/git diff或文件体积变化当作大型 STEP/STP、GLB/topology、STL、3MF 产物的 CAD 对比手段而应比较源码变更、scripts/inspect摘要、快照或生成的拓扑输出。无法修复时如何报告如果某个检查在当前环境中无法修复不要隐瞒按 repair-loop.md 的模板如实上报- what failed 什么失败了 - what was tried 尝试过什么 - which artifact is still usable哪个产物仍然可用 - which validation claims cannot be made哪些验证结论无法成立 - what the next source-level correction should be下一步应有的源码级修正这对应 SKILL.md 的一条硬规则“Report only checks that actually ran or are directly supported by tool output.”——只报告真实执行过、或有工具输出直接支撑的检查。小结这套闭环的源码级落点把 repair-loop 文档的流程映射到仓库实现可以形成一张可检索的索引修复环节仓库中的落点读失败输出cli_errors.py 的紧凑帧过滤与--verbose完整 traceback目标/命令合法性前置拦截gen/cli.py 的_validate_python_targets与--write参数几何健全性判定scripts/inspect validateinvalidTopology/openShell/nonPositiveVolume/noSolid/selfIntersecting见 inspection-and-validation.md引用重新发现scripts/inspect refs --facts --planes --positioning定位修正权威依据positioning.md快照策略与 packet 大小snapshot-review.md无关几何回归检查scripts/inspect diff ... --planes掌握这条闭环后面对 text-to-cad 工作流中的任意一类失败你都能先分类、再最小修改、然后按同一套工具链验证并如实报告而不是在“重新生成一遍试试”中反复消耗时间。【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考