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 提交訊息。」