SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场code-history

code-history

编程与开发

查看项目

更新于 10-15 09:31

技能介绍

用途

Code History 用于追溯特定代码随时间的演变——它何时被引入、如何变化以及为什么变化。

适用场景：

  • 理解某个函数或方法随时间的演变
  • 追踪某个特定代码模式何时被引入或修改
  • 查找哪个提交/PR 引入、修改或删除了某段代码
  • 调查代码为何变更以及每次修订的动机

不适用场景：

  • 用户想要修改代码（本技能为只读）
  • 用户想要没有特定目标的通用 git log
  • 用户只需要针对单行最后作者的 git blame
  • 用户只想查看某个特定提交的 diff（git show 已足够）

本技能为只读。绝不修改任何文件或运行写入命令。

主要能力

该技能通过一组工具与命令来收集和分析代码历史：

用途 工具 命令 / 模式
搜索代码模式历史 Bash git log -p --all -S '<pattern>'
追踪函数行历史 Bash git log -L :'<func>':<file> --no-patch
追踪文件历史 Bash git log --follow --oneline -- <path>
查找模式位置 Grep 在代码库中搜索模式
读取文件上下文 Read 读取周边代码以理解
将提交关联到 PR Bash gh pr list --search '<sha>' --state all

使用方式

第 1 步：识别目标

解析 $ARGUMENTS 以确定要追踪的内容：

输入类型 示例 检测方式
代码模式 user["type"] == "ADMIN" 包含运算符、引号、括号
函数/方法名 ensure_valid_state 单个标识符，无运算符
文件路径 src/auth/services.py 包含 / 或文件扩展名
模糊 其它 请用户澄清

如果输入是函数名，使用 Grep 搜索定义模式来定位它所属的文件。

第 2 步：收集历史

首先测量历史规模：

git log --oneline --all -S '<pattern>' | wc -l

然后选择合适策略：

  • 如果提交数 ≤ 30：使用 git log -p --all -S '<pattern>' 读取完整历史
  • 如果提交数 > 30：用 -- <file_path> 或 --since="1 year ago" 缩小范围。如果仍然很大，聚焦最近 20 个提交，并注明较早历史已被截断。

按目标类型：

  • 代码模式：git log -p --all -S '<pattern>'
  • 函数：补充 git log -L :'<function_name>':<file_path> --no-patch --oneline
  • 文件：git log --follow --oneline -- <file_path>

第 3 步：关联到 PR

对每个相关提交，提取 PR 引用：

  • 从提交消息中：解析 PR 编号（如 (#123)、Merge pull request #123）
  • 通过 gh CLI（如果可用）：gh pr list --search '<commit-sha>' --state all --json number,title,url --limit 1
  • 如果 gh 未安装或失败，仅依赖提交消息解析并注明。

第 4 步：分析变更

对历史中的每个提交进行分类：

维度 取值
变更类型 Added / Modified / Refactored / Moved / Deleted / Restored
意图 Bug fix / Feature / Refactoring / Performance / Cleanup / Migration
范围 Targeted（提交直接针对此代码）/ Incidental（更大变更的副作用）

从提交消息、PR 标题和 diff 上下文中确定意图。如果意图不明确，明确说明而不是猜测。

第 5 步：输出

时间线表格：

## Change History: `<target>`

| # | Date | Author | Commit | PR | Change |
|---|------|--------|--------|----|--------|
| 1 | YYYY-MM-DD | name | `abcdef1` | #N title | Added — initial implementation |
| 2 | YYYY-MM-DD | name | `abcdef2` | #N title | Modified — added validation |
| 3 | YYYY-MM-DD | name | `abcdef3` | #N title | Refactored — extracted to util |

详细分析（针对每个重要变更）：

  • 变更前后 diff 摘要
  • 变更意图（基于提交消息/PR）
  • 功能影响——行为或接口发生了什么变化

洞察（仅在历史中有直接证据支持时）：

  • 总结演变轨迹（例如“从 10 行辅助函数开始，经过 5 个 PR 成长为 80 行类”）
  • 标记历史中发现的具体问题：被回滚的变更、对同一区域的重复修补、提交消息与实际 diff 之间的范围不匹配
  • 如果同一提交触及多个相关位置，连接跨文件的相关变更

适用场景

  • 代码考古与理解遗留代码
  • 代码审查前的背景调查
  • 定位引入 bug 或行为的提交
  • 理解某段代码的设计决策历史

限制

  • 本技能为只读，不修改任何文件或运行写入命令
  • 不适用于通用 git log、单行 git blame 或查看单个提交 diff 的场景
  • 当历史提交数超过 30 时可能需要缩小范围或截断较早历史
  • 如果 gh CLI 不可用，PR 关联仅依赖提交消息解析
  • 意图不明确时会明确说明，而非猜测