Lindong-K / doc-watermark

Document Watermark · 文档水印

A professional, reading-friendly watermark for PDF / HTML / DOCX / TXT / Markdown, with built-in verification that proves the watermark never touches the reading area.

Design principle (industry standard, see 中文说明): the watermark must never enter the content area. Margin-first placement is preferred; full-page tiled patterns are the most intrusive option and are forbidden.

---

✨ Features

Format	Method
PDF	reportlab + pypdf overlay drawn at known page coordinates inside the page margins (left vertical text rotated 90° as a single run + bottom-right corner mark, 32% opacity by default). No CSS print positioning.
DOCX	Word-native VML watermark in the header layer (z-index below body text), light fill — no reliance on Word's unreliable transparency.
HTML	CSS screen-only watermark (content layer above it, z-index:-1), hidden on @media print.
TXT / MD	Header/footer signature lines.

• Verification (PDF): renders clean vs. watermarked pages at 1.5×, pixel-diffs them, and asserts every differing pixel lies in the page margins (content-area diff must be 0). Falls back to content-stream text detection when an overlay is too faint to diff (≤ 6% opacity).
• Windows robustness: probes file locks with an exclusive byte lock before writing; if the output is locked it automatically falls back to *_wm2, *_wm3 … and verifies the file timestamp after writing (no silent failures).
• Zero runtime temp files in the Harness plugin path (engine is piped via stdin, config via env).

🚀 Quick start

pip install -r requirements.txt
python demo.py          # generates neutral samples into ./examples and watermarks them

One-shot CLI:

python wm_engine.py config.json

config.json:

{
  "src": "C:\\path\\to\\doc.pdf",
  "watermark_text": "DeepSeek AI · Original",
  "position": "left_vertical+bottom_right",
  "color": "#0969DA",
  "opacity": 0.32,
  "verify": true
}

stdout returns one JSON report containing a ready-to-paste Markdown report and the per-page pixel-diff table.

⚙️ Configuration

Key	Default	Meaning
src	—	input document path (.pdf / .html / .docx / .txt / .md)
dst	*_wm.ext	optional custom output path
watermark_text	DeepSeek AI · Original	watermark string
position	left_vertical+bottom_right	left_vertical / bottom_right / left_vertical+bottom_right / center_diagonal / header_footer
color	#0969DA	hex color
opacity	0.32 (overlay 0.05)	margin tier; center_diagonal is clamped to ≤ 0.06 and drawn under the content layer
font_size	adaptive	font size (pt); per-format defaults otherwise
font	auto	PDF: STSong-Light for CJK, Helvetica otherwise
verify	true	run the render-diff verification (PDF)
page_margin_pt	28.8	page margin used by the content-area assertion (A4 default 0.4in)

🔍 Verification methodology

1. Generate two PDFs: A = clean original, B = watermarked.
2. Render every page at 1.5× (pypdfium2) and pixel-diff (Pillow, threshold > 40).
3. Assert: 100% of differing pixels are inside the page margins; content-area diff = 0.
4. Report per page: diff pixel count, bounding box (pt), content diff, verdict.

Sample output: examples/verification-report.md

🤖 DeepSeek Harness plugin

wm_plugin.host.js is the Host half of a dynamic Cordis plugin for DeepSeek Harness that registers a model-callable tool watermark_document. It pipes the engine via stdin and configuration via the WM_CONFIG environment variable — no temporary files are written. It locates wm_engine.py next to the target document or in the workspace root.

📄 License

MIT

---

中文说明

专业、不干扰阅读的文档水印引擎：PDF / HTML / DOCX / TXT / MD，自带客观验证。

设计红线（来自行业规范与实战踩坑）

1. 水印永不进入正文阅读区：优先放在页边距（左侧竖排品牌文字 + 右下角小标记）。
2. 必须覆盖页面时（如"机密"类），透明度不得超过 6%，且绘于内容层之下。
3. 禁止整页平铺水印纹（对文字密集文档最影响阅读）。
4. 竖排水印必须整段旋转 90° 一次绘制，严禁逐字符堆叠（基线不齐、大小不一）。
5. PDF 水印禁止用 CSS position:fixed 打印（定位不可靠、@page 边距会让其整体消失）——必须用 reportlab+pypdf 按已知页面坐标叠加。

快速上手

pip install -r requirements.txt
python demo.py

demo.py 会生成中性示例文档（examples/sample.*）并演示加水印与逐页 diff 验证， 输出报告见 examples/verification-report.md。

各格式方案

• PDF：reportlab 叠加层（左侧竖排 + 右下角，A4 默认 28.8pt 边距内），透明度 0.32。
• DOCX：Word 原生 VML 页眉水印（正文层之下，浅色填充）。
• HTML：CSS 屏幕水印（z-index:-1，内容层之上），打印时隐藏。
• TXT/MD：页眉/页脚署名行。

验证

1.5× 渲染"无水印 vs 有水印"两份 PDF 逐页像素 diff，断言差异像素 100% 位于页边距、正文区 0 差异； 覆盖式水印过淡时回退到内容流文本检出。实测 9 页文档全部通过。

Windows 健壮性

写入前用独占字节锁探测文件占用，被占用自动改用 _wm2/_wm3；写后校验非空 + 时间戳，防静默失败。

DeepSeek Harness 插件

wm_plugin.host.js 是动态 Cordis 插件的 Host 半区，注册模型可调用的 watermark_document 工具； 引擎经 stdin 传入、配置走 WM_CONFIG 环境变量，全程不写临时文件。引擎脚本放在文档同目录或 工作区根目录即可。