diff --git a/README.en-US.md b/README.en-US.md new file mode 100644 index 0000000..28a0b27 --- /dev/null +++ b/README.en-US.md @@ -0,0 +1,221 @@ +# StellarSpec + +[Simplified Chinese](README.md) | [English](README.en.md) + +🌟 **StellarSpec** - Smart Code Review Assistant + +A smart local code review tool based on large language models (LLM), developed in Go, built on the [Eino framework](https://github.com/cloudwego/eino). StellarSpec can automatically detect code changes in Git repositories and perform deep code reviews using AI large models, helping developers identify potential issues and optimize code quality. + +## ✨ Feature Highlights + +Implemented (Currently Available) +- 🔍 Smart Code Analysis: LLM-based code review +- 🚀 Concurrent Processing: Fixed at 10 concurrent executions +- 📊 Git Integration: Automatically detects changes in working directory and staging area (relative to HEAD) +- 🎯 Multi-language Recognition: Identifies 20+ language types by file extension +- 🌐 Internationalization: Supports Chinese/English reports and prompts +- 🛠️ Configuration Management: API Server/model/key/language persisted to local config +- 📝 Report Output: Generates Markdown append-only reports `code-review.md` per file + +Planned (To be completed/Wired) +- ⏱ Configurable Concurrency Limit: `--max-pool` (parameter reserved, not yet effective, default 10) +- 🔖 Review Specific Commits: `--commit-id` (not yet effective) +- 🧠 Chain-of-Thought Output: `--thinking-chain` (not yet effective) +- 📝 Custom Prompt: `--prompt-file` (not yet effective) +- 🎯 Scope Filtering: Review specified files/subdirectories (currently only reviews repository changes) + +## 🚀 Quick Start + +### Installation + +Recommended to use `Makefile` for building: + +```bash +# Clone the repository +git clone https://github.com/your-username/stellarspec.git +cd stellarspec + +# Build (output located at build/stellar) +make build +``` + +After building, the binary is located at `build/stellar`. To use it globally, copy it to a directory in your PATH: + +```bash +sudo cp build/stellar /usr/local/bin/stellar +``` + +### Configuration + +First-time use requires configuring the API server, model, and key. Replace `stellar` with your actual binary name (if changed). + +```bash +# Set API server address +stellar --set-apiserver https://api.siliconflow.cn/v1/ + +# Set LLM model +stellar --set-model deepseek-chat + +# Set API key +stellar --set-key sk-xxxxxxxxxxxxx + +# Set language (optional, defaults to Chinese) +stellar --set-lang zh # Chinese +stellar --set-lang en # English +``` + +The configuration file will be automatically saved to `$HOME/.stellarspec/cnf` + +### Basic Usage + +```bash +# Review changes in the current Git repository (relative to HEAD) +./build/stellar review + +# Using the installed binary +stellar review + +# View help (or use make run) +stellar --help +``` + +Notes: +- Currently only reviews "repository changes"; passing `review [path]` attempts to open a Git repository at the specified path. +- Precise review of "individual files/subdirectories" is not yet implemented, planned for future. +- After review completion, a `code-review.md` report file will be generated in the working directory. + +## 📖 Detailed Usage + +### Configuration Management + +```bash +# Use custom configuration file +stellar --conf /path/to/custom/config review + +# Set multiple configuration items at once +stellar --set-apiserver https://api.openai.com/v1 \ + --set-model gpt-4 \ + --set-key sk-xxxxxx \ + --set-lang en + +# Switch language setting +stellar --set-lang zh # Switch to Chinese +stellar --set-lang en # Switch to English +``` + +### Review Options (Reserved, Planned) + +The following options are reserved in the CLI but not yet effective in the engine; they will work once wired: + +```bash +# Specify concurrency count (default 10) +stellar review . --max-pool 20 + +# Review changes of a specific commit +stellar review --commit-id 1bacd3f + +# Enable chain-of-thought mode to view detailed analysis process +stellar review --thinking-chain + +# Use custom prompt template +stellar review --prompt-file custom_prompt.txt +``` + +### Supported File Types + +StellarSpec supports code review for the following programming languages: + +| Language | Extensions | Language | Extensions | +|----------|------------|----------|------------| +| Go | `.go` | Python | `.py` | +| JavaScript | `.js`, `.jsx` | Java | `.java` | +| TypeScript | `.ts`, `.tsx` | C/C++ | `.c`, `.cpp`, `.cc` | +| Rust | `.rs` | PHP | `.php` | +| Ruby | `.rb` | Swift | `.swift` | +| Kotlin | `.kt` | Scala | `.scala` | +| Shell | `.sh` | SQL | `.sql` | +| HTML | `.html`, `.htm` | CSS | `.css` | +| YAML | `.yaml`, `.yml` | JSON | `.json` | +| XML | `.xml` | Markdown | `.md` | + +## 🔧 Advanced Features + +### Concurrent Processing + +Current concurrency is fixed at 10. The `--max-pool` option is reserved and will support configurable concurrency limits once wired. + +### Chain-of-Thought Analysis + +`--thinking-chain` is reserved for future use to enable viewing the model's detailed analysis process (disabled by default). + +### Custom Prompt + +`--prompt-file` is reserved for future support to customize review prompts and focus points via file. + +## 📊 Review Report + +The report file is `code-review.md`, outputting per file with: + +- File Information: Path, recognized language type, timestamp +- Review Results: Model-generated conclusion text (templates switch by language) + +Note: Sections like "Issues Found/Improvement Suggestions/Solutions" in the example are carried within the model-generated text; templates are not yet strictly sectioned. + +## 🛠️ Technical Architecture + +### Core Components + +- **Eino Framework**: Provides LLM model integration and workflow orchestration +- **Git Integration**: Implements version control integration using the go-git library +- **Concurrent Processing**: Uses goroutines and semaphores for efficient concurrency +- **Configuration Management**: Flexible configuration system based on INI format + +### Project Structure + +``` +stellarspec/ +├── cmd/ # Cobra CLI entry +│ └── stellarspec.go +├── internal/ +│ ├── model/ +│ │ └── conf/ # INI configuration read/write +│ └── reviewer/ # Change collection / concurrent execution / report output +├── build/ # Build artifacts (git ignored) +├── go.mod +├── go.sum +└── README.md +``` + +## 🤝 Contribution Guide + +Welcome to contribute code! Please follow these steps: + +1. Fork this repository +2. Create a feature branch: `git checkout -b feature/amazing-feature` +3. Commit your changes: `git commit -m 'Add amazing feature'` +4. Push the branch: `git push origin feature/amazing-feature` +5. Submit a Pull Request + +## 📄 License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details + +## 🙏 Acknowledgments + +- [Eino](https://github.com/cloudwego/eino) - Powerful LLM application framework +- [Cobra](https://github.com/spf13/cobra) - Go CLI library +- [go-git](https://github.com/go-git/go-git) - Git implementation +- [go-diff](https://github.com/sergi/go-diff) - Diff comparison library + +- [ethereal14](https://github.com/ethereal14) - my good friend + +## 📞 Support + +If you encounter issues or have suggestions, please: + +- Submit an Issue +- Start a Discussion + +--- + +⭐ If this project has been helpful to you, please give us a Star!