iloom-flatten/skills/meoo-pdf/SKILL.md

name, description

name	description
meoo-pdf	使用此技能处理 PDF 文件的所有操作。包括：读取、提取文本/表格、合并/拆分 PDF、旋转页面、添加水印、创建新 PDF（支持中文）、填充 PDF 表单、提取图像以及对扫描件进行 OCR。触发场景：提及 '.pdf' 文件或要求生成/处理 PDF 成果。本技能已针对 meoo 沙箱环境优化，支持中文字体。

meoo-pdf: PDF 处理专家

⚠️ 核心执行原则

1. 环境适配：
   • 已预装 (Python)：pypdf, pdfplumber, reportlab, pandas。
   • 已预装 (Node.js)：pdf-lib。
   • 需按需安装：Poppler-utils (用于 pdftoppm 预览)、QPDF (用于高级页面操作/解密)、Tesseract-OCR (用于 OCR)。
2. 禁止直接读取：绝对禁止通过 read 或 view_file 工具直接读取此类二进制文件，这会导致乱码且无法获取有效信息。你必须使用本技能推荐的库编写脚本来解析内容。
3. 脚本执行：你必须先将脚本写入 home/project/tmp/ 目录（例如 home/project/tmp/process_pdf.py），然后运行。禁止使用 bash inline python。
4. 中文支持：沙箱已安装 fonts-wqy-microhei。在使用 reportlab 生成 PDF 时，必须注册并使用此中文字体。

---

📦 环境依赖安装指南

如果在执行过程中提示命令缺失，请先运行以下安装指令：

apt-get update && apt-get install -y poppler-utils qpdf tesseract-ocr

---

中文支持配置 (Python - ReportLab)

在生成 PDF 的脚本中注册中文字体：

from reportlab.pdfbase import ttfonts, pdfmetrics
from reportlab.platypus import Paragraph
from reportlab.lib.styles import getSampleStyleSheet

# 注册文泉驿微米黑
pdfmetrics.registerFont(ttfonts.TTFont('WenQuanYi', '/usr/share/fonts/truetype/wqy/wqy-microhei.ttc'))

# 使用示例
styles = getSampleStyleSheet()
styles['Normal'].fontName = 'WenQuanYi'
化学式：Paragraph("H<sub>2</sub>O", styles['Normal'])
数学公式：Paragraph("x<super>2</super>", styles['Normal'])

---

🎨 美学与专业美化指南 (Aesthetics Guide)

PDF 的专业感源于“秩序感”与“可访问性”：

1. CRAP 设计原则

• 对比 (Contrast)：标题字体需显著大于或黑于正文（建议正文 11-12pt）。
• 重复 (Repetition)：全文页眉、页脚、各级标题颜色必须保持 100% 视觉一致性。
• 对齐 (Alignment)：所有图片、文字块和表格必须基于隐形网格线对齐，严禁随意摆放位置。
• 亲密性 (Proximity)：图标与标签、图片与说明文字必须紧凑，不同章节间通过大留白区分。

2. 导航与交互

• 可点击目录：对于 5 页以上的文档，必须生成带有超链接的目录（TOC）和 PDF 书签（Bookmarks）。
• 禁止“图片化”：确保导出的 PDF 文字可选中、可搜索。严禁将整个文档转为单张大图 PDF。

3. 可访问性

• 为所有图表添加 Alt Text。
• 采用高对比度颜色组合（如黑字白底），确保内容易于阅读。

---

进阶功能

1. 元数据与加密 (pypdf)

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()
writer.append(reader)

# 设置元数据
writer.add_metadata({"/Title": "我的文档", "/Author": "meoo"})

# 加密
writer.encrypt("user_password", "owner_password")

with open("output.pdf", "wb") as f:
    writer.write(f)

2. 扫描件 OCR (自动化提取)

如果文档无可选文本，可将其转换为图像并使用 Tesseract：

from pdf2image import convert_from_path
import pytesseract

images = convert_from_path('scanned.pdf', dpi=300)
text = ""
for img in images:
    text += pytesseract.image_to_string(img, lang='chi_sim+eng')

---

常用工作流

1. 文本与表格提取

优先使用 pdfplumber 提取结构化数据：

import pdfplumber
with pdfplumber.open("input.pdf") as pdf:
    # 提取表格
    table = pdf.pages[0].extract_table()

2. 合并、拆分与旋转

使用 pypdf 进行基础页面操作：

from pypdf import PdfWriter
writer = PdfWriter()
writer.append("doc1.pdf")
writer.write("merged.pdf")

3. PDF 表单填充与标签

针对需要精准定位的表单填充或批注（基于图像坐标转换），请使用内置脚本：

python3 scripts/fill_pdf_form_with_annotations.py input.pdf fields.json output.pdf

4. 图片提取 (Image Extraction)

使用 pdfimages (来自 poppler-utils) 可以高效提取 PDF 中的原始图像：

# -j 参数确保将图像提取为 JPEG 格式
pdfimages -j input.pdf image_prefix

Tip

提取出的文件将命名为 image_prefix-000.jpg, image_prefix-001.jpg 等。

5. OCR 与扫描件处理

如果需要 OCR，需动态安装依赖：

apt-get update && apt-get install -y tesseract-ocr
pip install pytesseract

---

捆绑资源说明

• scripts/fill_pdf_form_with_annotations.py: 解决 PDF 坐标与图像坐标（DPI）映射的精准填充脚本。
• scripts/extract_form_field_info.py: 解析 PDF 表单域信息的辅助工具。