Skip to content

docs(logs): add sixth project log for JSON schema interface design (2026-06-02)

赵烜熠 requested to merge zxy into main

📝 变更概述 (Overview)

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

在前期完成项目原型脚手架、API/UI 基础联调以及 commit 数据采集思路梳理后，本阶段进一步聚焦于跨模块数据接口规范。为避免后续接入官方 benchmark、Milvus 向量检索和模型模块时出现字段命名混乱、接口反复修改等问题，本次日志系统整理了故障特征、补丁特征和匹配结果三类标准化 JSON Schema，并明确了模块之间的数据传递方式。

🔍 详细变更列表 (Changes)

1. 梳理标准化 Schema 目录结构

围绕系统后续的数据流转需求，整理了三类核心结构化数据规范：

  • crash_feature.schema.json：用于描述从 dmesg、vmcore 或人工问题描述中提取出的标准化故障特征；
  • patch_feature.schema.json：用于描述经过清洗和标准化处理后的 Linux upstream patch；
  • match_result.schema.json：用于描述故障记录与候选补丁之间的匹配结果、评分信息和推荐理由。

同时，通过 schema/README.md 统一记录 Schema 的设计原则和使用方式。

2. 统一跨模块数据规范

本阶段明确了以下基础约定：

  • 字段命名：统一采用 snake_case；
  • 缺失值处理：统一使用 null；
  • 离线语料格式：批量数据优先采用 JSONL；
  • API 数据格式：单次请求和响应采用普通 JSON；
  • 大体积原始数据：完整 dmesg、vmcore 和 diff 不直接嵌入 JSON，而是通过 raw_ref 和 raw_sha256 进行引用与校验；
  • 向量数据关联：高维向量不直接写入 JSON，而是通过 vector_id 和 embedding_model 与外部向量数据库关联。

3. 完善故障特征数据结构

围绕多模态输入标准化需求，进一步整理了故障特征中的核心字段，包括：

  • 数据来源：dmesg、vmcore、manual；
  • 标准化状态：status、parser_version、confidence；
  • 故障标签：kernel_version、arch、bug_class、panic_class；
  • 子系统与实体：subsystem_candidates、functions、files、modules、symbols；
  • 检索摘要：title、symptom、hypothesis、retrieval_text。

这一结构为后续 dmesg 解析器、vmcore 分析器和 Crash Hypothesis 生成模块预留了稳定接口。

4. 完善补丁特征数据结构

围绕 Linux upstream patch 知识库建设需求，整理了补丁侧的核心字段，包括：

  • commit 基础信息；
  • Fixes:、Cc: stable、Reported-by: 等修复信号；
  • 修改文件、函数和 diff 统计信息；
  • 内核版本范围；
  • retrieval_text；
  • vector_id 与 embedding_model。

该结构将用于后续 commit 数据采集、清洗、向量化和 Milvus 入库。

5. 预留分阶段检索与解释字段

为后续实现可解释性检索链路，在匹配结果中预留了以下字段：

  • prefilter_pass；
  • vector_score；
  • rerank_score；
  • advisor_score；
  • final_score；
  • subsystem_match；
  • kernel_version_compatible；
  • function_overlap；
  • file_overlap；
  • bug_class_match；
  • short_reason；
  • detailed_reason。

当前部分字段仍属于接口占位，后续将在 Milvus 向量召回、Cross-Encoder 重排和 Diagnostic Advisor 接入后逐步填充真实结果。

6. 梳理跨模块数据流

本阶段进一步明确了系统的数据流转路径：

dmesg / vmcore / 人工描述
        ↓
故障特征提取模块
        ↓
crash_feature
        ↓
元数据过滤与向量召回
        ↓
patch_feature 候选集合
        ↓
重排与 Advisor 分析
        ↓
match_result
        ↓
Top-3 推荐补丁与解释

通过统一 Schema，可以降低不同模块之间的耦合程度，为后续逐步替换占位实现和接入官方 benchmark 做好准备。

📂 日志归档位置

新增日志已归档至：

  • docs/logs/2026-06-02-log06-json-schema-interface.md

📌 后续计划

下一阶段将围绕 dmesg 基础解析器与单元测试继续推进，重点包括：

  • 内核版本提取；
  • Call Trace 调用栈提取；
  • BUG、PANIC、OOPS 等错误类型识别；
  • 子系统关键词初步判断；
  • 字段缺失情况下的容错处理；
  • dmesg parser 单元测试补充。

注：本次合并主要涉及开发日志归档，不包含业务逻辑代码修改。Schema 相关文件已在前期工程中完成初步整理，本日志用于记录和说明该阶段工作。

Merge request reports