AReaL `/gen-commit-msg` 解析:基于 Conventional Commits 的智能提交信息生成与范围推断

AReaL/gen-commit-msg解析:基于 Conventional Commits 的智能提交信息生成与范围推断【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaLAReaL 仓库将 Claude Code 斜杠命令 .claude/commands/gen-commit-msg.md 作为统一的提交信息生成入口:输入暂存区变更,命令按五步工作流(分析变更、类型分类、范围推断、消息生成、确认后提交)产出符合 Conventional Commits 规范、且与仓库既有风格一致的提交信息。读完本文,你将掌握该命令的参数与完整工作流、AReaL 特有的 scope 推断规则、12 种提交类型的适用边界,以及与之配套的 commit-conventions 技能 和 pre-commit 钩子 如何共同保证全仓库提交风格的一致性与机器可校验性。命令定位:它在 AReaL 的提交体系中处于什么位置AReaL 的 Agent 配置由四部分组成:.claude/agents/、.claude/skills/、.claude/commands/、.claude/rules/(CLAUDE.md 的 Extended Configuration 一节给出了完整索引)。其中命令(Commands)是用户显式调用的动作,共四个:命令作用/create-prrebase、squash 提交并以智能消息创建/更新 PR/gen-commit-msg从暂存区变更生成提交信息/review-pr动态分配 agent 的智能 PR 代码评审/translate-doc-zh将英文文档翻译为中文/gen-commit-msg并非孤立存在,它与另外两个机制互相咬合:commit-conventions 技能:位于 .claude/skills/commit-conventions/SKILL.md,其 frontmatter 声明 MUST load on every git commit,即任何产生提交的流程(直接git commit、/create-pr的 squash 提交、Agent 委托提交)都会自动加载该技能,作为提交格式与 scope 推断的权威来源。命令文档中的类型表与格式规则即与该技能对齐。conventional-pre-commit 钩子:.pre-commit-config.yaml 中配置了conventional-pre-commit(rev v4.4.0),运行在commit-msg阶段,并显式声明了与本命令类型表完全一致的 12 种类型:feat、fix、docs、gov、style、refactor、perf、test、build、ci、chore、revert。也就是说,即使绕过命令手工提交,格式错误也会在 commit 阶段被钩子拦截。CLAUDE.md 的 Git Workflow 一节也从仓库层面确认了这条约定:Conventional Commits (e.g.,feat:,fix:,docs:,gov:), ~72 chars subject, imperative voice, reasoning in body。从当前仓库提交历史看,该约定被严格遵循,例如 HEAD 提交fix(rollout): train safely on incomplete groups (#1563)即采用type(scope): subject结构、祈使语气,并在 body 中解释 why 而非 what。用法与参数命令在 Claude Code 中通过/gen-commit-msg调用,支持两个可选参数:/gen-commit-msg [--amend] [--scope scope]参数说明--amend不创建新提交,而是 amend(修正)上一个提交--scope scope强制指定 scope,如workflow、engine;不传时由命令根据变更文件路径推断五步工作流详解Step 1:分析变更命令首先通过三条 git 命令采集事实依据:# Check staged files git diff --cached --name-only # Check staged content git diff --cached # Check recent commit style git log --oneline -5第一条给出变更文件清单(后续 scope 推断的输入);第二条给出实际 diff 内容(用于判断是 feature、fix 还是 refactor);第三条回看最近 5 条提交,目的是对齐仓库既有风格——这是设计哲学中 Matches repositorys existing style 的直接落地,也呼应了 CLAUDE.md 中 Follow existing code patterns 的通用原则。Step 2:类型分类(Categorize)命令内置 12 种类型的判定表,与 conventional-pre-commit 钩子 的白名单一一对应:类型适用场景feat新增功能或能力fix缺陷修复docs纯文档变更gov治理或维护者职责变更(AReaL 自定义类型)style仅格式化/样式变更refactor不含功能/修复语义的代码重构perf性能优化test新增或修复测试build构建系统或依赖变更ciCI 流水线或工作流变更chore构建、依赖、配置类杂项变更revert回滚此前的某个提交值得注意的是gov这一类型:标准 Conventional Commits 规范中并无它,AReaL 引入它专门标记治理/维护者变更——因为该仓库将GOVERNANCE.md、.github/CODEOWNERS等治理文件与代码同等纳入版本管理(.pre-commit-config.yaml 中甚至有专门格式化.github/CODEOWNERS的format-codeowners钩子)。Step 3:范围推断(Determine Scope)命令文档定义了从变更文件路径到 scope 的基础映射:变更路径scopeareal/workflow/workflowareal/engine/engineareal/reward/rewardareal/dataset/datasetareal/api/apidocs/docs多个领域省略 scope 或使用更宽泛的术语而每次提交自动加载的 commit-conventions 技能 给出了更完整的权威映射表,补充了命令文档未列出的条目:文件路径模式scopeareal/utils/utilsareal/infra/infraareal/trainer/trainerareal/models/modelsareal/experimental/archonexamples/examplesAGENTS.md、.agents/、.claude/、.codex/、.opencode/agents这些 scope 与仓库真实目录结构严格对应:areal/workflow/(RolloutWorkflow 实现)、areal/engine/(FSDP2/Megatron/SGLang/vLLM 适配)、areal/reward/(奖励函数)、areal/dataset/(数据集加载器)、areal/api/(配置 dataclass 与契约)、areal/infra/(launcher、scheduler、RPC)等,目录划分见 CLAUDE.md 的 Core Directories 一节。技能中还固化了两条设计决策,值得注意:路径推断而非内容推断:scope 只由文件路径决定,不做基于 diff 内容的主观判断,保证结果确定、可复现;跨多领域时省略 scope,而不是临时发明一个新 scope——命令文档与技能在这点上完全一致。Step 4:生成消息(Generate Message)消息模板:type(scope): subject body [Optional sections:] Key changes: - change 1 - change 2 Refs: #123, #456生成规则:规则要求Subject祈使语气,约 50–72 字符,句末不加句号Body解释 为什么而非 做了什么,72 字符换行Key changes主要修改点的项目符号列表,面向复杂提交(commit-conventions 技能 进一步量化为 3 个及以上文件)Refs如适用,引用 issue / PR 编号72 字符的换行约束并非凭空而来:仓库文档工具链(mdformat--wrap88、ruff-format)整体偏保守的可读宽度,而提交历史中 body 的换行也确实稳定在 72 字符附近。Step 5:预览、确认与提交命令生成消息后先向用户展示预览框:───────────────────────────────────── feat(workflow): add vision support to RLVR Add VisionRLVRWorkflow for vision-language RL training. Supports image inputs alongside text prompts. ─────────────────────────────────────必须经用户确认后才执行提交,且提交采用 here-doc 形式以保留多行消息的精确格式:git commit -m $(cat EOF message EOF )这一步体现了该命令的核心设计哲学之一:Requires user confirmation before commit——命令只做生成与提案,提交动作始终由人把关。三个官方示例逐条解读命令文档给出了覆盖三类典型场景的完整示例,均使用 AReaL 真实模块名,可直接作为写作模板:单文件修复(scope 精确命中 reward 目录):fix(reward): handle empty completion in gsm8k Return 0 reward instead of raising exception when completion string is empty after extraction.Body 解释的是决策理由(返回 0 而不是抛异常),对应 gsm8k 奖励函数 这类奖励函数对异常输入的策略选择。多文件功能(触发 Key changes 段落):feat(engine): add CPU offload support to ArchonEngine Enable torch_memory_saver for model offloading during rollout phase to reduce GPU memory pressure. Key changes: - Add offload/onload methods to ArchonEngine - Integrate with weight update flow - Handle ROCm compatibility该示例与仓库实现相互印证:CPU offload 机制的底层支撑包括 areal/engine/awex/memory_saver.py(基于 torch_memory_saver 的内存保存)与 areal/utils/offload.py,ROCm 兼容则由 areal/infra/platforms/rocm.py 一类平台抽象承接。三条 Key changes 恰好展示了 跨多个文件但同一领域 → 保留单一 scope 项目符号清单 的组合写法。纯文档变更(scope 省略):docs: update algorithm comparison table Add SAPO and GSPO to the algorithm family documentation with configuration examples.SAPO/GSPO 是 docs/figures/ 中确有对应示意图(sapo.png、gspo.png)的算法,说明示例并非杜撰,而是取自真实维护场景。此外,commit-conventions 技能 还额外提供两个命令文档未收录的示例,覆盖了 Agent 工具链与治理两类场景:chore(agents): port review-pr command to OpenCode Add OpenCode-native commands with task() category delegation instead of hardcoded model names.gov(agents): add maintainer ownership for service modules Update CODEOWNERS and maintainer references to reflect current governance responsibilities.前者演示choreagentsscope(修改.claude/、.opencode/等 Agent 配置目录时的归类),后者演示自定义gov类型的真实用法。与 /create-pr 的协同:同一套规则的复用.claude/commands/create-pr.md 在 Step 4: Squash Commits into Single Commit 中显式引用了同一套规则:rebase 到origin/main后,用git reset --soft origin/main将分支内所有 WIP 提交压成一个提交,然后 Generate commit message using commit-conventions skill(注释直接指向 .claude/skills/commit-conventions/SKILL.md),其 PR 标题的 categorization 也与该技能的类型表保持一致。这意味着/gen-commit-msg(单次提交)与/create-pr(squash 后一次性提交)共享同一份类型表、scope 推断和格式规则,不会出现两种风格。CLAUDE.md 的 Squash WIP commits before opening PR 要求与 AGENTS.md 的 pre-commit install --install-hooks # hooks: Ruff, clang-format, mdformat, nbstripout, conventional-commits 安装说明共同构成从本地提交到 PR 的完整校验链。维护指南:如何扩展该命令文档尾部(HTML 注释中)嵌有一份面向维护者的指南,明确了两个扩展点:场景修改位置新增模块 scope更新 Determine Scope 一节的路径映射变更消息格式更新 Generate Message 的格式模板与规则结合 commit-conventions 技能的维护指南 可看到更细致的操作约定:新增模块时把路径模式加入 scope 表并保持 areal/ 子包在前、顶层目录在后的排序;该技能被设计为每次提交必加载,因此要求保持精简以控制每次提交的 token 开销;示例必须使用真实 AReaL 模块名,并同时展示 仅 subject 与 subject body key changes 两种形态。一个实践建议:修改命令文档中的类型表/scope 表后,务必同步三处——命令文档本身、commit-conventions 技能(权威来源)、以及 .pre-commit-config.yaml 中 conventional-pre-commit 的类型白名单——否则会出现 命令生成的消息被钩子拒绝 或 文档与技能口径不一致 的问题。小结/gen-commit-msg以git diff --cached为事实输入,产出type(scope): subject结构的提交信息,12 种类型与 pre-commit 钩子 白名单严格对齐;scope 采用确定性路径推断(areal/engine/→engine等),跨多领域时省略 scope 而非发明新词;完整规则(含更全的 scope 表与chore(agents)、gov(agents)示例)以 .claude/skills/commit-conventions/SKILL.md 为准,该技能在每次提交时自动加载;命令强制 预览 → 用户确认 → here-doc 提交 的流程,配合--amend、--scope参数覆盖修正提交与强制归类两类场景;与/create-pr的 squash 流程共享同一套规则,确保分支内多次 WIP 提交压缩后的最终消息与逐次提交风格统一。【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考