goodbuddy/docs/features/doc-extract.md

文档解析与本地 OCR

1. 目标

GoodBuddy 需要用同一条可信文档解析链路服务以下场景：

• 聊天附件问答；
• 知识库导入、同步、分块与来源定位；
• 后续的合同审阅、表格分析、演示文稿理解和文档转换。

文档解析不是对话模型的附属功能。它是主进程管理的独立基础能力，设置入口为“设置中心 / 文档解析”。

2. 当前基线

原生解析器已经支持：

• UTF-8 文本、代码、配置、HTML；
• 带文本层的 PDF；
• DOCX 正文；
• XLSX 工作表 XML 与共享字符串；
• PPTX 幻灯片文字。

现有局限：

• 纯扫描 PDF 没有文本层时无法提取内容；
• DOC、XLS、PPT 等旧版二进制 Office 格式不支持；
• Office 解析主要提取文字，不能完整保留表格、公式、图表和版面；
• 聊天附件和知识库直接调用底层解析函数，缺少可配置的统一工作流；
• 没有本地 OCR 模型状态、真实解析测试和按场景策略。

3. 产品原则

3.1 双通道解析

PDF 不是所有文档唯一的中间格式。解析应同时保留：

1. 原生语义通道：标题、段落、单元格、公式、备注和对象关系；
2. 渲染视觉通道：页码、版面、图表、图片和 OCR 结果。

两条通道合并为统一文档结构。转换为 PDF 用于补充视觉信息，不得覆盖更可靠的原生语义结果。

3.2 场景工作流

场景	默认预设	行为
聊天附件	自动解析	优先快速提取，文本不足时按需 OCR，有界截断后加入当前请求
知识库导入	完整索引	完整解析、按页或工作表定位、按需 OCR、分块与索引
扫描文档	OCR	页面渲染、文字识别、置信度与定位保留
表格分析	语义优先	单元格和值优先，PDF 或图片补充图表与打印布局
高保真审阅	视觉增强	原生解析、页面渲染、OCR 或视觉理解合并

3.3 本地优先

• 文本层和本地 OCR 均在设备上处理；
• 本地处理不因 Ask 或 Execute 模式改变；
• OCR 来源必须在“本地模型 / 远程服务”之间明确选择；
• 配置并保存远程服务即表示用户选择该处理路径，不再增加逐场景授权；
• API 密钥只能保存在主进程加密设置中；
• 测试文件不得自动进入聊天或知识库。

4. 设置设计

设置中心新增“文档解析”分类，结构如下：

1. 分类页头：“测试解析”“保存设置”；
2. 运行状态：原生解析、文档转换、本地 OCR；
3. 使用场景：聊天附件、知识库导入；
4. 文档转换；
5. OCR 识别；
6. 高级解析设置；

OCR 模型区沿用语音模型管理模式：

• 应用不内置模型权重；
• 用户按需从 ModelScope 下载，下载完成后离线使用；
• 显示来源、语言、运行时、模型体积、安装与校验状态；
• 联网设备可导出已安装模型 ZIP，离线或内网设备可直接导入；
• 支持下载进度、取消、删除、ZIP 导入导出、打开模型仓库和受管目录；
• “打开 ModelScope”直接显示在 OCR 模型卡片右上角，不使用手动导入折叠区；
• 模型操作即时生效，解析策略仍通过分类页头的“保存设置”提交。

4.1 第一阶段字段

• 聊天附件预设：auto、fast-text、high-fidelity；
• 知识库预设：complete-index、fast-index、high-fidelity；
• PDF OCR 策略：auto、always、disabled；
• OCR 来源：第一阶段固定为 local，远程服务入口禁用；
• 本地 OCR 模型：pp-ocrv6-tiny、pp-ocrv6-small、pp-ocrv6-medium；
• 单文档最大页数；
• OCR 并发数；
• 单页超时。

OCR 来源使用互斥选择。本地模型选中后才显示模型下拉列表、按需下载、导入和本地 OCR 参数；远程服务计划接入 MinerU、PaddleOCR-VL 等接口，第一阶段保持可读但禁用。来源选择本身就是用户的明确决策，不再显示额外的“隐私与云端处理”授权区。

5. 架构

聊天附件 ─┐
          ├─ DocumentParsingService
知识库导入 ┘     ├─ NativeDocumentParser
                 ├─ PdfTextQualityEvaluator
                 ├─ PdfPageRenderer
                 ├─ LocalOcrProvider
                 ├─ DocumentConversionProvider
                 └─ ParsedDocument merger

DocumentParsingService 是唯一场景入口：

