Files

Yaojia Wang 33db5aeb10 feat: complete phase 4 -- conversation replay API + analytics dashboard

- Replay models: StepType enum, ReplayStep, ReplayPage frozen dataclasses
- Checkpoint transformer: PostgresSaver JSONB -> structured timeline steps
- Replay API: GET /api/conversations (paginated), GET /api/replay/{thread_id}
- Analytics models: AgentUsage, InterruptStats, AnalyticsResult
- Analytics event recorder: Protocol + PostgresAnalyticsRecorder + NoOp
- Analytics queries: resolution_rate, agent_usage, escalation_rate, cost, interrupts
- Analytics API: GET /api/analytics?range=Xd with envelope response
- DB migration: analytics_events table + conversations column additions
- 74 new tests, 399 total passing, 92.87% coverage

2026-03-31 13:35:45 +02:00

40 KiB

Raw Blame History

Smart Support -- 详细开发计划

基于 CEO 计划、设计文档、工程评审计划、测试计划和 TODOS 综合制定。生成日期: 2026-03-29 预计总工期: 7-8 周 (1 名全职高级 Python 工程师)

配套文档: 技术栈、项目结构、架构决策 (ADR)、数据库 schema、API 协议、安全架构等详见 ARCHITECTURE.md

总览

Smart Support 是一个 AI 客服行动层框架。核心价值主张: "粘贴你的 API, 获得一个能执行真实操作的智能客服。"

框架不替代 Zendesk/Intercom, 而是补全它们缺失的"行动层" -- 让 AI 能直接调用内部系统完成查询、取消、退款等操作。

技术栈、项目结构、架构决策详见 ARCHITECTURE.md。本文档专注于 什么时候做什么、怎么验证、有什么风险。

Phase 1: 核心框架 (第 1-3 周)

Status: COMPLETED (2026-03-30) Dev log: Phase 1 Dev Log

目标

搭建完整的聊天回路: 用户在 React UI 发送消息 -> FastAPI WebSocket 接收 -> LangGraph Supervisor 处理 -> Mock Agent 响应 -> 流式返回给用户。所有会话状态通过 PostgresSaver 持久化。

任务清单

1.1 项目初始化与基础设施 (预计 2 天)

1.1.1 初始化 Python 项目结构 (pyproject.toml, 依赖管理)
- 文件: backend/pyproject.toml
- 工作量: S (2 小时)
- 依赖: 无
- 风险: 低
1.1.2 创建 Docker Compose 配置 (PostgreSQL 16 + 应用)
- 文件: docker-compose.yml
- 工作量: S (2 小时)
- 依赖: 无
- 风险: 低
1.1.3 配置 PostgresSaver 检查点持久化
- 文件: backend/app/db.py
- 工作量: M (4 小时)
- 依赖: 1.1.2
- 风险: 中 -- PostgresSaver schema 初始化需要验证兼容性
1.1.4 设置 pytest + FastAPI TestClient 测试框架
- 文件: backend/tests/conftest.py, backend/pyproject.toml
- 工作量: S (2 小时)
- 依赖: 1.1.1
- 风险: 低
1.1.5 配置环境变量管理 (LLM_PROVIDER, LLM_MODEL, DB 连接等)
- 文件: backend/app/config.py, .env.example
- 工作量: S (1 小时)
- 依赖: 无
- 风险: 低

1.2 YAML Agent 注册表 (预计 2 天)

1.2.1 设计 Agent YAML 配置 schema (name, description, permission, personality, tools)
- 文件: backend/agents.yaml
- 工作量: S (2 小时)
- 依赖: 无
- 风险: 低
1.2.2 实现 YAML 注册表加载器 + 校验 (无效 YAML 需给出文件/行号错误)
- 文件: backend/app/registry.py
- 工作量: M (4 小时)
- 依赖: 1.2.1
- 风险: 中 -- 校验逻辑需覆盖各种畸形输入
1.2.3 实现 Agent 人格配置 (tone, greeting, escalation_style)
- 文件: backend/app/registry.py (扩展)
- 工作量: S (1 小时)
- 依赖: 1.2.2
- 风险: 低
1.2.4 编写注册表加载器单元测试 (正常加载、空文件、无效 YAML、缺少必填字段)
- 文件: backend/tests/test_registry.py
- 工作量: S (2 小时)
- 依赖: 1.2.2
- 风险: 低

1.3 Mock Agent 与工具 (预计 1.5 天)

1.3.1 创建 Mock 订单查询 Agent + 工具 (get_order_status, get_tracking_info)
- 文件: backend/app/agents/order_lookup.py
- 工作量: M (3 小时)
- 依赖: 1.2.2
- 风险: 低
1.3.2 创建 Mock 订单操作 Agent + 工具 (cancel_order -- 需要 interrupt)
- 文件: backend/app/agents/order_actions.py
- 工作量: M (3 小时)
- 依赖: 1.2.2
- 风险: 低
1.3.3 创建通用回退 Agent (处理误路由和无法分类的意图)
- 文件: backend/app/agents/fallback.py
- 工作量: S (2 小时)
- 依赖: 1.2.2
- 风险: 低
1.3.4 编写 Mock Agent 单元测试
- 文件: backend/tests/test_agents.py
- 工作量: S (2 小时)
- 依赖: 1.3.1, 1.3.2, 1.3.3
- 风险: 低

1.4 LangGraph Supervisor 配置 (预计 2 天)

