@dongowu/git-ai-cli

v2.0.5

Published

a month ago

Generate git commit messages using AI - Rust Edition

Downloads

183

0High
0Medium
0Low

lab-jy

git ai commit cli openai deepseek ollama rust style-learning git-hook productivity

git-ai-cli 不仅仅是一个 Commit Message 生成器，它是你的全能 AI 开发助手。它能读懂你的代码 Diff，看懂你的分支意图，甚至帮你写好周报。

🦀 Rust 版说明（当前默认发布）

从 2.x 开始，git-ai-cli 默认发布 Rust 版（更快、单文件二进制）。推荐通过 npm 安装（会自动下载对应平台的二进制）：

npm install -g @dongowu/git-ai-cli

Rust 版目前包含 agent-lite（影响分析/符号搜索），增强安全/性能分析功能仍在迁移中。

如需旧版 TypeScript（1.x）请自行固定版本号安装。

🚀 快速开始

# 1. 安装
npm install -g @dongowu/git-ai-cli

# 2. 初始化 (自动探测本地模型或配置 API)
git-ai config

# 3. 使用
git add .
git-ai

✨ 核心特性

1. 🇨🇳 极致本土化 & 隐私优先

DeepSeek/Qwen 深度优化：内置专家级提示词，针对中文代码语境优化，不只是翻译 Diff，而是理解“意图”。
Ollama 零配置：自动探测本地运行的 Ollama 模型（如 llama3, deepseek-coder），无需手动输入模型名。数据完全不出网，绝对安全。

2. 🧠 上下文感知 (Context Aware)

风格学习：自动分析您最近的 10 次提交记录，模仿您的语气、格式（如 Emoji 使用习惯）和语言风格。
分支感知：读取当前分支名（如 feat/user-login, fix/JIRA-123），生成包含 Issue ID 或功能模块的规范提交信息。

3. 🤖 Agent 智能体

从单纯的"文本生成"进化为"智能代码专家"。

