dev-flow-cli

v1.2.0

Published

21 days ago

CLI tool to automate development workflow

0High
0Medium
0Low

sair1011

git workflow cli automation dev-flow

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

本地开发安装

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

克隆仓库到本地：

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

安装依赖：
```
npm install
```
链接到全局进行测试：
```
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 文档进行详细配置。

关键配置说明：

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

提交格式 (Type)：
- 如果不配置，默认可能只是简单的描述。
- 若需生成符合 Conventional Commits 规范（如 feat: add new feature）的消息，必须执行：
```
flow ai config set type=conventional
```
语言设置 (Locale)：
- 控制生成消息的语言（如中文或英文）。
- 例如设置为英文：
```
flow ai config set locale=en
```
- 设置为中文：
```
flow ai config set locale=zh
```
生成数量 (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）。

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

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

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

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

自动化步骤：

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

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

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