Files

T

zhuyongxin d6229f3385 feat(knowledge): 完成 L0+L1 混合检索集成

核心功能：
- 新增 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

2026-06-24 16:07:10 +08:00

3.5 KiB

Raw Blame History

Lookup Knowledge Integration - Decisions

关键技术决策

D1: L0 高置信度标准

决策：唯一匹配 = 高置信度，不调用 L1
理由：唯一匹配时已经明确知道用户需要哪个文档，无需额外的语义检索
权衡：可能遗漏相关文档，但换来更快响应（< 10ms vs 500ms）

D2: 文件保存策略

决策：保存到 knowledge_base/{category}/{filename}
理由：

支持 L0 完整文档读取（前 2000 字符）
为未来章节锚点预留基础
便于人工查看和维护

权衡：增加磁盘存储，但文件大小可控（Markdown 文档通常 < 100KB）

D3: metadata 字段类型

决策：TEXT 类型存储 JSON 字符串
理由：

Frontmatter 结构可能扩展
MySQL TEXT 支持最大 64KB（足够）
无需引入 JSON 类型（兼容性）

权衡：查询时需要反序列化，但 metadata 仅用于展示，不参与查询条件

D4: L1 条件调用

决策：仅在 L0 非唯一匹配时调用 L1
理由：

减少不必要的 embedding 调用
保持高置信度场景的低延迟

条件：l0Matches.size() != 1

D5: 事务一致性策略

决策：上传失败时调用 cleanupLocalFile() 清理
理由：避免孤儿文件（数据库记录不存在但文件存在）
实现：try-catch 块 + finally cleanup

实现决策

I1: Frontmatter 解析器

选型：SnakeYAML 2.0
理由：

轻量级，无额外依赖
成熟稳定（Spring Boot 也在用）

I2: L0 索引数据结构

选型：CopyOnWriteArrayList
理由：

读多写少场景（启动加载后主要是查询）
线程安全（支持并发查询）
简单可靠

权衡：写入时复制开销，但 L0 索引更新频率低（仅上传/删除时）

I3: 关键词匹配算法

策略：不区分大小写，双向包含

query.contains(keyword.toLowerCase()) || keyword.toLowerCase().contains(query)

理由：

用户可能输入部分关键词
关键词可能是复合词（如 "支付网关超时"）

I4: 文档读取截断

策略：前 2000 字符 + "..."
理由：

控制返回内容大小（避免 Agent context 溢出）
2000 字符足够覆盖大部分文档摘要和核心内容

可观测性决策

O1: 请求追踪

策略：8 位 UUID 作为 requestId
理由：

足够短（日志可读）
碰撞概率极低（单次会话不会重复）

O2: 日志层次

INFO: 查询请求、匹配结果、总耗时
DEBUG: 置信度判断、L1 触发条件、结果构建
WARN: 文件读取失败、解析失败

风险决策

R1: L0 索引无持久化

风险：应用重启需要重新扫描
缓解：启动扫描通常 < 1s（500 个文档）
接受理由：MVP 阶段优先简单可靠，Phase 2 再优化

R2: Frontmatter 校验宽松

风险：格式错误的 frontmatter 被忽略
缓解：记录 WARN 日志，开发者可追踪
接受理由：允许无 frontmatter 的文档上传（仅走 L1）

Archive 阶段记录

完成时间：2026-06-24

最终状态：

23/23 子任务完成
31/31 单元测试通过
应用成功启动，L0 索引正常加载
Flyway V004 迁移成功执行

关键指标：

L0 查询耗时: < 5ms
L0+L1 组合: < 500ms
启动扫描: < 20ms（1 个文档）

技术债务：无重大技术债务

轻微优化点（可后续改进）：

L0 索引持久化
Frontmatter 校验增强
独立日志文件
Micrometer 指标集成

3.5 KiB Raw Blame History Unescape Escape