SuperBizAgent-java/openspec/changes/lookup-knowledge-integration/proposal.md

# Proposal: L0+L1 混合检索集成

## 问题

当前只有 L1 向量语义检索（Milvus + BGE-M3），在遇到精确关键词查询时（如错误码 "ERR_TIMEOUT"、接口名 "PaymentGateway"）效率不够高：
- 需要调用 embedding API 生成向量（约 100-300ms）
- 语义检索返回相似但可能不精确的结果
- 无法快速定位已知关键词对应的完整文档

Agent 需要一个"先精确、后语义"的混合检索工具。

## 建议方案

### 架构设计：双层检索

```
lookup_knowledge(query)
    ↓
L0: 精确关键词匹配（内存索引，< 10ms）
    ├─ 匹配成功 + 唯一结果 → 返回完整文档（高置信度）
    └─ 未匹配 或 多个匹配 ↓
L1: 向量语义检索（Milvus，补充上下文）
    └─ 返回 Top-K 相似片段
```

**核心机制**：
1. **L0 索引**：启动时扫描 `knowledge_base/` 目录，解析 Markdown frontmatter，构建内存索引
2. **L1 复用**：调用现有 `VectorSearchService.searchSimilarDocuments()`
3. **条件调用**：L0 唯一匹配时不调用 L1（减少延迟）

### 1. Frontmatter 规范

所有知识库文档（`knowledge_base/` 目录）需在文件头添加 YAML frontmatter：

```yaml
---
title: 支付网关错误码定义              # 必填
keywords: [ERR_TIMEOUT, 超时, 支付网关]  # 必填，用于精确匹配
summary: 记录了支付网关所有核心错误码的含义及排查方向  # 必填
category: api                          # 可选，与现有 category 对齐
sections:                              # 预留字段（MVP 不实现）
  超时排查: "## 1. 超时类错误"
---

# 文档正文
...
```

**约束**：
- frontmatter 必须在文件最顶部（前面不能有空行）
- `title`, `keywords`, `summary` 为必填字段
- 缺少 frontmatter 的文档允许上传，但不参与 L0 索引（只走 L1）

### 2. 上传流程增强

**现有流程**：
```
POST /api/documents/upload
  ↓
DocumentManagementService.uploadDocument()
  ↓
文本提取 → 分块 → 向量化 → Milvus 索引
  ↓
元数据存 MySQL (ApiDocument)
```

**增强后流程**：
```
POST /api/documents/upload
  ↓
1. 文本提取（内存）
2. 保存原始文件到：knowledge_base/{category}/{fileName}
3. 解析 frontmatter（FrontmatterParser）
4. 分块 → 向量化 → Milvus 索引
5. 元数据存 MySQL（ApiDocument.metadata 存储 frontmatter JSON）
6. 更新 L0 内存索引（KnowledgeIndexService）
```

**关键决策**（grill 阶段确认）：
- ✅ 保存原始文件到本地（支持 L0 完整读取 + 未来扩展）
- ✅ metadata 字段：TEXT 类型存储 JSON 字符串
- ✅ ApiDocument.filePath 存储本地文件路径
- ✅ L0 高置信度 = 唯一匹配（不调用 L1）
- 按 category 分类存储：`knowledge_base/api/`, `knowledge_base/domain/`, `knowledge_base/troubleshooting/`

### 3. L0 索引服务

**KnowledgeIndexService**：
```java
@Service
public class KnowledgeIndexService {
    // 内存索引结构
    private List<KnowledgeEntry> knowledgeIndex = new ArrayList<>();
    
    // 启动时扫描
    @PostConstruct
    public void loadIndex() {
        // 递归扫描 knowledge_base/
        // 解析 frontmatter
        // 构建内存索引
    }
    
    // L0 精确匹配
    public List<KnowledgeEntry> exactMatch(String query) {
        // 关键词匹配（不区分大小写）
        // 匹配规则：query 包含 keywords 中的任一词
    }
    
    // 读取文档内容
    public String readDocument(String filePath, int maxChars) {
        // 读取文件，返回前 maxChars 字符
    }
}
```

**数据结构**：
```java
@Data
public class KnowledgeEntry {
    private String filePath;          // knowledge_base/api/payment-errors.md
    private String title;             // 支付网关错误码定义
    private List<String> keywords;    // [ERR_TIMEOUT, 超时, 支付网关]
    private String summary;           // 一句话摘要
    private String category;          // api
    private Map<String, String> sections;  // 预留字段
}
```

### 4. L1 复用

直接调用现有服务：
```java
@Autowired
private VectorSearchService vectorSearchService;

List<VectorSearchService.SearchResult> l1Results = 
    vectorSearchService.searchSimilarDocuments(query, 3, category);
```

### 5. 混合检索工具

