dsh-wsl-kit

One line: DeepSeek Harness agent in WSL, chat in a Windows browser — install this kit when paths, proxy, clipboard, and “open that file” must cross the OS boundary.

This is a meta-repo (docs + install script + cordis.patch.yml). It does not ship plugin runtimes. Each plugin repo ships a homepage README.md (often Chinese-first for newer plugins) plus README.en.md / README.zh.md as needed.

中文说明 → README.zh.md

How the pieces fit

The kit is not a runtime. install.sh loads Daily / GitHub / LLM / Full plugins into the dsh web profile. Chat stays on Windows; the agent and tools stay in WSL. A second tier of Linux/local capability plugins (inference, search, media, read-only DevOps, …) is not in install.sh — use link-linux-plugins.sh or dsh plugin add as needed. IM / Obsidian / Jev are likewise off install.sh.

flowchart TB
  subgraph win [Windows]
    browser["Browser :3081/?token="]
    host["Clipboard / Explorer / default browser"]
    vault["Obsidian vault (NTFS)"]
    localLLM["Ollama / llama.cpp / vLLM"]
  end
  subgraph wslbox [WSL]
    relay["port relay"]
    dsh["dsh web :3080"]
    subgraph kitPlugins ["install.sh suites · package.json bundle (npm-gated)"]
      daily["Daily: env net fetch open clipboard path browser launch"]
      guards["repeat-stop + tool-budget"]
      more["GitHub / LLM / Full doctors"]
    end
    subgraph winread [Windows read-only diagnostics · not in install.sh]
      wdiag["defender · eventlog · perf · power · registry · service"]
    end
    revive["dsh-wsl-revive — installs and reports the UI resident"]
    subgraph linuxOpt [Optional Linux local · not in install.sh]
      infer["ollama · llamacpp · vllm · vecmem"]
      media["media · search · secret · struct"]
      devops["git · tmux · compose · k8s · helm · terraform · …"]
      desk["playwright · mail · cal · pkg · rclone · db · glab"]
    end
    im["dsh-wsl-im — optional"]
    obsidian["dsh-wsl-obsidian — optional"]
    jev["dsh-wsl-jev — optional"]
  end
  api["DeepSeek API"]
  chats["Feishu / WeCom / DingTalk / QQ / Slack / Discord / Telegram"]

  browser --> relay --> dsh
  dsh --> kitPlugins
  dsh --> linuxOpt
  dsh --> api
  linuxOpt --> localLLM
  kitPlugins --> host
  chats --> im --> dsh
  obsidian --> vault
  dsh --> obsidian
  dsh --> jev

The bundle package, and why install.sh is still the way in

There is a package.json here that describes the same 31 plugins as one bundle (dsh.bundle.patch → cordis.patch.yml, which carries their config). It does not install today, and the reason is worth knowing before you try it:

pnpm add github:173787247/dsh-wsl-kit
  → ERR_PNPM_EXOTIC_SUBDEP: Exotic dependency "dsh-wsl-tray-launcher" (resolved via
    git-repository) is not allowed in subdependencies when blockExoticSubdeps is enabled

pnpm refuses a git-resolved dependency inside another git-resolved package. A github: bundle therefore cannot depend on github: plugins — so the bundle only becomes installable once the plugins are on npm, at which point its dependencies become ordinary version ranges.

Until then: use install.sh (or dsh plugin add per plugin). The package.json is the description of the destination, not a second route to it.

Plugin versions

Three plugins install under a different name than their repository. npm already had dsh-wsl-tray, dsh-wsl-expose and dsh-wsl-workspace taken by other authors' plugins, so these three publish under dsh-wsl-tray-launcher, dsh-wsl-portproxy and dsh-wsl-workspace-check. The repositories are unchanged — only dsh plugin add needs the package name. Everything else on this page links to the repository, which is what you clone or read.

Sibling checkout versions on 2026-09-18. Floors enforced by scripts/check-plugin-versions.sh are the minimum, not this snapshot.

