aicommit

终端中的 AI 约定式提交消息生成器。

通过 OpenAI、Gemini 或 Anthropic 分析暂存区的 git diff，自动生成符合 约定式提交 规范的提交消息。

English

特性

• 三种 AI 提供商：OpenAI（含 Azure/DeepSeek）、Gemini、Anthropic
• 开箱即用的约定式提交格式
• Gitmoji 支持（可选）
• 多语言提交消息
• 交互式工作流：接受、编辑、重新生成或取消
• 4 层配置优先级：CLI 参数 > 环境变量 > 项目配置 > 全局配置
• 自定义提示词文件
• Dry-run 模式
• lazygit 集成：一键生成消息并预填提交面板
• 零配置默认值——只需设置 API Key 即可使用

快速开始

# 无需安装，直接运行
npx @bhxch/aicommit

前提条件：Node.js >= 22.19、一个有暂存变更的 git 仓库、一个 API Key。

安装

# 直接使用 npx
npx @bhxch/aicommit

# 或全局安装
npm install -g @bhxch/aicommit
aicommit

使用

基本用法

# 先暂存你的变更
git add .

# 生成提交消息并交互确认
aicommit

工具会读取暂存区的 diff，发送给 AI 模型，然后展示生成的提交消息。你可以：

• Accept（接受） — 直接提交
• Edit（编辑） — 在 $EDITOR 中修改
• Regenerate（重新生成） — 生成新的消息
• Abort（取消） — 放弃提交

命令行选项

| 选项 | 说明 | |------|------| | -y, --yes | 跳过确认，直接提交 | | -a, --all | 生成前暂存所有变更（git add -A） | | --staged-only | 仅使用已暂存的变更；无暂存时报错 | | --dry-run | 仅生成消息，不提交 | | -c, --context <text> | 为 AI 提供额外上下文 | | -p, --prompt <file> | 使用自定义提示词文件 | | --prefix <text> | 在提交消息前添加前缀 | | --no-gitmoji | 禁用 gitmoji 表情前缀 | | -l, --lang <language> | 提交消息语言（默认：English） | | --provider <provider> | AI 提供商：openai、gemini、anthropic | | --model <model> | 模型名称（如 gpt-4o、gemini-2.0-flash） | | --temperature <number> | 采样温度，0–2（默认：0.7） | | --thinking | 启用 AI 模型推理模式（默认关闭） | | --thinking-level <level> | 推理深度 low/medium/high/xhigh/max（默认 low） | | --thinking-mode <mode> | Anthropic 程度传递机制 budget/effort（默认 budget；effort 直传原生 output_config.effort，仅 Opus 4.6+ 等新模型支持，且 --thinking-level 不校验、原样透传） | | --proxy <url> | 通过指定的 HTTP(S) 代理路由 API 请求 | | --no-proxy | 忽略代理设置，强制直连 |

示例

# 自动提交，无需确认
aicommit -y

# 预览消息但不提交
aicommit --dry-run

# 暂存所有变更并提交
aicommit -a -y

# 使用 Anthropic 并指定模型
aicommit --provider anthropic --model claude-sonnet-4-20250514

# 开启推理模式并指定思考深度
aicommit --thinking --thinking-level high

# 生成中文提交消息
aicommit -l "简体中文"

# 添加关于你所做变更的上下文
aicommit -c "重构了认证模块以使用 JWT"

# 在消息前添加工单编号
aicommit --prefix "PROJ-123"

与 lazygit 配合使用

lazygit v0.46.0 起内置了提交消息持久化机制：打开提交面板时会自动读取 git 目录下的 LAZYGIT_PENDING_COMMIT 文件预填消息，提交确认后自动清除。利用它，可以让 aicommit 生成的消息直接进入 lazygit 的提交流程。

在 ~/.config/lazygit/config.yml 中添加自定义命令：

customCommands:
  - key: '<c-a>'
    context: 'global'
    command: 'f="$(git rev-parse --git-dir)/LAZYGIT_PENDING_COMMIT"; aicommit --dry-run --staged-only 2>/dev/null | tee "$f.tmp"; test ${PIPESTATUS[0]} -eq 0 && mv "$f.tmp" "$f" || rm -f "$f.tmp"'
    description: 'AI 生成 commit message（生成后按 c 预填提交）'
    output: none
    loadingText: '正在生成 commit message…'

