创意工坊开发指南
这篇给准备自己制作 ECHO Steam 创意工坊内容的作者。只想订阅和启用作品,请看 Steam 创意工坊。下面以 2026-10-23 核对的源码、SDK 1.21.0 为依据;源码版本不代表 GitHub Release 和 Steam 起步包已更新到同一版。下载前核对 最新 GitHub Release 内实际提供的 .tgz,并在本地运行 version --json。
SDK 1.21:当前能力与兼容检查
Section titled “SDK 1.21:当前能力与兼容检查”SDK 1.21.0 的变更记录日期为 2026-10-18,新增接口要求包含对应实现的 ECHO 26.10.18 或更新宿主。SDK、Steam 应用和工坊起步包各自发布;安装新版 SDK 不会升级订阅者的宿主。
- 曲库、歌单、收藏、个人标签与稍后听支持分页工作流。
- 歌词、元数据和封面提供器统一候选搜索、预览、应用、拒绝与取消;曲库或缓存更新不会自动写入源文件。
- 插件可按声明和批准使用队列、输出设备、首页统计及歌词创作接口;音频事实和播放时钟仍由宿主持有。
- Afterglow 场景包可使用绘图原语、配色和动效组合歌词背景,沿用
lyrics-style类型。 - 调用新接口前使用
echo.host.getFeatureAvailability()检查实际能力。模拟预览通过不代表已在 Steam 发布物中可用。
先选作品类型
Section titled “先选作品类型”| 想做什么 | --kind / 起步方式 | 主要边界 |
|---|---|---|
| 配色、整包 CSS、宿主界面 | theme,如 --recipe css-theme | 样式作用域受限;自绘 UI 在沙箱中 |
| 歌词排版或纯背景 | lyrics-style;背景用主题的 lyrics-background runtime | 歌词与播放事实由宿主提供 |
| 可复用歌词动效 | animation-library | 仅有界关键帧数据,由宿主执行,不运行作者脚本 |
| 频谱或均衡预设 | visualizer-preset / dsp-preset | DSP 参数由 Audio Core 实际执行 |
| 本机 VST3 接入说明 | audio-plugin-profile | 不附带厂商插件或安装程序 |
| 新语言文案 | locale-pack | 缺失文案回退到内置语言 |
| 命令、面板、音源或歌词提供器 | plugin-package | 默认隔离沙箱,能力按权限声明 |
| Windows 系统壳程序 | native-shell | 便携 SDK 能创建;官方 Steam 工坊仍拒绝订阅者 .exe / .dll |
从简单类型开始。主题、歌词场面、可视化与 DSP 和 沙箱插件 有逐项教程。
建立并检查第一个项目
Section titled “建立并检查第一个项目”作者本机需要 Node.js 20+。SDK 不发布到 npm 公共仓库;可以克隆 SDK 仓库,或安装 GitHub Release 实际附带的 .tgz。下面是在克隆后的 SDK 根目录运行的 Windows PowerShell 示例:
node .\bin\echo-workshop-sdk.mjs version --jsonnode .\bin\echo-workshop-sdk.mjs init .\my-theme --recipe css-themecd .\my-themenpm run nextnpm run checknpm run dev编辑 content/ 的主题、歌词或预设 JSON;插件主要编辑 src/plugin.js。check 会先同步生成 content/community.echo 和清单哈希,再做结构、质量和 fixture 检查。不要手改生成的包与 SHA-256。 dev 是本地模拟控制台;保存时持续检查可运行 npm run watch。它们通过后,仍需在 Steam 版 ECHO 的创作台验证真实宿主效果。
SDK 1.17:把插件面板做成侧边栏页面
Section titled “SDK 1.17:把插件面板做成侧边栏页面”插件内层清单 manifest.contributes.panels 可给一个已打包的 HTML 面板声明 placement: "page"。例如已有 desk.html 的插件,在其内层插件清单中增加以下条目;不要把它误放进外层 content/echo.workshop.json:
{ "contributes": { "panels": [{ "id": "desk", "title": "资料台", "description": "我的曲库工具", "path": "desk.html", "placement": "page", "group": "library", "icon": "library" }] }}这是清单片段,须合并进 SDK 生成的完整内层清单,并确保 desk.html 被打包。ECHO 26.9.25+ 会把页面放在原生侧边栏、主内容区仍由同一隔离 iframe 渲染;标题栏、侧栏和播放栏属于宿主。旧宿主把它当普通 main 面板。新版源码已移除旧版的 8 个页面声明与 24 个侧栏页面配额;旧宿主仍可能保留限制,请按目标版本验证。group 可选 library、sources、playback、plugins。
插件可用 echo.ui.openPanel('desk') 打开已声明面板,或用 echo.navigation.open('plugin:<插件 id>:desk') 打开自己的页面;打开自己的页面无需 navigation 权限。页面里的 echo.ui.closePanel() 返回先前的内置页面。用 echo.ui.getContext() / onContextChanged() 适配语言、窗口尺寸、明暗主题和减少动效;可见面板可用 setPanelPresentation() 更新标题、徽标和注意状态。immersive 在 page 上仅隐藏宿主标题,不会盖住侧栏或播放栏。
同版还允许 mainMenus(可选快捷键)、trackContextMenus 的 selection: "multiple" 和 columns。这些条目都指向已声明的 commandId。批量菜单最多传 100 首当前选中歌曲;列命令每次最多处理 40 首可见歌曲,返回的文字最多 24 字符,歌曲行最多显示两个标签。先从 插件教程 的命令示例起步,再按 SDK 的 plugin-package.schema.json 和 echo-workshop-plugin.d.ts 加条目,不要依赖本体 DOM。
SDK 1.16:歌词、动效与主题组合
Section titled “SDK 1.16:歌词、动效与主题组合”ECHO 26.9.16+ 才具备这组完整宿主能力:
lyrics-viewruntime 可做歌词专用自绘页。它拿到当前曲歌词修订、宿主时钟、歌词交互和只读音频事件;暂停、seek、换曲时以新宿主锚点为准。看 SDK 的lyrics-authoring.md和examples/lyrics-view-runtime/。- 主题
runtime.presentation: "lyrics-background"只画歌词背景,保留宿主歌词和播放控件;只允许声明playback:read、audio:spectrum。主题、歌词自绘和背景可分别选择。看 SDK 的theme-parts.md。 animation-library导出数据动画,歌词场面通过依赖引用;本地dev有可交互的动效预览。它不开放选择器、任意 CSS、脚本或播放控制。- 稳定主题部件使用
data-echo-part/data-echo-state与--echo-*语义变量,避免绑定 ECHO 内部 class。创作台的宿主预览使用模拟歌曲和频谱,最后仍要在真实播放中验收。
权限和发布边界
Section titled “权限和发布边界”plugin-package 默认在沙箱里运行。确有完整系统访问需求时,--recipe full-trust-plugin 或 add . --permission system:full 会配对独立 .mjs trustedEntry;订阅者启用时必须明确批准,它能使用普通 Node.js 系统能力。它与仅用于数据动画的 animation-library、以及官方 Steam 当前不接收可执行文件的 native-shell 是三种不同机制。不要把本地 mock 的通过当作完整系统代码已经在 ECHO 里运行。
发布前执行 npm run check,确认 blocker 为零、fixture 全过,换掉占位预览图,核对内容许可、权限、networkHosts 与 compatibility.minEchoVersion。从 Steam 启动 ECHO,在 创意工坊 → 创作里导入、再过一次生产校验并手动发布;SDK CLI 与 CI 不上传。用普通账号走完订阅 → 下载 → 使用 → 停用,更新原条目时保留 PublishedFileID。详细步骤见 发布与更新;日常排错见 本地开发与调试。
已有项目升级时运行 upgrade . 刷新 .echo-sdk,然后 npm run check。SDK 包版本 1.21.0 不等于清单 schema 或插件 API 版本:当前源码契约仍是 schema 1、插件 API 2,以 version --json 和目标 ECHO 的兼容性为准。