Git 安全操作助手 (git-merge-assistant)

核心原则

本 Skill 的核心目标是让 Git 操作安全、可追溯、可视化。

• 安全第一：所有写操作（add/commit/merge/rebase/push）前必须请求用户确认
• 可追溯：操作前保存 HEAD hash 和完整 diff，提供回退命令
• 可视化：每次操作后生成操作报告（优先 HTML，降级为 Markdown）
• 最小提交：每次提交只包含一个逻辑变更
• 不盲目自动化：复杂冲突（同一区域被双方修改）不自动解决，提示用户手动介入

支持的交互模式

注意：push 模式仅在用户明确要求时执行。默认行为是只提交不上传。

10 步工作流

必须严格按照以下 10 个步骤顺序执行。

Step 0: 模式识别与用户确认

1. 根据用户描述判断操作模式。如果不确定，列出可能模式让用户选择。
2. 如果是合并/变基操作，确认源分支和目标分支。
3. 如果是提交类操作，列出当前所有变更文件，说明哪些是目标文件、哪些会被暂存。
4. 关键确认：在执行任何写操作之前，展示将要执行的命令并请求用户确认（y/n）。

Step 1: 预检查（Pre-flight Checks）

在执行操作前，检查以下风险并汇总警告：

# 检查是否有未保存的 IDE 临时文件
git ls-files --others --exclude-standard | grep -E "\.(swp|swo|~)$" && echo "⚠️ 发现未保存的临时文件"

# 检查是否有大文件（>1MB）
find . -type f -size +1M ! -path "./.git/*" | head -5 && echo "⚠️ 存在大文件，建议使用 Git LFS"

# 检查敏感信息（密码、密钥等）
git diff --cached | grep -iE "password|secret|api_key|token" && echo "⚠️ 发现敏感关键词，请确认是否应提交"

汇总警告信息并询问用户是否继续。如果用户选择否，停止操作。

Step 2: 暂存非目标文件 + 保存快照

目标文件识别逻辑：

• commit 模式：目标 = 所有已跟踪文件的变更（git diff --name-only 列出的文件），未跟踪文件不自动提交
• commit-file 模式：用户明确指定的文件为目标，其余变更暂存
• merge/rebase 模式：先处理工作区变更，防止脏工作区干扰

执行暂存（包含未跟踪文件）：

git stash push -u -m "stash-before-<operation>-<timestamp>"

保存快照：

# 记录当前 HEAD（供后续回退使用）
git rev-parse HEAD > .git-pre-operation-hash
# 保存工作区完整 diff（相对 HEAD）
git diff > .git-operation-snapshot.diff

记录操作前 HEAD hash，用于报告中生成回退命令。

Step 3: 拉取远程更新

git fetch origin

• 对 merge/rebase：确保源分支和目标分支的远程状态最新
• 对 push：先 fetch，检查是否落后于远程。若落后，提示先 pull/merge
• 对 commit：检查是否有远程更新需要先合并

Step 4: 分析差异

执行以下命令并向用户呈现结果：

git status --short
git diff --stat
git diff

分析要点（告知用户）：

• 变更文件列表及类型（新增/修改/删除）
• 变更行数统计
• 是否有调试代码、临时注释等不应提交的内容
• 如果是合并模式，分析两个分支的差异范围

Step 5: 执行操作（需用户确认）

展示将要执行的核心命令，请求用户确认。只有用户输入 y/yes 才执行。

示例：

即将执行：
  模式：commit
  命令：git add -u && git commit -m "<待编辑消息>"
  目标文件：src/main.py, src/utils.py
  将暂存非目标文件：tests/test_main.py
是否继续？(y/n)

不同模式的命令：

只提交不上传：除非用户明确要求 push，否则不执行任何推送操作。

Step 6: 冲突检测与处理

执行 merge/rebase 后，检查冲突：

git diff --name-only --diff-filter=U   # 列出冲突文件

若无冲突：继续 Step 7。

若有冲突：

1. 不自动解决。对每个冲突文件，显示冲突区块（<<<<<<< 标记的区域）。
2. 生成冲突报告：
• 冲突文件列表
• 每个冲突文件中的冲突行号及双方内容
• 建议：保留本地 / 保留远程 / 手动合并
3. 备份原始冲突文件：

```bash

mkdir -p .git-conflict-backup-$(date +%s)

cp .git-conflict-backup-*/

```

1. 提示用户手动处理：

```

检测到 2 个冲突文件。请手动编辑解决，完成后输入 'done' 继续。

编辑命令：vim src/login.py

```

1. 等待用户输入 done，然后验证所有冲突标记已解决（无 <<<<<<< 残留）。
2. 执行 git add 标记已解决。
3. 对于 merge 模式，继续 git commit（生成默认合并消息）；对于 rebase，执行 git rebase --continue。

Step 7: 提交消息生成与用户确认

这是用户特别要求的步骤 — 不直接提交，先生成消息给用户确认。

1. 根据变更文件列表和 diff 统计，生成一个默认消息模板：

• 单文件变更：[] 修改了 <文件名>
• 多文件变更：[] 更新了 <模块名> 相关功能

1. 展示消息给用户审查：

```

请审阅提交消息（第一行不超过 72 字符）：

————————————————————————————————

[fix] 修复登录验证逻辑

详细说明（可选）：

• 修复了空密码导致的崩溃

————————————————————————————————

输入 'y' 确认提交，输入 'n' 取消提交，或直接输入新的提交消息：

```

