Skip to content

docs(logs): add Log 11 for rerank and Top-3 advisor output (2026-06-21)

赵烜熠 requested to merge zxy into main

📝 变更概述 (Overview)

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

在前一阶段完成检索基线与内置候选库整理后，本阶段继续围绕原型系统中的重排与解释输出流程进行梳理，重点记录当前 rerank 模块的定位、规则化重排依据、候选补丁从 Top-N 到 Top-3 的压缩过程，以及 advisor 模块如何生成推荐理由。

当前官方 benchmark 仍未发布，因此本阶段仍以规则化原型链路整理和接口稳定性记录为主，暂不涉及 Cross-Encoder、真实 LLM Advisor、百万级补丁库评测或 Top-3 命中率实验。

🔍 详细变更列表 (Changes)

1. 归档 Log 11：规则化重排与 Top-3 可解释输出整理

新增第十一篇开发日志，记录当前原型系统中重排和解释输出模块的阶段性设计，主要包括：

  • 梳理 rerank 模块在整体 pipeline 中的位置；
  • 明确重排模块位于 retrieval 与 advisor 之间；
  • 整理候选补丁从召回结果进入重排阶段后的处理流程；
  • 分析规则化重排器的主要排序依据；
  • 梳理 Top-N 候选补丁到 Top-3 推荐结果的压缩过程；
  • 明确当前规则化 Advisor 与未来 LLM Diagnostic Advisor 的关系。

2. 整理规则化重排依据

日志中记录了当前规则化重排主要考虑的几类因素：

  • 检索阶段输出的基础相关性分数；
  • 故障特征与候选补丁之间的子系统匹配；
  • BUG、PANIC、OOPS 等基础错误签名匹配；
  • Cc: stable 等 stable 修复信号的辅助加权作用；
  • dmesg Call Trace 中函数名或调用路径与候选补丁文本之间的弱匹配信号。

当前重排逻辑主要用于原型流程验证和后续模型接入前的基线对照，不作为最终语义重排方案。

3. 梳理 Top-3 推荐输出结构

本阶段进一步整理了最终推荐结果中应包含的核心字段：

  • rank：候选补丁排名；
  • commit_id：补丁提交编号；
  • title：补丁标题；
  • subsystem：所属内核子系统；
  • score：综合排序分数；
  • reason：推荐理由；
  • evidence：支持推荐的关键证据。

这些字段可与前期设计的 match_result Schema 逐步对应，便于后续统一接口输出。

4. 明确 Advisor 模块作用

本阶段日志进一步明确，当前 Advisor 模块主要解决“为什么推荐这些补丁”的问题，而不是重新完成候选召回。

当前 Advisor 仍属于规则化解释模块，主要根据候选补丁和故障特征生成基础推荐理由。后续若接入 LLM Diagnostic Advisor，可以在保持输出结构稳定的前提下，将结构化证据交给模型生成更自然、更完整的解释。

5. 记录当前阶段局限

日志中同时记录了当前阶段存在的问题：

  • 当前重排逻辑仍主要依赖规则和少量样例；
  • 候选补丁仍主要来自内置样例库；
  • 缺少真实 diff、修改文件和修改函数信息；
  • Advisor 输出仍偏模板化；
  • 尚未接入 Cross-Encoder 或真实 LLM Advisor；
  • Top-3 输出尚未经过官方 benchmark 验证。

📂 日志归档位置

新增日志已归档至：

  • docs/logs/2026-06-21-log11-rerank-top3-advisor.md

📌 后续计划

下一阶段将围绕 Docker 服务编排与原型运行验证继续推进，重点包括：

  • 梳理当前 docker-compose.yml 中的服务配置；
  • 分析 Milvus、etcd、MinIO 等依赖服务在项目中的定位；
  • 梳理 FastAPI 服务的 Dockerfile；
  • 梳理 Streamlit UI 服务的 Dockerfile；
  • 验证 API 和 UI 的本地启动方式；
  • 记录当前无 GitLab CI pipeline 的原因；
  • 为后续自动化测试和部署脚本整理基础说明；
  • 持续关注官方 benchmark 发布进度。

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

Merge request reports