原始底稿流水线 v13.2（双输出：JSON 主 + MD 辅）

> 本文档描述一套通用材料全量转录流水线：把任意批量材料转写为结构化底稿，供下游 AI 工具消费。核心能力是双引擎 OCR 交叉核对 + 四档裁决 + 多模态兜底 + 防偷懒合约。

版本记录

功能实现状态

架构总览

┌─────────────────────────────────────────────────────┐
│  输入：批量材料（PDF / 图片 / 邮件 / Word / 音频）      │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  Phase 0  文件预标准化（<2 分钟）                      │
│  - 路径编码规范化（临时目录 + 映射表）                  │
│  - 压缩包跳过（只标注占位，不解包）                    │
│  - 文件头探测真实类型（不信任扩展名）                  │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  Phase 1  五路并行处理                                │
│  ├─ 文字型 PDF → PyMuPDF（50+ 页/秒）                 │
│  ├─ 扫描件 PDF → 双引擎 OCR 批量                      │
│  ├─ 图片      → 双引擎 OCR（普通）/ 多模态（长截图）    │
│  ├─ 邮件      → Python email 模块                    │
│  └─ 音频      → 转文字工具                            │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  Phase 2  交叉核对 + 四档裁决                          │
│  ≥95% 自动定稿 → 80-95% 定稿+差异标记 →               │
│  <80% AI 语义终裁 → 双引擎均失败 多模态兜底            │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  Phase 3  一次性组装（JSON 主 + MD 辅）                │
│  + 防偷懒合约（V0.5 确定性门禁）                       │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  Phase 4  V 阶段验证审查（三方视角）                   │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  输出：底稿 JSON（主）+ 底稿 MD（辅）+ schema.json     │
└─────────────────────────────────────────────────────┘

双引擎 OCR 交叉核对（核心能力）

0. 执行概览

文件输入
  │
  ├─ 文字型PDF → PyMuPDF（本地极速，50+页/秒）
  │
  ├─ 扫描件PDF / 图片
  │     │
  │     ├─ 中文打印体/截图/流水 → PaddleOCR 主力 + MinerU 核对
  │     ├─ 英文/外文合同         → MinerU 完整版 主力 + PaddleOCR 补缺
  │     └─ 纯图片框图/组织结构图  → 直接多模态（跳过 OCR API）
  │     │
  │     └─ 双引擎并行调用（线程池）
  │            │
  │            ├─ 相似度 ≥95% → 自动定稿（A级）
  │            ├─ 相似度 80-95% → 定稿+差异标记（B级）
  │            ├─ 相似度 <80% 或单引擎失败 →
  │            │     先 AI 语义终裁排假警报
  │            │     ├─ 实质一致 → 定稿
  │            │     └─ 真冲突 → 多模态兜底 / 人工复核
  │            └─ 双引擎均失败 → 多模态兜底（C级）
  │
  ├─ 微信长截图/复杂表格 → 直接多模态（跳过 OCR）
  │
  └─ Word/音频 → 对应工具处理

1. 引擎选择铁则（核心原则：按语言和类型选权威源）

代码化实现：_detect_language() 自动检测文本语言（CJK vs Latin 字符比例），_cross_check() 在四档裁决时自动按语言切换权威源。

实测经验：英文合同场景下 PaddleOCR 类引擎对数字严重欠提取（数字 token 可能仅为主引擎的约 1/9，丢失附件/价格表/付款条款）——英文材料必须以 MinerU 类完整版为权威源。

2. 双引擎并行调用

Step 1: 文件类型检测 → 分配引擎（中文 → PaddleOCR 主；英文 → MinerU 主）
Step 2: 双引擎并行调用（线程池，max_workers=2）
Step 3: 文本清洗（两引擎独立清洗后比对）
  ├─ 剥离 HTML 标签
  ├─ HTML 表格 → Markdown 表格（展开 colspan/rowspan）
  ├─ 解码 HTML 实体
  └─ 去多余空白、统一换行
Step 4: 交叉核对（四档裁决）
  ├─ ≥95%    → auto_resolved（A级）
  ├─ 80-95%  → auto_resolved_with_diff（B级）
  ├─ <80%    → 进入 AI 语义终裁
  └─ 单引擎   → single_engine（B级）
Step 5: 置信度评分（A-E）
Step 6: 结果输出（primary_text / diff_markup / confidence / status）

3. AI 语义一致性终裁（核心经验）

核心教训：机械相似度数字 ≠ 内容准确度。低相似度常为"格式/膨胀差异"而非"识别错误"。

触发条件：相似度 <80% / 英文合同 / 双引擎长度差 >2×

诊断顺序（先排除假警报）：

