# Commit Assistant

> 在代码提交（svn commit / git commit）前，自动执行一套完整的审查与提交辅助流程： 1. 阅读项目 CLAUDE.md 了解项目功能模块背景； 2. 阅读编码规范约束（统一编码约束、Qt 命名规范、日志规范）； 3. 自动调用 code-review-skill 对已完成的改动进行结构化评审； 4. 输出评审报告+修改说明，提交给用户进行确认； 5. 用户确认修复完成后，输出本次修改说明。 使用时机：用户说"要提交代码了"、"帮我审一下改动"、"看看这些改动有什么问题"、"准备 commit / svn ci"、或者直接描述需要提交评审的场景时，**必须**触发本 skill。 注意：本 skill 不直接执行 commit / push 等命令，仅输出报告和提交说明，由用户手动执行提交。

- Skill: `herxinsasa/commit-assistant` (Agent Skill, multi-file: 33 files)
- Install (CLI): `npx skillmds@latest add herxinsasa/commit-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/herxinsasa/commit-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: herxinsasa (https://skillmd.com/u/herxinsasa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/herxinsasa/commit-assistant

---


# Commit Assistant — 提交助手

## 适用版本管理工具

Git 和 SVN 均可使用。工具检测优先级：

1. 如果工作目录存在 `.git/`，则视为 **Git 仓库**。
2. 否则如果工作目录存在 `.svn/` 或上层目录存在 `.svn/`，则视为 **SVN 工作副本**。
3. 如果两者都不存在，提示用户安装/初始化版本管理工具（见下方【MCP 缺失处理】）。

---

## Step 0 — 检测版本管理工具

运行以下命令检测当前目录的版本管理工具：

```bash
# 检测 Git
if [ -d ".git" ]; then echo "GIT"; fi

