Refine GitHub issue forms (#2128)

Co-authored-by: Xiaoxia <terrence.huang@tenclass.com>
This commit is contained in:
Xiaoxia
2026-07-19 02:10:46 +08:00
committed by GitHub
co-authored by Xiaoxia
parent 3dea6e7f84
commit cb06516bea
8 changed files with 335 additions and 225 deletions
@@ -0,0 +1,77 @@
name: Build, setup, or flashing problem
description: Report a reproducible problem setting up, building, or flashing the firmware
title: "[Build] "
labels: ['bug']
body:
- type: markdown
attributes:
value: |
This form is for the open-source firmware. For device unbinding, email [xiaozhi.ai@tenclass.com](mailto:xiaozhi.ai@tenclass.com?subject=Device%20unbinding%20request) privately with the device ID and MAC address. Use the [XiaoZhi AI website](https://xiaozhi.me/) for other account and cloud-service requests.
- type: checkboxes
id: checklist
attributes:
label: Before submitting
options:
- label: I have tested a current source version and searched for an existing issue reporting the same problem.
required: true
- type: input
id: board
attributes:
label: Board or device
description: Enter the physical product/model and the selected board target or build variant.
placeholder: ex. Waveshare ESP32-S3-Touch-LCD-3.5B; target waveshare/esp32-s3-touch-lcd-3.5b
validations:
required: true
- type: input
id: source_version
attributes:
label: XiaoZhi source version
description: Paste the complete output of `git describe --tags --always --dirty`. Do not enter "latest".
placeholder: ex. v2.2.6-15-g1a2b3c4
validations:
required: true
- type: input
id: esp_idf_version
attributes:
label: ESP-IDF version
description: Paste the complete output of `idf.py --version`.
placeholder: ex. ESP-IDF v6.0.2
validations:
required: true
- type: textarea
id: problem
attributes:
label: Problem and reproduction steps
description: State what you tried, the exact commands or steps, what you expected, what happened, and any relevant local changes.
placeholder: |
Operating system:
Command or steps:
Expected result:
Actual result:
Local changes, if any:
validations:
required: true
- type: textarea
id: logs
attributes:
label: Complete error output
description: Paste the output from the first error through the final failure. Remove credentials, tokens, usernames, and other private information.
placeholder: Paste the complete output here, not only the final error line.
render: shell
validations:
required: true
- type: upload
id: attachments
attributes:
label: Optional files
description: Attach logs or a ZIP containing relevant configuration files. Review files for secrets first.
validations:
required: false
accept: ".log,.txt,.json,.zip"
@@ -1,103 +0,0 @@
name: Installation or build bug report
description: Report installation or build bugs
labels: ['bug']
body:
- type: checkboxes
id: checklist
attributes:
label: Answers checklist.
description: Before submitting a new issue, please follow the checklist and try to find the answer.
options:
- label: I have read the documentation [XiaoZhi AI Programming Guide](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb) and the issue is not addressed there.
required: true
- label: I have updated my branch (master or release) to the latest version and checked that the issue is present there.
required: true
- label: I have searched the issue tracker for a similar issue and not found a similar issue.
required: true
- type: input
id: xiaozhi_ai_version
attributes:
label: XiaoZhi AI version.
description: On which XiaoZhi AI version does this issue occur on? Run `git describe --tags` to find it.
placeholder: ex. v1.1.0-44-g140aab8
validations:
required: true
- type: dropdown
id: operating_system
attributes:
label: Operating System used.
multiple: false
options:
- Windows
- Linux
- macOS
validations:
required: true
- type: dropdown
id: build
attributes:
label: How did you build your project?
multiple: false
options:
- Command line with CMake
- Command line with idf.py
- CLion IDE
- VS Code IDE/Cursor
- Other (please specify in More Information)
validations:
required: true
- type: dropdown
id: windows_comand_line
attributes:
label: If you are using Windows, please specify command line type.
multiple: false
options:
- PowerShell
- CMD
validations:
required: false
- type: textarea
id: expected
attributes:
label: What is the expected behavior?
description: Please provide a clear and concise description of the expected behavior.
placeholder: I expected it to...
validations:
required: true
- type: textarea
id: actual
attributes:
label: What is the actual behavior?
description: Please describe actual behavior.
placeholder: Instead it...
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce.
description: 'How do you trigger this bug? Please walk us through it step by step. If this is build bug, please attach sdkconfig file (from your project folder). Please attach your code here.'
value: |
1. Step
2. Step
3. Step
...
validations:
required: true
- type: textarea
id: debug_logs
attributes:
label: Build or installation Logs.
description: Build or installation log goes here, should contain the backtrace, as well as the reset source if it is a crash.
placeholder: Your log goes here.
render: plain
validations:
required: false
- type: textarea
id: more-info
attributes:
label: More Information.
description: Do you have any other information from investigating this?
placeholder: ex. Any more.
validations:
required: false
+57 -95
View File
@@ -1,115 +1,77 @@
name: Runtime bug report
description: Report runtime bugs
name: Device runtime bug
description: Report a reproducible firmware problem while a device is running
title: "[Bug] "
labels: ['bug']
body:
- type: markdown
attributes:
value: |
This form is for the open-source device firmware. For device unbinding, email [xiaozhi.ai@tenclass.com](mailto:xiaozhi.ai@tenclass.com?subject=Device%20unbinding%20request) privately with the device ID and MAC address. Use the [XiaoZhi AI website](https://xiaozhi.me/) for other account and cloud-service requests.
- type: checkboxes
id: checklist
attributes:
label: Answers checklist.
description: Before submitting a new issue, please follow the checklist and try to find the answer.
label: Before submitting
options:
- label: I have read the documentation [XiaoZhi AI Programming Guide](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb) and the issue is not addressed there.
required: true
- label: I have updated my firmware to the latest version and checked that the issue is present there.
required: true
- label: I have searched the issue tracker for a similar issue and not found a similar issue.
- label: I have tested the latest applicable firmware and searched for an existing issue reporting the same problem.
required: true
- type: input
id: xiaozhi_ai_firmware_version
id: device
attributes:
label: XiaoZhi AI firmware version.
description: On which firmware version does this issue occur on?
placeholder: ex. v1.2.1_bread-compact-wifi
label: Device or development board
description: Enter the manufacturer, exact product/model, and hardware revision or SKU when known.
placeholder: ex. LilyGO T-Circle-S3 V1.1 or EchoEar N16R8
validations:
required: true
- type: dropdown
id: operating_system
- type: input
id: firmware_version
attributes:
label: Operating System used.
multiple: false
options:
- Windows
- Linux
- macOS
label: Firmware version
description: Paste the `App version:` value from the startup log. Do not enter a board name or "latest".
placeholder: ex. 2.2.6
validations:
required: true
- type: dropdown
id: build
- type: input
id: firmware_source
attributes:
label: How did you build your project?
multiple: false
options:
- Command line with CMake
- Command line with idf.py
- CLion IDE
- VS Code IDE/Cursor
- Other (please specify in More Information)
label: Firmware source or filename
description: State where the firmware came from and include its filename or board target when available.
placeholder: ex. xiaozhi.me, GitHub release echoear.bin, self-built target df-k10, or vendor firmware
validations:
required: true
- type: dropdown
id: windows_comand_line
- type: textarea
id: problem
attributes:
label: If you are using Windows, please specify command line type.
multiple: false
options:
- PowerShell
- CMD
label: Problem and reproduction steps
description: Describe the starting state, exact actions, expected result, actual result, frequency, and any relevant modifications.
placeholder: |
Steps:
Expected result:
Actual result:
Frequency:
Modifications, if any:
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Logs or other evidence
description: Paste relevant startup and failure logs, including a backtrace or reset reason when applicable. If logs are unavailable, briefly say why. Remove credentials, device IDs, MAC addresses, UUIDs, and other private information.
placeholder: Paste relevant logs here, or explain why logs cannot be collected.
render: shell
validations:
required: true
- type: upload
id: attachments
attributes:
label: Optional photos, videos, or log files
description: Attach files that help identify the hardware or demonstrate the failure. Review files for private information first.
validations:
required: false
- type: dropdown
id: power_supply
attributes:
label: Power Supply used.
multiple: false
options:
- USB
- External 5V
- External 3.3V
- Battery
validations:
required: true
- type: textarea
id: expected
attributes:
label: What is the expected behavior?
description: Please provide a clear and concise description of the expected behavior.
placeholder: I expected it to...
validations:
required: true
- type: textarea
id: actual
attributes:
label: What is the actual behavior?
description: Please describe actual behavior.
placeholder: Instead it...
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce.
description: 'How do you trigger this bug? Please walk us through it step by step. Please attach your code here.'
value: |
1. Step
2. Step
3. Step
...
validations:
required: true
- type: textarea
id: debug_logs
attributes:
label: Debug Logs.
description: Debug log goes here, should contain the backtrace, as well as the reset source if it is a crash.
placeholder: Your log goes here.
render: plain
validations:
required: false
- type: textarea
id: more-info
attributes:
label: More Information.
description: Do you have any other information from investigating this?
placeholder: ex. Any more.
validations:
required: false
accept: ".png,.jpg,.jpeg,.gif,.mp4,.mov,.webm,.log,.txt,.zip"
+37 -21
View File
@@ -1,34 +1,50 @@
name: Feature request
description: Suggest an idea for this project.
description: Propose an improvement to a supported device or the common firmware
title: "[Feature] "
labels: ['enhancement']
body:
- type: markdown
attributes:
value: |
* We welcome any ideas or feature requests! Its helpful if you can explain exactly why the feature would be useful.
* There are usually some outstanding feature requests in the [existing issues list](https://github.com/78/xiaozhi-esp32/labels/enhancement), feel free to add comments to them.
* If you would like to contribute, please read the [contributions guide](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb).
- type: textarea
id: problem-related
Use the **Board support request** form for a new board, hardware revision, or product variant. Account and cloud-product requests belong on the [XiaoZhi AI website](https://xiaozhi.me/).
- type: checkboxes
id: checklist
attributes:
label: Is your feature request related to a problem?
description: Please provide a clear and concise description of what the problem is.
placeholder: ex. I'm always frustrated when ...
label: Before submitting
options:
- label: I have searched the existing feature requests and did not find the same proposal.
required: true
- type: input
id: scope
attributes:
label: Affected device or area
description: Enter the device, board target, or firmware area. Enter "All devices" for a general request.
placeholder: ex. df-k10, audio, display, protocol, or All devices
validations:
required: true
- type: textarea
id: problem
attributes:
label: Problem or use case
description: Explain the current limitation and why the requested change would be useful.
validations:
required: true
- type: textarea
id: solution
attributes:
label: Describe the solution you'd like.
description: Please provide a clear and concise description of what you want to happen.
placeholder: ex. When using XiaoZhi ...
- type: textarea
id: alternatives
attributes:
label: Describe alternatives you've considered.
description: Please provide a clear and concise description of any alternative solutions or features you've considered.
placeholder: ex. Choosing other approach wouldn't work, because ...
label: Requested behavior
description: Describe the result or behavior you would like to see.
validations:
required: true
- type: textarea
id: context
attributes:
label: Additional context.
description: Please add any other context or screenshots about the feature request here.
placeholder: ex. This would work only when ...
label: Additional context
description: Optionally add alternatives, screenshots, diagrams, links, or testing information.
validations:
required: false
@@ -0,0 +1,67 @@
name: Board support request
description: Request support for a new board, product, hardware revision, or SKU
title: "[Board Support] "
labels: ['enhancement']
body:
- type: markdown
attributes:
value: |
Similar-looking products may use different pins and components. Please identify the exact hardware rather than only naming the closest supported board.
- type: checkboxes
id: checklist
attributes:
label: Before submitting
options:
- label: I have searched the repository and existing issues for this exact model and hardware revision.
required: true
- type: textarea
id: hardware
attributes:
label: Exact hardware
description: Provide the manufacturer, model, revision/SKU, main chip and memory, and an official product or hardware documentation link.
placeholder: |
Manufacturer and model:
Revision or SKU:
Chip, flash, and PSRAM:
Official link:
validations:
required: true
- type: textarea
id: request
attributes:
label: Requested support
description: Describe what should work and any known differences from the closest supported board.
validations:
required: true
- type: textarea
id: attempted
attributes:
label: What have you tried?
description: Include the closest board target or firmware, its version, and the result. Enter "None" if no existing target is appropriate.
validations:
required: true
- type: dropdown
id: testing
attributes:
label: Testing available
options:
- I can build, flash, collect logs, and test changes
- I can flash binaries and test changes
- I can provide hardware information only
- I cannot test changes
validations:
required: true
- type: upload
id: attachments
attributes:
label: Optional hardware files, photos, or logs
description: Attach public schematics, board photos, pinouts, or serial logs. Do not upload confidential material or secrets.
validations:
required: false
accept: ".png,.jpg,.jpeg,.pdf,.log,.txt,.json,.zip"
@@ -0,0 +1,42 @@
name: Firmware development question
description: Ask a focused technical question about this repository or supported hardware
title: "[Question] "
labels: ['question']
body:
- type: markdown
attributes:
value: |
This form is for technical questions about the open-source firmware. For device unbinding, email [xiaozhi.ai@tenclass.com](mailto:xiaozhi.ai@tenclass.com?subject=Device%20unbinding%20request) privately with the device ID and MAC address. Other account and cloud-service requests belong on the [XiaoZhi AI website](https://xiaozhi.me/).
- type: checkboxes
id: checklist
attributes:
label: Before submitting
options:
- label: I have searched the repository and existing issues and did not find an answer.
required: true
- type: input
id: context
attributes:
label: Relevant device, version, or code area
description: Enter the device/model, board target, source or firmware version, file, or subsystem that matters to the question.
placeholder: ex. zhengchen-cam on v2.2.6, or main/audio on current main
validations:
required: true
- type: textarea
id: question
attributes:
label: Goal and question
description: Explain what you are trying to accomplish and state the specific technical question.
validations:
required: true
- type: textarea
id: attempted
attributes:
label: What have you tried?
description: Optionally include relevant files, commands, experiments, logs, screenshots, or a minimal example.
validations:
required: false
+6 -6
View File
@@ -1,8 +1,8 @@
blank_issues_enabled: true
blank_issues_enabled: false
contact_links:
- name: 小智 AI 官方网站
- name: Unbind a previously owned device
url: https://github.com/78/xiaozhi-esp32/blob/main/.github/SUPPORT.md#unbind-a-previously-owned-device
about: If the device is bound to another account, email its device ID and MAC address privately. Do not post these identifiers in a public issue.
- name: Other cloud services and account requests
url: https://xiaozhi.me/
about: 激活设备、配置 AI、声纹识别、声音克隆等应有尽有,DIY 属于你自己的小智
- name: 小智 AI 聊天机器人百科全书
url: https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb
about: 开发文档、硬件制作、烧录教程、FAQ尽在小智百科
about: Use the XiaoZhi AI website for activation, agent configuration, voiceprint, voice cloning, and other cloud services
+49
View File
@@ -0,0 +1,49 @@
# Account and Device Support
This GitHub repository tracks the open-source XiaoZhi device firmware. Account recovery, device ownership, and cloud-service requests are handled outside the public issue tracker.
## Unbind a Previously Owned Device
If you purchased or received a used device that is still bound to another person's account:
1. Collect the device ID and MAC address using the instructions below.
2. Email [xiaozhi.ai@tenclass.com](mailto:xiaozhi.ai@tenclass.com?subject=Device%20unbinding%20request) with both identifiers.
3. Use an email subject such as `Device unbinding / 解绑设备 - Device ID XXX - MAC address XXX`.
For multiple devices, attach a list containing the device ID and MAC address for each device.
> **Privacy:** Send device IDs and MAC addresses only by email. Do not post them in a public GitHub issue, discussion, screenshot, or log.
### Why Both Identifiers Are Required
- The **MAC address** uniquely identifies the physical device hardware.
- The **device ID** is obtained by asking the AI running on the device. Providing the value reported by the device helps demonstrate that the requester has the device in hand and can operate it.
Together, these identifiers help the support team locate the correct binding record and avoid unbinding the wrong device.
### Find the Device ID
If the device can connect and have a conversation, ask it:
> What is my device ID?
Record the complete value reported by the device. Both the device ID and MAC address are required for the standard unbinding process. If the device cannot have a conversation or does not return a device ID, explain this in the email; the support team may require other proof of possession. Do not guess or substitute a temporary activation code.
### Find the MAC Address
1. Connect the powered-on device to a computer with a data-capable USB cable.
2. Open the device's serial port with a serial terminal. Developers with an ESP-IDF environment can use `idf.py monitor`.
3. Keep the serial terminal open and restart the device so that the complete startup log is captured.
4. Search the log for a line similar to:
```text
wifi:mode : sta (aa:bb:cc:dd:ee:ff)
```
5. The value inside the parentheses is the Wi-Fi MAC address to include in the email.
If that line does not appear, search the startup log for `MAC` or `mac_address`. If you still cannot identify it, attach the exact device model and explain the situation in the private email. Do not upload the unredacted startup log to a public GitHub issue because it may contain the MAC address, UUID, Wi-Fi name, and other device information.
## Other Account and Cloud-Service Requests
For verification codes, password recovery, activation, agent configuration, voiceprint, voice cloning, and other cloud services, use the [XiaoZhi AI website](https://xiaozhi.me/).