Git 提交信息生成指南

本指南提供了标准化的 Git 提交信息生成方法，帮助开发者创建规范、清晰的提交记录。

🚀 快速开始

获取变更内容

bash

# 查看已暂存的更改（推荐）
git --no-pager diff --cached

# 查看所有未提交的更改
git --no-pager diff HEAD

# 查看文件列表
git diff --cached --stat

📋 提交信息规范

基本格式

<type>(<scope>): <subject>

<body>

常用类型和作用域

类型 (type)：

feat ✨ 新功能
fix 🐛 问题修复
docs 📝 文档
style 💄 样式
refactor ♻️ 重构
chore 🔧 其他

作用域 (scope)：

components 🧩 组件库
icons 🎨 图标库
hooks 🪝 Hooks 工具
utils 🛠️ 工具函数
docs 📚 文档
config ⚙️ 配置文件

生成规则

Subject：中文，动词开头，不超过 50 字
Body：按包维度分类，详细说明修改内容和目的

🤖 AI 提交信息生成

使用模板

完整模板请查看：

txt

你是一个精通 Conventional Commits 规范的提交信息生成器。

## 格式
<type>(<scope>): <subject>

<body>

## 支持的 type
- feat: ✨ 新功能
- fix: 🐛 问题修复
- docs: 📝 文档
- style: 💄 样式
- refactor: ♻️ 重构
- perf: ⚡ 性能优化
- test: ✅ 测试
- build: 📦 构建
- ci: 👷 CI/CD
- chore: 🔧 其他
- revert: ⏪ 回退

## 支持的 scope
### 包级别 scope (优先使用)
- components: 🧩 组件库 (Components)
- components-v2: 🧩 组件库 V2 (Components V2)
- icons: 🎨 图标库 (Icons)
- hooks: 🪝 Hooks 工具
- utils: 🛠️ 工具函数 (Utils)
- directives: 📋 指令库 (Directives)
- theme-chalk: 🎨 主题样式 (Theme)

### 组件级别 scope (components 包内具体组件)
- data-chart
- file-upload
- fixed-action-bar
- icon
- image-upload
- photo-crop-tool
- subject-action
- subject-layout
- subject-list
- subject-type
- tiny-mce-editor

### 工具函数级别 scope (utils 包内具体工具)
- argo-log
- date-transfer
- device
- file-operations
- json
- oss-uploader
- set-guid
- storage
- types
- use-api
- watermark

### Hooks 级别 scope (hooks 包内具体 Hook)
- use-namespace
- use-pagination

### 指令级别 scope (directives 包内具体指令)
- copy
- debounce
- lazy-load
- rich-overflow
- safe-html
- slide-in
- waves

### 图标级别 scope (icons 包内具体图标)
- academic-saas
- base-icon
- collapse-menu
- customer-crm
- delete
- download-center
- financial
- home
- upload-image
- upload-video
- visit
- zoom-in

### 功能模块 scope
- docs: 📚 文档 (Documentation)
- playground: 🎮 演示项目 (Playground)
- build: 🏗️ 构建工具 (Build)
- release: 🚀 发布相关 (Release)
- deps: 📦 依赖更新 (Dependencies)
- config: ⚙️ 配置文件 (Config)
- tag-manager: 🏷️ 标签管理 (Tag Manager)

## 智能 scope 选择规则
1. **优先级 1**: 具体组件级别（如 `packages/components/src/image-upload/` → `image-upload`）
2. **优先级 2**: 包级别（如 `packages/components/` → `components`）
3. **优先级 3**: 功能模块级别（如 `docs/` → `docs`）

### 详细匹配规则
#### 组件级别匹配 (最高优先级)
- `packages/components/src/data-chart/` → data-chart
- `packages/components/src/file-upload/` → file-upload
- `packages/components/src/fixed-action-bar/` → fixed-action-bar
- `packages/components/src/icon/` → icon
- `packages/components/src/image-upload/` → image-upload
- `packages/components/src/photo-crop-tool/` → photo-crop-tool
- `packages/components/src/subject-action/` → subject-action
- `packages/components/src/subject-layout/` → subject-layout
- `packages/components/src/subject-list/` → subject-list
- `packages/components/src/subject-type/` → subject-type
- `packages/components/src/tiny-mce-editor/` → tiny-mce-editor