1.4.1 配置 LangGraph Supervisor (使用 langgraph-supervisor, 连接注册表中的 Agents)
- 文件: backend/app/graph.py
- 工作量: M (6 小时)
- 依赖: 1.2.2, 1.3.1, 1.3.2, 1.3.3
- 风险: 高 -- LangGraph supervisor 配置是核心, 如果阻塞超过 5 天需回退到单 Agent
1.4.2 实现基础 interrupt() 流程 (写操作触发人工确认)
- 文件: backend/app/graph.py (扩展)
- 工作量: M (4 小时)
- 依赖: 1.4.1
- 风险: 中 -- interrupt/resume 状态管理需仔细测试
1.4.3 配置 LLM Provider 抽象 (BaseChatModel + 环境变量切换)
- 文件: backend/app/llm.py
- 工作量: S (2 小时)
- 依赖: 1.1.5
- 风险: 低
1.4.4 实现 Token 用量统计回调
- 文件: backend/app/callbacks.py
- 工作量: S (2 小时)
- 依赖: 1.4.1
- 风险: 低
1.4.5 启用 Prompt Caching (从第一天减少重复 system prompt 的 LLM 成本)
- 文件: backend/app/llm.py (扩展)
- 工作量: S (1 小时)
- 依赖: 1.4.3
- 风险: 低
- 来源: TODOS.md 设计变更 -- "Prompt caching: 从第一天启用"
1.4.6 实现会话滑动窗口 TTL (30 分钟, 每次消息重置; 待审批的 interrupt 延长 TTL 直到解决)
- 文件: backend/app/session_manager.py
- 工作量: M (3 小时)
- 依赖: 1.4.1, 1.1.3
- 风险: 中 -- 需区分 session TTL (滑动窗口) 和 interrupt TTL (固定 30 分钟)
- 来源: design-doc.md -- "30-minute sliding window TTL (reset on each turn)"
1.4.7 编写 Graph 单元测试 (supervisor 路由、mock 工具调用、状态断言、session TTL)
- 文件: backend/tests/test_graph.py
- 工作量: M (4 小时)
- 依赖: 1.4.1, 1.4.2
- 风险: 中

1.5 FastAPI WebSocket 后端 (预计 2 天)

1.5.1 实现 FastAPI 应用入口 + WebSocket /ws 端点
- 文件: backend/app/main.py
- 工作量: M (4 小时)
- 依赖: 1.4.1
- 风险: 低
1.5.2 实现 WebSocket 流式输出 (astream_events)
- 文件: backend/app/main.py (扩展)
- 工作量: M (4 小时)
- 依赖: 1.5.1
- 风险: 中 -- 流式事件格式需与前端协议一致
1.5.3 实现 interrupt 响应处理 (WebSocket 接收审批/拒绝, 恢复 graph 执行)
- 文件: backend/app/main.py (扩展)
- 工作量: M (4 小时)
- 依赖: 1.5.2, 1.4.2
- 风险: 高 -- 断线重连 + 重发 interrupt 提示是易出错点
1.5.4 实现 DB 错误处理 (try/except 包裹 graph 调用, 返回友好错误信息)
- 文件: backend/app/main.py (扩展)
- 工作量: S (1 小时)
- 依赖: 1.5.1
- 风险: 低
1.5.5 编写 WebSocket 测试 (连接、消息流、流式输出、interrupt 响应、断线处理)
- 文件: backend/tests/test_websocket.py
- 工作量: M (4 小时)
- 依赖: 1.5.1, 1.5.2, 1.5.3
- 风险: 中

1.6 React 聊天 UI (预计 3 天) [可并行]

1.6.1 初始化 React 项目 (Vite 或 CRA)
- 文件: frontend/ 目录
- 工作量: S (1 小时)
- 依赖: 无
- 风险: 低
1.6.2 实现聊天消息列表组件 (支持流式 token 渲染)
- 文件: frontend/src/components/ChatMessages.tsx
- 工作量: M (4 小时)
- 依赖: 1.6.1
- 风险: 低
1.6.3 实现消息输入组件
- 文件: frontend/src/components/ChatInput.tsx
- 工作量: S (2 小时)
- 依赖: 1.6.1
- 风险: 低
1.6.4 实现 WebSocket 连接管理 (连接、断线重连、消息收发)
- 文件: frontend/src/hooks/useWebSocket.ts
- 工作量: M (4 小时)
- 依赖: 1.6.1
- 风险: 中 -- 需处理断线重连逻辑
1.6.5 实现 interrupt 确认 UI (确认/拒绝按钮, 操作详情展示)
- 文件: frontend/src/components/InterruptPrompt.tsx
- 工作量: M (3 小时)
- 依赖: 1.6.4
- 风险: 低
1.6.6 实现 Agent 操作内联展示 (工具调用过程可见)
- 文件: frontend/src/components/AgentAction.tsx
- 工作量: S (2 小时)
- 依赖: 1.6.2
- 风险: 低
1.6.7 集成聊天页面主组件
- 文件: frontend/src/pages/ChatPage.tsx
- 工作量: M (3 小时)
- 依赖: 1.6.2, 1.6.3, 1.6.4, 1.6.5, 1.6.6
- 风险: 低

Phase 1 检查点标准

通过以下全部验证才能进入 Phase 2:

docker compose up 成功启动 PostgreSQL + 应用
打开 http://localhost:8000 聊天 UI 加载正常
发送 "订单 1042 的状态" -> 收到 Mock Agent 的流式响应
发送 "取消订单 1042" -> 收到 interrupt 确认提示 -> 批准 -> 收到确认消息
发送 "取消订单 1042" -> 收到 interrupt 确认提示 -> 拒绝 -> 收到取消消息
多轮对话上下文保持 (通过 PostgresSaver 验证)
会话 30 分钟无活动后过期; 每次消息重置 TTL; 待审批 interrupt 延长 TTL
无效 YAML 配置启动时给出清晰错误信息
pytest --cov 覆盖率 >= 80% (Phase 1 代码)

Phase 1 测试要求

类型	测试项	文件
单元测试	YAML 注册表加载/校验	`tests/test_registry.py`
单元测试	Mock Agent 工具调用	`tests/test_agents.py`
单元测试	Graph supervisor 路由	`tests/test_graph.py`
单元测试	会话滑动窗口 TTL (过期、重置、interrupt 延长)	`tests/test_graph.py`
集成测试	WebSocket 消息流	`tests/test_websocket.py`
集成测试	interrupt 审批/拒绝流程	`tests/test_websocket.py`
E2E	Happy path: 查询 -> 响应	手动验证
E2E	取消 + 批准: 写操作 -> interrupt -> 批准	手动验证
E2E	取消 + 拒绝: 写操作 -> interrupt -> 拒绝	手动验证

Phase 1 风险项

