用途与实际影响
这项功能怎样使用
为什么需要它
一律使用重模型会增加等待，一律使用普通提字又可能丢掉复杂页面结构。这个入口把输入范围、结果要求和模型选择分开，并让模型不足时的增强有迹可查，而不是用“智能识别”掩盖真实判断方式。
举个实际例子
我可以说：“把这份多栏 PDF 的文字读出来并保留版面，文件留在本机。”系统会固定这一个输入并选择合适路线；如果给的是文件夹，也只处理本次明确要求的范围。
最后我会得到什么
返回对应文件的结果路径、实际引擎与模型、选择原因，以及是否发生增强。遇到不支持的文件、模型冲突、活跃任务或服务身份不符，会说明原因，不交回来自另一条未知路线的结果。
正常时
输入范围与路线明确，按请求执行并返回实际模型和输出。
发现问题时
自动提字不足时可以本地增强；增强失败保留首轮初步证据，但不标完成。
入口不可用或证据不足时
原件不可读、模型冲突或服务不是 LocalOCR 时停止相应请求，不抢端口、不换云服务。
从哪里开始
在本机已接入 LocalOCR 的 AI 对话中指定原件，或用“日常本机入口” ocr_smart.ps1 传入明确路径。
需要准备什么
- 图片、扫描 PDF 或目录
- 递归范围
- 想要文字、复杂版面还是指定模型
从开始到拿到结果
- 1
检查原件与可读内容
系统核对文件类型、页数和实际内容；已有文字层先直接取用，扫描图才进入识别。
- 2
选择本地路线
AI 核对实际文件与已登记模型，普通页面先轻量提字，复杂或显式结构需求按对应路线处理。
- 3
拿到可追溯结果
交回实际用过的模型、文字及输出位置；文件不支持或本地模型不可用时说明原因，不暗中上传或全库扫描。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
三条路线与统一执行已实现关键规则与设计选择
普通看图不强制 OCR（光学字符识别），数字文档有文字层时优先原生读取。
复杂程度取实际页内容与识别证据，不由文件名判断；只增强问题页，不把整份文档重跑重模型。
显式模型优先；结构解析需要单独选择，不是自动增强的第三级。
文件名或目录含中文、空格时仍用同一拖拽入口；它需要PowerShell 7.3+，旧Windows PowerShell 5.1不属于该入口的支持环境。入口传参已通过隔离检查，文字能否读全、读准仍需核对实际结果。
本模块用到的名词
- auto（自动选择）
- 按当前可解释规则选 ocr（光学字符识别） 或 vl；不是无条件选择最重模型，也不包含 structure（结构化版面）。
- explicit model（明确模型）
- 用户明确指定某个配置时按它执行；冲突要说明，不能静默改写。
- route（实际识别路线）
- 记录最终引擎、原因、信号与增强过程，方便解释与复核。
专业定义
明确读哪个文件、要文字还是结构；普通内容先提字，不够再本地增强。
解决什么
防止范围不明的批处理、轻重模型误用、显式选择被改写，以及客户端调用脚本与真实服务行为不一致。
当前怎样实现
- router.py 枚举支持的图片和 PDF；是否递归由 recursive 参数决定，不默认扩大目录范围。
- Smart Router v5 预路由让 auto 先 OCR（光学字符识别）；difficulty.py 结合逐页空结果、低置信度及表格/公式内容信号，service.py 只增强对应问题页。
- 同一任务保留增强前文字与几何；显式模型不参加自动替换，Structure（结构化版面） 不是自动流程的隐含第三层。
- model_registry.py 解析 profile（具体模型配置），核对引擎匹配；显式模型不被自动选择覆盖。
- start.bat使用pwsh，start.ps1声明PowerShell 7.3+；路径回调将Windows盘符转换为/mnt/<盘符>，Git固定start.bat为CRLF，避免中文批处理被异常解析。其后的localocr.cli继续共用OCRService、增强与输出合同，模型路线没有改变。
- ocr_smart.ps1 预览路线并验证服务健康，以 active_jobs 作为忙碌依据；缺字段为 readiness_unknown，不能当空闲。
执行流程
- 1
固定本次文件、目录递归范围与希望得到的结果。
- 2
优先检查原生可读内容；需要图片文字证据时进入 LocalOCR。
- 3
核对路径、类型、明确引擎与模型配置。
- 4
普通提字或复杂文档路线执行，必要时根据首轮结果增强。
- 5
交回实际路线与文件，不把预检建议当最终模型身份。
边界
- 支持的是明确文件和目录，不是私人库后台扫描。
- 仅需场景描述时由原生视觉处理；全本地要求下不向外部视觉服务发送像素。
- 普通 OCR（光学字符识别）、VL 和 Structure（结构化版面） 的适用范围不能互相冒充。
失败与恢复
- 输入不支持或不可读
- 返回明确的输入或读取错误，不制造空白成功结果。
- 显式引擎与模型不匹配
- 拒绝该组合，让调用方修正配置；不私自换模型。
- 本地增强失败
- 保留首轮 partial（初步结果）与失败原因，整体仍为失败，不能写入成功缓存。
- 端口是另一个服务
- 报告 non-LocalOCR service，停止提交；不把 18666 当自动后备。
真实入口
E:\Projects\Tools\LocalOCR\localocr\router.py支持类型与输入枚举
E:\Projects\Tools\LocalOCR\localocr\smart_router.py自动与显式路线
E:\Projects\Tools\LocalOCR\localocr\difficulty.py困难度依据
E:\Projects\Tools\LocalOCR\localocr\service.py实际增强与统一执行
E:\Projects\Tools\LocalOCR\ocr_smart.ps1Windows 有界入口与服务识别
如何验证
- 2026-09-07，376a777的24项Windows调用回归通过，4.210秒；另经真实start.bat、pwsh与已确认wsl.exe替身验证中文空格路径完整传递，0.458秒。检查在模型执行前结束，没有重验OCR（光学字符识别）效果或服务在线。原CLI（命令行工具）/API共用、显式选择和增强合同继续保留。
- 模型注册、分流与调用脚本行为有独立单元测试；当前机器测试与运行证据见总览技术层。
- 9 月 17 日禁用缓存的九例质量回执包含 auto_table，实际表格关键单元格通过；这个合成案例不证明任意版面都能正确选路。
与其他模块的关系
这个模块决定如何进入任务；表格与版面模块解释结构需求，结果与复核模块解释如何读返回值，任务与运行模块处理复用和故障。