

LocalOCR · 功能说明
同一份资料已经处理过时,能复用就不再等模型;正在处理时,我能知道它在哪一步,而不是反复按提交。这个模块把原件、请求和结果对在一起,让省时不会变成拿错旧文件。
当前情况:已有任务定位和结果复验功能,可避免重复提交;旧结果只有仍对应同一原件与运行条件才复用。显卡算出的结果和显卡被占时改用处理器(CPU)算出的结果分开登记,不会互相冒用。输出文件已经不在的完成记录,现在由后台在服务开着时每天最多清理一次,所以任务清单只是现存还能核对的记录,不是“一共做过多少次”的永久台账。要看最近的任务,由 AI 直接读任务记录;单独的观察接口 10 月 20 日已取消,查单个任务和精确取消都还在。
项目现状截至 2026-10-11 14:00(北京时间),于同日 16:30–16:48 只读核对;任务清单清理与设备分开登记按 10 月 26 日 04:14 合并进主线、并已装进现役版本的源码说明;具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库

LocalOCR · 功能说明
同一份资料已经处理过时,能复用就不再等模型;正在处理时,我能知道它在哪一步,而不是反复按提交。这个模块把原件、请求和结果对在一起,让省时不会变成拿错旧文件。
当前情况:已有任务定位和结果复验功能,可避免重复提交;旧结果只有仍对应同一原件与运行条件才复用。显卡算出的结果和显卡被占时改用处理器(CPU)算出的结果分开登记,不会互相冒用。输出文件已经不在的完成记录,现在由后台在服务开着时每天最多清理一次,所以任务清单只是现存还能核对的记录,不是“一共做过多少次”的永久台账。要看最近的任务,由 AI 直接读任务记录;单独的观察接口 10 月 20 日已取消,查单个任务和精确取消都还在。
项目现状截至 2026-10-11 14:00(北京时间),于同日 16:30–16:48 只读核对;任务清单清理与设备分开登记按 10 月 26 日 04:14 合并进主线、并已装进现役版本的源码说明;具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库


用途与实际影响
文件同名不代表内容相同,输出还在也不代表它完整。客户端窗口超时还可能留下正在执行的工作;如果不先定位任务就重试,会重复占用显卡,还可能混淆两次结果。
我可以问:“刚才那份扫描件等超时了,现在要不要重新提交?”系统会先查原任务:仍在处理就继续等待或由我取消,已经完成就直接读取结果,确实中断才明确说明。它不会因为窗口等超时就重复跑一份。
先得到原任务现在是处理中、完成还是中断;完整旧结果能核对时直接取回,否则才决定重新识别。部分页面证据可以帮助排查,但不是任何故障都能自动续跑。
旧结果与这份文件和要求确实相同、文件完整时直接复用。
等待窗口超时先查原任务,取消或中断后留下状态,不盲重交。
任务仍占资源或连终态都无法确认时停止新提交,先核对现场。

用途与实际影响
文件同名不代表内容相同,输出还在也不代表它完整。客户端窗口超时还可能留下正在执行的工作;如果不先定位任务就重试,会重复占用显卡,还可能混淆两次结果。
我可以问:“刚才那份扫描件等超时了,现在要不要重新提交?”系统会先查原任务:仍在处理就继续等待或由我取消,已经完成就直接读取结果,确实中断才明确说明。它不会因为窗口等超时就重复跑一份。
先得到原任务现在是处理中、完成还是中断;完整旧结果能核对时直接取回,否则才决定重新识别。部分页面证据可以帮助排查,但不是任何故障都能自动续跑。
旧结果与这份文件和要求确实相同、文件完整时直接复用。
等待窗口超时先查原任务,取消或中断后留下状态,不盲重交。
任务仍占资源或连终态都无法确认时停止新提交,先核对现场。

在同一 LocalOCR 对话中提供刚才返回的任务标识,先问“现在进行到哪”;不要仅凭等待窗口超时重新提交。
- 原任务标识或原件
- 本次识别要求
- 继续等待还是取消的选择


在同一 LocalOCR 对话中提供刚才返回的任务标识,先问“现在进行到哪”;不要仅凭等待窗口超时重新提交。
- 原任务标识或原件
- 本次识别要求
- 继续等待还是取消的选择



