EnterpriseArchitect/docs/agent-kb-retrieval-guide.md

Agent 知识库检索指南

版本: v1.0
维护: 严维序 (opengineer)
日期: 2026-06-22

---

一、检索工具选择决策树

需要检索知识库？
├── 精确查找已知页面 → wiki_get(lookup="页面路径")
├── 搜索未知内容
│   ├── 关键词明确 → wiki_search(query="关键词")
│   ├── 语义模糊 → wiki_search(query="自然语言问题")
│   └── 需要文档全文 → qmd query / qmd search
├── 需要深度分析（跨文档） → wiki_search + wiki_get 组合
├── 质量检查 → wiki_lint()
└── 系统状态确认 → wiki_status()

---

二、工具对比速查表

维度	wiki_search	wiki_get	qmd (CLI)
用途	模糊搜索/发现	精确读取	全文/语义搜索
查询类型	标题+路径+正文	精确路径或 ID	lex/vec/hyde 多类型
返回内容	匹配片段+元数据	完整页面内容	排序结果+评分
速度	快	最快	依赖索引（首次慢）
适用场景	"有没有关于 X 的文档"	"打开 X 页面"	"找所有涉及 Y 的内容"
依赖	无（OpenClaw 内置）	无（OpenClaw 内置）	QMD 服务（需运行）
搜索范围	Wiki vault	Wiki vault	注册的 markdown 目录

---

三、查询语句构造示例

wiki_search

简单关键词搜索:

wiki_search(query="nginx 配置")

多词精确搜索:

wiki_search(query="deployment pipeline CI/CD")

语义问题搜索:

wiki_search(query="如何配置 nginx 反向代理")

限制结果数量:

wiki_search(query="监控告警", maxResults=5)

wiki_get

按页面标题查找:

wiki_get(lookup="服务器清单")

按文件路径查找:

wiki_get(lookup="docs/deployment-guide")

分页读取大文件:

wiki_get(lookup="长文档", fromLine=1, lineCount=50)

qmd (CLI)

关键词搜索:

qmd search "nginx logrotate configuration"

语义搜索:

qmd query "如何解决 nginx 日志轮转失败的问题"

结构化搜索 (JSON):

qmd query --json --explain "nginx logrotate error"

多类型组合:

qmd query $'lex: nginx logrotate\nvec: how to fix log rotation failure'

---

四、结果处理流程

搜索结果
├── 有匹配结果
│   ├── 1-3 个结果 → wiki_get 逐个读取完整内容
│   ├── 4-10 个结果 → 按评分排序，取前 3 个读取
│   └── 10+ 个结果 → 收窄搜索词重新搜索
├── 无结果
│   ├── 尝试同义词/相关词重新搜索
│   ├── 尝试 qmd 搜索（如果 wiki_search 无结果）
│   └── 仍无结果 → 触发知识缺口上报
└── 结果不相关
    └── 调整查询词 → 重新搜索 → 仍不相关 → 上报缺口

---

五、知识缺口上报机制

触发条件

1. wiki_search 和 qmd 均无匹配结果
2. 搜索结果与需求明显不相关
3. 找到的文档内容已过时或不完整

上报格式

缺口上报应包含以下信息：

【知识缺口】

- 查询意图: [用户/Agent 想了解什么]
- 已尝试检索词: [用过的搜索词列表]
- 已搜索工具: [wiki_search / qmd]
- 期望内容: [期望知识库中应有什么内容]
- 紧急程度: [high / normal / low]
- 建议: [建议谁负责补充、建议写入什么内容]

上报目标

• 紧急缺口 → architect（梁思筑）
• 文档更新缺口 → 对应领域 Agent
• 通用知识缺口 → projectmanager（胡蓉）

---

六、最佳实践

DO ✅

• 先用 wiki_search 发现，再用 wiki_get 精读
• 搜索无结果时尝试多种表述方式
• wiki_search 结果多时限制 maxResults
• 大文档用 fromLine/lineCount 分页读取
• 定期运行 wiki_lint 检查知识库质量
• 每次重要发现后考虑是否需写入知识库

DON'T ❌

• 不要跳过 wiki_search 直接用 wiki_get 猜测路径
• 不要单次读取超大页面全部内容（影响上下文）
• 不要忽略 wiki_lint 的报告建议
• 不要在 wiki_search 无结果后直接放弃（尝试 qmd）
• 不要将敏感信息（密钥/密码）写入 Wiki

---

七、示例工作流

场景: 查找"如何部署 Node.js 服务"

1. wiki_search(query="Node.js 部署")
   → 返回 2 个匹配: "服务部署规范", "Node.js 开发指南"

2. wiki_get(lookup="服务部署规范")
   → 读取完整内容，找到 systemd 配置部分

3. wiki_get(lookup="Node.js 开发指南", fromLine=30, lineCount=20)
   → 补充读取环境变量和启动参数配置

4. 整合信息 → 回答 Agent 问题

场景: 知识库中无结果

1. wiki_search(query="淘宝 API 对接")
   → No results

2. qmd query "淘宝 API"
   → No results

3. 上报知识缺口:
   【知识缺口】
   - 查询意图: 淘宝电商 API 对接文档
   - 已尝试: wiki_search("淘宝 API 对接"), qmd query "淘宝 API"
   - 期望内容: 淘宝开放平台 API 对接指南
   - 紧急程度: normal
   - 建议: 联系 taobaospecialist (陆云帆) 补充