selvage

Selvage：AI 驱动的代码审查自动化工具

🌐 한국어

一款现代化的命令行工具，可帮助 AI 分析 Git 差异，以提升代码质量、查找 Bug 并识别安全漏洞。

🤖 AI Agents：请阅读我们的文档：https://selvage.ai/llms.txt

▶ 观看演示视频

Selvage：让代码审查更出色！

无需再等待审查！AI 会立即分析代码变更，帮助提升质量并预防 Bug。 借助智能上下文分析（基于 AST），结果准确且经济高效；同时支持对大型代码库进行多轮处理，并可与所有 Git 工作流无缝集成。

✨ 主要功能

• 🤖 支持多种 AI 模型：使用最新的大模型，包括 OpenAI GPT-5、Anthropic Claude Sonnet-4、Google Gemini 等
• 🔍 集成 Git 工作流：支持分析已暂存、未暂存的变更，以及特定提交或分支之间的变更
• 🎯 优化上下文分析：基于 Tree-sitter 的 AST 分析会自动提取包含变更行的最小代码块及其依赖语句，为各种情况提供经过上下文优化的信息
• 🔄 自动多轮处理：超过上下文限制时自动拆分提示词，支持稳定地审查大型代码库（现在，即使服务提供商未报错，只要总 token 数超过 200k，也会自动触发大型上下文模式）
• 🤖 支持 MCP 模式：在 Cursor、Claude Code 等工具中注册为 MCP 模式，并通过“审查当前变更”等自然语言请求代码审查
• 🔌 Claude Code 插件：通过 marketplace 使用一条命令安装，包含专用的 /review 技能和 selvage-reviewer Agent，可实现无缝集成
• 🧠 由 Agent 执行审查（get_review_context）：返回结构化的审查上下文（差异 + 智能上下文 + 系统提示词），让宿主 Agent（Claude Code、Cursor、Antigravity 等）使用自己的大模型执行代码审查——无需 API 密钥
• 📖 开源：依据 Apache-2.0 许可证自由使用和修改

🚀 快速开始

常规设置

1. 安装

推荐方式（使用 uv）

# Install uv (run once)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Selvage
uv tool install selvage

替代方式（使用 pipx）

# Install pipx (macOS)
brew install pipx

# Install Selvage
pipx install selvage

传统方式（pip）

# ⚠️ May cause externally-managed-environment error on some systems
pip install selvage

macOS/Linux 用户：如果运行 pip install 时遇到错误，请使用上面的 uv 或 pipx 方式。

2. 设置 API 密钥

从 OpenRouter 获取 API 密钥并进行设置：

export OPENROUTER_API_KEY="your_openrouter_api_key_here"

MCP 模式用法（推荐）

在 Cursor、Claude Code 等工具中注册为 MCP 模式，通过自然语言请求代码审查。

Cursor 集成

在 Cursor 的 MCP 配置文件中注册（路径可能因用户环境而异）：

常见路径： ~/.cursor/mcp.json

// Method 1: Using environment variables (if already set)
{
  "mcpServers": {
    "selvage": {
      "command": "uvx",
      "args": ["selvage", "mcp"]
    }
  }
}

// Method 2: Direct specification
{
  "mcpServers": {
    "selvage": {
      "command": "uvx",
      "args": ["selvage", "mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here"
      }
    }
  }
}

Claude Code 集成

方法 A：通过 Marketplace 安装插件（推荐）

从 Marketplace 安装 Selvage 插件，即可使用专属的 /review 技能和 selvage-reviewer Agent：

# Step 1: Add Selvage marketplace
/plugin marketplace add selvage-lab/selvage

# Step 2: Install the plugin
/plugin install selvage@selvage-lab-selvage

安装后，直接使用 /review 技能：

/review                      # Review unstaged changes
/review staged               # Review staged changes
/review branch main          # Review against main branch
/review commit abc1234       # Review from specific commit

