DSH adopts a “everything is a plugin” architecture, which means extensions to core functionality are usually implemented through plugins. During development and operations, keeping the DeepSeek Harness (DSH) core version up to date and obtaining official documentation are often two separate tasks. The dsh-updater-npm plugin combines these two capabilities: it can update DSH itself with a single npm command, incrementally sync official documentation locally, and provide search and reading tools.

Core Features

The plugin primarily provides the following capabilities:

  1. DSH Update (npm): Automatically checks the latest version of @deepseek-ai/dsh, supports one-click execution of npm install -g @deepseek-ai/dsh@latest, and displays real-time progress during updates.
  2. DSH Documentation (Official): Incrementally syncs the official docs/ directory locally (skips unchanged files based on GitHub blob sha), supports progress bar display, and provides two model tools: dsh_docs_search and dsh_docs_read.
  3. Multilingual Support: The UI and host-side messages support Chinese/English and automatically follow the system language preference.
  4. Plugin Self-Check and Gate: The plugin checks its own version against the latest npm version. If its own version is outdated, it prompts a plugin update first and disables the DSH update button.
  5. Runtime Mode Detection: Automatically detects whether the current DSH instance is running from a global npm installation (npm-global) or a source tree (source).
  6. Upgrade Safety Net: Automatically backs up configuration, presets, and session logs before upgrading (retaining the most recent 5 copies), and supports staged installation, rollback, and cleanup of leftover files.

Installation and Enablement

Installing the plugin requires DSH’s plugin management commands. After installation, restart the DSH Web instance. The settings page will show two cards: “DSH Update” and “DSH Docs”.

dsh plugin --profile web add dsh-updater-npm

Usage Guide

DSH Update Flow

Click “Update via npm” on the settings page to start an update. This action automatically checks for the latest version. When a newer version is detected, a small red dot appears next to “DSH Update” in the left navigation panel of the settings page.

The update process displays real-time progress. After completion, a “Restart DSH” button appears. Clicking it causes the process to exit using the original startup command and then relaunch.

Version Comparison Rule: Version comparison follows semver-style rules. If the local version is newer than the remote version (for example, rc.7 vs rc.6), the system does not incorrectly report an available update.

Plugin Self-Version Check: The card displays the plugin’s own version number. If a newer plugin version is detected, a red notice appears with an update command, and the “Update via npm” button is disabled. This prevents upgrade failures caused by flaws in older plugin upgrade flows (such as missing dependencies).

DSH Docs Sync

Docs sync is disabled by default. Enable the “Automatically sync official docs” toggle on the settings page.

  1. Storage Location: Documents are synced to $DSH_HOME/docs-sync/, and the index file is $DSH_HOME/docs-sync/.index.json.
  2. Search and Read: Once enabled, use dsh_docs_search to search the local index (Chinese queries prioritize Chinese docs) and dsh_docs_read to read docs (supports section-focused reading and 80KB truncation).
  3. Incremental Sync: The first sync contains approximately 217 documents; subsequent incremental updates run silently every 24 hours.

Runtime Mode and Update Strategy

The plugin adopts different update strategies based on the current DSH runtime mode:

Runtime Mode Update Method
npm-global Normal deployment scenario. On Windows, uses a staged update (new version installed into a separate staging directory, then atomically swapped and restarted); on non-Windows, uses in-place npm install -g.
source Source tree runtime mode (for example, pnpm dsh web). Updates cannot be performed via npm; use git pull instead.

Upgrade Safety Net Details:
In Windows environments, the plugin attempts to use PowerShell 7 (pwsh). If it is not installed, it offers a one-click installation prompt.
For npm-global mode, configuration files, presets, and session logs are automatically backed up to the $DSH_HOME/upgrade-backups/ directory before upgrading.
After the upgrade completes, the old version directory is renamed to dsh.old-* to preserve a rollback point. If an exception occurs during the upgrade, you can manually roll back if needed.

API and Commands

In addition to settings-page operations, the plugin provides HTTP endpoints and chat commands:

  • Check update: GET /dsh-updater-npm/check
  • Run update: POST /dsh-updater-npm/update
  • Restart instance: POST /dsh-updater-npm/restart
  • Clean leftover files: POST /dsh-updater-npm/cleanup
  • Trigger docs sync: POST /dsh-updater-npm/docs/sync
  • Search docs: GET /dsh-updater-npm/docs/search?q=&lang=&limit=
  • Read docs: GET /dsh-updater-npm/docs/read?path=&section=

Notes

  1. Windows Environment: PowerShell 7 (pwsh) must be installed; otherwise, the update feature may be restricted.
  2. Source Tree Mode: In source tree mode, npm update is unavailable; use git pull.
  3. Configuration File: The docs-sync toggle state is stored in $DSH_HOME/plugin-data/dsh-updater-npm/config.json.

Summary

By combining DSH update management with local synchronization of official documentation, dsh-updater-npm simplifies the maintenance workflow for developers. It provides clear progress feedback, robust backup and rollback mechanisms, and adaptation to different runtime modes. It is suitable for users who need to deeply integrate DSH official documentation locally and keep their toolchain up to date.