Suggested GitHub topics: dsh deepseek-harness plugin sidebar port lsof port-manager

中文文档见 README.zh.md。

A local-only, zero-runtime-dependency plugin for the DSH web client. It registers itself as a native right-sidebar page tab (through ctx.sidebarRightTabs + the keyed sidebar.right.pane.tab slot — the same mechanism the shipped Files page uses), and the data it renders is collected by its own host half with lsof / ps and delivered over a fenced JSON API.

Open the right sidebar  →  click the “Port Manager” capsule in the guide  →  the port list

Features

Language note. The panel UI ships in Simplified Chinese only — there is no i18n layer yet. This README uses English glosses for its labels, and gives the actual caption in parentheses the first time a control is named.

1. Sidebar entry

One guide capsule (order 15, plug glyph) in the right sidebar's guide page. Clicking it opens the app in the active pane; the tab chip carries its own icon, and splitting, floating and fullscreen are handled by the native docking kit.

2. Every listening port, and the app behind it

One card per listener:

The toolbar carries: the visible/total ports · N apps · M exposed · last scan time summary, a search box (port / app / command / directory / container name), filters (全部 all / 仅本机 loopback / 对外暴露 exposed / 可结束 killable), toggles (UDP, system entries), sorting (port / app / CPU / memory) and auto-refresh (manual / 3s / 10s / 30s, plus one refresh whenever the tab regains focus).

3. Per-port actions

The ⋯ menu refreshes the list immediately (立即刷新) and copies the whole port list as a Markdown table, or as :port app (pid) lines — handy for pasting straight into a conversation and asking a model to look at it.

Install

cd /path/to/dsh-PortManager        # this plugin directory
dsh plugin --profile web add "link:$PWD"

The command is a thin pnpm forwarder. Because this package declares dsh.bundle.patch, the package name is appended to the profile's dsh.profile.bundles. A new bundle layer needs a dsh web restart; afterwards, edits to lib/client.js alone are pushed to an open page by the client HMR driver, with no restart.

Verify the install:

node -e 'const h=process.env.DSH_HOME??process.env.HOME+"/.dsh";const p=require(h+"/profiles/web/package.json");console.log(p.dependencies["dsh-port-manager"], p.dsh.profile.bundles)'

(dsh --profile documents the profile directory as $DSH_HOME/profiles, which defaults to ~/.dsh/profiles.)

Uninstall:

dsh plugin --profile web remove dsh-port-manager

Compatibility

Platforms

Requirements

There are no dependencies: the host half imports only node:fs / node:http / node:https / node:child_process / node:os / node:util plus its sibling ./scan.js, so the plugin directory needs no node_modules and works immediately after a link: install.

Version adaptivity

The plugin is written so that a host or client it does not fully recognise degrades instead of breaking. Each row below is enforced by code, not by convention:

Architecture

lib/
├── index.js     host half — zero-dependency object plugin (export apply/inject), fenced /port-manager/api route
├── scan.js      scanning — lsof / ps / ss / docker ps → structured port records (pure, unit-tested)
└── client.js    browser half — a window.__ModuleLoader__ bundle registering the tab type + panel UI
test/            node --test: parsers, route + fence, bundle registration, real rendering assertions
scripts/         integration-scenario.mjs — real cordis Context + real dsh-host-webserver over real HTTP

The panel fetches /port-manager/api/<method>; the host half uses execFile, parses the output into port records and wraps them in a JSON envelope. Scans are cached for 1.2s with in-flight coalescing, so an auto-refresh interval never hammers lsof.

Security boundary

kill is this plugin's privileged surface, so:

