feat: add optional anchor info for reco sink

[neko-para]

neko-para/maa-support-extension#64

Summary by Sourcery

为节点识别事件添加可选的锚点元数据，并在识别管线和各语言绑定中贯通锚点信息。

New Features:

• 在运行识别任务时支持包含可选的锚点名称，并在节点识别开始通知中传播该信息。

Enhancements:

• 扩展识别 API 和通知负载，以便接收并携带管线中节点的可选锚点名称。
• 更新 Node.js 和 Python 绑定，在节点识别详情结构中暴露可选的锚点字段。

Original summary in English

Summary by Sourcery

Add optional anchor metadata to node recognition events and plumb anchor information through the recognition pipeline and language bindings.

New Features:

• Include optional anchor name when running recognition tasks and propagating it in node recognition start notifications.

Enhancements:

• Extend recognition API and notification payloads to accept and carry an optional anchor name for nodes in the pipeline.
• Update Node.js and Python bindings to expose the optional anchor field in node recognition detail structures.

[sourcery-ai]

Hey - 我发现了 1 个问题，并留下了一些整体性的反馈：

• 新的 run_recognition 函数签名让所有调用方都必须传入 anchor_name，而且改变了 ocr_cache 这个默认参数的位置；建议给 anchor_name 一个默认值（例如 std::nullopt），或者增加一个重载，以避免破坏现有调用点和 API 预期。
• 在 PipelineTask::recognize_list 中，锚点参数的构造方式是 node.anchor ? std::optional<std::string>{ node.name } : std::nullopt；如果目的是曝光锚点而不是节点名称，这里很可能应该使用锚点的值而不是节点名。
• 为了在传递可选锚点时避免不必要的字符串拷贝，建议把 run_recognition 的参数改为 const std::optional<std::string>& anchor_name（并相应更新调用处）。

给 AI Agent 的 Prompt

Please address the comments from this code review:

## Overall Comments
- 新的 `run_recognition` 函数签名让所有调用方都必须传入 `anchor_name`，而且改变了 `ocr_cache` 这个默认参数的位置；建议给 `anchor_name` 一个默认值（例如 `std::nullopt`），或者增加一个重载，以避免破坏现有调用点和 API 预期。
- 在 `PipelineTask::recognize_list` 中，锚点参数的构造方式是 `node.anchor ? std::optional<std::string>{ node.name } : std::nullopt`；如果目的是曝光锚点而不是节点名称，这里很可能应该使用锚点的值而不是节点名。
- 为了在传递可选锚点时避免不必要的字符串拷贝，建议把 `run_recognition` 的参数改为 `const std::optional<std::string>& anchor_name`（并相应更新调用处）。

## Individual Comments

### Comment 1
<location path="source/MaaFramework/Task/TaskBase.cpp" line_range="84-85" />
<code_context>
         { "name", data.name },
         { "focus", data.focus },
     };
+    if (anchor_name) {
+        cb_detail["anchor"] = *anchor_name;
+    }

</code_context>
<issue_to_address>
**issue (bug_risk):** 在当前实现中，如果 `anchor` 不存在，运行时负载会完全省略这个字段，而 MaaMsg 的约定是 `string | null`。

按照现在的写法，下游使用方只能看到字符串或缺失的 `anchor` 字段，而不会看到 `null`。如果有任何下游代码依赖该字段总是存在，或者明确为 `null`，这会引入一个隐蔽的破坏性变更。请在 `anchor_name` 未设置时始终将 `"anchor"` 设为 `null`，或者更新 MaaMsg 的约定以反映新的行为。
</issue_to_address>

---

Sourcery 对开源项目免费——如果你觉得我们的评审有帮助，欢迎分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请对每条评论点 👍 或 👎，我会根据这些反馈改进之后的评审。}

Original comment in English

Hey - I've found 1 issue, and left some high level feedback:

• The new run_recognition signature makes anchor_name mandatory for all callers and shifts the ocr_cache default argument; consider giving anchor_name a default (e.g., std::nullopt) or adding an overload to avoid breaking existing call sites and API expectations.
• In PipelineTask::recognize_list, the anchor argument is built as node.anchor ? std::optional<std::string>{ node.name } : std::nullopt; if the intent is to surface the anchor rather than the node name, this likely should use the anchor value instead.
• To avoid an unnecessary string copy when passing the optional anchor, consider changing run_recognition to take const std::optional<std::string>& anchor_name (and update the call site accordingly).

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The new `run_recognition` signature makes `anchor_name` mandatory for all callers and shifts the `ocr_cache` default argument; consider giving `anchor_name` a default (e.g., `std::nullopt`) or adding an overload to avoid breaking existing call sites and API expectations.
- In `PipelineTask::recognize_list`, the anchor argument is built as `node.anchor ? std::optional<std::string>{ node.name } : std::nullopt`; if the intent is to surface the anchor rather than the node name, this likely should use the anchor value instead.
- To avoid an unnecessary string copy when passing the optional anchor, consider changing `run_recognition` to take `const std::optional<std::string>& anchor_name` (and update the call site accordingly).

## Individual Comments

### Comment 1
<location path="source/MaaFramework/Task/TaskBase.cpp" line_range="84-85" />
<code_context>
         { "name", data.name },
         { "focus", data.focus },
     };
+    if (anchor_name) {
+        cb_detail["anchor"] = *anchor_name;
+    }

</code_context>
<issue_to_address>
**issue (bug_risk):** The runtime payload omits `anchor` entirely when absent, while the MaaMsg contract says `string | null`.

As written, consumers will now see either a string or a missing `anchor` field, never `null`. If any downstream code depends on the field always existing or being explicitly `null`, this introduces a subtle breaking change. Please either always set `"anchor"` to `null` when `anchor_name` is unset, or update the MaaMsg contract to reflect the new behavior.
</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.}