zzy2210 · webbrain-one · Aug 2, 2026
diff --git a/README.en-US.md 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!