模组系统（实验性）
桌面端提供一个 Forge 式的模组加载器：把 .zip 模组包拖进管理面板即可安装，模组可以注册命令、提供自定义歌词动画、读取播放状态，以及实现歌词动画透明视频导出等扩展能力。
先读这一段
模组由第三方提供，未经官方安全审计。启用后模组会以应用的完整权限运行，包括 Node.js 运行时和你保存在 Folia 里的全部设置（AI 服务地址与密钥也在其中）。
模组系统默认关闭，单个模组也默认禁用，启用时还会再弹一次确认窗口。请只启用你信任来源的模组。
实验阶段
当前的模组 API（apiVersion 1）仍在实验阶段，后续版本可能调整接口与权限定义，已安装的模组可能需要更新。
开启
设置 > 选项 > 实验室 > 模组系统，打开开关。- 开启后，
模组（实验性）命令和模组管理面板才会出现，加载器也才会扫描并加载模组。关闭时不会加载任何模组代码。 - 从命令面板搜索
模组进入管理面板。
只有桌面版有这个能力。
安装模组
在管理面板里，把 .zip 模组包直接拖进面板即可安装或覆盖更新。
安装时会做这些校验：
| 校验项 | 限制 |
|---|---|
| 文件类型 | 必须是 .zip |
| 包体积 | 最大 64 MB |
| 文件数量 | 最多 2000 个 |
| 路径安全 | 含不安全路径（越权解压）的包会被拒绝 |
| 清单 | 必须含唯一的 mod.json 且格式有效 |
| 入口文件 | mod.json 里声明的入口文件和视觉器文件必须存在 |
也可以点打开模组目录直接在文件管理器里查看模组所在位置。
管理
| 操作 | 说明 |
|---|---|
| 启用 / 禁用 | 单个模组的开关，启用时弹确认窗口 |
| 框选 + 批量启用 / 批量禁用 | 一次处理多个模组 |
| 重载 | 重新加载模组代码 |
| 执行 | 运行模组注册的命令 |
| 最近日志 | 查看模组的运行日志，排查加载失败 |
| 打开模组目录 | 在文件管理器中定位 |
模组还支持依赖声明、版本约束和生命周期清理。
文件变动会自动撤销信任
模组文件在你上次确认之后发生变化时，Folia 会自动禁用它并撤销既有信任，需要你确认来源无误后重新启用。
文件过多或过大导致无法校验内容指纹时，出于安全考虑同样不予启用。
透明歌词视频导出
模组可以实现歌词动画的透明视频导出。这一能力需要本机有 ffmpeg：
- 设置
FOLIA_FFMPEG_PATH环境变量，或 - 把 ffmpeg 放进应用旁的
ffmpeg-8.1.2文件夹
限制：
- 单次导出时间范围最长 15 分钟。
- Alpha 通道（透明背景）在 Windows 上有保证；其他平台可能不保留 Alpha，会导出成不透明底。这种情况下可以改用「主题背景色 + 纯文字动画」的组合，或换到 Windows 上导出。
- 当前歌曲没有可渲染的歌词时无法导出。
常见问题
找不到模组命令
先在 设置 > 选项 > 实验室 > 模组系统 里打开开关。关闭状态下这条命令不会出现。
模组装上了但功能没出现
模组安装完成后仍是禁用状态，需要在列表里单独启用并确认。如果启用失败，看最近日志。
模组突然被禁用了
模组文件在上次确认之后被改动过，信任已自动撤销。确认来源无误后重新启用即可。