Git 提交规范 (Commit Convention)

星枢终端项目采用 Conventional Commits 规范，使用 Commitlint 自动检查提交消息格式

---

提交消息格式

<可选 emoji> <type>(<scope>): <subject>

<body>

<footer>

示例

✨ feat(connections): 添加 SSH 连接断线自动重连功能

实现了 SSH 连接意外断开时的自动重连机制：
- 最多重试 3 次
- 每次重试间隔递增（1s, 2s, 4s）
- 保持终端状态不变

Closes #123

---

Type 类型

Type	说明	示例
feat	新功能	feat(batch): 添加批量命令执行功能
fix	Bug 修复	fix(sftp): 修复文件上传进度显示错误
docs	文档变更	docs: 更新 API 文档
style	代码格式（不影响功能）	style: 统一缩进为 2 空格
refactor	重构（既不是新功能也不是修复）	refactor(auth): 简化登录逻辑
perf	性能优化	perf(websocket): 优化心跳机制
test	测试相关	test(connections): 添加单元测试
build	构建系统或外部依赖变更	build: 升级 TypeScript 到 5.x
ci	CI 配置文件和脚本变更	ci: 添加自动化依赖审计
chore	其他变更	chore: 更新 .gitignore
revert	回退之前的提交	revert: 回退 feat(batch) 提交
security	安全修复（自定义）	security: 修复 SQL 注入漏洞
release	发布版本（自定义）	release: v1.2.0

---

Scope 范围（可选）

Scope 用于说明提交影响的范围，可以是模块名、文件名或功能名。

常用 Scope

• connections - 连接管理
• sftp - 文件传输
• auth - 用户认证
• batch - 批量操作
• ai-ops - AI 智能运维
• websocket - WebSocket 通信
• database - 数据库
• frontend - 前端
• backend - 后端
• docker - Docker 相关
• settings - 设置
• notifications - 通知
• audit - 审计日志
• ui - 用户界面

如果变更影响多个范围，可以省略 scope 或使用 * 表示全局。

---

Subject 主题

• 简短描述：不超过 100 个字符
• 使用祈使句：如 "添加"、"修复"、"更新"，而不是 "添加了"、"已修复"
• 首字母小写：除非是专有名词
• 不加句号：主题结尾不要加句号
• 用中文描述：本项目使用中文提交消息

✅ 好的示例

✨ feat(auth): 添加 Passkey 登录支持
🐛 fix(sftp): 修复上传大文件时内存溢出问题
refactor(websocket): 重构心跳机制以提高性能

❌ 不好的示例

添加了新功能。             # 缺少 type
feat: update                # subject 太简短
feat(auth): 添加了。        # 使用了"了"，不是祈使句
FIX: some bug.              # type 应该小写，subject 应该用中文
feat(auth): 添加功能。      # 主题不应该以句号结尾

---

Body 正文（可选）

• 详细描述：解释为什么做这个变更，以及实现方式
• 换行分段：body 与 subject 之间空一行
• 使用列表：可以使用 - 或 * 列出要点
• 补充细节：说明变更的动机、实现细节、影响范围等

示例

feat(batch): 添加批量命令执行功能

实现了在多个服务器上并发执行命令的功能：
- 支持自定义并发数（1-50）
- 支持超时控制（1-3600 秒）
- 支持任务取消与进度追踪
- 实时 WebSocket 推送子任务状态

数据库新增 batch_tasks 和 batch_subtasks 表。

---

Footer 页脚（可选）

关闭 Issue

使用 Closes、Fixes、Resolves 关键字关联 Issue：

Closes #123
Fixes #456, #789
Resolves #100

Breaking Changes

如果变更包含破坏性改动（不向后兼容），需要在 footer 中说明：

BREAKING CHANGE: 移除了旧版 API v1，请迁移到 v2

或者在 type 后面加 !：

feat(api)!: 重构 RESTful API 结构

---

完整示例

简单提交

