dsh-local-plugin-switch · 设置页「本地插件开关」
在 DSH 设置页里列出所有本地已安装插件,每个配一个开关:拨动即实时启停该
Loader 条目的 fiber,并把 disabled: true|false 落盘到当前 profile 的
cordis.patch.yml,因此重启后仍然生效。
宿主基础设施行显示为「宿主」且不可开关——关掉它们会连带弄坏这个页面自己。
插件 = 宿主 HTTP 路由(/dsh-local-plugin-switch/list|toggle)+ 浏览器端设置分区
(Slot settings.section,id local-plugin-switch)。
特性
- 实时开关:
entry.update({ disabled: true | null }, false, true) 立即停/启目标条目
的 fiber(宿主侧服务与路由随之上下线),无需重启实例。
- 持久化:同时把
- id: <rowId> + disabled: true|false 追加到 profile 的
cordis.patch.yml;重新启用时删除该行,并在文件被清空时还原空列表占位符 []。
- 自包含补丁编辑器:不依赖
dsh-market,lib/index.js 自带一份最小行级 YAML
读写(跳过 - insert: 块内的行,拒绝在顶层 flow 结构后追加)。
- 原生/宿主标记:模块名以
@deepseek-ai/ 或 cordis: 开头显示「原生」标签;
命中受保护清单的行显示「宿主」且不渲染开关。
- 收藏置顶:行首 ☆/★ 收藏,存
localStorage["dsh-local-plugin-switch.favorites"];
收藏行排最前,其余保持首次加载时的顺序(刷新不会跳行)。
- 宿主零依赖:只用
node:fs / node:path / node:os / node:url,不引入 YAML 解析库。
环境要求
- DSH 当前版本服务层:宿主
ctx.inject(['webServer', 'loader']),依赖这两个服务。
- 客户端需要
slots 与 locale;package.json dsh.client 声明 platform: "web",
inject 列出 locale / runtime / ui-settings / ui-primitives 四个客户端模块。
- 需要 DSH 进程对 profile 目录有写权限(要改写
cordis.patch.yml)。
部署(重启实例 + 硬刷新)
- 拷贝插件到 profile 的 node_modules:
Copy-Item -Recurse -Force D:\DSH\design\DSHPlugin-0831\dsh-local-plugin-switch $env:DSH_HOME\profiles\web\node_modules\dsh-local-plugin-switch
- 在
$env:DSH_HOME\profiles\web\cordis.patch.yml 追加本包自带的挂载行
(即包内 cordis.patch.yml,由 dsh.bundle.patch 指向):
- insert:
- id: dsh-local-plugin-switch
name: dsh-local-plugin-switch
- 重启 DSH web 实例;浏览器硬刷新(Ctrl+F5)后,设置页出现「本地插件开关」分区。
之后即可用这个页面本身开关别的插件:宿主侧实时生效,带客户端半的插件需刷新页面,
提示文案会写明是哪一种。
配置项
没有 settings.register,因此没有设置页配置项。 唯一的入参来自加载行 config:
| 字段 | 类型 | 默认值 | 含义 |
|---|
profile | string | --profile 命令行值,再退到 'web' | 读写哪个 profile 的 cordis.patch.yml 与 node_modules |
profile 目录解析:$DSH_HOME(缺省 ~/.dsh)+ profiles/<profile>。补丁文件优先取
加载器里 cordis:include 条目的 config.path(file:// 去协议、cordis.yml →
cordis.patch.yml),找不到才退回 <profileDir>/cordis.patch.yml。
主要能力
宿主注册两条 webServer 精确路由(kind: 'exact',挂在 ctx.effect 上随 fiber 释放):
| 路由 | 方法 | 说明 |
|---|
/dsh-local-plugin-switch/list | GET / HEAD | 返回所有非分组条目 {entryId, moduleName, enabled, fiberPhase, protected};其它方法 405 |
/dsh-local-plugin-switch/toggle | POST | 请求体 {name, enabled};非 POST 405;跨源 403 untrusted origin;请求体上限 4096 字节 |
toggle 的处理顺序与返回:
- 拒绝关闭本插件自身(400),避免关掉页面赖以运行的行。
- 命中受保护清单 → 403(
宿主基础设施,禁止开关)。
- 对
options.name === name 的每个非分组条目执行实时 entry.update;任一失败 → 502。
- 按
rowIdsForPackage 找出该包名对应的行 id,写入或删除补丁行。
- 返回
{ ok, restart, refresh, reason, rows }:restart 表示实时状态与期望不一致;
refresh 表示 <profileDir>/node_modules/<name>/package.json 声明了 dsh.client
(即有客户端半,需刷新页面)。
客户端注册 Slot settings.section(id local-plugin-switch,order 90,label 取自
locale 命名空间 settings.localPluginSwitch,含 zh/en 两套文案),每个条目一行:
状态点按 fiberPhase 着色(0 pending / 1 loading / 2 active / 3 failed / 4 null / 5 unloading),切换请求进行中所有开关置灰(aria-busy)。
文件结构
dsh-local-plugin-switch/
├── package.json # 包清单:main/exports、dsh.bundle.patch、dsh.client(platform web + 4 个 inject)
├── cordis.patch.yml # 本包提供的挂载行(insert id/name = dsh-local-plugin-switch)
└── lib/
├── index.js # 宿主半:两条 webServer 路由 + loader 实时开关 + cordis.patch.yml 行级读写 + 受保护清单
└── client.js # 浏览器半(预打包 __ModuleLoader__ bundle):设置分区 UI、收藏、locale、内联 CSS
验收清单
- 设置页出现「本地插件开关」分区,标题右侧显示条目数(
N 个)。
- 每行显示模块名 + 条目 id;
@deepseek-ai/*、cordis:* 行带「原生」标签。
- 宿主基础设施行显示「宿主」,没有开关。
- 关掉一个带客户端半的插件 → 提示「已切换,刷新页面生效」;刷新后其 UI 消失。
- 重启实例后被关掉的插件仍是关闭状态(补丁行已写入)。
$env:DSH_HOME\profiles\web\cordis.patch.yml 末尾应出现 - id: <rowId> + disabled: true。
备注 / 已知限制
- 只处理非分组条目:
entry.options.group 为真的条目在列表与开关里都被跳过。
- 补丁写回是行级启发式,不是 YAML 解析器:只识别
- id: X 紧跟两空格缩进的
disabled: true|false;行 id 必须匹配 /^[A-Za-z0-9_.-]+$/,否则写入失败并返回 reason。
文件末尾若是顶层 flow 结构(以 [/{ 起头)会拒绝追加。
- 受保护清单硬编码在
lib/index.js(注释说明移植自 dsh-market),按
cordis:、@deepseek-ai/cordis-plugin-、@deepseek-ai/dsh-* 等前缀匹配;
清单没覆盖到的内置模块在页面上是可开关的。
toggle 只做同源校验(Origin 的 host 等于 Host),本机任意工具都可直接 POST。
- 客户端
lib/client.js require('@deepseek-ai/dsh-client-ui-primitives') 取到 primitives
后未使用(UI 全部用 react/jsx-runtime 手写);dsh.client.inject 里的
dsh-client-locale / dsh-client-runtime 也未在该 bundle 中 require——属声明与实现
不一致,不影响运行。
- 部署现状(撰写本 README 时的快照):本机
$env:DSH_HOME\profiles\web\cordis.patch.yml
中尚无本插件的 insert 行,profiles\web\node_modules\ 下也没有该包目录;工作区
config\profiles-web\cordis.patch.yml 模板里已列出该行——需先按上面「部署」拷贝并挂载。