# Git Blame Story

> 把一个文件的修改史讲成故事——谁、何时、为何改了它。当用户说「讲讲这个文件的故事 / git-blame-story / 这个文件经历了什么 / 追溯文件历史 / 帮我看看这个文件的来龙去脉」时触发。

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

---


# git-blame-story — 文件修改史故事化

把枯燥的 `git log -- <file>` 变成一篇有温度的中文故事,帮你理解一段代码是怎么走到今天的。

## 何时触发

用户说下列任意一句时触发:

- "讲讲这个文件的故事"
- "git-blame-story"
- "这个文件经历了什么"
- "帮我追溯一下这个文件的历史"
- "这段代码是怎么来的"
- "来龙去脉"
- "帮我了解一下 <文件名>"

## 用法

### 第一步:采集文件历史素材

```bash
bash <skill>/bin/collect.sh <文件路径>
```

输出五段结构化文本:

- `META` — 文件路径、仓库名、采集时间、提交总数
- `COMMITS` — 逐条提交:hash、作者、日期、subject(含重命名追踪)
- `CONTRIBUTORS` — 贡献者排行(提交数降序)
- `TIMELINE` — 首次提交与最近提交的详情
- `CHURN` — 近期 5 次提交的增删行数趋势

### 第二步:Claude 叙述成故事

拿到素材后,按以下叙事框架输出中文故事:

---

## 叙事框架

```markdown
## <文件名> 的故事

### 诞生
（首次提交的背景:谁创建、何时、commit message 透露了什么动机?）

### 成长历程
（按时间顺序,用段落式叙述主要里程碑:重要功能新增、重构、模块迁移等。
  重点关注 message 含 refactor / move / rename / migrate 的提交。）

### 风雨时刻
（commit message 含 fix / hotfix / revert / emergency / bug 的提交,
  以及深夜(00:00–05:59)或密集修复期,推测当时遭遇了什么挑战。）

### 主要角色
（谁贡献最多?谁留下了最关键的一次提交?用贡献者排行和关键 commit 描述。）

### 现在的状态
（从最近几次提交推测:这个文件是活跃维护中、趋于稳定、还是已被遗忘?）

---

### 人物小传
（一句话:如果这个文件是个人,ta 是谁?例如:"一位经历过三次重构、身经百战的老将,如今安静守护着核心认证逻辑。"）
```

---

## 剧情推断规则

| commit message 关键词 | 推断方向 |
|----------------------|---------|
| `init` / `initial` / `add` (首次) | 诞生背景 |
| `feat` / `add` / `implement` | 功能扩张期 |
| `refactor` / `move` / `rename` / `migrate` | 架构调整,可能有大手术 |
| `fix` / `hotfix` / `bug` | 遭遇问题,推测是 bug 还是需求误解 |
| `revert` | 走了弯路,后来回头了 |
| `cleanup` / `chore` / `remove` | 瘦身或收尾 |
| 深夜提交(00:00–05:59) | deadline 压力 or 紧急修复 |
| 短时间内多条密集提交 | 紧张的攻坚期 |

---

## 硬规则

- **忠于事实**:故事里提到的人物、时间、事件必须有对应 commit 佐证;可以演绎语气和情绪,但不能凭空捏造关键情节。
- **不足时如实说**:commit message 语义不清时,描述"当时改动了 <模块>,具体动机不详",不要编造。
- **打码隐私**:commit message 或文件路径中出现疑似密钥、密码、手机号、身份证号,用 `[已打码]` 替换。
- **善意叙述**:不影射任何个人能力或品行,吐槽代码变迁但不评价人;深夜提交归因于"项目压力"而非个人习惯。
- **提交数极少时**:少于 3 条提交则说明"故事还太短,可能是新文件或历史不完整",给出已有的有限信息。
- **全中文输出**:故事全文中文;代码标识符、API 名、文件路径、commit hash 保留英文。

## 边界

- 只读 git,不写任何文件,不推送。
- 只处理 commit subject 和统计数字;不读取 diff 正文。
- 仅分析单个文件;多文件场景请分别运行 collect.sh 再汇总。
- 若文件不在 git 追踪范围内或不存在,collect.sh 会明确报错并退出。