Windows OCR：本地图片与页面文字识别

ocr_image 使用服务端 Windows 的 Windows.Media.Ocr 识别图片文字，适用于扫描件、公告图片和页面中没有 DOM 文本的区域。它不是二维码解码器，也不等于文档结构化提取；图片中的表格、印章、手写字和模糊字符需要另外核对。

有 DOM 文本时优先使用 get_browser_state 或 get_element_text，不必先截图再 OCR。

1. 运行条件

运行浏览器服务的机器必须是 Windows。客户端是 Windows、服务端是 Linux 时，不能使用这项内置 OCR。
代码通过系统自带的 Windows PowerShell 调用 WinRT，不要求另外安装云端 OCR SDK，也不把识别图片发送给云端识别服务。
需要系统有可用的 OCR 语言包，默认请求 zh-Hans-CN。识别英文可指定 en-US。
需要读取图片和创建临时文件的权限。网页元素识别还需要有效浏览器任务。

语言包可在 Windows「设置 → 时间和语言 → 语言和区域」中检查；相关可选功能名称通常为“光学字符识别”，具体入口随系统而异。

当前脚本先尝试请求语言，失败时会尝试用户配置的语言。返回的 language 是请求语言，并不证明实际使用了该语言引擎；当前实现没有返回 engineLanguage。遇到中文被识别成零散拉丁字母时，应检查语言包，不能据此判断原图内容。

2. 参数说明

统一入口为 POST /playwright/command，method 为 ocr_image。

参数	说明
`id`	外层任务 ID；页面元素截图需要有效任务
`path`	服务端本地图片文件路径，不是远程 URL；相对路径按服务进程工作目录解析
`index`	当前页面快照中的元素索引
`selector`	图片或待识别区域的 CSS 选择器
`frame`	元素位于 iframe 时指定对应 frame
`language`	可选，请求的识别语言；默认 `zh-Hans-CN`

选择 path 或页面元素定位其中一种方式即可。如果同时传入非空 path，代码优先读取文件，不使用元素参数。页面索引必须来自最新快照，避免识别错图。

读取服务端图片

下面的路径和任务 ID 均为示例，应替换为实际值：

{
  "id":"1001",
  "method":"ocr_image",
  "params":{
    "path":"tmp/sample-notice.png",
    "language":"zh-Hans-CN"
  }
}

文件路径分支本身不需要截图浏览器；页面元素分支必须先启动任务。远程调用时，本机文件需要先按文件上传说明放到服务端，不能把客户端磁盘路径当成服务端路径。

读取页面区域

{
  "id":"1001",
  "method":"ocr_image",
  "params":{
    "selector":"#notice-image",
    "language":"zh-Hans-CN"
  }
}

服务先调用元素截图能力，将图保存在服务端，再识别。元素在 iframe 时，先通过 list_frames 确定对应 frame，再传 frame 参数。元素截图失败会直接返回失败，不会继续 OCR。

3. 判断识别是否成功

OCR 结果放在 data 内。必须同时检查外层 ok 和内层 data.ok：外层成功可能只表示命令正常返回，内层仍可能是识别失败。

以下是省略部分字段的示意响应，内容为虚构文本：

{
  "ok":true,
  "code":1,
  "data":{
    "ok":true,
    "text":"示例公告：系统维护中",
    "language":"zh-Hans-CN",
    "lineCount":1,
    "ms":120,
    "target":"path=tmp/sample-notice.png",
    "imagePath":"<服务端图片绝对路径>"
  }
}

字段	含义
`data.ok`	OCR 是否成功完成；成功不代表文字完全正确
`text`	识别到的文本，可能为空
`lineCount`	返回文本的行数
`ms`	已取得的执行耗时；早期失败不保证存在
`imagePath`	实际读取图片的服务端路径
`imageUrl`	有可用图片地址时附带，不保证所有本地文件都可以通过 HTTP 访问
`error`、`hint`	失败原因及可能的处理建议
`engineMissing`	没有可用 OCR 引擎时可能返回 `true`
`ocrSupported`	失败时附带的环境检查结果，仅表示能否定位 Windows PowerShell，不证明语言包可用

当前返回值没有逐字置信度、文字坐标或实际引擎语言信息。不要按源码注释中的字段设想编写客户端，应以实际返回结构为准。

4. 与人工协作结合

request_human_input 可以在请求协助时附带识别结果：

{
  "id":"1001",
  "method":"request_human_input",
  "params":{
    "prompt":"请核对图片中的公告内容",
    "selector":"#notice-image",
    "ocr":true,
    "ocrLanguage":"zh-Hans-CN",
    "timeoutSeconds":300
  }
}

这里参数名是 ocrLanguage，而 ocr_image 使用 language。结果可能包含 ocr、ocrText 或 ocrError。接口创建请求成功不代表用户已经收到通知，宿主仍需展示求助信息。

OCR 只能提供文字参考，不能证明登录、短信验证、扫码或人工确认已经完成。遇到需要本人操作的验证时，应保留浏览器状态，等待真实答复，再读取页面确认结果。

5. 常见问题与数据保护

现象	排查方式
外层成功但没有文字	检查 `data.ok`、`error` 和 `engineMissing`
找不到图片	检查服务进程工作目录、文件是否存在、访问权限以及是否误传客户端路径
环境支持但引擎缺失	检查所需 OCR 语言包；环境检测不会验证语言包
中文内容识别错误	检查语言包、原图清晰度、旋转角度、裁剪范围；关键字段人工核对
页面元素找不到	重新获取快照，确认选择器、页签和 iframe
上传或截图后读错图	核对 `target`、`imagePath`，不要继续使用旧索引

本地识别不代表所有结果都不会留档。页面截图、命令响应、trace、临时参数文件可能包含证照与个人信息，分享前按留档脱敏说明核验。教程仅使用虚构图片与占位路径，不复制实际证照、手机号、验证码或账号。