# 屏幕区域与 OCR 自动化

官方“屏幕与识别”插件 `xfe.vision` 提供 17 个节点。节点库可按“文字识别”“图像识别”“屏幕区域”“鼠标操作”“剪贴板”分类浏览，或搜索 OCR、文字、图像、颜色等关键词。

## 开始使用

1. 打开工作流工具栏的更多菜单，创建“框选 OCR 模板”。
2. 运行后拖动框选目标区域，按 Enter 或“使用此区域”确认；Esc 取消。
3. OCR 在本地识别简体中文和英文，日志节点显示识别文本。无须配置 AI 服务或联网下载模型。

也可以在 OCR、文字查找或图像查找节点的属性面板中点击“框选识别区域”，提前保存固定区域。选择本地图像文件后，框选会打开该图像；不填写图像路径时，框选当前屏幕。清除区域后使用整个图像或整个虚拟桌面。“坐标 / 数据绑定”支持数值微调与 JSON 绑定，取消框选不会修改旧值。

定时流程应预先保存固定区域，避免使用需要人工确认的“框选屏幕区域”节点。窗口移动或显示器排列改变后，应重新框选。

## 节点

以下 ID 均以 `xfe.vision.` 开头。

| 分类 | 节点 ID | 用途 |
|---|---|---|
| 屏幕区域 | selectRegion | 运行时交互框选，返回 region 和中心 point |
| 屏幕区域 | capture | 将完整桌面或区域保存为 PNG |
| 文字识别 | ocr | 返回文字、行、词、位置及置信度 |
| 文字识别 | findText / waitText / clickText | 查找文字、等待出现、识别并点击 |
| 图像识别 | findImage / waitImage / clickImage | 按匹配相似度查找、等待、点击模板图像，兼容旧版容差 |
| 图像识别 | pixel / waitColor | 读取 RGB / #RRGGBB，等待颜色满足条件 |
| 鼠标操作 | click / move / drag / scroll | 单击或双击、移动、拖拽、垂直或水平滚轮 |
| 剪贴板 | clipboardRead / clipboardWrite | 读取或写入文本 |

完整输入、输出、默认值见插件包内 `plugin.json`。查找返回 `found`、`matches`、首个匹配 `region` 与中心 `point`；等待超时返回 `found=false`、`timedOut=true`，可以连接条件节点。点击节点未找到目标时报告错误，不会点击任意位置。

## 从屏幕制作找图模板

1. 添加“查找目标图像”“等待图像出现”或“查找并点击图像”，在属性面板点击“从屏幕框选模板”。
2. 软件会暂时隐藏主窗口并冻结屏幕。拖动框选目标，按 Enter 或“使用此模板”确认；Esc 取消。模板取自原始冻结图像，不包含选区边框或遮罩。
3. 属性面板显示缩略图和像素尺寸。“预览原图”打开完整模板，“重新框选模板”替换模板；取消重新框选保留原图。仍可“导入本地图像”。
4. 设置最低匹配相似度，默认 90%，支持滑块和百分比输入。相似度越高越严格；100% 要求所有像素完全一致。
5. 点击“测试匹配”查看查找位置、相似度和标框图像。此操作始终调用查找能力，即使当前节点用于点击，也不会点击屏幕；可以停止或关闭预览。预览需要静态参数，使用数据绑定时运行完整流程验证。

屏幕框选和本地图像导入均转换成内嵌 PNG，随工作流保存、复制、撤销重做、导入导出携带，无须保留源图文件。单个模板上限 2 MiB PNG、1048576 像素，单边最多 8192 像素；建议只框选具有明显特征的小区域。进程消息上限 8 MiB，包含所有模板与参数，超过时会提示缩小模板或拆分子流程。

插件 1.1.0 的 `templatePath` 接受 PNG data URI 或旧式本地路径，`minimumSimilarity` 接受 0.01～1。评分为 `1 - 所有像素 RGB 绝对差的平均值 / 255`，采用全部像素计算，结果按分数从高到低排列并排除重叠命中。这个分数表示像素相似程度，不是 OCR 置信度。固定尺寸模板不支持自动缩放或旋转，界面尺寸、DPI 或主题改变后应重新框选。

旧版工作流保持插件版本锁定。使用新模板功能会将该流程的“屏幕与识别”版本更新到已安装的 1.1.0 或更新版本，并保留其他找图节点（包括子图）的旧版容差模式。在“匹配方式”中可以主动切换到相似度；切回旧版时显式保存 `minimumSimilarity: null`，再使用 `tolerance`（每个 RGB 通道允许的最大差值，0～255）。默认值只补充缺省参数，显式 null 不会被覆盖。

