Introduction¶

In DSH’s document processing pipeline, there is often a question that needs to be answered: Compared to the previous version, what has changed in this file? Using Word’s built-in “Compare” feature requires uploading the file to a third-party server; using git diff, the output is a line-by-line patch, so if you change a specific price term, you have to find it yourself among a screen full of -/+. dsh-doc-compare is a plugin designed for this specific task.

What is it¶

dsh-doc-compare (npm package name @deepwhale-cn/dsh-doc-compare) is a DSH plugin, authored by feely0208 (Wenzhou Deepwhale Intelligent Technology Co., Ltd.), under the MIT License, current version 0.1.0. It reads in two .docx / .md / .txt files, performs a clean comparison at the paragraph level, and outputs a “Before -> After” report, suitable for item-by-item verification of contracts or proposal documents.

Core Capabilities¶

Below is an introduction to the capabilities listed in the README.

1. Three types of paragraph-level differences: added, deleted, modified. Modified items show the content before and after, highlighting the changed words or sentences.
2. Structure risks are highlighted separately: Renamed, deleted, or demoted titles (e.g., H2 dropped to H3) are listed separately in the report. In contract scenarios, these changes are usually more critical to confirm than typos.
3. Table comparison by row: The report shows row changes for each table (e.g., 3 → 4 rows), and specifically which rows were added, deleted, or modified.
4. Two output formats: Default Markdown report, can be saved separately with --out; --json outputs machine-readable results.
5. Local execution: No internet connection required, no uploads, no calls to third-party APIs; .docx files are parsed locally within the process using the pure JS library mammoth.

Installation and Usage¶

The installation command comes from the plugin README:

dsh plugin --profile web add @deepwhale-cn/dsh-doc-compare

After installation, there are two entry points: the command line dsh-doc-compare, and the sidebar “Document Comparison” panel. Environment requirements: Node >= 18, dsh >= 0.1.0-rc.6 and < 0.3.0; the only third-party dependency is mammoth ^1.13.0, pure JS, offline capable, installation size is approx 1.9MB, the rest are Node built-in modules.

Typical Usage¶

Three typical ways to call the command line:

# Output Markdown report to terminal
dsh-doc-compare 合同-旧.docx 合同-新.docx

# Save report + machine-readable JSON
dsh-doc-compare 旧.md 新.md --out 比对报告.md
dsh-doc-compare 旧.txt 新.txt --json

Exit codes are key for scripted calls. The README provides three levels:

Use --max-paragraphs when you need to limit the comparison volume. By default, only the first 2000 paragraphs (narrative paragraphs, including titles) are compared; excess parts are explicitly warned about in the report. Increase this value when a full comparison is needed; the hard limit is 5000.

The usage on the panel side is different: paste a segment of text on the left and right, compare locally, and view modifications/additions/deletions in the panel. Title structure changes are listed separately with a red risk bar. File comparison does not go through the panel; the panel does not read local file paths. Use the command line when comparing files.

Suitable Scenarios and Notes¶

Suitable for people and processes that need to confirm document changes item by item: pre-signing contract verification, finalizing proposal reviews, and batch checking which clauses have changed across multiple versions. For documents with significant differences or large sizes, first confirm if the paragraph count falls within the default 2000 paragraphs.

Two prerequisites for use: the plugin runs with the permissions of the current dsh process; what files it can read depends on the process permissions. Before installation, check the source code and license; this plugin is under the MIT license. The plugin only reads the original files and does not rewrite documents; only --out writes the report, and it writes to the specified path.

Related Links¶

• Directory: https://www.skillhub.cn/plugins/feely0208/dsh-doc-compare
• GitHub: https://github.com/feely0208/dsh-doc-compare