Local dsh line: 0.2.1-rc.5 (npm, 2026-10-30). The 0.2.1 line carries the web UI; scripts still assume dsh ≥0.1.2.

Daily

GitHub add-on and optional

Full-set extras

Shared helper dsh-wsl-common 0.1.0 is a library, not a KIT_SET entry.

Compatibility (2026-09)

⚠️ Breaking changes in dsh 0.2.1-alpha.2 (released 2026-10-09)

These hit things in this kit. Read this before upgrading, not after the UI stops working.

What you gain: the working_directory tool, shared AGENTS.md from an agents directory (DSH_AGENTS_HOME), an experimental Git Worktrees plugin, session state-record APIs, Web binding to a chosen address with native HTTPS, pi-ai 1.0.2.

One habit: read the release notes' "Other changes" section before upgrading — every breaking change lives there. We upgraded first and read afterwards, and paid for it with a night of debugging.

⚠️ Breaking changes in dsh 0.2.1-alpha.3 and 0.2.1-alpha.4

Read from the upstream release notes on 2026-10-16, after upgrading to alpha.4 without reading them first. The one change that mattered was a single line under Other changes.

How to check the second row for yourself

grep 'disabling profile plugin row' /tmp/dsh-web.log     # a plugin was disabled at startup

The log is appended across restarts, so count the lines before upgrading and compare afterwards — a bare grep -c reports every past start as well.

⚠️ dsh 0.2.1-alpha.5 (released 2026-10-16)

No breaking change. Its "Other changes" adds one slot, conversation.input.model.label, for plugins that relabel the composer's model selector. Nothing in this kit is affected.

Recorded so the next upgrade does not have to re-derive it — and because the two releases before it did break things.

Upgrading, and what keeps the UI reachable

Use scripts/upgrade-dsh-full.sh; it reads the target release's notes before it installs anything, and docs/UPGRADE.zh.md describes the layers and the traps.

Two scripts exist so a broken UI does not need a person at the keyboard:

Plugin README policy### Plugin README policy

• This Compatibility section is the suite matrix. Each plugin README has a matching Compatibility table (EN + ZH): minimum dsh ≥0.1.2, pointer here for latest verified, kit set, and notes that cloud Flash / Agent Teams are not owned by WSL plugins.
• When dsh ships a new line (e.g. 0.1.5 GA or 0.1.6), update this kit table first, then refresh plugin “currently …” lines (or re-run the suite doc sync). Do not invent per-plugin “verified” dates without a smoke pass.
• API-sensitive plugins (net, fetch, port, expose, tray, hostsvc) carry an extra Scope paragraph; thinner Daily tools keep the shared table only.

No kit code change is required solely for V4.1 Flash — update model ids in settings if you still default to retired names.

60-second start (recommended: Daily set)

Prereq: dsh works inside WSL (profile usually web). Prefer 0.2.1-rc.5 or newer from the same train.

curl -fsSL https://raw.githubusercontent.com/173787247/dsh-wsl-kit/master/install.sh \
  | KIT_SET=daily bash

Then:

1. Restart via scripts/restart-dsh-web.sh (starts dsh on :3080 and the Windows relay on :3081)
2. In Windows open the URL printed by restart-dsh-web.sh (dsh ≥0.1.2 includes ?token=; bare :3081 is 401. Not :3080). Token is also written to /tmp/dsh-ui-url (WSL).
3. Open a new session (old sessions keep the old toolset)
4. Optionally merge cordis.patch.yml into your profile (a later plugin config replaces the whole object — restate every key you still need)

From a local clone: KIT_SET=daily bash install.sh

What restart-dsh-web.sh loads

• NODE_USE_ENV_PROXY=1, OLLAMA_API_KEY default ollama
• NO_PROXY=127.0.0.1,localhost only (do not inherit Clash RFC1918 NO_PROXY globs — they make Node skip the proxy and timeout on api.deepseek.com)
• Optional: source "$HOME/.dsh/dsh-wsl-github.env" yourself before start when using GitHub App plugins

