PDFCompress

PDFCompress 是一个面向人类和 AI 代理的开源、保持结构的 PDF 压缩工具。它使用经过独立验证的 WPS 风格图像预设，但不调用或分发 WPS DLL，也不依赖 WPS 账户。

其核心规则很简单：

将文本和矢量保持为文本和矢量；仅对过大的绘制图像进行降采样；在发布结果之前进行验证。

功能特性

• 根据实际的 PDF 变换矩阵计算图像分辨率，包括嵌套在 Form XObjects 中的图像。

• 应用与 WPS 兼容的 high、standard、medium 和 low 设置。

• 为评奖、招投标和归档附件添加 archive-safe 配置文件。

• 保留源文件，并以原子方式写入不同的输出路径。

• 默认保留书签、附件、注释、字体和可见的 PDF 结构。

• 除非明确接受签名失效，否则拒绝处理已签名的 PDF。

• 在每次候选输出后验证页数、页面框和可提取文本。

• 支持目标大小，而无需反复重新压缩之前的 JPEG 结果。

• 提供 Python API、CLI、共享 Agent Skill、Codex 插件、Claude Code 插件和 MCP 服务器。

Related MCP server: MokuPDF

安装

需要 Python 3.11 或更高版本。

git clone https://github.com/ncepuee/PDFCompress.git
cd PDFCompress
python -m pip install -e ".[mcp]"

使用 uv：

uv tool install --editable ".[mcp]"

安装标记的 GitHub 发布版本而无需克隆：

uv tool install "pdfcompress-agent[mcp] @ git+https://github.com/ncepuee/PDFCompress.git@v0.1.0"

快速开始

压缩前先进行分析：

pdfcompress analyze "input.pdf" --json

使用与 WPS 兼容的高质量配置文件进行压缩：

pdfcompress compress "input.pdf" "output.pdf" --preset high --json

对于必须小于 4 MB 的正式附件：

pdfcompress compress "input.pdf" "output.pdf" `
  --preset archive-safe `
  --target-size-mb 4 `
  --json

验证现有的一对文件：

pdfcompress verify "input.pdf" "output.pdf" --json

预设

四个与 WPS 兼容的值是从已安装的压缩插件的 generateCompressArgs 分支中恢复的，并在配套的分析说明中进行了独立记录。确切的 WPS 重采样内核、色度子采样策略和完整的优化器位掩码未被复制或声称。

目标大小行为

当提供 --target-size-mb 时，PDFCompress 会从请求的预设开始，逐步尝试更强的配置文件。每次尝试都会重新打开原始 PDF：

archive-safe → high → standard → medium → low

选择第一个在限制范围内的已验证候选。如果没有配置文件能达到限制，则返回最小的已验证候选并附带警告。PDFCompress 不会为了强制达到目标而静默地栅格化页面、删除字体或移除附件。

代理集成

Claude Code

首先安装 Python 包，然后为会话加载插件：

cd PDFCompress
claude --plugin-dir .

以 /pdfcompress:pdf-compress 调用该技能，或让 Claude 压缩 PDF。Claude Code 还会加载插件的 .mcp.json，并通过 stdio 启动 pdfcompress-mcp。

Codex

该仓库包含一个经过验证的 .codex-plugin/plugin.json、一个共享的 skills/ 目录和 .mcp.json。可以从本地 Codex 市场安装，或者将技能复制到个人/项目技能目录。必须安装核心包，以便 pdfcompress-mcp 位于 PATH 中。

通用 MCP 客户端

使用此 stdio 配置：

{
  "mcpServers": {
    "pdfcompress": {
      "type": "stdio",
      "command": "pdfcompress-mcp",
      "args": []
    }
  }
}

MCP 工具：

• analyze_pdf(path, password?)

• compress_pdf(input_path, output_path, preset?, target_size_mb?, overwrite?, allow_signature_loss?)

• verify_pdf(input_path, output_path)

开源研究与采纳的思想

有关许可边界，请参阅 THIRD_PARTY_NOTICES.md。

安全性与限制

• 重写 PDF 会使数字签名失效。默认行为是停止。

• 加密的 PDF 需要密码；输出时保留加密。

• 版本 0.1 跳过图像蒙版、透明度、自定义解码数组、不常见的色彩空间和非 8 位图像，而不是冒视觉损坏的风险。

• 文本相等性检查使用可提取文本。没有 OCR 的扫描页面仍需要视觉 QA。

• 在对具有法律意义或高度复杂的文档使用该工具之前，建议进行像素级渲染比较。

• 如果候选文件不比源文件小，PDFCompress 会输出源文件的逐字节副本，并报告未找到安全的尺寸缩减。

验证示例

在开发过程中使用的一份 12 页、图像密集的 PDF 上：

在 100 DPI 渲染比较下，所有页面尺寸均匹配；archive-safe 结果的每页平均 RGB RMS 差为 0.388，在 0–255 通道尺度上的最大值为 3.002。这是一个验证案例，而非普遍的质量保证。

开发

python -m pip install -e ".[mcp,dev]"
pytest
ruff check .

测试会生成自己的 PDF，其中包含可搜索文本和高分辨率图像。仓库中不包含任何私人文档。

许可证

PDFCompress 根据 MIT 许可证 发布。第三方依赖保留其各自的许可证。

有关版本化变更和可下载的 Python 包，请参阅变更日志和 GitHub 发布。