commit

name	commit
description	生成代码评审友好的 commit 信息

我是 Git Commit 生成技能，专门为 xiaozhi-client 项目生成符合规范的、代码评审友好的 commit 信息，同时遵循务实开发理念。

技能使用原则

• 真实准确，但避免过度详细：基于实际代码改动生成信息，不虚构不存在的细节
• 评审友好优先，格式完美次之：让评审人快速理解改动比完美格式更重要
• 简单明确优于复杂说明：优先选择清晰直接的描述方式
• 务实开发指导：突出"为什么改"和"改了什么"两个核心问题

技能能力

1. 代码改动分析

核心能力：分析实际的代码改动，提取关键信息用于生成 commit 信息。

分析流程

# 1. 更新远程分支信息
git fetch origin

# 2. 获取主分支名称
MAIN_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')

# 3. 获取改动内容（优先检查未 add 的改动）
git diff --no-pager
git diff --cached --no-pager

# 4. 获取相对于主分支的改动
git diff --no-pager origin/$MAIN_BRANCH...HEAD

分析要点

• 改动范围：哪些文件、模块被修改
• 改动类型：新增功能、修复 bug、重构、文档更新等
• 影响分析：改动对现有功能的影响
• 验证方式：如何验证改动的正确性

2. Commit 类型判断

根据改动内容自动判断合适的 commit 类型。

Type 类型定义

• feat：新增 feature
• fix：修复 bug
• docs：仅仅修改了文档，比如 README、CHANGELOG、CONTRIBUTE 等等
• style：仅仅修改了空格、格式缩进、逗号等等，不改变代码逻辑
• refactor：代码重构，没有加新功能或者修复 bug
• perf：优化相关，比如提升性能、体验
• test：测试用例，包括单元测试、集成测试等
• chore：改变构建流程、或者增加依赖库、工具等
• revert：回滚到上一个版本

类型判断示例

// feat 判断标准
// - 新增文件
// - 新增公共方法
// - 新增配置选项
// - 新增 API 端点

// fix 判断标准
// - 修复 bug
// - 修复内存泄漏
// - 修复崩溃问题
// - 修复类型错误

// refactor 判断标准
// - 代码结构调整
// - 变量重命名
// - 代码提取/合并
// - 类型定义优化

// test 判断标准
// - 新增测试用例
// - 修复测试用例
// - 提高测试覆盖率

3. 分支名称生成

根据改动内容生成符合规范的分支名称。

分支命名规范

• 前缀类型：feature/、bugfix/、docs/、test/、refactor/、chore/
• 格式要求：kebab-case 格式，简洁反映改动内容
• 长度限制：不超过 50 字符

分支命名示例

# 功能开发
feature/add-user-auth-api
feature/implement-websocket-adapter
feature/support-modelscope-integration

# Bug 修复
bugfix/fix-memory-leak
bugfix/fix-type-error-in-mcp-service
bugfix/fix-connection-timeout-issue

# 文档更新
docs/update-readme-installation
docs/add-mcp-protocol-guide

# 测试相关
test/add-unit-tests-for-connection-manager
test-improve-test-coverage

# 重构
refactor-simplify-mcp-manager
refactor-optimize-path-alias-system

4. Commit 信息生成

生成符合代码评审友好的 commit 信息。

Commit 信息结构

<type>(<scope>): <subject>

## 改动说明
- 为什么改：<改动动机和问题背景>
- 改了什么：<具体的改动内容>
- 影响范围：<受影响的模块和兼容性>
- 验证方式：<测试方法或验证点>

输出格式

<分支名称>

<type>(<scope>): <subject>

## 改动说明
- 为什么改：<改动动机和问题背景>
- 改了什么：<具体的改动内容>
- 影响范围：<受影响的模块和兼容性>
- 验证方式：<测试方法或验证点>

Commit 示例

示例 1：功能开发

feature/add-user-auth-api

feat(api): 新增用户认证接口

