企业官网建设流程全解析

text-to-cad构建失败诊断手册：repair-loop修复循环的完整方法论

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

text-to-cad是一个面向 AI 智能体的 CAD/CAE/CAM 技能库，可以从自然语言生成 STEP 模型并自动完成检验、导出与评审。当模型构建失败时，项目内置了一套名为repair-loop（修复循环）的诊断方法论：读取失败输出 → 归类故障 → 最小化修改 → 重跑验证，直到问题闭环。本文带你完整掌握这套 CAD 构建失败诊断与修复方法。

为什么构建会失败：repair-loop 的六步闭环

text-to-cad 的 CAD 技能把工作流中的失败视为可管理的常规事件，而不是事故。repair-loop.md 定义了一个固定的六步循环：

1. 读取失败命令的输出—— 失败信息通常指向你自己生成器里的具体一行代码
2. 对故障归类—— 语法错误、几何无效、倒角失败、定位偏差……每类有固定解法
3. 做最小且有责任范围的修改—— 只改导致问题的源码片段
4. 重跑失败命令—— 不扩大改动面
5. 重跑所有受影响的验证检查—— 防止修复引入新问题
6. 报告剩余风险或刻意的偏差—— 诚实交代哪些验证无法断言

这套循环嵌在 SKILL.md 第 10 步"Repair and rerun"中：检查失败时，只改最小的责任源码段，重新生成，再重跑失败的验证。

高频故障类型与修复方法速查

repair-loop 文档把真实工程经验浓缩成了故障分类表，以下是新手最常踩的几类。

放样（Loft）失败："Failed to create valid loft"

多截面放样报错时，消息往往不告诉你坏在哪一站。修复顺序：

• 前缀二分法：用faces[:5]、[:10]、[:20]逐步扩大截面集合，定位断裂点，同时观察报告体积——"成功"但体积荒谬的放样已经失败了
• 相邻两两放样：若每对相邻截面都成功、全集却失败，问题几乎都是截面点数不一致，请保证每站固定采样数

两个隐蔽原因：某站截面实际断成两个闭合区域（Face.is_valid为 False 但不抛异常）；以及组件在某站不存在时采样被丢弃，导致点数逐站漂移。

布尔减除大曲面：进程"卡死"不返回

对一张大型 B 样条曲面做布尔减除，成本按刀具数量超线性增长。文档记录了实测数据：一张约 4900 控制点的曲面，1 个刀具 24 秒，4 个 70 秒，41 个 15 分钟跑不完，44 个跑了 7 小时仍未完成。

诊断特征：CPU 持续 100%，进度文件冻结在第一阶段。

正确的修法是不切：浅而纯装饰的凹槽根本不需要布尔。19 米模型渲染到 1920px 时 1px 约等于 10mm，4mm 的槽根本是亚像素级——它"看得见"全靠边缘线框。只给改变轮廓的开口保留布尔，其余用加法建模。

源码导入或语法失败

常见原因清单（新手重灾区）：

• Python 语法错误或缺少 import
• build123d 符号名写错
• 入口函数没有命名为gen_step()
• 函数外的代码产生了副作用

修复要点：让gen_step()返回可转 STEP 的形状；输出路径由 CLI 命令参数持有，不要写进gen_step()里。

几何无效或缺失

开放草图、减除轮廓落在目标之外、零厚度、布尔运算失败、把构造几何当导出几何——都会导致无效模型。解法：闭合轮廓、确认尺寸为正、通孔刀具要"穿过去"、对失败特征做简化后增量重建。

圆角/倒角失败

半径超出局部几何、选中了微小边、布尔后拓扑变得复杂。解法：缩小半径、更严格地筛选边集、把圆角挪到建模后期、按特征意图分组处理边。

比例或包围盒不对

单位不匹配、直径/半径混淆、拉伸方向错误、零件未居中、导入 STEP 自带意外单位。先核对参数值，再用refs --facts --planes --positioning检查事实与平面，量取关键尺寸后回改源码。

特征消失

Mode.ADD/Mode.SUBTRACT写反、特征轮廓不在目标内、盲孔太浅、前序操作后选择器失效。确认特征模式，加大贯穿切割长度，重新生成并测量特征专属引用。

选择器脆弱与定位偏差

任意索引选择、拓扑变更后索引漂移、相似面不可区分——解法是按轴、平面、位置、法向或检查过的引用选择，用refs --facts --planes --positioning重新发现稳定参考。

装配定位错误的来源更多：零件局部原点搞错、AssemblyHelper的 fixed/moving 顺序颠倒、关节轴反向、对称摆放符号错误等。修复路径是先查 positioning.md 中的修正清单，做最小源码纠正，再重新生成装配并重跑检查。

修复之后：用 diff 确认没有误伤

改动可能波及无关几何时，对修复前后的 STEP 做差异对比：

python scripts/inspect diff path/to/before.step path/to/after.step --planes

此外，text-to-cad 规定快照验证是强制的——任何新建或可见更新的主 STEP 都必须跑一次 scripts/snapshot 并人工评审输出，确定性检查通过不是跳过理由。策略细节见 snapshot-review.md。

修不动时：如何报告失败的修复

如果当前环境无法修复，不要假装通过。按 repair-loop.md 末尾的模板如实报告五件事：

• 什么失败了
• 尝试过什么
• 哪个工件仍然可用
• 哪些验证声明无法做出
• 下一步源码层面的修正应该是什么

配合 inspection-and-validation.md 中的验证报告结构（生成结果、包围盒、平面、定位、特征检查、视觉评审），你的最终交付将是诚实且可追溯的。

关键资料导航

掌握这六步循环和这张故障速查表，text-to-cad 的构建失败就从"黑盒报错"变成了有章可循的排障流程——这正是 agent 驱动 CAD 工作流最值钱的能力：不只是生成模型，更是自主修复模型。

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