**LookupKnowledgeTool**（供 Agent 调用）：
```java
@Tool(name = "lookup_knowledge", 
      description = "查询知识库文档。优先精确匹配，自动补充语义相关片段。")
public LookupResult lookup(
    @P("query") String query,
    @P("section_title") String sectionTitle  // 预留参数，MVP 不实现
) {
    // Step 1: L0 精确匹配
    List<KnowledgeEntry> l0Matches = knowledgeIndexService.exactMatch(query);
    
    // Step 2: 判断是否高置信度（唯一匹配）
    boolean highConfidence = (l0Matches.size() == 1);
    
    // Step 3: L1 条件调用
    List<SearchResult> l1Results = null;
    if (!highConfidence) {
        l1Results = vectorSearchService.searchSimilarDocuments(query, 3, null);
    }
    
    // Step 4: 组装结果
    return buildResult(l0Matches, l1Results, highConfidence);
}
```

**返回格式**：
```json
{
    "found": true,
    "primary": {
        "content": "文档前2000字符...",
        "source": "knowledge_base/api/payment-errors.md",
        "matchType": "exact_L0",
        "confidence": "high",
        "availableSections": null
    },
    "supplement": {
        "content": "Milvus检索到的相关片段...",
        "source": "其他文档路径",
        "matchType": "semantic_L1"
    }
}
```

## 范围

### 核心功能（MVP）
1. ✅ FrontmatterParser：解析 YAML frontmatter（使用 snakeyaml）
2. ✅ KnowledgeIndexService：启动扫描 + 内存索引 + L0 精确匹配
3. ✅ 上传流程增强：保存本地 + 解析 frontmatter + 更新 L0 索引
4. ✅ LookupKnowledgeTool：L0 + L1 混合检索 + 条件调用
5. ✅ ApiDocument.metadata 字段扩展（存储 frontmatter JSON）

### 预留但不实现
- ⏸️ sections 分段加载（`availableSections` 返回 null）
- ⏸️ watchdog 热更新（重启生效）
- ⏸️ L0 索引持久化（内存索引，启动扫描）

## 非目标

- 不修改现有 VectorSearchService 逻辑
- 不修改 Milvus 索引结构
- 不实现文档版本管理
- 不支持其他文件格式（仅 .md）

## 技术选型

| 组件 | 技术选型 | 说明 |
|------|---------|------|
| YAML 解析 | snakeyaml 2.0 | 解析 frontmatter |
| L0 索引 | 内存 `List<KnowledgeEntry>` | 启动扫描，快速查询 |
| L1 检索 | 复用 VectorSearchService | Milvus + BGE-M3 |
| 文件存储 | 本地文件系统 | `knowledge_base/{category}/` |

## devflow 上下文约束

**必须遵守**（来自 phase1-infrastructure）：
- 枚举存储为 VARCHAR，JPA 使用 `@Enumerated(EnumType.STRING)`
- Milvus collection 需 `loadCollection()`
- 复用现有 `VectorSearchService` 接口
- 文档元数据存入 `ApiDocument` 实体

**术语对齐**：
- `ApiDocument`：文档元数据实体，扩展 `metadata` 字段存储 frontmatter
- `category`：文档分类（api/domain/troubleshooting），与 Phase 1 对齐

### 关键假设

1. **L0 高置信度定义：唯一匹配**
   - 假设：1 个匹配结果即为高置信度，不调用 L1
   - 验证方式：✅ grill 阶段已确认
   - 状态：已验证

2. **knowledge_base/ 目录权限**
   - 假设：应用有读写权限
   - 验证方式：启动时创建目录
   - 风险：Docker 部署时路径映射

3. **TEXT 字段存储 JSON**
   - 假设：TEXT 类型可存储 JSON 字符串（< 64KB）
   - 验证方式：✅ grill 阶段已确认
   - 状态：已验证

## 主要风险

### 风险 1：知识库目录权限问题
- **影响**：无法创建 knowledge_base/ 或保存文件
- **概率**：中（Docker 环境常见）
- **缓解**：启动时检查并创建目录，Docker 部署时正确挂载卷
- **检测**：apply 阶段测试文件保存功能

### 风险 2：L0 关键词匹配不准确
- **影响**：误匹配或漏匹配
- **概率**：中（依赖 frontmatter 质量）
- **缓解**：frontmatter keywords 需要精心维护，L1 作为兜底
- **后续**：引入模糊匹配或同义词扩展

### 风险 3：事务一致性（孤儿文件）
- **影响**：文件保存成功但事务回滚，产生孤儿文件
- **概率**：低
- **缓解**：异常时调用 cleanupLocalFile() 清理
- **检测**：集成测试验证

## 验收标准

### 功能验收
1. ✅ 上传带 frontmatter 的 .md 文档成功
2. ✅ L0 精确匹配："ERR_TIMEOUT" → 返回完整文档（matchType=exact_L0）
3. ✅ L0 未匹配："如何优化性能" → 降级到 L1（matchType=semantic_L1）
4. ✅ L0 多个匹配："超时" → 返回 L0 列表 + L1 补充
5. ✅ 缺少 frontmatter 的文档只走 L1

### 性能验收
- L0 查询响应时间 < 10ms
- L0 + L1 组合查询 < 500ms
- 启动扫描时间 < 5s（假设 < 1000 个文档）

### 集成验收
- Agent 调用 `lookup_knowledge("ERR_TIMEOUT")` 返回正确文档
- Agent 调用 `lookup_knowledge("支付失败")` 返回语义相关文档