description	用于读取、生成、拆分、合并、加密、提取文本/表格/图片或 OCR 处理 PDF 文件的请求。
lazy_load	true
name	pdf
think_type	react

PDF Processing Skill

🚀 中文排版唯一入口：@[skfile:scripts/font_setup.py] — 自动发现系统字体 + CID fallback，一行代码搞定 FONT_TITLE / FONT_BODY。详见 @[skfile:references/chinese-typography.md]

Overview

PDF 全能处理技能。支持 读取/创建/编辑 PDF 三大类操作，内置跨平台中文字体引擎和风格化布局能力。

Capabilities & Triggering

🎯 该技能处理什么

能力域	具体操作	依赖库
读取与提取	文本、表格、元数据、图片提取	pypdf, pdfplumber
页面操作	合并、拆分、旋转、水印、加密/解密	pypdf
PDF 创建	文本/表格/多页/中文排版 PDF	reportlab
中文字体	自动注册系统字体 + CID fallback	@[skfile:scripts/font_setup.py]
扫描件 OCR	图片型 PDF 文字识别	pytesseract, pdf2image

🚫 什么情况下不应激活此技能

不适用场景	说明	建议替代
纯图片处理与转换（非 PDF 场景）	如 JPG→PNG、图片滤镜	使用通用图片处理能力
PDF 内图层/注释编辑	本技能不处理 PDF 内嵌注释或图层操作	—
PDF 表单填写与提取	不处理 AcroForm / XFA 表单	—
大语言模型对 PDF 内容的理解/总结	仅提取原始文本/表格，不进行语义分析	交由 LLM 处理提取后的文本

🔄 触发流程

用户请求 → 判断是否涉及 .pdf 文件或 PDF 操作
   ├─ 是 → 激活本技能
   │     ├─ 读取/提取类 → 生成 Python 脚本 → Lint 检查 → 运行 → 返回结果
   │     ├─ 创建/编辑类 → 生成 Python 脚本 → Lint 检查 → 运行 → 返回产出文件
   │     └─ 中文排版 → 通过 @[skfile:scripts/font_setup.py] 注册字体 → 按规范排版
   └─ 否 → 不激活

Work Flow

理解需求 — 判断用户要的是读取、创建、编辑还是转换操作
初始化目录 — 确保 @[param:thread_dir]/tmps/ 与 @[param:user_work_dir] 存在
- 中间脚本、临时文本、调试文件写入 @[param:thread_dir]/tmps/
- 最终 PDF、Excel、文本等交付文件写入 @[param:user_work_dir]
- 错误日志写入 @[param:thread_dir]/tmps/error.log
依赖检查 — 生成脚本前先确认所需库可导入；缺失时先告知用户缺少的包，不要生成必然失败的脚本
- 基础 PDF 创建：reportlab
- PDF 读取/合并/拆分/加密：pypdf
- 表格提取：pdfplumber，导出 Excel 时还需要 pandas 与 openpyxl
- OCR：pytesseract、pdf2image，且系统需安装 Tesseract 与 Poppler
生成脚本 — 使用 write tool 生成 Python 脚本到 @[param:thread_dir]/tmps/
- 创建 PDF 时，除非用户明确要求，否则禁止在 PDF 内容中使用 Emoji 表情符号（如 ❌ ✅ ⚠️ 🚀 ⭐ 等）
- 应使用纯文本替代：如 [x]/[✓]、注意、重要 等
- 文字颜色必须保证高可读性：正文使用黑色（#000000 或 black），标题使用黑色或深色（如 #1a1a1a、#333333）
- 禁止使用浅色/淡色文字：如灰色（#999999、#cccccc）、浅蓝、浅绿等低对比度颜色
- 背景色必须为白色或极浅色：禁止使用深色背景（如深蓝 #1a237e、深灰 #333333、黑色背景等），深色背景会使深色文字难以辨认
- 如需强调，使用加粗或下划线替代浅色文字或深色背景
Lint 检查 — 运行语法检查，确保代码无语法错误（详见下方 Lint 检查流程）
执行脚本 — 使用 @[tool:py_exec] 的 file 参数执行生成的 Python 脚本
- 不要用 shell 执行 python / python3 / pip
- 不要拼接 @[param:python_env]\python、@[param:python_env]/bin/python 或 @[param:py_exe]
- 输出文件必须按第 2 步目录规则保存
返回结果 — 提取类返回文本/表格内容，创建/编辑类返回 @[param:user_work_dir] 下的最终文件路径

Lint 检查流程

生成的 Python 脚本在运行前必须通过语法检查，杜绝"边运行边报错边修改"的情况。流程如下：

生成代码 → 写入 .py 文件 → py_compile 编译检查
                                ↓
                          ✅ 通过 → 继续执行脚本
                                ↓
                          ❌ 失败 → 分析错误 → 重写修正 → 重新编译
                                                     ↓
                                          (最多重试 3 次)
                                ↓
                   3 次均失败 → 报告错误信息给用户

