Slopsmith 插件开发快速入门：20 行代码写出你的第一个 plugin.json 插件

Slopsmith 是一款自托管的 Docker Web 应用，用于浏览、播放和练习交互式全乐队乐谱（吉他、贝斯、键盘、鼓与人声），最吸引开发者的正是它强大的插件系统。本教程带你从零开始，用约 20 行代码写出第一个 Slopsmith 插件——一份 plugin.json 清单加最小前后端文件，重启容器即可在导航栏看到它。

🧩 先认识 Slopsmith 插件系统：30 秒看懂机制

Slopsmith 的插件就是一个放在plugins/目录下的文件夹。启动时，插件加载器 plugins/init.py 会自动发现每个子目录中的plugin.json清单文件，然后按声明挂载：

• 导航链接（nav）——出现在顶部导航栏
• 独立页面（screen.html+screen.js）——插件自己的完整界面
• 设置面板（settings.html）——注入到 Settings 页
• 后端 API（routes.py）——注册在/api/plugins/<插件id>/下的 FastAPI 路由

上图：Slopsmith 曲库浏览器。顶部导航栏里 “Create from Tab”“Download CDLC” 等入口，正是插件通过nav字段自动挂载的结果——你的第一个插件也会出现在这个位置。

插件能做的事情非常广泛：仓库自带的 3D Highway 就是一个典型例子，它把整个播放器视觉换成了带景深相机和灯光的 3D 效果。

🚀 快速开始：Docker 一键部署 Slopsmith

插件开发需要一个运行中的 Slopsmith。整个过程只需三步：

git clone https://gitcode.com/gh_mirrors/sl/slopsmith cd slopsmith DLC_PATH=/path/to/your/songs docker compose up -d

1. 克隆仓库并进入目录
2. 用DLC_PATH指向你的歌曲文件夹（PSARC 或 sloppak 歌曲）
3. 启动容器后，浏览器打开http://localhost:8000

上图：Slopsmith 播放器主界面——这也是你的插件脚本将要运行其中的环境。

📦 第一个 plugin.json：20 行代码的核心

插件清单的完整 schema 见 docs/plugin-manifest.schema.json，其中只有id和name是必填字段，其余全部按需组合。以下是本教程示例的完整plugin.json（11 行）：

{ "id": "my_first_plugin", "name": "My First Plugin", "version": "1.0.0", "nav": { "label": "My First Plugin", "screen": "plugin-my_first_plugin" }, "screen": "screen.html", "script": "screen.js", "routes": "routes.py" }

各字段速查表：

创建插件目录结构：

plugins/ my_first_plugin/ plugin.json screen.html screen.js routes.py

💡 参考真实案例：内置小游戏插件 plugins/minigames/plugin.json 还额外声明了settings.server_files（参与设置导出/导入）和diagnostics（参与诊断包导出），都是可选的进阶字段。

🖥️ 最小前端：screen.html 与 screen.js

screen.html是一段HTML 片段（不能有<html>/<body>标签），会被注入到<div class="screen">容器中，可直接使用 Tailwind 工具类：

<div class="max-w-3xl mx-auto px-6 pt-24"> <h1 class="text-3xl font-bold text-white mb-2">My First Plugin</h1> <p id="hello-output" class="text-gray-400">Loading…</p> </div>

screen.js运行在全局作用域，可访问window.playSong、window.showScreen、window.slopsmith事件总线等核心 API。建议用 IIFE 包裹，避免污染全局变量：

(function () { 'use strict'; fetch('/api/plugins/my_first_plugin/hello') .then((r) => r.json()) .then((data) => { document.getElementById('hello-output').textContent = data.message; }); })();

⚙️ 最小后端：8 行 routes.py 写出你的 API

routes.py必须导出一个setup(app, context)函数。context字典提供持久配置目录config_dir、get_dlc_dir()、元数据库meta_db、日志器log等——后端状态请写入config_dir下（该目录在 Docker 卷中持久保存）：

def setup(app, context): log = context["log"] log.info("my_first_plugin ready") @app.get("/api/plugins/my_first_plugin/hello") def hello(): return {"message": "Hello, Slopsmith!"}

路由统一注册在/api/plugins/{plugin_id}/前缀下，天然避免与其他插件冲突。注意：日志请一律使用context["log"]，不要用print()。

📥 安装与验证：重启容器即可生效

插件安装就是“丢文件夹 + 重启”，没有任何注册步骤：

1. 确认 4 个文件已放入plugins/my_first_plugin/（若用 Docker 卷挂载了插件目录，则放入对应宿主机目录）
2. 重启容器：docker compose restart
3. 刷新浏览器http://localhost:8000，顶部导航栏应出现My First Plugin入口
4. 点击导航进入插件页面，应显示后端返回的Hello, Slopsmith!
5. 也可直接访问http://localhost:8000/api/plugins/my_first_plugin/hello验证 API

✅ 看到导航链接 + 页面内容 + API 三处全部正常，恭喜你——第一个 Slopsmith 插件就跑通了。

⚠️ 常见坑位：为什么我的插件没出现

加载过程的所有警告都会以[Plugin]前缀写入服务器日志，用docker compose logs查看是最快的排错入口。

📚 进阶路线：从入门到完整插件

掌握基本骨架后，建议按以下路径升级你的插件：

• 加设置面板：plugin.json加"settings": { "html": "settings.html" }，片段会被注入 Settings 页
• 加新手引导：参考 plugins/app_tour_library/tour.json 的 spotlight 步骤格式
• 声明能力域（capabilities）：让其他插件与核心能感知你的 provider/requester 关系，详见 docs/capability-domains.md
• 写 Highway 可视化插件："type": "visualization"+window.slopsmithViz_<id>渲染器工厂，参考 plugins/highway_3d/plugin.json
• 参与诊断与备份：diagnostics与settings.server_files字段说明见 CLAUDE.md

完整插件规范（前端全局 API、playSong包装链、WebSocket 协议、load_sibling等）都在 CLAUDE.md 中，社区插件开发约定见 CONTRIBUTING.md；想写小游戏类插件可再读 plugins/minigames/README.md 中的 SDK 用法。

从这份 20 行的 plugin.json 起步，重启容器，你的功能就会出现在 Slopsmith 的导航栏里——这就是它插件系统的全部“仪式感”。🎸