源码教程：文件上传、截图、PDF 与 OCR

这一组命令连接浏览器对象与服务端文件系统。路径属于服务端，不能把客户端路径直接当成服务器可以打开的文件。文件传输协议见第 12 篇，OCR 使用方式见第 16 篇。

1. upload_file 的两个入口分支

注册层先检查 contentBase64 或 url：存在时调用 uploadFileInline，先落盘，再进入页面上传；否则要求 path，调用 uploadFile。因此一次调用应明确选择一种来源，不要同时传互相矛盾的文件来源。

页面上传最终定位 input[type=file] 并使用浏览器文件输入能力设置文件。file input 常被隐藏，不能套用普通按钮的“只挑可见元素”策略。selector 与 index 至少选择一个，iframe 中的 selector 还需要 frame。

{"id":"1001","method":"upload_file","params":{"selector":"input[type=file]","path":"tmp/sample-logo.png"}}

path 需要按上传存储模块的解析规则使用；通过上传接口获得的相对路径按服务端上传目录解析，使用绝对路径时则指向服务端已有文件。不要假定所有命令的相对路径基准相同，OCR 文件路径的基准是进程工作目录。

实现不能只检查 setInputFiles 是否返回：框架可能消费文件后重置 input，甚至替换整个节点。回读应解释 filesLength、监听信息、consumed 和页面变化，避免因新 input 为空误判失败。上传后出现裁剪窗口时，需完成裁剪，不能直接再次上传。

2. screenshot 的目标选择

screenshot 优先处理 index/selector 指定的元素；没有元素定位时使用 Page.screenshot。只有 clipX、clipY、clipWidth、clipHeight 全部存在时才设置裁剪区域。fullPage 控制整页截图，不应同时把“元素截图”和“整页截图”当成两张产物。

默认不返回 Base64。未指定 path 且没有要求 inline 时，会生成任务目录中的 shot-N.png；指定 inline 才把图片编码放入结果。图像路径在任务 data 目录内时可生成 image URL，任意本地路径不会自动变成公开下载地址。

截图期间实现会隐藏交互高亮层，再恢复它，避免彩色编号挡住二维码或表单。截图失败应返回错误或降级说明，不凭页面文本声称已经取得图片。

{"id":"1001","method":"screenshot","params":{"fullPage":false,"inline":false}}

3. get_element_screenshot 与 pdf

get_element_screenshot 复用元素截图辅助逻辑，支持 frame。它通过浏览器截图获取像素，不是将跨域图片画到 canvas 后读取，所以不受同一种 canvas 污染限制。返回路径、URL 或显式请求的 Base64。

pdf 使用当前 Page 的 PDF 能力并保存文件，不是先做 OCR 再生成文档。该能力受浏览器引擎支持范围约束；不能向所有引擎承诺可用。导出前应等待字体、图片和业务内容完成加载。

4. ocr_image 的源码链

path 分支：解析文件路径并检查存在
元素分支：解析任务与 Frame → 元素截图
 → WindowsOcr.read
 → 将内置脚本写临时文件（处理 UTF-8 BOM）
 → Windows PowerShell 调用 Windows.Media.Ocr
 → 从输出文件读取文字与错误标识
 → data.ok/text/language/lineCount 等字段
 → 清理临时脚本和输出文件

PlaywrightService.ocrImage 即使识别失败，也可能以外层成功响应返回内部 OCR 结果。客户端必须检查 data.ok。语言缺失、平台不支持、文件不存在和文字识别为空是不同情况。

请求 language 不等于实际引擎语言；当前脚本会尝试用户语言回退，但未返回实际 engineLanguage。阅读源码时应核对返回语句，不能只照抄注释。

5. 验证方法

使用无个人信息的本地示例图片测试上传、节点替换、隐藏 input 和裁剪流程；验证默认截图只返回文件位置，inline 才返回 Base64，路径与文件实际一致。OCR 使用人为制作的示例文字，并分别检查语言包可用与不可用的返回。截图和 OCR 结果均应按敏感资料管理，默认留档不等于自动脱敏。

注册参数与 Java 入口

以下按 CommandTable 实际读取参数整理。* 表示注册层使用必填读取器；其余字段省略后由服务决定默认行为。带条件的入口仍需满足正文说明，例如上传文件来源、元素定位二选一。外层 id 不重复列出。