1. 为什么我要给 AI 编程助手加一道 Git 提交门用 AI 编程助手写代码最爽的是生成速度最慌的是提交那一刻。你可能也遇到过助手说“测试已跑通”“安全检查没问题”你顺手git add . git commit结果第二天发现某个函数根本没被测试覆盖或者一段临时调试代码被带进了主分支。问题不在于助手不靠谱而在于“检查”这件事没有变成项目里可执行、可拦截的固定动作。我试过在对话里反复叮嘱“记得跑测试”但每次新开会话都要重说一遍而且助手说“已完成”并不等于命令真的执行过。后来我把思路换成让 Python 写一个 Git pre-commit 钩子把 AI 助手产出的代码挡在提交门外只有通过校验的暂存内容才允许入库。同时本地多个 AI 助手Cursor、Claude Code、命令行脚本需要统一鉴权我用 TaoToken 做统一 Key 与 API 通道避免每个工具各配一套密钥。这篇面向的是已经在本地仓库接入 AI 编程助手、想让提交前多一道自动校验的开发者。你会拿到可复制的pre-commit配置、settings.json/config.toml骨架、TaoToken 统一 Key 接入示例以及触发钩子、拦截失败提交的完整验证动作。全程 Python Git不需要额外服务。2. TaoToken 前置统一 Key 与 API 通道在写钩子之前先把鉴权这层理顺。本地可能同时跑着几个 AI 助手一个负责补全一个负责重构一个负责跑测试脚本。如果每个工具都单独填 Key、单独记额度管理成本很快就上来了。TaoToken 的作用是提供一个统一的 API 通道你申请一次 Key多个助手共用同一个入口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。注意这里说的是统一鉴权和调用通道不是让你把编辑器换掉——编辑器还是你原来的编辑器只是把模型请求指向同一个 Key。实际操作上你需要在控制台创建一个 API Key然后把它写进各助手的配置文件。Key 本身不要硬编码进仓库用环境变量或本地未跟踪的配置文件承载。下面给一个.env骨架配合.gitignore使用# .env务必加入 .gitignore不要提交 TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api# .gitignore .env .quality-gate/注意.quality-gate/是后面钩子生成的通行证目录属于本地状态不应该进版本库否则会污染提交内容。拿到 Key 之后先别急着写钩子用一条最小请求确认通道可用。这一步能帮你把“Key 问题”和“钩子问题”分开排查后面出错时不会混在一起。3. 可复制配置settings.json 与 config.toml 骨架不同助手读不同格式的配置。Cursor 类工具常用settings.json一些命令行 Agent 用config.toml。下面两份骨架都指向 TaoToken 的统一入口你可以按需取用。先看settings.json{ aiProvider: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, model: claude-sonnet, timeoutMs: 60000 }, qualityGate: { enabled: true, markerDir: .quality-gate, requireTestPass: true, requireAuditPass: true } }再看config.toml[provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet timeout_ms 60000 [quality_gate] enabled true marker_dir .quality-gate require_test_pass true require_audit_pass true两份配置的关键点一致base_url指向统一通道api_key_env指向环境变量而不是明文 Keyquality_gate段落告诉助手通行证放在哪、需要哪些检查通过。这样钩子和助手读的是同一份约定不会各说各话。接下来是钩子本体。Git 的pre-commit钩子放在.git/hooks/下默认不随仓库分发更好的做法是放到仓库内的hooks/目录再用core.hooksPath指过去。先写钩子脚本#!/bin/sh # hooks/pre-commit python scripts/check_quality_gate.py然后写 Python 校验脚本这是整道门的核心# scripts/check_quality_gate.py import os import subprocess import sys import time MARKER_DIR .quality-gate TEST_FLAG os.path.join(MARKER_DIR, test-passed.flag) AUDIT_FLAG os.path.join(MARKER_DIR, audit-passed.flag) TOLERANCE_MS 2000 # Windows 文件时间精度容差 def staged_files(): out subprocess.run( [git, diff, --cached, --name-only, --diff-filterACMR], capture_outputTrue, textTrue, checkTrue, ).stdout return [f for f in out.splitlines() if f.strip()] def newest_source_mtime(files): newest 0.0 for f in files: if os.path.exists(f): newest max(newest, os.path.getmtime(f)) return newest def marker_mtime(path): return os.path.getmtime(path) if os.path.exists(path) else 0.0 def main(): files staged_files() if not files: return 0 for flag in (TEST_FLAG, AUDIT_FLAG): if not os.path.exists(flag): print(f[质量门禁] 拦截缺少通行证 {flag}) return 1 newest_src newest_source_mtime(files) oldest_marker min(marker_mtime(TEST_FLAG), marker_mtime(AUDIT_FLAG)) if newest_src oldest_marker TOLERANCE_MS / 1000: print([质量门禁] 拦截通行证已过期暂存代码比检查结果更新) return 1 print([质量门禁] 通过测试与审计通行证有效放行) return 0 if __name__ __main__: sys.exit(main())启用钩子只需要一条命令git config core.hooksPath hooks如果你在 Windows 上编辑器可能把钩子存成 CRLF而sh执行时换行符错误会直接失败。用.gitattributes固定为 LFhooks/pre-commit text eollf4. 验证请求触发钩子并拦截失败提交配置写完必须实际触发一次确认门真的会拦人。先制造一个“没有通行证”的场景rm -rf .quality-gate echo print(debug) app.py git add app.py git commit -m test: 无通行证提交预期结果是提交被拒绝终端输出类似[质量门禁] 拦截缺少通行证 .quality-gate/test-passed.flag接着模拟“通行证过期”。先手动生成两张通行证再修改代码让源码时间晚于通行证mkdir -p .quality-gate touch .quality-gate/test-passed.flag .quality-gate/audit-passed.flag sleep 3 echo # 新改动 app.py git add app.py git commit -m test: 过期通行证提交这次应该看到[质量门禁] 拦截通行证已过期暂存代码比检查结果更新最后验证放行路径。重新生成通行证且不再改动源码touch .quality-gate/test-passed.flag .quality-gate/audit-passed.flag git commit -m feat: 通过门禁的提交输出应为[质量门禁] 通过测试与审计通行证有效放行三种场景对照如下场景暂存内容通行证状态结果无通行证有改动不存在拒绝提交通行证过期有改动早于源码修改时间拒绝提交检查后提交有改动晚于源码修改时间允许提交如果你还想在提交前用模型做一次语义检查可以把暂存 diff 发给模型对话接口确认入口在 https://taotoken.net/api 配合前面settings.json里的baseUrl即可。长期跑编码 Agent 的话Coding Plan 更适合持续调用场景。5. 本篇常见错排查钩子不生效最常见的原因是core.hooksPath没设或设错。先确认git config --get core.hooksPath如果输出为空说明钩子根本没被 Git 读取重新执行git config core.hooksPath hooks。如果输出是别的路径检查hooks/pre-commit是否真的在那个目录下。第二个高频问题是权限。Linux/macOS 下钩子需要可执行权限chmod x hooks/pre-commitWindows 上则要确认换行符是 LF用file hooks/pre-commit或编辑器查看出现 CRLF 就按第 3 节的.gitattributes修正。第三个问题是通行证时间判断过于严格导致刚检查完就提交也被拦。这通常是文件系统时间精度或时钟漂移造成的脚本里的TOLERANCE_MS 2000就是为此留的容差。如果你的环境时间差更大可以适当调大但不要调得太大否则过期判断会失效。第四个问题是.quality-gate/被误提交。检查.gitignore是否包含它已经误提交的话用git rm -r --cached .quality-gate移出暂存区。注意本地钩子可以被--no-verify绕过通行证也能手工伪造。它的定位是防止正常开发中的流程遗漏不是密码学级别的安全边界。团队项目仍应在 CI 里独立重跑测试和审计把远程结果作为最终依据。6. 把检查变成可验证的步骤这套方案真正改变的不是多了几个配置文件而是把“提交”拆成了几个可验证的动作助手按统一 Key 调用模型检查脚本产出通行证Git 钩子验证通行证是否对应当前暂存代码。你不再依赖“应该检查过了”这种判断而是必须拿出测试和审计结果才能过门。落地时建议先只拦“测试未通过”这一项跑顺之后再加入安全审计和注释一致性检查避免一上来门太严导致自己频繁绕过。接入文档和 API Key 管理在 https://taotoken.net/api-keys 与 https://taotoken.net/doc 先把 Key 和通道跑通再回来调钩子排查会清晰很多。