dsh-hotswap：DeepSeek Harness 运行时插件热插拔管理器

前言¶

DeepSeek Harness (DSH) 的设计理念是「一切皆插件」。在实际开发或调试过程中，如果需要启用/停用某个插件，或者挂载/卸载一个新的 bundle，通常需要重启 dsh web 进程，这会打断当前的工作流。

dsh-hotswap 是一个 Web 插件热插拔管理器，由 HongzhongL 维护。它解决了这个问题，允许你在不重启 dsh web 的情况下，运行时启用、停用或重启 Cordis 插件，并自动同步 profile 中的 bundle 配置。

核心功能¶

1. 运行时热启停¶

插件通过调用 Loader 的 entry.update({ disabled: true/false }) 接口实现热插拔。
* 热停用：调用该接口后，插件当场卸载，服务、工具、监听器等资源会被立即回收。
* 热启用：调用该接口后，插件会当场重新导入并启动，包括那些启动时处于停用状态的插件。

2. 热重启与 Bundle 同步¶

热重启：插件支持卸载后重新加载，并尽力清除 Node ESM 模块缓存以尝试加载磁盘上的新代码（此过程为 best-effort）。
Bundle 自动同步（热挂载）：插件会监视 profile 的 package.json 中的 dsh.profile.bundles 配置。当配置条目发生增删时，它会通过 Include 根分组自动执行热挂载或卸载，无需手动重启。

3. 持久化与配置管理¶

持久化：每次开关插件的状态，插件都会将 disabled: true 写入 profile 的 cordis.patch.yml 文件中，并维护一个名为 # === dsh-hotswap managed block === 的自动区块。这样重启 dsh web 后，开关状态依然生效。
外部停用识别：插件能识别 cordis.patch.yml 中手写的 disabled: true 行。当你在界面上启用插件时，它会同步移除该配置行，避免状态不一致。

4. 安全护栏¶

为了防止误操作导致系统崩溃，插件内置了安全机制：
* 保护名单：webserver、connection、api-gateway、modules、typert*、web*、hmr 等关键条目以及插件自身本身不能被停用。
* 表达式控制：受 !!js 表达式控制的条目或父分组被停用的条目，不允许切换状态。
* 一键恢复：提供「全部恢复」功能，重新启用所有由管理器停用的插件。

安装与配置¶

安装¶

通过 DSH 的 CLI 工具安装该插件：

dsh plugin --profile web add dsh-hotswap
# 安装完成后，需要重启 dsh web 才能生效
dsh web

配置（可选）¶

插件支持通过 profile 的 cordis.patch.yml 进行覆盖配置：

- id: dsh-hotswap
  config:
    profile: web              # 持久化目标 profile（默认从 Loader baseUrl 推导）
    protected: [some-id]      # 追加不可停用的条目 id

使用方式¶

界面操作¶

安装完成后，在 DSH Web 的 设置 → 插件 → 「插件管理」 标签页中，可以看到当前挂载的所有 Cordis 插件列表。列表支持搜索和筛选，并显示每个插件的状态灯和徽章。

每个插件条目右侧提供了开关和重启按钮，点击即可执行热启停或热重启操作。

配置文件修改¶

在 profile 的 package.json 中修改 dsh.profile.bundles 配置，保存后，dsh-hotswap 会自动检测变化并执行对应 bundle 的热挂载或卸载。

恢复关键插件¶

如果误停了关键插件导致界面无法操作，可以编辑 UI 上显示的持久化文件（cordis.patch.yml），手动删除 dsh-hotswap 的自动区块，然后重启 dsh web 即可恢复。

注意事项与限制¶

安全风险¶

本插件暴露了同源的 HTTP 端点（/_dsh/hotswap/*），且不额外加鉴权。
* 仅本地安全：只要 Web 服务绑定在 127.0.0.1，就只有本机进程能调用，相对安全。
* 局域网风险：如果 webserver 的 host 设为 0.0.0.0 暴露到局域网，局域网内任何设备都能控制你的插件（进而驱动 agent）。切勿暴露到不可信网络。
* 来源校验：来源校验（isSameOrigin）只拦截带 Origin 头的跨站请求；无 Origin 头的本机程序（如 curl）会被放行。这意味着不要与不信任的进程共享这台机器。

兼容性¶

本插件开发/测试于 DSH 0.1.0-rc.6。
热重启与代码重载依赖 Cordis Loader 的内部 API（entry._dispose / entry.refresh / loader.internal），这些不是公开契约。升级 DSH 后，这些 API 可能发生变化，升级前需确认兼容性。

已知限制¶

客户端 UI 延迟：停用某个插件后，已经打开的页面里它注入的客户端 UI（如设置页标签）需要刷新页面后才会消失。
ESM 缓存：热重启的「代码重载」是 best-effort，Node ESM 模块缓存无法被可靠失效，多数情况下只是卸载后重新 apply，未必能读取到磁盘上的新代码。
Headless 模式：headless profile 没有 webServer，本插件只服务于 Web 界面，无法在 Headless 模式下工作。
持久化范围：运行时启停只影响当前进程；持久化只覆盖本管理器经手的开关。手动写在围栏外的配置行不会被改动（除非点击「启用」时顺手移除）。