mcpField
A
aif-commit

aif-commit

github.com/lee-to开发1.1k100 次安装今天更新
代码仓库

关于 aif-commit

aif-commit 是面向开发者的 Conventional Commits 提交信息生成技能。它会分析暂存差异，并可依据项目配置和活动计划检查提交分组与上下文。

主要功能

  1. 01分析暂存文件与差异
  2. 02生成 Conventional Commits 信息
  3. 03读取项目规则与配置
  4. 04支持活动计划提交分组

适用场景

  1. 01为暂存改动拟定提交信息
  2. 02按计划将改动分成多次提交

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lee-to/ai-factory --skill aif-commit

安装后在 Claude Code 中输入/aif-commit确认已加载。

详细介绍

Conventional Commit 生成器

生成符合 Conventional Commits 规范的提交消息。

工作流

首先： 如果 .ai-factory/config.yaml 存在，则读取它以确定：

  • 路径： paths.description、paths.architecture、paths.rules_file、paths.roadmap、paths.rules、paths.plan 和 paths.plans
  • 语言： 用于提示词和提交消息规范的 language.ui
  • 工作流： 用于只读式活跃计划发现的 workflow.plan_id_format（默认为 slug；sequential 使用带编号的完整计划查找）
  • Git 偏好： 用于活跃计划发现和提交后推送行为的 git.enabled、git.create_branches 和 git.skip_push_after_commit
  • 规则层级： rules.base 以及任何命名的 rules.<area> 条目

如果 config.yaml 不存在，则使用默认值：

  • 路径：上下文资料使用 .ai-factory/，paths.plan 使用 .ai-factory/PLAN.md，paths.plans 使用 .ai-factory/plans/
  • 语言：en（英语）
  • 工作流：workflow.plan_id_format: slug
  • Git：git.enabled: true、git.create_branches: true
  • Git 偏好：skip_push_after_commit: false

读取 .ai-factory/skill-context/aif-commit/SKILL.md——如果该文件存在，则必须读取。

此文件包含 /aif-evolve 根据补丁、代码库惯例和技术栈分析积累的项目专属规则。这些规则针对当前项目进行了定制。

如何应用 skill-context 规则：

  • 将其视为对本技能通用说明的项目级覆盖规则
  • 当 skill-context 规则与此 SKILL.md 中的通用规则冲突时，以 skill-context 规则为准（更具体的上下文优先级更高——遵循与嵌套 CLAUDE.md 文件相同的原则）
  • 如果没有冲突，则同时应用：SKILL.md 中的通用规则和 skill-context 中的项目规则
  • 即使 skill-context 规则似乎与本技能的默认规则矛盾，也不要忽略它们——这些规则源于项目经验，证明默认规则并不足够
  • 重要： skill-context 规则适用于本技能的所有输出，包括提交消息格式和规范。如果 skill-context 规则要求“提交必须遵循格式 X”或“消息必须包含 Y”，则必须遵守。生成违反 skill-context 规则的提交消息属于错误。

