From be24de9cedad520639eed1cb3459e75cee9345e8 Mon Sep 17 00:00:00 2001 From: bizwings Date: Mon, 22 Jun 2026 23:13:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20BIZ-19=20Agent=20=E7=9F=A5=E8=AF=86?= =?UTF-8?q?=E5=BA=93=E9=9B=86=E6=88=90=E6=8C=87=E5=8D=97=20+=20=E7=9F=A5?= =?UTF-8?q?=E8=AF=86=E6=9F=A5=E8=AF=A2=E6=9C=80=E4=BD=B3=E5=AE=9E=E8=B7=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: multica-agent --- docs/Agent 知识库集成指南.md | 130 +++++++++++++++++++++++++++++ docs/知识查询最佳实践.md | 156 +++++++++++++++++++++++++++++++++++ 2 files changed, 286 insertions(+) create mode 100644 docs/Agent 知识库集成指南.md create mode 100644 docs/知识查询最佳实践.md diff --git a/docs/Agent 知识库集成指南.md b/docs/Agent 知识库集成指南.md new file mode 100644 index 0000000..ff789ab --- /dev/null +++ b/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 — 角色特定查询指引 \ No newline at end of file diff --git a/docs/知识查询最佳实践.md b/docs/知识查询最佳实践.md new file mode 100644 index 0000000..f2d8c7f --- /dev/null +++ b/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` — 集成方案总览 \ No newline at end of file