图像在 UI 和 Runner 间按原始像素加载，避免 PNG 的 DPI 元数据触发缩放。相关绘图语义见 [Microsoft DrawImageUnscaled 文档](https://learn.microsoft.com/en-us/dotnet/api/system.drawing.graphics.drawimageunscaled?view=windowsdesktop-10.0)。

## 坐标和数据联动

区域采用 `{"x":100,"y":200,"width":640,"height":320}`，点采用 `{"x":420,"y":360}`。

- 屏幕区域与输出坐标相对于整个 Windows 虚拟桌面，单位是物理像素。左侧或上方显示器可以产生负坐标。
- 图像文件使用原始图像像素；裁剪区域中的识别结果仍相对于原图。输出中的 `coordinateSpace` 区分 `screen` 与 `image`。
- 文字匹配支持包含、精确、正则及忽略大小写；中文匹配会忽略 OCR 插入的词间空白。匹配矩形覆盖实际命中的词。
- 将查找节点的 `point` 输出连接到“点击屏幕坐标”，或用 `{"$node":"节点ID.point"}` 绑定。OCR 的 `text` 可传给变量、日志、AI、HTTP、企微等节点。
- 区域或图像路径绑定为空时会报错，不会自动改为全屏识别。

## C# 示例

```csharp
var selected = await context.InvokeAsync("xfe.vision.selectRegion", new JsonObject(), cancellationToken);
var recognized = await context.InvokeAsync("xfe.vision.ocr", new JsonObject
{
    ["region"] = selected["region"]!.DeepClone(),
    ["language"] = "chi_sim+eng",
    ["segmentation"] = "SparseText",
    ["scale"] = 2
}, cancellationToken);
await context.LogAsync(recognized["text"]!.GetValue<string>(), cancellationToken);
```

可导入的图形与纯 C# 示例分别在 `samples/workflows/screen-ocr-graph.xfeworkflow`、`samples/workflows/screen-ocr-code.xfeworkflow`。OCR 节点提供“测试文字识别”，预览在独立 Runner 中执行；预览需要静态参数，使用上游绑定时运行完整工作流验证。

## 已验证的界面

![OCR 节点与区域属性](screenshots/workflow-ocr-tools.png)

![真实鼠标框选测试窗口](screenshots/screen-region-picker.png)

![模板缩略图、重新框选与匹配相似度](screenshots/workflow-image-template.png)

![实际 Runner 的匹配预览与得分](screenshots/workflow-image-match-dialog.png)

![从屏幕框选模板](screenshots/screen-template-picker.png)

Windows x64 Release 构建为零警告、零错误；80 项 XFE XUnit 测试及 20 项完整 UI 检查通过，包括 150% DPI 下的 640×240 物理像素框选、取消保留旧模板、原始像素验证、实际 Runner 匹配预览和指针处滚轮缩放。检查结果见 [完整 UI 报告](screenshots/image-templates-ui-results.json)。截图全部使用自建测试内容。

## 运行与限制

当前离线 OCR 引擎支持 Windows x64 / x86，随插件分发 chi_sim 与 eng 模型，以及应用本地的 Microsoft C++ 运行库；ARM64 保留构建配置，其余屏幕能力可用，原生 OCR 会提示使用 x64 客户端。截图与放大后的 OCR 输入均限制为 4000 万像素，超出时缩小区域或降低放大倍数。

OCR、图像匹配与轮询支持取消，原生识别中的强制停止由 Runner 的退出机制处理。屏幕和鼠标操作取得桌面独占租约；鼠标操作沿用 InputController 和标准输入后端。拖拽异常、取消、Ctrl+Alt+F12 紧急停止会释放按键，紧急停止也会关闭活动框选窗口。锁屏、安全桌面、受保护内容和没有交互桌面的会话不保证可截图。

识别效果取决于字体、分辨率、背景对比度与排版；可调整语言、放大倍数、置信度及排版模式。自动测试使用自建图像和测试窗口，不扫描用户桌面内容。多屏混合 DPI 的硬件组合还需在目标设备上手动验收。

实现依据：[Tesseract .NET 包](https://github.com/charlesw/tesseract)、[Tesseract 引擎](https://github.com/tesseract-ocr/tesseract)、[官方 fast 模型](https://github.com/tesseract-ocr/tessdata_fast)。模型固定提交与 SHA256 记录在插件 `tessdata/SOURCES.json`，许可随插件分发。