type DocumentParsingPurpose = 'chat-attachment' | 'knowledge-index'

type DocumentParsingService = {
  parse(
    name: string,
    bytes: Buffer,
    purpose: DocumentParsingPurpose,
    signal?: AbortSignal
  ): Promise<ParsedDocument>
}

聊天上下文管理器与知识库服务依赖该接口，不直接选择 OCR Provider。

6. 统一结果

第一阶段兼容现有 ParsedDocument，并逐步扩展：

type ParsedDocument = {
  title: string
  sourceFormat: string
  content: string
  sections: Array<{
    locator: string
    content: string
    method?: 'native' | 'ocr' | 'converted' | 'vision'
    confidence?: number
  }>
  warnings?: string[]
}

定位字段必须对使用者有意义：

• PDF：第 3 页；
• XLSX：工作表：预算 / A1:F28；
• PPTX：幻灯片 5；
• DOCX：标题路径或页码；
• 文本：全文。

7. 本地 OCR 基线

7.1 模型与运行时

全平台功能基线：

• 模型：PP-OCRv6 ONNX/ORT；
• 轻量下载档位：Tiny，约 6 MiB，用于低资源设备和六平台离线链路；
• 推荐下载档位：Small，约 30 MiB，官方支持 50 种语言；
• 高精度下载档位：Medium，约 132 MiB，官方支持 50 种语言，但识别较慢且需要更多内存；
• 运行时：ONNX Runtime WebAssembly；
• 处理环境：隔离 Worker；
• 加速：WebGPU 或平台原生执行 Provider，仅作为可选层；
• 回退：任何加速失败后使用 WASM CPU。

需要覆盖的发布矩阵：

• Windows x64、Windows arm64；
• macOS x64、macOS arm64；
• Linux x64、Linux arm64。

模型清单必须固定以下信息：

• 上游仓库和不可变 revision；
• 文件名、字节数和 SHA-256；
• 模型族、语言、质量和速度；
• 许可证名称、完整许可证和来源；
• 检测模型、识别模型、字符字典的匹配关系。

运行时不得从 main、latest 或其他可变地址加载模型。

7.2 下载与安装

Tiny、Small 和 Medium 模型均由 PaddlePaddle 官方 ModelScope 仓库提供。Small 是默认推荐档位；Medium 面向更高识别质量，但具有更高内存占用和延迟。每个档位的检测模型、识别模型与字符字典配置分别使用固定提交，并在应用内记录文件字节数和 SHA-256。

下载流程：

1. 主进程从固定 ModelScope resolve/<revision>/... 地址读取文件；
2. 禁用凭据与缓存，限制重定向次数和单文件大小；
3. 写入受管目录下的随机临时安装目录；
4. 边下载边计算 SHA-256，并核对完整字节数；
5. 三个文件全部通过校验后写入安装清单；
6. 原子重命名为正式模型目录；
7. 失败、取消或退出时删除临时文件。

模型只在下载或用户显式打开仓库时访问网络。OCR 推理从受管目录读取已校验文件，不发起网络请求。

7.3 离线 ZIP 迁移

语音模型和 OCR 模型使用同一种离线迁移流程：

1. 联网设备完成受信任来源下载和校验；
2. 在模型卡片选择“导出 ZIP”；
3. 将 ZIP 通过组织批准的介质传输到离线或内网设备；
4. 在相同模型的卡片选择“导入 ZIP”；
5. 主进程按当前应用内置目录重新校验，并在全部通过后原子安装。

ZIP 根目录包含模型文件和 goodbuddy-model.json。清单格式为 goodbuddy-model-archive，当前版本为 1，记录：

• 模型类型：speech 或 document-ocr；
• 内置模型 ID 和显示名称；
• 文件名、角色、原始字节数和 SHA-256；
• 导出时间。

导出不能直接信任已有安装清单，必须重新读取并校验每个文件。导入不能只信任 ZIP 自声明内容，模型 ID、文件角色、字节数和哈希必须再次与当前应用内置目录完全匹配。导入通过后复用普通本地安装的受控临时目录和原子重命名路径。

归档处理使用有界流式读写，不把大型模型或整个展开结果复制到内存。主进程限制压缩包大小、条目数、清单大小、单文件大小和总展开大小，并拒绝：

• 绝对路径、..、目录或嵌套路径；
• 大小写不敏感的重复条目；
• 未声明、缺失或角色不匹配的文件；
• 模型类型或模型 ID 不匹配；
• 解压后大小或 SHA-256 不匹配；
• 超过边界的压缩包和压缩炸弹。

