feat: 新增 Radiation 排序方式及可选 center 参数

[1204244136]

Summary by Sourcery

在各类视觉识别流水线中新增一种带可选中心坐标的 Radiation 结果排序模式，通过 NodeJS 绑定和文档对其进行暴露，并改进 Windows 键盘输入事件的扫描码处理。

New Features:

• 引入 Radiation order_by 模式，使所有相关视觉识别器可以根据距离参考中心点的远近对识别结果进行排序。
• 在流水线配置和绑定中新增可选的 center 参数，用于配置 Radiation 排序所使用的参考点。

Bug Fixes:

• 修正 Windows 键盘输入模拟，通过向按键事件 API 提供正确的扫描码来提升按键处理的可靠性。

Enhancements:

• 扩展流水线解析、导出和类型定义，以支持新的 Radiation 模式和 center 参数。
• 在英文和中文的流水线协议文档中补充 Radiation 排序行为及 center 选项的说明。

Original summary in English

Summary by Sourcery

Add a new Radiation result-sorting mode with optional center coordinates across vision recognition pipelines, expose it through NodeJS bindings and docs, and improve Windows keyboard input event scan code handling.

New Features:

• Introduce a Radiation order_by mode that sorts recognition results by distance from a reference center for all relevant vision recognizers.
• Add an optional center parameter to configure the reference point used by Radiation sorting in pipeline configurations and bindings.

Bug Fixes:

• Correct Windows keyboard input simulation by supplying proper scan codes to key event APIs to improve key handling reliability.

Enhancements:

• Extend pipeline parsing, dumping, and typing to support the new Radiation mode and center parameter.
• Document the Radiation sorting behavior and center option in both English and Chinese pipeline protocol docs.

[sourcery-ai]

Hey - 我发现了两个问题，并给出了一些整体性的反馈：

• 在 sort_by_radiation_ 中，你在排序比较器里每次比较都调用了 std::hypot；你可以通过比较平方距离（避免开方）来降低开销，或者在排序前为每个结果预先计算一次距离。

给 AI 代理的提示

Please address the comments from this code review:

## Overall Comments
- In `sort_by_radiation_`, you’re calling `std::hypot` inside the sort comparator for every comparison; you could reduce overhead by comparing squared distances instead (avoiding the sqrt) or by precomputing each result’s distance once before sorting.

## Individual Comments

### Comment 1
<location path="source/MaaWin32ControlUnit/Input/SeizeInput.cpp" line_range="240" />
<code_context>

     inputs[0].type = INPUT_KEYBOARD;
     inputs[0].ki.wVk = static_cast<WORD>(key);
+    inputs[0].ki.wScan = static_cast<WORD>(MapVirtualKeyW(static_cast<UINT>(key), MAPVK_VK_TO_VSC));

     SendInput(ARRAYSIZE(inputs), inputs, sizeof(INPUT));
</code_context>
<issue_to_address>
**suggestion (bug_risk):** 请考虑为 wScan 使用 MAPVK_VK_TO_VSC_EX，或加入对扩展键的专门处理。

使用 MAPVK_VK_TO_VSC 的 MapVirtualKeyW 在处理扩展键时（例如方向键、右 Ctrl/Alt）可能返回错误的扫描码。由于现在显式设置了 wScan，建议使用 MAPVK_VK_TO_VSC_EX，或者为扩展键添加条件分支，以确保在不同键盘布局下都有正确行为。
</issue_to_address>

### Comment 2
<location path="source/binding/NodeJS/src/apis/pipeline.d.ts" line_range="52" />
<code_context>
                 index?: number
                 method?: 10001 | 3 | 5
                 green_mask?: boolean
+                center?: [number, number]
             },
             'template',
</code_context>
<issue_to_address>
**suggestion:** 为 center 元组引入一个可复用的 Point 类型别名，以避免重复。

`center` 的 `[number, number]` 元组在多个识别类型中出现。请引入一个共享别名，例如 `type Point = [number, number];`，并使用 `center?: Point`，以提升可维护性和可读性，尤其是在这一结构在其他地方也会复用的情况下。

建议实现如下：

