Home / All Skills / Content & Media Creation / paddleocr-doc-parsing
English (EN)简体中文 (ZH)日本語 (JA)
Content & Media Creation · freestylefly/canghe-skills

paddleocr-doc-parsing

Advanced document parsing with PaddleOCR. Returns complete document structure including text, tables, formulas, charts, and layout information. The AI agent extracts relevant content based on user needs.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Author freestyleflyGitHub freestylefly/canghe-skills ↗License MIT（仓库根 LICENSE）Commit dd0bf35595
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Implemented via 'script orchestration + external API': the model is strictly constrained to execute scripts/vl_caller.py to call the PaddleOCR document parsing API and must not parse documents by itself.

skills/paddleocr-doc-parsing/SKILL.md
**⛔ MANDATORY RESTRICTIONS - DO NOT VIOLATE ⛔**
What this does: Eliminates the fallback of the model 'inspecting images and parsing them itself' using hard constraints in a destructive tone.

Standard workflow is a single command: pass --file-url or --file-path to vl_caller.py, and the script handles encoding, requests, and encapsulation.

skills/paddleocr-doc-parsing/SKILL.md
python scripts/vl_caller.py --file-url "URL provided by user" --pretty
What this does: Serves as the skill's execution entry point, where arguments determine local file or remote URL.

Persists raw JSON to the system temporary directory by default and prints the absolute path to stderr; skips persistence only when --stdout is passed.

skills/paddleocr-doc-parsing/SKILL.md
Default path pattern: `<system-temp>/paddleocr/doc-parsing/results/result_<timestamp>_<id>.json`
What this does: Enforces an artifact persistence strategy to ensure large JSON outputs can be inspected later.

Outputs a stable envelope (ok/text/result/error), where text is the concatenated markdown across pages and result is the raw response.

skills/paddleocr-doc-parsing/SKILL.md
"text": "Full markdown/HTML text extracted from all pages",
What this does: Wraps unstable provider responses into a consistent structure for easy consumption by models or programs.

Credentials are injected via environment variables (API URL / ACCESS_TOKEN / optional TIMEOUT) and read by the script at runtime.

skills/paddleocr-doc-parsing/SKILL.md
primaryEnv: PADDLEOCR_ACCESS_TOKEN
What this does: Declares primary credential environment variables in the frontmatter to guide users through the configuration flow.

Provides explicit error handling (403 authentication failure / 429 quota exhausted / unsupported formats), requiring errors to be displayed as-is before stopping.

skills/paddleocr-doc-parsing/SKILL.md
→ Token is invalid, reconfigure with correct credentials
What this does: Translates API failures into definite actionable instructions rather than leaving the model to guess or backtrack.

Large PDFs are first sliced by page range using split_pdf.py before parsing (single-request limit is 100 pages).

skills/paddleocr-doc-parsing/SKILL.md
python scripts/split_pdf.py large.pdf pages_1_5.pdf --pages "1-5"
What this does: Provides companion tools to handle pagination for large files and avoid exceeding limits.

Output schema has dedicated reference documentation loaded on demand for debugging and format understanding.

skills/paddleocr-doc-parsing/SKILL.md
`references/output_schema.md` - Output format specification
What this does: Applies progressive disclosure, moving details into references rather than cluttering SKILL.md.

2Core Capabilities

01Document structure parsing: text, tables, formulas (LaTeX), charts, headers/footers, seals, layout, and reading order
02Dual input via local files or remote URLs (--file-path / --file-url), with explicit --file-type specification supported
03Automatic persistence of raw JSON to a temporary directory with path reporting; overridable via --output/--stdout
04Pagination handling for large PDFs: split_pdf.py supports mixed page ranges
05First-time configuration guidance: provides API acquisition URLs and lists required variables when env vars are missing
06Self-test script: smoke_test.py validates configuration and optional API connectivity
07File optimization capabilities: Pillow for image compression and pypdfium2 for PDF processing
08Stable output envelope and error codes (ok/text/result/error, INPUT/CONFIG/API_ERROR)

3External Dependencies

KindDependency / Endpoint
clipython（技能声明的 bins 依赖）
networkPaddleOCR Layout Parsing API（用户自备端点，路径以 /layout-parsing 结尾）
packagehttpx（HTTP 客户端）
packagepython-dotenv（读取环境变量）
packagepypdfium2（PDF 拆页/处理）
packagePillow（图像处理）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
  • scripts/: Execute local script or command: scripts/vl_caller.py (main parsing entry point, calls API via httpx)
  • 网络端点: Declare external network access: PaddleOCR Layout Parsing API (user endpoint specified by PADDLEOCR_DOC_PARSING_API_URL, called via httpx)
  • 本地工作目录: File read/write and artifact output: <system-temp>/paddleocr/doc-parsing/results/result_*.json (default persistence)
Audit Notes: Rated 🟠 orange: The skill reads its own declared env credentials (PADDLEOCR_ACCESS_TOKEN, etc.) for its intended purpose and sends user documents (local files or URLs) to an external PaddleOCR service for parsing. This triggers two orange criteria: 'reading credentials/env' and 'sending user material to an external backend'. It also performs local file writes (temporary JSON, optional .env). It does not involve reverse engineering, protection bypass, or arbitrary code execution, so it does not reach red. Risk notice: orange, strictly managed—document contents leave the local machine; do not paste tokens into chat during initial setup.

5Second-Pass Verification

  • [ok] 文件面核对 — §1 列出 11 个文件：SKILL.md、_meta.json、references/output_schema.md、7 个 scripts、2 个 requirements；与 internal_assets 一致。
  • [ok] 网络调用真伪 — §3 network 命中 lib.py 的 urllib.parse；结合 SKILL.md 的 API 流程与 requirements.txt 的 httpx，确认真实外发到用户端点。
  • [ok] 凭证读取复核 — frontmatter requires.env 明列三个变量，配置流程与错误处理段反复引用，确认真实读取。
  • [ok] 写盘复核 — §3 写盘命中 configure.py 的 open(env_file,"w")；SKILL.md 另述默认 temp 落盘与 --output，结论成立。
  • [ok] 行为限制是否落空 — ⛔ 强制约束为提示层，不构成技术隔离；宿主若允许仍可绕过，故 injection_surface 按提示层描述。
  • [ok] 档位判定复核 — 读 env 凭据 + 外发用户素材 → 🟠 orange 成立，未达 red。

6Verdict & Scenarios

  • Comprehensive parsing capabilities for complex document structures (tables, formulas, charts, layout, reading order).
  • Stable output contract (envelope + error codes) facilitating programmatic consumption and downstream extraction.
  • Complete set of companion scripts: page splitting, optimization, configuration, and self-testing out of the box.
  • Thorough security reminders: warns against pasting credentials into chat and avoids writing to .env by default.
    • Best for: Users who need structured extraction of text, tables, formulas, and charts from complex documents (invoices, financial reports, academic papers, multi-column publications); scenarios where PaddleOCR endpoints and tokens are available and sending documents to the service is permitted.
    Not for: Scenarios with strict requirements against data leaving the local machine (confidential/compliance-restricted); tasks requiring only simple text OCR or screenshot recognition (SKILL.md explicitly discourages this); environments without API credentials and unwilling to configure external services.
    Install Agent-Ready
    ① Verified Mirror 2026-10-10
    Option A · Direct DownloadDownload paddleocr-doc-parsing.tar.gz
    sha256: 677ae1c7c7845ee9…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit dd0bf35595.