1. Browser fence. /port-manager/api is a raw node:http route registered by the plugin — it bypasses DSH's /api gateway and therefore does not inherit its Host/Origin check or auth cookie. The host half re-implements the same loopback / trustedHosts / same-origin / sec-fetch-site checks, and answers 403 to anything untrusted.
2. Re-verified before terminating. The list may be seconds old and PIDs get reused. kill asks lsof -nP -iTCP:<port> -sTCP:LISTEN -Fpc again to confirm that this PID is listening on this port right now, and cross-checks the uid with ps.
3. The protection policy is enforced server-side — a greyed-out button is not a security boundary. Refused (403 refused) are: other users' processes, system accounts (root / _windowserver / …), executables under system directories (/System, /usr/libexec, …), macOS ControlCenter (AirPlay holds 5000/7000), the DSH host's own process chain — the plugin lives inside the host process, so killing an ancestor would take the UI down with it; this is decided from process.pid's ancestry, never from the request's Host header — and the DSH port the request itself came from.
4. Protected and unkillable entries carry a lock icon in the UI, and errors such as refused / not-listening are echoed verbatim as a toast in the panel. Nothing fails silently.

Development

node --test        # 32 cases: parsers / route / fence / bundle registration / component rendering / real cordis integration
node --check lib/index.js && node --check lib/scan.js && node --check lib/client.js

test/host.test.mjs drives the route handler with a fake ctx and fake req/res. test/integration.test.mjs (with scripts/integration-scenario.mjs) goes further: it boots a real cordis Context and a real dsh-host-webserver in a child process, mounts the plugin's apply into the live service tree, and verifies the fence (cross-origin 403, same-origin pass), method dispatch and real scan results over real HTTP.

test/client.test.mjs loads the bundle against a fake window.__ModuleLoader__ and a fake ctx, then renders the panel to HTML with react-dom/server (React is resolved by path from the local profile or a sibling plugin's node_modules; the rendering assertions are skipped when it cannot be found). The port cards really are rendered to HTML and then asserted on.

To change the UI, edit lib/client.js only — saving pushes the change into open pages through @deepseek-ai/dsh-client-hmr. Changing the host half (routes / scanning) needs a dsh web restart, or temporarily adding the insert row to the profile's cordis.patch.yml (that file is live-reloaded).

Known limitations

• UDP has no LISTEN state — only TCP is scanned by default; UDP needs the toggle (lsof -nP -iUDP).
• Other users' processes are visible but not killable — they are listed, the buttons are disabled, and kill answers 403.
• No cwd means no “Reveal” — readable for same-user processes, not for system ones.
• The list is a snapshot — there is no filesystem event feed, so it relies on auto-refresh or a manual refresh. One scan costs roughly 0.6s including the Docker query.
• Narrow panels (under ~320px) wrap the action buttons; that is the native panel width, so drag the panel wider or go fullscreen.

Contributing

Issues and pull requests are welcome at https://github.com/wyzh0117/dsh-port-manager/issues.

Before opening a PR:

node --test && node --check lib/index.js && node --check lib/scan.js && node --check lib/client.js

Please keep the two constraints that make this plugin installable without a build step:

• the host half (lib/index.js, lib/scan.js) imports nothing but node:* and ./scan.js;
• the browser half (lib/client.js) requires nothing from the module table except react.

Adding a bare import of an @deepseek-ai/* package to either half breaks a link: install and the browser bundle respectively.

Changelog

0.1.0

• Native right-sidebar page tab: guide capsule, keyed sidebar.right.pane.tab body, and a tab title with its own icon.
• Port scanning through lsof (with an ss fallback) plus ps enrichment, Docker container mapping, well-known-port hints, search / filters / sorting / auto-refresh.
• Per-port Open / Copy / Details (with HTTP probe) / Reveal / Kill, with SIGTERM → SIGKILL escalation and a server-side protection policy.
• 32 tests, including a real-cordis integration scenario over real HTTP.

Acknowledgements

Built against the DSH plugin API of @deepseek-ai/dsh 0.1.5-rc.*, following the same conventions as the shipped sidebar pages. Thanks to the DSH plugin community for the reference implementations that made the native-tab wiring legible.

License

MIT © 2026 dsh-port-manager contributors

_{If this plugin saved you a lsof lookup, a star helps other people find it.}