```typescript
                green_mask?: boolean
                center?: Point
            },
            'template',
            Mode
                green_mask?: boolean
                detector?: 'SIFT' | 'KAZE' | 'AKAZE' | 'BRISK' | 'ORB'
                ratio?: number
                center?: Point
            },
            'template',
            Mode
                order_by?: OrderByMap['ColorMatch']
                index?: number

```

1. 在这个声明文件中引入一个可复用的元组别名，例如放在其他共享类型别名附近：
   `type Point = [number, number];`
2. 确保本文件中所有表示二维点的 `[number, number]` 都更新为使用新的 `Point` 别名，以保持一致性。
</issue_to_address>

---

Sourcery 对开源项目免费——如果你觉得这些审查有帮助，欢迎分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论上点 👍 或 👎，我会根据你的反馈改进后续的代码审查。}

Original comment in English

Hey - I've found 2 issues, and left some high level feedback:

• In sort_by_radiation_, you’re calling std::hypot inside the sort comparator for every comparison; you could reduce overhead by comparing squared distances instead (avoiding the sqrt) or by precomputing each result’s distance once before sorting.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `sort_by_radiation_`, you’re calling `std::hypot` inside the sort comparator for every comparison; you could reduce overhead by comparing squared distances instead (avoiding the sqrt) or by precomputing each result’s distance once before sorting.

## Individual Comments

### Comment 1
<location path="source/MaaWin32ControlUnit/Input/SeizeInput.cpp" line_range="240" />
<code_context>

     inputs[0].type = INPUT_KEYBOARD;
     inputs[0].ki.wVk = static_cast<WORD>(key);
+    inputs[0].ki.wScan = static_cast<WORD>(MapVirtualKeyW(static_cast<UINT>(key), MAPVK_VK_TO_VSC));

     SendInput(ARRAYSIZE(inputs), inputs, sizeof(INPUT));
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Consider MAPVK_VK_TO_VSC_EX or extended-key handling for wScan.

MapVirtualKeyW with MAPVK_VK_TO_VSC can return incorrect scan codes for extended keys (e.g., arrows, right Ctrl/Alt). Since wScan is now set explicitly, consider using MAPVK_VK_TO_VSC_EX or a conditional path for extended keys to ensure correct behavior across keyboard layouts.
</issue_to_address>

### Comment 2
<location path="source/binding/NodeJS/src/apis/pipeline.d.ts" line_range="52" />
<code_context>
                 index?: number
                 method?: 10001 | 3 | 5
                 green_mask?: boolean
+                center?: [number, number]
             },
             'template',
</code_context>
<issue_to_address>
**suggestion:** Introduce a reusable Point type alias for the center tuple to avoid duplication.

The `[number, number]` tuple for `center` appears in multiple recognition types. Please introduce a shared alias, e.g. `type Point = [number, number];`, and use `center?: Point` for better maintainability and clarity, especially if this shape is reused elsewhere.

Suggested implementation:

```typescript
                green_mask?: boolean
                center?: Point
            },
            'template',
            Mode
                green_mask?: boolean
                detector?: 'SIFT' | 'KAZE' | 'AKAZE' | 'BRISK' | 'ORB'
                ratio?: number
                center?: Point
            },
            'template',
            Mode
                order_by?: OrderByMap['ColorMatch']
                index?: number

```

1. Introduce a reusable tuple alias in this declaration file, e.g. near the other shared type aliases:
   `type Point = [number, number];`
2. Ensure all other occurrences of `[number, number]` representing a 2D point in this file are updated to use the new `Point` alias for consistency.
</issue_to_address>

---

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

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[MistEO]

🤖 center 用 {-1,-1} 做"未指定"哨兵这里有点犹豫。项目自 v5.6 起 roi/target 负坐标已经有"从边缘反向计算"的语义了，center 作为屏幕坐标直接走哨兵等于给这一个字段开特例，不太对称。要么跟 roi/target 一样支持负值反向（这样 [-1,-1] 自然就是屏幕右下角），要么直接 std::optional<cv::Point>，倾向后者，简单直接。其他改得挺好。

[MistEO]

🤖 optional 化 center 👍。按仓库 checklist 还差 tools/pipeline.schema.json 和 Python maa/pipeline.py 里各 J* 的 center（以及 schema 里 order_by 枚举补上 Radiation），补完我再扫一遍