aicommit

AI 驱动的 commit message 生成器。比 aicommits / opencommit 多做了三件事：

1. 读项目自身规范 —— 自动加载 commitlint 配置 / COMMIT_CONVENTION.md / commit-convention.json 等项目级约定，也读取 CLAUDE.md / AGENTS.md / .cursorrules 等通用约定文档
2. 生成 → commitlint 自检 → 失败重试 —— 不通过校验的 message 永远不会落到你手上
3. 基于 AI SDK —— 一份代码同时支持 OpenAI 兼容（DeepSeek/Qwen/Moonshot/Groq/Azure/ollama 等）和 Anthropic 原生 API，切换只改配置

安装

cd scripts/aicommit
pnpm install
pnpm link --global   # 暴露 `aicommit` 命令到全局

这是一个独立 package，不会进入 funhub 的 pnpm workspace，不污染主项目依赖。

配置

第一次使用必须配置 provider / baseUrl / apiKey / model。配置存在 ~/.aicommitrc.json（自动设为 0600）。

OpenAI 兼容（DeepSeek 示例）

aicommit config set provider openai
aicommit config set baseUrl https://api.deepseek.com/v1
aicommit config set apiKey  sk-xxxxxxxx
aicommit config set model   deepseek-chat

OpenAI 官方

aicommit config set provider openai
aicommit config set baseUrl https://api.openai.com/v1
aicommit config set apiKey  sk-xxxxxxxx
aicommit config set model   gpt-4o-mini

Anthropic 原生

aicommit config set provider anthropic
aicommit config set apiKey   sk-ant-xxxx
aicommit config set model    claude-3-5-sonnet-latest

其他可选项

aicommit config set language     zh        # 'zh' | 'en'，默认 zh
aicommit config set maxDiffChars 12000     # 超长 diff 的截断阈值
aicommit config show                        # 查看（apiKey 已遮蔽）
aicommit config path                        # 打印配置文件路径

项目级 Commit 约定

除了 commitlint 配置之外，aicommit 还支持在项目根目录放置专用的 commit 约定文件。无需安装 commitlint，用更轻量的方式定义你的 commit 规范。

快速生成模板

aicommit init               # 生成 COMMIT_CONVENTION.md（Markdown 格式）
aicommit init --format json  # 生成 commit-convention.json（JSON 格式）

方式一：Markdown 自然语言（COMMIT_CONVENTION.md 或 .aicommit.md）

用自然语言描述你的 commit 规范，AI 会直接理解并遵守：

# Commit Convention

## 规则
- type 使用英文，subject 使用中文
- scope 从以下模块中选取：auth, home, api, shared
- 涉及破坏性变更时必须在 footer 加 BREAKING CHANGE

## 示例
feat(auth): 添加微信扫码登录
fix(api): 修复分页查询越界问题

方式二：JSON 结构化（commit-convention.json 或 .aicommit.rules.json）

用 JSON 精确定义规则，字段会直接映射为 prompt 约束：

{
  "types": ["feat", "fix", "docs", "style", "refactor", "perf", "test", "chore"],
  "scopes": ["auth", "home", "api", "shared"],
  "headerMaxLength": 80,
  "scopeRequired": false,
  "rules": [
    "subject 使用中文",
    "body 解释「为什么」而不是「做了什么」"
  ],
  "examples": [
    "feat(auth): 添加微信扫码登录",
    "fix(api): 修复分页查询越界问题"
  ]
}

优先级

当多个配置来源共存时，优先级为：commitlint 配置 > commit-convention.json > 默认值。Markdown 约定文件的内容会独立注入 prompt，不与结构化规则冲突。

使用

# 1. 暂存改动
git add -p

# 2. 生成 commit message（默认只打印不提交）
aicommit

# 3. 直接生成并提交
aicommit -y

# 4. 生成后进编辑器再改
aicommit -e

# 临时切换模型 / provider
aicommit --model gpt-4o
aicommit --provider anthropic --model claude-3-5-sonnet-latest

# 关闭 commitlint 自检
aicommit --no-lint

工作原理

git diff --cached        ┐
git diff --stat          │
git log -n 15            ├─→  prompt（system 含规则/约定/示例，user 含本次 diff）
COMMIT_CONVENTION.md     │                   │
commit-convention.json   │                   │
CLAUDE.md / AGENTS.md    │                   ▼
commitlint config        ┘            AI SDK generateText
                                      │
                                      ▼
                            commitlint 自检
                                      │
                          ┌───────────┴───────────┐
                       valid                    invalid
                          │                       │
                          ▼               把错误回喂模型重试 (≤2 次)
                  打印 / 提交

项目结构

src/
├── cli.ts        # commander 入口
├── config.ts     # ~/.aicommitrc.json 读写
├── git.ts        # git 命令封装
├── context.ts    # 读 COMMIT_CONVENTION.md / commit-convention.json / CLAUDE.md / commitlint
├── prompt.ts     # system + user prompt 拼装（含 ticket 提取、diff 智能裁剪）
├── llm.ts        # AI SDK 调用
└── lint.ts       # @commitlint/lint 自检

隐私说明

• 只发送已 git add 的 diff，不会读未暂存内容
• diff 与项目约定文档会发送到你配置的 baseUrl，请确保该端点符合你/团队的合规要求
• apiKey 存在 ~/.aicommitrc.json 并设为 0600