RepoWise git_indexer 深度解析:将 Git 提交历史转化为代码健康、归属与缺陷预测信号
RepoWise git_indexer 深度解析:将 Git 提交历史转化为代码健康、归属与缺陷预测信号
git_indexer 是 RepoWise 摄取(ingestion)管线中负责“挖掘 Git 历史”的核心模块:它把仓库的提交历史转成逐文件的元数据(所有权、churn、热点、共变、变更熵、历史缺陷),供 wiki 与 health 层消费。本文以该模块的官方文档(packages/core/src/repowise/core/ingestion/git_indexer/README.md)为骨架,结合仓库源码深入讲解其窗口锚定机制、双档位(FULL/ESSENTIAL)索引策略、单次仓库级 git log 的性能设计、每提交行与即时变更风险,以及 agent 溯源(agent provenance)的确定性分类规则,帮助读者理解 RepoWise 的 Git 智能从何而来、如何配置,以及如何把同样的模式复用到自己的索引器实现中。
Purpose:提交历史里挖出的信号清单
git_indexer 存在的意义,是把一个仓库的提交历史变成 wiki 和 health 层能直接消费的信号。按照官方文档,它产出的信号包括:
- 提交计数与活跃窗口:90 天 / 30 天提交数、文件年龄(
age_days)、is_stable稳定标记; - 贡献者与所有权:贡献者数、bus factor、主所有人与近期所有人(FULL 档基于 blame,其他档位退化为提交作者统计);
- 重要提交与提交类别占比:significant commits,以及 feature / fix / refactor 等类别的比例;
- 时间热点分数:指数衰减的 churn 分数,以及仓库级百分位(
churn_percentile、is_hotspot); - 共变伙伴与 Hassan 变更熵(History Complexity Metric);
- 逐函数 blame:修改次数与行年龄,服务于函数级健康;
- 历史缺陷(prior-defect history):在窗口内触碰每个文件的 bug-fix 提交数——官方文档明确指出这是“最具性价比的缺陷预测信号”;
- agent 溯源:每个提交由哪个编码 agent(若有)在什么自主性档位下创作,以及逐文件的
agent_authored_pct聚合。
从源码看,这些信号的实际落点可以在 file_history.py 的 new_meta 默认字典里一览无余:commit_count_total/90d/30d、primary_owner_*、top_authors_json、significant_commits_json、temporal_hotspot_score、prior_defect_count、change_entropy、co_change_partners_json 等字段一一对应。所有下游特性(wiki 生成、健康评分)在 Git 不可用或仓库无历史时都能优雅降级——GitIndexer.index_repo 在 repo is None 时返回空摘要而非抛错。
窗口锚定(REPOWISE_GIT_WINDOW_ANCHOR)
所有活跃窗口(90d/30d、年龄、时间衰减、共变/熵衰减、缺陷窗口)都相对**同一个参考“现在”**来度量:
- 默认行为:以被索引提交(HEAD)的 committer 日期为锚点。这样索引是确定性的——稍后对同一提交重新索引会得到完全相同的窗口;并且对历史检出(historical checkout)正确:在旧提交上 detached 检出的工作树,度量的是该提交之前的窗口,而不是它未来的一片空窗。这也是缺陷基准(defect benchmark)校准所用的锚点,blame 标记(
code_age_volatility、逐函数 blame 汇总)同样从它读取行年龄。 REPOWISE_GIT_WINDOW_ANCHOR=now:改用墙钟now(),于是“最近有改动”相对的是今天,即使 checkout 没有移动。
源码实现上,indexer.py 中 _WALL_CLOCK_ANCHORS = frozenset({"now", "0", "false", "no", "off"}) 定义了哪些取值走墙钟;file_history.py 的 _window_anchor(as_of_ts) 在 as_of_ts 为空时回退到 datetime.now(UTC)。as_of_ts 由 GitIndexer._resolve_as_of_ts 解析,贯穿 index_file、compute_co_changes_and_entropy(见 co_change.py 中 now_ts = as_of_ts if as_of_ts is not None else time.time())以及 compute_prior_defects 的窗口边界解析(prior_defects.py 中 _resolve_rev_range)。
配套的守卫开关是 REPOWISE_SKIP_EDITOR_SETUP=1:它让 init 索引一个临时 worktree 时不去触碰开发者的全局编辑器配置;init --no-editor-setup 是同一开关的命令行形态,适合一次性运行。
Public API
模块通过 repowise.core.ingestion.git_indexer 导入,公开的 API 包括:
GitIndexer—— 编排器,提供index_repo(全量索引)与index_changed_files(增量索引)两个核心方法;GitIndexTier——FULL(默认)或ESSENTIAL索引深度;GitIndexSummary——index_repo返回的计数 + 耗时摘要;backfill_full_tier(indexer, repo_id, *, job_store=None)—— 把 ESSENTIAL 索引提升为 FULL,作为可恢复(resumable)的阶段执行;- 模块级构件(直接做单元测试):
index_file、compute_co_changes_and_entropy、compute_percentiles、compute_prior_defects、get_blame_ownership、is_significant_commit、detect_original_path、is_fix_commit。
其中 GitIndexer 的构造参数(见 indexer.py)包括:repo_path、commit_limit(默认取 _DEFAULT_COMMIT_LIMIT = 500)、follow_renames(默认 False)、tier、exclude_patterns(用 pathspec 的 gitwildmatch 解析)、record_episodes(默认关闭,避免只读命令意外持久化行)、max_workers。
index_repo 还暴露一组线程安全的进度回调:on_start(total)、on_file_done()、on_commit_done()、on_co_change_start(total)、on_co_change_done()、on_warning(text),便于管线上报阶段进度。返回的 GitIndexSummary(见 records.py)除 files_indexed / hotspots / stable_files / duration_seconds 外,还携带 commit_rows、commit_file_rows、fix_event_rows、repo_totals 与 history_coverage——后者是一份可序列化的索引覆盖率报告(eligible/files_with_history/unavailable/retained/workers 等字段)。
Tiers:FULL 与 ESSENTIAL 双档位
| Tier | 逐文件历史 | git blame 所有权 + 逐函数 blame |
共变 + 熵 |
|---|---|---|---|
FULL(默认) |
有 | 有 | 有 |
ESSENTIAL |
有 | 无(退化为提交作者归属) | 无(延后) |
ESSENTIAL 服务于大型仓库上的快速编排路径(--mode fast):它跳过两个 O(repo) 量级的信号,让首次索引快速落地,之后再由 backfill_full_tier 补上 blame 与共变/熵。缺陷通道(prior-defect pass)在两个档位都会运行,因为它的范围被窗口限定,不是 O(repo)。
从源码看,档位的门控是纯属性逻辑:tiers.py 中 GitIndexTier 是 StrEnum,includes_blame 与 includes_co_change 属性只在 FULL 时为真(另有 includes_function_blame 控制逐行 BlameIndex 的构建)。indexer.py 中 _co_change_task 在 ESSENTIAL 档直接返回空 CoChangeWalk(),include_blame = self.tier.includes_blame 则贯穿每个文件的 index_file 调用。
backfill_full_tier(backfill.py)是 ESSENTIAL→FULL 的提升器:构造时无论何种档位,都会在运行期间强制 GitIndexer.tier = GitIndexTier.FULL 并事后恢复;传入 job_store 时,会以 BACKFILL_PHASE = "git.backfill" 创建 JobStore 记录,从 RUNNING 推进到 COMPLETED/FAILED,从而实现崩溃检测与续跑。源码注释也坦白:当前 worker 是“薄脚手架”——本质上是为仓库重跑一次 FULL 索引,更细粒度的逐文件续跑是后续工作。
性能设计:一次仓库级提交索引
朴素的实现会为每个被跟踪文件派发一个 git log -- <file> 子进程——即 O(files) 次子进程。当重命名追踪关闭(默认状态)时,indexer.py 只构建一次仓库级提交索引(git_commit_index.load_commit_index / git log -<commit_limit> --numstat),每个逐文件 worker 从这份共享字典读取自己的切片。深度被 _DEFAULT_COMMIT_LIMIT(默认 500,最新 N 个提交)封顶,把 init 控制在时间与内存预算内。
重命名保留历史
所有共享遍历(提交索引、共变、历史缺陷)都以最新在前的顺序读取 git 的重命名行,并把更早的提交记在文件 HEAD 路径名下(records.RenameTrail),因此 churn、年龄、作者、共变伙伴与修复计数都能跨越重命名。路径被不同文件复用的情况,则只保留它自己的提交。
RenameTrail(records.py)是一个“路径→HEAD 路径”的映射器:遍历按最新在前进行,重命名先于任何更老的提交被看到,逐路径解析即可把重命名前的提交带到当前名字下。它还有一个精妙的顺序约束:必须先解析完某提交自身的路径再记录该提交的重命名,否则“把 a 移到 b 同时又新建 a”的提交会把新 a 错挂给 b。
prior-defect 通道绕过的坑
深度上限按提交数封顶,因此在高频仓库里,热门文件的切片会低估较宽的窗口。compute_prior_defects 于是不读共享索引——它运行自己的一次按日期限定的 git log prior_sha..HEAD --name-status,以窗口内活动规模(而非仓库总年龄)为代价触达完整窗口。窗口化且带衰减的信号(90d 计数、熵)能容忍上限,因为旧提交的贡献趋近于零。
实际实现(prior_defects.py)分两步:先解析窗口起点(--before 定位的边界提交)得到拓扑范围 prior_sha..head,用 is_fix_commit 关键字规则分类每个非 merge 提交,并把修复归因到它触碰的每个可索引文件(按 HEAD 路径);第二步按批(_SHAPE_BATCH_SIZE = 300)打开每个修复提交的 -U0 diff,只保留真正改动生产代码的提交(fix_shape 模块的 classify_fix_shape),并同时返回 counts(过滤后,health 生物标记实际打分所用)与 raw_counts(过滤前),使噪音可见可查。
逐提交行 + 即时变更风险
同一次仓库级遍历还产出逐提交的行(git_commits 表),而不只是逐文件聚合。load_commit_index 接受可选的 commit_sink:在既有遍历过程中把每个提交(sha、作者、时间戳、主题,以及它在所有文件上的完整 (path, added, deleted) 足迹)追加进 sink——不多花一次 git 调用。随后 commit_rows.build_commit_rows 把这些行转成携带 Kamei 变更特征(触碰的行/文件/目录/子系统数、churn 熵)以及来自 analysis.change_risk 的校准变更风险分数/等级的行——运行时安全(纯算术,无 LLM、无 blame)。作者经验(在实时 repowise risk 路径中唯一需要子进程的变更风险特征)在这里被内存中重构:按最老→最新遍历提交,每位作者的历史提交数就是累计值。该特性在重命名追踪模式下为空(那一路走逐文件遍历而非批处理索引)。
从 indexer.py 的实现看,commit_rows 与 commit_file_rows 是成对构建、成对赋值的(built, built_files 一起成功才写入),避免写出“提交存在但文件明细描述的是另一组”的半成品;任何异常都会被捕获并降级为日志,绝不拖垮文件级 git 元数据。增量侧则有 capture_new_commit_rows(since_ts=...) 作为对偶,只遍历比最新已持久化提交更新的提交。repo_totals(见 records.py 的 RepoTotals 与 capture_repo_totals)则用少数廉价 git rev-list/shortlog 调用捕获全史统计(真实项目年龄、提交数、贡献者数),不依赖深度封顶的样本——stats 页面读的是它,而不是 commit_rows。其中全史 churn 是唯一的 O(history) 调用,通过 _folded_churn 的“锚点 + 增量范围”折叠来摊销,并受 _CHURN_COMMIT_CEILING = 50_000 与 _CHURN_REANCHOR_STRIDE = 100 双重约束,防止 diff 属性变化导致的漂移无限累积。
Agent 溯源:确定性、精度优先
agent_provenance.py 给每个被遍历的提交打上 {agent, autonomy_tier, channel, confidence} 标签,数据来源是本地 git 历史中存在的归因通道——身份字段(bot 账号 / 服务邮箱)、精确的消息脚注(“Generated with Claude Code”、Codex、opencode、aider)、锚定到服务身份的 Co-authored-by: trailer、git-ai 作者注释(refs/notes/ai),以及 agent-trace 记录(厂商中立的 agent-trace 标准,从 .agent-trace/traces.jsonl 读取)。档位:
- Tier 1(近自主):agent 服务账号撰写了提交;
- Tier 2(人类驱动的 agent):脚注、注释、trace 记录,或服务身份作为committer覆盖人类作者;
- Tier 3(协助):仅有 co-author trailer。
Agent-trace 记录携带编辑或提交时捕获的 vcs.revision,因此 AgentTraceIndex 在 revision 匹配提交本身(置信度 high)或其一父提交(被追踪变更落入子提交,置信度 medium)时归因该记录,且要求记录的文件集合与提交变更路径有交集。胜出记录的主导 model_id(models.dev 的 provider/model 形式)随之带到提交上,支持 opus-vs-sonnet 拆分。
AgentTraceIndex 还产出逐文件行份额:从每条记录的 ranges[] 计算 AI/混合贡献者写入的不同行数(跨路径的所有记录做区间并集去重),外加 {model_id: line_count} 分解。这与 revision 无关(无 vcs.revision 的记录仍计数),且按路径键控,所以编排器能把它与共变/缺陷信号一起并入 git_metadata,在重命名追踪遍历下同样工作。“N% AI-written” 的分母是文件当前 LOC,由下游应用——索引器只存 AI 分子,保持与 LOC 解耦。
设计规则(源码与文档一致):
- 精度优先:每个模式都锚定到服务身份,裸名字永不匹配(名叫 “Devin” 的人类贡献者不得变成 Devin agent);给人类提交打上错误的 “agent-authored” 标签比漏判更糟。源码中
_BOT_LOGINS映射把<login>[bot]@users.noreply.github.com规范化为copilot/devin/cursor/jules等,_AGENT_ALIASES再解析Assisted-by:/Generated-by:trailer 与 git-ai note 中的自由文本。 - 仅本地通道:PR 级证据(bot PR 作者、agent 分支前缀、PR-body 脚注)需要 forge API,超出范围——剥离 trailer 的 squash merge 是已知的 recall 损失,文档明确声明而不用索引时的网络调用去修补。
- 零额外成本:分类复用既有提交索引遍历——对已解析记录做纯内存正则,约 20 µs/提交(默认提交深度下约 10 ms),无额外
git通道。 - 配置驱动:仓库可在
.repowise/config.yaml的agent_provenance:块下扩展注册表(service_emails、footer_patterns、coauthor_patterns)——在内置规则之上叠加,畸形条目跳过并告警。源码示例:
agent_provenance:
service_emails:
mybot@example.com: {agent: mybot, tier: 1}
footer_patterns:
- {pattern: "Generated by MyBot", agent: mybot}
coauthor_patterns:
- {pattern: "^co-authored-by: mybot <[^>]*@example\\.com>", agent: mybot}
持久化形态是 git_commits 上五个可空列(agent_name/agent_autonomy_tier/agent_channel/agent_confidence/agent_model_id),以及 git_metadata 上的逐文件汇总(提交级 agent_commit_count、agent_authored_pct、agent_tier_counts_json;行级 agent_line_count、agent_line_model_json),在 /git-metadata 文件视图和 MCP get_context 的所有权块中展示。
内部模块布局
| 模块 | 内容 |
|---|---|
tiers.py |
GitIndexTier 枚举 + includes_blame / includes_co_change / includes_function_blame |
_constants.py |
提交深度默认值、衰减半衰期、bug-fix 关键字分类器(is_fix_commit,与基准镜像一致)+ PRIOR_DEFECT_WINDOW_DAYS、跳过启发式、GitPython 噪音补丁 |
records.py |
_CommitRec、GitIndexSummary(携带 commit_rows)、git log 记录格式 + 重命名/跳过路径辅助 |
commit_rows.py |
build_commit_rows——基于遍历沉没提交的逐提交 Kamei 特征 + 变更风险(纯内存作者经验) |
agent_provenance.py |
AgentProvenanceClassifier——确定性逐提交 agent 归因(本地通道、配置可扩展) |
file_history.py |
index_file——逐文件解析 + 基础指标(blame 由档位门控) |
enrich.py |
blame 所有权、提交重要性、重命名检测、百分位 |
function_blame.py |
逐行 blame 索引 → 逐函数修改次数 + 行年龄(FULL 档;供给 function_hotspot / code_age_volatility) |
co_change.py |
compute_co_changes_and_entropy——仓库级衰减加权配对遍历 + Hassan HCM |
prior_defects.py |
compute_prior_defects——窗口内逐文件 bug-fix 计数(防泄漏、镜像基准) |
indexer.py |
GitIndexer 类,串联以上模块;把共变/熵/缺陷并入逐文件元数据;后向兼容实例 shim |
backfill.py |
backfill_full_tier 可恢复的 ESSENTIAL→FULL 提升 |
(git_commit_index.py 位于 ingestion/ 上一级——indexer.py 消费的仓库级提交分桶遍历,即“Performance”一节所述。)
几个值得展开的常量细节( _constants.py):
- 深度与回退:
_DEFAULT_COMMIT_LIMIT = 500;第二层更深的仓库级遍历_DEEP_WALK_COMMIT_LIMIT = 20_000专门服务“窗口索引缺失”的文件,用一次--skip遍历替代数千次逐文件git log(源码注释引用过一个 9k 提交 WinUI monorepo 上 3,295 次 spawn 的案例);_DEEP_WALK_MIN_FALLBACK = 100保证小仓库(通常零缺失)不会为深度遍历付出全史成本。 - 提交消息过滤:硬跳过
Merge前缀;软跳过Bump/chore:/ci:/style:/build:/release:——但若消息含决策信号词(migrate、replace、refactor、adopt、deprecate、rewrite等),则保留。_MIN_MESSAGE_LEN = 12过滤无意义短消息。 - 修复提交的唯一口径:
is_fix_commit是“匹配任一 INCLUDE 且不匹配任一 EXCLUDE”,_FIX_COMMIT_INCLUDE覆盖fix/bug/patch/resolves?/fixes? #N等,_FIX_COMMIT_EXCLUDE排除Merge/typo/bump/deps/chore/lint/format/style/docs等;它与基准的find_fix_commits逐字节一致,保证“产品 == 基准”。 - 缺陷窗口:
PRIOR_DEFECT_WINDOW_DAYS = 180(约 6 个月),刻意匹配基准的defect_window_months: 6——比 90d 活跃信号更宽,因为缺陷历史比近期 churn 更慢热。 - 共变/熵的规模护栏:共变配对在提交触碰超过
_MAX_FILES_PER_COMMIT_FOR_COCHANGE = 200个文件时整体跳过(最坏情况 500 文件 × 2000 提交会产生约 2.5 亿对 ≈ 16 GB 内存);变更熵更严格,超过_MAX_FILES_PER_COMMIT_FOR_ENTROPY = 30的文件被整提交剔除(Hassan 2009 的常见过滤器)。配对记录要求_MIN_CO_CHANGE_SUPPORT次共享提交,每文件保留_MAX_PARTNERS_PER_FILE个最强伙伴(用每文件有界最小堆实现,保持持久化列线性规模)。 - 热点判定双门槛:
churn_percentile是仓库相对值,安静仓库上“top quartile”会退化为“任何 90 天内被碰过的文件”,因此还要求绝对下限——90 天内至少HOTSPOT_MIN_COMMITS_90D = 3次提交,且衰减 churn 分数 ≥HOTSPOT_MIN_TEMPORAL_SCORE = 0.5(或 90 天内 ≥HOTSPOT_HIGH_COMMITS_90D = 8次提交的持续高量)。该规则与 SQL 侧的PERCENT_RANK路径(crud/git.py::recompute_git_percentiles)镜像同步。 - blame 的规模护栏:超过
_MAX_BLAME_SIZE_BYTES = 100 KB的文件跳过 blame(blame 是 O(lines),会阻塞执行线程),改用提交作者归属估计;单个文件索引超过_FILE_INDEX_TIMEOUT_SECS = 45.0秒则记录已有部分数据并释放信号量槽位。 - GitPython 噪音补丁:
_CatFileContentStream.__del__在管道关闭后排水会抛ValueError,模块启动时用一个吞异常的_quiet_del替换它,防止无害但刷屏的 stderr traceback。 - 提交体字节上限:
_MAX_COMMIT_BODY_BYTES = 1024,按 UTF-8 字节精确截断(_truncate_body),且只有_body_carries_decision(含## why/## motivation/closes #等 PR 标记或决策信号词)的提交体才被保留,避免宽 squash 提交把同一正文按文件重复复制放大 8 倍。
扩展点与降级契约
下游索引器可以直接用自己的 executor 调用模块函数,或“不子类化任何东西”、只传入不同的 GitIndexTier;backfill_full_tier 接受任意 JobStore 做检查点/续跑。所有扩展点都遵循“失败隔离”契约:blame 尽力而为、超时保留部分数据、prior-defect 的 shape 过滤失败时按 code_fix 保守计数、git_commits 构建失败只记日志不破坏文件级元数据。
测试覆盖
- tests/unit/test_git_indexer.py:逐函数行为,含修复提交分类器与缺陷计数;
- tests/unit/ingestion/test_git_indexer_tiers.py:档位门控 + backfill;
- tests/integration/test_git_intelligence_integration.py:端到端。
对应仓库中的模块级测试还包括 _parse_commit_record 的 NUL/0x1f 分隔记录解析、_split_record 对 --name-status 路径块与多行正文的右对齐切分(tests/unit/ingestion/test_prior_defect_walk.py 是其护栏)等。这些测试共同锁定了“确定性、防泄漏、基准对齐”这三条主线:同一提交重索引产出相同窗口、历史检出不泄漏未来修复、产品缺陷计数与基准严格一致。