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

本地开发与调试

写 Workshop 内容时，保存 → check → 看报告 → 修 会占大部分时间。本页讲怎么把 SDK 当成日常开发工具。索引 → 创意工坊 SDK。

日常循环

Section titled “日常循环”
  1. 开一个终端在项目目录：cd .\my-project
  2. 另开终端跑监听（可选）：npm run watch
  3. 改 content/ 或 src/ 里的文件并保存
  4. npm run check — 看结尾 Gate 一行和上面的报错
  5. 需要预览：npm run dev，浏览器打开控制台给出的地址
  6. 卡住了：npm run next 看待办和还能加什么
Terminal window
# 等价命令（不在生成项目里时）
node ..\echo-workshop-sdk\bin\echo-workshop-sdk.mjs watch .
node ..\echo-workshop-sdk\bin\echo-workshop-sdk.mjs check . --json > gate.json

check 里到底跑了什么

Section titled “check 里到底跑了什么”

一次 check 按顺序做：

阶段作用
sync把 src/ 打进 community.echo，重算 echo.workshop.json 哈希
validateSchema、跨文件约束、networkHosts、apiVersion 一致等
quality预览图尺寸、描述长度、占位符、标签、主题/CSS 规则等
test (fixtures)mock host 跑确定性脚本，测权限与 API 调用

结尾示例：

[echo-workshop-sdk] Gate PASS for echo.harbor-theme · quality 9 pass / 1 warning / 0 blocker · fixtures 1/1
  • blocker = 0 才能考虑发布
  • warning 不强制，但 next 会告诉你该不该修
  • 早期可 npm run check -- --warn-only（退出码 0，仍打印失败项）

next：今天先修什么

Section titled “next：今天先修什么”
Terminal window
npm run next

输出分两块：

  1. Fix-first — 来自当前 quality 报告，每条带「跑这条命令能清掉它」
  2. 还允许的动作 — 宿主白名单里还能 add 的 slot、color、permission、capability

适合每天开工先看一眼，避免在 blocker 没清完时加新功能。

dev 作者控制台

Section titled “dev 作者控制台”
Terminal window
npm run dev
# 默认 http://127.0.0.1:41783 ，占用则自动顺延并打印实际端口

控制台里通常能看到：

区域用途
Gate 状态与 check 相同的 PASS/FAIL 摘要
Permissions / capabilities插件或 runtime 已声明能力
Fixtures点跑 mock 测试
Previewstylesheet/runtime/歌词/可视化/DSP 有 fixture 预览链接
Recent file最近改动的源文件
Raw report完整 JSON，方便复制给协作者

控制台显示 Disconnected → dev 进程已退出，看启动 dev 的那个终端报错，修完再开。不是 ECHO 断线。

显式指定端口且被占用会直接失败（不顺延），适合 CI 或固定端口脚本：

Terminal window
node .\bin\echo-workshop-sdk.mjs dev . --port 41783

watch：保存即重跑

Section titled “watch：保存即重跑”
Terminal window
npm run watch
  • 递归监听项目文件
  • 合并编辑器连续保存（防抖）
  • 忽略 SDK 自己写回的 manifest 变更，避免死循环
  • 每次结束打印与 check 相同的一行 Gate 摘要

适合改 CSS、改 plugin.js、调 JSON 时开着。

单独跑 quality / test

Section titled “单独跑 quality / test”
Terminal window
npm run quality
npm run test
node .\bin\echo-workshop-sdk.mjs validate .
node .\bin\echo-workshop-sdk.mjs explain .
node .\bin\echo-workshop-sdk.mjs inspect . --json
命令何时用
quality只关心预览图、描述、占位符、标签 warning
test只跑 mock fixture，不重算 manifest
validate只校验 manifest 与内容文件
explain人读摘要：kind、版本、许可、文件列表
inspect机器可读项目状态

--json 给脚本和编辑器

Section titled “--json 给脚本和编辑器”

这些命令支持 --json，方便 CI 或自己写脚本解析：

check · quality · test · validate · next · version · doctor · snippet · api · example list

Terminal window
npm run check -- --json | jq .gate

生成项目的 GitHub Actions 已示范如何把 check 输出贴进 PR summary → 索引 · VS Code 与 CI。

占位符会被 quality 拦住

Section titled “占位符会被 quality 拦住”

quality 会扫描标题、描述、VST ClassId 等是否仍为模板占位，例如：

  • Replace with…
  • 00000000000000000000000000000000（假 ClassId）
  • todo / workshop author 等

audio-plugin-profile 类占位符是 blocker；其它 kind 可能是 warning。发布前用真实文案替换。

推荐工具链

Section titled “推荐工具链”
工具用法
VS Code默认构建任务 Ctrl+Shift+B = check；任务面板可开 Dev console
Git每轮 check 通过后 commit；manifest 由 sync 生成，要一并提交
Node 20+node --version；SDK 零依赖，不必 npm install 整个 monorepo

Windows：路径有空格请加引号 dev ".\My Harbor"。

相关文档

Section titled “相关文档”