vault backup: 2026-04-06 16:23:54

2 - Projects/Smart Support.md

@@ -1,7 +1,8 @@
 ---
 created: 2026-03-29
+updated: 2026-04-06
 type: project
-status: active
+status: completed
 deadline: ""
 tags:
   - ai-agent
@@ -14,6 +15,8 @@ tags:
   - customer-support
   - websocket
   - postgresql
+  - react
+  - docker
 ---
 
 # Smart Support
@@ -31,35 +34,56 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 ```
 
 核心组件：
-- **langgraph-supervisor** v1.1 - 多 Agent 编排
-- **langchain-mcp-adapters** - MCP 工具集成
-- **PostgresSaver** - 会话状态持久化
-- **interrupt()** - 写操作人工确认
+- **langgraph-supervisor** v0.0.31 -- 多 Agent 编排
+- **langchain-mcp-adapters** -- MCP 工具集成
+- **langgraph-checkpoint-postgres** v3.0.5 -- 会话状态持久化
+- **interrupt()** -- 写操作人工确认（30 分钟 TTL 自动取消）
 
 ## 技术栈
 
-- Python 3.11+, FastAPI, LangGraph v1.1
-- React（前端）, PostgreSQL（Docker Compose）
-- Claude Sonnet 4.6（可切换 LLM）
+| 组件 | 技术 | 版本/说明 |
+|------|------|-----------|
+| 后端 | Python 3.11+ / FastAPI | Web 框架 + WebSocket |
+| Agent 编排 | LangGraph 1.x | Supervisor 模式多 Agent 路由 |
+| 检查点 | langgraph-checkpoint-postgres | PostgreSQL 持久化 |
+| MCP | langchain-mcp-adapters | MultiServerMCPClient |
+| 数据库 | PostgreSQL 16 | Docker Compose 部署 |
+| LLM | Claude Sonnet 4.6（默认） | 支持 Anthropic/OpenAI/Google 切换 |
+| 前端 | React 19 + TypeScript + Vite 6 | React Router 7.x |
+| 测试 | pytest 8.3+ / vitest 4.1.2 | 后端 516 测试 92%+ 覆盖率 |
+| 部署 | Docker Compose | PostgreSQL + FastAPI + nginx |
+| 代码质量 | ruff 0.9+ | Python linting + formatting |
 
 ## 核心特性
 
 - 多 Agent 协作，YAML 驱动配置
-- OpenAPI 规范自动生成 MCP 服务器 + Agent 配置（LLM 辅助分类 + 人工审核）
-- 写操作人工确认（30 分钟超时自动取消）
-- 对话回放 + 数据分析仪表盘
-- Webhook 升级通知
+- 意图分类（单意图/多意图/模糊检测），LLM 结构化输出
+- OpenAPI 规范自动生成 @tool 函数 + Agent YAML（LLM 辅助分类 + 人工审核）
+- 写操作人工确认（interrupt()，30 分钟 TTL 超时自动取消）
+- 对话回放 + 数据分析仪表盘（解决率、Agent 使用率、升级率、成本）
+- Webhook 升级通知（指数退避重试）
 - 垂直行业模板（电商、SaaS、金融科技）
+- SSRF 防护（私有 IP 拦截、DNS 重绑定防御、重定向链验证）
+- WebSocket 流式输出 + 速率限制（10 msg/10s per thread）
+- 错误分类 + 自动重试（ErrorCategory 枚举，可重试错误指数退避）
 
 ## 开发阶段
 
 | 阶段 | 周期 | 内容 | 状态 | 详情 |
 |------|------|------|------|------|
 | Phase 1 | 第 1-3 周 | 核心框架 | COMPLETED (2026-03-30) | [[Smart Support/Phase 1 - 核心框架]] |
-| Phase 2 | 第 3-4 周 | 多 Agent + 安全 | 未开始 | [[Smart Support/Phase 2 - 多 Agent + 安全]] |
-| Phase 3 | 第 4-6 周 | OpenAPI 自动发现 | 未开始 | [[Smart Support/Phase 3 - OpenAPI 自动发现]] |
-| Phase 4 | 第 6-7 周 | 分析 + 回放 | 未开始 | [[Smart Support/Phase 4 - 分析 + 回放]] |
-| Phase 5 | 缓冲周 | 打磨 + 演示 | 未开始 | [[Smart Support/Phase 5 - 打磨 + 演示]] |
+| Phase 2 | 第 3-4 周 | 多 Agent + 安全 | COMPLETED (2026-03-30) | [[Smart Support/Phase 2 - 多 Agent + 安全]] |
+| Phase 3 | 第 4-6 周 | OpenAPI 自动发现 | COMPLETED (2026-03-30) | [[Smart Support/Phase 3 - OpenAPI 自动发现]] |
+| Phase 4 | 第 6-7 周 | 分析 + 回放 | COMPLETED (2026-03-31) | [[Smart Support/Phase 4 - 分析 + 回放]] |
+| Phase 5 | 缓冲周 | 打磨 + 演示 | COMPLETED (2026-03-31) | [[Smart Support/Phase 5 - 打磨 + 演示]] |
+
+## 项目数据
+
+- 后端测试：516 个（单元 ~400 + 集成 ~7 + E2E ~3）
+- 前端测试：~23 个（vitest + happy-dom）
+- 代码覆盖率：92.88%
+- 应用版本：v0.5.0
+- Git 最新提交：`af53111` refactor: fix architectural issues
 
 ## 目标用户
 
@@ -67,43 +91,137 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 
 ## 仓库
 
-- 代码：`ssh://git@git.colacoder.com:2200/kai/smart-support.git`
+- 代码：`git@git.colacoder.com:kai/smart-support.git`
 - 分支：`main`
