ChatGPTClaudeGrok / X / CursorGemini

DSH plugin HTTP 服务器:路由、配置与服务接口到底该怎么对齐才不会出现 404

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessHTTP 服务器路由index 注入
插件想加一个 HTTP 端点,路由注册了却 404,或配置改了不生效。本文讲 exact 与 prefix 的匹配顺序、回退席位为何只能有一个所有者、resource 与 handler 的边界,以及 TLS 与压缩的加载期校验。

路由注册了却 404,通常不是路径写错,而是被回退席位或前缀匹配顺序盖过去了。 DSH plugin 的 HTTP 服务器匹配顺序是固定的:exact、最长前缀、回退。注册顺序不参与匹配,这一点先记住。 DSH插件 加 HTTP 端点却返回 404,先查回退席位与匹配顺序。

服务器只服务浏览器

它不是能力 seam,也不属于 agent loop。(来源)

dsh-host-webserver 是 GUI Host 的浏览器 HTTP 载体:一个 node:http 服务器——配置 tls 时改用 node:https——提供 ctx.webServer、具名路由注册表、可选的 gzip 响应压缩、index.html 转换回调,以及一个可由插件认领的回退(handler 或 resource)。

它不属于 agent 循环,也不是能力 seam;唯一涉及的 harness 概念是 index 渲染所代表的 Peer。

其他插件负责注册所有功能路由,包括 /api 桥接、插件 bundle 与 HMR 事件流。该服务器只服务浏览器:Electron 通过 file:// 加载已构建文件,并经 IPC 桥接发送 fetch 请求,不使用本服务器。

路由匹配:exact、最长前缀、回退

注册顺序不带语义,冲突即配置错误。(来源)

WebRouteKind 只有两种:exact 逐字匹配 pathname;prefix 的 p 匹配 p 与 p/<anything>。WebRoute 的 path 是绝对路径、不带结尾斜杠;handler 拥有完整响应生命周期,可以像 SSE 那样一直持有响应。

匹配顺序固定:先查 exact 表,再取最长匹配前缀,最后落到已注册的回退。注册顺序不携带任何面向请求的语义。

具名路由在组合上互不相交,任何未被具名路由认领的请求都由回退席位应答。席位只有一个所有者,第二次注册会抛异常。

发布的 Web 组合用 dsh-host-frontend-static 认领席位,它是一台遵循固定语义的 SPA dist 服务器:Connection 在读取 dist 根目录和配置 index 的 HTML 前完成认证;非 index 资产保持公开;非 GET/HEAD 返回 405;越出 dist 根目录的遍历返回 403;现有文件直接提供;缺失或不是文件的目标返回空的 404;未知扩展名按 octet-stream 发送。

resource 与 handler 的边界

会产生副作用或返回私有数据的路由,即使应答 GET 也应当用 handler。(来源)

路由或回退可以用 resource——一个把 Fetch Request 映射为 Response 的函数——代替 handler。WebResource 应答 HTTP GET 与 HEAD 请求,也应答进程内读取。

关键区别在 Peer:HTTP 的 GET、HEAD 请求不带 Peer 到达 resource;readResource(request, peer) 则在进程内按调用方准入的 Peer 读取它。读取遵循同样的匹配顺序,但只到达 resource。

因此官方给的判据很实用:返回 owner 私有数据或会执行操作的路由,即使应答 GET 也保持为 handler。resource 更适合公开的、无副作用的读取。

配置:地址、TLS 与压缩

监听地址必须是具体字面量,通配地址在加载期就被拒绝。(来源)

Config 的字段与默认值:

  1. host — 本地某个接口的具体 IPv4 或 IPv6 字面量。回环字面量把服务器留在这台机器;其他字面量服务该地址所属网络,除非配置 tls,否则以明文 HTTP 提供服务。未指定地址在加载时即被拒绝,因为它会一次性暴露到所有接口。
  2. port — 监听端口;0 表示由操作系统分配。
  3. tls — 证书链文件与私钥文件,均在监听器绑定前读取一次。文件不可读、为空、PEM 无效或密钥与证书不匹配都会拒绝初始化,而不是回退到 HTTP;材料不会重读,替换证书需要重载。
  4. compression — 'none' 或 'gzip',默认 'none'。
  5. compressionLevel — gzip DEFLATE 等级 0 到 9,默认 1。
  6. compressionThresholdBytes — 已知响应长度的最小 gzip 门槛,默认 1024;未知长度的流也算符合条件。

载体不拥有认证或 Origin 策略。随附的 dsh web 命令默认选择回环并接受一个具体的 --host 地址;非回环绑定以明文 HTTP 提供服务时会在启动时警告。其 Connection 插件为每个 Host API route 与 stream 提供 Host/Origin 校验和浏览器会话认证;绑定地址加 --trusted-host 决定接受哪个浏览器 Host;--public-url 只改变公告的 URL。

服务行为:监听、注册、压缩与 index 注入

