feat: initial project setup with planning docs
Smart Support - AI customer service action layer framework. Includes design doc, CEO plan, eng review, test plan, and README.
This commit is contained in:
Yaojia Wang
160
README.md
Normal file
160
README.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user