# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Changed（变更）
- 规范化 `SKILL.md` 正文骨架，补齐输入、输出、校验、失败恢复和公共约束摘要；git-commit 的既有功能语义保持不变。

## [2.2.0] - 2026-02-13

### Changed
- **动态语言检测**：移除 `config.yaml` 中硬编码的 `default_language`，改为运行时动态检测
  - 优先级：用户指定（`--lang`） > 最近 5 次 commit 主体语言 > 设备默认语言
  - 最近 5 次 commit 以多数语言为准（如 3 中文 + 2 英文 → 中文）
  - 平局时使用设备默认语言
  - 无 commit 时使用设备默认语言（检测 `$LANG` 环境变量）

### Added
- 新增 `--lang <zh|en>` 参数，支持用户临时指定提交信息语言

## [2.1.0] - 2026-02-13

### Added
- **自动推送**：提交成功后默认自动执行 `git push`
  - 自动模式：直接推送，无需确认
  - 审核模式：询问是否推送
  - 自动检测并设置上游分支（`git push -u origin <branch>`）
- 新增 `--no-push` 参数，跳过自动推送（仅本地提交）

### Changed
- 工作流程增加"自动推送"步骤（步骤 6），原"安全回滚"调整为步骤 7
- 更新重要约束，明确"默认推送"行为

## [2.0.1] - 2026-02-11

### Fixed
- Auto stage now includes untracked files by default (even when the staging area is not empty), preventing “new files missing from commit”.

### Added
- `--no-untracked` option to disable automatic handling of untracked files.

## [2.0.0] - 2026-01-19

### Added
- **工作模式**：新增自动模式和审核模式，默认使用自动模式
  - 自动模式：AI 自主决策暂存、拆分、提交，无需用户确认
  - 审核模式：在关键决策点暂停，等待用户确认
- 新增 `--review` 参数启用审核模式
- 新增 `--no-all` 参数在自动模式下跳过自动暂存
- 在 config.yaml 中新增 `modes` 配置段，定义两种模式的行为

### Changed
- **破坏性变更**：默认行为从"审核模式"改为"自动模式"
  - 暂存区为空时，自动模式默认执行 `git add -A`（而非提示用户选择）
  - 达到拆分阈值时，自动模式自动拆分提交（而非仅给出建议）
  - 提交前，自动模式直接提交（而非显示 commit message 等待确认）
  - 如需原有交互行为，请使用 `--review` 参数启用审核模式

## [1.0.0] - 2026-01-18

### Added
- 初始化 git-commit skill
- 从 zcf:git-commit 迁移到项目级技能管理
- 支持 Conventional Commits 规范
- 支持可选 emoji 前缀
- 智能拆分提交建议
- 根据仓库历史自动选择语言
- 默认运行本地 Git 钩子（可 --no-verify 跳过）
- 在 README.md 中添加致谢章节，说明参考了 UfoMiao/zcf 项目

# Git Commit Skill 配置
#
# 版本号遵循语义化版本规范：主版本号.次版本号.修订号
# - 不兼容的 API 修改 → 主版本号+1
# - 向下兼容的新功能 → 次版本号+1
# - 问题修正 → 修订号+1

skill_info:
  name: git-commit              # 技能名称（与目录名一致）
  version: 2.2.0                # 当前版本（动态语言检测）
  description: "仅用 Git 分析改动并生成 conventional commit 信息（可选 emoji），默认自动 push"  # 技能描述（最大 1024 字符）
  author: "Bensz Conan"
  category: "git"               # 技能分类（normal/git/data-analysis/devops 等）

# 工作模式配置
modes:
  # 默认模式（auto/review）
  default: "auto"               # auto: AI 自主决策；review: 关键步骤需用户确认
  # 自动模式行为
  auto:
    auto_stage: true            # 暂存区为空时自动 git add -A
    auto_stage_untracked: true  # 暂存区非空但存在未跟踪文件时，自动补齐未跟踪文件到暂存区
    auto_split: true            # 达到阈值时自动拆分提交
    auto_commit: true           # 直接提交，不询问确认
    auto_push: true             # 提交成功后自动 push
  # 审核模式行为（当传入 --review 参数时）
  review:
    prompt_stage: true          # 暂存区为空时提示用户选择
    prompt_untracked: true      # 存在未跟踪文件时提示是否补齐（可选仅暂存未跟踪文件）
    prompt_split: true          # 给出拆分建议，询问是否接受
    prompt_commit: true         # 显示 commit message，询问是否确认
    prompt_push: true           # 提交成功后询问是否推送

