git-blame-story

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

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

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

何时触发

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

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

用法

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

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

输出五段结构化文本:

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

第二步:Claude 叙述成故事

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

---

叙事框架

## <文件名> 的故事

### 诞生
（首次提交的背景:谁创建、何时、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 会明确报错并退出。