git-ai-audit

v0.1.1

Published

a month ago

用 AI 审计 git 提交内容的本地插件：pre-commit/pre-push 钩子 + CLI + 本地网页面板

0High
0Medium
0Low

cranux

git git-hooks pre-commit pre-push code-review ai llm openai deepseek ollama cli

git-ai-audit

English · 架构文档

用 AI 审计 git 提交内容的本地插件。提交或推送时自动把 diff 交给你配置的模型，找出明显的语法错误、逻辑错误和值得确认的可疑点；本地网页面板管理 AI 源、策略和启用的仓库。

四种触发方式：pre-commit 钩子、pre-push 钩子、命令行 git ai-audit review、面板按钮
任意 OpenAI 兼容接口都能用：OpenAI、DeepSeek、Ollama 本地模型、各类中转站
只审计你在面板里打开开关的仓库，其他仓库完全不受影响
默认策略：error 级发现拦截提交，warning / info 只警告；AI 源出错不阻塞提交

安装

npm install -g git-ai-audit

要求 Node.js ≥ 20 与 git。安装后 git ai-audit 与 git-ai-audit 两种写法等价。

从源码安装：

git clone https://github.com/cranux/git-ai-audit.git
cd git-ai-audit
npm install
npm run build
npm link

快速开始

# 1. 启动面板，添加 AI 源
git ai-audit panel --open

# 2. 在要审计的仓库里启用（或在面板「仓库」页添加并打开开关）
cd your-repo
git ai-audit init

# 3. 正常提交，pre-commit 自动审计暂存区；push 时审计将要推送的 commit
git commit -m "..."

提交被拦截时终端会打印发现列表和跳过方法。手动审计随时可以运行：

git ai-audit review

工作原理

git commit ──▶ .git/hooks/pre-commit ──▶ git-ai-audit hook pre-commit
                                              │
                    读注册表：仓库未启用则直接放行
                                              │
              git diff --cached ─▶ 过滤二进制/忽略文件 ─▶ 按大小分块
                                              │
                      并发调用 AI 源（OpenAI 兼容 /chat/completions）
                                              │
                    解析 JSON 发现 ─▶ 按策略判定 ─▶ 写历史 ─▶ 退出码

钩子脚本只有一行转发；真正的逻辑在 CLI 里。钩子运行时会再读一次注册表，所以即使钩子文件残留，未启用的仓库也不会被审计。工具自身的任何内部错误都会打印一行并放行，不会把仓库锁死。

命令

| 命令 | 说明 | |---|---| | git ai-audit init | 注册并启用当前仓库，安装 pre-commit / pre-push 钩子 | | git ai-audit uninstall | 停用当前仓库，移除本工具钩子并恢复原有钩子 | | git ai-audit review | 审计暂存区，等价于 --staged | | git ai-audit review --commit <sha> | 审计单个 commit | | git ai-audit review --range <A..B> | 审计区间，例如 main..HEAD | | git ai-audit review --json | 以 JSON 输出结果，可与上面的选项组合 | | git ai-audit panel [--port 3777] [--open] | 启动本地面板，--open 自动打开浏览器 | | git ai-audit hook <pre-commit\|pre-push> | 钩子内部调用，不需要手动执行 |

退出码

| 退出码 | 含义 | |---|---| | 0 | 通过，或只有未达到拦截级别的发现，或 AI 源出错且策略为放行 | | 1 | 按策略拦截 | | 2 | 参数或环境错误：不是 git 仓库、没有可用的 AI 源、git 命令失败、面板启动失败 |

钩子子命令永远不会因为工具自身的错误返回非零值。

`--json` 输出

{
  "id": "6d1c…",
  "createdAt": "2026-09-01T12:00:00.000Z",
  "repoPath": "/abs/path/repo",
  "trigger": "cli",
  "mode": "staged",
  "target": "staged",
  "provider": { "name": "DeepSeek", "model": "deepseek-chat" },
  "filesReviewed": 3,
  "findings": [
    {
      "file": "src/a.ts",
      "line": 12,
      "severity": "error",
      "category": "syntax",
      "message": "缺少右括号",
      "suggestion": "在第 12 行末尾补上 )"
    }
  ],
  "summary": "一句话总结",
  "providerErrors": [],
  "blocked": true,
  "exitCode": 1,
  "reason": "发现 1 个 error、0 个 warning，按策略 blockOn=error 拦截",
  "durationMs": 2310
}

