product-doc-reader

name	product-doc-reader
description	产品工程图纸结构化提取器 v5.0。pdftotext 优先 + Vision 兜底，支持软连字符清理/跨行关联/数据校验。专为 Your Company 线材产品图纸设计。
metadata	{"openclaw":{"emoji":"📐","version":"5.0.1","requires":{"anyBins":["python3","pdftoppm"]}}}

Product Doc Reader 📐

产品工程图纸 → 结构化数据 (v5.0.1 修复版)

将 PDF 格式的产品图纸自动转换为结构化 JSON 和 Markdown，专为线材/连接器产品图纸设计。

v5.0.1 最新修复（2026-03-24）：

• ✅ 软连字符清理（\xad 导致产品名断裂）
• ✅ 跨行关联优化（长度值分行问题）
• ✅ 数据校验增强（排除 BJ 编号/电气参数/线材规格）
• ✅ 599-028 修复（右上角客户品名信息栏提取）

---

🎯 使用场景

• 客户发来产品图纸 PDF，需要提取 BOM、规格参数
• 批量处理工程图纸，建立产品数据库
• 图纸内容归档到知识库（Obsidian/Markdown）
• 图纸比对（新旧版本 BOM 差异）
• 客户图纸适配（C331 等非福睿标准模板）
• Excel 模具号列自动填充

---

🏗️ 架构 (v5.0 混合策略)

PDF 图纸
  ├─→ pdftotext（精确文本，保留布局）⭐ 优先
  │     ├─→ 清理软连字符 \xad
  │     ├─→ BOM 物料清单（字体嵌入，100% 准确）
  │     ├─→ 产品规格矩阵（跨行关联）
  │     └─→ 字段规则识别（BJ/599-xxx/ITEM）
  │
  ├─→ pdftoppm（PDF → PNG，300 DPI）
  │     └─→ Vision API（Gemini 2.5 Flash）⭐ 兜底
  │           ├─→ 布局理解
  │           ├─→ 图形/尺寸标注
  │           ├─→ 测试要求结构化表格
  │           └─→ 多页合并
  │
  └─→ 合并策略
        ├─→ 模具号：pdftotext 优先（精确）
        ├─→ 产品名：pdftotext 优先（排除 BOM 词汇）
        ├─→ 包装规范：pdftotext 优先（BJ 精确匹配）
        ├─→ 长度：pdftotext 优先（跨行关联）
        ├─→ 测试要求：Vision 结构化表格
        └─→ 字段校验 + 置信度评分

字段识别规则

规则	示例	说明
BJ + 8 位数字	BJ0599-0002	包装规范（福睿内部编码）
599-xxx	599-002	Drawing No. / 物料编码
ITEM 栏的值	5001-127A	Model No.（客户图纸常见）
CUSTOMER ITEM	HDACFM	客人品名
MODEL NO.	OP-DP09	型号（多产品图纸）

数据校验规则

校验项	规则	示例
模具号格式	必须包含字母 + 数字	✅ 5001-130A ❌ P
排除单字符	长度 ≤ 2	❌ P, 1
排除 BJ 开头	包装规范	❌ BJ0599-0002
排除 599 开头	Drawing No.	❌ 599-002
产品名长度	> 3 字符	❌ 300, 60H
排除纯数字	长度值	❌ 9144, 10000
排除电气参数	电压/频率	❌ 300V, 60HZ
排除线材规格	导体规格	❌ 32BC, 511BC

---

🔧 依赖

工具	用途	安装
python3	运行脚本	系统自带
pdftoppm	PDF 转 PNG	brew install poppler
tesseract	OCR 备用（可选）	brew install tesseract tesseract-lang

不再依赖： docling

---

📋 快速使用

基本提取（混合模式，推荐）

cd skills/product-doc-reader
python3 scripts/extract_hybrid.py <图纸.pdf>
# 输出到 ./output/<图纸名>.json 和 .md

