集成方案设计

3.1 现有 Agent 机器人架构分析

根据你的描述，你的 Agent 机器人具有以下特征：

• 输入渠道: Telegram / Discord
• 核心能力:
  • 接收自然语言指令
  • 网络搜索
  • 爬取页面内容
  • 生成代码
• 当前痛点: Token 消耗过大，需要将大量上下文塞进 LLM

当前工作流程的问题

用户请求 → Telegram/Discord Bot → Agent → 搜索/爬取 → 生成代码
                           ↓
                    [问题：大量原始数据直接送入 LLM]
                           ↓
                    高 Token 消耗 + 可能超出上下文限制

3.2 qmd 集成架构设计

方案 A: 直接 CLI 集成（推荐用于快速验证）

这是最直接的集成方式，通过调用 qmd 命令行工具实现：

用户请求 → Telegram/Discord Bot → Agent 
                                        ↓
                                   判断是否需要知识检索
                                        ↓
                              是 → 调用 qmd query/search
                                        ↓
                                   获取相关文档片段
                                        ↓
                                   精简上下文送入 LLM
                                        ↓
                              生成响应 → 返回用户

优点:

• 实现简单，无需修改 qmd 代码
• 立即可用，快速验证可行性
• 灵活性高，可自定义调用逻辑

缺点:

• 需要在本机安装 qmd
• 进程间通信有一定开销
• 错误处理依赖命令行返回值

方案 B: MCP 服务器集成（推荐用于生产环境）

利用 qmd 内置的 MCP 服务器，实现更深度的集成：

┌─────────────────────────────────────────────────────────────┐
│                    Agent 机器人系统                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌──────────────┐    │
│  │ Telegram    │    │ Discord     │    │ 其他渠道      │    │
│  │ Bot         │    │ Bot         │    │              │    │
│  └──────┬──────┘    └──────┬──────┘    └──────┬───────┘    │
│         └─────────────────┬───────────────────┘             │
│                           ↓                                 │
│                   ┌───────────────┐                        │
│                   │  消息路由器    │                        │
│                   └───────┬───────┘                        │
│                           ↓                                 │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Agent 核心处理逻辑                        │  │
│  │  ┌────────────────────────────────────────────────┐  │  │
│  │  │ 意图识别 → 工具选择 → 执行 → 响应生成              │  │  │
│  │  └────────────────────────────────────────────────┘  │  │
│  └────────────────────────┬─────────────────────────────┘  │
│                           ↓                                 │
│              ┌─────────────────────────┐                   │
│              │     qmd MCP 客户端       │                   │
│              │  ┌───────────────────┐  │                   │
│              │  │ qmd_search        │  │                   │
│              │  │ qmd_vsearch       │  │                   │
│              │  │ qmd_query         │  │                   │
│              │  │ qmd_get           │  │                   │
│              │  │ qmd_multi_get     │  │                   │
│              │  └───────────────────┘  │                   │
│              └───────────┬─────────────┘                   │
│                          ↓ (MCP Protocol)                  │
│              ┌─────────────────────────┐                   │
│              │     qmd MCP 服务器       │                   │
│              └───────────┬─────────────┘                   │
│                          ↓                                 │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              qmd 本地搜索引擎                          │  │
│  │  ┌─────────┐ ┌──────────┐ ┌──────────┐              │  │
│  │  │ BM25    │ │ Vector   │ │ Reranker │              │  │
│  │  │ Index   │ │ Index    │ │ Model    │              │  │
│  │  └─────────┘ └──────────┘ └──────────┘              │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

MCP 集成的优势:

• 标准化的工具调用接口
• 类型安全的参数传递
• 更好的错误处理和状态管理
• 支持多个 Agent 共享同一个 qmd 实例

3.3 数据流设计

场景 1: 基于历史文档的代码生成

用户: "帮我写一个用户认证模块，参考我们之前的项目规范"

Agent 处理流程:
1. 解析意图：需要参考历史项目文档
2. 调用 qmd: qmd_query "user authentication project specification"
3. qmd 返回最相关的 5-10 个文档片段
4. Agent 构建精简上下文（约 5000 tokens vs 原本可能的 100,000+ tokens）
5. 调用 LLM 生成代码，附带相关规范
6. 返回生成的代码给用户

场景 2: 会议纪要的智能问答

用户: "上个月的产品会议中，我们决定的发布日期是什么？"

Agent 处理流程:
1. 识别需要查询会议记录
2. 调用 qmd: qmd_query "product meeting release date last month"
3. qmd 在 meetings 集合中检索相关文档
4. 提取关键信息片段
5. 生成回答："根据 2026-01-15 的会议纪要，发布日期定在..."

场景 3: 网络搜索 + 本地知识融合

用户: "搜索最新的 Python 异步编程最佳实践，并结合我们的代码规范"

Agent 处理流程:
1. 并行执行：
   - 网络搜索：搜索 Python async best practices 2026
   - 本地检索：qmd_query "Python async coding standards"
2. 合并结果：
   - 网络结果提供最新趋势
   - 本地结果提供团队规范
3. 生成综合回答和代码示例

3.4 索引策略设计

推荐的知识库结构

~/agent-knowledge/
├── projects/                    # 项目文档
│   ├── project-a/
│   │   ├── README.md
│   │   ├── api-docs.md
│   │   └── architecture.md
│   └── project-b/
│       └── ...
├── meetings/                    # 会议纪要
│   ├── 2026-01-15-product.md
│   ├── 2026-01-20-tech.md
│   └── ...
├── standards/                   # 规范和最佳实践
│   ├── coding-standards.md
│   ├── api-design.md
│   └── security-guidelines.md
├── snippets/                    # 代码片段
│   ├── auth-patterns.md
│   ├── database-queries.md
│   └── ...
└── research/                    # 研究报告
    └── ...

qmd 集合配置建议

# 项目文档
qmd collection add ~/agent-knowledge/projects --name projects
qmd context add qmd://projects "项目文档和技术规范"

# 会议纪要
qmd collection add ~/agent-knowledge/meetings --name meetings
qmd context add qmd://meetings "团队会议纪要和决策记录"

# 代码规范
qmd collection add ~/agent-knowledge/standards --name standards
qmd context add qmd://standards "编码规范和最佳实践"

# 代码片段
qmd collection add ~/agent-knowledge/snippets --name snippets
qmd context add qmd://snippets "常用代码片段和模式"

# 生成向量嵌入
qmd embed

3.5 方案对比与选择建议

渐进式集成路径

建议采用渐进式集成策略：

Phase 1: 快速验证（1-2 天）

• 使用方案 A（CLI 调用）
• 验证 qmd 是否能有效减少 token 消耗
• 测试核心用例的搜索质量

Phase 2: 优化迭代（1 周）

• 根据反馈调整索引策略
• 优化查询提示词
• 建立评估基准

Phase 3: 生产部署（1-2 周）

• 迁移到方案 B（MCP 集成）
• 添加监控和日志
• 建立自动化维护流程（定期 re-index）

参考资料

• QMD GitHub - Using with AI Agents - Agent 集成指南
• Model Context Protocol - MCP 官方文档
• GitHub MCP Server - MCP 服务器示例