docs(mvp): 添加知识库检索架构和使用文档

新增文档： - mvp/architecture/knowledge-retrieval-architecture.md * 架构位置和数据流说明 * L0+L1 混合检索流程图 * 核心组件详细设计 * 与现有架构的集成方式 * 性能指标和可观测性 - mvp/architecture/knowledge-retrieval-usage.md * 快速开始指南 * 文档格式要求和最佳实践 * 使用场景和示例 * 故障排查和性能优化 * 维护知识库的完整流程更新文档： - mvp/README.md - 添加知识库检索文档入口完善 MVP 架构文档，为后续开发和维护提供完整参考
2026-06-24 16:26:15 +08:00
parent 3956426c97
commit 36abfc4675
5 changed files with 997 additions and 0 deletions
@@ -0,0 +1,109 @@
+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，再次查询验证内存索引是否已更新。
@@ -0,0 +1,168 @@
+ 
+MVP 开发计划：知识库查询系统
+一、需求概述
+构建一个最小化但可运行的知识库查询系统，让诊断 Agent 在排查问题时，能够按需查询知识文档（如接口定义、错误码解释、排障指南）。
+二、核心机制
+整个系统围绕两个核心概念：索引目录 和 查询工具。
+
+索引目录（_index.yaml）：知识库的“地图”，记录每个文档的路径、摘要和关键词。
+查询工具（lookup_knowledge）：Agent 调用的函数，根据关键词匹配索引目录，返回对应文档内容。
+
+三、知识库目录结构
+
+知识库中的所有文档存放在 knowledge_base/ 目录下，按以下结构组织：
+```
+
+knowledge_base/
+├── _index.yaml                    # MVP 阶段手动编写
+├── interfaces/                    # 接口文档
+│   └── payment-gateway/
+│       └── _errors.md            # 支付网关特有错误码
+└── troubleshooting/              # 排障指南
+    └── gateway-timeout.md        # 支付网关超时排查
+```
+每个文档头部必须包含 YAML 元数据（front matter）：
+```
+---
+title: 支付网关错误码定义
+type: error_definition
+keywords: [ERR_TIMEOUT, 超时, timeout, ERR_BALANCE, 余额不足]
+---
+```
+
+# 内容正文
+
+四、_index.yaml 格式（MVP）
+_index.yaml 内容示例：
+files:
+  - file: "interfaces/payment-gateway/_errors.md"
+    summary: "支付网关特有错误码：ERR_TIMEOUT(超时)、ERR_BALANCE(余额不足)"
+    keywords: ["ERR_TIMEOUT", "超时", "timeout", "ERR_BALANCE", "余额不足"]
+
+  - file: "troubleshooting/gateway-timeout.md"
+    summary: "支付网关超时的排查步骤和解决方法"
+    keywords: ["超时", "timeout", "网关", "支付失败"]
+说明：
+
+file：相对于 knowledge_base/ 的路径
+summary：一句话文档摘要
+keywords：该文档相关的关键词（用于匹配查询）
+
+五、lookup_knowledge 函数规范
+5.1 函数签名
+def lookup_knowledge(query_text: str) -> dict:
+    """
+    功能：查询知识库，返回匹配的文档内容
+
+    参数：
+        query_text: str - 查询关键词（如错误码、接口名、问题描述）
+
+    返回：
+        dict - {"found": bool, "content": str, "source": str}
+            found: 是否找到匹配文档
+            content: 文档内容（前 2000 字符）
+            source: 匹配到的文件路径
+    """
+5.2 执行逻辑
+
+读取 knowledge_base/_index.yaml 文件的 files 列表
+遍历每个条目，检查 query_text 中的关键词是否出现在该条目的 summary 或 keywords 中
+如果找到匹配：
+
+根据 file 路径读取对应 Markdown 文件
+返回内容的前 2000 字符
+
+如果未找到匹配：
+
+返回 {"found": False, "content": "", "source": ""}
+
+5.3 关键约束
+
+MVP 阶段不做向量搜索，仅做关键词匹配
+关键词匹配规则：query_text 中包含的任何词，与 keywords 数组中的任何词相同即视为匹配
+返回内容限制在 2000 字符以内，避免浪费 Token
+不区分大小写（ERR_TIMEOUT 和 err_timeout 应匹配）
+
+六、Agent 集成规范
+6.1 工具注册
+将 lookup_knowledge 注册为 Agent 的可用工具之一，工具定义如下：
+{
+    "name": "lookup_knowledge",
+    "description": "查询知识库文档。传入你想查的关键词（如错误码、接口名、问题描述），返回对应的文档内容。",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query_text": {
+                "type": "string",
+                "description": "查询关键词，例如 'ERR_TIMEOUT'、'支付网关超时'"
+            }
+        },
+        "required": ["query_text"]
+    }
+}
+6.2 System Prompt 指示
+在传给 LLM 的 System Prompt 中，加入以下指示：
+## 知识查询规则
+
+当你诊断过程中拿到具体信息（如错误码、接口名）后，如需查询其定义或背景知识，请使用 `lookup_knowledge` 工具。典型触发时机：
+- 查到了错误码，需要了解其含义
+- 确认了接口名，需要查看接口文档
+- 需要排障指南
+
+示例：查到错误码 ERR_TIMEOUT → 调用 lookup_knowledge("ERR_TIMEOUT")
+
+七、验收标准
+7.1 功能测试
+测试编号测试场景输入预期输出TC-001查询已知错误码"ERR_TIMEOUT"返回 _errors.md 中 ERR_TIMEOUT 的定义TC-002查询已知关键词"支付网关超时"返回 gateway-timeout.md 内容TC-003查询不存在的内容"未知错误码XYZ"返回 {"found": False}TC-004内容长度限制很长的文档返回内容不超过 2000 字符
+7.2 集成测试
+完成一次完整诊断流程：
+用户提问: "订单123为什么支付失败"
+→ Agent 查订单状态 → 发现错误码 ERR_TIMEOUT
+→ Agent 调用 lookup_knowledge("ERR_TIMEOUT") → 获取错误码定义
+→ Agent 结合日志输出诊断报告
+
+八、实施步骤
+Step 1：准备知识库
+
+创建 knowledge_base/ 目录
+创建至少 2 个 Markdown 文档（含 YAML 头部）
+手动编写 _index.yaml（不超过 10 个条目）
+
+Step 2：实现工具函数
+
+在 Agent 代码中实现 lookup_knowledge 函数
+实现从 _index.yaml 读取和关键词匹配逻辑
+实现从文件系统读取 Markdown 内容
+
+Step 3：集成到 Agent
+
+将 lookup_knowledge 注册为 Agent 的工具
+在 System Prompt 中加入知识查询规则
+验证工具是否能正常被 LLM 调用
+
+Step 4：端到端验证
+
+跑通至少一个完整诊断流程
+验证查询结果正确性
+验证未匹配时的兜底逻辑
+
+九、不纳入 MVP 的范围（后续再做）
+
+不支持向量检索（后续用 BGE-M3 + Milvus）
+不支持自动生成 _index.yaml（后续用脚本自动生成）
+不支持多轮对话中的知识缓存（后续用 Redis）
+不支持文档版本管理（后续用 Git）
+
+十、代码示例（参考，非强制）
+以下是 lookup_knowledge 的核心逻辑伪代码，供理解参考：
+读取 _index.yaml
+解析为 files 列表
+
+for each file in files:
+    if query_text 中的任意关键词 匹配 file.keywords 中的任意条目:
+        读取 file.path 指向的 Markdown 文件
+        返回 content 的前 2000 字符
+        标记 found=True
+
+如果没有匹配:
+    返回 found=False