使用流程：

1. 在 Files 面板暂存变更（space 逐个暂存，a 全部暂存）
2. 按 <c-a>，等待 AI 生成提交消息
3. 在 Files 面板按 c 打开提交面板，消息已预填，可继续编辑
4. 按 enter 确认提交

说明：

• --dry-run 只生成消息不提交，实际提交仍由 lazygit 完成；--staged-only 确保只基于已暂存变更生成
• 消息先写入 .tmp 临时文件，成功后原子重命名为 LAZYGIT_PENDING_COMMIT；生成失败时（无暂存变更、API 出错等）不会写入新消息，按 c 得到的是正常的提交面板
• 该文件位于 git 目录内，不会进入版本控制，提交确认后由 lazygit 自动删除
• 命令使用了 bash 的 PIPESTATUS。lazygit 通过 $SHELL -c 执行自定义命令：$SHELL 为 bash 时一切正常；为 zsh 时会静默失效（不报错但消息不会写入）。跨 shell 请把命令中 aicommit ... | tee ... 起的部分改为 if aicommit --dry-run --staged-only >"$f.tmp" 2>/dev/null; then mv "$f.tmp" "$f"; else rm -f "$f.tmp"; fi

配置

配置按优先级从高到低解析（高优先级覆盖低优先级）：

1. CLI 参数
2. 环境变量（AICOMMIT_* 前缀）
3. 项目配置（git 根目录下的 .aicommitrc.json）
4. 全局配置（~/.aicommitrc.json）
5. 默认值

配置文件

在项目根目录或用户主目录下创建 .aicommitrc.json：

{
  "provider": "openai",
  "model": "gpt-4o",
  "temperature": 0.7,
  "language": "English",
  "gitmoji": true,
  "thinking": false,
  "thinkingLevel": "medium",
  "thinkingMode": "budget",
  "prefix": "",
  "promptFile": "",
  "openai": {
    "apiKey": "sk-xxx",
    "baseUrl": "https://api.openai.com/v1",
    "apiVersion": ""
  },
  "gemini": {
    "apiKey": "xxx",
    "baseUrl": ""
  },
  "anthropic": {
    "apiKey": "sk-ant-xxx",
    "baseUrl": ""
  }
}

环境变量

| 变量 | 说明 | |------|------| | AICOMMIT_OPENAI_API_KEY | OpenAI API Key | | AICOMMIT_OPENAI_BASE_URL | OpenAI 基础 URL（用于 Azure/DeepSeek） | | AICOMMIT_AZURE_API_VERSION | Azure OpenAI API 版本 | | AICOMMIT_GEMINI_API_KEY | Gemini API Key | | AICOMMIT_GEMINI_BASE_URL | Gemini 基础 URL | | AICOMMIT_ANTHROPIC_API_KEY | Anthropic API Key | | AICOMMIT_ANTHROPIC_BASE_URL | Anthropic 基础 URL | | AICOMMIT_PROVIDER | 默认提供商 | | AICOMMIT_MODEL | 默认模型 | | AICOMMIT_LANGUAGE | 默认语言 | | AICOMMIT_TEMPERATURE | 默认温度 | | AICOMMIT_PREFIX | 默认前缀 | | AICOMMIT_PROMPT_FILE | 自定义提示词文件路径 | | AICOMMIT_GITMOJI | 是否启用 gitmoji（true/false） | | AICOMMIT_THINKING | 启用推理模式（true/false） | | AICOMMIT_THINKING_LEVEL | 推理深度（low/medium/high/xhigh/max） | | AICOMMIT_THINKING_MODE | Anthropic 程度机制（budget/effort） | | AICOMMIT_STAGED_ONLY | 仅使用已暂存的变更（true/false） | | AICOMMIT_PROXY | HTTP(S) 代理 URL（回退到 HTTPS_PROXY/HTTP_PROXY） | | AICOMMIT_NO_PROXY | 设为 true 时忽略代理并直连（kill switch） |

注意： 工具也会读取 OPENAI_API_KEY、GEMINI_API_KEY、ANTHROPIC_API_KEY 等标准环境变量作为回退（会输出警告）。建议优先使用 AICOMMIT_* 前缀的版本。