风险	严重度	缓解措施
LangGraph supervisor 配置复杂度超预期	高	如果阻塞超过 5 天, 回退到单 Agent + 工具路由, 后续再重构为多 Agent
PostgresSaver schema 兼容性问题	中	提前阅读 langgraph-checkpoint-postgres 文档, 使用官方 migration
WebSocket interrupt/resume 状态管理	中	先实现最简版本 (无断线重连), 后续迭代增强
流式事件格式前后端不一致	中	提前定义 WebSocket 消息协议文档, 前后端同步开发

Phase 1 交付物

FastAPI 后端 (WebSocket 聊天端点)
LangGraph Supervisor + 3 个 Mock Agent
YAML Agent 注册表加载器
PostgresSaver 检查点持久化
React 聊天 UI (流式输出 + interrupt 确认)
Docker Compose 配置
单元测试 + 集成测试 (覆盖率 >= 80%)

Phase 2: 多 Agent 路由 + 安全层 (第 3-4 周)

Status: COMPLETED (2026-03-30) Dev log: Phase 2 Dev Log

目标

完善 Supervisor 的意图分类和多 Agent 路由能力, 实现 Webhook 升级、垂直行业模板、中断超时处理。

前置条件

Phase 1 检查点全部通过
TODOS.md 中无阻塞 Phase 2 的待办项

任务清单

2.1 Supervisor 路由增强 (预计 2 天)

2.1.1 实现 LLM 结构化输出的意图分类 (基于 Agent 描述选择)
- 文件: backend/app/graph.py (增强)
- 工作量: M (4 小时)
- 依赖: Phase 1 完成
- 风险: 中 -- 路由准确率需要评估
2.1.2 实现多意图请求处理 ("取消订单并给我一个折扣" -> 顺序执行)
- 文件: backend/app/graph.py (增强)
- 工作量: M (6 小时)
- 依赖: 2.1.1
- 风险: 高 -- 多意图原子性问题 (全部成功 vs. 部分失败升级)
2.1.3 实现歧义意图处理 (无法分类时询问澄清问题)
- 文件: backend/app/agents/fallback.py (增强)
- 工作量: S (2 小时)
- 依赖: 2.1.1
- 风险: 低
2.1.4 编写路由测试 (正确路由、多意图、歧义、回退)
- 文件: backend/tests/test_routing.py
- 工作量: M (4 小时)
- 依赖: 2.1.1, 2.1.2, 2.1.3
- 风险: 低

2.2 Mock 折扣 Agent (预计 0.5 天)

2.2.1 创建 Mock 折扣 Agent + 工具 (apply_discount, generate_coupon)
- 文件: backend/app/agents/discount.py
- 工作量: S (2 小时)
- 依赖: Phase 1
- 风险: 低
2.2.2 更新 agents.yaml 添加折扣 Agent 配置
- 文件: backend/agents.yaml
- 工作量: S (30 分钟)
- 依赖: 2.2.1
- 风险: 低

2.3 中断超时处理 (预计 1 天)

2.3.1 实现 30 分钟 TTL 自动取消机制
- 文件: backend/app/interrupt_manager.py
- 工作量: M (4 小时)
- 依赖: Phase 1 (interrupt 基础)
- 风险: 中 -- 定时器精度和状态一致性
2.3.2 实现过期后重试提示 (重新评估当前状态后重新发起)
- 文件: backend/app/interrupt_manager.py (扩展)
- 工作量: M (3 小时)
- 依赖: 2.3.1
- 风险: 中
2.3.3 编写中断超时测试
- 文件: backend/tests/test_interrupt.py
- 工作量: S (2 小时)
- 依赖: 2.3.1, 2.3.2
- 风险: 低

2.4 Webhook 升级 (预计 1 天)

2.4.1 实现 Webhook 升级模块 (HTTP POST 到配置的 URL, 包含完整对话上下文)
- 文件: backend/app/escalation.py
- 工作量: M (3 小时)
- 依赖: Phase 1
- 风险: 低
2.4.2 实现 Webhook 重试机制 (指数退避, 最多 3 次)
- 文件: backend/app/escalation.py (扩展)
- 工作量: S (2 小时)
- 依赖: 2.4.1
- 风险: 低
2.4.3 编写 Webhook 测试 (成功发送、目标不可达、重试)
- 文件: backend/tests/test_escalation.py
- 工作量: S (2 小时)
- 依赖: 2.4.1, 2.4.2
- 风险: 低

2.5 垂直行业模板 (预计 0.5 天)

2.5.1 创建电商模板 YAML (订单查询、订单操作、折扣)
- 文件: backend/templates/e-commerce.yaml
- 工作量: S (1 小时)
- 依赖: 1.2.2
- 风险: 低
2.5.2 创建 SaaS 模板 YAML (账户查询、订阅管理、计费)
- 文件: backend/templates/saas.yaml
- 工作量: S (1 小时)
- 依赖: 1.2.2
- 风险: 低
2.5.3 创建 Fintech 模板 YAML (交易查询、争议处理)
- 文件: backend/templates/fintech.yaml
- 工作量: S (1 小时)
- 依赖: 1.2.2
- 风险: 低
2.5.4 实现模板加载逻辑 (选择模板 -> 覆盖 agents.yaml)
- 文件: backend/app/registry.py (扩展)
- 工作量: S (2 小时)
- 依赖: 2.5.1, 2.5.2, 2.5.3
- 风险: 低

Phase 2 检查点标准

发送 "查询订单 1042" -> 路由到订单查询 Agent
发送 "取消订单 1042 并给我一个 10% 折扣" -> 顺序执行两个 Agent
发送模糊消息 -> 回退 Agent 请求澄清
interrupt 超过 30 分钟 -> 自动取消 + 提供重试选项
Agent 升级 -> Webhook POST 发送成功 (或重试后日志记录)
使用电商模板启动 -> 3 个预配置 Agent 正常工作 (实际 4 个: +discount)
pytest --cov 覆盖率 >= 80% (实际 92.60%, 188 tests)

Phase 2 测试要求

