OpenClaw Conventional Commits 技能指南

OpenClaw Conventional Commits 技能概述

Conventional Commits 技能为你的 OpenClaw 工作流带来结构化、符合规范的提交信息。你不再需要从零编写提交信息或费力记忆 Conventional Commits 规范，只需让 OpenClaw 代理根据你的暂存变更生成或验证信息即可。

Conventional Commits 是一种轻量级的提交信息约定，提供清晰、机器可读的历史记录。它驱动着自动变更日志、语义化版本控制和发布工具，广泛应用于数千个开源和企业项目中。通过这个 OpenClaw 技能，你可以轻松获得这些好处，无需额外的认知负担。

典型工作流：

1. 使用 git add 暂存你的变更。
2. 让 OpenClaw 编写提交信息。
3. 代理分析差异，确定正确的类型（feat、fix、docs 等），并提出格式正确的信息——随时可以提交。

Conventional Commits 技能安装前的准备

在安装 Conventional Commits 技能之前，请确保你已具备：

• OpenClaw 已安装并运行（v1.0+）
• Git 已安装（v2.20+）— 官方下载
• 已使用 git init 初始化的项目仓库
• clawhub CLI 已安装，用于技能管理

验证你的环境：

# 检查 OpenClaw 版本
openclaw --version

# 检查 Git 版本
git --version

# 确认你在一个 Git 仓库中
git status

如何安装 Conventional Commits 技能

使用一条命令安装 Conventional Commits 技能：

npx clawhub@latest install conventional-commits

验证安装：

clawhub list

你应该能在已安装技能列表中看到 conventional-commits。该技能开箱即用——无需 API 密钥或外部服务。

Conventional Commits 技能配置指南

此技能只需最少配置。它读取你暂存的 Git 变更，并根据 Conventional Commits 规范格式化信息。不过，你可以自定义其行为以匹配团队的约定。

提交类型

该技能识别标准的 Conventional Commits 类型：

| 类型 | 使用场景 | |------|---------| | feat | 面向用户的新功能 | | fix | Bug 修复 | | docs | 仅文档变更 | | style | 格式化、缺少分号（不涉及逻辑变更） | | refactor | 代码重构，非功能或修复 | | perf | 性能改进 | | test | 添加或更新测试 | | chore | 构建流程、依赖更新、工具配置 | | ci | CI/CD 配置变更 |

作用域提交

该技能支持作用域提交信息，适用于 monorepo 和大型项目：

feat(auth): add OAuth2 login flow
fix(api): handle null response from payment endpoint
docs(readme): update installation instructions

你可以在项目配置中定义允许的作用域，以保持贡献者之间的一致性。

Conventional Commits 技能使用示例

1. 根据暂存变更生成提交信息

你："为我的暂存变更写一条提交信息。"

代理检查 git diff --staged，识别出你添加了一个新的 API 端点，并返回：

feat(api): add user profile endpoint

Implement GET /api/users/:id/profile with authentication
middleware and response caching.

你可以接受、编辑，或要求代理以不同的语气或作用域重新生成。

2. 验证现有提交信息

你："检查这条提交信息是否符合约定：'Updated the login page'"

代理分析信息并给出具体反馈：

• 缺少类型前缀——应以 feat:、fix: 或其他有效类型开头
• 使用了过去时（"Updated"）——约定建议使用祈使语气（"update"）
• 建议修正：fix(auth): update login page layout

3. 批量验证最近的提交

你："验证这个分支上最近 10 条提交信息。"

代理遍历你最近的提交历史，标记所有不符合约定的提交，并为每条提供修正建议。这在将功能分支合并到 main 之前非常有用。

4. 生成破坏性变更提交

你："将此作为破坏性变更提交——我们移除了 v1 API。"

代理格式化正确的破坏性变更提交：

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: All /api/v1/* routes have been removed.
Consumers must migrate to /api/v2/* before upgrading.

! 后缀和 BREAKING CHANGE 脚注都已包含，确保与 semantic-release 和 standard-version 等工具兼容。

安全与最佳实践

Conventional Commits 技能是 OpenClaw 生态中最安全的技能之一——它纯粹进行文本格式化和验证，没有外部 API 调用，也不会在本地 Git 仓库之外进行写操作。

遵循以下指南获得最佳体验：

• 提交前审查。 在接受生成的信息之前务必阅读。代理从差异中推断意图，但你最了解上下文。
• 使用一致的作用域。 为你的项目定义一份允许的作用域列表，并与团队共享，防止作用域混乱。
• 结合 CI 验证。 commitlint 等工具可以在 CI 流水线中强制执行 Conventional Commits，捕获任何跳过技能的手动提交。
• 启用预提交钩子。 使用 husky 或 lefthook 自动运行提交信息验证。

常见错误与故障排除

"Not a git repository"

该技能需要你在一个 Git 初始化的目录中。

# 初始化新仓库
git init

# 或导航到你的现有项目
cd /path/to/your/project

"No staged changes found"

该技能需要暂存的变更来生成有意义的提交信息。

# 暂存特定文件
git add src/feature.ts

# 或暂存所有变更
git add -A

"Unable to determine commit type"

当差异非常大或涉及许多不相关的文件时可能出现。尝试暂存更小、更聚焦的变更集，或手动指定类型：

你："为这些变更写一条 refactor 提交信息。"