Contributing / 贡献指南

Contributions are welcome! Here's everything you need to get started.

欢迎贡献！以下是你需要了解的全部内容。

Quick Links / 快速链接

• Code of Conduct
• Issue Tracker
• Discussions

Prerequisites / 前置要求

• Rust 1.75+ — install via rustup
• Git
• Terminal with 256-color and Unicode support (for TUI testing)

Note for docs contributors: Node.js 18+ is only needed if you want to build the VitePress documentation site locally. Core Rust development does not require Node.js.

Clone and Build / 克隆并构建

# Clone the repository
git clone https://github.com/Agions/synerix.git
cd synerix

# Build the release binary
cargo build --release

# Run the TUI directly
cargo run --release

# Run all tests
cargo test --workspace

Development Setup / 开发环境

Rust Toolchain / Rust 工具链

# Install Rust via rustup (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify installation
rustc --version  # Should be 1.75+
cargo --version

Project Structure / 项目结构

synerix/
├── crates/
│   ├── synerix/           # Main binary + TUI application
│   │   ├── src/
│   │   │   ├── app/       # State machine, event loop, input handling
│   │   │   ├── tui/       # Ratatui widgets, theme, layout, renderer
│   │   │   ├── agent/     # Agent loop + orchestration
│   │   │   ├── tools/     # Tool registry + builtins
│   │   │   ├── skills/    # Skills system
│   │   │   ├── mcp/       # MCP protocol client
│   │   │   ├── sandbox/   # Security sandbox
│   │   │   ├── llm/       # LLM adapters + streaming
│   │   │   └── session/   # SQLite persistence
│   │   └── Cargo.toml
│   └── synerix-core/      # Shared types + utilities
├── docs/                  # VitePress documentation
├── benches/               # Performance benchmarks
└── Cargo.toml             # Workspace root

Code Standards / 代码规范

Formatting / 格式化

# Check formatting (CI enforces this)
cargo fmt --all -- --check

# Auto-format all code
cargo fmt --all

Linting / 代码检查

# Run clippy with all warnings as errors (CI enforces this)
cargo clippy --all-targets --all-features -- -D warnings

# Quick type check without full build
cargo check --all-targets

Testing / 测试

# All tests
cargo test --workspace

# Unit tests only (faster)
cargo test --lib

# With output
cargo test -- --nocapture

# Specific test
cargo test test_name

Commit Convention / 提交规范

We use Conventional Commits. Each commit message should be clear and descriptive.

我们使用 Conventional Commits 规范。每条提交信息都应清晰且有描述性。

feat: add slash menu widget
fix: correct scroll offset calculation
refactor: extract widget primitives
docs: update getting started guide
style: align rustfmt settings
test: add integration tests for MCP
chore: bump ratatui to 0.30

Pull Request Process / PR 流程

1. Fork the repo on GitHub
2. Create a branch: git checkout -b feat/your-feature
3. Make changes and ensure tests pass: cargo test --workspace
4. Lint and format: cargo fmt --all && cargo clippy --all-targets -- -D warnings
5. Commit with a clear message following Conventional Commits
6. Push to your fork: git push origin feat/your-feature
7. Open a PR on GitHub with a clear description

PR Checklist / PR 检查清单

• [ ] cargo fmt --all passes without changes
• [ ] cargo clippy --all-targets -- -D warnings passes
• [ ] cargo test --workspace passes
• [ ] Commit messages follow Conventional Commits
• [ ] Documentation updated if needed

Common Issues / 常见问题

Issue / 问题	Solution / 解决方案
cargo: command not found	Install Rust via curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
error: linker 'cc' not found	Install Xcode command line tools: xcode-select --install (macOS) or sudo apt install build-essential (Linux)
TUI renders incorrectly	Ensure your terminal supports 256 colors and Unicode; set TERM=xterm-256color
Tests hang or timeout	Some tests require network; run cargo test --lib for unit tests only
cargo fmt CI failure	Run cargo fmt --all before committing
Clippy warnings	Fix all warnings; CI uses -D warnings (treats warnings as errors)

License / 许可证

By contributing, you agree that your contributions will be licensed under the MIT License.