SnapOCR v1.0.3

SnapOCR v1.0.3 是稳定性与正确性修复版：功能与界面没有变化，修掉 22 个缺陷 —— 其中 2 个会让程序在特定操作下崩溃或永久失效，1 个会把导出的表格悄悄写错列，1 个让长截图在真实网页上拼不出来。另外把 docx 导出提速 123 倍。

从 v1.0.1 或更早版本升级的用户，请先看 v1.0.2 的说明：那一版修的是「双击没反应」，本版是在它基础上的进一步收敛。

🛡️ 会让程序崩掉 / 失效的

• 关闭程序时后台还有任务在跑 → 进程崩溃：批量识别、PDF 识别、翻译中直接点关闭，正在运行的线程被析构，进程 abort，用户看到的是「程序突然消失」。现在会先请求可取消的任务收手，再给它们 3 秒收尾时间，超时的等它自然结束后再退出。实测批量处理 5 张图中退出：2.0 秒干净退出，退出码 0（修复前退出码 127）。
• 截图遮罩被 Alt+F4 关掉后，「立即截图」永久没反应：用任何非 Esc 的方式关掉遮罩，主窗口仍以为截图还在进行中，之后每次触发都被判定为「正在截图」而直接忽略，只能重启程序。长截图的控制条同理会永久拦住下一次截图。现在两个控件关闭时都会补发取消信号，主窗口也会检测对象是否已销毁并自动恢复状态。

📊 导出的表格会错列

• 表格某行某格没有文字 → 整列左移：原来的列边界是「词与词间隙的中点」，缺一个字就少一根边界，右侧所有单元格往前顶一格。3 列表格导出 Excel 后，第 3 列的数据跑到第 2 列，且没有任何提示。现在改成按「单元格水平区段重叠合并」生成全局列带，每行的列数恒定等于总列数，空格留空串。
• 列挨得很紧的表格会被并成一列：切列阈值原来绑死在「0.9 倍字高」，密集排版、小字号截图就整片并成一列。现在按「全表没有任何文字跨过的竖直空白缝」切列 —— 缝宽与字高无关，5 px 的缝也能切对；同时允许少量行跨过缝隙，表头合并单元格不会被多切一列。

🖼️ 长截图

• 页面上有视频、滚动条、走秒的时钟 → 拼接直接失败，长图里出现整段重复内容。根因有三层：模板取新帧顶部 100 px，正好压着动态内容时它本身就是噪声；重叠区平均差超过阈值就整体判「拼不上」；相关系数门槛对动态画面过于苛刻。现在改为：缩略图粗搜（噪点被平均掉、排版结构还在）+ 多候选复评 + 「逐列差异比例中位数」判定（对得齐时只有动态那几列不齐，对不齐时整体都差）+ 动态列自动屏蔽。实测页面有 22% 面积的固定视频时，拼接结果从 2400 px（5 次整帧追加）变成 900 px（5 次正常重叠）。
• 大片纯色区域让长截图提前结束：纯色模板在模板匹配里处处得 1.0，位置退化到 (0,0)，连续几帧后被判「页面已到底」。现在先做纹理预检，再做像素级复核。

⚡ 性能

• docx 导出 10 万行要 419 秒：add_paragraph() 是 O(n) 插入，整体退化成 O(n²)。改为直接构造 XML 节点插入，线性写入 —— 10 万行 3.4 秒，提速 123 倍，回读 10 万段内容逐字一致。
• 启动后 1–3 秒内改任何设置，整窗冻结近 2 秒：改设置会重建识别引擎，而重建要抢一把正被预热线程持有的锁。现在改为无锁清引用 + 版本号校验，改设置立即返回。
• 超大 PDF 页面撑爆内存：4000×5000 pt 的页面按原比例渲染会生成 8000×10000 的位图，单页常驻内存 +306 MB。现在按「单边 4096 像素、总量 1600 万像素」钳制，同一页面降到 3276×4096。

🖥️ 多屏与单实例

