用途:当场景遇到 SDK、引擎或 Explorer 缺陷、而准备采用绕过方案之前,先上报给 SDK 团队,以便平台修复后让后续场景不再需要绕过。
主要能力:通过单一脚本 {baseDir}/scripts/report.mjs(需 Node ≥ 18,无依赖)完成检查、征得同意与提交。先判断是否可上报:问题须属于平台(SDK7 API、组件或系统与文档/类型不符、Explorer 渲染或运行错误、Creator Hub 或 @dcl/sdk CLI 失败、缺少场景合理需要的能力),且你正准备绕过或需告知用户无法实现,并确认该问题尚未被已有技能记录为已知问题。用户代码错误、API 误用、用户侧网络或钱包问题、非阻塞的功能建议不上报。
使用方式:先确定 fingerprint(区域+症状的小写 kebab-case 稳定标识),运行 node {baseDir}/scripts/report.mjs check --fingerprint <slug>,读取输出第一行的结果标记(not-reported、reported、consent:denied、consent:unknown)。consent:unknown 时需用平实语言征求用户一次同意,再用 consent --grant 或 consent --deny 记录,结果存于场景根目录 .dcl-sdk-reports/ 文件夹。随后撰写面向未见过该场景的 SDK 工程师的报告(title ≤120 字符、description ≤10000 字符含期望、实际、最小复现与出现位置、可选 workaround ≤5000 字符、kind 为 bug/limitation/docs-gap、fingerprint、可选 skill 与 agent),通过 stdin 以 JSON 提交。
限制与注意:严禁包含用户场景代码、资源名、内容 URL、钱包地址、姓名、邮箱、文件路径、API 密钥或令牌;脚本会脱敏常见模式但使用者是首要防线。脚本自身补充 SDK 版本、操作系统与 Node 版本。submit 保存后即返回,后台发送,无需等待。无法发送的报告会保留队列并后台重试,不会重复;多次失败后放弃,之后可重新上报。可用 status 查看状态,flush 仅用于排障,设置 DCL_SDK_ISSUE_REPORTS=off 可禁用上报,DCL_SDK_ISSUE_REPORTS_URL 指向其他服务。若脚本出错则继续绕过流程;consent 本身失败时本会话不再询问。