Files
CADmind/backend/docs/thread-reliability-fix.md
2026-09-24 10:40:57 +08:00

54 lines
6.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 真实外螺纹与建模中断恢复
## 已确认的问题
2026-09-11 的端盖任务使用圆截面 `helical_sweep` 代替公制60°螺纹,并尝试螺距2、线材半径1/1.25/2.5等相邻圈相切或相交的参数。原能力契约错误地推荐用这一方式构造M系列螺纹。
独立几何实验还发现:在当前 build123d/OCCT 组合中,圆柱直接与多实体 IsoThread 用 `+` 融合可能返回有效的一实体结果,却丢掉圆柱芯体。显式展开 solids 后 fuse 能保留芯体。有效性检查必须结合材料和体积,不可仅检查 `is_valid`。
服务器任务被Linux OOM杀死;本地任务在开孔中以-9退出,同期macOS内存日志记录杀死异常占用的Python进程。没有对失控运算做无保护重放,因此不声称已经确定OCCT内部哪条指令导致全部内存增长。
## 通用修复
- 新增 `metric_thread`:采用已安装的 bd_warehouse IsoThread 构造真实60°单线外螺纹,含芯体,可开贯通内孔。使用逐实体融合,检查单实体、有效性与芯体体积。资料:https://bd-warehouse.readthedocs.io/en/latest/thread.html
- 删除圆线材螺旋模拟公制螺纹的契约和经验,拒绝相邻圈相交或接近相切的圆线材螺旋。
- 布尔融合显式展开实体;操作返回无效几何时不再写入会话上下文。
- 限深开孔不再为求深度而复制并变换整个目标BRep;贯穿开孔改用包围盒八角投影,支持任意法向。
- 批次成功、部分成功后失败及风险操作前保存真实STEP/STL检查点,原子发布完整目录,仅保留最新应急检查点。检查点不代表评审通过。
- 父进程每次轮询检查CAD进程树的内存。默认上限为物理内存35%与2GiB的较小值,可用 `CADMIND_WORKER_MEMORY_MB` 设置;macOS使用libproc物理足迹,含压缩内存,避免将虚拟地址预留误当内存使用;Linux使用RSS加交换内存。超限终止CAD进程树,优先恢复已提交的整件候选;没有候选时恢复有效检查点,避免后续临时测试组件替换完整进度。
- 区分已有实体与只有操作记录的中断提示。
## 验证
`tests/quality/test_thread_reliability.py` 覆盖M12×1.5、M60×2、左旋M20×1.5的贯通螺纹管、真实牙顶处实体/空气交替采样、芯体存在、四向矩形开窗、STEP回读、重叠线圈拒绝、Compound融合保留芯体、失败批次保存实体。
`tests/quality/test_isolated.py` 验证进程中断和内存保护恢复检查点,后续任务仍可执行。
这些是几何与执行验证,不是实物旋合、公差等级或加工认证。资源保护并不保证任意几何都能完成;保护触发时保留已经通过检查的实际进度,不用占位体冒充完成品。
## 真实 Luna 回归发现的核验接口问题
同一原始请求通过 `generate_quality` / `run_isolated` 调用 GPT-5.6 Luna,新能力生成了真实螺纹、八个矩形开窗、四个径向圆孔和中心套筒。但独立评审曾将“缺少当前实体测量”错误归为“外部资料缺失”,并因此暂停。
新增实际平面边界、沿世界Z轴螺旋边采样的导程/旋向,以及与螺旋边相连牙侧面的轴向截面角测量。长螺旋按弧长自适应采样,避免相位展开混叠。测量不回抄操作参数;轴线限制、导程与多线螺距的区别会明确返回。新增 measurement 评审类别,让模型补充材料点检查而不是询问用户或重建已有几何。
续跑还暴露 claims 工具原来只声明任意对象,模型会虚构 helix 类型或误用 axis_direction。现在生成和修复反馈都提供执行器支持的明确类型/字段契约;axis_direction 仅检查操作记录的 axis 参数,不能拿来核验整个零件的同轴性。可选断言格式问题不降低冻结需求和独立几何核验要求。
验证记录:原始失败任务 `quality_20260911_094935_94be905d`;同文新生成 `quality_20260911_101234_7b5d543d`(真实螺纹与全部开孔);续跑 `quality_20260911_102527_432ece2d` 的 candidate_002、candidate_003 分别通过主体与特征评审。输出模型和 API 事件保留在各自 output 目录,可核对 `model=gpt-5.6-luna` 与实际调用能力。
## 局部倒角与恢复兼容性
实测发现原 `chamfer_edge.outer_top/outer_bottom` 按最长边选择,在螺纹端部外缘分段时可能错误选择完整的内孔圆边。现改为水平端面的真实外环;新增 `by_index`,可用 `inspect_geometry(include_edges=true)` 的当前边索引处理局部孔口。索引在几何改变后必须重新获取。
`metric_thread.end_chamfer` 用45°外包络切削生成指定宽度的外牙引导倒角,避免将内孔倒角冒充外螺纹引导。M60×2、内孔52、引导0.5的独立测试测得两个锥面半径29.5–30、轴向宽0.5、半角45°,且内孔边的材料保留。
`inspect_geometry.conical_faces` 返回实际锥面位置、半角、轴向及径向跨度。圆孔边0.3倒角的选边/几何变化/锥面测量已有回归验证。旧任务某个操作在修订能力后不能重放时,保留可重放前缀和完整原始序列交给 Luna 修复,不在模型获得工具前直接中止;前缀不代表完成品。
## 网格与最终回归
真实外牙引导倒角产生极窄平面时,build123d 粗网格可能留下空三角化,随后 `tessellate` 访问 `NbNodes` 导致任务中止。新增统一网格检查:只对缺失三角化的面使用较细的 Delabella 三角化重试,仍失败则返回明确几何错误;不跳过面。渲染与STL导出共用此检查。M60×2引导倒角回归还检查二进制STL边使用次数,确认闭合、无非流形边。
完整重建成功后也保存独立STEP/STL检查点,再生成预览,避免显示失败丢失已完成实体。2026-09-11本地质量回归共134项通过;记录 `/tmp/cadmind-thread-final-tests-v4.log`。
局部倒角调用显式使用目标实体的 `chamfer` 方法,避免边对象缓存的 `topo_parent` 指向旧对象时发生 `NCollection_IndexedDataMap::FindFromKey`。重试统计区分不同目标和选边,但同一选边仅反复缩小半径仍受重复失败限制。新回归验证了旧父引用、不同选边与半径重复失败的区别;完整质量测试136项通过(`/tmp/cadmind-thread-final-tests-v5.log`)。