监听失败会拒绝初始化,不会假装启动成功。(来源)

WebServer(ctx.webServer)在激活时立即监听;监听失败(EADDRINUSE 等)会使初始化被拒绝,启动进程会报告失败的 fiber。

register(route) 添加一条具名路由并返回其 disposer。重复的 (kind, path) 会抛异常,因为路由模式是组合层约定,冲突即配置错误。

gzip 在服务器内部包装符合条件且基于 socket 的响应,因此 handler 继续直接持有 ServerResponse,resource 则把 Response 交给服务写回。已有内容编码、Cache-Control: no-transform、范围响应、SSE、ZIP 与打包后的 .gz Worker 镜像都保持 identity 响应。

index 注入有两个入口:collectIndexInjections(peer) 经一次传入页面所代表 Peer 的 webserver/index-inject emit 收集结构化 IndexInjection 行;renderIndex(html, peer) 把它们渲染进成功的根路径和配置 index 响应,随后再按注册顺序应用原始的 tapIndex(transform) 逃生口转换。dsh-client-modules 以启动 manifest 行回应该事件。

读取事实用 port(包含 config.port 为 0 时系统分配的端口)与 protocol(http: 或 https:),不要自己猜。

异常、销毁与输出归属

拆卸必须强制关闭连接,否则 SSE 会把进程挂住。(来源)

处理过程中抛出异常的请求会记录为警告并应答 400(响应头已发出时则销毁 socket),绝不导致进程退出。典型场景是畸形的 % 转义撞上 decodeURIComponent,或客户端在请求体中途断开。

dispose 把 close() 与 closeAllConnections() 配对使用,因为处理器可能像 SSE 那样保持响应打开,而这类连接永远不会自行结束;没有强制关闭,拆卸就会挂起。

TLS socket 只有完成握手后才计入连接,因此服务器会把原始 TLS socket 与升级后的 socket 一并跟踪,并在 dispose 时销毁两者。

该包从不打印输出:URL 行归 shell 所有。这条边界常被误当成“启动没成功”,其实只是输出归属不同。

验证:注册一个端点

验证要覆盖匹配顺序、回退与销毁三条路径。(来源) 六步:

  1. 注册 exact 的 /api/ping,请求它,断言命中而非落到回退。
  2. 注册 prefix 的 /assets,请求 /assets/app.js,断言命中;请求 /assets 本身也应命中。
  3. 同时注册 exact /a/b 与 prefix /a,请求 /a/b,断言 exact 优先。
  4. 请求一个未被认领的路径,断言由回退应答(在静态组合下是 404 或 index)。
  5. 重复注册相同的 (kind, path),断言抛异常,而不是后注册者覆盖。
  6. 开一条 SSE 长连接后调 dispose,断言进程不挂起且 closeAllConnections 生效。

如果第 3 步命中了 prefix,先检查是不是把两者都写成了 prefix——最长前缀只在前缀之间比较。

客户端分层的整体关系,可以对照Web Client 分层;路由释放器的常见问题见Web 路由释放器。

一句话收束: 只服务浏览器、exact 先于前缀、回退唯一所有者、私有数据用 handler、通配地址加载即拒、拆卸必须强制关连接。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里路由注册了却返回 404,最先应该查什么?

先查回退席位与匹配顺序。DSH plugin 的匹配顺序固定为 exact 表、最长匹配前缀、最后落到已注册回退;注册顺序本身不携带任何面向请求的语义。

DSH plugin 的 HTTP 服务器能同时注册两个回退吗,会怎样?

不能,DSH plugin 的回退席位只有一个所有者。DSH plugin 在第二次注册回退时会抛异常,冲突属于组合层配置错误。

DSH plugin 的 Electron 也用这个服务器吗?

不用,DSH plugin 的 Electron 通过 file:// 加载已构建文件。DSH plugin 的 HTTP 服务器只服务浏览器,Electron 的 fetch 请求走 IPC 桥接。

DSH plugin 的 TLS 证书在运行中能热更新吗,替换要重载吗?

不能,DSH plugin 在监听器绑定前只读一次证书。DSH plugin 替换证书需要重载;文件不可读、为空或不匹配都会拒绝初始化,而不是回退到 HTTP。

相关术语

WebRoute
WebRoute 是一条具名路由,含 exact 或 prefix 匹配、绝对路径与拥有完整响应生命周期的 handler。— packages/host/webserver/src/index.ts
WebResource
WebResource 是把 Fetch Request 映射为 Response 的函数,HTTP GET/HEAD 到达时没有 Peer。— packages/host/webserver/src/index.ts
readResource
readResource 是在进程内按调用方准入的 Peer 读取 resource 的入口,匹配顺序与 HTTP 相同但只到达 resource。— packages/host/webserver/src/index.ts
collectIndexInjections
collectIndexInjections 通过一次 webserver/index-inject emit 收集结构化 IndexInjection 行,供 renderIndex 渲染。— packages/host/webserver/src/index.ts

来源