Align DeepSeek Harness across machines: DSH plugin drift

DeepSeek Harness will drift across machines from three independent sources: different update methods, different entry points (global and npx coexisting), and different timing. Saying it was upgraded is not enough when two copies on one machine can still diverge. The fix is a manifest with the CLI version and DSH plugin list, plus three fixed audit tables.

Why DeepSeek Harness drifts across machines

Bottom line: drift equals update-method differences plus entry-point differences plus timing differences. The most overlooked and most confusing is the entry point, because it produces identical versions with different behavior.

Option A: manifest-driven alignment (recommended, auditable)

Bottom line: write the CLI version and the DSH plugin list into one executable manifest, run it on each machine, and archive the output. Lowest effort, most stable payoff.

1. Create the alignment manifest:

# dsh-align.txt
cli: @deepseek-ai/dsh@0.2.0-rc.2
plugin: <plugin-package>@<version>
plugin: <plugin-package>@<version>

2. Encode execution as a script — the key is pinning the entry point and data directory:

set -euo pipefail
export DSH_HOME="$HOME/.dsh"          # unify the data directory
npm i -g @deepseek-ai/dsh@0.2.0-rc.2
dsh plugin add <plugin-package>@<version>
dsh --version && dsh plugin           # archive the output for comparison

3. Run the same script everywhere and collect output in one place, even if that place is a shared channel — what matters is comparable text.
4. Upgrade by editing the manifest and re-running; keep the previous manifest as the rollback point.
5. Choose plugins in DSH Plugin Hub first, then write them into the script instead of installing while browsing.

Option B: image or distribution alignment (best with many machines)

Bottom line: preset the CLI and common plugins into an image or internal package so machines pull one artifact. Saves bandwidth and time, and makes versions identical by construction.

1. Build an internal image (see Path C in installing DeepSeek Harness in Docker) and tag it by version.
2. Document the distribution path so machines pull from the internal source instead of the public internet.
3. Upgrade by publishing a new tag; machines change tags, and old tags remain for rollback.
4. Keep data separate from the carrier: the artifact holds the program while DSH_HOME stays local to each machine. Upgrades should never touch data.

Option C: configuration management takes over (larger fleets)

Bottom line: once machine count grows, encode set-data-directory, install-pinned-version, install-plugin-list and verification as an idempotent task and let configuration management run it.

1. Convert the Option A script into an idempotent task — re-running produces no side effects.
2. Validate on one machine before rolling out; never flip the whole fleet at once.
3. Collect output centrally so versions and DSH plugin lists are auditable at any time.
4. Pair it with distribution: the task executes, the image or private registry supplies.

Three audit tables for DeepSeek Harness alignment

Bottom line: alignment is not "upgrade and done" — it is being able to answer what this machine has and how it differs from the standard. Three tables cover version, plugins and configuration.

1. CLI version table: dsh --version plus which -a dsh to confirm a single entry point. More than one entry means not aligned.
2. Plugin table: collect dsh plugin output per machine and compare counts and versions.
3. Configuration table: DSH_HOME target, proxy and registry settings, profile selection. These three explain "same version, different behavior."

Four drift diagnostics for DeepSeek Harness

Bottom line: diagnose outside-in — entry point, version, plugin set, configuration. The first two explain obvious differences; the last two explain hidden ones.

1. which -a dsh returns exactly one result. More means dual entry points.
2. dsh --version matches the manifest. Otherwise the update missed the executed copy.
3. dsh plugin matches the standard list. Missing entries mean skipped installs or a different profile.
4. echo $DSH_HOME and proxy settings match. Otherwise behavior differs for reasons unrelated to version.
5. Run one and two first — they take a minute — before touching three and four. Do not reinstall to start.

DSH plugin troubleshooting across machines

Bottom line: in multi-machine setups, matching versions is only the baseline; entry point, data directory and plugin list determine actual behavior.

1. Unify the entry point — keep either the global install or npx, not both (see npx versus global drift).
2. Unify the data directory — leaving DSH_HOME unset delegates the decision to defaults that may vary per machine.
3. Make the plugin list exportable — if you cannot export it, you cannot compare it.
4. Restart the service after upgrades, and include the restart in the script.
5. Record validated version combinations — the only basis for rollback.
6. Repair status, stated honestly: these options follow the official CLI's version and plugin management notes. There is no official guide for multi-machine alignment, so confirm package names, versions and flags against your own environment.

Sources: apps/cli/README.md, apps/desktop/README.zh.md, npm @deepseek-ai/dsh.