5.5 KiB
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 调用。
- 函数签名 def lookup_knowledge(query_text: str, section_title: str = None) -> dict:
- 执行逻辑（严格按顺序执行） 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，再次查询验证内存索引是否已更新。