dsh-port-manager

English | 中文

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 依赖目录：

   $src = '.\dsh-port-manager'
   $dst = "$env:USERPROFILE\.dsh\profiles\node_modules\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: 'dsh-port-manager'
         config:
           role: provider
   
       - id: dsh-port-manager-routes
         name: '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 <n> | 最高 | | $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 中。