代理（HTTP Proxy）

aicommit 支持通过 HTTP(S) 代理发起 API 请求，适用于公司代理或无法直连 API 的网络环境。

解析优先级（从高到低）：

1. CLI 参数：--proxy <url> / --no-proxy
2. AICOMMIT_* 环境变量：AICOMMIT_PROXY
3. 配置文件：.aicommitrc.json 中的 proxy
4. 标准环境变量（自动回退）：HTTPS_PROXY，其次 HTTP_PROXY

强制直连（kill switch）： --no-proxy、AICOMMIT_NO_PROXY=true 或配置项 noProxy: true 会忽略上述全部代理设置并直连——即使设置了 HTTPS_PROXY。

# 用 AICOMMIT_ 环境变量指定代理
export AICOMMIT_PROXY="http://127.0.0.1:7890"
aicommit

# 自动回退到标准环境变量
export HTTPS_PROXY="http://127.0.0.1:7890"
aicommit

# 命令行临时指定
aicommit --proxy http://127.0.0.1:7890

# 强制直连（忽略已设置的代理）
aicommit --no-proxy

配置文件示例：

{
  "proxy": "http://127.0.0.1:7890",
  "noProxy": false
}

实现说明： 启用代理时，aicommit 会将进程全局的 fetch 替换为 undici 的 fetch 并设置 ProxyAgent，因此 OpenAI、Gemini、Anthropic 三个提供商的请求都会经代理转发。

自定义提示词

使用 -p 指定你自己的系统提示词文件：

aicommit -p ./my-prompt.md

文件内容会完全替换内置的提示词模板。

提供商配置

OpenAI

export AICOMMIT_OPENAI_API_KEY="sk-xxx"
aicommit --provider openai --model gpt-4o

使用 Azure OpenAI 或 DeepSeek 时，设置 baseUrl 和可选的 apiVersion：

export AICOMMIT_OPENAI_BASE_URL="https://your-resource.openai.azure.com/"
export AICOMMIT_AZURE_API_VERSION="2024-02-15-preview"

Gemini

export AICOMMIT_GEMINI_API_KEY="xxx"
aicommit --provider gemini --model gemini-2.0-flash

Anthropic

export AICOMMIT_ANTHROPIC_API_KEY="sk-ant-xxx"
aicommit --provider anthropic --model claude-sonnet-4-20250514

思考控制（Thinking）

--thinking 开启推理模式，--thinking-level 控制思考深度（low/medium/high/xhigh/max，默认 low）。挡位按 provider 映射为各自的原生参数：

| Provider | 映射参数 | low | medium | high | xhigh | max | |---|---|---|---|---|---|---| | Anthropic | thinking.budget_tokens（默认 budget 模式） | 2048 | 8192 | 16384 | 24576 | 32000 | | Gemini | thinkingConfig.thinkingBudget | 2048 | 8192 | 16384 | 24576 | 32768 | | OpenAI | reasoning_effort（同名直传） | low | medium | high | xhigh | max |

注意事项：

• Anthropic 可用 --thinking-mode effort（或 AICOMMIT_THINKING_MODE=effort）改为直传原生 output_config.effort，仅 Opus 4.6+ 等新模型支持，旧模型会返回 400；此时 --thinking-level 不做校验，任意非空字符串原样透传。默认 budget 模式对所有支持 extended thinking 的模型（Sonnet 4.5 起）兼容。
• Gemini 的 max 挡（32768）需要 Gemini 2.5 Pro，Flash 系列上限为 24576（xhigh）。
• OpenAI 的 reasoning_effort 仅推理模型（o 系列、gpt-5 系列等）支持；关闭思考时不会发送该参数。
• 开启思考时，Anthropic 与 OpenAI 均不发送 temperature（两家 API 在推理模式下拒绝或忽略非默认温度）。

开发

cd packages/cli
npm install
npm run build    # 使用 tsup 构建
npm run dev      # 使用 tsx 运行（开发模式）
npm test         # 使用 vitest 运行测试
npm run lint     # 类型检查

致谢

本项目 CLI 工具源自 ai-commit-ext（AI Commit VSCode 扩展），将其核心 AI 提交生成能力提取为独立的命令行工具。

许可证

MIT