贡献指南
参与贡献
开发环境搭建、常用命令、测试与 Git 工作流
参与贡献
欢迎为 ZapMomo 贡献代码！本篇面向想参与开发的同学，介绍从零搭建开发环境到提交 PR 的完整流程；如果你只是想使用 ZapMomo，请看快速开始。
开发环境
| 工具 | 版本 | 用途 |
|---|---|---|
| Rust | 1.97.1（由 rust-toolchain.toml 固定） | 编译 / 测试 / Lint / Format |
| pnpm | 任意现代版本 | Tauri CLI 与文档站依赖管理 |
| Linux 额外依赖 | webkit2gtk 等 | 构建桌面应用（zapmomo-app）需要 |
克隆仓库后，cargo build 首次编译会自动拉取 sherpa-onnx 预编译库；如在代理环境下下载失败，可设置 SHERPA_ONNX_LIB_DIR 指向已缓存的库目录。
常用命令
核心 CLI
# 开发
cargo run # 直接运行（无参进入帮助）
cargo run -- config # 显示配置
cargo run -- completion bash # 生成 shell 补全
# 测试
cargo test
cargo test -- --test-threads=1 # 单线程测试（避免 env 竞争）
# 代码质量
cargo fmt # 格式化代码
cargo fmt --check # 格式检查
cargo clippy -- -D warnings # 严格 Lint 检查
# 完整检查（CI 同款）
cargo fmt --check && cargo clippy -- -D warnings && cargo test
# 覆盖率
cargo tarpaulin桌面应用（Tauri 2，位于 src-tauri/）
# 安装 Tauri CLI（首次）
pnpm install
# 开发模式（热重载，需已下载模型：cargo run -- kws install-model）
pnpm tauri dev
# 构建当前平台安装包（macOS: .app/.dmg）
pnpm tauri build
# 仅检查 / Lint tauri crate（Linux 需 webkit 依赖）
cargo check -p zapmomo-app
cargo clippy -p zapmomo-app -- -D warnings测试
# 常规测试（不依赖模型）
cargo test -- --test-threads=1
# 模型相关测试（需先下载模型）
./scripts/run-kws-model-tests.shKWS / ASR / TTS / LLM 模型不入库，按 models/manifest.json 清单下载（详见模型来源与校验）：
cargo run -- kws install-model # 或 asr / tts install-model已知限制（开发模式）
pnpm tauri dev 下点击「重启」（设置页 / 右键菜单 / 托盘）后新进程会白屏：Tauri 内置重启不重跑 beforeDevCommand，而 tauri dev 在应用退出时会拆掉 Vite dev server，新进程连不上 localhost:1420（tauri#6163）。需要重启效果时请手动重跑 pnpm tauri dev；生产打包版重启正常。
Git 工作流
分支命名
feature/xxx— 新功能fix/xxx— Bug 修复docs/xxx— 文档更新refactor/xxx— 重构
Commit 规范
<type>(<scope>): <description>
[optional body]| 类型 | 说明 |
|---|---|
feat | 新功能 |
fix | Bug 修复 |
docs | 文档更新 |
style | 代码格式 |
refactor | 重构 |
perf | 性能优化 |
test | 测试相关 |
chore | 构建 / 工具 |
提交 PR
- 从
main切出符合命名规范的分支。 - 开发并确保本地通过完整检查：
cargo fmt --check && cargo clippy -- -D warnings && cargo test（涉及桌面应用时另跑cargo clippy -p zapmomo-app -- -D warnings）。 - 按规范提交 commit，推送并向
main发起 PR，描述清楚动机与改动点。 - CI 通过、Review 通过后合并；版本发布由 release-plz 自动完成，无需手动 bump。