6.0 KiB
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