git commit -m "fix(sftp): 修复文件下载中文文件名乱码"

包含 Body 的提交

git commit -m "feat(ai-ops): 添加系统健康分析功能

实现了基于 AI 的系统健康分析：
- 分析 CPU、内存、磁盘使用率
- 识别异常进程和资源泄漏
- 提供优化建议

Closes #234"

破坏性变更

git commit -m "refactor(database)!: 重构数据库 Schema

将 connections 表拆分为 ssh_connections 和 rdp_connections，
提高查询性能并简化数据结构。

BREAKING CHANGE: 旧版数据需要执行迁移脚本 migrate_v2.sql

Closes #345"

---

验证机制

项目使用 Husky + Commitlint 在提交时自动检查格式：

1. Pre-commit Hook：运行代码格式化和 Lint 检查
2. Commit-msg Hook：先校验“可选 Emoji + Conventional + 中文 subject”，再由 Commitlint 做规则检查

Pre-commit 补充说明（2026-04-15）

• 智能引号拦截：scripts/check-smart-quotes.js 会检查暂存区代码文件中的 ‘ ’ “ ”，命中即阻止提交，避免引号边界问题。
• 安全格式化：lint-staged 对暂存代码执行 eslint --fix 与 prettier --write，减少格式化噪音进入提交历史。
• 质量总闸门：pre-commit 在 lint-staged 后强制执行 npm run -s quality:check，统一覆盖 debt:check、前端 typecheck、零 warning lint 与 format:check。
• 受控降级开关：若历史格式债务暂未清理，可临时设置 SKIP_PRECOMMIT_QUALITY=1 跳过 quality:check，但仍保留 lint-staged 对暂存区的检查；建议仅短期使用并尽快补齐全仓质量。
• any 与噪音处理：debt:check 持续拦截新增 : any / <any> / any[]，并过滤注释类噪音，避免无效告警干扰提交。

如果提交消息格式错误

$ git commit -m "update code"

⧗   input: update code
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings

正确的提交方式

$ git commit -m "✨ feat(connections): 添加连接分组功能"

[main 1a2b3c4] feat(connections): 添加连接分组功能
 3 files changed, 150 insertions(+), 20 deletions(-)

---

配置文件

• Commitlint 配置：commitlint.config.js
• Husky Hooks：.husky/pre-commit、.husky/commit-msg
• Pre-commit 任务编排：.lintstagedrc.js
• 智能引号检查脚本：scripts/check-smart-quotes.js
• 规则扩展：基于 @commitlint/config-conventional

---

常见问题 (FAQ)

Q: 必须使用 Emoji 吗？

是的。提交信息开头必须包含一个 Emoji 或 Gitmoji，例如：

✨ feat(websocket): 增加静默执行路径同步
:bug: fix(lint): 修复 eslint-plugin-import 异常

不带 Emoji 的提交信息将被 commit-msg hook 拒绝。

Q: 提交消息必须用中文吗？

是的。为了保持项目一致性，所有提交消息的 subject 和 body 应使用简体中文。

Q: 如何跳过提交检查？

优先使用受控方式，仅跳过全仓质量门禁并保留暂存区检查：

SKIP_PRECOMMIT_QUALITY=1 git commit -m "✨ feat(scope): 示例"

如果确实需要（如紧急修复）再使用：

git commit --no-verify -m "emergency fix"

但这会跳过所有 Git hooks（包括代码检查），请谨慎使用。

Q: WIP 提交怎么办？

WIP（Work In Progress）提交会被自动忽略，但建议使用正确的格式：

git commit -m "wip: 正在开发批量操作功能"

Q: Merge 提交会被检查吗？

不会。Commitlint 会自动忽略以 Merge branch 开头的提交。

---

参考资源

• Conventional Commits 规范
• Commitlint 文档
• Angular 提交规范

---

文档生成时间：2025-12-23 相关任务：工具链 - 实施 Commitlint