wyzh0117/dsh-port-manager

dsh-port-manager

dsh 原生侧边栏应用 —— 本机现在开着哪些端口、是谁占的、一句话把它处理掉。

license
node
dsh
platform
dependencies
tests

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

GitHub topics（仓库设置里加）： dsh deepseek-harness plugin sidebar port lsof port-manager

English docs: README.md。

一个纯本地、零运行时依赖的 dsh web 插件。它把自己注册成右侧栏的原生 page 类型 tab
（走 ctx.sidebarRightTabs + 带 key 的 sidebar.right.pane.tab 插槽，和官方「文件」页同一套机制），
数据由插件自己的宿主半用 lsof / ps 采集后经围栏 JSON 接口送到面板。

打开右侧栏  →  点 guide 里的 “Port Manager” 胶囊  →  端口列表

功能

1. 侧边栏入口

在右侧栏的 guide 页贡献一枚「Port Manager」胶囊（order 15，图标为插头），点开即在当前分栏
打开应用；tab 胶囊自带图标，可拖拽 / 分栏 / 浮动 / 全屏，全部由 dsh 原生机制负责。

2. 端口全貌 + 占用它的应用

每个监听一条卡片，展示：

| 字段 | 说明 |
| --- | --- |
| 端口 / 协议 | :3080、TCP（UDP 需手动开开关） |
| 绑定范围 | 仅本机（回环）/ 局域网（指定网卡）/ 所有网卡（对外暴露，橙色警示） |
| 应用 | 友好名：.app 包名、node · vite、python · http.server、Docker 容器名…… 并标注类别（Node / Python / Docker / 应用 / 服务 / 进程） |
| 进程 | PID、所属用户、已运行时长、CPU、内存 |
| 工作目录 | 进程 cwd（一行路径，用「定位」按钮打开） |
| 常见用途 | :5173 Vite dev、:5432 PostgreSQL、:7000 macOS AirPlay 接收器 这类提示 |
| 容器 | 命中 docker ps 端口映射时显示容器名与镜像 |

顶部还有：可见/总数 个端口 · N 个应用 · M 个对外 · 上次扫描时间、搜索框（端口 / 应用 /
命令 / 目录 / 容器名）、筛选（全部 / 仅本机 / 对外暴露 / 可结束）、开关（UDP、系统项）、
排序（端口 / 应用 / CPU / 内存）、自动刷新（手动 / 3s / 10s / 30s，切回 tab 时也会自动刷新一次）。

3. 每个端口下方的常用操作

| 操作 | 行为 |
| --- | --- |
| 打开 | 用系统默认浏览器打开 http://localhost:（TLS 端口走 https） |
| 复制 | 菜单：localhost:port / http://localhost:port / :port / lsof -i :port / kill  / 工作目录 / 启动命令 |
| 详情 | 展开进程详情：完整命令行（点击即复制）、cwd、父进程链、监听绑定明细、容器；内含 HTTP 探测（状态码、Server、X-Powered-By、Content-Type、页面标题、耗时） |
| 定位 | 在访达（Linux 为文件管理器）里打开该进程的工作目录 |
| 结束 | 二次确认后就地结束：先 SIGTERM，1.7 秒没退出自动升级 SIGKILL；也可直接「强制 -9」 |

右上角 ⋯ 可立即刷新，也能一键复制端口清单（Markdown 表格）或端口 + 进程列表，方便直接贴进对话里让模型排查。

安装

cd /path/to/dsh-PortManager        # 本插件目录
dsh plugin --profile web add "link:$PWD"

该命令是 pnpm 的转发器，装完会把 dsh-port-manager 追加进 profile 的 dsh.profile.bundles
（因为本包含 dsh.bundle.patch）。新增 bundle 层需要重启 dsh web；之后只改 lib/client.js
时会由客户端 HMR 触发重载，不必重启。

验证：

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 的说明里 profile 目录就是 $DSH_HOME/profiles，未设置时默认 ~/.dsh/profiles。）

卸载：

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

兼容性

平台

