paddleocr-doc-parsing

PaddleOCR 文档解析 Skill

何时使用此 Skill

适用于以下情况：

• 含有表格的文档（发票、财务报告、电子表格）
• 含有数学公式的文档（学术论文、科学文档）
• 含有图表和示意图的文档
• 多栏布局（报纸、杂志、宣传册）
• 需要进行版面分析的复杂文档结构
• 任何需要结构化理解的文档

以下情况请改用文本识别：

• 仅提取简单文本
• 对速度要求很高的快速 OCR 任务
• 含有清晰文本的屏幕截图或简单图像

如何使用此 Skill

⛔ 强制限制 - 切勿违反 ⛔

1. 只能使用 PaddleOCR 文档解析 API - 执行脚本 python scripts/vl_caller.py
2. 切勿直接解析文档 - 不要自行解析文档
3. 切勿提供替代方案 - 不要建议“我可以尝试分析一下”或类似说法
4. 如果 API 失败 - 显示错误消息并立即停止
5. 不得使用备用方法 - 不要尝试通过其他方式解析文档

如果脚本执行失败（API 未配置、网络错误等）：

• 向用户显示错误消息
• 不要提出使用你的视觉能力提供帮助
• 不要询问“你想让我尝试解析吗？”
• 只需停止并等待用户修复配置

基本工作流

1. 执行文档解析：

   python scripts/vl_caller.py --file-url "URL provided by user" --pretty
   

   或解析本地文件：

   python scripts/vl_caller.py --file-path "file path" --pretty
   

   可选：显式设置文件类型：

   python scripts/vl_caller.py --file-url "URL provided by user" --file-type 0 --pretty
   

   • --file-type 0：PDF
   • --file-type 1：图像
   • 如果省略，服务可以根据输入推断文件类型。

   默认行为：将原始 JSON 保存到临时文件：

   • 如果省略 --output，脚本会自动将文件保存到系统临时目录下
   • 默认路径格式：<system-temp>/paddleocr/doc-parsing/results/result_<timestamp>_<id>.json
   • 如果提供 --output，则会覆盖默认临时文件保存位置
   • 如果提供 --stdout，则会将 JSON 输出到 stdout，且不保存文件
   • 在保存模式下，脚本会在 stderr 中输出保存文件的绝对路径：Result saved to: /absolute/path/...
   • 在默认或自定义保存模式下，响应前先读取并解析已保存的 JSON 文件
   • 在保存模式下，始终告知用户保存文件的路径，并说明其中包含完整的原始 JSON
   • 仅当你明确希望跳过文件持久化时才使用 --stdout

2. 输出 JSON 包含所有文档数据，内容完整，包括：

   • 页眉、页脚、页码
   • 正文
   • 含结构信息的表格
   • 公式（含 LaTeX）
   • 插图和图表
   • 脚注和参考文献
   • 印章和图章
   • 版面和阅读顺序

   输入类型说明：

   • 支持的文件类型取决于模型和端点配置。
   • 始终遵循端点 API 文档中说明的文件类型限制。

3. 从输出 JSON 中提取用户需要的内容，使用以下字段：

   • 顶层 text
   • result[n].markdown
   • result[n].prunedResult

重要：完整显示内容

关键：必须根据用户的需求，向用户显示提取出的完整内容。

• 输出 JSON 包含结构化的所有文档内容
• 在保存模式下，可以在保存的 JSON 文件中查看原始提供方结果
• 显示用户请求的完整内容，不要截断或概述
• 如果用户要求“所有文本”，请显示完整的 text 字段
• 如果用户要求“表格”，请显示文档中的所有表格
• 如果用户要求“主要内容”，请过滤掉页眉和页脚，但显示所有正文文本

这意味着：

• 要做：根据要求显示完整文本、所有表格和所有公式
• 要做：使用以下字段呈现内容：顶层 text、result[n].markdown 和 result[n].prunedResult
• 不要做：使用“...”截断内容，除非内容过长（超过 10,000 个字符）
• 不要做：用户要求完整内容时，只提供概述或摘录
• 不要做：用户需要完整输出时，说“以下是预览”

正确示例：

User: "Extract all the text from this document"
Agent: I've parsed the complete document. Here's all the extracted text:

[Display entire text field or concatenated regions in reading order]

Document Statistics:
- Total regions: 25
- Text blocks: 15
- Tables: 3
- Formulas: 2
Quality: Excellent (confidence: 0.92)

错误示例：

User: "Extract all the text"
Agent: "I found a document with multiple sections. Here's the beginning:
'Introduction...' (content truncated for brevity)"

了解 JSON 响应

输出 JSON 使用一个封装结构包装原始 API 结果：

{
  "ok": true,
  "text": "Full markdown/HTML text extracted from all pages",
  "result": { ... },  // raw provider response
  "error": null
}

关键字段：

• text — 所有页面提取出的 Markdown 文本（可用于快速显示文本）
• result — 原始提供方响应对象
• result[n].prunedResult — 每页的结构化解析输出（布局／内容／置信度及相关元数据）
• result[n].markdown — 以 Markdown／HTML 格式完整呈现的页面输出

