diff --git a/README.md b/README.md index 21d2d9f..11fb173 100644 --- a/README.md +++ b/README.md @@ -15,18 +15,37 @@ PRs Welcome

+

+ 简体中文 | + English | + 日本語 +

+ --- -## 🌟 设计初衷与定位 +## 🌟 为什么做 git-air？ -市面上有许多优秀的云端与 CI/CD 级别的 AI Code Review 平台（如各类 PR 自动审查 Bot），它们在团队协作和远程代码门禁上表现出色。 +### 痛点：AI 写代码一时爽，Review 起来火葬场 -**而 `git-air` 的定位是：将审查能力极致前置到开发者的本地终端（Pre-Commit / Local CLI）。** +现在的开发工作流几乎离不开 AI 辅助（Cursor、Copilot、各种大模型插件）。几秒钟生成上百行代码，写起来确实爽快。 -在代码正式 push 或发起 PR 之前，在本地敲一行命令，就能以零延迟、极简的方式先做一轮深度扫描，把潜在的并发隐患、逻辑缺陷与敏感信息拦截在本地，作为开发者最轻量顺手的日常命令行结对编程助手。 +**但这也带来了一个全新的致命痛点：** +- **“看起来太完美”的视觉欺骗**：AI 生成的代码排版工整、注释漂亮、语法标准，极容易让人产生盲目信任； +- **生成 AI 的“自恋惯性”**：在同一个对话上下文里，你问写代码的那个 AI *“有没有 Bug”*，它往往带有思维惯性与自恋幻觉，大概率自信满满地回复 *“逻辑完全正确、非常健壮”*； +- **隐蔽暗坑极难肉眼捕捉**：比如在某个 `if err != nil` 提前返回时漏了解锁（Mutex Leak）、协程内部缺少 `recover`、循环内未释放的连接……这些隐患肉眼一扫极易漏掉。 + +这导致了一个尴尬的死循环：**AI 负责批量生产代码，人类程序员负责在半夜线上故障时擦屁股。** + +--- + +### 解法：把审查能力极致前置到本地终端（Pre-Commit） + +市面上有许多优秀的云端与 CI/CD 级别的代码审查平台，而 **`git-air` 的定位是：在代码正式 commit 或发起 PR 之前，作为你本地终端里完全独立的“第三方审查员”。** + +它完全剥离聊天上下文，像一个**坐在你工位旁边、嘴有点损但眼神极毒的资深架构师同事**，只对纯粹的代码变更（`git diff`）进行冷酷挑刺： - ⚡ **Git 原生极简体验**：无需改变任何工作习惯，在命令行敲 `git air` 即可秒级唤起。 -- 🧠 **全模型自由接入**：开箱即用支持 **Google Gemini、DeepSeek、本地离线 Ollama、OpenAI** 以及任何兼容 OpenAI 协议的自定义端点。 +- 🧠 **全模型自由接入**：开箱即用预置 **Google Gemini、Anthropic Claude、xAI Grok、DeepSeek、本地离线 Ollama、OpenAI** 等全系列模型。 - 🛡️ **智能降噪过滤**：自动剥离 `go.sum`、`package-lock.json`、`*.pb.go`、`*.gen.go` 等锁文件与自动生成代码，省 Token、防死循环。 - 🎯 **严谨架构师准则**：直奔主题，聚焦并发竞态、死锁、SQL 注入、空指针、资源泄露，并直接提供修复参考代码。 - 📋 **团队规范适配（`.airules`）**：在项目根目录放置 `.airules`，AI 自动加载团队专属架构规范并最高优先级执行。 diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..f30f877 --- /dev/null +++ b/README_EN.md @@ -0,0 +1,185 @@ +

+ git-air logo +

+ +

git-air 🍃

+ +

+ A lightweight, lightning-fast, Git-native AI code reviewer written in pure Go. +

+ +

+ Go Version + License + PRs Welcome +

+ +

+ 简体中文 | + English | + 日本語 +

