feat(review): 几何干涉检查 find_collisions（BVH 粗筛 + 容器过滤）

C++（cad_mcp_plugins）：
- 新增 bvh.h：header-only 2D BVH（质心中位分割，叶<=4，SelfPairs 交叉对枚举）
- 新增 find_collisions.cpp：粗筛 AABB 相交实体对，附重叠盒 + 逐轴重叠比 ratio
  （= 逐轴重叠长/较短长 之积，退化轴取 1.0），按 ratio 降序 + 分页；
  narrow=true 只对返回页跑 intersectWith 细筛（附 exact）
- 容器过滤（关键）：图框块/分区边界会与一切相交，用重叠【度】判定
  deg >= max(exclude_container_deg=8, exclude_container_frac=0.25 * 其他实体数)，
  与图幅/缩放无关；被剔除者在 excluded_containers 里如实报告
  （初版用面积判据对多图框并排失效：3 框只占并集 27/13/7% 全部漏过，
   全模型 163 对噪声；改度判据后图框 deg=35/25/23 vs 其余 deg<=3，分离干净）
- cmakelists.txt + 两个 mcp_config.json 注册（28 工具）

agent 侧（Python）：
- cad_tools.READ_ONLY_TOOLS += find_collisions（受控子循环可调用）
- checks.check_collisions + run_deterministic_checks（受 CHECK_COLLISIONS 开关，默认关）
- config += CHECK_COLLISIONS=False / COLLISION_MIN_OVERLAP=0.5
- checklist.py / review_checklist.json += 「干涉/碰撞」类别（high）+ 提示词协议
  （先 find_collisions 拿候选 → inspect_region 目视确认；AABB 相交 != 真干涉）

验证：
- verify_collisions.py 17/17 PASS：全模型候选 163→80（全部 ratio=0.000），
  min_overlap=0.5 → 0 对；逐图框 0 对；narrow top-5 中 4 条 exact=true；
  --inject 注入深重叠矩形报出 ratio=0.902 并清理 2/2
- pytest 355 passed（新增 12 项）
- 端到端：LLM 主动调用 find_collisions{min_overlap:0.2,narrow:true,window:<图框>}，未误报

tests/fakes.py

