DeepSeek Harness HTTP 服务器子系统拆解

DeepSeek Harness（简称 dsh）是 DeepSeek AI 开源的 agent 框架，采用一切皆插件的架构，由 Cordis 框架驱动，以 MIT 协议在 GitHub 上开放，目前处于开发者预览阶段。跑一条 npx @deepseek-ai/dsh web 就能拉起它的 Web UI，而这背后真正承接浏览器请求的，是仓库里 packages/host/webserver 目录下的一个小包 dsh-host-webserver。它是一个提供 ctx.webServer 服务的 node:http 插件，不属于 agent loop，也不是能力接缝，甚至不了解任何 harness 概念。官方文档对它的定位很明确：浏览器的 HTTP 载体。本文基于这份子系统文档，拆一拆这台最不像主角的服务器。

它只做一件事：给浏览器当载体

dsh-host-webserver 在激活时立即监听，向插件容器暴露 ctx.webServer。它刻意不承载任何业务功能：/api 桥接、插件 bundle、热模块替换（HMR）事件流，全部由其他插件以具名路由的形式注册进来；静态文件则归回退席位的主人管。它也只服务浏览器：Electron 桌面端通过 file:// 直接加载构建产物，再经 IPC 桥转发 fetch 请求，根本不经过这台服务器。

路由是组合契约，不是分发表

路由只有两种匹配方式：exact 按路径逐字匹配，prefix 匹配前缀本身及其下所有子路径。每条路由由匹配种类、绝对路径和处理器组成，处理器拥有完整的响应生命周期，可以把连接一直挂着，SSE（Server-Sent Events）推流就是这种用法。

匹配顺序固定为三步：先查全表 exact，再取最长匹配前缀，最后落到回退处理器。值得琢磨的是，注册顺序不携带任何面向请求的语义，先来后到都不影响命中结果。文档给出的理由是：具名路由在组合上互不相交，既然彼此不相交，谁先谁后都一样。于是重复注册相同的匹配种类加路径会直接抛异常，因为路由模式是组合层契约，冲突即配置错误，静默覆盖只会把问题埋得更深。

回退席位只有一个主人

任何未被具名路由认领的请求，都交给回退席位。这个席位全局唯一，第二次注册会抛异常，理由很直白：两个回退无法组合。官方发布的 Web 组合里，认领席位的是 dsh-host-frontend-static，一个语义固定的 SPA 静态服务器：非 GET/HEAD 请求返回 405，路径越出 dist 根目录返回 403，任何未命中都以 HTTP 200 回退到 index.html，未知扩展名按 octet-stream 发送。在席位主人注册之前，服务器对未匹配的请求先回 404。

除普通路由外，registerUpgrade 注册的升级路由按精确路径匹配，一条 socket 只能有一个协议主人，重复注册同样抛异常。升级处理器拥有协议协商和连接内容，webserver 只负责递送裸 socket，未匹配的升级连接直接关闭。

配置只有两项，安全姿态写得很直白

配置只有 host 和 port 两个字段。host 只接受 127.0.0.1（默认姿态）和 0.0.0.0（刻意的网络暴露）两个值；没有 TLS、认证或 origin 策略，所以绑定到非回环地址就等于把服务器暴露给整个网络。文档明确说，部署加固或者前置一个真正的反向代理，在面向开发者的 v1 里是有意不做的。port 写 0 表示让操作系统分配端口，ctx.webServer.port 能读出实际监听端口，组合期的其他插件（比如目录选择器）会以此为事实做适配。

index.html 的转换管道

tapIndex(transform) 注册一个纯 HTML 到 HTML 的转换函数，按注册顺序作用于每一个 index 响应，包括根路径和每次 SPA 回退。client-modules 插件就用它在页面里注入启动 manifest（元数据清单）。对应的 applyIndexTaps(html) 是执行入口，由回退主人在渲染每个 index 响应时调用。

错误隔离与拆卸

单个请求处理中抛异常，比如畸形的 % 转义撞上 decodeURIComponent，或者客户端在请求体读到一半时断开，只会被记录为警告并应答 400；响应头已经发出时则直接销毁 socket。无论哪种情况都不会导致进程退出。升级处理器抛异常或升级 socket 出现传输错误，同样记警告并销毁对应 socket。

拆卸语义同样讲究：dispose 把 close() 与 closeAllConnections() 配对使用，并销毁所有受跟踪的升级 socket。原因是 SSE 这类处理器会让连接永不自行结束，没有强制关闭，整个拆卸流程就会挂住。反过来，启动阶段的监听失败（比如端口被占用）会让初始化被拒绝，启动进程报告失败的 fiber。最后一个细节：这个包从不打印任何输出，URL 那一行归 shell 所有。

小结

dsh-host-webserver 的价值不在功能多少，而在边界清晰：路由表是组合层契约，冲突即报错；回退席位唯一，静态文件语义集中在一处；错误隔离保证一个坏请求拖不垮整个 agent 宿主。对想研究 agent 框架工程结构的人来说，这种载体插件不碰业务的分层是一个干净的参考样本。项目仍在快速迭代，接口可能出现破坏性变更，动手前建议先看仓库文档。