pdf处理大师

概述

墨序 PDF 工具箱

使用用户自己的墨序 API Key 按实际处理页数扣除点数，PDF 始终在用户本机处理。远程服务只接收服务类型、页数、费用和结果 SHA-256 摘要，不接收 PDF、提取文字或输出文件。

API Key 点数结算

1. 先确认合并、拆分或文字提取的输入、页码范围和输出位置。不得把文件路径或文档内容发送给计费服务。
2. 先用 scripts/pdf_meter.py 计算本次页数，再运行 python3 scripts/billing_client.py quote --units 页数。展示后台返回的单价、预留点数和账户可用点数。
3. 只有用户明确确认本次费用后，才生成一次性 UUID 幂等键，运行：

   python3 scripts/billing_client.py reserve --quote 报价ID 
     --idempotency-key 本次UUID --confirm

1. 预留成功后执行本地 PDF 处理和交付检查。成功后用同一任务结算：

   python3 scripts/billing_client.py finalize --task 任务ID 
     --result 最终PDF、TXT或拆分目录 --units 实际页数 --confirm

只有返回 verified=true 才交付。本地处理失败或用户取消时，运行 python3 scripts/billing_client.py cancel --task 任务ID --confirm 释放预留点数。

未配置 WRITER_API_KEY 时，运行 python3 scripts/billing_client.py info 查看创建密钥和充值入口。既有 MOXU_API_KEY 也兼容。不得把 API Key 写入 Skill、命令参数、结果文件或日志。网络状态不明时查询原任务，不创建新任务。

计费页数口径：合并按所有输入页数合计；拆分按选中页数合计，未指定范围时为原文档全部页数；文字提取按输入文档全部页数。报价与结算页数必须一致。

PDF 处理

所有命令都使用 scripts/pdf_tool.py。输出路径不存在时才创建；除非用户明确要求，不覆盖现有文件。

合并

按用户指定的顺序合并，不自行按文件名重排。

python3 scripts/pdf_tool.py merge --output 输出.pdf 文件1.pdf 文件2.pdf

拆分

不写 --ranges 时每页生成一个 PDF。写入 1-3,4-6,8 时生成三个分组文件。页码从 1 开始。

python3 scripts/pdf_tool.py split --input 输入.pdf --output-dir 拆分结果 --ranges "1-3,4-6,8"

提取文字

--ocr auto 先读取 PDF 文本层，只对没有有效文字的页面使用 OCR。always 强制全文 OCR，never 只读取文本层。

python3 scripts/pdf_tool.py extract --input 输入.pdf --output 提取结果.txt --ocr auto --lang chi_sim+eng

OCR 使用本机的 pdftoppm 和 tesseract。引擎不可用时，明确列出缺少的程序及安装方式，不把空文本当作成功结果。macOS 可使用 brew install poppler tesseract tesseract-lang，Ubuntu/Debian 可使用 sudo apt-get install poppler-utils tesseract-ocr tesseract-ocr-chi-sim。安装系统程序前必须先征得用户同意。

交付检查

• 处理前记录输入 PDF 数量和总页数；处理后重新打开输出 PDF，确认页数与预期一致。
• 合并和拆分不修改原文件。遇到加密 PDF 时停止，请用户提供已解密副本；不尝试破解密码。
• OCR 结果按页标注，并告知用户 OCR 可能需要人工校对。
• 只交付最终 PDF 或 TXT 文件和简短的处理摘要。