Introduction

The core idea of DeepSeek Harness (DSH) is “everything is a plugin.” As the number of locally installed plugins grows, the problem developers face gradually shifts from “how to use” to “how to manage.” How can you confirm that a plugin matches the capabilities it declares? Are there conflicts between different plugins? After upgrading DSH, do existing plugins still work correctly? DSH Harbor provides an evidence-based, read-only ledger for plugins already installed on a machine. Through capabilities such as capability inventory, declared-versus-detected comparison, runtime attribution, conflict detection, version drift tracking, and upgrade preflight, it helps developers govern their setup without breaking the existing environment.

Core Capabilities

DSH Harbor performs evidence-first governance of plugins, primarily including the following capabilities:

  • Capability inventory: Scans all third-party plugins in DSH configuration files and reports against a fixed vocabulary of 13 capabilities. Source-code findings carry file:line evidence, ensuring traceability of origin.
  • Declared vs detected: Compares the capability declarations in a plugin’s package.json with the detected capabilities, exposing missing or unknown capability IDs. If a declaration is malformed, reporting is suppressed to prevent a single bad package from affecting overall results.
  • Runtime attribution: In the DSH host runtime, enumerates tools, providers, and routes, and attributes them only to plugins installed by the currently active configuration file. Host registry entries corresponding to uninstalled plugins are marked as coverage gaps.
  • Conflict detection: Searches the ledger for tool names, route prefixes, provider IDs, client module IDs, and order-sensitive message hooks within the same configuration file.
  • Version drift: Detects version differences across configuration files. Local offline mode is the default. Optional upstream checks are independent of the preflight flow, and their results are cached.
  • Change timeline: Snapshots track additions, removals, version changes, configuration migrations, capability changes, and declaration changes.
  • Upgrade preflight: Before upgrading DSH, checks plugin compatibility, validates dsh.client.inject IDs and host peer ranges, and checks agent-presets.default in the configuration file for migration issues.

Usage

DSH Harbor provides CLI commands for scanning and preflight checks.

Upgrade Preflight

Before upgrading, you can use the following commands to check plugin compatibility under the target DSH version:

# 列出发行标签、最新版本和本地缓存的宿主机树
harbor preflight --list

# 检查 DSH 的下一个版本（或指定具体版本）
harbor preflight --dsh next

# 检查特定版本，并以 JSON 格式输出
harbor preflight --dsh 0.1.5-rc.2 --json

Cross-Process / Uninstalled Checks

When you are not operating within a specific configuration profile (for example, in CI) or when a package is not installed, you can explicitly specify the check target:

# 检查当前仓库（需先构建）
harbor preflight --dsh next --plugin .

# 检查远程包
harbor preflight --dsh next --pack @scope/some-plugin@1.2.3

Notes

  • Runtime environment and permissions: DSH plugins run in the host machine’s Node.js runtime domain and have the same local privileges as DSH itself. Therefore, review the source code and license before installing or enabling them.
  • Node version requirement: resolve hook requires Node.js 20.6 or later.
  • Offline mode: The default scanning path is offline. Only explicit --check-updates, harbor preflight, or update operations in the settings panel contact the registry.
  • Configuration checks: DSH 0.1.2 introduces a rename of the built-in agent preset (code -> ptc). If agent-presets.default in settings.yaml has not been migrated, new sessions will fail, and preflight will report the issue.
  • Ledger nature: DSH Harbor is a read-only ledger for installed plugins. It provides evidence and detects conflicts, rather than fixing issues.

Summary

DSH Harbor focuses on objective, evidence-first governance of installed DeepSeek Harness plugins. By providing mechanisms such as conflict detection, version drift tracking, and upgrade preflight, it helps developers maintain predictability and stability in a complex plugin ecosystem.