💡 无需 API 密钥！ 该插件使用 get_review_context 调用 Claude Code 自带的大模型进行代码审查，因此无需外部 API 密钥。

方法 B：注册 MCP 服务

# Method 1: Using environment variables (if already set)
claude mcp add selvage -- uvx selvage mcp

# Method 2: Direct specification
claude mcp add selvage -e OPENROUTER_API_KEY=your_openrouter_api_key_here -- uvx selvage mcp

用法

重启 IDE 后，向编码助手请求审查：

Please review current changes using selvage mcp
Review changes between current branch and main branch using claude-sonnet-4-thinking with selvage mcp

🎉 完成！ Selvage 将分析并审查代码，然后通过编码助手提供结果。

CLI 模式用法

直接在终端中使用：

selvage review --model claude-sonnet-4-thinking

💡 更多选项： CLI 用法 | 实用用法指南

🎯 实用用法指南

MCP 模式用法

基本用法

# Basic review request
Please review current changes using selvage mcp

# Review staged changes
Review staged work using gpt-5-high with selvage mcp

# Review against specific branch
Review current branch against main branch using selvage mcp

# Review with automatic model selection
Review current branch against main branch using selvage mcp, automatically selecting appropriate model

Agent 委托审查（无需 API 密钥）

get_review_context 工具会返回结构化的审查上下文，以便宿主 Agent 使用自己的大模型进行代码审查——无需 Selvage API 密钥。

# Request agent-delegated review context
Get review context for current changes using selvage mcp, then review the code

# Agent-delegated review for staged changes
Get review context for staged changes using selvage mcp

# Agent-delegated review against branch
Get review context comparing current branch to main using selvage mcp

💡 工作原理：Selvage 提取 diff、基于 AST 的 Smart Context 和系统提示词，并将其作为结构化上下文返回。随后，宿主 Agent（Claude Code、Cursor、Antigravity 等）直接使用自己的大模型进行审查，无需外部 API 密钥。

高级工作流

多模型对比审查

Review staged work using both gpt-5-high and claude-sonnet-4-thinking with selvage mcp, then compare the results

分步代码改进工作流

1. Review current changes using claude-sonnet-4-thinking with selvage mcp
2. Critically evaluate review feedback for validity against current codebase and set priorities
3. Apply improvements sequentially based on established priorities

CI/CD 集成场景

# Code quality verification before PR creation
Review changes against main branch using selvage mcp for code quality verification before PR creation

# Final check before deployment
Perform comprehensive review of staged changes using selvage mcp for final check before deployment

⌨️ CLI 用法

直接在终端中使用。虽然推荐使用 MCP 模式，但 CLI 适用于脚本和 CI/CD。

配置 Selvage

# View all settings
selvage config list

# Set default model
selvage config model <model_name>

# Set default language
selvage config language <language_name>

代码审查

selvage review [OPTIONS]

主要选项

• --repo-path <path>：Git 仓库路径（默认：当前目录）
• --staged：仅审查已暂存的更改
• --target-commit <commit_id>：审查从指定提交到 HEAD 的更改（例如 abc1234）
• --target-branch <branch_name>：审查当前分支与指定分支之间的更改（例如 main）
• --model <model_name>：使用的 AI 模型（例如 claude-sonnet-4-thinking）
• --open-ui：审查完成后自动启动 UI
• --no-print：不在终端输出审查结果（默认启用终端输出）
• --skip-cache：不使用缓存，执行新的审查

用法示例

# Review current working directory changes
selvage review

# Final check before commit
selvage review --staged

# Review specific files only
git add specific_files.py && selvage review --staged

# Code review before sending PR
selvage review --target-branch develop

# Quick and economical review for simple changes
selvage review --model gemini-2.5-flash

# Review and then view detailed results in web UI
selvage review --target-branch main --open-ui

Git 工作流集成

团队协作场景