原始结果位置（默认）：脚本在 stderr 上打印的临时文件路径

使用示例

示例 1：提取完整文档文本

python scripts/vl_caller.py \
  --file-url "https://example.com/paper.pdf" \
  --pretty

然后使用：

• 顶层 text 快速输出全文
• 需要按页面输出时使用 result[n].markdown

示例 2：提取结构化页面数据

python scripts/vl_caller.py \
  --file-path "./financial_report.pdf" \
  --pretty

然后使用：

• 使用 result[n].prunedResult 获取结构化解析数据（布局／内容／置信度）
• 使用 result[n].markdown 获取呈现后的页面内容

示例 3：打印 JSON 但不保存

python scripts/vl_caller.py \
  --file-url "URL" \
  --stdout \
  --pretty

然后返回：

• 用户要求完整文档内容时，返回完整的 text
• 用户需要完整的结构化页面数据时，返回 result[n].prunedResult 和 result[n].markdown

首次配置

未配置 API 时：

错误会显示：

PADDLEOCR_DOC_PARSING_API_URL not configured. Get your API at: https://paddleocr.com

配置流程：

1. 向用户显示完整的错误消息（包括 URL）。

2. 引导用户安全地进行配置：

   • 建议通过宿主应用的标准方式进行配置（例如设置文件、环境变量界面），而不是在聊天中粘贴凭据。
   • 列出所需的环境变量：

     - PADDLEOCR_DOC_PARSING_API_URL
     - PADDLEOCR_ACCESS_TOKEN
     - 可选：PADDLEOCR_DOC_PARSING_TIMEOUT
     

3. 如果用户仍在聊天中提供凭据（接受任何合理格式）：

   • PADDLEOCR_DOC_PARSING_API_URL=https://xxx.paddleocr.com/layout-parsing, PADDLEOCR_ACCESS_TOKEN=abc123...
   • 这是我的 API：https://xxx，令牌是：abc123
   • 复制粘贴的代码格式
   • 任何其他合理格式
   • 安全提示：提醒用户，在聊天中分享的凭据可能会存储在对话历史中。建议尽可能通过宿主应用的配置来设置凭据。

4. 解析并验证值：

   • 提取 PADDLEOCR_DOC_PARSING_API_URL（查找包含 paddleocr.com 或类似内容的 URL）
   • 确认 PADDLEOCR_DOC_PARSING_API_URL 是以 /layout-parsing 结尾的完整端点
   • 提取 PADDLEOCR_ACCESS_TOKEN（较长的字母数字字符串，通常为 40 个或更多字符）
   • 明确告知用户需要设置哪些环境变量

5. 请用户确认环境已配置：

   • 等待用户确认已在宿主应用、运行时环境或相应的配置文件中设置这些值
   • 出于安全原因，如果该技能安装在宿主应用目录下（例如 ~/.claude/skills），默认不要运行 configure.py 或创建本地 .env 文件

6. 仅在确认后重试：

   • 用户确认环境变量已可用后，重试原始解析任务

重要：错误消息的格式是严格固定的，必须与脚本提供的内容完全一致。不要修改或改写。

处理大型文件

API 没有文件大小限制。对于 PDF，每次请求最多可处理 100 页。

大型文件处理提示：

对大型本地文件使用 URL（推荐）

对于非常大的本地文件，优先使用 --file-url，而不是 --file-path，以避免 Base64 编码开销：

python scripts/vl_caller.py --file-url "https://your-server.com/large_file.pdf"

处理指定页面（仅限 PDF）

如果只需要大型 PDF 中的特定页面，请先提取这些页面：

# Extract pages 1-5
python scripts/split_pdf.py large.pdf pages_1_5.pdf --pages "1-5"

# Mixed ranges are supported
python scripts/split_pdf.py large.pdf selected_pages.pdf --pages "1-5,8,10-12"

# Then process the smaller file
python scripts/vl_caller.py --file-path "pages_1_5.pdf"

错误处理

身份验证失败（403）：

error: Authentication failed

→ 令牌无效，请使用正确的凭据重新配置

API 配额超限（429）：

error: API quota exceeded

→ 每日 API 配额已用尽，请告知用户等待或升级

不支持的格式：

error: Unsupported file format

→ 不支持此文件格式，请转换为 PDF/PNG/JPG

重要说明

• 脚本绝不会筛选内容——始终返回完整数据
• 由 AI Agent 决定要呈现的内容——根据用户的具体请求决定
• 始终提供所有数据——可根据不同需求重新解读
• 不会丢失任何信息——完整保留文档结构

参考文档

• references/output_schema.md - 输出格式规范

注意：模型版本和能力由你的 API 端点（PADDLEOCR_DOC_PARSING_API_URL）决定。

在以下情况下将这些参考文档载入上下文：

• 调试复杂的解析问题
• 需要了解输出格式
• 处理提供方 API 详情

测试技能

验证技能是否正常运行：

python scripts/smoke_test.py

此操作会测试配置，并可选择测试 API 连通性。