DeepSeek Harness Plugin

wingsky-1/dsh-plugin-hub#packages/dsh-lan-proxy

Stars ★ 32 Downloads (30d) 1,518 Category Remote & Mobile Added 2026-08-18 npm @wingsky-1/dsh-lan-proxy

Access the dsh web UI over LAN: HTTP/HTTPS/WS forwarding plus TLS (self-signed or custom certificates); adaptive Brotli/gzip compression for HTTP and permessage-deflate for WebSocket; half-open WebSocket probing keeps mobile clients from going stale after backgrounding; launch-token auto-injection lets LAN devices connect without copying the token; DNS-rebinding protection + loopback-only upstream allowlist. Retired by the author: published npm versions stay installable but receive no further DSH adaptations (migration guide: docs/migrations/dsh-lan-proxy.md in the repository).

Install

# from npm (prebuilt)

dsh plugin --profile web add @wingsky-1/dsh-lan-proxy

# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)

dsh plugin --profile web add github:wingsky-1/dsh-plugin-hub#path:/packages/dsh-lan-proxy

Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).

README

CI

简体中文 | English

Maintenance status: limited maintenance

I have temporarily stopped using DeepSeek Harness, and this project is entering limited maintenance. Maintenance will prioritize evaluating reproducible user-reported bugs, especially security, data integrity and core functionality issues. Support for newer upstream rc releases will be considered based on actual demand, the scope of changes and available time; there is no commitment to support every release or to a fixed response, fix or release schedule.

New features, major refactoring and the 1.0.0 rewrite plan are on hold. The repository and published packages remain available. Community fixes, forks and maintenance handover proposals are welcome; PRs will be reviewed as time permits, without a guarantee of prompt merging. Compatibility is defined by this README and the corresponding release notes; alpha compatibility is not promised.

See the maintenance announcement for the full statement and handover discussion.

A collection of plugins for the DSH (DeepSeek Harness) web GUI, distributed via npm: install them all at once as a single bundle, or pick individual plugins as needed.

  • Bundle package: @wingsky-1/dsh-plugins-all — install everything in one shot
  • Individual plugins: @wingsky-1/dsh-* — install only what you need
  • The current source tree maintains five packages: one bundle and four feature packages; the bundle contains all four feature packages

Quick navigation

Before you start · Quick start · Plugin list · Configuration and maintenance · Verification and troubleshooting · Detailed reference · Development and architecture

Before you start

Version support (rc only)

This plugin set only adapts to rc (release-candidate) releases of DeepSeek Harness — alpha versions are not supported.

Version 0.2.11 targets the rc.1 baseline below; 0.2.10 targets the older rc.2 baseline. Before installing, confirm that the target plugin version is published in the registry and matches your DSH version.

  • The official type-layer catalog in pnpm-workspace.yaml is the single version source; each package's peerDependencies is an exact-version projection generated by pnpm catalog:sync-peers. Packages on this branch project dsh 0.2.2-rc.1 and Cordis 4.1.0; the DSH CLI and every linked/registry plugin must match this exact target; other DSH versions are unsupported
  • Running DSH 0.2.2-rc.1 requires Node >=24.9. The repository's Node >=23.6 threshold for running TypeScript tests directly with native type stripping is a development-tool minimum; the two thresholds serve different purposes
  • Upgrade order: stop the running old dsh web and back up plugin configuration and session data, upgrade the DSH CLI to 0.2.2-rc.1, update the plugins to 0.2.11 with dsh plugin ... update, then start the new dsh web and verify it. Release artifacts may be published before a user upgrades, but the old CLI cannot install or load the new plugins normally; do not use allow-version to bypass the peer check
  • Per-release adaptation baselines, breaking changes and upgrade guides live in Release Notes
  • Support for newer official rc releases is evaluated individually, without a commitment to follow every release. Alpha versions are unsupported; versions outside the stated compatibility baseline are not covered by a compatibility promise.

Individual install vs. bundle: pick ONE

Each individual package and the bundle share the same patch id (dsh-*). Install only one way — installing both dsh-plugins-all and any individual package such as @wingsky-1/dsh-notifier results in duplicate same-name entries, and dsh web fails to start with a duplicate error (detectable, not corrupting). To adjust: uninstall the bundle, or uninstall the corresponding individual package, then restart.