@@ -204,6 +204,7 @@ STANDARD_TOOLS = [
     tool_schema("get_entity_detail", "实体详情"),
     tool_schema("find_duplicate_entities", "重复实体"),
     tool_schema("find_zero_length", "零长度实体"),
+    tool_schema("find_collisions", "干涉候选"),
     tool_schema("add_leader_annotation", "添加引线批注"),
     tool_schema("highlight_entities", "高亮实体"),
     tool_schema("delete_entities", "删除实体"),

tests/test_cad_tools.py

@@ -1,6 +1,6 @@
 """`dwg_review.cad_tools` 单元测试。"""
 
-from dwg_review.cad_tools import CadTools, is_write_tool
+from dwg_review.cad_tools import READ_ONLY_TOOLS, CadTools, is_write_tool
 from dwg_review.mcp_client import result_json
 from tests.fakes import FakeMcpClient, ok_text, tool_schema
 
@@ -19,10 +19,15 @@ def test_write_exact_names_detected():
 
 
 def test_readonly_tools_are_not_write():
-    for name in ("query_entities", "get_text_content", "zoom_to_window", "find_zero_length"):
+    for name in ("query_entities", "get_text_content", "zoom_to_window",
+                 "find_zero_length", "find_collisions"):
         assert is_write_tool(name) is False
 
 
+def test_find_collisions_is_whitelisted():
+    assert "find_collisions" in READ_ONLY_TOOLS
+
+
 # ---------------------------------------------------------------------------
 #  注册表
 # ---------------------------------------------------------------------------

tests/test_checklist.py

@@ -76,6 +76,19 @@ def test_build_system_prompt_instructs_inspect_region():
     assert "不需要判断截图够不够清楚" in prompt
 
 
+def test_build_system_prompt_mentions_collision_tool():
+    prompt = build_system_prompt(DEFAULT_CHECKLIST, allow_tools=True)
+    # 干涉排查入口：find_collisions 粗筛候选 + 强调 AABB 相交 ≠ 真干涉
+    assert "find_collisions" in prompt
+    assert "包围盒相交" in prompt
+    assert "不等于真干涉" in prompt
+
+
+def test_default_checklist_has_collision_category():
+    titles = [c["title"] for c in DEFAULT_CHECKLIST["categories"]]
+    assert "干涉/碰撞" in titles
+
+
 def test_build_system_prompt_requires_structured_json_output():
     # allow_tools=False 以隔离「工具提示块」里的「只读」字样
     prompt = build_system_prompt(DEFAULT_CHECKLIST, allow_tools=False)

tests/test_checks.py

@@ -2,6 +2,7 @@
 
 from dwg_review import checks
 from dwg_review.checks import (
+    check_collisions,
     check_duplicate_entities,
     check_zero_length,
     derive_from_evidence,
@@ -127,6 +128,79 @@ def test_duplicate_swallows_tool_error():
     assert any("find_duplicate_entities 失败" in line for line in logs)
 
 
+# ---------------------------------------------------------------------------
+#  check_collisions
+# ---------------------------------------------------------------------------
+def _collision_item(a="A1", b="B1", ratio=0.8, same_layer=True):
+    return {
+        "a": {"handle": a, "type": "LINE", "layer": "0", "bbox": {}},
+        "b": {"handle": b, "type": "LWPOLYLINE", "layer": "0", "bbox": {}},
+        "overlap": {"bbox": {}, "width": 1.0, "height": 1.0, "area": 1.0, "ratio": ratio},
+        "same_layer": same_layer,
+        "same_type": False,
+    }
+
+
+def test_collisions_turn_items_into_issues():
+    client = FakeMcpClient(responses={"find_collisions": ok_text({
+        "total": 2, "returned": 2, "offset": 0, "entity_count": 10,
+        "items": [_collision_item("A1", "B1", 0.9), _collision_item("A2", "B2", 0.6)],
+    })})
+    ctx = make_ctx(client=client)
+    issues = check_collisions(ctx, WINDOW, min_overlap=0.5, limit=200, log=QUIET)
+    assert [i["handles"] for i in issues] == [["A1", "B1"], ["A2", "B2"]]
+    assert all(i["category"] == "干涉" and i["severity"] == "medium" for i in issues)
+    assert all(i["handle"] == i["handles"][0] for i in issues)
+    assert "0.90" in issues[0]["message"]
+
+
+def test_collisions_skips_items_missing_handles():
+    client = FakeMcpClient(responses={"find_collisions": ok_text({
+        "items": [
+            {"a": {"handle": "A1"}, "b": {}},
+            {"a": {}, "b": {"handle": "B1"}},
+            _collision_item("A2", "B2"),
+        ],
+    })})
+    ctx = make_ctx(client=client)
+    issues = check_collisions(ctx, WINDOW, min_overlap=0.5, limit=200, log=QUIET)
+    assert [i["handles"] for i in issues] == [["A2", "B2"]]
+
+
+def test_collisions_tolerates_missing_ratio():
+    client = FakeMcpClient(responses={"find_collisions": ok_text({
+        "items": [{"a": {"handle": "A1"}, "b": {"handle": "B1"}, "overlap": {}}],
+    })})
+    ctx = make_ctx(client=client)
+    issues = check_collisions(ctx, WINDOW, min_overlap=0.5, limit=200, log=QUIET)
+    assert len(issues) == 1
+    assert "重叠比 ?" in issues[0]["message"]
+
+
+def test_collisions_passes_params():
+    client = FakeMcpClient(responses={"find_collisions": ok_text({"items": []})})
+    ctx = make_ctx(client=client)
+    check_collisions(ctx, WINDOW, min_overlap=0.75, limit=33, log=QUIET)
+    assert client.arguments_of("find_collisions") == {
+        "window": WINDOW, "min_overlap": 0.75, "limit": 33,
+    }
+
+
+def test_collisions_swallows_tool_error():
+    logs = []
+    client = FakeMcpClient(responses={"find_collisions": McpToolError("炸了")})
+    ctx = make_ctx(client=client)
+    assert check_collisions(ctx, WINDOW, min_overlap=0.5, limit=200, log=logs.append) == []
+    assert any("find_collisions 失败" in line for line in logs)
+
+
+def test_collisions_tolerates_non_dict_envelope():
+    client = FakeMcpClient(responses={"find_collisions": ok_text("oops")})
+    ctx = make_ctx(client=client)
+    assert check_collisions(ctx, WINDOW, min_overlap=0.5, limit=200, log=QUIET) == []
+
+
+
 # ---------------------------------------------------------------------------
 #  derive_from_evidence
 # ---------------------------------------------------------------------------
@@ -171,6 +245,7 @@ def build_ctx():
         "find_zero_length": ok_text({"items": [{"handle": "Z1", "type": "LINE", "length": 0.0}]}),
         "find_duplicate_entities": ok_text({"groups": [
             {"type": "LINE", "handles": ["D1", "D2"]}]}),
+        "find_collisions": ok_text({"items": [_collision_item("C1", "C2", 0.9)]}),
     })
     return make_ctx(client=client)
 
