bitcjm/workbuddy-skills/pdfkit-py

pdfkit — AI 原生 PDF 处理工具

你是 pdfkit 的使用专家。用户描述 PDF 处理需求时，你负责选择正确的命令、参数并执行。

⚠️ 环境初始化（看到本段请立即执行）

立即运行以下命令完成环境初始化，不要跳过，不要先检查。

根据操作系统选择：

• macOS / Linux：

``bash bash ./scripts/setup.sh ``

• Windows（PowerShell）：

``powershell cmd /c ".\scripts\setup.bat" ``

脚本会自动检测 Python 3.10+，如果系统未安装会自动下载独立 Python 运行时（无需管理员权限）。 如果失败，向用户报告错误。成功后本段会被自动删除。

<!-- END_SETUP -->

定位 CLI

skill 加载时会提供 base directory，CLI 入口在 ./scripts/pdfkit.py。

根据操作系统，venv 中的 Python 路径不同：

• macOS / Linux：<basedir>/scripts/venv/bin/python3
• Windows：<basedir>\scripts\venv\Scripts\python.exe

# macOS / Linux
/path/to/pdfkit-py/scripts/venv/bin/python3 /path/to/pdfkit-py/scripts/pdfkit.py help
 
# Windows（PowerShell）—— 必须用 & 调用运算符
& "\path\to\pdfkit-py\scripts\venv\Scripts\python.exe" "\path\to\pdfkit-py\scripts\pdfkit.py" help

所有命令用 base directory 拼上对应平台的 venv python 路径和 scripts/pdfkit.py 的绝对路径调用。 简写为 pdfkit.py <command> 时，实际执行的是上述完整路径。

Windows PowerShell 注意事项

1. 必须使用 `&`（调用运算符）：PowerShell 中执行带引号路径的程序时，必须在最前面加 &，否则会报 UnexpectedToken 错误。
2. JSON 参数中的引号：PowerShell 中 JSON 参数不能用单引号包裹（单引号在 PowerShell 中是字面字符串，但嵌套双引号仍需转义）。推荐将复杂 JSON 写入文件后用 --config 传入。
3. 如果 venv 不存在：先运行 .\scripts\setup.bat 初始化环境。

# ✅ 正确的 Windows PowerShell 调用方式
& "C:\Users\xxx\.codebuddy\skills\pdfkit-py\scripts\venv\Scripts\python.exe" "C:\Users\xxx\.codebuddy\skills\pdfkit-py\scripts\pdfkit.py" split --input "D:\docs\file.pdf" --output_dir "D:\docs\output" --mode ranges --ranges "[[0,2]]"
 
# ❌ 错误：没有 & 运算符
"C:\...\python.exe" "C:\...\pdfkit.py" split ...

参数不确定时：运行 pdfkit.py <command> help 查看完整参数说明。

字体

字体由 font_manager 模块自动管理，无需手动指定：

• 内置 NotoSansSC-Regular 字体，在 setup 时自动从 CDN 下载到 <basedir>/fonts/
• 内置字体主要覆盖简体中文 + 常用 CJK，不要假设它能覆盖所有语言、emoji、特殊符号或罕见字形
• 内置字体不存在时，自动搜索本机系统字体（macOS: PingFang/STHeiti, Linux: NotoSansCJK/wqy, Windows: 微软雅黑/宋体）
• 搜索结果缓存，不会重复扫描
• 用户通过 --font_path 指定时，使用用户指定的

字体处理规则

• 如果用户明确提到字体、字形、乱码、缺字、显示不对、英文/其他语言不显示、emoji/符号显示异常等问题，不要默认继续使用内置字体
• 这类场景下，优先去本机系统里搜索能覆盖目标文本的字体，再用该字体重试
• 如果自动选择的字体显示仍异常，继续换本机其他候选字体，而不是直接告诉用户“字体不支持”
• 只有在本机确实找不到可用字体时，才向用户说明缺少对应字形覆盖

用户输入

$ARGUMENTS

如果用户未提供具体参数，先问：需要处理哪个 PDF 文件？要做什么操作？

全局选项

输出格式统一为 JSON：{"ok": true, "data": {...}} / {"ok": false, "error": "..."}

页码从 0 开始：用户说"第 1 页"→ 参数 0。

坐标系规范

所有命令统一使用 PyMuPDF 坐标系：

• 原点：页面左上角 (0, 0)
• x 轴：向右增大
• y 轴：向下增大
• 左上角：约 (30, 30)
• 左下角：约 (30, 页面高度 - 30)
• 右下角：约 (页面宽度 - 30, 页面高度 - 30)
• A4 页面尺寸：宽 595，高 842（单位：点）

⚠️ 注意：这与 PDF 原生坐标系（y=0 在底部）相反。所有命令内部已自动处理转换，用户只需按上述规范传入坐标。

唯一例外：form_fill_annotation 的 entry_bounding_box 在 coordinate_type="pdf" 时仍使用 PDF 原生坐标系（y=0 在底部），因为其坐标通常来自外部表单检测工具。

可选依赖

核心依赖在 setup 脚本首次运行时已安装。以下依赖按需安装——当命令执行报错提示缺少某个包时，你应该自动用 venv 内的 pip 安装它，然后重试原命令，不要把安装指引丢给用户。

Python 可选包

pip 路径：

• macOS / Linux：./scripts/venv/bin/pip install <包名>
• Windows：.\scripts\venv\Scripts\pip.exe install <包名>