类型	测试项	文件
单元测试	意图分类准确性	`tests/test_routing.py`
单元测试	多意图顺序执行	`tests/test_routing.py`
单元测试	中断 TTL 超时	`tests/test_interrupt.py`
单元测试	Webhook 发送/重试	`tests/test_escalation.py`
集成测试	完整多 Agent 路由流程	`tests/test_routing.py`
E2E	多轮上下文: "查询 1042" 然后 "取消那个" -> 正确实体解析	手动验证

Phase 2 风险项

风险	严重度	缓解措施
多意图原子性不清晰	高	采用 best-effort 模式: 部分失败时升级人工, 不回滚已完成操作
Supervisor 路由准确率不足	中	编写路由准确率评估数据集, 设定基线 (>90% 准确率)
30 分钟 TTL 定时器精度	低	使用数据库时间戳比对, 不依赖内存定时器

Phase 2 交付物

完善的多 Agent 路由 (意图分类 + 多意图 + 歧义处理)
Mock 折扣 Agent
interrupt 30 分钟 TTL 自动取消 + 重试
Webhook 升级模块 (带重试)
3 个垂直行业模板 (电商、SaaS、Fintech)
路由 + 中断 + 升级测试

Phase 3: OpenAPI 自动发现 (第 4-6 周)

Status: COMPLETED (2026-03-30) Dev log: Phase 3 Dev Log

目标

实现 "粘贴 API URL, 自动生成可用工具" 的核心差异化功能。解析 OpenAPI 3.0 规范, 生成 MCP 服务器, LLM 辅助分类端点, 运维审核后自动生成 Agent 配置。

前置条件

Phase 2 检查点全部通过
TODOS: 工具接口决策 (支持 MCP/CLI/直接 API 三种后端) 在此阶段开始前完成 (~2-3 小时研究)

任务清单

3.0 工具接口研究 (预计 0.5 天) [来自 TODOS.md]

3.0.1 研究 MCP Python SDK (mcp on PyPI), 确定 MCP/CLI/API 三种后端的抽象方式
- 工作量: S (2-3 小时)
- 依赖: 无
- 风险: 低
3.0.2 设计工具基类, 抽象多后端支持 (LangChain @tool 函数式封装)
- 文件: backend/app/tools/base.py
- 工作量: M (3 小时)
- 依赖: 3.0.1
- 风险: 中

3.1 SSRF 防护工具 (预计 1 天) [可提前并行开发]

3.1.1 实现 SSRF 防护模块 (屏蔽私有 IP: 10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x, ::1)
- 文件: backend/app/openapi/ssrf.py
- 工作量: M (3 小时)
- 依赖: 无
- 风险: 低
3.1.2 实现 DNS 重绑定防护 (解析 DNS 后再验证 IP, 不信任域名)
- 文件: backend/app/openapi/ssrf.py (扩展)
- 工作量: M (3 小时)
- 依赖: 3.1.1
- 风险: 中 -- 需覆盖 IPv6 和边界情况
3.1.3 编写 SSRF 防护测试 (私有 IP、localhost、169.254.x、DNS 重绑定、正常 URL)
- 文件: backend/tests/test_ssrf.py
- 工作量: S (2 小时)
- 依赖: 3.1.1, 3.1.2
- 风险: 低

3.2 OpenAPI 规范解析 (预计 2 天)

3.2.1 实现 OpenAPI 规范获取 (URL 下载, 经 SSRF 检查)
- 文件: backend/app/openapi/fetcher.py
- 工作量: M (3 小时)
- 依赖: 3.1.1
- 风险: 低
3.2.2 实现 OpenAPI 规范校验 (使用 openapi-spec-validator)
- 文件: backend/app/openapi/validator.py
- 工作量: S (2 小时)
- 依赖: 3.2.1
- 风险: 低
3.2.3 实现端点提取和结构化 (路径、方法、参数、请求体、响应)
- 文件: backend/app/openapi/parser.py
- 工作量: M (6 小时)
- 依赖: 3.2.2
- 风险: 中 -- 真实 OpenAPI 规范的复杂度 (嵌套 $ref, allOf, etc.)
3.2.4 编写解析器测试 (有效规范、无效规范、100+ 端点、边界 case)
- 文件: backend/tests/test_openapi_parser.py
- 工作量: M (3 小时)
- 依赖: 3.2.3
- 风险: 低

3.3 LLM 辅助分类 (预计 2 天)

3.3.1 实现 LLM 端点分类 (每个端点: 读/写、客户参数、推荐 Agent 分组)
- 文件: backend/app/openapi/classifier.py
- 工作量: M (6 小时)
- 依赖: 3.2.3
- 风险: 中 -- LLM 分类质量依赖 prompt 设计
3.3.2 实现分类结果结构化输出 (JSON schema 约束)
- 文件: backend/app/openapi/classifier.py (扩展)
- 工作量: S (2 小时)
- 依赖: 3.3.1
- 风险: 低
3.3.3 编写分类器测试 (Mock LLM 响应, 验证分类逻辑)
- 文件: backend/tests/test_classifier.py
- 工作量: M (3 小时)
- 依赖: 3.3.1
- 风险: 低

3.4 运维审核 UI (预计 1.5 天)

3.4.1 实现分类结果审核 API (GET 分类结果, POST 修正)
- 文件: backend/app/openapi/review_api.py
- 工作量: M (4 小时)
- 依赖: 3.3.1
- 风险: 低
3.4.2 实现审核 UI 页面 (表格展示每个端点分类, 可编辑) -- deferred to Phase 5
- 文件: frontend/src/pages/ReviewPage.tsx
- 工作量: M (6 小时)
- 依赖: 3.4.1
- 风险: 低

3.5 MCP 服务器生成 (预计 2 天)

3.5.1 实现 MCP 工具包装器生成 (每个端点 -> LangChain @tool 或 MCP server)
- 文件: backend/app/openapi/generator.py
- 工作量: L (8 小时)
- 依赖: 3.3.1, 3.0.2
- 风险: 高 -- MCP 服务器生成是本项目最复杂的代码生成任务
3.5.2 实现 Agent YAML 自动生成 (基于分类结果生成 agents.yaml)
- 文件: backend/app/openapi/generator.py (扩展)
- 工作量: M (4 小时)
- 依赖: 3.5.1
- 风险: 中
3.5.3 编写生成器测试 (生成的工具可调用, YAML 可加载)
- 文件: backend/tests/test_generator.py
- 工作量: M (4 小时)
- 依赖: 3.5.1, 3.5.2
- 风险: 低