| 平台 | 扫描 | 打开 / 定位 | 说明 |
| --- | --- | --- | --- |
| macOS | lsof（+ ps，可选 docker ps） | open | 主要且完整验证过的目标平台。Docker 信息通过 /var/run/docker.sock 与 ~/.docker/run/docker.sock 探测 |
| Linux | lsof，缺失时回退 ss -ltnpH / ss -lunpH | xdg-open | 功能对齐，含 Docker |
| Windows | 没有 lsof，ss 又是 Linux 专有，扫描会给出警告并返回空列表 | cmd /c start、explorer | 非支持目标：扫描半没有 Windows 后端。open 另外会拒绝含 cmd 控制符的路径 |

依赖要求

| 项 | 版本 | 声明位置 |
| --- | --- | --- |
| 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 |
| 外部命令 | lsof、ps（系统自带）；可选 ss、docker | — |

本包没有 dependencies：宿主半只用 node:fs / node:http / node:https /
node:child_process / node:os / node:util 加同目录的 ./scan.js。所以插件目录不需要
node_modules（link: 安装后即可加载），也不会踩「裸 import 从插件目录解析不到」的坑。

不同版本自适应

插件被写成「遇到不完整认识的宿主 / 客户端就降级，而不是坏掉」。下表的每一行都由代码保证，
不是约定：

| 面 | 插件怎么做 | 换个版本会怎样 |
| --- | --- | --- |
| 宿主半激活 | export const inject = ["webServer"] | 在没有 web server 的 profile（headless / CLI）下插件直接不激活，而不是加载失败 |
| 可选宿主服务 | ctx.get("webRuntime")?.trustedHosts ?? [] | 服务存在时按可信主机列表放行；不存在时围栏退回「仅回环」，这是更严格的那一侧 |
| 浏览器半激活 | export const inject = ["slots", "sidebarRightTabs"] | 客户端构建里没有原生侧栏页签注册表时，浏览器半不激活而不是抛错；宿主半与它的接口照常工作 |
| 插槽契约 | ctx.slots.inject(name, () => ctx.slots.register(...))，包在 ctx.effect 里 | 插槽注册是响应式且可回收的：插槽晚一点出现、或某个版本改了贡献位置，都是「插槽在时就注册，插槽没了就拆掉」 |
| 设计 token | 每个 token 都写成 var(--dsw-alias-, ) | token 被改名或缺失时降级成可读的硬编码颜色，而不是整块面板失去样式；明暗主题自动跟随宿主 |
| 模块表 | bundle 只 require("react") | 图标全部内联 SVG、样式走一个 。没有裸 import 就既不需要 node_modules 解析，也不会以 “missed the module table” 炸掉整个 bundle |
| 包管理器 | 全仓库无依赖、node_modules 被 gitignore | link:、tarball、npm 装到的都是同一份字节，不需要任何构建步骤 |
| 命令可用性 | POSIX 用 which、Windows 用 where；lsof 缺失回退 ss | 扫描器缺失时在面板上给一条 warnings，永不崩溃 |

架构

lib/
├── index.js    宿主半：零依赖对象插件（export apply/inject），注册 /port-manager/api 围栏路由
├── scan.js     扫描与解析：lsof / ps / ss / docker ps → 结构化端口记录（纯函数可单测）
└── client.js   浏览器半：window.__ModuleLoader__ bundle，注册原生 tab 类型 + 面板 UI
test/           node --test：解析单测、路由单测、bundle 注册与真实渲染断言、真实 cordis 集成
scripts/        integration-scenario.mjs：集成场景脚本（真 cordis + 真 webServer + 真 HTTP）

数据流：面板 fetch("/port-manager/api/") → 宿主半 execFile 调系统命令 → 解析成
端口记录 → JSON 信封返回。宿主半带 1.2s 扫描缓存与并发合并，自动刷新不会把 lsof 打满。

| 接口 | 用途 |
| --- | --- |
| list | 扫描端口（includeUdp / force / docker 可选） |
| detail | 单进程详情（命令行、cwd、父进程链、它占用的端口） |
| kill | 结束进程（先校验「它确实还在监听这个端口」） |
| open | 系统浏览器打开 |
| reveal | 文件管理器打开目录 |
| probe | 本机 HTTP(S) 探测 |

安全边界

kill 是这个插件的特权面，因此：

