创意工坊开发指南

这篇给准备自己制作 ECHO Steam 创意工坊内容的作者。只想订阅和启用作品，请看 Steam 创意工坊。下面以 D:\ECHO 的 2026-09-25 源码、SDK 1.17.0 为依据；源码版本不代表 GitHub Release 和 Steam 起步包已更新到同一版。下载前核对最新 GitHub Release 内实际提供的 .tgz，并在本地运行 version --json。

先选作品类型

想做什么	`--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 和沙箱插件有逐项教程。

建立并检查第一个项目

作者本机需要 Node.js 20+。SDK 不发布到 npm 公共仓库；可以克隆 SDK 仓库，或安装 GitHub Release 实际附带的 .tgz。下面是在克隆后的 SDK 根目录运行的 Windows PowerShell 示例：

node .\bin\echo-workshop-sdk.mjs version --json
node .\bin\echo-workshop-sdk.mjs init .\my-theme --recipe css-theme
cd .\my-theme
npm run next
npm run check
npm run dev

编辑 content/ 的主题、歌词或预设 JSON；插件主要编辑 src/plugin.js。check 会先同步生成 content/community.echo 和清单哈希，再做结构、质量和 fixture 检查。不要手改生成的包与 SHA-256。 dev 是本地模拟控制台；保存时持续检查可运行 npm run watch。它们通过后，仍需在 Steam 版 ECHO 的创作台验证真实宿主效果。

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 个 page；所有已启用插件合计最多 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：歌词、动效与主题组合

ECHO 26.9.16+ 才具备这组完整宿主能力：

lyrics-view runtime 可做歌词专用自绘页。它拿到当前曲歌词修订、宿主时钟、歌词交互和只读音频事件；暂停、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。创作台的宿主预览使用模拟歌曲和频谱，最后仍要在真实播放中验收。

权限和发布边界

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.17.0 不等于清单 schema 或插件 API 版本：当前源码契约仍是 schema 1、插件 API 2，以 version --json 和目标 ECHO 的兼容性为准。