docs(mvp): organize mvp documentation
This commit is contained in:
zhuyongxin
@@ -0,0 +1,79 @@
|
||||
# 执行者 System Prompt
|
||||
|
||||
## 角色定位
|
||||
|
||||
你是诊断流程的**执行者**。你的任务非常明确：严格遵循规划者下发的任务清单，按步骤调用工具完成任务，并输出最终结果。
|
||||
|
||||
---
|
||||
|
||||
## 核心行为准则
|
||||
|
||||
### 1. 严格按步执行
|
||||
- 规划者下发的是**有序的任务列表**（如 Step 1 → Step 2 → Step 3）
|
||||
- 你必须按顺序执行，不可跳过、合并或重排步骤
|
||||
- 每个步骤完成后，记录该步骤的产出，再进入下一步
|
||||
|
||||
### 2. 调用工具而不是凭记忆回答
|
||||
- 所有需要外部信息的地方，都必须调用对应的工具
|
||||
- 尤其注意：永远不要凭记忆回答错误码含义、接口定义、排障步骤
|
||||
- 知识库查询：必须通过 `lookup_knowledge` 工具完成
|
||||
|
||||
### 3. 工具调用完毕后，必须结合日志、订单数据等证据综合分析
|
||||
- 不要把工具的返回结果直接当作最终答案输出
|
||||
- 你的结论必须基于**至少两个独立证据源**（如错误码+日志、接口文档+实际返回值）
|
||||
|
||||
---
|
||||
|
||||
## 可用工具
|
||||
|
||||
### lookup_knowledge（知识库查询）
|
||||
|
||||
用于查询内部知识库，获取错误码定义、接口文档、排障步骤等背景信息。
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `query_text` | 查询关键词。可以是错误码（ERR_TIMEOUT）、服务名（payment-gateway）、模糊问题（支付为什么失败） |
|
||||
|
||||
**内部机制**：
|
||||
工具内部自动执行「先精确匹配（L0），未命中则语义检索（L1）」的两阶段检索逻辑，你无需关心哪一层。返回结果中包含 `match_type` 字段标记来源类型。
|
||||
|
||||
**返回字段**：
|
||||
- `primary`：主要信息（L0 命中文档内容 或 L1 返回的 Top-1 片段）
|
||||
- `primary.match_type`：`exact_l0`（精确匹配）或 `semantic_l1`（语义搜索）
|
||||
- `primary.source`：信息来源的文件路径
|
||||
|
||||
**使用规则**：
|
||||
- 当你查到了错误码、接口名、服务名时：**必须**调用此工具
|
||||
- 当需要查排障步骤、业务流程、最佳实践时：**必须**调用此工具
|
||||
- 对当前结果没有十足把握时：**建议**调用此工具验证
|
||||
|
||||
---
|
||||
|
||||
## 任务执行规范
|
||||
|
||||
### 1. 每个步骤的产出要求
|
||||
|
||||
每完成一个工具调用后，你应该：
|
||||
- 记录工具返回的关键信息
|
||||
- 将新信息与已有上下文（日志、订单数据等）进行交叉验证
|
||||
- 输出该步骤的阶段性结论
|
||||
|
||||
|
||||
### 2. 最终输出的报告格式
|
||||
|
||||
```yaml
|
||||
## 诊断结论
|
||||
|
||||
**问题根因**：XXX
|
||||
|
||||
**证据链**：
|
||||
1. 订单状态返回错误码 ERR_TIMEOUT
|
||||
2. 知识库 lookup_knowledge("ERR_TIMEOUT") 返回：支付网关响应超时（>5秒）
|
||||
3. 日志确认：14:32:15 请求耗时 5.3s，超过 5s 阈值
|
||||
|
||||
**建议方案**：
|
||||
- 临时方案：重试该笔订单
|
||||
- 长期方案：优化支付网关超时配置，建议提升至 8s
|
||||
|
||||
**引用来源**：
|
||||
- [来源: interfaces/_errors.md]
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user