180 lines
4.5 KiB
Markdown
180 lines
4.5 KiB
Markdown
# 项目结构
|
||
|
||
**技术栈:**
|
||
- 后端: Python + MySQL + Redis（参考 mateclaw-server 的 Spring Boot 架构）
|
||
- 前端: Electron（参考 mateclaw-desktop）
|
||
- Web 页面: Vite + Vue3（参考 mateclaw-ui）
|
||
- 目标: openclaw/mateclaw 的克隆项目
|
||
|
||
**参考项目架构（基于 mateclaw）:**
|
||
```
|
||
SentClaw/
|
||
├── backend/ # Python 后端（替换 Spring Boot）
|
||
│ ├── app/
|
||
│ │ ├── api/ # API 路由
|
||
│ │ ├── models/ # SQLAlchemy 数据库模型
|
||
│ │ ├── schemas/ # Marshmallow 序列化/验证
|
||
│ │ ├── services/ # 业务逻辑层
|
||
│ │ ├── agents/ # Agent 引擎
|
||
│ │ ├── tools/ # 工具系统 + MCP 适配器
|
||
│ │ ├── skills/ # 技能管理
|
||
│ │ ├── channels/ # 渠道适配器
|
||
│ │ ├── workspace/# 工作空间和文件管理
|
||
│ │ ├── memory/ # 记忆系统
|
||
│ │ ├── llm/ # LLM 多厂商接入
|
||
│ │ └── core/ # 核心配置（config.py）
|
||
│ ├── alembic/ # 数据库迁移
|
||
│ ├── tests/ # 测试
|
||
│ ├── run.py # 应用入口
|
||
│ └── Dockerfile
|
||
├── web/ # Vite + Vue3 Web 前端
|
||
│ ├── src/
|
||
│ │ ├── api/ # API 调用封装
|
||
│ │ ├── views/ # 页面组件
|
||
│ │ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── router/ # Vue Router 配置
|
||
│ │ └── types/ # TypeScript 类型定义
|
||
│ └── package.json
|
||
├── desktop/ # Electron 桌面应用
|
||
│ └── src/
|
||
│ ├── main/ # Electron 主进程
|
||
│ ├── preload/ # 预加载脚本
|
||
│ └── renderer/ # 渲染进程（Vue3）
|
||
└── scripts/ # 脚本
|
||
└── setup.sh # 一键初始化脚本
|
||
```
|
||
|
||
**核心模块:**
|
||
- Agent 引擎：ReAct、Plan-and-Execute、StateGraph
|
||
- 工具系统：内置工具 + MCP 协议
|
||
- 技能管理：技能包 + ClawHub 市场
|
||
- 记忆系统：短期记忆 + 对话后提取 + 记忆整合
|
||
- 多渠道接入：Web、钉钉、飞书、Telegram、Discord 等
|
||
- 多厂商模型：20+ LLM 厂商支持
|
||
|
||
## 开发命令
|
||
|
||
### 快速初始化
|
||
|
||
```bash
|
||
# 一键初始化所有环境
|
||
./scripts/setup.sh
|
||
```
|
||
|
||
### Docker 服务
|
||
|
||
```bash
|
||
# 启动 MySQL + Redis
|
||
docker-compose up -d
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
```
|
||
|
||
### 后端开发
|
||
|
||
```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 # 运行在 http://localhost:5000
|
||
|
||
# 代码格式化
|
||
black app/
|
||
|
||
# 代码检查
|
||
flake8 app/
|
||
|
||
# 类型检查
|
||
mypy app/
|
||
|
||
# 运行测试
|
||
pytest
|
||
```
|
||
|
||
### 前端开发
|
||
|
||
```bash
|
||
cd web
|
||
|
||
# 安装依赖（首次）
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev # 运行在 http://localhost:5173
|
||
|
||
# 代码检查
|
||
npm run lint
|
||
|
||
# 代码格式化
|
||
npm run format
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
```
|
||
|
||
### 桌面应用开发
|
||
|
||
```bash
|
||
cd desktop
|
||
|
||
# 安装依赖（首次）
|
||
npm install
|
||
|
||
# 启动开发模式
|
||
npm run dev
|
||
|
||
# 打包应用
|
||
npm run dist
|
||
```
|
||
|
||
## 开发服务器启动顺序
|
||
|
||
1. **启动 Docker 服务**（MySQL + Redis）
|
||
2. **初始化后端**（虚拟环境、依赖、数据库迁移）
|
||
3. **启动后端服务**（python run.py）
|
||
4. **启动前端服务**（npm run dev，新终端）
|
||
5. **启动桌面应用**（可选，npm run dev，新终端）
|
||
|
||
## 包边界和入口点
|
||
|
||
- **后端入口**: `backend/run.py` → Flask 应用工厂 `app/__init__.py:create_app()`
|
||
- **前端入口**: `web/src/main.ts` → Vue 根组件 `App.vue`
|
||
- **桌面应用入口**: `desktop/src/main/index.ts` → Electron 主进程
|
||
|
||
## 配置文件
|
||
|
||
- **环境变量**: `.env`（从 `.env.example` 复制）
|
||
- **后端配置**: `backend/app/config.py`
|
||
- **前端配置**: `web/vite.config.ts`
|
||
- **桌面应用配置**: `desktop/electron.vite.config.ts`
|
||
|
||
## 数据库
|
||
|
||
- **数据库**: MySQL 8.0
|
||
- **ORM**: SQLAlchemy
|
||
- **迁移工具**: Alembic
|
||
- **初始化脚本**: `scripts/init-db.sql`
|
||
- **默认账号**: admin / admin123
|
||
|
||
## 注意事项
|
||
|
||
1. 确保 Docker 服务在启动后端之前已运行
|
||
2. 前端通过 Vite 代理访问后端 API（/api → http://localhost:5000）
|
||
3. 修改后端模型后需要运行 `flask db migrate` 和 `flask db upgrade`
|
||
4. 前端和后端都需要各自安装依赖
|
||
5. 首次运行需要初始化数据库（`flask db upgrade`）
|