first commit
This commit is contained in:
@@ -0,0 +1,305 @@
|
||||
# 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) 的设计和实现。
|
||||
Reference in New Issue
Block a user