DeepSeek Harness 侧栏接口 405 空响应：webRuntime 被移除怎么修

升级到 DeepSeek Harness（DSH）0.2.1 之后，侧栏看起来还在，但 Markdown 预览打不开、文件树空白、git 操作无反应；打开开发者工具一看，这些请求全是 405，响应体还是空的。 这不是网络问题，也不是权限问题，而是插件还在等一个已经不存在的服务：webRuntime 在 0.2.1 被删除了，替代者叫 webStartup。旧插件因此永久 pending，它注册的路由一个都没挂上。

DeepSeek Harness 405 空体是动态路由没挂载的指纹

一句话结论：同一插件的所有接口一起返回空体 405、插件列表里又有 pending (waiting for service: webRuntime)，就可以直接判定是服务名迁移问题。 与其他 405 的区分：

据讨论里的源码核对，app-boot/src/index.ts:1072-1074 对 pending 的 entry 不会重新求值；frontend-static/src/index.ts:122-125 会把未匹配的 POST 交给静态处理器，于是返回空体 405（#10027）。侧栏插件的常规用法可以对照 侧栏插件教程。

0.2.1 把 DSH 的 webRuntime 换成了什么

一句话结论：公开服务从 webRuntime 换成了 webStartup，同时信任主机的配置方式也变了；插件如果只改一半，就会停在 pending。

迁移链路：

• 旧插件声明 inject: ['webRuntime']，启动时等服务。
• 0.2.1 不再注册 webRuntime，该服务永远不出现。
• entry 永久 pending，但宿主不报错，只留一条 warning。
• 插件里 ctx.webRuntime.register(...) 的代码从未执行。
• 请求到达宿主，没有匹配的动态路由，落到静态兜底，返回空体 405。

官方升级指南里记录了这次迁移（web-listener-trust-config），但 release notes 里不一定显眼，所以很多人升级后才发现。

DeepSeek Harness 的三种恢复方式

一句话结论：插件作者已跟进就升级版本，没跟进就本地改服务名，插件不是刚需就先禁用。

修法一：升级插件到适配 0.2.1 的版本

这是最干净的做法，前提是插件作者已经跟进。 以侧栏插件为例，0.24.1 仍用 webRuntime，0.28.0 已迁移。

1. 打开插件详情，确认最新版本号与更新日志里是否提到 webStartup；预期能判断该版本是否已迁移。
2. 在插件市场点更新，等待安装完成；预期 profile 下的包被替换。
3. 重启 DSH；预期插件状态从 pending 变为 active。
4. 打开侧栏，依次点 Markdown 预览、文件树、git 操作；预期接口不再 405。
5. 如果更新后仍 pending，检查 profile 里是否还有旧版本残留目录；预期只剩一份插件副本。

修法二：本地改插件产物，把服务名换掉

插件作者还没跟进时，可以自己改构建产物，通常只有 inject 和两三处调用点，适合临时救急。

1. 找到 profile 下的插件目录，例如 ~/.dsh/profiles/<profile>/node_modules/dsh-better-sidebar；预期编辑的是 profile 实际加载的产物。
2. 打开 lib/index.js，搜索 webRuntime；预期得到完整引用清单。
3. 把 inject 里的 webRuntime 改成 webStartup；预期该行能解析新服务。
4. 把 ctx.webRuntime 的调用改成 ctx.webStartup，注意方法名是否也变了；预期注册代码能编译到新 API。
5. 重启 DSH，确认插件 active、接口恢复；预期改动在下次插件更新前有效。

这条修法的风险是：插件更新会覆盖改动，需要重新打补丁；新服务的方法签名不同，只改名字仍会报错；改的是 node_modules，清理依赖后可能丢失，务必记录。

修法三：临时禁用插件，换替代方案

如果这个插件不是刚需，先禁用能立刻消除 405 和 pending，避免它影响其他插件的加载。

1. 打开插件列表，禁用仍在 inject webRuntime 的插件；预期重启后 pending 行消失。
2. 重启 DSH；预期 405 不再出现、其他插件状态正常。
3. 用 DSH 自带功能或其他已适配插件替代它的能力；预期工作流能继续。
4. 等插件作者发布兼容版本后再启用；预期能力恢复且不需要手工补丁。

DSH 插件恢复后的验证与避坑

一句话结论：插件 active 只是必要条件，重启两次并逐个接口验证，才能确认不是加载顺序碰巧对了。 验证步骤：

1. 看插件状态；预期是 active，不是 pending。
2. 侧栏的每个 API 都试一次：预览、文件树、git status、保存；预期全部成功。
3. 用浏览器开发者工具看响应码；预期 200/204，而不是 405 空体。
4. 重启两次；预期状态稳定，不会因为加载顺序又变回 pending。
5. 再装一个无关插件；预期不会把已修复的插件挤回 pending。

避坑要点：

• 不要把 405 当成后端路由 bug，先看插件状态，能省很多时间。
• webRuntime 是公开服务名，删除属于破坏性变更；插件没跟进时，升级前先查兼容性。
• 改 node_modules 不是长期方案，记录改动并推动插件作者适配。
• 0.2.1 的信任主机配置也变了，如果修完服务名仍 403/401，继续查 trustedHosts，别把 DSH插件 的权限问题当成路由问题。

DeepSeek Harness webRuntime 常见问题

Q：DeepSeek Harness 升级 0.2.1 后侧栏预览 405、文件树和 git 都不能用，为什么？ A：DeepSeek Harness 升级后侧栏 405，是插件仍在 inject 已被删除的 webRuntime 服务。0.2.1 把公开服务改成 webStartup，旧插件永久 pending，它注册的 API 没有挂载；请求落到静态文件兜底，返回空体 405。升级插件或把 inject 改成 webStartup 即可恢复。

Q：DeepSeek Harness 的 webRuntime 和 webStartup 有什么区别，为什么插件失效？ A：DeepSeek Harness 的 webRuntime 与 webStartup 都是插件访问 Web 服务的入口，0.2.1 删除了前者、保留后者，并调整了信任配置。插件如果仍写 inject: webRuntime，服务不存在就停在 pending，不会报错；依赖它注册的路由自然全部消失。

Q：怎么确认 DeepSeek Harness 的 405 是插件 pending，而不是路由写错？ A：DeepSeek Harness 的 405 若来自 pending 插件，插件列表会有 pending (waiting for service: webRuntime)，且响应体为空。路由写错通常返回 404 或带错误信息；pending 插件对应的请求会落到静态兜底，同一插件的所有 API 一起失效。

Q：不想升级插件，DeepSeek Harness 里能直接改 webRuntime 引用吗？ A：DeepSeek Harness 里可以直接改插件构建产物，把 inject 和 ctx.webRuntime 的引用改成 webStartup，通常只有两三处。但这是本地补丁，插件下次更新会被覆盖，适合临时救急；长期还是升级到适配 0.2.1 的版本。