What you get immediately

Daily = table above + win_launch + dsh-repeat-stop + dsh-tool-budget + dsh-wsl-fetch.

Smoke: in a new session ask “run net_doctor” and “copy this path to the Windows clipboard”. Prefer model deepseek-flash for cloud; keep Agent Teams off for first smoke.

Install sets (short list)

Do not start with Full — get Daily working, then add plugins for specific pains.

Desktop is a separate set on purpose. dsh-wsl-wininput types and clicks, dsh-wsl-winctl moves and closes windows; dsh-wsl-uia and dsh-wsl-winshot are the observation half of the same pair. That is a different power level from reading counters and an event log, so full never pulls it in.

Optional: GitHub day

GitHub from WSL is credentials + API + browser open + proxy — not one mega-plugin. After KIT_SET=github:

1. Create the App per dsh-wsl-github (read-only Metadata / PRs / Actions; webhooks off)
2. Before start: source "$HOME/.dsh/dsh-wsl-github.env"
3. New session → github_app_hint / github_repo_status; never paste PEM / PAT into chat

Node 24 + Windows proxy

export HTTP_PROXY=http://127.0.0.1:7890   # or Clash mixed port, e.g. 16006
export HTTPS_PROXY=http://127.0.0.1:7890
export NODE_USE_ENV_PROXY=1
# Prefer restart-dsh-web.sh so NO_PROXY stays loopback-only

Still failing → ask the agent to run net_doctor.

• API works, web_fetch fails → dsh-wsl-fetch (Daily already installs it).
• Third-party Workers / Cloudflare 403 (1010) via Clash → add a DIRECT rule for that host (plugin cannot override site WAF).

Local OpenAI-compatible backends on Windows: add dsh-wsl-hostsvc, run host_reach, merge examples/local-llm-providers.settings.yaml.

Troubleshooting

Connectivity, UI token 401, Ollama ctx, and fetch faults: docs/TROUBLESHOOTING.md (中文: TROUBLESHOOTING.zh.md).

Order of play: host_reach → net_doctor → dns_doctor → clock_doctor → workspace/mnt → expose (LAN only).

Maintaining this kit

Which file is generated and which is handwritten, what each of the thirty-two scripts does and when to run it, and the invariants that keep twenty-six plugin copies from drifting: docs/MAINTENANCE.zh.md.

Full catalog (reference)

Daily (KIT_SET=daily)

GitHub add-ons

Doctors / UI / tier 2

Related: session-contract. Awesome listing snippet: awesome-wsl-kit.md.

Awesome status (2026-09-24): ~35 Daily/tool plugins on awesome main (including jev / obsidian). The 22 Linux-optional plugins are in PRs – (CI green, awaiting merge). Queue: docs/AWESOME_QUEUE.zh.md. This kit meta-repo is not submitted to awesome — install via this repo / install.sh.

Beyond the kit

Do not reopen work that already shipped (fetch 0.1.2, obscura, version floors, 401 health, hostsvc apiReady, :3081 token relay). A new repo only for a new product. DingTalk does not get one.

Plan (2026-09-24): Keep Daily stable; ship new products as optional Linux/local plugins (Chinese homepage + README.en.md; read-only / double-gated by default). Full catalog + batch link → docs/OPTIONAL_PLUGINS.md · bash scripts/link-linux-plugins.sh. Awesome queue → docs/AWESOME_QUEUE.zh.md.

Security

• Plugins share your Harness permissions (files, network, Windows via PowerShell/cmd).
• win_launch is allowlisted; cred_hint / GitHub App never dump secrets into chat.
• win_notify blocks on a MessageBox — keep text short and secret-free.
• Keep *.env under ~/.dsh/ at chmod 600; never commit API keys.

Topics

deepseek-harness · dsh-plugin · wsl · windows · github-app

License

MIT — same as the individual plugins.