Per-plugin security boundaries

  • The native DSH LAN listener must explicitly bind one concrete local IPv4/IPv6 address. --public-url only advertises an HTTP(S) root and grants no trust; --trusted-host only extends the accepted Host/Origin authorities.
  • Native TLS protects transport but does not authenticate the caller by itself. Plugin APIs retain a loopback fast path. A non-loopback short request may enter only when the official ctx.connection.requestRejection(req) returns undefined; that check covers Host/Origin, cross-site, cookie and API peer and must fail closed on errors. A non-loopback SSE or other long stream must additionally retain the PeerScope returned by ctx.connection.admit and bind closure to that peer lifecycle. Peer release must immediately stop broadcasts and close the stream. Before enabling LAN access in a new deployment, complete per-plugin authentication, SSE/WebSocket and real-device acceptance. A successful TLS handshake does not by itself prove that a plugin is usable.
  • Certificate chains, private keys and client trust are user-managed. The certificate SAN must cover the visited authority; never place private keys, startup tokens or session credentials in the repository, logs or public reports.
  • The stdio subprocesses of dsh-mcp-manager inherit host privileges; only configure MCP servers you trust.
  • Plugin management routes use a loopback fast path plus official identity admission. Wrong Host/Origin, cross-site requests, missing credentials, 401/403, admission errors and long-stream lifecycle failures all fail closed; unsupported methods still return 405.
  • dsh-notifier owns its configuration files; settings responses mask channel credentials, but notification text and outbound error details are not redacted and may reach logs, history and push services.
  • dsh-provider-usage keeps API keys on the host, never in the browser.
  • dsh-verify-isolated uses a temporary DSH_HOME, independent profile, port and browser instance; this is a verification boundary, not a global security guarantee.

See each plugin README for its threat model and hardening details.

Quick start

Prerequisite: DeepSeek Harness installed and dsh web running normally (for running dsh without a global install, see "Without a global dsh install" below).

Install plugins (add)

# Install everything (recommended)
dsh plugin --profile web add @wingsky-1/dsh-plugins-all

# Or install individual plugins (as needed)
dsh plugin --profile web add @wingsky-1/dsh-notifier
dsh plugin --profile web add @wingsky-1/dsh-mcp-manager

After install / uninstall / update, restart dsh web once (bundle layers are only composed at startup) for the sidebar / settings page to reflect the change.

Access and verify

Restart dsh web, open its startup URL, and check the installed plugin cards under Settings → Plugins. For notifier, send a test notification. dsh-lan-proxy is retired; read the LAN proxy retirement and migration guide before changing a LAN deployment.

Plugin list

Package What it does Docs Status
@wingsky-1/dsh-notifier Task-event notifications via browser, host toast, Bark and Webhook. README · Architecture Published
@wingsky-1/dsh-provider-usage Multi-provider usage statistics, trends and reports with custom adapters. README · Adapter guide · Architecture Published
@wingsky-1/dsh-mcp-manager Per-workspace MCP configuration and middleware-based tool access. README · Architecture · Upgrade repair Published
@wingsky-1/dsh-verify-isolated Isolated browser verification for DSH plugin development. README · Architecture Published

Configuration and maintenance

Use the plugin cards under Settings → Plugins; configuration and storage boundaries differ by plugin, so follow its README.

Uninstall plugins (remove)

dsh plugin --profile web remove @wingsky-1/dsh-notifier

Update plugins (update)

# Update a single plugin to latest
dsh plugin --profile web update @wingsky-1/dsh-notifier

# Update the bundle (aggregate + the sub-packages it pulls in) to latest
dsh plugin --profile web update @wingsky-1/dsh-plugins-all

# Update all plugins under the current profile
dsh plugin --profile web update

After install / uninstall / update, restart dsh web once (bundle layers are only composed at startup) for the sidebar / settings page to reflect the change.

Verification and troubleshooting

If a plugin is missing after installation, first restart dsh web. For duplicate entry errors, check that bundle and individual packages are not installed together.

Upgraded DSH from a pre-0.1.5 version and a historical session will not open? Sessions failing with cannot safely transform unclassified message source were hit by the host migration gate on the capability-catalog messages injected by early dsh-mcp-manager builds (the artifact is intact — it simply cannot be read). One command recovers them:

# stop dsh web before applying; logs being written cannot be safely rewritten
node scripts/maintenance/repair-mcp-catalog-sessions.mjs          # dry run: list affected sessions
node scripts/maintenance/repair-mcp-catalog-sessions.mjs --apply  # apply (backup first), then restart dsh web

See the repair guide · issue #723

Upgrade notice and repair: a historical session will not open (mcp-catalog)

