194 lines
7.9 KiB
Markdown
194 lines
7.9 KiB
Markdown
---
|
||
name: blade-commit
|
||
description: SpringBlade 通用 Git 提交工具。基于 Gitmoji 规范生成提交信息。当用户要求提交代码、commit 变更、生成 commit message、或使用 /blade-commit 时触发。默认强制简单模式（gitmoji + 一句话描述），仅当显式传入 --d 或 --detail 参数时才启用详细模式（gitmoji + conventional commit + 变更列表）。只执行 commit，绝不 push 或执行其他远程操作。确保每次提交都带有 gitmoji 图标。
|
||
---
|
||
|
||
# Blade Commit
|
||
|
||
通用 Git 提交工具，基于 Gitmoji 规范生成风格统一的提交信息。
|
||
|
||
## 铁律
|
||
|
||
- **只做 commit**：禁止执行 `git push`、`git pull`、`git rebase`、`git merge`、`git reset --hard` 或任何非暂存/提交的 git 操作
|
||
- **零署名**：提交信息中不得出现 `Powered by`、`Created by`、`Co-authored-by`、`Generated by` 或任何形式的工具/AI 署名
|
||
- **必须有 Gitmoji**：每条提交信息必须以 gitmoji 代码开头（如 `:sparkles:`）
|
||
|
||
## 使用方式
|
||
|
||
- `/blade-commit` — 简单模式（默认，强制单行）
|
||
- `/blade-commit --d` 或 `/blade-commit --detail` — 详细模式（多行带变更列表）
|
||
- `/blade-commit -m "自定义信息"` — 使用用户指定的信息，自动补全 gitmoji 格式
|
||
|
||
## 模式判定规则
|
||
|
||
**无论变更多大、涉及多少文件，只要用户没有显式传入 `--d` 或 `--detail` 参数，就必须使用简单模式。** 不要因为 diff 内容多就自动升级为详细模式——模式选择权在用户手中，而非由变更规模决定。
|
||
|
||
## 两种模式
|
||
|
||
### 简单模式（默认，强制）
|
||
|
||
单行格式：`:<gitmoji>: <简要描述>`
|
||
|
||
一句话说清楚改了什么。无论改动大小，只要没有 `--d` / `--detail` 参数，一律使用此格式。
|
||
|
||
```
|
||
:sparkles: 新增角色授权接口
|
||
:bug: 修复用户分页查询未过滤已删除数据
|
||
:zap: 优化字典查询排序逻辑
|
||
:recycle: 重构租户删除逻辑，迁移至 TenantService
|
||
:memo: 补充 OSS 接入文档
|
||
:wrench: 调整 application-dev.yml 数据源配置
|
||
:tada: x.x.x.RELEASE
|
||
```
|
||
|
||
### 详细模式（需显式传入 `--d` 或 `--detail`）
|
||
|
||
多行格式，适用于涉及多文件、多项改动的较大提交：
|
||
|
||
```
|
||
:<gitmoji>: <type>(<scope>): <标题摘要>
|
||
|
||
- <变更点1>
|
||
- <变更点2>
|
||
- ...
|
||
```
|
||
|
||
标题行由 gitmoji + conventional commit 类型 + 作用域 + 摘要组成，空一行后用 bullet points 逐条列出具体变更。
|
||
|
||
**示例 1 — 新功能：**
|
||
```
|
||
:sparkles: feat(system): 新增接口权限模块
|
||
|
||
- 新增 ApiScope 实体与对应 Mapper / Service / Controller
|
||
- 新增 ApiScopeHandler 处理端点级权限过滤
|
||
- 在 RoleController 中追加接口权限授权接口
|
||
- 补充 blade_api_scope 建表语句与初始化菜单 SQL
|
||
```
|
||
|
||
**示例 2 — Bug 修复：**
|
||
```
|
||
:bug: fix(auth): 修复登录 IP 锁定后刷新令牌仍可通过的问题
|
||
|
||
- RefreshTokenGranter 增加 IP 锁定状态校验
|
||
- LoginAttemptService 补充刷新场景下的失败计数复位逻辑
|
||
- 新增单元测试覆盖刷新 Token 的 IP 锁定分支
|
||
```
|
||
|
||
**示例 3 — 重构：**
|
||
```
|
||
:recycle: refactor(resource): 重构 OssEndpoint 按职责拆分 Controller
|
||
|
||
- 拆分文件上传、文件下载、文件删除为独立 Controller
|
||
- 抽取 OssService 处理跨厂商统一逻辑
|
||
- 原 OssEndpoint 保留兼容入口，内部委派至新 Controller
|
||
```
|
||
|
||
**示例 4 — 性能优化：**
|
||
```
|
||
:zap: perf(system): 优化字典批量查询性能
|
||
|
||
- DictCache 改用 Caffeine 二级缓存，减少 Redis 往返
|
||
- DictMapper 补充 code + dict_key 联合索引提示
|
||
- 调整 DictService 的 getList 为按租户分片查询
|
||
```
|
||
|
||
## Gitmoji 对照表
|
||
|
||
根据变更内容选择最匹配的 gitmoji：
|
||
|
||
| Gitmoji | 图标 | type | 场景 |
|
||
|---|---|---|---|
|
||
| `:sparkles:` | ✨ | feat | 新增功能、新特性 |
|
||
| `:bug:` | 🐛 | fix | 修复 Bug |
|
||
| `:zap:` | ⚡ | perf | 性能优化、改进提升 |
|
||
| `:recycle:` | ♻️ | refactor | 重构（不改变外部行为） |
|
||
| `:memo:` | 📝 | docs | 文档新增或变更 |
|
||
| `:wrench:` | 🔧 | chore | 配置变更、杂项 |
|
||
| `:white_check_mark:` | ✅ | test | 添加或修改测试 |
|
||
| `:tada:` | 🎉 | release | 发布新版本、里程碑 |
|
||
| `:fire:` | 🔥 | remove | 移除代码或文件 |
|
||
| `:lipstick:` | 💄 | style | UI / 样式调整 |
|
||
| `:ambulance:` | 🚑 | hotfix | 紧急修复 |
|
||
| `:construction:` | 🚧 | wip | 开发进行中 |
|
||
| `:arrow_up:` | ⬆️ | deps | 升级依赖版本 |
|
||
| `:arrow_down:` | ⬇️ | deps | 降级依赖版本 |
|
||
| `:lock:` | 🔒 | security | 安全相关修复 |
|
||
| `:truck:` | 🚚 | move | 移动 / 重命名文件 |
|
||
| `:art:` | 🎨 | style | 改进代码结构 / 格式化 |
|
||
| `:package:` | 📦 | build | 构建系统变更 |
|
||
| `:rewind:` | ⏪ | revert | 回退变更 |
|
||
| `:heavy_plus_sign:` | ➕ | deps | 添加依赖 |
|
||
| `:heavy_minus_sign:` | ➖ | deps | 移除依赖 |
|
||
|
||
## 执行流程
|
||
|
||
### 第一步：收集信息
|
||
|
||
并行执行：
|
||
- `git status` — 查看工作区状态
|
||
- `git diff --staged` — 已暂存的变更
|
||
- `git diff` — 未暂存的变更
|
||
- `git log --oneline -5` — 最近提交记录，确认当前项目的提交风格
|
||
|
||
### 第二步：适配项目风格
|
||
|
||
阅读 `git log` 结果，判断当前项目的提交语言（中文/英文）和习惯。提交信息的语言应与项目历史保持一致：
|
||
- 如果历史提交以中文为主，使用中文
|
||
- 如果历史提交以英文为主，使用英文
|
||
- 如果混合使用，默认中文
|
||
|
||
### 第三步：分析变更
|
||
|
||
阅读 diff 内容，判断：
|
||
1. **变更类型**：新功能？Bug修复？重构？文档？配置？性能优化？
|
||
2. **影响范围（scope）**：涉及哪个模块或功能（如 `system`、`auth`、`desk`、`resource`、`develop`、`gateway`、`tool` 等）
|
||
3. **核心改动**：最关键的变更是什么
|
||
4. 如果变更混合了多种类型，选最主要的类型
|
||
|
||
### 第四步：暂存文件
|
||
|
||
- 使用 `git add <具体文件路径>` 逐个添加，不要用 `git add .` 或 `git add -A`
|
||
- 排除不该提交的文件：`.env`、密钥文件、IDE 配置（`.idea/`、`.vscode/`）、编译产物（`target/`、`dist/`）、系统文件（`.DS_Store`）
|
||
- **前端工程排除规则**：如果项目根目录存在 `package.json`、`vite.config.*`、`vue.config.*` 等前端工程标识文件，则自动将 `website.js`（通常位于 `src/config/website.js`）从暂存列表中排除，即使该文件有变更也不提交。如果 `website.js` 已被暂存，执行 `git reset HEAD <website.js路径>` 将其移出暂存区
|
||
- 如果用户已经手动暂存过文件，跳过此步（但仍需检查并移除已暂存的 `website.js`）
|
||
|
||
### 第五步：生成提交信息并提交
|
||
|
||
根据模式选择对应格式，使用 HEREDOC 执行 commit：
|
||
|
||
**简单模式：**
|
||
```bash
|
||
git commit -m "$(cat <<'EOF'
|
||
:sparkles: 新增角色授权接口
|
||
EOF
|
||
)"
|
||
```
|
||
|
||
**详细模式：**
|
||
```bash
|
||
git commit -m "$(cat <<'EOF'
|
||
:sparkles: feat(system): 新增接口权限模块
|
||
|
||
- 新增 ApiScope 实体与对应 Mapper / Service / Controller
|
||
- 新增 ApiScopeHandler 处理端点级权限过滤
|
||
- 在 RoleController 中追加接口权限授权接口
|
||
- 补充 blade_api_scope 建表语句与初始化菜单 SQL
|
||
EOF
|
||
)"
|
||
```
|
||
|
||
### 第六步：确认结果
|
||
|
||
执行 `git status` 确认提交成功，向用户展示提交结果。
|
||
|
||
## 写好提交信息的要点
|
||
|
||
- **简单模式**：一句话说清楚"做了什么"，精炼但不含糊，80 字符以内为佳
|
||
- **详细模式**：
|
||
- 标题行概括全局，不超过 72 字符
|
||
- bullet points 按重要性排序：先新增，后优化，再修复
|
||
- 每个 bullet 要具体，提到文件名或模块名让人知道改了哪里
|
||
- 不要超过 8 条 bullet，太多说明应该拆分 commit
|
||
- **选对 gitmoji**：看对照表选最贴合的。不确定时 `:sparkles:` 适用于大多数新功能，`:zap:` 适用于优化改进
|
||
- 如果用户通过 `-m` 指定了信息，保留用户原意，只在格式上对齐规范（补 gitmoji、调整格式）
|