smart-git-review

基于 Git Hooks 和 AI 大模型的自动化代码审查工具。支持 commit/push/pull 时自动审查，并可将质量规范前置植入 Claude Code / Kilo Code / Cursor / Cline 等 AI 编码工具。

包名是 smart-git-review。npm 上存在同名的 git-ai-review 包（非本项目），请统一使用 npx smart-git-review <命令>。 本地安装后，旧命令 git-ai-review 仍作为兼容别名可用（已装的 Git Hooks 无需改动）。

安装

npm install smart-git-review --save-dev

审查需要配置 API Key（见下方「环境变量」）。要求 Node.js >= 18。

快速开始

# 1. 安装 Git Hooks
npx smart-git-review install

# 2. 正常使用 git (commit/push 时自动触发审查)
git commit -m "feat: 新功能"

审查结果会输出到终端，并保存到 .git-ai-review/reviews/（JSON + HTML）。

命令

| 命令 | 说明 | |------|------| | install / uninstall | 安装 / 卸载 Git Hooks（自定义 hook 会备份为 *.git-ai-review.bak） | | review | 手动审查当前暂存的变更 | | rules | 列出所有可用预设规则 | | enable <id> / disable <id> | 启用 / 禁用预设规则 | | inject [opts] | 将质量规范植入 AI 编码工具（--tool、--rules、--no-agents） | | uninject [opts] | 移除已植入的规范 | | reports [--json] | 列出待处理的审查报告 | | ack <id\|--all> | 将报告标记为已处理 | | health [--json] | 代码健康报告（质量评分、技术债趋势、高频问题） | | pr [opts] | 将审查结果发布到 GitHub / GitLab PR 评论 | | serve [port] | 启动本地审查报告查看器（默认 7799） |

审查触发时机

| Hook | 触发时机 | 默认 | 配置项 | |------|----------|------|--------| | pre-commit | git commit 前 | ✅ 开启 | reviewOnCommit | | post-commit | git commit 后 | ✅ 开启 | 仅补充提交信息与相关会话，不改变审查结果 | | pre-push | git push 前 | ❌ 关闭 | reviewOnPush | | post-merge | git pull 后 | ❌ 关闭 | reviewOnPull（适合代码审查人员） |

预设规则库

开箱即用的审查规则，涵盖安全、性能、架构、代码质量等维度：

内置规则

| 规则 ID | 描述 | 适用场景 | |---------|------|----------| | security | 核心目标：基于 git diff 中的新增和修改行 (+ lines)，狙击潜在的安全隐患。 | 所有项目 | | architecture | 核心目标：基于变更代码，识别设计缺陷、架构腐化、安全韧性与性能风险。 | 所有项目 | | react-typescript | 核心目标：预防运行时崩溃、性能灾难和安全漏洞。 | 所有项目 | | vue-typescript | 核心目标：预防响应式陷阱、组件通信混乱、性能问题及安全漏洞。 | 所有项目 | | vibe-coding | 核心目标：针对 AI/LM 生成代码特有毒点的精准识别。 | 所有项目 | | database | 数据库与 ORM 性能审查 | 所有项目 | | performance | 核心目标：识别代码变更中潜在的性能问题和资源浪费。 | 所有项目 | | code-smells | 核心目标：识别影响可维护性、可读性、安全性和性能的代码坏味道。 | 所有项目 | | business-design | 核心目标：检测代码变更中的业务逻辑缺陷，包括状态机错误、并发竞态、权限漏洞、一致性缺失、异步/回调/缓存导致的业务风险等 | 所有项目 | | impeccable | 核心目标：追求代码的无瑕品质，从可读性到健壮性的全面质量检查。 | 所有项目 | | systematic-debugging | 核心目标：用 4 阶段根因分析法审查代码变更，防止「创可贴式修复」。 | 所有项目 | | memory-leak-backend-resource | 服务端资源与运行时泄漏审查 | 所有项目 | | memory-leak-frontend-lifecycle | 前端内存泄漏审查 | 所有项目 | | memory-leak-verification | 内存泄漏修复验证审查 | 所有项目 |

来自 skills.sh 生态的规则

