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

429 lines
22 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.
"""claims 是 IR 里可选的一组机器可核验的结构化断言(见 prompt_builder.py 里的schema说明)。
这是⑤核验层的核心机制:过去一整天的bug(V导向块的孔被后续union填平、轴承孔方向理解反、
球环机构假装能转其实焊死、精确数字没有真被采纳)全部是靠人工写一次性Python脚本、对着
FreeCAD截图或bounding box肉眼核对才发现的——这种发现方式不可复制、不可规模化。claims把
"GPT自己在assumptions里声称做到了什么"变成"执行器在导出文件前自动核对是否真的做到",
核对不通过就带着具体原因打回现有的重试循环,跟is_valid/solid_count检查走的是同一条路。
每类claim复用的都是这个项目里已经反复验证过的几种探针手法,不是新发明的:
- hole: 探针圆柱沿声明的轴向贯穿整个包围盒,检查探针区域内是否真的没有材料——
对应"孔被后续boolean_combine(union)意外填平"这个真实踩过的坑。
- axis_direction: 直接核对某个操作自己记录在trace里的axis参数,而不是靠猜包围盒
长轴方向——精确,且信息本来就有,不需要额外几何推断。
- real_overlap / no_overlap: 分别对应"贴合不算真连接,必须有真实体积重叠"和
"间隙嵌套的独立实体不能被意外焊死"这两条已经写进提示词的规则,现在能自动核对。
- dimension: 核对某个操作产出的实体在某个轴向上的实际尺寸是否符合声明——用来验证
用户给的精确数字有没有真的被采纳,而不是被"合理猜测"覆盖掉。
"""
_NON_NUMERIC_FIELDS = {"type", "target", "axis", "expected_axis", "id_a", "id_b"}
def _coerce_numeric_strings(value):
"""大模型偶尔会把claim里的数字写成带引号的字符串(比如"40"而不是40)——
跟executor.py里对能力参数做的处理是同一个坑,同一个修法:值本身是对的,
不该因为JSON输出的类型小瑕疵,就让claim检查器深处的build123d/OCCT构造函数
直接崩出一个"must be real number, not str"这种跟claim内容本身毫无关系的
原始异常,把整个agent会话都带崩、被迫退回一次性生成流程。"""
if isinstance(value, str):
try:
return float(value)
except ValueError:
return value
if isinstance(value, list):
return [_coerce_numeric_strings(v) for v in value]
return value
def _coerce_claim(claim: dict) -> dict:
return {
k: (v if k in _NON_NUMERIC_FIELDS else _coerce_numeric_strings(v))
for k, v in claim.items()
}
def _get_shape(context: dict, op_id: str):
if op_id not in context:
raise KeyError(f"claims引用的id '{op_id}' 在IR中不存在")
return context[op_id]
def _get_params(trace: list, op_id: str) -> dict:
for entry in trace:
if entry["id"] == op_id:
return entry.get("params", {})
return {}
def _overlap_volume(a, b) -> float:
inter = a & b
if inter is None:
return 0.0
return inter.volume
def _check_hole(claim: dict, context: dict) -> list:
from build123d import Circle, Plane, Pos, extrude
from .inspection import matching_hole_surface
target_id = claim.get("target")
if not target_id:
return ["CLAIM_ERROR(hole): 缺少target字段,不知道要在哪个实体上核对孔"]
target = _get_shape(context, target_id)
bbox = target.bounding_box()
axis = claim["axis"]
diameter = claim["diameter"]
if axis not in ("X", "Y", "Z") or diameter <= 0:
return ["CLAIM_ERROR(hole): 轴向或孔径不合法"]
tolerance = claim.get("tolerance_mm", max(0.05, diameter * 0.005))
if tolerance <= 0 or tolerance >= diameter / 2:
return ["CLAIM_ERROR(hole): 孔径容差不合法"]
probe_r = max(diameter / 2 - tolerance / 2, diameter * 0.49)
x, y, z = claim.get("x", 0), claim.get("y", 0), claim.get("z", 0)
if not matching_hole_surface(target, axis, diameter, [x, y, z], tolerance):
return [f"CLAIM_FAILED(hole@{target_id}): 未找到指定位置、方向与直径的圆柱孔壁;"
"空旷区域或更大的开口不等于指定孔径的孔"]
# 探针构造方式跟 hole_through_axis.py 完全一致,保证轴向语义不会理解反
if axis == "X":
length = bbox.size.X + 20
start = bbox.min.X - 10
plane = Plane(origin=(start, y, z), x_dir=(0, 1, 0), z_dir=(1, 0, 0))
probe = extrude(plane * Circle(probe_r), amount=length)
elif axis == "Y":
length = bbox.size.Y + 20
start = bbox.min.Y - 10
plane = Plane(origin=(x, start, z), x_dir=(1, 0, 0), z_dir=(0, 1, 0))
probe = extrude(plane * Circle(probe_r), amount=length)
else: # Z
length = bbox.size.Z + 20
start = bbox.min.Z - 10
plane = Plane.XY.offset(start)
probe = extrude(plane * (Pos(x, y, 0) * Circle(probe_r)), amount=length)
blocked_volume = _overlap_volume(probe, target)
if blocked_volume > max(1e-6, probe.volume * 1e-8):
return [
f"CLAIM_FAILED(hole@{target_id}): 声明位置(x={x},y={y},z={z})沿{axis}轴、"
f"直径{diameter}mm的孔实际没有打穿——探测到约{blocked_volume:.1f}mm^3的残留材料"
f"挡住了孔,很可能是被后续某个boolean_combine(union)重新填平了,请检查主体结构"
f"的footprint有没有盖住这个孔的位置,或者孔本身的坐标/轴向是否写错了"
]
return []
def _check_axis_direction(claim: dict, trace: list) -> list:
target_id = claim["target"]
expected = claim["expected_axis"]
params = _get_params(trace, target_id)
actual = params.get("axis")
if actual is None:
from build123d import Vector
op = next((e.get("op", "").removeprefix("op_") for e in trace if e["id"] == target_id), "")
field = {"cut_openings": "normal", "place_on_plane": "normal", "extrude": "direction"}.get(op)
vector = params.get(field) if field else None
if vector is not None:
direction = Vector(vector)
if direction.length > 1e-9:
direction = direction.normalized()
component = "XYZ".index(expected)
if abs(abs(tuple(direction)[component])-1) < 1e-7:
return []
return [f"CLAIM_FAILED(axis_direction@{target_id}): 操作方向{list(direction)}不平行于{expected}轴"]
return [f"CLAIM_ERROR(axis_direction@{target_id}): 该操作没有可核对的axis/normal/direction参数;仅检查对应操作的构造方向。请用inspect_geometry测实体,孔用hole声明。"]
if actual != expected:
return [
f"CLAIM_FAILED(axis_direction@{target_id}): 声明这里的轴向应该是{expected},"
f"但实际操作里用的是{actual}轴,方向理解反了或者写错了"
]
return []
def _check_real_overlap(claim: dict, context: dict) -> list:
id_a, id_b = claim["id_a"], claim["id_b"]
min_overlap = claim.get("min_overlap_mm3", 1.0)
overlap = _overlap_volume(_get_shape(context, id_a), _get_shape(context, id_b))
if overlap < min_overlap:
return [
f"CLAIM_FAILED(real_overlap {id_a}+{id_b}): 声明这两部分需要真实体积重叠(焊死关系),"
f"实际重叠体积只有{overlap:.2f}mm^3(要求>={min_overlap}mm^3)——很可能只是表面贴合、"
f"恰好相切,没有真正嵌入几毫米,union不会把它们焊成一体"
]
return []
def _check_no_overlap(claim: dict, context: dict) -> list:
id_a, id_b = claim["id_a"], claim["id_b"]
max_overlap = claim.get("max_overlap_mm3", 0.5)
overlap = _overlap_volume(_get_shape(context, id_a), _get_shape(context, id_b))
if overlap > max_overlap:
return [
f"CLAIM_FAILED(no_overlap {id_a}+{id_b}): 声明这两部分需要保持独立、互不融合"
f"(间隙/可动关系),实际重叠体积达到{overlap:.2f}mm^3(要求<={max_overlap}mm^3)——"
f"间隙留得不够,union后会被意外焊死,失去相对运动的能力"
]
return []
def _check_dimension(claim: dict, context: dict) -> list:
target_id = claim["target"]
axis = claim["axis"]
expected = claim["expected_mm"]
tol = claim.get("tolerance_mm", 0.5)
bbox = _get_shape(context, target_id).bounding_box()
actual = {"X": bbox.size.X, "Y": bbox.size.Y, "Z": bbox.size.Z}[axis]
if abs(actual - expected) > tol:
return [
f"CLAIM_FAILED(dimension@{target_id}.{axis}): 声明尺寸应为{expected}mm(容差±{tol}mm),"
f"实际测得{actual:.2f}mm,跟声明的数值对不上,请检查参数是否正确传递"
]
return []
def _check_arc(claim: dict, context: dict) -> list:
"""核对目标实体上是否存在一条圆弧边,圆心落在声明的位置附近、半径符合声明——
对应折弯圆角/倒角这类"声称做了个R几的圆角"的场景。用弧长/半径反推圆心角,
可选进一步核对角度(比如声明这是一个精确90°的折弯,不是随便一个圆角)。"""
import math
from build123d import GeomType
target_id = claim["target"]
shape = _get_shape(context, target_id)
near = claim["near"]
expected_radius = claim["radius"]
tol = claim.get("tolerance_mm", 0.2)
angle_deg = claim.get("angle_deg")
angle_tol = claim.get("angle_tolerance_deg", 1.0)
near_xyz = (near + [0, 0, 0])[:3] if len(near) < 3 else near[:3]
candidates = []
for e in shape.edges():
if e.geom_type != GeomType.CIRCLE:
continue
c = e.arc_center
dist = math.dist((c.X, c.Y, c.Z), near_xyz)
if dist <= tol + 1.0 and abs(e.radius - expected_radius) <= tol:
candidates.append(e)
if not candidates:
return [
f"CLAIM_FAILED(arc@{target_id}): 声明位置{near}附近应该有一条半径{expected_radius}mm"
f"(容差±{tol}mm)的圆弧边,实际没有找到匹配的边——检查折弯/圆角是否真的做出来了,"
f"或者位置/半径参数是否正确"
]
if angle_deg is not None:
for e in candidates:
actual_angle = math.degrees(e.length / e.radius)
if abs(actual_angle - angle_deg) <= angle_tol:
return []
found = [round(math.degrees(e.length / e.radius), 1) for e in candidates]
return [
f"CLAIM_FAILED(arc@{target_id}): 位置{near}附近找到半径匹配的圆弧,但角度不对——"
f"声明应为{angle_deg}°(容差±{angle_tol}°),实际测得{found}"
]
return []
def _check_opening(claim: dict, context: dict) -> list:
"""核对一个孔/槽这类切除特征的真实开口尺寸和中心位置——跟hole只查"通不通"不同,
这个进一步核对开口本身的形状尺寸(比如长圆槽的长度/宽度)和中心坐标是否精确符合
声明,而不是只要"有个洞"就算数。做法:在声明位置放一个明显比预期开口大的探针,
探针减去实体得到的就是真实的镂空区域,量它的包围盒和中心即可。"""
from build123d import Align, Box, Circle, Plane, Pos, extrude
target_id = claim["target"]
shape = _get_shape(context, target_id)
axis = claim["axis"]
x, y, z = claim.get("x", 0), claim.get("y", 0), claim.get("z", 0)
probe_radius = claim["probe_radius"]
tol = claim.get("tolerance_mm", 0.3)
bbox = shape.bounding_box()
if axis == "X":
length = bbox.size.X + 20
start = bbox.min.X - 10
plane = Plane(origin=(start, y, z), x_dir=(0, 1, 0), z_dir=(1, 0, 0))
probe = extrude(plane * Circle(probe_radius), amount=length)
in_plane_axes = ("Y", "Z")
elif axis == "Y":
length = bbox.size.Y + 20
start = bbox.min.Y - 10
plane = Plane(origin=(x, start, z), x_dir=(1, 0, 0), z_dir=(0, 1, 0))
probe = extrude(plane * Circle(probe_radius), amount=length)
in_plane_axes = ("X", "Z")
else:
length = bbox.size.Z + 20
start = bbox.min.Z - 10
plane = Plane.XY.offset(start)
probe = extrude(plane * (Pos(x, y, 0) * Circle(probe_radius)), amount=length)
in_plane_axes = ("X", "Y")
# 【重要,真实踩过的坑】探针为了保证真能贯穿整个实体,长度故意留了20mm余量,
# 两端会伸到材料外面很远;而且这个"镂空区域"在贯穿方向上是连通的一整片(从孔
# 里穿出去之后就是零件外部的空旷区域,没有"天花板"挡住),直接拿"探针减实体"
# 的结果去量包围盒,贯穿方向的尺寸会被探针自己的余量撑得很大,不是真实开口
# 的深度。正确做法:先算"探针 与 实体 的交集",这部分就是探针范围内真实存在
# 的材料,材料本身在贯穿方向上的实际范围(比如板厚)才是应该拿来限制镂空区域的
# 边界——而不是拿零件整体的包围盒或者探针自己的余量来限制。
material_in_probe = probe & shape
if material_in_probe is None or not material_in_probe.solids():
return [
f"CLAIM_FAILED(opening@{target_id}): 声明位置(x={x},y={y},z={z})附近的探针范围内"
f"完全没有材料——这里要么本来就不该是实体的一部分,要么坐标写错了,无法核对开口"
]
mbox = material_in_probe.bounding_box()
trim_box = Pos(mbox.min.X, mbox.min.Y, mbox.min.Z) * Box(
mbox.size.X, mbox.size.Y, mbox.size.Z, align=(Align.MIN, Align.MIN, Align.MIN)
)
void = (probe - shape) & trim_box
if void is None or not void.solids():
return [
f"CLAIM_FAILED(opening@{target_id}): 声明位置(x={x},y={y},z={z})附近完全没有镂空区域,"
f"跟声明的开口对不上——检查这个特征是不是真的被后续操作填平了"
]
vbox = void.bounding_box()
size_map = {"X": vbox.size.X, "Y": vbox.size.Y, "Z": vbox.size.Z}
center_map = {"X": (vbox.min.X + vbox.max.X) / 2, "Y": (vbox.min.Y + vbox.max.Y) / 2, "Z": (vbox.min.Z + vbox.max.Z) / 2}
a1, a2 = in_plane_axes
violations = []
if "expected_length" in claim:
dims = sorted([size_map[a1], size_map[a2]], reverse=True)
actual_len = dims[0]
if abs(actual_len - claim["expected_length"]) > tol:
violations.append(
f"CLAIM_FAILED(opening@{target_id}.length): 声明开口长度{claim['expected_length']}mm"
f"(容差±{tol}mm),实际测得{actual_len:.2f}mm"
)
if "expected_width" in claim:
dims = sorted([size_map[a1], size_map[a2]])
actual_width = dims[0]
if abs(actual_width - claim["expected_width"]) > tol:
violations.append(
f"CLAIM_FAILED(opening@{target_id}.width): 声明开口宽度{claim['expected_width']}mm"
f"(容差±{tol}mm),实际测得{actual_width:.2f}mm"
)
if "expected_center" in claim:
ec = claim["expected_center"]
actual_center = (center_map[a1], center_map[a2])
for i, ax in enumerate((a1, a2)):
if abs(actual_center[i] - ec[i]) > tol:
violations.append(
f"CLAIM_FAILED(opening@{target_id}.center_{ax}): 声明开口中心{ax}坐标"
f"{ec[i]}mm(容差±{tol}mm),实际测得{actual_center[i]:.2f}mm"
)
return violations
_CHECKERS = {
"hole": lambda c, ctx, trace: _check_hole(c, ctx),
"axis_direction": lambda c, ctx, trace: _check_axis_direction(c, trace),
"real_overlap": lambda c, ctx, trace: _check_real_overlap(c, ctx),
"no_overlap": lambda c, ctx, trace: _check_no_overlap(c, ctx),
"dimension": lambda c, ctx, trace: _check_dimension(c, ctx),
"arc": lambda c, ctx, trace: _check_arc(c, ctx),
"opening": lambda c, ctx, trace: _check_opening(c, ctx),
}
# 每种claim类型的必填字段——生成层(尤其是多轮agent模式)偶尔会漏填字段,之前这种
# 情况统一被当成"引用了不存在的id"报出去,其实是两回事:一个是"claim本身写得不完整",
# 一个是"claim引用的id在当前IR里确实不存在",混在一起会让理解层误判问题出在哪、
# 多花好几轮才能改对。这里先显式检查必填字段是否齐全,齐全了才交给具体checker去跑,
# 报错信息因此能精确说"到底缺了哪个字段"还是"引用的哪个id不存在"。
_REQUIRED_FIELDS = {
"hole": ["target", "axis", "diameter"],
"axis_direction": ["target", "expected_axis"],
"real_overlap": ["id_a", "id_b"],
"no_overlap": ["id_a", "id_b"],
"dimension": ["target", "axis", "expected_mm"],
"arc": ["target", "near", "radius"],
"opening": ["target", "axis", "probe_radius"],
}
def claim_schema():
"""Expose exactly the checks understood by the executor to the generating model."""
number = {"type": "number"}
axis = {"type": "string", "enum": ["X", "Y", "Z"]}
coordinates = {key: number for key in ("x", "y", "z")}
fields = {
"hole": {"axis": axis, "diameter": number, "tolerance_mm": number, **coordinates},
"axis_direction": {"expected_axis": axis},
"real_overlap": {"id_a": {"type": "string"}, "id_b": {"type": "string"}, "min_overlap_mm3": number},
"no_overlap": {"id_a": {"type": "string"}, "id_b": {"type": "string"}, "max_overlap_mm3": number},
"dimension": {"axis": axis, "expected_mm": number, "tolerance_mm": number},
"arc": {"near": {"type": "array", "items": number, "minItems": 3, "maxItems": 3},
"radius": number, "angle_deg": number, "tolerance_mm": number, "angle_tolerance_deg": number},
"opening": {"axis": axis, "probe_radius": number, **coordinates, "tolerance_mm": number,
"expected_length": number, "expected_width": number,
"expected_center": {"type": "array", "items": number, "minItems": 2, "maxItems": 2}},
}
descriptions = {
"hole": "最终实体的真实圆柱孔壁及贯通检查。不能用于螺纹或矩形槽。",
"axis_direction": "仅核对指定操作trace中的axis参数,或cut_openings/place_on_plane的normal、extrude的显式direction向量。target必须是这些操作,不能用来判断布尔结果的同轴性、螺纹旋向或导程;这些请用 inspect_geometry。",
"real_overlap": "两个实体的真实相交体积。",
"no_overlap": "两个实体的最大允许相交体积。",
"dimension": "指定实体沿世界轴的总包络尺寸,不是局部特征尺寸。",
"arc": "指定圆心附近的圆弧半径及可选圆心角。",
"opening": "贯通开口的局部尺寸与平面中心;复杂多层壁请用 inspect_geometry 及材料点探测。",
}
variants = []
for kind, required in _REQUIRED_FIELDS.items():
properties = {"type": {"type": "string", "enum": [kind]}, **fields[kind]}
if "target" in required:
properties["target"] = {"type": "string"}
variants.append({"type": "object", "description": descriptions[kind], "properties": properties,
"required": ["type", *required], "additionalProperties": False})
return {"type": "array", "items": {"anyOf": variants},
"description": "可选机器断言,只能使用列出的类型和字段。无适用检查可传空数组,冻结需求与独立几何评审仍照常执行。螺纹导程、牙型等请先用 inspect_geometry 实测,不要虚构 claim 类型。"}
def check_claims(claims: list, context: dict, trace: list) -> list:
"""核对IR里声明的所有claims,返回违反的claim描述列表(空列表=全部通过)。"""
from .validation import finite
if not isinstance(claims, list):
return ["CLAIM_ERROR: claims 必须为数组"]
violations = []
for claim in claims:
if not isinstance(claim, dict):
violations.append("CLAIM_ERROR: 每个 claim 必须为对象")
continue
ctype = claim.get("type")
checker = _CHECKERS.get(ctype)
if checker is None:
violations.append(f"CLAIM_ERROR: 未知的claim类型 '{ctype}',可选值 {list(_CHECKERS)}")
continue
missing = [f for f in _REQUIRED_FIELDS[ctype] if f not in claim]
if missing:
violations.append(
f"CLAIM_ERROR: '{ctype}'类型的claim缺少必填字段 {missing},"
f"完整必填字段是 {_REQUIRED_FIELDS[ctype]},当前claim内容: {claim}"
)
continue
claim = _coerce_claim(claim)
if not finite(claim):
violations.append("CLAIM_ERROR: 数值必须有限,不能使用 NaN/Infinity")
continue
try:
violations.extend(checker(claim, context, trace))
except KeyError as e:
violations.append(f"CLAIM_ERROR: claim引用了不存在的id -> {e}")
except Exception as e: # noqa: BLE001 - 任何claim都不能把整个建模会话崩掉,
# 必须变成可读反馈交回给现有的重试循环,跟claim校验失败走同一条路
violations.append(
f"CLAIM_ERROR: 核对'{ctype}'类型的claim时出错({type(e).__name__}: {e}),"
f"当前claim内容: {claim},请检查字段的值是否合理(比如坐标/半径/直径是不是"
f"合法数字、引用的id是否拼写正确)"
)
return violations