git-aiflow
v1.0.37
Published
🚀 An AI-powered workflow automation tool for effortless Git-based development, combining smart GitLab/GitHub merge & pull request creation with Conan package management.
Maintainers
heisirReadme
AIFlow
🚀 基于 AI 的智能工作流自动化工具，支持 GitLab 合并请求创建和 Conan 包管理。
📖 English | 中文
📋 目录
✨ 功能特性
- 🤖 AI 智能生成：使用 OpenAI API 自动生成提交信息和分支名称
- 🔄 自动化工作流：从代码变更到合并请求一键完成
- 📦 Conan 包管理：专门支持 Conan 包版本更新
- 🌐 多平台 Git 集成：支持 GitHub、GitLab、Gitee 等多个 Git 托管平台
- 📱 企业微信通知：通过 WeCom Webhook 发送通知
- 🎯 智能分支检测：自动识别目标分支
- 🔧 灵活配置：支持多种配置选项和环境变量
- 📝 交互式文件选择：智能文件暂存，支持批量选择和分类显示
- 🎯 仅提交模式：支持仅提交代码变更而不创建合并请求
- 👥 合并请求管理：支持指派人和审查者自动配置
- 🌍 多语言支持：AI 生成内容支持多种语言（中文、英文、日文等）
🛠️ 工具介绍
本项目包含两个主要工具：
1. AIFlow (aiflow)
通用的 Git 自动合并请求工具，适用于任何代码变更。
使用场景：
- 功能开发
- Bug 修复
- 代码重构
- 文档更新
2. AIFlow Conan (aiflow-conan)
专门用于 Conan 包版本更新的自动化工具。
使用场景：
- 依赖包版本更新
- 安全补丁应用
- 包配置优化
📋 环境要求
- Node.js: >= 22.0.0
- npm: >= 11.0.0
- Git: 已配置且能访问远程仓库
- Git 托管平台: GitHub、GitLab、Gitee 等平台的 Personal Access Token
- OpenAI: 有效的 API Key（💡 推荐：查看 免费模型配置指南 获取免费API）
🔧 安装配置
1. 克隆项目
git clone [email protected]:HeiSir2014/git-aiflow.git
cd git-aiflow2. 安装依赖
npm install3. 构建项目
npm run build4. 配置 AIFlow
交互式初始化配置：
# 初始化本地配置
aiflow init
# 或初始化全局配置
aiflow init --global您也可以手动创建配置文件或使用环境变量。
配置优先级（从高到低）：
- 命令行参数
- 本地配置文件（
.aiflow/config.yaml） - 全局配置文件（
~/.config/aiflow/config.yaml或%APPDATA%/aiflow/config.yaml） - 环境变量（
.env文件或系统环境变量）
配置文件示例：
# AIFlow 配置文件
# 配置优先级: 命令行参数 > 本地配置 > 全局配置 > 环境变量
# OpenAI API 配置 - 用于AI驱动的功能
openai:
# OpenAI API 密钥 (必需) - 用于生成提交信息和代码分析
key: sk-your-actual-openai-api-key
# OpenAI API 基础URL (必需) - API请求的端点地址
baseUrl: https://api.openai.com/v1
# OpenAI 模型名称 (必需) - 指定使用的AI模型，如 gpt-3.5-turbo, gpt-4
# 💡 免费模型推荐：查看 docs/free-models.md 获取免费API配置
model: gpt-3.5-turbo
# 模型最大上下文token数 (可选) - 手动指定模型的最大上下文长度，默认为8192
# 常见模型推荐值：gpt-3.5-turbo: 16384, gpt-4: 8192, gpt-4-turbo/4o: 128000
max_context_tokens: 16384
# Git 平台配置 - 支持多个Git托管平台及平台级设置 (推荐)
git_platforms:
# GitHub 平台配置
github.com:
access_token: ghp_xxxxxxxxxxxxxxxxxxxxx
# GitLab 平台配置 - 支持平台级 merge_request 设置
gitlab.example.com:
access_token: glpat-xxxxxxxxxxxxxxxxxxxxx
merge_request:
assignee: username1 # 单个指派人用户名
assignees: # 多个指派人用户名列表
- username1
- username2
reviewers: # 审查者用户名列表
- reviewer1
- reviewer2
# Gitee 平台配置
gitee.com:
access_token: gitee_xxxxxxxxxxxxxxxxxxxxx
# 旧格式兼容性支持 (已弃用，建议使用 git_platforms)
# git_access_tokens:
# github.com: ghp_xxxxxxxxxxxxxxxxxxxxx
# Conan 包管理器配置 - 用于C++包管理和版本更新
conan:
# Conan 远程仓库基础URL (Conan操作时必需) - Conan包仓库的API地址
# remoteBaseUrl: https://conan.example.com
# Conan 远程仓库名称 (可选) - 默认使用的仓库名称，默认为'repo'
remoteRepo: repo
# 企业微信通知配置 - 用于发送操作结果通知
wecom:
# 启用企业微信通知 (可选) - 是否开启通知功能，默认为false
enable: true
# 企业微信机器人Webhook地址 (可选) - 用于发送通知消息的机器人地址
webhook: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your-webhook-key
# Git 合并请求配置 - 控制MR的默认行为
git:
# 压缩提交 (可选) - 合并时是否将多个提交压缩为一个，默认为true
squashCommits: true
# 删除源分支 (可选) - 合并后是否删除源分支，默认为true
removeSourceBranch: true
# AI生成语言 (可选) - AI生成commit message和MR描述的语言，默认为en
# 支持的语言代码: en, zh-CN, zh-TW, ja, ko, fr, de, es, ru, pt, it
generation_lang: en
# 旧格式兼容性支持 (已弃用，建议使用 git_platforms.<hostname>.merge_request)
# merge_request:
# assignee_id: 0
# assignee_ids: []
# reviewer_ids: []🚀 使用方法
AIFlow 工具
用于处理已暂存的 Git 变更：
# 1. 初始化配置（首次使用）
aiflow init # 本地配置
aiflow init --global # 全局配置
# 2. 暂存你的变更（或让工具自动选择）
git add . # 手动暂存所有变更
# 或者直接运行 aiflow，工具会提供交互式文件选择
# 3. 运行自动 MR 工具
aiflow # 完整工作流：暂存 → 提交 → 创建 MR
aiflow --commit-only # 仅提交模式：暂存 → 提交（不创建 MR）
aiflow -co # 仅提交模式（短参数）
# 4. 使用 CLI 参数覆盖配置
aiflow -ok sk-abc123 -gat github.com=ghp-xyz789
# 5. 查看帮助信息
aiflow --config-help # 查看配置选项帮助
aiflow --help # 查看一般帮助交互式文件选择功能： 当没有暂存文件时，工具会自动提供交互式文件选择界面：
📁 Detected file changes:
──────────────────────────────────────────────────
📝 Modified files:
1. src/components/UserProfile.tsx
2. src/api/userService.ts
❓ Untracked files:
3. src/types/user.ts
4. README.md
🎯 File selection options:
• Enter file numbers (e.g., 1,3,5 or 1-5)
• Type "all" to stage all files
• Type "modified" to stage only modified files
• Type "untracked" to stage only untracked files
• Press Enter or type "cancel" to cancel
📋 Select files to stage: 1,3工作流程：
- ✅ 检查暂存的变更（如无则提供交互式文件选择）
- 🎯 自动检测目标分支
- 🤖 AI 生成提交信息和分支名
- 📤 创建分支并推送
- 📋 创建合并请求（支持指派人和审查者）
- 📱 发送企业微信通知
- 📋 复制 MR 信息到剪贴板
AIFlow Conan 工具
用于更新 Conan 包版本：
# 初始化配置（首次使用）
aiflow-conan init # 本地配置
aiflow-conan init --global # 全局配置
# 更新指定包（使用默认仓库）
aiflow-conan <package-name>
# 更新指定包（指定仓库）
aiflow-conan <package-name> <remote-repo>
# 示例
aiflow-conan zterm
aiflow-conan winusb repo
# 使用 CLI 参数覆盖配置
aiflow-conan -ok sk-abc123 -gat gitlab.example.com=glpat-xyz789 zterm
# 查看配置帮助
aiflow-conan --config-help
# 查看帮助信息
aiflow-conan --help前置要求：
- 当前目录包含
conandata.yml - 当前目录包含
conan.win.lock
工作流程：
- 📦 从远程获取最新包信息
- 📝 更新本地配置文件
- 🎯 检测目标分支
- 🤖 AI 生成提交信息
- 📤 创建分支并推送
- 📋 创建 GitLab 合并请求
- 📱 发送企业微信通知
⚙️ 配置说明
配置方式
AIFlow 支持多种配置方式，优先级从高到低如下：
- 命令行参数（最高优先级）
- 本地配置文件（
.aiflow/config.yaml） - 全局配置文件（
~/.config/aiflow/config.yaml或%APPDATA%/aiflow/config.yaml） - 环境变量（最低优先级）
交互式配置
# 初始化本地配置
aiflow init
# 初始化全局配置
aiflow init --globalCLI 参数
| 短参数 | 长参数 | 描述 | 必需/可选 |
|--------|--------|------|-----------|
| -ok | --openai-key | OpenAI API 密钥 | 必需 |
| -obu | --openai-base-url | OpenAI API 基础 URL | 必需 |
| -om | --openai-model | OpenAI 模型名称 | 必需 |
| -omct | --openai-max-context-tokens | 模型最大上下文token数 | 可选 |
| -gat | --git-access-token | Git 访问令牌 (格式: 主机名=令牌) | 必需 |
| -crbu | --conan-remote-base-url | Conan 仓库 API URL | Conan操作必需 |
| -crr | --conan-remote-repo | Conan 仓库名称 | 可选 |
| -ww | --wecom-webhook | 企业微信 webhook URL | 可选 |
| -we | --wecom-enable | 启用企业微信通知 | 可选 |
| -sc | --squash-commits | 压缩提交 | 可选 |
| -rsb | --remove-source-branch | 删除源分支 | 可选 |
| -ggl | --git-generation-lang | AI 生成语言 | 可选 |
| -co | --commit-only | 仅提交模式 | 可选 |
| -cmo | --commit-only | 仅提交模式 | 可选 |
| -mrai | --merge-request-assignee-id | 指派人用户ID | 可选 |
| -mrais | --merge-request-assignee-ids | 指派人用户ID列表 | 可选 |
| -mrris | --merge-request-reviewer-ids | 审查者用户ID列表 | 可选 |
环境变量（兼容性支持）
| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| OPENAI_KEY | OpenAI API 密钥 | - |
| OPENAI_BASE_URL | OpenAI API 基础 URL | https://api.openai.com/v1 |
| OPENAI_MODEL | OpenAI 模型名称 | gpt-3.5-turbo |
| OPENAI_MAX_CONTEXT_TOKENS | 模型最大上下文token数 | 8192 |
| GIT_ACCESS_TOKEN_<HOST> | Git 访问令牌 (如: GIT_ACCESS_TOKEN_GITHUB_COM) | - |
| CONAN_REMOTE_BASE_URL | Conan 远程服务器 URL | - |
| CONAN_REMOTE_REPO | Conan 远程仓库名 | repo |
| WECOM_WEBHOOK | 企业微信 Webhook URL | - |
| WECOM_ENABLE | 启用企业微信通知 | false |
| SQUASH_COMMITS | 是否压缩提交 | true |
| REMOVE_SOURCE_BRANCH | 合并后删除源分支 | true |
| GIT_GENERATION_LANG | AI 生成语言 | en |
| MERGE_REQUEST_ASSIGNEE_ID | 指派人用户ID | - |
| MERGE_REQUEST_ASSIGNEE_IDS | 指派人用户ID列表 | - |
| MERGE_REQUEST_REVIEWER_IDS | 审查者用户ID列表 | - |
Git 平台 Token 权限要求
GitLab Personal Access Token 权限：
- ✅
api- 完整 API 访问 - ✅
read_user- 读取用户信息 - ✅
read_repository- 读取仓库信息 - ✅
write_repository- 写入仓库信息
GitHub Personal Access Token 权限：
- ✅
repo- 完整仓库访问权限 - ✅
workflow- 工作流访问权限（如需要）
Gitee Personal Access Token 权限：
- ✅
projects- 项目权限 - ✅
pull_requests- 拉取请求权限
🔄 工作流程
自动检测功能
工具会自动检测以下信息：
Git 平台项目信息
- 从
git remoteURL 解析项目信息 - 支持 HTTP 和 SSH URL 格式
- 自动检测 GitHub、GitLab、Gitee 等平台
- 智能 API 端点探测（支持企业自部署实例）
- 从
目标分支检测
- 优先级：
main>master>develop - 检查远程分支是否存在
- 如果当前分支是默认分支之一，则使用当前分支
- 优先级：
分支命名规则
{git-user}/{ai-branch-name}-{date}git-user: Git 用户名ai-branch-name: AI 生成并清理的分支名date: 格式为 YYYYMMDD
AI 生成规则
工具使用 OpenAI API 分析代码差异，生成：
提交信息
- 遵循 Conventional Commits 规范
- 包含变更摘要和详细描述
- 自动识别变更类型（feat/fix/chore/docs 等）
分支名称
- 简洁明了的英文描述
- 自动清理特殊字符
- 符合 Git 分支命名规范
📚 使用案例
案例 1：日常功能开发
# 开发新功能
git add src/components/UserProfile.tsx
git add src/api/userService.ts
# 使用 AIFlow 自动化处理
aiflow
# 输出示例：
# ✅ 生成提交信息: feat(user): add user profile component with API integration
# ✅ 生成分支名称: feat/user-profile-component
# 🎉 合并请求创建: https://gitlab.com/project/-/merge_requests/123案例 2：仅提交模式
# 仅提交代码变更，不创建 MR
aiflow --commit-only
# 输出示例：
# ✅ 生成提交信息: fix(auth): resolve login validation issue
# ✅ 成功提交变更
# 📝 提交信息: fix(auth): resolve login validation issue案例 3：交互式文件选择
# 直接运行，让工具自动选择文件
aiflow
# 工具会显示：
# 📁 Detected file changes:
# 📝 Modified files:
# 1. src/auth.ts
# 2. src/types.ts
# ❓ Untracked files:
# 3. README.md
#
# 📋 Select files to stage: 1,3案例 4：C++ 包更新
# 更新 Conan 包
aiflow-conan zterm
# 自动流程：
# 📦 检测最新版本: zterm/1.0.0.26
# 📝 更新配置文件
# 🤖 生成提交信息: chore: update zterm package to version 1.0.0.26
# 📋 创建合并请求
# 📱 发送团队通知案例 5：团队协作配置
# 配置合并请求指派和审查者 (使用用户ID，旧格式)
aiflow -mrai 123 -mrris 456,789
# 推荐：在配置文件中使用用户名配置 (新格式)
git_platforms:
gitlab.example.com:
access_token: glpat-xxxxxxxxxxxxxxxxxxxxx
merge_request:
assignee: username1
assignees:
- username1
- username2
reviewers:
- reviewer1
- reviewer2🎯 最佳实践
1. 配置管理
- 本地项目配置：项目特定设置放在
.aiflow/config.yaml - 全局配置：通用设置放在全局配置文件
- 敏感信息：使用环境变量存储 API 密钥
2. 团队协作
- 统一配置：团队使用相同的 OpenAI 模型配置
- 分支策略：配置合适的分支保护规则
- 通知设置：配置企业微信群组通知
3. 安全考虑
- 访问令牌：定期轮换 Git 平台访问令牌
- 权限控制：使用最小权限原则配置令牌
- 敏感数据：不要在配置文件中硬编码密钥
4. 工作流优化
- 提交频率：建议小批量、频繁提交
- 分支命名：让 AI 自动生成语义化分支名
- 代码审查：配置自动指派审查者
🔍 故障排除
常见问题
1. "No staged changes found"
# 解决方案：暂存你的变更
git add .2. "Missing required configuration"
# 解决方案：初始化配置或检查配置文件
aiflow init
# 或检查现有配置
aiflow --config-help3. "Could not determine target branch"
# 解决方案：检查远程分支
git branch -r
git remote -v4. "Git API error"
# 解决方案：验证访问令牌权限
# GitLab:
curl -H "PRIVATE-TOKEN: your-token" https://gitlab.com/api/v4/user
# GitHub:
curl -H "Authorization: Bearer your-token" https://api.github.com/user5. Conan 包更新失败
# 检查必需文件
ls -la conandata.yml conan.win.lock
# 检查 Conan 服务器连接
curl http://your-conan-server.com/v1/ping6. 交互式文件选择不工作
# 确保在 Git 仓库中运行
git status
# 检查是否有文件变更
git diff --name-only7. 合并请求指派失败
# 检查用户ID是否正确
# GitLab: 在项目设置中查看用户ID
# GitHub: 使用用户名而不是ID
# 验证访问令牌权限
curl -H "PRIVATE-TOKEN: your-token" https://gitlab.com/api/v4/projects/PROJECT_ID/members8. Windows PowerShell 执行策略错误
问题描述：
在 Windows 系统中运行 aiflow 命令时可能出现以下错误：
aiflow : 无法加载文件 C:\Users\user\AppData\Roaming\npm\aiflow.ps1，因为在此系统上禁止运行脚本。
有关详细信息，请参阅 https://go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。
所在位置 行:1 字符: 1
+ aiflow
+ ~~~~~~
+ CategoryInfo : SecurityError: (:) []，PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess原因分析： Windows PowerShell 默认的执行策略限制了脚本的运行，这是一个安全机制，防止恶意脚本执行。
解决方案：
方法一：修改当前用户执行策略（推荐）
# 以管理员身份运行 PowerShell，然后执行：
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force方法二：临时绕过执行策略
# 每次运行时临时绕过（不推荐）
PowerShell -ExecutionPolicy Bypass -Command "aiflow"方法三：使用 npx 直接运行
# 如果上述方法都不行，可以使用 npx
npx aiflow验证修复：
# 检查当前执行策略
Get-ExecutionPolicy -List
# 应该看到 CurrentUser 的策略为 RemoteSigned安全说明：
RemoteSigned策略要求从互联网下载的脚本必须由受信任的发布者签名- 本地创建的脚本可以运行而无需签名
- 这是一个相对安全的设置，比完全开放的
Unrestricted策略更安全
日志系统
AIFlow 使用基于 Winston 的企业级日志系统：
日志位置：
- Windows:
%APPDATA%\aiflow\logs\ - macOS:
~/Library/Application Support/aiflow/logs/ - Linux:
~/.config/aiflow/logs/
日志文件：
aiflow.log- 所有级别的日志error.log- 仅错误级别的日志
日志功能：
- 📁 按文件大小自动滚动（10MB/文件，保留5个文件）
- 🕐 包含时间戳、上下文标记和详细元数据
- 📊 结构化 JSON 格式便于分析
- 🏷️ 服务级别的上下文标记（Shell、GitService、HttpClient 等）
调试模式
查看实时日志：
# 查看所有日志
tail -f ~/.config/aiflow/logs/aiflow.log
# 仅查看错误日志
tail -f ~/.config/aiflow/logs/error.log
# Windows 用户
Get-Content -Path "$env:APPDATA\aiflow\logs\aiflow.log" -Wait日志分析
工具会输出详细的执行步骤：
🚀 AIFlow Tool
📁 Working directory: /path/to/project
⏰ Started at: 2024-01-01T12:00:00.000Z
──────────────────────────────────────────────────
✅ Environment validation passed
🎯 Target branch: main
🤖 Generating commit message and branch name...
✅ Generated commit message: feat: add new feature
✅ Generated branch name: username/add-new-feature-20240101
📤 Creating branch and pushing changes...
📋 Creating Merge Request...
🎉 Merge Request created: https://github.com/user/project/pull/123
📢 Sending notification...
📢 Notification sent via WeCom webhook.
✅ AIFlow workflow completed successfully!👨💻 开发说明
项目结构
src/
├── services/ # 核心服务
│ ├── git-service.ts # Git 操作
│ ├── git-platform-service.ts # Git 平台抽象接口
│ ├── gitlab-platform-service.ts # GitLab 平台实现
│ ├── github-platform-service.ts # GitHub 平台实现
│ ├── openai-service.ts # OpenAI API
│ ├── conan-service.ts # Conan API
│ ├── wecom-notifier.ts # 企业微信通知
│ ├── conandata-service.ts # Conan 数据文件操作
│ ├── conanlock-service.ts # Conan 锁文件操作
│ └── file-updater-service.ts # 文件更新操作
├── utils/ # 工具函数
│ └── string-util.ts # 字符串处理
├── http/ # HTTP 客户端
│ └── http-client.ts
├── test/ # 测试文件
├── config.ts # 配置管理
├── logger.ts # 日志系统
├── aiflow-app.ts # 通用 MR 工具
├── aiflow-conan-app.ts # Conan 更新工具
├── shell.ts # Shell 命令执行
└── index.ts # 入口文件开发命令
# 安装依赖
npm install
# 开发模式（监听文件变化）
npm run dev
# 构建项目
npm run build
# 运行测试
npm test
# 代码检查
npm run lint
# 格式化代码
npm run format添加新功能
- 在相应的 service 中添加新方法
- 更新主应用类的逻辑
- 添加相应的测试
- 更新文档
测试
# 运行所有测试
npm test
# 运行特定测试
npm test -- --grep "GitService"
# 覆盖率报告
npm run test:coverage📄 许可证
本项目采用 MIT 许可证。详见 LICENSE 文件。
🤝 贡献
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交变更 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
📚 扩展资源
📞 支持
如有问题或建议，请：
注意：使用前请确保已正确配置所有必需的环境变量，并且具有相应服务的访问权限。