- 任务身份绑定源路径/内容、请求语义、逐页路由、具体 profile、实际权重、实现/运行库、实际计算设备(GPU 或 CPU)和输出目录;开发源码改变不自动改变已激活冻结版本。Device=auto 因显卡被占改走 CPU 时,先查同一请求在显卡上和在 CPU 上是否已有有效结果,命中就直接复用;新算出的 CPU 结果按 CPU 身份另行登记,不改名冒充显卡结果。
- service.py 在正式写盘前后维护任务状态,复用时检查客观文件及所有输出的非空大小和 SHA-256,不只判断文件存在。
- 正式文件名包含请求身份;无哈希同名 TXT/MD/JSON 仅供兼容展示,不能作为缓存或原件身份依据。
- server.py 暴露 /jobs/<job_key> 与指定 cancel 入口;active_localocr_task 返回 409,调用方应读取原任务,不隐式新建队列。
- 增强或执行失败可以保存首轮文字与 checkpoints.py 的逐页部分证据,仍是 partial 而非完整成功缓存;取消响应标 terminal/non-retryable。


- 任务身份绑定源路径/内容、请求语义、逐页路由、具体 profile、实际权重、实现/运行库、实际计算设备(GPU 或 CPU)和输出目录;开发源码改变不自动改变已激活冻结版本。Device=auto 因显卡被占改走 CPU 时,先查同一请求在显卡上和在 CPU 上是否已有有效结果,命中就直接复用;新算出的 CPU 结果按 CPU 身份另行登记,不改名冒充显卡结果。
- service.py 在正式写盘前后维护任务状态,复用时检查客观文件及所有输出的非空大小和 SHA-256,不只判断文件存在。
- 正式文件名包含请求身份;无哈希同名 TXT/MD/JSON 仅供兼容展示,不能作为缓存或原件身份依据。
- server.py 暴露 /jobs/<job_key> 与指定 cancel 入口;active_localocr_task 返回 409,调用方应读取原任务,不隐式新建队列。
- 增强或执行失败可以保存首轮文字与 checkpoints.py 的逐页部分证据,仍是 partial 而非完整成功缓存;取消响应标 terminal/non-retryable。

- 单独的 observer.py 和任务列表接口 10 月 20 日已取消,文件已不存在:要看最近的任务,AI 直接读
_server/(docs/QUICKSTART_FOR_AI.md);server.py 只保留 health、单任务查询、精确取消和两个 OCR(光学字符识别)入口。这些都不提供 token 生成速率。jobs/ *.json
- OCRService 启动时只调用 job_registry.recover_abandoned 回收遗留锁:复核遗留锁对应的进程身份,确认执行者已死亡才将 running 标成 failed / owner_exited 并清除占用;活任务不会仅因运行时间长被接管,不产生页级自动续跑。启动时不再同步扫描全部任务清单、逐条查输出,服务因此能更快开始接单。
- 输出已丢失的完成记录交给后台线程 retire_missing_outputs,最多每 24 小时一轮:只挑 completed、且登记的正式输出全部确认已不存在的记录,在登记锁(registry guard)下重读确认后删掉这条清单记录;带运行锁的、读不了的、路径不确定的一律保留。缓存命中时仍每次核对输出,不依赖这轮清理。
- 若失败终态本身无法写入,service.py 保留恢复锁并记录 terminal_persistence_failure;health 返回 not-ready / job_state_persistence_failed,后续请求以 503 拒绝,不能把状态未落盘的服务继续当正常执行器。


