# 项目结构

**技术栈:**
- 后端: 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`）