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

作者常见问题

给第一次接触 Workshop 创作的作者。分步教程见 索引；发布流程见 发布与更新。

谁需要读这套文档？

Section titled “谁需要读这套文档？”
你是…需要 SDK 吗
只想订阅别人做的主题/插件不需要，看 Steam 创意工坊
想往 Steam 发主题、歌词、可视化、DSP、语言包、沙箱插件需要，从 索引 开始
只想写本地 plugins/ 目录插件看 插件创作指南，不是本 SDK
只想导入 JSON 自定义主题（设置里）看 AI 主题生成指南，不是 Workshop 包

SDK 会自动上传 Steam 吗？

Section titled “SDK 会自动上传 Steam 吗？”

不会。 任何 CLI 命令、npm script、GitHub Actions 都只在本地校验。上传/发布只能在 ECHO 创意工坊 → 创作里由你手动确认。

不装 ECHO 能写吗？

Section titled “不装 ECHO 能写吗？”
阶段是否必须装 ECHO
init / 编辑 / check / dev / test不必（Node 20+ 即可）
创作台发布、Steam 订阅测试必须（Steam 版）

本地 mock host 很有用，但不能代替 Steam 客户端下载和 ECHO「使用」流程。

和「插件创作指南」有什么关系？

Section titled “和「插件创作指南」有什么关系？”

插件创作指南 面向 ECHO Next 本地插件（plugins/ 目录、更宽的宿主 API 面）。

工坊 沙箱插件 是另一套：

  • 包格式是 community.echo + 外层 echo.workshop.json
  • 权限更窄，无 Node / SQLite / 主界面 DOM
  • 必须用 SDK 生成和 check，不要把本地插件文件夹直接当 Workshop 包上传

两篇文档都提到的概念（命令、provider、权限）语义相近，但文件格式和运行时不同。

和「AI 主题生成指南」有什么关系？

Section titled “和「AI 主题生成指南」有什么关系？”
AI 主题 JSONWorkshop 主题包
产物echo-next.custom-themetheme.json (+ 可选 CSS / UI)
导入方式设置 → 外观 → 导入Steam 订阅 + ECHO「使用」
工具手搓或 AI 生成 JSONecho-workshop-sdk

想把 AI 生成的配色迁移到 Workshop：参考 hex 值重写 theme.json 的 light/dark，或做到 stylesheet 档；不能直接把 custom-theme 文件当 Workshop 清单上传。

check 全绿，用户那边还报错？

Section titled “check 全绿，用户那边还报错？”
  1. 订阅者没点「使用」 — 订阅只下载，见 Steam 创意工坊。
  2. ECHO 版本低于 minEchoVersion — 降低声明或提示用户升级。
  3. 生产环境额外策略 — 创作台校验通过只代表作者路径 OK；用户机还有本地校验、隔离状态。
  4. 插件权限用户拒绝 — 直链来源、一起听上传等，用户取消后插件不得死循环弹窗。

作者应用自己 Steam 账号走一遍：订阅 → 使用 → 功能验证 → 停用。

项目 id 怎么起名？

Section titled “项目 id 怎么起名？”

规则（简化）：

  • 小写为主，如 echo.harbor-theme
  • 字符：字母、数字、.、_、-
  • 长度约 3–80
  • 全局唯一（你的 Steam 条目 id，不要和别人撞车）

init 时可用 --id echo.my-name；只写目录名时会从文件夹名推断。

version 和 SDK 包版本是一回事吗？

Section titled “version 和 SDK 包版本是一回事吗？”

不是。

字段含义
@echo/workshop-sdk 包版本（如 1.11.0）工具链版本
content/echo.workshop.json → version你的 Workshop 条目版本（给用户看、更新用）
compatibility.minEchoVersion支持的最旧 ECHO 客户端

升级 SDK：upgrade .。升级条目：改 Workshop version + changeNote 再发布。

可以用 AI / Cursor 帮我写吗？

Section titled “可以用 AI / Cursor 帮我写吗？”

可以，但建议：

  1. 把 索引、对应 分步教程 和 snippet list 输出一起发给 AI。
  2. 强调 权限白名单、networkHosts、包体限制。
  3. 每改一轮就跑 npm run check，不要一次生成巨大项目。
  4. 联网/catalog 类不要让它写平台爬虫或 Cookie 逻辑。

networkHosts 为什么这么严？

Section titled “networkHosts 为什么这么严？”
  • 只能声明公网域名或公网 IPv4，无协议、无端口、无私网/本机/通配符。
  • 用户第一次播某域名还要再确认。
  • 生产环境会解析 DNS 并固定连接已校验地址，防止插件随意探测内网。

这是故意设计，不是 SDK 刁难作者。

标签 warning 要不要管？

Section titled “标签 warning 要不要管？”

quality 可能 warning「标签未在 AppID 配置」。kinds 和生成项目会带该内容类型的默认 Steam 标签；尽量用宿主已配置的 tag，减少 listing 侧问题。blocker 必须清零；warning 发布前建议处理。

我能修改/重新上传别人的工坊项吗？

Section titled “我能修改/重新上传别人的工坊项吗？”

不能（除非那是你 Steam 账号下的条目）。只能 fork SDK 仓库 echo-workshop-sdk 改工具链，或做自己的新 id 条目。

Windows 路径要注意什么？

Section titled “Windows 路径要注意什么？”
  • 路径有空格请加引号：init ".\My Harbor"
  • 示例统一用 .\bin\echo-workshop-sdk.mjs 相对路径
  • Git 换行建议保留 SDK 生成的 .gitattributes

还缺什么文档？

Section titled “还缺什么文档？”