# 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) 的设计和实现。