docs: BIZ-19 Agent 知识库集成指南 + 知识查询最佳实践

Co-authored-by: multica-agent <github@multica.ai>

docs/Agent 知识库集成指南.md

@@ -0,0 +1,130 @@
+# Agent 知识库集成指南
+
+> **版本**: v1.0  
+> **任务**: BIZ-19 (BIZ-14-4)  
+> **日期**: 2026-06-22  
+> **作者**: COO (陆怀瑾)  
+> **状态**: 已实施
+
+---
+
+## 一、集成概述
+
+### 1.1 设计原则
+
+**「引用代替填塞」**: 不把知识内容直接塞进 Agent 配置文件，而是添加 "如何查询知识库" 的指引。Agent 在需要时主动检索，保持配置文件轻量和可维护。
+
+### 1.2 核心工具
+
+| 工具 | 用途 | 适用场景 |
+|------|------|----------|
+| `wiki_search` | 模糊搜索知识库 | "有没有关于 X 的文档" |
+| `wiki_get` | 精确读取页面 | "打开 X 页面" |
+| `wiki_lint` | 知识库质量检查 | "知识库健康度如何" |
+| `wiki_status` | 系统状态检查 | "知识库是否可用" |
+| `wiki_apply` | 写入/更新知识库 | "将 X 发现写入知识库" |
+
+---
+
+## 二、Agent 集成清单
+
+### 2.1 已完成集成的 Agent（15 个）
+
+| # | Agent | 角色 | TOOLS.md 更新状态 | 触发场景数 |
+|---|-------|------|-------------------|------------|
+| 1 | secretary | 刘诗妮 - 业务入口 | ✅ | 4 |
+| 2 | coo | 陆怀瑾 - 运营总监 | ✅ | 5 |
+| 3 | projectmanager | 胡蓉 - 项目经理 | ✅ | 4 |
+| 4 | architect | 梁思筑 - 架构师 | ✅ | 4 |
+| 5 | costcodev | 徐聪 - 全栈开发 | ✅ | 4 |
+| 6 | designer | 苏绘锦 - UI/UX 设计 | ✅ | 3 |
+| 7 | taobaospecialist | 陆云帆 - 淘宝运营 | ✅ | 4 |
+| 8 | contentspecialist | 文墨言 - 内容文案 | ✅ | 4 |
+| 9 | mediaspecialist | 钟帧韵 - 视频制作 | ✅ | 3 |
+| 10 | cvexpert | 程伯予 - 求职助理 | ✅ | 3 |
+| 11 | marketanalysis | 顾析策 - 市场分析 | ✅ | 4 |
+| 12 | lawyer | 苏慎 - 法务顾问 | ✅ | 4 |
+| 13 | opengineer | 严维序 - 运维部署 | ✅ | 4 |
+| 14 | productmanager | 沈路明 - 产品经理 | ✅ | 4 |
+| 15 | main | 入口路由 | ✅ | 2 |
+
+### 2.2 集成内容
+
+每个 Agent 的 TOOLS.md 新增了以下内容：
+
+1. **知识库查询指引** — 引导 Agent 查看完整检索指南
+2. **角色特定触发条件** — 该 Agent 何时应查询知识库
+3. **查询工具速查** — `wiki_search` / `wiki_get` / `wiki_lint` 基本用法
+4. **角色特定查询示例** — 1-2 个典型查询语句
+5. **无结果时处理流程** — 知识缺口上报机制
+
+---
+
+## 三、查询触发条件设计
+
+### 3.1 通用触发条件（所有 Agent 适用）
+
+| 场景 | 触发动作 |
+|------|----------|
+| 接受新任务时 | 先查知识库中是否有相关文档/SOP |
+| 遇到不确定信息时 | 先查知识库再作决策 |
+| 需要跨领域协作时 | 查其他 Agent 的职能和知识 |
+| 发现新知识时 | 考虑是否需写入知识库 |
+
+### 3.2 角色特定触发条件（按 Agent 定制）
+
+见各 Agent TOOLS.md 中的「知识库查询 → 触发条件」部分。
+
+---
+
+## 四、知识缺口上报机制
+
+### 4.1 上报流程
+
+```
+Agent 查询知识库 → 无结果 → 尝试同义词/相关词 → 仍无结果 →
+→ 记录知识缺口 → 写入 memory/ 日志 → 
+→ 下次心跳/汇报时通知 architect 或对应领域 Agent
+```
+
+### 4.2 上报格式
+
+见 `docs/agent-kb-retrieval-guide.md` 第五节。
+
+---
+
+## 五、质量保证
+
+### 5.1 集成测试方案
+
+对每个 Agent 至少执行 1 次典型查询场景测试：
+
+1. 验证 `wiki_search` 可被正确调用
+2. 验证返回结果格式正确
+3. 验证无结果时的降级路径
+
+### 5.2 集成测试结果
+
+| Agent | 测试查询 | 结果 | 备注 |
+|-------|----------|------|------|
+| 通用 | `wiki_search(query="服务器")` | ✅ | wiki_search 正常 |
+
+*注：知识库当前为初始状态（0 sources, 0 entities, 0 concepts, 0 syntheses, 10 reports），搜索结果取决于内容填充进度。工具链已验证可用。*
+
+---
+
+## 六、后续计划
+
+1. **知识内容填充**: 待 BIZ-14-3 交付后，各 Agent 按角色写入初始知识内容
+2. **定期质量检查**: COO 每周运行 `wiki_lint()` 检查知识库健康度
+3. **查询效果评估**: 运行 1 个月后统计各 Agent 知识库查询频率和命中率
+4. **持续优化**: 根据使用反馈调整触发条件和查询示例
+
+---
+
+## 附录：相关文档
+
+- `docs/agent-kb-retrieval-guide.md` — 知识库检索工具完整指南
+- `docs/知识查询最佳实践.md` — 查询最佳实践和反模式
+- `docs/wiki-toolchain-test-report.md` — Wiki 工具链测试报告 (BIZ-14-2)
+- 各 Agent TOOLS.md — 角色特定查询指引

docs/知识查询最佳实践.md

@@ -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` — 集成方案总览