kai/knowledge-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault: update Smart Support project -- v0.6.0, API v1, auth, structlog, architecture patterns

Browse Source
This commit is contained in:
Yaojia Wang
2026-04-06 23:56:42 +02:00
parent 998df02055
commit 949863408c
1 changed files with 73 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
2 - Projects/Smart Support.md
View File

@@ -1,8 +1,8 @@
--- ---
created: 2026-03-29 created: 2026-03-29
updated: 2026-04-06 updated: 2026-04-07
type: project type: project
status: completed status: active
deadline: "" deadline: ""
tags: tags:
- ai-agent - ai-agent
@@ -48,11 +48,14 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
| 检查点 | langgraph-checkpoint-postgres | PostgreSQL 持久化 | | 检查点 | langgraph-checkpoint-postgres | PostgreSQL 持久化 |
| MCP | langchain-mcp-adapters | MultiServerMCPClient | | MCP | langchain-mcp-adapters | MultiServerMCPClient |
| 数据库 | PostgreSQL 16 | Docker Compose 部署 | | 数据库 | PostgreSQL 16 | Docker Compose 部署 |
| LLM | Claude Sonnet 4.6（默认） | 支持 Anthropic/OpenAI/Google 切换 | | DB 迁移 | Alembic | 自动运行 migrations |
| LLM | Claude Sonnet 4.6（默认） | 支持 Anthropic/OpenAI/Azure/Google 切换 |
| 前端 | React 19 + TypeScript + Vite 6 | React Router 7.x | | 前端 | React 19 + TypeScript + Vite 6 | React Router 7.x |
| 测试 | pytest 8.3+ / vitest 4.1.2 | 后端 516 测试 92%+ 覆盖率 | | 测试 | pytest 8.3+ / vitest 4.1.2 | 后端 516+ 测试 94%+ 覆盖率 |
| 部署 | Docker Compose | PostgreSQL + FastAPI + nginx | | 部署 | Docker Compose | PostgreSQL + FastAPI + nginx |
| 日志 | structlog | 结构化日志（console/json 模式） |
| 代码质量 | ruff 0.9+ | Python linting + formatting | | 代码质量 | ruff 0.9+ | Python linting + formatting |
| 认证 | API Key | `X-API-Key` header / `?token=` for WS |
## 核心特性 ## 核心特性
@@ -76,14 +79,15 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
| Phase 3 | 第 4-6 周 | OpenAPI 自动发现 | COMPLETED (2026-03-30) | [[Smart Support/Phase 3 - OpenAPI 自动发现]] | | 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 4 | 第 6-7 周 | 分析 + 回放 | COMPLETED (2026-03-31) | [[Smart Support/Phase 4 - 分析 + 回放]] |
| Phase 5 | 缓冲周 | 打磨 + 演示 | COMPLETED (2026-03-31) | [[Smart Support/Phase 5 - 打磨 + 演示]] | | Phase 5 | 缓冲周 | 打磨 + 演示 | COMPLETED (2026-03-31) | [[Smart Support/Phase 5 - 打磨 + 演示]] |
| Post | 2026-04 | 架构修复 + 工程改进 | 进行中 | API v1 版本化、structlog、Alembic、认证、GraphContext/WebSocketContext |
## 项目数据 ## 项目数据
- 后端测试：516 个（单元 ~400 + 集成 ~7 + E2E ~3） - 后端测试：516+ 个（单元 ~439 + 集成 ~51 + E2E ~26）
- 前端测试：~23 个（vitest + happy-dom） - 前端测试：~23 个（vitest + happy-dom）
- 代码覆盖率：92.88% - 代码覆盖率：~94%
- 应用版本：v0.5.0 - 应用版本：v0.6.0
- Git 最新提交：`af53111` refactor: fix architectural issues - Git 最新提交：`f069943` refactor: engineering improvements -- API versioning, structured logging, Alembic, error standardization
## 目标用户 ## 目标用户
@@ -99,28 +103,36 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
客户端 -> 服务器： 客户端 -> 服务器：
- `{"type": "message", "thread_id": "...", "content": "..."}` - `{"type": "message", "thread_id": "...", "content": "..."}`
- `{"type": "interrupt_response", "thread_id": "...", "interrupt_id": "...", "approved": true/false}` - `{"type": "interrupt_response", "thread_id": "...", "approved": true/false}`
服务器 -> 客户端： 服务器 -> 客户端（8 种消息类型）：
- `{"type": "token", "thread_id": "...", "content": "..."}` -- 流式 token - `{"type": "token", "agent": "...", "content": "..."}` -- 流式 token
- `{"type": "interrupt", ...}` -- 人工确认提示（含 TTL） - `{"type": "interrupt", "thread_id": "...", "action": "...", "params": {...}}` -- 人工确认提示
- `{"type": "tool_call", ...}` / `{"type": "tool_result", ...}` -- 工具调用 - `{"type": "clarification", "thread_id": "...", "message": "..."}` -- 意图模糊，请求澄清
- `{"type": "message_complete", ...}` -- 消息完成 - `{"type": "interrupt_expired", "thread_id": "...", "action": "...", "message": "..."}` -- 审批超时
- `{"type": "error", ...}` -- 错误 - `{"type": "tool_call", "agent": "...", "tool": "...", "args": {...}}` -- 工具调用
- `{"type": "tool_result", "agent": "...", "tool": "...", "result": ...}` -- 工具返回
- `{"type": "message_complete", "thread_id": "..."}` -- 消息完成
- `{"type": "error", "message": "..."}` -- 错误
WebSocket 连接需 `?token=<ADMIN_API_KEY>` 认证（未配置 key 时跳过）。
## REST API ## REST API
| 方法 | 路径 | 说明 | 所有端点使用 `/api/v1/` 前缀。管理端点需 `X-API-Key` header（`ADMIN_API_KEY` 未配置时跳过认证）。
|------|------|------|
| WS | `/ws` | WebSocket 聊天 | | 方法 | 路径 | 认证 | 说明 |
| GET | `/api/health` | 健康检查 | |------|------|------|------|
| GET | `/api/conversations` | 对话列表（分页） | | WS | `/ws` | Token | WebSocket 聊天（`?token=<key>`） |
| GET | `/api/replay/{thread_id}` | 回放时间线（分页，默认 20 步） | | GET | `/api/v1/health` | 无 | 健康检查 |
| GET | `/api/analytics?range=7d` | 分析摘要（1d/7d/30d/90d） | | GET | `/api/v1/conversations` | API Key | 对话列表（分页） |
| POST | `/api/openapi/import` | 开始 OpenAPI 导入 | | GET | `/api/v1/replay/{thread_id}` | API Key | 回放时间线（分页） |
| GET | `/api/openapi/jobs/{id}` | 导入任务状态 | | GET | `/api/v1/analytics?range=7d` | API Key | 分析摘要 |
| PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | 修改端点分类 | | POST | `/api/v1/openapi/import` | API Key | 开始 OpenAPI 导入 |
| POST | `/api/openapi/jobs/{id}/approve` | 审核通过，生成工具 | | GET | `/api/v1/openapi/jobs/{id}` | API Key | 导入任务状态 |
| GET | `/api/v1/openapi/jobs/{id}/classifications` | API Key | 获取端点分类 |
| PUT | `/api/v1/openapi/jobs/{id}/classifications/{idx}` | API Key | 修改端点分类 |
| POST | `/api/v1/openapi/jobs/{id}/approve` | API Key | 审核通过，生成工具代码 + Agent YAML |
## 数据库表 ## 数据库表
@@ -129,9 +141,12 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
| checkpoints | LangGraph 状态快照（自动管理） | | checkpoints | LangGraph 状态快照（自动管理） |
| checkpoint_writes | 检查点写入记录 | | checkpoint_writes | 检查点写入记录 |
| conversations | 对话元数据（状态、解决类型、使用 Agent、Token、成本） | | conversations | 对话元数据（状态、解决类型、使用 Agent、Token、成本） |
| interrupts | 人工确认记录（pending/approved/rejected/expired） | | active_interrupts | 人工确认记录（interrupt_id, action, params, resolved_at） |
| sessions | 会话状态持久化（last_activity, has_pending_interrupt），供 PgSessionManager 使用 |
| analytics_events | 分析事件流（事件类型、Agent、工具、Token、成本、耗时） | | analytics_events | 分析事件流（事件类型、Agent、工具、Token、成本、耗时） |
数据库迁移通过 Alembic 管理，应用启动时自动执行 `run_alembic_migrations()`。
## 架构决策（ADR） ## 架构决策（ADR）
| ADR | 决策 | 理由 | | ADR | 决策 | 理由 |
@@ -166,26 +181,39 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
``` ```
backend/app/ backend/app/
main.py -- FastAPI 入口 (v0.5.0) main.py -- FastAPI 入口 (v0.6.0), 全局异常处理, 中断清理循环
config.py -- Pydantic Settings config.py -- Pydantic Settings（含 admin_api_key, log_format）
db.py -- AsyncPostgreSQL + AsyncPostgresSaver db.py -- AsyncPostgreSQL + AsyncPostgresSaver + Alembic runner
llm.py -- LLM 提供商工厂（Anthropic/OpenAI/Google） llm.py -- LLM 提供商工厂（Anthropic/OpenAI/Azure/Google）
graph.py -- LangGraph Supervisor 构建 graph.py -- LangGraph Supervisor 构建，返回 GraphContext
graph_context.py -- GraphContext: 图 + 分类器 + 注册表的类型化封装
ws_handler.py -- WebSocket 消息分发 + 流式 + 速率限制 ws_handler.py -- WebSocket 消息分发 + 流式 + 速率限制
ws_context.py -- WebSocketContext: WS 处理依赖打包
auth.py -- API Key 认证中间件（X-API-Key / ?token= for WS）
api_utils.py -- 共享 envelope() 响应格式
logging_config.py -- structlog 配置（console/json）
registry.py -- YAML Agent 注册表 + 模板支持 registry.py -- YAML Agent 注册表 + 模板支持
intent.py -- LLM 意图分类器 intent.py -- LLM 意图分类器
session_manager.py -- Session TTL（30m 滑动窗口） session_manager.py -- Session TTL（30m 滑动窗口）+ PgSessionManager
interrupt_manager.py -- 中断 TTL 追踪 + 自动取消 interrupt_manager.py -- 中断 TTL 追踪 + 自动取消 + PgInterruptManager
escalation.py -- Webhook 升级（指数退避） escalation.py -- Webhook 升级（指数退避）
conversation_tracker.py -- 对话生命周期追踪 conversation_tracker.py -- 对话生命周期追踪
callbacks.py -- Token 用量回调 callbacks.py -- Token 用量回调
safety.py -- 确认策略规则 + MCP 错误分类
agents/ -- Agent 定义（order_lookup, order_actions, discount, fallback） agents/ -- Agent 定义（order_lookup, order_actions, discount, fallback）
openapi/ -- OpenAPI 解析 + 分类 + 生成（ssrf, fetcher, parser, classifier, generator） openapi/ -- OpenAPI 解析 + 分类 + 生成（ssrf, fetcher, parser, classifier, generator, review_api）
replay/ -- 回放模型 + 转换器 + API replay/ -- 回放模型 + 转换器 + API
analytics/ -- 分析模型 + 事件记录 + 查询 + API analytics/ -- 分析模型 + 事件记录 + 查询 + API
tools/ -- 错误处理（ErrorCategory, classify_error, with_retry）
``` ```
### 架构模式
- **Protocol 接口**：所有跨模块边界使用 Protocol（SessionManagerProtocol, InterruptManagerProtocol 等）
- **Frozen dataclasses**：GraphContext, WebSocketContext, SessionState, InterruptRecord 等全部不可变
- **Composition Root**：main.py lifespan() 统一组装所有依赖
- **Envelope 响应**：`{"success": bool, "data": T, "error": str | null}` 统一格式
- **双实现状态管理**：内存版（开发）+ PostgreSQL 版（生产多 Worker）
## 计划文档 ## 计划文档
项目根目录下： 项目根目录下：
@@ -235,12 +263,18 @@ cd ../frontend && npm test
## 已知技术债务 ## 已知技术债务
- [ ] 认证/授权系统（生产部署前） - [x] ~~认证/授权系统~~ -- 已实现 API Key 认证（`auth.py`，`ADMIN_API_KEY`）
- [x] ~~中断清理未定时调度~~ -- 已实现 `_interrupt_cleanup_loop` 后台任务（60s 间隔）
- [x] ~~猴子补丁~~ -- 已替换为 GraphContext 类型化封装
- [x] ~~dispatch_message 参数膨胀~~ -- 已替换为 WebSocketContext
- [x] ~~_envelope 重复定义~~ -- 已提取到 api_utils.py
- [x] ~~前端缺失消息类型~~ -- 已添加 clarification/interrupt_expired/tool_result 处理
- [ ] 多租户架构（第一个付费客户后） - [ ] 多租户架构（第一个付费客户后）
- [ ] CI/CD 流水线（原型阶段手动部署） - [ ] CI/CD 流水线（原型阶段手动部署）
- [ ] 速率限制进程全局状态 -- 多 Worker 需 Redis - [ ] 速率限制进程全局状态 -- 多 Worker 需 Redis
- [ ] 中断清理未定时调度（cleanup_expired 存在但未触发） - [ ] 生产环境切换到 PgSessionManager/PgInterruptManager
- [ ] NoOpAnalyticsRecorder 已注册 -- PostgresAnalyticsRecorder 集成待完善 - [ ] OpenAPI approve 后的工具尚未运行时注入到 _TOOL_MAP（仅生成代码 + YAML）
- [ ] SSRF DNS 重绑定 TOCTOU 窗口（实践中利用难度大）
- [ ] SaaS/Fintech 模板工具仅为桩（无实现） - [ ] SaaS/Fintech 模板工具仅为桩（无实现）
- [ ] 工具生成基于字符串模板 -- 复杂场景可能需 AST - [ ] 工具生成基于字符串模板 -- 复杂场景可能需 AST