git-ai-cli

🤖 AI-Powered Git Assistant: Commit, Context & Report

🚀 DeepSeek 深度优化 | 🏠 Ollama 隐私优先 | 🧠 分支感知 | 🛡️ Copilot 守护 | 📊 智能周报

English • 快速开始 • 核心特性 • Git Flow • 智能周报

---

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

---

Made with ❤️ by git-ai team
_{🤖 Generated by git-ai 🚀}