内容
<div align="center">
<br/>
<h1>🛍️ 商贸操作系统 AI</h1>
<p><strong>自主多智能体电子商务运营系统</strong></p>
<br/>
<p>
<img src="https://img.shields.io/badge/Python-3.13-%233776AB?logo=python&logoColor=white" alt="Python 3.13"/>
<img src="https://img.shields.io/badge/LangGraph-0.4-%2300B4D8?logo=langchain&logoColor=white" alt="LangGraph"/>
<img src="https://img.shields.io/badge/CrewAI-0.105-%23FF6B35" alt="CrewAI"/>
<img src="https://img.shields.io/badge/LangChain-0.3-%231F2937" alt="LangChain"/>
<img src="https://img.shields.io/badge/FastAPI-0.115-%23009688?logo=fastapi&logoColor=white" alt="FastAPI"/>
<img src="https://img.shields.io/badge/Next.js-14.2-%23000000?logo=next.js&logoColor=white" alt="Next.js"/>
<img src="https://img.shields.io/badge/Streamlit-1.40-%23FF4B4B?logo=streamlit&logoColor=white" alt="Streamlit"/>
<br/>
<img src="https://img.shields.io/badge/coverage-80%25-%23a0c334" alt="覆盖率 80%"/>
<img src="https://img.shields.io/badge/code%20style-ruff-%23D32F2F" alt="Ruff"/>
<img src="https://img.shields.io/badge/license-MIT-%23blue" alt="MIT 许可证"/>
</p>
<br/>
</div>
<!-- Hero screenshot -->
<p align="center">
<img src="docs/images/01-storefront.png" alt="商贸操作系统 AI 店面" width="90%"/>
</p>
---
## 📋 概述
商贸操作系统 AI 是一个**自主、事件驱动的电子商务平台**，其中**五个专业 AI 智能体**协同工作以运行完整的店面。一个**LangGraph 监督器**将客户意图路由到正确的智能体，一个**CrewAI 顺序团队**处理欺诈分析，而**EventBus**实现智能体之间的工作流——所有这些都无需人工干预。
> *"不仅仅是一个店面——一个由 5 个专业智能体协同工作的 AI 驱动体验。"*
### 有什么不同
| 典型的电子商务演示 | 商贸操作系统 AI |
|------------------------|-------------------|
| CRUD 应用与聊天机器人 | **5 个智能体**与 LangGraph 协调 |
| 硬编码的业务逻辑 | **动态路由**通过 AgentRegistry |
| 单个 LLM 调用所有功能 | **CrewAI 多智能体管道**用于欺诈 |
| 每次对话无记忆 | **MemorySaver**每会话上下文 |
| 静态定价 | **动态定价**通过定价智能体 |
| 人工审核欺诈 | **AI 信号分析师 → 裁决者**辩论 |
---
## 👀 看它在行动 — 完整的 AI 购物之旅
观看所有 5 个智能体如何通过真实的客户对话协同工作：
### 🏠 1. 店面
一个功能齐全的电子商务商店，配备真实的产品摄影、类别筛选和 AI 驱动的推荐。
<p align="center">
<img src="docs/images/01-storefront-full.png" alt="店面" width="90%"/>
</p>
---
### 🤖 2. AI 助手 — 奇迹发生的地方
**AI 助手**是系统的核心——一个 LangGraph 监督器自动将每个查询路由到正确的专业智能体。
#### 🎧 客户支持 — 商店信息和订单
客户询问商店、如何下单和配送跟踪。**支持智能体**使用 **RAG（ChromaDB）** 提供准确的、基于政策的回应。
<p align="center">
<img src="docs/images/02-agent-support.png" alt="支持智能体" width="80%"/>
</p>
#### 📦 库存智能体 — 检查产品可用性
客户询问特定库存中的产品。**库存智能体**查询实时数据库并回应实时库存水平。
<p align="center">
<img src="docs/images/03-agent-inventory.png" alt="库存智能体" width="80%"/>
</p>
#### 🏷️ 定价智能体 — 查找优惠和促销
客户寻找正在进行的促销活动。**定价智能体**分析当前销售和滞销库存，以建议最好的优惠。
<p align="center">
<img src="docs/images/04-agent-pricing.png" alt="定价智能体" width="80%"/>
</p>
#### 📋 订单管理 — 跟踪真实订单
通过店面下单，然后**订单智能体**被要求检查其状态——显示真实的订单生命周期管理与跟踪。
<p align="center">
<img src="docs/images/05-agent-order.png" alt="订单智能体" width="80%"/>
</p>
#### 🛡️ 欺诈智能体 — CrewAI 多智能体分析 ⭐
相同的订单被发送到**欺诈智能体**进行安全分析。**CrewAI 顺序团队**（信号分析师 → 风险裁决者）辩论信号并产生风险决策。
<p align="center">
<img src="docs/images/06-agent-fraud.png" alt="欺诈智能体 - CrewAI 分析" width="80%"/>
</p>
---
### ⚙️ 3. 管理仪表盘 — 实时操作
操作仪表盘显示实时欺诈警报、库存水平和所有智能体活动的完整审计跟踪。
<p align="center">
<img src="docs/images/08-admin-dashboard.png" alt="管理仪表盘" width="90%"/>
</p>
---
### 📖 4. API 文档
每个智能体的功能也通过 REST API 暴露，并具有完整的 Swagger 文档。
<p align="center">
<img src="docs/images/09-api-docs.png" alt="API 文档" width="90%"/>
</p>
---
## 🧠 系统架构
```
┌─────────────────────────────────────────┐
│ NEXT.JS 店面 │
│ 产品 · 购物车 · AI 聊天 · 管理 │
└───────────────┬─────────────────────────┘
│ HTTP / SSE
┌───────────────▼─────────────────────────┐
│ FASTAPI REST 层 │
│ (9 MCP 工具 · 流式聊天) │
└───────────────┬─────────────────────────┘
│
┌────────────────────▼────────────────────────┐
│ LANGGRAPH 监督器 │
│ 智能体注册路由 · MemorySaver │
│ （关键词预检查 → LLM 备用） │
└──────┬──────┬──────┬──────┬──────┬──────────┘
│ │ │ │ │
┌──────▼┐ ┌──▼──┐ ┌─▼──┐ ┌─▼───┐ ┌▼──────────┐
│支持│ │库存│ │欺诈│ │订单│ │定价 │
│（RAG）│ │（LLM）│ │（Crw│ │（LLM）│ │（LLM） │
└──────┘ └─────┘ └────┘ └─────┘ └───────────┘
│ │ │ │ │
┌──────▼──────▼──────▼──────▼──────▼──────────┐
│ MCP 工具层（SQLAlchemy） │
│ 产品 · 订单 · 客户 · 日志 │
└───────────────────┬──────────────────────────┘
│
┌───────────────────▼──────────────────────────┐
│ 事件总线 + 工作流 │
│ order.created → 欺诈检查 → 扣除库存 │
│ → 低库存警报 → 状态更新 → 日志 │
└──────────────────────────────────────────────┘
```
---
## 🤖 五个智能体
| 智能体 | 框架 | 核心能力 | 示例查询 |
|-------|-----------|----------------|---------------|
| **🎧 支持** | LangChain + ChromaDB RAG | 基于实际文档的政策问答 | *"我可以退换损坏的商品吗？"* |
| **📦 库存** | LangChain + Groq LLM | 实时库存查询，低库存警报 | *"你们有白色 T 恤吗？"* |
| **🛡️ 欺诈** | CrewAI（2 角色顺序） | 信号分析师 → 风险裁决者管道 | *"检查订单 O2004 的欺诈情况"* |
| **📋 订单** | LangChain + Groq LLM | 完整生命周期：跟踪、取消、发货 | *"我的订单 O2001 在哪里？"* |
| **🏷️ 定价** | LangChain + Groq LLM | 销售建议，滞销分析 | *"有哪些商品在打折？"* |
### 智能体协作实战
当客户下订单时，系统会协调多智能体工作流：
```
订单已放置
│
├─▶ 欺诈智能体（CrewAI）分析 4 个信号
│ ├─ 速度检查（15 分钟窗口）
│ ├─ 国家不匹配检测
│ ├─ 新账户 + 高价值评分
│ └─ 处置邮件检测
│
├─▶ 库存智能体扣除库存
│ └─ 如果达到阈值，则触发低库存警报
│
├─▶ 订单状态 → 已确认
│
└─▶ 所有步骤记录到 AgentLog
└─ 管理仪表盘实时更新
```
---
## 🧩 技术深度解析
### LangGraph — 协调脊柱
整个智能体路由系统使用 **LangGraph 的 StateGraph** —— 一个有状态的、基于图的协调框架。每个用户查询都流经一个有向图：
```python
graph = StateGraph(GraphState)
graph.add_node("supervisor", supervisor_node) # 路由决策
graph.add_node("fraud", fraud_node) # 智能体执行
graph.add_conditional_edges("supervisor", route_decision, route_map)
compiled = graph.compile(checkpointer=MemorySaver())
```
**MemorySaver** 启用每会话的对话历史记录——具有上下文感知能力的多次交互，无需外部数据库。
### CrewAI — 多智能体欺诈管道
欺诈检测智能体运行一个 **CrewAI 顺序团队** —— 两个 AI 智能体辩论每个标记的订单：
```python
analyst = Agent(role="Fraud Signal Analyst", ...)
adjudicator = Agent(role="Risk Adjudicator", ...)
crew = Crew(agents=[analyst, adjudicator], tasks=[analyze, adjudicate])
result = crew.kickoff() # 两个智能体 → 一个决定
```
| 角色 | 责任 |
|------|---------------|
| **信号分析师** | 客观解读原始欺诈信号 |
| **风险裁决者** | 做出最终决定：`APPROVE` / `HOLD` / `REJECT` |
这模仿了现实世界的欺诈操作——分析师准备证据，高级审查员做出决定。
### RAG（ChromaDB）—— 基于事实的支持
支持智能体使用 **检索增强生成** 与 ChromaDB。客户查询被嵌入句子转换器，匹配政策文档，LLM 响应基于实际政策文本：
```python
vectorstore = load_vectorstore() # ChromaDB 与政策嵌入
docs = vectorstore.similarity_search(query, k=3) # 顶部 3 个政策块
# LLM 生成答案，基于检索的政策文本
```
### MCP 工具层 — 解耦的数据访问
九个数据库支持的工具位于统一的 `call_tool()` 接口后面。智能体直接不接触数据库：
```python
def call_tool(tool_name: str, **kwargs):
return get_tool(tool_name)(**kwargs)
# 任何智能体通过相同的接口查询任何数据：
products = call_tool("search_products", query="t-shirt")
signals = call_tool("get_fraud_signals", order_id="O2004")
```
**注册工具：** `get_all_products`, `search_products`, `get_low_stock_products`, `get_product_by_id`, `get_order_by_id`, `get_orders_by_email`, `get_fraud_signals`, `get_all_flagged_orders`, `append_order`
### 事件总线 — 智能体间协作
进程内发布/订阅系统启用**解耦、事件驱动的工作流**:
```python
event_bus.emit("order.created", {"order_id": "O2042"})
# 自动触发（无需人工干预）：
# 1. 欺诈智能体运行 CrewAI 分析
# 2. 库存智能体扣除库存
# 3. 如果达到阈值，则触发库存警报
# 4. 订单状态更新为已确认
```
---
## 🚀 快速开始
### 先决条件
- Python 3.13+ · Node.js 18+ · Groq API 密钥（[免费](https://console.groq.com）)
### Docker（一键）
```bash
docker compose -f infrastructure/docker-compose.yml up
```
访问 **http://localhost:3000**
### 手动设置
**终端 1 — 后端：**
```bash
git clone https://github.com/hamidnaseem3549/commerceos-ai.git
cd commerceos-ai
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # 添加您的 GROQ_API_KEY
python scripts/seed.py
python rag/vectorstore_setup.py
uvicorn backend.main:app --reload --port 8000
```
**终端 2 — 前端：**
```bash
cd commerceos-ai/frontend
npm install && npm run dev
```
打开 **http://localhost:3000** 🎉
---
## 🧪 测试与质量
```bash
pytest tests/ -v --cov=commerceos # 33 个测试，覆盖率 80%+
ruff check . # lint 检查 — clean
```
| 指标 | 状态 |
|--------|--------|
| 测试 | ✅ **33 通过** |
| linting | ✅ **Ruff clean** (108 个问题已解决) |
| 覆盖率 | ✅ **80%+** |
| 测试套件 | 智能体 · 工具 · 工作流 · 监督器 |
| CI | ✅ GitHub Actions（lint + test + coverage） |
---
## 🏗️ 项目结构
```
commerceos-ai/
│
├── commerceos/ # 🧠 核心 AI 引擎
│ ├── agents/ # 5 个可插拔智能体（BaseAgent）
│ ├── orchestration/ # LangGraph 监督器 + 事件总线
│ ├── mcp/ # 9 个统一数据访问工具
│ ├── database/ # SQLAlchemy ORM + SQLite 种子
│ └── observability/ # JSON 日志 + 活动跟踪
│
├── frontend/ # 🎨 Next.js 14 店面
├── backend/ # 🌐 FastAPI REST API
├── pages/ # 🖥️ Streamlit 视图（legacy）
├── ui/ # 共享组件和资产
├── infrastructure/ # 🐳 Docker + docker-compose
├── tests/ # 🧪 33 个集成测试
├── rag/ # 📚 ChromaDB 向量存储
└── data/ # 📦 CSV 种子数据
```
---
## 🛠️ 技术栈
| 类别 | 技术 |
|----------|-----------|
| **AI 协调** | LangGraph（StateGraph + MemorySaver） |
| **智能体框架** | LangChain，CrewAI（顺序团队） |
| **向量存储（RAG）** | ChromaDB + 句子转换器 |
| **LLM 提供商** | Groq（llama-3.3-70b） |
| **后端** | FastAPI，SQLAlchemy 2.0，Pydantic |
| **前端** | Next.js 14，React 18，Tailwind CSS |
| **数据库** | SQLite（开发）/ PostgreSQL-ready |
| **基础设施** | Docker，docker-compose |
| **CI/CD** | GitHub Actions（lint + test + coverage） |
| **质量** | Ruff（linting），pytest-cov（coverage） |
---
## 👨💻 作者
**Hamid Naseem** — 渴望成为 AI 工程师
[GitHub](https://github.com/hamidnaseem3549) · [LinkedIn](https://www.linkedin.com/in/hamid-naseem-354h)
---
## 📄 许可证
MIT
---
<div align="center">
<p>
<strong>Built with LangGraph · CrewAI · LangChain · FastAPI · Next.js</strong>
</p>
<p>
<a href="#-overview">概述</a> ·
<a href="#-see-it-in-action">演示</a> ·
<a href="#-system-architecture">架构</a> ·
<a href="#-the-five-agents">智能体</a> ·
<a href="#-technology-deep-dive">技术深度解析</a> ·
<a href="#-quick-start">快速开始</a>
</p>
<br/>
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器