✨ feat(commit-message): bundle policy and validator
This commit is contained in:
+132
-62
@@ -1,92 +1,162 @@
|
||||
---
|
||||
name: commit-message
|
||||
description: "Use when the user asks for help writing a commit message, wants emoji/type(scope): subject formatting, or asks to review staged changes before committing."
|
||||
description: "当用户需要撰写或审查提交信息、检查已暂存改动、判断是否拆分提交，或使用 emoji 与提交类型（作用域）格式时使用。"
|
||||
---
|
||||
|
||||
# Commit Message（提交信息建议器）
|
||||
# Commit Message（提交信息）
|
||||
|
||||
## Overview
|
||||
## 概述
|
||||
|
||||
Create a repository-compliant recommendation from the staged diff. Resolve its
|
||||
boundary and enforced rules before drafting.
|
||||
根据已暂存的差异生成符合仓库规范的提交信息建议。先确定当前有效的机器策略，
|
||||
再判断一次提交的逻辑边界，并在展示任何候选信息前完成校验。
|
||||
|
||||
## When to Use
|
||||
本 skill 自带可独立部署的机器资产：
|
||||
|
||||
Use for commit-message drafting, staged-boundary review, split decisions, or
|
||||
emoji/type(scope): subject formatting.
|
||||
- `references/commit_policy.json`：提交信息格式策略。
|
||||
- `scripts/validate_commit_message.py`：候选信息和 CI 输入校验器。
|
||||
|
||||
## When Not to Use
|
||||
以包含本文件的目录作为 skill 根目录解析上述路径。不要假设存在 Playbook checkout、
|
||||
仓库 `docs/` 目录或特定的当前工作目录。
|
||||
|
||||
Do not use for PR titles, release notes, changelogs, or exact-message execution.
|
||||
## 适用场景
|
||||
|
||||
## Inputs
|
||||
以下情况使用本 skill：撰写提交信息、审查已暂存边界、判断是否拆分提交，或处理
|
||||
`emoji/type(scope): subject` 格式。
|
||||
|
||||
Use staged/unstaged state and repository policy.
|
||||
交互式起草 PR 标题、发布说明、变更日志，以及执行用户已经明确给出的原文，不使用
|
||||
本 skill。validator 的无参数 CI 模式可以把 `pull_request.title` 当作独立输入校验；
|
||||
这不表示交互式 commit-message 工作流负责起草 PR 标题。
|
||||
|
||||
## Procedure
|
||||
## 输入
|
||||
|
||||
1. **Baseline state**
|
||||
- 暂存状态：`git status --short` 和 `git diff --cached`。
|
||||
- 暂存内容指纹：
|
||||
`git diff --cached --binary --no-ext-diff | git hash-object --stdin`。
|
||||
- 未暂存状态，必须与已暂存差异分开检查。
|
||||
- 适用的项目指引和机械约束，例如 hook、CI 或显式机器策略。
|
||||
- 本 skill 目录中的 bundled policy 和 validator。
|
||||
|
||||
- Inspect staged and unstaged changes separately.
|
||||
- If nothing is staged, do not produce a final diff-based message. Offer an
|
||||
unstaged draft only when explicitly requested.
|
||||
- Record the staged file list and summary for the final consistency check.
|
||||
## 有效策略
|
||||
|
||||
2. **Resolve effective policy**
|
||||
validator 按以下固定优先级选择机器策略：
|
||||
|
||||
- Read applicable repository instructions, mechanical enforcement
|
||||
(`commitlint`, hooks, CI workflow/env, validation scripts), then the nearest
|
||||
`commit_message.md`.
|
||||
- Effective enforcement overrides optional prose defaults. Report conflicts
|
||||
and use a form accepted by both whenever possible.
|
||||
- With no repository policy, state and use this Conventional Commits fallback:
|
||||
`type(scope): subject`; optional scope; type from `feat`, `fix`, `docs`,
|
||||
`style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, or `revert`; no
|
||||
emoji; imperative lowercase subject, at most 72 characters, no final period.
|
||||
1. 命令行 `--policy <path>`。
|
||||
2. 环境变量 `COMMIT_POLICY_PATH`。
|
||||
3. 本文件旁的 `references/commit_policy.json`。
|
||||
|
||||
3. **Classify the boundary**
|
||||
同时读取适用的项目指引、hook 和 CI 约束；它们用于发现冲突，但不会改变上述路径
|
||||
优先级。需要让项目规则成为机器策略时，必须通过前两项之一显式选择对应 JSON。
|
||||
policy 的 `emoji.requirement_env` 未设置时使用 `required_by_default`；设置成
|
||||
非空 `false_values` 中任一值时关闭要求，设置成其它值时开启要求。空
|
||||
`false_values` 属无效 policy。
|
||||
|
||||
- Identify the dominant intent and required coupled changes.
|
||||
- For unrelated intents, stop before drafting a combined message. Output
|
||||
ordered groups with files, intent, and a provisional message for each.
|
||||
- Continue with one combined message only after the user explicitly opts out
|
||||
of the recommended split.
|
||||
显式机器策略与 bundled 默认值不一致时，必须在结果中说明。不要从说明性文件中
|
||||
推断规则覆盖。bundled policy 缺失、损坏或版本不支持时，应报告部署错误，不能
|
||||
悄悄退回到自行编造的 Conventional Commits 约定。
|
||||
|
||||
4. **Draft and validate**
|
||||
## 流程
|
||||
|
||||
- Produce one recommendation. Add alternatives only when materially distinct
|
||||
valid type or scope interpretations remain.
|
||||
- Add body/footer only for motivation, impact, verification, issue links, or
|
||||
breaking changes.
|
||||
- Use a repository validator when it accepts candidate input. Otherwise check
|
||||
type, emoji, scope, length, subject, body, and footer manually. A HEAD-only
|
||||
check does not validate a candidate.
|
||||
- Rerun the staged summary before finalizing. If it changed, reread the diff
|
||||
and restart classification.
|
||||
1. **基线状态**
|
||||
|
||||
5. **Finalize safely**
|
||||
分别检查已暂存和未暂存改动，记录完整 cached diff 的上述指纹。如果没有任何
|
||||
已暂存改动，停止并说明无法根据实际差异生成最终建议。只有用户明确要求时，才
|
||||
可以提供基于未暂存内容的草稿。
|
||||
|
||||
Label the result as a suggestion or final choice. Run `git commit` only after
|
||||
explicit user authorization.
|
||||
2. **判断提交边界**
|
||||
|
||||
## Output Contract
|
||||
找出主要意图，以及保证该意图正确所必需的文件或 hunk。如果同一文件内存在多个
|
||||
无关 hunk，也必须按 patch 边界拆分，不能只按文件归组。如果已暂存改动包含互不
|
||||
相关的意图，按顺序列出拆分组并为每组给出独立信息。在用户明确选择不拆分前，
|
||||
不要用一个主题掩盖多个意图。
|
||||
|
||||
| State | Required output |
|
||||
| --- | --- |
|
||||
| Single intent | `Detected`, `Spec`, one `Proposed`, `Validation`, optional body/footer and materially distinct alternatives |
|
||||
| Mixed intents | `Detected`, `Split` groups, and `Notes`; no combined `Proposed` until the user opts out of splitting |
|
||||
3. **起草信息**
|
||||
|
||||
`Spec` names the source, enforcement, and conflicts. `Validation` names the
|
||||
validator result or manual checks.
|
||||
对单一意图给出一个具体建议。只有存在实质不同且均有效的 type 或 scope 解释时，
|
||||
才增加备选项。只有在说明动机、影响、验证、任务链接或破坏性变更时，才添加正文
|
||||
或 footer。
|
||||
|
||||
## Success Criteria
|
||||
4. **校验候选信息**
|
||||
|
||||
- Output matches the current staged diff and effective policy
|
||||
- Mixed work yields a split plan, not a disguised combined message
|
||||
- Every candidate is validated; filler alternatives are omitted
|
||||
- No commit runs without explicit authorization
|
||||
使用 Python 3.10 或更高版本。根据本文件位置解析 skill 根目录，对每一个候选主题
|
||||
以进程 API 的 `argv` 参数数组运行 validator：
|
||||
|
||||
## Failure Handling
|
||||
```text
|
||||
argv = [
|
||||
"<python3>",
|
||||
"<skill-root>/scripts/validate_commit_message.py",
|
||||
"--subject",
|
||||
"<candidate>",
|
||||
]
|
||||
```
|
||||
|
||||
No staged diff: explain and stop. No policy: state the fallback. Conflicts:
|
||||
report them and use the stricter accepted form. Changed staging: restart.
|
||||
路径和候选必须分别作为 argv 元素传入；禁止把候选拼接到 shell 命令字符串中。
|
||||
Linux/macOS 通常使用 `python3`，Windows 使用当前环境可用的 Python 3 入口。
|
||||
|
||||
对提交信息文件可使用 `--message-file <path>`，但该模式只校验首行主题，不机械
|
||||
校验 body/footer；结果中的 `Validation` 必须明确这一边界。如果项目指引要求使用
|
||||
bundled policy 之外的策略，传入 `--policy <path>`；否则让 validator 使用随 skill
|
||||
携带的 JSON。无参数运行检查 CI payload；只有未识别事件或本地调用才回退 `HEAD`，
|
||||
不能代替对新起草候选的校验。已识别的 push/PR 事件缺失或损坏 payload 时必须失败。
|
||||
PR 必须同时校验 `pull_request.title` 和本地 Git 中的 `base.sha..head.sha` 完整提交
|
||||
范围；遇到 shallow repository、缺失范围元数据或 Git 对象时必须失败。PR CI 的
|
||||
workflow 编排必须来自可信 base/default branch：直接触发时使用
|
||||
`pull_request_target`，或先用 `pull_request` 准备输入、再由默认分支的
|
||||
`workflow_run` 执行校验。普通 `pull_request` 中来自 PR head 的 workflow 即使切到
|
||||
base worktree，也仍可被待审改动删除或绕过。可信 workflow 必须从 `base.sha` 的
|
||||
可信 base worktree 运行 wrapper、validator 和 policy；只能读取 PR head 的 Git
|
||||
对象，不能在持有 secret 的步骤 checkout 或执行 PR head 内容。
|
||||
普通 push 必须校验本地 Git 中的 `before..after` 完整范围；新分支 push 的 `before`
|
||||
为零对象时，必须用 payload 的目标 `refs/heads/*` 和本地分支图计算该分支相对其它
|
||||
分支新增的完整提交集合。缺少有效范围元数据、目标引用或所需 Git 对象时必须失败；
|
||||
push 所在仓库遇到 shallow repository 也必须失败。不能用可能截断的 payload
|
||||
`commits` 数组或计数字段证明范围完整。
|
||||
|
||||
5. **一致性复核**
|
||||
|
||||
最终确定前重新运行 `git status --short` 和 cached diff 指纹。任一结果发生变化时，
|
||||
重新阅读差异、判断边界并重新校验候选信息；不要只比较文件名或 diff stat。
|
||||
|
||||
6. **安全收尾**
|
||||
|
||||
明确标注结果是建议还是最终选择。除非用户在审阅建议后明确授权，否则绝不运行
|
||||
`git commit`，不暂存文件，也不修改 index。
|
||||
|
||||
## 输出约定
|
||||
|
||||
以下固定字段名保留英文，以兼容已有调用方；字段内容使用中文：
|
||||
|
||||
单一意图必须包含：
|
||||
|
||||
- `Detected`：已暂存文件、主要意图，以及是否需要拆分。
|
||||
- `Spec`：使用的 bundled 或显式机器策略，以及项目机械约束冲突。
|
||||
- `Proposed`：一个已经校验通过的主题；确有必要时附正文或 footer。
|
||||
- `Validation`：validator 命令及其结果。
|
||||
- `Notes`：歧义、剩余风险或实质不同的备选解释。
|
||||
|
||||
多个意图必须包含 `Detected`、按顺序排列的 `Split` 分组以及 `Notes`。每个 `Split`
|
||||
分组都必须包含：
|
||||
|
||||
- `Files/Hunks`：文件及具体 hunk/patch 边界；同一文件可出现在不同组。
|
||||
- `Intent`：该组唯一的逻辑意图。
|
||||
- `Spec`：该组候选使用的机器策略和冲突。
|
||||
- `Proposed`：该组已经校验通过的独立主题。
|
||||
- `Validation`：该组实际运行的 validator argv 和结果。
|
||||
|
||||
在用户明确选择不拆分前，不要给出合并后的 `Proposed`。任何组未校验通过时，不得
|
||||
把整份拆分建议标为已验证。
|
||||
|
||||
## 成功标准
|
||||
|
||||
- 建议准确描述当前已暂存差异，而不是猜测用户意图。
|
||||
- 每个候选都使用 bundled 或显式选定的策略完成校验。
|
||||
- 混合改动得到明确的拆分建议。
|
||||
- 暂存状态或完整 cached diff 指纹变化会触发重新基线和重新判断。
|
||||
- 未经明确授权，不执行提交、暂存或 index 写入。
|
||||
|
||||
## 失败处理
|
||||
|
||||
- 没有已暂存差异：说明限制，并停止生成最终的差异型信息。
|
||||
- policy 或 validator 缺失/无效：报告部署或配置错误。
|
||||
- 候选无效：报告 validator 原因，不把它标记为合规信息。
|
||||
- 意图混合或无法判断：建议拆分并说明边界依据。
|
||||
- 审查期间项目状态变化：重新执行基线和边界判断。
|
||||
|
||||
Reference in New Issue
Block a user