Pdfkit Py

pdfkit — AI 原生 PDF 处理工具

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

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

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

根据操作系统选择：

• macOS / Linux：

  bash ./scripts/setup.sh
  

• Windows（PowerShell）：

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

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

定位 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

pdfkit.py pdf_create --output report.pdf \
  --elements '[{"type":"heading","text":"标题"},{"type":"paragraph","text":"正文"}]' \
  --font_path fonts/DroidSansFallback.ttf

pdfkit.py pdf_create --output report.pdf \
  --elements '[{"type":"heading","text":"报告"},{"type":"paragraph","text":"内容"}]' \
  --page_size A4 --watermark '{"text":"草稿"}'

watermark — 添加水印

# 自动搜索字体（推荐）
pdfkit.py watermark --input doc.pdf --output out.pdf --text "机密"

# 指定字体
pdfkit.py watermark --input doc.pdf --output out.pdf \
  --text "机密" --font_path /path/to/font.ttf

# 密集模式 + 自定义样式
pdfkit.py watermark --input doc.pdf --output out.pdf \
  --text "CONFIDENTIAL" --mode dense --opacity 0.1 --angle 30

add_page_numbers — 添加页码

pdfkit.py add_page_numbers --input doc.pdf --output out.pdf
pdfkit.py add_page_numbers --input doc.pdf --output out.pdf \
  --position bottom_right --format "第 {page} 页 / 共 {total} 页" \
  --font_path fonts/DroidSansFallback.ttf

remove_headers_footers — 清除页眉页脚

# 仅识别
pdfkit.py remove_headers_footers --input doc.pdf --extract_only

# 清除
pdfkit.py remove_headers_footers --input doc.pdf --output clean.pdf

组织与变换 (10)

compress — 压缩 PDF

pdfkit.py compress --input doc.pdf --output out.pdf --quality ebook
pdfkit.py compress --input doc.pdf --output out.pdf --target_size_mb 5

split — 拆分 PDF

pdfkit.py split --input doc.pdf --output_dir /tmp/split/
pdfkit.py split --input doc.pdf --output_dir /tmp/split/ --mode ranges --ranges '[[0,2],[3,5]]'

merge — 合并 PDF

pdfkit.py merge --inputs '["a.pdf","b.pdf"]' --output merged.pdf

rotate — 旋转页面

pdfkit.py rotate --input doc.pdf --output out.pdf --angle 90
pdfkit.py rotate --input doc.pdf --output out.pdf --angle 180 --pages '[0,2]'

crop — 裁剪页面

# 裁剪第一页，保留左上角 400x500 区域
pdfkit.py crop --input doc.pdf --output out.pdf --left 0 --top 0 --right 400 --bottom 500

坐标使用统一坐标系（左上角原点，y↓）。

convert — 格式转换

pdfkit.py convert --input doc.pdf --output doc.docx --to_format docx
pdfkit.py convert --input doc.html --output doc.pdf --to_format pdf

pdf_to_word — PDF 转 Word

pdfkit.py pdf_to_word --input doc.pdf --output doc.docx
pdfkit.py pdf_to_word --input doc.pdf --output doc.docx --pages '[0,5]'

bookmarks — 书签管理

# 获取书签
pdfkit.py bookmarks --action get --input doc.pdf

# 设置书签
pdfkit.py bookmarks --action set --input doc.pdf --output out.pdf \
  --bookmarks '[{"level":1,"title":"第一章","page":0},{"level":2,"title":"1.1 节","page":2}]'

安全与表单 (8)

encrypt — 加密

pdfkit.py encrypt --input doc.pdf --output out.pdf --user_password "secret"
pdfkit.py encrypt --input doc.pdf --output out.pdf \
  --user_password "read" --owner_password "admin" --allow_print --allow_copy

decrypt — 解密

pdfkit.py decrypt --input encrypted.pdf --output out.pdf --password "secret"

form_detect — 检测表单

pdfkit.py form_detect --input form.pdf

form_fill — 填写表单

pdfkit.py form_fill --input form.pdf --output filled.pdf \
  --fields '[{"field_id":"name","value":"张三"},{"field_id":"date","value":"2026-01-01"}]'

form_fill_annotation — 注释方式填表

pdfkit.py form_fill_annotation --input form.pdf --output filled.pdf \
  --form_fields '[{"page":0,"x":100,"y":200,"text":"张三","font_size":12}]'

flatten — 扁平化

pdfkit.py flatten --input form.pdf --output flat.pdf
pdfkit.py flatten --input doc.pdf --output flat.pdf --flatten_annotations --pages '[0,1]'

redact — 涂黑脱敏

# 按文本涂黑
pdfkit.py redact --input doc.pdf --output out.pdf \
  --redactions '[{"type":"text","text":"身份证号","page":-1}]'

# 按区域涂黑
pdfkit.py redact --input doc.pdf --output out.pdf \
  --redactions '[{"type":"area","rect":[100,200,300,230],"page":0}]'

# 按正则涂黑
pdfkit.py redact --input doc.pdf --output out.pdf \
  --redactions '[{"type":"regex","pattern":"\\d{18}","page":-1}]'

redactions 支持的类型：

sign_pdf — 数字签名