3.6 异步导入流程 (预计 1 天)

3.6.1 实现后台异步任务 (不阻塞聊天)
- 文件: backend/app/openapi/importer.py
- 工作量: M (4 小时)
- 依赖: 3.5.1, 3.5.2
- 风险: 中
3.6.2 实现 WebSocket 进度更新 (解析中 -> 分类中 -> 审核中 -> 完成)
- 文件: backend/app/openapi/importer.py (扩展)
- 工作量: M (3 小时)
- 依赖: 3.6.1
- 风险: 低
3.6.3 编写导入流程集成测试
- 文件: backend/tests/test_importer.py
- 工作量: M (3 小时)
- 依赖: 3.6.1, 3.6.2
- 风险: 低

Phase 3 检查点标准

粘贴一个真实 OpenAPI 规范 URL -> 端点被正确解析
LLM 分类结果展示在审核页面, 可编辑
审核通过后, 自动生成的工具在聊天中可用
SSRF 尝试 (localhost, 私有 IP) 被阻止并返回清晰错误
无效/畸形 OpenAPI 规范 -> 返回清晰错误信息
100+ 端点的规范 -> 生成不超时
导入过程不阻塞聊天, 进度通过 WebSocket 更新
pytest --cov 覆盖率 >= 80%

Phase 3 测试要求

类型	测试项	文件
单元测试	SSRF 防护 (各种 IP/域名)	`tests/test_ssrf.py`
单元测试	OpenAPI 解析 (有效/无效/复杂规范)	`tests/test_openapi_parser.py`
单元测试	LLM 分类 (Mock LLM)	`tests/test_classifier.py`
单元测试	MCP 工具/YAML 生成	`tests/test_generator.py`
集成测试	完整导入流程	`tests/test_importer.py`
E2E	粘贴规范 URL -> 工具生成 -> 在聊天中使用	手动验证

Phase 3 风险项

风险	严重度	缓解措施
MCP 服务器代码生成质量不稳定	高	先支持简单 REST API (GET/POST), 复杂场景 (OAuth, 分页) 延后
真实 OpenAPI 规范的边界 case 超多	高	使用 openapi-spec-validator 做前置校验, 不支持的特性给出明确提示
LLM 分类准确率不够	中	运维审核 UI 是安全网, LLM 只是建议
DNS 重绑定防护遗漏	中	解析后缓存 IP, 请求时二次验证

Phase 3 交付物

SSRF 防护独立模块
OpenAPI 规范解析器
LLM 辅助端点分类器
运维审核 API + UI
MCP 工具/Agent YAML 自动生成器
异步导入流程 (带 WebSocket 进度)
完整测试套件

Phase 4: 对话回放 + 数据分析 (第 6-7 周)

Status: COMPLETED (2026-03-31) Dev log: Phase 4 Dev Log

目标

实现对话回放 UI (逐步查看 Agent 决策过程) 和数据分析仪表盘 (解决率、Agent 使用率、升级率、每次对话成本)。

前置条件

Phase 1 检查点通过 (PostgresSaver 数据可查询)
Phase 2 检查点通过 (有足够的对话数据类型)
注意: Phase 4 不依赖 Phase 3, 如果 Phase 3 延迟可提前启动

任务清单

4.1 对话回放 API (预计 2 天)

4.1.1 设计回放数据模型 (步骤类型: agent_selection, tool_call, tool_result, interrupt, response)
- 文件: backend/app/replay/models.py
- 工作量: M (3 小时)
- 依赖: Phase 1
- 风险: 低
4.1.2 实现分页回放 API (GET /api/replay/{thread_id}, 支持 200+ 轮次)
- 文件: backend/app/replay/api.py
- 工作量: M (6 小时)
- 依赖: 4.1.1
- 风险: 中 -- PostgresSaver checkpoint 数据的查询性能
4.1.3 实现 checkpoint 数据 -> 结构化时间线 JSON 转换
- 文件: backend/app/replay/transformer.py
- 工作量: M (4 小时)
- 依赖: 4.1.2
- 风险: 中 -- checkpoint 内部结构可能随 LangGraph 版本变化
4.1.4 编写回放 API 测试 (正常回放、404、分页、空对话)
- 文件: backend/tests/test_replay.py
- 工作量: M (3 小时)
- 依赖: 4.1.2, 4.1.3
- 风险: 低

4.2 回放 UI (预计 2 天)

4.2.1 实现对话列表页面 (选择要回放的对话)
- 文件: frontend/src/pages/ReplayListPage.tsx
- 工作量: M (3 小时)
- 依赖: 4.1.2
- 风险: 低
4.2.2 实现步骤时间线组件 (逐步展示 Agent 决策、工具调用、结果)
- 文件: frontend/src/components/ReplayTimeline.tsx
- 工作量: M (6 小时)
- 依赖: 4.1.3
- 风险: 低
4.2.3 实现回放详情页面 (集成时间线 + 对话内容)
- 文件: frontend/src/pages/ReplayPage.tsx
- 工作量: M (4 小时)
- 依赖: 4.2.1, 4.2.2
- 风险: 低

4.3 数据分析 API (预计 2 天)

4.3.1 实现解决率查询 (成功工具调用 + 无升级)
- 文件: backend/app/analytics/queries.py
- 工作量: M (4 小时)
- 依赖: Phase 1 (callbacks.py)
- 风险: 中 -- 需要从 checkpoint 数据中提取结构化指标
4.3.2 实现 Agent 使用率查询 (每个 Agent 的调用次数和占比)
- 文件: backend/app/analytics/queries.py (扩展)
- 工作量: M (3 小时)
- 依赖: 4.3.1
- 风险: 低
4.3.3 实现升级率查询 (升级到人工的对话占比)
- 文件: backend/app/analytics/queries.py (扩展)
- 工作量: S (2 小时)
- 依赖: 4.3.1
- 风险: 低
4.3.4 实现每次对话成本查询 (基于 token 用量统计)
- 文件: backend/app/analytics/queries.py (扩展)
- 工作量: M (3 小时)
- 依赖: Phase 1 (callbacks.py)
- 风险: 低
4.3.5 实现分析 API 端点 (GET /api/analytics, 聚合所有指标)
- 文件: backend/app/analytics/api.py
- 工作量: M (3 小时)
- 依赖: 4.3.1, 4.3.2, 4.3.3, 4.3.4
- 风险: 低
4.3.6 编写分析查询测试 (有数据、无数据零状态、大量数据)
- 文件: backend/tests/test_analytics.py
- 工作量: M (3 小时)
- 依赖: 4.3.5
- 风险: 低