输出到指定目录

python3 scripts/extract_hybrid.py <图纸.pdf> -o /path/to/output -f both

输出 JSON 到 stdout（管道使用）

python3 scripts/extract_hybrid.py <图纸.pdf> --stdout -f json

纯 Vision 模式（备用）

python3 scripts/extract_hybrid.py <图纸.pdf> --vision-only

纯文本模式（快速）

python3 scripts/extract_hybrid.py <图纸.pdf> --text-only

参数说明

参数	说明	默认
pdf_path	PDF 文件路径（必填）	-
-o, --output-dir	输出目录	配置文件 output_dir
-f, --format	输出格式：json / md / both	配置文件 format
--config	覆盖配置文件路径	config/default.json
--vision-only	仅用 Vision API	关闭
--text-only	仅用 pdftotext	关闭
--stdout	输出到 stdout	关闭
--dpi	OCR DPI（默认 300）	300
--no-cache	禁用 Vision 缓存	关闭

配置文件

默认配置位于 config/default.json，包含：

• 默认输出格式、输出目录、置信度阈值、Vision 缓存目录
• Vision provider/model
• 模板识别规则：farreach_599 / customer_c331 / english_title_block
• 数据校验规则：模具号排除前缀、产品名排除词、线材规格/电气参数过滤规则

CLI 参数优先级高于配置文件。

Vision 兜底与缓存

混合模式下，脚本先跑 pdftotext。只有关键字段缺失、BOM 为空、结果低于置信度阈值，或使用 --vision-only 时，才会调用 Vision。

Vision 结果按 PDF 内容 hash + prompt hash + model 生成缓存 key，默认写入配置中的 cache_dir。重复处理同一文件会复用缓存；需要强制重新调用时使用 --no-cache。

批量处理与断点续跑

python3 scripts/batch_process_drive.py --input-dir ./drawings --output-dir ./output --resume
python3 scripts/batch_process_drive.py --drive-folder-id <folder_id> --output-dir ./output --resume

批处理会生成：

• .product-doc-reader-state.json：每个文件的成功/失败、输出路径、错误原因、更新时间
• accepted/：置信度达标且无关键 warning 的结果
• review/：置信度低于阈值或存在 warning 的结果
• batch-summary.md：成功、失败、待复核数量和原因

可用参数：

• --resume：跳过已成功项目
• --force：重新处理已成功项目
• --confidence-threshold 80：设置待复核阈值
• --state-file <path>：指定断点状态文件

SSA 投递台集成

投递台 runtime 会在本地保存上传文件后，对疑似产品图纸 PDF 触发 product-doc-reader。触发条件包括：

• 本地分类为 Product Spec
• 文件名或说明包含 599-xxx、drawing、technical、spec、datasheet、catalog

提取摘要会写入 intake record 的 analysis.productDoc，包含产品名、模具号、图纸号、包装规范、BOM 行数、置信度、warnings、是否需人工复核。该集成只保存分析结果，不移动文件、不同步 CRM、不发送外部消息。

---

📊 输出结构

JSON 字段

