report-sdk-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reporting SDK Issues

报告SDK问题

When a scene hits an SDK, engine, or Explorer defect and you are about to work around it, report it first. The SDK team uses these reports to fix the platform, and the fix removes the need for the workaround in every future scene.

Everything goes through one script,

{baseDir}/scripts/report.mjs

(Node ≥ 18, no dependencies). The first line of its output is always the result token; read that line. Run the script; don't open it or

scripts/redaction.mjs

to read them. This page has everything you need, and reading them only costs time.

当场景遇到SDK、引擎或Explorer缺陷，而你正准备采用变通方案时，请先上报该问题。SDK团队会利用这些报告修复平台问题，修复后所有未来的场景都无需再使用该变通方案。

所有操作都通过一个脚本完成：

{baseDir}/scripts/report.mjs

（需Node ≥ 18，无依赖）。其输出的第一行始终是结果令牌；请读取该行内容。直接运行脚本即可，不要打开它或

scripts/redaction.mjs

查看内容。本页面已包含你需要的所有信息，查看这些脚本只会浪费时间。

1. Decide whether it's reportable

1. 判断是否可上报

Report it when all of these hold:

The problem is in the platform, not the scene: an SDK7 API, component, or system behaves differently from its documentation or types; the Explorer renders or runs it wrong; the Creator Hub or
```
@dcl/sdk
```
CLI fails; or a capability a scene reasonably needs is missing.
You are about to apply a workaround, or you have to tell the user it can't be done.
No skill already documents it as a known issue (check the relevant skill's Gotchas / "Known issue" notes). Known issues are already tracked.

Don't report mistakes in the user's code, your own misuse of an API, network or wallet problems on the user's side, or feature ideas that aren't blocking anything.

当所有以下条件都满足时，上报该问题：

问题出在平台而非场景：SDK7 API、组件或系统的行为与文档或类型定义不符；Explorer渲染或运行错误；Creator Hub或
```
@dcl/sdk
```
CLI故障；或缺少场景合理所需的功能。
你正准备采用变通方案，或不得不告知用户该需求无法实现。
没有任何Skill已将其记录为已知问题（检查相关Skill的注意事项/「已知问题」说明）。已知问题已被跟踪。

不要上报用户代码中的错误、你自己对API的误用、用户侧的网络或钱包问题，或不构成阻塞的功能想法。

2. Pick a fingerprint and check

2. 选择问题指纹并检查

The fingerprint is a stable, lowercase kebab-case slug of area + symptom. Make it so that another agent hitting the same issue in another scene would pick the same slug. Don't include scene-specific names.

The table below shows made-up examples of the format only. They aren't real reports.

Issue (illustrative)	Fingerprint
A controlled `Input` keeps old text after the value is reset	`ui-input-controlled-reset`
`Tween` on a parented entity ignores the parent's rotation	`tween-parent-rotation-ignored`
`AudioSource` with `loop: true` stops after the first loop in the Explorer	`audio-source-loop-stops`
The docs say `getPlayer()` returns `wearables` , but it's undefined	`docs-get-player-wearables-missing`

bash

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

First line	What to do
`not-reported`	Go to step 3.
`reported`	Already reported from this scene. Apply the workaround; say nothing about reporting.
`consent:denied`	The user said no, or reporting is disabled. Apply the workaround. Never ask again.
`consent:unknown`	Ask the user once (below), then go to step 3 if they agree.

问题指纹是由领域+症状组成的稳定的小写kebab-case格式slug。要确保另一个Agent在另一个场景中遇到相同问题时，会使用相同的slug。不要包含场景特定的名称。

下表仅为格式示例，并非真实上报内容。

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

bash

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

第一行输出	操作建议
`not-reported`	进入步骤3。
`reported`	该场景已上报过此问题。应用变通方案即可，无需提及上报事宜。
`consent:denied`	用户已拒绝，或上报功能已禁用。应用变通方案。切勿再次询问。
`consent:unknown`	询问用户一次（见下文），若用户同意则进入步骤3。

Asking for consent (once per scene)

征求用户同意（每个场景仅一次）

Ask in plain language, and don't call any tool until the user answers:

"I ran into what looks like a bug in the Decentraland SDK: [one-line summary]. I'm going to work around it. Can I send a short description of SDK issues like this to the Decentraland team so they can fix them? It won't include your scene's code or any personal info, and I'll only ask once for this scene."

Record the answer:

bash

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

The answer is stored in a

.dcl-sdk-reports/

folder at the scene root, next to the record of sent reports. The folder carries its own

.gitignore

, so git ignores it without the scene's

.gitignore

being touched, and deploys leave it out like every path starting with a dot. Don't add it to

.gitignore

.dclignore

. If the user later says "stop sending SDK reports" or "you can send them again", run the matching command. Don't ask any other time.

Running as a subagent? There's no user to ask. On

consent:unknown

, skip the report, apply the workaround, and tell your caller that an SDK issue could be reported if the user agrees.

用平实的语言询问，在用户回答前不要调用任何工具：

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

记录用户的回答：

bash

node {baseDir}/scripts/report.mjs consent --grant   # 同意
node {baseDir}/scripts/report.mjs consent --deny    # 拒绝

回答会存储在场景根目录的

.dcl-sdk-reports/

文件夹中，与已发送报告的记录放在一起。该文件夹自带

.gitignore

，因此git会自动忽略它，无需修改场景的

.gitignore

，且部署时会像所有以点开头的路径一样被排除在外。不要将其添加到

.gitignore

或

.dclignore

中。如果用户之后说「停止发送SDK报告」或「你可以再次发送」，运行对应的命令即可。其他时候不要询问。

作为子Agent运行？ 没有可询问的用户。当状态为

consent:unknown

时，跳过上报，应用变通方案，并告知调用方：如果用户同意，可以上报该SDK问题。

3. Write and submit the report

3. 编写并提交报告

Write the report for an SDK engineer who has never seen this scene:

title (≤ 120 chars): the symptom, e.g. "Controlled Input does not clear when its value is reset to an empty string".
description (≤ 10,000 chars): what you expected, what happened, a minimal reproduction in generic SDK7 code (a few lines, not the user's code), and where it shows up (Explorer, preview, Creator Hub, CLI) if you know.
workaround (optional, ≤ 5,000 chars): what you're about to do instead.
kind:
```
bug
```
(behaves wrong),
```
limitation
```
(missing capability), or
```
docs-gap
```
(the docs or types are wrong or missing).
fingerprint: the slug from step 2.
skill (optional): the skill this falls under, e.g.
```
build-ui
```
.
agent (optional): your tool's name, e.g.
```
claude-code
```
,
```
cursor
```
.

Never include the user's scene code, asset names, URLs of their content, wallet addresses, names, emails, file paths, API keys, or tokens. The script redacts common patterns as a safety net, but you're the first line of defense.

The script adds the SDK version, OS, and Node version itself. Send the JSON on stdin:

bash

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

In a shell without heredocs (e.g. PowerShell), write the JSON to a temporary file outside the scene folder and pass

--file <path>

First line	Tell the user (one line)
`queued`	"I'm reporting this SDK issue to the Decentraland team: <title>."
`already-reported`	Nothing.
`invalid: …`	Fix the listed fields and submit again.
`consent:…`	You skipped step 2; go back to it.

submit

returns as soon as the report is saved: a background process sends it, so don't wait for it or check on it. Go straight to the workaround. Reporting never blocks the work. If the script errors out, carry on without it. If

consent

itself fails (for example, the scene folder is read-only), don't ask the user again during this session.

A report that couldn't be sent stays queued and is retried in the background on later

check

and

submit

runs, never duplicated. A report the service keeps failing on is given up after a few tries, and then the same issue can be reported again.

面向从未见过该场景的SDK工程师编写报告：

title（≤ 120字符）：症状描述，例如「Controlled Input does not clear when its value is reset to an empty string」。
description（≤ 10,000字符）：你预期的结果、实际发生的情况、通用SDK7代码的最小复现示例（只需几行，不要用用户的代码），以及出现问题的位置（Explorer、预览、Creator Hub、CLI）（如果你知道的话）。
workaround（可选，≤ 5,000字符）：你准备采用的变通方案。
kind：
```
bug
```
（行为错误）、
```
limitation
```
（功能缺失）或
```
docs-gap
```
（文档或类型定义错误/缺失）。
fingerprint：步骤2中的slug。
skill（可选）：该问题所属的Skill，例如
```
build-ui
```
。
agent（可选）：你使用的工具名称，例如
```
claude-code
```
、
```
cursor
```
。

绝对不要包含用户的场景代码、资源名称、其内容的URL、钱包地址、姓名、邮箱、文件路径、API密钥或令牌。脚本会自动脱敏常见模式作为安全网，但你是第一道防线。

脚本会自动添加SDK版本、操作系统和Node版本。通过标准输入发送JSON：

bash

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`	「我正在将此SDK问题上报给Decentraland团队：<title>。」
`already-reported`	无需告知。
`invalid: …`	修复列出的字段后重新提交。
`consent:…`	你跳过了步骤2，请返回执行。

submit

命令在报告保存后立即返回：后台进程会发送报告，因此无需等待或检查。直接去处理变通方案即可。上报永远不会阻塞工作。 如果脚本出错，直接继续工作即可。如果

consent

命令本身失败（例如场景文件夹是只读的），本次会话期间不要再询问用户。

无法发送的报告会保持排队状态，并在后续

check

和

submit

运行时在后台重试，绝不会重复提交。如果服务持续失败，报告在几次尝试后会被放弃，之后相同问题可以再次上报。

Reference

参考

Request and response contract for the reporting service:
```
{baseDir}/references/api.md
```
```
node {baseDir}/scripts/report.mjs status
```
shows the consent, the endpoint, and how many reports were sent, are pending, were rejected, or were given up after repeated failures.
```
node {baseDir}/scripts/report.mjs flush
```
sends queued reports right away and waits for the result. Only for troubleshooting; normal use never needs it.
To disable reporting on a machine or in CI, set
```
DCL_SDK_ISSUE_REPORTS=off
```
. This always wins over a stored consent.
```
DCL_SDK_ISSUE_REPORTS_URL
```
points the script at another service (an https URL). Set to
```
none
```
,
```
off
```
or empty, it keeps queueing reports without sending them.

上报服务的请求与响应约定：
```
{baseDir}/references/api.md
```
```
node {baseDir}/scripts/report.mjs status
```
显示授权状态、上报端点，以及已发送、待处理、已拒绝或多次失败后放弃的报告数量。
```
node {baseDir}/scripts/report.mjs flush
```
立即发送排队的报告并等待结果。仅用于故障排查；正常使用永远不需要。
要在某台机器或CI中禁用上报，设置
```
DCL_SDK_ISSUE_REPORTS=off
```
。该设置优先级始终高于存储的授权状态。
```
DCL_SDK_ISSUE_REPORTS_URL
```
将脚本指向另一个服务（https URL）。设置为
```
none
```
、
```
off
```
或空值时，报告会继续排队但不会发送。