@@ -210,3 +285,22 @@ def test_run_respects_unclosed_switch(monkeypatch):
     ctx = build_ctx()
     ev = make_evidence(polylines={"items": [{"handle": "P1", "vertex_count": 4, "closed": False}]})
     assert [i["handle"] for i in run_deterministic_checks(ctx, ev, log=QUIET)] == ["Z1", "D1"]
+
+
+def test_run_collisions_off_by_default(monkeypatch):
+    # 默认不跑干涉粗筛（AABB 相交噪声大），工具调用里不应出现 find_collisions
+    monkeypatch.setattr(checks.config, "CHECK_COLLISIONS", False)
+    ctx = build_ctx()
+    run_deterministic_checks(ctx, make_evidence(), log=QUIET)
+    assert "find_collisions" not in ctx.client.called_names()
+
+
+def test_run_collisions_when_enabled(monkeypatch):
+    monkeypatch.setattr(checks.config, "CHECK_COLLISIONS", True)
+    monkeypatch.setattr(checks.config, "COLLISION_MIN_OVERLAP", 0.6)
+    ctx = build_ctx()
+    issues = run_deterministic_checks(ctx, make_evidence(), log=QUIET)
+    by_handle = {i.get("handle"): i for i in issues}
+    assert "C1" in by_handle
+    assert by_handle["C1"]["category"] == "干涉"
+    assert ctx.client.arguments_of("find_collisions")["min_overlap"] == 0.6

tests/test_config.py

@@ -77,6 +77,8 @@ def test_credibility_constants_have_expected_types():
     assert isinstance(config.ZERO_LENGTH_TOLERANCE, float)
     assert isinstance(config.DUP_TOLERANCE, float)
     assert isinstance(config.DUP_GROUP_LIMIT, int)
+    assert isinstance(config.CHECK_COLLISIONS, bool)
+    assert isinstance(config.COLLISION_MIN_OVERLAP, float)
 
 
 def test_tiling_constants_have_expected_types():
@@ -132,6 +134,13 @@ def test_credibility_defaults_are_on():
     assert config.CHECK_UNCLOSED_POLYLINES is True
 
 
+def test_collision_defaults_are_sane():
+    # 干涉粗筛默认关闭（AABB 相交噪声大，改由 LLM 按需调用）；
+    # 阈值须落在 [0,1]（重叠比是乘积，可能为 0）
+    assert config.CHECK_COLLISIONS is False
+    assert 0.0 <= config.COLLISION_MIN_OVERLAP <= 1.0
+
+
 def test_checklist_path_resolves_relative_to_root():
     assert config.CHECKLIST_PATH.name == "review_checklist.json"
     assert config.CHECKLIST_PATH.parent == config.PROJECT_ROOT

tests/test_review.py

@@ -357,6 +357,7 @@ def test_review_tools_swap_raw_view_tools_for_inspect_region(monkeypatch):
     names = _tool_names(make_ctx())
     assert "inspect_region" in names
     assert "query_entities" in names            # 其余只读工具照旧
+    assert "find_collisions" in names           # 干涉粗筛对 LLM 可见
     assert "zoom_to_window" not in names
     assert "zoom_to_entity" not in names
     assert "get_viewport_screenshot" not in names