kai/smart-support
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
98331abbd5922b7f9ae228dc40e03d35db6d4a6a
smart-support/docs/DEVELOPMENT-PLAN.md
Yaojia Wang 98331abbd5 Update doc
2026-03-30 15:09:04 +02:00

39 KiB
Raw Blame History

Smart Support -- 详细开发计划

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

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

目录

  1. 总览
  2. Phase 1: 核心框架
  3. Phase 2: 多 Agent 路由 + 安全层
  4. Phase 3: OpenAPI 自动发现
  5. Phase 4: 对话回放 + 数据分析
  6. Phase 5: 打磨 + Demo 准备
  7. Phase 6: 客户接入
  8. 并行化策略
  9. 全局风险登记册
  10. 验收标准总览

总览

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 周)

目标

完善 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 正常工作
  • pytest --cov 覆盖率 >= 80% (Phase 1 + Phase 2 代码)

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 周)

目标

实现 "粘贴 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 页面 (表格展示每个端点分类, 可编辑)
    • 文件: 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 周)

目标

实现对话回放 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 使用率、升级率、每次对话成本
  • 无对话数据时仪表盘显示零状态
  • 导航在聊天、回放、仪表盘之间切换正常
  • 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 完成后, 勾选对应的检查点标准和任务清单。