pdfkit.py sign_pdf --input doc.pdf --output signed.pdf \
  --signature '{"text":"张三","position":"bottom_right"}'

pdfkit.py sign_pdf --input doc.pdf --output signed.pdf \
  --signature '{"image":"seal.png","position":[400,50],"width":150,"height":60}' \
  --pages '[0]'

signature 字段：

IR 中间表示 (5)

ir_export — 导出 PDF 结构为 JSON

pdfkit.py ir_export --input doc.pdf --output structure.json
pdfkit.py ir_export --input doc.pdf --output structure.json --include_images --include_fonts

ir_import — 从 JSON 重建 PDF

pdfkit.py ir_import --input structure.json --output rebuilt.pdf

ir_inspect — 结构摘要

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

ir_modify — 精准修改

pdfkit.py ir_modify --input doc.pdf --output out.pdf \
  --operations '[{"type":"replace_text","page":0,"find":"旧文本","replace":"新文本"}]'

operations 支持的类型：

ir_diff — 对比差异

pdfkit.py ir_diff --left old.pdf --right new.pdf
pdfkit.py ir_diff --left old.pdf --right new.pdf --output diff.json --text_only

元工具 (4)

detect_type — 检测页面类型

pdfkit.py detect_type --input doc.pdf
pdfkit.py detect_type --input doc.pdf --pages '[0,1]'

exec_python — 沙箱执行 Python

最后手段，仅当现有命令无法完成时使用。

pdfkit.py exec_python --code 'import fitz; doc=fitz.open("doc.pdf"); print(len(doc))'

layout_engine — 排版引擎

内部使用，一般不直接调用。

扩展机制（Extension）

当内置的命令无法满足复杂需求时（如多步骤批处理流程、特殊格式转换、业务定制逻辑等），可以通过扩展脚本来扩充能力。

工作原理

扩展脚本放在 skill basedir 的 ../pdfkit-extension/scripts/ 目录下，与内置命令遵循完全相同的接口约定（COMMAND、DESCRIPTION、PARAMS、handler），由 pdfkit.py 自动发现和注册。

/path/to/skills/                        ← skill basedir 的父目录
├── pdfkit-py/                          ← pdfkit skill 目录（skill basedir）
│   ├── scripts/
│   │   ├── pdfkit.py                   ← 入口（自动扫描扩展）
│   │   └── pdfkit/commands/            ← 内置 50 个命令
│   └── ...
└── pdfkit-extension/                   ← 扩展目录（用户创建，与 pdfkit-py 同级）
    └── scripts/
        ├── batch_watermark.py          ← 扩展脚本 1
        ├── invoice_extract.py          ← 扩展脚本 2
        └── ...

查看可用扩展

pdfkit.py extension --help

使用扩展命令

扩展命令可以像内置命令一样直接调用：

# 直接调用
pdfkit.py batch_watermark --input_dir /tmp/pdfs --text "机密"

# 通过 extension 子命令调用
pdfkit.py extension batch_watermark --input_dir /tmp/pdfs --text "机密"

# 查看扩展命令帮助
pdfkit.py batch_watermark help

创建扩展脚本

1. 创建扩展目录：

mkdir -p <skill basedir>/../pdfkit-extension/scripts

2. 复制模板：

cp <skill basedir>/scripts/pdfkit/extension_template.py \
   <skill basedir>/../pdfkit-extension/scripts/my_script.py

3. 编辑脚本，修改 COMMAND、DESCRIPTION、PARAMS 和 handler 函数。

扩展脚本模板结构

COMMAND = "my_extension"              # 命令名
DESCRIPTION = "我的自定义 PDF 扩展"     # 描述
CATEGORY = "extension"                # 分类
PARAMS = [
    {"name": "input", "type": "str", "required": True, "help": "输入 PDF"},
    {"name": "output", "type": "str", "required": True, "help": "输出 PDF"},
]

def handler(params):
    # 处理逻辑...
    return {"message": "done", "output": params["output"]}

适用场景

执行策略

遇到复杂 PDF 任务时：

1. 先查看是否有可复用的扩展：pdfkit.py extension --help
2. 有现成扩展 → 直接调用
3. 没有现成扩展但内置命令可组合完成 → 拆解为多个内置命令依次执行
4. 需要新扩展 → 为用户创建扩展脚本到 ../pdfkit-extension/scripts/

执行规范

1. 先理解需求：分析用户描述，确定操作和参数
2. 参数确认：关键参数缺失时先问用户
3. 不确定参数时：运行 pdfkit.py <command> help 查看完整参数说明
4. 路径处理：输入用用户路径，输出未指定时给合理默认值（同目录，或 macOS/Linux 用 /tmp/、Windows 用 %TEMP%）
5. 复杂 JSON 参数：优先写入文件后用 --config 传入
6. 页码从 0 开始：用户说"第 1 页"→ 参数 0
7. 错误处理：
   • 依赖缺失 → 提示安装
   • 加密 PDF → 提示用户提供密码
   • 扫描件文本为空 → 建议用 edit_scanned 或 ocr_locate
8. 复合操作：拆解后依次执行（如「提取第 3-5 页并转图片」= split + to_images）

场景速查