# 检测 SVN
if [ -d ".svn" ] || svn info > /dev/null 2>&1; then echo "SVN"; fi
```

- 如果检测到 **Git**：后续使用 `git diff --cached`、`git diff HEAD`、`git status` 等命令获取改动。
- 如果检测到 **SVN**：后续使用 `svn diff`、`svn status` 获取改动。
- 如果两者都未检测到：进入【MCP 缺失处理】。

### MCP 缺失处理

如果当前环境缺少 Git/SVN 的 MCP 支持或命令行工具：

1. **检查是否已安装 `mcp__git__*` 或 `mcp__svn__*` 工具**：
   - 如果已安装但无权限，向用户申请权限：
     > "检测到您已安装 Git/SVN MCP，但当前无执行权限。请授权后重试。"
   - 如果未安装：
     > "当前环境未检测到 Git/SVN 工具支持。建议安装方式：\n"
     > "- Git：访问 https://git-scm.com/downloads 下载安装\n"
     > "- SVN：访问 https://tortoisesvn.net/downloads.html（Windows）或使用包管理器安装\n"
     > "- 或在 Claude Code 中配置对应的 MCP Server\n"
     > "安装完成后请重新触发本 skill。"

---

## Step 1 — 阅读项目文档（前置准备）

在评审代码之前，必须先阅读项目说明，了解项目背景和模块划分。

### 1.1 阅读项目说明文档

依次查找并阅读以下文件（只要存在就读取）：

- `CLAUDE.md`（项目级，优先）
- `README.md`
- `docs/project-overview.md`
- `docs/README.md`

> 这些文档通常包含：项目名称、版本、功能模块划分、技术栈、架构说明。读取后总结项目背景，在后续评审报告中引用。

### 1.2 阅读编码规范约束

从本 skill 的 `references/` 目录读取以下规范文件：

1. `./references/统一编码约束说明.md` —— C++ 通用编码规范（命名、注释、格式化、头文件管理、类设计等）
2. `./references/Qt命名规范.md` —— Qt 控件命名、信号槽命名规范
3. `./references/日志规范约束说明.md` —— 日志格式、级别、内容、可视化分析要求

阅读后总结关键规范要点，后续评审需对照这些规范检查代码改动。

> **提示**：如果项目本身也包含 `.claude/coding-standard.md` 或类似的本地编码规范，优先以项目本地规范为准，本 skill 的规范作为补充。

---

## Step 2 — 获取代码改动

根据检测到的版本管理工具，获取待评审的改动内容。

### Git 场景

| 场景 | 命令 |
|------|------|
| 已暂存（staged） | `git diff --cached` |
| 未暂存（unstaged） | `git diff HEAD` |
| 已提交未推送 | `git diff origin/$(git branch --show-current)...HEAD` |
| 指定 commit | `git show <commit-hash>` |
| 指定范围 | `git diff <from>..<to>` |

**默认行为**：先执行 `git status` 查看当前状态，然后询问用户要评审哪一部分改动（已暂存/未暂存/全部）。

> **新增文件检测**：在 `git status` 输出中，检查是否有 `Untracked files:` 下列出的新文件未被 `git add` 纳入暂存。如有，记录文件列表，在后续 Step 4 『依赖完整性』检查项中提示用户是否需要 `git add`。

### SVN 场景

| 场景 | 命令 |
|------|------|
| 本地修改 | `svn diff` |
| 指定文件/目录 | `svn diff <path>` |
| 指定版本范围 | `svn diff -r <rev1>:<rev2>` |

**默认行为**：执行 `svn status` 查看本地修改状态，然后执行 `svn diff` 获取改动内容。

> **新增文件检测**：在 `svn status` 输出中，检查是否有 `?`（未版本化）状态的新增文件。如有，记录文件列表，在后续 Step 4 『依赖完整性』检查项中提示用户是否需要 `svn add`。

---

### 2.1 新增文件 add 状态检查

在获取 diff 内容的同时，执行 `git status` 或 `svn status` 检查是否存在**未纳入版本管理的新增文件**：

| 工具 | 未纳入特征 | 参考命令 |
|------|-----------|---------|
| Git | `Untracked files:` 下列出，状态 `??` | `git status --short` |
| SVN | 状态列显示 `?` | `svn status` |

**处理流程**：

1. **列出未 add 文件**：从 status 输出中提取所有未纳入的新增文件路径。
2. **向用户确认**：

   ```
   ⚠️ 检测到以下新增文件尚未纳入版本管理，提交时将不会被包含：
   - <文件1>
   - <文件2>

   是否执行 add 操作将上述文件纳入版本管理？（是/否）
   ```

3. **根据用户回复处理**：
   - **用户确认（是）**：执行 `git add <文件列表>` 或 `svn add <文件列表>`，然后回到本步骤重新获取完整 diff（此时新增文件将包含在 diff 中供评审）。
   - **用户拒绝（否）**：记录该情况，在 Step 4 提交专项检查的「依赖完整性」中标记为 ⚠️，继续后续评审流程。

---

## Step 3 — 调用 code-review-skill 进行评审

将 Step 1 中获取的项目背景、编码规范要点，以及 Step 2 中获取的 diff 内容，传递给已存在的 `code-review-skill`。

### 调用方式

使用 `Skill` 工具调用 `code-review`，或参考 `./references/code-review-skill/SKILL.md` 的评审流程手动执行。

**调用时必须附带上下文的参数**：

1. **项目背景**：项目名称、功能模块、技术栈（来自 Step 1.1）。
2. **编码规范要点**：来自 Step 1.2，summary 成 5-10 条最关键的规范要求。
3. **Diff 内容**：来自 Step 2。

### 评审范围要求

除了 code-review-skill 自带的通用评审维度外，还需**额外关注**以下与提交场景相关的检查项：

| 检查项 | 说明 |
|--------|------|
| 调试代码清理 | 是否遗留 `printf`、`std::cout`、临时测试代码、死代码 |
| 废弃文件处理 | 是否有应删除但未删除的废弃文件（通过 `git status` 或 `svn status` 的 `?`/`!` 状态识别） |
| 依赖完整性 | 新增文件是否被正确纳入版本管理；删除文件是否被正确标记 |
| 敏感信息泄漏 | diff 中是否包含密码、密钥、IP、内部 URL、个人路径等 |
| 配置文件变更 | 配置文件改动是否合理，避免将个人本地配置提交 |
| 二进制/大文件 | 是否误提交了编译产物、日志文件、大数据文件 |

---

## Step 4 — 输出评审报告 + 等待用户确认

将 code-review-skill 的评审结果整合为一份完整的《提交评审报告》，格式如下：

```markdown
# 提交评审报告 — <项目名称>