- 单独的 observer.py 和任务列表接口 10 月 20 日已取消,文件已不存在:要看最近的任务,AI 直接读
_server/(docs/QUICKSTART_FOR_AI.md);server.py 只保留 health、单任务查询、精确取消和两个 OCR(光学字符识别)入口。这些都不提供 token 生成速率。jobs/ *.json
- OCRService 启动时只调用 job_registry.recover_abandoned 回收遗留锁:复核遗留锁对应的进程身份,确认执行者已死亡才将 running 标成 failed / owner_exited 并清除占用;活任务不会仅因运行时间长被接管,不产生页级自动续跑。启动时不再同步扫描全部任务清单、逐条查输出,服务因此能更快开始接单。
- 输出已丢失的完成记录交给后台线程 retire_missing_outputs,最多每 24 小时一轮:只挑 completed、且登记的正式输出全部确认已不存在的记录,在登记锁(registry guard)下重读确认后删掉这条清单记录;带运行锁的、读不了的、路径不确定的一律保留。缓存命中时仍每次核对输出,不依赖这轮清理。
- 若失败终态本身无法写入,service.py 保留恢复锁并记录 terminal_persistence_failure;health 返回 not-ready / job_state_persistence_failed,后续请求以 503 拒绝,不能把状态未落盘的服务继续当正常执行器。



| 名词 | 意思 |
|---|---|
| request identity(请求身份) | 输入、模型和请求参数的组合,防止同名文件或不同模型共享错误结果。 |
| formal output(正式输出) | 本次请求完成并通过相应检查的结果路径;与兼容显示副本和 partial 初步证据不同。 |
| 单任务查询 | 按任务编号看这个任务现在的状态,不替调用方创建或重新执行任务;原来单独的 observer 接口已取消。 |

查询、取消、复验与结果复用有同一套身份;窗口超时不是重交信号。



查询、取消、复验与结果复用有同一套身份;窗口超时不是重交信号。

- HTTP 409 / active_localocr_task: 读取已返回的 job_key 和查询入口,不盲目重复提交。
- 输出丢失、为空或指纹不匹配: 不接受缓存命中,保留原件与请求依据后重新判断执行。
- 客户端 exit 124: 先回查服务端任务状态;不能仅凭退出码认定识别失败。
- 增强失败但有首轮文字: 明确为 partial,不把这些文件提升为正式成功结果。

- HTTP 409 / active_localocr_task: 读取已返回的 job_key 和查询入口,不盲目重复提交。
- 输出丢失、为空或指纹不匹配: 不接受缓存命中,保留原件与请求依据后重新判断执行。
- 客户端 exit 124: 先回查服务端任务状态;不能仅凭退出码认定识别失败。
- 增强失败但有首轮文字: 明确为 partial,不把这些文件提升为正式成功结果。

- 服务崩溃遗留 running 与锁: 下次启动核对进程身份;已死亡的执行标 owner_exited 并解除占用,活执行保留,不自动重跑。
- 任务终态无法写入: 保留恢复锁与原始/落盘错误,health 标不可继续接单;先修复实际存储问题,不以进程存在或盲重提掩盖。

- 服务崩溃遗留 running 与锁: 下次启动核对进程身份;已死亡的执行标 owner_exited 并解除占用,活执行保留,不自动重跑。
- 任务终态无法写入: 保留恢复锁与原始/落盘错误,health 标不可继续接单;先修复实际存储问题,不以进程存在或盲重提掩盖。