相似度低（如 13%）
  ├─ ① HTML 表格膨胀？ 主引擎含原始 <table> 块（4–16×膨胀）
  │     → 先 HTML→Markdown 清洗再比（清洗后常 ≥95%）
  ├─ ② 引擎选择错？ 英文合同误用 PaddleOCR 作权威源
  │     → 改以 MinerU 为主
  ├─ ③ 格式差异？ 截图/凭证类 UI 元素保留程度不同
  │     → 内容其实一致
  └─ ④ 以上皆否 → 才是真识别错误 → 多模态兜底 / 人工复核

4. 多模态兜底（OCR 失败时的终级防线）

多模态转录质量控制：
1. 完整逐字转录：不能摘要，不能省略细节
2. 保留原始格式：换行、段落、表格结构尽量保留
3. 标记不确定内容：模糊/难以辨认的文字用 [?] 标记
4. 输出前先说明图片内容类型（聊天记录/银行流水/合同/其他）

5. 差异标记落地

80-95% 相似度文件，用 <ins>/<del> 标记具体差异段落（不是只写相似度数值）：

付款金额：<del>¥1,234,567.89</del><ins>¥1,234,587.89</ins>
收款方：XX科技有限公司

6. 置信度 A-E 评分标准

置信度标注范式（落到每份材料）：

7. 引擎级批量处理（性能优化 + 失败隔离）

当处理 ≥2 个扫描件 PDF 时，必须走引擎级批量路径：

单个扫描件 PDF → 双引擎并行（单文件）
≥2 扫描件 PDF → 引擎级批量
   ├─ MinerU 批量接口（一批 ≤50 文件）
   ├─ PaddleOCR 多任务并行提交 + 统一轮询
   └─ 结果对齐 → 逐文件交叉核对

失败隔离：批量提交时单文件失败或文件不存在不再拖垮整批，失败文件单独标记 error，其余正常返回。

实测数据（真实项目，11 个 PDF / 127 页）：单文件级并行 43.9s → 引擎级批量 20.14s（提升约 54%）。

8. 失败降级矩阵

9. 脚本调用入口

# 组装底稿 JSON + MD 双输出
from assemble_json import ManuscriptAssembler
asm = ManuscriptAssembler()
result = asm.assemble("案件简称", reports, "输出目录")
# result = {"status": "ok", "json_path": ..., "md_path": ..., "material_count": N}
#         或 {"status": "degraded", "md_path": ..., "error": "..."}（自动降级 MD）

# 或走 parallel_main 闭环入口（依赖 OCR 后端）
from parallel_main import assemble_manuscript_output
result = assemble_manuscript_output("案件简称", parallel_results, output_dir)

# 自动环境检查
python auto_env_check.py

三条硬性规则（P0 强制）

环境配置

自动环境检查

启动时自动检测 OCR API 连通性，未配置时使用降级模式（速度较慢）：

python auto_env_check.py

期望输出：

PaddleOCR API: ✅ 已配置
MinerU API:    ✅ 已配置

API 配置

OCR 引擎（PaddleOCR / MinerU）的 token 通过环境变量注入，禁止硬编码：

# Linux/macOS
export PADDLEOCR_TOKEN="your_token"
export MINERU_TOKEN="your_token"

# Windows PowerShell
$env:PADDLEOCR_TOKEN = "your_token"
$env:MINERU_TOKEN = "your_token"

或通过配置文件（路径由 OCR_API_CONFIG 环境变量指定，默认 ~/.workbuddy/ocr_api_config.json）：

{"paddleocr": {"token": "..."}, "mineru": {"token": "..."}}

降级模式

Phase 0：文件预标准化（<2 分钟）

消除路径编码问题的根源。所有后续步骤的前提。

0a：创建项目临时目录

{temp_dir}/{project_slug}/
├── pdf\     (PDF001.pdf, PDF002.pdf, ...)
├── img\     (IMG001.jpg, IMG002.png, ...)
├── audio\   (AUD001.mp3, ...)
├── txt\     (TXT001.txt, ...)
└── mapping.json  (原始名→临时名映射表)

0b：跳过压缩包（R1 规则）

SKIP_EXTENSIONS = {'.zip', '.rar', '.7z', '.tar', '.gz', '.bz2', '.xz'}

遇到压缩包，记录到 skipped_archives 列表，后续在底稿中标注。

0c：识别文字型 PDF

用 PyMuPDF 快速探测每个 PDF 是否有可提取的文字（第一页 >50 字符 → 文字型，走快速通道）。

0d：文件类型探测（不信任扩展名）

