commitlint

Commitlint

验证提交消息是否遵循 Conventional Commits 规范。 支持自动生成变更日志、语义化版本控制，以及保持 Git 历史记录整洁。

此技能的功能

1. 检查是否已安装 @commitlint/cli 和 @commitlint/config-conventional；如果缺少则安装。
2. 检测项目专属的 commitlint 配置；如果不存在，则使用合理的默认配置。
3. 验证提交消息的类型、范围、主题、正文和页脚格式。
4. 报告错误，并提供具体的修复方法和示例。

安装检查

# Check if commitlint is available
npx commitlint --version 2>/dev/null

如果尚未安装，请全局安装：

npm install -g @commitlint/cli @commitlint/config-conventional

如果安装失败（权限不足、没有 npm），请停止验证，并报告问题及解决步骤：

• 使用 sudo npm install -g ... 或修复 npm 权限
• 使用 Node 版本管理器（nvm、volta、fnm）
• 如果尚未安装，请安装 Node.js

不要悄悄跳过验证。

配置检测优先级

1. 项目根目录中的 commitlint.config.js
2. 项目根目录中的 .commitlintrc.json
3. 项目根目录中的 .commitlintrc.yaml
4. 项目根目录中的 .commitlintrc
5. package.json 中的 commitlint 字段
6. 默认配置（参见 references/conventional-commits.md）

如果项目中不存在配置，请使用参考文档中的默认配置创建临时 .commitlintrc.json，然后再运行验证。

验证工作流

1. Check commitlint installation
   ├─ Installed → continue
   └─ Missing → install, then continue (fail if install fails)

2. Detect project config
   ├─ Found → use it
   └─ Not found → use default config from references/

3. Run validation
   ├─ From a string:
   │    echo "<message>" | npx commitlint
   ├─ From a file:
   │    cat <file> | npx commitlint
   └─ From last git commit:
        git log -1 --format=%B | npx commitlint

4. Report results
   ├─ Valid → confirm and proceed
   └─ Invalid → show errors, suggest fixes, re-validate after correction

验证方法

验证提交消息字符串

echo "feat(api): add login endpoint" | npx commitlint

验证文件内容

cat path/to/message-file.txt | npx commitlint

验证最近一次 Git 提交

git log -1 --format=%B | npx commitlint

错误处理

安装失败

如果无法安装 commitlint，请报告错误并提供解决步骤。不要继续验证。

消息无效

验证失败时，请报告每条错误，并说明：

• 未通过的规则（例如 type-enum、header-max-length）
• 错误之处（例如不允许使用类型 feature）
• 具体的修复方法（例如改用 feat）

示例：

Validation failed:

1. type-enum: type 'feature' is not allowed
   Allowed: feat, fix, docs, style, refactor, perf, test, build, ci,
            chore, revert
   Fix: use 'feat' instead of 'feature'

2. header-max-length: header is 72 characters (max 50)
   Fix: shorten to 'feat: add user authentication with JWT'

报告错误后，请建议一条修正后的消息并重新验证。

格式参考

完整的 Conventional Commits 格式规范、类型说明、规则、默认配置和示例，请参见 references/conventional-commits.md。