内容
# AI 支持 Copilot — 大型语言模型 + MCP + 多模态 + 可观察性 + 多智能体编排
一个完整的 AI 驱动的支持票务处理系统，演示了：
- **模型上下文协议（MCP）** 用于工具集成
- **多智能体编排** （分诊 → 研究 → 行动 → 监督）
- **多模态大型语言模型** 支持（文本 + 视觉）
- **可观察性** 具有结构化跟踪
- **无框架** - 为教育清晰度而手工构建的架构
该项目设计用于工作坊和学习，包含合成数据和清晰的实现模式。
## 架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 支持 Copilot 主机 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 分诊 │──▶│ 研究 │──▶│ 行动 │──▶│ 监督 │ │
│ │ 智能体 │ │ 智能体 │ │ 智能体 │ │ 智能体 │ │
│ └──────────┘ └────┬─────┘ └──────────┘ └──────────┘ │
│ │ │
│ │ MCP 客户端 │
│ ▼ │
│ ┌────────────────┐ │
│ │ MCP 工具 API │ │
│ └────────┬───────┘ │
└───────────────────────┼─────────────────────────────────────────┘
│
┌───────────────────────┼─────────────────────────────────────────┐
│ │ 支持 MCP 服务器 │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ support_docs.search │ │
│ │ incidents.search │ │
│ │ status.check │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ 合成数据 │ │
│ │ - 运行手册 │ │
│ │ - 事件 │ │
│ │ - 服务状态 │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 项目结构
```
.
├── README.md # 本文件
├── prd.md # 产品需求文档
├── requirements.txt # Python 依赖项
├── data/ # 合成数据
│ ├── docs/runbooks/ # 支持文档
│ ├── incidents/ # 事件数据库
│ ├── status/ # 服务状态
│ └── tickets/ # 示例票据
├── support_mcp_server/ # MCP 服务器实现
│ ├── config.py
│ ├── tools_support_docs.py
│ ├── tools_incidents.py
│ ├── tools_status.py
│ └── server.py
└── support_copilot_host/ # 主机应用程序
├── config.py
├── models.py # 数据模型
├── llm_client.py # 大型语言模型包装器
├── mcp_client.py # MCP 客户端
├── agents.py # 四个智能体
├── orchestrator.py # 主流程
├── observability.py # 跟踪
├── cli.py # 命令行界面
└── examples.py # 工作坊演示
```
## 设置
### 1. 先决条件
- Python 3.11+
- OpenAI API 密钥（或兼容的大型语言模型提供商）
### 2. 安装依赖项
```bash
python -m venv .venv
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
pip install -r requirements.txt
```
### 3. 设置环境变量
```bash
export OPENAI_API_KEY="your-api-key-here"
```
或创建 `.env` 文件（您可以使用现有的 `openai_key.env` 作为参考）：
```bash
OPENAI_API_KEY=your-api-key-here
LLM_MODEL_NAME=gpt-4o-mini # 可选，默认为 gpt-4o-mini
```
## 交互式 Jupyter 笔记本
**非常适合工作坊和交互式学习！**
我们提供了 **3 个 Jupyter 笔记本** 用于动手探索：
### 1. 快速入门演示（`demo_quickstart.ipynb`）
**⏱️ 5 分钟** - 完美适用于工作坊介绍
- 处理 2 个示例票据端到端
- 查看完整输出（客户回复 + 内部备注）
- 比较不同票据类型
- **最佳用途：** 首次演示，测试设置
### 2. MCP 工具深入探讨（`demo_mcp_tools.ipynb`）
**⏱️ 15 分钟** - 了解工具层
- 连接到 MCP 服务器
- 单独测试每个工具（`support_docs.search`、`incidents.search`、`status.check`）
- 探索搜索算法和评分
- 性能分析
- 现实世界的票据分诊场景
- **最佳用途：** 教授 MCP 概念，工具定制
### 3. 完整流程探索（`demo_complete_flow.ipynb`）
**⏱️ 20-30 分钟** - 全系统深入探讨
- 完整的票据处理流程
- 单独测试每个智能体（分诊、研究、行动、监督）
- 详细跟踪探索
- 处理所有 4 个示例票据
- 比较结果和行为
- **最佳用途：** 了解多智能体编排，调试
### 运行笔记本
**先决条件：**
```bash
# 安装 Jupyter
pip install jupyter
# 启动 MCP 服务器（在单独的终端中）
python -m support_mcp_server.server
# 启动 Jupyter
jupyter notebook
```
然后打开任何演示笔记本并顺序运行单元格！
**工作坊提示：** 从 `demo_quickstart.ipynb` 开始给观众留下深刻印象，然后根据兴趣深入 `demo_mcp_tools.ipynb` 或 `demo_complete_flow.ipynb`。
---
## 用法
### 快速入门：运行示例票据
这需要 **两个终端**:
**终端 1 - 启动 MCP 服务器：**
```bash
python -m support_mcp_server.server
```
**终端 2 - 运行示例票据：**
```bash
python -m support_copilot_host.cli run-sample --id TICKET-001
```
### 可用命令
#### 列出可用示例票据
```bash
python -m support_copilot_host.cli list-samples
```
#### 运行特定示例票据
```bash
python -m support_copilot_host.cli run-sample --id TICKET-001
python -m support_copilot_host.cli run-sample --id TICKET-002
python -m support_copilot_host.cli run-sample --id TICKET-003
python -m support_copilot_host.cli run-sample --id TICKET-004
```
#### 运行自定义票据
```bash
python -m support_copilot_host.cli run-ticket \
--description "用户无法导出仪表板到 CSV" \
--log "2025-11-01T10:00:00Z ERR_EXPORT_TIMEOUT service=export_service"
```
#### 运行工作坊演示
```bash
python -m support_copilot_host.examples
```
## 示例票据
该项目包含四个合成票据：
1. **TICKET-001**: 导出到 CSV 超时（已知问题 + 服务降级）
2. **TICKET-002**: SSO 身份验证失败（正在调查事件）
3. **TICKET-003**: 工作区权限问题（配置错误）
4. **TICKET-004**: API 速率限制（已解决事件）
## 多智能体流程
每个票据都经过四个智能体：
1. **分诊智能体**: 分析票据，分类问题类型，决定使用哪些工具
2. **研究智能体**: 调用 MCP 工具（文档，事件，状态）以收集上下文
3. **行动智能体**: 起草客户面对面的回复和内部备注
4. **监督智能体**: 审查输出的质量，安全性和幻觉
## MCP 工具
MCP 服务器公开三个工具：
- `support_docs.search`: 搜索内部运行手册
- `incidents.search`: 查找相关事件
- `status.check`: 检查服务健康状态
## 可观察性
每个票据执行都会生成一个跟踪记录：
- 唯一的跟踪 ID
- 每个事件的时间戳
- 智能体步骤（大型语言模型调用，工具调用，输出）
- 完整的有效载荷数据（如果较大，则截断）
跟踪记录：
- 在终端中显示为漂亮的表格
- 保存到 `traces/trace.jsonl` 作为 JSONL
- 用于调试和工作坊演示
## 自定义
### 添加新的运行手册
在 `data/docs/runbooks/` 中创建 markdown 文件：
```markdown
# 我的新运行手册
问题描述...
解决方法：
1. 步骤一
2. 步骤二
```
### 添加新的事件
编辑 `data/incidents/incidents.json`:
```json
{
"incident_id": "INC-1005",
"title": "新事件",
"status": "正在调查",
"summary": "...",
"tags": ["tag1", "tag2"]
}
```
### 更改大型语言模型
设置环境变量：
```bash
export LLM_MODEL_NAME="gpt-4o"
```
## 工作坊用法
该项目设计用于一个 3 小时的 workshop：
1. **阶段 1**: 解释架构和 MCP 概念
2. **阶段 2**: 演示 MCP 服务器和工具
3. **阶段 3**: 显示单个智能体基准（无工具）
4. **阶段 4**: 添加 MCP 工具集成
5. **阶段 5**: 重构为多智能体模式
6. **阶段 6**: 探索可观察性和跟踪记录
7. **阶段 7**: 讨论扩展（RAG，更多智能体等）
参见 `prd.md` 以获取详细的工作坊计划。
## 开发
### 运行测试
```bash
# 首先启动 MCP 服务器
python -m support_mcp_server.server
# 在另一个终端中，运行测试票据
python -m support_copilot_host.cli run-sample --id TICKET-001
```
### 查看跟踪记录
```bash
# 跟踪记录保存到 traces/trace.jsonl
cat traces/trace.jsonl | jq .
```
## 限制
这是一个 **工作坊/教育项目**，不是生产就绪的：
- 简单的关键词搜索（无嵌入/向量搜索）
- 无数据库持久性
- 无身份验证
- 同步智能体执行（无并行化）
- 有限的错误处理
## 未来扩展
参见 `prd.md` 第 13 节以获取想法：
- 文档/事件的向量搜索
- 并行研究智能体
- 反馈收集
- Web UI
- 高级评估指标
## 许可证
教育使用。有关完整详细信息，请参见 `prd.md`。
## 问题？
请参考 `prd.md` 以获取完整的实现细节和架构决策。
