# 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 信息时：

确保代码已暂存：git add 需要提交的文件
调用此技能：/commit 或 skill: commit
分析输出结果：获取分支名称建议和 commit 信息
使用建议的 commit：git commit -m "<commit 信息>"
创建分支（如需要）：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 信息始终保持高质量，便于代码评审和项目维护，同时符合务实开发理念。