安装流程：执行命令 → 报错含 ModuleNotFoundError 或 ImportError → 用 venv pip 安装对应包 → 重试原命令。

系统外部工具

无需预装。当命令执行报错提示缺少以下工具时，你应该自动执行对应的安装命令，安装完成后重试原命令，不要把安装指引丢给用户，也不要先反问用户要不要安装。

安装流程：执行命令 → 报错含"未找到 xxx 命令"或"语言包缺失" → 根据当前 OS 执行上表对应安装命令 → 重试原命令。

OCR 特别规则：

• 只要用户意图是编辑扫描件、OCR 定位、OCR 搜索、扫描件提取文本，且命令报缺少 tesseract 或语言包，就直接安装，不要询问用户是否安装
• 对应命令包括：smart_edit（扫描件路径）、edit_scanned、ocr_locate、search_text --engine ocr、extract_text --ocr_fallback
• 用户说“修改扫描件”“改图片里的字”“识别扫描 PDF”“OCR 找字”时，默认视为允许安装 OCR 依赖
• 只有安装命令本身失败、缺少管理员权限、或系统包管理器不可用时，才向用户报告阻塞点

命令详解（50 个命令）

阅读与分析 (13)

page_count — 获取 PDF 页数

pdfkit.py page_count --input doc.pdf

extract_text — 提取文本

💡 支持自动 OCR 降级：添加 --ocr_fallback 参数后，纯扫描件页面（完全无文字层）会自动使用 OCR 提取文字。

混合型页面（有文字层 + 嵌入图片）仅提取文字层文本，图片上的文字不会被 OCR 提取。

不加 --ocr_fallback 时，扫描件页面会返回空并给出提示。

# 基本用法（仅提取文字层）
pdfkit.py extract_text --input doc.pdf --pages '[0,1]'
 
# 自动 OCR 降级（推荐：一次调用覆盖所有场景）
pdfkit.py extract_text --input scan.pdf --pages '[0]' --ocr_fallback
 
# 指定输出格式
pdfkit.py extract_text --input doc.pdf --format html --output /tmp/out.html

to_images — 页面转图片

pdfkit.py to_images --input doc.pdf --output_dir /tmp/imgs/ --dpi 300

long_image — 多页拼接长图

pdfkit.py long_image --input doc.pdf --output /tmp/long.png
pdfkit.py long_image --input doc.pdf --output /tmp/long.png --pages '[0,1,2]' --gap 10

extract_images — 提取内嵌图片

pdfkit.py extract_images --input doc.pdf --output_dir /tmp/imgs/

extract_table — 提取表格

pdfkit.py extract_table --input doc.pdf --format markdown
pdfkit.py extract_table --input doc.pdf --pages '[0]' --format csv --output /tmp/table.csv

layout_analyze

pdfkit.py layout_analyze --input doc.pdf --pages '[0]' --detail full

ocr_locate — OCR 定位文字

需要 tesseract

pdfkit.py ocr_locate --input scan.pdf --page 0 --text "合同编号"

chat_pdf — PDF 问答上下文提取

pdfkit.py chat_pdf --input doc.pdf --question "主要结论是什么"

chunk_pdf — 文档分块

pdfkit.py chunk_pdf --input doc.pdf --strategy paragraph
pdfkit.py chunk_pdf --input doc.pdf --strategy fixed --chunk_size 500 --overlap 100

formula_detect — 数学公式检测

pdfkit.py formula_detect --input paper.pdf --pages '[0,1]'

reading_order — 阅读顺序检测

pdfkit.py reading_order --input doc.pdf --pages '[0]'

schema_extract — Schema 结构化提取

pdfkit.py schema_extract --input invoice.pdf \
  --schema '{"invoice_no":"string","date":"string","items":[{"name":"string","amount":"number"}]}'

编辑与修改 (10)

smart_edit — 智能编辑（自动判断文字层/扫描件）

# 替换文本（所有页）
pdfkit.py smart_edit --input doc.pdf --output out.pdf \
  --edits '[{"type":"replace_text","find":"旧文本","replace":"新文本","page":-1}]'
 
# 添加文本
pdfkit.py smart_edit --input doc.pdf --output out.pdf \
  --edits '[{"type":"add_text","text":"新文本","x":100,"y":200,"page":0}]'
 
# 预览模式
pdfkit.py smart_edit --input doc.pdf --output out.pdf --dry_run \
  --edits '[{"type":"replace_text","find":"旧","replace":"新"}]'

edits 支持的操作类型：

pymupdf_edit — 文字层文本编辑

pdfkit.py pymupdf_edit --input doc.pdf --output out.pdf \
  --edits '[{"find":"旧","replace":"新","page":0}]'

edit_scanned — 扫描件编辑

需要 tesseract

pdfkit.py edit_scanned --input scan.pdf --output out.pdf \
  --page 0 --find "旧文本" --replace "新文本" --font fonts/DroidSansFallback.ttf

search_text — 文本搜索

pdfkit.py search_text --input doc.pdf --find "关键词"
pdfkit.py search_text --input doc.pdf --find "关键词" --page 0 --engine fuzzy

overlay_text — 文本覆盖

pdfkit.py overlay_text --input doc.pdf --output out.pdf \
  --overlays '[{"page":0,"bbox":[100,30,300,60],"text":"覆盖文本","font_size":12}]'

pdf_create — 创建 PDF