• 混合 DPI 多屏，跨屏截图有 1–2 px 接缝：整块虚拟桌面原来只用一个统一缩放比，两块屏 DPI 不同时这个值等于加权平均 —— 100% 的屏被放大、125% 的屏被压缩，右半边文字发虚、边缘错位。现在逐屏配对，每块屏用自己的物理/逻辑比例绘制与裁剪。实测「左屏 1:1 + 右屏 2:1」布局下，分界线从错误的 x≈33 回到正确的 x=50。
• 125% 缩放下长截图控制条跑到屏幕外：控制条原来按物理像素摆位，而 Qt 的窗口定位用逻辑坐标，缩放后直接飞出屏幕点不到。现在改用逻辑坐标 + 所在屏幕判断 + 边界夹取。
• 同时启动两个实例，单实例保护失效：两个进程几乎同时启动时双方都还没开始监听，互相探不到，结果双双启动（两套全局热键钩子、两份历史互相覆盖）。现在改用内核互斥体仲裁，本地套接字只负责「唤起已运行的窗口」。实测并发启动 3 个只活 1 个，第二个实例 0.8 秒退出。

🔧 其它加固

• 「截图贴图」开关此前完全没生效（代码里没有任何地方读取它），现在生效。
• 长截图预览里的「识别」按钮会绕过 OCR 忙碌检查，导致两个任务抢同一个引擎，现在纳入统一检查。
• 拖入 PDF 文件时不检查「PDF 识别」开关状态，现在会提示并拒绝。
• PDF 识别正常完成后进度框可能误触发「已取消」，现在先断开信号再复位。
• Ctrl+A, Ctrl+B 这类多段组合热键会被校验放行，但底层键盘库不支持，现在明确拒绝。
• Excel 导出中以 = 开头的文本会被写成公式（公式注入），现在按纯文本写入。
• 识别结果里含 \x00 等 XML 非法控制字符会让 docx 导出直接抛异常，现在过滤后正常导出。
• 翻译功能在语言配置缺失时会抛 StopIteration 使对话框崩溃，现在回落到第一个可用语言。
• 保存文件时没写扩展名会存成无后缀文件，现在按所选格式补 .txt / .docx / .xlsx。
• 抓屏失败（权限、远程桌面、锁屏）以前只写日志，界面上毫无反应，现在会弹窗说明。

📦 下载说明

文件	说明
SnapOCR-v1.0.3-win64.7z	推荐：onedir 绿色包，解压一次即用，启动约 2.5 秒
SnapOCR-v1.0.3-win64.zip	与 7z 内容逐字节相同，只是容器不同；给 winget（只认 zip）用，手工安装用 7z 更省 35 MB
SnapOCR.exe	单文件版，双击即用。⚠ 实测有约 13% 概率启动失败（onefile 解压问题），不建议日常使用，见下方说明
*.sha256	SHA-256 校验文件

系统要求：Windows 10/11 x64。默认简体中文模型已内置，识别全程离线；切换到繁中 / 英 / 日 / 韩时首次会下载对应模型（只下载模型文件，不上传任何截图或识别文本），之后离线可用。

SHA-256 校验值：

SnapOCR-v1.0.3-win64.7z
29fec864e619aeff605c1dd11c3ed7b4693d7c72153f116dffc06c476be55177

SnapOCR-v1.0.3-win64.zip
d6fdf2b05660a6a796183552cfd2166c4e1ed2c8a3344d455ee633d197a75591

SnapOCR.exe
68dbec68c8bb8934e045e2ab324d609938acf999ee0e54df4d8bda2c683a5abf

⚠️ 关于单文件版 SnapOCR.exe

它是 PyInstaller onefile 打包，每次启动都要把 155 MB 解压到临时目录。本机（Windows 11 x64）
实测 52 次启动失败 7 次（13.5%），表现为双击后没有任何窗口、退出码 127
（ERROR_PROC_NOT_FOUND）。把临时目录换到另一块盘仍然 3/20 失败，所以与磁盘无关；
同一份 onedir 产物 20 次启动 0 次失败。日常使用请下载 7z 或 zip 绿色包。

