不重复跑同一份材料,也不把旧结果套到新原件上
现在
常用
任务记录数是现存清单,不是全部历史;11 月 4 日本机服务没在监听,在线查询没有验证
截至 11 月 4 日 · 项目源码和任务记录

同一份资料已经处理过时,能复用就不再等模型;正在处理时,我能知道它在哪一步,而不是反复按提交。这个模块把原件、请求和结果对在一起,让省时不会变成拿错旧文件。

当前情况:已有任务定位和结果复验功能,可避免重复提交;旧结果只有仍对应同一原件与运行条件才复用。显卡算出的结果和显卡被占时改用处理器(CPU)算出的结果分开登记,不会互相冒用。输出文件已经不在的完成记录,现在由后台在服务开着时每天最多清理一次,所以任务清单只是现存还能核对的记录,不是“一共做过多少次”的永久台账。要看最近的任务,由 AI 直接读任务记录;单独的观察接口 10 月 20 日已取消,查单个任务和精确取消都还在。

项目现状截至 2026-10-11 14:00(北京时间),于同日 16:30–16:48 只读核对;任务清单清理与设备分开登记按 10 月 26 日 04:14 合并进主线、并已装进现役版本的源码说明;具体测试保留各自日期,页面不实时探测运行状态。

项目源码:公开仓库

不重复跑同一份材料,也不把旧结果套到新原件上
现在
常用
任务记录数是现存清单,不是全部历史;11 月 4 日本机服务没在监听,在线查询没有验证
截至 11 月 4 日 · 项目源码和任务记录

同一份资料已经处理过时,能复用就不再等模型;正在处理时,我能知道它在哪一步,而不是反复按提交。这个模块把原件、请求和结果对在一起,让省时不会变成拿错旧文件。

当前情况:已有任务定位和结果复验功能,可避免重复提交;旧结果只有仍对应同一原件与运行条件才复用。显卡算出的结果和显卡被占时改用处理器(CPU)算出的结果分开登记,不会互相冒用。输出文件已经不在的完成记录,现在由后台在服务开着时每天最多清理一次,所以任务清单只是现存还能核对的记录,不是“一共做过多少次”的永久台账。要看最近的任务,由 AI 直接读任务记录;单独的观察接口 10 月 20 日已取消,查单个任务和精确取消都还在。

项目现状截至 2026-10-11 14:00(北京时间),于同日 16:30–16:48 只读核对;任务清单清理与设备分开登记按 10 月 26 日 04:14 合并进主线、并已装进现役版本的源码说明;具体测试保留各自日期,页面不实时探测运行状态。

项目源码:公开仓库

这项功能怎样使用

用途与实际影响

为什么需要它

文件同名不代表内容相同,输出还在也不代表它完整。客户端窗口超时还可能留下正在执行的工作;如果不先定位任务就重试,会重复占用显卡,还可能混淆两次结果。

举个实际例子

我可以问:“刚才那份扫描件等超时了,现在要不要重新提交?”系统会先查原任务:仍在处理就继续等待或由我取消,已经完成就直接读取结果,确实中断才明确说明。它不会因为窗口等超时就重复跑一份。

最后我会得到什么

先得到原任务现在是处理中、完成还是中断;完整旧结果能核对时直接取回,否则才决定重新识别。部分页面证据可以帮助排查,但不是任何故障都能自动续跑。

结果怎么看
正常时

旧结果与这份文件和要求确实相同、文件完整时直接复用。

发现问题时

等待窗口超时先查原任务,取消或中断后留下状态,不盲重交。

入口不可用或证据不足时

任务仍占资源或连终态都无法确认时停止新提交,先核对现场。

这项功能怎样使用

用途与实际影响

为什么需要它

文件同名不代表内容相同,输出还在也不代表它完整。客户端窗口超时还可能留下正在执行的工作;如果不先定位任务就重试,会重复占用显卡,还可能混淆两次结果。

举个实际例子

我可以问:“刚才那份扫描件等超时了,现在要不要重新提交?”系统会先查原任务:仍在处理就继续等待或由我取消,已经完成就直接读取结果,确实中断才明确说明。它不会因为窗口等超时就重复跑一份。

最后我会得到什么

先得到原任务现在是处理中、完成还是中断;完整旧结果能核对时直接取回,否则才决定重新识别。部分页面证据可以帮助排查,但不是任何故障都能自动续跑。

结果怎么看
正常时

旧结果与这份文件和要求确实相同、文件完整时直接复用。

发现问题时

等待窗口超时先查原任务,取消或中断后留下状态,不盲重交。

入口不可用或证据不足时

任务仍占资源或连终态都无法确认时停止新提交,先核对现场。

从哪里开始

在同一 LocalOCR 对话中提供刚才返回的任务标识,先问“现在进行到哪”;不要仅凭等待窗口超时重新提交。