强制执行： 生成任何输出内容后，都要根据所有 skill-context 规则进行检查。如果违反了任何规则，请先修正输出，再呈现给用户。

  1. 分析变更

    • 运行 git status 查看已暂存的文件
    • 运行 git diff --cached 查看已暂存的变更
    • 如果没有暂存内容，显示警告并建议暂存文件

  2. 解析活动计划上下文（只读，可选）

    • 按以下只读优先级解析活动计划：
      1. @<plan-file-or-directory> 参数（当参数以 @ 开头时）
      2. paths.plans 中基于分支的完整计划或 ultra 包
      3. paths.plans 中的单个完整计划，或其中的单个 ultra 包
      4. paths.plan 中的快速计划
    • 如果参数不以 @ 开头，则继续将其视为提交范围/上下文。
    • 旧版 @<plan-file> 语法仍然有效；扩展形式还接受 ultra 目录或其 index.md。
    • 查找基于分支的完整计划时：
      • 当 git.enabled = true 时，使用 git branch --show-current 获取当前分支
      • 将每个 / 替换为 -，得到 <branch-stem>
      • 当 workflow.plan_id_format = sequential 时，对以下两种路径都使用 Glob： paths.plans/[0-9][0-9][0-9][0-9]_<branch-stem>.md 和 paths.plans/[0-9][0-9][0-9][0-9]_<branch-stem>/index.md
      • Read 每个目录候选项，仅保留其中 index.md 恰好包含一个 ``
      • 使用编号最高的有效产物；如果存在多个有效候选项，则发出 WARN [aif-commit]；如果两种形态的最高前缀相同，则优先选择 ultra
      • 如果没有有效的顺序编号匹配项，则检查 paths.plans/<branch-stem>/index.md，然后检查 paths.plans/<branch-stem>.md；选择前先 Read 目录入口文件，仅当其中恰好包含一个 ultra 标记时才保留；如果两种形态都有效，则发出警告并优先选择 ultra
    • 如果 git 模式关闭、无法解析分支，或不存在基于分支的计划，则统计根目录下的 *.md 完整计划，以及直接子目录中包含 `` 的 */index.md 入口文件；排除已解析的快速计划路径，不统计阶段文件。
    • 在规范化显式指定的 ultra 目录，或将显式指定的 index.md 视为 ultra 之前，先 Read 并要求其中恰好包含一个 ``；否则以计划完整性错误 STOP。
    • 自动发现的目录入口文件仅当包含 `` 时才计入；忽略无关的 */index.md 文件。
    • 如果无法解析出活动计划，或活动计划入口文件没有 ## Commit Plan，则保持当前暂存差异行为不变。
    • 此命令绝不修改活动计划。

  3. 有可用的提交计划分组时使用它

    • 如果当前计划包含 ## Commit Plan，请解析：

      • 提交组编号／名称
      • 任务范围，例如 after tasks 1-3 或 tasks 4-6
      • 建议的 Conventional Commits 提交消息

    • 阅读计划中的 ## Tasks 或 ## Implementation Tasks 部分，将任务范围映射到任务描述和任何 Files: 提示。

    • 对于超大型计划，将当前提交组中的每项任务映射到其阶段索引／详情链接，阅读每个对应的阶段文件，并根据 ## Files to Change 表格和完整的 ## Task N 规范构建暂存路径映射。仅阅读 index.md 并不足够。

    • 如果一个阶段包含多个提交组中的任务，请使用各个 ## Task N 部分区分文件／代码块的归属；没有任务级证据时，不要将该阶段的整个文件表分配给每个组。

    • 更改暂存区之前，先将已暂存文件／代码块与计划分组进行比对：

      • 使用 git diff --cached --name-only 获取已暂存文件路径
      • 如果某个文件可能跨多个组，则使用 git diff --cached 检查已暂存代码块的依据

    • 如果无法将文件映射到各组，请停止并要求用户调整分组。

    • 使用整文件暂存前，先将分组文件与 git diff --name-only 中未暂存的工作区路径进行比对。

    • 只有在每个计划组的文件集合互不重叠，且 git diff --name-only 中未出现任何分组文件时，才能使用 git add <files>。

    • 如果同一文件跨多个计划组，请为每个组使用代码块级暂存（git add -p 或 git apply --cached）。

    • 如果分组文件与未暂存的工作区路径重叠，请按组保留并应用原始已缓存补丁（git diff --cached + git apply --cached）、使用代码块级暂存，或在更改暂存区之前停止。

    • 如果无法有把握地进行代码块级暂存，请在更改暂存区之前停止，并要求用户调整分组或将所有内容一起提交。

    • 存在可用分组时，请询问：

      AskUserQuestion: 当前计划包含 Commit Plan。应如何提交这些已暂存更改？

选项：
1. 遵循 Commit Plan
2. 将所有内容一起提交
3. 调整分组

    • 遵循 Commit Plan → 确认计划分组和消息，然后按用户确认的多次提交暂存／提交流程继续。

    • 将所有内容一起提交 → 本次忽略计划分组，继续当前的单条消息流程。

    • 调整分组 → 询问用户调整后的分组，然后在提交前根据已暂存文件进行验证。

  4. 运行上下文检查（只读）

    • 检查已解析的架构和描述文档（使用配置中的路径），以发现明显的范围／边界偏差。
    • 检查已解析的 RULES.md 和路线图文档（使用配置中的路径），以发现规则和里程碑对齐问题。
    • 检查规则层级（已解析的 paths.rules_file + rules.base + 命名的 rules.<area>）中的提交约定。
    • 缺失的可选文件（ROADMAP.md、RULES.md）属于 WARN，不构成阻碍。
    • 绝不通过此命令修改上下文文档。
    • 如果用户希望单独检查规则，请建议使用 /aif-rules-check；/aif-commit 的检查标签应保持为 WARN／ERROR。

  5. 确定提交类型

    • feat：新功能
    • fix：修复错误
    • docs：仅修改文档
    • style：代码风格（格式化、分号）
    • refactor：既不修复错误也不增加功能的代码更改
    • perf：性能改进
    • test：添加或修改测试
    • build：构建系统或依赖项
    • ci：CI 配置
    • chore：维护任务

  6. 确定范围

    • 根据文件路径确定（例如，src/auth/ → auth）
    • 根据提供的参数确定
    • 可选——如果更改涉及多个领域，则省略

  7. 生成消息

    • 主题行控制在 72 个字符以内
    • 使用祈使语气（用“add”，而不是“added”）
    • 类型后面的首字母不要大写
    • 主题末尾不要加句号