+ +--- + +## 🌟 Why git-air? + +### The Pain Point: AI Writes Code Fast, But Reviewing It Is a Nightmare + +Most developers today rely heavily on AI coding assistants (Cursor, Copilot, and LLM extensions). Generating hundreds of lines of code in seconds feels incredible. + +**However, this introduces a critical new problem:** +- **The "Looks Perfect" Illusion**: AI-generated code features neat indentation, convincing naming, and flawless syntax, making it dangerously easy to trust blindly; +- **The Confirmation Bias of Generating Models**: In the same conversation thread, asking the very same AI *"Are there any bugs here?"* almost always yields a self-flattering response: *"The logic is completely solid and robust!"*; +- **Subtle Traps Missed by Human Eyes**: Overlooked unlocked mutexes on early `return` paths, missing `recover()` inside goroutines, unreleased database connections in loops... These critical traps easily slip past quick manual skimming. + +This creates an absurd cycle: **AI mass-produces code, while human engineers spend late nights fixing production crashes.** + +--- + +### The Solution: Shift Code Review Directly to Your Local Terminal (Pre-Commit) + +While there are great cloud/CI-based PR review bots, **`git-air` is designed to be your independent, cold-blooded "third-party auditor" right inside your local terminal before you ever type `git commit`.** + +Completely isolated from your chat history, it acts like a **grumpy but sharp senior architect sitting beside your desk**, ruthlessly inspecting only raw code changes (`git diff`): + +- ⚡ **Git-Native Simplicity**: No workflow changes needed. Just run `git air` in your terminal for instant feedback. +- 🧠 **Universal Multi-Model Support**: Pre-configured support for **Google Gemini, Anthropic Claude, xAI Grok, DeepSeek, Local Ollama, OpenAI**, and any OpenAI-compatible custom endpoint. +- 🛡️ **Smart Noise Reduction**: Automatically strips out `go.sum`, `package-lock.json`, `*.pb.go`, and lockfiles to save tokens and eliminate review loops. +- 🎯 **Strict Senior Architect Persona**: Zero corporate fluff. Directly flags concurrency deadlocks, SQL injections, nil dereferences, and resource leaks with copy-paste code patches. +- 📋 **Team Rules Support (`.airules`)**: Drop an `.airules` file in your repo root, and the AI will prioritize your team-specific guidelines. +- 🪝 **One-Click Pre-commit Hook**: Mounts as a local Git hook in one command to block dangerous bugs before code is committed. + +--- + +## 📦 Installation + +### Option 1: Via Go Install (Recommended) +```bash +go install github.com/unclesam-ly/git-air@latest +``` + +### Option 2: Build from Source +```bash +git clone https://github.com/unclesam-ly/git-air.git +cd git-air +go build -o git-air . +sudo mv git-air /usr/local/bin/ +``` + +--- + +## 🚀 Quick Start + +### 1. Configure Model & API Key + +`git-air` comes with pre-configured endpoints and default models for all major AI providers. Simply pass `--provider`: + +```bash +# 1. Google Gemini (Recommended: fast & cost-effective) +git air config set --provider gemini --key "YOUR_KEY" + +# 2. Anthropic Claude (Claude-3.7 / 3.5 Sonnet) +git air config set --provider claude --key "YOUR_KEY" --model anthropic/claude-3.7-sonnet + +# 3. xAI Grok (Grok-2 / Grok-3) +git air config set --provider grok --key "YOUR_KEY" --model grok-2-latest + +# 4. DeepSeek (Deep reasoning) +git air config set --provider deepseek --key "YOUR_KEY" --model deepseek-chat + +# 5. SiliconFlow (DeepSeek-V3 hosted) +git air config set --provider siliconflow --key "YOUR_KEY" --model deepseek-ai/DeepSeek-V3 + +# 6. Qwen / DashScope (Alibaba Cloud) +git air config set --provider qwen --key "YOUR_KEY" --model qwen-plus + +# 7. Zhipu AI (GLM-4) +git air config set --provider zhipu --key "YOUR_KEY" --model glm-4-plus + +# 8. Moonshot AI (Kimi) +git air config set --provider moonshot --key "YOUR_KEY" + +# 9. Groq (Ultra-fast inference) +git air config set --provider groq --key "YOUR_KEY" --model llama-3.3-70b-versatile + +# 10. OpenRouter (Universal AI Gateway) +git air config set --provider openrouter --key "YOUR_KEY" + +# 11. 100% Offline Local Privacy (Ollama) +git air config set --provider ollama --model qwen2.5-coder + +# 12. OpenAI Official (GPT-4o / o3-mini) +git air config set --provider openai --key "YOUR_KEY" --model gpt-4o-mini +``` + +Check current configuration: +```bash +git air config get +``` + +--- + +### 2. Everyday Commands + +```bash +# Review currently staged changes (default) +git air + +# Review the previous commit +git air HEAD~1 + +# Review differences between branches +git air main..feature-agent + +# Review a specific file +git air internal/service/chat.go + +# Temporarily override provider or model +git air --provider deepseek --model deepseek-chat +``` + +--- + +### 3. One-Click Git Pre-commit Hook + +Install the hook inside any Git repository: +```bash +git air hook install +``` +From now on, whenever you run `git commit`, `git-air` will automatically perform a code review in your terminal and warn you of any blocker issues! + +To uninstall: +```bash +git air hook uninstall +``` + +--- + +## ⚙️ Configuration Hierarchy + +`git-air` searches for configurations in the following priority order: +1. **CLI Flags** (`--key`, `--model`, `--provider`, `--prompt`) +2. **Environment Variables** (`GIT_AIR_API_KEY`, `GIT_AIR_PROVIDER`, `GIT_AIR_MODEL`) +3. **Project Config** (`./config.yaml` or `./.git-air.yaml` in repo root) +4. **Global User Config** (`~/.git-air/config.yaml`) + +--- + +## 📋 Custom Team Rules (`.airules`) + +Create an `.airules` file in your repository root. `git-air` will automatically inject these rules into the model with highest priority: + +```markdown +# Team Coding Guidelines +1. All SQL operations must reside in the DAO/repository layer. No raw SQL string concatenation; +2. Concurrent shared variable access must use sync.RWMutex or sync/atomic; +3. Opened resource handles (DB rows, HTTP resp.Body, files) must be immediately closed via defer; +4. Never discard errors with blank identifiers (_ = err). +``` + +--- + +## 📄 License + +This project is licensed under the [MIT License](LICENSE). Contributions, PRs, and issues are welcome! diff --git a/README_JA.md b/README_JA.md new file mode 100644 index 0000000..39a9724 --- /dev/null +++ b/README_JA.md @@ -0,0 +1,184 @@ +

