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。
This commit is contained in:
gjm committed 2026-10-16 19:15:32 +08:00
1 parent 3bc64b6c3e
commit b757892c67
18 files changed
+1003 -45

No files matched your search

+37 -6
View File
@@ -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}
)