Symptom: after upgrading from a pre-0.1.5 DSH, some historical sessions report in the GUI:

历史加载失败:failed to observe session "session-…":
cannot safely transform unclassified message source;
source v0 artifact remains unchanged (raw log: …/session.jsonl.zstd)(gateway/internal)

and session.v3.jsonl.zstd never appears next to the original log — every attempt fails the same way.

Cause (the session is not corrupt): dsh-mcp-manager 0.2.x and earlier wrote the catalog injection message as source.kind = "mcp-catalog", while DSH 0.1.5's session-format v2-to-v3 migration validates surface source.kind against a closed whitelist; a self-invented value is refused and the artifact is (by host design) preserved unchanged. The v3 read path itself does not validate that field, so only sessions written before the upgrade by a host that ran this plugin with catalog injection are affected; new sessions after the upgrade are fine.

Repair: current plugin versions use the host-registered generic source shape (no such message is produced any more). Artifacts already on disk are repaired in place by a one-off script that touches only source metadata, never the body or the event sequence:

# stop dsh web first: a log being written is not guaranteed safe to rewrite
node scripts/maintenance/repair-mcp-catalog-sessions.mjs          # dry run: list affected sessions
node scripts/maintenance/repair-mcp-catalog-sessions.mjs --apply  # apply: .bak-<timestamp> first, atomic write
# restart dsh web and open the session
  • Reads <DSH_HOME> by default (--home <dir> / DSH_HOME overrides it); --session <id> limits it to one session
  • Idempotent; self-checked writes (frame structure + per-line JSON + zero leftover legacy kinds); rollback = restore the .bak-<timestamp>
  • v3 sessions are repaired by default too: a v3 session can carry both kinds (created before the upgrade, written incrementally after it), and a future v3-to-v4 migration with a similar gate would repeat this outage; the rewrite only swaps source metadata, leaving v3 semantics unchanged. --legacy-only limits the run to v0/v1/v2
  • Never writes a v3 artifact: DSH still performs the migration itself for v0/v1/v2
  • Details and evidence: dsh-mcp-manager README and issue #723

Detailed reference

Capabilities in detail

  • Task-event notification center: six task-event kinds (ask / approval / completion / subagent completion / error / turn end) with dual-channel delivery — browser notifications
    • host system toasts — plus Bark / Webhook push to your phone; quiet hours with urgent exceptions, per-channel popup/sound switches (4 tones), and a host capability self-check (/diagnostics)
  • Context-cost-controlled MCP management: project-level MCP is collapsed into the four atomic tools ws_mcp_list / ws_mcp_detail / ws_mcp_search / ws_mcp_call by default, so project-level scale never balloons the context (middleware: all folds global servers into the middleware too, hot-switchable from the settings page); per-working-directory project/global config tiers let each repo carry its own MCP servers without cross-project interference
  • Extensible usage-stats framework: supports multi-provider usage stats and custom data-source adapters; covers daily usage derivation, usage trends, peak/valley countdown, and daily/weekly/monthly reports
  • Engineering-quality backing: every plugin ships smoke assertions (route fences / client contracts), plus build contract + pack checks + full gates run in CI

@wingsky-1/dsh-notifier

Task-event notification center: 6 event kinds (ask / approval / completion / subagent completion / error / turn end), dual channels (browser Notification + host system toast) plus Bark/Webhook push channels (ntfy, Gotify, self-hosted gateways); quiet hours with urgent exceptions, per-channel popup/sound switches (4 tones), and a host capability self-check (/diagnostics with availability and remediation hints)

@wingsky-1/dsh-provider-usage

Multi-provider usage stats framework (v2 adapter contract): persistent capsule + detail panel; DeepSeek official (interval-bookkeeping daily usage derivation + peak/valley countdown badge — works even without an official usage endpoint) and OpenCode Go built in; plug in any data source with a single mjs file, hot-swappable from the settings page; daily/weekly/monthly usage reports (generated via the host llm, including directory and time-of-day observations); API keys stay on the host, never reach the browser

@wingsky-1/dsh-mcp-manager

MCP server manager (stdio / streamable-http): per-working-directory project/global config tiers; all MCP collapsed into 4 atomic tools via the middleware (no model-visible mcp__ direct-call tools); workspace isolation prevents cross-project interference; configs store ${ENV} references only — no plaintext secrets on disk; runtime registration API for other plugins to inject MCP servers; optional MCP call statistics and debug mode (metadata-only, off by default)

