Skip to content

docs(logs): add Log 09 for commit ingestion parser fix (2026-06-15)

赵烜熠 requested to merge zxy into main

📝 变更概述 (Overview)

本次提交属于文档更新，主要归档“灵枢”项目的第九篇开发日志（Log 09）。

在前一阶段完成轻量 Commit 采集脚本原型梳理和 JSONL 输出初步验证后，本阶段进一步聚焦于当前脚本中暴露出的解析边界问题，重点围绕 commit ID 提取、commit 标题解析、维护标签跳过规则和基础测试样例设计进行整理。

当前官方 benchmark 仍未发布，因此本阶段仍以小规模模块完善和数据入口稳定性为主，暂不涉及 GitPython 全量遍历、百万级 commit 入库、Milvus 向量索引或实际命中率评测。

🔍 详细变更列表 (Changes)

1. 归档 Log 09：轻量 Commit 采集脚本解析规则修正与测试用例设计

新增日志记录了当前 scripts/ingest_commits.py 轻量原型中待修正的解析边界问题，主要包括：

  • 首条 commit 记录可能保留 commit 前缀，导致 commit_id 解析异常；
  • 原有标题提取方式可能误将 Fixes:、Cc:、Signed-off-by: 等维护标签行作为标题；
  • 当前修复信号规则仍主要基于 Fixes:、Cc: stable 和 bug 等轻量关键词；
  • JSONL 输出格式需要保持稳定，便于后续 retrieval 模块读取。

2. 设计 Commit ID 统一解析策略

本阶段明确了新的 commit ID 提取思路：

  • 对每个 commit block 的首行进行预处理；
  • 若首行以 commit 开头，则先移除该前缀；
  • 再提取剩余内容中的第一个字段作为 commit hash；
  • 对无法解析的 block 进行跳过或异常记录。

该策略用于统一处理首条 commit 与后续 commit 的格式差异。

3. 设计 Commit 标题提取优化策略

本阶段明确标题提取不应直接使用 block 最后一行，而应：

  • 跳过 commit hash 行；
  • 跳过空行；
  • 跳过 Author:、Date: 等 Git 元信息行；
  • 跳过 Fixes:、Cc:、Reported-by:、Signed-off-by: 等维护标签行；
  • 优先选择第一条有效正文行作为标题。

该规则可以减少将维护标签误识别为 commit 标题的问题。

4. 设计 Commit Ingestion 基础测试样例

本阶段设计了多类测试场景，为后续补充自动化测试做准备：

  • 首条 commit 带 commit 前缀；
  • 后续 commit 不带 commit 前缀；
  • 标题后存在 Fixes: 或 Signed-off-by: 等标签；
  • 普通文档修改不命中修复信号；
  • 标题中包含 bug 关键词的修复提交能够被保留。

5. 明确与后续完整采集器的衔接关系

当前轻量脚本仍不等同于最终 GitPython 全量采集器。本阶段日志明确了后续完整采集器仍需要继续补充：

  • Linux upstream 仓库读取；
  • v3.10 tag 定位；
  • commit 历史遍历；
  • 修改文件和 diff 抽取；
  • Merge commit 识别；
  • 子系统推断；
  • embedding_text 构造；
  • JSONL 或 Milvus 写入。

📂 日志归档位置

新增日志已归档至：

  • docs/logs/2026-06-15-log09-commit-ingestion-parser-fix.md

📌 后续计划

下一阶段将围绕检索基线与内置候选库整理继续推进，重点包括：

  • 梳理 src/lingshu/retrieval/ 模块；
  • 分析当前内置候选补丁库结构；
  • 梳理简单语义打分逻辑；
  • 明确关键词重叠、子系统匹配和 stable 标签加权策略；
  • 检查 Top-N 召回结果与 rerank 模块之间的接口；
  • 为后续将 JSONL commit 数据接入 retrieval 模块做准备。

注：本次合并仅涉及 docs/logs/ 目录下的开发日志归档，不包含业务逻辑代码修改。

Merge request reports