Runtime UI 主题

runtime 档主题是 Workshop 里自由度最高的一类：用 content/ui/ 里的 HTML/CSS/JS 画整套界面，通过 postMessage 桥与宿主通信。入门配色/CSS 见 主题教程。

Runtime UI 跑在 ECHO 沙箱里，不是随便开的浏览器标签。无 Node、无任意 fetch 到未声明域名、无绕过 Audio Core。宿主保留紧急退出条和 capability 检查。

何时选 runtime

需求	更合适的档
只改颜色	colors
改布局氛围、不写 CSS	skin
精细 CSS、仍用 ECHO 壳	stylesheet
完全自定义导航/歌词/频谱 UI	runtime

新建：

node .\bin\echo-workshop-sdk.mjs init .\my-ui --recipe custom-ui
cd .\my-ui
npm run check
npm run dev

已有 skin/stylesheet 项目：

node .\bin\echo-workshop-sdk.mjs scaffold .\my-theme --preset runtime

minEchoVersion 须 ≥ 26.8.20。

项目里多了什么

content/
├── echo.workshop.json
├── theme.json              # 声明 runtime 档与 ui 入口
└── ui/
    ├── index.html          # 沙箱页面入口
    ├── app.css
    └── app.js              # 通过桥接调用宿主能力

TypeScript 补全：.echo-sdk/echo-workshop-ui-runtime.d.ts（与插件的 echo-workshop-plugin.d.ts 不同）。

桥接模型（人话版）

1. 你的 app.js 在 iframe 沙箱里跑。
2. 需要曲库、播放、队列等时，发 postMessage 给宿主，宿主校验 capability 后执行。
3. 宿主把结果回传；Audio Core、真实文件路径、未声明网络仍不可见。
4. dev 控制台会列出已声明 capability、fixture 和最近改动的文件。

初始化片段：

node .\bin\echo-workshop-sdk.mjs snippet ui-runtime-init

插件用 permission（如 library:read）。Runtime UI 用 capability（如导航、歌词、频谱、主题本地 storage）。增能力：

npm run add -- --capability playback:control

未声明就调用 → 本地 mock 报 capability-denied，与插件权限错误类似。

官方完整示例

SDK 仓库 examples/retro-modern-ui-runtime/：

• 沙箱 UI + 曲库浏览、随机/循环、当前歌词行、频谱、主题内搜索记忆
• 使用的 capability：navigation、playback、library、queue、window 等
• 适合当 runtime 项目结构参考，不要整包抄袭 id

node .\bin\echo-workshop-sdk.mjs example retro-modern-ui-runtime .\retro-ui
cd .\retro-ui
npm run dev

开发循环

1. 改 content/ui/* 或 theme.json。
2. npm run watch 或保存后手动 npm run check。
3. npm run dev — 打开作者控制台；runtime 项目有 fixture 预览链接。
4. 控制台 Disconnected → 看终端报错，修完重开 dev。
5. check 全绿后，按 发布与更新 走创作台。

硬性规则

• 必须保留宿主 紧急退出 chrome（生成项目会带；删了 check/blocker）。
• 样式与脚本仅作用于沙箱页，不要假设能改 ECHO 原生侧栏 DOM。
• 需要联网时：插件式 networkHosts + 权限/capability 声明同样适用。
• inline script 注入、远程 @import 等仍会被宿主 sanitation 拦截（与 stylesheet 主题同类策略）。

与插件 runtime 的区别

	Runtime 主题	沙箱插件面板
目的	替换主界面体验	附加命令/面板/提供器
入口	用户选主题为「当前主题」	用户启用插件
包 kind	theme	plugin-package
典型文件	content/ui/	src/plugin.js + panel.html

同一作者可以既发 runtime 主题，又发独立插件；不要混在一个 manifest kind 里。

相关文档

• 主题教程 · 实战 C 概览
• 官方示例与片段
• 发布与更新