| name | git-changelog-generator |
| description | 分析 Git 提交记录并生成面向非技术用户的友好变更日志。当用户需要将技术性提交日志转换为易读的更新摘要、创建发布说明或向客户/利益相关者沟通产品变更时调用此技能。 |
Git 变更日志生成器
本技能将技术性的 Git 提交记录转化为清晰、结构化且面向非技术用户的变更日志,帮助最终用户理解产品更新内容。
核心能力
- 自然语言处理:分析提交消息以提取关键变更信息
- 智能分类:自动将提交归类到不同类型(功能、修复、改进、安全等)
- 用户友好翻译:将专业技术术语转化为通俗易懂的语言
- 结构化输出:生成格式规范、结构一致的变更日志
- 高度可定制:支持多种输出格式、语言和风格偏好
使用场景
在以下情况调用此技能:
- 用户提供了需要转换为发布说明的 Git 提交日志
- 团队需要向非技术利益相关者传达产品更新
- 产品经理需要面向客户的变更日志
- 营销团队需要用户友好的更新摘要
- 任何人需要将开发者提交转化为业务价值
输入要求
可接受的输入格式
- 原始 Git 日志输出(来自
git log 命令)
- 格式化的提交列表(JSON、YAML 或纯文本)
- 单条或多条提交消息
- 特定版本的提交范围(如
git log v1.0..v2.0)
推荐的 Git 日志格式
为了获得最佳效果,使用以下 git log 格式:
git log --pretty=format:"%h|%s|%b|%an|%ad" --date=short
此格式提供:提交哈希 | 主题 | 正文 | 作者 | 日期
变更类型分类
主要分类
| 类别 | 识别关键词 | 用户友好标签 |
|---|
| 新功能 | feat, add, new, implement, introduce | ✨ 新功能 |
| Bug 修复 | fix, bug, issue, resolve, patch | 🐛 问题修复 |
| 优化改进 | improve, refactor, optimize, enhance | ⚡ 优化改进 |
| 性能提升 | perf, speed, fast, latency, throughput | 🚀 性能提升 |
| 安全更新 | security, vuln, cve, protect, safe | 🔒 安全更新 |
| 文档更新 | docs, readme, guide, comment | 📝 文档更新 |
| 破坏性变更 | breaking, remove, deprecate, major | ⚠️ 破坏性变更 |
| 依赖更新 | deps, update, upgrade, bump | 📦 依赖更新 |
| 测试相关 | test, spec, coverage, e2e | 🧪 测试相关 |
| 样式调整 | style, format, lint, prettier | 💄 样式调整 |
分类规则
- 优先检查提交主题:查找常规提交前缀(feat:, fix: 等)
- 分析正文中的关键词:搜索类别特定的术语
- 考虑上下文:利用周围提交来推断意图
- 默认归为"改进":如果不清楚,分类为一般性改进
输出结构
标准变更日志格式
# [版本 X.X] 变更日志 - YYYY-MM-DD
## 版本概览
[2-3句话概述本次发布的主要内容]
---
## ✨ 新功能
### [功能名称]
**更新内容:** [不含技术术语的清晰描述]
**为什么重要:** [用户收益和价值主张]
**影响范围:** [如何影响日常使用]
---
## 🐛 问题修复
### [问题描述]
**解决的问题:** [用简单语言描述故障]
**改进之处:** [现在的改善情况]
**用户收益:** [用户体验的提升]
---
## ⚡ 优化与增强
### [改进领域]
**改进内容:** [增强功能的描述]
**您会注意到:** [具体的实际收益]
---
## 🚀 性能更新
### [组件/领域]
**速度提升:** [用易懂的语言描述性能提升]
**实际影响:** [示例场景]
---
## 🔒 安全更新
### [安全领域]
**新增保护:** [哪些方面更加安全]
**您的数据更安全因为:** [解释说明]
---
## 📊 发布统计
- 总变更数:[数量]
- 新功能数:[数量]
- 问题修复数:[数量]
- 优化改进数:[数量]
- 安全更新数:[数量]
---
*基于 [提交数量] 次提交生成,由 [贡献者数量] 位贡献者完成*
语言风格指南
核心原则
1. 避免专业技术术语 ❌ → ✅
| 技术术语 | 用户友好的替代说法 |
|---|
| 重构代码库 | 改进内部系统 |
| 实现缓存机制 | 让加载速度更快 |
| 修复竞态条件 | 解决时序问题 |
| 更新依赖项 | 升级底层技术 |
| 优化数据库查询 | 让数据获取更快 |
| 增加错误处理 | 更好的错误恢复能力 |
| 迁移到新的 API | 升级连接系统 |
| 增强日志记录 | 改进问题检测能力 |
2. 聚焦用户影响
反面示例:
"重构认证模块以实现 OAuth 2.0 和 JWT 令牌并增强会话管理"
正面示例:
"更安全的登录系统:我们升级了登录方式,使其更加安全和可靠。您的会话现在可以保持更长时间而无需重新登录,并且账户受到行业标准的保护。"
3. 使用主动语态
被动语态(避免):
"仪表板的性能通过优化数据库查询得到了改善"
主动语态(推荐):
"得益于优化的数据检索,您的仪表板现在加载更快"
4. 具体说明收益
不要只说"性能提升了",而是说:
- "页面加载速度快了40%"
- "搜索结果即时显示"
- "报告从几分钟缩短到几秒钟生成"
语气选项
根据目标受众配置语气:
🏢 专业版(默认)
😊 友好休闲版
- 对话式语气
- 鼓励使用表情符号
- 适合消费者应用/SaaS 产品
📋 简洁版
🔬 详细版
自定义选项
输出格式
用户可以请求特定格式:
- Markdown(默认)- 完整的格式化文档
- 纯文本 - 简单的文本版本
- HTML - Web 就绪格式
- JSON - 用于 API/集成的结构化数据
- 邮件模板 - 可直接发送给订阅者
语言支持
- 中文(默认)
- English(英语)
- 日本語(日语)
- 한국어(韩语)
- 其他语言可按需提供
自定义章节
用户可以指定包含/排除哪些章节:
- 仅包含某些类别
- 添加自定义章节(如"已知问题"、"迁移指南")
- 调整章节顺序
- 按组件/模块分组而非按类型分组
详细程度
- 高层概括:每个变更一行摘要
- 标准版(默认):类别 + 描述 + 收益
- 详细版:包含技术上下文 + 用户影响 + 示例
- 管理层版:聚焦业务的指标和投资回报率
处理工作流
第一步:输入分析
- 从输入中解析提交消息
- 提取元数据(作者、日期、哈希值)
- 识别提交格式(常规提交、自定义、自由格式)
第二步:内容理解
- 应用 NLP 技术理解语义
- 将技术术语映射到用户友好的概念
- 识别相关提交之间的关系
- 区分重要变更与微小调整
第三步:智能分类
- 使用分类规则对每个提交进行分类
- 将相关的提交组合在一起
- 按影响力和用户相关性排序
- 识别破坏性变更或关键更新
第四步:语言转换
- 用用户友好的语言重写技术内容
- 添加关于变更为何重要的上下文
- 包含具体的使用场景和收益
- 确保术语的一致性
第五步:格式化输出
- 应用选定的输出格式
- 按照模板进行结构化
- 添加统计摘要
- 审查清晰度和完整性
使用示例
示例1:基本用法
输入:
feat: add dark mode support
fix: resolve login timeout issue
perf: optimize image loading by 50%
docs: update API documentation
输出:
# 变更日志
## ✨ 新功能
### 暗色模式支持
**更新内容:** 您现在可以切换到更深色的配色方案,让眼睛更舒适。
**为什么重要:** 非常适合深夜工作或在光线较暗的环境中减少眼睛疲劳。
**如何使用:** 在设置中找到主题切换开关即可。
---
## 🐛 问题修复
### 登录超时问题
**解决的问题:** 部分用户在使用过程中被意外退出登录。
**改进之处:** 会话管理现在更加稳定可靠。
**用户收益:** 可以更长时间地保持登录状态而不被打断。
---
## 🚀 性能更新
### 更快的图片加载
**速度提升:** 浏览时图片几乎瞬间显示。
**实际影响:** 相册和产品图片的加载速度提高了一倍,让浏览体验更流畅。
示例2:带自定义选项
请求:
"生成一个友好风格的中文 JSON 格式变更日志,仅关注功能和问题修复"
输出:
{
"version": "未指定",
"language": "zh-CN",
"tone": "friendly",
"summary": "本次更新带来了新功能并修复了一些问题",
"changes": [
{
"category": "新功能",
"icon": "✨",
"title": "暗色模式支持",
"description": "现在可以切换到护眼的深色主题啦!特别适合夜间使用。",
"benefit": "在设置中找到主题开关即可体验"
},
{
"category": "问题修复",
"icon": "🐛",
"title": "登录超时问题",
"description": "修复了使用过程中意外掉线的问题",
"benefit": "现在可以更稳定地保持登录状态"
}
],
"statistics": {
"total_changes": 2,
"new_features": 1,
"bug_fixes": 1
}
}
最佳实践
为获得最佳效果
- 提供清晰的输入:尽可能使用格式良好的 git log 输出
- 指定受众:说明谁将阅读变更日志(客户、高管等)
- 设定上下文:如果提交含义模糊,提供产品/领域背景
- 定义范围:指明这是针对特定版本还是时间段
- 请求格式:提前指定期望的输出格式
处理边缘情况
高度技术性的提交
如果提交非常技术化:
- 如果可能,研究代码库上下文
- 关注"做了什么"而非"怎么做"
- 使用类比来解释复杂概念
- 承认如果翻译需要假设
含糊不清的提交消息
如果提交缺少细节:
- 将类似的模糊提交组合在一起
- 从文件路径或模块名推断目的
- 标记为"一般改进"并使用谨慎的语言
- 建议未来采用更好的提交实践
大量提交
处理许多提交时:
- 总结相似变更组
- 仅突出最有影响力的变更
- 在顶部创建执行摘要
- 提供详细分解作为附录
质量保证清单
交付输出前,请验证:
集成建议
版本控制系统
适用于任何提供提交日志的 VCS:
- Git(主要支持)
- Mercurial
- Subversion
- Perforce
- Azure DevOps
CI/CD 集成
可集成到发布流水线中:
- 在打标签/发布时自动运行
- 生成变更日志产物
- 发布到文档站点
- 通过邮件/通知发送
工具兼容性
输出兼容以下平台:
- GitHub Releases
- GitLab Releases
- Bitbucket
- Confluence
- Notion
- WordPress
- 静态网站生成器
局限性与注意事项
本技能擅长之处
- 将技术语言翻译为非技术语言
- 自动识别变更类别
- 创建结构化、易于扫读的输出
- 适应不同受众和格式
需要人工审核的内容
- 高度领域特定的术语
- 有争议或敏感的变更
- 法律/合规方面的影响
- 战略性传播决策
- 竞争情报方面的考虑
准确性说明
- 分类准确性取决于提交消息的质量
- 收益陈述可能需要产品知识
- 性能声明应基于实际指标进行验证
- 安全披露应遵循负责任披露指南
故障排除
常见问题
问题:输出过于技术化
解决方案:重新请求时明确指示避免专业术语;指定目标受众(例如,"向我的祖母解释")
问题:遗漏了重要变更
解决方案:提供更多产品上下文;突出应该强调的特定提交
问题:分类不正确
解决方案:手动覆盖分类;在输入中提供分类提示
问题:太冗长/简洁
解决方案:调整详细程度参数;指定大致长度或章节数量
高级功能
变更影响力评分
自动按用户影响力为每个变更评分:
- 关键(5/5):影响核心功能或安全性
- 高(4/5):主要功能或频繁使用的修复
- 中等(3/5):明显的改进或修复
- 低(2/5):次要增强或边界情况修复
- 外观(1/5):仅视觉或文档方面的更改
使用评分来:
- 确定变更日志中的优先顺序
- 创建突出最重要变更的执行摘要
- 按重要性级别过滤不同受众的内容
贡献者认可
可选择性地包含贡献者致谢:
- 列出贡献者及其贡献次数
- 突出新贡献者
- 认可重大贡献
- 链接到贡献者资料(如适用)
相关问题追踪
将变更日志条目链接到:
- 问题跟踪器 ID(GitHub Issues、JIRA 等)
- 功能请求讨论
- 错误报告讨论
- 社区反馈
多版本比较
生成对比视图:
- 自上一版本以来的新增内容
- 多个版本的累计变更
- 版本间的迁移指南
- 破坏性变更警告
反馈与持续改进
本技能基于以下方面持续改进:
- 用户对输出质量的反馈
- 领域特定词汇的添加
- 新的变更类型分类
- 格式模板的增强
- 语言风格的完善
请提供反馈,帮助我们将未来的输出定制为满足您的特定需求!