# Code quality verification before Pull Request creation
selvage review --target-branch main --model claude-sonnet-4-thinking

# Pre-analysis of changes for code reviewers
selvage review --target-branch develop --model claude-sonnet-4-thinking

# Comprehensive review of all changes after specific commit
selvage review --target-commit a1b2c3d --model claude-sonnet-4-thinking

开发阶段质量管理

# Quick feedback during development (before WIP commit)
selvage review --model gemini-2.5-flash

# Final verification of staged changes (before commit)
selvage review --staged --model claude-sonnet-4-thinking

# Emergency review before hotfix deployment
selvage review --target-branch main --model claude-sonnet-4-thinking

大规模代码审查

# Large codebases are automatically handled
selvage review --model claude-sonnet-4  # Usage is the same, multi-turn processing automatically applied after detection

Selvage 会自动处理超出大模型上下文限制的大型代码更改。 当用量达到约 200k 个 token（以 tiktoken 为准）时，大上下文模式会自动启动，只需等待其完成。

成本优化

# Use economical models for small changes
selvage review --model gemini-2.5-flash

查看结果

审查结果会直接输出到终端，同时自动保存到文件。

如需更多审查管理和复查，可使用 Web UI：

# Manage all saved review results in web UI
selvage view

# Run UI on different port
selvage view --port 8502

UI 主要功能：

• 📋 显示所有审查结果的列表
• 🎨 以 Markdown 格式显示
• 🗂️ 查看 JSON 结构化结果

🌐 智能上下文分析与支持的 AI 模型

🎯 智能上下文分析

Selvage 使用基于 Tree-sitter 的 AST 分析，精准提取仅与更改行相关的代码块，兼顾成本效益与审查质量。

智能上下文的工作原理

• 精准提取：仅提取包含变更行的最小函数／类代码块及相关依赖项（导入等）
• 成本优化：仅发送必要的上下文，而非整个文件，大幅减少 Token 使用量
• 质量保证：通过基于 AST 精准理解代码结构，保持较高的审查准确性

智能上下文自动应用

Selvage 会分析文件大小和变更范围，自动选择最高效的审查方法：

🎯 Small Changes           → Fast and accurate analysis with Smart Context
📄 Small Files            → Complete context understanding with full file analysis
📋 Partial Edits in Large Files → Focused analysis of related code with Smart Context
📚 Large Changes in Big Files   → Comprehensive review with full file analysis

💡 自动优化：无需任何手动配置，系统会针对不同情况自动应用最佳分析方法。

智能上下文支持的语言

• Python、JavaScript、TypeScript、Java、Kotlin

通用上下文提取支持

• 主要编程语言：Go、Ruby、PHP、C#、C/C++、Rust、Swift、Dart 等

🚀 通用上下文提取方法可为主要编程语言提供出色的代码审查质量。 智能上下文支持的语言也在不断扩展。

支持的 AI 模型

🚀 只需一个 OpenRouter API 密钥，即可管理以下所有模型！

OpenAI 模型（OpenRouter 或 OpenAI API 密钥）

• gpt-5.2-codex：⭐ 推荐 - 能力最强的 Agent 编码模型，推理能力更强（400K 上下文）

Anthropic 模型（OpenRouter 或 Anthropic API 密钥）

• claude-opus-4.6：⭐ 推荐 - 前沿推理模型，支持扩展思考（1M 上下文）
• claude-sonnet-4.5：混合推理模型，支持扩展思考，适用于高级编码（1M 上下文）

Google 模型（OpenRouter 或 Google API 密钥）

• gemini-3-pro：⭐ 推荐 - 最先进的推理模型（1M+ Token）
• gemini-3-flash：适用于 Agent 工作流的高速、高性价比模型（1M+ Token）

🌟 OpenRouter 提供的模型（仅限 OpenRouter API 密钥）

