DeepSeek Harness 插件：本地插件开关 (`dsh-local-plugin-switch`)

前言¶

DeepSeek Harness (DSH) 的核心设计理念是「一切皆插件」。在本地开发环境中，通过配置文件管理插件的状态（disabled 字段）是标准做法，但这通常需要手动编辑 YAML 文件并重启实例。对于频繁调试或需要快速启停某些 Loader 条目（fiber）的开发者来说，缺乏可视化的控制手段会增加操作成本。

dsh-local-plugin-switch 是一个用于在 DSH 设置页增加「本地插件开关」分区的插件。它列出了当前 profile 中已安装的非分组插件，允许用户通过点击开关实时启停对应的 fiber，并将状态持久化写入配置文件。

核心能力¶

实时开关与持久化¶

插件宿主通过调用 entry.update({ disabled: true | null }, false, true) 立即停止或启动目标条目的 fiber，无需重启 DSH 实例。同时，它会将操作结果以 - id: <rowId>\n disabled: true|false 的形式追加到当前 profile 的 cordis.patch.yml 文件中。重启实例后，插件会读取该文件并保持关闭状态。

自包含补丁编辑器¶

插件不依赖外部市场（dsh-market），在 lib/index.js 中内置了一个最小化的 YAML 读写逻辑。它采用启发式匹配来处理行级补丁写入（例如识别 - id: X 后紧跟两空格缩进的 disabled 字段），支持追加新行和删除旧行。

标记与筛选¶

原生/宿主识别：模块名以 @deepseek-ai/ 或 cordis: 开头的条目会显示「原生」标签；命中受保护清单的条目显示「宿主」，且不可关闭（受保护清单硬编码在 lib/index.js 中，防止误关基础设施导致页面失效）。
分组过滤：插件列表仅包含 entry.options.group 为 false 的非分组条目。
收藏置顶：支持在行首添加 ☆ 或 ★ 进行收藏，状态保存在浏览器的 localStorage 中，刷新后收藏项会排在最前。

零依赖架构¶

宿主侧仅使用 Node.js 内置模块（node:fs, node:path, node:os, node:url），不引入 YAML 解析库，降低了依赖复杂度。

接口与插槽¶

宿主路由¶

插件在宿主注册了两条精确路由（kind: 'exact'），挂载在 ctx.effect 上随 fiber 释放：

路由	方法	说明
`/dsh-local-plugin-switch/list`	GET / HEAD	返回所有非分组条目列表（包含 `entryId`, `moduleName`, `enabled`, `fiberPhase`, `protected`）。
`/dsh-local-plugin-switch/toggle`	POST	接收 `{name, enabled}` 请求体。请求体上限 4096 字节。支持同源校验，任意工具可直接 POST。

设置页插槽¶

客户端通过注册 settings.section 插槽（id: local-plugin-switch）在设置页面生成分区。该分区包含条目列表、开关控件以及基于 fiberPhase 的状态着色（0 pending / 1 loading / 2 active / 3 failed / 4 null / 5 unloading）。

部署与启用¶

本插件目前没有标准安装命令，需按以下步骤手动挂载：

拷贝文件：将插件目录拷贝到 profile 的 node_modules 下。

    Copy-Item -Recurse -Force .\dsh-local-plugin-switch $env:DSH_HOME\profiles\web\node_modules\

挂载插件：在 profile 的 cordis.patch.yml 末尾追加本包自带的挂载行（即包内 cordis.patch.yml 的内容）：

    - insert:
        - id: dsh-local-plugin-switch
          name: dsh-local-plugin-switch

重启与刷新：重启 DSH web 实例，并在浏览器执行硬刷新（Ctrl+F5）。

典型用法¶

部署完成后，在 DSH 设置页会出现「本地插件开关」分区。用户可以：
* 查看当前所有本地插件及其状态。
* 点击开关实时停用插件（宿主侧服务立即下线）。
* 刷新页面后，再次打开设置页，之前关闭的插件状态保持关闭。

对于标记了客户端半（dsh.client）的插件，关闭后页面通常会提示「已切换，刷新页面生效」。

限制与注意事项¶

补丁解析限制：补丁写回逻辑是启发式的，并非完整的 YAML 解析器。它只识别特定格式的行，行 ID 需匹配正则 /^[A-Za-z0-9_.-]+$/，否则写入会失败。
安全边界：toggle 路由仅做同源校验，这意味着本机任意工具都可以直接向该接口发送 POST 请求来开关插件。
代码不一致：客户端代码中声明了 @deepseek-ai/dsh-client-ui-primitives 等依赖，但实际实现中并未使用这些模块（均为手写 UI），这属于声明与实现的不一致，不影响运行。

总结¶

dsh-local-plugin-switch 为 DSH 本地开发提供了一个轻量级的插件管理入口。它通过原生插槽和 HTTP 路由，在无需引入重型依赖的情况下，实现了可视化的开关控制和配置持久化。适合需要在本地环境中频繁调试或管理 Loader 状态的开发者。

项目主页: GitHub
目录页: SkillHub