mcpField
C
commit-archaeologist

commit-archaeologist

github.com/shubhamsaboo开发143.3k531 次安装1 周前更新
代码仓库

关于 commit-archaeologist

commit-archaeologist 是供开发者追溯文件或代码片段由来的本地 Skill。它结合 Git 历史、共同变更文件和提交信息线索，且不会修改仓库。

主要功能

  1. 01追溯文件和行范围历史
  2. 02识别引入提交及后续修改
  3. 03查找反复共同变更的文件
  4. 04提取提交信息中的意图线索
  5. 05离线只读运行

适用场景

  1. 01了解代码片段存在的原因
  2. 02重构前核对历史约束
  3. 03调查变通方案或反常设计

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shubhamsaboo/awesome-llm-apps --skill commit-archaeologist

安装后在 Claude Code 中输入/commit-archaeologist确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
references/
reading-git-history.md
scripts/
archaeologist.py

详细介绍

Commit Archaeologist

git blame 会指出最后修改某一行的人。此技能会还原该行存在的原因。它会追溯文件或当前行范围的本地 git 历史，识别其来源和后续编辑，找出反复与其一同变更的文件，并从提交消息中提取意图线索。

所有操作都在本地进行。不会发起网络调用、使用 API 密钥或写入仓库。

适用场景

  • 用户询问某个代码块、函数或文件为何存在
  • 用户想知道是谁引入了代码，以及之后有哪些改动
  • 重写或重构需要了解历史约束和变更风险
  • 某个变通方案、临时分支或令人意外的设计选择需要背景信息

不适用场景

  • 用户只想查看原始 blame 输出或提交列表
  • 任务是压缩、删除或重写 git 历史
  • 仓库位于远程，且尚未克隆到本地
  • 问题涉及整个项目的架构，而非某个文件或代码区域

收集目标信息

获取仓库路径和受版本控制的文件路径。用户提到当前代码块或函数时，使用行范围。如果缺少其中任一路径，只询问缺失的值。不要扫描同级仓库。

路径应为相对于仓库的路径，并使用正斜杠。行范围使用当前行号，且包含起止行，例如 40-72。

执行挖掘

从此技能目录运行：

python3 scripts/archaeologist.py /path/to/repo src/cache.py --lines 40-72 --json

如需查看文件的完整历史，请省略 --lines：

python3 scripts/archaeologist.py /path/to/repo src/cache.py --json

该脚本为只读。指定范围时，它会使用 git line-log；未指定范围时，它会跟踪重命名并读取文件历史。它还会通过 blame 读取当前的代码归属信息。如果脚本拒绝某个路径或范围，请报告该错误，并要求用户提供修正后的目标。

解读 JSON 之前，请先阅读 references/reading-git-history.md。其中的置信度规则可避免将 blame 归属、相关性和提交消息线索误当成确定结论。

阅读 JSON

  • region：规范化后的仓库、当前及历史路径、模式、范围和共同变更阈值
  • introduced_by：所选历史中最早的提交
  • timeline：按从早到晚排序的提交，包含类别、变更文件和检测到的重命名
  • co_changed：在足够多的所选提交中与目标一同出现的文件
  • authors：当前 blame 行和历史提交计数，二者分开列出
  • intent_signals：从提交消息中发现的问题引用、回退、变通方案、临时标记和未完成工作标记

信号列表为空，表示提交消息没有说明原因。这不代表该变更没有原因。

撰写报告

将 JSON 整理成一份简短的“这段代码为何存在”报告：

  1. 结论。 用一到两句话说明最可能的解释，并标注置信度：高、中或低。
  2. 起源。 列出引入该代码的哈希、日期、作者、主题，以及有助于说明最初目的的相关文件。
  3. 时间线。 按从早到晚的顺序排列。不会改变整体脉络的机械性编辑可以合并说明，但须保留回退、修复和变通方案。
  4. 关联文件。 将反复共同变更视为耦合线索进行说明。不要把 changed_files 中只出现一次的文件当成依赖项。
  5. 意图证据。 引用简短的提交主题或信号词。超出这些事实的结论须标注为推断。
  6. 变更风险。 指出编辑前值得检查的约束、关联文件和未解决的临时选择。

在正文中使用短哈希，但保留足够字符以便识别。除非用户要求，否则不要输出完整 JSON。

证据规则

  • 当前的 blame 归属不能证明最初的作者身份。
  • 最早选取的提交是该区域的引入提交，但不一定是该文件的首次提交。
  • 反复共同变更表明可能存在耦合，但不能证明存在依赖关系。
  • 提交分类是基于提交消息的启发式判断，并非经过验证的问题类型。
  • “Temporary”和“workaround”是强烈的意图线索，但只有提交消息的作者或关联讨论才能确认该约束是否仍然适用。
  • 如果历史记录稀少或消息含糊，请说“历史记录显示”和“可能”，不要凭空编造设计理由。

后续跟进

最后提出一个相关的后续问题，例如：

  • “要我评估这看起来是有意为之还是意外造成的吗？”
  • “要我梳理一下如果此区域发生变更，哪些内容可能会出问题吗？”

对于是否出于有意选择的问题，应综合考虑反复编辑、问题引用、回退操作和明确的约束用词。对于变更风险问题，应先检查反复共同变更的文件以及最近改变行为的提交，再提出编辑建议。用户提出要求之前，不要修改代码。

文件

  • scripts/archaeologist.py：离线 Git 历史遍历器和 JSON 报告构建器
  • references/reading-git-history.md：解读与置信度指南

评论

支持 Markdown