# SmartCommerce Agent

> 电商售后与智能物流多智能体系统

SmartCommerce Agent 是一个基于 LangGraph 的开源电商客服平台。系统将用户请求路由到 FAQ、订单、智能物流、退款、支付、人工转接等专家 Agent，并通过 RAG、MCP 工具、会话记忆和服务端安全校验完成可追踪的业务闭环。

项目支持两种运行模式：不配置模型密钥时使用确定性离线流程，便于本地开发和持续集成；配置 OpenAI 兼容模型后启用在线意图路由与 Function Calling。

## 核心能力

- **七类专家 Agent**：FAQ、订单、智能物流、退款、支付、人工转接和通用接待。
- **智能物流异常处理**：识别快递丢失、物流停滞、包裹破损和错误签收。
- **安全工具链**：物流异常必须按 `get_order → create_logistics_ticket` 顺序执行。
- **RAG 引用**：从企业政策知识库检索依据，并在答案中展示来源。
- **MCP 工具服务**：订单、支付、退款、物流工单和人工工单能力由 FastMCP 独立提供。
- **多层记忆**：LangGraph Checkpointer 保存会话状态，SQLite 保存跨会话业务记忆。
- **故障转人工**：业务接口失败后自动创建高优先级人工工单并保留工具轨迹。
- **可量化评测**：覆盖意图、工具顺序、RAG 来源、多轮指代、安全规则和响应延迟。

## 系统架构

```text
Streamlit UI / FastAPI
          │
          ▼
   LangGraph Supervisor
          │
  ┌───────┼──────────┬────────┬────────┬──────────┐
  ▼       ▼          ▼        ▼        ▼          ▼
 FAQ    Order    Logistics  Refund   Payment   Escalation
 Agent   Agent      Agent     Agent    Agent       Agent
  │       │          │        │        │          │
 RAG      └──────────┴────────┴────────┴──────────┘
知识库                       MCP Tools
                              │
                 SQLite 订单 / 退款 / 工单 / 记忆
```

物流异常采用受控写入流程：

```text
识别物流异常
  → 查询当前用户订单
  → 校验订单归属
  → 分类 lost / stalled / damaged / wrong_delivery
  → 创建物流异常工单
  → 返回工单号和物流政策来源
```

详细设计见 [架构文档](docs/architecture.md)。

## 技术栈

- Python 3.10～3.12
- FastAPI + Streamlit
- LangChain + LangGraph
- FastMCP + LangChain MCP Adapters
- SQLite + LangGraph SQLite Checkpointer
- Pydantic + pytest + Ruff

## 快速开始

### Windows PowerShell

```powershell
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1
```

安装完成后，在两个终端中分别启动：

```powershell
.\scripts\start-api.ps1
```

```powershell
.\scripts\start-ui.ps1
```

### macOS / Linux

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
cp .env.example .env
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```

在另一个终端中运行：

```bash
source .venv/bin/activate
streamlit run frontend.py --server.port 8501
```

服务地址：

- Web UI：<http://127.0.0.1:8501>
- OpenAPI：<http://127.0.0.1:8000/docs>
- 健康检查：<http://127.0.0.1:8000/health>

## 模型配置

复制 `.env.example` 为 `.env`。不设置 `LLM_API_KEY` 时系统运行在 `offline_rule` 模式，MCP、RAG、Memory 和评测仍然可用。

```dotenv
LLM_API_KEY=
LLM_MODEL=gpt-4o-mini
LLM_BASE_URL=
```

使用其他 OpenAI 兼容服务时，填写对应的模型名与 Base URL。不要提交真实 `.env` 或 API 密钥。

## 示例请求

| 用户 | 问题 | 预期行为 |
|---|---|---|
| `u001` | `查询 ORD-1001 的物流` | 调用 `get_order` |
| `u001` | `ORD-1002 三天没有物流更新了` | 查询订单后创建物流工单 |
| `u001` | `ORD-1001 显示签收但我没收到` | 创建错误签收工单并引用政策 |
| `u002` | `ORD-1002 的包裹丢了` | 拒绝越权订单，不创建工单 |
| `u001` | `七天无理由退货有什么条件？` | RAG 回答并引用退款政策 |
| `u001` | `这个订单能退款吗？` | 使用多轮记忆解析订单号 |

内置数据仅用于本地开发与自动测试。

## 测试与评测

```powershell
.\.venv\Scripts\python.exe -m pytest --cov=app --cov-report=term-missing
.\.venv\Scripts\python.exe -m evaluation.run_eval
```

配置模型后，可运行在线评测：

```powershell
.\.venv\Scripts\python.exe -m evaluation.run_eval --online
```

当前离线基准：

| 指标 | 结果 |
|---|---:|
| 自动测试 | 64/64 |
| 代码覆盖率 | 86% |
| 单轮评测集 | 70 条 |
| 智能物流专项 | 100%（10/10） |
| 物流工具顺序 | 100%（10/10） |
| 多轮场景 | 100%（6/6） |
| 安全检查 | 100%（9/9） |
| P95 响应时间 | 28.76 ms |

这些数字来自确定性离线回归基准，用于验证工程流程，不代表在线大模型的泛化准确率。评测定义和限制见 [评测文档](docs/evaluation.md)，最近一次原始结果见 [latest.json](evaluation/results/latest.json)。

## 安全设计

- `user_id` 由服务端上下文强制注入，忽略模型或用户伪造的身份参数。
- 不存在和越权订单统一返回 `ORDER_NOT_FOUND`，避免泄露其他用户数据。
- 写入型工具在数据库业务层再次验证订单归属与参数白名单。
- 工具异常与业务拒绝分开记录，接口异常才触发自动转人工。
- `.env`、本地数据库、虚拟环境和缓存文件均被 Git 忽略。

## 项目结构

```text
app/
├── agent/graph.py          # LangGraph 编排与安全工具流
├── mcp_server/server.py    # FastMCP 工具服务
├── skills/loader.py        # Skill 动态加载
├── database.py             # 数据模型与业务安全规则
├── context.py              # Context Engineering
├── rag.py                  # 知识库检索与引用
├── router.py               # 意图路由
├── runtime.py              # MCP、模型与 Checkpointer 生命周期
└── main.py                 # FastAPI 应用
skills/                     # 七类 Agent 的 YAML 与 Prompt
knowledge/                  # 企业政策知识库
evaluation/                 # 70 条单轮、6 组多轮与安全评测
tests/                      # 单元、集成与端到端测试
docs/                       # 架构与评测文档
frontend.py                 # Streamlit UI
```

## 参与贡献

提交代码前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。安全问题请按照 [SECURITY.md](SECURITY.md) 私下报告。

## 致谢

项目实现参考了 LangGraph、LangChain MCP Adapters 以及以下公开项目的工程思路：

- [Pragatheswar-72/support-agent](https://github.com/Pragatheswar-72/support-agent)
- [ntg2208/production-ai-customer-support-langchain](https://github.com/ntg2208/production-ai-customer-support-langchain)

## License

[MIT](LICENSE)