4.4 分析仪表盘 UI (预计 1.5 天)

4.4.1 实现仪表盘页面 (解决率、Agent 使用率、升级率、成本)
- 文件: frontend/src/pages/DashboardPage.tsx
- 工作量: M (6 小时)
- 依赖: 4.3.5
- 风险: 低
4.4.2 实现零状态处理 (无对话数据时的友好提示)
- 文件: frontend/src/pages/DashboardPage.tsx (扩展)
- 工作量: S (1 小时)
- 依赖: 4.4.1
- 风险: 低
4.4.3 实现前端路由 (聊天 / 回放 / 仪表盘导航)
- 文件: frontend/src/App.tsx
- 工作量: S (2 小时)
- 依赖: 4.4.1, 4.2.3
- 风险: 低

Phase 4 检查点标准

完成一次对话后, 在回放页面可以逐步查看 Agent 决策过程
200+ 轮次的对话回放, 分页正常, 无慢查询
仪表盘显示: 解决率、Agent 使用率、升级率、每次对话成本
无对话数据时仪表盘显示零状态
导航在聊天、回放、仪表盘之间切换正常 -- frontend deferred to Phase 5
pytest --cov 覆盖率 >= 80%

Phase 4 测试要求

类型	测试项	文件
单元测试	回放 API (分页、404、数据转换)	`tests/test_replay.py`
单元测试	分析查询 (各指标、零状态)	`tests/test_analytics.py`
集成测试	完整回放流程 (对话 -> 回放)	`tests/test_replay.py`
E2E	选择已完成对话 -> 步骤回放正确渲染	手动验证

Phase 4 风险项

风险	严重度	缓解措施
PostgresSaver checkpoint 数据结构变化	中	在 transformer 层做版本适配, 不直接耦合内部结构
200+ 轮次查询性能	中	使用分页 + 数据库索引, 必要时增加 SQL 查询优化
分析指标定义不够精确	低	"解决率 = 成功工具调用 + 无升级" 作为初始定义, 后续加入客户满意度信号

Phase 4 交付物

分页回放 API + checkpoint -> 时间线转换
回放列表 + 详情 UI
4 个分析指标查询 (解决率、Agent 使用率、升级率、成本)
分析仪表盘 UI (含零状态)
前端路由导航
完整测试套件

Phase 5: 打磨 + Demo 准备 (第 7-8 周)

目标

错误处理加固、Demo 脚本和示例数据准备、Docker Compose 全栈部署验证、文档完善。为第一个客户演示做好准备。

前置条件

Phase 1-4 检查点全部通过

任务清单

5.1 错误处理加固 (预计 2 天)