# 提交类型定义
commit_types:
  feat: "新增功能"
  fix: "缺陷修复"
  docs: "文档与注释"
  style: "风格/格式（不改语义）"
  refactor: "重构（不新增功能、不修缺陷）"
  perf: "性能优化"
  test: "新增/修复测试"
  chore: "构建/工具/杂务"
  ci: "CI/CD 配置与脚本"
  revert: "回滚提交"

# Emoji 映射
emoji_map:
  feat: "✨"
  fix: "🐛"
  docs: "📝"
  style: "🎨"
  refactor: "♻️"
  perf: "⚡️"
  test: "✅"
  chore: "🔧"
  ci: "👷"
  revert: "⏪️"

# 拆分提交的阈值
split_thresholds:
  max_lines: 300  # 单次提交最大改动行数
  max_dirs: 5     # 跨越的顶级目录数
  max_files: 20   # 单次提交最大文件数

# 提交信息约束
message_constraints:
  max_subject_length: 72    # 主题行最大长度
  max_body_lines: 10        # 正文最大行数
  max_body_items: 3         # 正文列表项数量

# 提交信息语言检测策略
#
# 语言选择优先级（从高到低）：
# 1. 用户明确指定：通过 --lang zh 或 --lang en 参数
# 2. 最近 5 次 commit 的主体语言：统计最近 5 次提交信息的语言，以多数为准
#    - 例如：3 次简体中文 + 2 次英文 → 使用简体中文
#    - 例如：2 次中文 + 3 次英文 → 使用英文
#    - 平局时优先使用用户设备默认语言
# 3. 用户设备默认语言：检测操作系统的 locale 设置
#    - macOS/Linux: $LANG 环境变量
#    - Windows: 系统语言设置
#    - 如检测到 zh_CN、zh_TW 等中文 locale → 使用简体中文
#    - 其他情况 → 使用英文
#
# 注意：此配置项仅作文档说明，实际语言由 AI 在运行时动态检测

# Git Commit

本 README 面向**使用者**：如何触发并正确使用 `git-commit` skill。
执行指令与硬性规范在 [`SKILL.md`](SKILL.md)；默认参数在 [`config.yaml`](config.yaml)。

---

## 用法 🚀

### 最推荐用法（自动模式）

```bash
# 自动分析改动、暂存、拆分并提交（无需任何确认）
提交 Git 改动
```

### 结合 emoji 和签名

```bash
# 自动模式 + emoji + 签名
提交 Git 改动，使用 emoji，然后签名
```

### 需要审核每个步骤（审核模式）

```bash
# 在暂存、拆分、提交前暂停，等待你确认
提交 Git 改动，使用审核模式
```

---

## 工作模式 📖

本技能支持两种工作模式，满足不同场景需求：

| 模式 | 触发方式 | 适用场景 | 行为特征 |
|------|----------|----------|----------|
| **自动模式** | 默认（无参数） | 日常开发、快速提交 | AI 自主决策所有步骤，无需确认 |
| **审核模式** | `--review` 参数 | 重要提交、需要精细控制 | 在关键决策点暂停，等待确认 |

### 自动模式（默认）

**适用场景**：大多数日常提交

**行为特征**：
- 暂存区为空时，自动执行 `git add -A`
- 存在未跟踪文件时，默认会自动把未跟踪文件加入暂存区（即使暂存区已非空），避免“新文件漏提交”
- 检测到大规模改动时，自动拆分为多个提交
- 直接执行提交，不询问确认

**设计理念**：commit 的顺利提交比内容本身更重要；如不满意可直接 `git reset` 回退。

### 审核模式

**适用场景**：重要发布、多人协作项目、需要精细控制提交内容

**行为特征**：
- 暂存区为空时，提示你选择暂存方式
- 检测到大规模改动时，给出拆分建议并询问是否接受
- 提交前显示生成的 commit message，询问是否确认

---

## 使用示例

### 示例 1：快速提交日常改动

**场景**：你刚完成一个小功能，想快速提交

```
你：提交 Git 改动

技能：[自动执行]
1. 检测到 3 个文件改动
2. 自动暂存所有文件
3. 生成 commit message：
   feat(auth): add OAuth2 login flow
   - implement Google and GitHub third-party login
   - add user authorization callback handling
4. 提交成功
```

