Preface¶

In the DSH plugin ecosystem, Agents often need to compare two pieces of content: configuration snippets, API responses, tables, or document revisions. dsh-tool-diff is a DSH Diff text comparison tool plugin maintained by omdsh-dev, designed to consolidate such comparisons into a read-only, pure-function, zero-dependency diff utility.

Below, we introduce its positioning, installation, typical usage, and usage boundaries.

What This Is¶

dsh-tool-diff provides text / JSON / CSV / Markdown structured comparison and generates unified diffs.

It registers the diff tool with row id tool-diff and is licensed under MIT.

Core Features¶

The diff tool supports the following action types:

• text: Text comparison.
• json: JSON structured comparison.
• csv: CSV structured comparison.
• markdown: Markdown structured comparison.
• patch: Generates a unified diff and validates it in-memory—never writing to disk.

All action types output a JSON text string envelope with a common summary:

{
  "equal": true,
  "truncated": false,
  "beforeBytes": 128,
  "afterBytes": 132,
  "changes": []
}

The field meanings are as follows:

• equal: Whether the two sides are equal.
• truncated: Whether the output has been truncated.
• beforeBytes: Byte count of the before side.
• afterBytes: Byte count of the after side.
• changes: List of changes.

Installation and Activation¶

First, install to the target profile, then verify the plugin has been registered.

The verified installation command for the headless profile is:

dsh plugin --profile headless add github:omdsh-dev/dsh-tool-diff

Note:

• web and headless are different profiles.
• Installing for web does not automatically override headless.
• dsh run uses the headless profile by default.
• If the target profile is web, you need to install separately for the web profile.

After installing for the web profile, you can confirm the tool row has appeared using the following command:

dsh --profile web --dump-config | grep tool-diff

Run validation:

dsh run "Use the diff tool to compare two pieces of text"

Typical Usage¶

When calling the diff tool, you need to fill in the following fields:

1. action: Select the comparison type—supports text, json, csv, markdown, patch.

2. before: The original content.

3. after: The new content.

Optional fields:

• format: Supports unified, structured, both.
• unified is the default for text / patch.
• structured is the default for json / csv / markdown.
• key: For CSV scenarios, key can specify the primary key column name or a 1-based index; by default, comparison is by position.

Below is a minimal call requirement:

Use the diff tool to compare two pieces of text

Applicable Scenarios and Notes¶

Suitable for the following scenarios:

• Need to compare two pieces of text, JSON, CSV, or Markdown content.
• Need to generate a unified diff.
• Need a read-only, pure-function, zero-dependency comparison tool.
• Do not want patch files written to disk—only want to generate and validate in memory.

Usage boundaries:

• Read-only: Does not read files, write files, access the network, or invoke git.
• patch is only generated and validated in memory—never written to disk.
• Single-side input is limited to 256 KiB.
• Output is limited to 64 KiB.
• timeoutMs is 2000.
• Tool parameters are recorded in session logs—do not pass sensitive data.
• The plugin runs with the current DSH process permissions; review the source code and license before installation.

Reference¶

GitHub repository:

https://github.com/omdsh-dev/dsh-tool-diff