{
  "product_name": "HDMI2CABLE4K6030F, HDMI2CABLE4K6010M",
  "model_no": "5001-131A",
  "drawing_no": "599-028",
  "packaging_spec": "BJ0599-0053, BJ0599-0055",
  "material_code": "599-028",
  "length_mm": "9144+50, 10000+50",
  "mold_info": "",
  "mold_number": "",
  "bom": [
    {
      "no": "①",
      "part_name": "CABLE",
      "spec": "HDMI2 4K60 30AWG...",
      "quantity": "M"
    }
  ],
  "tolerances": [
    { "range": "0.5-3.0", "hardware": "±0.05", "plastic": "±0.1" }
  ],
  "test_requirements": {
    "table": [],
    "other_tests": ["100% OPEN SHORT MISS WIRE TEST", "PASS 4K@60HZ"]
  },
  "pin_assignment": {
    "connectors": ["HDMI"],
    "description": ""
  },
  "dimensions": ["11.33±0.3", "20.8±0.3"],
  "notes": ["ROHS compliant"],
  "revision_history": [
    { "revision": "A0", "date": "2026/03/17", "description": "" }
  ],
  "company": "珠海福睿电子 FARREACH",
  "drawing_date": "2026/03/17",
  "drawn_by": "Kenny",
  "checked_by": "X.J.C",
  "approved_by": "Lin.",
  "products": [
    {
      "customer_item": "HDMI2CABLE4K6030F",
      "length_mm": "9144+50",
      "material_code": "599-028",
      "packaging_spec": "BJ0599-0053"
    }
  ],
  "source_file": "599-028.pdf",
  "extraction_method": "hybrid",
  "pages": 1,
  "confidence": 100.0,
  "warnings": []
}

---

✅ 测试结果（58 份 599 系列图纸）

产品类型	图纸数量	模具号范围	成功率
HDMI 转接头	7	AD4001-009 ~ MB-003	100%
HDMI 线缆	20	5001-119A ~ OP-HD65	100%
DP-HDMI 转换器	8	AP-073A / AP-079A	100%
USB-C 转 HDMI	3	OP-USB09 / TP-C089B	100%
DP 光纤线缆 (AOC)	1	OP-DP09 (7 款)	100%
KVM 线缆	5	DP-033A ~ 5001-127A	100%
USB 转接头	3	AD9017 / USB-3005A-014	100%
DP 线缆	1	DP-021B	100%

总计： 58/58 (100%)

---

⚠️ 已知限制与优化建议

1. Google Drive 搜索分页

问题： gog drive search "599" 只返回 17 个结果，实际有 58 个。

解决： 逐个搜索 599-001 到 599-058。

2. 产品名提取依赖排除列表

问题： 需要手动添加新 BOM 词汇。

解决： 已添加 50+ 排除词，后续发现新词继续添加。

3. 批量处理断点续传

现状： batch_process_drive.py 已支持状态文件、--resume、--force、失败隔离和低置信度分离。

4. 特殊模板适配

问题： 客户图纸（如 C331 模板）字段位置不同。

解决： 已支持跨行关联（上下 5 行搜索）。

5. 数据校验需人工审核

现状： 置信度低于阈值或存在 warning 的结果会自动进入 review/，仍需人工确认后再入库。

---

📁 文件结构

product-doc-reader/
├── SKILL.md                      ← 本文件
├── DEVELOPMENT_SUMMARY.md        ← 开发总结（踩坑记录）
├── config/
│   └── default.json              ← 默认输出、模板、校验、缓存配置
├── scripts/
│   ├── extract_hybrid.py         ← v5.0.1 核心提取脚本
│   ├── batch_599_full.py         ← 旧 599 批处理脚本
│   └── batch_process_drive.py    ← 可续跑批处理脚本
├── tests/
│   ├── test_extract_hybrid.py    ← parser/cache/config 回归测试
│   └── test_batch_processor.py   ← 续跑和复核分离测试
├── examples/
│   └── hybrid/                   ← 测试输出示例
└── output/                       ← 默认输出目录

---

🔄 版本历史

版本	日期	改进
v5.0.1	2026-03-24	599-028 修复：软连字符清理/跨行关联/数据校验
v5.0.0	2026-03-24	pdftotext 优先 + 数据校验规则
v4.0.0	2026-03-23	pdftotext + Vision 混合策略
v3.0.0	2026-03-23	纯 Vision API（Gemini Flash）
v2.0.0	2026-03-23	Docling + 区域分割 + Tesseract OCR

---

📞 维护者

开发： WILSON
测试： Jaden
最后更新： 2026-03-24 15:00

---

Product Doc Reader v5.0.1 - 生产就绪 ✅