用途:git blame 只能指出某行最后由谁修改,本技能则重建该行存在的原因。它追踪文件或当前行范围在本地 git 历史中的来源与后续编辑,找出反复与其一同变更的文件,并从提交信息中提取意图线索。
主要能力:输出结构化 JSON,包含 region(规范化仓库、当前与历史路径、模式、范围、共同变更阈值)、introduced_by(所选历史中最旧的提交)、timeline(从旧到新的提交及类别、变更文件、检测到的重命名)、co_changed(在足够多所选提交中与目标同时出现的文件)、authors(当前 blame 行与历史提交计数分开保留)、intent_signals(提交信息中的 issue 引用、回滚、变通方案、临时标记、未完成标记)。
使用方式:从技能目录运行只读脚本,例如 python3 scripts/archaeologist.py /path/to/repo src/cache.py --lines 40-72 --json;查看整个文件历史时省略 --lines。路径需相对仓库并使用正斜杠,行范围使用当前行号且含端点。解读 JSON 前应阅读 references/reading-git-history.md 中的置信度规则。
适用场景:用户询问某段代码、函数或文件为何存在;想知道谁引入代码及之后发生了什么;重写或重构前需要历史约束与变更风险;需要理解变通方案、临时分支或意外设计选择的背景。
限制:不适用于只想要原始 blame 输出或提交列表、要压缩删除或重写 git 历史、仓库为远程且未本地克隆、或问题涉及项目整体架构而非单个文件或区域的情况。当前 blame 归属不等于原始作者;所选最旧提交只是该区域的引入,不一定是文件首个提交;反复共同变更只暗示耦合,不证明依赖;提交类别是信息启发式,非已验证的问题类型;空信号列表只表示提交信息未说明原因,不代表没有原因。历史稀少或信息模糊时应使用“历史显示”“可能”等措辞,不要编造设计理由。未经用户要求不要修改代码。