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）

1. 扫描 dist 目录下的所有 .tgz 文件
2. 按插件名分组，按版本号排序
3. 提供 RESTful API 接口
4. 执行归档、恢复、清理操作

Client 半（client.js）

1. 在设置页注册「插件归档」小节
2. 实时轮询归档状态
3. 提供交互式管理界面
4. 调用 Host API 执行操作

使用场景

1. 发布新版本后

• 运行 pnpm pack 生成新的 .tgz 文件
• 在设置页点击「📦 一键归档所有」
• 旧版本自动移至归档目录

2. 需要恢复旧版本

• 在归档详情中找到目标版本
• 点击「恢复」按钮
• 旧版本复制回 dist 根目录

3. 清理存储空间

• 在插件列表中点击「🗑️ 清理」
• 或点击「🗑️ 清理所有归档」
• 归档目录中的旧版本被删除

注意事项

1. 路径安全：所有文件操作都经过路径验证，防止路径穿越攻击
2. 错误处理：所有操作都有完善的错误处理和用户反馈
3. 实时更新：状态变化后自动刷新界面
4. 配置持久化：配置存储在插件目录下，跨重启保持

版本历史

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 管理界面
• 一键归档和清理

---

最后更新：2026-08-16