Baidu OCR Codex Skill

一个用于 Codex 的文档 OCR skill。它通过百度 PaddleOCR AI Studio OCR Jobs API，将 PDF、图片或 Office 文档转换为按页拆分的 Markdown、结构化 JSON 和相关图片资源。

推荐的 Codex 全局提示词

将下面这段规则加入你的 Codex 全局提示词（例如全局 AGENTS.md）：

凡是需要读取、解析、总结或检索 PDF，优先调用 $baiduocr 将 PDF 转换为 Markdown，并把输出目录作为该 PDF 的可复用解析缓存。后续再次处理同一 PDF 时，如果对应 Markdown 已存在且与源 PDF 一致，优先读取已有 Markdown，不要重复 OCR；只有 Markdown 缺失、源 PDF 已更新、现有结果不完整，或用户明确要求重新解析时，才重新调用 $baiduocr。

这样设置后，第一次处理 PDF 时会先生成 Markdown；后续调用可以直接使用已有 Markdown，减少重复 OCR、等待时间和 API 消耗。

安装

git clone https://github.com/Leehow/baiduocr-skill.git \
  ~/.codex/skills/baiduocr
python -m pip install requests

如果目标目录已经存在，请先自行确认其中是否有需要保留的改动，不要直接覆盖。

配置 API Token

脚本只从环境变量读取 token：

export BAIDUOCR_TOKEN='your-token'

不要把真实 token 写入代码、提交到 GitHub，或放入 OCR 输出目录。

使用

在 Codex 中可以直接说：

使用 $baiduocr 把 /absolute/path/to/document.pdf 转成 Markdown。

也可以直接运行脚本：

python ~/.codex/skills/baiduocr/scripts/baiduocr.py \
  /absolute/path/to/document.pdf \
  --output-dir /absolute/path/to/ocr-output

输入也可以是 HTTP(S) URL：

python ~/.codex/skills/baiduocr/scripts/baiduocr.py \
  'https://example.com/document.pdf' \
  --output-dir /absolute/path/to/ocr-output

输出

• doc_0.md, doc_1.md, ...：逐页 Markdown。
• doc_0.json, doc_1.json, ...：移除临时签名图片 URL 后的稳定结构化页面数据。
• result.jsonl：API 原始结果，仅用于调试和溯源。
• Markdown 引用的图片及 API 返回的其他页面图片。

再次处理同一 PDF 时，应优先复用这些 Markdown。只有源文件变化、输出缺失或不完整， 或明确要求重新 OCR 时，才重新提交任务。

可选参数

• --doc-orientation：启用文档方向分类。
• --doc-unwarping：启用文档矫正。
• --chart-recognition：启用图表识别。
• --model：覆盖默认模型 PaddleOCR-VL-1.6。
• --poll-interval：修改默认的 5 秒轮询间隔。

测试

离线回归测试不会发起网络请求或调用 API：

cd ~/.codex/skills/baiduocr/scripts
python -m unittest -v test_baiduocr.py

Repository layout

baiduocr/
├── SKILL.md
├── README.md
├── agents/
│   └── openai.yaml
└── scripts/
    ├── baiduocr.py
    └── test_baiduocr.py