### 示例 2：带 emoji 的风格化提交

**场景**：你想让 commit 历史更生动

```
你：提交 Git 改动，使用 emoji

技能：[自动执行]
✨ feat(ui): add user authentication flow

- implement login form with email and password fields
- add authentication state management hook

Closes #42
```

### 示例 3：审核模式 - 大规模改动拆分

**场景**：你修改了很多文件，想确保提交粒度合理

```
你：提交 Git 改动，使用审核模式

技能：[暂停并询问]
检测到 15 个文件、450 行改动，建议拆分为 3 个提交：

1. feat(ui): add login component (src/components/LoginForm.tsx)
2. fix(api): resolve token validation (src/api/auth.ts)
3. docs(auth): update authentication guide (docs/auth-guide.md)

是否接受此拆分方案？[Y/n]

你：Y

技能：[按顺序执行 3 个提交]
```

### 示例 4：跳过 Git 钩子

**场景**：本地有 lint 钩子，但你想先提交稍后修复

```
你：提交 Git 改动，跳过钩子检查

技能：[自动执行，跳过 --no-verify]
提交成功（已跳过本地钩子）
```

---

## 使用参数

### 模式控制

| 参数 | 作用 |
|------|------|
| `--review` | 启用审核模式 |
| `--no-all` | 自动模式下跳过自动暂存 |
| `--no-untracked` | 不自动处理未跟踪文件（避免新文件被自动加入暂存区） |

### 提交控制

| 参数 | 作用 |
|------|------|
| `--no-verify` | 跳过本地 Git 钩子 |
| `--amend` | 修补上一次提交（⚠️ 仅限未推送分支） |
| `--signoff` | 附加 `Signed-off-by` 行 |

### 内容控制

| 参数 | 作用 |
|------|------|
| `--emoji` | 在提交信息中包含 emoji 前缀 |
| `--scope <scope>` | 指定提交作用域 |
| `--type <type>` | 强制提交类型 |

---

## 提交类型与 Emoji

| 类型 | 说明 | Emoji |
|------|------|-------|
| `feat` | 新增功能 | ✨ |
| `fix` | 缺陷修复 | 🐛 |
| `docs` | 文档与注释 | 📝 |
| `style` | 风格/格式 | 🎨 |
| `refactor` | 重构 | ♻️ |
| `perf` | 性能优化 | ⚡️ |
| `test` | 新增/修复测试 | ✅ |
| `chore` | 构建/工具 | 🔧 |
| `ci` | CI/CD 配置 | 👷 |
| `revert` | 回滚提交 | ⏪️ |

---

## 智能拆分规则

当改动满足以下条件时，技能会自动拆分提交：

| 拆分类型 | 触发条件 |
|----------|----------|
| **规模过大** | 改动行数 > 300 或文件数 > 20 |
| **跨模块过多** | 跨越顶级目录数 > 5 个 |
| **类型混合** | 包含 2 种以上不同类型的改动（如 feat + fix） |
| **功能独立** | 涉及 2 个以上互不相关的功能模块 |

---

## 常见问题

### Q：自动模式会不会误提交不想要的内容？

A：可以使用 `--review` 参数启用审核模式，在暂存前确认要提交的文件；或者先用 `git add <path>` 手动暂存需要的文件。若你不希望新文件被自动加入暂存区，请使用 `--no-untracked`。

### Q：如何让技能默认使用中文 commit message？

A：编辑 [`config.yaml`](config.yaml) 中的 `default_language: "zh"`。

### Q：自动模式会跳过 Git 钩子吗？

A：不会。自动模式依然会执行本地 Git 钩子；如需跳过，请使用 `--no-verify` 参数。

### Q：如何查看最近的 commit message？

A：技能会在提交成功后显示完整信息；也可用 `git log -1 --format=full` 查看。

---

## 更多文档

- [`SKILL.md`](SKILL.md) — 技能执行规范和工作流
- [`config.yaml`](config.yaml) — 可配置参数
- [`CHANGELOG.md`](CHANGELOG.md) — 版本变更历史

---

## WHICHMODEL - 模型选择最佳实践

**最后更新**：2026-01-25

### 披露信息

