kai/knowledge-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
407b455f19cd2659ac66debad47fb791d3a46fb1
knowledge-base/2 - Projects/Smart Support/Phase 1 - 核心框架.md

8.9 KiB
Raw Blame History

created, type, status, parent, phase, timeline
created type status parent phase timeline
2026-03-29 project 未开始 Smart Support 1 第 1-3 周

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 配置格式：
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 发送
  • 消息协议：
// 客户端 → 服务器
{"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