dsh-fixed-port-bridge

@ljwei-stak/dsh-fixed-port-bridge

给 DeepSeek Harness（DSH）一个固定的本地端口。

DSH 桌面端的启动器把 --port 0 写死在代码里，所以它的 web 端口每次启动都由操作系统随机分配（实测同一台机器上依次是 59507 → 65361 → 54266 → 58834）。任何"记住 DSH 端口"的客户端——桌宠、IDE 插件、浏览器书签、反向代理——每次重启都要改一遍。

这个插件在 DSH 进程内监听一个你在配置里指定的端口，把连接原样转发给宿主当次真实绑定的端口。客户端从此只认一个地址。

原理

你的客户端 ──固定端口──► 本插件（跑在 DSH 进程里）──► DSH 真实端口（随机）

• 通过 ctx.inject(['webServer']) 拿到宿主服务，惰性读取它真实绑定的 listenedPort
• net.createServer 在 config.port 上监听，每个连接用 socket.pipe 原样转发
• 因为生命周期跟着 DSH 走，DSH 起来它就在，不需要独立守护进程、不需要开机自启、不需要扫描端口

安装

1. 插件市场（桌面端推荐）

在 DSH 的插件市场里，来源填本仓库地址：

https://github.com/Alice-Marx/dsh-fixed-port-bridge

2. npm（web profile）

dsh plugin add @ljwei-stak/dsh-fixed-port-bridge

桌面端的 desktop profile 由 Electron 应用独占管理，dsh plugin 命令行按设计拒绝修改它，所以桌面端请走插件市场。

3. 手工放置

把包目录放进 /node_modules/@ljwei-stak/dsh-fixed-port-bridge，并在该 profile 的 package.json 里把包名追加进 dsh.profile.bundles，然后重启 DSH。

配置

装好之后：在 DSH 设置里直接改（不用重启）

装好并重启一次 DSH 之后，设置里会多出「固定端口」板块（settings.section）。在里面填端口、保存即可 —— 端口当场热切到新值，不用重启 DSH，桌宠/脚本那边同步改成新端口就行。

端口取值优先级（先到先得）：

1. /.dsh-fixed-port-bridge.json —— 在设置面板里保存端口时写下的那份
2. 插件自带 cordis.patch.yml 里的 config.port
3. 内置默认 19387

一旦落过盘，再改 yml 就不生效。 只要第 1 项存在，它就一直盖住 config.port。想交回 yml 控制：删掉 /.dsh-fixed-port-bridge.json 再重启 DSH。改 yml 的人要知道这一条，否则会遇到"改了配置没反应"。

首次安装：yml 里的默认值

cordis.patch.yml 依旧是首次安装时的端口来源（还没落过盘时，它就是唯一生效的配置）：

- insert:
    - id: fixed-port-bridge
      name: "@ljwei-stak/dsh-fixed-port-bridge"
      required: false
      config:
        port: 19387      # ← 首次安装的默认值

改这一处需要重启 DSH。记得同时把客户端里的地址改成新端口 —— 端口的两半分别在这两处。

设置面板背后的两个端点

浏览器半不读也不写 yml，它只调宿主半挂在 web 面上的两个 exact 路由（同源，走 DSH 当次真实端口或固定端口都行）：

方法 · 路径 · 作用 GET · /coopanion/fixed-port-bridge/state · 读状态：{ ok, port, source, listening, hostPort, canPersist, configPath } POST · /coopanion/fixed-port-bridge/port · 热切端口并落盘，body 为 { "port": 19387 }，成功回 { ok: true, port, previousPort }

source 取值：file（来自状态文件）或 config（来自 config.port，尚未落过盘）。

错误码：

HTTP · error · 含义 403 · forbidden · Host 头不是 127.0.0.1 / localhost，挡跨站请求 405 · method-not-allowed · 对 /port 用了非 POST 400 · bad-json · 请求体不是合法 JSON；body 超过 4KB 也落这个码（超限即拒，不会回 413） 400 · invalid-port · port 不是 1024–65535 之间的整数 409 · unchanged · 新端口和当前正在监听的一致，什么都没做 400 · port-in-use · 新端口绑不上，旧端口继续监听（先 listen 成功才关旧链路） 400 · persist-failed · 端口已经切过去了，但写状态文件失败 —— 重启后会回退

注意这两个端点挂在宿主真实的 web 面上，所以固定端口上暴露的仍然是整个 web 面（含 GUI），见「已知边界」第 1 条 —— 本插件只做整端口 TCP 直通，不做路径过滤。

验证

# 端口有人监听，且返回 DSH 的状态
curl -s http://127.0.0.1:19387/<your-client-path>

# 确认是本插件在监听：这个 PID 应该等于 DSH 主进程的 PID
netstat -ano | findstr :19387
tasklist | findstr "DeepSeek Harness"

如果固定端口的监听 PID 是一个独立的 node.exe，说明占着端口的是别的进程（例如你自己搭的中继），本插件会因为 EADDRINUSE 记一条 warn 然后让位——宿主不会受影响。

自测

npm test

preflight.mjs 会用一个桩宿主启动插件、伪造一个上游服务，验证"能导入 / 能监听 / 能转发 / 换 config.port 真的换端口"。它不触碰真实的 DSH。

兼容性

• 不声明 engines.dsh，也不声明 @deepseek-ai/* peer 依赖 —— 这样 DSH 的 evaluatePluginCompatibility 不会因版本范围把你拦在门外。
• 行上带 required: false：插件运行时抛错时宿主跳过它，而不是让整个 DSH 起不来。
• apply 全程 try/catch，任何异常只记日志。
• 浏览器半只用 "dsh": { "client": { "platform": "web" } } 声明装载，故意不写 `client.inject`。inject 的含义是"必须先把这些客户端包注入进来"，缺任何一个整个板块就挂起不出现；而本机的 @deepseek-ai/dsh-client-ui-slots 是个指向已失效目标的 junction，硬声明它等于自己制造装不上的情况。客户端代码里对两个服务都做了可选探测：有 ctx.slots 才注册板块，没有就 warn 后跳过；locale 缺失就回落到内置中文。

已知边界

1. 只做 TCP 转发，不做路径过滤：固定端口上暴露的是整个 DSH web 面（含 GUI），不限于某一条路径。默认只绑 127.0.0.1，不对外网开放。
2. 依赖宿主的 `webServer` 服务（listenedPort / server.address() / config.port 三选一取值）。DSH 大版本若改变这个服务的形状，插件会失效，症状是固定端口无人监听。
3. 端口被占用时不抢占：记一条 warn 后让位，宿主照常运行。

License

MIT