JuntaoXiao/PDF-electronic-signature

dsh-pdf-sign

DeepSeek Harness (DSH) 的 PDF 电子签名插件 —— 生成手写风格签名图、在 PDF 上盖章、并用你自己的证书做真正的 PKCS#7 数字签名。

DeepSeek Harness 的 PDF 电子签名插件 —— 生成手写风格签名图、在 PDF 上盖章、并用你自己的证书做真正的 PKCS#7 数字签名。

English · 中文

English

功能说明

三项能力，刻意保持彼此独立，因为它们意味着非常不同的东西：

| 工具 | 产出内容 | 保证 |
|---|---|---|
| pdf_signature_image | 根据姓名生成手写风格签名图（PNG/SVG） | 无 —— 它只是美术图 |
| pdf_sign_stamp | 在 PDF 页面上放置墨迹（签名图和/或文字块） | 仅视觉 |
| pdf_sign_digital | 对整个文件的 PKCS#7/CMS 分离式签名 | 密码学保证（/ByteRange + CMS） |
| pdf_sign_cert_generate | 用于测试的自签名证书 + .p12 捆绑包 | 无 —— 自签名 |
| pdf_sign_inspect | 对 PDF 包含哪些签名的结构化报告 | 仅检查 |

这一区别很重要：盖章式签名看起来像已签名，但什么也证明不了。数字签名能证明文档在签名后未被篡改，并标识密钥持有者 —— 但只有来自真实 CA 的证书才能让阅读器将其显示为受信任。

安装

dsh plugin --profile web add dsh-pdf-sign

重启 DSH，然后 pdf_sign_ 工具即可供智能体使用。

快速开始

1. Make a signature image
pdf_signature_image(text="Juntao Xiao", output_path="/abs/path/sig.png")

2. Stamp it on the last page
pdf_sign_stamp(pdf_path="/abs/path/contract.pdf",
image_path="/abs/path/sig.png",
text="Juntao Xiao", date_text="2026-09-20",
anchor="bottom-right", width=200)

3. Add a real digital signature
pdf_sign_cert_generate(common_name="Juntao Xiao", passphrase="secret",
output_dir="/abs/path/certs")
pdf_sign_digital(pdf_path="/abs/path/contract.pdf",
output_path="/abs/path/contract-signed.pdf",
p12_path="/abs/path/certs/signing-cert.p12",
passphrase="secret", reason="Approval")

工具参考

pdf_signature_image

| 参数 | 类型 | 说明 |
|---|---|---|
| text | 字符串，必填 | 签名文本，通常是签名者的姓名 |
| output_path | 字符串，必填 | 绝对路径；.png（默认）或 .svg |
| font_size | 数字 | 字形大小，单位为 px（默认 120） |
| width | 数字 | 输出 PNG 宽度，单位为 px |
| color | 字符串 | blue-black\|black\|blue\|red、#rrggbb，或分量范围为 0–1 的 r,g,b |
| rotation | 数字 | 整个签名的倾斜角度，单位为度（默认 -2.5） |
| jitter | 数字 | 手写不规则程度，0 = 完全平直（默认 1） |
| underline | 布尔值 | 签名下方的笔锋装饰（默认 true） |
| letter_spacing | 数字 | 字形之间的额外 px 间距 |
| font_file | string | 显式指定字体文件；默认使用找到的最佳手写字体 |
| format | png\|svg | 强制指定输出格式 |

每个字形都使用以文本为种子的模式，作为其自身旋转、垂直抖动的节点输出——因此相同的名字始终会产生完全相同的签名，这在文档被重新签署时非常重要。

最佳可用字体会被自动检测：Windows 上的楷体/标楷体/华文行楷，macOS 上的 Songti/Kai，Linux 上的 Noto Serif CJK/AR PL UKai。

pdf_sign_stamp

| 参数 | 类型 | 说明 |
|---|---|---|
| pdf_path | string，必填 | 源 PDF |
| output_path | string | 默认位于源文件旁边的 -signed.pdf |
| image_path | string | 签名图像（PNG/JPEG） |
| text / date_text / reason | string | 键入的文本块行 |
| page | number\|"last"\|"all" | 默认 last |
| anchor | enum | top/middle/bottom × left/center/right；默认 bottom-right |
| x, y | number | 显式 PDF 点原点，覆盖 anchor |
| width | number | 图像宽度，单位为点（默认 180） |
| opacity | number | 0–1（默认 1） |
| rotation | number | 图像旋转角度，单位为度 |
| margin | number | 边缘边距，单位为点（默认 48） |
| font_size | number | 文本块大小（默认 10） |
| color | string | #rrggbb 或 r,g,b |
| drop_background | string | 将纯色背景抠成透明：none（默认）、white、auto 或 #rrggbb |
| drop_tolerance | number | “此像素为背景”的每通道容差（默认 28） |
| trim_image | boolean | 裁剪透明边距，使墨迹定义边界框（默认 true） |

