---
created: "2026-03-29"
type: project
status: active
deadline: ""
---

# Smart Support

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

## 目标

解决现有客服工具（Zendesk、Intercom）自动化率卡在 20-30% 的问题。这些工具能回答 FAQ，但无法执行内部系统操作。Smart Support 作为「行动层」补充，让 AI 直接调用客户的内部系统完成查订单、取消订单、发优惠券等操作。

## 架构

```
客户 → React Chat UI → FastAPI WebSocket → LangGraph Supervisor → Agent → MCP Tools → 客户内部系统
```

核心组件：
- **langgraph-supervisor** v1.1 - 多 Agent 编排
- **langchain-mcp-adapters** - MCP 工具集成
- **PostgresSaver** - 会话状态持久化
- **interrupt()** - 写操作人工确认

## 技术栈

- Python 3.11+, FastAPI, LangGraph v1.1
- React（前端）, PostgreSQL（Docker Compose）
- Claude Sonnet 4.6（可切换 LLM）

## 核心特性

- 多 Agent 协作，YAML 驱动配置
- OpenAPI 规范自动生成 MCP 服务器 + Agent 配置（LLM 辅助分类 + 人工审核）
- 写操作人工确认（30 分钟超时自动取消）
- 对话回放 + 数据分析仪表盘
- Webhook 升级通知
- 垂直行业模板（电商、SaaS、金融科技）

## 开发阶段

| 阶段 | 周期 | 内容 | 状态 |
|------|------|------|------|
| 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 周 | 对话回放 + 数据分析仪表盘 | 未开始 |

### Phase 1：核心框架（第 1-3 周）

- [ ] FastAPI 后端 + WebSocket 聊天端点
- [ ] Docker Compose 配置（PostgreSQL 16 + 应用）
- [ ] PostgresSaver 检查点持久化（`.setup()` 初始化）
- [ ] LangGraph Supervisor 配置（2-3 个演示 Agent：订单查询、FAQ、升级）
- [ ] YAML Agent 注册表加载器（含验证，无效 YAML 报明确错误）
- [ ] Agent 人设配置（YAML 中 tone/greeting 字段）
- [ ] React 聊天 UI + WebSocket 连接 + 逐 token 流式渲染
- [ ] 基础 `interrupt()` 流程（写操作触发确认提示）
- [ ] Fallback Agent（路由错误时兜底）
- [ ] Token 用量统计回调（LangChain callback，写入 PostgreSQL）
- [ ] DB 连接错误处理（try/except，返回用户友好错误）
- [ ] **集成检查点：** 第 3 周末，完整聊天闭环端到端可用

### Phase 2：多 Agent + 安全（第 3-4 周）

- [ ] 完整 Supervisor 路由 + 意图分类
- [ ] Webhook 升级通知（HTTP POST 到配置 URL，含完整对话上下文）
- [ ] Webhook 失败重试（指数退避）
- [ ] 垂直行业模板（电商、SaaS YAML 配置文件）
- [ ] 过期中断处理（30 分钟 TTL 自动取消 + 重试提示）
- [ ] **集成检查点：** 第 4 周末，多 Agent 路由 + 中断流程可用

### Phase 3：OpenAPI 自动发现（第 4-6 周）

- [ ] SSRF 防护模块（屏蔽内网 IP、localhost、169.254.x，DNS 重绑定防护）
- [ ] OpenAPI 3.0 规范解析器（用 `openapi-spec-validator` 验证）
- [ ] 无效/格式错误规范 → 明确错误信息
- [ ] 从规范生成完整 MCP 服务器（每个端点一个工具）
- [ ] LLM 辅助端点分类（读/写、客户参数识别、Agent 分组建议）
- [ ] 运维审核/修正 UI（确认 LLM 分类结果）
- [ ] 从分类结果自动生成 Agent YAML 配置
- [ ] 异步导入 + WebSocket 进度更新（「解析规范...」「生成工具 3/50...」「完成！」）
- [ ] **集成检查点：** 第 6 周末，粘贴真实 API 规范 → 工具在聊天中可用

### Phase 4：分析 + 回放（第 6-7 周）

- [ ] 自定义分页回放 API 端点（`/api/replay/{thread_id}`）
- [ ] 回放 UI（React 时间线组件，逐步展示 Agent 决策、工具调用、返回结果）
- [ ] 分析查询（解决率、Agent 使用率、升级率、每次对话成本）
- [ ] 解决率计算：成功工具调用 + 未触发升级
- [ ] 分析仪表盘 UI + 零数据状态处理
- [ ] **集成检查点：** 第 7 周末，完整产品演示就绪

### Phase 5：打磨 + 演示准备（缓冲）

- [ ] 错误处理加固
- [ ] 演示脚本 + 示例数据
- [ ] Docker Compose 全栈部署配置
- [ ] 90 秒屏幕录制

## 目标用户

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

## 仓库

- 代码：`ssh://git@git.colacoder.com:2200/kai/smart-support.git`
- 分支：`main`
- 本地路径：`/Users/yiukai/Documents/git/smart-support`

## 计划文档

项目根目录下：
- `design-doc.md` - 设计文档（问题定义、约束、方案选择）
- `ceo-plan.md` - CEO 计划（产品愿景、范围决策）
- `eng-review-plan.md` - 工程评审（架构决策、测试策略、失败模式）
- `eng-review-test-plan.md` - 测试计划（测试路径、边界情况、E2E 流程）
- `TODOS.md` - 待办事项

## 关键决策

- 用 LangGraph 内置能力（supervisor、checkpointer、interrupt），不自己造轮子
- PostgresSaver 从第一天起使用，为后期分析和回放打基础
- OpenAPI 导入生成完整 MCP 服务器（非简单 @tool 函数），LLM 辅助端点分类
- 路由错误时有 fallback agent 兜底
- 解决率定义：成功工具调用 + 未升级
- Token 用量从第一天起记录

## 待解决

- [ ] 认证/授权系统（生产部署前）
- [ ] 多租户架构（第一个付费客户后）
- [ ] CI/CD 流水线（原型阶段手动部署）
- [ ] 路由准确率评估数据集
- [ ] 过期中断处理（Phase 2 实现）
- [ ] SSRF 防护模块（Phase 3 前构建）

## Related

- [[Billo Release Agent]] - 另一个 AI Agent 项目