kai/knowledge-base

Fork 0

Files

Yaojia Wang 7ab3575374 vault backup: 2026-04-06 16:23:54

2026-04-06 16:23:54 +02:00

9.1 KiB

Raw Blame History

created, updated, type, status, parent, phase, timeline, tags

created

updated

type

status

parent

phase

timeline

Phase 1：核心框架

目标

搭建 Smart Support 的核心闭环：客户发消息 → AI Agent 处理 → 流式回复。这个阶段结束时，应该有一个完整可运行的聊天应用，能通过 mock 工具回答问题，并在写操作时触发人工确认。

阶段产出

可运行的全栈应用（docker compose up 一键启动）
聊天界面能发消息、收到流式回复
2-3 个演示 Agent 通过 mock 工具执行操作
写操作自动触发确认提示

集成检查点

第 3 周末验证：

docker compose up → PostgreSQL + FastAPI 正常启动
打开 http://localhost:8000 → 聊天界面加载
发送「查询订单 1042 的状态」→ 收到流式回复
发送「取消订单 1042」→ 收到确认提示 → 批准 → 确认取消
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 + 返回错误消息

9.1 KiB Raw Blame History Unescape Escape