zjsthmjialin/pdf-background-gray-codex-skill

PDF 去底灰（原分辨率）Codex Skill

Awesome DSH Plugin

remove-pdf-background-gray 是一个用于扫描型 PDF 的 Codex Skill。它可以去除纸张扫描产生的灰底或偏白底色，同时保持页面尺寸、嵌入图像的原始像素尺寸和文字的连续抗锯齿边缘。

这个项目既可以作为 Codex Skill 自动调用，也可以直接运行其中的 Python 脚本。

DeepSeek Harness (DSH) 插件安装

remove-pdf-background-gray 也是 DeepSeek Harness (DSH) 插件，一条命令安装：

dsh plugin --profile web add dsh-pdf-background-gray

重启 DSH Web 后，向 Agent 说“把这份扫描 PDF 去底灰”即自动走技能工作流（要求本机 Python 3.10+ 与 python -m pip install pypdf Pillow numpy）。

- npm: https://www.npmjs.com/package/dsh-pdf-background-gray
- 插件源码：本仓库 dsh-pdf-background-gray/ 目录

核心特点

- 保持原分辨率：直接处理 PDF 内嵌图像，不缩放图像。
- 不整页重绘：不先把 PDF 页面渲染成新图片再重新组装。
- 保护文字边缘：使用连续的高光映射，不使用容易产生锯齿的硬阈值或黑白二值化。
- 无损写回：处理后的图像使用 Flate 无损压缩写回 PDF，避免再次 JPEG 压缩文字边缘。
- 内置验证：输出后检查页数、页面框和嵌入图像像素尺寸是否改变。
- 安全中止：遇到内联图像或透明蒙版时停止处理，避免悄悄破坏复杂页面。

适用范围

适合以下情况：

- 扫描书籍、档案、讲义或合同的纸张底色发灰。
- 希望背景变白，但不希望文字被二值化或出现明显锯齿。
- 需要保持原始 DPI、图像宽高和 PDF 页面尺寸。
- PDF 页面主要由 JPEG、灰度图或 RGB 扫描图组成。

不建议直接用于：

- 以矢量文字、复杂插画或透明图层为主的 PDF。
- 灰色本身就是内容的一部分，例如铅笔画、浅灰表格、医学影像或艺术作品。
- 需要极致压缩体积，而不是优先保证文字边缘质量的场景。
- 带有透明蒙版、内联图像或特殊色彩空间且尚未人工检查的文件。

处理前建议使用 pdfinfo、pdffonts 和 pdfimages -list 检查 PDF 结构，并先对一页代表性内容做测试。

已验证效果

本 Skill 最初用于处理一份真实扫描 PDF，验证结果如下：

| 项目 | 结果 |
| --- | --- |
| PDF 页数 | 194 页 |
| 处理的独立图像对象 | 713 个 |
| 页面数量 | 处理前后相同 |
| 页面尺寸与页面框 | 处理前后相同 |
| 嵌入图像像素尺寸 | 处理前后相同 |
| 文字边缘 | 保留连续灰阶抗锯齿，未做黑白二值化 |
| 原文件大小 | 48,838,427 字节，约 46.6 MiB |
| 输出文件大小 | 174,219,856 字节，约 166.1 MiB |

背景灰度在代表页中主要集中于约 252。默认参数保持灰度 230 及以下不变，并将 230 到 252 的高光区域平滑过渡到纯白。

文件体积增大是预期结果：原 PDF 的扫描图像主要使用有损 JPEG 压缩，而处理后为了避免再次损伤文字边缘，改用 Flate 无损压缩。不同 PDF 的体积变化会有明显差异。

上述结果来自一个具体文件，不代表所有 PDF 都会获得相同的视觉效果或体积变化。处理重要资料前请保留原文件并抽查输出。

在 Codex 中安装

方法一：通过 Git 克隆

将仓库克隆到 Codex 的个人 Skills 目录：

git clone https://github.com/zjsthmjialin/pdf-background-gray-codex-skill.git
"$HOME\.codex\skills\remove-pdf-background-gray"

如果仓库为私有状态，需要先配置 GitHub 凭据或使用 GitHub CLI 登录：

gh auth login

安装完成后重启 Codex，使新 Skill 被自动发现。

方法二：手动复制

把整个项目目录复制到：

%USERPROFILE%\.codex\skills\remove-pdf-background-gray

最终结构中应直接包含 SKILL.md，不要多嵌套一层目录。

在 Codex 中使用

可以显式调用 Skill：

使用 $remove-pdf-background-gray 处理 C:\path\input.pdf，去掉扫描底灰，保持原分辨率和文字抗锯齿。

也可以用自然语言触发：

把这个扫描 PDF 的页面底色去除，保持原分辨率不变，文字不要出现锯齿，只去底灰。

Codex 应先检查 PDF 类型和代表页，再调用脚本生成新文件并验证输出。

直接运行脚本

环境要求

- Python 3.10 或更高版本
- pypdf
- Pillow
- NumPy

安装依赖：

python -m pip install pypdf Pillow numpy

基本命令

在项目根目录运行：

python scripts/remove_pdf_background_gray.py
"C:\path\input.pdf"
"C:\path\output.pdf"

输入和输出路径必须不同。脚本不会覆盖原文件。

调整参数

python scripts/remove_pdf_background_gray.py
"C:\path\input.pdf"
"C:\path\output.pdf"
--low 235
--white-point 250

| 参数 | 默认值 | 作用 |
| --- | ---: | --- |
| --low | 230 | 此值及以下保持不变；提高它可保护更多浅灰细节 |
| --white-point | 252 | 达到此值时映射为纯白；降低它会更积极地去除较深底灰 |

参数必须满足：

text
0

许可证

当前仓库尚未提供许可证文件。在明确添加许可证之前，代码默认保留全部权利；公开使用、修改或再分发前请先联系作者确认授权范围。