severity：error / warning / info
category：syntax（语法错误）/ logic（逻辑错误）/ question（值得确认的疑问）
line 可能为 null；suggestion 可能缺省
trigger：pre-commit / pre-push / cli / panel

AI 源

面板「AI 源」页可以配置多个源并选一个作为当前源。所有源都通过 OpenAI 兼容的 POST {baseUrl}/chat/completions 调用，不依赖任何厂商 SDK。

| 预设 | Base URL | 默认模型 | 需要 Key | |---|---|---|---| | OpenAI | https://api.openai.com/v1 | gpt-4o-mini | 是 | | DeepSeek | https://api.deepseek.com/v1 | deepseek-chat | 是 | | Ollama（本地） | http://localhost:11434/v1 | qwen2.5-coder:7b | 否 | | 自定义 | 任意 OpenAI 兼容地址 | 自填 | 视服务而定 |

预设只是新建时的默认填值，保存后可以随意改。「测试」按钮会发一个最小请求验证连通性并显示耗时。

用 Ollama 在本机跑

ollama pull qwen2.5-coder:7b
ollama serve

在面板里选「Ollama（本地）」预设，Key 留空，保存后点「测试」。代码不会离开本机。

请求与容错

每次请求带 temperature: 0，要求模型只输出 JSON。
模型回复不是合法 JSON 时会带着原回复重试一次；再失败按「AI 源出错」处理。
单次请求超时由每个源的 timeoutMs 决定，默认 30 秒，从连接到读完响应体都受它约束。

哪些仓库会被审计

面板「仓库」页的注册表是唯一依据：

打开开关：把 pre-commit 和 pre-push 钩子装进该仓库，并记为启用。
关闭开关：移除本工具的钩子，恢复之前的钩子，记为停用。
没添加或没打开开关的仓库：不会被安装任何东西。
git ai-audit init 等价于添加并打开开关，uninstall 等价于关闭开关。

「扫描」可以输入一个父目录，列出其中一层子目录里的 git 仓库批量勾选。

已有钩子

如果仓库里已经有自己的 pre-commit 或 pre-push 钩子，启用时会把它改名为 <name>.pre-git-ai-audit，本工具的钩子跑完后再调用它（pre-push 的 stdin 会原样透传）。关闭开关时改回原名。

使用 husky 等 `core.hooksPath` 的仓库

工具不会覆盖 core.hooksPath，而是把仓库标记为「手动接入」并打印需要加入钩子文件的那一行，例如在 .husky/pre-commit 里加：

git-ai-audit hook pre-commit "$@" || exit $?

pre-push 同理，把 stdin 透传给命令即可。

git worktree

钩子会装进主仓库的 .git/hooks（git 只认这个目录），注册表以主工作树根目录为键。在 linked worktree 里提交也会被审计，不需要单独启用。

面板

git ai-audit panel --open

终端会打印一个带 #token= 的地址，只有通过这个地址打开的页面能调用接口。面板只监听 127.0.0.1，关闭终端即停止。

| 页面 | 功能 | |---|---| | 仓库 | 添加路径或扫描父目录、启用开关、移除；core.hooksPath 仓库显示手动接入说明 | | AI 源 | 增删改、按预设填表、测试连通性、设为当前；Key 只显示后 4 位 | | 策略 | 拦截级别、AI 源出错行为、语言、分块大小、并发、超时、忽略模式、历史目录与条数 | | 审计 | 选仓库和范围（暂存区 / 某个 commit / 区间）运行，按文件分组显示发现 | | 历史 | 按仓库筛选，点开查看某次审计的完整结果 |

面板不是常驻服务，需要时启动即可；钩子和 CLI 不依赖面板运行。

策略与配置

全局配置

路径 ~/.config/git-ai-audit/config.json，权限 0600，包含 AI 源（含 API Key）、当前源、策略和仓库注册表。环境变量 GIT_AI_AUDIT_CONFIG 可以改路径。

策略项及默认值：

