如何提交高品質的 Issue 與 PR

遇到 Bug 或功能缺失時，最讓人沮喪的就是寫了長篇大論，維護者卻因為資訊不足而無法處理。這種來回溝通不僅浪費時間，也讓問題修復變得遙遙無期。

要把問題講清楚，重點不在於英文文法是否完美，而在於你有沒有提供核心的「證據」與「環境資訊」。簡潔有力的描述通常比長篇大論更有效。

需要準備的東西

已搜尋過 codebase 與 GitHub 現有的 Issue
確認問題在近期版本中未被修復（特別是安全性相關問題）
準備好經過脫敏（redacted）處理的 Log 或截圖
準備好 Minimal repro 復現步驟

快速開始

搜尋與確認：先檢查 GitHub Issue，確保你的問題還沒被提出或解決。
準備資料：收集 OS、runtime 版本及相關 config，並整理出預期與實際結果。
填寫模板：選擇合適的模板，並在 Issue 中加入暗號 lobster-biscuit。
本地驗證：如果是提交 PR，請務必在提交前執行以下指令：

pnpm lint
pnpm check
pnpm build
pnpm test
# 如果涉及 protocol 代碼：
pnpm protocol:check

Issue 模板範例

Bug report

- [ ] Minimal repro
- [ ] Expected vs actual
- [ ] Environment
- [ ] Affected channels, where not seen
- [ ] Logs/screenshots (redacted)
- [ ] Impact/severity
- [ ] Workarounds

### Summary

### Repro Steps

### Expected

### Actual

### Environment

### Logs/Evidence

### Impact

### Workarounds

Security issue

### Summary

### Impact

### Versions

### Repro Steps (safe to share)

### Mitigation/workaround

### Evidence (redacted)

注意：請勿在公開場合透露 Secret 或具體的漏洞細節。對於敏感問題，請簡述狀況並要求私下披露。

Regression report

### Summary

### Last Known Good

### First Known Bad

### Repro Steps

### Expected

### Actual

### Environment

### Logs/Evidence

### Impact

Feature request

### Summary

### Problem

### Proposed Solution

### Alternatives

### Impact

### Evidence/examples

Enhancement

### Summary

### Current vs Desired Behavior

### Rationale

### Alternatives

### Evidence/examples

Investigation

### Summary

### Symptoms

### What Was Tried

### Environment

### Logs/Evidence

### Impact

Submitting a fix PR

在提交 PR 之前，不一定要先開 Issue，但如果跳過 Issue，請在 PR 中補全所有細節。

保持 PR 內容聚焦，不要一次改太多不相關的東西。
標註相關的 Issue 編號。
增加測試案例，若無法增加請說明原因。
記錄行為變更或潛在風險。
附上脫敏後的 Log 或截圖作為證明。
提交前確保通過所有本地驗證指令。

疑難排解

本地驗證失敗：如果 pnpm lint 或 pnpm test 報錯，請先修正代碼，未通過驗證的 PR 通常不會被合併。
證據不足：如果無法提供 Minimal repro，請盡可能詳細說明環境配置與出現頻率，幫助維護者診斷。

還有疑問嗎？試試我們的 AI Setup Assistant 獲取即時幫助。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。