f93e8baef1
Smart Support - AI customer service action layer framework. Includes design doc, CEO plan, eng review, test plan, and README.
161 lines
5.9 KiB
Markdown
161 lines
5.9 KiB
Markdown
# 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
|