这个 zip 资产就是为此新增的：winget 的 SnapOCR 清单改走 zip + onedir，不走单文件版。

⬆️ 要不要升级

建议都升。 下面这些都不是极端操作，但 v1.0.2 会出问题：

• 批量识别/PDF 识别还没跑完就关程序 → 进程崩溃；
• 用 Alt+F4 关掉截图遮罩 → 之后截图功能一直没反应，只能重启；
• 识别带空单元格的表格并导出 Excel → 数据悄悄错列；
• 长截图一个带视频或滚动条的网页 → 拼不出来，出来一堆重复内容；
• 导出几万行文本为 docx → 等几分钟；
• 双屏且缩放比不同屏不同 → 跨屏截图边缘发虚。

⚠️ SmartScreen 提示

本程序暂未做代码签名，首次运行可能弹出「Windows 已保护你的电脑」。点「更多信息 → 仍要运行」即可，建议先用上方校验值核对文件完整性。介意的话可从源码自行构建（Python 3.10+）：pip install -r requirements.txt && python entry.py。

📝 反馈

识别不准、有 bug、想要新功能？欢迎提 Issue，附上截图（脱敏后）和期望文本是最有效的反馈方式。完整测试报告见仓库 docs/QA-REPORT-2026-11-06.md（第 7 章与第 8 章为本版修复记录）。

SnapOCR v1.0.2

SnapOCR v1.0.2 是稳定性修复版：功能与界面没有变化，修掉 18 个缺陷，其中 3 个会让程序「双击没反应」，3 个会在长时间任务里把界面卡住或让数据悄悄丢掉。

🛡️ 修好了「双击没反应」

• 历史文件被改坏就打不开程序：history.json 里只要有一条结构不对（手工编辑、磁盘写坏、旧版本残留），构造窗口时就抛异常，进程直接退出、连报错窗口都没有。现在逐条校验，坏记录跳过并在状态栏提示「已跳过 N 条」，11 组脏数据全部能正常启动。
• 设置文件里快捷键写错也打不开：settings.json 的 hotkey_capture 变成 null、数字或数组时，拼提示文字时 .upper() 直接崩。现在逐项类型兜底，非法值回落到默认的 Ctrl+Alt+Q，9 组脏数据全部正常启动。
• 双开互相覆盖历史：同时开两个实例时，两边各自持有全量历史、退出时全量重写，后写的把先写的记录永久抹掉，还会出现一次热键弹出两个遮罩。现在程序是单实例的：再次双击只是把已有窗口唤到前台。需要刻意多开排查问题可以加 --multi。

🚀 修好了「卡住 / 占内存 / 静默失效」

• 导出大文件时界面整段冻住：PDF / docx 渲染原来在主线程同步跑，10 万行 PDF 要 137 秒，期间窗口无法拖动。现在整体搬到后台线程：77 万字符导出时 start() 1 毫秒返回；超过 20 万字会先提示预计耗时；进度框可取消，取消后会删掉半成品文件。
• 批量识别一次性把图片全读进内存：500 张 1080p 会常驻 600 MB 以上，读盘还在 GUI 线程里做，点下去界面先卡 1 秒。现在只把路径交给线程，线程逐张读、逐张识别，并显示「第 x/y 张：文件名」进度。
• PDF 识别点了「取消」没反应：取消后不发任何信号，进度框留在屏幕上下不去。现在取消必定发信号、关框、提示「已取消」。
• 改快捷键失败却提示「已保存」：注册失败被静默吞掉，用户以为生效了、实际热键全废。现在失败会回滚到上一次真正注册成功的组合并弹窗说明（提示文案按平台区分：Linux 需 root、macOS 需辅助功能权限）。
• 单个按键也能被注册成热键：把热键设成 A 或 F1 会把全系统这个键劫持掉，打字都在截图。现在保存前校验必须是「修饰键 + 普通键」，A / F1 / Ctrl+Shift 一律拒绝。

