zhuyongxin
c86045b33f
归档信息： - 变更名称：phase-1-infrastructure - 工作流：spec-driven - 归档位置：openspec/changes/archive/2026-06-23-phase-1-infrastructure/ 完成情况： - ✅ 所有产物完成（proposal, design, specs, tasks） - ✅ 任务完成：33/35 (94%) - ⚠️ 2 个任务跳过（混合检索、集成测试，有充分理由） 验收结果： - ✅ 静态验证：编译通过 - ✅ 脚本验证：16/16 单元测试通过 - ✅ 端到端验证：上传→索引→检索→删除完整流程 Delta Specs： - 跳过同步（用户选择） - functional-specs.md 保留在归档目录中 devflow 档案： - ✅ 已完整回填（brief, evidence, decisions, acceptance） - ✅ devflow/index.md 状态更新为 archived
169 lines
6.0 KiB
Markdown
169 lines
6.0 KiB
Markdown
|
||
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
|