## 一、项目背景
（来自 Step 1.1 的 project context，2-3 句话）

## 二、改动概览
（统计改动：新增 X 文件、修改 Y 文件、删除 Z 文件、行数变化等）

## 三、通用评审结果
（来自 code-review-skill 的输出，按 Critical / Warning / Suggestion 分级展示）

## 四、提交专项检查
| 检查项 | 状态 | 说明 |
|--------|------|------|
| 调试代码清理 | ✅ / ⚠️ / ❌ | 通过 / 发现遗留 / 需处理 |
| 废弃文件处理 | ✅ / ⚠️ / ❌ | 通过 / 发现未清理 / 需处理 |
| 依赖完整性 | ✅ / ⚠️ / ❌ | 通过 / 新增文件未 add / 删除文件未标记删除 |
| 敏感信息泄漏 | ✅ / ❌ | 通过 / 发现问题 |
| 配置文件变更 | ✅ / ⚠️ | 通过 / 需确认 |
| 二进制/大文件 | ✅ / ⚠️ | 通过 / 发现异常 |

## 五、修改建议清单
（为每条建议分配编号，每条包含：编号 + 文件位置 + 问题 + 建议修改方式）

例如：
1. `src/main.cpp:45` — 函数超过50行，建议拆分为 `initConfig()` 和 `startWorker()`
2. `src/utils.h:12` — 头文件缺少 `#pragma once`
3. `src/logger.cpp:88` — 遗留调试日志 `std::cout`，应移除或改用 LOG_DEBUG
```

## 六、评审结论

**评审结论以结论标题形式展示，不使用复选框，避免视觉误解。**

- **结论：通过** — 无 Critical/Warning 问题，代码符合提交标准。
- **结论：有条件通过** — 存在 Warning 级别问题，建议修复后再提交。
- **结论：不通过** — 存在 Critical 级别问题，必须修复后才能提交。

---

### 评审后处理流程

根据六评审结论，分两种路径处理：

| 评审结论 | 后续流程 |
|----------|----------|
| **通过** | 直接进入【Step 5 — 确认提交】，询问用户是否立即执行提交 |
| **有条件通过 / 不通过** | 进入【Step 4.5 — 处理方案选择】，由用户决定如何处理修改建议 |

> **注意**：评审报告输出后，根据评审结论自动分流，不自动执行任何修复或提交操作。


---

## Step 4.5 — 处理方案选择（有条件通过 / 不通过时）

当评审结论为**有条件通过**或**不通过**时，向用户展示以下处理方案并等待选择：

```
评审发现以下问题需处理，请选择后续操作：

A. 采纳修改建议 — 按编号指定需自动修复的项，例如输入 "A 1,3,5" 或 "A 1-3,7"
B. 忽略修改建议 — 跳过修复，直接生成本次提交说明
C. 自行修改 — 用户手动修复代码，完成后回复 "已修复" 以继续
D. 其他 — 自定义输入需求或疑问

请输入选项（A/B/C/D）：
```

### 选项处理逻辑

| 用户输入 | 处理逻辑 |
|----------|----------|
| `A` / `采纳` / `A 1,3,5` | 解析用户指定的编号，仅自动修复对应建议项。修复完成后重新运行 Step 3（code-review）确认问题是否解决 |
| `B` / `忽略` / `跳过` | 跳过修复，直接进入 Step 6 生成本次提交说明 |
| `C` / `自行修改` / `自己改` | 告知用户："请自行修改，完成后回复 '已修复' 或 '继续'，我将重新评审。" 然后等待用户后续输入 |
| `D` / 任意自定义描述 | 根据用户描述执行对应操作（如额外检查、解释某条建议、生成特定代码片段等） |
| 无输入或模糊输入 | 再次提示用户选择，或询问 "您想采纳哪几条修改建议？请回复编号" |

### 自动修复建议的实现要求

当用户指定了要修复的建议编号时：

1. **读取对应建议的详细信息**（文件路径、行号、问题描述、建议修改方式）。
2. **定位到具体文件和位置**，读取相关代码上下文。
3. **执行修改**：使用 `Edit` 工具应用修复。
   - 优先采用最安全的修复方式（如添加 `#pragma once`、删除调试日志、重命名变量等）。
   - 如果修复涉及较大重构（如拆分函数），先向用户展示修改方案，确认后再执行。
