report-sdk-issue

SDK の問題を報告する

シーンで SDK、エンジン、または Explorer の不具合に遭遇し、回避策を適用しようとしている場合は、まず報告してください。SDK チームは報告を参考にプラットフォームを修正します。修正されれば、今後のすべてのシーンで回避策が不要になります。

すべて {baseDir}/scripts/report.mjs という 1 つのスクリプトを通じて処理します（Node ≥ 18、依存関係なし）。出力の 1 行目は常に結果トークンです。その行を確認してください。スクリプトを実行してください。内容を読むためにスクリプトや scripts/redaction.mjs を開かないでください。このページに必要な情報はすべて記載されており、それらを読むだけでも時間がかかります。

1. 報告対象かどうかを判断する

次のすべてに当てはまる場合は報告してください。

• 問題がシーンではなくプラットフォームにある：SDK7 の API、コンポーネント、またはシステムの動作がドキュメントや型定義と異なる、Explorer での表示や実行に誤りがある、Creator Hub または @dcl/sdk CLI が失敗する、あるいはシーンで必要とされる機能が存在しない。
• 回避策を適用しようとしている、またはユーザーに実現できないと伝えなければならない。
• その問題が既知の問題としてすでにスキルに記載されていない（該当するスキルの注意点／「既知の問題」の注記を確認してください）。既知の問題はすでに追跡されています。

ユーザーのコードの誤り、自分による API の誤用、ユーザー側のネットワークやウォレットの問題、または何も妨げていない機能のアイデアは報告しないでください。

2. フィンガープリントを選び、確認する

フィンガープリントは、領域＋症状を表す、安定した小文字のケバブケースのスラッグです。別のシーンで同じ問題に遭遇した別のエージェントが、同じスラッグを選ぶようにしてください。シーン固有の名前は含めないでください。

以下の表は形式を示すための架空の例です。実際の報告ではありません。

問題（例）	フィンガープリント
制御された Input で、値をリセットしても古いテキストが残る	ui-input-controlled-reset
親エンティティに設定された Tween が、親の回転を無視する	tween-parent-rotation-ignored
loop: true の AudioSource が Explorer で最初のループの後に停止する	audio-source-loop-stops
ドキュメントでは getPlayer() が wearables を返すとあるが、実際は未定義である	docs-get-player-wearables-missing

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

1 行目	対応方法
not-reported	手順 3 に進みます。
reported	このシーンからはすでに報告済みです。回避策を適用し、報告については何も言わないでください。
consent:denied	ユーザーが同意しなかったか、報告が無効になっています。回避策を適用してください。再度尋ねないでください。
consent:unknown	以下の手順で一度だけユーザーに尋ね、同意した場合は手順 3 に進みます。

同意を尋ねる（シーンごとに一度）

平易な言葉で尋ね、ユーザーが回答するまでツールを呼び出さないでください。

"Decentraland SDK のバグと思われる問題に遭遇しました：[問題の概要を 1 行で記載]。回避策を適用します。このような SDK の問題について、修正のために Decentraland チームへ簡単な説明を送ってもよいですか？シーンのコードや個人情報は含まれません。また、このシーンでは一度だけお尋ねします。"

回答を記録します。

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

回答はシーンのルートにある .dcl-sdk-reports/ フォルダーに保存されます。このフォルダーには専用の .gitignore が含まれているため、シーンの .gitignore に手を加えなくても git に無視されます。また、ドットで始まるすべてのパスと同様に、デプロイ対象から除外されます。.gitignore や .dclignore には追加しないでください。ユーザーが後から「SDK の報告を停止して」または「再び報告してよい」と言った場合は、対応するコマンドを実行してください。それ以外のタイミングで尋ねないでください。

サブエージェントとして実行していますか？ ユーザーに尋ねることはできません。consent:unknown の場合は報告をスキップして回避策を適用し、ユーザーが同意すれば SDK の問題を報告できることを呼び出し元に伝えてください。

3. レポートを作成して送信する

この状況を見たことがない SDK エンジニア向けに、レポートを作成します。

• title（120 文字以内）：症状を記載します。例：「値を空文字列にリセットしても、Controlled Input がクリアされない」。
• description（10,000 文字以内）：期待していた動作、実際に起きたこと、汎用的な SDK7 コードでの最小再現例（ユーザーのコードではなく数行）、および発生箇所（分かる場合は Explorer、プレビュー、Creator Hub、CLI）を記載します。
• workaround（任意、5,000 文字以内）：代わりに行う予定の方法を記載します。
• kind：bug（動作が誤っている）、limitation（機能がない）、または docs-gap（ドキュメントや型が誤っている、または不足している）。
• fingerprint：手順 2 のスラッグです。
• skill（任意）：該当するスキルです。例：build-ui。
• agent（任意）：使用しているツールの名前です。例：claude-code、cursor。

絶対に含めないでください：ユーザーのシーンコード、アセット名、コンテンツの URL、ウォレットアドレス、名前、メールアドレス、ファイルパス、API キー、トークン。スクリプトは安全策として一般的なパターンを自動的に削除しますが、最初に情報を守るのはあなたです。

スクリプトが SDK バージョン、OS、Node バージョンを自動的に追加します。JSON を stdin から渡してください。

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

ヒアドキュメントを使えないシェル（PowerShell など）では、シーンフォルダーの外に一時ファイルとして JSON を書き込み、--file <path> を渡してください。

1 行目	ユーザーへの説明（1 行）
queued	"この SDK の問題を Decentraland チームに報告しています：。"
already-reported	何も伝えません。
invalid: …	指摘されたフィールドを修正して、もう一度送信してください。
consent:…	手順 2 をスキップしています。手順 2 に戻ってください。

submit はレポートが保存されるとすぐに戻ります。バックグラウンドプロセスが送信するため、待ったり状況を確認したりしないでください。そのまま回避策に進んでください。報告によって作業が止まることはありません。 スクリプトでエラーが発生した場合は、そのまま作業を続けてください。consent 自体が失敗した場合（例：シーンフォルダーが読み取り専用の場合）、このセッション中にユーザーへ再度確認しないでください。

送信できなかったレポートはキューに残り、後続の check と submit の実行時にバックグラウンドで再試行されます。重複して送信されることはありません。サービス側で繰り返し失敗するレポートは、数回の試行後に送信を断念します。その後は同じ問題を再度報告できます。

リファレンス

• 報告サービスのリクエストとレスポンスの仕様：{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、または空に設定すると、送信せずにレポートをキューに残します。