- 任务身份与缓存复验
- 正式结果提交与初步证据
- 查询和精确取消
- 由 AI 直接读任务记录(
_server/)jobs/ *.json
- 任务、输出和进程测试分别覆盖当前行为;普通测试不能证明真实长文档的恢复速度。
- 重跑同一合成请求可验证复用,但不能据此推导任意私人原件准确率。截至 2026-11-04 13:30,正式任务目录有 6,822 份登记:完成 6,747、失败 75、运行中 0;这是现存的全部登记、不排除样例,只是写盘登记,不说明当时服务一定空闲。2026-10-30 11:07 时是 11,588 份(完成 11,514、失败 74),2026-10-11 14:00 时是 16,151 份(完成 16,107、失败 44)。完成数变少,原因至少包括 10 月 26 日起每天清掉输出已不在的完成记录(服务开着时才跑;10 月 30 日 12:29 跑过一轮,清单一下少了四千多条),不能理解成实际识别量减少;现在的数只是现存清单里能数到的记录数,是历史上处理过多少次的下限,不是全历史累计。那时排除项目样例、冒烟测试和 8 月 18 日开发空白图后,16,074 条完成登记都存着输出位置——这个筛选后的数和输出位置覆盖,10 月 22 日没能按同一筛选口径重数;部分旧记录被清理后,也已无法从现存清单复原这组集合,目前 Unknown。这是“存过结果”的数量,不等于现在仍有效的缓存数:输出指纹、模型身份和负向证据没有逐条复验,有效缓存数没有核对,目前未知。缓存命中也不新增登记,所以没有历史命中次数。
- 10 月 11 日那 44 条失败登记里(10 月 11 日之后新增的失败登记还没分类,原因 Unknown):执行超时 7 条、推理失败 4 条、执行进程已退出(owner_exited)1 条,另有 32 条旧记录没有错误码,这只是记录里缺这个字段,不代表失败没有原因;5 条带部分结果文件。现行源码含逐页检查点、取消终态和缓存工件身份合同;9 月 17 日 Windows 同源普通 OCR(光学字符识别)的首次与 cache_hit 输出哈希一致,证明的是那条已知样例的复用。9 月 24 日和 10 月 16 日两版验收的合成质量测试都明确关闭了缓存,不是缓存命中测试;现役 10 月 26 日版的验收回执也只有依赖、单元测试和合成质量三步,没有读到新的 Windows 端到端回执;这些都不代表私人长文档或自动逐页续跑已经验收。
结果与复核模块定义什么才算有效结果,本模块决定是否复用;运行与资源模块负责活动执行和终止边界。

- 任务身份与缓存复验
- 正式结果提交与初步证据
- 查询和精确取消
- 由 AI 直接读任务记录(
_server/)jobs/ *.json
- 任务、输出和进程测试分别覆盖当前行为;普通测试不能证明真实长文档的恢复速度。
- 重跑同一合成请求可验证复用,但不能据此推导任意私人原件准确率。截至 2026-11-04 13:30,正式任务目录有 6,822 份登记:完成 6,747、失败 75、运行中 0;这是现存的全部登记、不排除样例,只是写盘登记,不说明当时服务一定空闲。2026-10-30 11:07 时是 11,588 份(完成 11,514、失败 74),2026-10-11 14:00 时是 16,151 份(完成 16,107、失败 44)。完成数变少,原因至少包括 10 月 26 日起每天清掉输出已不在的完成记录(服务开着时才跑;10 月 30 日 12:29 跑过一轮,清单一下少了四千多条),不能理解成实际识别量减少;现在的数只是现存清单里能数到的记录数,是历史上处理过多少次的下限,不是全历史累计。那时排除项目样例、冒烟测试和 8 月 18 日开发空白图后,16,074 条完成登记都存着输出位置——这个筛选后的数和输出位置覆盖,10 月 22 日没能按同一筛选口径重数;部分旧记录被清理后,也已无法从现存清单复原这组集合,目前 Unknown。这是“存过结果”的数量,不等于现在仍有效的缓存数:输出指纹、模型身份和负向证据没有逐条复验,有效缓存数没有核对,目前未知。缓存命中也不新增登记,所以没有历史命中次数。
- 10 月 11 日那 44 条失败登记里(10 月 11 日之后新增的失败登记还没分类,原因 Unknown):执行超时 7 条、推理失败 4 条、执行进程已退出(owner_exited)1 条,另有 32 条旧记录没有错误码,这只是记录里缺这个字段,不代表失败没有原因;5 条带部分结果文件。现行源码含逐页检查点、取消终态和缓存工件身份合同;9 月 17 日 Windows 同源普通 OCR(光学字符识别)的首次与 cache_hit 输出哈希一致,证明的是那条已知样例的复用。9 月 24 日和 10 月 16 日两版验收的合成质量测试都明确关闭了缓存,不是缓存命中测试;现役 10 月 26 日版的验收回执也只有依赖、单元测试和合成质量三步,没有读到新的 Windows 端到端回执;这些都不代表私人长文档或自动逐页续跑已经验收。
结果与复核模块定义什么才算有效结果,本模块决定是否复用;运行与资源模块负责活动执行和终止边界。
复制 AI 续作说明
项目:不重复跑同一份材料,也不把旧结果套到新原件上;仓库:wlyaaaaa/LocalOCR;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。





