跳转到内容
ECHO Next 文档
⌂ 回到首页

创意工坊 SDK 教程

给要在 Steam 创意工坊 发布主题、歌词场面、可视化、均衡预设、语言包或沙箱插件的作者。

SDK 仓库：github.com/Moekotori/echo-workshop-sdk

创意工坊 SDK本地插件
发布方式Steam 创意工坊放进 plugins/ 目录
运行环境ECHO 沙箱ECHO 主程序插件页
适用版本Steam 版 ECHOECHO Next 本地插件
工具echo-workshop-sdk CLI手写 echo.plugin.json

Steam 版用户订阅工坊内容后，在 ECHO 里点「使用」才会生效，流程见 Steam 创意工坊。本 SDK 不会自动上传 到 Steam；发布只能在 ECHO 的「创意工坊 → 创作」里确认。

分步教程

Section titled “分步教程”
教程适合
主题：从配色到 CSS第一次做换肤、整包 stylesheet
沙箱插件：命令与音源目录hello 插件、联网 catalog、权限声明
JSON 内容：歌词 / 可视化 / DSP / 语言包非代码类工坊条目
Runtime UI 主题沙箱 HTML/CSS/JS 整页换肤
官方示例与代码片段拷贝 hello / cinema / 片段与 snippet
本地开发与调试dev / watch / quality / next / --json
歌词场面实战cinema 槽位、隐藏迷你条、transport
语言包locale.json、回退、文言文示例
可视化与 DSP频谱三样式、31 段 EQ 调参
VST3 接入配置ClassId 映射，不含插件二进制
音源目录 APIsearch / browse / resolve 详解
发布与更新check 全绿后在 ECHO 创作台上线
作者常见问题边界、选型、版本、AI 协作
  • 订阅者（只用别人做的内容）→ Steam 创意工坊，不必装 SDK。
  • 作者（自己发 Workshop 条目）→ 读本系列；本地 check 通过后还要走 发布与更新。

check / dev / CI 是作者本地门禁，通过只说明包结构、权限和 mock 测试 OK。不能代替 Steam 下载、ECHO「使用」和生产宿主策略。发布前后请用真实 Steam 账号自测订阅流程。

项目里有什么

Section titled “项目里有什么”

init 或 example 生成的工作区大致如下：

my-project/
├── echo.workshop.project.json   # 作者项目：Steam 标签、描述、可见性、预览图路径
├── preview.png                  # 256×256 列表预览（发布前换掉占位图）
├── package.json                 # npm run check / dev / watch
├── content/                     # 打包进工坊的最终内容
│   ├── echo.workshop.json       # 外层清单：id、版本、文件哈希、兼容性
│   └── theme.json 等            # 按 kind 不同（见下表）
├── src/                         # 插件源码（check 时 sync 进 content/community.echo）
│   └── plugin.js
├── .echo-sdk/                   # 便携 SDK 副本 + TypeScript 声明
└── .vscode/                     # JSON Schema、构建任务、echo- 代码片段
内容类型主要编辑位置content/ 入口文件
主题content/theme.json（+ 可选 theme.css / ui/）theme.json
歌词场面content/lyrics-style.jsonlyrics-style.json
可视化content/visualizer.jsonvisualizer.json
DSPcontent/dsp.jsondsp.json
语言包content/locale.jsonlocale.json
沙箱插件src/plugin.js（及 panel 等）community.echo（自动生成）

改 content/ 或 src/ 后跑 npm run check，SDK 会 sync 并重算 echo.workshop.json 里的 files[].sha256。不要自己编 hash。

ECHO 不内置网易云、Spotify、YouTube 等流媒体平台。插件可以返回作者自有的 HTTP(S) 直链目录，用户确认后才播放。完整法律边界 → 下载与插件音源法律边界。

你需要准备什么