## 改动说明
- 为什么改：提升系统安全性，实现基于 JWT 的用户认证
- 改了什么：新增 UserAuthController，实现 register、login、refresh-token 接口
- 影响范围：新增 /api/auth/* 路由，需要前端适配认证流程
- 验证方式：新增 15 个单元测试，集成测试验证完整流程

示例 2：Bug 修复

bugfix/fix-memory-leak

fix(core): 修复内存泄漏导致的性能问题

## 改动说明
- 为什么改：生产环境发现内存持续增长导致服务崩溃
- 改了什么：修复 EventEmitter 监听器未移除问题，优化内存管理
- 影响范围：核心服务内存使用优化约 30%，API 接口保持不变
- 验证方式：24 小时压力测试验证内存稳定性

示例 3：代码重构

refactor/simplify-mcp-manager

refactor(mcp): 简化 MCP 服务管理器实现

## 改动说明
- 为什么改：原实现过于复杂（340 行），包含不必要的互斥锁和状态管理
- 改了什么：移除复杂的并发控制，简化为直接的单例实现（133 行）
- 影响范围：功能保持完整，大幅降低维护成本，API 保持向后兼容
- 验证方式：所有现有测试通过，功能验证正常

示例 4：测试相关

test/add-connection-manager-tests

test(mcp): 补充连接管理器的单元测试

## 改动说明
- 为什么改：连接管理器模块测试覆盖率不足
- 改了什么：新增 12 个测试用例，覆盖核心功能和边界情况
- 影响范围：测试覆盖率从 65% 提升至 85%
- 验证方式：所有新增测试通过，覆盖率报告符合要求

示例 5：文档更新

docs/update-mcp-protocol-guide

docs(mcp): 更新 MCP 协议集成文档

## 改动说明
- 为什么改：现有文档未包含最新的 ModelScope 集成说明
- 改了什么：新增 ModelScope 配置章节，更新示例代码
- 影响范围：仅文档更新，不影响代码功能
- 验证方式：文档本地渲染验证，链接检查通过

生成 Commit 时的注意事项

1. 真实性原则

• 基于实际改动：不要虚构不存在的内容
• 避免夸大：如实描述改动，不过度宣传
• 技术准确：确保技术实现描述的准确性和专业性

2. 评审友好原则

• 突出重点：评审人最关心的是"为什么改"和"改了什么"
• 具体明确：避免模糊的描述，如"优化了性能"应具体说明如何优化
• 结构清晰：按照模板结构组织信息，便于快速阅读

3. 格式规范

• 标题简洁：commit 标题不超过 50 字符
• 使用中文：所有 commit 信息必须使用中文
• 忽略分支名：不参考当前分支名称（通常不具有参考价值）
• 不执行提交：仅提供 commit 信息建议，不执行实际的 git commit 操作

xiaozhi-client 项目特定规范

1. 路径别名系统

项目使用复杂的路径别名系统，commit 信息中应正确引用：

// 常见 scope 定义
- cli: CLI 层 (src/cli/)
- mcp-core: MCP 核心层 (src/mcp-core/)
- server: 后端服务层 (src/server/)
- web: 前端 Web 应用 (src/web/)
- config: 配置管理 (src/config/)
- endpoint: 端点处理 (src/endpoint/)
- utils: 通用工具 (src/utils/)
- types: 类型定义 (src/types/)
- test: 测试相关
- docs: 文档相关
- build: 构建相关

2. 常见改动模式

// MCP 服务相关改动
feat(mcp): 支持新增的 MCP 服务器
fix(mcp): 修复 MCP 连接超时问题
refactor(mcp): 重构 MCP 服务管理器

// CLI 相关改动
feat(cli): 新增配置验证命令
fix(cli): 修复命令行参数解析错误

// Web UI 相关改动
feat(web): 新增服务配置界面
fix(web): 修复 WebSocket 连接断开问题

// 配置相关改动
feat(config): 支持环境变量配置
fix(config): 修复配置文件解析错误

// 测试相关改动
test(mcp): 补充 MCP 协议集成测试
test(cli): 新增命令行工具测试

3. 与项目开发理念一致

• 功能驱动：commit 信息应体现"需要什么功能就实现什么功能"
• 优雅实现：描述代码如何清晰、可维护、结构合理
• 避免过度设计：不提及为了"未来可能需要"而增加的复杂度
• 务实开发：反映"先实现功能，遇到问题再优化"的开发方式

质量检查清单

生成 commit 信息后，应检查以下项目：

• commit 标题符合 git 规范，简洁明确，不超过 50 字符
• 类型选择正确（feat/fix/refactor/test/docs 等）
• scope 准确反映改动模块
• 改动说明包含"为什么改"、"改了什么"、"影响范围"、"验证方式"
• 所有内容使用中文
• 基于实际代码改动，无虚构内容
• 技术描述准确专业
• 分支名称符合规范（前缀 + kebab-case）
• 便于代码评审人快速理解改动

使用方式

当需要生成 commit 信息时：

1. 确保代码已暂存：git add 需要提交的文件
2. 调用此技能：/commit 或 skill: commit
3. 分析输出结果：获取分支名称建议和 commit 信息
4. 使用建议的 commit：git commit -m "<commit 信息>"
5. 创建分支（如需要）：git checkout -b <分支名称>

集成方式

1. Git 别名

# 设置 commit 生成别名
git config --global alias.gencommit '!git add -A && echo "请使用 /commit 技能生成 commit 信息"'

2. 与其他技能配合

• type-validator：修复类型错误后再生成 commit
• localization-validator：确保本地化符合要求
• ci-validator：commit 前运行完整质量检查

通过这个技能，可以确保 xiaozhi-client 项目的 commit 信息始终保持高质量，便于代码评审和项目维护，同时符合务实开发理念。