-- 本地路径：`/Users/yiukai/Documents/git/smart-support`
+- 本地路径（Windows）：`C:\Users\yaoji\git\ColaCoder\smart-support`
+
+## WebSocket 协议
+
+客户端 -> 服务器：
+- `{"type": "message", "thread_id": "...", "content": "..."}`
+- `{"type": "interrupt_response", "thread_id": "...", "interrupt_id": "...", "approved": true/false}`
+
+服务器 -> 客户端：
+- `{"type": "token", "thread_id": "...", "content": "..."}` -- 流式 token
+- `{"type": "interrupt", ...}` -- 人工确认提示（含 TTL）
+- `{"type": "tool_call", ...}` / `{"type": "tool_result", ...}` -- 工具调用
+- `{"type": "message_complete", ...}` -- 消息完成
+- `{"type": "error", ...}` -- 错误
+
+## REST API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| WS | `/ws` | WebSocket 聊天 |
+| GET | `/api/health` | 健康检查 |
+| GET | `/api/conversations` | 对话列表（分页） |
+| GET | `/api/replay/{thread_id}` | 回放时间线（分页，默认 20 步） |
+| GET | `/api/analytics?range=7d` | 分析摘要（1d/7d/30d/90d） |
+| POST | `/api/openapi/import` | 开始 OpenAPI 导入 |
+| GET | `/api/openapi/jobs/{id}` | 导入任务状态 |
+| PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | 修改端点分类 |
+| POST | `/api/openapi/jobs/{id}/approve` | 审核通过，生成工具 |
+
+## 数据库表
+
+| 表 | 用途 |
+|----|----|
+| checkpoints | LangGraph 状态快照（自动管理） |
+| checkpoint_writes | 检查点写入记录 |
+| conversations | 对话元数据（状态、解决类型、使用 Agent、Token、成本） |
+| interrupts | 人工确认记录（pending/approved/rejected/expired） |
+| analytics_events | 分析事件流（事件类型、Agent、工具、Token、成本、耗时） |
+
+## 架构决策（ADR）
+
+| ADR | 决策 | 理由 |
+|-----|------|------|
+| ADR-001 | LangGraph Supervisor 多 Agent | 内置编排，无需自定义 |
+| ADR-002 | PostgresSaver 从第一天起 | Phase 4 分析需要可查询的检查点数据 |
+| ADR-003 | WebSocket + astream_events() | 双向低延迟流式 |
+| ADR-004 | YAML 声明式 Agent 注册 | 非开发者可配置 Agent |
+| ADR-005 | LangGraph interrupt() HITL | 框架内置，深度集成检查点 |
+| ADR-006 | OpenAPI: 解析 -> LLM 分类 -> 人工审核 | 平衡自动化与安全 |
+| ADR-007 | SSRF 独立模块 | 可复用，可独立测试 |
+
+## 安全架构
+
+- **L1 输入验证**：消息格式、长度限制（10k 字符）、Agent YAML 启动验证
+- **L2 SSRF 防护**：私有 IP 拦截、DNS 重绑定防御、重定向链验证
+- **L3 HITL**：写操作 interrupt()、30 分钟 TTL 自动取消
+- **L4 权限隔离**：Agent 级工具集、读 Agent 无法调写工具
+- **L5 审计追踪**：全操作记录、PostgreSQL 存储、回放 API
 
 ## 完整文档（已同步）
 
