ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 路由 404:webserver disposer 按 path 删除

故障排查发布于 2026-11-03作者: DeepSeek Plugin 插件市场
DeepSeek Harnesswebserver路由 404disposer插件热重载registerUpgrade
DeepSeek Harness 插件卸载或热重载后路由 404、upgrade 握手 0 字节断开,日志空白。根因是 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 字节断开,日志里没有任何痕迹

一句话结论:这不是「插件没启动」,而是「路由被别人的清理函数删了」,两者的区别是前者有加载日志、后者完全无声。 三类表现对照:

  1. HTTP 路由:请求返回 404,且没有「路由未找到」之外的任何日志。看起来就像这个路径从来没注册过。
  2. upgrade 路由:握手直接 0 字节断开,与「路径根本不存在」完全一致,客户端拿不到任何错误码。
  3. 最迷惑的一种:插件其实已经卸载、不再工作,但某个 /status 仍返回 200——那是另一个问题(HTTP 路由的 disposer 没被 ctx.effect 收集,所以卸载时没删),与本篇的「删错别人的」不是同一件事。

讨论里报告者的亲身经历是:插件注册 1 个 upgrade 路由 + 2 个 HTTP 路由,卸载后 /status 仍 200、/send-image 返回 503、/pet(upgrade)0 字节。三个现象背后是两个不同的机制,排查时必须分开归因。

最小复现:四步把「删别人的」摆出来

关键判据是:先注册 A、注销、注册 B、再调一次 A 的 disposer,B 会消失。 步骤:

  1. 准备一个 WebServer 实例,注册 A。 执行 const w = new WebServer() 与 const disposeA = w.registerUpgrade({ path: '/pet', tag: 'A' })。
  2. 调用一次 A 的 disposer,模拟 A 下线。 执行 disposeA(),预期:/pet 从 upgrades 表消失。这一步是正常清理。
  3. 注册 B,模拟新实例上线。 执行 w.registerUpgrade({ path: '/pet', tag: 'B' }),预期:不抛 duplicate upgrade route,因为 A 已经先注销了。
  4. 再调一次 A 的 disposer。
js
disposeA()
console.log(w.upgrades.has('/pet'))   // false —— B 被删了