4. **修复完成后**：
   - 报告修复了哪些项、哪些项因冲突/复杂度需要用户手动处理。
   - 询问用户："是否重新运行评审确认修复结果？"
   - 如果用户确认，回到 Step 3 重新 diff + 评审。
   - 如果用户认为无需重审，直接进入 Step 6 生成本次提交说明。

> **原则**：只修复用户明确指定的建议编号，不擅自修复用户未提及的项。


---

## Step 5 — 确认提交 / 生成本次修改说明

当评审**通过**或用户完成修复后，执行本步骤。

### 5.1 通过场景（评审结论为通过）

直接输出提交前确认清单和本次修改说明，要求输出内容精简准确，不需要写具体值或代码：

```markdown
评审通过，本次改动可直接提交。

---
## 提交前确认清单
- 修改文件：<文件列表>
- 无新增/删除文件（如有则列明）
- 无编译产物、IDE 缓存、敏感信息
- 无未跟踪文件需要纳入版本管理

---
## 本次修改说明
【<项目名称><版本号>】
新增：
- <新增项1>

修改：
- <修改项1>

删除：
- <删除项1>

---
## 例子
【DF2.6.0_tyreGuide】
新增
- SD卡健康检查：引导周期结束时对SD执行读写校验，失败时以警告形式通知前端
	- 新增错误码
    - 运维模块注册通知处理
- 模板配置完整性检查

修改
- 图片导出路径重构
- 关闭授权管理调试开关
```

**询问用户是否确认提交**，用户确认后本次 skill 流程结束。

### 5.2 修复后场景

当用户确认已按评审报告修复完毕，并明确说"帮我生成提交说明"、"写一下 commit message"、"生成修改日志"时执行。

#### 生成规则

1. **项目名称**：从 CLAUDE.md / README.md 中提取，若找不到则使用工作目录名称。
2. **版本号**：优先从项目文档提取，如 `【DF调焦软件1.0】`。
3. **分类统计**：
   - **新增**：本次新增的文件/模块/功能
   - **修改**：本次修改的文件/模块/功能
   - **删除**：本次删除的文件/模块
4. **简洁明了**：每条说明控制在 15 字以内，不展开技术细节。

#### 输出格式模板

```markdown
【<项目名称><版本号>】

新增：
- <新增功能/模块1>
- <新增功能/模块2>

修改：
- <修改内容1>
- <修改内容2>

删除：
- <删除内容1>
```

如果没有某类改动，则不显示该类标题（例如没有删除则不显示"删除："）。

### Git Commit Message 版本

如果用户需要直接用于 `git commit` 的 message，额外输出一个精简版：

```
feat(<模块>): <简短描述>
新增:
- xxx
修改:
- xxx
删除:
- xxx
```

---

## 附录：参考文件索引

| 文件 | 用途 |
|------|------|
| `./references/统一编码约束说明.md` | C++ 通用编码规范 |
| `./references/Qt命名规范.md` | Qt 项目命名与信号槽规范 |
| `./references/日志规范约束说明.md` | 日志输出规范要求 |
| `./references/code-review-skill/SKILL.md` | 代码评审 Skill 入口 |

---

## 触发关键词

当用户说出以下任何内容时，应触发本 skill：

- "帮我审一下改动"
- "看看这些改动有什么问题"
- "准备 commit"
- "准备 svn ci"
- "要提交了"
- "提交前评审"
- "生成提交说明"
- "写一下 commit message"
- "帮我整理一下这次改了什么"
- 任何与"提交"、"commit"、"ci"、"改动评审"相关的请求