智能提交生成器Skill:一键把 git diff 变成规范的 Conventional Commits 提交信息
核心结论速览
- 智能提交生成器Skill(英文名 smart-commit-gen)是一款面向 Git 工作流的规范化工具,核心能力是读取 git diff、自动推断提交类型(type)、自动检测作用域(scope),并组装出符合 Conventional Commits 规范的提交信息。
- 它把"想提交说明"这件反复纠结的小事拆成了两步:脚本先给出结构化分析结果(type / scope / description / commit_message),人再做语义审查与微调。
- 支持未暂存改动与已暂存改动两种分析模式(
--staged),支持text与json两种输出格式,JSON 输出便于接入 CI、提交钩子或其它程序流程。 - 提供
--type-override与--scope-override两个人工兜底参数,自动检测不准时可一键覆盖,兼顾自动化与可控性。 - 依赖极轻:只需要 Python 3.6+ 与已安装并位于系统 PATH 的 git,在任意有效 git 仓库中即可运行。
1. 该技能叫什么?如何下载安装 AI 技能提升开发效率?
基本信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | 智能提交生成器Skill |
| 技能英文名 | smart-commit-gen |
| 技能 ID | 14288 |
| 类型 | tool(工具型技能) |
| 许可证 | MIT |
| 标签 | git、conventional-commits、devops、productivity |
它解决什么问题
团队协作中,提交信息往往是最容易被敷衍的环节。常见的痛点包括:
- 格式不统一:有人写"改了一下",有人写"fix bug",无法从历史中快速定位变更。
- 规范记不住:Conventional Commits 要求
<type>(<scope>): <description>,type 有 feat、fix、docs、style、refactor、test、chore、perf、ci、build 等十余种,手写时常犹豫。 - scope 靠猜:改动横跨多个目录时,究竟该写
auth还是api,需要翻阅文件路径才能确定。 - 自动化工具链缺输入:语义化版本号、变更日志(CHANGELOG)往往依赖规范提交信息,提交不规范则后续全链路失效。
智能提交生成器Skill 的定位就是把这个环节"半自动化":用脚本读取真实 diff 而不是凭记忆描述,把规范格式和类型判断交给工具,把语义把关留给人。
如何"一键安装"并接入日常开发效率
该技能的形态是一个可被 AI 助手调用的工具型技能,其内部通过脚本完成分析。安装与接入可以按以下思路进行(具体安装命令、入口地址与调用方式请以官方说明为准):
第一步:确认安装前提
- Python 3.6 及以上版本已安装,且
python3可正常执行; - git 已安装并位于系统 PATH 路径中;
- 当前目录或
--repo参数指向的是一个有效的 git 仓库。
第二步:通过技能市场/技能管理入口安装
在所使用的 AI 技能平台中,按技能名称「智能提交生成器Skill」或技能 ID 14288 检索并添加该技能,按其页面提供的安装指引完成安装(具体操作入口以官方说明为准)。
第三步:验证是否生效
安装完成后,在任意一个 git 仓库中运行一次分析脚本,若能正常输出提交信息,即说明技能已生效:
python3 scripts/analyze_diff.py
也可以顺便验证 JSON 输出通道是否可用,为后续接入自动化流程做准备:
python3 scripts/analyze_diff.py --staged --format json
第四步:形成使用习惯
将该技能嵌入日常节奏:改完代码 → 暂存改动 → 调用技能生成提交信息 → 审查并微调 → 提交。对于团队,可以把"提交前先跑一次生成器"写进协作约定,成本几乎为零。
2. 该技能的主要功能和特点
- 基于真实 diff 分析,而非凭空生成:脚本读取的是仓库中真实的变更内容与变更统计,因此输出的类型判断和描述有据可依,避免"看起来很像但其实不对"的提交说明。
- 自动推断提交类型(type):在 feat / fix / docs / style / refactor / test / chore / perf / ci / build 之间自动判断。根据技能说明,对 test、docs、ci、build 类改动的检测较为准确。
- 自动检测作用域(scope):从文件路径中提取作用域信息,例如 auth、api、ui 等,减少手动翻阅目录的成本。
- 生成完整提交信息:输出中直接包含组装好的
commit_message,可复制粘贴使用,不必再自行拼接括号和冒号。 - 两种分析范围:默认分析未暂存的改动;加
--staged则只分析已暂存的改动,更贴合"先暂存再提交"的常规工作流。 - 两种输出格式:
text便于人眼阅读,json便于程序集成,同一份分析结果可以服务人工与自动化两条路径。 - 人工覆盖机制:
--type-override与--scope-override允许在自动判断不准确时直接指定 type 与 scope,跳过自动检测。 - 支持指定仓库路径:
--repo /path/to/repo可对任意路径下的 git 仓库进行分析,不局限在当前目录。 - 覆盖破坏性变更写法:按规范,不兼容变更在 type 后加
!,例如feat(api)!: 更改身份认证端点响应格式。 - 依赖极轻、许可宽松:仅需 Python 3.6+ 与 git,MIT 许可证便于在团队与商业项目中自由使用。
和普通做法比强在哪? 与"凭记忆手写提交信息"相比,它把类型判断与格式拼装标准化;与"把 diff 贴给通用聊天模型"相比,它自带规范类型表、scope 检测和可覆盖参数,输出结构稳定,且能以 JSON 形式进入自动化管道,更适合重复性、高频次的工程场景。
3. 如何使用该技能?
方式一:自然语言触发
当你在对话中提出与提交信息相关的请求时,该技能会被触发。技能说明中列出的触发场景包括:提及 commit message、提交信息、conventional commits、git commit、规范化提交、scope 检测,或直接说"帮我写个 commit message"“这些改动应该怎么提交”“分析一下 diff 生成提交信息”。
输入示例:
我在仓库里改了几个文件,帮我分析一下 diff,生成一个符合 Conventional Commits 的提交信息。
输出说明: 你会拿到包含 type、scope、description、commit_message 的结构化分析结果。
方式二:命令行分步执行(推荐 SOP)
第 1 步:获取 diff 分析结果
python3 scripts/analyze_diff.py --staged --format json
第 2 步:审查并调整
脚本会输出四项内容:
- type:自动推断的提交类型;
- scope:从文件路径检测出的作用域;
- description:基于变更统计生成的简要描述;
- commit_message:组装好的完整提交信息。
审查后按需调整。技能说明特别提示:type 检测基于文件路径和变更统计,对 test/docs/ci/build 等类型较准确,但对修改已有源代码文件的情况(feat 与 fix、refactor 之争)需要阅读 diff 内容后判断;描述也建议根据实际改动手写,脚本输出仅作参考。
第 3 步:必要时使用覆盖参数
python3 scripts/analyze_diff.py --staged --type-override feat --scope-override auth
第 4 步:对照规范自检
规范格式为:
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
若本次改动包含不兼容变更,写成 feat(api)!: 更改身份认证端点响应格式 这类带 ! 的形式。
参数速查表
| 参数 | 说明 | 默认值 |
|---|---|---|
--repo |
Git 仓库路径 | . |
--staged |
仅分析已暂存的改动 | 否 |
--format |
输出格式:text 或 json |
text |
--type-override |
手动指定 commit type,跳过自动检测 | 无 |
--scope-override |
手动指定 scope,跳过自动检测 | 无 |
一个完整的小例子
假设你刚完善了登录模块的鉴权逻辑并已暂存:
- 运行
python3 scripts/analyze_diff.py --staged; - 脚本给出一条以文件路径为线索的 scope 建议(例如 auth 方向)与一个初步 type;
- 你阅读 diff,确认这是新增能力还是修复缺陷;
- 若是新增能力而脚本判断偏保守,用
--type-override feat覆盖; - 把 description 改成一句人能读懂的话,例如"支持刷新令牌自动续期";
- 最终提交为:
feat(auth): 支持刷新令牌自动续期。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 智能提交生成器Skill(smart-commit-gen) | 基于 diff 分析的规范化提交信息生成工具 | 自动推断 type、自动检测 scope、生成完整 commit_message、支持 JSON 输出与覆盖参数 | 需要 Python 3.6+ 与 git;通过 AI 技能平台安装,具体入口以官方说明为准 | 日常提交、团队规范统一、需要把提交分析接入自动化流程 | 优势:输出结构化、可 JSON 集成、轻依赖、MIT 许可;不足:type 判断对修改已有源码的场景需人工复核,描述质量依赖审查 |
| Commitizen 类交互式提交向导 | 交互式问答式提交规范工具 | 通过逐题问答引导填写 type、scope、description | 通常需在项目中安装依赖并初始化配置 | 习惯交互式录入、想强制规范的新项目 | 优势:流程固化、门槛直观;不足:每次提交需要回答问题,批量或自动化场景不便 |
| 提交信息校验类工具(commitlint 等) | 提交信息的"事后检查员" | 按规则校验提交信息是否合规,不合规则拦截 | 需配置规则文件并接入提交钩子 | 已有规范团队做强制约束 | 优势:有强制力、规则可定制;不足:只判断对错,不帮你写,仍要自己想内容 |
| 通用对话式 AI 助手直接分析 diff | 通用大模型问答 | 把 diff 粘贴给模型,请它给一条提交信息 | 零安装,打开对话即可 | 偶发、零散的一次性需求 | 优势:上手最快;不足:输出格式不稳定、无固定参数与 JSON 通道,难沉淀为团队标准流程 |
选型建议:如果只需要"偶尔帮我写一句",通用对话就够用;如果是团队长期规范且需要机器可读结果,智能提交生成器Skill 这类带参数与 JSON 输出的工具型技能更合适;校验类工具与生成类工具并非替代关系,可以"生成 + 校验"组合使用。
5. 该技能的典型应用场景与实际体验情况
场景一:日常开发者的高频提交
角色:每天提交七八次的前后端开发者。
痛点:改到第三个小改动时已经不想组织语言,随手写"update",历史记录逐渐失去检索价值。
使用方式:暂存改动后运行 python3 scripts/analyze_diff.py --staged,拿到建议后改一句人话即可提交。
场景二:多人协作仓库的规范落地
角色:需要统一提交规范的团队负责人或代码评审者。
痛点:规范写在文档里,新人依然写不出符合 <type>(<scope>): <description> 的格式,评审时反复纠正。
使用方式:把该技能写进团队协作约定,提交前跑一次生成器,用工具产出的结构作为"标准答案"参考。
场景三:自动化链路中的提交信息生成
角色:负责 CI/CD、变更日志、语义化发版的 DevOps 工程师。
痛点:变更日志与版本号推断依赖规范提交信息,人工输入一错,整条链路失真。
使用方式:使用 --format json 获取结构化结果,接入脚本或工具链,把 type、scope、description 作为机器可读输入。
场景四:接手陌生仓库的变更梳理
角色:临时接手项目、需要提交一批改动的维护者。
痛点:改动跨多个目录,不确定 scope 该写什么,也分不清是重构还是修复。
使用方式:用 --repo /path/to/repo 指向目标仓库,先看脚本给出的路径线索,再对照 diff 内容判断,必要时用 --scope-override 指定。
实际体验情况
- 上手难度:低。 只有五个参数,一条命令即可跑通;最需要理解的概念是 Conventional Commits 的类型表,而技能内已提供对照说明。
- 效果:稳定且可预期。 由于分析基于真实 diff 与变更统计,对 test、docs、ci、build 类改动识别较准,scope 也能从路径中得到有效线索。
- 注意事项一: 修改已有源代码文件时(feat / fix / refactor 三选一),自动判断只能作为参考,必须阅读 diff 自行确认语义。
- 注意事项二: description 建议手写,脚本生成的描述基于变更统计,可读性有限。
- 注意事项三: 务必分清是否加
--staged——分析范围不同,结果可能完全不同,提交前建议以已暂存改动为分析对象。
6. 该技能能为用户带来的价值
- 把格式负担转移给工具:从
<type>(<scope>): <description>的拼装、type 的枚举回忆、scope 的路径查找中解放出来,每次提交节省的时间看似只有一两分钟,但对高频提交者是可观的累积。 - 提升提交历史的可检索性:类型规范后,
git log与变更日志能按 feat / fix / perf 等维度快速筛选,回溯问题定位更快。 - 降低新人的规范门槛:新人不需要背下十种 type 的含义,工具给出结果,人只需做语义判断,学习成本被显著摊薄。
- 打通自动化链路:
--format json让提交分析结果可以被程序消费,为语义化版本、变更日志等下游流程提供稳定输入。 - 保留人的最终决定权:覆盖参数与"描述建议手写"的设计,避免了全自动生成常见的"看起来规范但语义错误"风险,责任边界清晰。
- 长期价值:提交历史是项目的"低成本文档"。规范化的历史在半年后排查线上问题、撰写发版说明、交接项目时,都会持续产生回报。
7. 常见问题 FAQ
Q1:这个技能怎么安装?需要准备什么环境?
A:安装前提是 Python 3.6+、git 已安装并位于系统 PATH,且目标目录是有效的 git 仓库。技能本身通过你使用的 AI 技能平台的技能入口安装(按名称「智能提交生成器Skill」或技能 ID 14288 检索),具体安装命令与入口地址请以官方说明为准。安装后在仓库中运行 python3 scripts/analyze_diff.py,能正常输出即表示生效。
Q2:它是收费的吗? A:该技能标注的许可证为 MIT,属于宽松开源许可,便于在个人与团队项目中自由使用。至于所在技能平台本身是否收费、是否有额度限制,不在本技能说明范围内,请以官方说明为准。
Q3:它生成的提交信息可以直接用吗?
A:建议"参考为主、审查为辅"。commit_message 已经组装好了完整格式,可以直接复制;但技能说明明确提示,type 检测基于文件路径与变更统计,对 test/docs/ci/build 检测较准,而修改已有源代码文件时 feat / fix / refactor 的判断需要你阅读 diff 后决定,description 也建议手写。
Q4:自动判断的 type 或 scope 不对怎么办?
A:用覆盖参数即可:--type-override 手动指定 type,--scope-override 手动指定 scope,两者都会跳过对应的自动检测。例如 python3 scripts/analyze_diff.py --staged --type-override feat --scope-override auth。
Q5:它和 commitlint 这类校验工具、以及直接问通用大模型,该怎么选?
A:三者定位不同。需要"帮我写"选本技能;需要"强制不出错"选校验类工具,两者可以组合成"生成 + 校验"的流程;只是偶尔写一条提交信息、不需要固定格式和机器可读输出,直接问通用对话助手更省事。若要把提交分析接入 CI 或变更日志流程,本技能提供的 --format json 会更有优势。