Smart Commit

智能 Commit Message 生成器 —— 基于 diff 分析自动生成规范的 commit message。

设计哲学

遵循「确定性用代码，模糊性用 LLM」原则（详见 ~/.codebuddy/skills/dev-flow/references/core-principles.md §19）。

用途

基于代码增量 Diff，自动生成符合 Conventional Commits 规范的 commit message。 同时输出精简版和标准版两套 commit body，由用户选择使用。

使用场景

• 用户请求生成 commit message / 提交信息
• 用户说"帮我提交"/"smart commit"/"生成提交"
• dev-flow 流程中「Commit Message 生成」步骤调用

关键资源

Commit Message 格式规范

Header 格式

{action}: {简短描述}

不使用 scope，header 中不包含 (scope) 部分。

Action 决策规则（LLM 模糊判断）

LLM 基于 diff 内容 + 用户描述判断 action，参考以下映射：

⚠️ 禁止反模式：用户未提供描述时，LLM 基于 diff 实际内容判断 action，不得一律用 chore。

Commit Body 双模式

始终同时生成两套 body，分开展示供用户选择。

精简版 Body

每个改动模块一行概述，格式：- {动作} {模块/文件简称}

- 新增批量导出限制配置组件
- 修改账户设置页面集成新入口
- 新增权限策略查询 Hook

标准版 Body

详细说明「改了什么」+「为什么改/改动效果」，格式：- {动作} {具体文件/模块}，{原因或效果}

- 新增 FeatureToggle 组件，支持按成员维度配置功能权限，包含成员搜索和批量选择功能
- 修改 SettingsPage 页面，在安全设置区块集成功能限制入口，使用条件渲染控制可见性
- 新增 useFeaturePolicy Hook，封装权限策略的 CRUD 操作和本地缓存逻辑

Body 生成规则（LLM 模糊判断）

1. 按改动文件/模块分组，每组用 - 开头
2. 按重要性排序（核心逻辑 > 辅助功能 > 配置/样式）
3. 每条控制在一行内
4. body 与 header 之间必须有一个空行

工作流程

步骤 1：获取代码改动信息（脚本化）

~/.codebuddy/skills/smart-commit/scripts/git-diff-summary.sh

脚本自动：

• 优先检查 staged，无暂存改动则降级到工作区
• 默认输出 full diff，超过 200 行（阈值在 YAML）自动降级为 --stat
• 元信息（mode/line_count/source）写到 stderr 便于 LLM 感知

阈值需要调整？改 config/action-map.yaml 的 diff_threshold.full_diff_max_lines。

步骤 2：生成简短描述（LLM 模糊判断）

情况 A：用户提供了自定义描述 → 直接使用，跳过 diff 分析 情况 B：用户未提供描述 → 基于 diff 内容 AI 生成，规则：

步骤 3：LLM 决定 action

基于 diff 内容 + 描述，按「Action 决策规则」中的映射表判断 action。合法 actions 白名单见 config/action-map.yaml。

步骤 4：LLM 生成双模式 body

基于 diff 内容分别生成精简版和标准版 body，遵循「Commit Body 双模式」规则。

步骤 5：二段式展示

生成后按「精简版 → 标准版」二段式展示。

🔴 可复制容器（强制）：每个版本的 commit message 主体必须用「text 围栏代码块」包裹（三反引号 + text），让 IDE 渲染出复制按钮。 标题层（📝 汇总 + 📋/📄 子标题）用加粗强调，不带任何分割线；仅 commit message 主体入代码块。

📝 Commit Message 已生成：

**📋 【精简版】**

```text
feat: 新增暗色模式开关

- 新增 ThemeToggle 组件
- 修改全局样式变量
- 新增主题持久化 Hook
```

**📄 【标准版】**

```text
feat: 新增暗色模式开关

- 新增 ThemeToggle 组件，支持一键切换亮色/暗色主题，含过渡动画
- 修改全局 CSS 变量，将硬编码颜色值替换为 CSS 自定义属性以支持主题切换
- 新增 useTheme 自定义 Hook，封装主题状态管理和 localStorage 持久化逻辑
```

步骤 6：用户交互决策

展示后弹出交互选项（使用 ask_followup_question）：

步骤 7：自动提交（仅当用户选择「自动提交」选项时）

⚠️ 默认不执行任何 git 操作，仅在用户明确选择「📦 自动提交」选项时执行：

# 0. 提交前身份检查（强制，禁止跳过）
git config user.name
git config user.email
git log -1 --format='%an | %ae'   # 仓库最近一次提交作者（预期身份参照）
git branch --show-current          # 确认当前分支

# 1. 暂存所有改动
git add .

# 2. 使用多行 commit（header + body）
git commit -m "header行" -m "body第1行" -m "body第2行" ...

# 3. 提交成功后展示结果
git log --oneline -1

身份一致性校验（红线）：

1. 实测 user.name/user.email 与仓库历史作者（git log -1）或调用方提供的预期身份（如 dev-comp 工作上下文 git_identity）比对
2. 不一致（如全局公司身份误用于开源仓库）→ 🔴 拦截提交，弹 ask_followup_question 向用户呈现「实测值 vs 预期值」，选项：修正 local config 后重试 / 确认改用实测值继续 / 取消提交；未经用户确认不得 git commit
3. 仓库无历史提交时，以调用方提供的预期身份为准，无预期身份则默认采用实测值并明确告知用户

❌ 禁止自动执行 git push，push 始终由用户自行决定。

异常兜底

无代码改动时

git-diff-summary.sh 的 stderr 会输出 {"mode":"empty",...}，此时提示用户先进行代码修改，或手动提供描述信息。

脚本不可用时（兜底）

如果脚本因任何原因无法执行（权限、路径不存在等），LLM 应：

1. 优先告知用户脚本错误，建议重装/修复 Skill
2. 不得回退到自己心算 diff 内容——应提示用户使用 git diff --cached 或 git diff 获取

完整示例

示例 1：用户提供描述

用户：帮我生成 commit message，描述：新增暗色模式

AI 执行：
1. 调用 scripts/git-diff-summary.sh → 拿到 file list / stat / diff
2. 使用用户提供的描述："新增暗色模式"
3. LLM 判断 action → feat（新增功能）→ 校验在白名单内
4. LLM 基于 diff 生成精简版/标准版 body
5. 二段式展示 + 用户交互

示例 2：用户未提供描述

用户：帮我生成当前 diff 的 commit message

AI 执行：
1. 调用 scripts/git-diff-summary.sh → 拿到 diff
2. LLM 基于 diff 生成简短描述："修复 marketplace 生成脚本 YAML 多行描述解析失败"
3. LLM 判断 action → fix（修复 bug）
4. LLM 基于 diff 生成精简版/标准版 body
5. 二段式展示 + 用户交互

最终输出形态（标题层用加粗强调，无分割线；commit message 主体在 ```text 代码块内，IDE 渲染复制按钮）：

📝 Commit Message 已生成：

**📋 【精简版】**

```text
fix: 修复 marketplace 生成脚本对 YAML 多行描述解析失败的问题

- 修复 YAML 多行字段解析逻辑
- 调整 description 字段读取容错
```

**📄 【标准版】**

```text
fix: 修复 marketplace 生成脚本对 YAML 多行描述解析失败的问题

- 修复 generate-marketplace.js 中的 YAML 多行字段解析逻辑
- 调整 description 字段读取容错，遇到非字符串值时回退到默认描述
```