用途：当需要一次性从大量文件中提取内容，并希望所有文件共享同一套提取配置时使用 batch。它支持目录与 glob、并发执行、按文件覆盖配置以及逐文件容错。
主要能力：xberg batch 在一次运行中对多个文档执行提取，返回包含 results、total_ms、per_file_ms 以及（出现失败时）errors 的 JSON 信封。results 中每项是一份完整提取文档；一个输入可能产生多份文档，因此不要按位置把 results 与输入一一对应，per_file_ms 与输入对齐，失败情况需查看 errors。batch 默认 --format json，而单个 extract 默认 --format text。
基本用法：xberg batch .pdf；混合格式并输出 markdown 供 LLM 使用：xberg batch docs/.docx --content-format markdown；递归场景先用 shell 展开：xberg batch $(find ./corpus -name '.pdf')。可配合 jq 检查结果，例如 xberg batch reports/.pdf | jq '.results[] | {chars: (.content | length), mime: .mime_type}'。
并发控制：--max-concurrent 限制同时提取的文件数；省略时由调度器根据总线程预算推导。内存受限或启用 OCR/ML 模型时可调低，因为每个进行中的提取都占用自己的缓冲区。版面密集型批次会进一步受限（全 PDF 版面批次并发为 1，混合版面为 2）。--max-threads 可额外限制内部线程总量，例如 xberg batch *.pdf --max-concurrent 2 --max-threads 4。
按文件覆盖：--file-configs 指向一个 JSON 文件，把每个路径映射到该文件专属的覆盖对象，合并到共享配置之上。键为命令行传入的文件路径，值为 snake_case 的逐文件提取配置对象。
输出布局：使用 text/toon 输出并提取图片时，--output-dir 指定引用图片文件（如 image_0.png）的写出目录，该目录必须已存在；JSON 输出会内联图片字节并忽略 --output-dir。
错误恢复：批量提取按文件容错，一个不可读或损坏的文档不会停止其余任务。应检查 results 中的部分内容与 errors，而不是只依赖进程退出码。大批量中含少量大文件时，可配合 --max-concurrent 避免内存耗尽。
共享配置：extract 的每个标志也适用于 batch（OCR、分块、版面、内容格式等），并对所有文件共享，除非被 --file-configs 覆盖。也支持配置文件，并从当前工作目录向上自动发现，例如 output_format = "markdown" 配 [ocr] backend = "tesseract"、language = "eng"，再执行 xberg batch corpus/*.pdf --config xberg.toml。
程序化调用：Python 中 extract_batch 接收 ExtractInput 列表并返回一个信封，results 数组为每个输入保存一份文档；逐输入覆盖放在 ExtractInput.config（FileExtractionConfig）。Node.js 对应 extractBatch，Rust 使用 extract_batch(inputs, &config)。注册 xberg MCP 服务器后，优先使用 extract_batch 工具而非调用 shell。
常见陷阱：batch 与 extract 默认格式不同，依赖输出形状的脚本需显式设置 --format；--output-dir 不会自动创建；启用 OCR/版面的大批量可能需要显式 --max-concurrent 上限；--file-configs 的路径键必须与命令行传入的路径一致，而非解析后的绝对路径。其余细节暂未提供。