Introduction¶

When developing user interfaces or enabling agents to interact with pages, you often face one question: Did the page actually change after this modification? Visually comparing two screenshots is prone to missing details, and writing pixelmatch scripts from scratch every time is too repetitive.

dsh-screenshot-diff is a workflow-type plugin within the DeepSeek Harness (DSH) ecosystem. DSH’s philosophy is “everything is a plugin,” and repetitive verification actions like this are well-suited for being encapsulated as plugins: one command takes two existing screenshots as input and outputs a diff image highlighting differences in red, a triple comparison image with labels, and a JSON snippet consumable by scripts. It does not handle screenshot capture; the input must be two screenshots you have already captured.

What is it¶

dsh-screenshot-diff is maintained by PangYiMing, currently at version 0.1.1, and is licensed under MIT. One-sentence positioning: performs pixel-level diffing on two existing screenshots based on pixelmatch and produces two files:

<out>/diff.png            Diff highlighting differences in red ([255,0,0])
<out>/compare-triple.png  Triple comparison: Left A | Middle B | Right diff <similarity>, with labels in the top-left corner

It also outputs a JSON snippet via stdout with fields similarity, numDiffPixels, total, sensitivity, and threshold, facilitating further judgment within scripts.

Core Features¶

1. Three levels of sensitivity:

   • normal: Grayscale + threshold 0.1 + ignore anti-aliasing; results are stable.
   • high: Color + threshold 0.02 + includes anti-aliasing.
   • ultra: threshold 0.01; most sensitive, but also generates the most noise.

2. Detail control: --threshold N can explicitly override the pixelmatch threshold, overriding the sensitivity presets; --crop-top PX trims the top of both images by a certain number of physical pixels simultaneously, suitable for filtering out fixed page headers.

3. Automatic dependency discovery follows this order: --compare-tool parameter > COMPARE_TOOL_ENV environment variable > scripts/compare-tool in the repository. The underlying dependencies are sharp / pngjs / pixelmatch.

4. Fails immediately if dimensions do not match, without stretching—this is an intentional design to avoid layout differences being masked by scaling.

Installation and Usage¶

Install from GitHub using the following command:

dsh plugin --profile demo add github:PangYiMing/dsh-screenshot-diff

The README also lists a command dsh plugin --profile demo add dsh-screenshot-diff, marked as available “after publishing to npm,” but currently, installation via GitHub is the primary method.

Before installing, it is recommended to browse the repository source code and LICENSE: the plugin runs with the permissions of the current dsh process. Please confirm that the code behavior and license (this plugin is MIT) meet your expectations before installing.

Typical Usage¶

First, prepare two screenshots captured in the same viewport and resolution, then run:

bash scripts/diff.sh /abs/path/imgA.png /abs/path/imgB.png \
  --label-a before \
  --label-b after \
  --sensitivity high \
  --out /tmp/diff-out

This command compares imgA.png and imgB.png and outputs to /tmp/diff-out with high sensitivity. Available parameters are as follows:

Usage Advice¶

The README provides several usage guidelines that are worth following:

• Similarity does not equal a conclusion. Even if the similarity is above 90%, manually check if the diff area is concentrated in the positions that should have been changed.
• First run with normal; upgrade to high when you need to capture low-contrast differences like light gray or white gradients. ultra generates the most noise, so use it with caution.
• The two images must be from the same viewport/resolution and the same page state (scroll position, popups, loading states), otherwise the diff result is meaningless.

Use Cases and Notes¶

Suitable for frontend development, UI regression testing, and scenarios where page changes need to be verified after an agent operates on a browser. The prerequisite is that you already have a means of capturing screenshots; this plugin only fills in the “comparison” step.

Reiterating security: the plugin runs with the permissions of the current dsh process. Please check the repository source code and license yourself before installing.

Conclusion¶

dsh-screenshot-diff reduces the task of “where exactly are the differences between two screenshots” to a single command: the diff image locates differences, the triple comparison image facilitates manual review, and the JSON result is for script judgment. Combined with three sensitivity levels and threshold overrides, it covers most daily comparison needs.

• Community Directory Page: https://www.skillhub.cn/plugins/PangYiMing/dsh-screenshot-diff (Independent site, no official affiliation with DeepSeek / Huanfang)
• GitHub Repository: https://github.com/PangYiMing/dsh-screenshot-diff