具体操作

优先使用 @[tool:py_exec] 执行短代码完成编译检查：

import py_compile
py_compile.compile(r"<file_path>", doraise=True)

编译通过后，使用 @[tool:py_exec] 的 file="<file_path>" 执行脚本。
不要用 shell 调用 Python 编译或执行脚本。
如果编译错误包含编码问题，检查文件头是否包含 # -*- coding: utf-8 -*-

图片产物不验证规则

生成的图片保存完成后，禁止对图片文件内容进行二次验证或审查，包括但不限于：

❌ 禁止调用 analyze_image 对生成的图片内容进行识别、比对或检查
❌ 禁止任何形式的图片内容解读：不询问"图片里画了什么"、"图表数据是否准确"等
❌ 禁止将图片传给外部工具做 OCR/图形识别
✅ 允许的行为仅限：确认图片文件是否存在、文件大小是否合理、文件格式是否正确

执行检查

如果在 lint 检查后的完成报告中包含对图片内容的描述（如"图表显示了正确的数据分布"），应予以删除或替换为仅报告文件路径和尺寸。

Failure Strategy

失败场景	回退策略
字体注册失败（中文显示方框□□□）	引擎自动降级为 CID 字体（STSong-Light / STHeiti-Light），始终可用
PDF 加密/损坏无法读取	提示用户确认文件完整性，尝试 `pypdf` 的 `strict=False` 模式
OCR 失败（Python 包或系统依赖缺失）	明确报告缺少 `pytesseract` / `pdf2image` / Tesseract / Poppler 中的哪一项；不要静默降级为普通文本提取，除非用户接受
表格提取为空	尝试调整 `extract_tables()` 参数（`vertical_strategy`, `horizontal_strategy`）
pypdf 不支持的加密格式	提示使用 PDF 解密工具或提供密码
ReportLab TTC 加载失败	字体引擎自动规避 TTC，改用 CID 字体
Lint 检查 3 次均失败	报告编译错误详情给用户，建议手动检查代码

Quick Reference

1. 读取 PDF

from pypdf import PdfReader

reader = PdfReader("input.pdf")
print(f"Pages: {len(reader.pages)}")
text = "".join(page.extract_text() for page in reader.pages)

2. 提取表格

import pdfplumber

with pdfplumber.open("input.pdf") as pdf:
    tables = [page.extract_tables() for page in pdf.pages]

3. 合并 PDF

from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf in ["doc1.pdf", "doc2.pdf"]:
    [writer.add_page(p) for p in PdfReader(pdf).pages]
writer.write("merged.pdf")

4. 拆分 PDF

reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    w = PdfWriter(); w.add_page(page)
    w.write(f"page_{i+1}.pdf")

5. 旋转页面

page = PdfReader("input.pdf").pages[0]
page.rotate(90)
writer = PdfWriter(); writer.add_page(page)
writer.write("rotated.pdf")

6. 提取元数据

meta = PdfReader("doc.pdf").metadata
print(f"Title: {meta.title}, Author: {meta.author}")

中文字体系统

统一方案：所有中文 PDF 创建场景使用 @[skfile:scripts/font_setup.py] 注册字体。禁止直接注册 CID 字体或手动指定字体文件路径（字体引擎内部已自动处理 CID fallback）。

# ✅ 唯一入口：智能字体引擎
import importlib.util
from pathlib import Path

FONT_SETUP_PATH = Path(r"@[skfile:scripts/font_setup.py]")
spec = importlib.util.spec_from_file_location("pdf_font_setup", FONT_SETUP_PATH)
font_setup = importlib.util.module_from_spec(spec)
spec.loader.exec_module(font_setup)
setup_font_env = font_setup.setup_font_env

status = setup_font_env(print_report=True)          # 自动发现系统字体 + CID fallback
FONT_TITLE = status['title_font']                   # e.g. 'MicrosoftYaHei' / 'PingFangSC'
FONT_BODY  = status['body_font']                    # e.g. 'SimSun' / 'STSong'

工作原理：

自动检测操作系统 → 遍历系统字体目录 → 注册最佳可用字体
若系统字体不可用 → 自动降级为 CID 字体（STSong-Light / STHeiti-Light），不出方框乱码
返回 FONT_TITLE / FONT_BODY 变量，直接用于 reportlab 样式定义

📐 完整的中文字体样式规范（配色方案、层级体系、商务报告完整示例、排版排查）详见： @[skfile:references/chinese-typography.md]

reportlab - 创建中文 PDF

