ai-agent/README_ZH.md

AgentDesk

English | 简体中文

开源的 AI Agent 客服系统，支持知识库问答、人工接管、工单闭环和私有化部署。

面向需要同时处理在线咨询、知识库问答、人工协同和服务跟踪的团队。它不是把 LLM 接进聊天框，而是一套围绕客服场景设计的 AI Helpdesk 基础系统。

产品预览

客户侧在线咨询、客服工作台、知识库、模型配置和 AI Agent 编排都在同一套系统中完成。

客户侧在线咨询

客户可以在 Web 聊天页中直接发起咨询。AI Agent 会先接待，基于知识库回答问题；当用户明确要求人工介入时，会触发转人工确认流程。

客服工作台

客服工作台支持会话列表、消息处理、AI 转人工、客服回复、会话标签、关联客户和工单信息查看，适合客服日常接待使用。

知识库与 AI 配置

知识库 FAQ	AI Agent 配置

知识库用于沉淀 FAQ、文档和可检索内容；AI Agent 可以绑定模型配置、知识库、Skills 和工具能力，形成面向具体客服场景的智能客服实例。

模型配置

模型配置支持 OpenAI-compatible 接入方式，可分别配置大语言模型、向量模型和重排模型，并管理上下文、输出、超时、重试和启用状态。

为什么选择它

• AI 先接待：让 AI Agent 优先处理常见问题、标准流程和知识库问答。
• 知识约束回答：通过 RAG 和 Answerability Gate 判断知识片段是否足以回答，减少超出知识库范围的乱答。
• 自然转人工：当知识库不足、用户明确要求或流程需要人工确认时，进入人工接管。
• 会话到工单闭环：在线会话、客服接待、工单创建、状态流转和处理记录在同一套系统里完成。
• 适合二次开发：后端使用 Go，前端使用 Next.js，支持 Skills、MCP 和 OpenAI-compatible 模型接入。
• 可私有化部署：支持 SQLite / MySQL 和 Qdrant，适合本地体验、内网部署和企业自托管。

核心能力

• AI Agent 客服：AI 优先回复，支持兜底、确认、工具调用和人工协同。
• 在线会话系统：支持访客会话、消息收发、未读状态、会话分配、转接和关闭。
• 客服工作台：客服可接管会话、回复用户、转接同事、关联客户和创建工单。
• 知识库 RAG：支持知识库、文档、FAQ、切片、向量检索、检索日志和质量分析。
• Answerability Gate：判断检索内容是否足以支撑回答，不足时返回兜底提示并建议联系人工。
• 工单系统：支持从会话创建工单、分类、指派、状态流转、进展记录和闭环处理。
• 客服组织管理：支持客服档案、客服组、排班和自动分配能力。
• AI 扩展能力：支持 Skills、MCP 调试和外部工具接入。
• 多入口接入：提供管理后台、客服工作台、客户侧 Web 页面和嵌入式 SDK。

适用场景

• 官网在线客服
• SaaS 产品支持
• AI + 人工混合接待
• 企业内部服务台
• 售后、报障、投诉和运营支持
• 需要知识库问答与人工协同的客服团队

快速开始

推荐先用 Docker Compose 体验完整服务：

docker compose up -d --build

完整英文配置与排查说明见 Docker Compose Quick Start。

如需在官网或产品中嵌入客服入口，见 Web Widget Integration。

如需接入 OpenAI-compatible 模型供应商，见 Model Provider Configuration。

Compose 默认会启动：

• cs-ai-agent：应用服务，端口 8083
• mysql：MySQL 8.4，数据卷 mysql-data
• qdrant：向量数据库，数据卷 qdrant-data，端口 6333 / 6334

启动后访问：

• 管理后台：http://localhost:8083/dashboard
• 客服工作台：http://localhost:8083/dashboard/conversations
• 客户侧 Web 接入示例：http://localhost:8083/support/demo
• 客户侧聊天页：http://localhost:8083/support/chat

默认管理员账号：

• 用户名：admin
• 密码：ChangeMe123!

首次用于公网或团队环境前，请务必修改默认管理员密码，并配置独立的鉴权、会话和模型密钥。

本地开发

环境要求

• Go 1.26+
• Node.js 20+
• pnpm
• Qdrant

准备配置

cp config/config.example.yaml config/config.yaml

默认配置使用：

• SQLite：data/app.db
• Backend：http://127.0.0.1:8083
• Qdrant gRPC：127.0.0.1:6334

如果本地还没有 Qdrant，可以用 Docker 启动：

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

安装前端依赖：

cd web
pnpm install
cd ..

同时启动后端和前端开发服务：

make dev

或分别启动：

make run-go
make web-dev

开发环境默认入口：

• 管理后台：http://localhost:3000/dashboard
• 客服工作台：http://localhost:3000/dashboard/conversations
• 客户侧 Web 接入示例：http://localhost:3000/support/demo
• 客户侧聊天页：http://localhost:3000/support/chat

技术栈

• Backend：Golang + Gin + GORM + github.com/mlogclub/simple
• Frontend：Next.js 16 + React 19 + shadcn/ui + Tailwind CSS
• Database：SQLite / MySQL
• Vector DB：Qdrant
• AI：OpenAI-compatible LLM / Embedding + RAG + Skills + MCP

