dsh-port-manager

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# dsh-port-manager

**A native DSH sidebar app** — which ports this machine is listening on, which app owns each one, and one click to deal with it.

[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D20-3c873a.svg)](https://nodejs.org)
[![dsh](https://img.shields.io/badge/dsh-%5E0.1.5--rc.1-6b4fbb.svg)](#compatibility)
[![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)](#platforms)
[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](./package.json)
[![tests](https://img.shields.io/badge/tests-node%3Atest-6da55f.svg)](./test)

`dsh` · `deepseek-harness` · `plugin` · `sidebar` · `port` · `lsof` · `port-manager`

> **Suggested GitHub topics:** `dsh` `deepseek-harness` `plugin` `sidebar` `port` `lsof` `port-manager`
>
> 中文文档见 [README.zh.md](./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:

| Field | What it shows |
| --- | --- |
| Port / protocol | `:3080`, TCP (UDP behind a toggle) |
| Bind scope | **loopback only** / **LAN** (a named interface) / **all interfaces** (exposed — orange warning) |
| App | Friendly name: `.app` bundle name, `node · vite`, `python · http.server`, Docker container… plus a category badge (Node / Python / Docker / App / Service / Process) |
| Process | PID, owning user, uptime, CPU, memory |
| Working directory | The process cwd, on one line (open it from the **定位 / Reveal** button) |
| Well-known port | Hints such as `:5173 Vite dev`, `:5432 PostgreSQL` |
| Container | Container name and image when a `docker ps` port mapping matches |

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

| Action | Behaviour |
| --- | --- |
| **打开 / Open** | Opens `http://localhost:` in the system browser (TLS ports go to https) |
| **复制 / Copy** | Menu: `localhost:port` / `http://localhost:port` / `:port` / `lsof -i :port` / `kill ` / working directory / launch command |
| **详情 / Details** | Expands the process view: full command line (click to copy), cwd, parent chain, every listening binding, container — plus an **HTTP probe** reporting status code, `Server`, `X-Powered-By`, `Content-Type`, page title and latency |
| **定位 / Reveal** | Opens the process working directory in Finder (the file manager on Linux) |
| **结束 / Kill** | After a second confirmation: `SIGTERM` first, escalating to `SIGKILL` automatically if the process is still alive 1.7s later. A direct force `-9` is also available |

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

```bash
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:

```bash
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:

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

---

## Compatibility

### Platforms

| Platform | Scanning | Open / Reveal | Notes |
| --- | --- | --- | --- |
| **macOS** | `lsof` (+ `ps`, optional `docker ps`) | `open` | The primary, fully exercised target. Docker enrichment is detected through `/var/run/docker.sock` and `~/.docker/run/docker.sock` |
| **Linux** | `lsof`, falling back to `ss -ltnpH` / `ss -lunpH` when `lsof` is absent | `xdg-open` | Full feature parity, including Docker |
| **Windows** | `lsof` is not present and `ss` is Linux-only, so scanning reports a warning and an empty list | `cmd /c start`, `explorer` | Not a supported target: the scanning half has no Windows backend. `open` additionally rejects paths containing characters `cmd` would interpret |

### Requirements

| Requirement | Version | Where it is declared |
| --- | --- | --- |
| DSH | `^0.1.5-rc.1` | `dsh.plugin.json` → `engines.dsh` |
| Node.js | `>= 20` | `package.json` → `engines.node` |
| `@deepseek-ai/cordis` | `^4.0.1` (peer) | `package.json` → `peerDependencies` |
| React | `^18.2.0` (peer) | `package.json` → `peerDependencies` |
| External commands | `lsof`, `ps` (system-provided); optional `ss`, `docker` | — |

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:

| Surface | What the plugin does | What you get on a different version |
| --- | --- | --- |
| Host half activation | `export const inject = ["webServer"]` | On profiles with no web server (headless / CLI) the plugin simply stays dormant instead of failing to load |
| Optional host service | `ctx.get("webRuntime")?.trustedHosts ?? []` | Trusted hosts are honoured when the service exists; without it the request fence falls back to loopback-only, which is the stricter default |
| Client half activation | `export const inject = ["slots", "sidebarRightTabs"]` | A client build without the native sidebar-tab registry leaves the browser half inactive rather than throwing; the host half and its API keep working |
| Slot contract | `ctx.slots.inject(name, () => ctx.slots.register(...))` via `ctx.effect` | Slot registration is reactive and disposable: if a slot appears later, or a version renames where it is contributed, the tab registers when the slot exists and is torn down when it goes away |
| Design tokens | Every token is read as `var(--dsw-alias-*, )` | A renamed or missing token degrades to a readable hard-coded colour instead of an unstyled panel, and light/dark themes follow the host automatically |
| Module table | The bundle `require`s **only** `react` | Icons are inline SVG and styles ship through one `