通过文件头检测实际类型（PDF: %PDF-；ZIP 含 docx: PK\x03\x04；PNG: \x89PNG；JPEG: \xff\xd8）。文件名/扩展名可能误导（如"记录.png"实际是聊天截图，不是银行流水）——始终用文件头检测 + 内容预览确认。

Phase 1：五路并行处理（核心）

主 Agent（只协调不执行）
    │
    ├── Phase 0：主 Agent 执行预标准化（<2min）
    │
    ├── Phase 1a：子 Agent-邮件 → 并行提取全部 .eml（~2min）
    │
    ├── Phase 1b：子 Agent-PDF（文字型）→ PyMuPDF 快速提取（<30s）
    │
    ├── Phase 1b：子 Agent-PDF（扫描/复杂）→ 双引擎 OCR（~5min）
    │
    ├── Phase 1c：子 Agent-图片 → 双引擎 OCR（~3min）
    │
    ├── Phase 1c：子 Agent-图片（长截图/复杂表格）→ 多模态完整转录
    │
    └── Phase 1d：子 Agent-音频 → 转文字工具（~5min）
    │
    ▼
Phase 2：交叉核对报告 + 差异裁决 + 多轮自验证
Phase 3：一次性组装

Phase 2：交叉核对汇总 + 差异裁决 + 多轮自验证

四档裁决规则

差异标记落地方法

80-95% 相似度文件，用 <ins>/<del> 标记具体差异段落（difflib 逐段对比）。

多轮自验证

同一工具调用多次（不同参数/预处理），结果稳定就通过：

第1遍：默认参数
第2遍：调整图片预处理（二值化/降噪）
第3遍：调整 OCR 参数（更细致识别）

3 次结果一致 → 通过
规范化后一致 → 通过（标注 normalized）
不一致 → 标记不确定，建议人工复核

多模态抽样验证（核心经验固化）

核心发现：策略差异 ≠ 内容错误。 截图类/凭证类文件即使双引擎相似度只有 56%，图片本身极清、文字 100% 可读、OCR 结果均准确。

验证逻辑：

问题: N 个文件双引擎相似度 56-95%
     ↓
假设: 策略差异 ≠ 内容错误（截图类文件本身清晰）
     ↓
验证: 用多模态模型读取相似度最低的 10-25% 文件
     ↓
发现: 图片极清 → 文字 100% 可读 → OCR 结果准确 → 差异=提取策略
     ↓
裁决: 抽样 100% 通过 → 整体 N 个文件全部通过 → 0 人工复核

关键经验总结：

Phase 3：一次性组装

> 职责边界：本流水线只做结构化标记（金额/日期/主体等），不做材料分类、不做证明目的分析——那些是下游分析环节的职责。

结构化关键信息标记

在转录文本中自动标记语义锚点（<!-- EVID: [类型] [内容摘要] -->）：
- 金额标记（¥/$/USD/EUR/元/万）
- 日期标记（YYYY年M月D日 等）
- 主体标记（公司/机关/机构全称）

防偷懒合约条款（V0.5 确定性门禁）

> 本流水线是偷懒重灾区。以下条款为硬合约，自动检查，不达标 BLOCK，不得交付。

合约 1：JSON 结构完整性（防"简化版蒙混"）

• claim：每件材料 JSON 必须含 pages[blocks{type,bbox,content}] 完整结构，transcript_fulltext 为全文转录
• verification：deterministic（脚本逐件检查 pages/blocks/bbox 字段存在性）
• threshold：材料总数 N → JSON 条目 N 条 → 含 pages+blocks+bbox 的条目 = N
• consequence：任何一件缺 bbox → BLOCK，报告具体缺失字段与材料编号

合约 2：schema 版本一致性（防"贴错标签"）

• claim：schema_version 必须与实际 JSON 结构一致
• verification：deterministic（脚本比对版本标签与实际结构）
• consequence：版本标签与实际结构不匹配 → BLOCK，标记"贴错标签"

合约 3：材料全量覆盖（防"截断凑数"）

• claim：输入材料全部处理，输出条目数 = 输入材料数
• verification：deterministic（输入计数 vs JSON materials 长度）
• consequence：输出 < 输入且无解释 → BLOCK

合约 4：双引擎交叉核对不可省（防"单源冒充"）

• claim：每件材料必须经 ≥2 独立引擎处理，或明示降级原因
• verification：deterministic（检查 engine_source 字段 + cross_check_stats 统计）
• consequence：single_engine 条目未标注降级原因 → WARNING；未走交叉核对流程 → BLOCK

反合理化检查

Phase 4：V 阶段验证审查

三方独立审查

审修一体闭环

发现问题 → 判断严重程度 → 选择修复方式 → 执行修复 → 重新审查 → 循环直到全部通过

交付形式审查

