基于 LLM 的人机协同客服框架 | LLM-Powered Human-in-the-Loop Customer Service Framework
English | 简体中文
Enterprise-Support-Agent 是一个创新的企业级智能客服框架，采用**人机协同（Human-in-the-Loop）**架构设计。它不是简单地让 AI 完全自动化客服工作，而是将 AI 的智能响应能力与人工的专业判断完美结合，特别适合需要访问敏感数据或执行关键操作的企业场景。
在传统的 AI 客服系统中，要么完全依赖 AI（可能导致安全风险），要么完全依赖人工（效率低下）。本框架提供了第三种方案：Agent 主动索取数据，人工仅执行。
用户提问 → AI 智能分析 → 需要查询数据？
├─ 否 → AI 直接回复用户
└─ 是 → AI 生成 SQL/操作指令 → 挂起请求
↓
人工执行并回填结果
↓
AI 自动生成最终回复
关键优势：
- 🔒 数据安全：敏感数据库访问权限保留在人工手中，AI 无直接访问权限
- ⚡ 高效响应：常见问题由 AI 即时回答，无需人工介入
- 🎯 精准查询：AI 生成精确的 SQL 查询语句或操作指令，人工只需执行和返回结果
- 🤖 Agent 主导：AI 主动判断何时需要数据，生成具体的查询指令，而非被动等待审核
- 🔄 灵活扩展：可根据企业安全策略调整人机协同的边界
这解决了大模型无法直接连接内网核心数据库的安全矛盾。
- 🤖 多模型支持：支持 Gemini、Qwen、DeepSeek、Kimi、Doubao 等主流 LLM
- 💬 即时通讯集成：基于 NoneBot2，支持 QQ、微信等 IM 平台
- 📚 知识库管理：本地知识库 + 动态学习机制
- 🔐 安全过滤：内置敏感信息检测和 SQL 注入防护
- 📊 会话管理：智能会话上下文管理，支持多用户并发
- 🎨 消息缓冲：自动合并连续消息，提升用户体验
- 🔍 数据库查询：可选的数据库集成，支持人工辅助查询
- 📝 持续学习：记录人工纠正和经验，不断优化回复质量
┌─────────────────────────────────────────────────────────────┐
│ 用户层 │
│ (QQ群、企业微信、Slack等) │
└────────────────────┬────────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────────┐
│ 消息接入层 │
│ (NoneBot2 + OneBot) │
│ • 消息接收与发送 │
│ • 消息缓冲与合并 │
│ • 图片处理 │
└────────────────────┬────────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────────┐
│ 安全过滤层 │
│ • 敏感信息检测 │
│ • SQL注入防护 │
│ • 批量数据请求拦截 │
└────────────────────┬────────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────────┐
│ AI 智能体层 │
│ ┌──────────────────────────────┐ │
│ │ 响应模式决策引擎 │ │
│ │ • 直接回复模式 │ │
│ │ • 人工查询模式 │ │
│ │ • 边界界定模式 │ │
│ └──────────┬───────────────────┘ │
│ │ │
│ ┌──────────▼───────────────────┐ │
│ │ 知识库检索 │ │
│ │ • 本地知识库 │ │
│ │ • 学习知识库 │ │
│ │ • 人工经验库 │ │
│ └──────────┬───────────────────┘ │
│ │ │
│ ┌──────────▼───────────────────┐ │
│ │ LLM 推理 │ │
│ │ • 多模型支持 │ │
│ │ • 上下文管理 │ │
│ │ • 流式输出 │ │
│ └──────────┬───────────────────┘ │
└────────────────────┼────────────────────────────────────────┘
│
┌────────────┴────────────┐
│ │
┌───────▼────────┐ ┌────────▼──────────┐
│ 直接回复用户 │ │ 生成查询指令 │
│ │ │ (发送给人工) │
└────────────────┘ └────────┬──────────┘
│
┌────────▼──────────┐
│ 人工执行查询 │
│ • 数据库查询 │
│ • 后台操作 │
│ • 结果返回 │
└────────┬──────────┘
│
┌────────▼──────────┐
│ AI 整合结果 │
│ 回复用户 │
└───────────────────┘
以下时序图展示了 Agent 主导的数据检索流程：
sequenceDiagram
participant User as 用户
participant Agent as AI 智能体
participant Human as 人工客服
participant DB as 业务数据库
User->>Agent: 帮我查下订单 PO20260101 的状态
Agent->>Agent: 分析意图 (需要查询数据库？)
Agent->>Agent: 生成 SQL 查询指令
Note over Agent: 【挂起请求】<br/>生成内部指令
Agent-->>Human: 【内部指令】<br/>SQL: SELECT order_id, status, updated_at<br/>FROM orders WHERE order_id = 'PO20260101'<br/>后台路径: 订单管理 → 订单查询
Agent-->>User: 稍等，正在为您查询订单信息...
Note right of Human: 人工确认权限<br/>并执行查询
Human->>DB: 执行 SQL 查询
DB-->>Human: 返回结果:<br/>{order_id: "PO20260101",<br/>status: "已发货",<br/>updated_at: "2026-01-02 10:30"}
Human-->>Agent: 回填查询结果 (JSON)
Agent->>Agent: 整合数据生成回复
Agent->>User: 您的订单 PO20260101 当前状态为"已发货"，<br/>更新时间：2026-01-02 10:30
Note over User,Agent: 完整闭环完成
关键特点：
- Agent 主动生成具体的 SQL 语句，而非模糊的"帮我查一下"
- 人工只需执行指令并回填结果，无需理解业务逻辑
- Agent 自动将结构化数据转换为用户友好的自然语言回复
- Python 3.11+
- 支持的 LLM API（至少配置一个）：
- Gemini API
- 阿里云通义千问 API
- 字节跳动豆包 API
- Moonshot Kimi API
- DeepSeek API
- （可选）即时通讯平台：QQ、微信等
- （可选）企业数据库访问权限
💡 Mock 模式说明：本项目内置了 Mock 数据库模式。Agent 会生成真实的 SQL 语句（如 Oracle SQL），Mock 引擎会拦截并模拟返回虚拟数据，无需配置真实数据库即可体验完整的人机协同流程。这使得项目可以立即运行和演示，同时也是生产环境的安全实践。
- 克隆项目
git clone https://github.com/LouisUltra/Enterprise-Support-Agent.git
cd enterprise-support-agent- 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# 或
.venv\Scripts\activate # Windows- 安装依赖
pip install -e .- 配置环境变量
复制示例配置文件并编辑：
cp .env.example .env编辑 .env 文件，至少配置一个 LLM 模型：
# 选择当前使用的模型
ACTIVE_MODEL=qwen
# 配置通义千问（示例）
QWEN_API_KEY=your_qwen_api_key_here
QWEN_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-vl-max
# 配置 IM 平台（可选）
ONEBOT_WS_URLS=["ws://127.0.0.1:3001"]
QQ_GROUPS=[123456789]
ADMIN_QQ=987654321- 准备知识库
将 knowledge_base_examples/ 中的示例文件复制到实际知识库目录，并根据您的业务定制：
# 示例文件仅供参考，请根据实际业务定制
cp -r knowledge_base_examples/* your_knowledge_base/- 运行测试
pytest tests/ -v- 启动服务
python -m enterprise_support_agent在 .env 文件中配置您选择的 LLM 模型：
# 当前激活的模型
ACTIVE_MODEL=qwen
# Qwen 配置
QWEN_API_KEY=sk-xxxxx
QWEN_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-vl-max支持的模型：
- Gemini: Google 的多模态模型
- Qwen: 阿里云通义千问，支持视觉理解
- DeepSeek: 高性价比的开源模型
- Kimi: Moonshot 的长文本模型
- Doubao: 字节跳动的豆包模型
知识库文件放在 knowledge_base_examples/ 目录（可在配置中修改）：
knowledge_base_examples/
├── 01_Database_Query_Guide.md # 数据库查询指南
├── 02_Platform_Operations.md # 平台操作手册
├── 03_API_Integration.md # API 集成文档
├── 04_Common_Issues.md # 常见问题解答
└── 05_Security_Guidelines.md # 安全规范
定制建议：
- 使用您实际的业务术语替换示例中的通用术语
- 添加您的数据库表结构和常用查询
- 补充您的 API 文档和错误码说明
- 记录您的业务流程和操作规范
系统提示词位于 prompts/system_prompt.md，定义了 AI 的行为模式：
- 响应模式：直接回复 vs 人工查询
- 知识库使用：如何检索和引用知识库
- 安全边界：哪些请求需要拒绝或转人工
定制要点：
- 调整响应语气和风格
- 定义您的业务边界
- 添加特定场景的处理规则
用户: "API 返回 401 错误是什么意思？"
↓
AI: 检索知识库 → 找到答案
↓
AI: "401 错误表示认证失败。请检查：
1. API Key 是否正确
2. API Key 是否已过期
3. 请求头是否包含正确的 Authorization"
用户: "帮我查一下订单 PO20260101 的状态"
↓
AI: 分析 → 需要查询数据库
↓
AI: 生成内部指令（发送给人工客服）:
【内部查询请求】
1. 意图：查询订单状态
2. SQL: SELECT order_id, status, updated_at
FROM orders WHERE order_id = 'PO20260101'
3. 后台路径：订单管理 → 订单查询
4. 回复策略：根据状态告知用户
↓
人工: 执行 SQL → 返回结果
↓
AI: 整合结果回复用户:
"您的订单 PO20260101 当前状态为'已发货'，
更新时间：2026-01-02 10:30"
用户: "什么时候能收到货款？"
↓
AI: 判断 → 属于财务/业务问题
↓
AI: "这属于财务结算范畴，技术客服无法查询。
建议您联系财务部门或查看官网公告。"
如果您的安全策略允许，可以配置数据库连接：
# 企业数据库配置
ENTERPRISE_DB_HOST=your-db-host
ENTERPRISE_DB_PORT=1521
ENTERPRISE_DB_USER=readonly_user
ENTERPRISE_DB_PASSWORD=your_password
ENTERPRISE_DB_NAME=your_database
# 是否自动执行 SQL（谨慎使用）
AUTO_EXECUTE_SQL=false
DB_MAX_ROWS=100安全建议：
- 使用只读账号
- 限制查询结果行数
- 建议保持
AUTO_EXECUTE_SQL=false，由人工审核后执行
系统会自动记录以下信息用于持续改进：
- 人工纠正 (
data/corrections.md)：记录 AI 回复错误及正确答案 - 人工经验 (
data/human_experience.md)：记录人工处理的特殊案例 - 核心规则 (
data/redlines.md)：手动维护的关键规则
这些文件会在后续对话中被引用，帮助 AI 不断改进。
- 会话超时：默认 30 分钟无活动自动清除
- 上下文保留：保留最近 20 条消息作为上下文
- 多用户隔离：不同用户的会话完全独立
配置项：
SESSION_TIMEOUT_MINUTES=30
MESSAGE_BUFFER_SECONDS=45enterprise-support-agent/
├── src/enterprise_support_agent/
│ ├── bot/ # 机器人核心
│ │ ├── agent.py # AI 智能体
│ │ └── message_buffer.py # 消息缓冲
│ ├── context/ # 会话管理
│ │ └── session.py # 会话存储
│ ├── database/ # 数据库集成
│ │ └── enterprise_query.py
│ ├── llm/ # LLM 接口
│ │ ├── base.py # 基础接口
│ │ ├── gemini.py # Gemini 实现
│ │ ├── qwen.py # Qwen 实现
│ │ └── ...
│ ├── security/ # 安全模块
│ │ └── filters.py # 安全过滤器
│ └── config.py # 配置管理
├── tests/ # 测试用例
├── knowledge_base_examples/ # 知识库示例
├── prompts/ # 系统提示词
├── data/ # 运行时数据
└── pyproject.toml # 项目配置
- 在
src/enterprise_support_agent/llm/创建新文件 - 继承
BaseLLM类 - 实现
generate()和generate_stream()方法 - 在
config.py中添加配置项
示例：
from .base import BaseLLM, Message
class YourLLM(BaseLLM):
def __init__(self, api_key: str, api_base: str, model: str):
self.api_key = api_key
self.api_base = api_base
self.model = model
async def generate(self, messages: list[Message]) -> str:
# 实现您的 LLM 调用逻辑
pass
async def generate_stream(self, messages: list[Message]):
# 实现流式输出
pass编辑 src/enterprise_support_agent/security/filters.py：
BLOCKED_PATTERNS = [
# 添加您的拦截规则
(r"your_pattern", "reason"),
]
WARNING_PATTERNS = [
# 添加您的警告规则
(r"your_pattern", "reason"),
]# 运行所有测试
pytest tests/ -v
# 运行特定测试
pytest tests/test_security.py -v
# 查看覆盖率
pytest tests/ --cov=enterprise_support_agent --cov-report=html- 构建镜像
docker build -t enterprise-support-agent:latest .- 运行容器
docker run -d \
--name support-agent \
-v $(pwd)/.env:/app/.env \
-v $(pwd)/data:/app/data \
-v $(pwd)/knowledge_base:/app/knowledge_base \
enterprise-support-agent:latestdocker-compose up -d- 使用进程管理器（如 systemd、supervisor）
- 配置日志轮转
- 设置监控告警
- 定期备份数据目录
- 使用反向代理（如 Nginx）
我们欢迎所有形式的贡献！
- Fork 本项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
- 🐛 报告 Bug
- ✨ 提出新功能
- 📝 改进文档
- 🎨 优化代码
- 🌐 添加翻译
- 🧪 编写测试
本项目采用 MIT 协议开源 - 详见 LICENSE 文件
- NoneBot2 - 优秀的 Python 异步机器人框架
- OneBot - 统一的聊天机器人应用接口标准
- 所有 LLM 提供商：Google Gemini、阿里云通义千问、DeepSeek、Moonshot、字节跳动豆包
- 项目主页：https://github.com/LouisUltra/Enterprise-Support-Agent
- 问题反馈：https://github.com/LouisUltra/Enterprise-Support-Agent/issues
- 讨论区：https://github.com/LouisUltra/Enterprise-Support-Agent/discussions
- 支持更多 LLM 模型（Claude、GPT-4 等）
- Web 管理界面
- 多语言支持（英语、日语等）
- 语音消息支持
- 知识库可视化编辑器
- 性能监控面板
- 插件系统
如果这个项目对您有帮助，请给我们一个 ⭐️ Star！