Smart Diff: 遇到超大变更不再瞎编。Agent 会自动分析统计数据，只读取核心文件的代码，大幅降低 Token 限制带来的影响。
影响分析 (Impact Analysis): 修改了核心 API？Agent 会主动搜索整个代码库（git grep），检查调用方是否同步修改，并在 Commit Body 中提示潜在风险。
Git Flow 护航: 在 release/* 或 hotfix/* 分支上自动开启深度检查，守卫生产环境。

4. 🛡️ GitHub Copilot CLI 智能守护 (New)

双层 AI 架构：专业 Commit 生成 + 深度代码分析。

代码影响分析: 使用 GitHub Copilot CLI 深度分析代码变更的影响范围和潜在风险
风险检测: 自动识别破坏性变更、潜在 Bug 和安全隐患
测试建议: 智能推荐需要测试的场景和用例
受影响区域: 分析哪些模块和文件可能受到影响
可选启用: 通过 --copilot 参数按需启用，不强制依赖

5. ⚙️ 工程化配置 (Project Config)

项目级配置：支持在项目根目录创建 .git-ai.json，团队统一共享模型和 Prompt 配置（优先级 > 全局配置）。
智能忽略：支持 .git-aiignore 文件，排除自动生成文件（如 package-lock.json）或大文件，节省 Token 并提高准确性。

6. 🪝 无感集成 (Git Hook)

零打扰：安装 Hook 后，只需执行 git commit（不带 -m），AI 自动填充消息并打开编辑器。
兼容性：完美兼容现有 Git 工作流，支持 git commit --no-verify 跳过。

7. 📊 智能周报 (AI Report)

一键生成：git-ai report 自动分析你最近的代码提交。
价值导向：将零碎的 Commit 转化为结构化的"核心产出"、"问题修复"和"技术优化"报告。

⚙️ 高级配置

项目级配置文件 `.git-ai.json`

在项目根目录创建此文件，可覆盖全局设置，方便团队统一规范：

{
  "provider": "deepseek",
  "baseUrl": "https://api.deepseek.com/v1",
  "model": "deepseek-reasoner",
  "agentModel": "deepseek-chat",
  "locale": "zh",
  "enableFooter": true
}

说明：

model：基础模式生成提交信息的模型
agentModel：Agent 模式（-a）专用模型（建议选择稳定支持 tools 的模型；DeepSeek 常用 deepseek-chat）
locale：仅支持 zh / en
apiKey 建议通过环境变量或全局配置设置，不要提交到仓库

命令行配置（可脚本化）

# 查看当前生效配置（包含环境变量覆盖）
git-ai config get --json

# 设置全局配置（写入全局配置文件）
git-ai config set model deepseek-chat

# 设置项目级配置（写入当前项目 .git-ai.json）
git-ai config set agentModel deepseek-chat --local

# 查看可配置项 / 环境变量覆盖
git-ai config describe

环境变量（CI/脚本）

常用环境变量（优先级高于配置文件）：

GIT_AI_PROVIDER / GIT_AI_BASE_URL / GIT_AI_MODEL / GIT_AI_AGENT_MODEL
GIT_AI_API_KEY（也支持 DEEPSEEK_API_KEY、OPENAI_API_KEY）
GIT_AI_TIMEOUT_MS（请求超时，默认 120000）
GIT_AI_MAX_DIFF_CHARS（控制 diff 截断长度）
GIT_AI_MAX_OUTPUT_TOKENS（控制输出 token 上限）
GIT_AI_DEBUG=1（打印更详细错误）

OpenCommit 兼容变量（可直接复用）：

OCO_AI_PROVIDER / OCO_MODEL / OCO_API_KEY
OCO_TOKENS_MAX_INPUT / OCO_TOKENS_MAX_OUTPUT

忽略文件 `.git-aiignore`

在项目根目录创建，用于排除不想发送给 AI 的文件（语法同 .gitignore）：

package-lock.json
dist/
*.min.js

同时兼容 OpenCommit 的 .opencommitignore（两者都会读取）。

常见问题

1) 401 / API Key 无效

先看生效配置：git-ai config get --json --local
再检查环境变量是否覆盖：GIT_AI_API_KEY / DEEPSEEK_API_KEY / OPENAI_API_KEY / OCO_API_KEY

2) Diff 被截断

通过 .git-aiignore / .opencommitignore 忽略大文件（lock/build/map）
或设置 GIT_AI_MAX_DIFF_CHARS（也兼容 OCO_TOKENS_MAX_INPUT）

3) Agent 自动回退到基础模式

设置 GIT_AI_DEBUG=1 可以看到回退原因（超时/限流/鉴权等）

📖 使用方式

场景一：交互式提交 (Interactive)

git add .
git-ai

场景二：Copilot 智能守护模式 🌟 推荐

git add .
git-ai --copilot
# 1. 使用 DeepSeek/Ollama 生成专业 commit message
# 2. GitHub Copilot CLI 深度分析代码影响
# 3. 展示风险提示和测试建议
# 4. 确认后提交

输出示例：

✨ Generated commit message(s):

feat(auth): implement JWT token refresh mechanism

📊 Impact Analysis:
   Modified authentication flow to support automatic token refresh

⚠️  Potential Risks:
   • Breaking change: Old tokens will be invalidated
   • Session management logic needs update

🔗 Affected Areas:
   • Login component
   • API middleware
   • User session store

✅ Test Recommendations:
   • Test token expiration handling
   • Verify refresh token rotation
   • Check concurrent request handling

场景三：Git Flow 最佳实践 (Hook)

这是最流畅的体验。你不需要改变任何习惯，只需一次安装：

# 在当前项目安装
git-ai hook install

# 或者全局安装（所有项目生效）
git-ai hook install --global

之后只需：

git checkout -b feature/awesome-login
# ... 写代码 ...
git add .
git commit  # ✨ AI 自动帮你写好了 "feat(login): implement awesome login logic"

场景四：生成周报 (Report)

每逢周五不想写周报？

# 生成本周日报/周报
git-ai report

# 生成最近 30 天的汇报
git-ai report --days 30

# 从“上次 tag”到当前代码生成版本功能描述
git-ai report --from-last-tag

# 指定 tag 范围生成发布说明（例如 v1.0.21 -> v2.0.0）
git-ai report --from-tag v1.0.21 --to-ref v2.0.0

🛠 命令速查

| 命令 | 别名 | 说明 | |------|------|------| | git-ai config | config | 初始化配置（设置模型、Key、语言） | | git-ai config get | | 查看当前生效配置（支持 --json / --local） | | git-ai config set <key> <value> | | 设置配置（支持 --local / --json） | | git-ai config describe | | 查看可配置项与环境变量覆盖 | | git-ai | | 交互式生成并提交 | | git-ai --copilot | | Copilot 守护模式 (代码影响分析 & 风险检测) | | git-ai -a | | Agent 模式 (深度分析 & 影响检查) | | git-ai -a --copilot | | 终极模式 (Agent + Copilot 双重保障) | | git-ai -y | | 跳过确认直接提交 | | git-ai -n 3 | | 生成 3 条候选消息 | | git-ai -l en | | 强制输出语言（en/zh） | | git-ai hook install | | 安装 Git Hook (支持 --global) | | git-ai hook remove | | 移除 Git Hook | | git-ai report | | 生成 AI 周报 / 版本说明 (支持 --days / --from-last-tag / --from-tag --to-ref) | | git-ai msg | | 仅输出消息（供脚本调用） |

🤖 支持的模型

| 类型 | 服务商 | 优势 | 配置方式 | |------|--------|------|----------| | 本地隐私 | Ollama | 免费、离线、绝对隐私 | git-ai config 自动探测 | | | LM Studio | 兼容性好 | 手动输入 URL | | 国内高速 | DeepSeek | 性价比之王，代码能力极强 | API Key | | | 通义千问 | 阿里生态，长文本能力强 | API Key | | | 智谱/Moonshot | 国内主流模型 | API Key | | 国际通用 | OpenAI | GPT-4o 基准能力 | API Key |

📄 License

Apache 2.0