Dev Flow CLI

Dev Flow CLI 是一个用于自动化团队 Git 工作流的命令行工具。它旨在帮助开发者遵循“严格私有分支 + 线性历史”的规范，简化日常的 Git 操作，确保代码库的整洁和版本管理的规范性。

📖 背景

本项目基于 团队 Git 工作流规范 构建，核心原则包括：

• 严格私有分支：个人开发分支仅限本人使用。
• 线性历史 (Linear History)：通过 Rebase 和 Squash 策略，杜绝无意义的 Merge Commit。
• 原子提交：一个功能在公共分支上体现为 1 个 Commit。
• 版本闭环：自动化处理版本发布和分支清理。

🚀 安装

NPM 安装

你可以选择全局安装或者安装到项目中。

全局安装（推荐用于个人常用工具）： 这样你可以在任何目录下直接使用 flow 命令。

npm install -g dev-flow-cli

项目内安装（推荐用于团队统一规范）： 将工具安装为项目的开发依赖，确保团队成员使用相同版本的工具。

npm install --save-dev dev-flow-cli

本地开发安装

如果你想参与本项目开发，或者进行源码调试：

1. 克隆仓库到本地：

   git clone https://github.com/007sair/dev-flow-cli.git
   cd dev-flow-cli

2. 安装依赖：

   npm install

3. 链接到全局进行测试：

   npm link

🛠 使用指南

启动方式

1. 全局安装 / 本地开发链接后 直接在终端运行：

flow

2. 项目内安装 (Local Dependency) 在项目根目录下使用 npx 运行：

npx flow

或者在 package.json 的 scripts 中添加：

"scripts": {
  "flow": "flow"
}

然后运行 npm run flow。

交互式菜单

? 请选择当前工作流阶段
> AI 智能提交      (生成 Commit Message)
  特性同步         (个人分支 -> 公共特性分支)
  预发布           (特性分支 -> Release 分支)
  正式发布         (Release -> Master)
  AI 配置          (设置 API Key 等)

常用命令

• flow：启动交互式主菜单。
• flow ai：直接使用 AI 生成并提交代码（等同于 aicommits）。
• flow --help：查看帮助信息和阶段说明。
• flow --version：查看当前版本。

🌊 工作流阶段详解

阶段 0：AI 智能提交 (AI Smart Commit)

目标：利用 AI 自动分析暂存区（Staged）的代码变更，生成符合规范的 Commit Message，减少人工编写成本。

底层能力： 本功能基于 aicommits 封装。

• 如果不带参数运行 flow ai，将进入交互模式，提供“生成并复制”、“生成并提交”等选项。
• 如果带参数运行（如 flow ai -c -g 3），则直接透传参数给 aicommits。

配置指南： 首次使用需要配置 API Key。推荐使用 flow ai setup 进行交互式配置，或参考 aicommits 文档进行详细配置。

关键配置说明：

为了获得最佳体验，建议进行以下配置：

1. 提交格式 (Type)：

   • 如果不配置，默认可能只是简单的描述。
   • 若需生成符合 Conventional Commits 规范（如 feat: add new feature）的消息，必须执行：

     flow ai config set type=conventional

2. 语言设置 (Locale)：

   • 控制生成消息的语言（如中文或英文）。
   • 例如设置为英文：

     flow ai config set locale=en

   • 设置为中文：

     flow ai config set locale=zh

3. 生成数量 (Generate)：

   • 控制每次生成的可选消息数量。
   • 例如每次生成 3 条供选择：

     flow ai config set generate=3

💡 提示：所有 flow ai 开头的配置命令实际上都是在调用 aicommits config。更多高级用法请查阅 aicommits 官方文档。

阶段 1：特性同步 (Feature Sync Pro)

目标：将个人开发分支（如 feat/user-task-01）以线性原子提交的方式合并到公共特性分支（如 feat/1.0.0）。

1. 安全检查：确认当前分支为私有分支，防止误操作多人协作分支。
2. 自动变基 (Rebase)：拉取目标公共分支最新代码，将个人分支变基到最新节点，消除冲突隐患。
3. 智能压缩 (Smart Squash)：
   • 检测到多次提交时，自动使用 git reset --soft 将碎片提交回退到暂存区。
   • 引导用户输入 Commit Message，打包为一个原子提交。
   • 保留个人分支历史，支持后续继续开发（无需删除分支）。
4. 线性合并：切换到公共分支，执行 Fast-forward 合并。
5. 推送与恢复：推送公共分支到远程，并切回个人分支恢复工作状态。

💡 优势：既保证了公共历史的绝对整洁（线性），又避免了传统 Squash Merge 导致的个人分支与公共分支历史断层问题。

阶段 2：预发布 (Pre-Release)

目标：从公共特性分支冻结代码，创建 Release 分支准备发版。

自动化步骤：

1. 同步远程分支信息。
2. 选择来源的公共特性分支（feat/*）。
3. 确定发布版本号（支持 Major/Minor/Patch 自动计算）。
4. 自动创建 release 分支（如 release/v1.0.0）。
5. 将 release 分支推送到远程。

阶段 3：正式发布 (Release Finish)

目标：完成发布流程，生成 Changelog 并打 Tag。

自动化步骤：

1. 获取远程所有 release 分支。
2. 选择要发布的 release 分支。
3. 调用 standard-version 自动生成 CHANGELOG.md 并更新版本号。
4. 自动打 Git Tag。
5. 推送分支和 Tag 到远程。
6. 提示后续操作（如发起 Pull Request 合并到 master）。

📦 依赖库

• aicommits: AI 自动生成提交信息。
• inquirer: 交互式命令行界面。
• execa: 执行 Shell 命令。
• chalk: 终端输出着色。
• semver: 语义化版本处理。
• standard-version: 自动化版本控制和 Changelog 生成。

📄 许可证

ISC