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,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