非拉丁文本（中文、日文、韩文等）使用子集嵌入的系统 TrueType 字体绘制，因为 pdf-lib 的标准字体仅支持 WinAnsi，完全无法编码这些字符。

背景透明度——在叠加两张图像之前请先阅读

签名和印章图像通常导出为不透明图像，并带有纯色背景。不透明背景是一个填充矩形：它会遮住其下方绘制的任何内容。因此，放在签名上方的印章会擦除签名，而盖在正文文本上的图章会将该文本变白。如果你在未使用 drop_background 的情况下传入这样的图像，工具会在其 note 中说明，而不是静默失败。

pdf_sign_stamp(pdf_path="contract.pdf", image_path="signature.png",
drop_background="white")          # opaque white export
pdf_sign_stamp(pdf_path="contract.pdf", image_path="scan.jpg",
drop_background="auto")           # samples the border

- white — 用于通常的白底导出。
- auto — 采样图像边框并抠掉主导边框颜色。当背景是灰白色或你并不知道背景颜色时使用。（它采用最常见的边框颜色，而不是平均值，因此延伸到边缘之外的墨迹不会把估计值拖向灰色。）
- #rrggbb — 显式指定颜色。
颜色保真度得以保留：该工具包对每个像素进行反合成（I = (C − B·(1−a)) / a），而不是仅仅将其淡化，因此叠加在页面上的结果能够还原原始像素，而不会显得发白褪色。只有浅色背景才能以这种方式进行抠图（最暗通道必须 ≥ 32）；深色背景会被拒绝，并给出解释性错误。PNG 和 JPEG 源文件均可使用。

随后 trim_image 会裁剪透明边距，因此放置框会跟随实际墨迹而非源画布——这一点很重要，因为带内边距的画布否则会让图章看起来比预期小得多、偏移得多。

pdf_sign_digital

| 参数 | 类型 | 说明 |
|---|---|---|
| pdf_path | string，必填 | 源 PDF |
| p12_path | string，必填 | 包含私钥的 PKCS#12（.p12/.pfx）文件 |
| passphrase | string | PKCS#12 口令（未受保护时为空） |
| name / reason / location / contact_info | string | 记录在签名中 |
| signing_time | string | ISO 时间戳；默认为当前时间 |
| page | number\|"last" | 签名部件所在的页面 |
| widget_rect | number[4] | 以点为单位的 [x1,y1,x2,y2] 签名部件矩形 |
| sub_filter | enum | adbe.pkcs7.detached（默认）或 ETSI.CAdES.detached |
| signature_length | number | 预留的占位字节数；如果签名报告长度错误，请增大该值 |

pdf_sign_cert_generate

创建自签名证书和 .p12，或打包现有的密钥 + 证书对（同时传入 key_path 和 cert_path）。需要 OpenSSL；Git for Windows 中自带的 OpenSSL 会被自动找到。

pdf_sign_inspect

报告签名字段、已签名的字节范围数量、CMS 子过滤器以及占位符元数据。仅进行结构检查——它不验证密码学有效性，后者需要签名者的证书链。

安全立场

- 不附带任何密钥、CA 或信任锚。 这里的任何内容都无法伪造出阅读器会信任的签名。
- 自签名证书生成的签名会验证为完整，但显示为不受信任。这是正确且预期的结果；获取 CA 签发的证书是你自己的事。
- 你的私钥和口令保留在你的机器上。该插件不会向任何地方传输任何内容。
- 签名写入占位符时不使用对象流，这是增量更新签名方案所必需的——并非风格上的选择。

要求

- Node.js ≥ 20
- OpenSSL，仅用于 pdf_sign_cert_generate（自动检测，包括 Git for Windows）
- 可选：用于 PNG 光栅化的原生 @resvg/resvg-js 绑定。它作为依赖项提供；如果无法在你的平台上加载，pdf_signature_image 会改为写入 SVG，并明确说明这一点。

已知限制

- pdf_sign_inspect 不执行密码学验证，也不查询信任存储。
- 加密 PDF 会以 ignoreEncryption 加载，因此不支持对加密文档进行签名。
- 子集嵌入的 CJK 字体会适度增加文件大小（仅子集，而非整个字体）。
- 提供了 ETSI.CAdES.detached，但只有 adbe.pkcs7.detached 经过了端到端实测。

许可

MIT

中文

它做什么

五种能力，刻意分开——因为它们代表的东西完全不同：