Section titled “你需要准备什么”
项目要求
Node.js20 或更高（init / check / dev 只需要 Node，不强制先装 ECHO）
编辑器VS Code 推荐；生成项目自带 JSON Schema 和代码片段
ECHO发布前在 Steam 版里走创作台；本地 check 不依赖 ECHO
Steam从 Steam 启动 ECHO，在线状态正常

获取 SDK

Section titled “获取 SDK”

三种方式，内容相同：

  1. GitHub 克隆（推荐开发者）
    Terminal window
    git clone https://github.com/Moekotori/echo-workshop-sdk.git
    cd echo-workshop-sdk
  2. npm 安装（适合 CI 或固定版本）
    Terminal window
    npm install github:Moekotori/echo-workshop-sdk
    npx echo-workshop-sdk version
  3. Steam 工坊起步包 — 订阅工坊项目 3784997717，与 GitHub 发行版同步。

当前 SDK 包版本 1.11.0，清单 schema 1，沙箱插件 API 2。查机器可读能力表：

Terminal window
node .\bin\echo-workshop-sdk.mjs version --json

30 秒：第一个项目

Section titled “30 秒：第一个项目”

下面用 最小插件 走一遍完整本地流程。

  1. 克隆 SDK 后，在空目录初始化：
    Terminal window
    node .\bin\echo-workshop-sdk.mjs example hello-plugin .\my-hello
    cd .\my-hello
  2. 看下一步该做什么：
    Terminal window
    npm run next
  3. 跑完整本地门禁（同步、校验、质量报告、fixture 测试）：
    Terminal window
    npm run check
  4. 打开作者控制台和预览：
    Terminal window
    npm run dev

hello-plugin 只有一条命令和一个 playback:read 权限，适合第一天熟悉结构。改代码主要编辑 src/plugin.js；保存后 check 会把内容同步进 content/community.echo。

想先做主题而不是插件：

Terminal window
node .\bin\echo-workshop-sdk.mjs example minimal-theme .\my-theme
cd .\my-theme
npm run check

七种内容类型

Section titled “七种内容类型”
--kind做什么常见起步
theme换肤、整包 CSS、自定义 UI--recipe css-theme 或 --preset skin
lyrics-style歌词场面布局--recipe cinema-lyrics
visualizer-preset频谱样式（bars / wave / radial）--recipe radial-visualizer
dsp-preset31 段均衡预设--recipe vocal-eq
audio-plugin-profile本机 VST 接入配置说明--kind audio-plugin-profile
locale-packECHO 未内置的语言包（如文言文）--recipe wenyan-locale
plugin-package沙箱插件（命令、面板、提供器）--recipe plugin-complete 或 hello-plugin 示例

按效果挑模板，不必记 --kind：

Terminal window
node .\bin\echo-workshop-sdk.mjs recipes
node .\bin\echo-workshop-sdk.mjs init .\harbor --recipe css-theme

Recipe 对照表

Section titled “Recipe 对照表”
--recipe内容类型你会得到
colors-theme主题只改深浅色，最少字段
skin-theme主题声明式外壳、舞台与氛围
css-theme主题整包 CSS（stylesheet 档）
custom-ui主题沙箱 HTML/CSS/JS 自定义界面
editorial-lyrics歌词封面 + 歌词网格（默认台）
cinema-lyrics歌词影院舞台，常隐藏迷你播放条
compact-lyrics歌词一行封面 + 标题的紧凑台
cover-lyrics歌词大封面柱歌词台
bars-visualizer可视化镜像频谱柱
wave-visualizer可视化波形
radial-visualizer可视化径向频谱
flat / vocal-eq / bass-eqDSP平坦 / 人声 / 低频 31 段预设
plugin-complete插件命令 + 面板 + Agent + 提供器
source-catalog插件作者自有直链目录
lyrics-source插件歌词提供器 + 当前歌词面板
wenyan-locale语言包文言文等额外 locale

推荐创作路线

