redactpdf

redactpdf

分享 PDF 通常意味着你相信屏幕上涂黑的内容确实已经消失。但很多时候并非如此：文本仍留在文件中，可以直接复制出来。redactpdf 采取了相反的做法。它会在本地 PDF 的文本层中查找敏感文本，生成一份副本，将每个匹配的字符实际替换掉，然后重新读取输出文件，以证明已无法提取任何要求移除的内容。如果验证失败，它会报错，而不是生成文件。

它会检测四类敏感文本。社会安全号码必须符合 SSA 自身的有效性规则（区域码为 001-899，但不包括 666；组号为 01-99；序列号为 0001-9999），因此不会标记格式相符的随机数字组。支付卡号由 13 至 19 位数字组成，数字之间允许用单个空格或连字符分隔，并且必须通过 Luhn 校验。内置类别还包括电子邮件地址和北美电话号码——格式为 (ddd) ddd-dddd、ddd-ddd-dddd、ddd.ddd.dddd 或 ddd ddd dddd，可带可选的 +1 前缀。除此之外，terms 可让你指定自定义的字面字符串，匹配时不区分大小写，并单独统计。省略 detect 时会运行全部四类检测。

检测会针对每个提取出的字符串进行——也就是纯文本或 FlateDecode 内容流中 Tj 和 TJ 操作符的字符串操作数——因此，若匹配内容被拆分到两个字符串操作数中，就不会被检测到。这是该工具所用文本层模型明确说明的限制，并非隐瞒不提。

check_pdf 会报告将要移除的内容，但不会写入任何文件。redact_pdf 会写入脱敏后的副本——绝不会修改输入文件——将每个匹配的字符替换为 #，同时保留字符串长度，然后验证结果。免费处理的文档最多为 10 页；超过此页数时，两个工具都会要求提供许可证。此版本中的许可证检查仅验证格式：由 16 至 512 个 [A-Za-z0-9_-] 字符组成并以 . 分隔的令牌会被视为格式正确，可通过 license 参数或 BLACKOUT_LICENSE 环境变量提供——超出页数上限时，错误会区分缺少许可证（LICENSE_REQUIRED）和许可证格式错误（LICENSE_INVALID）。加密 PDF、基于 xref 或对象流构建的 PDF，以及格式错误的文件会被报告为不受支持，而不会被悄然跳过。

两个工具都会以一行摘要、一个空行和一个围栏 JSON 代码块作为响应，其中包含 path、outputPath（check_pdf 时为 null）、pages、counts、extractableChars——对于 check_pdf，表示输入中落在检测匹配范围内的字符；对于成功的 redact_pdf，则按设计为 0——以及 licenseState。

命令行

npx @reneturcios/redactpdf check_pdf '{"path":"/abs/path/report.pdf"}'
npx @reneturcios/redactpdf redact_pdf '{"path":"/abs/path/report.pdf","terms":["falcon"]}'
npx @reneturcios/redactpdf --version

除非另有 output_path 指定，redact_pdf 会写入 <input>-redacted.pdf（即将输入路径中的 .pdf 后缀替换为该名称）；输出路径不能与输入路径相同，且只有在 overwrite 为 true 时才会替换已有输出文件。

退出代码：成功时为 0，运行时错误时为 1（会打印工具的错误文本），用法错误时为 2。

MCP 服务

npx -y @reneturcios/redactpdf mcp

MCP 客户端配置：

{
  "mcpServers": {
    "redactpdf": {
      "command": "npx",
      "args": ["-y", "@reneturcios/redactpdf", "mcp"]
    }
  }
}

工具

• check_pdf — 报告本地 PDF 中将被涂黑的内容，以及每个类别的匹配数量，不会写入任何内容。
  • path（字符串，必填）— 此计算机上某个 PDF 的绝对路径
  • detect（字符串数组，可选）— 可选值为 ssn、card、email、phone；省略则检测所有类别
  • terms（字符串数组，可选）— 要匹配的字面字符串，不区分大小写
• redact_pdf — 写入本地 PDF 的涂黑副本，永久移除检测到的敏感文本，并验证其已彻底删除。绝不会修改输入文件。
  • path（字符串，必填）— 此计算机上某个 PDF 的绝对路径
  • output_path（字符串，可选）— 默认为 <input>-redacted.pdf；不得与输入文件相同
  • detect（字符串数组，可选）— 可选值为 ssn、card、email、phone；省略则检测所有类别
  • terms（字符串数组，可选）— 要匹配的字面字符串，不区分大小写
  • overwrite（布尔值，可选，默认值为 false）— 允许替换现有输出文件
  • license（字符串，可选）— Pro 许可证令牌；未提供时使用 BLACKOUT_LICENSE

Docker

docker run -i ghcr.io/cloudcorprecords/redactpdf
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/redactpdf check_pdf '{"path":"/w/report.pdf"}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios