1仕組みと動作原理

実装方式は「スクリプトオーケストレーション + 外部API」：モデルはscripts/vl_caller.pyを実行してPaddleOCRドキュメント解析APIを呼び出すことのみに厳密に制限され、自身でドキュメントを解析することは禁じられています。

skills/paddleocr-doc-parsing/SKILL.md

**⛔ MANDATORY RESTRICTIONS - DO NOT VIOLATE ⛔**

ここでの目的：破壊的なトーンを持つ強制制約によって、モデルが「自力で画像を見て解析する」逃げ道を塞ぎます。

標準ワークフローは単一コマンド：vl_caller.pyに--file-urlまたは--file-pathを渡し、スクリプトがエンコード／リクエスト／カプセル化を担当します。

skills/paddleocr-doc-parsing/SKILL.md

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

ここでの目的：これがスキルの実行エントリポイントであり、引数によってローカルファイルかリモートURLかを決定します。

デフォルトで生のJSONをシステムの一時ディレクトリに永続化し、stderrに絶対パスを出力します。--stdoutが指定された場合のみ永続化をスキップします。

skills/paddleocr-doc-parsing/SKILL.md

Default path pattern: `<system-temp>/paddleocr/doc-parsing/results/result_<timestamp>_<id>.json`

ここでの目的：生成物の保存ポリシーを規定し、巨大なJSONでも後から確認できるようにします。

出力は安定したenvelope（ok/text/result/error）であり、textは各ページのMarkdown連結、resultは生のレスポンスです。

skills/paddleocr-doc-parsing/SKILL.md

"text": "Full markdown/HTML text extracted from all pages",

ここでの目的：不安定なプロバイダーのレスポンスを固定構造でラップし、モデルやプログラムが利用しやすくします。

認証情報は環境変数（API URL / ACCESS_TOKEN / 任意のTIMEOUT）経由で注入され、実行時にスクリプトによって読み取られます。

skills/paddleocr-doc-parsing/SKILL.md

primaryEnv: PADDLEOCR_ACCESS_TOKEN

ここでの目的：frontmatterで主要な認証情報の環境変数を宣言し、設定フローでユーザーを適切に誘導します。

明確なエラーハンドリング（403 認証失敗 / 429 クォータ枯渇 / 未対応フォーマット）を提供し、エラーをそのまま表示して停止するよう要求します。

skills/paddleocr-doc-parsing/SKILL.md

→ Token is invalid, reconfigure with correct credentials

ここでの目的：APIの失敗を曖昧にせず、モデルが推測でフォールバックするのではなく確定した行動指示に変換します。

大容量PDFは解析前にsplit_pdf.pyを使ってページ範囲ごとに分割します（1リクエストの上限は100ページ）。

skills/paddleocr-doc-parsing/SKILL.md

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

ここでの目的：付属ツールで大容量ファイルのページ分割を処理し、上限超過を防ぎます。

出力スキーマには独立したリファレンスドキュメントがあり、デバッグやフォーマット理解の際にオンデマンドで読み込みます。

skills/paddleocr-doc-parsing/SKILL.md

`references/output_schema.md` - Output format specification

ここでの目的：段階的開示を採用し、詳細をSKILL.mdに詰め込まずreferencesに逃がします。

2コア機能

01ドキュメント構造解析：テキスト、表、数式（LaTeX）、グラフ、ヘッダー/フッター、印章、レイアウト、読み取り順序

02ローカルファイルとリモートURLのデュアル入力（--file-path / --file-url）、--file-typeの明示的指定が可能

03生のJSONを一時ディレクトリへ自動保存しパスを返却（--output/--stdoutで上書き可能）

04大容量PDFのページ分割処理：split_pdf.pyによる複合ページ範囲のサポート

05初回設定ガイダンス：環境変数不足時にAPI取得URLを提示し、必要な変数を一覧化

06セルフテストスクリプト：smoke_test.pyによる設定および任意のAPI疎通確認

07ファイル最適化機能：Pillowによる画像圧縮とpypdfium2によるPDF処理

08安定した出力envelopeとエラーコード（ok/text/result/error、INPUT/CONFIG/API_ERROR）

3外部依存関係

Kind	Dependency / Endpoint
cli	python（技能声明的 bins 依赖）
network	PaddleOCR Layout Parsing API（用户自备端点，路径以 /layout-parsing 结尾）
package	httpx（HTTP 客户端）
package	python-dotenv（读取环境变量）
package	pypdfium2（PDF 拆页/处理）
package	Pillow（图像处理）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトまたはコマンドの実行: scripts/vl_caller.py（解析のメインエントリポイント、httpxでAPIを呼び出し）
网络端点: 外部ネットワークアクセスの宣言: PaddleOCR Layout Parsing API（PADDLEOCR_DOC_PARSING_API_URLが指すユーザーエンドポイント、httpxで呼び出し）
本地工作目录: ファイルの読み書きと成果物の出力: <system-temp>/paddleocr/doc-parsing/results/result_*.json（デフォルトで保存）

監査ノート： 判定 🟠 orange：スキルが自己申告した用途のために自身の環境変数から認証情報（PADDLEOCR_ACCESS_TOKENなど）を読み取り、ユーザーのドキュメント（ローカルファイルまたはURL）を外部のPaddleOCRサービスに送信して解析するため、「認証情報/envの読み取り」および「ユーザー素材の外部サービスバックエンドへの送信」の2つのorangeトリガーに該当します。またローカル書き込み（一時JSON、任意の.env）も含みます。リバースエンジニアリング、防御回避、任意コード実行は含まれないためredには達しません。リスク注意事項：orange、厳格管理対象——ドキュメント内容がローカル外に送信されます。初回設定時にチャット上へトークンを貼り付けないでください。

5二重目の独立検証

[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。

6結論

複雑なドキュメント構造の解析機能が充実（表/数式/グラフ/レイアウト/読み取り順序）。

出力規約が安定しており（envelope + エラーコード）、プログラムによる利用や二次抽出が容易。

付属スクリプトが充実：ページ分割、最適化、設定、セルフテストがすべて網羅。

安全に関する注意喚起が万全：チャットへの認証情報貼り付け警告、デフォルトで.envへ書き込まない仕様。

最適な用途： 複雑なドキュメント（請求書/財務諸表/学術論文/段組み刊行物）からテキスト、表、数式、グラフを構造化して抽出する必要があるユーザー。すでにPaddleOCRのエンドポイントとトークンを保持しており、該当サービスへドキュメントを送信して解析させる運用が可能なシナリオ。

不向きな用途： データがローカル環境外に出ることを禁止する厳格な要件（機密情報/コンプライアンス等）があるシナリオ。単純なテキストOCRやスクリーンショット認識のみで済むタスク（SKILL.mdで明確に非推奨と明記）。API認証情報がなく、外部サービスの設定を行う予定がない環境。

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

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit dd0bf35595.