Section titled “推荐创作路线”
  1. 初始化 — init 或 example，目录名会推断 id / 标题。
  2. 编辑 — 主题 / 歌词 / 可视化 / DSP 改 content/ 下 JSON；插件改 src/plugin.js。
  3. 迭代 — npm run next 看质量报告待办和宿主还允许加什么；add / set / scaffold 增量修改，不必重写整份 JSON。
  4. 验证 — npm run check 必须全绿再考虑发布；早期可用 npm run check -- --warn-only 边看报告边改。
  5. 预览 — npm run dev 打开本地作者控制台；stylesheet / runtime / 歌词 / 可视化 / DSP 项目另有 fixture 预览。
  6. 发布 — 在 ECHO「创意工坊 → 创作」里校验并上传。SDK 命令永不上传。

完整 checklist 可在 SDK 里查看：

Terminal window
node .\bin\echo-workshop-sdk.mjs guide checklist

常用命令

Section titled “常用命令”
命令作用
init ./dir --kind theme新建项目
init ./dir --recipe cinema-lyrics按效果新建
example hello-plugin ./dir拷贝官方完整示例
next .先列待修复项，再列可加槽位 / 权限
add . --permission library:read白名单内追加权限
set . --title "Harbor Night"改标题、描述、样式等
scaffold . --preset runtime主题换档（colors → skin → stylesheet → runtime）
check .完整本地门禁
dev .作者控制台（默认端口 41783，占用时自动顺延）
watch .保存即重跑 check
fix .补 preview.png、README、minEchoVersion 等
upgrade .刷新项目内 .echo-sdk 副本（不覆盖你的内容）
explain . / inspect .人读 / 机器读项目摘要
sync .仅同步 manifest 与插件包（check 会自动做）
guide / guide troubleshoot中文说明书与排错速查
snippet list常用代码片段（含所需权限）
api echo.queue.moveItem查方法对应权限
api errors查错误是否可重试

生成项目里可直接 npm run check、npm run dev。VS Code 默认构建任务 ECHO Workshop: Check（Ctrl+Shift+B）。

VS Code 与 CI

Section titled “VS Code 与 CI”

生成项目已配置：

  • JSON Schema — 编辑 echo.workshop.json、theme.json 等时字段错误会标红
  • 代码片段 — 在 .js / .json 里输入 echo- 前缀展开（与 snippet list 相同）
  • 插件类型 — .echo-sdk/echo-workshop-plugin.d.ts 为 echo.* 提供补全

自带 .github/workflows/validate-workshop.yml：每次 push / PR 跑与本地相同的 check 门禁，并把摘要写入 GitHub Actions job summary。模板要求 Node 22，与本地 Node 20+ 兼容。

  1. 把项目 push 到 GitHub 后，PR 页可直接看 gate 摘要是否 PASS。
  2. 若 CI 报 Generated files are committed 失败：本地执行 npm run check && git add -A 再提交 sync 后的 manifest。
  3. 发布仍只在 ECHO 创作台手动确认；CI 不会上传 Steam。

主题四档

Section titled “主题四档”

主题可以逐级升级，不必重来：

档位作用最低 ECHO
colors只改深浅色26.8.15
skin声明式外壳（默认）26.8.15
stylesheet整包 CSS26.8.20
runtime沙箱 HTML/CSS/JS 自定义界面26.8.20

换档示例：

Terminal window
node .\bin\echo-workshop-sdk.mjs scaffold .\my-theme --preset stylesheet
  • basePreset 只能用宿主公开预设（如 classic），不能用 FINAL、nyanCat、darkSideMoon。
  • 整包 CSS 必须写在 html[data-workshop-theme-pack="<你的包 id>"] 选择器下。
  • 内联脚本、远程 @import、非栅格 url() 会被宿主拦截。
  • stylesheet 和 runtime 主题的 minEchoVersion 建议 ≥ 26.8.20。

沙箱插件要点

Section titled “沙箱插件要点”

工坊插件与 本地插件创作指南 共用相似概念，但权限更窄、运行在沙箱里。

