dsh-my-plugins

📑 目录

• 📸 界面预览
• ✨ 功能特性
• 🚀 快速开始
• 📖 使用说明
• 🔧 工作原理
• 🧪 开发与测试
• ⚠️ 已知限制
• 🤝 贡献
• 📄 许可证

📸 界面预览

「设置 → 插件 → 我的插件」页（v1.4.0）：搜索框右侧新增「安装插件」按钮，弹窗支持 GitHub / link / file / npm 四种安装方式；插件卡片列表含版本、安装来源、配置与 Cordis 状态。

✨ 功能特性

🚀 快速开始

前提条件

• 已安装 DSH CLI 与 pnpm（dsh plugin 内部转发到 pnpm）

安装

# 方式一：从 GitHub 安装
dsh plugin --profile web add github:Ycet/dsh-my-plugins

# 方式二：从本地源码安装（开发）
dsh plugin --profile web add dsh-my-plugins@file:<absolute-path-to-plugin>

包声明了 dsh.bundle 补丁层，dsh plugin 会自动把加载项合入 profile 的 bundle 层，无需手动编辑 cordis.patch.yml。

[!NOTE] file: 安装是快照：更新源码后需重新执行安装命令，再重启 dsh web 生效（bundle 层变更不热加载）。

启动

1. 重启网页应用：dsh web
2. 打开 http://127.0.0.1:3080，进入「设置 → 插件」
3. 切换到「我的插件」标签查看全部用户安装的插件

📖 使用说明

1. 打开「设置 → 插件 → 我的插件」；
2. 安装：点击搜索框右侧「安装插件」，在弹窗中选择安装方式并输入地址/路径/包名后点击「安装」；GitHub 输入 owner/repo（可附 #分支或tag），link / file 输入本地绝对路径（link 自动读取源码 package.json 的包名），npm 输入包名（可附 @版本）；同名插件已安装时会提示确认后切换来源。安装完成后重启 dsh web 生效；
3. 批量检查：点击搜索框右侧「检查更新」可一次检查所有已安装插件；有更新的插件状态标签变为黄色「待更新」，展开卡片点击「立即更新」逐个升级；
4. 搜索：在顶部输入框按名称或介绍过滤插件；
5. 启停：点击卡片上的「禁用插件 / 启用插件」，按提示重启 dsh web 后生效；
6. 更新（GitHub 来源）：点击「检查更新」查看上游是否有新版本；有更新时点击「立即更新」，完成后重启 dsh web 生效；
7. 移除：点击「移除插件」，在二次确认弹窗中点击「确认移除」，重启 dsh web 后完成卸载。

[!NOTE] 安装、更新与移除均通过官方 dsh plugin CLI 执行；操作完成提示出现在页面右下角 toast 中，之后需在终端重启 dsh web 使改动完全生效。

🔧 工作原理

双面插件（宿主 + 浏览器）。宿主在 webServer 注册 /my-plugins/api 前缀路由（仅接受同源信任请求的 POST，按路径段分发方法）：

关键机制：

• 安装输入校验：GitHub owner/repo（可附 #ref）、npm 包名 / 版本、本地绝对路径均在服务端严格校验后才拼装 dsh plugin ... add <spec> 参数（link 方式自动读取源码目录 package.json 的 name 拼成 <name>@link:<路径>）；

• 同名安装确认：npm / link 方式可解析出包名，若 profile 中已安装同名插件，先返回确认提示，用户确认后才执行覆盖安装（支持切换安装来源，如 file: → github:）；

• 托管状态块：启停覆盖写入 profile 的 cordis.patch.yml，用 # >>> dsh-my-plugins managed states >>> 标记边界，由宿主维护，避免与手工补丁混淆；

• 来源判定：根据包元数据识别 GitHub（git+https://github.com/… 等）、本地（file: 路径）、Registry（npm 版本规格）与手工 patch 四种来源，并据此决定是否支持自动更新；GitHub 来源及 Registry 上游的 owner/repo 经客户端同规则校验后渲染为指向 https://github.com/<owner>/<repo> 的链接（新标签页打开），非法元数据回退纯文本（v1.5.0 起）；

• 更新安全性：check-update 做版本语义比较并确认已安装 commit；update 前校验 profile 内被引用的本地安装包是否失效（v1.3.6 起），存在失效依赖时拒绝更新并提示先修复安装来源；

• 移除清理：remove 成功后同步清理该插件入口对应的托管禁用状态，保持 profile 补丁文件整洁。

🧪 开发与测试

npm test   # node --test test/*.test.mjs

test/metadata.test.mjs 覆盖纯函数契约：包根解析（packageRootOf）、来源判定（sourceOf）、GitHub 元数据与版本比较（githubRepoOf / compareVersions）、patch 插入块扫描（scanPatchInsertIds）、托管状态读写（readManagedStates / writeManagedStates）、更新参数构造（updateArgsFor）与失效本地依赖检测（missingLocalDependency）；v1.4.0 起新增安装输入校验（resolveInstallSpec / splitNpmInput）、同名依赖检测（existingDependency）与 CLI 错误摘要（summarizeCliError）用例。

⚠️ 已知限制

• 自动更新仅限 GitHub 来源：Registry、本地安装与手工 patch 来源不支持自动更新，卡片会显示对应原因（upstreamAhead 表示 GitHub 上游已有新 Release，但当前 npm 安装源尚未发布可安装更新）。
• 固定引用无法跟踪：插件固定在 tag 或 commit 时无法检查分支更新；无法确认已安装 Git commit 时不会安全判断更新。
• 操作需重启生效：安装、启停、更新与移除均在重启 dsh web 后完全生效（bundle 层不热加载）。
• 安装同名覆盖：npm / link 安装解析到已安装的包名时需二次确认；github / file 方式无法预先得知包名，重复安装由 pnpm 直接处理。
• 移除即卸载：移除操作从当前 profile 删除插件依赖，属于不可逆操作，请谨慎使用。

🤝 贡献

欢迎提交 Issue 与 Pull Request：发现问题请携带 DSH 版本、插件版本与复现步骤到 Issues 反馈；改进请按 Fork → 分支 → PR 流程提交，并在提交前运行 npm test 确保契约测试通过。

📄 许可证

本项目使用 MIT 许可证。