docs: BIZ-19 Agent 知识库集成指南 + 知识查询最佳实践
Co-authored-by: multica-agent <github@multica.ai>
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
# 知识查询最佳实践
|
||||
|
||||
> **版本**: v1.0
|
||||
> **任务**: BIZ-19 (BIZ-14-4)
|
||||
> **日期**: 2026-06-22
|
||||
|
||||
---
|
||||
|
||||
## 一、查询策略
|
||||
|
||||
### 1.1 渐进式检索原则
|
||||
|
||||
```
|
||||
先宽后窄 → 先模糊后精确 → 先搜索后读取
|
||||
```
|
||||
|
||||
**标准流程**：
|
||||
1. `wiki_search(query="关键词")` — 发现有哪些相关内容
|
||||
2. `wiki_get(lookup="匹配页面")` — 精确读取具体内容
|
||||
3. 如搜索结果过多（>10） → 收窄关键词重新搜索
|
||||
4. 如搜索结果与需求不相关 → 调整表述方式重新搜索
|
||||
|
||||
### 1.2 查询词构造技巧
|
||||
|
||||
#### DO ✅
|
||||
|
||||
| 技巧 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| 用领域特定术语 | `wiki_search(query="nginx 反向代理")` | 专业词汇提升精确度 |
|
||||
| 用动词+对象 | `wiki_search(query="部署 Node.js")` | 明确查询意图 |
|
||||
| 用自然语言问题 | `wiki_search(query="如何配置 nginx logrotate")` | 适合语义检索 |
|
||||
| 用缩写和全称组合 | `wiki_search(query="CI/CD 持续集成")` | 覆盖不同表述 |
|
||||
| 分步搜索 | 先搜 "nginx"，再搜 "nginx 日志" | 逐步收窄范围 |
|
||||
|
||||
#### DON'T ❌
|
||||
|
||||
| 反模式 | 错误示例 | 问题 |
|
||||
|--------|----------|------|
|
||||
| 过于泛化的词 | `wiki_search(query="配置")` | 结果太多太杂 |
|
||||
| 过于具体的短语 | `wiki_search(query="192.168.1.99 端口 22 上的 nginx")` | 命中率低 |
|
||||
| 跳过搜索直接 guess 路径 | `wiki_get(lookup="随便猜的页面名")` | 大概率找不到 |
|
||||
| 一次加载超大页面 | `wiki_get(lookup="巨型文档")` | 超出上下文容量 |
|
||||
| 无结果后直接放弃 | 只搜一次就说"知识库没内容" | 可能是查询词不准确 |
|
||||
|
||||
---
|
||||
|
||||
## 二、结果处理
|
||||
|
||||
### 2.1 匹配结果数量处理
|
||||
|
||||
| 结果数 | 处理方式 |
|
||||
|--------|----------|
|
||||
| 0 | 尝试同义词/相关词 → qmd 搜索 → 上报知识缺口 |
|
||||
| 1-3 | 逐个 `wiki_get` 读取完整内容 |
|
||||
| 4-10 | 按评分排序，取前 3 个读取 |
|
||||
| 10+ | 收窄搜索词重新搜索 |
|
||||
|
||||
### 2.2 大页面分页读取
|
||||
|
||||
```bash
|
||||
# 超过 100 行的页面，分页读取
|
||||
wiki_get(lookup="长文档标题", fromLine=1, lineCount=50) # 第一部分
|
||||
wiki_get(lookup="长文档标题", fromLine=51, lineCount=50) # 第二部分
|
||||
```
|
||||
|
||||
### 2.3 信息来源交叉验证
|
||||
|
||||
当多个查询返回不同信息时：
|
||||
1. 检查页面更新时间（优先信任较新的）
|
||||
2. 交叉对比多个来源
|
||||
3. 如信息冲突 → 标记为"需确认"，汇报给 architect
|
||||
|
||||
---
|
||||
|
||||
## 三、知识缺口处理
|
||||
|
||||
### 3.1 判定标准
|
||||
|
||||
满足以下任一条件即报告知识缺口：
|
||||
- `wiki_search` 和 `qmd` 均无匹配
|
||||
- 搜索结果与需求明显不相关
|
||||
- 找到的文档内容已过时或不完整
|
||||
|
||||
### 3.2 上报模板
|
||||
|
||||
```
|
||||
【知识缺口 - YYYY-MM-DD】
|
||||
|
||||
- 查询 Agent: [Agent 名称]
|
||||
- 查询意图: [想了解什么]
|
||||
- 已尝试检索: [用过的搜索词, 换行列出]
|
||||
- 已使用工具: wiki_search / qmd
|
||||
- 期望内容: [知识库中应有什么]
|
||||
- 紧急程度: high / normal / low
|
||||
- 建议: [谁补充、什么内容]
|
||||
```
|
||||
|
||||
### 3.3 上报路径
|
||||
|
||||
| 缺口类型 | 上报目标 |
|
||||
|----------|----------|
|
||||
| 架构/技术 | architect (梁思筑) |
|
||||
| 业务/流程 | projectmanager (胡蓉) |
|
||||
| 法务/合规 | lawyer (苏慎) |
|
||||
| 市场/分析 | marketanalysis (顾析策) |
|
||||
| 通用/不确定 | COO (陆怀瑾) — 由 COO 分配 |
|
||||
|
||||
---
|
||||
|
||||
## 四、知识库写入准则
|
||||
|
||||
### 4.1 何时写入
|
||||
|
||||
- 完成重要决策后（如架构选型、策略调整）
|
||||
- 发现可复用的模板/清单
|
||||
- 完成深度分析后（市场报告、竞品分析）
|
||||
- 知识缺口被填补后
|
||||
|
||||
### 4.2 写入工具选择
|
||||
|
||||
| 场景 | 工具 |
|
||||
|------|------|
|
||||
| 创建新知识页面 | `wiki_apply(op="create_synthesis", ...)` |
|
||||
| 更新已有页面元数据 | `wiki_apply(op="update_metadata", ...)` |
|
||||
|
||||
### 4.3 不写入的内容
|
||||
|
||||
- 机密信息（密码、密钥、token）
|
||||
- 临时信息（当天的具体任务进度）
|
||||
- 已过时会被频繁更新的数据
|
||||
- 纯个人笔记（放 `memory/` 下）
|
||||
|
||||
---
|
||||
|
||||
## 五、定期维护
|
||||
|
||||
### 5.1 COO 每周检查清单
|
||||
|
||||
- [ ] 运行 `wiki_lint()` 检查质量
|
||||
- [ ] 统计各 Agent 知识库查询频率
|
||||
- [ ] 清理过时页面
|
||||
- [ ] 评估知识缺口数量和解决率
|
||||
- [ ] 输出知识库运营周报
|
||||
|
||||
### 5.2 Agent 自检清单
|
||||
|
||||
每次心跳时：
|
||||
- [ ] 上次查询的知识缺口是否已上报
|
||||
- [ ] 本轮工作中是否有应写入知识库的发现
|
||||
|
||||
---
|
||||
|
||||
## 附录
|
||||
|
||||
- `docs/agent-kb-retrieval-guide.md` — 工具使用完整指南
|
||||
- `docs/Agent 知识库集成指南.md` — 集成方案总览
|
||||
Reference in New Issue
Block a user