306 lines
5.5 KiB
Markdown
306 lines
5.5 KiB
Markdown
# SentClaw
|
||
|
||
> 🤖 基于 Python + Vue3 的 AI 智能助手系统，支持多 Agent 编排、Skills、Memory、MCP 协议与多渠道接入
|
||
|
||
## 项目简介
|
||
|
||
SentClaw 是 openclaw/mateclaw 的克隆项目，旨在提供一个功能完整、易于扩展的个人 AI 助手系统。
|
||
|
||
### 核心功能
|
||
|
||
- **多 Agent 编排** — ReAct、Plan-and-Execute、StateGraph
|
||
- **工具与技能系统** — 内置工具 + MCP 协议 + ClawHub 市场
|
||
- **多层记忆** — 短期记忆 + 对话后提取 + 记忆整合
|
||
- **多渠道接入** — Web、钉钉、飞书、Telegram、Discord
|
||
- **多厂商模型** — 支持 20+ LLM 厂商
|
||
|
||
## 技术栈
|
||
|
||
### 后端
|
||
- **框架**: Flask 3.0
|
||
- **数据库**: MySQL 8.0 + Redis 7
|
||
- **ORM**: SQLAlchemy 2.0
|
||
- **迁移**: Alembic
|
||
- **认证**: Flask-JWT-Extended
|
||
|
||
### 前端
|
||
- **框架**: Vue 3 + TypeScript
|
||
- **构建工具**: Vite 5
|
||
- **UI 组件**: Element Plus
|
||
- **状态管理**: Pinia
|
||
- **路由**: Vue Router
|
||
|
||
### 桌面应用
|
||
- **框架**: Electron + electron-vite
|
||
- **渲染进程**: Vue 3（复用 Web 前端）
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Docker & Docker Compose
|
||
- Node.js 18+
|
||
- Python 3.9+
|
||
|
||
### 一键初始化
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone <repository-url>
|
||
cd SentClaw
|
||
|
||
# 运行初始化脚本
|
||
./scripts/setup.sh
|
||
```
|
||
|
||
### 手动安装
|
||
|
||
#### 1. 启动 Docker 服务
|
||
|
||
```bash
|
||
# 复制环境变量
|
||
cp .env.example .env
|
||
|
||
# 启动 MySQL 和 Redis
|
||
docker-compose up -d
|
||
```
|
||
|
||
#### 2. 后端设置
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 创建虚拟环境
|
||
python3 -m venv venv
|
||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 初始化数据库
|
||
flask db upgrade
|
||
|
||
# 启动服务
|
||
python run.py
|
||
```
|
||
|
||
#### 3. 前端设置
|
||
|
||
```bash
|
||
cd web
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
#### 4. 桌面应用（可选）
|
||
|
||
```bash
|
||
cd desktop
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发模式
|
||
npm run dev
|
||
```
|
||
|
||
### 访问应用
|
||
|
||
- **Web 前端**: http://localhost:5173
|
||
- **后端 API**: http://localhost:5000
|
||
- **默认账号**: admin / admin123
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
SentClaw/
|
||
├── backend/ # Python 后端
|
||
│ ├── app/
|
||
│ │ ├── api/ # API 路由
|
||
│ │ ├── models/ # 数据库模型
|
||
│ │ ├── schemas/ # 序列化/验证
|
||
│ │ ├── services/ # 业务逻辑
|
||
│ │ ├── agents/ # Agent 引擎
|
||
│ │ ├── tools/ # 工具系统
|
||
│ │ ├── skills/ # 技能管理
|
||
│ │ ├── channels/ # 渠道适配器
|
||
│ │ ├── workspace/# 工作空间
|
||
│ │ ├── memory/ # 记忆系统
|
||
│ │ ├── llm/ # LLM 接入
|
||
│ │ └── core/ # 核心配置
|
||
│ ├── alembic/ # 数据库迁移
|
||
│ ├── tests/ # 测试
|
||
│ └── run.py # 应用入口
|
||
├── web/ # Vue3 Web 前端
|
||
│ ├── src/
|
||
│ │ ├── api/ # API 调用
|
||
│ │ ├── views/ # 页面
|
||
│ │ ├── stores/ # Pinia stores
|
||
│ │ └── router/ # 路由配置
|
||
│ └── package.json
|
||
├── desktop/ # Electron 桌面应用
|
||
│ └── src/
|
||
│ ├── main/ # 主进程
|
||
│ ├── preload/ # 预加载脚本
|
||
│ └── renderer/ # 渲染进程
|
||
├── scripts/ # 脚本
|
||
│ └── setup.sh # 初始化脚本
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
└── README.md
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 后端开发
|
||
|
||
```bash
|
||
cd backend
|
||
source venv/bin/activate
|
||
|
||
# 代码格式化
|
||
black app/
|
||
|
||
# 代码检查
|
||
flake8 app/
|
||
|
||
# 类型检查
|
||
mypy app/
|
||
|
||
# 运行测试
|
||
pytest
|
||
```
|
||
|
||
### 前端开发
|
||
|
||
```bash
|
||
cd web
|
||
|
||
# 代码检查
|
||
npm run lint
|
||
|
||
# 代码格式化
|
||
npm run format
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
```
|
||
|
||
### 桌面应用开发
|
||
|
||
```bash
|
||
cd desktop
|
||
|
||
# 开发模式
|
||
npm run dev
|
||
|
||
# 打包应用
|
||
npm run dist
|
||
```
|
||
|
||
## 数据库迁移
|
||
|
||
```bash
|
||
cd backend
|
||
source venv/bin/activate
|
||
|
||
# 创建新迁移
|
||
flask db migrate -m "描述信息"
|
||
|
||
# 应用迁移
|
||
flask db upgrade
|
||
|
||
# 回滚迁移
|
||
flask db downgrade
|
||
```
|
||
|
||
## Docker 命令
|
||
|
||
```bash
|
||
# 启动服务
|
||
docker-compose up -d
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 进入 MySQL 容器
|
||
docker-compose exec mysql mysql -u sentclaw -p
|
||
|
||
# 进入 Redis 容器
|
||
docker-compose exec redis redis-cli -a redis123
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
主要配置文件：`.env`
|
||
|
||
```bash
|
||
# MySQL 配置
|
||
MYSQL_ROOT_PASSWORD=root123
|
||
MYSQL_DATABASE=sentclaw
|
||
MYSQL_USER=sentclaw
|
||
MYSQL_PASSWORD=sentclaw123
|
||
|
||
# Redis 配置
|
||
REDIS_PASSWORD=redis123
|
||
|
||
# 后端配置
|
||
FLASK_ENV=development
|
||
FLASK_DEBUG=True
|
||
FLASK_PORT=5000
|
||
SECRET_KEY=your-secret-key
|
||
|
||
# 数据库连接
|
||
DATABASE_URL=mysql+pymysql://sentclaw:sentclaw123@localhost:3306/sentclaw
|
||
|
||
# Redis 连接
|
||
REDIS_URL=redis://:redis123@localhost:6379/0
|
||
|
||
# LLM API Keys（根据需要填写）
|
||
DASHSCOPE_API_KEY=
|
||
OPENAI_API_KEY=
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 后端无法连接 MySQL
|
||
|
||
确保 Docker 服务已启动：
|
||
```bash
|
||
docker-compose ps
|
||
```
|
||
|
||
检查 .env 中的数据库配置是否正确。
|
||
|
||
### 前端无法连接后端 API
|
||
|
||
检查后端是否已启动（http://localhost:5000），并查看 Vite 配置中的代理设置。
|
||
|
||
### 数据库迁移失败
|
||
|
||
删除现有数据库并重新初始化：
|
||
```bash
|
||
docker-compose down -v
|
||
docker-compose up -d
|
||
flask db upgrade
|
||
```
|
||
|
||
## 贡献指南
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 许可证
|
||
|
||
Apache License 2.0
|
||
|
||
## 致谢
|
||
|
||
本项目参考了 [mateclaw](https://gitee.com/matevip_admin/mateclaw) 的设计和实现。
|