jcleener/dsh-local-plugin-switch

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:  +   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）。

部署（重启实例 + 硬刷新）

1. 拷贝插件到 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

2. 在 $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

3. 重启 DSH web 实例；浏览器硬刷新（Ctrl+F5）后，设置页出现「本地插件开关」分区。

之后即可用这个页面本身开关别的插件：宿主侧实时生效，带客户端半的插件需刷新页面，
提示文案会写明是哪一种。

配置项

没有 settings.register，因此没有设置页配置项。 唯一的入参来自加载行 config：

| 字段 | 类型 | 默认值 | 含义 |
|---|---|---|---|
| profile | string | --profile 命令行值，再退到 'web' | 读写哪个 profile 的 cordis.patch.yml 与 node_modules |

profile 目录解析：$DSH_HOME（缺省 ~/.dsh）+ profiles/。补丁文件优先取
加载器里 cordis:include 条目的 config.path（file:// 去协议、cordis.yml →
cordis.patch.yml），找不到才退回 /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 的处理顺序与返回：

1. 拒绝关闭本插件自身（400），避免关掉页面赖以运行的行。
2. 命中受保护清单 → 403（宿主基础设施,禁止开关）。
3. 对 options.name === name 的每个非分组条目执行实时 entry.update；任一失败 → 502。
4. 按 rowIdsForPackage 找出该包名对应的行 id，写入或删除补丁行。
5. 返回 { ok, restart, refresh, reason, rows }：restart 表示实时状态与期望不一致；
refresh 表示 /node_modules//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

验收清单

1. 设置页出现「本地插件开关」分区，标题右侧显示条目数（N 个）。
2. 每行显示模块名 + 条目 id；@deepseek-ai/、cordis: 行带「原生」标签。
3. 宿主基础设施行显示「宿主」，没有开关。
4. 关掉一个带客户端半的插件 → 提示「已切换，刷新页面生效」；刷新后其 UI 消失。
5. 重启实例后被关掉的插件仍是关闭状态（补丁行已写入）。
6. $env:DSH_HOME\profiles\web\cordis.patch.yml 末尾应出现 - id:  +   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 模板里已列出该行——需先按上面「部署」拷贝并挂载。