

LocalOCR · 功能说明
升级识别引擎不应顺手改坏正在工作的环境。我先得到一份独立候选,确认依赖、逻辑和实际合成识别都合格才切换;旧环境保留自己的代码和验收依据,失败时能检查后回退,而不是只留一个不知道能否运行的目录。
当前情况:9 月 17 日那次演练实际验过新旧识别环境之间的切换、回退和恢复;现役已是 10 月 26 日验收的快照(上一版是 10 月 16 日验收的一版),它们各有自己的验收,但都还没有同样的 Windows 端到端演练(从 Windows 入口真实走一遍识别、切换和回退);完全离线的新电脑安装仍未验证。“上一版”是按切换规则推断的,previous 链接这次没有重新读取;这次也没有重做切换、回滚或离线新机验证。10 月 31 日主线还加了切换成功后清掉更旧环境的代码,只留当前版和上一版;实际清没清没有读到,不能说旧版已经删完。11 月 4 日想再读现役版本,Linux 子系统入口超时,没读到,现役的说法仍停在 10 月 30 日的核对。
现役版本身份与验收回执于 2026-10-30 11:11–11:15(北京时间)只读核对(2026-11-04 09:06–09:14 重读超时),上一版与更早版本的身份和验收以 2026-10-20 07:41 的只读核对为准,其余项目现状截至 2026-10-11 14:00;具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库

LocalOCR · 功能说明
升级识别引擎不应顺手改坏正在工作的环境。我先得到一份独立候选,确认依赖、逻辑和实际合成识别都合格才切换;旧环境保留自己的代码和验收依据,失败时能检查后回退,而不是只留一个不知道能否运行的目录。
当前情况:9 月 17 日那次演练实际验过新旧识别环境之间的切换、回退和恢复;现役已是 10 月 26 日验收的快照(上一版是 10 月 16 日验收的一版),它们各有自己的验收,但都还没有同样的 Windows 端到端演练(从 Windows 入口真实走一遍识别、切换和回退);完全离线的新电脑安装仍未验证。“上一版”是按切换规则推断的,previous 链接这次没有重新读取;这次也没有重做切换、回滚或离线新机验证。10 月 31 日主线还加了切换成功后清掉更旧环境的代码,只留当前版和上一版;实际清没清没有读到,不能说旧版已经删完。11 月 4 日想再读现役版本,Linux 子系统入口超时,没读到,现役的说法仍停在 10 月 30 日的核对。
现役版本身份与验收回执于 2026-10-30 11:11–11:15(北京时间)只读核对(2026-11-04 09:06–09:14 重读超时),上一版与更早版本的身份和验收以 2026-10-20 07:41 的只读核对为准,其余项目现状截至 2026-10-11 14:00;具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库


用途与实际影响
能克隆源码不代表能加载模型,模型目录存在也不代表依赖兼容;一个可响应的服务甚至可能尚未运行过显卡任务。恢复必须回到真实文件与样例,不能用“安装成功”三个字代替可用结果。
我说“试试新版本,但别把能用的旧版弄坏”:系统创建候选并给出质量与身份回执,通过后才停原服务切换;旧版有有效回执才能回滚。网络或模型不足时停在候选阶段,现役环境不被覆盖。
知道当前哪一版实际能识别、上一版能否回退,以及新版本在真实样例上是否通过。已有切换和回退验收仍按原日期说明;全新离线电脑从零恢复还需要另备系统与模型文件。
版本换多了,旧环境会一直占着硬盘。现在新版切换成功后,系统会尝试把更早启用过的环境清掉,只留当前版和上一版,所以随时还有一个能退回去的。还有任务或进程在用、目录身份对不上的不删,从没启用过的候选也不碰;清不掉就记下原因,下次切换或明确说“把旧环境清掉”时再试,切换本身仍算成功。这段代码 10 月 31 日才进主线,实际清理结果还没读到。