1. 浏览器围栏：/port-manager/api 是插件自己注册的裸 node:http 路由，不经过 dsh 的
/api 网关，没有自带的 Host/Origin 校验与鉴权 Cookie。所以宿主半复刻了与网关一致的
loopback / trustedHosts / 同源 / sec-fetch-site 检查，非可信来源一律 403。
2. 结束前再校验：列表可能是几秒前扫出来的，PID 可能已被系统复用。kill 会重新用
lsof -nP -iTCP: -sTCP:LISTEN -Fpc 确认该 PID 此刻仍在监听这个端口，并用 ps 核对 uid。
3. 保护策略在服务端强制（不是只把按钮置灰）：非当前用户、系统账号
（root / _windowserver / …）、系统目录里的可执行文件（/System、/usr/libexec…）、
macOS 的 ControlCenter（AirPlay 占着 5000/7000）、DSH 宿主所在进程链
（插件就住在宿主进程里，结束了当前界面也会一起没 —— 按 process.pid 的祖先链判定，
不信任请求头里的 Host）、以及请求来源指向的 DSH 端口，全部会被 kill 接口拒绝（403
refused），UI 上同时显示锁图标与原因。
4. 受保护/不可结束的条目在 UI 上带锁图标，refused / not-listening 等错误会在面板内以
toast 原文回显，不会静默失败。

开发

node --test        # 32 个用例：解析 / 路由 / 围栏 / bundle 注册 / 组件渲染 / 真实 cordis 集成
node --check lib/index.js && node --check lib/scan.js && node --check lib/client.js

test/host.test.mjs 用假 ctx 抓路由 handler 打假 req/res；test/integration.test.mjs（配
scripts/integration-scenario.mjs）更进一步：它在子进程里起真的 cordis Context + 真的
dsh-host-webserver，把插件 apply 挂进真实服务树，再用真实 HTTP 请求验证围栏（异源 / 跨站
403、同源放行）、方法分发与真实扫描结果。

test/client.test.mjs 用假的 window.__ModuleLoader__ + 假 ctx 装载 bundle，并用
react-dom/server 把面板真渲染成 HTML（React 从本机 profile 或兄弟插件的 node_modules
里按路径解析；找不到就跳过渲染断言），因此端口卡片是真的渲染成 HTML 后被断言的。

改 UI 只动 lib/client.js，保存后由 @deepseek-ai/dsh-client-hmr 推到已打开的页面；改宿主半
（路由/扫描）需要重启 dsh web，或把 insert 行临时写进 profile 的 cordis.patch.yml
（该文件是 live 重载的）。

已知限制

- UDP 没有 LISTEN 状态：默认只看 TCP，UDP 需要手动打开开关（lsof -nP -iUDP）。
- 别人的进程只能看不能杀：非当前用户的监听会列出但按钮禁用（kill 也会 403）。
- 工作目录读不到就没有「定位」：同用户进程一般可读，系统进程不可读。
- 端口清单是快照：没有 fs 事件，需要自动刷新或手动刷新；扫描一次约 0.6s（含 docker 查询）。
- 面板很窄时（。

提交 PR 前请先跑：

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

请守住让它「不需要构建步骤即可安装」的两条约束：

- 宿主半（lib/index.js、lib/scan.js）除 node: 与 ./scan.js 外不 import 任何东西；
- 浏览器半（lib/client.js）除 react 外不从模块表 require 任何东西。

给任一半加一个 @deepseek-ai/ 的裸 import，会分别破坏 link: 安装和浏览器 bundle。

更新日志

0.1.0

- 原生右侧栏 page 类型 tab：guide 胶囊、带 key 的 sidebar.right.pane.tab 主体，以及带图标的
tab 标题。
- 基于 lsof（缺失回退 ss）+ ps 富化的端口扫描，Docker 容器映射、常见端口提示、
搜索 / 筛选 / 排序 / 自动刷新。
- 每个端口的打开 / 复制 / 详情（含 HTTP 探测）/ 定位 / 结束，SIGTERM → SIGKILL 升级与
服务端保护策略。
- 32 个用例，含一套真 cordis、真 HTTP 的集成场景。

致谢

基于 @deepseek-ai/dsh 0.1.5-rc. 的插件 API 开发，沿用官方侧栏页面的同一套约定。感谢
dsh 插件社区里那些参考实现，它们让原生 tab 的接线方式变得可读。

许可

MIT © 2026 dsh-port-manager contributors

如果这个插件帮你省下了一次 lsof，一颗 star 能让更多人找到它。

Star History Chart