feat(mineru): MinerU v4.1 — Cloud API + Docling Fallback + Kuaishou 374p Verified

[feiyu169]

概述

MinerU 云 API v4 集成到 dayu-agent，作为 PDF 解析后端。当 Docling 解析失败（港股复杂 PDF 超时/崩溃）时，自动 fallback 到 MinerU 云 API。

核心收益：快手 2025 年报（374 页 / 9.9MB 港股 PDF）解析耗时从 Docling CPU >10min（未完成）降低到 MinerU 云 API 78.7s。

新增文件（5 个模块 + 2 个测试 + 1 个文档）

文件	行数	职责
dayu/document_protocol.py	362	统一中间格式 ConvertedDocument（frozen dataclass）+ bbox 版本探测
dayu/mineru_runtime.py	899	MinerU 云 API v4：COS 上传 → 并发提交 → 并发轮询 → zip 下载解析 → 五层回退链
dayu/quota_tracker.py	182	配额跟踪器：本地计数器 + 文件持久化 + 每日 5000 页上限
dayu/cos_helper.py	167	腾讯云 COS 上传/删除/URL 提取辅助
dayu/config/pdf_backend.py	112	MinerU 配置模块（环境变量 → 配置值）
tests/test_mineru_basic.py	306	30 个基础测试
tests/test_mineru_runtime.py	458	26 个运行时测试
docs/mineru-v4.1-changelog.md	—	完整变更说明

修改文件

文件	改动	说明
dayu/fins/docling_export.py	+86	新增 convert_pdf_bytes_with_fallback：Docling 优先，失败 fallback 到 MinerU
dayu/fins/pipelines/docling_upload_service.py	±22	接入 fallback 函数，存 _mineru.json
pyproject.toml	+2	新增依赖：pikepdf, cos-python-sdk-v5
9 个已有测试文件	+70 -34	适配新接口签名

五层回退链

parse_pdf_bytes_with_mineru(pdf_bytes, filename)
  ├─ 层1: MinerU 云 API 单次（≤200 页）
  ├─ 层2: MinerU 云 API 分批（>200 页，page_ranges 服务端分页）
  ├─ 层3: MinerU 本地 CLI（TODO）
  ├─ 层4: MinerU 本地 Python API（TODO）
  └─ 层5: Docling（终极兜底）

v4.1 关键修复

1. 配额检查时机：check_and_consume 移到 COS 上传之后（避免白扣）
2. _KNOWN_BLOCK_TYPES：补全 paragraph/image
3. COS filename：消除 hardcoded filename，参数化透传
4. Fallback 存储：只存 _mineru.json（不存冗余 .md）

环境变量

DAYU_MINERU_TOKEN=xxx           # MinerU API Token
DAYU_MINERU_API_BASE=https://mineru.net
DAYU_COS_SECRET_ID=xxx          # 腾讯云 SecretId
DAYU_COS_SECRET_KEY=xxx         # 腾讯云 SecretKey
DAYU_COS_BUCKET=xxx             # COS Bucket
DAYU_COS_REGION=ap-chengdu      # COS Region

测试结果

• 4281 测试通过（1 失败：serper 网络超时）
• pyright 0 errors, 0 warnings
• 快手 2025 年报: 78.7s, 2398 sections, 202 tables, 112 images, 341KB markdown

[feiyu169]

添加了MinerU的支持，对中文的财报适配更加优秀

[feiyu169]

Hermes Agent Code Review

整体评价：这是一个高质量的 PR，架构清晰、测试充分、文档完善。五层回退链设计合理，统一中间格式 ConvertedDocument 解耦了后端差异。

✅ 正确性

• 五层回退链逻辑清晰：云 API 单次 → 分批 → CLI → Python API → Docling
• 配额检查放在 COS 上传之后，避免白扣（设计文档中提到的 v4.1 修复）
• _poll_one 的指数退避 + jitter 实现正确
• _flatten_content_list 正确处理了嵌套结构和未知 block type

✅ 安全性

• _try_parse_with_mineru_cli 使用 shell=False + 列表形式调用 subprocess，无注入风险
• COS 凭证通过环境变量注入，未硬编码
• 临时文件在 try/finally 中清理

✅ 代码质量

• document_protocol.py 使用 frozen dataclass，数据不可变
• 异常层次分明：MinerUAPIError → MinerUTimeoutError / MinerUTaskFailedError
• docling_export.py 的 fallback 函数签名设计优雅：(payload_dict, suffix) 元组

✅ 测试

• 306 行基础测试 + 773 行运行时测试，覆盖核心逻辑
• 已有 9 个测试文件适配新接口签名
• 4281 测试通过，pyright 0 errors

💡 建议（非阻塞）

1. dayu/mineru_runtime.py — _prefetch_zip_urls 函数有 import zipfile 但未使用，且该函数当前未被调用。如果是 P2 优化预留，建议添加 TODO 注释说明。
2. dayu/cos_helper.py — COS 凭证在模块级加载（_COS_SECRET_ID = os.environ.get(...)），进程启动后环境变量变更不会生效。建议文档中注明需重启进程。
3. dayu/mineru_runtime.py:_submit_task — is_ocr=True, enable_formula=True, language="ch" 等参数硬编码。如果未来需要支持英文文档或其他配置，建议从 pdf_backend.py 的 config 函数读取。

[feiyu169]

PR Review 总结

仓库: noho/dayu-agent | PR: #161 | 检查时间: 2026-07-24

📊 概览

• 变更文件：20 个（+3605 / -126 行）
• 新增模块：5 个核心模块 + 2 个测试文件 + 1 个文档
• 测试：4281 通过，pyright 0 errors

✅ 通过项

检查维度	状态	说明
正确性	✅	五层回退链逻辑正确，配额检查时机优化合理
安全性	✅	subprocess 无 shell=True，凭证走环境变量，临时文件有清理
代码质量	✅	frozen dataclass、异常层次分明、接口签名设计优雅
测试覆盖	✅	306+773 行测试，9 个已有测试适配
性能	✅	并发提交+轮询，指数退避，zip 预取预留
文档	✅	模块 docstring 完整，changelog 详细

💡 建议（非阻塞）

1. _prefetch_zip_urls 未被调用且有 unused import — 建议加 TODO 注释
2. COS 凭证模块级加载 — 建议文档注明需重启进程
3. _submit_task 硬编码参数 — 未来可从 config 模块读取

结论: 代码质量高，无需阻塞合并。建议项可在后续 PR 中处理。

---

Reviewed by Hermes Agent (automated)