# HTTP OCR 逻辑设计

需求来源为 [PRD](./prd.md#13-http-paddleocr-vl-扩展规划)，场景验收见
[User Stories](./user-stories.md)。当前生产机制及与设计的差异见[实现说明](./implementation.md)，
逐项验证见[进度](./progress.md#2026-09-19-实现与验证)。以下规则保留需求追溯职责。

## 输入路由

L-I1（FR-I1、FR-I2、FR-I4；US-I1、US-I2、US-I3、US-I6）：先区分用户操作与输入类型，
再判断实际生效的模型及 Runtime 能力。显式提取图片文字使用已保存 OCR 配置，优先于普通
图片直传分支，也不受文档快速工作流的隐式跳过规则影响。

| 输入或操作 | 处理 |
| --- | --- |
| 普通聊天图片，实际支持图片输入 | 作为图片请求发送，不调用 OCR |
| 普通聊天图片，实际不支持或能力未确认 | 明确提示提取文字或切换视觉模型，不静默 OCR，不声称已发送图片 |
| 明确提取图片文字 | 调用配置的 OCR；模型视觉能力不影响此操作 |
| PDF、Office | 沿用文档原生解析与按需 OCR 工作流 |
| 知识库图片文字提取及索引 | 由知识库工作流决定，不读取聊天模型视觉开关作为路由依据 |

L-I2（FR-I3、FR-I5；US-I1、US-I4、US-I7）：原图与请求副本分开，缩放、转码不覆盖原图。
纯图片无解析正文及清单前置条件；显式 OCR 产物关联回原附件。文档图片保存与模型请求选择
分别处理，只有明确选入请求且满足实际能力、数量和容量限制的图片才进入模型输入。

L-I3（FR-I2、FR-I3；US-I3、US-I11）：附件身份、原始名称与来源不因 OCR 改变，发送方式
单独记录为图片或提取文字。只有 OCR 返回非空可靠文字且结果保存成功，才切到提取文字；
显示名派生为“原文件名 · 提取文字”。提取文字模式只拼入文本，不同时传原图或把解析中
提取的其他图片自动附加。失败、取消、空文字保持原方式；用户可显式切回图片并重新校验
能力。重试采用当前已保存 OCR 设置，开始时说明来源；旧结果在新结果成功前保持可用。

## 选图与发送

L-I4（FR-I5；US-I7、US-I8、US-I9）：预览待添加选择是短期 UI 状态，目标草稿的附件引用
才是“已附加”的依据。进入预览默认零选择，切页签保留选择，关闭清空未添加选择。已附加
项不能靠取消勾选移除，必须明确执行移除操作。测试预览不提供添加入口。

添加提交包含明确的目标会话及来源结果 imageId 集合，提交时冻结目标，不根据异步完成时
活动会话改归属。Main 确认目标可编辑、源资源仍存在、数量与容量可接受后复制到会话所有
的稳定文件资产，再保存草稿引用；任一复制或保存失败回滚本批新副本，保留原选择与草稿。
无有效目标时必须先选择或新建会话，不隐式创建或采用第一个会话。活动回复不阻止下一条
草稿编辑，但仍遵循已有 Runtime/模型选择锁定规则。

以“目标草稿 + 来源结果 ID + imageId”判断重复添加；来源结果 ID 只标识实际解析产物，
不引入结果版本历史。同一草稿存在该图片引用时返回已有附件，不重复占用容量或位置。
移除后可再次添加；发送后新草稿可再次添加。重解析生成新结果和图片 ID，不自动替换
已附加副本。父文档与副本没有级联删除关系，来源关联用于说明及跳转，不作为副本存活条件。

L-I5（FR-I1、FR-I5、FR-H9；US-I2、US-I8、US-I10）：选图和发送沿用 PRD 第 3.2.1 节
现有附件限制。父文档和每张图片分别占一个附件位置；现有基线为每消息 8 个附件、Main
16 个上下文项目及 12 MiB 暂存内容上限。实现从同一共享契约读取这些值，不在预览、IPC
或 Provider 中定义独立的“选图上限”。图片副本使用既有图片请求转码路径，原始资产大小
与请求副本大小分开计算，不能把尚未选中的全部插图计入本次发送容量。

选图批次先去掉已附加项再整批校验；超限全部拒绝并保留选择，不沿用文件粘贴入口的截取
剩余位置行为。发送前重新读取完整草稿并校验，不依赖添加时的剩余位置。文本父附件只
拼入一次，不为每个图片副本重复加入父文档正文；模型正文仅附简短来源信息及图片输入。
仅图片父文档仍作为来源附件保留并计入附件数量，但不生成空 text context；同批至少有一张
从该结果选出的图片（或其显式 OCR 文字）才可携带它发送，否则提示选择图片或移除该文档。

能力判定取本次实际模型与实际 Runtime 消费路径的交集。添加时显示能力问题但允许保存
待修复草稿，发送和入队接受前必须通过校验；未知能力不能当作支持。切换模型/Runtime、
恢复队列及真正开始执行时重新校验。队列能力失配转为可恢复失败并保留资源，用户可恢复
到草稿修正或切换到支持的配置后重试；队列内容不会静默转文字或丢图。不以工具拿到图片
引用代替聊天模型收到图片的证据，也不因模型支持视觉而隐式调用 OCR。

## 来源与选项

L-H1（FR-H1、FR-H2；US-H1、US-H2、US-H8）：每次解析开始时读取并冻结已保存的来源、
地址和选项。选择 HTTP 后只检查 HTTP 配置；本地模型状态不再是 HTTP 的前置条件。
HTTP 失败不触发本地下载或切换。快速工作流优先于 OCR 设置，仍不运行 OCR。

L-H5（FR-H11、FR-H12；US-H12）：来源切换保留各自配置，测试要求先保存；解析结果记录
本次 Provider 与生效选项，不含凭据。查看已存结果不触发解析，修改配置不改写旧结果。

配置为设备级共享值；项目、会话和知识库范围决定结果归属，不创建独立 OCR 配置。应用中心
的本机推理监控启用、常驻与窗口开关不决定 OCR 来源或可用性。HTTP 来源不依赖本地监控
入口和模型加载状态。菜单及设置直达返回规则见 [入口与职责](./ui-design.md#11-入口与职责)
（FR-H1、FR-H12、FR-I5；US-H16）。

L-H2（FR-H4；US-H4、US-H9）：高级布尔项使用“服务默认 / 开启 / 关闭”语义。
服务默认省略字段，不将未知默认值写成 `false`。`markdownIgnoreLabels` 使用三种状态：
省略表示服务默认，空数组表示不排除标签，非空数组表示明确排除的标签集合。保存设置
不得把空数组归一为缺省。任务内选项不随用户中途修改设置变化。

自定义过滤的正向“保留”开关与排除集合取反映射。首次进入自定义且无旧值时从全部保留
开始，明确显示此初始值；不猜测服务默认。已有自定义排除列表在切换模式后保留，未知或
不常用标签也必须呈现并保留，不能保存时丢弃。默认保存结果引用的图片；过滤使图片不再
被正文引用时才可不提交对应图片。过滤设置不控制模型自动选图。

## 页面与图片

L-H3（FR-H2、FR-H5、FR-H7；US-H2、US-H5、US-H8）：页面定位来自输入任务的原始页号。
单页图片请求可确定其 PDF 页号或 PPTX 幻灯片号；整份 PDF 请求在核对返回数量和顺序后
映射到原始页号，不依赖此次部署缺失的 `page_index`。不连续 OCR 页不能直接跨页合表。
重组输出保留 `sourcePages` 集合，无法恢复对应关系时报告失败，不能猜测唯一页号。

L-H4（FR-H3；US-H3、US-H7）：以“文档 + 原始页 + 页内图片键”关联图片。只处理有界、
可解码的内联图片，不下载服务返回 URL。Markdown 中的 `![]()` 和 HTML `img src` 均须
映射到保存后的受管资源；表格 HTML 需要既有安全渲染处理。模型正文与向量索引不混入
Base64。筛除页眉图等内容时，对应图片只有仍被结果引用才需要提交。

## 结果与失败

| 条件 | 处理规则 | 关联 |
| --- | --- | --- |
| 原生文本可靠且未要求 OCR | 直接使用原生结果，不探测 HTTP | FR-H2 / US-H2 |
| HTTP 与图片保存完成 | 提交逐页内容、图片引用和诊断；置信度缺失就省略 | FR-H3、FR-H7 / US-H1、US-H3 |
| 自动聊天 OCR 失败且有可靠原生文字 | 沿用既有原生文字回退，并标明未完成 OCR 页 | FR-H6 / US-H6 |
| 自动聊天已取得文字但部分图片失败 | 保留文字和具体缺图警告；缺图引用改成文字说明 | FR-H3、FR-H6 / US-H7 |
| 自动聊天跨页重组失败，但逐页结果可用 | 保留原逐页正文、图片及页码，显示重组失败和部分结果；不使用映射不明的重组内容 | FR-H5、FR-H6 / US-H5、US-H6 |
| 知识库完整索引或高保真缺页、缺图、重组失败 | 本次失败，不替换已有成功结果；允许重试 | FR-H3、FR-H5、FR-H6 / US-H3、US-H5、US-H7 |
| 用户取消解析或应用关闭 | 中止客户端请求，不启动后续任务，仅清理本次无有效引用的临时资源；草稿、已发送、已入队引用的资源保留 | FR-H6、FR-H9 / US-H6、US-H10、US-I5 |
| 无文字但有已保存的有效插图 | 结果为仅图片，可预览并按 L-I4 选择；聊天父文档无可发送文本，知识库不生成空 chunk，不标为文本索引成功 | FR-H3、FR-H7、FR-I5 / US-H3、US-I7 |
| 无文字且无有效图片 | 失败，保留原件供重试，不能标为空成功 | FR-H6 / US-H15 |

请求状态按“准备、请求、校验、保存、完成”推进，提交前可进入失败或取消；资源及引用已
提交后按完成结算，迟到取消不删除结果。
HTTP 中止不保证服务端 GPU 推理立刻停止；本部署没有探测服务端取消接口。

L-H8（FR-H6、FR-H9、FR-H12；US-H6、US-H14、US-H15）：任务运行状态与结果完整程度
分开。已保存结果可为完整、部分或仅图片，当前任务另有运行、失败、取消或中断状态。
打开旧结果时可以同时显示本次重解析失败，不能用单一 status 覆盖旧结果。
自动聊天允许的可靠文本回退必须将缺页/缺图范围和警告随文本传给模型；知识库完整索引
及高保真严格失败。快速索引只按所选原生策略完成，不因用户明确禁用 OCR 而假称漏页
已经识别。仅图片的知识库结果可保存供预览和选图，但显示“无可索引文字”，不算索引成功。
已有可检索结果重解析后变成仅图片时，不以空索引替换旧结果，本次报告无可索引文字并保留
旧结果；首次导入没有旧结果时可保留图片资产和该状态。

首次批次导入失败或取消沿用批次回滚，失败摘要保留可重试信息但不是草稿附件。重解析
失败不删除已有附件。任务取消通过同一 operationId/AbortSignal 传播，取消后的迟到响应
不提交结果；应用退出停止后续请求，重启将未完成任务显示为中断，不恢复 HTTP 调用。
有受管原件则手动重试；原件尚未保存则重新选择。重启仅根据数据库现有引用清理无主暂存，
无需记录逐页持久运行日志。

## 资源归属

L-H6（FR-H8、FR-H9、FR-I3；US-H10、US-H11、US-I4、US-I5）：草稿资源暂存于应用目录；
发送被接受及队列记录持久化前，文档完成原文件、解析正文、图片的持久化及会话关联，纯图片
完成原图持久化及关联。失败保留草稿供重试，不标为已发送。
恢复队列读取持久化附件引用；取消生成不删除已提交资源。移除草稿附件、取消解析或批次失败
只清理本次无有效引用的资源。启动、退出或定时清理不得一律删除临时目录；可恢复草稿引用
的文件须继续可用。删除会话只释放其归属和引用，无其他有效引用时才删除文件。

L-H7（FR-H10、FR-H11；US-H11、US-H13）：知识库文档独立持有正文、chunks 和图片关系，
两种来源模式的派生资源均归应用管理。删除文档或来源时按有效引用清理；外部原文件不属于
派生资源清理范围。聊天和知识库重解析均先完成新结果及必要资源保存，再替换引用；失败或
取消清理新暂存，旧结果保持可用。旧资源仅在替换成功且无引用时回收。

已发送消息及已接受队列的正文、选图、发送方式和资源引用冻结。历史消息“再次解析”产生
新草稿附件，不修改消息；草稿重解析成功仅更新草稿引用，其他有效引用保持原结果。修改队列
附件须先恢复整条输入到草稿，再重解析或改变发送方式，不额外复制一条仍待发送的输入。队列
恢复到草稿时先保存草稿引用再移除队列引用，失败保持队列。队列删除只释放该项引用；
取消正在生成的回复保留已发送输入。会话删除和项目删除均使用同一引用清理规则。
目标已有草稿时，将恢复文字以空行追加、附件按来源去重合并，提交前校验合并后的数量与
容量；超限则保留队列及原草稿，提示先发送或整理草稿，不覆盖已有输入。

L-H9（FR-I5、FR-H9、FR-H10；US-I8、US-I9）：从聊天或知识库选出的图片在添加成功时
已是会话独立副本，其来源名称、定位和源 ID 随附件保存。来源删除或重解析不删除副本，
来源跳转失效不妨碍打开原图和发送。移除父文档只解除父文档引用，移除副本只解除该图片
引用。草稿、消息、队列、分支等已有有效引用共同决定是否清理文件；不为跨库引用建立
全局去重或资源保活服务。知识库与聊天原资产各自清理，复制时失败只回滚本批新资源。

## 完整性检查

来源选择、缺省值、正向过滤、混合页、图片键、完整/部分/仅图片结果、失败取消、原图保存、
显式 OCR 发送方式、选图幂等、目标选择、共享限额、发送入队、重解析及清理均已有确定规则。
组件和布局见 [UI 设计](./ui-design.md)，逐项验收见其完整矩阵；这些范围没有留待后续产品
决策的选图缺口。

实际直连和托管 OpenCode 图片消费、扫描 PDF 与跨页合表示例已取得真实证据，见进度。
其他 Runtime、本地 OCR 各平台和部署高级模型的本轮验证范围仍需分别核对。
模型声明与接口成功不替代效果测试；跨页整理默认关闭，失败明确报告。