feat(review): agent 侧虚拟工具 inspect_region —— 按可读分辨率放大指定区域

解决三个缺口：① 放大没复用标定/瓦片数学（LLM 一次 zoom 只出一张，宽区域仍读不清）；
②「看清没」由 VLM 自评（易过度自信/幻觉）；③ 只能按 handle / 手算 bbox 指认，
图上看到但没 handle 的东西指认不了。

核心思路：把「放大」升级成一个语义化工具——LLM 只指认「要看哪里」，由 agent 复用
tiling.py 的标定数学算出该切几张、每张覆盖多大，用构造保证可读。

新增 dwg_review/inspect.py（agent 侧，不编 DLL）：
- TOOL_SCHEMA：inspect_region(target, purpose)；target 三形态 {handle} / {window} /
  {label,cx,cy,span}，purpose = text(8px) / line(6px)。
- InspectState：单图框内「截图标签 → 世界可见范围」登记表，支持逐级下钻
  （返回的 inspect-N 可继续作为 label 指认）。
- resolve_target / _point_box：label+cx+cy → WCS。cy 是图像坐标（上→下），
  世界 y 必须翻转（y = y2 - cy*H）——单测专门钉住。
- plan_tiles：复用 world_per_px + tiles_for_box + subdivide；超 INSPECT_MAX_TILES(4)
  则硬失败并给出「缩小 target / 分多次请求」的指引（不静默降级）；拿不到比例/像素
  则退回单张并如实告知。

关键几何：CAD 的 _.ZOOM _W 是等比适配（不拉伸），故「截图上的归一化坐标」必须按
max(W/ew, H/eh) 反算真实可见范围（新增 tiling.visible_box）——直接用送进去的窗口会偏。
zoom_to_window 返回的 view 是「加过 margin 的窗口」，不是可见范围，不能混用。

证据层配套：evidence_model.make_image(..., window=) 记录每张图的可见世界范围；
capture_images 用 view_px（overall 图原始像素）+ visible_box 逐张登记。

子循环接入：_run_readonly_tool 在只读白名单校验之前拦截 inspect_region（它不在
READ_ONLY_TOOLS 里，内部只调白名单内的只读 MCP 工具）；_review_tools 启用时用
inspect_region 取代三个裸视口工具；inspect_region 计入 _VIEW_TOOLS → 结束复位视口。
配置：INSPECT_ENABLED(True) / INSPECT_MAX_TILES(4)。

端到端实测（真实图纸 1 图框）：取证与审查两阶段均在最大化态、结束精确还原（4 项 PASS）；
LLM 的 11 次取证调用里 2 次是 inspect_region，且都显式给 window + purpose:"text"
（x[20000,115000] y[-6500,3000]，即 A0 图框底部横条＝标题栏所在）。
验收口径达成：报告报出标题栏乱码 ???????????????，而 get_text_content 对全图返回 0 条文字
（本图文字全在块/自定义实体内）→ 块内文字是被视觉放大读出来的。
pytest 343 passed。

dwg_review/phases/evidence.py

@@ -20,6 +20,9 @@ _LABEL_OVERALL = "overall"
 # 绘图区最大化用的工具名（旧版插件没有此工具 → 静默降级）
 _TOOL_DRAWING_AREA = "set_drawing_area"
 
+# zoom 时四周留边比例（与 `zoom_to_window` 的默认 margin 一致）
+_ZOOM_MARGIN = 0.02
+
 
 @contextlib.contextmanager
 def maximized_drawing_area(ctx):
@@ -95,7 +98,7 @@ def sub_windows(window, tiles):
     return out
 
 
-def _zoom_and_shot(ctx, window, margin=0.02):
+def zoom_and_shot(ctx, window, margin=_ZOOM_MARGIN):
     """缩放到窗口、等待渲染、截一张图，返回 (b64, mime) 或 None。"""
     ctx.tools.call("zoom_to_window", dict(window, margin=margin))
     time.sleep(config.RENDER_WAIT)