格式

<type>(<scope>): <subject>

<body>

<footer>

示例

简单功能：

feat(auth): add password reset functionality

包含正文的错误修复：

fix(api): handle null response from payment gateway

The payment API can return null when the gateway times out.
Added null check and retry logic.

Fixes #123

破坏性变更：

feat(api)!: change response format for user endpoint

BREAKING CHANGE: user endpoint now returns nested profile object

行为

调用时：

  1. 检查暂存的更改

  2. 分析差异内容

  3. 解析可选的活动计划上下文，并在可用时使用 ## Commit Plan 分组

  4. 执行只读上下文检查，并以 WARN/ERROR 总结发现

  5. 如果提交类型为 feat/fix/perf，且存在路线图，则检查里程碑关联；如果缺少关联，则发出警告，并建议在提交正文/页脚中添加关联

  6. 提议一条提交消息

  7. 在提交前向用户确认：

    AskUserQuestion: Proposed commit message:

<type>(<scope>): <subject>

Options:
1. Commit as is
2. Edit message
3. Cancel

  8. 处理用户响应：

    • 按原样提交 → 继续执行第 9 步
    • 编辑消息 → 通过 AskUserQuestion 请用户提供修正后的消息，然后使用新消息返回第 7 步
    • 取消 → 停止，切勿提交。结束工作流

  9. 使用确认后的消息执行 git commit

  10. 提交后的推送处理：

  • 如果解析后的配置中 git.skip_push_after_commit = true：

    • 完全跳过推送提示
    • 本地提交成功后结束工作流

  • 否则（默认行为），询问是否推送：

    • 显示分支/领先状态：git status -sb
    • 如果分支没有上游分支，使用：git push -u origin <branch>
    • 否则使用：git push
    AskUserQuestion: 推送到远程？

选项：
1. 立即推送
2. 跳过推送
    • 立即推送 → 根据上游状态执行推送命令：
      • 如果分支没有上游分支 → git push -u origin <branch>
      • 否则 → git push
    • 跳过推送 → 结束工作流

如果提供了参数（例如，/aif-commit auth）：

  • 将其用作范围
  • 或用作提交消息的上下文

重要事项

  • 切勿提交密钥或凭据
  • 提交前仔细检查大型差异
  • /aif-commit 不会隐式启用严格模式——除非用户明确要求阻止操作，否则上下文门控仅发出警告
  • 在此命令中，将已解析的架构、路线图、RULES.md、描述和计划文档视为只读上下文
  • 如果没有解析到有效计划，或有效计划中没有 ## Commit Plan，则保持当前暂存差异行为不变。
  • 如果暂存的更改包含无关工作（例如，一个功能加一个错误修复，或对独立模块的更改），建议拆分为多个提交：

    1. 展示哪些文件／代码块属于哪个提交

    2. 与用户确认拆分计划：

      AskUserQuestion: Split into separate commits?

Options:
1. Yes, split as suggested
2. No, commit everything together
3. Let me adjust the grouping

    3. 处理用户的回复：

      • Yes, split as suggested → 继续执行第 4 步
      • No, commit everything together → 继续执行第 5 步（提出一条提交说明）
      • Let me adjust the grouping → 通过 AskUserQuestion 请用户调整分组，然后返回第 2 步并使用新计划

    4. 更改暂存状态之前，确认每个计划分组的文件集合是否互不重叠、是否有文件横跨多个分组，以及分组中的文件是否与 git diff --name-only 列出的未暂存工作区路径重叠。

    5. 如果所有分组的文件集合互不重叠，且没有分组文件出现在 git diff --name-only 中，则使用 git reset HEAD 取消暂存所有更改，然后分别使用 git add <files> + git commit 暂存并提交各分组。

    6. 如果分组文件与未暂存的工作区路径重叠，则在取消暂存前保留每个分组原有的暂存补丁，并使用 git apply --cached 仅重新应用该补丁；否则使用按代码块暂存，或在更改暂存状态前停止。

    7. 如果一个文件横跨多个分组，则对每个分组使用按代码块暂存：通过 git add -p 或 git apply --cached 仅暂存该分组的代码块，提交后再处理下一个分组。

    8. 如果无法有把握地进行按代码块暂存或应用缓存补丁，则在更改暂存状态前停止，并请用户调整分组或将所有内容一起提交。

    9. 仅在所有提交完成后询问是否需要推送

  • 绝不要添加 Co-Authored-By 或任何其他标注 AI 作者身份的提交尾注。提交中不得包含 AI 共同作者行

评论

支持 Markdown