Files
2026-09-24 10:40:57 +08:00

160 lines
7.2 KiB
Python
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.
"""每个操作执行完之后,无条件核对它自己契约里声明的postcondition。
为什么需要这一层(真实踩过的坑):
一整轮排查下来发现,我们最严重的几个bug都是同一个形状——操作"返回成功了,
但其实什么也没干":boolean_combine的cut切偏了没切到东西、shell抽壳选错了开口
面、union焊接的两块根本没接触。这些操作在OCCT层面都是合法的(减去一个不相交的
实体当然合法,结果就是原样返回),所以不报错、不警告,错误一路带到最终零件,
只有等人看渲染图才发现"槽怎么没了"。
契约里其实一直写着每个能力该达成什么("体积应减小""体积应增加"……),48份全都写了,
但执行层从来没有执行过它——这些话只是给人看的。这个模块把它变成机器每一步都跑的
硬断言:方向错了(该减的反而增了)或者根本没变化(等于没干活),当场打回,带着能看懂
的原因交给理解层去改,而不是让它安静地混过去。
跟同类项目的区别也在这里:他们靠agent自己记得在代码里写检查(写不写全凭自觉),
我们是写进契约、执行器强制执行,agent想跳过都跳不掉。
设计原则:宁可漏报也不能自己崩。任何拿不到体积/面积的情况一律跳过检查,
这一层是安全网,不能反过来变成新的故障源。
"""
# "基本等于没变化"的判定阈值(mm^3)。真正的空操作变化量是0(或1e-9级的浮点噪声),
# 而再小的真实特征(比如0.3mm倒角)去除的体积也远大于这个数,所以这个阈值只会
# 命中真正什么都没干的操作,不会误伤小特征。
_NEGLIGIBLE_MM3 = 1e-4
# 刚体变换(平移/旋转)允许的相对体积漂移,只用于吸收浮点误差
_RIGID_REL_TOL = 1e-6
class PostconditionError(Exception):
"""操作执行完了,但没有达成它契约里声明的效果。"""
def _volume(shape):
"""拿不到体积就返回None,交给调用方跳过检查——绝不抛异常。"""
try:
v = shape.volume
except Exception: # noqa: BLE001
return None
if not isinstance(v, (int, float)):
return None
return float(v)
def _area(shape):
try:
a = shape.area
except Exception: # noqa: BLE001
return None
if not isinstance(a, (int, float)):
return None
return float(a)
# 契约里 postcondition_check 允许的全部取值——同时是执行器和回归测试的单一事实来源。
# 新增一种检查类型时,这里和下面的分支要一起加,测试会自动覆盖到。
SUPPORTED_CHECKS = frozenset({
"none",
"sketch_area_positive",
"volume_positive",
"geometry_changed",
"volume_decrease",
"volume_increase",
"volume_unchanged",
})
def check_postcondition(op_name: str, check: str, target, result) -> None:
"""按契约声明的类型核对这次操作的结果。不通过则抛PostconditionError。"""
if not check or check == "none" or result is None:
return
# 取值拼错时必须立刻报出来。否则这条契约会被静默跳过、该能力从此完全不受核对——
# 这正是这套机制本身要消灭的那类"安静地什么都没做",不能让它出现在自己身上。
if check not in SUPPORTED_CHECKS:
raise PostconditionError(
f"UNKNOWN_POSTCONDITION_CHECK({op_name}): 契约里声明的 postcondition_check="
f"'{check}' 不是合法取值,合法取值为 {sorted(SUPPORTED_CHECKS)}"
)
if check == "sketch_area_positive":
area = _area(result)
if area is not None and area <= 0:
raise PostconditionError(
f"POSTCONDITION_FAILED({op_name}): 契约声明这一步应该生成一个二维草图,"
f"但结果面积为{area:.6f},等于没有生成有效轮廓——检查尺寸参数是不是"
f"给了0或者互相矛盾的值"
)
return
if check == "volume_positive":
vol = _volume(result)
if vol is not None and vol <= 0:
raise PostconditionError(
f"POSTCONDITION_FAILED({op_name}): 契约声明这一步应该生成一个体积大于0的"
f"实体,实际体积为{vol:.6f}——检查尺寸/拉伸距离等参数是不是给了0或者负值"
)
return
# 剩下三种都需要跟target比较
if target is None:
return
before = _volume(target)
after = _volume(result)
if before is None or after is None:
return
delta = after - before
if check == "geometry_changed":
if not result.is_valid:
raise PostconditionError(f"INVALID_GEOMETRY({op_name}): 圆角结果无效")
if abs(delta) <= _NEGLIGIBLE_MM3:
removed = target - result
added = result - target
change = (removed.volume if removed is not None else 0) + (added.volume if added is not None else 0)
if change <= 1e-7:
raise PostconditionError(f"NO_EFFECT({op_name}): 几何没有变化")
return
if check == "volume_decrease":
if delta > _NEGLIGIBLE_MM3:
raise PostconditionError(
f"POSTCONDITION_FAILED({op_name}): 契约声明这一步应该去除材料、体积减小,"
f"实际体积却从{before:.3f}增加到了{after:.3f}(多了{delta:.3f}mm^3)——"
f"方向反了,检查是不是把切除做成了合并,或者参数传错了"
)
if abs(delta) <= _NEGLIGIBLE_MM3:
raise PostconditionError(
f"POSTCONDITION_FAILED({op_name}): 契约声明这一步应该去除材料,但体积"
f"几乎没有变化({before:.3f} -> {after:.3f}),等于这一步什么都没做——"
f"最常见的原因是特征的位置/尺寸算错了,压根没落在target的实体范围内,"
f"检查坐标和方向,确认它真的穿进了材料里"
)
return
if check == "volume_increase":
if delta < -_NEGLIGIBLE_MM3:
raise PostconditionError(
f"POSTCONDITION_FAILED({op_name}): 契约声明这一步应该增加材料、体积变大,"
f"实际体积却从{before:.3f}减少到了{after:.3f}——方向反了,检查参数"
)
if abs(delta) <= _NEGLIGIBLE_MM3:
raise PostconditionError(
f"POSTCONDITION_FAILED({op_name}): 契约声明这一步应该增加材料,但体积"
f"几乎没有变化({before:.3f} -> {after:.3f}),等于这一步什么都没做——"
f"检查新增部分的位置/尺寸是不是算错了,或者完全被已有实体包住了"
)
return
if check == "volume_unchanged":
tol = max(abs(before) * _RIGID_REL_TOL, _NEGLIGIBLE_MM3)
if abs(delta) > tol:
raise PostconditionError(
f"POSTCONDITION_FAILED({op_name}): 平移/旋转属于刚体变换,形状和体积都"
f"不应该变化,实际体积从{before:.3f}变成了{after:.3f}——说明这一步不只是"
f"移动了物体,几何本身被改动了,这不正常"
)
return