预期:打印 false,B 的路由无声消失。register() 走 exact / prefixes 表时行为完全相同(#11579)。

这个复现成立的前提只有一个:disposer 被调用第二次。听起来苛刻,实际并不——ctx.effect 的清理与显式 dispose() 并存时就会发生。

为什么真实场景里会咬人:清理顺序不可控

一句话结论:插件的卸载、重载顺序以及同一服务被多个实例先后注册的顺序都不可控,只要出现「旧 disposer 晚于新注册」,路由就会消失。 三处不可控:

  1. ctx.effect 收集的 disposer 在插件卸载时执行,但卸载发生在哪个时刻不由插件决定。
  2. 显式 dispose() 可能同时被调用,于是同一个清理函数被执行两次;第一次正常,第二次就删掉了后来者。
  3. 多实例场景(热重载、双开、插件 A 被替换成新版本)让「同名 path 先后归属不同实例」成为常态。

报告者与回复者都强调,这个 bug 的排查成本高不是因为现象复杂,而是因为没有任何日志或异常——你只能看到「路由不见了」,看不到「路由被谁删了」。

正确写法:删之前先确认归属

一句话结论:disposer 改成 if (table.get(route.path) === route) table.delete(route.path),两张表各一处,最小改动即可。 步骤如下:

  1. 改 register() 的 disposer。 从 () => { table.delete(route.path) } 改成下面这种先判断归属的写法:
js
return () => {
  if (table.get(route.path) === route) table.delete(route.path)
}
  1. 改 registerUpgrade() 的 disposer。 同样加归属判断,把 this.upgrades 作为目标表。
  2. 确认 route 是对象引用。 注册时存的是对象本身,所以 get(path) === route 是 O(1) 的引用比较,没有性能影响。
  3. 跑四组断言。 预期:同名二次注册抛 duplicate;旧 disposer 删掉后来者注册的 upgrade 路由确实发生;register() 的 exact 表同样中招;改完后不再误删。
  4. 在插件自己的测试里加这条回归。 这是 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,那里抛错只伤自己。

两条判断理由:

  1. disposer 被调两次是合法场景,不是调用方 bug;给合法场景抛错不合理。
  2. 泄漏的代价大于暴露 bug 的收益:泄漏的表现是「路由还在、插件已死」,报告者被这种假象骗了 10 小时。

真要留痕,用 logger.warn 打一行「disposer 发现 path 已归属其它 route」,既不中断,又可查。

用户侧排查顺序:先分清「没注册」还是「被删了」

一句话结论:按「路由表 → 插件加载状态 → 清理顺序」三层查,能避免把两个不同 bug 混成一个。 步骤:

  1. 确认插件当前是否加载。 预期:插件列表里状态正常、没有加载失败。若插件根本没起来,先看它的加载日志,不要怀疑路由。
  2. 直接请求路由看状态码。 HTTP 404 = 路由不在表里;upgrade 0 字节 = 同样不在表里。两者都指向「注册没了」。
  3. 回顾操作顺序。 预期:故障是否发生在「卸载/重载之后又装了新版本」这个时间点。是的话,本篇命中概率高。
  4. 检查插件是否把 disposer 收进 ctx.effect。 如果没收集,卸载后路由会留下来继续 200,那就不是「删错」,而是「没删」——两个方向相反的问题。
  5. 把版本与行号记下来。 回复者核对 packages/host/webserver/src/index.ts:445-466(rc.2 的 lib/index.js:326-346 同构),disposer 在 :451 与 :465。

修复状态与边界

一句话结论:这是 API 契约层的缺陷,产品侧一行可修,但截至该讨论尚未合并;用户与插件作者都应按「归属判断」自行规避。 三条边界:

  1. 版本一致性:master ce7073d5 的 src/index.ts:445-466 与 0.2.1-rc.2 的 lib/index.js:326-346 行为一致,换版本不改变结论。
  2. 提交渠道:仓库 CONTRIBUTING.md 写明当前不接受外部 PR,问题走 GitHub Discussions;这也意味着修复节奏取决于维护者。
  3. 不是唯一原因:热重载后 404 也可能来自「插件没重新加载」或「disposer 没被 effect 收集」。本篇只覆盖「归属判断缺失」这一支,其余两支要各自取证。

排查注意事项

路由类故障的排查原则是:先确定「表里有没有」,再讨论「为什么没有」。 六条要点:

  1. 静默 404 优先怀疑清理逻辑,不是插件注册代码。
  2. upgrade 的 0 字节与 404 等价,别去抓握手报文找原因。
  3. 区分「没删」与「删错」:前者路由残留并继续响应,后者路由消失。
  4. disposer 必须幂等,被调两次不是异常场景。
  5. 同一 effect 里多条 disposer 要逐条 try/catch,否则一条抛错拖垮整批。
  6. 插件作者要把归属判断写进测试,这是契约,不靠记忆保证。

来源:Discussion #11579。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 插件热重载后路由全变 404 且日志无线索,是什么原因?

DeepSeek Harness 里常见原因是路由 disposer 按 path 删除、不校验归属。旧实例的清理在东山再起之后才执行时,会把新实例注册的同名路由一起删掉,而且失败完全静默,只在请求时表现为 404。位置在 webserver 的 register() / registerUpgrade() 返回的清理函数。

DeepSeek Harness 的 upgrade 路由为什么表现为 0 字节断开而不是报错?

因为在 DeepSeek Harness 里 upgrade 路由被删除后,服务端会把该路径当成根本不存在,握手阶段就直接断开且不回任何数据。它与「路径不存在」的表现完全一致,所以从客户端看只有 0 字节,既没有 404 也没有异常日志,这正是这条故障难查的地方。

插件里注册多条路由时,disposer 应该怎么写才不会被旧实例误删?

DeepSeek Harness 插件里的 disposer 要先比较归属,再删除:if (table.get(route.path) === route) table.delete(route.path)。register 的 exact/prefixes 两张表与 registerUpgrade 的 upgrades 表各需要一处,route 是对象引用,比较是 O(1),没有性能影响。

为什么 DeepSeek Harness 的 disposer 在发现「不是自己」时建议 warn 而不是抛错?

因为在 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

来源