🔧 其它加固

• 历史写入改「临时文件 + 原子替换 + fsync」：磁盘写满或断电不会把已有记录截断成半个 JSON，写失败会提示而不是静默丢失。
• 截图遮罩改为覆盖整个虚拟桌面，副屏在主屏左侧/上方（坐标为负）时选区不再偏移；长截图回传绝对物理坐标。
• 零尺寸图片不再触发除零；灰度 / 四通道截图统一转成三通道再识别。
• 超长单行文本翻译会循环分块（每段 ≤5000 字符），不会再发出超限请求被接口拒绝。
• 预热失败（模型缺失、目录不可写）会在状态栏说明，不再静默。
• 空内容不再导出空白文件；Excel 导出跳过空行；旧版本识别结果结构异常时容错。

📦 下载说明

文件	说明
SnapOCR-v1.0.2-win64.7z	推荐：onedir 绿色包，解压一次即用，启动约 2.5 秒
SnapOCR.exe	单文件版，双击即用（每次启动要自解压 160 MB，约 11–16 秒）
*.sha256	SHA-256 校验文件

系统要求：Windows 10/11 x64。默认简体中文模型已内置，识别全程离线；切换到繁中 / 英 / 日 / 韩时首次会下载对应模型（只下载模型文件，不上传任何截图或识别文本），之后离线可用。

SHA-256 校验值：

SnapOCR-v1.0.2-win64.7z
40bd0c545cd41d360b3fc72755b7b89fac566178c4d02694e1db2ba18af7570e

SnapOCR.exe
ef694b4a52ac28679a70594129ef461d8cacd6e9f21e661324aec6c44d8bd50c

⬆️ 要不要升级

建议都升。 v1.0.1 在下面这些情况下会出问题，而它们都不是极端操作：

• 用过一段时间的 history.json 恰好有一条坏记录 → 打不开；
• 手工改过设置里的快捷键（写错格式）→ 打不开；
• 习惯开两个窗口对照着用 → 历史会莫名少记录；
• 导出大段内容、批量识别几十张图 → 界面冻结几十秒。

⚠️ SmartScreen 提示

本程序暂未做代码签名，首次运行可能弹出「Windows 已保护你的电脑」。点「更多信息 → 仍要运行」即可，建议先用上方校验值核对文件完整性。介意的话可从源码自行构建（Python 3.10+）：pip install -r requirements.txt && python entry.py。

📝 反馈

识别不准、有 bug、想要新功能？欢迎提 Issue，附上截图（脱敏后）和期望文本是最有效的反馈方式。完整测试报告见仓库 docs/QA-REPORT-2026-11-06.md。

SnapOCR v1.0.1

SnapOCR v1.0.1 补丁版：修两个实际会踩到的问题，功能没有变化。

🐞 修复

• 表格识别导出的 Excel 里字被拆开：原先单元格内按字符切分后用空格拼接，姓名 会变成 姓 名、苹果 变成 苹 果。现在跟随「智能排版」设置压缩汉字之间的空格（英文单词与数字之间的间隔保留），姓名 / 苹果 / 香蕉 原样输出。
• 贴图关掉后再贴第二张，贴图不出来：贴图窗口关闭时立即销毁（WA_DeleteOnClose），主窗口却还留着旧引用，第二次贴图遍历列表时抛 RuntimeError，新贴图创建不出来。现在清理列表时跳过已销毁的窗口。

📄 文档校正

• 1080p 全屏识别耗时从「约 7 秒」改为「约 7–10 秒（视 CPU 与文字密度）」。实测 1920×1080 深色代码图 38 行约 9.8 秒，原先写小了。
• 下载文件名同步为 v1.0.1。

📦 下载说明

文件	说明
SnapOCR-v1.0.1-win64.7z（115 MB）	推荐：onedir 绿色包，解压一次即用，启动快
SnapOCR.exe（155 MB）	单文件版，双击即用（每次启动要自解压，较慢）
*.sha256	SHA-256 校验文件

