dsh-plugin-toggle-manager

Readme

# DSH Plugin Manager

`dsh-plugin-toggle-manager` 是 DSH Web 的可视化插件管理器。安装后，在 **设置 → 插件 → 插件管理** 中管理当前 Web profile 的插件状态与搭配，而不需要手动修改 DSH 的配置文件。

- 当前版本：**1.0.0**
- 安装目标：DSH **Web** profile
- 许可证：MIT

> 本项目既可作为 npm 插件安装，也允许完整复制、Fork 或修改源码后自行打包安装。npm 安装是日常用户的推荐方式；源码方式适合开发、审查和二次开发。

## 基础功能

### 插件状态

- 显示 Cordis Loader 当前识别到的插件；
- 支持按插件名称或 Loader ID 搜索；
- 分开显示 **插件总数**、**当前已启用数量** 与 **非官方插件总数**；
- 对可安全管理的非官方插件提供启用/停用操作。

### 插件搭配（Plugin sets）

- 可从当前状态创建搭配；
- 可从原始配置创建搭配：不预先选择可选的非官方插件，但始终保留 DSH 必需组件和管理器；
- 可编辑、保存并应用多套插件组合；
- 删除搭配只会删除搭配记录，不会删除插件，也不会直接改变当前状态。

### 删除第三方插件

对当前 Web profile **直接安装**、且被明确识别为非官方的插件，提供带二次确认的删除入口。删除会清理相关的 profile 依赖、已知启动配置、搭配引用、锁文件记录与该 profile 的安装链接。

DSH Harness / DSH Web 核心组件、插件管理器自身和插件分组均受保护，不能从本界面停用或删除。

## 推荐安装：通过 npm + npx

发布到 npm 后，普通用户不需要克隆源码、不需要全局安装 DSH，也不需要手动复制文件。直接在 PowerShell 中执行：

```powershell
npx --yes --package @deepseek-ai/dsh dsh plugin --profile web add dsh-plugin-toggle-manager
```

含义是：

1. `npx --package @deepseek-ai/dsh` 临时获取 DSH 命令；
2. `dsh plugin --profile web add` 在正确的 Web profile 中调用 pnpm；
3. `dsh-plugin-toggle-manager` 未指定版本号，npm 会安装该包 `latest` 标签指向的最新稳定版；
4. DSH 自动把声明了 `dsh.bundle.patch` 的插件加入 profile bundle 列表。

安装成功后，打开或刷新 DSH Web，在 **设置 → 插件 → 插件管理** 中查看页面。

> 不写版本号不代表已经安装的插件会自行更新。需要更新时，重新执行一次相同的安装命令；它会重新解析 npm 的 `latest` 标签。

如果电脑已经安装了 `dsh` 命令，也可以使用等价的简短写法：

```powershell
dsh plugin --profile web add dsh-plugin-toggle-manager
```

如果你的 npm / pnpm 被配置为第三方镜像，并且刚发布的版本尚未同步到镜像，可在包名后追加 npm 官方 registry 参数：

```powershell
npx --yes --package @deepseek-ai/dsh dsh plugin --profile web add dsh-plugin-toggle-manager --registry=https://registry.npmjs.org/
```

### 更新

日常更新直接重复推荐安装命令即可：

```powershell
npx --yes --package @deepseek-ai/dsh dsh plugin --profile web add dsh-plugin-toggle-manager
```

它等价于显式写 `@latest`：

```powershell
npx --yes --package @deepseek-ai/dsh dsh plugin --profile web add dsh-plugin-toggle-manager@latest
```

只有需要固定到某个历史版本、复现问题或测试指定版本时，才写版本号：

```powershell
npx --yes --package @deepseek-ai/dsh dsh plugin --profile web add dsh-plugin-toggle-manager@1.0.0
```

常规的 `npm publish` 会把稳定版发布到 `latest` 标签；若以后发布 beta / next 测试版，应让测试用户显式使用对应标签，例如 `@beta` 或 `@next`。

> 这里的 `npx` 运行的是 **DSH CLI**，不是本插件自身的可执行文件；这是为了让插件始终安装到 DSH 的正确 profile 中。

## 从源码安装或二次开发

可以复制、Fork 或克隆本仓库的全部源码。源码目录本身不是可直接加载的 DSH profile 依赖；请先将源码打成 npm tarball，再交给 DSH 安装。