收尾

1. 知识反哺：将本次底稿制作经验写入项目记忆
2. 产物推送：展示底稿给用户
3. 临时文件清理：删除临时目录

输出结构（JSON 主 + MD 辅双输出）

输出路径：项目底稿目录（如 [项目底稿目录]/01_原始底稿/）

[案件简称]_原始底稿.json   ← 主格式：机器消费（下游 AI 工具优先读这个）
[案件简称]_原始底稿.md    ← 辅助格式：人眼核校 / 审查 / 团队阅卷
schema.json               ← Schema 契约（下游消费字段规范）

JSON 结构（schema_version 1.0.0）

{
  "schema_version": "1.0.0",
  "metadata": {
    "case_name": "[案件简称]",
    "generated_at": "YYYY-MM-DD HH:MM:SS",
    "total_materials": 0,
    "processing_stats": {"auto_resolved": 0, "auto_resolved_with_diff": 0,
                         "multimodal_rescued": 0, "need_multimodal": 0, "single_engine": 0},
    "cross_check_stats": {"A": 0, "B": 0, "C": 0, "D": 0, "E": 0}
  },
  "materials": [
    {
      "m_id": "M001",
      "source_file": "合同扫描件.pdf",
      "file_type": "pdf|image|word|email|audio|unknown",
      "ocr_status": "auto_resolved|auto_resolved_with_diff|multimodal_rescued|need_multimodal|single_engine",
      "confidence": "A|B|C|D|E",
      "similarity": 0.97,
      "engine_source": "mineru|paddleocr|multimodal_vision",
      "language": "zh|en",
      "pages": [
        {
          "page_idx": 0,
          "blocks": [
            {
              "type": "text|title|table|image|equation|list|code|discarded",
              "bbox": [x0, y0, x1, y1],
              "text_level": 0,
              "content": "…",
              "engine_source": "mineru|paddleocr"
            }
          ]
        }
      ],
      "diff_markup": "…（80-95% 定稿时含 <ins>/<del>）",
      "transcript_fulltext": "…（全文转录，MD 渲染的数据源）",
      "raw_structured": {
        "mineru_content_list": null,
        "mineru_middle": null,
        "paddle_layouts": null
      }
    }
  ]
}

MD 结构（从 JSON 渲染）

# 原始底稿：[案件简称]
> 生成时间：YYYY-MM-DD HH:MM
> 材料总数：X 件
> 质量控制：双引擎 OCR 交叉核对 ✅ | 结构化 JSON 输出 ✅ | AI 语义终裁 ✅ | 多模态兜底 ✅
> 自动定稿：N 件 | 差异标记定稿：M 件 | 多模态转录：K 件 | 待人工复核：L 件

## 处理统计
## 交叉核对统计

# 正文
## M001：[材料名称]
### 来源信息
- 原始文件：`[文件名]`
- 处理方式：MinerU 结构化解析（权威源）/ 多模态完整转录…
- 核对状态：✅ 自动定稿（A级）…
- 双引擎相似度：97.00%
### 全文转录

依赖

# 核心依赖（轻量）
pip install requests pymupdf python-docx

不需要安装本地 AI 模型：OCR 走线上引擎 API，多模态走主模型视觉。

本仓库 scripts/：
- assemble_json.py：交叉核对报告 → 底稿 JSON + MD 渲染 + Schema 校验（零外部依赖，可直接运行）
- parallel_main.py：文件级并行调度 + 智能路由 + 双输出闭环入口（依赖 OCR 后端接口，见 ocr_backend.py）
- ocr_backend.py：OCR 引擎接口契约 + Mock 演示（真实调用需自行实现 parse_file()）
- auto_env_check.py：自动检测 OCR API 配置状态
- test_assemble_json.py：组装器功能测试（模拟真实交叉核对报告）

边界

本技能不做什么：
- 不筛选提取（那是下游梳理环节的事）
- 不分析法律含义（那是策略分析环节的事）
- 不做多次版本迭代（Phase 3 一次性组装）
- 不依赖本地 AI 模型（OCR 走线上 API，多模态走主模型）
- 不做材料分类
- 不生产 Word/PDF 交付卷（JSON→MD 由本流水线产出；最终交付卷由下游环节导出）

运行环境

• 推荐：在支持技能/工具调用的 AI 工作台（如 WorkBuddy）中运行——多模态兜底、AI 语义终裁依赖主模型视觉识别能力
• 最小：标准 Python 3.8+ 环境（assemble_json.py 零依赖可跑；完整流水线需配置 OCR 引擎 token + 可选安装 PyMuPDF/python-docx）
• OCR 引擎 token 通过环境变量注入（禁止硬编码）