gcw_uZ9OegMF/cc-type-clf
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

cc-type-clf — Conventional Commits 类型分类器

给定一条 commit 标题(type(scope): description),在去掉 type 前缀之后,预测它属于哪一类:feat / fix / docs / chore / refactor。

模型只看描述部分(以及可选的 scope),所以它不是在“抄答案”,而是真的从描述推断类型。适合用来给暂未写类型的提交建议一个类型,或检查 type 与描述是否匹配。

  • 模型 ID:cc-type-classifier
  • 版本:1.0.0
  • 框架:scikit-learn(TF-IDF + Logistic Regression)
  • 许可证:Apache License 2.0

任务定义

项内容
输入commit 描述,例如 fix crash when parsing an empty toml file
输出5 个类别上的概率分布,取最大者为预测类型
类别feat fix docs chore refactor
语言中英混合(训练数据以英文为主,含中文提交)

训练数据

数据来自 AtomGit 上 4 个仓颉社区仓库的公开提交历史,通过 AtomGit API 分页抓取(脚本见 collect_commits.py):

仓库保留的样本
Cangjie/cangjie_compiler785
Cangjie/cangjie_tools515
Cangjie/cangjie_stdx437
Cangjie/cangjie_docs186
合计1923
  • 时间范围:2025-08-04 至 2026-10-22。
  • 只保留符合 Conventional Commits 前缀(feat / fix / docs / chore / refactor / perf / test / build / ci / style / revert)的提交;合并提交(!612 merge ...)等非规范信息被丢弃。
  • 训练集只使用 5 个样本量足够的类别;perf(14) / test(4) / build(3) / ci(2) 因样本过少未作为类别,对应的提交不参与训练。
  • 类别分布明显不均衡:fix 1225 条,feat 292,chore 218,docs 123,refactor 42。

数据集随模型一起发布:data/commits.jsonl(每行一条,含 repo / sha / date / type / scope / description / subject)。

方法

  1. 特征:对描述做两路 TF-IDF —— 字符 char_wb n-gram(1,4) 与空白切分词 n-gram(1,2),min_df=2、sublinear_tf=True;scope 作为独立 token(scope_<name>)拼在末尾。
  2. 分类器:LogisticRegression(max_iter=2000, class_weight="balanced")。
  3. 模型选择:按时间切分,前 70% 训练、接下来 10% 验证,在 C ∈ {1,2,4,8,16} 上按验证集 macro-F1 选参,最终用 80% 数据重训。
  4. 测试集是时间上新于训练与验证数据的最近 20%(380 条),避免同一时期的提交同时出现在训练和测试里。

评估结果

指标数值
测试集大小380
Accuracy0.6737
多数类基线(全部猜 fix)0.6263
Macro F10.4411
Weighted F10.6437

各类别表现(测试集):

类别PrecisionRecallF1支持数
chore0.890.760.8241
docs0.360.100.1640
feat0.310.290.3052
fix0.730.860.79238
refactor0.200.110.149

混淆矩阵(行=真实,列=预测,顺序 chore docs feat fix refactor):

[[ 31   0   1   9   0]
 [  3   4   6  26   1]
 [  1   1  15  34   1]
 [  0   6  25 205   2]
 [  0   0   1   7   1]]

完整指标见 model/metrics.json,可用 train.py 复现。

使用方式

pip install -r requirements.txt

# 命令行
python predict.py "fix: crash when parsing an empty toml file"
python predict.py "补充中心仓的使用说明"

# 管道
git log --format=%s -n 20 | python predict.py

# 输出 JSON(每行一条,便于脚本消费)
python predict.py --json "fix: crash when parsing an empty toml file"
git log --format=%s -n 20 | python predict.py --json
import joblib

model = joblib.load("model/cc-type-clf.joblib")
text = "crash when parsing an empty toml file"   # 已去掉 type 前缀
ranked = sorted(zip(model.classes_, model.predict_proba([text])[0]),
                key=lambda kv: -kv[1])
print(ranked[0])   # ('fix', 0.85...)

模型权重以 Git LFS 存储,克隆后请先执行 git lfs pull 再加载 model/cc-type-clf.joblib。

predict.py 会自动剥离 type(scope): 前缀再推理,所以可以直接把完整的 commit 标题交给它。

测试

python -m unittest discover -s tests -v

测试覆盖 predict.py 的前缀剥离、scope token、无前缀标题和概率排序四个场景;使用假模型,不依赖 LFS 权重,因此克隆后无需先 git lfs pull 即可运行。

局限

  • 训练量小(1923 条)且高度不均衡,docs / refactor 的召回率很低,多数被误判为 fix。
  • 只在仓颉社区 4 个仓库的提交上训练,换到别的项目、别的写作习惯时分布会漂移。
  • 描述本身常常无法区分 fix 与 feat(例如 “support xxx”),这类样本即便人工标注也有歧义,模型无法可靠区分。
  • 输出仅作建议,不建议用作 CI 门禁或自动改写提交信息。

数据来源与许可

  • 训练数据是上述 4 个公开仓库的 commit 消息元数据(标题、日期、sha),不含代码内容。
  • 各仓库内容按其自身许可证发布;本模型权重与脚本以 Apache License 2.0 发布,LICENSE 为完整文本。
  • 若你希望移除自己仓库的提交数据,可以提 issue,我会重新生成数据集并发布新版本。

文件说明

文件说明
model-config.yaml模型元信息(名称、版本、框架、任务、依赖)
model/cc-type-clf.joblib训练好的 sklearn Pipeline(特征 + 分类器),通过 Git LFS 存储
model/metrics.json完整评估指标、混淆矩阵、选参记录
data/commits.jsonl训练/评估数据集(1923 条)
collect_commits.py从 AtomGit API 抓取提交标题
make_dataset.py解析前缀、生成 data/commits.jsonl
train.py训练与评估,产出 model/
predict.py命令行推理
tests/test_predict.pypredict.py 的前缀解析与排序单测

复现

python collect_commits.py <ATOMGIT_TOKEN> "cangjie_tools,cangjie_docs,cangjie_stdx,cangjie_compiler" 30 commit_subjects.jsonl
python make_dataset.py
python train.py

由于抓取结果会随仓库历史增长而变化,重新生成的数据集不会与随包发布的 data/commits.jsonl 逐字节一致;评估数字也会略有浮动。