用途与实际影响
能克隆源码不代表能加载模型,模型目录存在也不代表依赖兼容;一个可响应的服务甚至可能尚未运行过显卡任务。恢复必须回到真实文件与样例,不能用“安装成功”三个字代替可用结果。
我说“试试新版本,但别把能用的旧版弄坏”:系统创建候选并给出质量与身份回执,通过后才停原服务切换;旧版有有效回执才能回滚。网络或模型不足时停在候选阶段,现役环境不被覆盖。
知道当前哪一版实际能识别、上一版能否回退,以及新版本在真实样例上是否通过。已有切换和回退验收仍按原日期说明;全新离线电脑从零恢复还需要另备系统与模型文件。
版本换多了,旧环境会一直占着硬盘。现在新版切换成功后,系统会尝试把更早启用过的环境清掉,只留当前版和上一版,所以随时还有一个能退回去的。还有任务或进程在用、目录身份对不上的不删,从没启用过的候选也不碰;清不掉就记下原因,下次切换或明确说“把旧环境清掉”时再试,切换本身仍算成功。这段代码 10 月 31 日才进主线,实际清理结果还没读到。

新版本在独立环境里通过实际样例,旧版也确实可回退后才切换,并用 Windows 入口再读一次文件。
候选失败就保留现役版本;旧目录没有有效验证时不宣称可回滚。
缺依赖、模型文件或显卡条件时停在相应步骤,源码目录存在不等于恢复成功。

新版本在独立环境里通过实际样例,旧版也确实可回退后才切换,并用 Windows 入口再读一次文件。
候选失败就保留现役版本;旧目录没有有效验证时不宣称可回滚。
缺依赖、模型文件或显卡条件时停在相应步骤,源码目录存在不等于恢复成功。

在已接入 LocalOCR 的本机 AI 对话中明确提出升级或换机恢复,并说明现役版本与可用模型材料;这属于维护流程。
- 当前安装状态与候选版本
- 可用模型、网络和旧版回执
- 要验证的实际样例


在已接入 LocalOCR 的本机 AI 对话中明确提出升级或换机恢复,并说明现役版本与可用模型材料;这属于维护流程。
- 当前安装状态与候选版本
- 可用模型、网络和旧版回执
- 要验证的实际样例