@wingsky-1/dsh-verify-isolated

Isolated-environment browser verification skill for DSH plugin development: temp DSH_HOME + independent profile + independent port + independent browser instance (four-way isolation), one-command launch with automatic cleanup; bundled zero-dependency raw-CDP browser driver (snapshot / click / screenshot / eval, with device-viewport emulation), optional isolation audit, first-run dialogs skipped by default

Pin a version (@version)

Omitting @version installs the default latest (recommended). Only when the registry has not synced the latest yet, or the latest has issues in your environment, append @version to the package name — works for both add and update:

# Install a specific version (instead of latest)
dsh plugin --profile web add @wingsky-1/dsh-notifier@<version>

# Update to a specific version
dsh plugin --profile web update @wingsky-1/dsh-notifier@<version>

Without a global dsh install

If there is no global dsh command on the machine, use npx to run it on the fly (dsh plugin calls pnpm under the hood, so pnpm and Node.js must still be installed locally):

# Install the bundle
npx @deepseek-ai/dsh plugin --profile web add @wingsky-1/dsh-plugins-all

# Install an individual plugin (with a version pin)
npx @deepseek-ai/dsh plugin --profile web add @wingsky-1/dsh-notifier@<version>

# Uninstall / update (same shape — swap add for remove / update)
npx @deepseek-ai/dsh plugin --profile web remove @wingsky-1/dsh-notifier
npx @deepseek-ai/dsh plugin --profile web update @wingsky-1/dsh-plugins-all

npx fetches @deepseek-ai/dsh on each run. To pin it, run pnpm add -g @deepseek-ai/dsh (or npm i -g @deepseek-ai/dsh) and then use dsh directly.