需要准备什么
  • 原任务标识或原件
  • 本次识别要求
  • 继续等待还是取消的选择
从开始到拿到结果
1先找原任务
系统查询活跃状态和已保存结果,确认原件及请求是否仍相同。
2按真实状态处置
在跑则继续查询或精确取消;正式结果完整有效则直接复用。
3必要时才重试
中断或输入改变才重新执行,并区分部分证据、缓存和完整结果。
从哪里开始

在同一 LocalOCR 对话中提供刚才返回的任务标识,先问“现在进行到哪”;不要仅凭等待窗口超时重新提交。

需要准备什么
  • 原任务标识或原件
  • 本次识别要求
  • 继续等待还是取消的选择
从开始到拿到结果
1先找原任务
系统查询活跃状态和已保存结果,确认原件及请求是否仍相同。
2按真实状态处置
在跑则继续查询或精确取消;正式结果完整有效则直接复用。
3必要时才重试
中断或输入改变才重新执行,并区分部分证据、缓存和完整结果。
技术实现与依据(一)
这里保留实现、关键条件、精确入口、历史记录和验证结果。
任务定位与结果复验已实现
关键规则与设计选择
1
使用 results[].output_files 指向的正式文件,不靠同名兼容副本判断。
2
相同请求仍需复核输出,缓存命中只代表可复用。
3
当前已有逐页原子检查点和部分证据读取;它们不等于任意长 PDF 自动断点续跑,更不能在用户取消后自动重试。
当前怎样实现
  • 任务身份绑定源路径/内容、请求语义、逐页路由、具体 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。
技术实现与依据(一)
这里保留实现、关键条件、精确入口、历史记录和验证结果。
任务定位与结果复验已实现
关键规则与设计选择
1
使用 results[].output_files 指向的正式文件,不靠同名兼容副本判断。
2
相同请求仍需复核输出,缓存命中只代表可复用。
3
当前已有逐页原子检查点和部分证据读取;它们不等于任意长 PDF 自动断点续跑,更不能在用户取消后自动重试。
当前怎样实现
  • 任务身份绑定源路径/内容、请求语义、逐页路由、具体 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。
技术实现与依据(二)
1
从本次原件与请求确定任务身份。
2
复验已有结果,完整有效时直接复用。
3
已有活跃任务时返回明确定位,不并发重交。
4
确需新执行时由同一服务负责处理与状态。
5
超时或中断后先查原任务和文件,再决定等待、精确取消或有界重试。
  • 单独的 observer.py 和任务列表接口 10 月 20 日已取消,文件已不存在:要看最近的任务,AI 直接读 _server/jobs/*.json(docs/QUICKSTART_FOR_AI.md);server.py 只保留 health、单任务查询、精确取消和两个 OCR(光学字符识别)入口。这些都不提供 token 生成速率。
  • 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 拒绝,不能把状态未落盘的服务继续当正常执行器。
执行流程
技术实现与依据(二)
1
从本次原件与请求确定任务身份。
2
复验已有结果,完整有效时直接复用。
3
已有活跃任务时返回明确定位,不并发重交。
4
确需新执行时由同一服务负责处理与状态。
5
超时或中断后先查原任务和文件,再决定等待、精确取消或有界重试。
  • 单独的 observer.py 和任务列表接口 10 月 20 日已取消,文件已不存在:要看最近的任务,AI 直接读 _server/jobs/*.json(docs/QUICKSTART_FOR_AI.md);server.py 只保留 health、单任务查询、精确取消和两个 OCR(光学字符识别)入口。这些都不提供 token 生成速率。
  • 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 接口已取消。
专业定义

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

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

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

出问题时(一)
解决什么
防止重复执行、旧结果错配、坏缓存被接受,以及等待期限与执行期限混为一谈。
边界
客户端 timeout(等待超时)不证明服务端任务终止。
不承诺永久任务档案或跨任意故障的自动续跑。
write_outputs=false 不登记正式写盘任务与结果缓存,内存证据不能冒充已保存证据。
失败与恢复
  • HTTP 409 / active_localocr_task: 读取已返回的 job_key 和查询入口,不盲目重复提交。
  • 输出丢失、为空或指纹不匹配: 不接受缓存命中,保留原件与请求依据后重新判断执行。
  • 客户端 exit 124: 先回查服务端任务状态;不能仅凭退出码认定识别失败。
  • 增强失败但有首轮文字: 明确为 partial,不把这些文件提升为正式成功结果。
出问题时(一)
解决什么
防止重复执行、旧结果错配、坏缓存被接受,以及等待期限与执行期限混为一谈。
边界
客户端 timeout(等待超时)不证明服务端任务终止。
不承诺永久任务档案或跨任意故障的自动续跑。
write_outputs=false 不登记正式写盘任务与结果缓存,内存证据不能冒充已保存证据。
失败与恢复
  • 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。