- pyproject.toml 为 localocr 0.7.0,声明 Python >=3.10,实际运行环境是 Python 3.12.3,安装器固定调用 python3.12;GPU 依赖允许 >=3.3.1,<3.5,而当前锁定和实装为 Paddle 3.4.0/cu129、PaddleOCR 3.7.0、PaddleX 3.7.2,声明和安装分别核对。
- install_wsl.sh 创建 /root/localocr-runtimes/<unique-candidate>,按运行锁文件装依赖并固定源码快照;9 月 24 日后的快照除 app 外也固定 LICENSE、AGENTS 和 scripts/*.ps1(尤其负责路径换算的 windows_paths.ps1)。Python safe-path 与该版本 PYTHONPATH 隔离开发目录,数据 cwd 和输出位置仍保留原项目。
- 安装不加载 GPU 模型也不自动激活。缺模型时明确 download_models.py --allow-heavy,再 validate --allow-heavy 分别验依赖、逻辑和禁用缓存的合成质量;任何源码/依赖/权重变化使验收失效。
- 权重不重复复制到每个 venv,profile 的实际 artifact_paths 参与指纹。新权重独立版本目录,不覆盖仍被 current(当前版本)/previous(上一版本)引用的文件;模型缓存存在、成功加载和实际识别分开。
- manage_runtime.py inspect 返回真实代码和解释器;activate/rollback 在服务停止且接收方自己的回执仍匹配时切换 current/previous 原子链接。现在 current 指向 speed-20261026-0400(10 月 30 日只读核对);previous 链接这次没有重新读取,按切换规则应是原现役 batch-results-20261016,未核实。10 月 20 日核对时 current 指向 batch-results-20261016、previous 指向 memory-fix-20261012-1522,两个链接都在北京时间 10 月 16 日 12:33 前后切换;9 月 24 日的 audit-fixes 快照和 9 月 17 日的 Paddle 3.4.0 版本当时仍留在目录里,但不再被 current/previous 引用。9 月 24 日之后,开发提交 be4d584(9 月 29 日,只改说明文档)和 50af3fa(10 月 1 日,删掉没用到的辅助代码)只是小改;10 月 12 日到 16 日的 54d8505、b5243c0(强模型内存与整机内存预算)、b647551、4937e0d、e52de0f(Windows 入口输出、期限和缺失输入)、0749391(批量中途出错保留已完成结果)随 10 月 16 日快照装进当时的现役;10 月 26 日的 985d750(显卡被占时普通 OCR 改走 CPU、视频帧识别提速)和 b987deb / d9e51bd(启动不再同步扫描任务清单,04:14 合并)随 speed-20261026-0400 装进现役:现役里的 service.py、runtime.py、gpu_broker.py、job_registry.py、model_profiles.json 与源码 SHA-256 逐一相同。Windows 入口仍为 PowerShell 7.3+ 和同一有界 wrapper,旧的可编辑开发安装不能冒充现役版本。
- 退休环境清理(提交 26ffed7,北京时间 10 月 31 日 21:17,docs/UPGRADING.md、scripts/manage_runtime.py):激活成功后,先把原 previous 的目录身份和验收证据原子写入运行根目录的
.retirements.json,切换完成后尝试删除,只保留 current、previous 两代。每个目标重新核对 current/previous、目录设备号和 inode、venv 配置、源码快照和通过回执,并查进程和未结束的作业;活用者或可疑身份保留并写原因;删除中途失败可按原目录身份重试,失败不改变激活回执。显式manage_runtime.py retire可收养操作者确认曾激活的旧环境,从未激活的候选不自动收养;没有新增后台任务。这已在主线源码实现;.retirements.json和实际目录清单 11 月 4 日没读到,不能写成已清理或只剩两代。


- pyproject.toml 为 localocr 0.7.0,声明 Python >=3.10,实际运行环境是 Python 3.12.3,安装器固定调用 python3.12;GPU 依赖允许 >=3.3.1,<3.5,而当前锁定和实装为 Paddle 3.4.0/cu129、PaddleOCR 3.7.0、PaddleX 3.7.2,声明和安装分别核对。
- install_wsl.sh 创建 /root/localocr-runtimes/<unique-candidate>,按运行锁文件装依赖并固定源码快照;9 月 24 日后的快照除 app 外也固定 LICENSE、AGENTS 和 scripts/*.ps1(尤其负责路径换算的 windows_paths.ps1)。Python safe-path 与该版本 PYTHONPATH 隔离开发目录,数据 cwd 和输出位置仍保留原项目。
- 安装不加载 GPU 模型也不自动激活。缺模型时明确 download_models.py --allow-heavy,再 validate --allow-heavy 分别验依赖、逻辑和禁用缓存的合成质量;任何源码/依赖/权重变化使验收失效。
- 权重不重复复制到每个 venv,profile 的实际 artifact_paths 参与指纹。新权重独立版本目录,不覆盖仍被 current(当前版本)/previous(上一版本)引用的文件;模型缓存存在、成功加载和实际识别分开。
- manage_runtime.py inspect 返回真实代码和解释器;activate/rollback 在服务停止且接收方自己的回执仍匹配时切换 current/previous 原子链接。现在 current 指向 speed-20261026-0400(10 月 30 日只读核对);previous 链接这次没有重新读取,按切换规则应是原现役 batch-results-20261016,未核实。10 月 20 日核对时 current 指向 batch-results-20261016、previous 指向 memory-fix-20261012-1522,两个链接都在北京时间 10 月 16 日 12:33 前后切换;9 月 24 日的 audit-fixes 快照和 9 月 17 日的 Paddle 3.4.0 版本当时仍留在目录里,但不再被 current/previous 引用。9 月 24 日之后,开发提交 be4d584(9 月 29 日,只改说明文档)和 50af3fa(10 月 1 日,删掉没用到的辅助代码)只是小改;10 月 12 日到 16 日的 54d8505、b5243c0(强模型内存与整机内存预算)、b647551、4937e0d、e52de0f(Windows 入口输出、期限和缺失输入)、0749391(批量中途出错保留已完成结果)随 10 月 16 日快照装进当时的现役;10 月 26 日的 985d750(显卡被占时普通 OCR 改走 CPU、视频帧识别提速)和 b987deb / d9e51bd(启动不再同步扫描任务清单,04:14 合并)随 speed-20261026-0400 装进现役:现役里的 service.py、runtime.py、gpu_broker.py、job_registry.py、model_profiles.json 与源码 SHA-256 逐一相同。Windows 入口仍为 PowerShell 7.3+ 和同一有界 wrapper,旧的可编辑开发安装不能冒充现役版本。
- 退休环境清理(提交 26ffed7,北京时间 10 月 31 日 21:17,docs/UPGRADING.md、scripts/manage_runtime.py):激活成功后,先把原 previous 的目录身份和验收证据原子写入运行根目录的
.retirements.json,切换完成后尝试删除,只保留 current、previous 两代。每个目标重新核对 current/previous、目录设备号和 inode、venv 配置、源码快照和通过回执,并查进程和未结束的作业;活用者或可疑身份保留并写原因;删除中途失败可按原目录身份重试,失败不改变激活回执。显式manage_runtime.py retire可收养操作者确认曾激活的旧环境,从未激活的候选不自动收养;没有新增后台任务。这已在主线源码实现;.retirements.json和实际目录清单 11 月 4 日没读到,不能写成已清理或只剩两代。

- 当前没有能由已有证据证明的完整离线重建包,也没有把所有 Python 依赖、WSL(Windows 的 Linux 子系统)系统和模型权重打成已验收的单个恢复工件。10 月 11 日只读统计本机模型缓存为 18 个目录、共 3.9 GiB,只说明文件还在,不证明今天全部能重新加载。


- 当前没有能由已有证据证明的完整离线重建包,也没有把所有 Python 依赖、WSL(Windows 的 Linux 子系统)系统和模型权重打成已验收的单个恢复工件。10 月 11 日只读统计本机模型缓存为 18 个目录、共 3.9 GiB,只说明文件还在,不证明今天全部能重新加载。



| 名词 | 意思 |
|---|---|
| venv(Python 独立环境) | 隔离项目依赖的现有运行目录,不是模型权重的替代品。 |
| model cache(模型缓存) | 本机保存的模型文件;存在性、可加载与识别效果是三层不同证据。 |
| smoke test(小样例运行检查) | 让指定文件经真实入口走到结果,验证一条具体路线;不是全面准确率基准。 |

把代码、依赖和模型身份作为同一运行版本管理;能回滚升级,不等于已有断网新机的一键恢复包。



把代码、依赖和模型身份作为同一运行版本管理;能回滚升级,不等于已有断网新机的一键恢复包。

- Python 包或模型配置不兼容: 保留实际版本与异常,定位对应依赖/适配器,不盲目批量升级。
- 模型缓存缺失: 按已选模型定位所需工件;取得模型与是否运行重型预热分开判断。
- 服务在线但模型任务没跑通: 仅报告服务可达,继续把模型路线标成未验收。
- 只有源码却要求完全离线恢复: 明确还缺依赖、WSL(Windows 的 Linux 子系统) 和模型工件,不虚构已存在的恢复包。

- Python 包或模型配置不兼容: 保留实际版本与异常,定位对应依赖/适配器,不盲目批量升级。
- 模型缓存缺失: 按已选模型定位所需工件;取得模型与是否运行重型预热分开判断。
- 服务在线但模型任务没跑通: 仅报告服务可达,继续把模型路线标成未验收。
- 只有源码却要求完全离线恢复: 明确还缺依赖、WSL(Windows 的 Linux 子系统) 和模型工件,不虚构已存在的恢复包。

- 当前依赖声明
- 联网安装路径
- 显式重型预热
- WSL(Windows 的 Linux 子系统) 运行入口
- 具体模型与选项
- 真实解释器/源码身份与 validate、activate、rollback 入口
- 独立候选、验收、原子激活与由旧版本自证的回滚合同
- 现役 10 月 26 日快照(speed-20261026-0400)验收:北京时间 10 月 26 日 04:05:49 开始、用时约 139 秒,依赖、单元测试、质量三步退出码都是 0,验收期间环境保持不变;单元测试共 206 项、19 项按条件跳过。这是 10 月 26 日的历史回执,不是今天重跑;现役验收目录里没有读到 Windows 端到端回执。10 月 30 日 11:11 左右和 11 月 4 日 09:06–09:14 本机服务健康检查都被拒绝连接,只说明那一刻服务没有在监听;11 月 4 日只读 inspect 现役版本返回 HCS_E_CONNECTION_TIMEOUT,current、previous 和退休清单都没读到;这次没有启动服务或模型,此刻是否在线仍未验证,不能由已安装就推成在线,也不说明安装损坏。
- 之前的 10 月 16 日快照验收:北京时间 10 月 16 日 12:29:59 开始、用时约 179 秒,依赖、单元测试、质量三步退出码都是 0;187 项单元测试 170 项通过、17 项按条件跳过、0 项失败;禁用缓存的 9 个合成质量案例全部满足各自门槛,两页 VL 案例字符错误率仍是 1.33%,验收目录里同样没有 Windows 端到端回执。更早的 10 月 12 日快照验收:183 项单元测试、16 项按条件跳过、0 项失败。
- 9 月 24 日快照(当时现役)验收:181 项单元测试 165 项通过、16 项按条件跳过、0 项失败;禁用缓存的 9 个合成质量案例全部满足各自门槛,其中两页 VL 案例字符错误率仍是 1.33%,质量通过不等于零错。回执 SHA-256:acceptance 为 b8108918f6dd6e1d198d994650ac878adc67b0827d8142f15c0d0affd808e084,quality 为 f6b2992b585be305e4641d03dcc5dbbb0ff2dd2ed02955ec66d78a0514fe7070,单元测试日志为 1c65c402192327e844e00338300d1eb52a0489bad40bfbf2f2f3e679dca7368d。它的验收目录里也没有 Windows 端到端回执。

- 当前依赖声明
- 联网安装路径
- 显式重型预热
- WSL(Windows 的 Linux 子系统) 运行入口
- 具体模型与选项
- 真实解释器/源码身份与 validate、activate、rollback 入口
- 独立候选、验收、原子激活与由旧版本自证的回滚合同
- 现役 10 月 26 日快照(speed-20261026-0400)验收:北京时间 10 月 26 日 04:05:49 开始、用时约 139 秒,依赖、单元测试、质量三步退出码都是 0,验收期间环境保持不变;单元测试共 206 项、19 项按条件跳过。这是 10 月 26 日的历史回执,不是今天重跑;现役验收目录里没有读到 Windows 端到端回执。10 月 30 日 11:11 左右和 11 月 4 日 09:06–09:14 本机服务健康检查都被拒绝连接,只说明那一刻服务没有在监听;11 月 4 日只读 inspect 现役版本返回 HCS_E_CONNECTION_TIMEOUT,current、previous 和退休清单都没读到;这次没有启动服务或模型,此刻是否在线仍未验证,不能由已安装就推成在线,也不说明安装损坏。
- 之前的 10 月 16 日快照验收:北京时间 10 月 16 日 12:29:59 开始、用时约 179 秒,依赖、单元测试、质量三步退出码都是 0;187 项单元测试 170 项通过、17 项按条件跳过、0 项失败;禁用缓存的 9 个合成质量案例全部满足各自门槛,两页 VL 案例字符错误率仍是 1.33%,验收目录里同样没有 Windows 端到端回执。更早的 10 月 12 日快照验收:183 项单元测试、16 项按条件跳过、0 项失败。
- 9 月 24 日快照(当时现役)验收:181 项单元测试 165 项通过、16 项按条件跳过、0 项失败;禁用缓存的 9 个合成质量案例全部满足各自门槛,其中两页 VL 案例字符错误率仍是 1.33%,质量通过不等于零错。回执 SHA-256:acceptance 为 b8108918
f6dd6e1d 198d9946 50ac878a dc67b082 7d8142f1 5c0d0aff d808e084,quality 为 f6b2992b 585be305 e4641d03 dcc5dbbb 0ff2dd2e d02955ec 66d78a05 14fe7070,单元测试日志为 1c65c4021 92327e84 4e003383 00d1eb52 a0489bad 40bfbf2f 2f3e679d ca7368d。它的验收目录里也没有 Windows 端到端回执。

- 9 月 17 日那一版(当时的上一版,现已不是 previous):冻结环境验收 174 普通通过/1 跳过、九个合成质量案例全部满足各自门槛。它的 windows-end-to-end.json 绑定 3a4bf13,真实走过 Paddle 3.4.0→3.3.1→3.4.0 切换及代码身份核对,普通 OCR(光学字符识别)首次 27.951 秒/缓存 1.284 秒,停止和重启通过,最终按需停止;回执也如实保留了第一次发布脚本退出码 1、修正后退出码 0 的过程。演练里的 3.3.1 是当时保留的旧环境,不是现在的 previous;从 9 月 24 日版起,包括 10 月 12 日、10 月 16 日两版和现役 10 月 26 日版,都还没有做过同等演练,这次也没有重做切换、回滚或离线新机验证。
- 9 月 17 日那一版的 acceptance/quality/Windows 端到端回执 SHA-256 分别为 4204f7d2291f205c799dfb6fc6a016cdfb06c2b365a1eeff682bec823ea7b757、a34aef982c321e28e951afa9d0efea815632f4d1050018d08e635332c3c88953、55156bed06e712ad3c87d3f1c99241046e4341204c057c3c1f55199cabf98d62;它们只证明 9 月 17 日那一版,不能当作现役的验证,也不证明干净断网新机或任意真实文档质量。
本模块恢复可执行环境;输入路线决定实际任务,运行层管理资源,最终仍由输出与原图复核证明用户拿到了什么。

- 9 月 17 日那一版(当时的上一版,现已不是 previous):冻结环境验收 174 普通通过/1 跳过、九个合成质量案例全部满足各自门槛。它的 windows-end-to-end.json 绑定 3a4bf13,真实走过 Paddle 3.4.0→3.3.1→3.4.0 切换及代码身份核对,普通 OCR(光学字符识别)首次 27.951 秒/缓存 1.284 秒,停止和重启通过,最终按需停止;回执也如实保留了第一次发布脚本退出码 1、修正后退出码 0 的过程。演练里的 3.3.1 是当时保留的旧环境,不是现在的 previous;从 9 月 24 日版起,包括 10 月 12 日、10 月 16 日两版和现役 10 月 26 日版,都还没有做过同等演练,这次也没有重做切换、回滚或离线新机验证。
- 9 月 17 日那一版的 acceptance/quality/Windows 端到端回执 SHA-256 分别为 4204f7d2291f
205c799d fb6fc6a0 16cdfb06 c2b365a1 eeff682b ec823ea7 b757、a34aef98 2c321e28 e951afa9 d0efea81 5632f4d1 050018d0 8e635332 c3c88953、55156bed06e71 2ad3c87d 3f1c9924 1046e434 1204c057 c3c1f551 99cabf98 d62;它们只证明 9 月 17 日那一版,不能当作现役的验证,也不证明干净断网新机或任意真实文档质量。
本模块恢复可执行环境;输入路线决定实际任务,运行层管理资源,最终仍由输出与原图复核证明用户拿到了什么。
复制 AI 续作说明
项目:升级先验候选,出问题能回到真正验证过的旧版本;仓库:wlyaaaaa/LocalOCR;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。