```powershell
# 进入复制或克隆得到的项目根目录
npm run check

# 使用临时 npm 缓存打包，不污染全局 npm 缓存
$cache = Join-Path $env:TEMP 'dsh-plugin-manager-npm-cache'
npm pack --cache $cache

# 安装刚生成的本地包
$package = (Resolve-Path '.\dsh-plugin-toggle-manager-1.0.0.tgz').Path
npx --yes --package @deepseek-ai/dsh dsh plugin --profile web add $package
```

本项目没有运行时依赖需要在源码目录执行 `npm install`。DSH 运行所需的 peer dependencies 由目标 DSH Web profile 提供。

### 修改源码后的建议

1. 修改 `lib/index.js`、`lib/client.js` 或 `cordis.patch.yml`；
2. 执行 `npm run check`；
3. 修改了功能时，应提高 `package.json` 的版本号；
4. 执行 `npm pack --cache $cache`；
5. 用上面的 `npx ... dsh plugin ... add <本地 tgz>` 命令安装新包。

不要在相同版本号下反复覆盖已经被 profile 引用的本地 `.tgz` 文件。版本升级后重新安装新 tarball，更容易保持 pnpm 锁文件与内容一致。

## 从旧的本地包迁移到 npm 版

早期本地包使用的是 `@deepseek-ai/dsh-plugin-toggle` 这个内部/本地名称，不能作为普通用户发布到 npm。公开 npm 版使用名称 **`dsh-plugin-toggle-manager`**，功能和版本号仍是 **1.0.0**。

同一 Web profile 不应同时保留两个管理器，否则它们会注册相同的 `plugin-toggle` 服务条目。首次迁移时按顺序执行：

```powershell
# 1. 移除旧的本地/内部包
npx --yes --package @deepseek-ai/dsh dsh plugin --profile web remove @deepseek-ai/dsh-plugin-toggle

# 2. 安装 npm 上的公开包
npx --yes --package @deepseek-ai/dsh dsh plugin --profile web add dsh-plugin-toggle-manager
```

执行第一步后管理页会暂时消失；第二步安装成功后，刷新或重新打开 DSH Web 即可恢复。不要手动删除 `node_modules` 目录来代替这两个命令。

## 配置与安全边界

- 插件启用/停用写入当前 Web profile 的用户 `cordis.patch.yml`；
- 插件搭配写入当前 Web profile 的 `dsh-plugin-toggle.presets.json`；
- 安装、更新和卸载由 DSH 的 `plugin` 命令处理 profile 的 `package.json`、`pnpm-lock.yaml` 和 bundle 配置；
- 关键配置写入前会创建 `.bak` 恢复点；被用户确认删除的第三方插件代码目录不会自动归档。

本插件只操作当前 DSH Web profile，不扫描或删除任意磁盘目录。第三方插件的热插拔支持程度可能不同；个别前端资源在停用或删除后可能需要手动刷新或重新打开 DSH Web。

## 开发检查

```powershell
npm run check
$cache = Join-Path $env:TEMP 'dsh-plugin-manager-npm-cache'
npm pack --dry-run --cache $cache
```

发布包应只包含以下六项：

```text
package/LICENSE
package/README.md
package/package.json
package/cordis.patch.yml
package/lib/index.js
package/lib/client.js
```

## 发布到 GitHub 和 npm

- GitHub 作为源码仓库：提交源码、文档和许可证；
- npm 作为用户安装来源：发布 `dsh-plugin-toggle-manager`；
- 详细的上传顺序、应提交/忽略的文件和 npm 发布命令见 [PUBLISHING.md](PUBLISHING.md)。

## 兼容性

本版本在 DSH **0.1.0-rc.6** 的 Web profile 中构建和验证。包使用以下 peer dependencies：

- `@deepseek-ai/cordis`：`^4.0.1`
- `@deepseek-ai/cordis-plugin-loader`：`^1.0.2`
- `@deepseek-ai/dsh-host-webserver`：`^0.1.0-rc.5`

不同 DSH 版本与第三方插件可能存在行为差异。升级 DSH 或批量调整插件之前，建议先保留 profile 配置备份。

## 许可证

MIT，详见 [LICENSE](LICENSE)。