echo-nebula Alpha 概览

目标读者：正在评估或接入 Godot 玩家主动反馈的开发者。

echo-nebula 是 Godot 优先的玩家主动反馈收集器。玩家通过按钮、F8、菜单或代码打开反馈面板，填写描述，并明确选择是否附带截图、最近日志和联系方式。Alpha 文档跟随 contracts version 0.4.0-alpha.1。

P0 主链路是：开发者注册、创建组织和项目、生成 project key、初始化 Godot SDK、玩家确认隐私提示、public API 写入、在同意允许时上传附件，并通过 admin API 查看反馈。

从本地到第一条反馈

1. 按 本地开发 启动 PostgreSQL、MinIO、public API、admin API、Developer Console 和文档站，并运行 ./scripts/e2e-all.sh 确认栈可用。
2. 打开 开发者控制台，注册开发者，创建组织和项目，然后生成 Project Key。Project Key 仅用于 Public API 的 GET /v1/sdk/config、POST /v1/feedback/reports 和受 consent 限制的附件路由；控制台管理操作使用开发者登录态和 /admin/v1/*。
3. 按 Godot 快速接入 安装插件，填入 public_api_base_url 和 project key，绑定按钮、菜单、F8 或代码触发点。
4. 按 发送第一条反馈 在游戏里打开反馈面板，填写描述，并让玩家明确选择截图、最近日志和联系方式。
5. 回到 Developer Console 的反馈详情页查看状态、附件、联系方式、评论和审计记录；若要直接调试接口，可对照 Admin API。

最小示例

EchoNebulaFeedback.configure({
  "project_key": "enb_pk_xxx",
  "public_api_base_url": "http://localhost:4000",
  "locale": "auto"
})
EchoNebulaFeedback.open_feedback_panel({ "trigger_source": "button" })

X-Project-Key 只能用于 public API。后台读取和管理操作使用 admin API 返回的开发者 JWT。

常见错误

• 不要默认上传截图。截图必须由玩家手动勾选。
• 不要静默上传联系方式。联系方式只能由玩家填写或确认。
• 不要把 echo-nebula 当成崩溃监控平台，P0 主对象是 feedback_report。
• 不要用 Project Key 读取或管理 Admin API 数据；它只能认证已发布的 Public API SDK 配置与反馈接收路由。

下一步

先运行 本地开发，再继续 Godot 快速接入。