端口管理器WASD258-jpg/dsh-port-manager

dsh-port-manager

DeepSeek Harness（DSH）社区插件：让 DSH web 不再死占 3080，并列出本机所有已占用端口，方便选一个空闲端口。

这是社区项目，并非 DeepSeek 官方插件，也不代表 DeepSeek 的认可或背书。

功能

- 设置 → 端口管理：在 DSH web 界面里直接查看和切换端口
- 本机端口清单：列出 TCP/UDP 监听端口、监听地址、进程名、PID，标记当前 DSH 端口
- 空闲端口推荐：根据当前占用列表推荐空闲端口，一键填入
- 热切换：切换端口不重启 dsh 进程、不丢会话，页面自动跳转到新地址
- 持久化：端口写入 $DSH_HOME/dsh-port-manager.json，重启 DSH 后继续使用新端口
- 占用保护：目标端口被占用时直接拒绝，并提示占用者进程与 PID

安装

要求：DSH web profile（@deepseek-ai/dsh-web-app），Node.js 环境为 DSH 自带或系统 Node。

1. 克隆或下载本仓库：

git clone https://github.com/WASD258-jpg/dsh-port-manager.git

2. 安装到 DSH profile 依赖目录（二选一）：

方式 A：npm 安装（推荐）

cd "$env:USERPROFILE\.dsh\profiles"
npm install @wasd258/dsh-port-manager --no-save

方式 B：从源码手动复制

$src = '.\dsh-port-manager'
$dst = "$env:USERPROFILE\.dsh\profiles\node_modules\@wasd258\dsh-port-manager"
New-Item -ItemType Directory -Force -Path "$dst\lib" | Out-Null
Copy-Item "$src\package.json" $dst -Force
Copy-Item "$src\lib\index.js","$src\lib\client.js" "$dst\lib" -Force
Copy-Item "$src\LICENSE","$src\NOTICE" $dst -Force

（Linux/macOS 把 $env:USERPROFILE\.dsh 换成 ~/.dsh；设置了 DSH_HOME 就用 $DSH_HOME。）

3. 编辑 $DSH_HOME/profiles/web/cordis.patch.yml，追加：

端口管理插件：CLI --port > 插件配置 > DSH_WEB_PORT > 3080
- id: webserver
inject: [webStartup, dshPortManager]
config:
host: !!js ctx.webStartup.host ?? '127.0.0.1'
port: !!js ctx.dshPortManager.startupPort(ctx.webStartup.port)

- insert:
- id: dsh-port-manager
name: '@wasd258/dsh-port-manager'
config:
role: provider

- id: dsh-port-manager-routes
name: '@wasd258/dsh-port-manager'
inject: [webServer, dshPortManager, subprocess, sandboxPolicy]
config:
role: routes

如果你已经手工给 webserver 行写过配置，请把 port 表达式替换为
!!js ctx.dshPortManager.startupPort(ctx.webStartup.port)，并确保
inject 同时包含 webStartup 与 dshPortManager。

4. 重启一次 DSH web（退出后重新打开即可）。设置页出现 端口管理 即安装成功。

使用

1. 打开 DSH web → 设置 → 端口管理
2. 查看“本机已占用端口”，点“重新扫描”可强制刷新
3. 点一个“推荐空闲端口”，或手动输入 1–65535 的端口（0 = 系统自动分配）
4. 点 应用新端口并跳转；等待 1 秒左右，页面自动跳到新地址

热切换期间会短暂关闭旧监听。已打开的其它标签页会断开，需要重新打开新地址。

端口优先级

| 来源 | 优先级 |
|---|---|
| dsh web --port  | 最高 |
| $DSH_HOME/dsh-port-manager.json | 高 |
| DSH_WEB_PORT 环境变量 | 中 |
| 3080 | 默认 |

插件在 UI 中切换时会把实际监听端口写回配置（输入 0 时回写系统分配到的端口）。删除 dsh-port-manager.json 即回到默认 3080。

HTTP API

host half 注册在 /api/dsh-port-manager 前缀下：

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /status | 当前端口、期望端口、URL |
| GET | /ports | 本机监听端口列表（?force=1 强制刷新） |
| POST | /apply | 切换端口，请求体 {"port": 3210} |

Windows 上端口枚举优先使用 PowerShell 的 Get-NetTCPConnection/Get-NetUDPEndpoint，失败时回退到 netstat；Linux/macOS 回退到 /proc 或 netstat。

工作原理

- lib/index.js（host half）
- role: provider：读取 dsh-port-manager.json，提供 dshPortManager 服务
- role: routes：注册 HTTP API；切换时先绑定新端口的新 server，响应返回后再关闭旧监听
- lib/client.js（web half）：向设置页注册“端口管理”卡片
- 切换不重启进程：webServer 的路由表保持不变，仅替换底层 node:http server

隐私与安全

- 插件不发起任何网络请求、不上传数据、无遥测
- 只在本地执行系统命令读取端口占用（Windows：PowerShell；其它：netstat//proc）
- 配置只写在本地 $DSH_HOME/dsh-port-manager.json
- 端口清单与热切换 API 只接受本机回环连接：即使用户把 DSH 配置为 0.0.0.0，插件 API 也不会暴露给局域网/公网
- 写操作 /apply 还要求 Content-Type: application/json 且浏览器请求必须同源，防止恶意网页跨站切换端口
- 插件不会修改 DSH 的绑定 host；host 仍由 DSH webserver 配置决定

兼容性

开发与验证环境：

- DeepSeek Harness 0.1.0-rc.6（web profile，Windows 11 + PowerShell）
- 参照提交 47f9438 的 bundle patch 接口

其它版本若有 webserver 行结构变化，只需要按上面的说明调整 cordis.patch.yml。

官方生态要求

DeepSeek 当前建议社区作者把插件放在自己的 GitHub 项目中，并为仓库添加
dsh-plugin topic 方便发现。官方仓库目前不接受
外部 PR，也没有强制社区插件仓库模板。原文见官方
CONTRIBUTING.zh.md。

许可证

MIT。cordis.patch.yml 中 webserver 端口表达式参照 DeepSeek Harness web app bundle patch 修改，原始
DeepSeek 版权和 MIT 许可声明保留在 NOTICE 中。