RepoGeist 用本地 AI 追查代码历史

Git 能找回删掉的代码，却不一定能解释当初为什么删。RepoGeist 把这两件事分开处理：先用确定性程序整理仓库历史，再让本地模型根据有限证据回答问题。它的价值，是把散落在提交、分支和历史文件里的线索，变成可以追查的材料。

这是作者为 Hacktoberfest 2026 Open-Source AI Challenge 第 4 周「Ghost in the Machine」提交的开源项目。对程序员更有参考价值的，是它怎样划分 Git、检索和模型的职责，以及证据不足时怎样停下来。

找回历史代码，和解释删除原因是两回事

RepoGeist 将自己定位为注重隐私的 Git 考古工具。它统计提交、贡献者、文件、语言和活动情况，识别长期没有动静的分支，并查找在所分析的 HEAD 中已经消失的文件。这里的 HEAD，可以理解为本次分析选定的当前提交。

作者准备了一个可复现的合成演示仓库，包含 10 个确定性提交和一个陈旧的实验分支。演示路线从 Graveyard 开始：找到已经不在 HEAD 中的 auth/legacy.py，再通过 Code Resurrection 直接从 Git 读取它最后的历史版本，整个过程不修改工作区。

随后，Ghost Chat 接收删除提交、相关认证改动和限定范围的元数据，解释这些材料能证明什么。删除发生在哪次提交，可以查；开发者为什么决定删除，如果提交记录没写，就只能回答动机未知。

恢复文件内容，不等于恢复作者意图。

这个边界对接手老项目尤其有用。旧模块消失，可能伴随替换实现，也可能只是一次清理。即使相邻提交出现了认证逻辑改动，也不能自动把时间上的接近当成因果证明。

为什么先整理证据，再让模型开口

RepoGeist 的核心架构，是将 Git 事实与 AI 文字分开。原文用这段流程说明两者怎样衔接：

Git repository
  -> deterministic extraction
  -> SQLite evidence records
  -> bounded keyword/entity retrieval
  -> local Ollama prompt
  -> evidence-linked response

最该看的是 bounded keyword/entity retrieval 这一行：模型接收的是经过范围限制的关键词、实体检索结果，输入并非整个仓库。

事实层读取真实 Git 对象，把结果存成 SQLite 证据记录。生成层再根据任务组织材料：Ghost Chat 回答仓库问题；Commit Autopsy 解读受限大小的 diff；The Repository Speaks 将事实里程碑写成灵异编年史、技术纪录片或开发者回顾，三种风格都要求关联证据。

默认模型是通过 Ollama 运行的开放权重模型 Qwen2.5 3B，运行地址和模型名称都能配置。证据包包括相关提交元数据、变更路径、删除记录；分析单次提交时，再加入有限的 diff。回答会引用提供给模型的提交和文件。

这种拆法还有一个实际收益：Ollama 不可用时，事实看板、时间线、Graveyard、Code Resurrection 和确定性报告仍能使用，只有 AI 端点返回配置指引。工具还支持导出 Markdown 和 JSON 调查报告。

模型负责解释，查证入口和基础功能则保留在应用里。

本地运行怎样落实隐私和权限边界

前端采用 Next.js 和 TypeScript，后端采用 FastAPI、SQLAlchemy 和 SQLite。RepoGeist 通过参数数组调用原生 Git，禁用 hooks，也不执行被分析仓库中的代码。API 的导入范围限制在配置好的仓库根目录内，避免它浏览宿主机上的任意路径。

这些约束和本地推理一起构成隐私方案。作者认为，历史记录可能包含未发布功能、内部名称、安全修复和架构线索，因此不应默认把全部材料交给封闭的托管 API。本地部署允许源码、Git 历史、提示词和模型响应留在开发者机器上，也允许团队替换模型、检查提示词、调整检索，或离线工作。

仓库内容本身也被当作不可信数据。提交消息可能夹带提示词注入（prompt injection），也就是诱导模型改变行为的指令。系统提示词会明确告诉模型：仓库文字是证据，不是指令。模型同时没有执行 shell、任意读文件、读取秘密、修改仓库或发出外部请求的工具。

本地推理解决数据去向，权限限制约束模型能做的事。

原文也提醒，开放权重不等于不受限制的开源，具体模型许可证仍需要审核。拿到权重并能本地运行，是隐私承诺的技术基础，不能代替许可判断。

我的判断

我认可它把可验证事实放在前面的设计。相比直接让通用聊天助手阅读一批 Git 日志，RepoGeist 提供了更明确的证据入口；相比手动查日志和历史文件，它尝试减少收集线索、组织上下文的重复劳动。

但效果证据目前还比较有限。作者报告，6 个后端测试在真实临时 Git 仓库上通过，Ruff、TypeScript 检查和 Next.js 生产构建通过，构建生成了 11 个应用路由。Docker Compose 配置及前后端镜像构建成功，后端容器完成了演示仓库导入、10 次提交分析、Graveyard 查询和历史源码读取。已安装的前端依赖树报告 0 个已知漏洞。

这些结果支持基础流程可运行，不能证明复杂仓库里的分析准确率。原文没有给出大型仓库性能、检索召回率，或与人工调查、其他模型的对照数据；「0 个已知漏洞」也只对应当时检查的前端依赖树。

AI 部分有实际运行记录：qwen2.5:3b 的 Ghost Chat 回答引用了认证删除提交和 auth/legacy.py，并承认具体动机没有记录；Haunted Chronicle 输出了按时间排列的行内引用和完整证据面板。这说明预期行为至少在演示中出现过，仍不足以保证模型每次都能守住边界。

受限证据包能控制输入规模，也可能漏掉关键上下文。原文没有说明文件重命名、跨分支演化，以及提交之外的讨论如何处理。若决定只留在 issue、评审或聊天里，Git 考古就有天然缺口。引用方便核查，也不代表引用一定支持模型写出的每个结论。

能拿来做什么

• 接手前端或全栈老项目时，可以先查已删除模块及其关联提交，用历史版本确认旧实现做过什么，再判断是否值得恢复；删除理由应单独核实。
• 给日常 AI 编程工具增加提交解读功能时，可以沿用「事实提取、证据存储、有限检索、模型解释」的流程，并为回答保留可打开的提交与文件引用。
• 在涉及内部源码的仓库里试用时，可以先核对仓库根目录配置、Ollama 地址和模型许可证，再用少量熟悉的历史问题检查回答是否得到证据支持。
• 评估这类工具时，可以准备一个「能找到删除提交，但没有记录删除原因」的案例，观察它是否明确承认未知，并检查 AI 不可用时基础查询是否仍然可用。