预设适合做什么
basic一条命令，最小权限
complete命令 + 面板 + Agent + 提供器
catalog作者自有直链音源目录（不是官方流媒体）
lyrics歌词提供器 + 当前歌词面板

插件项目会自动引用 .echo-sdk/echo-workshop-plugin.d.ts，API 2 的 echo.* 返回值有完整类型补全。

插件包最多 32 个文件，单文件 UTF-8 上限 512 KiB，序列化整包上限 2 MiB。允许扩展名：.css、.html、.js、.mjs、.json。内层插件 apiVersion 必须与外层 echo.workshop.json 的 compatibility.pluginApiVersion 完全一致。

联网插件还要在外层清单声明 networkHosts（纯域名或公网 IPv4，不带协议和端口），并申请 network:request 权限。mock 会在本地拒绝未声明域名，避免上线后才踩坑：

Terminal window
node .\bin\echo-workshop-sdk.mjs add . --permission network:request
node .\bin\echo-workshop-sdk.mjs api errors

歌词、可视化、DSP

Section titled “歌词、可视化、DSP”

歌词场面 — 宿主拥有所有槽位，你只摆位置和白名单样式。可用槽包括 cover、title、lyrics、current-line、spectrum、play-toggle 等。隐藏迷你播放条时必须自带 play-toggle。

可视化 — 宿主只接受 bars、wave、radial，没有 particles。调色板 1–8 个不重复 #rrggbb，barCount 8–128。

DSP / EQ — 必须是官方 31 段频率布局；增益 -12..12，Q 0.1..12，preamp -12..6。JSON 只是预设，播放时仍由 Audio Core 执行。

从零到发布

Section titled “从零到发布”
  1. 本地 npm run check 全绿（warning 自行判断是否可接受）。
  2. 换掉占位 preview.png（256×256），写好 README 和列表描述（建议 ≥ 80 字）。
  3. 确认 license、tags、minEchoVersion 与真实测试版本一致。
  4. 从 Steam 启动 ECHO → 创意工坊 → 创作。
  5. 导入或关联本地项目，走 ECHO 内置校验。
  6. 校验通过后发布。公开 SDK 起步包 ID 固定为 3784997717，更新时继续用同一项，不要新建。

用户侧订阅与启用流程 → Steam 创意工坊。

常见排错

Section titled “常见排错”

先跑 npm run check，看结尾一行 Gate 摘要：

[echo-workshop-sdk] Gate PASS for echo.my-item · quality 9 pass / 0 warning / 0 blocker · fixtures 1/1
  • blocker — 发布前必须 0
  • warning — 作者自行判断；next . 会给出修复命令
  • fixtures — mock 测试通过数

早期迭代可用 npm run check -- --warn-only（退出码 0 但仍打印失败）；发布前必须完整 PASS。

现象常见原因处理
Manifest hash mismatch改了 content/ 或 src/ 没同步再跑 check（会自动 sync）
capability-denied用了未声明的权限/capabilityadd . --permission … 或 --capability …
network-host-denied请求了清单未声明的域名在外层 echo.workshop.json 声明 networkHosts
network-port-denied用了非 443/80 端口改用默认端口
Preview must be …预览图不合规npm run fix
Project id is invalidid 格式不对小写 echo.xxx，见 FAQ
Plug-in package exceeds limit超 32 文件 / 512KiB / 2MiB精简资源
Port 41783 was busydev 端口占用不传 --port 时自动换端口
创作台仍失败生产校验更严 / Steam 未就绪见 发布与更新

完整双语手册 → SDK TROUBLESHOOTING.md。更多问答 → 作者 FAQ。

许可与贡献

Section titled “许可与贡献”

SDK 包内类型、Schema、CLI、模板和示例采用 MIT License。你的原创 Workshop 内容版权归你，可用 init / set 的 --license 声明（默认 All-Rights-Reserved）。

想改 SDK 本身：到 echo-workshop-sdk 提 issue 或 PR，流程见仓库 CONTRIBUTING.md。

相关文档

Section titled “相关文档”