SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场git-commits-and-reporting

git-commits-and-reporting

编程与开发

查看项目

更新于 10-18 18:02

技能介绍

用途

该技能把每次变更的提交历史与给审查者的简短报告都规范化：提交信息采用 Conventional Commits 并带有正确尾注，提交信息钩子与检查器共享同一套规则；发布标签单调递增；证据报告中的数字必须来自具名文件；需要人工介入时只提出一个清晰问题。三个脚本分别在提交或发送前检查提交信息、标签和报告。

主要能力

提交信息规则

  • 头部格式为 <type>(<scope>): <subject>，最多 72 字符，祈使语气，小写开头，无句尾句号。
  • scope 可以是 src/features/ 或 src/ 下的文件夹（tasks、ui、data）、固定 scope（repo、deps、docs、ci、tooling、e2e、release、skills）或 contracts/commits.json 的 extraScopes 条目；多包时为工作区文件夹。
  • ! 仅用于破坏持久化数据或公共契约的变更。
  • 每个提交只包含一个行为及其测试和代码，正文说明原因。当 contracts/commits.json 设置 requirementRef 时，豁免范围外的 feat 或 fix 还需注明所服务的需求（如 TASK-12、#31、spec 4.2）。
  • 尾注位于最后一段，Gate-Change: 必须精确：当变更文件匹配 quality-gates.json 中的 gatedPaths 时恰好出现 Gate-Change: <reason>，否则绝不出现。Spec-Change: <requirement> <what changed> 仅在因需求变化而改变测试预期时使用。原因至少 10 个字符。保留会话要求的 Co-Authored-By: 行。
  • 使用 git commit --cleanup=strip -F reports/commit-message.txt 提交已检查的文件，以去除注释行。

钩子与检查器一致性

scripts/git/commit-message-rules.ts（commit-msg 钩子）与 check-commits.mjs 提供相同的 18 条规则 ID，两者都运行 scripts/git/commit-message-samples.json 测试套件。规则变更需在同一提交中同时更新两者及样本列表。

禁止绕过或重写

不使用 --no-verify、LEFTHOOK=0、amend、rebase 或强制推送已推送的提交。钩子失败意味着提交尚未就绪。

对外操作限制

未经开发者在本会话中明确同意，不得推送、推送标签、上传商店（eas submit、Transporter、Play API）、更改 App Store Connect 或 Play Console、提交审核、向生产渠道推送 OTA 更新。

发布标签

标签仅来自发布步骤，在上传成功后创建，且为附注标签（如 git tag -a v1.4.0+ios.14 -m "App Store build 14"）：两条通道（EAS 和本地）上为 vX.Y.Z+ios.<n> 和 vX.Y.Z+android.<n>，审查者说“ship”后为 vX.Y.Z。不得移动、删除或重用标签；构建号只能递增。多包时标签以应用文件夹开头：<app>/vX.Y.Z+ios.<n>。

证据报告

每个完成的切片和发布都以证据报告结束：先以用户语言陈述结果（最多 240 字符、2 句话），包含 Evidence: 行，数字从具名文件复制（绝不凭记忆），最多一个请求及其默认值，最多五项待查看内容，诚实的“未测试或未验证”列表，技术细节最后。

暂停提问

在列出的情况下暂停并提问（references/stop-and-ask.md）：一条消息、一个可一词回答的请求、所需时间、期间适用的默认值；然后继续做不依赖答案的其他工作。发布停止（签名、协议、401/403、缺少应用记录、处理状态失败）绝不重试。

密钥保护

绝不读取、打印、复制或提交密钥：存储 API 密钥（.p8、Play 服务账号 JSON）、密钥库和证书、配置文件、令牌、.env 文件、密码。如任务似乎需要，请提问。

使用方式

  1. 一次性安装钩子规则：复制 templates/scripts/git/ 到 scripts/git/，运行 npx jest scripts/git。仅在需要更改 scope 文件夹、添加 scope 或开启需求规则时复制 templates/contracts/commits.json 到 contracts/commits.json。
  2. 暂存恰好一个切片，用 git status 和 git diff --cached --stat 确认。
  3. 从 templates/reports/commit-message.txt 写入消息文件，替换所有占位符，删除不适用的尾注行。
  4. 检查：node ${CLAUDE_SKILL_DIR}/scripts/check-commits.mjs . --message reports/commit-message.txt --staged，修复所有 FAIL 直到 RESULT: PASS，然后提交。
  5. 报告前检查历史：node ${CLAUDE_SKILL_DIR}/scripts/check-commits.mjs . --range <base>..HEAD。
  6. 写证据报告：复制模板到 reports/evidence-<YYYY-MM-DD>-<slug>.md，仅从证据文件和 Jest 摘要填写。
  7. 检查报告：node ${CLAUDE_SKILL_DIR}/scripts/check-report.mjs . --report reports/evidence-<...>.md。
  8. 需要人工时，填写 templates/reports/request.md 或 templates/reports/release-stop.md，用 --kind request 检查后发送，并继续不依赖答案的工作。
  9. 上传或“ship”后，按发布步骤创建标签并运行 node ${CLAUDE_SKILL_DIR}/scripts/check-tags.mjs .。仅在开发者本会话同意后推送标签。

适用场景

  • React Native 项目的 Git 提交信息规范化与校验。
  • 发布标签创建与检查。
  • 切片与发布证据报告撰写与校验。
  • 需要人工介入时的提问与发布停止消息。

限制

  • 规则与脚本面向特定仓库结构（src/features/、quality-gates.json、contracts/ 等），需按项目配置。
  • 钩子与检查器必须同步更新，否则可能出现一个通过另一个失败。
  • 不提供自动推送、上传或发布能力；这些操作需开发者明确同意。
  • 报告中的数字必须来自具名文件，不能凭记忆或使用排练/试运行结果。