-- [[Smart Support/Architecture]] - 系统架构文档（12 章，含 ADR、数据库设计、API 协议）
-- [[Smart Support/Development Plan]] - 详细开发计划（6 Phase，任务清单 + 检查点 + 风险）
-- [[Smart Support/Phase 1 Dev Log]] - Phase 1 开发日志（88% 覆盖率，82 个单元测试）
+- [[Smart Support/Architecture]] -- 系统架构文档（12 章，含 ADR、数据库设计、API 协议）
+- [[Smart Support/Development Plan]] -- 详细开发计划（5 Phase，任务清单 + 检查点 + 风险）
+- [[Smart Support/Phase 1 Dev Log]] -- Phase 1 开发日志（88% 覆盖率，82 个单元测试）
+- [[Smart Support/Phase 2 Dev Log]] -- Phase 2 开发日志（90% 覆盖率，153 个测试）
+- [[Smart Support/Phase 3 Dev Log]] -- Phase 3 开发日志（93% 覆盖率，322 个测试）
+- [[Smart Support/Phase 4 Dev Log]] -- Phase 4 开发日志（93% 覆盖率，399 个测试）
+- [[Smart Support/Phase 5 Dev Log]] -- Phase 5 开发日志（93% 覆盖率，449 个测试）
+
+## 项目模块结构
+
+```
+backend/app/
+  main.py              -- FastAPI 入口 (v0.5.0)
+  config.py            -- Pydantic Settings
+  db.py                -- AsyncPostgreSQL + AsyncPostgresSaver
+  llm.py               -- LLM 提供商工厂（Anthropic/OpenAI/Google）
+  graph.py             -- LangGraph Supervisor 构建
+  ws_handler.py        -- WebSocket 消息分发 + 流式 + 速率限制
+  registry.py          -- YAML Agent 注册表 + 模板支持
+  intent.py            -- LLM 意图分类器
+  session_manager.py   -- Session TTL（30m 滑动窗口）
+  interrupt_manager.py -- 中断 TTL 追踪 + 自动取消
+  escalation.py        -- Webhook 升级（指数退避）
+  conversation_tracker.py -- 对话生命周期追踪
+  callbacks.py         -- Token 用量回调
+  agents/              -- Agent 定义（order_lookup, order_actions, discount, fallback）
+  openapi/             -- OpenAPI 解析 + 分类 + 生成（ssrf, fetcher, parser, classifier, generator）
+  replay/              -- 回放模型 + 转换器 + API
+  analytics/           -- 分析模型 + 事件记录 + 查询 + API
+  tools/               -- 错误处理（ErrorCategory, classify_error, with_retry）
+```
 
 ## 计划文档
 
 项目根目录下：
-- `design-doc.md` - 设计文档（问题定义、约束、方案选择）
-- `ceo-plan.md` - CEO 计划（产品愿景、范围决策）
-- `eng-review-plan.md` - 工程评审（架构决策、测试策略、失败模式）
-- `eng-review-test-plan.md` - 测试计划（测试路径、边界情况、E2E 流程）
-- `TODOS.md` - 待办事项
+- `design-doc.md` -- 设计文档（问题定义、约束、方案选择）
+- `ceo-plan.md` -- CEO 计划（产品愿景、范围决策）
+- `eng-review-plan.md` -- 工程评审（架构决策、测试策略、失败模式）
+- `TODOS.md` -- 待办事项
 
-## 关键决策
+## 快速启动
 
-- 用 LangGraph 内置能力（supervisor、checkpointer、interrupt），不自己造轮子
-- PostgresSaver 从第一天起使用，为后期分析和回放打基础
-- OpenAPI 导入生成完整 MCP 服务器（非简单 @tool 函数），LLM 辅助端点分类
-- 路由错误时有 fallback agent 兜底
-- 解决率定义：成功工具调用 + 未升级
-- Token 用量从第一天起记录
+```bash
+# 1. 克隆 + 配置
+git clone <repo-url> && cd smart-support
+cp .env.example .env && cp backend/.env.example backend/.env
+# 编辑 .env 设置 ANTHROPIC_API_KEY
 
-## 待解决
+# 2. 启动
+docker compose up -d
+# PostgreSQL: localhost:5433 | Backend: localhost:8000 | Frontend: localhost:80
+
+# 3. 测试
+cd backend && pytest --cov=app --cov-report=term-missing
+cd ../frontend && npm test
+```
+
+## 已知技术债务
 
 - [ ] 认证/授权系统（生产部署前）
 - [ ] 多租户架构（第一个付费客户后）
 - [ ] CI/CD 流水线（原型阶段手动部署）
-- [ ] 路由准确率评估数据集
-- [ ] 过期中断处理（Phase 2 实现）
-- [ ] SSRF 防护模块（Phase 3 前构建）
+- [ ] 速率限制进程全局状态 -- 多 Worker 需 Redis
+- [ ] 中断清理未定时调度（cleanup_expired 存在但未触发）
+- [ ] NoOpAnalyticsRecorder 已注册 -- PostgresAnalyticsRecorder 集成待完善
+- [ ] SaaS/Fintech 模板工具仅为桩（无实现）
+- [ ] 工具生成基于字符串模板 -- 复杂场景可能需 AST
 
 ## Related
 
-- [[Billo Release Agent]] - 另一个 AI Agent 项目
+- [[Billo Release Agent]] -- 另一个 AI Agent 项目