249 lines
9.1 KiB
Markdown
249 lines
9.1 KiB
Markdown
---
|
||
created: 2026-03-29
|
||
type: project
|
||
status: COMPLETED (2026-03-30)
|
||
parent: "[[Smart Support]]"
|
||
phase: 1
|
||
timeline: 第 1-3 周
|
||
tags:
|
||
- phase-1
|
||
- fastapi
|
||
- websocket
|
||
- langgraph
|
||
- agent-orchestration
|
||
- postgresql
|
||
- react
|
||
- yaml-registry
|
||
- interrupt
|
||
- hitl
|
||
- docker
|
||
- mock-agent
|
||
- token-tracking
|
||
- prompt-caching
|
||
- session-ttl
|
||
---
|
||
|
||
# Phase 1：核心框架
|
||
|
||
## 目标
|
||
|
||
搭建 Smart Support 的核心闭环：客户发消息 → AI Agent 处理 → 流式回复。这个阶段结束时，应该有一个完整可运行的聊天应用，能通过 mock 工具回答问题，并在写操作时触发人工确认。
|
||
|
||
## 阶段产出
|
||
|
||
- 可运行的全栈应用（`docker compose up` 一键启动）
|
||
- 聊天界面能发消息、收到流式回复
|
||
- 2-3 个演示 Agent 通过 mock 工具执行操作
|
||
- 写操作自动触发确认提示
|
||
|
||
## 集成检查点
|
||
|
||
第 3 周末验证：
|
||
1. `docker compose up` → PostgreSQL + FastAPI 正常启动
|
||
2. 打开 `http://localhost:8000` → 聊天界面加载
|
||
3. 发送「查询订单 1042 的状态」→ 收到流式回复
|
||
4. 发送「取消订单 1042」→ 收到确认提示 → 批准 → 确认取消
|
||
5. `pytest --cov` → 80%+ 覆盖率
|
||
|
||
---
|
||
|
||
## 任务清单
|
||
|
||
### 1. 基础设施搭建
|
||
|
||
- [ ] 初始化 Python 项目（`pyproject.toml`，依赖：fastapi, uvicorn, langgraph, langchain-anthropic, langgraph-checkpoint-postgres, langchain-mcp-adapters）
|
||
- [ ] 创建 `docker-compose.yml`（PostgreSQL 16 + 应用容器）
|
||
- [ ] 配置环境变量（`.env.example`）：`LLM_PROVIDER`, `LLM_MODEL`, `ANTHROPIC_API_KEY`, `DATABASE_URL`
|
||
- [ ] 创建项目目录结构：
|
||
|
||
```
|
||
backend/
|
||
├── app/
|
||
│ ├── __init__.py
|
||
│ ├── main.py
|
||
│ ├── graph.py
|
||
│ ├── registry.py
|
||
│ ├── callbacks.py
|
||
│ └── agents/
|
||
│ ├── __init__.py
|
||
│ ├── order_lookup.py
|
||
│ ├── faq.py
|
||
│ └── fallback.py
|
||
├── agents.yaml
|
||
└── tests/
|
||
├── __init__.py
|
||
├── test_graph.py
|
||
├── test_registry.py
|
||
├── test_websocket.py
|
||
└── conftest.py
|
||
```
|
||
|
||
### 2. PostgresSaver 检查点配置
|
||
|
||
- [ ] 在 `main.py` 启动时初始化 PostgresSaver（调用 `.setup()` 创建表结构）
|
||
- [ ] 配置连接池（asyncpg）
|
||
- [ ] 验证检查点持久化：重启应用后，之前的对话上下文仍可恢复
|
||
- [ ] DB 连接错误处理：graph 调用外层 try/except，捕获 DB 异常时返回「抱歉，系统暂时无法保存对话，请稍后重试」
|
||
|
||
### 3. YAML Agent 注册表
|
||
|
||
- [ ] 定义 `agents.yaml` 配置格式：
|
||
|
||
```yaml
|
||
agents:
|
||
- name: order_lookup
|
||
description: 查询订单状态、物流跟踪信息
|
||
permission: read
|
||
personality:
|
||
tone: professional
|
||
greeting: "您好，我来帮您查询订单信息。"
|
||
tools:
|
||
- get_order_status
|
||
- get_tracking_info
|
||
|
||
- name: faq
|
||
description: 回答常见问题（退货政策、运费、营业时间等）
|
||
permission: read
|
||
personality:
|
||
tone: friendly
|
||
greeting: "有什么可以帮您的？"
|
||
tools: []
|
||
|
||
- name: fallback
|
||
description: 通用兜底 Agent，处理无法路由的请求
|
||
permission: read
|
||
personality:
|
||
tone: helpful
|
||
tools: []
|
||
```
|
||
|
||
- [ ] 实现 `registry.py`：加载 YAML，验证必填字段（name, description, permission），缺失字段报明确错误（含文件名和字段名）
|
||
- [ ] 无效 YAML 语法 → 启动时抛出错误，包含行号
|
||
- [ ] Agent personality 配置解析（tone, greeting, escalation_message）
|
||
|
||
### 4. LangGraph Supervisor 配置
|
||
|
||
- [ ] 使用 `langgraph-supervisor` 创建 supervisor graph
|
||
- [ ] 从 agent 注册表动态注册 agents（注册表驱动，非硬编码）
|
||
- [ ] 每个 agent 配置对应的 mock 工具（`@tool` 装饰器）
|
||
- [ ] Mock 工具实现：
|
||
- `get_order_status(order_id: str)` → 返回模拟订单数据（状态、日期、金额）
|
||
- `get_tracking_info(order_id: str)` → 返回模拟物流数据
|
||
- `cancel_order(order_id: str)` → 返回取消确认（触发 interrupt）
|
||
- [ ] Fallback agent：当 supervisor 路由失败或 agent 返回「无法处理」时，fallback agent 接管，尝试所有可用工具
|
||
- [ ] Supervisor 使用 `ChatAnthropic`（Claude Sonnet 4.6），通过 `LLM_PROVIDER` + `LLM_MODEL` 环境变量可切换
|
||
|
||
### 5. interrupt() 人工确认流程
|
||
|
||
- [ ] 在 agent 调用写操作工具前触发 `interrupt()`
|
||
- [ ] 判断逻辑：agent YAML 中 `permission: write` 的 agent，其所有工具调用都触发确认
|
||
- [ ] 确认提示格式：「即将执行：取消订单 #1042。确认执行？[是/否]」
|
||
- [ ] 用户回复「是」→ `Command(resume="approved")` → 执行操作
|
||
- [ ] 用户回复「否」→ `Command(resume="rejected")` → 返回「操作已取消」
|
||
- [ ] 确认状态通过 PostgresSaver checkpoint 持久化
|
||
|
||
### 6. FastAPI WebSocket 端点
|
||
|
||
- [ ] `ws://localhost:8000/ws` WebSocket 端点
|
||
- [ ] 连接时生成 `thread_id`（UUID），作为 PostgresSaver 的 thread 标识
|
||
- [ ] 接收消息 → 调用 supervisor graph（`ainvoke` / `astream_events()`）
|
||
- [ ] 流式输出：通过 `astream_events()` 获取 LLM token，逐个通过 WebSocket 发送
|
||
- [ ] 消息协议：
|
||
|
||
```json
|
||
// 客户端 → 服务器
|
||
{"type": "message", "content": "查询订单 1042"}
|
||
|
||
// 服务器 → 客户端（流式 token）
|
||
{"type": "token", "content": "您"}
|
||
{"type": "token", "content": "的"}
|
||
{"type": "token", "content": "订单"}
|
||
|
||
// 服务器 → 客户端（确认提示）
|
||
{"type": "interrupt", "action": "cancel_order", "params": {"order_id": "1042"}, "message": "即将取消订单 #1042，确认执行？"}
|
||
|
||
// 客户端 → 服务器（确认回复）
|
||
{"type": "resume", "decision": "approved"}
|
||
|
||
// 服务器 → 客户端（错误）
|
||
{"type": "error", "message": "系统暂时无法处理，请稍后重试"}
|
||
```
|
||
|
||
- [ ] 断线处理：WebSocket 关闭时清理资源，不影响其他连接
|
||
- [ ] 无效 JSON → 返回 error 消息，不断开连接
|
||
|
||
### 7. React 聊天 UI
|
||
|
||
- [ ] 基础聊天界面（消息列表 + 输入框 + 发送按钮）
|
||
- [ ] WebSocket 连接管理（连接、断线重连）
|
||
- [ ] 流式 token 渲染（逐字显示 AI 回复）
|
||
- [ ] 中断确认 UI：收到 `interrupt` 消息时，显示操作描述 + 「确认」/「取消」按钮
|
||
- [ ] 错误提示：收到 `error` 消息时，显示红色提示
|
||
- [ ] Agent 操作可视化：显示 agent 正在执行的工具调用（如「正在查询订单...」）
|
||
|
||
### 8. Token 用量统计
|
||
|
||
- [ ] 实现 `callbacks.py`：LangChain callback handler，记录每次 LLM 调用的 input/output tokens
|
||
- [ ] 数据写入 PostgreSQL（独立表或利用 checkpoint metadata）
|
||
- [ ] 每条记录包含：`thread_id`, `agent_name`, `input_tokens`, `output_tokens`, `model`, `timestamp`
|
||
|
||
### 9. 测试
|
||
|
||
- [ ] **Graph 测试：** supervisor 收到「查询订单」→ 路由到 order_lookup agent → 调用 get_order_status → 返回结果
|
||
- [ ] **Graph 测试：** supervisor 收到模糊请求 → 路由到 fallback agent
|
||
- [ ] **Graph 测试：** agent 调用写操作 → interrupt 触发 → resume approved → 操作执行
|
||
- [ ] **Graph 测试：** interrupt → resume rejected → 操作取消
|
||
- [ ] **注册表测试：** 有效 YAML → agents 正确加载
|
||
- [ ] **注册表测试：** 无效 YAML → 明确错误信息
|
||
- [ ] **注册表测试：** 缺失必填字段 → validation error
|
||
- [ ] **WebSocket 测试：** 发送消息 → 收到流式 token
|
||
- [ ] **WebSocket 测试：** 发送无效 JSON → 收到 error，连接不断
|
||
- [ ] **WebSocket 测试：** 断线 → 服务器清理资源
|
||
- [ ] **DB 测试：** 连接正常 → checkpoint 持久化成功
|
||
- [ ] **DB 测试：** 连接失败 → 用户收到友好错误
|
||
- [ ] **E2E 测试：** 完整聊天流程（发消息 → 收回复）
|
||
- [ ] **E2E 测试：** 完整确认流程（写操作 → 确认 → 执行）
|
||
|
||
## 技术要点
|
||
|
||
| 组件 | 技术选型 | 说明 |
|
||
|------|---------|------|
|
||
| Web 框架 | FastAPI | 原生 WebSocket + async 支持 |
|
||
| Agent 编排 | langgraph-supervisor v1.1 | 内置 supervisor + middleware |
|
||
| 状态持久化 | langgraph-checkpoint-postgres v3.0.5 | 需调用 `.setup()` 初始化 |
|
||
| LLM | ChatAnthropic (Claude Sonnet 4.6) | 通过 LangChain BaseChatModel 抽象 |
|
||
| 流式输出 | astream_events() | Messages 模式，逐 token 推送 |
|
||
| 前端 | React | WebSocket 连接 + 流式渲染 |
|
||
| 数据库 | PostgreSQL 16 | Docker Compose 部署 |
|
||
| 测试 | pytest + FastAPI TestClient | 80%+ 覆盖率 |
|
||
|
||
## 依赖项
|
||
|
||
```
|
||
langgraph>=1.1.0
|
||
langgraph-supervisor
|
||
langgraph-checkpoint-postgres>=3.0.5
|
||
langchain-anthropic
|
||
langchain-mcp-adapters
|
||
fastapi
|
||
uvicorn[standard]
|
||
asyncpg
|
||
pyyaml
|
||
pytest
|
||
httpx
|
||
```
|
||
|
||
## 风险与缓解
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
|------|------|---------|
|
||
| LangGraph supervisor 路由不准 | Agent 收到错误类型的请求 | Fallback agent 兜底 + agent description 写清楚 |
|
||
| PostgresSaver 初始化失败 | 应用无法启动 | 启动时检查连接，失败报明确错误 |
|
||
| WebSocket 连接不稳定 | 用户体验差 | 前端自动重连 + 断线提示 |
|
||
| LLM API 超时 | 用户等待无响应 | 设置 timeout + 返回错误消息 |
|
||
|
||
## Related
|
||
|
||
- [[Smart Support]]
|
||
- [[Smart Support/Phase 2 - 多 Agent + 安全]]
|