Discontinued (do not install; deprecated on npm):

  • @wingsky-1/dsh-skill-explorer (skill-center / skill management) is discontinued; both the plugin package and the bundle package have been removed. A better implementation now ships on the web UI side, @linxin666/dsh-client-ui-skill-explorer (dsh-web-ui repository packages/dsh-skill-explorer), which supports symlink detection, safe handling of linked skills, and more. Use the built-in skill center in the web UI instead.
  • @wingsky-1/dsh-idle-archive (idle-conversation archiving prompt) is discontinued because the community offers more mature session lifecycle-management / archiving implementations (e.g. dsh-session-pruner).
  • @wingsky-1/dsh-subagent-model-inherit (child agents inherit parent-session model and reasoning effort) is discontinued because official dsh-subagent 0.1.2-alpha.2 natively implements resolveChildAgentOptions (child agents inherit the parent session's model / reasoning effort / output-token limit).
  • @wingsky-1/dsh-codegraph (codegraph local code-graph MCP + worktree development discipline) is discontinued: the wrapper tools are tightly coupled to the codegraph CLI version, so the maintenance cost exceeds the benefit.
  • @wingsky-1/dsh-mem0 (mem0 long-term memory system) is discontinued: environment-isolation and related defects were never resolved (#644 / #612), so it no longer meets the bar for continued maintenance.
  • @wingsky-1/dsh-web-file-preview (rewrites "open with the default application" into the built-in right-Sidebar preview) is discontinued: official dsh 0.1.6 routes delivered-file mention clicks to the built-in Sidebar preview, leaving only the card menu's explicit "open in default app" entry, which the plugin rewrote against the user's explicit intent (#840).
  • @wingsky-1/dsh-worktree-sidebar (binds a git worktree to the current session's right-Sidebar file tree) is discontinued: DSH 0.2.1-rc.2 ships a native alternative with different semantics; migration and retirement notes are in docs/migrations/worktree-sidebar.md. Only the old external adapter is retired; the optional official Git Worktrees bundle remains supported in DSH 0.2.2-rc.1, and its metadata still loads through the official mechanism.
  • @wingsky-1/dsh-lan-proxy (LAN HTTP/HTTPS/WebSocket forwarding, TLS, compression and keep-alive) is no longer independently maintained and is removed from the current source tree and bundle. Native DSH LAN/TLS covers the main entry path; the native remote mux has negotiated permessage-deflate and uses Ping/inactive termination, but the old package's path-specific WebSocket allowlist, compression bridge and half-open keep-alive policy are not promised as equivalent. Authentication, certificate management and plugin API fences also remain different. See the migration guide.
  • @wingsky-1/dsh-decision-gateway (a general advisory decision gateway with JEV as its first provider) is discontinued: there is no direct replacement. The retirement notes cover archival information and leftover cleanup.

Uninstall these packages if you installed them before:

dsh plugin --profile web remove @wingsky-1/dsh-skill-explorer
dsh plugin --profile web remove @wingsky-1/dsh-idle-archive
dsh plugin --profile web remove @wingsky-1/dsh-subagent-model-inherit
dsh plugin --profile web remove @wingsky-1/dsh-codegraph
dsh plugin --profile web remove @wingsky-1/dsh-mem0
dsh plugin --profile web remove @wingsky-1/dsh-web-file-preview
dsh plugin --profile web remove @wingsky-1/dsh-worktree-sidebar
dsh plugin --profile web remove @wingsky-1/dsh-lan-proxy
dsh plugin --profile web remove @wingsky-1/dsh-decision-gateway

dsh-memory (project long-term memory) is not included yet; it is planned.

Legacy packages (published historically, no longer distributed):

@wingsky-1/dsh-gzip and the later @wingsky-1/dsh-lan-proxy are both retired.

Historically, HTTP response compression moved from dsh-gzip into lan-proxy. Current native host compression supports none | gzip. The native remote mux WebSocket path has negotiated permessage-deflate and uses Ping/inactive termination, but this is not equivalent to lan-proxy's path-specific WebSocket compression bridge, half-open keep-alive and mobile reconnection policies. Review the migration guide and accept those differences before adopting native LAN:

dsh plugin --profile web remove @wingsky-1/dsh-gzip
dsh plugin --profile web remove @wingsky-1/dsh-lan-proxy

@wingsky-1/dsh-opencode-usage → renamed/refactored to @wingsky-1/dsh-provider-usage

Refactored into a multi-provider adapter framework (built-in OpenCode Go, custom data-source adapters supported). The patch id changed from ui-dsh-opencode-usage to ui-dsh-provider-usage and config keys were adjusted — nothing migrates automatically. Reinstall, then re-check your settings in the settings panel (e.g. apiKey, baseUrl):

dsh plugin --profile web remove @wingsky-1/dsh-opencode-usage
dsh plugin --profile web add @wingsky-1/dsh-provider-usage

Both legacy packages are marked deprecated on npm (installing them prints a migration hint).

Plugin row ID migration (v0.2.5 → the next release)

The next release uses dsh-* row IDs. Existing profiles are not rewritten automatically; stop dsh web before migrating.

From a source checkout (maintainers):

pnpm migrate:plugin-rows -- --home "$DSH_HOME"
# Review the dry-run report, then:
pnpm migrate:plugin-rows -- --home "$DSH_HOME" --apply

The tool changes only patch id fields, preserves name, disabled, config and row order, and writes a backup. Users who installed from npm without a source checkout must not run the repository script directly; follow the one-time procedure in the matching release notes. As a manual fallback, back up the profile patch first, change only id: ui-dsh-* to id: dsh-*, leave name and config untouched, and start DSH afterwards.

Related projects

  • dsh-web-mobile (npm: @dsh-external/dsh-mobile-nav) — DSH web mobile adaptation: auto-collapses the sidebar on narrow screens, opens TOC as a drawer. A lot of this project's development and debugging was done by using it remotely from a phone / tablet.
  • dsh-web-ui — A collection of DSH web UI skins. Learned many good practices from it; it is also the inspiration for DSH plugin development.
  • dsh-routing-suite / dsh-router-standard — Provides the Router Standard agent preset (task-aware reasoning-mode routing: spec / mixed / react) for selecting presets in a session.

Development and architecture

Runtime prerequisite: DSH 0.2.2-rc.1 requires Node >=24.9. Repository development and tests use native type stripping with a separate Node >=23.6 tool threshold; pnpm must be >=11.

Build / contract / test / pack commands, directory layout, and host- & client-side coding conventions all live in DEVELOPMENT.md (start at §0); contributing workflow in CONTRIBUTING.md; issue workflow in ISSUE-WORKFLOW.md. Plugin capabilities, architecture, and runtime mechanisms (SVG architecture diagrams and Mermaid sequences) are covered in the architecture documentation (in Chinese).

Plugins were reviewed before being moved into this repository (self-contained build, privacy cleanup, security hardening, complete metadata).

Contributing

See CONTRIBUTING.md: Conventional Commits, feature branch + PR workflow, pre-commit checks (sensitive info / artifact boundaries).

License

MIT

Content from the project README on GitHub ↗

Links

More in this category

View the whole category →

Community comments

Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.