取消文件对话框不会改变安装状态。导入和导出也不会切换当前语音/OCR 模型，不会隐式保存文档解析设置。

7.4 PDF 流程

1. 使用 PDF.js 读取每页文本层；
2. 评估有效字符数、乱码率和图片占比；
3. auto 模式只渲染文本不足的页面；
4. always 模式渲染所有页面；
5. Worker 将页面限制在配置的最大边长内；
6. OCR 返回文字、坐标和置信度；
7. 按页合并原生文本与 OCR，不重复可靠文本；
8. 达到页数、超时、取消或输出限制时停止并返回明确错误。

受密码保护、损坏或超限的 PDF 不得进入 OCR。

8. Office 与转换

8.1 新格式

• DOCX：正文、标题、表格、批注和图片关系；
• XLSX：工作表、单元格地址、值、公式、合并关系和图表；
• PPTX：幻灯片、文字对象、备注、图片和阅读顺序。

Office 内嵌图片 OCR 属于增强流程，不能替代原生结构解析。

8.2 旧格式

DOC、XLS、PPT 通过 DocumentConversionProvider 转换：

1. 转换为 DOCX、XLSX 或 PPTX，供语义解析；
2. 转换为 PDF，供页码、版面和视觉解析；
3. 合并结果并记录转换警告。

本地 LibreOffice Provider 必须：

• 在隔离子进程中运行；
• 禁用宏和网络；
• 使用单任务临时目录；
• 限制输入大小、输出大小、内存和超时；
• 在成功、失败、取消和退出时清理；
• 不接受用户提供的任意命令参数。

9. 安全边界

• 文件路径解析、读取、大小检查和格式校验在主进程完成；
• OCR Worker 只接收当前任务所需的有界页面图像和只读模型；
• 不向 Worker 暴露文件系统、Electron API、凭据或任意网络访问；
• 文档内容视为不可信数据，不解释其中的提示词为系统指令；
• 模型和转换程序必须固定版本并校验哈希；
• OCR 输出受字符数限制，错误不得包含绝对路径或未脱敏文档内容；
• 取消、超时和应用关闭必须终止待处理页面并释放模型会话。

10. 错误与回退

必须区分：

• 不支持的格式；
• 文档损坏或受密码保护；
• 文本层为空但 OCR 未启用；
• OCR 模型不可用；
• OCR 超时或取消；
• 文档页数、大小或输出超限；
• 本地转换服务未配置；
• 所选远程 OCR 服务不可用或配置不完整。

auto 工作流可以从 OCR 回退到可靠的原生文本，但不能把空结果标记为成功。知识库导入失败时保留来源和可重试上下文。

11. 实施阶段

阶段一

• 新增文档解析设置分类和持久化契约；
• 建立 DocumentParsingService，供聊天和知识库共用；
• 将无文本 PDF 识别为可触发 OCR 的明确状态；
• 接入 PP-OCRv6 Tiny、Small、Medium 的 ModelScope 下载、校验、ZIP 离线迁移、删除与 WASM Worker；
• 实现真实文件测试和六平台验证入口。

阶段二

• 增强 DOCX、XLSX、PPTX 语义结构；
• 实现按页混合文本层与 OCR；
• 增加版面、表格和阅读顺序。

阶段三

• 增加 LibreOffice 和 API 转换 Provider；
• 支持 DOC、XLS、PPT；
• 增加 MinerU、PaddleOCR-VL 等远程 OCR 服务连接配置；
• 增加高保真工作流和解析结果预览。

12. 验收

• 同一份扫描 PDF 可从聊天附件和知识库得到一致的逐页文本；
• 文本型 PDF 在 auto 模式下不运行 OCR；
• 本地 OCR 在六个平台和两种架构上完全离线运行；
• 模型文件损坏时拒绝加载并显示可恢复错误；
• 未安装模型时扫描文档提示用户前往“文档解析”下载，文本型文档仍可原生解析；
• 下载中可显示文件与总进度并允许取消，失败或取消后不留下已安装状态；
• ModelScope 下载与 ZIP 导入均经过同一大小和 SHA-256 校验；
• 语音和 OCR 模型可在联网设备导出 ZIP，并在离线设备导入后完成真实推理；
• 路径穿越、未知条目、错误模型 ID、篡改文件和超限 ZIP 均被拒绝；
• 超页数、超时、取消和关闭不会留下运行任务；
• 测试解析不会创建聊天消息或知识库文档；
• 选择本地模型时没有任何文档上传；
• 文档中的提示词不会改变系统、模式或工具权限。