官方示例与代码片段

SDK 仓库 examples/ 分两类：完整可 check 的项目 和 可复制进你项目的脚本片段。索引 → 创意工坊 SDK。

列出所有示例

node .\bin\echo-workshop-sdk.mjs example list
node .\bin\echo-workshop-sdk.mjs example list --json

拷贝完整项目到空目录：

node .\bin\echo-workshop-sdk.mjs example hello-plugin .\my-hello
node .\bin\echo-workshop-sdk.mjs example minimal-theme .\my-theme

init / example 只接受空目录；有残留文件会报 Target directory must be empty。

完整项目（第一天推荐）

示例	类型	说明
`hello-plugin`	插件	一条命令 + `playback:read`，插件教程入门
`minimal-theme`	主题	最少字段 colors 档，主题教程入门
`stylesheet-theme`	主题	整包 CSS，需 ECHO 26.8.20+
`retro-modern-ui-runtime`	主题	完整 runtime UI，见 Runtime UI
`lyrics-cinema-scene`	歌词	影院台 + 自备播放控制
`visualizer-radial`	可视化	径向频谱
`dsp-vocal`	DSP	人声向 31 段 EQ
`locale-wenyan`	语言包	文言文 locale

每个示例目录里有 README.md 和可跑的 check / test 命令。

插件片段（复制进你的 `src/plugin.js`）

这些不是完整项目；从 examples/<name>/plugin.js 复制逻辑，并在 manifest 里声明对应的 contributes 与 permissions。

片段目录	用途	典型权限 / 贡献
`lyrics-source`	歌词候选 + `echo.lyrics.get()`	`lyrics:provide`, `lyrics:read`
`metadata-provider`	元数据/封面候选	metadata / cover provider 声明
`network-source`	分页 catalog + resolve 直链	`sources:provide`, `network:request`, networkHosts
`listen-together`	一起听上传 API 2	`playback:share`, networkHosts
`author-agent`	作者自定义 Agent 处理	`agent:runtime`
`complete-ui-theme`	插件导出主题预设到「我的主题」	非 Workshop 主题包，是 import 片段

复制后务必：

npm run add -- --permission <缺的权限>
npm run check

代码片段（snippet）

比翻 examples 更快的方式：

node .\bin\echo-workshop-sdk.mjs snippet list
node .\bin\echo-workshop-sdk.mjs snippet plugin-command
node .\bin\echo-workshop-sdk.mjs snippet lyrics-provider
node .\bin\echo-workshop-sdk.mjs snippet ui-runtime-init

生成项目还带 .vscode/echo-workshop.code-snippets — 在 src/plugin.js 或 JSON 里输入 echo- 前缀展开。

snippet 名	作用
`plugin-command`	注册命令 + 读播放状态
`plugin-storage`	沙箱 JSON 存储
`plugin-settings`	读 manifest 里声明的设置项
`lyrics-provider`	歌词候选 provider
`source-provider-search`	音源 search/resolve 骨架
`network-get`	声明域名后的 GET
`ui-runtime-init`	Runtime 主题桥接初始化
`theme-colors`	colors 档 tone 块

每条 snippet 输出都会标注 requires 权限/capability 和应粘贴的 target 文件。

Recipe 与 example 怎么选

你想…	用
按效果一键脚手架	`init --recipe <id>`（见索引 · Recipe 对照表）
学习最小完整结构	`example hello-plugin` / `example minimal-theme`
学习某一高级能力	复制 `examples/` 片段 + snippet
在已有项目上叠加	`add` / `set` / `scaffold` / `next`

本地 mock 的限制

test / dev 里的 mock host：

会 enforce 权限与 networkHosts（这是好事）
不会真的访问外网（生产才会，且仍受 capability 限制）
不能证明 Steam 客户端下载行为

所以示例里常用 example.invalid 域名；换成你的域名时记得写进 networkHosts。

进阶插件能力

metadata、歌词源、一起听等片段说明见插件教程 · 进阶能力。