dsh-dist-manager · 插件分发目录管理插件
曾用名 dist-archive-plugin（2026-08-16 更名：消除与它管理的 dist/ 数据目录的名字混淆）。
自动管理插件分发目录（dist/）的版本归档：将旧版本移至归档目录，保留最新版本在 dist 根目录。提供 WebUI 管理界面，支持一键归档、恢复版本、清理归档等操作。
功能特性
核心功能
- 自动归档：自动扫描 dist 目录下的插件包，按插件名分组，按版本号排序
- 版本管理：保留最新版本，将旧版本移至归档目录
- WebUI 管理：在设置页 → 插件归档 小节提供完整的管理界面
- 一键操作：支持一键归档所有插件、一键清理所有归档
管理功能
- 查看状态：实时显示插件总数、当前版本数、已归档版本数
- 单个归档：对特定插件执行归档操作
- 版本恢复：从归档目录恢复特定版本到 dist 根目录
- 归档清理：清理特定插件或所有插件的归档
安装 / 打包
# 安装（装完重启 WebUI 生效）
dsh plugin --profile web add <插件目录>
# 打包归档（产物输出到你的 dist 目录）
pnpm pack --pack-destination <你的插件分发目录>
# 卸载
dsh plugin --profile web remove dsh-dist-manager
dsh 请替换为你自己 DSH 安装对应的 CLI 调用方式。
界面行为
设置 → 插件归档
- 统计卡片：显示插件总数、当前版本数、已归档版本数
- 操作按钮：
- 📦 一键归档所有：将所有插件的旧版本移至归档目录
- 🗑️ 清理所有归档：删除所有归档目录
- 插件列表：显示每个插件的详细信息
- 最新版本号
- 版本总数
- 已归档版本数
- 单个归档/清理按钮
- 归档详情：显示每个插件的归档版本列表，支持恢复操作
API 接口
GET /dist-manager/status - 获取归档状态摘要GET /dist-manager/details - 获取详细归档信息POST /dist-manager/archive - 执行归档操作POST /dist-manager/restore - 恢复特定版本POST /dist-manager/clean - 清理归档GET /dist-manager/config - 获取配置POST /dist-manager/config - 更新配置
配置
配置读取优先级：cordis.yml 的 Config 字段（apply(ctx, config)）> config.json 文件 > 默认路径。
link 安装时写 config.json；tgz 安装时建议直接在 cordis.yml 里配：
{
"distDir": "<你的插件分发目录>/dist",
"archiveDir": "<你的插件分发目录>/dist/archive",
"autoArchive": true,
"keepVersions": 1
}
不配置时默认取插件目录上级的 dist/（link 安装场景），无需改配置即可使用。
配置项说明
distDir：dist 目录路径archiveDir：归档目录路径autoArchive：是否自动归档（预留功能）keepVersions：保留的版本数量（预留功能）
目录结构
dist/
├── 插件1-最新版本.tgz
├── 插件2-最新版本.tgz
├── archive/
│ ├── 插件1/
│ │ ├── 插件1-旧版本1.tgz
│ │ └── 插件1-旧版本2.tgz
│ └── 插件2/
│ └── 插件2-旧版本1.tgz
└── dsh-dist-manager/ ← 本插件（管理上面这个 dist/）
工作原理
Host 半（index.js）
- 扫描 dist 目录下的所有
.tgz 文件
- 按插件名分组，按版本号排序
- 提供 RESTful API 接口
- 执行归档、恢复、清理操作
Client 半（client.js）
- 在设置页注册「插件归档」小节
- 实时轮询归档状态
- 提供交互式管理界面
- 调用 Host API 执行操作
使用场景
1. 发布新版本后
- 运行
pnpm pack 生成新的 .tgz 文件
- 在设置页点击「📦 一键归档所有」
- 旧版本自动移至归档目录
2. 需要恢复旧版本
- 在归档详情中找到目标版本
- 点击「恢复」按钮
- 旧版本复制回 dist 根目录
3. 清理存储空间
- 在插件列表中点击「🗑️ 清理」
- 或点击「🗑️ 清理所有归档」
- 归档目录中的旧版本被删除
注意事项
- 路径安全：所有文件操作都经过路径验证，防止路径穿越攻击
- 错误处理：所有操作都有完善的错误处理和用户反馈
- 实时更新：状态变化后自动刷新界面
- 配置持久化：配置存储在插件目录下，跨重启保持
版本历史
v0.1.1 (2026-08-16)
- 更名：包名/目录
dist-archive-plugin → dsh-dist-manager（消除与 dist/ 数据目录的名字混淆；API 路径 /dist-archive/* → /dist-manager/*）
- 修复：清理归档按钮请求体错误（单个清理/全部清理都失效）
- 修复：插件名/版本号路径白名单校验落地（防路径穿越）
- 变更：配置支持
apply(ctx, config)（cordis.yml 可改），tgz 安装也可用
v0.1.0 (2026-08-16)
- 初始版本
- 基础归档功能
- WebUI 管理界面
- 一键归档和清理
姊妹仓库
同族的其它 DSH 插件（各一个独立仓库）：
许可
双许可——文档与代码分开：
- 代码（
index.js、client.js 与其它源文件）：MIT —— 拿去用、改、再发，保留版权声明即可。
- 文档（本 README 的正文）：CC BY 4.0 —— 可以自由使用、改编、连商用都行，但要署名（莉娅 / @feverZHONG）并注明来源。
两份许可的全文：LICENSE（MIT）／LICENSE-DOCS（CC BY 4.0）。
最后更新：2026-10-02 · 莉娅（@feverZHONG）· 宇宙美好记录官
