docs: 图像与OCR 组 10 项能力问题检测报告
- 静态核对 + 真实运行双路验证，含 P0~P3 分级问题清单与修复优先级建议 - P0: GetOcrTextNew 目录字段无法传图（不可用）；P1: Click 忽略 position/click_key、GetOcrTable 输出字段无效 - 算法层（飞桨 OCR/模板匹配 0.9993）实测正常，问题集中在目录与实现脱节
This commit is contained in:
yu
parent
a4b7e24acd
commit
a3fbae9d83
99
docs/图像与OCR问题检测报告.md
Normal file
99
docs/图像与OCR问题检测报告.md
Normal file
@ -0,0 +1,99 @@
|
||||
# 图像与OCR 能力问题检测报告
|
||||
|
||||
- **检测时间**：2026-10-30 10:00–10:10
|
||||
- **检测人**：刘爱家（AI 辅助静态核对 + 真实运行验证）
|
||||
- **检测范围**：图像与OCR 分组已接入的全部 10 项能力（Image 7 项 + OcrOffline 3 项）
|
||||
- **检测方式**：
|
||||
1. 静态核对——组件目录（catalog.json）字段定义 vs 实现代码（vision.ts / ocr-caps.ts）逐键比对
|
||||
2. 真实运行——GDI 生成含中英文的测试图、真实截屏、模板匹配直测、OCR 引擎实识别（飞桨 @gutenye/ocr-node）
|
||||
- **说明**：本次仅检测未修改任何代码，问题留给同事修复。
|
||||
|
||||
---
|
||||
|
||||
## 一、结论概览
|
||||
|
||||
| 组件 | 名称 | 可用性 | 核心问题 |
|
||||
|---|---|---|---|
|
||||
| Image_Screenshot | 屏幕截图 | ⚠️ 基本可用 | 截图范围/图像来源字段无效，仅支持全屏 |
|
||||
| Image_Find | 查找图像 | ✅ 可用 | accuracy2 字段无效 |
|
||||
| Image_Find_V1 | 查找图像 | ⚠️ 有隐患 | window_obj 必填但被忽略，实际全屏查找 |
|
||||
| Image_Click | 点击图像 | ⚠️ 有缺陷 | position（点击位置）被忽略，永远点中心 |
|
||||
| Image_Click_V1 | 点击图像 | ⚠️ 有缺陷 | 同上 |
|
||||
| Image_Click_V2 | 点击图像 | ⚠️ 有缺陷 | 同上 |
|
||||
| Image_Click_V3 | 鼠标点击图像 | ❌ 功能缺失 | click_key（左/右键）被忽略，右键点击无法实现；窗口限定无效 |
|
||||
| OcrOffline_GetOcrTextNew | 图像OCR识别 | ❌ 不可用 | **按目录配置无法传入图片路径，任何填写方式都报「图片路径为空」** |
|
||||
| OcrOffline_GetOcrTextPosition | 图像OCR识别（含坐标） | ✅ 可用 | 无阻塞性问题 |
|
||||
| OcrOffline_GetOcrTable | 获取表格数据（OCR） | ⚠️ 部分可用 | 保存至数据表/Excel 的 4 个字段全部无效；返回扁平文本非表格结构 |
|
||||
|
||||
**正常项（已实测确认）**：截屏产物正确；模板匹配精度高（自测得分 0.9993）；OCR 中文/数字识别准确、坐标与置信度返回正常；找图失败时报错提示合理。
|
||||
|
||||
---
|
||||
|
||||
## 二、问题清单（按严重度）
|
||||
|
||||
### P0-1 OcrOffline_GetOcrTextNew：目录字段与实现完全脱节，组件不可用
|
||||
|
||||
- **现象**：该组件在目录里唯一的图片相关字段是 `uiSelector`（目标，非必填），而实现读取图片路径的键列表为 `image_path/imagePath/file_path/filePath/path/image/pictureSource`——**不包含 uiSelector**。
|
||||
- **后果**：用户按目录界面填参数，无论怎么填都无法把图片传进实现，必然报「图片路径为空」。已实测复现：`{ uiSelector: "D:/.../ocr_input.png" }` → `RuntimeError: 图片路径为空`。
|
||||
- **修复建议**：实现读取键中加入 `uiSelector`，或目录为该组件增加 `image_path` 必填字段（与 GetOcrTextPosition 保持一致）。
|
||||
|
||||
### P1-1 Image_Click 全 4 版本：忽略「点击位置」字段
|
||||
|
||||
- **现象**：目录字段 `position`（点击位置，默认 center），实现拿到匹配区域后**固定点击中心点**（`vision.ts` 中 `x + width/2, y + height/2`），position 值从不读取。
|
||||
- **后果**：用户选择「左上角/右上角/自定义偏移」等位置时静默失效，点击落点与预期不符且无任何提示。
|
||||
|
||||
### P1-2 Image_Click_V3：忽略「鼠标按键」字段，右键点击无法实现
|
||||
|
||||
- **现象**：目录字段 `click_key`（鼠标按键，默认 left），实现写死左键单击（`mouse_event(2,...)`按下 + `mouse_event(4,...)`弹起）。
|
||||
- **后果**：右键菜单类自动化场景完全无法实现，且不报错（静默按左键执行）。
|
||||
|
||||
### P1-3 OcrOffline_GetOcrTable：输出相关 4 个字段全部无效
|
||||
|
||||
- **现象**：目录字段 `showTable`（保存至数据表）、`isExcel`（保存至Excel）、`excelName`、`excelPath`，实现全部不读取；仅返回按 y 坐标排序的**扁平文本行数组**。
|
||||
- **后果**：「将结果保存至数据表/Excel」的承诺静默不执行；且行内多列文本不拆分（如「鼠标 20」作为一整行文本返回），拿不到结构化表格。
|
||||
|
||||
### P2-1 Image_Find_V1 / Image_Click_V3：「窗口对象」必填但被忽略
|
||||
|
||||
- **现象**：目录要求 `window_obj` 必填、`find_range`（图像查找范围）可选，实现两者都不读取，永远全屏截图查找。
|
||||
- **后果**：用户以为限定了窗口范围，实际全屏找图——找到错误目标（其他窗口的同款图标）或找不到时无从排查。且 window_obj 必填迫使用户必须配置一个无意义的参数。
|
||||
|
||||
### P2-2 Image_Screenshot：「截图范围」「图像来源」字段无效
|
||||
|
||||
- **现象**：目录字段 `pictureSource`（图像来源）、`shotRange`（截图范围），实现不读取，固定全屏（`PrimaryScreen`）。目录里还有 `action/position/position_img` 三个疑似遗留占位字段。
|
||||
- **后果**：只支持全屏截图；另外多显示器环境只截主屏，副屏内容丢失。
|
||||
|
||||
### P3-1 「特征相似度」accuracy2 字段无效
|
||||
|
||||
- Image_Find / Image_Click / Image_Click_V1 的 `accuracy2`（特征相似度）字段，实现不读取。当前实现是纯像素差模板匹配，没有特征匹配层，该字段为冗余配置。
|
||||
|
||||
### P3-2 「展示鼠标移动轨迹」show_track 字段无效
|
||||
|
||||
- Image_Click 全版本的 `show_track` 被忽略。当前实现 SetCursorPos 直接跳转，无轨迹动画。低优先级。
|
||||
|
||||
### P3-3 其他小问题
|
||||
|
||||
- Image_Screenshot 当 `image_path` 为空时输出文件落盘到进程工作目录（不可预期）；因该字段必填，实际风险低，建议加显式校验。
|
||||
- OcrOffline_GetOcrTable 的行排序仅按 y 坐标，同一行内多个文本块不合并、不按 x 排序，多列场景顺序不稳定。
|
||||
|
||||
---
|
||||
|
||||
## 三、实测验证记录（正常部分证据）
|
||||
|
||||
| 测试 | 结果 |
|
||||
|---|---|
|
||||
| GDI 生成测试图（600×200，含「RPA流程测试ABC123」「名称 数量」「鼠标 20」） | 成功 |
|
||||
| Image_Screenshot 截屏逻辑（同款 PowerShell 脚本） | 成功，产物 246KB PNG |
|
||||
| findImage 模板匹配（app_logo_tpl 模板 vs 实时截屏） | 命中 (93,27)，得分 **0.9993** |
|
||||
| OcrOffline_GetOcrTextNew（传入 image_path 时） | 识别结果 `RPA流程测试ABC123\n名称 数量\n鼠标 20` 完全正确 |
|
||||
| OcrOffline_GetOcrTextPosition | 3 行文本坐标 + 置信度（0.999/0.949/0.899）返回正常 |
|
||||
| 找图失败路径 | 正确抛「屏幕中未找到目标图像」并附建议（注：vitest 环境内 PowerShell 受 PATH 限制报 ENOENT，真实应用主进程不受影响） |
|
||||
|
||||
**说明**：OCR 引擎（飞桨）与模板匹配算法本身质量良好，问题集中在**目录字段与实现的键名/功能脱节**——与此前 Office、数据处理组发现的拼接列、单元格格式问题是同一类「接入只对了一半」的缺陷。
|
||||
|
||||
---
|
||||
|
||||
## 四、给同事的修复优先级建议
|
||||
|
||||
1. **先修 P0-1**（GetOcrTextNew 传图键）——1 行改动，组件从不可用变可用
|
||||
2. **再修 P1 三项**（Click 的 position/click_key、GetOcrTable 的输出字段）——都是读键 + 少量分支逻辑
|
||||
3. **P2/P3 可排后**——窗口限定、截图范围属于功能增强，当前行为可接受但建议在 UI 上隐藏无效字段避免误导
|
||||
Loading…
Reference in New Issue
Block a user