# Lookup Knowledge Integration - Brief

## 背景

当前系统只有 L1 向量语义检索（Milvus + BGE-M3），在处理精确关键词查询时效率不够高：
- 需要调用 embedding API（约 100-300ms）
- 语义检索可能返回相似但不精确的结果
- 无法快速定位已知关键词对应的完整文档

## 目标

为 Agent 提供混合检索工具（lookup_knowledge），优先使用 L0 精确匹配知识库元数据，必要时补充 L1 语义检索。

**核心价值**：
- L0 唯一匹配：< 10ms 响应（不调用 embedding）
- L0 多匹配/未匹配：自动补充 L1 语义结果
- Agent 获得高置信度反馈（confidence: high/low）

## 范围

### In Scope
- ✅ Frontmatter 解析器（解析 Markdown YAML frontmatter）
- ✅ L0 内存索引（启动扫描 + 精确匹配）
- ✅ 文档上传增强（保存本地 + 解析 frontmatter + L0 索引同步）
- ✅ LookupKnowledgeTool（L0+L1 混合检索）
- ✅ 数据库迁移（api_document.metadata 字段）

### Out of Scope（Phase 2）
- ❌ 章节锚点功能（sectionTitle 参数预留）
- ❌ L0 索引持久化（当前内存，重启重建）
- ❌ 批量导入工具
- ❌ 知识库管理 API

## 非目标

- 不替代 L1 语义检索（L1 仍然是核心能力）
- 不支持模糊搜索（L0 只做精确关键词匹配）
- 不实现全文索引（复杂查询仍走 L1）

## 关键约束

1. **Frontmatter 规范**：必填字段 title, keywords, summary
2. **L0 高置信度标准**：唯一匹配（不调用 L1）
3. **文件保存策略**：knowledge_base/{category}/{filename}
4. **事务一致性**：上传失败时清理本地文件

## 成功标准

- ✅ L0 查询响应时间 < 10ms
- ✅ L0+L1 组合查询 < 500ms
- ✅ 单元测试覆盖率 > 80%
- ✅ 应用启动时 L0 索引正常加载