kai/knowledge-base

Fork 0

Files

Yaojia Wang ab3263c474 vault backup: 2026-04-06 23:27:39

2026-04-06 23:27:39 +02:00

11 KiB

Raw Blame History

created, updated, type, status, deadline, tags

created

updated

type

status

deadline

Smart Support

AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作的智能客服。

目标

解决现有客服工具（Zendesk、Intercom）自动化率卡在 20-30% 的问题。这些工具能回答 FAQ，但无法执行内部系统操作。Smart Support 作为「行动层」补充，让 AI 直接调用客户的内部系统完成查订单、取消订单、发优惠券等操作。

架构

客户 → React Chat UI → FastAPI WebSocket → LangGraph Supervisor → Agent → MCP Tools → 客户内部系统

核心组件：

langgraph-supervisor v0.0.31 -- 多 Agent 编排
langchain-mcp-adapters -- MCP 工具集成
langgraph-checkpoint-postgres v3.0.5 -- 会话状态持久化
interrupt() -- 写操作人工确认（30 分钟 TTL 自动取消）

技术栈

组件	技术	版本/说明
后端	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 驱动配置
意图分类（单意图/多意图/模糊检测），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 + 安全	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

目标用户

中型电商公司（日均 500-5000 订单，5-20 名客服）的客户体验负责人。

仓库

代码：git@git.colacoder.com:kai/smart-support.git
分支：main
本地路径（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 -- 详细开发计划（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 -- 工程评审（架构决策、测试策略、失败模式）
TODOS.md -- 待办事项

快速启动

# 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

自动编排脚本

项目 scripts/ 目录下有基于 autonomous-agent-harness 模式的自动化脚本：

脚本	用途	模式
`auto-pilot.sh`	多阶段自动执行（每阶段独立 `claude -p` session）	Sequential Pipeline
`dev-sequential.sh`	单功能开发（plan → TDD → de-sloppify → verify → commit）	Sequential Pipeline
`de-sloppify.sh`	独立清理 pass（新上下文 = 无作者偏见）	De-Sloppify
`full-verify.sh`	全套质量门（测试、安全、模块独立性、代码质量）	Verification Pipeline
`pr-review-loop.sh`	自动审查 open PRs	Continuous PR Loop
`health-monitor.sh`	服务健康检查（可配 Windows Task Scheduler）	Scheduled Monitor
`phases.json`	声明式阶段定义（任务、验收标准、模式、依赖）	配置文件

大部分时候不需要外部脚本 — 在 Claude Code 内直接用：

/ecc:feature-dev "描述" — 单功能全流程
/gsd:autonomous — 全项目多阶段自动

脚本只在以下场景使用：上下文窗口不够、无人值守运行、需要 Santa Method 消除作者偏见。

CLAUDE.md 已更新：Step 2 从 /ecc:orchestrate（legacy）迁移到 /ecc:feature-dev + GSD。

已知技术债务

认证/授权系统（生产部署前）
多租户架构（第一个付费客户后）
CI/CD 流水线（原型阶段手动部署）
速率限制进程全局状态 -- 多 Worker 需 Redis
中断清理未定时调度（cleanup_expired 存在但未触发）
NoOpAnalyticsRecorder 已注册 -- PostgresAnalyticsRecorder 集成待完善
SaaS/Fintech 模板工具仅为桩（无实现）
工具生成基于字符串模板 -- 复杂场景可能需 AST

Billo Release Agent -- 另一个 AI Agent 项目

11 KiB Raw Blame History Unescape Escape