FSMN VAD社区贡献指南：提交PR和issue的正确姿势

1. 贡献背景与价值

1.1 开源项目的重要性

FSMN VAD 是基于阿里达摩院 FunASR 框架开发的语音活动检测（Voice Activity Detection, VAD）模型，具备高精度、低延迟和轻量级等优势。该项目已被广泛应用于会议录音处理、电话分析、音频质量检测等多个实际场景。

随着社区用户的不断增长，越来越多开发者希望参与到项目的优化与功能扩展中。为了保障代码质量和协作效率，建立一套清晰、规范的贡献流程至关重要。

本指南旨在为所有希望参与 FSMN VAD 项目维护和改进的开发者提供标准化的操作指引，涵盖 issue 提交、PR 创建、代码风格要求以及审核流程等内容。

1.2 社区协作的核心原则

尊重开源精神：所有贡献均应以提升项目稳定性、可用性和可维护性为目标。
问题先行，实现跟进：建议在提交 Pull Request 前先通过 Issue 明确需求或 Bug。
文档同步更新：功能变更需同步修改相关说明文档，确保用户能及时获取最新信息。
保持沟通透明：鼓励在 PR 和 Issue 中积极讨论技术方案，避免闭门造车。

2. 如何正确提交 Issue

2.1 提交前的自查清单

在创建新的 Issue 之前，请务必完成以下检查：

✅ 是否已在已有 Issues 中搜索过类似问题？
✅ 是否阅读了官方文档并确认是项目本身的缺陷而非使用不当？
✅ 是否能够复现该问题？是否准备了最小可复现示例？

若以上均为“是”，则可以继续提交 Issue。

2.2 Issue 分类与模板

根据问题性质，Issue 可分为三类，每类对应不同的标题前缀和内容结构：

类型	标题前缀	适用场景
Bug 报告	`[BUG]`	功能异常、崩溃、结果错误等
功能请求	`[FEATURE]`	新增功能或模块建议
使用咨询	`[QUESTION]`	安装、配置、参数调优等问题

示例：Bug 报告模板

[BUG] 批量处理长音频时内存溢出 **环境信息** - Python 版本: 3.9.16 - FSMN VAD 版本: v1.2.0 - 操作系统: Ubuntu 20.04 - 硬件: CPU-only, 内存 8GB **问题描述** 当上传一个时长超过 30 分钟的 `.wav` 文件进行批量处理时，服务自动终止，终端输出 `MemoryError`。 **复现步骤** 1. 启动 WebUI：`python app.py` 2. 进入「批量处理」页面 3. 上传 35 分钟的单声道 WAV 音频（16kHz, 16bit） 4. 点击“开始处理” **预期行为** 正常返回语音片段列表 **实际行为** 服务崩溃，日志显示内存耗尽 **附加信息** - 音频文件大小：约 330MB - 其他短音频（<5分钟）处理正常

示例：功能请求模板

[FEATURE] 支持实时流式麦克风输入 **需求背景** 目前实时流式功能仅支持网络流输入，缺少本地麦克风采集能力，在语音交互测试场景下不够便捷。 **期望功能** - 在「实时流式」页面增加“启用麦克风”按钮 - 支持浏览器权限授权后采集音频流 - 实时显示语音片段时间戳 **参考实现** 可借鉴 Web Audio API + MediaRecorder 的前端方案，后端采用 chunk 流式推理

3. 如何提交高质量的 Pull Request

3.1 PR 准备流程

一个高质量的 PR 应遵循以下流程：

Fork 仓库
访问 FSMN VAD GitHub 主页，点击右上角Fork按钮创建个人副本。

克隆到本地

git clone https://github.com/your-username/fsmn-vad.git cd fsmn-vad

创建特性分支
```
git checkout -b feat/microphone-input
```
编码与测试
修改代码，并确保通过本地测试（如有）。

提交并推送

git add . git commit -m "feat: add microphone input support" git push origin feat/microphone-input

发起 PR
回到 GitHub 页面，点击 “Compare & pull request”。

3.2 PR 内容规范

必须包含的内容

清晰的标题：使用语义化前缀，如：
- feat:新功能
- fix:修复 Bug
- docs:文档更新
- refactor:重构代码
- test:添加测试用例
详细描述说明
包括：
- 解决的问题（关联 Issue 编号）
- 实现思路简述
- 是否影响现有接口
- 是否需要文档更新
代码质量要求
- 符合 PEP8 规范（推荐使用black或autopep8格式化）
- 添加必要的注释，尤其是核心逻辑部分
- 不引入未使用的依赖
- 尽量不修改无关文件

示例 PR 描述

feat: implement microphone input for real-time streaming Closes #45 ## 概述 本 PR 实现了「实时流式」页面的浏览器麦克风音频采集功能，用户可通过点击按钮启动录音，系统将分块发送至后端进行流式 VAD 检测。 ## 技术实现 - 前端使用 Web Audio API 获取麦克风流 - 通过 WebSocket 发送 16kHz 单声道 PCM 数据块（每 200ms 一帧） - 后端新增 `/ws/vad/stream` 接口接收流数据并返回实时检测结果 - UI 实时展示语音段起止时间 ## 影响范围 - 新增文件：`app.py`, `templates/index.html`, `static/js/mic.js` - 修改文件：`requirements.txt`（添加 websockets） ## 测试情况 - Chrome 120+ 正常运行 - Safari 存在兼容性问题（已标注 TODO）

4. 代码审查与合并流程

4.1 自动化检查机制

所有 PR 将触发 CI/CD 流水线，包括：

代码格式检查（flake8 / black）
依赖安全扫描（safety check）
基本功能测试（unittest）

若任一环节失败，PR 将被标记为 ❌，需修复后再重新触发。

4.2 人工评审要点

维护者将从以下几个维度评估 PR 质量：

维度	审查重点
功能完整性	是否完整解决所提问题
架构合理性	是否符合现有设计模式
性能影响	是否引入显著资源消耗
用户体验	是否破坏 UI/UX 一致性
文档同步	是否更新 README 或手册

4.3 常见拒绝原因

未填写 PR 描述或描述不清
修改范围过大且无拆分计划
引入非必要第三方库
未处理边界条件（如空输入、异常中断）
与项目长期方向不符的功能

提示：对于大型功能（如新增模块），建议先提交 RFC（Request for Comments）Issue 进行设计讨论，达成共识后再编码。

5. 最佳实践与避坑指南

5.1 高效协作技巧

小步快跑：将大功能拆分为多个小 PR，便于快速反馈
及时沟通：若 PR 长时间未被 review，可在评论中礼貌提醒
关注反馈：对 reviewer 提出的意见应及时回应，即使不同意也应说明理由

5.2 常见误区警示

误区	正确做法
直接在 main 分支开发	使用独立 feature 分支
一次提交大量无关更改	按功能拆分多次提交
忽略测试覆盖	至少保证主路径有测试
修改他人代码不通知	在 PR 中 @ 相关作者