• minimax-m2.5（MiniMax）：⭐ 推荐 - 最先进的开源编码模型（SWE-bench 80.2%，200K 上下文）
• glm-5（Zhipu AI）：用于复杂系统的旗舰级 745B MoE 模型（200K 上下文）
• qwen3-coder（Qwen）：专为编码打造的模型（262K 上下文）
• kimi-k2.5（Moonshot AI）：大上下文处理模型（262K 上下文）
• deepseek-r1-0528（DeepSeek）：专为推理打造的模型（163K 上下文）
• deepseek-v3-0324（DeepSeek）：先进的对话模型（163K 上下文）

可用的免费层级模型：qwen3-coder-free、kimi-k2.5-free、deepseek-v3-0324-free、deepseek-r1-0528-free

📄 审查结果存储格式

审查结果会在输出到终端的同时保存为结构化文件：

• 📋 Markdown 格式：结构清晰、易于阅读，包含摘要、问题列表和改进建议
• 🔧 JSON 格式：用于程序化处理及与其他工具集成

💡 高级设置（面向开发者／贡献者）

git clone https://github.com/selvage-lab/selvage.git
cd selvage

# Install all development dependencies automatically
uv sync --dev --extra e2e

# Run
uv run selvage --help

git clone https://github.com/selvage-lab/selvage.git
cd selvage
pip install -e .

# Development dependencies only
uv sync --dev

# E2E test environment included
uv sync --dev --extra e2e

# Run tests
uv run pytest tests/

# Install with development dependencies (pytest, build, etc.)
pip install -e .[dev]

# Install with development + E2E test environment (testcontainers, docker, etc.)
pip install -e .[dev,e2e]

export OPENAI_API_KEY="your_openai_api_key_here"
export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
export GEMINI_API_KEY="your_gemini_api_key_here"

# Set default model to use (for advanced users)
selvage config model claude-sonnet-4-thinking

# Check configuration
selvage config list

# Enable debug mode (for troubleshooting and development)
selvage config debug-mode on

🔧 故障排除

安装错误

externally-managed-environment 错误（macOS/Linux）

# Solution 1: Use uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install selvage

# Solution 2: Use pipx
brew install pipx  # macOS
pipx install selvage

# Solution 3: Use virtual environment
python3 -m venv ~/.selvage-env
source ~/.selvage-env/bin/activate
pip install selvage

API 密钥错误

# Check environment variable
echo $OPENROUTER_API_KEY

# Permanent setup (Linux/macOS)
echo 'export OPENROUTER_API_KEY="your_key_here"' >> ~/.bashrc
source ~/.bashrc

找不到模型错误

# Check available model list
selvage models

# Use correct model name
selvage review --model claude-sonnet-4-thinking

网络连接错误

# Retry ignoring cache
selvage review --skip-cache

# Check detailed info with debug mode
selvage config debug-mode on
selvage review

🤝 参与贡献

Selvage 是一个开源项目，我们始终欢迎您参与贡献！无论是报告 Bug、提出功能建议、改进文档还是贡献代码，任何形式的贡献都值得感谢。

如何参与贡献：

• 🐛 在 GitHub Issues 报告 Bug 或提出功能建议
• 🔧 通过 Pull Request 贡献代码
• 📚 改进文档并参与翻译

详细的贡献指南请参阅 CONTRIBUTING.md。

📜 许可证

Selvage 基于 Apache License 2.0 发布。该许可证允许商业使用、修改和分发，并包含全面的专利保护和商标限制。

📋 更新日志

查看 Selvage 的所有版本变更和新功能。

📋 查看完整更新日志 →

您可以查看每个版本的详细变更，包括新功能、Bug 修复和性能改进。

📞 联系方式和社区

• 🐛 Bug 报告和功能请求：GitHub Issues
• 📧 直接联系：[email protected]

使用 Selvage 编写更出色的代码！🚀
⭐ 如果这个项目对您有帮助，请在 GitHub 上给我们点个 Star！