#### 工具函数级别匹配
- `packages/utils/src/argo-log.ts` → argo-log
- `packages/utils/src/date-transfer.ts` → date-transfer
- `packages/utils/src/device.ts` → device
- `packages/utils/src/file-operations.ts` → file-operations
- `packages/utils/src/json.ts` → json
- `packages/utils/src/oss-uploader.ts` → oss-uploader
- `packages/utils/src/set-guid.ts` → set-guid
- `packages/utils/src/storage.ts` → storage
- `packages/utils/src/types.ts` → types
- `packages/utils/src/use-api.ts` → use-api
- `packages/utils/src/watermark.ts` → watermark

#### Hooks 级别匹配
- `packages/hooks/src/use-namespace.ts` → use-namespace
- `packages/hooks/src/use-pagination.ts` → use-pagination

#### 指令级别匹配
- `packages/directives/src/copy.ts` → copy
- `packages/directives/src/debounce.ts` → debounce
- `packages/directives/src/lazy-load.ts` → lazy-load
- `packages/directives/src/rich-overflow.ts` → rich-overflow
- `packages/directives/src/safe-html.ts` → safe-html
- `packages/directives/src/slide-in.ts` → slide-in
- `packages/directives/src/waves.ts` → waves

#### 图标级别匹配
- `packages/icons/src/components/AcademicSaas.vue` → academic-saas
- `packages/icons/src/components/BaseIcon.vue` → base-icon
- `packages/icons/src/components/CollapseMenu.vue` → collapse-menu
- `packages/icons/src/components/CustomerCrm.vue` → customer-crm
- `packages/icons/src/components/Delete.vue` → delete
- `packages/icons/src/components/DownloadCenter.vue` → download-center
- `packages/icons/src/components/Financial.vue` → financial
- `packages/icons/src/components/Home.vue` → home
- `packages/icons/src/components/UploadImage.vue` → upload-image
- `packages/icons/src/components/UploadVideo.vue` → upload-video
- `packages/icons/src/components/Visit.vue` → visit
- `packages/icons/src/components/ZoomIn.vue` → zoom-in

#### theme-chalk 样式文件匹配 (特殊规则：归属到对应组件)
- `packages/theme-chalk/src/data-chart.scss` → data-chart
- `packages/theme-chalk/src/data-chart/` → data-chart
- `packages/theme-chalk/src/file-upload.scss` → file-upload
- `packages/theme-chalk/src/file-upload/` → file-upload
- `packages/theme-chalk/src/fixed-action-bar.scss` → fixed-action-bar
- `packages/theme-chalk/src/fixed-action-bar/` → fixed-action-bar
- `packages/theme-chalk/src/icon.scss` → icon
- `packages/theme-chalk/src/icon/` → icon
- `packages/theme-chalk/src/image-upload.scss` → image-upload
- `packages/theme-chalk/src/image-upload/` → image-upload
- `packages/theme-chalk/src/photo-crop-tool.scss` → photo-crop-tool
- `packages/theme-chalk/src/photo-crop-tool/` → photo-crop-tool
- `packages/theme-chalk/src/subject-action.scss` → subject-action
- `packages/theme-chalk/src/subject-action/` → subject-action
- `packages/theme-chalk/src/subject-layout.scss` → subject-layout
- `packages/theme-chalk/src/subject-layout/` → subject-layout
- `packages/theme-chalk/src/subject-list.scss` → subject-list
- `packages/theme-chalk/src/subject-list/` → subject-list
- `packages/theme-chalk/src/subject-type.scss` → subject-type
- `packages/theme-chalk/src/subject-type/` → subject-type
- `packages/theme-chalk/src/tiny-mce-editor.scss` → tiny-mce-editor
- `packages/theme-chalk/src/tiny-mce-editor/` → tiny-mce-editor
- `packages/theme-chalk/src/base.scss` → theme-chalk (全局基础样式)
- `packages/theme-chalk/src/normalize.scss` → theme-chalk (样式重置)
- `packages/theme-chalk/src/mixins/` → theme-chalk (样式混入)
- `packages/theme-chalk/src/common/` → theme-chalk (通用样式)
#### 功能模块匹配
- `docs/` → docs
- `scripts/` → build
- `package.json`、`pnpm-lock.yaml` → deps
- `.vscode/`、`*.config.js` → config