@@ -209,6 +212,8 @@ def capture_images(ctx, window, *, tiles=0, max_images=None, frame=None,
     - 局部窗口优先由 `_plan_tiles` 按**实体分布**给出（空白区不出图）；
       不可用时退回 `sub_windows(window, tiles)`，**同样按内容过滤**空白象限
       （过滤后为空则退回未过滤集合，保证不漏拍）。
+    - 每张图登记其**实际可见世界范围**（`window` 字段）——审查阶段的 `inspect_region`
+      靠它把「截图上的归一化坐标」映射回 WCS（逐级下钻）。
     - 结束时**复位到整体视口**，保证后续流程从整幅视图起手。
     - 受 max_images（默认 config.EVIDENCE_MAX_IMAGES）截断。
     """
@@ -216,14 +221,23 @@ def capture_images(ctx, window, *, tiles=0, max_images=None, frame=None,
         max_images = config.EVIDENCE_MAX_IMAGES
     images = []
 
-    def _add(shot, label):
-        if shot and len(images) < max_images:
-            images.append(evidence_model.make_image(shot[0], shot[1], label))
-
     # 整体图：既是证据，也用于测量绘图区**实际像素**（决定单张截图的世界覆盖范围）
-    overall = _zoom_and_shot(ctx, window)
+    overall = zoom_and_shot(ctx, window)
     view_px = image_size_b64(overall[0]) if overall else None
-    _add(overall, _LABEL_OVERALL)
+
+    def _add(shot, label, win):
+        """登记截图；`win` 为送给 CAD 的窗口，用于反算实际可见世界范围。"""
+        if shot and len(images) < max_images:
+            images.append(
+                evidence_model.make_image(
+                    shot[0], shot[1], label,
+                    window=tiling.visible_box(
+                        tiling.window_to_box(win), view_px, _ZOOM_MARGIN
+                    ),
+                )
+            )
+
+    _add(overall, _LABEL_OVERALL, window)
 
     # 内容过滤：空白区不出图。按**实体 bbox** 判定，规划与回退两条路径共用同一谓词；
     # 实体数据被截断时不可信，放弃过滤（宁可多拍也不漏）。
@@ -237,10 +251,10 @@ def capture_images(ctx, window, *, tiles=0, max_images=None, frame=None,
     for i, sub in enumerate(regions, 1):
         if len(images) >= max_images:
             break
-        _add(_zoom_and_shot(ctx, sub), f"tile-{i}")
+        _add(zoom_and_shot(ctx, sub), f"tile-{i}", sub)
 
     # 复位整体视口（不截图）
-    ctx.tools.call("zoom_to_window", dict(window, margin=0.02))
+    ctx.tools.call("zoom_to_window", dict(window, margin=_ZOOM_MARGIN))
     return images
 
 

dwg_review/phases/review.py

@@ -14,7 +14,7 @@
 
 import json
 
-from .. import config, evidence_model
+from .. import config, evidence_model, inspect
 from ..cad_tools import READ_ONLY_TOOLS, is_write_tool
 from ..findings import parse_conclusion
 from ..llm_client import LlmClient, downsample_image_b64
@@ -24,7 +24,13 @@ from ..mcp_client import McpError, McpToolError, result_images, result_texts
 _MAX_OBS_IMAGES = config.REVIEW_OBS_IMAGES
 
 # 会改动视口的只读取证工具：用过之后须把视口复位，别把用户的 CAD 留在放大处
-_VIEW_TOOLS = frozenset({"zoom_to_window", "zoom_to_entity"})
+_VIEW_TOOLS = frozenset({"zoom_to_window", "zoom_to_entity", inspect.TOOL_NAME})
+
+# 启用 inspect_region 时，这三个裸视口工具不再直接提供给 LLM（由 inspect_region 统一代理），
+# 但仍留在只读白名单里，作为兜底仍然可被调用。
+_RAW_VIEW_TOOLS = frozenset(
+    {"zoom_to_window", "zoom_to_entity", "get_viewport_screenshot"}
+)
 
 
 def evidence_payload(evidence):
@@ -45,8 +51,17 @@ def evidence_payload(evidence):
     }
 
 
-def _run_readonly_tool(ctx, name, args, image_budget):
-    """执行一个只读取证工具，返回回灌给 LLM 的 content 列表。"""
+def _run_readonly_tool(ctx, name, args, image_budget, *, evidence=None, state=None):
+    """执行一个只读取证工具，返回回灌给 LLM 的 content 列表。
+
+    `inspect_region` 是 **agent 侧虚拟工具**（不走 MCP），在只读白名单校验**之前**拦截：
+    它内部只调白名单内的只读 MCP 工具。
+    """
+    if name == inspect.TOOL_NAME:
+        if not config.INSPECT_ENABLED or evidence is None or state is None:
+            return [{"type": "text", "text": "inspect_region 当前不可用。"}], image_budget
+        return inspect.inspect_region(ctx, evidence, args, image_budget, state)
+
     if name not in READ_ONLY_TOOLS or is_write_tool(name):
         return [{"type": "text", "text": f"工具 {name} 不在只读取证白名单内，已拒绝。"}], image_budget
 
@@ -75,6 +90,19 @@ def _run_readonly_tool(ctx, name, args, image_budget):
     return content, image_budget
 
 
+def _review_tools(ctx):
+    """审查子循环提供给 LLM 的工具 schema。
+
+    启用 `inspect_region` 时，用它**取代**三个裸视口工具（`zoom_to_window` /
+    `zoom_to_entity` / `get_viewport_screenshot`）——一个语义化入口比三个裸工具更好用，
+    且可读性由 agent 保证；关闭时维持原样（退回旧行为）。
+    """
+    if config.INSPECT_ENABLED:
+        names = READ_ONLY_TOOLS - _RAW_VIEW_TOOLS
+        return ctx.tools.openai_tools(names=names) + [inspect.TOOL_SCHEMA]
+    return ctx.tools.openai_tools(names=READ_ONLY_TOOLS)
+
+
 def _reset_viewport(ctx, evidence):
     """把视口复位到该图框的整幅视图（审查中的放大不应残留给用户）。"""
     win = evidence.get("window")
@@ -121,8 +149,9 @@ def _review_frame(ctx, evidence, system_prompt, log, view_changed):
         {"role": "user", "content": user_content},
     ]
 
-    tools_schema = ctx.tools.openai_tools(names=READ_ONLY_TOOLS)
+    tools_schema = _review_tools(ctx)
     image_budget = [_MAX_OBS_IMAGES]
+    state = inspect.InspectState(evidence)
 
     for _ in range(max(0, ctx.max_iters)):
         resp = ctx.llm.chat(messages, tools=tools_schema)
@@ -142,7 +171,9 @@ def _review_frame(ctx, evidence, system_prompt, log, view_changed):
             log(f"      [取证] {name} {args if args else ''}")
             if name in _VIEW_TOOLS:
                 view_changed[0] = True
-            content, image_budget = _run_readonly_tool(ctx, name, args, image_budget)
+            content, image_budget = _run_readonly_tool(
+                ctx, name, args, image_budget, evidence=evidence, state=state
+            )
             messages.append(
                 {"role": "tool", "tool_call_id": tool_call.id, "content": content}
             )