zhuyongxin
d6229f3385
核心功能： - 新增 FrontmatterParser 解析 YAML frontmatter - 新增 KnowledgeIndexService L0 内存索引 - 新增 LookupKnowledgeTool 混合检索工具 - 增强 DocumentManagementService 文件保存和索引同步 技术实现： - 数据库迁移 V004: api_document.metadata (TEXT) - 依赖新增: snakeyaml 2.0 - 配置新增: knowledge.base-path - 可观测性: requestId 追踪 + 性能日志 质量保证： - 单元测试: 31/31 通过 - 测试覆盖: FrontmatterParser(11), KnowledgeIndexService(13), LookupKnowledgeTool(7) - 启动验证: L0 索引正常加载 归档文档： - OpenSpec: openspec/changes/lookup-knowledge-integration/ - devflow 档案: devflow/projects/2026-06-24-lookup-knowledge-integration/ - handoff: handoff/2026-06-24-lookup-knowledge-integration.md
53 lines
1.8 KiB
Markdown
53 lines
1.8 KiB
Markdown
# 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 索引正常加载
|