CONTRIBUTING_ZH.md

参与贡献

英文版本请查看 CONTRIBUTING.md。

感谢你为 py-xiaozhi 做出贡献。我们欢迎 Bug 反馈、文档修复、测试补充、工具链改进，以及范围清晰的新功能。

开始之前

• 提交前先搜索现有的 Issue 和 Pull Request，避免重复。
• 对于较大的新功能、架构调整或行为变更，建议先开 Issue 讨论。
• 文档修复、小型 Bug 修复和聚焦明确的改进，一般可以直接提交 Pull Request。

开发环境

基本要求

• Python >=3.10
• Git
• 如果需要验证音频能力，请准备可用的麦克风和扬声器

安装依赖

git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi

# 基础安装
uv sync

# GUI + 开发工具
uv sync --extra gui --group dev

如果你不使用 uv，可以使用以下兼容方案：

pip install -e .
pip install -e '.[gui]'
pip install pytest pytest-asyncio ruff pyinstaller

开发流程

1. Fork 仓库，并从 main 创建功能分支。
2. 尽量让每次修改只聚焦一个问题、一个功能或一类文档更新。
3. 提交信息遵循 Conventional Commits，例如 fix(audio): handle empty frame。
4. 如果修改影响行为、配置或公共接口，请同步更新文档。
5. 如果修改涉及正确性或回归风险，请补充或更新测试。

推荐分支命名：

• feature/xxx
• fix/xxx
• docs/xxx
• refactor/xxx
• test/xxx

质量要求

提交 Pull Request 前，请根据改动类型运行相应检查：

ruff check .
ruff format .
pytest

如有必要，也请验证对应运行路径，例如：

• GUI 改动：运行 python main.py
• CLI 改动：运行 python main.py --mode cli
• 协议改动：验证 websocket 或 mqtt
• 文档改动：在 documents/ 下本地预览

Pull Request 要求

每个 Pull Request 都应尽量满足以下要求：

• 清楚说明问题背景和解决方案。
• 如有相关 Issue，请附上关联链接。
• 提供必要的验证步骤、截图或日志，方便审核。
• 保持改动范围合理，避免混入无关重构。
• 遵循现有代码风格和项目结构。

Maintainer Workflow

维护者通常会按以下流程审核贡献：

1. 先将改动归类为 bug、feature、docs、refactor 或 maintenance。
2. 确认改动范围是否清晰、问题是否可复现、方向是否符合项目规划。
3. 检查测试、文档和验证证据，再决定是否提出修改意见或批准。
4. 在 CI 通过且反馈处理完成后合并。
5. 合并后按正常发布流程进入后续版本，合并不等于立即发布。

详细文档

• 项目文档：https://huangjunsen0406.github.io/py-xiaozhi/
• 详细贡献指南（英文）：https://huangjunsen0406.github.io/py-xiaozhi/en/contributing
• 详细贡献指南（中文）：https://huangjunsen0406.github.io/py-xiaozhi/contributing

再次感谢你的贡献。