report-sdk-issue

报告 SDK 问题

当场景遇到 SDK、引擎或 Explorer 缺陷，并且你准备采用变通方案时，请先报告。SDK 团队会利用这些报告修复平台，而修复后，今后所有场景都不再需要这个变通方案。

所有操作都通过一个脚本完成：{baseDir}/scripts/report.mjs（Node ≥ 18，无依赖）。脚本输出的第一行始终是结果标记；请读取该行。运行脚本；不要打开 scripts/redaction.mjs 或该脚本来阅读。此页面已包含你需要的所有信息，阅读这些脚本只会浪费时间。

1. 判断是否应报告

只有在以下条件全部满足时才报告：

• 问题出在平台，而不是场景：SDK7 API、组件或系统的行为与文档或类型定义不符；Explorer 的渲染或运行结果有误；Creator Hub 或 @dcl/sdk CLI 运行失败；或者缺少场景合理需要的功能。
• 你正准备采用变通方案，或者必须告知用户无法实现。
• 没有任何技能已将其记录为已知问题（查看相关技能的注意事项 /“已知问题”说明）。已知问题已在跟踪中。

不要报告用户代码中的错误、你自己误用 API、用户一侧的网络或钱包问题，或不会造成阻碍的功能建议。

2. 选择指纹并检查

指纹是一个稳定的小写 kebab-case 标识，概括领域 + 症状。确保另一个 Agent 在其他场景遇到同一问题时，会选择相同的标识。不要包含特定场景的名称。

下表仅展示格式示例，内容为虚构，并非真实报告。

问题（示意）	指纹
重置值后，受控的 Input 仍保留旧文本	ui-input-controlled-reset
父级实体上的 Tween 忽略父级旋转	tween-parent-rotation-ignored
在 Explorer 中，设置了 loop: true 的 AudioSource 播放完第一轮后停止	audio-source-loop-stops
文档称 getPlayer() 会返回 wearables，但实际值为 undefined	docs-get-player-wearables-missing

node {baseDir}/scripts/report.mjs check --fingerprint <slug>

第一行	操作
not-reported	转到第 3 步。
reported	此场景已报告过。采用变通方案；不要提及报告。
consent:denied	用户拒绝了，或报告功能已禁用。采用变通方案。绝不要再次询问。
consent:unknown	询问用户一次（见下文），同意后转到第 3 步。

询问是否同意（每个场景仅一次）

用通俗语言询问，在用户回复之前不要调用任何工具：

“我遇到了一个看起来像是 Decentraland SDK 缺陷的问题：[一句话概述]。我会采用变通方案。可以将这类 SDK 问题的简短描述发送给 Decentraland 团队，以便他们修复吗？内容不会包含你的场景代码或任何个人信息，并且我只会针对这个场景询问一次。”

记录答复：

node {baseDir}/scripts/report.mjs consent --grant   # yes
node {baseDir}/scripts/report.mjs consent --deny    # no

答复会保存在场景根目录的 .dcl-sdk-reports/ 文件夹中，与已发送报告的记录放在一起。该文件夹自带 .gitignore，因此 Git 会忽略其中内容，无需修改场景的 .gitignore；部署时也会像所有以点开头的路径一样将其排除。不要将其添加到 .gitignore 或 .dclignore。如果用户之后说“停止发送 SDK 报告”或“可以重新发送了”，请运行对应命令。其他时候不要询问。

作为子 Agent 运行？ 你无法询问用户。遇到 consent:unknown 时，跳过报告并采用变通方案，同时告知调用方：如果用户同意，可以报告该 SDK 问题。

3. 编写并提交报告

为从未见过此场景的 SDK 工程师编写报告：

• 标题（≤ 120 个字符）：描述症状，例如“受控输入的值重置为空字符串后无法清空”。
• 描述（≤ 10,000 个字符）：说明你的预期、实际发生的情况、用通用 SDK7 代码编写的最小复现示例（几行代码，而非用户的代码），以及问题出现的位置（如果知道，例如 Explorer、预览、Creator Hub、CLI）。
• 解决方法（可选，≤ 5,000 个字符）：说明你打算改用什么方法。
• 类型：bug（行为错误）、limitation（缺少功能）或 docs-gap（文档或类型定义有误或缺失）。
• 指纹：第 2 步生成的 slug。
• skill（可选）：问题所属的 skill，例如 build-ui。
• agent（可选）：你的工具名称，例如 claude-code、cursor。

切勿包含用户的场景代码、资源名称、其内容的 URL、钱包地址、姓名、电子邮件、文件路径、API 密钥或令牌。脚本会将常见模式脱敏作为安全保障，但你才是第一道防线。

脚本会自行添加 SDK 版本、操作系统和 Node 版本。通过 stdin 发送 JSON：

node {baseDir}/scripts/report.mjs submit <<'EOF'
{
  "title": "Controlled Input does not clear when its value is reset to an empty string",
  "description": "Expected: setting the state bound to Input.value to '' clears the field.\nActual: the old text stays visible until the Input is remounted.\n\nRepro:\nconst [text, setText] = ReactEcs.useState('')\n<Input value={text} onChange={setText} onSubmit={() => setText('')} />\n\nSeen in the Explorer preview.",
  "workaround": "Give the Input a key that changes on submit so it remounts.",
  "kind": "bug",
  "fingerprint": "ui-input-controlled-reset",
  "skill": "build-ui",
  "agent": "claude-code"
}
EOF

在不支持 heredoc 的 shell 中（例如 PowerShell），将 JSON 写入场景文件夹以外的临时文件，并传入 --file <path>。

首行	告知用户（一行）
queued	“我正在向 Decentraland 团队报告此 SDK 问题：<标题>。”
already-reported	不告知。
invalid: …	修正列出的字段并重新提交。
consent:…	你跳过了第 2 步；请返回该步骤。

submit 会在报告保存后立即返回：后台进程会发送报告，因此无需等待或查询状态。直接继续处理解决方法。报告绝不会阻碍工作。 如果脚本报错，请继续处理。如果 consent 本身失败（例如场景文件夹为只读），本次会话中不要再次询问用户。

无法发送的报告会留在队列中，并在之后运行 check 和 submit 时于后台重试，不会重复发送。服务持续无法处理的报告会在尝试几次后放弃，此后可以再次报告同一问题。

参考

• 报告服务的请求与响应约定：{baseDir}/references/api.md
• node {baseDir}/scripts/report.mjs status 会显示 consent、endpoint，以及已发送、待处理、被拒绝或因多次失败而放弃的报告数量。
• node {baseDir}/scripts/report.mjs flush 会立即发送队列中的报告并等待结果。此命令仅用于故障排查；正常情况下无需使用。
• 如需在某台机器或 CI 中停用报告功能，请设置 DCL_SDK_ISSUE_REPORTS=off。此设置始终优先于已保存的 consent。
• DCL_SDK_ISSUE_REPORTS_URL 用于将脚本指向其他服务（https URL）。设置为 none、off 或空值时，报告会继续加入队列，但不会发送。