pdf-2

pdf-2

用途

此技能支持高级 PDF 处理，包括对图像进行 OCR 以提取文本、提取表单数据、将表格解析为结构化格式、验证和添加数字签名、合并/拆分 PDF，以及处理注释。它专为在 OpenClaw 中自动化文档工作流而设计。

适用场景

当任务涉及扫描版或复杂 PDF 时，请使用此技能，例如提取带表格和表单的发票数据、验证带签名的法律文件，或通过合并文件来准备报告。处理不可搜索的 PDF（例如使用 OCR），或需要与其他工具集成以构建文档流水线时，也可使用此技能。

主要功能

• OCR：使用 Tesseract 引擎提取文本；通过 --lang 标志指定语言（例如，英语使用 --lang eng）。
• 表单提取：将 PDF 表单解析为 JSON；使用 --fields 标志提取文本框或复选框等字段。
• 表格解析：检测表格并将其转换为 CSV；使用 --layout auto 或 --layout grid 指定布局。
• 数字签名：使用 --verify 标志验证签名；使用 --sign 和证书路径添加新签名。
• 合并/拆分：通过 --inputs 标志合并多个 PDF；按页码范围拆分，例如 --pages 1-5。
• 注释：使用 --extract-annotations 或 --add-annotation type=highlight text="Note" 提取或添加注释（例如高亮）。

用法模式

对于一次性任务，通过 CLI 调用；对于脚本化工作流，通过 API 调用。使用管道串联命令，例如将 OCR 输出传给文本处理器。批量处理时，在脚本中使用循环。务必明确指定输入/输出路径。处理大型文件时，设置 --timeout 300 以延长操作时间。在 JSON 配置文件中设置默认值，例如 {"default_lang": "eng"}。

常用命令/API

CLI 命令：

• OCR：openclaw pdf-2 ocr --input path/to/file.pdf --lang eng --dpi 300 --output extracted.txt
• 表单提取：openclaw pdf-2 extract-form --file form.pdf --fields name,address --output data.json
• 表格解析：openclaw pdf-2 parse-table --input table.pdf --page 2 --output tables.csv
• 签名验证：openclaw pdf-2 verify-signature --file signed.pdf --cert path/to/cert.pem
• 合并 PDF：openclaw pdf-2 merge --inputs file1.pdf file2.pdf --output merged.pdf
• 拆分 PDF：openclaw pdf-2 split --input original.pdf --pages 1-3 --output split_folder/

API 端点：

• OCR：使用 JSON 请求体向 /api/pdf-2/ocr 发送 POST 请求：{"file": "base64encoded_string", "lang": "eng", "dpi": 300}
• 表单提取：向 /api/pdf-2/extract-form 发送 POST 请求，请求体为：{"file": "base64encoded", "fields": ["name", "address"]}
• 表格解析：向 /api/pdf-2/parse-table 发送 POST 请求，请求体为：{"file": "base64encoded", "page": 2}

代码片段：

1. 使用 Python API 调用进行 OCR：

   import requests; import os; import base64
   api_key = os.environ['OPENCLAW_API_KEY']
   response = requests.post('https://api.openclaw.ai/api/pdf-2/ocr', headers={'Authorization': f'Bearer {api_key}'}, json={'file': base64.b64encode(open('file.pdf', 'rb').read()).decode()})
   

2. 在 shell 脚本中使用 CLI：

   export OPENCLAW_API_KEY=your_key
   openclaw pdf-2 ocr --input input.pdf --output output.txt
   

配置格式： API 请求或 CLI 配置使用 JSON，例如 {"lang": "eng", "timeout": 60}。保存为 .json 文件，并通过 --config path/to/config.json 传入。

集成说明

API 调用需要通过环境变量进行身份验证：设置 OPENCLAW_API_KEY=your_api_key。对于 CLI，请确保已安装 OpenClaw CLI（例如通过 npm install openclaw 安装）并完成身份验证。通过管道传递输出与其他服务集成，例如将 OCR 结果发送给 NLP 工具。在 API 请求体中通过 base64 编码处理文件上传。对于 Webhook，请使用 /api/pdf-2/webhook 端点，并在请求中提供回调 URL。

错误处理

检查 API 错误的 HTTP 状态码（例如，输入错误时为 400，未授权时为 401）；解析 JSON 响应以获取 {"error": "File not found"} 等详细信息。对于 CLI，错误会输出到 stderr，并附带代码（例如，失败时退出代码为 1）。处理常见问题：使用 try-except 处理 API 超时，例如在 Python 中：try: requests.post(...) except requests.exceptions.Timeout: print("Timeout occurred")。在执行命令前验证输入，例如使用 os.path.exists() 检查文件是否存在。使用指数退避策略重试暂时性错误。

具体使用示例

1. 从扫描版发票 PDF 中提取并解析表格：

   • 首先执行 OCR：openclaw pdf-2 ocr --input invoice_scanned.pdf --lang eng --output ocr_output.txt
   • 然后解析表格：openclaw pdf-2 parse-table --input invoice_scanned.pdf --page 1 --output invoice_tables.csv
   • 这会生成一个 CSV 文件，供后续分析使用，例如导入数据库。

2. 合并 PDF 并验证报告的签名：

   • 合并文件：openclaw pdf-2 merge --inputs report_part1.pdf report_part2.pdf --output final_report.pdf
   • 验证签名：openclaw pdf-2 verify-signature --file final_report.pdf --cert company_cert.pem
   • 如果有效，则继续；否则，记录错误并处理。

图关系

• 依赖于：ocr-1（提供核心 OCR 功能）
• 集成了：document-1（用于通用文档存储和检索）
• 冲突项：无
• 相关项：pdf-1（基础 PDF 处理，这是其高级版本）
• 集群归属：community（用于协作技能的共享集群）