PPX 解析

使用本地 ppx CLI 将 PDF 和图像解析为结构化的 Markdown 与 JSON。

运行时要求

• 使用 Python >= 3.12。
• 建议将 PPX 安装至虚拟环境，而非系统 Python 环境。
• 若缺少 ppx，请先阅读 references/troubleshooting.md，并在安装依赖前创建虚拟环境。
• 保持本技能 frontmatter 中的 version 与仓库根目录下的 pyproject.toml 文件同步，同步方式为运行 scripts/sync_version.py。

工作流程

1. 确认运行时环境使用的是 Python >= 3.12。
2. 使用 scripts/check_ppx_env.sh 检查运行时环境。
3. 若未安装 ppx，请创建或激活一个虚拟环境，并在其中安装 PPX。
4. 选择解析选项：
   • 默认使用 --ocr auto。
   • 对于扫描版 PDF 或截图，请使用 --ocr yes。
   • 对于原生 PDF，若 OCR 引入了干扰噪声，则使用 --ocr no。
   • 默认使用 --table auto。
   • 仅当用户需要最高表格识别精度，且已配置 LLM 后端时，才使用 --table llm。
5. 执行命令：ppx parse -o
   。
6. 检查输出目录，并报告主要产出物：
   • doc.md
   • doc.json
   • pages/
   • 若提取了图示，则还包括 images/
7. 若解析失败，请总结失败步骤，并从 references/ 加载对应说明文档。

常用命令

ppx parse report.pdf -o output/
ppx parse scan.pdf --ocr yes -o output/
ppx parse figure.png -o output/
ppx parse report.pdf --pages "1-5,10" -o output/
ppx parse report.pdf --table llm --backend deepseek -o output/

输出契约

• 优先返回输出目录的绝对路径。
• 明确指出结果来源于 doc.md、doc.json 还是页面级文件（page-level files）。
• 当 OCR 模式、表格模式或后端配置对识别精度产生实质性影响时，需特别说明。

参考文档

• 选择解析参数（flags）时，请参阅 references/cli-options.md。
• 使用 DeepSeek、Paddle 或 GLM 后端时，请参阅 references/backend-config.md。
• 当 PPX 缺失、Python 版本过低或运行时依赖出错时，请参阅 references/troubleshooting.md。