| 项 | 默认 | 说明 | |---|---|---| | blockOn | error | error / warning / never，达到该级别的发现拦截提交 | | onProviderError | warn | AI 源网络错误、超时或输出无法解析时：warn 放行并警告，block 拦截 | | language | zh-CN | 要求模型用哪种语言写说明 | | maxChunkChars | 60000 | 单次请求最多送入的 diff 字符数，超大文件截断并注明 | | concurrency | 3 | 并发请求数 | | ignore | *.lock、package-lock.json、pnpm-lock.yaml、yarn.lock、dist/**、*.min.js、*.min.css、*.map | glob；不含斜杠的模式按文件名匹配 | | history.dir | ~/.local/share/git-ai-audit/history | 历史目录，支持 ~ | | history.maxEntries | 200 | 保留条数，0 表示不记录 |

仓库级配置

可选文件 <repo>/.git-ai-audit.json，可以随代码提交，只允许下面四项，覆盖全局值：

{ "blockOn": "warning", "language": "en-US", "ignore": ["*.snap"], "maxChunkChars": 40000 }

出现其他字段时整个文件会被忽略。

环境变量

| 变量 | 作用 | |---|---| | GIT_AI_AUDIT_SKIP=1 | 本次钩子直接放行 | | GIT_AI_AUDIT_CONFIG | 覆盖全局配置路径 | | NO_COLOR / FORCE_COLOR | 关闭 / 强制终端彩色输出 |

跳过一次审计：

GIT_AI_AUDIT_SKIP=1 git commit -m "..."

或者使用 git 自带的 --no-verify。

历史记录

每次审计一个 JSON 文件，只存结果不存 diff，权限 0600，超过保留条数时删最旧的。面板「历史」页读的就是这个目录。

pre-push 审计的范围

推送时钩子从 git 拿到每个引用的本地与远端提交：

远端已有基准：审计 远端提交..本地提交。
推新分支：审计任何远端都还没有的提交，最多最近 20 个；超过时终端会打印「只审计最近 20 个」的提示。
删除分支：不审计。

多个引用会逐个审计，任意一个被拦截则整次推送失败。

安全

面板只绑定 127.0.0.1，每个接口请求必须带启动时生成的随机 token，Origin 头存在时必须是本机。
API Key 只存在本机配置文件里（0600），面板读取时脱敏，回传脱敏值不会覆盖原 Key。
diff 只发送到你配置的 AI 源；用 Ollama 时不出本机。
用户传入的 commit / 区间不允许以 - 开头，避免被 git 当成选项。

排错

| 现象 | 原因与处理 | |---|---| | 提交时打印「未找到 git-ai-audit 命令，跳过审计」 | 钩子找不到 PATH 里的命令。确认 npm install -g 的 bin 目录在 PATH 中，GUI 客户端可能需要重启 | | 打印「未配置 AI 源，跳过审计」 | 面板里没有设为当前的源，运行 git ai-audit panel 添加 | | 打印「AI 源错误 … 请求超时」后提交成功 | 策略 onProviderError=warn 放行；检查网络、Base URL、Key，或把超时调大 | | 面板页面显示「令牌」错误 | 重新从终端打印的带 #token= 的地址打开；面板每次启动 token 都不同 | | 启用后没有审计 | 仓库使用了 core.hooksPath（husky 等），按提示手动加入那一行 | | 想临时跳过 | GIT_AI_AUDIT_SKIP=1 git commit … 或 git commit --no-verify | | 配置文件损坏 | 自动备份为 config.json.bak 并重建默认配置，终端和面板会提示 |

开发

npm install
npm run typecheck     # 后端 + 面板前端类型检查
npm run test:unit     # 单元、API 测试
npm test              # 构建 + 全部测试（含真实 git 钩子的 e2e）
npm run build         # tsc → dist/，vite → dist/web/
node dist/cli/index.js --help

代码结构与设计见 docs/ARCHITECTURE.md，原始设计文档在 docs/superpowers/specs/。

许可

PolyForm Noncommercial 1.0.0。个人、教育、非营利等非商业用途可以自由使用、修改和分发；任何商业用途，包括基于本项目的商业二次开发，均不允许。商业授权请联系作者。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

git-ai-audit

安装

快速开始

工作原理

命令

退出码

--json 输出

AI 源

用 Ollama 在本机跑

请求与容错

哪些仓库会被审计

已有钩子

使用 husky 等 core.hooksPath 的仓库

git worktree

面板

策略与配置

全局配置

仓库级配置

环境变量

历史记录

pre-push 审计的范围

安全

排错

开发

许可

`--json` 输出

使用 husky 等 `core.hooksPath` 的仓库