# Smart Support

AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作的智能客服。

## 问题

现有客服工具（Zendesk、Intercom、Ada）擅长回答 FAQ，但自动化率卡在 20-30%。剩下 70% 的工单需要人工登录内部系统，手动查订单、取消订单、发优惠券。

Smart Support 是补全这个缺口的「行动层」。它不替代现有客服平台，而是让 AI 能直接调用内部系统完成操作。

## 工作原理

```
客户消息 → Chat UI → FastAPI WebSocket → LangGraph Supervisor → 专业 Agent → MCP Tools → 你的内部系统
                                                ↑                      ↑
                                          Agent 注册表            interrupt()
                                          (YAML 配置)           (人工确认)
                                                ↑
                                          PostgresSaver
                                         (会话状态持久化)
```

1. 客户在聊天界面发送消息
2. LangGraph Supervisor 分析意图，路由到对应的专业 Agent
3. Agent 通过 MCP 协议调用你的内部系统（查订单、取消订单、发折扣...）
4. 涉及写操作时，自动触发人工确认流程
5. 所有操作全程记录，支持回放和分析

## 核心特性

- **多 Agent 协作** - 不同操作由不同 Agent 处理，各自拥有独立的权限边界和工具集
- **即插即用** - 粘贴 OpenAPI 规范 URL，自动生成 MCP 工具和 Agent 配置
- **人工确认** - 所有写操作（取消、退款、修改）需要人工审批，读操作直接执行
- **会话上下文** - 支持多轮对话，Agent 能理解「取消那个订单」这样的指代
- **实时流式输出** - WebSocket 双向通信，逐 token 流式返回
- **对话回放** - 逐步查看 Agent 决策过程、工具调用和返回结果
- **数据分析** - 解决率、Agent 使用率、升级率、每次对话成本
- **YAML 驱动配置** - Agent 定义、人设、垂直模板全部通过 YAML 配置

## 技术栈

| 组件 | 技术选型 |
|------|---------|
| 后端 | Python 3.11+, FastAPI |
| Agent 编排 | LangGraph v1.1, langgraph-supervisor |
| 工具集成 | langchain-mcp-adapters, @tool |
| 状态持久化 | PostgreSQL + langgraph-checkpoint-postgres |
| LLM | Claude Sonnet 4.6（可切换 OpenAI、Google 等） |
| 前端 | React |
| 部署 | Docker Compose |

## 项目结构

```
smart-support/
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI + WebSocket 入口
│   │   ├── graph.py         # LangGraph Supervisor 配置
│   │   ├── agents/          # Agent 定义 + 工具
│   │   ├── registry.py      # YAML Agent 注册表加载器
│   │   ├── openapi/         # OpenAPI 解析 + MCP 服务器生成
│   │   ├── replay/          # 对话回放 API
│   │   ├── analytics/       # 数据分析查询 + API
│   │   └── callbacks.py     # Token 用量统计
│   ├── agents.yaml          # Agent 注册表配置
│   ├── templates/           # 垂直行业模板
│   └── tests/
├── frontend/                # React 聊天 UI + 回放 + 仪表盘
├── docker-compose.yml       # PostgreSQL + 应用
└── pyproject.toml
```

## 快速开始

```bash
# 启动 PostgreSQL 和应用
docker compose up

# 访问聊天界面
open http://localhost:8000
```

## Agent 配置示例

```yaml
# agents.yaml
agents:
  - name: order_lookup
    description: 查询订单状态、物流信息
    permission: read
    personality:
      tone: professional
      greeting: "您好，我来帮您查询订单信息。"
    tools:
      - get_order_status
      - get_tracking_info

  - name: order_actions
    description: 取消订单、修改订单
    permission: write  # 触发人工确认
    personality:
      tone: careful
      greeting: "我可以帮您处理订单变更，所有操作都会先经过您的确认。"
    tools:
      - cancel_order
      - modify_order

  - name: discount
    description: 发放优惠券、折扣码
    permission: write
    tools:
      - apply_discount
      - generate_coupon
```

## OpenAPI 自动接入

不需要手动写 MCP 连接器。粘贴你的 API 规范 URL：

1. 框架解析 OpenAPI 3.0 规范
2. LLM 自动分类每个端点（读/写、客户参数、Agent 分组）
3. 运维人员审核分类结果
4. 自动生成 MCP 服务器 + Agent YAML 配置
5. 新工具立即可用

## 安全设计

- **人工确认** - 所有写操作需要客户或运维人员批准
- **SSRF 防护** - OpenAPI URL 导入时屏蔽内网地址和 DNS 重绑定攻击
- **操作审计** - 每个操作记录 Agent、参数、结果、时间戳
- **权限隔离** - 每个 Agent 只能访问其配置的工具集
- **中断超时** - 30 分钟未确认的操作自动取消，防止过期审批

## 开发阶段

| 阶段 | 周期 | 内容 |
|------|------|------|
| Phase 1 | 第 1-3 周 | 核心框架：Chat UI + Supervisor + Agent 注册表 + 中断流程 |
| Phase 2 | 第 3-4 周 | 多 Agent 路由 + Webhook 升级 + 垂直模板 |
| Phase 3 | 第 4-6 周 | OpenAPI 自动发现 + MCP 服务器生成 + SSRF 防护 |
| Phase 4 | 第 6-7 周 | 对话回放 + 数据分析仪表盘 |

## 目标用户

中型电商公司（日均 500-5000 订单，5-20 名客服）的客户体验负责人。

他们的痛点：客服需要在 Zendesk 和 Shopify 后台之间反复切换，手动执行查询和操作。Smart Support 让 AI 直接完成这些操作，人工只需审批关键步骤。

## 相关文档

- [设计文档](design-doc.md) - 问题定义、约束、方案选择
- [CEO 计划](ceo-plan.md) - 产品愿景、范围决策
- [工程评审计划](eng-review-plan.md) - 架构决策、测试策略、失败模式
- [测试计划](eng-review-test-plan.md) - 测试路径、边界情况、E2E 流程
- [待办事项](TODOS.md) - 延迟到后续阶段的工作

## License

MIT