dsh-watcher: Automatic API Change Comparison and Impact Analysis Tool for DeepSeek Harness Plugins

Introduction¶

DeepSeek Harness (DSH) is in a phase of high-frequency iteration, and plugin APIs frequently undergo breaking changes. The official team usually does not maintain a CHANGELOG.md, and explanations in community Discussions rely on manual writing, which can lead to incomplete coverage and delays.

dsh-watcher is an automatic API surface comparison engine used to check, in one command before an upgrade, whether dependent APIs and configuration fields have changed, the scope of changes, and their specific impact. It uses the git history of the official repository and the docs/cordis-api / docs/subsystems documentation layer as the source of truth, providing AST-level diff analysis.

Core Features¶

dsh-watcher provides the following core capabilities:
* AST-level breaking-change diff: Performs syntactic-level breaking-change detection for the plugin API surface.
* Plugin impact analysis: Analyzes the specific impact of changes on your plugin source code.
* Daily feedback radar: Aggregates daily summaries from official Discussions and repository-wide Issues/PRs.
* Agent skill: Provides a pre-upgrade comparison procedure that the Agent can follow.
* CI watch: Supports CI environments, periodically monitors the official repository, and automatically generates reports.

Installation and Activation¶

Install it as a DSH plugin. The main process entry point registers the bundled skill into ctx.skills:

dsh plugin --profile web add github:2DogsLee/dsh-watcher

Prerequisites:
* You need a local checkout of the official DeepSeek Harness repository, with a path that includes docs/cordis-api and docs/subsystems.
* This package only includes the procedure; the scripts that actually run require a full clone of this repository.

Activation:
After installation, restart DSH. When you need to upgrade DSH or a plugin reports an interface error, the Agent can follow the procedure to run the comparison before modifying code.

Typical Usage¶

1. Configure the official repository path (one-time configuration):

    $env:DSH_CHECKOUT = "D:\path\to\deepseek-harness-checkout"

2. Run a version comparison:

    ./scripts/diff-api.ps1 -From dsh-v0.1.7-rc.2 -To dsh-v0.2.0-rc.2

3. View the report:
   • Human-readable: archive/0.1.7-rc.2_to_0.2.0-rc.2/report.md
   • Machine-readable: archive/0.1.7-rc.2_to_0.2.0-rc.2/report.json

Breaking-Change Heuristics¶

Conservative heuristic rules are currently used: it prefers reporting a warning over missing a breaking change. The main determination signals are as follows:

Notes¶

• Conservative strategy: This tool aims to reduce false negatives, so it may produce some false positives. If you encounter false positives, it is recommended to file an Issue to tighten the rules.
• Environment requirements: The comparison and scanning scripts require a full clone of this repository. The skill only contains procedural instructions.
• License: MIT License.