exam2md

将带批注或手写痕迹的考试 PDF 转换为 Markdown 题目文档。

exam2md 会将 PDF 页面渲染为图片，抑制红色和蓝色手写痕迹，将印刷文本、公式和插图分轨提取，再为每份 PDF 生成结构化 Markdown 文档包。

复查流程采用目标驱动设计：每一页都会根据明确的目标状态进行评估，并记录为 pass、needs_fix 或 uncertain。通过的内容进入最终 Markdown，未通过的内容进入草稿和 QA 报告，避免可信结果和待修正内容混在一起。

安装

npm install -g exam2md

本地开发：

npm install
npm link

依赖

brew install poppler

安装一个受支持的复查 CLI，并确保它在 PATH 中可用。

检查环境：

exam2md doctor

使用

exam2md ./pdfs
exam2md ./paper.pdf -o markdown_output
exam2md ./paper.pdf --reviewer auto --review-rounds 3
exam2md ./paper.pdf --effort high
exam2md ./paper.pdf --timeout 60
exam2md ./paper.pdf --no-context-pages
exam2md review markdown_output/paper/.exam2md/manifest.json --audit-passed
exam2md ./paper.pdf --accept-last-fix
exam2md review markdown_output/paper/.exam2md/manifest.json

带批注考试扫描件推荐使用：

exam2md ./pdfs -o markdown_output --reviewer auto --effort medium --review-rounds 2 --timeout 180 --dpi 240 --accept-last-fix

输出

每个 Markdown 文件都有一个同级 assets 目录：

markdown_output/
└── paper/
    ├── paper.md
    ├── paper.assets/
    │   ├── q01_fig01.png
    │   └── q02_fig01.png
    └── .exam2md/
        ├── manifest.json
        ├── paper_draft.md
        ├── paper_qa.md
        └── paper_evolution.json

Markdown 图片路径全部使用相对路径：

![问题 1 图 1](paper.assets/q01_fig01.png)

数学公式使用标准 Markdown/LaTeX 分隔符：

• 行内公式：$...$
• 行间公式：$$...$$

目标驱动复查

每一页都按固定的目标驱动流程处理：

1. 明确目标：将印刷题目转换为 Markdown，并把题图放在对应题目旁边；
2. 对照原图和清理图；
3. 分别提取文本、公式和插图；
4. 按原题顺序重建题目逻辑；
5. 将插图裁剪结果关联到对应题目；
6. 排除手写答案、推导、圈画、勾选和平台界面元素；
7. 检查文字、公式、选项、单位和图片引用；
8. 返回页面状态：pass、needs_fix 或 uncertain。

只有状态为 pass 的页面会进入最终 Markdown。状态为 needs_fix 的页面会进入草稿文件，并在 QA 报告中记录原因。初次提取结果为 usable 的页面即使包含少量疑点，也会继续进入复查。

局部不确定不会被悄悄藏起来：能定位到原文片段时，正文会用斜体标出；对应题目下方会加入小号引用说明。完全看不清、没有图像依据或无法验证的内容不会被写进可信正文。

每份输出都会在 .exam2md/ 中生成一份 evolution 报告，记录页面状态、失败原因、已采用的恢复机制、题图统计和下一轮推荐参数。每次运行都会追加一条精简的 practiceLog，最多保留最近 20 次，让重复实践有审计轨迹，但不会把项目变成日志堆。

这套迭代循环是保守的：它只沉淀具体失败模式，例如题图截图过小、复查器失败、草稿页或局部不确定。它不会静默改写提示词，不会编造缺失内容，也不会把失败页面藏起来。

报告写入前会自动整理。重复的截图诊断会被归一成短句，例如 used readable question-section fallback，避免多轮重试后 QA 和 evolution 文件充满冗余描述。

如果页面过于模糊、文字被遮挡，或复查调用超过超时时间，exam2md 会保留当前草稿并停止继续重建该页。

图中小标签会通过截图保留。只要题干和选项可识别，页面不会因为图内小字未逐个转写而降级为草稿。exam2md 会用低成本的确定性规则清掉重复题干和相邻题目残片。如果题图截图小到无法阅读，会自动替换为对应题目的可读题块兜底图，避免输出误导性碎片。如果清理答案痕迹会破坏题图完整性，则保留完整题图，并在 QA 中记录。

默认会附带相邻页清理图作为上下文，用于判断续题和题号。可使用 --no-context-pages 关闭。

如果希望在复查器没有报告不确定项时接受最后一轮修正文稿，可使用 --accept-last-fix。不使用该参数时，仍返回 needs_fix 的页面会保留在草稿包中。

如果要强制复审已经通过的页面，使用 exam2md review ... --audit-passed。

默认参数偏保守。正式转换时建议使用上面的推荐命令：更高 DPI 有利于识别小公式，相邻页上下文有利于处理跨页续题，--accept-last-fix 可在复查器已给出无不确定修正文稿时减少人工处理量。

限制

完全被遮挡或无法辨认的印刷文字不能被可靠恢复。此类内容会标记为 uncertain，并在修正前排除在最终 Markdown 之外。