- **覆盖厂商**：Anthropic, OpenAI（2/6 = 33%）
- **来源构成**：社区 70%, 官方 20%, 技术博客 10%
- **数据时效**：2024-10 至 2026-01
- **局限性**：未覆盖国产模型，未独立测试 commit 信息生成准确率

---

### 场景化建议

#### 场景 1：标准提交信息生成（最常见）

**触发条件**：日常代码提交，需要生成规范的 commit message

| 项目 | 建议 |
|------|------|
| **推荐模型** | Claude Haiku 4.5 |
| **推理强度** | low |
| **预期成本** | ~$0.001-0.01/次 |

**理由**：
- Haiku 是 Anthropic 最快的模型，响应时间 < 1 秒
- 成本仅为 Sonnet 的 20%
- commit 信息生成是简单的文本处理任务，主要是模式匹配和模板填充
- [社区反馈](https://www.reddit.com/r/ClaudeAI/comments/1ocpoye/haiku_45_better_than_sonnet/) 显示 Haiku 在简单脚本任务中表现优异

**避免**：无需升级，除非遇到复杂的代码逻辑分析需求

**来源**：[Haiku System Card](https://www.anthropic.com/claude-haiku-4-5-system-card) + Reddit 社区讨论

---

#### 场景 2：复杂改动分析

**触发条件**：
- 需要深度理解代码变更的业务逻辑
- 大规模改动的拆分决策（>300 行，多模块）
- 需要判断破坏性变更

| 项目 | 建议 |
|------|------|
| **推荐模型** | Claude Sonnet 4.5 |
| **推理强度** | medium |
| **预期成本** | ~$0.02-0.10/次 |

**理由**：
- Sonnet 在代码分析任务中表现出色
- 更适合需要"中等复杂度理解"的场景
- [社区对比](https://medium.com/@ayaanhaider.dev/sonnet-4-5-vs-haiku-4-5-vs-opus-4-1-which-claude-model-actually-works-best-in-real-projects-7183c0dc2249) 显示 Sonnet 在复杂场景下的优势
- **复杂改动拆分需要一定的推理能力**

**避免**：简单提交不需要 Sonnet，用 Haiku 即可

**来源**：社区对比讨论 + 官方模型选择指南

---

#### 场景 3：批量提交

**触发条件**：
- 需要连续生成多个 commit message
- 成本敏感，需要高性价比

| 项目 | 建议 |
|------|------|
| **推荐模型** | Claude Haiku 4.5 |
| **推理强度** | low |
| **预期成本** | ~$0.005-0.03/批 |

**理由**：
- Haiku 成本最低，适合批量提交
- 批量提交中速度优势明显
- [社区验证](https://chatlyai.app/blog/claude-haiku-4-5-use-cases) 显示 Haiku 能"handle high-volume tasks without breaking the bank"

**避免**：复杂改动拆分时不要只用 Haiku

**来源**：社区反馈 + 官方文档

---

### 对比总结

| 模型 | 最适合 | 最不适合 | 相对成本 | 相对速度 | 推荐度 |
|------|-------|---------|---------|---------|-------|
| **Haiku 4.5** | 标准提交、批量提交 | 复杂改动分析 | $ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **Sonnet 4.5** | 复杂改动拆分、破坏性变更判断 | 简单提交（浪费） | $$$ | ⭐⭐⭐⭐ | ⭐⭐ |
| **Opus 4.5** | **不推荐** | 所有场景 | $$$$$ | ⭐ | ⭐ |

**说明**：
- Haiku 覆盖 95% 的 Git 提交场景
- Sonnet 仅在复杂改动拆分时才值得使用
- Opus 对此任务**完全不必要**，成本过高且无性能提升

---

### 通用原则

1. **默认从 Haiku 开始**：95% 的 Git 提交任务 Haiku 足够，无需升级
2. **简单任务、快速响应**：Git 提交是高频操作，Haiku 的 <1 秒响应时间明显优于 Sonnet 的 3-5 秒
3. **成本敏感**：批量提交时成本差异明显（Haiku 是 Sonnet 成本的 1/5）
4. **复杂度判断**：仅当改动规模 >300 行或跨 >5 个模块时，考虑升级 Sonnet
5. **避免过度设计**：commit 信息生成是简单的文本处理任务，Haiku 完全胜任

---

### ⚠️ 争议点

#### Haiku vs Sonnet：Git 提交真的可以用 Haiku 吗？

| 观点 | 支持者 | 理由 |
|------|-------|------|
| **Haiku 足够** | Reddit 社区 | Git 提交是简单任务，Haiku 在文本生成任务中表现稳定 |
| **Sonnet 更保险** | 部分开发者 | 担心 Haiku 在复杂改动分析时出错 |

**数据支持**：
- [某用户测试](https://medium.com/@cognidownunder/claude-haiku-4-5-matches-sonnets-coding-skills-at-80-less-cost-changes-everything-297f4b163d4e)：Haiku 在编码任务中匹配 Sonnet 能力，成本降低 80%
- [官方文档](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model)：Haiku 专为"高吞吐量、低延迟"场景设计

**建议**：
- **默认使用 Haiku**：Git 提交属于简单的文本处理任务，Haiku 完全胜任
- **仅在以下情况升级 Sonnet**：
  - 改动规模 >300 行或跨 >5 个模块
  - 需要深度理解业务逻辑才能确定提交类型
  - 需要判断破坏性变更（API 变更、配置格式变更）
  - Haiku 出现理解错误时（极少见）

---

### 更新记录

- 2026-01-25：首次调研，覆盖 Anthropic/OpenAI
- 建议：2026-07 重新调研（6 个月后）

---

### 来源链接

**官方文档**：
- [Claude Tool Use Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)
- [Choosing the right model](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model)
- [Claude Haiku 4.5 System Card](https://www.anthropic.com/claude-haiku-4-5-system-card)

**社区讨论**：
- [Sonnet 4.5 vs Haiku 4.5 vs Opus 4.1](https://medium.com/@ayaanhaider.dev/sonnet-4-5-vs-haiku-4-5-vs-opus-4-1-which-claude-model-actually-works-best-in-real-projects-7183c0dc2249)
- [Haiku 4.5 better than Sonnet? (Reddit)](https://www.reddit.com/r/ClaudeAI/comments/1ocpoye/haiku_45_better_than_sonnet/)
- [Claude Haiku 4.5: Features, Testing Results, and Use Cases](https://www.datacamp.com/fr/blog/anthropic-claude-haiku-4-5)

**技术博客**：
- [Top Use Cases for Claude Haiku 4.5](https://chatlyai.app/blog/claude-haiku-4-5-use-cases)
- [Claude Haiku 4.5 matches Sonnet's coding skills at 80% less cost](https://medium.com/@cognidownunder/claude-haiku-4-5-matches-sonnets-coding-skills-at-80-less-cost-changes-everything-297f4b163d4e)

---

## 致谢

本技能的开发参考了 [UfoMiao/zcf](https://github.com/UfoMiao/zcf) 项目，汲取了其在 Conventional Commits 规范实现方面的设计思路。感谢原作者的开源贡献。

---
name: git-commit
description: 当用户明确要求"提交 Git 改动"、"生成 commit 信息"或"创建 git commit"时使用。仅用 Git 分析改动并自动生成 conventional commit 信息（可选 emoji）；必要时建议拆分提交，默认运行本地 Git 钩子（可 --no-verify 跳过），提交后默认自动 push（可 --no-push 跳过）。
metadata:
  author: Bensz Conan
  short-description: 仅用 Git 分析改动并生成 conventional commit 信息（可选 emoji），默认自动 push
  keywords:
    - git-commit
    - git commit
    - conventional commit
    - commit message
category: normal
---

# Git Commit

## 目标

当用户明确要求"提交 Git 改动"、"生成 commit 信息"或"创建 git commit"时使用。仅用 Git 分析改动并自动生成 conventional commit 信息（可选 emoji）；必要时建议拆分提交，默认运行本地 Git 钩子（可 --no-verify 跳过），提交后默认自动 push（可 --no-push 跳过）。

## 流程

### 输入

#### 触发场景

- 用户要提交代码改动
- 需要生成符合规范的提交信息
- 需要判断是否应该拆分提交
- 需要包含 emoji 的提交信息

### 执行步骤

#### 工作模式

本技能支持两种工作模式：

| 模式 | 触发方式 | 行为特征 |
|------|----------|----------|
| **自动模式** | 默认（无参数） | AI 自主决策所有步骤：自动暂存、自动拆分、直接提交 |
| **审核模式** | `--review` 参数 | 在关键决策点暂停，等待用户确认暂存方式、拆分建议、提交信息 |

**默认使用自动模式**，因为大多数情况下 commit 的顺利提交比内容本身更重要；如不满意可直接回退。

#### 工作流程

##### 1. 仓库/分支校验

- 通过 `git rev-parse --is-inside-work-tree` 判断是否位于 Git 仓库
  - **如不在 Git 仓库**：提示 `git init` 初始化仓库后继续
- 读取当前分支/HEAD 状态：
  - **如处于 detached HEAD 状态**：提示风险并确认是否继续
    - 检测方法：`git rev-parse --symbolic-full-name HEAD` 返回 `HEAD`
    - 提示内容："⚠️ 当前处于 detached HEAD 状态，提交将不属于任何分支。建议先创建分支（`git switch -c <branch-name>`）或切换到现有分支（`git switch <branch-name>`）"
  - **如处于 rebase/merge 冲突状态**：给出明确指导
    - **检测到 Git 冲突**：当前处于 rebase/merge 冲突状态，请先处理冲突：
      1. 查看冲突文件：`git status`
      2. 解决冲突（编辑标记为 `<<<<<<<` 的文件）
      3. 标记冲突已解决：`git add <冲突文件>`
      4. 继续 rebase/merge：`git rebase --continue` 或 `git merge --continue`
      5. 完成后重新运行 git-commit
    - 或跳过当前提交：`git rebase --skip`
    - 或中止 rebase/merge：`git rebase --abort` / `git merge --abort`

##### 2. 改动检测

- 用 `git status --porcelain` 与 `git diff` 获取已暂存与未暂存的改动
  - **如无改动**：提示 "当前无改动，无需提交"，退出
- 额外检测 **未跟踪文件（untracked）**：用 `git ls-files --others --exclude-standard` 列出未跟踪且未被忽略的文件
- 若存在未跟踪文件：
  - **自动模式**（默认）：
    - 若暂存区为空：自动执行 `git add -A`（除非传入 `--no-all` 或 `--no-untracked` 跳过）
    - 若暂存区非空：仅暂存未跟踪文件（除非传入 `--no-untracked` 跳过）
      - 先获取列表：`git ls-files --others --exclude-standard`
      - 再执行：`git add -- <untracked_paths...>`
      - 如路径可能包含空格/特殊字符：用 NUL 分隔更稳妥
        - `git ls-files --others --exclude-standard -z | xargs -0 git add --`
      - 说明：此操作不会影响你已暂存/未暂存的其他改动，只是把“新文件”补进暂存区，避免漏提交
  - **审核模式**：提示用户选择：
    - **选项 1**：暂存所有改动（`git add -A`）
    - **选项 2**：仅暂存未跟踪文件（`git add -- <untracked_paths...>`）
    - **选项 3**：暂存部分文件（`git add <path>...`）
    - **选项 4**：取消命令，手动分组暂存后重试
- 若暂存区为空且无未跟踪文件：
  - **自动模式**：自动执行 `git add -A`（除非传入 `--no-all` 跳过）
  - **审核模式**：提示用户选择暂存方式（同上）

##### 3. 拆分建议

按以下决策树判断是否需要拆分提交：

**1. 强制拆分条件**（任一满足则建议拆分）：
- 超过规模阈值：改动行数 > 300 行或跨越目录数 > 5 个
- 多种提交类型：包含 2 种以上不同类型的改动（如 feat + fix）
- 多个独立功能：改动涉及 2 个以上互不相关的功能模块

**2. 建议拆分条件**（不满足强制条件时）：
- 文件类型混合：源代码 + 文档/测试在同一提交
- 可回滚性差：单个提交回滚会影响其他功能

**3. 单一提交条件**（以上都不满足）：
- 改动规模适中（< 300 行）
- 单一功能模块
- 单一提交类型
- 可独立回滚

若检测到多组独立变更或 diff 规模过大：
- **自动模式**：按分组自动执行多次提交（不询问）
- **审核模式**：给出每一组的 pathspec 拆分建议，询问是否接受

##### 4. 提交信息生成

###### 格式规范

遵循 Conventional Commits 规范：

```
[<emoji>] <type>(<scope>)?: <subject>

<body>

<footer>
```

###### 类型（type）

详见 config.yaml 中的 `commit_types` 定义。

###### Emoji 映射（使用 --emoji 时）

详见 config.yaml 中的 `emoji_map` 定义。

###### 自动识别 type 和 scope

**type 自动识别**：根据改动内容自动识别（如新增功能 → feat，修复缺陷 → fix）

**scope 自动识别**：
- 取改动文件的最上层模块名（如改动 `src/auth/login.ts` → scope 为 `auth`）
- 如跨越多个模块，省略 scope（如 `feat: add user feature`）
- 用户可通过 `--scope` 参数覆盖自动识别的 scope

###### 内容要求

- **主题行**：首行 ≤ 72 字符，祈使语气，使用动词开头
- **正文**：
  - 必须在 subject 之后空一行
  - 使用列表格式，每项以 `-` 开头
  - 每项必须使用动词开头的祈使句
  - 禁止使用冒号分隔的格式（如 "Feature: description"）
  - 说明变更的动机、实现要点或影响范围（3 项以内为宜）
- **脚注**：
  - 必须在 Body 之后空一行
  - 破坏性变更：`BREAKING CHANGE: <description>`
  - 其它采用 git trailer 格式（如 `Closes #123`）

###### 破坏性变更检测与处理

**检测规则**（满足任一条件即为破坏性变更）：
- 删除了公开 API（函数、类、方法）
- 修改了公开 API 的签名（参数、返回值）
- 修改了配置文件的格式
- 删除了配置项或改变了配置项的语义
- 数据库 schema 变更（不兼容旧版本）

**处理方式**：
- 在 type 后添加感叹号标记，如 `feat(api)!: redesign authentication API`
- 在脚注中说明 `BREAKING CHANGE: <description>`
- 建议将破坏性变更拆分为独立提交（如与修复混在同一提交）

###### 语言选择

按以下优先级**动态检测**提交信息语言：

1. **用户明确指定**：通过 `--lang zh` 或 `--lang en` 参数临时切换语言
2. **最近 5 次 commit 的主体语言**：
   - 执行 `git log -n 5 --pretty=%s` 获取最近 5 次提交的主题行
   - 统计各语言出现次数，以**多数为准**（如 3 次中文 + 2 次英文 → 使用中文）
   - 平局时（如 2 次 + 2 次 + 1 次其他）优先使用设备默认语言
3. **设备默认语言**（当仓库无 commit 时）：
   - 检测环境变量 `$LANG`（macOS/Linux）或系统语言设置
   - 如检测到 `zh_CN`、`zh_TW`、`zh_HK` 等 → 使用简体中文
   - 其他情况 → 使用英文

**检测示例**：
```bash
# 获取最近 5 次 commit 主题
git log -n 5 --pretty=%s

# 检测设备语言
echo $LANG  # 例如：zh_CN.UTF-8 → 中文；en_US.UTF-8 → 英文
```

##### 5. 执行提交

- **自动模式**：
  - 单提交场景：直接执行 `git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`
  - 多提交场景：按分组自动依次执行 `git add <paths> && git commit ...`
- **审核模式**：
  - 单提交场景：显示生成的 commit message，询问是否确认后再提交
  - 多提交场景：给出每一组的 `git add <paths> && git commit ...` 指令，询问是否执行

##### 6. 自动推送

提交成功后，默认自动执行 push：

- **自动模式**：提交成功后直接执行 `git push`（除非传入 `--no-push`）
- **审核模式**：提交成功后询问是否推送
- **推送前检查**：
  - 检查当前分支是否有上游分支：`git rev-parse --abbrev-ref --symbolic-full-name @{u}`
  - 如无上游分支：自动执行 `git push -u origin <branch>` 设置上游并推送
  - 如有上游分支：直接执行 `git push`
- **推送失败处理**：
  - 如推送被拒绝（远程有新提交）：提示用户先拉取（`git pull --rebase`）后再推送
  - 如无推送权限：提示用户检查远程仓库配置

##### 7. 安全回滚

##### 7. 安全回滚

如误暂存，可用 `git restore --staged <paths>` 撤回暂存（命令会给出指令）

如误提交（未推送），可用 `git reset --soft HEAD~1` 撤回提交（保留改动）

如已推送，需使用 `git revert` 创建反向提交（避免强制推送）

#### 使用参数

##### 模式控制

- `--review`：启用审核模式（在关键决策点暂停，等待用户确认）
- `--no-all`：在自动模式下跳过自动暂存（包括自动 `git add -A` 与自动补齐未跟踪文件）
- `--no-untracked`：在自动/审核模式下不自动处理未跟踪文件（避免把“新文件”自动加入暂存区）

##### 提交控制

- `--no-verify`：跳过本地 Git 钩子
- `--no-push`：提交后不自动推送（仅本地提交）
- `--amend`：修补上一次提交（⚠️ 危险操作：仅在未推送的本地分支使用，已推送的分支使用会导致历史不一致）
- `--signoff`：附加 `Signed-off-by` 行

##### 内容控制

- `--emoji`：在提交信息中包含 emoji 前缀
- `--scope <scope>`：指定提交作用域
- `--type <type>`：强制提交类型
- `--lang <zh|en>`：临时指定提交信息语言（覆盖自动检测）

### 输出

#### 输出示例

##### 使用 emoji

```
✨ feat(ui): add user authentication flow

- implement Google and GitHub third-party login
- add user authorization callback handling
- improve login state persistence logic

Closes #42
```

##### 不使用 emoji

```
feat(auth): add OAuth2 login flow

- implement Google and GitHub third-party login
- add user authorization callback handling
- improve login state persistence logic
```

##### 包含破坏性变更

```
feat(api)!: redesign authentication API

- migrate from session-based to JWT authentication
- update all endpoint signatures
- remove deprecated login methods

BREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration
```

##### 拆分提交示例

**自动模式**：自动执行以下三个提交（不询问）

**审核模式**：检测到多组独立变更，建议拆分为以下提交：

###### 提交 1：feat(ui): add user authentication flow
```bash
git add src/components/LoginForm.tsx src/hooks/useAuth.ts
git commit -m "feat(ui): add user authentication flow

- implement login form with email and password fields
- add authentication state management hook

Closes #42"
```

###### 提交 2：fix(api): resolve token validation error
```bash
git add src/api/auth.ts
git commit -m "fix(api): resolve token validation error

- add proper error handling for expired tokens
- update token refresh logic"
```

###### 提交 3：docs(auth): update authentication documentation
```bash
git add docs/auth-guide.md
git commit -m "docs(auth): update authentication documentation

- add OAuth2 integration guide
- update troubleshooting section"
```

### 输出管理

#### BenszAPI 任务工作区


### 校验

交付前校验仓库位于 Git 工作树、无未处理 rebase/merge 冲突，提交信息符合 Conventional Commits（主题不超过 72 字符；正文项目原则上建议不超过 3 项，超出时说明原因），并确认 hook、commit 和（未使用 `--no-push` 时）push 的实际结果；无改动时明确返回无需提交。

### 失败与恢复

检测到 rebase/merge 冲突时，保留仓库现状和命令错误，先按上方指导处理后再重试；检测到 detached HEAD 时先提示风险并等待用户确认，用户不确认则停止，确认后才继续；hook 失败、提交失败或 push 被拒时停止后续步骤并给出可复现的处理命令。不要覆盖或丢弃未提交改动。误暂存/未推送误提交按上方安全回滚说明恢复，已推送提交使用 `git revert`，不强制改写远程历史。


## 约束

<!-- BEGIN COMMON CONSTRAINTS -->
<!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 -->
<!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->

### 公共硬约束

本块由 `docs/templates/skill-common-constraints.md` 统一维护；每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块，不得在副本中改写公共规则。

- 任务需要落盘时，使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录；共享材料放入 `shared/`，Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。
- 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
- 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
- Skill 版本唯一记录在自身 `config.yaml:skill_info.version`；公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。
- `bensz-collect-bugs` 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 `~/.bensz-skills/bugs/`，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。

<!-- End of canonical common constraints. -->
<!-- END COMMON CONSTRAINTS -->

### Skill 专属约束

#### 重要约束

- **仅使用 Git**：不调用任何包管理器/构建命令
- **尊重钩子**：默认执行本地 Git 钩子；使用 `--no-verify` 可跳过
- **默认推送**：提交成功后默认自动 push；使用 `--no-push` 可跳过
- 用户明确请求本 Skill 即授权其配置中声明的提交流程；默认模式且未传入 `--no-push` 时按配置直接执行 push，审核模式按流程在提交后询问；传入 `--no-push` 时明确跳过 push，不再询问
- **不改源码内容**：命令只读写 `.git/COMMIT_EDITMSG` 与暂存区
- **安全提示**：在 rebase/merge 冲突、detached HEAD 等状态下会先提示处理/确认再继续