PDF 转 Markdown
将 PDF 的每一页统一转换为图片并进行视觉识别，适用于文本型 PDF、扫描件、幻灯片、表格、公式、图表和复杂版式文档。
使用方式
python scripts/convert.py "path/to/document.pdf"
如需指定输出位置：
python scripts/convert.py "path/to/document.pdf" --out-dir "path/to/output"
API Key 从私有配置或 --api-keys-file 读取。禁止在输出、日志、命令记录或公开文件中暴露 API Key，也不要修改原始 PDF。
输出结果
成功后只保留一个以 PDF 文件名命名的目录：
document/
├── document.md
├── document.json
└── pages/
├── page_0001.jpg
├── page_0002.jpg
└── ...
document.md：完整的 Markdown 转录内容；document.json：页数、模型、处理状态、耗时和文件体积等精简信息，不保存转录正文；pages/：每页一张本地 JPEG 图片。
Markdown 中的页面图片使用相对路径，可在本地直接点击或预览，不依赖在线图床。成功后自动清理临时文件；任务中断或存在失败页时保留断点信息以便续跑。
识别规则
使用 agnes-2.5-flash 进行视觉识别，并关闭 Thinking。保留原文语言、标题、段落、列表、表格、脚注、数学公式和有信息价值的图表说明。不提取 PDF 原始文字，不复制 PDF 内嵌图片，不执行 LaTeX 语法检查，也不因 LaTeX 格式问题重复请求。
页面会渲染为 RGB JPEG，目标为 200 DPI、长边不超过 2800 像素、单张不超过 3 MiB。为调用视觉模型，页面压缩副本会临时上传到第三方图床；图床地址不会写入最终 Markdown 或 JSON。处理敏感文件前，应提醒用户这一点。
处理效率与失败控制
- 所有 API Key 和 worker 共享全局 20 RPM；默认 8 个并发 worker；
- 每页最多 4 次 Agnes 请求，重试次数包含图片降级和网络重试；
- 429、网络错误和临时服务错误采用有限退避；
- 413 或图片过大时，仅降低上传副本尺寸后有限重试；
- API Key 无效、权限错误、模型或请求格式错误时停止无效路径，不重复发送相同请求；
- 支持断点续跑，成功页面不会重复调用 API；
- 存在失败页时明确报告失败，不将生成 Markdown 文件视为全部成功。
JSON 还会记录页面渲染耗时、视觉识别耗时、总耗时，以及页面图片、Markdown 和 JSON 的实际文件体积。