系统要求：Windows 10/11 x64。默认简体中文模型已内置，识别全程离线；切换到繁中 / 英 / 日 / 韩时首次会下载对应模型（只下载模型文件，不上传任何截图或识别文本），之后离线可用。

SHA-256 校验值：

SnapOCR-v1.0.1-win64.7z
2bb9c437aa4831a91bc0202dc1e4b42166c65b412698feb80aadb8de5db312c6

SnapOCR.exe
338d059232fd22205b5bc19a9a84a67bc81410b3c08e69734b704d5167c2553a

⬆️ 要不要升级

会用表格识别导出 Excel，或者会连着贴多张图 → 建议升。其余情况 v1.0.0 继续用没有问题，功能上没有差别。

⚠️ SmartScreen 提示

本程序暂未做代码签名，首次运行可能弹出「Windows 已保护你的电脑」。点「更多信息 → 仍要运行」即可，建议先用上方校验值核对文件完整性。介意的话可从源码自行构建（Python 3.10+）：pip install -r requirements.txt && python entry.py。

📝 反馈

识别不准、有 bug、想要新功能？欢迎提 Issue，附上截图（脱敏后）和期望文本是最有效的反馈方式。

SnapOCR v1.0.0

SnapOCR v1.0.0 首个正式版发布。

✨ 功能亮点

• 截图识别：Ctrl+Alt+Q 框选即识别、即复制，全程本地离线，截图不出本机
• 深色截图增强：深色 IDE / 暗色网页自动反色 + CLAHE 对比度增强，自带工具容易漏检的场景专用
• 可搜索历史：每次识别自动存档，关键词即时过滤、浮窗预览、双击再次复制
• 截屏翻译：Ctrl+Alt+T 框选即译，11 种语言互译（必应翻译 + MyMemory，免 Key）
• 长截图：Ctrl+Alt+L 自动滚动拼接整页
• PDF 整档识别：拖入 PDF 逐页识别，进度可取消
• 表格识别：框选表格 → 行列矩阵 → 一键导出 Excel
• 截图贴图：截图钉在桌面置顶，滚轮缩放、Ctrl+滚轮调透明度
• 批量识别：文件夹拖入排队识别（递归、去重、上限 500 张）
• 多语言：内置简体中文模型，离线即用；繁中 / 英 / 日 / 韩首次切换时会联网下载对应识别模型，下载后本地缓存、之后离线可用
• 导出：txt / docx / pdf / md / xlsx
• 二维码兜底：区域内无文字时自动解码二维码

📦 下载说明

文件	说明
SnapOCR-v1.0.0-win64.7z（113 MB）	推荐：onedir 绿色包，解压一次即用，启动快（单文件 exe 每次启动要自解压 160 MB）
SnapOCR.exe（153 MB）	单文件版，双击即用
*.sha256	SHA-256 校验文件
compare-dark-ui.png / hero-15s.gif	深色增强对比图 / 15 秒串联演示（宣传素材）

系统要求：Windows 10/11 x64。无需安装 Python；默认简体中文模型已内置，识别全程离线。首次切换到繁中 / 英 / 日 / 韩时会联网下载对应识别模型（只下载模型文件，不上传任何截图或识别文本），之后离线可用。

SHA-256 校验值：

SnapOCR-v1.0.0-win64.7z
57b6810ee3626ba06f9227741ec4b7640f308057bbde9c294f4fd8b45ae75127

SnapOCR.exe
211267420dd489330ef0ed5799b8d6a8c97f20aee71b1714e33fc19748cb7afb

⚠️ SmartScreen 提示

本程序暂未做代码签名，首次运行可能弹出「Windows 已保护你的电脑」。点「更多信息 → 仍要运行」即可，建议先用上方校验值核对文件完整性。介意的话可从源码自行构建（Python 3.10+）：pip install -r requirements.txt && python entry.py。

📝 反馈

识别不准、有 bug、想要新功能？欢迎提 Issue，附上截图（脱敏后）和期望文本是最有效的反馈方式。