5.1.1 审查所有 MCP 工具调用的错误处理 (超时、认证失败、网络错误)
- 文件: 全部 backend/app/agents/*.py
- 工作量: M (4 小时)
- 依赖: Phase 1-3
- 风险: 低
5.1.2 实现 MCP 错误分类 (可重试 vs. 不可重试, 指数退避策略)
- 文件: backend/app/tools/error_handler.py
- 工作量: M (4 小时)
- 依赖: 5.1.1
- 风险: 低
5.1.3 审查前端错误处理 (断线提示、服务端错误友好展示)
- 文件: frontend/src/ 各组件
- 工作量: M (3 小时)
- 依赖: Phase 1 前端
- 风险: 低
5.1.4 处理边界情况 (空消息、超长消息 10K+、快速连发消息、取消已取消的订单、WebSocket 断线 mid-stream 清理)
- 文件: backend/app/main.py, backend/app/agents/*.py, frontend/src/
- 工作量: M (6 小时)
- 依赖: Phase 1-2
- 风险: 低
- 来源: eng-review-test-plan.md 边界 case 清单
5.1.5 编写边界情况测试 (含: 取消已取消订单返回合适错误、WebSocket 断线服务端清理、快速连发无竞态、歧义无上下文时澄清提问)
- 文件: backend/tests/test_edge_cases.py
- 工作量: M (4 小时)
- 依赖: 5.1.4
- 风险: 低

5.2 Demo 准备 (预计 1.5 天)

5.2.1 创建 Demo 脚本 (预设对话流程, 覆盖: 查询、取消+批准、多轮上下文、OpenAPI 导入)
- 文件: docs/demo-script.md
- 工作量: M (3 小时)
- 依赖: Phase 1-4
- 风险: 低
5.2.2 准备示例数据 (Mock 订单数据, 预置对话用于回放演示)
- 文件: backend/fixtures/demo_data.py
- 工作量: M (3 小时)
- 依赖: 5.2.1
- 风险: 低
5.2.3 准备示例 OpenAPI 规范 (用于 Phase 3 功能演示)
- 文件: backend/fixtures/sample_openapi.yaml
- 工作量: S (1 小时)
- 依赖: Phase 3
- 风险: 低
5.2.4 录制 90 秒 Demo 视频
- 工作量: M (3 小时)
- 依赖: 5.2.1, 5.2.2, 5.2.3
- 风险: 低

5.3 全栈部署验证 (预计 1 天)

5.3.1 验证 Docker Compose 一键启动 (PostgreSQL + 后端 + 前端)
- 文件: docker-compose.yml
- 工作量: M (4 小时)
- 依赖: Phase 1-4
- 风险: 中 -- 多服务联调可能有端口/网络问题
5.3.2 验证环境变量配置文档完整性
- 文件: .env.example, docs/deployment.md
- 工作量: S (1 小时)
- 依赖: 5.3.1
- 风险: 低
5.3.3 端到端冒烟测试 (全部 6 条 E2E 关键路径)
- 工作量: M (3 小时)
- 依赖: 5.3.1
- 风险: 低

5.4 文档完善 (预计 1 天)

5.4.1 更新 README.md (快速开始、配置说明、架构图)
- 文件: README.md
- 工作量: M (3 小时)
- 依赖: Phase 1-4
- 风险: 低
5.4.2 编写 Agent 配置指南 (如何添加新 Agent、如何配置工具)
- 文件: docs/agent-config-guide.md
- 工作量: M (3 小时)
- 依赖: Phase 1-2
- 风险: 低
5.4.3 编写 OpenAPI 导入指南
- 文件: docs/openapi-import-guide.md
- 工作量: S (2 小时)
- 依赖: Phase 3
- 风险: 低
5.4.4 编写部署指南
- 文件: docs/deployment.md
- 工作量: S (2 小时)
- 依赖: 5.3.1
- 风险: 低

Phase 5 检查点标准

docker compose up 从零启动, 所有功能正常
6 条 E2E 关键路径全部通过:
1. Happy path: "订单 1042 的状态" -> 查询 -> 回答
2. 取消+批准: "取消订单 1042" -> interrupt -> 批准 -> 确认
3. 取消+拒绝: "取消订单 1042" -> interrupt -> 拒绝 -> 无操作
4. 多轮上下文: "查询 1042" 然后 "取消那个" -> 正确实体解析
5. OpenAPI 导入: 粘贴规范 URL -> 工具生成 -> 在聊天中使用
6. 对话回放: 选择已完成对话 -> 步骤回放正确渲染
Demo 视频录制完成 (90 秒)
文档完整 (README, Agent 配置, OpenAPI 导入, 部署)
pytest --cov 全项目覆盖率 >= 80%

Phase 5 测试要求

类型	测试项	文件
单元测试	边界情况 (空消息、超长消息、连发、取消已取消订单)	`tests/test_edge_cases.py`
集成测试	WebSocket 断线 mid-stream 服务端清理	`tests/test_edge_cases.py`
集成测试	快速连发消息无竞态	`tests/test_edge_cases.py`
集成测试	歧义无上下文意图 -> 澄清提问	`tests/test_edge_cases.py`
E2E	全部 6 条关键路径	手动冒烟测试

Phase 5 风险项

风险	严重度	缓解措施
Docker 多服务联调问题	中	逐步添加服务, 不要一次全部配置
Demo 演示时服务不稳定	中	准备离线录制的 Demo 视频作为备选

Phase 5 交付物

错误处理加固后的后端 + 前端
Demo 脚本 + 示例数据 + 示例 OpenAPI 规范
90 秒 Demo 视频
全栈 Docker Compose 部署 (验证通过)
完整文档集 (README, Agent 配置, OpenAPI 导入, 部署)

Phase 6: 客户接入 (第 8 周起)

目标

为第一个真实客户构建 MCP 连接器, 将框架接入客户的内部系统。这是从 Demo 到真实产品的关键一步。

来源: ceo-plan.md Phase 5 -- "Real connectors for first client's systems"

前置条件

Phase 5 检查点全部通过 (完整 Demo 可运行)
已有至少 1 个设计合作伙伴 (来自业务验证)

任务清单

6.1 客户系统对接 (工期视客户系统复杂度而定)

6.1.1 分析客户 API 系统 (Shopify Admin API / 自定义 REST / 其他)
- 工作量: M (4-8 小时)
- 依赖: 客户提供 API 文档或 OpenAPI 规范
- 风险: 中 -- 客户 API 文档质量不可控
6.1.2 构建客户专属 MCP 连接器 (或使用 Phase 3 OpenAPI 自动生成)
- 文件: backend/mcp_servers/{client_name}/
- 工作量: L (1-3 天, 视 API 复杂度)
- 依赖: 6.1.1
- 风险: 高 -- OAuth、分页、速率限制等实际 API 问题
6.1.3 配置客户专属 agents.yaml (Agent 分组、权限、人设)
- 文件: backend/agents.yaml (客户版本)
- 工作量: S (2 小时)
- 依赖: 6.1.2
- 风险: 低
6.1.4 端到端测试: 真实 API 调用 (查询真实订单、执行真实操作)
- 工作量: M (4 小时)
- 依赖: 6.1.2, 6.1.3
- 风险: 高 -- 生产数据的边界 case

6.2 生产准备 (预计 2 天)

6.2.1 实现 Auth 系统 (API key 认证 WebSocket, session 认证 Dashboard)
- 文件: backend/app/auth.py
- 工作量: M (1 天)
- 依赖: Phase 4 完成
- 风险: 中
- 来源: TODOS.md -- "Auth system: P1 before production deployment"
6.2.2 部署到云环境 (Fly.io / Railway / AWS)
- 工作量: M (4 小时)
- 依赖: 6.2.1
- 风险: 中

Phase 6 检查点标准

客户专属 MCP 连接器能调用真实 API
使用客户数据完成完整对话流程 (查询、操作、确认)
Auth 系统保护所有端点
部署到云环境, 客户可通过 URL 访问

Phase 6 风险项

风险	严重度	缓解措施
客户 API 文档质量差或缺失	高	先用 Phase 3 OpenAPI 自动发现, 人工补充缺失部分
OAuth / 速率限制等真实 API 问题	高	Phase 5 的 MCP 错误分类 (5.1.2) 已实现重试/升级策略
客户数据边界 case 超预期	中	逐步上线: 先只读操作, 验证后再开放写操作

Phase 6 交付物

客户专属 MCP 连接器
客户专属 Agent 配置
Auth 系统 (API key + session)
云端部署

并行化策略

通道	内容	模块	可并行阶段
A	后端核心 (Phase 1-2)	`backend/app/`	Phase 1-2
B	前端 UI	`frontend/`	Phase 1 与 A 并行
C	SSRF 防护工具 (独立模块)	`backend/app/openapi/ssrf.py`	Phase 1 期间可提前开发

Phase 1: A (后端) + B (前端) + C (SSRF) 三路并行
Phase 2: 依赖 Phase 1 后端完成, 串行
Phase 3: 依赖 Phase 2, 串行 (但 C 的 SSRF 已完成)
Phase 4: 不依赖 Phase 3, 可与 Phase 3 后半段并行启动
Phase 5: 依赖 Phase 1-4, 串行
Phase 6: 依赖 Phase 5 + 客户, 按客户节奏推进

全局风险登记册

编号	风险	严重度	阶段	缓解措施
R1	LangGraph supervisor 配置复杂度超预期	高	Phase 1	5 天阻塞则回退单 Agent
R2	MCP 服务器代码生成质量不稳定	高	Phase 3	先支持简单 REST, 复杂场景延后
R3	真实 OpenAPI 规范边界 case	高	Phase 3	前置校验, 不支持的特性明确提示
R4	多意图原子性不清晰	高	Phase 2	Best-effort, 部分失败升级人工
R5	interrupt/resume 状态管理	中	Phase 1	先实现最简版, 后续迭代
R6	PostgresSaver checkpoint 结构变化	中	Phase 4	transformer 层做版本适配
R7	LLM 分类准确率不够	中	Phase 3	运维审核 UI 作为安全网
R8	DNS 重绑定防护遗漏	中	Phase 3	解析后缓存 IP, 二次验证
R9	无客户验证需求	高	全局	Phase 1 完成后立即进行客户对话

验收标准总览

工程完成标准

完整框架: Chat UI + Agent Router + Context Manager 端到端运行
多 Agent 路由: 基于意图正确选择 Agent
会话上下文: Agent 正确解析跨轮次引用 ("取消那个")
人工确认: 写操作需要审批才能执行
可插拔 MCP: 新工具可通过配置添加, 无需改代码
OpenAPI 自动发现: 粘贴 URL -> 工具可用
对话回放: 逐步查看 Agent 决策过程
数据分析: 解决率、Agent 使用率、升级率、成本
90 秒 Demo 视频
全项目测试覆盖率 >= 80%

业务验证标准

Demo 完成后 2 周内, 至少与 5 位真实电商运营者对话
Demo 完成后 4 周内, 至少 1 个付费试点

范围外事项 (来自工程评审)

以下内容明确不在原型范围内:

认证/授权系统 (延迟到预生产)
多租户架构 (延迟到第一个付费客户)
CI/CD 管道 (原型阶段手动部署)
速率限制 (延迟到预生产)
Zendesk/Intercom 市场集成 (延迟到验证后)
移动端响应式 UI (仅支持桌面端 Demo)
国际化 (i18n)
计费/定价基础设施
分发管道 (手动 Docker Compose 部署)

待办事项追踪 (来自 TODOS.md)

待办	时间点	状态
工具接口决策 (MCP/CLI/API 三后端)	Phase 3 开始前	待完成 -- 见任务 3.0
Auth 系统 (API key + session)	Phase 6 任务 6.2.1	待完成
Prompt Caching	Phase 1 任务 1.4.5	待完成
Checkpointer 迁移计划	已解决 (PostgresSaver 从第一天开始)	已完成

本文档应随开发进展持续更新。每个 Phase 完成后, 勾选对应的检查点标准和任务清单。

40 KiB Raw Blame History

Smart Support -- 详细开发计划

目录

总览

Phase 1: 核心框架 (第 1-3 周)

目标

任务清单

1.1 项目初始化与基础设施 (预计 2 天)

1.2 YAML Agent 注册表 (预计 2 天)

1.3 Mock Agent 与工具 (预计 1.5 天)

1.4 LangGraph Supervisor 配置 (预计 2 天)

1.5 FastAPI WebSocket 后端 (预计 2 天)

1.6 React 聊天 UI (预计 3 天) [可并行]

Phase 1 检查点标准

Phase 1 测试要求

Phase 1 风险项

Phase 1 交付物

Phase 2: 多 Agent 路由 + 安全层 (第 3-4 周)

目标

前置条件

任务清单

2.1 Supervisor 路由增强 (预计 2 天)

2.2 Mock 折扣 Agent (预计 0.5 天)

2.3 中断超时处理 (预计 1 天)

2.4 Webhook 升级 (预计 1 天)

2.5 垂直行业模板 (预计 0.5 天)

Phase 2 检查点标准

Phase 2 测试要求

Phase 2 风险项

Phase 2 交付物

Phase 3: OpenAPI 自动发现 (第 4-6 周)

目标

前置条件

任务清单

3.0 工具接口研究 (预计 0.5 天) [来自 TODOS.md]

3.1 SSRF 防护工具 (预计 1 天) [可提前并行开发]

3.2 OpenAPI 规范解析 (预计 2 天)

3.3 LLM 辅助分类 (预计 2 天)

3.4 运维审核 UI (预计 1.5 天)

3.5 MCP 服务器生成 (预计 2 天)

3.6 异步导入流程 (预计 1 天)

Phase 3 检查点标准

Phase 3 测试要求

Phase 3 风险项

Phase 3 交付物

Phase 4: 对话回放 + 数据分析 (第 6-7 周)

目标

前置条件

任务清单

4.1 对话回放 API (预计 2 天)

4.2 回放 UI (预计 2 天)

4.3 数据分析 API (预计 2 天)

4.4 分析仪表盘 UI (预计 1.5 天)

Phase 4 检查点标准

Phase 4 测试要求

Phase 4 风险项

Phase 4 交付物

Phase 5: 打磨 + Demo 准备 (第 7-8 周)

目标

前置条件

任务清单

5.1 错误处理加固 (预计 2 天)

5.2 Demo 准备 (预计 1.5 天)

5.3 全栈部署验证 (预计 1 天)

5.4 文档完善 (预计 1 天)

Phase 5 检查点标准

Phase 5 测试要求

Phase 5 风险项

Phase 5 交付物

Phase 6: 客户接入 (第 8 周起)

目标

前置条件

任务清单

6.1 客户系统对接 (工期视客户系统复杂度而定)

6.2 生产准备 (预计 2 天)

Phase 6 检查点标准

Phase 6 风险项

Phase 6 交付物

并行化策略

全局风险登记册

40 KiB

Raw Blame History