1. 用户选择：
• y/yes → 执行 git commit -m "<消息>"
• n/no → 撤回提交（不执行 commit，恢复到操作前状态），告知用户已取消
• 输入其他内容 → 使用用户输入的内容作为提交消息，然后执行 commit

1. 提交消息推荐格式（不强求，作为建议）：

```

(): <简短描述>

<详细说明（可选）>

```

Step 8: 恢复暂存文件

如果 Step 2 中暂存了非目标文件，现在恢复：

git stash pop --index

如果恢复时有冲突（暂存的文件与当前工作区有重叠），提示用户手动解决。

Step 9: 生成操作报告

优先尝试 HTML 报告：

如果 scripts/generate_git_report.py 存在且 Python3 可用，生成 HTML 报告：

python3 <skill-path>/scripts/generate_git_report.py \
  --repo-path <repo-path> \
  --output <report-path>/git-report-<timestamp>.html \
  --operation "<operation>" \
  --commit-range <start-hash>..<end-hash>

降级方案（Markdown）：

如果 HTML 脚本不可用或执行失败，自动生成 Markdown 格式报告（输出到控制台或保存为 .md 文件）：

# Git 操作报告
- 操作时间：2025-05-25 10:30:00
- 操作类型：merge (feature/login → master)
- 操作前 commit：a1b2c3d
- 操作后 commit：d4e5f6g

## 变更统计
| 文件 | 新增行 | 删除行 |
|------|--------|--------|
| src/login.py | +15 | -3 |

## 冲突处理
- 冲突文件：无

## 回退命令
如需回退到此操作前状态，执行：
  git reset --hard a1b2c3d
  git stash pop   # 若之前有 stash

报告必须包含回退命令，以操作前保存的 HEAD hash 生成回退指南。

常用场景完整示例

场景一：安全提交（只提交不上传）

用户：帮我提交代码
助手：
  1. 模式：commit
  2. 当前变更文件：src/main.py(+42-10), src/utils.py(+5-2), tests/test_main.py(+20-0)
     目标文件：所有已跟踪文件的变更
     暂存文件：无（所有变更都是目标）
  3. 预检查：无警告
  4. 暂存并保存快照...
  5. fetch origin... 已是最新
  6. 差异分析：3 个文件被修改，共 +67 -12 行
  7. 即将执行：git add -u && git commit -m "<待编辑>"
     是否继续？y
  8. 请编辑提交消息：[feat] 增加用户认证模块
     确认提交？(y/n/编辑) y
  9. 提交成功。恢复暂存...
  10. 生成报告（含回退命令）...
     操作完成。是否推送？(y/n) n

场景二：合并分支并遇到冲突

用户：把 feature/payment 合并到 develop
助手：
  1. 模式：merge，源=feature/payment，目标=develop
  2. 预检查：无警告
  3. 暂存当前工作区（如有）...
  4. fetch origin
  5. 分析差异：两分支共有 3 个文件可能冲突
  6. 即将执行：git checkout develop && git merge feature/payment
     是否继续？y
  7. 检测到冲突：src/payment.py 第 45-52 行
     冲突内容：if amount > 100 (HEAD) vs if amount >= 100 (feature/payment)
     已备份原始冲突文件到 .git-conflict-backup-xxx/
     请手动解决冲突，完成后输入 'done'。
     编辑命令：vim src/payment.py
  8. 用户完成，验证无冲突标记，执行 git add
  9. 生成合并提交消息，确认后提交
  10. 恢复暂存...
  11. 生成报告（含冲突详情和回退命令）

报告脚本

本 Skill 捆绑了 HTML 报告生成脚本。当需要生成报告时，读取并执行 scripts/generate_git_report.py。

脚本路径相对于 SKILL.md：scripts/generate_git_report.py

脚本用法

python3 <skill-path>/scripts/generate_git_report.py \
  --repo-path /path/to/repo \
  --output /path/to/report.html \
  --operation "merge: feature/login -> master" \
  --commit-range HEAD~3..HEAD \
  --pre-hash a1b2c3d

参数说明：

• --repo-path：Git 仓库路径（必填）
• --output：输出 HTML 文件路径（必填）
• --operation：操作描述（必填）
• --commit-range：要展示的 commit 范围，如 HEAD~3..HEAD（可选）
• --conflict-files：冲突文件列表，逗号分隔（可选）
• --pre-hash：操作前 HEAD hash，用于生成回退命令（可选）

降级方案

如果 Python3 或脚本不可用，使用以下命令生成 Markdown 报告：

{
  echo "# Git 操作报告"
  echo "- 操作：<operation>"
  echo "- 时间：$(date)"
  echo ""
  echo "## 提交记录"
  git log --oneline -5
  echo ""
  echo "## 文件变更"
  git diff --stat HEAD~1..HEAD
  echo ""
  echo "## 回退命令"
  echo "git reset --hard <pre-hash>"
  echo "git stash pop"
} > report.md

安全回退指南

每次操作报告中都会提供回退命令。用户也可主动要求回退：

用户：回退上一次操作
助手：根据保存的快照，执行以下命令即可恢复：
  git reset --hard $(cat .git-pre-operation-hash)
  git stash pop

建议用户定期清理 .git-pre-operation- 和 .git-conflict-backup- 文件。