[1204244136]

Default both controllers to a 720-pixel short side, preserve screenshot dimensions unless resizing is explicit, and remove duplicate OCR ROI offsets.

Add configurable controller resolution, optional screenshot coordinate transforms, migration documentation, and native regression tests using synthetic images.

Sourcery 摘要

在统一且可配置的坐标系下对齐控制器截图、OCR 和输入操作，同时除非请求调整大小，否则保留截图尺寸不变。

新功能：

• 允许连接选择控制器截图的短边长度，或使用原生尺寸。
• 提供可选的截图元数据，用于将裁剪或调整大小后的图像坐标映射回控制器坐标。

错误修复：

• 将 OCR 区域和返回的框与控制器坐标系对齐，避免重复应用 ROI 偏移。
• 默认保留截图尺寸，并确保截图、OCR、操作和 Pipeline 坐标保持一致。

增强功能：

• 围绕可配置的默认 720 像素短边，统一 Win32 和 ADB 的坐标行为。
• 记录坐标约定、缩放变换，以及模板和 Pipeline ROI 的兼容性要求。

文档：

• 添加英文和中文文档，涵盖截图坐标约定、控制器分辨率设置，以及图像到控制器的坐标变换。

测试：

• 添加原生回归测试，覆盖可配置分辨率、坐标一致的点击、裁剪和调整大小变换、四舍五入后的尺寸、Pipeline 缩放匹配、MCP 元数据，以及全局 OCR 框。

Original summary in English

Sourcery 摘要

统一控制器、截图、OCR、输入和 Pipeline 的坐标处理，同时使分辨率和图像到控制器的转换可配置。

新功能：

• 允许 Win32 和 ADB 连接选择控制器截图的短边尺寸或原生尺寸。
• 提供可选的截图元数据，用于将裁剪或缩放后的图像坐标映射回控制器坐标。

错误修复：

• 将截图、OCR 区域和结果、输入操作以及 Pipeline 坐标统一到共享的控制器坐标系中。
• 防止重复应用 OCR 区域偏移，并在未明确请求缩放时保留截图尺寸。

增强功能：

• 在 Win32 和 ADB 控制器之间统一默认的 720 像素短边坐标基准。
• 明确坐标、缩放、裁剪、模板和 Pipeline ROI 的兼容性要求。

文档：

• 使用英文和中文记录截图坐标约定、可配置的控制器分辨率以及图像到控制器的转换。

测试：

• 增加原生回归测试，覆盖可配置分辨率、坐标一致的输入、裁剪和缩放转换、四舍五入后的尺寸、Pipeline 缩放匹配、MCP 元数据以及全局 OCR 框。

Original summary in English

Summary by Sourcery

Unify controller, screenshot, OCR, input, and Pipeline coordinate handling while making resolution and image-to-controller transformations configurable.

New Features:

• Allow Win32 and ADB connections to select a controller screenshot short side or native dimensions.
• Provide optional screenshot metadata for mapping cropped or resized image coordinates back to controller coordinates.

Bug Fixes:

• Align screenshots, OCR regions and results, input actions, and Pipeline coordinates to a shared controller coordinate system.
• Prevent duplicate OCR region offsets and preserve screenshot dimensions unless resizing is explicitly requested.

Enhancements:

• Standardize the default 720-pixel short-side coordinate basis across Win32 and ADB controllers.
• Clarify coordinate, scaling, cropping, template, and Pipeline ROI compatibility requirements.

Documentation:

• Document screenshot coordinate conventions, configurable controller resolutions, and image-to-controller transformations in English and Chinese.

Tests:

• Add native regression coverage for configurable resolutions, coordinate-consistent input, crop and resize transforms, rounded dimensions, Pipeline scale matching, MCP metadata, and global OCR boxes.

[sourcery-ai]

您好——我发现了 1 个问题

AI 代理提示

请处理本次代码审查中的评论：

## 单条评论

### 评论 1
<location path="maa_mcp/vision.py" line_range="149" />
<code_context>
     region: Optional[Tuple[int, int, int, int]] = None,
-    resolution: Optional[int] = 720,
-) -> Optional[str]:
+    resolution: Optional[int] = None,
+    include_metadata: bool = False,
+) -> Optional[Union[str, dict]]:
</code_context>
<issue_to_address>
**issue (bug_risk)：** 未经过验证的非整数 `resolution` 会传递到 `_resize_short_edge`；诸如 `1.5` 这样的值会使 `cv2.resize` 接收到浮点型输出尺寸，并引发底层 OpenCV `TypeError`，而不是返回文档中说明的失败结果或清晰的参数错误。

**触发条件：** MCP 调用方无视类型注解，提供浮点型分辨率时。

**建议修复：** 在处理前将 `resolution` 验证为精确的正整数（或 `None`），并抛出清晰的 `ValueError`。
</issue_to_address>

---

Sourcery 对开源项目免费——如果您喜欢我们的审查结果，请考虑分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

Original comment in English

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="maa_mcp/vision.py" line_range="149" />
<code_context>
     region: Optional[Tuple[int, int, int, int]] = None,
-    resolution: Optional[int] = 720,
-) -> Optional[str]:
+    resolution: Optional[int] = None,
+    include_metadata: bool = False,
+) -> Optional[Union[str, dict]]:
</code_context>
<issue_to_address>
**issue (bug_risk):** A non-integer `resolution` reaches `_resize_short_edge` without validation; values such as `1.5` make `cv2.resize` receive a floating-point output dimension and raise a low-level OpenCV `TypeError` instead of returning the documented failure result or a clear argument error.

**Triggers:** When an MCP caller supplies a floating-point resolution despite the type annotation.

**Suggested fix:** Validate `resolution` as an exact positive integer (or `None`) before processing and raise a clear `ValueError`.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook