PaddleOCR文档解析技能

何时使用此技能

触发关键词（路由）：YAML文件中列出了双语触发词（中文和英文）描述如上所述——使用该字段进行发现和路由。

文档解析适用于：

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

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

• 简单的纯文本提取
• 速度至关重要的快速OCR任务
• 带有清晰文本的截图或简单图像

安装

在使用此技能前请先安装Python依赖包。从技能目录（skills/paddleocr-doc-parsing）：

pip install -r requirements.txt

可选— 用于文档优化和split_pdf.py（页面提取）：

pip install -r requirements-optimize.txt

如何使用此技能

⛔ 强制性限制 - 请勿违反 ⛔

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被省略，脚本会自动保存在系统临时目录下
   • 默认路径模式：<系统临时目录>/paddleocr/doc-parsing/results/result_<时间戳>_<ID>.json
   • 如果--output被指定，它将覆盖默认的临时文件目标位置
   • 如果--stdout被指定，JSON 将打印到标准输出，且不保存文件
   • 在保存模式下，脚本会在标准错误上打印已保存的绝对路径：结果已保存至：/绝对路径/...
   • 在默认/自定义保存模式下，响应前需读取并解析已保存的 JSON 文件
   • 在保存模式下，始终告知用户已保存的文件路径，并说明完整的原始 JSON 数据可在该处获取
   • 仅当您明确希望跳过文件持久化时，才使用--stdout 输出的 JSON 包含

2. 完整的文档内容：页眉、页脚、页码

   • 主文本内容
   • 带结构的表格
   • 公式（含 LaTeX 格式）
   • 图表
   • 脚注和参考文献
   • Footnotes and references
   • 印章
   • 布局与阅读顺序

   输入类型说明：

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

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

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

重要：完整内容显示

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

• 输出JSON以结构化格式包含了文档的全部内容
• 在保存模式下，原始的提供商结果可以在保存的JSON文件中查看
• 显示用户所请求的全部内容，请勿截断或总结
• 如果用户要求“所有文本”，请展示全部内容文本领域
• 如果用户询问“表格”，则显示文档中的所有表格
• 如果用户询问“主要内容”，则过滤掉页眉/页脚但显示所有正文文本

这意味着：

• 要做的：按要求显示完整文本、所有表格、所有公式
• 要做的：使用以下字段呈现内容：顶层文本、结果[n].markdown和结果[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格式呈现的完整页面输出

原始结果位置（默认）：脚本在标准错误输出上打印的临时文件路径

使用示例

示例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

那么返回：

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

首次配置

当 API 未配置时：

错误将显示：

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

配置工作流程：

1. 向用户显示确切的错误信息（包括URL）。指导用户进行安全配置：

2. 指示用户访问PaddleOCR网站，点击API，选择所需模型，然后复制API_URL和Token。它们分别对应用于身份验证的API URL（PADDLEOCR_DOC_PARSING_API_URL）和访问令牌（PADDLEOCR_ACCESS_TOKEN）。支持的模型：PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5。可选地，请用户通过

   • Instruct the user to visit thePaddleOCR website, clickAPI, select the model you need, then copy theAPI_URLandToken. They correspond to the API URL (PADDLEOCR_DOC_PARSING_API_URL) and access token (PADDLEOCR_ACCESS_TOKEN) used for authentication. Supported models:PP-StructureV3,PaddleOCR-VL,PaddleOCR-VL-1.5.
   • Optionally, ask the user to configure the request timeout viaPADDLEOCR_DOC_PARSING_TIMEOUT.
   • 建议通过宿主应用程序的标准方法（例如，配置文件、环境变量用户界面）进行配置，而非在聊天中粘贴凭据。例如，在 OpenClaw 中，环境变量可以在~/.openclaw/openclaw.json中进行设置。

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

   • PADDLEOCR_DOC_PARSING_API_URL=https://xxx.paddleocr.com/layout-parsing, PADDLEOCR_ACCESS_TOKEN=abc123...
   • 这是我的 API：https://xxx 和令牌：abc123
   • 粘贴的代码格式

   警告用户，在聊天中共享的凭据可能会存储在对话历史中。建议尽可能通过宿主应用程序的配置来设置。

   然后解析并验证这些值：

   • 提取PADDLEOCR_DOC_PARSING_API_URL（查找包含paddleocr.com或类似内容的 URL）
   • 确认PADDLEOCR_DOC_PARSING_API_URL是一个完整的端点，以/layout-parsing
   • 结尾提取PADDLEOCR_ACCESS_TOKEN

4. （长字母数字字符串，通常为40个字符以上）请用户确认环境已配置完成

5. 。仅在确认后重试

   • ：

一旦用户确认环境变量可用，重试原始解析任务

处理大文件

API 没有文件大小限制。对于 PDF 文件，每个请求最多处理 100 页。处理大文件的提示

：

对大型本地文件使用 URL（推荐）对于非常大的本地文件，建议使用--file-url而非--file-path

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智能体决定呈现内容- 基于用户具体需求
• 所有数据始终可用- 可根据不同需求重新解析
• 信息永不丢失- 完整文档结构得以保留

参考文档

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

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

在以下情况下，请将这些参考文档加载到上下文中：

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

测试技能

要验证技能是否正常工作：

python scripts/smoke_test.py

此测试可验证配置，并可选择性地测试API连通性。