🚫 Emoji 禁用规则：生成的 PDF 内容中，除非用户明确要求，否则禁止使用任何 Emoji 表情符号。标题、正文、表格、页眉页脚等所有文本内容均适用。 🎨 颜色与背景规则：所有文字颜色必须保证高可读性。正文使用黑色（#000000 / black），标题使用深色（#1a1a1a、#333333）。禁止使用浅色/淡色文字（如 #999999、#cccccc、浅蓝、浅绿等低对比度颜色）。背景色必须为白色或极浅色，禁止使用深色背景（如深蓝 #1a237e、深灰 #333333、黑色背景等）。强调内容用加粗或下划线替代浅色文字或深色背景。

核心模式（含中文 + 多页）

import importlib.util
from pathlib import Path
from reportlab.lib.pagesizes import A4
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
from reportlab.lib.styles import ParagraphStyle
from reportlab.lib.enums import TA_CENTER, TA_LEFT

FONT_SETUP_PATH = Path(r"@[skfile:scripts/font_setup.py]")
spec = importlib.util.spec_from_file_location("pdf_font_setup", FONT_SETUP_PATH)
font_setup = importlib.util.module_from_spec(spec)
spec.loader.exec_module(font_setup)
setup_font_env = font_setup.setup_font_env

# 1. 注册字体（唯一入口）
status = setup_font_env()
FONT_TITLE, FONT_BODY = status['title_font'], status['body_font']

# 2. 定义样式
s_title = ParagraphStyle('Title', fontName=FONT_TITLE, fontSize=18, leading=28, alignment=TA_CENTER)
# ⚠️ 中文排版关键：使用 TA_LEFT（左对齐）+ charSpace=0，避免中文字间距被拉开
s_body  = ParagraphStyle('Body',  fontName=FONT_BODY,  fontSize=12, leading=20, alignment=TA_LEFT,
                         charSpace=0, wordSpace=0)

# 3. 构建文档
doc = SimpleDocTemplate("output.pdf", pagesize=A4)
story = [
    Paragraph("悯农 · 李绅", s_title),
    Spacer(1, 12),
    Paragraph("锄禾日当午，汗滴禾下土。", s_body),
    PageBreak(),
    Paragraph("第 2 页内容", s_body),
]
doc.build(story)

⚠️ 常见陷阱

问题	原因	方案
中文显示方框(□□□)	未通过字体引擎注册字体	调用 `setup_font_env()` 即可解决
TTC 加载失败	ReportLab 对 TTC 兼容性差	字体引擎自动规避，内部用 CID fallback
下标/上标乱码	Unicode 下标字符(₀₁₂₃)不支持	用 `<sub>`/`<super>` XML 标签
中文 PDF 字间距过大（字符被拉开）	使用了 `TA_JUSTIFY` 两端对齐，或未设置 `charSpace=0`	正文使用 `TA_LEFT` 左对齐 + `charSpace=0, wordSpace=0`；正文推荐优先使用 MicrosoftYaHei 字体

pdfplumber - 高级表格提取

import pandas as pd
import pdfplumber

with pdfplumber.open("input.pdf") as pdf:
    all_tables = []
    for page in pdf.pages:
        for table in page.extract_tables():
            if table:
                df = pd.DataFrame(table[1:], columns=table[0])
                all_tables.append(df)

if all_tables:
    pd.concat(all_tables, ignore_index=True).to_excel("output.xlsx", index=False)

OCR - 扫描件文字识别

# Requires: pip install pytesseract pdf2image
import pytesseract
from pdf2image import convert_from_path

# 注意：除 Python 包外，还需要系统安装 Tesseract OCR 与 Poppler。
# 这些系统依赖缺失时，应向用户报告并停止，不要把扫描件当作普通文本 PDF 处理。

images = convert_from_path('scanned.pdf')
text = "".join(f"Page {i+1}:\n{pytesseract.image_to_string(img)}\n\n"
               for i, img in enumerate(images))

安全操作

添加水印

from pypdf import PdfReader, PdfWriter

watermark = PdfReader("watermark.pdf").pages[0]
writer = PdfWriter()
for page in PdfReader("doc.pdf").pages:
    page.merge_page(watermark)
    writer.add_page(page)
writer.write("watermarked.pdf")

加密保护

from pypdf import PdfReader, PdfWriter

writer = PdfWriter()
for page in PdfReader("input.pdf").pages:
    writer.add_page(page)
writer.encrypt("userpass", "ownerpass")
writer.write("encrypted.pdf")

索引

内容	位置
中文字体样式规范（配色/层级/风格引擎）	@[skfile:references/chinese-typography.md]
字体自动注册引擎	@[skfile:scripts/font_setup.py]
完整商务报告示例（含配色）	@[skfile:references/chinese-typography.md]（配色方案章节）
可配置多行文本排版（歌词/诗歌）	@[skfile:references/chinese-typography.md]（多行排版章节）
常见排版问题排查表	@[skfile:references/chinese-typography.md]（排查表章节）