| 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 会明确报错并退出。