+ git-air logo +

+ +

git-air 🍃

+ +

+ Go言語で書かれた、空気のように軽快で高速なGitネイティブAIコードレビューツール。 +

+ +

+ Go Version + License + PRs Welcome +

+ +

+ 简体中文 | + English | + 日本語 +

+ +--- + +## 🌟 なぜ git-air を開発したのか？ + +### 課題：AIが書いたコードは気持ちいいが、レビューは悪夢 + +現代の開発では、AI（Cursor、Copilot、各種LLMプラグイン）を活用することが当たり前になりました。数秒で数十行・数百行のコードが生成されるため、開発スピードは劇的に向上します。 + +**しかし、そこには見過ごせない重大な課題が存在します：** +- **「見た目が完璧すぎる」という錯覚**：インデントやコメント、命名が綺麗なため、バグがないと盲信しやすい； +- **生成AI自身の「自己肯定バイアス」**：同じチャット内で生成AIに「このコードにバグはある？」と聞いても、「問題なく堅牢に動作します！」と返ってくることが多い； +- **人間の目で見落としやすい潜在的な罠**：`if err != nil` の早期リターン時にロック解除（Mutex Leak）を忘れたり、Goroutine 内で `recover` がなかったり、ループ内でコネクションが解放されなかったりするバグは、目視では非常に見落としやすい。 + +その結果、**「AIがコードを大量生産し、深夜に人間が本番障害の対応に追われる」**という本末転倒な状況が生まれます。 + +--- + +### 解決策：レビューをローカルターミナル（Pre-Commit）に完全前置 + +GitHubなどのCI/CD上で動作するボットも優秀ですが、**`git-air` はコードを `git commit` する前に、ローカル端末上で動作する完全に独立した「第三者監査役」として設計されています。** + +チャット履歴のコンテキストを一切排除し、まるで**あなたの隣に座る口は悪いが目の鋭いシニアアーキテクト**のように、純粋な差分（`git diff`）だけを厳しくチェックします： + +- ⚡ **Gitネイティブな極上の操作性**：いつもの作業フローを崩さず、ターミナルで `git air` と叩くだけで即座に起動。 +- 🧠 **主要モデルを完全網羅**：**Google Gemini、Anthropic Claude、xAI Grok、DeepSeek、ローカルOllama、OpenAI** などを設定なしで即座に切り替え可能。 +- 🛡️ **スマートなノイズ除去**：`go.sum` や `package-lock.json`、自動生成された `*.pb.go` を自動除外。Token消費を抑え、思考ループを防ぎます。 +- 🎯 **厳格なシニアエンジニア基準**：お世辞や無駄口は一切なし。並行処理の競合、デッドロック、SQLインジェクション、NULLポインタ、リソースリークを指摘し、具体的な修正コードを直接提示します。 +- 📋 **チーム規約の読み込み（`.airules`）**：リポジトリ直下に `.airules` を配置するだけで、チーム固有のアーキテクチャ規約を最優先で適用。 +- 🪝 **ワンクリックで Pre-commit フック化**：コマンド1発でGitフックとして登録。危険なコードのコミットを未然にブロックします。 + +--- + +## 📦 インストール + +### 方法 1: Go Install（推奨） +```bash +go install github.com/unclesam-ly/git-air@latest +``` + +### 方法 2: ソースコードからビルド +```bash +git clone https://github.com/unclesam-ly/git-air.git +cd git-air +go build -o git-air . +sudo mv git-air /usr/local/bin/ +``` + +--- + +## 🚀 クイックスタート + +### 1. モデルと API Key の設定 + +`git-air` は国内外の主要LLMのエンドポイントと推奨モデルを標準プリセットしています。`--provider` を指定するだけで簡単に切り替えられます： + +```bash +# 1. Google Gemini (推奨: 高速・低コスト) +git air config set --provider gemini --key "YOUR_KEY" + +# 2. Anthropic Claude (Claude-3.7 / 3.5 Sonnet) +git air config set --provider claude --key "YOUR_KEY" --model anthropic/claude-3.7-sonnet + +# 3. xAI Grok (Grok-2 / Grok-3) +git air config set --provider grok --key "YOUR_KEY" --model grok-2-latest + +# 4. DeepSeek (高度な推論・思考モデル) +git air config set --provider deepseek --key "YOUR_KEY" --model deepseek-chat + +# 5. SiliconFlow (DeepSeek-V3 高速ホスティング) +git air config set --provider siliconflow --key "YOUR_KEY" --model deepseek-ai/DeepSeek-V3 + +# 6. 通義千問 (Qwen / Alibaba Cloud) +git air config set --provider qwen --key "YOUR_KEY" --model qwen-plus + +# 7. 智譜 AI (GLM-4) +git air config set --provider zhipu --key "YOUR_KEY" --model glm-4-plus + +# 8. Moonshot AI (Kimi) +git air config set --provider moonshot --key "YOUR_KEY" + +# 9. Groq (超高速推論) +git air config set --provider groq --key "YOUR_KEY" --model llama-3.3-70b-versatile + +# 10. OpenRouter (マルチモデル統合ゲートウェイ) +git air config set --provider openrouter --key "YOUR_KEY" + +# 11. ローカル完全オフライン・プライバシー重視 (Ollama) +git air config set --provider ollama --model qwen2.5-coder + +# 12. OpenAI 公式 (GPT-4o / o3-mini) +git air config set --provider openai --key "YOUR_KEY" --model gpt-4o-mini +``` + +現在の設定を確認： +```bash +git air config get +``` + +--- + +### 2. よく使うレビューコマンド + +```bash +# 現在ステージングされた（git add済み）変更をレビュー（デフォルト） +git air + +# 直前のコミット内容をレビュー +git air HEAD~1 + +# ブランチ間の差分をレビュー +git air main..feature-agent + +# 特定のファイルのみをレビュー +git air internal/service/chat.go + +# 一時的にモデルやProviderを指定して実行 +git air --provider deepseek --model deepseek-chat +``` + +--- + +### 3. ワンタッチで Pre-commit フックを登録 + +Git リポジトリ直下で以下を実行： +```bash +git air hook install +``` +以降、`git commit` を実行するたびにターミナル上で自動レビューが走り、重大な欠陥があればコミット前に警告を出してくれます！ + +フックを解除する場合： +```bash +git air hook uninstall +``` + +--- + +## ⚙️ 設定の優先順位 + +1. **コマンドライン引数** (`--key`, `--model`, `--provider`, `--prompt`) +2. **環境変数** (`GIT_AIR_API_KEY`, `GIT_AIR_PROVIDER`, `GIT_AIR_MODEL`) +3. **プロジェクト個別設定** (リポジトリ直下の `./config.yaml` または `./.git-air.yaml`) +4. **グローバル設定** (`~/.git-air/config.yaml`) + +--- + +## 📋 チーム規約のカスタマイズ（`.airules`） + +リポジトリのルートディレクトリに `.airules` ファイルを作成すると、AI はそのルールを最優先事項として適用します： + +```markdown +# チーム共通開発ルール +1. すべての SQL 処理は DAO 層に集約し、文字列結合による生 SQL は禁止とする； +2. 並行処理で共有変数を扱う場合は、sync.RWMutex または sync/atomic を使用すること； +3. オープンしたリソース（DB rows、HTTP レスポンス、ファイル）は defer Close() で確実に解放すること； +4. error をアンダースコア（_ = err）で無条件に無視することを禁止する。 +``` + +--- + +## 📄 ライセンス + +本プロジェクトは [MIT ライセンス](LICENSE) のもとで公開されています。Issue や Pull Request も大歓迎です！