Sentra Agent 是一个功能完整、高度模块化的 AI 智能对话机器人框架，专为构建生产级对话 AI 应用而设计。它整合了多个强大的子系统，提供从消息适配、工具调用、知识检索到拟人化交互的完整解决方案。
- 高度模块化 - 每个功能独立封装，按需组合使用
- 平台无关 - 支持多种即时通讯平台（QQ、微信等）
- 工具增强 - 内置 80+ 工具，支持文件处理、网络爬取、数据分析等
- 知识驱动 - 基于 Neo4j 的知识图谱和向量数据库
- 拟人化交互 - 智能消息合并、自然发送间隔、情感感知回复
- 高性能 - Redis 缓存、并发控制、流式输出
- 可观测性 - 完整的日志系统、性能监控、调试工具
- 消息合并 CD - 等待用户发完再回复（默认 5 秒）
- 智能回复判断 - 使用 OpenAI tools 确保 100% 准确判断
- 并发控制 - 一次只处理一个对话，更拟人
- 发送间隔 - 模拟真人打字速度和思考时间
- 回复策略 - 智能决定是否使用回复功能
- 失败优雅跳过 - AI 生成失败时自然跳过，不卡住
- 全局历史记录 - 每个会话保留最近 100 条对话
- 工具任务历史 - 记录近期工具调用总结（最近 15 条）
- 消息队列 - 智能累积和处理未回复消息
- 对话引用 - 自动引用和关联历史消息
- 独立判断模型 - 使用 gpt-4o-mini 等快速模型
- OpenAI Tools - 100% 返回结构化 JSON
- 多维度评估 - 置信度、理由、上下文分析
- 成本优化 - 判断和回复分离，节省 89% 成本
基于 Model Context Protocol (MCP) 的强大工具系统，支持 80+ 内置工具。
用户请求 → 智能规划 → 工具选择 → 并行执行 → 结果汇总 → 生成回复
- 智能规划 - 自动分解任务为可执行步骤
- 工具丰富 - 80+ 内置工具，涵盖各种场景
- 并行执行 - 支持工具并发调用，提升效率
- 流式输出 - 实时反馈执行进度和结果
- Redis 集成 - 缓存、指标监控、执行历史
文档处理
- PDF、Word、Excel、PPT 解析和生成
- Markdown、CSV、JSON、XML 转换
- 文本提取、格式转换、内容分析
网络工具
- 网页爬取（Puppeteer + Readability）
- API 调用（GET、POST、GraphQL）
- 搜索引擎集成
- RSS 订阅解析
数据操作
- Redis 读写操作
- Neo4j 图数据库查询
- SQL 数据库操作
- 向量数据库检索
多媒体
- 图片分析（OCR、物体识别、情感分析）
- 图片生成和编辑
- 视频信息提取
- 音频处理
时间和日期
- 自然语言时间解析（中英文）
- 时区转换
- 日期计算
- 定时任务管理
实用工具
- 代码执行（安全沙箱）
- 数学计算
- 单位转换
- 加密解密
- 正则表达式测试
基于 Neo4j 和向量数据库的多模态知识检索系统。
- 文本知识库 - 向量化存储，语义搜索
- 图像知识库 - 图片特征提取和相似度检索
- 知识图谱 - Neo4j 存储实体关系
- 混合检索 - 向量 + 关键词 + 图谱联合检索
- 情感分析 - 图片和文本情感识别
- 向量化: OpenAI Embeddings (text-embedding-3-small)
- 图数据库: Neo4j 5.x
- 缓存: Redis + NodeCache
- 分词: Segment (中文) + Natural (英文)
统一的消息适配层，支持多种即时通讯平台。
- QQ: NapCat 适配器（OneBotV11 协议）
- 微信: 企业微信、个人微信适配
- 其他: 可扩展的适配器接口
- 消息收发统一接口
- 文件上传下载
- 群组和好友管理
- 事件监听和处理
- WebSocket 长连接
为 AI 添加情感感知和表达能力。
- 情感识别 - 识别文本和图片中的情感
- 情感表达 - 根据情感选择合适的回复风格
- 情感分析 - 多维度情感评分
- 表情推荐 - 智能推荐合适的表情符号
集中化的提示词模板管理系统。
- 模板库 - 预设各种场景的提示词
- 变量替换 - 动态参数注入
- 阶段提示词 - 为不同执行阶段定制提示
- A/B 测试 - 提示词效果对比
- Node.js ≥ 18.0.0
- Redis ≥ 6.0（推荐 7.x）
- Neo4j ≥ 5.0（用于知识图谱）
- Docker - 用于容器化部署
- PM2 - 用于进程管理
git clone https://github.com/JustForSO/Sentra-Agent.git
cd sentra-agent# 安装主项目依赖
npm install
# 安装子模块依赖
cd sentra-mcp && npm install && cd ..
cd sentra-rag && npm install && cd ..# 使用 Docker
docker run -d --name redis -p 6379:6379 redis:7-alpine
# 或使用本地安装
redis-server# 使用 Docker
docker run -d \
--name neo4j \
-p 7474:7474 \
-p 7687:7687 \
-e NEO4J_AUTH=neo4j/your_password \
neo4j:5-community
# 访问 http://localhost:7474 确认启动成功复制示例配置：
cp .env.example .env
cp test/.env.example test/.env编辑 test/.env:
# ==================== API 配置 ====================
API_BASE_URL=https://api.openai.com/v1
API_KEY=your-openai-api-key
# 回复模型（主要模型）
MODEL_NAME=gpt-4o
# 判断模型（便宜快速）
JUDGE_MODEL=gpt-4o-mini
# ==================== WebSocket 配置 ====================
WS_URL=ws://localhost:6702
# ==================== Redis 配置 ====================
REDIS_HOST=localhost
REDIS_PORT=6379
# ==================== Neo4j 配置 ====================
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
# ==================== 机器人配置 ====================
BOT_NAME=失语
BOT_ALIASES=失语症,小失语
# ==================== 拟人化配置 ====================
ENABLE_MESSAGE_MERGE=true
MESSAGE_MERGE_DELAY=5000
REPLY_CONCURRENCY=1
REPLY_COOLDOWN=2000参考 sentra-adapter/napcat 文档配置 NapCat。
npm test┌─────────────────────────────────────────────────────────┐
│ Sentra Agent 框架 │
└─────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Adapter │ │ MCP │ │ RAG │
│ 适配层 │ │ 工具系统 │ │ 知识检索 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
│ QQ/微信等 │ │ 80+ Tools │ │ Neo4j + │
│ 平台消息 │ │ Redis集成 │ │ Vectors │
└───────────┘ └───────────┘ └───────────┘
│ │ │
└───────────────────┴───────────────────┘
│
┌────────▼────────┐
│ 智能对话引擎 │
│ • 消息合并 │
│ • 并发控制 │
│ • 历史管理 │
│ • 智能判断 │
└─────────────────┘
1. 接收消息
↓
2. Adapter 解析 → 标准化格式
↓
3. 消息合并 → 等待用户发完（5秒 CD）
↓
4. 智能判断 → 是否需要回复？
↓ 需要
5. 记录历史 → 全局历史 + 工具历史
↓
6. 构建上下文 → System + 历史 + 当前消息
↓
7. MCP 规划 → 分解任务 → 选择工具
↓
8. RAG 检索 → 相关知识（如需要）
↓
9. 工具执行 → 并行调用 → 获取结果
↓
10. 生成回复 → AI 生成最终答案
↓
11. 拟人发送 → 分段 + 间隔 + 回复策略
↓
12. 记录反馈 → 工具总结 + 对话历史
传统模式（不判断）:
100 条群聊消息 × gpt-4o = $0.625/天
智能判断模式:
判断: 100 × gpt-4o-mini = $0.0075
回复: 10 × gpt-4o = $0.0625
总计: $0.07/天
节省: 89% 成本！
- 工具执行结果缓存
- 向量检索缓存
- 知识图谱查询缓存
- 一次处理一个对话
- 避免过度并发
- 降低 API 调用频率
- 流式输出 - 实时反馈执行进度
- 工具并行 - 多个工具同时执行
- 预加载 - 常用数据提前加载
- 懒加载 - 按需加载大型模块
sentra-agent/
├── agent.js # 核心 Agent 类
├── package.json # 主项目配置
├── .env # 环境变量
│
├── test/ # 测试和主要运行环境
│ ├── smart-agent-test.js # 主程序入口
│ ├── .env # 独立配置
│ ├── .env.example # 配置模板
│ ├── 1.txt # System Prompt
│ ├── README.md # 测试文档
│ └── *.md # 各功能文档
│
├── sentra-mcp/ # 🛠️ MCP 工具框架
│ ├── src/
│ │ ├── sdk/ # SDK 接口
│ │ ├── mcp/ # MCP 服务器/客户端
│ │ ├── tools/ # 80+ 内置工具
│ │ └── redis/ # Redis 集成
│ └── package.json
│
├── sentra-rag/ # 🧠 知识检索系统
│ ├── src/
│ │ ├── sdk/ # RAG SDK
│ │ ├── services/ # 核心服务
│ │ │ ├── embedding.js # 向量化
│ │ │ ├── neo4j.js # 图数据库
│ │ │ └── vector.js # 向量检索
│ │ └── storage/ # 数据存储
│ └── package.json
│
├── sentra-adapter/ # 🔌 平台适配器
│ ├── napcat/ # QQ 适配器
│ │ ├── config.json # NapCat 配置
│ │ └── README.md # 使用文档
│ ├── wechat/ # 微信适配器
│ └── llonebot/ # LLOneBot 适配器
│
├── sentra-emo/ # 🎭 情感系统
│ ├── emotion-detector.js # 情感识别
│ └── emotion-expresser.js # 情感表达
│
├── sentra-prompts/ # 📝 提示词管理
│ ├── templates/ # 提示词模板
│ └── manager.js # 模板管理器
│
├── src/ # 核心功能模块
│ ├── config.js # 配置管理
│ ├── agent.js # Agent 实现
│ ├── token-counter.js # Token 计算
│ └── utils.js # 工具函数
│
├── examples/ # 示例代码
│ ├── basic-chat.js # 基础对话
│ ├── tool-usage.js # 工具使用
│ └── rag-search.js # 知识检索
│
└── docs/ # 文档
├── API.md # API 文档
├── TOOLS.md # 工具列表
└── DEPLOYMENT.md # 部署指南
在 sentra-mcp/src/tools/ 创建新工具：
export default {
name: 'my_custom_tool',
description: '工具描述',
inputSchema: {
type: 'object',
properties: {
param1: { type: 'string', description: '参数1' }
},
required: ['param1']
},
async execute(args) {
// 工具逻辑
return { result: 'success' };
}
};实现标准适配器接口：
class CustomAdapter {
async connect() { /* 连接逻辑 */ }
async sendMessage(msg) { /* 发送消息 */ }
async onMessage(callback) { /* 接收消息 */ }
}添加自定义知识源：
import SentraRAG from 'sentra-rag';
const rag = new SentraRAG();
await rag.init();
// 添加文本知识
await rag.addText('知识内容', { source: 'custom' });
// 添加图片知识
await rag.addImage('/path/to/image.jpg', { tag: 'product' });# 检查 Redis 是否运行
redis-cli ping
# 应该返回 PONG# 访问 Neo4j 浏览器
# http://localhost:7474
# 检查用户名密码是否正确# 确认 NapCat 已启动
# 检查端口 6702 是否被占用
netstat -ano | findstr 6702- 检查 API_KEY 是否正确
- 确认网络可以访问 OpenAI API
- 查看 API 额度是否充足
启用详细日志：
# test/.env
TEST_MODE=true
LOG_LEVEL=debuglogs/
├── app.log # 应用日志
├── error.log # 错误日志
├── tool.log # 工具调用日志
└── performance.log # 性能日志
查看执行统计：
redis-cli
> KEYS sentra:exec:*
> GET sentra:exec:stats查看缓存：
> KEYS sentra:cache:*
> TTL sentra:cache:some_keydocker build -t sentra-agent .version: '3.8'
services:
redis:
image: redis:7-alpine
ports:
- "6379:6379"
neo4j:
image: neo4j:5-community
ports:
- "7474:7474"
- "7687:7687"
environment:
- NEO4J_AUTH=neo4j/password
sentra-agent:
build: .
depends_on:
- redis
- neo4j
environment:
- REDIS_HOST=redis
- NEO4J_URI=bolt://neo4j:7687
volumes:
- ./test/.env:/app/test/.envdocker-compose up -d# 安装 PM2
npm install -g pm2
# 启动应用
pm2 start test/smart-agent-test.js --name sentra-agent
# 查看状态
pm2 status
# 查看日志
pm2 logs sentra-agent
# 重启
pm2 restart sentra-agent我们欢迎所有形式的贡献！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
- Bug 修复 - 修复已知问题
- 新功能 - 添加新特性
- 文档 - 改进文档
- 代码优化 - 重构和性能优化
- 测试 - 添加测试用例
- 工具 - 新增工具或改进现有工具
本项目采用 MIT License 开源协议。
- 所有贡献者和用户的支持
- 开源社区的无私分享
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: support@sentra.ai
如果这个项目对你有帮助，请给我们一个 Star！
Made with ❤️ by Sentra Team