## 重要提醒
**在分析 git diff 时，必须：**
1. **完整获取所有修改文件**：使用 `git diff --staged --name-only` 获取完整文件列表
2. **优先识别具体模块**：按照优先级匹配最具体的 scope
3. **theme-chalk 特殊处理**：样式文件修改要归属到对应的组件，而不是 theme-chalk 包
4. **分析关键变更**：对于重要文件，要分析具体变更内容
5. **不要遗漏包内容**：如果有 `packages/` 目录修改，必须优先按最具体的模块分类
6. **智能分析修改意图**：根据代码变更模式判断真实目的
   - 删除禁用检查逻辑 → 可能是修复功能失效问题
   - 简化事件处理 → 可能是解决交互问题
   - 移除冗余代码 → 可能是优化代码结构
   - 添加/修改样式 → 可能是修复样式问题或优化UI

## 生成规则
1. **subject 生成规则**
   - 用中文，动词开头
   - 不超过 50 字，不以句号结尾
   - **必须包含具体组件或功能名称**
   - 格式：`<动词><具体组件/功能><简短描述>`
   - 示例：
     - `优化图片上传组件预览功能` (而不是 `优化组件功能`)
     - `修复数据图表组件空状态显示问题` (而不是 `修复显示问题`)
     - `新增富文本编辑器工具栏配置` (而不是 `新增配置`)

2. **body 分类规则**
   - **第一优先级**: 按具体组件分类（`packages/components/src/` 下的组件）
   - **第二优先级**: 按包维度分类（`packages/` 目录下的包）
   - **第三优先级**: 按功能模块分类（非包内容）

3. **body 结构 - 详细版本**
   ```
   ### 组件名称 (具体组件路径)
   - 修改文件：`packages/components/src/image-upload/src/image-upload.vue`
   - 变更内容：具体修改的功能点、属性、方法或样式
   - 影响范围：该修改影响的具体功能或用户体验
   - 修改原因：为什么要做这个修改

   ### 包名 (@qxs-bns/package-name)
   - 修改文件：`packages/package-name/src/xxx.ts`
   - 变更内容：具体修改点
   - 影响范围：影响的功能范围
   - 修改原因：修改的目的和背景
   ```

4. **分类优先级和详细描述要求**
   - **具体模块级别修改（最高优先级）**:
     - **组件级别**: `packages/components/src/` 下的具体组件
     - **工具函数级别**: `packages/utils/src/` 下的具体工具
     - **Hooks 级别**: `packages/hooks/src/` 下的具体 Hook
     - **指令级别**: `packages/directives/src/` 下的具体指令
     - **图标级别**: `packages/icons/src/components/` 下的具体图标
     - **样式级别**: `packages/theme-chalk/src/` 下对应组件的样式文件

   - **包级别修改**: 当修改涉及包的通用部分时
     - components: 组件库通用修改（如类型定义、工具函数等）
     - icons: 图标库通用修改（如构建脚本、基础样式等）
     - hooks: Hooks 工具通用修改（如类型定义、工具函数等）
     - utils: 工具函数通用修改（如类型定义、索引文件等）
     - directives: 指令库通用修改（如类型定义、工具函数等）
     - theme-chalk: 主题样式通用修改（全局样式、主题变量、混入等）

   - **功能模块修改**: 非包内容
     - **文档模块**: `docs/` 目录（组件文档、使用指南等）
     - **配置模块**: 根目录配置文件（开发环境、构建配置等）
     - **脚本模块**: `scripts/` 目录（发布脚本、构建脚本等）
     - **依赖模块**: `pnpm-lock.yaml`, `package.json` 依赖变更

5. **组件功能识别和描述规则**
   #### 图片上传组件 (image-upload)
   - 预览功能、上传逻辑、文件校验、进度显示、删除功能、拖拽上传
   - 禁用状态、文件格式限制、大小限制、多文件上传

   #### 文件上传组件 (file-upload)
   - 文件选择、上传进度、文件类型校验、大小限制、批量上传

   #### 数据图表组件 (data-chart)
   - 图表渲染、数据绑定、空状态显示、加载状态、图表类型切换

   #### 富文本编辑器 (tiny-mce-editor)
   - 工具栏配置、内容编辑、插件集成、样式定制、事件处理

   #### 图片裁剪工具 (photo-crop-tool)
   - 裁剪区域选择、比例设置、旋转功能、缩放功能、预览效果

   #### 主题相关组件 (subject-*)
   - 数据展示、操作交互、布局排版、状态管理、事件响应

