LEGO Parts Extractor

从 LEGO 说明书 PDF 中提取零件清单，生成符合模板格式的 Excel 文件。

工作流程总览

本技能支持两种输入源：PDF 文件 和 HTML 网页（含本地文件）。 根据输入类型选择对应工作流程：

• PDF 输入 → PDF 提取工作流程（见下方）
• HTML 输入 → HTML 提取工作流程（见下方）

PDF 提取工作流程

1. 确认输入文件

• PDF 文件位置（单个或批量）
• 模板 Excel 文件（用于颜色代码映射，可选）
• 输出目录

2. 提取 PDF 图片

LEGO 说明书通常是图片型 PDF，需要先提取内嵌图片：

import fitz  # pymupdf

doc = fitz.open(pdf_path)
for page_num in range(len(doc)):
    page = doc[page_num]
    pix = page.get_pixmap(dpi=150)
    pix.save(f"page_{page_num+1}.png")

3. 定位零件表页面

关键规则：零件表通常在特定页面，其他页面是拼搭步骤

• 先询问用户零件表在哪几页（如 "只有第3页是零件表"）
• 常见模式：Page 2-3 或仅 Page 3
• 拼搭步骤页面（Step 1, 2, 3...）不是完整零件清单

4. 视觉提取零件数据

从零件表图片中识别：

• 零件编号：如 3024, 3005, 4073 等
• 颜色名称：如 Black, White, Dark Bluish Gray 等
• 数量：每个零件的数量

5. 颜色代码映射

从模板 Excel 的 Sheet2 获取颜色代码：

• D列 = 颜色编号
• E列 = Stud.io 颜色名称

常见颜色映射（参考 references/color_codes.md）：

• Black = 026
• White = 001
• Dark Bluish Gray = 199
• Light Bluish Gray = 194
• Reddish Brown = 192

6. 生成 Excel 文件

输出格式（四列）： | 零件编号 | 颜色编号 | 数量 | 原始颜色名称 |

使用 scripts/generate_excel.py 批量生成。

HTML 提取工作流程

当用户提供 URL 或本地 HTML 文件时使用此流程。

1. 确认输入

• 在线网页：提供 URL（如 https://bricklink.com/...）
• 本地文件：提供 .html 文件路径
• 模板 Excel 文件（用于颜色代码映射，可选）
• 输出目录

2. 抓取 HTML 内容

支持两种方式：

方式 A：脚本自动抓取（推荐）

# 安装BeautifulSoup4（获得最佳提取效果）
pip install beautifulsoup4

# 从URL提取
python scripts/extract_html.py --url "https://example.com/parts" --set-name "MOC-001"

# 从本地HTML提取
python scripts/extract_html.py --file "parts.html" --set-name "MOC-001"

# 使用自定义选择器
python scripts/extract_html.py --url "https://example.com" --selector "table.parts"

# 批量处理（urls.txt 每行一个URL或文件路径）
python scripts/extract_html.py --batch urls.txt --output-dir output/

方式 B：AI 辅助提取

当 BeautifulSoup4 未安装时，将网页 URL 或 HTML 内容交给 AI 模型分析，从页面结构中提取零件数据。

3. 自动检测零件表

脚本会自动尝试以下常见选择器模式：

用户也可手动指定选择器：

--selector ".part-row"          # 指定容器
--part-selector "div[data-part]"  # 指定零件行

4. 提取零件字段

每个零件提取三个字段：

5. 输出 JSON 数据

提取结果以 JSON 格式输出（可指定 --output 保存到文件）：

{
  "set_name": "MOC-001",
  "parts": [
    {"part_num": "3024", "color": "Black", "qty": 5},
    {"part_num": "3005", "color": "White", "qty": 3}
  ]
}

6. 生成 Excel

将 JSON 数据传入 generate_excel.py 生成 Excel：

python scripts/generate_excel.py --data parts.json --template template.xlsx --output output/

关键注意事项

PDF 访问问题

• 文件名含 & 等特殊字符时，Python/PowerShell 可能无法直接访问
• 解决方案：使用 glob 匹配或复制到临时路径

HTML 抓取注意事项

• 编码问题：脚本自动尝试 UTF-8 → GBK → GB2312 → Latin-1 多种编码
• 反爬虫：部分网站（如 BrickLink）需要登录或设置了防护，建议先尝试直接抓取，若失败可手动保存 HTML 文件后本地处理
• BeautifulSoup4：强烈建议安装以获得最佳提取效果，未安装时自动降级为 AI 辅助提取
• SSL 证书：支持忽略自签名证书（内网场景）
• URL 含特殊字符：文件名含 & 等特殊字符时，Python 可能无法直接访问，可先复制到临时路径

Excel 文件锁定

• Windows 下 Excel 文件可能被 WPS/Edge 锁定
• 解决方案：生成到临时文件名，然后用 -Force 覆盖

颜色代码缺失

• 模板中可能缺少某些颜色
• 查阅 Stud.io 标准编号手动补充
• 参考 references/color_codes.md

编码问题

• Windows 下使用 openpyxl 而非 pandas（pandas 有中文编码问题）
• PowerShell 不支持 &&，用 ; 或分开执行

Resources

scripts/

• generate_excel.py - 批量生成 Excel 文件的主脚本
• extract_images.py - 从 PDF 提取图片
• extract_html.py - 从 HTML 网页/URL 提取零件数据（支持批量）

references/

• color_codes.md - LEGO 颜色代码映射参考

assets/

• template.xlsx - Excel 模板文件（可选，用户可指定自己的模板）