主题教程：从配色到 CSS

从最少字段的 配色主题 做起，再按需升到 整包 CSS。完整索引 → 创意工坊 SDK。

AI 主题生成指南产出的是 echo-next.custom-theme JSON，在设置里导入。工坊主题是独立 Workshop 包，走 SDK 与 Steam 发布，两者不要混用文件格式。

选哪一档

档位	改什么	最低 ECHO	起步命令
`colors`	深浅色 hex	26.8.15	`--recipe colors-theme`
`skin`	声明式 chrome / 舞台	26.8.15	`--recipe skin-theme`
`stylesheet`	整包 CSS	26.8.20	`--recipe css-theme`
`runtime`	沙箱 HTML/CSS/JS UI	26.8.20	`--recipe custom-ui`

已有低档位项目可 换档不重开：

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

实战 A：最小配色主题

适合第一次验证「能 check、能 dev、能进创作台」。

拷贝官方示例：

node .\bin\echo-workshop-sdk.mjs example minimal-theme .\harbor-colors
cd .\harbor-colors

打开 content/theme.json，改 light / dark 里的 hex（如 appBg、accent、text）。
basePreset 保持 classic 等公开预设，不要用 FINAL / nyanCat / darkSideMoon。
验证：
Terminal window
```
npm run check
npm run dev
```
换 preview.png（256×256），npm run set -- --title "你的标题" 更新列表文案。

theme.json 核心字段示例：

{
  "type": "echo-workshop-theme-preset",
  "schemaVersion": 1,
  "id": "echo.harbor-colors",
  "title": "Harbor Colors",
  "basePreset": "classic",
  "dark": {
    "appBg": "#141218",
    "panel": "#1e1a26",
    "accent": "#c48bff",
    "text": "#ddd3ec"
  },
  "light": {
    "appBg": "#f6f2fb",
    "panel": "#fdfbff",
    "accent": "#7a3ff2",
    "text": "#3a2f4d"
  }
}

外层 content/echo.workshop.json 的 compatibility.minEchoVersion 对 colors 档通常填 26.8.15。

实战 B：整包 CSS 主题

适合要控制背景渐变、侧栏、播放条等具体样式。

新建或换档：
Terminal window
```
node .\bin\echo-workshop-sdk.mjs init .\harbor-css --recipe css-theme
cd .\harbor-css
```
已有 colors 项目：scaffold . --preset stylesheet
确认 content/theme.json 指向 CSS 文件（生成项目已配好）。

编辑 content/theme.css。所有规则必须写在包 id 选择器下：

html[data-workshop-theme-pack="echo.harbor-css"] {
  --color-bg: #10131a;
  --color-text: #d8e8f3;
  color-scheme: dark;
}
html[data-workshop-theme-pack="echo.harbor-css"] .player-bar {
  border-top: 1px solid rgb(102 204 255 / 0.22);
}

把 echo.harbor-css 换成你项目的 id（与 theme.json / 清单一致）。

minEchoVersion 设为 26.8.20 或更高：
Terminal window
```
npm run set -- --title "Harbor Stylesheet"
```
并检查 echo.workshop.json 里 compatibility.minEchoVersion。
npm run check → npm run dev 看 fixture 预览与门禁摘要。

内联 <script>、远程 @import、非栅格 url() 会被丢弃或拒绝。
stylesheet 覆盖 skin；runtime 替换可见 chrome，但仍须保留宿主紧急退出条。
不要试图解锁内置皮肤包名。

实战 C：runtime 自定义 UI（概览）

--recipe custom-ui 或 scaffold . --preset runtime 会生成 content/ui/（HTML/CSS/JS）。UI 与宿主通过 postMessage 桥通信，类型见 .echo-sdk/echo-workshop-ui-runtime.d.ts。

先跑通 colors 或 stylesheet，确认 check/dev 流程，再升 runtime。runtime 调试面更大，权限与 capability 也要在清单里逐项声明。

常用片段：

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

常用 set / add

命令	作用
`set . --title "…"`	改标题
`set . --description "…"`	改列表描述（建议 ≥ 80 字）
`set . --license MIT`	改内容许可
`add . --color #66ccff`	主题色板追加（宿主白名单内）

改完一律 npm run check。质量报告里的 warning（如 tags）用 npm run quality 单独看。

发布前检查

npm run check 全绿
preview.png 非占位、256×256
minEchoVersion 不高于你实测过的最旧 ECHO
CSS 选择器里的 pack id 与 manifest id 一致
在 ECHO 创作台导入后，使用一次看主题是否生效

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