6. **修改意图识别规则（具体化）**
   - **删除 disabled 检查** → 修复 [组件名] 禁用状态下 [具体功能] 失效的问题
   - **简化事件处理函数** → 优化 [组件名] 的 [具体事件] 响应逻辑
   - **移除冗余的条件判断** → 简化 [组件名] 的 [具体逻辑] 处理流程
   - **调整 CSS 样式** → 修复 [组件名] 的 [具体样式问题]（如布局、颜色、尺寸等）
   - **更新组件属性绑定** → 修复 [组件名] 的 [具体属性] 数据绑定问题
   - **重构函数调用** → 优化 [组件名] 的 [具体功能] 执行逻辑

7. **最终输出要求**
   - **仅输出一条 commit message**，符合 Conventional Commits 格式
   - **直接输出文本格式**，不要代码块包装
   - **不要任何额外解释、说明或前缀**
   - **subject 必须包含具体组件或功能名称**
   - **优先使用具体组件名作为 scope**：如 `image-upload`、`data-chart` 等
   - **优先使用 fix 类型**：当识别到修改是为了解决功能问题时

## 示例输出格式（优化版）

### 组件级别修改示例
```
fix(image-upload): 修复图片上传组件预览功能在禁用状态下失效问题

### 图片上传组件 (image-upload)
- 修改文件：`packages/components/src/image-upload/src/image-upload.vue`
- 变更内容：移除预览功能中的 disabled 状态检查逻辑，允许在禁用状态下正常预览已上传图片
- 影响范围：禁用状态下的图片预览功能
- 修改原因：修复用户反馈的禁用状态下无法预览图片的问题，提升用户体验

- 修改文件：`packages/theme-chalk/src/image-upload.scss`
- 变更内容：调整禁用状态下预览按钮的样式，保持可点击状态
- 影响范围：预览按钮的视觉状态和全局主题样式
- 修改原因：配合功能修复，确保样式与功能保持一致
```

### 工具函数级别修改示例
```
feat(oss-uploader): 新增 OSS 上传工具支持分片上传功能

### OSS 上传工具 (oss-uploader)
- 修改文件：`packages/utils/src/oss-uploader.ts`
- 变更内容：新增分片上传方法，支持大文件断点续传和上传进度回调
- 影响范围：大文件上传功能和用户体验
- 修改原因：解决大文件上传超时和失败率高的问题
```

### Hooks 级别修改示例
```
fix(use-pagination): 修复分页 Hook 在数据重置时页码不归零问题

### 分页 Hook (use-pagination)
- 修改文件：`packages/hooks/src/use-pagination.ts`
- 变更内容：在数据重置时自动将当前页码重置为第一页
- 影响范围：所有使用该 Hook 的分页功能
- 修改原因：修复数据刷新后页码状态不正确的问题
```

### 指令级别修改示例
```
perf(lazy-load): 优化懒加载指令性能，减少重复监听

### 懒加载指令 (lazy-load)
- 修改文件：`packages/directives/src/lazy-load.ts`
- 变更内容：优化 IntersectionObserver 的使用，避免重复创建监听器
- 影响范围：页面滚动性能和内存占用
- 修改原因：提升大量图片懒加载场景下的性能表现
```

### 图标级别修改示例
```
style(home): 优化首页图标视觉效果，调整线条粗细

### 首页图标 (home)
- 修改文件：`packages/icons/src/components/Home.vue`
- 变更内容：调整图标线条粗细，优化在小尺寸下的显示效果
- 影响范围：所有使用首页图标的界面
- 修改原因：提升图标在不同尺寸下的视觉清晰度
```


## 更多示例参考

### 新功能示例
```
feat(data-chart): 新增数据图表组件空状态展示功能

### 数据图表组件 (data-chart)
- 修改文件：`packages/components/src/data-chart/src/empty.vue`
- 变更内容：新增空状态组件，支持自定义空状态图标、文案和操作按钮
- 影响范围：数据为空时的用户界面展示
- 修改原因：提升用户体验，明确告知用户当前无数据状态
```

### 样式优化示例
```
style(photo-crop-tool): 优化图片裁剪工具操作按钮布局和交互效果

### 图片裁剪工具 (photo-crop-tool)
- 修改文件：`packages/components/src/photo-crop-tool/src/photo-crop-tool.vue`
- 变更内容：调整裁剪、旋转、重置按钮的排列方式，增加按钮悬停效果
- 影响范围：工具栏按钮的视觉布局和交互反馈
- 修改原因：提升操作界面的美观性和用户交互体验
```

