DeepSeek Harness 路由 404:webserver disposer 按 path 删除
DeepSeek Harness(DSH)插件卸载或热重载之后,它注册的 HTTP 路由变成 404、WebSocket upgrade 路由变成「连接 0 字节直接断开」,而日志里什么都没有**——这类「静默消失」的典型根因,是 webserver 的路由 disposer 按 path 删除、不校验归属。** register() / registerUpgrade() 返回的清理函数写的是 table.delete(route.path):只要同一个 path 先被 A 注册、A 的 disposer 在 B 注册之后才被调用,B 的路由就会被静默删掉,而且 A 的 disposer 不会报任何错。重复注册时两个函数都会抛 duplicate ... route,说明 path 本来就是唯一键——既然唯一,disposer 就更该确认自己删的是不是自己那条(#11579)。
症状:静默 404 与 0 字节断开,日志里没有任何痕迹
一句话结论:这不是「插件没启动」,而是「路由被别人的清理函数删了」,两者的区别是前者有加载日志、后者完全无声。 三类表现对照:
- HTTP 路由:请求返回 404,且没有「路由未找到」之外的任何日志。看起来就像这个路径从来没注册过。
- upgrade 路由:握手直接 0 字节断开,与「路径根本不存在」完全一致,客户端拿不到任何错误码。
- 最迷惑的一种:插件其实已经卸载、不再工作,但某个
/status仍返回 200——那是另一个问题(HTTP 路由的 disposer 没被ctx.effect收集,所以卸载时没删),与本篇的「删错别人的」不是同一件事。
讨论里报告者的亲身经历是:插件注册 1 个 upgrade 路由 + 2 个 HTTP 路由,卸载后 /status 仍 200、/send-image 返回 503、/pet(upgrade)0 字节。三个现象背后是两个不同的机制,排查时必须分开归因。
最小复现:四步把「删别人的」摆出来
关键判据是:先注册 A、注销、注册 B、再调一次 A 的 disposer,B 会消失。 步骤:
- 准备一个 WebServer 实例,注册 A。 执行
const w = new WebServer()与const disposeA = w.registerUpgrade({ path: '/pet', tag: 'A' })。 - 调用一次 A 的 disposer,模拟 A 下线。 执行
disposeA(),预期:/pet从 upgrades 表消失。这一步是正常清理。 - 注册 B,模拟新实例上线。 执行
w.registerUpgrade({ path: '/pet', tag: 'B' }),预期:不抛duplicate upgrade route,因为 A 已经先注销了。 - 再调一次 A 的 disposer。
disposeA()
console.log(w.upgrades.has('/pet')) // false —— B 被删了
预期:打印 false,B 的路由无声消失。register() 走 exact / prefixes 表时行为完全相同(#11579)。
这个复现成立的前提只有一个:disposer 被调用第二次。听起来苛刻,实际并不——ctx.effect 的清理与显式 dispose() 并存时就会发生。
为什么真实场景里会咬人:清理顺序不可控
一句话结论:插件的卸载、重载顺序以及同一服务被多个实例先后注册的顺序都不可控,只要出现「旧 disposer 晚于新注册」,路由就会消失。 三处不可控:
ctx.effect收集的 disposer 在插件卸载时执行,但卸载发生在哪个时刻不由插件决定。- 显式
dispose()可能同时被调用,于是同一个清理函数被执行两次;第一次正常,第二次就删掉了后来者。 - 多实例场景(热重载、双开、插件 A 被替换成新版本)让「同名 path 先后归属不同实例」成为常态。
报告者与回复者都强调,这个 bug 的排查成本高不是因为现象复杂,而是因为没有任何日志或异常——你只能看到「路由不见了」,看不到「路由被谁删了」。
正确写法:删之前先确认归属
一句话结论:disposer 改成 if (table.get(route.path) === route) table.delete(route.path),两张表各一处,最小改动即可。 步骤如下:
- 改
register()的 disposer。 从() => { table.delete(route.path) }改成下面这种先判断归属的写法:
return () => {
if (table.get(route.path) === route) table.delete(route.path)
}
- 改
registerUpgrade()的 disposer。 同样加归属判断,把this.upgrades作为目标表。 - 确认
route是对象引用。 注册时存的是对象本身,所以get(path) === route是 O(1) 的引用比较,没有性能影响。 - 跑四组断言。 预期:同名二次注册抛
duplicate;旧 disposer 删掉后来者注册的 upgrade 路由确实发生;register()的 exact 表同样中招;改完后不再误删。 - 在插件自己的测试里加这条回归。 这是 API 契约行为,靠读代码容易漏,必须用断言锁住。
另一种可选设计是给 disposer 加归属 token(例如内部包一层
{ route, token }),但上面的最小改动已经足够,不必为此改数据结构。
发现「不是自己」时:静默跳过加 warn,别抛错
一句话结论:抛错本身不危险,但同一个 ctx.effect 里的 disposer 用 .then 串联、没有 try/catch,一条抛错会让后面几条压根不执行,造成泄漏。 依据来自三种写法对照:
| 「不是自己」时的写法 | 结果 |
|---|---|
抛错,多条路由共用一个 ctx.effect | 后续全部跳过,泄漏 |
抛错,每条路由各自一个 ctx.effect | 无泄漏(各条 .then 链独立) |
静默跳过(if (get === route) delete) | 无泄漏 |
根因在 cordis/lib/index.js:1179:同一批 disposer 用 task = task.then(() => runDisposable(disposable)) 串联,没有 try/catch。对照 fiber._unload()(:1373-1382)是每个独立 try/catch,那里抛错只伤自己。
两条判断理由:
- disposer 被调两次是合法场景,不是调用方 bug;给合法场景抛错不合理。
- 泄漏的代价大于暴露 bug 的收益:泄漏的表现是「路由还在、插件已死」,报告者被这种假象骗了 10 小时。
真要留痕,用 logger.warn 打一行「disposer 发现 path 已归属其它 route」,既不中断,又可查。
用户侧排查顺序:先分清「没注册」还是「被删了」
一句话结论:按「路由表 → 插件加载状态 → 清理顺序」三层查,能避免把两个不同 bug 混成一个。 步骤:
- 确认插件当前是否加载。 预期:插件列表里状态正常、没有加载失败。若插件根本没起来,先看它的加载日志,不要怀疑路由。
- 直接请求路由看状态码。 HTTP 404 = 路由不在表里;upgrade 0 字节 = 同样不在表里。两者都指向「注册没了」。
- 回顾操作顺序。 预期:故障是否发生在「卸载/重载之后又装了新版本」这个时间点。是的话,本篇命中概率高。
- 检查插件是否把 disposer 收进
ctx.effect。 如果没收集,卸载后路由会留下来继续 200,那就不是「删错」,而是「没删」——两个方向相反的问题。 - 把版本与行号记下来。 回复者核对
packages/host/webserver/src/index.ts:445-466(rc.2 的lib/index.js:326-346同构),disposer 在:451与:465。
修复状态与边界
一句话结论:这是 API 契约层的缺陷,产品侧一行可修,但截至该讨论尚未合并;用户与插件作者都应按「归属判断」自行规避。 三条边界:
- 版本一致性:master
ce7073d5的src/index.ts:445-466与0.2.1-rc.2的lib/index.js:326-346行为一致,换版本不改变结论。 - 提交渠道:仓库
CONTRIBUTING.md写明当前不接受外部 PR,问题走 GitHub Discussions;这也意味着修复节奏取决于维护者。 - 不是唯一原因:热重载后 404 也可能来自「插件没重新加载」或「disposer 没被 effect 收集」。本篇只覆盖「归属判断缺失」这一支,其余两支要各自取证。
排查注意事项
路由类故障的排查原则是:先确定「表里有没有」,再讨论「为什么没有」。 六条要点:
- 静默 404 优先怀疑清理逻辑,不是插件注册代码。
- upgrade 的 0 字节与 404 等价,别去抓握手报文找原因。
- 区分「没删」与「删错」:前者路由残留并继续响应,后者路由消失。
- disposer 必须幂等,被调两次不是异常场景。
- 同一 effect 里多条 disposer 要逐条 try/catch,否则一条抛错拖垮整批。
- 插件作者要把归属判断写进测试,这是契约,不靠记忆保证。
常见问题
DeepSeek Harness 里常见原因是路由 disposer 按 path 删除、不校验归属。旧实例的清理在东山再起之后才执行时,会把新实例注册的同名路由一起删掉,而且失败完全静默,只在请求时表现为 404。位置在 webserver 的 register() / registerUpgrade() 返回的清理函数。
因为在 DeepSeek Harness 里 upgrade 路由被删除后,服务端会把该路径当成根本不存在,握手阶段就直接断开且不回任何数据。它与「路径不存在」的表现完全一致,所以从客户端看只有 0 字节,既没有 404 也没有异常日志,这正是这条故障难查的地方。
DeepSeek Harness 插件里的 disposer 要先比较归属,再删除:if (table.get(route.path) === route) table.delete(route.path)。register 的 exact/prefixes 两张表与 registerUpgrade 的 upgrades 表各需要一处,route 是对象引用,比较是 O(1),没有性能影响。
因为在 DeepSeek Harness 的同一个 ctx.effect 里,disposer 是用 .then 串联的,没有 try/catch(cordis/lib/index.js:1179)。一条抛错会让后面几条压根不被调用,造成路由泄漏。disposer 被调用两次本身是合法场景,所以更稳的做法是静默跳过并 logger.warn 留痕。
相关术语
- disposer
- disposer 是 DeepSeek Harness 注册资源时返回的清理函数,调用它应当撤销这次注册。webserver 的 register() 与 registerUpgrade() 都会返回 disposer,插件通常通过 ctx.effect() 把它们交给框架在卸载时统一执行。— https://github.com/deepseek-ai/deepseek-harness/discussions/11579
- registerUpgrade
- registerUpgrade 是 webserver 注册 WebSocket upgrade 路由的接口,按 path 存入 upgrades 表;同一 path 重复注册会抛 duplicate upgrade route。它的 disposer 在 packages/host/webserver/src/index.ts:465 附近,同样只做 table.delete(route.path)。— https://github.com/deepseek-ai/deepseek-harness/discussions/11579
- ctx.effect
- ctx.effect 是 DeepSeek Harness 插件上下文提供的生命周期注册方式,传入的回调返回一个 disposer,在插件卸载时执行。它与显式 dispose() 可能同时存在,因此同一个 disposer 被调用两次是合法场景。— https://github.com/deepseek-ai/deepseek-harness/discussions/11579
来源
- #11579 — webserver 的路由 disposer 按 path 删除,不校验归属(同名路由会被旧实例静默删掉)· deepseek-ai(GitHub Discussions)