🚀 AI智能代码审查工具 - 结合静态规则检测和AI智能分析，为你的代码提供全方位的安全和质量审查。
- 🔍 静态规则检测 - 内置安全、性能、最佳实践规则
- 🧠 AI智能分析 - 支持 OpenAI / Anthropic / Gemini 的统一对接
- 🧩 审查技能编排 - 支持 Skills 约束输出，强制细化风险分析与修复建议
- ⚡ Git Diff增量审查 - 智能识别变更内容，只审查修改的代码行，大幅提升审查效率
- 🚀 智能分批处理 - 自动优化大文件处理，支持分段分析
- 📊 大文件支持 - 智能分段处理超大文件，突破token限制
- 🎯 Git Hook集成 - 支持暂存区文件审查和指定文件审查
- 📁 多语言支持 - JavaScript、TypeScript、Python、Java、Go、C++、PHP等
- ⚙️ 高度可配置 - 自定义规则、风险等级、AI参数
- 🔧 自动安装 - 一键安装配置文件和Git Hook
在项目中安装 smart-review，安装后会自动初始化配置并集成到 git pre-commit 钩子：
npm install --save-dev smart-reviewyarn add --dev smart-review💡 安装完成后，工具会自动：
- 创建
.smart-review配置目录和配置文件- 设置 git pre-commit 钩子，在每次提交时自动进行代码审查
安装完成后，工具会自动创建配置目录和文件。如需手动重新初始化：
node bin/install.js初始化后的目录结构：
.smart-review/
├── smart-review.json # 主配置文件
├── ai-rules/ # AI规则目录
└── local-rules/ # 本地静态规则目录
├── security.js # 安全规则
├── performance.js # 性能规则
└── best-practices.js # 最佳实践规则
node bin/review.js --stagednode bin/review.js --files test/src/test-file.js
node bin/review.js --files test/src/index.tsx,test/src/large-test-file.js启用增量审查模式后，工具会智能识别文件的变更内容，只审查修改的代码行，大幅提升审查效率：
# 审查暂存区的变更内容（推荐）
node bin/review.js --staged
# 审查指定文件的变更内容
node bin/review.js --files src/modified-file.js增量审查模式的优势：
- ⚡ 高效审查 - 只分析变更的代码行，跳过未修改的内容
- 🎯 精准定位 - 问题报告直接关联到具体的变更行
- 💰 成本优化 - 减少AI API调用的token消耗
- 🚀 快速反馈 - 大幅缩短审查时间，特别适合大型项目
工作原理：
- 自动检测Git变更（通过
git diff） - 提取变更的代码行和上下文
- 只对变更内容进行静态规则检测和AI分析
- 保持完整的上下文信息，确保分析准确性
对于超大文件，工具会自动进行智能分段处理：
node bin/review.js --files test/src/large-test-file.js输出示例：
代码审查审查中，请等待...
🔍 开始逐段分析文件: test/src/large-test-file.js，共 2 段
🔍 开始分析第 1/2 段 (行 1-150)，预估2400 tokens, 共150 行代码
✅ 第 1 段分析完成，发现 8 个问题
🔍 开始分析第 2/2 段 (行 130-302)，预估2800 tokens, 共172 行代码
✅ 第 2 段分析完成，发现 12 个问题
🎯 分段分析完成，共发现 20 个问题
对于多个文件的批次处理：
代码审查审查中，请等待...
🔍 开始分析批次文件: src/utils.js, src/config.js, src/helper.js，预估3200 tokens, 共3 个文件
✅ 批次分析完成: src/utils.js, src/config.js, src/helper.js，发现 5 个问题，耗时: 2.3s
当前已完成进度: 1/3，总耗时: 2.3s
🔍 开始分析批次文件: src/api.js, src/database.js，预估2800 tokens, 共2 个文件
✅ 批次分析完成: src/api.js, src/database.js，发现 3 个问题，耗时: 1.8s
当前已完成进度: 2/3，总耗时: 4.1s
在 package.json 中添加：
{
"husky": {
"hooks": {
"pre-commit": "smart-review --staged"
}
}
}- 支持在 Git Bash、CMD、PowerShell 中进行交互中断
- 审查过程中输入
q或按Esc可中断审查并输出已完成结果 - 中断不会被视为审查失败，只有存在阻断风险才会阻止提交
{
"ai": {
"enabled": true,
"provider": "openai",
"model": "deepseek-chat",
"apiKey": "your-api-key",
"baseURL": "https://api.deepseek.com/v1",
"reviewOnlyChanges": true,
"maxResponseTokens": 8192,
"maxFileSizeKB": 500,
"enabledFor": [".js", ".ts", ".jsx", ".less", ".css", ".tsx", ".vue", ".py", ".java", ".go", ".rs", ".cpp", ".c", ".cs", ".php"],
"useStaticHints": true,
"maxRequestTokens": 8000,
"minFilesPerBatch": 1,
"maxFilesPerBatch": 20,
"tokenRatio": 4,
"chunkOverlapLines": 5,
"includeStaticHints": true,
"skills": {
"enabled": true,
"strict": false,
"maxSkillsPerRequest": 4,
"required": ["DIFF_RISK_GUARD", "EVIDENCE_ENFORCER"],
"optional": ["SECURITY_DEEP", "LOGIC_CORRECTNESS", "API_CONTRACT"],
"routes": [
{
"match": ["**/auth/**", "**/security/**"],
"modes": ["diff", "batch", "segment"],
"add": ["SECURITY_DEEP", "API_CONTRACT"]
}
]
},
"tools": {
"enabled": false,
"maxCalls": 2,
"maxReadLines": 400,
"maxSearchMatches": 50,
"maxSearchFiles": 120,
"maxListFiles": 200,
"allow": [
"read_file",
"get_staged_diff",
"list_files",
"search_in_file",
"get_file_outline",
"search_in_repo",
"list_changed_files"
]
},
"temperature": 0,
"concurrency": 3
},
"riskLevels": {
"critical": { "block": true },
"high": { "block": true },
"medium": { "block": true },
"low": { "block": false },
"suggestion": { "block": false }
},
"suppressLowLevelOutput": false,
"useExternalRulesOnly": false,
"fileExtensions": [".js", ".jsx", ".less", ".css", ".ts", ".tsx", ".vue", ".svelte", ".py", ".java", ".go", ".rs", ".cpp", ".c", ".h", ".php", ".rb", ".html", ".css", ".scss", ".less"],
"ignoreFiles": [
"**/node_modules/**",
"**/dist/**",
"**/build/**",
"**/coverage/**",
"**/*.min.js",
"**/*.bundle.js",
"test/src/risky-code.js",
"large.*\\.js$"
]
}enabled: 是否启用AI分析provider: 模型提供方，支持openai、anthropic、geminimodel: 对应提供方的模型名称apiKey: 统一 API 密钥字段（也可通过环境变量注入）baseURL: API基础URLreviewOnlyChanges: 是否启用Git Diff增量审查模式。true时只审查变更的代码行，false时审查整个文件内容。默认为true，大幅提升审查效率maxResponseTokens: AI响应最大token数maxFileSizeKB: 单文件最大大小限制enabledFor: AI分析支持的文件扩展名useStaticHints: 是否将静态规则作为AI分析的上下文maxRequestTokens: 请求最大token数minFilesPerBatch: 批处理最小文件数maxFilesPerBatch: 批处理最大文件数tokenRatio: Token估算比例chunkOverlapLines: 分段重叠行数，保持上下文连续性includeStaticHints: 是否在AI分析中包含静态规则提示temperature: AI模型的创造性参数，0表示最确定性的输出concurrency: 并发AI请求数量，默认3个。设置为1或更小时使用串行处理，大于1时启用并发处理以提升性能skills.enabled: 是否启用审查技能编排skills.strict: 是否强制检查输出是否满足“路径/片段/原因/建议”约束skills.maxSkillsPerRequest: 单次请求最多启用的技能数量skills.required: 必选技能列表skills.optional: 可选技能列表（按模式补充）skills.routes: 按文件路径和模式动态追加技能（match/modes/add）tools.enabled: 启用本地只读工具调用（见下方工具清单）tools.maxCalls: 单次请求最多工具调用轮次tools.maxReadLines:read_file单次读取最大行数tools.maxSearchMatches:search_in_file/search_in_repo单次最多返回匹配条数tools.maxSearchFiles:search_in_repo单次最多扫描文件数tools.maxListFiles:list_files单次最多返回文件数tools.allow: 工具白名单（仅允许模型调用白名单中的工具）
read_file: 读取指定文件的行区间get_staged_diff: 获取暂存区 diff（可按文件路径过滤）list_files: 递归列出仓库内文件（支持子目录和关键字/通配符过滤）search_in_file: 在单个文件内按文本或正则搜索get_file_outline: 提取文件结构轮廓（类/函数/方法等）search_in_repo: 在仓库范围内按文本或正则搜索（支持扫描文件数和结果数上限）list_changed_files: 获取 Git 变更文件列表（支持 staged/unstaged 和状态过滤）
critical: 致命风险high: 高危风险medium: 中危风险low: 低危风险suggestion: 建议性问题
每个等级可配置 block 属性，决定是否阻断提交。
true: 仅输出阻断等级的问题（即block: true的风险等级）false: 输出所有检测到的问题（默认行为）
此配置允许您在保持现有阻断逻辑的同时，控制是否显示低等级的问题。当启用时，只有会阻断提交的问题才会在输出中显示，有助于聚焦于关键问题。
true: 仅使用外部规则模式 - 只加载.smart-review/local-rules目录中的规则，完全忽略内置规则false: 合并模式（默认） - 内置规则与外部规则合并，同名规则外部覆盖内置，不同名规则为新增
此配置控制规则的加载策略：
- 仅外部规则模式：适用于需要完全自定义规则集的场景，不受内置规则影响
- 合并模式：适用于在内置规则基础上进行扩展或覆盖的场景
Smart Reviewer 提供两种层级的忽略配置：文件级别和代码行级别。
在配置文件中设置 ignoreFiles 数组，支持三种匹配模式：
精确匹配
{
"ignoreFiles": [
"src/config/secrets.js",
"test/fixtures/data.json"
]
}Glob 模式
{
"ignoreFiles": [
"**/node_modules/**",
"dist/*",
"**/*.min.js",
"**/build/**",
"**/*.bundle.js"
]
}正则表达式
{
"ignoreFiles": [
".*\\.generated\\.",
"large.*\\.js$",
"/test.*\\.spec\\./",
".*\\.temp\\."
]
}在代码中使用特殊注释来忽略特定行或代码块的审查：
单行忽略
// review-disable-next-line
const password = "hardcoded-password"; // 下一行会被忽略
/* review-disable-next-line */
const apiKey = "sk-1234567890"; // 下一行会被忽略多行忽略
// review-disable-start
const config = {
password: "admin123",
apiKey: "secret-key",
token: "hardcoded-token"
};
// review-disable-end
/* review-disable-start */
function unsafeFunction() {
eval(userInput); // 这段代码块会被忽略
document.innerHTML = data;
}
/* review-disable-end */支持的注释格式
- JavaScript/TypeScript:
//和/* */ - Python/Ruby:
# - HTML/Svelte:
<!-- --> - CSS/SCSS/Less:
/* */ - Java/Go/C/C++/Rust/PHP:
//和/* */
注意事项
- 忽略注释必须在独立的注释行中，不能与代码混写
review-disable-next-line只影响紧接着的下一行代码review-disable-start/end必须成对出现，影响两个注释之间的所有代码- 文件内忽略只影响静态规则检测，不影响AI分析
在 .smart-review/local-rules/ 目录下创建 JavaScript 文件：
// .smart-review/local-rules/custom-security.js
export const rules = {
security: [
{
id: 'CUSTOM001',
name: '敏感信息泄露',
pattern: '(token|secret|password)\\s*=\\s*[\'"][^\'"]+[\'"]',
risk: 'high',
message: '发现可能的敏感信息硬编码',
suggestion: '使用环境变量或安全配置管理',
flags: 'gi'
}
]
};支持更复杂的检测逻辑：
export const rules = {
performance: [
{
id: 'PERF001',
name: '复杂度检测',
pattern: function(content) {
// 自定义检测逻辑
const lines = content.split('\n');
const issues = [];
lines.forEach((line, index) => {
if (line.includes('for') && line.includes('for')) {
issues.push(`第${index + 1}行：嵌套循环可能影响性能`);
}
});
return issues;
},
risk: 'medium',
message: '发现性能问题',
suggestion: '优化算法复杂度'
}
]
};在 .smart-review/ai-rules/ 目录下创建自定义AI提示词文件：
.smart-review/ai-rules/custom-prompts.txt
请特别关注以下代码模式：
1. 检查是否存在未处理的Promise rejection
2. 验证API调用是否有适当的错误处理
3. 确保敏感数据不会被意外记录到日志中
.smart-review/ai-rules/security-focus.txt
安全审查重点：
- 检查用户输入验证
- 确认权限控制逻辑
- 验证数据加密和脱敏处理
💡 提示: AI提示词文件可以是
.txt、.md或任何文本文件，内容会被添加到AI分析的上下文中。
- SEC001: 硬编码密码检测 - 检测硬编码的密码或密钥
- SEC002: SQL注入风险 - 检测字符串拼接SQL查询
- SEC003: XSS风险 - 检测直接操作HTML内容的风险
- SEC004: 命令注入风险 - 检测命令执行函数调用
- PERF001: 循环内数据库查询 - 检测可能导致N+1查询问题的代码
- PERF002: 内存泄漏风险 - 检测定时器使用但未清理的情况
- BP001: 调试代码 - 检测console.log、print、alert等调试代码
- BP002: 魔法数字 - 检测常见的魔法数字，建议使用常量
Smart Reviewer 的核心性能优化特性，通过智能识别变更内容，实现高效的增量审查：
- 审查速度提升 70-90% - 只分析变更的代码行，跳过未修改内容
- Token消耗减少 60-80% - 大幅降低AI API调用成本
- 内存占用优化 - 只加载和处理变更相关的代码段
- 网络传输优化 - 减少API请求的数据量
- ✅ 日常开发提交 - 小范围代码修改，审查速度极快
- ✅ 功能迭代 - 针对性审查新增和修改的功能代码
- ✅ Bug修复 - 快速验证修复代码的安全性和质量
- ✅ 代码重构 - 专注于重构部分的影响分析
{
"ai": {
"reviewOnlyChanges": true,
"contextMergeLines": 10, // 保持变更行周围的上下文
"chunkOverlapLines": 5 // 确保分析的连续性
}
}Smart Reviewer 采用智能分批处理技术，能够高效处理超大文件：
- 智能检测: 自动识别超过token限制的大文件
- 分段处理: 将大文件分割为多个重叠段落
- 上下文保持: 通过重叠行数保持代码上下文连续性
- 并行分析: 支持多段并行处理，提升分析速度
{
"ai": {
"maxRequestTokens": 8000, // 单次请求最大 token 数
"chunkOverlapLines": 5, // 分段重叠行数
"minFilesPerBatch": 1, // 每批次最少文件数
"maxFilesPerBatch": 10 // 每批次最多文件数
}
}-
合理设置批处理参数
{ "ai": { "maxRequestTokens": 6000, "chunkOverlapLines": 10, "minFilesPerBatch": 1, "maxFilesPerBatch": 5 } } -
启用并发处理
{ "ai": { "concurrency": 3, // 并发 AI 请求数量 "maxFilesPerBatch": 5 // 控制批次文件数 } } -
调整智能分批参数
{ "ai": { "minFilesPerBatch": 1, "maxFilesPerBatch": 5 } } -
文件过滤优化
{ "ignoreFiles": [ "**/*.min.js", // 跳过压缩文件 "**/dist/**", // 跳过构建产物 "**/*.generated.*" // 跳过生成文件 ] }
- 流式处理: 大文件采用流式读取，减少内存占用
- 请求重试: 内置智能重试机制，处理网络波动
- 缓存机制: 静态规则结果缓存，避免重复计算
- 增量分析: 只分析变更的文件部分
import { CodeReviewer } from './lib/reviewer.js';
import { ConfigLoader } from './lib/config-loader.js';
// 加载配置
const configLoader = new ConfigLoader('/path/to/project');
const config = await configLoader.loadConfig();
const rules = await configLoader.loadRules(config);
// 创建审查器
const reviewer = new CodeReviewer(config, rules);
// 审查暂存区文件
const result = await reviewer.reviewStagedFiles();
// 审查指定文件
const result = await reviewer.reviewSpecificFiles(['test/src/test-file.js']);
// 处理结果
if (result.blockSubmission) {
console.log('发现阻断性问题，请修复后再提交');
result.issues.forEach(issue => {
console.log(`${issue.file}:${issue.line} - ${issue.message}`);
});
}import { CodeReviewer } from './lib/reviewer.js';
import { defaultConfig, defaultRules } from './lib/default-config.js';
const customConfig = {
...defaultConfig,
ai: {
...defaultConfig.ai,
enabled: false // 禁用AI分析
},
riskLevels: {
...defaultConfig.riskLevels,
low: { block: true } // 低危也阻断
}
};
const reviewer = new CodeReviewer(customConfig, defaultRules);可通过环境变量配置：
# 统一 API 配置（最高优先级）
export AI_API_KEY="your-api-key"
# 按 Provider 配置
export OPENAI_API_KEY="your-api-key"
export ANTHROPIC_API_KEY="your-api-key"
export GEMINI_API_KEY="your-api-key"
# 或 Google 生态变量
export GOOGLE_API_KEY="your-api-key"
# 调试模式
export DEBUG_SMART_REVIEW=true
# 国际化（i18n）
# Windows PowerShell（当前会话）
$env:SMART_REVIEW_LOCALE='zh-CN' # 或 'en-US'
# macOS/Linux bash
export SMART_REVIEW_LOCALE=zh-CN # 或 en-US如果需要使用自定义的 OpenAI 兼容服务，请在项目的配置文件中设置 ai.baseURL：
{
"ai": { "provider": "openai", "baseURL": "https://api.openai.com/v1" }
}- 配置项
locale：在.smart-review/smart-review.json顶层设置输出与模板语言，支持zh-CN、en-US。示例：{"locale": "en-US"}。 - 环境变量
SMART_REVIEW_LOCALE：优先级最高，安装和复制模板时将按该值选择语言目录。 - 选择优先级：环境变量 > 项目配置
.smart-review/smart-review.json> 模板默认配置templates/smart-review.json>zh-CN。 - 模板目录结构：
templates/rules/<locale>/security.js|performance.js|best-practices.js；当指定语言缺失某文件时自动回退到zh-CN。 - 控制台与 Git 钩子提示会随
locale切换语言，无需额外配置。 - 切换示例：
- PowerShell：
$env:SMART_REVIEW_LOCALE='en-US'; node bin/install.js - Bash：
export SMART_REVIEW_LOCALE=en-US && node bin/install.js
- PowerShell：
如需新增语言（例如 ja-JP），在 templates/rules/ja-JP/ 下添加三类规则模板文件，并在配置中设置 "locale": "ja-JP" 或通过环境变量切换即可。
smart-review [options]
选项:
--staged 审查 Git 暂存区文件
--files <files> 审查指定文件（逗号分隔）
--ai 强制启用 AI 分析
--no-ai 禁用 AI 分析
--diff-only 仅审查变更行（Git Diff 模式）
--debug 输出调试日志增量审查相关说明：
--diff-only：仅审查变更行（Git Diff 模式），覆盖配置项ai.reviewOnlyChanges- 禁用增量审查：在
.smart-review/smart-review.json将ai.reviewOnlyChanges设为false，适用于需要全面审查的场景
使用示例：
# 强制使用增量审查模式
smart-review --staged --diff-only
# 审查完整文件内容（在配置中关闭增量）
# .smart-review/smart-review.json
{
"ai": { "reviewOnlyChanges": false }
}
smart-review --files src/important.js
# 结合其他参数使用
smart-review --staged --diff-only --debugname: Code Review
on: [push, pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm install
- run: npx smart-review --files $(git diff --name-only HEAD~1)
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}code_review:
stage: test
script:
- npm install
- npx smart-review --files $(git diff --name-only $CI_MERGE_REQUEST_TARGET_BRANCH_SHA)
variables:
OPENAI_API_KEY: $OPENAI_API_KEY-
AI分析失败
⚠️ 检测到 Node 版本 < 18 或缺少全局 fetch解决方案: 升级到 Node.js 18+ 或安装 fetch polyfill
-
配置文件未找到
❌ 配置文件加载失败解决方案: 确保
.smart-review/smart-review.json存在且格式正确 -
API密钥错误
❌ OpenAI API调用失败解决方案: 检查
OPENAI_API_KEY环境变量或配置文件中的密钥 -
大文件处理超时
❌ 文件分析超时
解决方案:
- 降低
ai.maxRequestTokens或减少批次文件数（maxFilesPerBatch），并适当降低chunkOverlapLines - 增加
chunkOverlapLines以减少分段数量 - 检查网络连接稳定性
-
分段分析结果不完整
⚠️ 部分分段分析失败解决方案:
- 检查文件编码是否为 UTF-8
- 确保文件没有语法错误
- 调整
maxRequestTokens配置
-
内存占用过高
❌ 内存不足错误
解决方案:
- 减少
maxFilesPerBatch配置值 - 调整
minFilesPerBatch/maxFilesPerBatch控制每批文件数量 - 添加更多文件到
ignoreFiles列表
- Token 限制错误
❌ Request too large
解决方案:
- 降低
maxRequestTokens配置值 - 减少每批文件数量或启用增量审查
--diff-only - 检查是否有超大的单行代码
启用调试日志：
DEBUG_SMART_REVIEW=true smart-review --staged
# 或
smart-review --staged --debug欢迎提交 Issue 和 Pull Request！
- Fork 项目
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 开启 Pull Request
⭐ 如果这个项目对你有帮助，请给个 Star！