zhuyongxin
36abfc4675
新增文档： - mvp/architecture/knowledge-retrieval-architecture.md * 架构位置和数据流说明 * L0+L1 混合检索流程图 * 核心组件详细设计 * 与现有架构的集成方式 * 性能指标和可观测性 - mvp/architecture/knowledge-retrieval-usage.md * 快速开始指南 * 文档格式要求和最佳实践 * 使用场景和示例 * 故障排查和性能优化 * 维护知识库的完整流程 更新文档： - mvp/README.md - 添加知识库检索文档入口 完善 MVP 架构文档，为后续开发和维护提供完整参考
110 lines
5.5 KiB
Markdown
110 lines
5.5 KiB
Markdown
Coding Agent 执行清单：L0+L1 混合检索 MVP 实现
|
||
你可以直接将以下完整的指令文档复制给你的 Coding Agent（如 Claude Code、Cursor），让它严格按照此规范实现。
|
||
|
||
📋 任务总览
|
||
在现有的 Milvus 向量检索（L1）基础之上，新增一层基于 Markdown 文件头的精确匹配检索（L0），构建一个“先精确、后语义”的混合检索工具 lookup_knowledge。
|
||
|
||
一、文件头规范定义
|
||
所有存放在 knowledge_base/ 目录下的 .md 知识库文档，必须在文件最顶部添加 YAML Frontmatter（被 --- 包裹），包含以下字段：
|
||
---
|
||
title: 支付网关错误码定义 # 【必填】文档标题
|
||
keywords: [ERR_TIMEOUT, 超时, 支付网关] # 【必填】核心关键词数组，用于精确匹配
|
||
summary: 记录了支付网关所有核心错误码的含义及排查方向。 # 【必填】文档一句话摘要，用于辅助匹配
|
||
sections: # 【可选】大文件的章节锚点，用于渐进式读取
|
||
超时排查: "## 1. 超时类错误"
|
||
限流排查: "## 2. 限流类错误"
|
||
---
|
||
# 这里是 Markdown 正文内容...
|
||
约束：
|
||
|
||
文件头必须在文件的最顶部，前面不能有空行。
|
||
keywords 仅需包含错误码、服务名、专有名词等适合精确匹配的词，不需要长句。
|
||
|
||
二、索引模块：启动加载与热更新
|
||
|
||
解析依赖：使用 python-frontmatter 库解析 MD 文件头。
|
||
启动扫描：项目启动时，递归扫描 knowledge_base/ 目录下所有 .md 文件，提取元数据。
|
||
内存结构：将提取的元数据组装为一个全局列表 KNOWLEDGE_INDEX，结构如下：
|
||
KNOWLEDGE_INDEX = [
|
||
{
|
||
"file": "knowledge_base/payment/errors.md",
|
||
"title": "支付网关错误码定义",
|
||
"keywords": ["ERR_TIMEOUT", "超时", "支付网关"],
|
||
"summary": "记录了...",
|
||
"sections": {"超时排查": "## 1. 超时类错误"}
|
||
}
|
||
]
|
||
|
||
热更新监听：使用 watchdog 库监听 knowledge_base/ 目录。当 .md 文件被新增或修改时，重新解析该文件头，并增量更新内存中的 KNOWLEDGE_INDEX 字典。
|
||
|
||
三、工具函数实现：lookup_knowledge
|
||
实现一个名为 lookup_knowledge 的工具供 Agent 调用。
|
||
1. 函数签名
|
||
def lookup_knowledge(query_text: str, section_title: str = None) -> dict:
|
||
2. 执行逻辑（严格按顺序执行）
|
||
Step 1: Layer 0 精确匹配（前置导航）
|
||
遍历 KNOWLEDGE_INDEX，将 query_text 与每个条目做大小写不敏感的匹配：
|
||
|
||
匹配规则：检查 query_text 是否包含 keywords 数组中的任一词汇；或者 query_text 是否与 summary 有一定的文本重合度（防自然语言漏匹配）。
|
||
命中处理：
|
||
|
||
如果命中，获取该条目的 file 路径。
|
||
如果传入了 section_title：通过正则表达式，从文件正文中截取 sections[section_title] 对应的标题及其下方段落内容返回。
|
||
如果未传入 section_title：直接 open() 读取文件内容，截取前 2000 字符返回。
|
||
标记 match_type: "exact_L0"。
|
||
|
||
Step 2: Layer 1 语义检索补充（原 RAG）
|
||
|
||
触发条件：无论 L0 是否命中，都调用现有的 Milvus 向量检索逻辑（BGE-M3 embedding + Milvus search），获取 Top-1 的相关 Chunk。
|
||
目的：作为补充上下文，提供语义关联信息。
|
||
标记：match_type: "semantic_L1"。
|
||
|
||
Step 3: 结果组装与返回
|
||
将 L0 和 L1 的结果组装成统一格式返回给 Agent。如果两层均无结果，found 置为 False。
|
||
3. 返回格式规范
|
||
{
|
||
"found": true,
|
||
"primary": {
|
||
"content": "文档前2000字或指定section内容...",
|
||
"source": "knowledge_base/payment/errors.md",
|
||
"match_type": "exact_L0"
|
||
},
|
||
"supplement": {
|
||
"content": "Milvus检索到的Top-1语义片段...",
|
||
"source": "其他文档路径",
|
||
"match_type": "semantic_L1"
|
||
}
|
||
}
|
||
(注：如果 L0 未命中，primary 字段为 null，仅返回 supplement。)
|
||
|
||
四、Agent 工具注册定义
|
||
将 lookup_knowledge 注册为 Agent 可用的工具，工具描述 JSON 如下：
|
||
{
|
||
"name": "lookup_knowledge",
|
||
"description": "查询知识库文档。系统会先尝试通过关键词精确匹配完整文档，并自动补充语义相关的片段。如果已知具体的文档章节，可传入 section_title 获取特定段落。",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"query_text": {
|
||
"type": "string",
|
||
"description": "查询关键词，例如 'ERR_TIMEOUT'、'支付网关超时'"
|
||
},
|
||
"section_title": {
|
||
"type": "string",
|
||
"description": "可选。如果primary结果返回了sections目录，可通过指定章节标题来获取该章节的详细内容，避免读取大文件超出长度限制。"
|
||
}
|
||
},
|
||
"required": ["query_text"]
|
||
}
|
||
}
|
||
|
||
五、实施与验收标准
|
||
请 Coding Agent 按以下步骤实施并自测：
|
||
|
||
安装依赖：pip install python-frontmatter watchdog
|
||
按照规范实现文件头解析与 watchdog 监听逻辑。
|
||
改造现有 Agent 代码，按上述逻辑实现 lookup_knowledge。
|
||
验收用例 1（L0 命中）：创建带文件头的 MD，调用 lookup_knowledge("ERR_TIMEOUT")，验证返回的 primary 是否为完整 MD 内容，supplement 是否为 Milvus 的检索结果。
|
||
验收用例 2（L0 未命中）：调用 lookup_knowledge("如何处理系统异常")，验证 primary 是否为 null，supplement 是否正常返回语义结果。
|
||
验收用例 3（热更新）：在程序运行期间修改 MD 的文件头 keywords，再次查询验证内存索引是否已更新。
|