| 工具 | 产出 | 保证 |
|---|---|---|
| pdf_signature_image | 手写风格签名图（PNG/SVG） | 无，它只是图像 |
| pdf_sign_stamp | 把签名盖到 PDF 页面上（签名图 和/或 文字块） | 仅视觉 |
| pdf_sign_digital | 覆盖整个文件的 PKCS#7/CMS 分离式签名 | 密码学保证（/ByteRange + CMS） |
| pdf_sign_cert_generate | 自签名证书 + .p12（测试用） | 无，自签名 |
| pdf_sign_inspect | PDF 中签名结构的检查报告 | 仅结构检查 |

这个区分很关键：盖章看起来像签了名，但什么都证明不了；数字签名能证明文件在签名后未被改动、并标识持钥者身份——但只有来自真实 CA 的证书，PDF 阅读器才会显示为「受信任」。

安装

dsh plugin --profile web add dsh-pdf-sign

重启 DSH 后，agent 即可使用 pdf_sign_ 系列工具。

快速开始

1. 生成签名图
pdf_signature_image(text="肖俊涛", output_path="D:/sign/sig.png")

2. 盖到最后一页
pdf_sign_stamp(pdf_path="D:/contract.pdf",
image_path="D:/sign/sig.png",
text="肖俊涛", date_text="2026-09-20",
anchor="bottom-right", width=200)

3. 加真正的数字签名
pdf_sign_cert_generate(common_name="肖俊涛", passphrase="你的口令",
output_dir="D:/sign/certs")
pdf_sign_digital(pdf_path="D:/contract.pdf",
output_path="D:/contract-signed.pdf",
p12_path="D:/sign/certs/signing-cert.p12",
passphrase="你的口令", reason="合同审批")

五个实现要点

1. 确定性签名：每个字以独立的旋转+抖动节点渲染，抖动由文本内容做种子——同一个名字永远生成一模一样的签名，重复签署不会出现两种笔迹。
2. 中文文字盖章需要嵌入字体：pdf-lib 的标准字体是 WinAnsi 编码，无法编码任何中文。插件会自动寻找系统中可嵌入的 TrueType 中文字体（楷体／黑体／仿宋／等线）并做子集嵌入。
3. 数字签名的占位符必须禁用对象流保存（useObjectStreams: false），这是增量更新签名方案的硬性要求，不是代码风格选择。
4. 白底必须转透明，否则叠放会互相遮盖（drop_background）。签名与印章图通常是不透明的实底图，而不透明背景就是一个实心矩形——印章盖在签名上会把签名整个擦掉，盖在正文上会把正文涂白。所以：

pdf_sign_stamp(pdf_path="合同.pdf", image_path="签名.png",
drop_background="white")     # 常见白底导出图
pdf_sign_stamp(pdf_path="合同.pdf", image_path="扫描件.jpg",
drop_background="auto")      # 自动采样边框色

- white：常规白底导出图；auto：采样边框并去掉占主导的边框色；也可直接给 #rrggbb。
- 保留颜色保真：不是简单地把白变透明（那会让墨迹发灰），而是对每个像素做反合成（I = (C − B·(1−a)) / a），使结果叠到页面上后与原图像素完全一致。
- 取的是边框众数而非均值——墨迹触到画布边缘时，均值会被拉灰（实测会把 250,248,245 误算成 238,236,233），众数不受影响。
- 仅支持浅色背景（最暗通道 ≥ 32）；深色背景会明确报错，不静默出错。PNG 与 JPEG 均可。
- 未指定 drop_background 而图片又是「全不透明且 ≥90% 近白」时，工具会在 note 里主动提示该开这个参数，而不是让你事后才发现白块盖住了东西。
5. trim_image（默认开）裁掉透明留白：让放置框跟着真实墨迹走，而不是源画布。否则带大量留白的画布会让印章看起来远小于预期、位置也偏。

安全立场

- 不内置任何密钥、CA 或信任锚。这里没有任何东西能伪造出阅读器会信任的签名。
- 自签名证书产生的签名「完整性有效」但显示为「不受信任」——这是正确且预期的结果；取得 CA 签发的证书是你自己的事。
- 你的私钥与口令只留在本机，插件不向任何地方传输数据。

已知限制

- pdf_sign_inspect 不做密码学验证，也不查询信任库。
- 加密 PDF 以 ignoreEncryption 方式加载，因此不支持对加密文档签名。
- ETSI.CAdES.detached 虽已提供，但只有 adbe.pkcs7.detached 经过端到端实测。
- 文本图章使用子集嵌入字体，会让 PDF 略微变大（只嵌入用到的字形，不是整个字体）。

许可

MIT

本项目是 DeepSeek Harness 的社区插件，并非 DeepSeek 官方产品。
本插件与 Adobe、OpenSSL 及任何证书颁发机构均无从属关系。