| 规则 ID | 描述 | 来源 | |---------|------|------| | grill-me | A relentless interview to sharpen a plan or design. | mattpocock/skills | | caveman-review | caveman-review | juliusbrussee/caveman | | web-design-guidelines | Review UI code for Web Interface Guidelines compliance. Use | vercel-labs/agent-skills | | react-best-practices | 规则版本：2025.11 | vercel-labs/agent-skills | | verification-before-completion | Use when about to claim work is complete, fixed, or passing, | obra/superpowers | | supabase-postgres-best-practices | Postgres performance optimization and best practices from Su | supabase/agent-skills | | supabase | 触发场景：任何涉及 Supabase 的任务。触发词：Supabase 产品（Database、Auth、Edge Fu | supabase/agent-skills | | receiving-code-review | Use when receiving code review feedback, before implementing | obra/superpowers | | test-driven-development | Use when implementing any feature or bugfix, before writing | obra/superpowers | | webapp-testing | Toolkit for interacting with and testing local web applicati | anthropics/skills | | code-review | Review the changes since a fixed point (commit, branch, tag, | mattpocock/skills | | resolving-merge-conflicts | Use when you need to resolve an in-progress git merge/rebase | mattpocock/skills | | improve-codebase-architecture | Scan a codebase for deepening opportunities, present them as | mattpocock/skills | | diagnosing-bugs | Diagnosis loop for hard bugs and performance regressions. Us | mattpocock/skills | | setup-pre-commit | 使用 Husky + lint-staged 配置 pre-commit 钩子（Prettier、ESLint、类型检查 | mattpocock/skills | | a-philosophy-of-software-design | Apply John Ousterhout-inspired software design rules when re | ciembor/agent-rules-books | | agnix | Use when user asks to 'lint agent configs', 'validate skills | agent-sh/agnix | | brainstorming | You MUST use this before any creative work - creating featur | obra/superpowers | | caveman-commit | caveman-commit | juliusbrussee/caveman | | caveman-compress | You should always make sure to run the test suite before pus | juliusbrussee/caveman | | caveman-evidence-review | 执行规则：只读操作员，不写入、不审批、不取消、不回滚、不导出 | juliusbrussee/caveman | | caveman-explore | Read-only repository explorer. Use PROACTIVELY for cold-star | juliusbrussee/caveman | | claude-api | claude-api | anthropics/skills | | clawsec-scanner | Automated vulnerability scanner for agent platforms. Perform | prompt-security/clawsec | | clean-architecture | Apply Robert C. Martin-inspired architecture rules when sepa | ciembor/agent-rules-books | | clean-code | Apply Robert C. Martin-inspired clean code rules when improv | ciembor/agent-rules-books | | code-complete | Apply Steve McConnell-inspired construction rules when imple | ciembor/agent-rules-books | | codebase-design | Shared vocabulary for designing deep modules. Use when the u | mattpocock/skills | | composition-patterns | ⚠️ React 19+ only. Skip this section if using React 18 o | vercel-labs/agent-skills | | design-an-interface | Generate multiple radically different interface designs for | mattpocock/skills | | designing-data-intensive-applications | Apply Martin Kleppmann-inspired data-system rules when desig | ciembor/agent-rules-books | | dispatching-parallel-agents | Use when facing 2+ independent tasks that can be worked on w | obra/superpowers | | domain-driven-design | Apply Eric Evans-inspired DDD rules when modeling a complex | ciembor/agent-rules-books | | domain-modeling | Build and sharpen a project's domain model. Use when discuss | mattpocock/skills | | executing-plans | Use when you have a written implementation plan to execute i | obra/superpowers | | finishing-a-development-branch | Use when implementation is complete, the suite is green, and | obra/superpowers | | git-guardrails-claude-code | Set up Claude Code hooks to block dangerous git commands (pu | mattpocock/skills | | grill-with-docs | 目标：通过高强度追问把一个模糊的计划或设计逼到可执行状态，并在过程中沉淀 ADR 与术语表。 | mattpocock/skills | | grilling | 描述：Grill the user relentlessly about a plan, decision, or id | mattpocock/skills | | handoff | Compact the current conversation into a handoff document for | mattpocock/skills | | implement-spec | Implement a specification in code. | mattpocock/skills | | implementing-domain-driven-design | Apply Vaughn Vernon-inspired implementation DDD rules when b | ciembor/agent-rules-books | | investigate-first | Diagnose ambiguous failures before editing. Use for unknown | juliusbrussee/caveman | | karpathy-guidelines | Behavioral guidelines to reduce common LLM coding mistakes. | mxyhi/ok-skills | | lean-build | Build feature work with high overbuilding risk. Use for new | juliusbrussee/caveman | | loop-me | Grill me about specs for the workflows I want to build, with | mattpocock/skills | | migrate-to-shoehorn | Migrate test files from as type assertions to @total-types | mattpocock/skills | | migration | Implement reversible compatibility-safe transitions. Use for | juliusbrussee/caveman | | offensive-api-security | Comprehensive API security testing methodology covering REST | SnailSploit/Claude-Red | | offensive-dependency-confusion | Deep-dive offensive methodology for dependency confusion and | SnailSploit/Claude-Red | | offensive-deserialization | Insecure deserialization exploitation across Java, PHP, .NET | SnailSploit/Claude-Red | | offensive-graphql | Offensive methodology for attacking GraphQL APIs during pene | SnailSploit/Claude-Red | | offensive-supply-chain | Comprehensive offensive methodology for software supply chai | SnailSploit/Claude-Red | | patterns-of-enterprise-application-architecture | Apply Martin Fowler-inspired enterprise architecture rules w | ciembor/agent-rules-books | | pr | Use when writing a PR body. | mattpocock/skills | | react-native-skills | vercel-react-native-skills | vercel-labs/agent-skills | | react-view-transitions | Guide for implementing smooth, native-feeling animations usi | vercel-labs/agent-skills | | release-it | Apply Michael T. Nygard-inspired production reliability rule | ciembor/agent-rules-books | | request-refactor-plan | Create a detailed refactor plan with tiny commits via user i | mattpocock/skills | | requesting-code-review | Use when completing tasks, implementing major features, or b | obra/superpowers | | retro | Conduct a retrospective on a coding session. | mattpocock/skills | | safe-refactor | Restructure code while preserving behavior. Use for extracti | juliusbrussee/caveman | | scaffold-exercises | Create exercise directory structures with sections, problems | mattpocock/skills | | setup-ts-deep-modules | Wire dependency-cruiser into a TypeScript repo so each packa | mattpocock/skills | | surgical-patch | Fix bugs and small behavior changes at the narrowest respons | juliusbrussee/caveman | | tdd | Test-driven development. Use when the user wants to build fe | mattpocock/skills | | triage | Move issues and external PRs through a state machine of tria | mattpocock/skills | | ubiquitous-language | Extract a DDD-style ubiquitous language glossary from the cu | mattpocock/skills | | verify-and-stop | Prove existing work meets acceptance conditions without expa | juliusbrussee/caveman | | working-effectively-with-legacy-code | Apply Michael Feathers-inspired legacy-code rules when chang | ciembor/agent-rules-books | | writing-beats | Writing, exploit; assemble raw material into a journey of be | mattpocock/skills | | writing-for-agents | Writing documents for agents. Use when creating or editing s | mattpocock/skills | | writing-fragments | Writing, explore: mine raw fragments, no structure yet. | mattpocock/skills | | writing-plans | Use when you have a spec or requirements for a multi-step ta | obra/superpowers | | writing-shape | Writing, exploit: shape raw material into an article, paragr | mattpocock/skills | | writing-skills | Use when creating new skills, editing existing skills, or ve | obra/superpowers |

规则管理

# 列出所有可用规则
npx smart-git-review rules

# 启用规则
npx smart-git-review enable security
npx smart-git-review enable grill-me

# 禁用规则
npx smart-git-review disable vibe-coding

配置

在项目根目录创建 .gitaireviewrc.json：

{
  "model": "qwen3.6-plus",
  "apiUrl": "https://coding.dashscope.aliyuncs.com/v1/chat/completions",
  "blockOnCritical": true,
  "reviewOnCommit": true,
  "reviewOnPush": false,
  "reviewOnPull": true,
  "openViewer": true,
  "presetRules": ["security", "react-typescript", "vibe-coding", "grill-me"]
}

常用配置项：

| 配置项 | 默认值 | 说明 | |--------|--------|------| | model | qwen3.6-plus | AI 模型；回落到 GIT_AI_REVIEW_MODEL | | apiUrl | 阿里云 DashScope | API 地址；回落到 GIT_AI_REVIEW_API_URL | | blockOnCritical | false | 发现 CRITICAL 问题时阻断提交 | | reviewOnCommit / reviewOnPush / reviewOnPull | true / false / false | 各 hook 的审查开关 | | presetRules | ["vibe-coding"] | 启用的预设规则 ID 列表；审查时按规则路由只加载与本次 diff 相关的规则 | | ruleRouting | true | 规则路由开关：按 diff 的后缀/目录匹配加载领域规则（如出现 .sql 才挂 database），false 则全量加载 | | rules | [] | 自定义规则（预设 ID、文件路径或纯文本），不受规则路由影响，永远加载 | | openViewer | true | 审查后自动打开 HTML 报告；自动化场景建议 false | | sessionWindowHours | 12 | 关联「会话 → 提交」的回溯时间窗口（小时） | | maxDiffLines | 2000 | 单次审查的最大 diff 行数 | | skipPatterns | 锁文件/构建产物等 | 跳过的文件模式 | | businessContext | 关闭 | 业务上下文加载（文档、领域模型等） |

优先级：.gitaireviewrc.json 的 model / apiUrl 高于 同名环境变量，环境变量高于内置默认值。

全局配置回退

个人偏好（model、theme、suppressAcknowledged 等）可放在 ~/.config/smart-git-review/config.json，跨项目复用。项目 .gitaireviewrc.json 优先，未覆盖的键回落到全局配置。

配置文件不接受 API key

.gitaireviewrc.json（及全局配置）中的 apiKey 字段会被忽略并打印警告——防止密钥被误提交进仓库。请始终通过环境变量 GIT_AI_REVIEW_API_KEY 提供密钥。

环境变量

| 变量名 | 说明 | 默认值 | |--------|------|--------| | GIT_AI_REVIEW_API_KEY | API 密钥（必需） | - | | GIT_AI_REVIEW_MODEL | AI 模型 | qwen3.6-plus | | GIT_AI_REVIEW_API_URL | API 地址 | 阿里云 DashScope | | DASHSCOPE_API_KEY | 密钥回退值 | - |

规则植入

将质量规范前置到「用 AI 写代码」的环节：

# 自动检测项目中的工具并植入（默认规则：vibe-coding,security,performance,code-smells）
npx smart-git-review inject

# 指定工具和规则
npx smart-git-review inject --tool claude --rules security,performance

# 植入所有规则到所有工具
npx smart-git-review inject --tool all --rules all

# 清除已植入的规范
npx smart-git-review uninject --tool all

| 工具 | 载体 | |------|------| | Claude Code | .claude/rules/*.md（支持路径限定） | | Kilo Code | .kilo/rules/*.md + .kilo/plugin/git-ai-review.ts | | Cursor | .cursor/rules/*.md | | Windsurf | .windsurf/rules/*.md | | Cline | .clinerules | | GitHub Copilot | .github/copilot-instructions.md | | 通用 | AGENTS.md（所有工具都能读取的兼容层） |

审查报告与 Kilo Code 自动投递

inject --tool kilo 会生成 Kilo Code 插件（.kilo/plugin/git-ai-review.ts），让报告无需手动转发：

• 自动投递：把未处理的报告注入系统提示，Kilo 在后续对话中自动判定真伪；也可调用 get_pending_reviews / acknowledge_review 工具。
• 会话归属：插件记录「会话 → 改动文件」到 .git-ai-review/sessions.jsonl；post-commit 据此把本次提交涉及的所有会话写入报告的 sessions 字段。
• 去重：报告有 pending / acknowledged 两种状态，处理过的不再重复投递。

npx smart-git-review reports
npx smart-git-review reports --json
npx smart-git-review ack --all

其他

# 代码健康报告
npx smart-git-review health

# 发布审查结果到 PR 评论
npx smart-git-review pr

# 启动本地查看器
npx smart-git-review serve

更新日志

本文件记录每个发布版本的更新内容。发布新版本时在此顶部追加条目， packages/core/README.md 的「更新日志」章节会由它自动生成。

格式：## [版本号] - YYYY-MM-DD + 变更要点。

[1.1.2] - 2026-10-15

• 新增规则路由（ruleRouting，默认开启）：审查时按 diff 涉及的后缀/目录只加载相关预设规则（如出现 .sql/models/ 才挂 database），security、performance 等通用规则始终加载，rules 中的自定义规则不受路由影响，ruleRouting: false 可全量加载。
• 新增全局配置回退：个人偏好（model、theme、suppressAcknowledged 等）可放 ~/.config/smart-git-review/config.json 跨项目复用，项目 .gitaireviewrc.json 优先。
• 配置文件中的 apiKey 字段现在会被警告并忽略（设计理念：配置文件永不接受 key，防止误提交进仓库）。
• 规则演化：更新 architecture、business-design、grill-me 等 6 条既有规则，新增 handoff、implement-spec、pr、retro 等 9 条 mattpocock/skills 规则，预设规则 81 → 90。
• 修复同步工具把新规则注册进 PRESET_RULES 时替换逻辑无效导致静默漏注册的问题（本次漏注册的 9 条规则已补上）。
• 修复 e2e 测试在 Windows 上的两个环境问题：子进程 spawn node ENOENT（改用 process.execPath）和 .git 只读对象文件导致的 EPERM 清理失败；测试基线恢复全绿（20 个用例）。
• 新增配置加载测试（全局回退/优先级、apiKey 警告、规则路由）。

[1.1.1] - 2026-09-29

• 新增分块审查：diff 超过 reviewChunkChars（默认 12000）时按文件拆块并行审查，跨块按问题签名去重；单次调用超出 maxPromptChars 时显式警告（替代原先 5000 字符静默截断）。
• 新增误报抑制（suppressAcknowledged，默认开启）：已 ack 报告中的问题进入抑制基线，后续命中不再计数/阻断，仍记录在报告的 suppressed 字段备查。
• 修复 inject --tool all 写入 Copilot 的 .github/copilot-instructions.md 时因父目录不存在报 ENOENT；uninject 现在会清理遗留的空目录（如 .github/、.claude/），其中存在用户文件的目录自动保留。
• 新增测试基线（bun run test，12 个用例）：抑制签名/基线、分块打包/去重、inject 往返、端到端 review 流程。

[1.1.0] - 2026-09-24

• CLI 命令由 git-ai-review 更名为 smart-git-review；保留 git-ai-review 作为兼容别名，已装的 Git Hooks 无需改动。
• 注册全部 81 条预设规则（此前仅 26 条可通过 --rules / presetRules 使用），rules 命令可完整列出。
• README 命令统一为 npx smart-git-review，并补充命令表、post-commit、配置项、Kilo 自动投递等章节；README 生成器同步更新。

[1.0.9] - 2026-09-18

• 新增「审查报告自动投递给 Kilo Code」：报告索引与 pending/ack 状态、会话归属（sessions.jsonl + post-commit）、Kilo 插件、reports / ack 命令。
• evolve-inject.js --adapt 支持写入模式：结构化输出、预览确认、备份与 node --check 校验。
• 新增 21 个 prompt 规则文件。
• 修复 --adapt 备份/校验文件写入 src/ 被随包发布的问题（移至 .evolve-preview/）。

[1.0.8] - 2026-09-11

• 新增 18 个来自 skills 的规则（caveman-*、tdd、triage、writing-*、investigate-first 等），并批量更新既有提示词。

[1.0.6] - 2026-07-23

• 新增 claude-api 等提示词，批量更新既有审查规则。

[1.0.5] - 2026-07-20

• 调整审查结果输出（output/writer.js）与 AI 调用逻辑（review/ai.js）。

[1.0.4] - 2026-07-08

• 集成新的 skills 规则并优化 skill 更新策略。

[1.0.3] - 2026-07-06

• 规则抓取改为先 clone 后抓取。

[1.0.1] - 2026-06-26

• 初始版本：Git Hooks 自动审查、预设规则库、规则植入（inject）。

许可证

MIT