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
1.8 KiB
1.8 KiB
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）
关键约束
- Frontmatter 规范：必填字段 title, keywords, summary
- L0 高置信度标准：唯一匹配（不调用 L1）
- 文件保存策略：knowledge_base/{category}/{filename}
- 事务一致性：上传失败时清理本地文件
成功标准
- ✅ L0 查询响应时间 < 10ms
- ✅ L0+L1 组合查询 < 500ms
- ✅ 单元测试覆盖率 > 80%
- ✅ 应用启动时 L0 索引正常加载