内容
# AI Ops 指挥中心 — 多智能体电商支持系统
欢迎来到 **AI Ops 指挥中心**，一个客户支持票处理系统。其核心设计是一个协作的多智能体中继，由 LangGraph 协调，与安全的 MCP（模型上下文协议）工具服务器交互，并在操作仪表盘上进行实时审计。
---
## 工作流程概述
当收到客户支持票时：
1. **分诊智能体** 按类别和优先级对票进行分类。
2. **研究智能体** 调用 MCP 工具来收集客户事实、订单历史和政策搜索结果。
3. **解决方案智能体** 起草量身定制的解决方案或在符合条件时请求退款。
4. **质量保证智能体** 审查草稿，批准或将其路由回修订（在 2 次尝试后升级到人工）。
5. **人工介入** 在需要授权的操作中暂停执行（例如退款），在人工批准后继续。
6. **指挥中心仪表盘** 实时显示跟踪、工具调用和批准队列。
---
## 系统架构
组件之间的交互流程：
```mermaid
graph TD
User([客户票]) -->|提交票| API[FastAPI 后端]
API -->|持久化状态| DB[(PostgreSQL + pgvector)]
%% 智能体编排
subgraph AgentLoop ["智能体循环（LangGraph）"]
State([票状态]) --> Triage[分诊智能体]
Triage --> Research[研究智能体]
Research --> Resolution[解决方案智能体]
Resolution --> QA{质量保证智能体}
QA -- 已批准 --> EndState([已解决状态])
QA -->|"拒绝 / 重试 < 2"| Resolution
QA -->|"拒绝 / 重试 >= 2"| Escalate[升级到人工]
end
API -->|调用图| State
%% MCP 服务器
subgraph MCPServer ["MCP 服务器（工具）"]
KB[搜索知识库]
Profile[获取客户资料]
Orders[获取订单详情]
Refund[请求退款]
end
Research & Resolution -->|查询 / 操作| MCPServer
MCPServer -->|HTTP 内部 API| API
%% 仪表盘
subgraph StreamlitDashboard ["Streamlit 仪表盘"]
Feed[票源]
Detail[实时跟踪和工具调用]
Queue[批准队列]
end
StreamlitDashboard -->|查询跟踪和批准| API
StreamlitDashboard -->|POST 批准 / 拒绝| API
API -.->|中断状态检查点| DB
```
---
## 仓库结构
代码库组织成独立、解耦的组件：
- **[后端/](file:///Users/harshitchoudhary/Tech2go/Agentic/multi-agent-ecommerce-support/multiagent-ecommerce-support-system/backend/)**：核心 FastAPI 网络服务和数据库模式定义，包括 Alembic 迁移和数据库种子脚本。
- **[mcp_server/](file:///Users/harshitchoudhary/Tech2go/Agentic/multi-agent-ecommerce-support/multiagent-ecommerce-support-system/mcp_server/)**：FastMCP 服务器，通过干净的工具暴露数据库交互，供 LLM 智能体使用。
- **[agents/](file:///Users/harshitchoudhary/Tech2go/Agentic/multi-agent-ecommerce-support/multiagent-ecommerce-support-system/agents/)**：LangGraph 定义，协调智能体节点任务（分诊、研究、解决方案、质量保证）。
- **dashboard/**：*（计划中 - 第 6 步）* Streamlit 用户界面，显示实时票源并处理人工介入批准。
---
## 实现进度检查清单
该项目目前处于 **中途阶段（第 3 步完成）**。
- [x] **步骤 1：设置数据库**
- PostgreSQL 模式，包含 `customers`、`orders`、`tickets`、`agent_traces`、`tool_calls`、`refunds` 和 `kb_docs` 表。
- Alembic 迁移管道。
- 虚假数据生成器（Faker）和知识库嵌入加载器（pgvector + Ollama）。
- [x] **步骤 2：构建 MCP 服务器（“手”）**
- FastMCP 框架设置。
- 用于客户资料、订单详情和票历史的数据库查找工具。
- [ ] *待处理*：知识库语义搜索和退款/更新/升级工具。
- [x] **步骤 3：构建一个智能体，端到端**
- LangGraph 环境设置。
- 使用本地 Ollama 模型 (`llama3.1:8b`) 的分诊智能体节点，用于分类和优先处理票。
- 自动数据库分类修补和执行跟踪到 `agent_traces`。
- 验证脚本运行模拟票端到端。
- [ ] **步骤 4：添加其余智能体链**
- 集成研究智能体、解决方案智能体和质量保证智能体节点。
- 强制质量保证拒绝重试阈值（在尝试 2 次后升级到人工）。
- [ ] **步骤 5：添加人工批准步骤**
- 实现 LangGraph 中断检查点。
- 暴露用于人工批准/拒绝的 API 端点。
- [ ] **步骤 6：构建仪表盘**
- Streamlit 应用程序，显示实时票源、详细跟踪和批准控制。
- [ ] **步骤 7：为您的作品集进行润色**
- 系统性能和安全调整。
---
## 入门指南
您可以使用 Docker Compose 一键运行整个堆栈（数据库、后端 API 和 MCP 服务器），也可以单独运行组件进行开发。
### 方法 1：使用 Docker Compose 运行（推荐）
1. 确保 **Ollama** 在您的主机上运行，并具有所需的模型：
```bash
ollama pull llama3.1:8b
ollama pull nomic-embed-text
```
2. 从根目录启动整个堆栈：
```bash
docker compose up --build
```
*这会自动构建后端和 MCP 服务器容器，启动带有 `pgvector` 的 PostgreSQL 容器，执行数据库迁移 (`alembic upgrade head`)，并暴露服务：*
- **后端 API**：`http://localhost:8000`
- **MCP 服务器（SSE）**：`http://localhost:8001`
3. 种子数据库（在主机上运行；需要安装后端虚拟环境依赖）：
```bash
cd backend
source venv/bin/activate
python -m seed.generate_data
python -m seed.generate_embeddings
```
---
### 方法 2：手动本地设置（单个组件）
如果您正在修改代码并希望进行本地开发的热重载，请参考各个 README 指南：
1. 设置数据库和 REST API：**[后端 README](file:///Users/harshitchoudhary/Tech2go/Agentic/multi-agent-ecommerce-support/multiagent-ecommerce-support-system/backend/README.md)**
2. 设置和运行 MCP 工具层：**[MCP 服务器 README](file:///Users/harshitchoudhary/Tech2go/Agentic/multi-agent-ecommerce-support/multiagent-ecommerce-support-system/mcp_server/README.md)**
3. 设置和运行 LangGraph 工作区：**[智能体 README](file:///Users/harshitchoudhary/Tech2go/Agentic/multi-agent-ecommerce-support/multiagent-ecommerce-support-system/agents/README.md)**