项目结构

.
├── cmd/                    # server / migration / generator / testdata
├── internal/
│   ├── bootstrap/          # 启动、路由、数据库和迁移初始化
│   ├── builders/           # model / 聚合结果到 response DTO 的映射
│   ├── handlers/           # dashboard / api / third HTTP handlers
│   ├── middleware/         # Gin middleware
│   ├── migration/          # 幂等数据迁移
│   ├── models/             # GORM models
│   ├── repositories/       # 数据访问层
│   ├── services/           # 业务编排和事务边界
│   ├── ai/                 # LLM / RAG / Runtime / Skills / MCP
│   └── pkg/                # config / dto / enums / httpx / utils 等基础包
├── web/                    # Next.js 前端工程
│   ├── app/dashboard/      # 管理后台与客服工作台
│   ├── app/support/        # 客户侧接入和聊天页面
│   ├── components/         # React 组件
│   ├── lib/                # API client、SDK 源码和工具函数
│   └── public/sdk/         # 构建后的嵌入式 SDK
├── config/                 # 配置文件
├── docker/                 # Docker 配置
└── docs/                   # 项目文档

常用命令

make dev            # 同时启动后端和前端开发服务
make run            # 构建前端 SPA 后启动后端
make run-go         # 启动后端，自动确保 SPA 已构建
make web-dev        # 启动前端开发服务
make build          # 构建前端 SPA 和当前平台 Go 二进制
make build-linux    # 构建 linux/amd64 二进制
make release        # 构建常用平台二进制
make web-build-spa  # 构建 web 静态 SPA 和嵌入式 SDK
make test           # 运行 Go 测试，自动确保 SPA 已构建
make check          # 运行 Go 测试、前端 typecheck 和 lint
make generator      # 执行代码生成
make enums          # 生成前端枚举
make migration      # 执行 migration
make testdata       # 初始化演示/测试数据

AI Agent 工作流

flowchart TD
    A[用户发起咨询<br/>Web 客服入口 / Open API] --> B[创建或匹配会话]
    B --> C[客户发送消息]
    C --> D[触发 AI Reply Runtime]
    D --> E[加载会话历史 / AI 配置]
    E --> F[按绑定知识库执行检索]
    F --> G{知识片段是否足以回答?}
    G -- 否 --> Z[返回知识库兜底提示<br/>并建议联系人工客服]
    G -- 是 --> H[准备 Skills / MCP Tools]
    H --> I[将可信知识上下文交给 Agent]
    I --> J{直接回复?}
    J -- 是 --> K[LLM 基于知识生成回复并返回用户]
    J -- 否 --> N{是否调用 Graph / MCP Tool?}
    N -- 是 --> O[执行 Skill / Graph / MCP Tool]
    O --> P{需要用户确认?}
    P -- 否 --> I
    P -- 是 --> Q[向用户发起确认]
    Q --> R{用户确认结果}
    R -- 确认转人工 --> S[会话转人工并进入待接入池]
    S --> T[自动分配或人工分配]
    T --> U[客服工作台接管]
    U --> V{是否需要工单跟踪?}
    V -- 是 --> W[创建或关联工单]
    V -- 否 --> X[人工继续处理]
    W --> X
    X --> Y[问题解决并关闭]
    R -- 确认建单 --> AA[从当前会话创建工单]
    AA --> I
    R -- 取消 --> K
    N -- 否 --> K

业务闭环

flowchart LR
    A[客户咨询] --> B[AI Agent 接待]
    B --> C{知识库可回答?}
    C -- 是 --> D[AI 基于可信知识回复]
    C -- 否 --> E[兜底提示 / 建议人工]
    D --> F{是否需要人工?}
    E --> G[人工接管]
    F -- 否 --> H[会话结束或沉淀数据]
    F -- 是 --> G
    G --> I[客服工作台处理]
    I --> J{是否需要跟踪?}
    J -- 是 --> K[创建 / 关联工单]
    J -- 否 --> L[直接解决]
    K --> M[工单流转与进展记录]
    M --> N[处理完成]
    L --> N

Docker 镜像

如果只需要构建应用镜像，可以自行准备 MySQL 和 Qdrant，并挂载配置文件：

docker build -t cs-ai-agent .
docker run --rm -p 8083:8083 \
  -v $(pwd)/docker/cs-ai-agent.yaml:/app/config/config.yaml:ro \
  -v cs-ai-agent-data:/app/data \
  cs-ai-agent

Compose 使用 docker/cs-ai-agent.yaml 作为容器内配置，应用会通过 Docker 内部服务名访问 mysql 和 qdrant。

开源定位

AgentDesk 适合作为以下方向的开源基础项目：

• AI 客服系统
• AI Helpdesk / AI Support Platform
• RAG 可回答性判定 + Human Handoff 的落地样板
• 面向企业场景的 AI Agent 应用框架

如果你在寻找一个以 AI Agent 为中心，而不是仅仅把 LLM 嵌进聊天框的客服系统，这个项目就是为此设计的。