### 重构示例
```
refactor(tiny-mce-editor): 重构富文本编辑器配置管理，提升可维护性

### 富文本编辑器 (tiny-mce-editor)
- 修改文件：`packages/components/src/tiny-mce-editor/src/config.ts`
- 变更内容：将编辑器配置拆分为基础配置、工具栏配置和插件配置三个模块
- 影响范围：编辑器初始化和配置管理逻辑
- 修改原因：提升代码可读性和可维护性，便于后续功能扩展
```

## 🎯 关键要求总结
1. **scope 必须具体**：按优先级使用最具体的模块名
   - 组件级别：`image-upload`、`data-chart` 等
   - 工具函数级别：`oss-uploader`、`watermark` 等
   - Hooks 级别：`use-pagination`、`use-namespace` 等
   - 指令级别：`lazy-load`、`debounce` 等
   - 图标级别：`home`、`delete` 等

2. **theme-chalk 特殊处理**：样式文件修改归属到对应组件
   - `packages/theme-chalk/src/image-upload.scss` → 使用 `image-upload` scope
   - `packages/theme-chalk/src/data-chart/` → 使用 `data-chart` scope

3. **subject 必须明确**：包含具体模块名和功能点
   - ✅ `修复图片上传组件预览功能在禁用状态下失效问题`
   - ✅ `优化 OSS 上传工具分片上传性能`
   - ❌ `修复组件问题`、`优化工具`

4. **变更内容必须详细**：说明修改了什么具体功能、方法或属性
5. **影响范围必须明确**：说明修改影响的具体功能或用户体验
6. **修改原因必须清晰**：解释为什么要做这个修改

输入：你自己获取详细的文件变更信息（如果你不会请告诉我，我会提供 `git diff` 的变更内容。）
输出：你需要生成符合以上所有规则的中文提交信息，（**直接输出文本(txt)格式代码块，不要任何额外解释或说明**）。

快速使用

获取变更内容：git --no-pager diff --cached
复制模板内容，将 diff 输出粘贴到模板末尾
提供给 AI 工具生成规范的提交信息

📖 提交信息示例

feat(components): 新增按钮组件

### @qxs-bns/components
- 修改文件：`packages/components/src/Button/Button.vue`
- 变更内容：新增按钮组件，支持多种尺寸和状态
- 目的：提供基础的按钮交互组件

### @qxs-bns/theme-chalk
- 修改文件：`packages/theme-chalk/src/button.scss`
- 变更内容：新增按钮样式定义
- 目的：为按钮组件提供视觉样式支持

🎯 常用场景

准备提交时（推荐）

bash

# 查看已暂存的更改
git --no-pager diff --cached

# 使用 AI 生成提交信息后提交
git commit -m "AI生成的提交信息"

处理大量修改

bash

# 先查看文件列表
git diff --cached --stat

# 获取完整 diff
git --no-pager diff --cached > changes.diff

⚠️ 注意事项

使用 git --no-pager diff --cached 避免输出被截断
确保已将修改添加到暂存区 (git add)
生成的提交信息可根据实际情况微调

🛠️ 推荐工具

Conventional Commits: VS Code 插件，提供提交模板
GitLens: 增强 Git 功能
Git Graph: 可视化 Git 历史

🔗 相关文档

开发指南 - 完整的开发流程
快速开始 - 项目快速上手
依赖管理 - 依赖配置指南

💡 提示: 建议将此指南加入书签，在每次提交前参考使用，养成规范提交的好习惯！

Git 提交信息生成指南 ​

🚀 快速开始 ​

获取变更内容 ​

📋 提交信息规范 ​

基本格式 ​

常用类型和作用域 ​

生成规则 ​

🤖 AI 提交信息生成 ​

使用模板 ​

快速使用 ​

📖 提交信息示例 ​

🎯 常用场景 ​

准备提交时（推荐） ​

处理大量修改 ​

⚠️ 注意事项 ​

🛠️ 推荐工具 ​

🔗 相关文档 ​

Git 提交信息生成指南

🚀 快速开始

获取变更内容

📋 提交信息规范

基本格式

常用类型和作用域

生成规则

🤖 AI 提交信息生成

使用模板

快速使用

📖 提交信息示例

🎯 常用场景

准备提交时（推荐）

处理大量修改

⚠️ 注意事项

🛠️ 推荐工具

🔗 相关文档