first commit

2026-04-07 16:05:05 +08:00
commit 9d9bdbb1ce
136 changed files with 5103 additions and 0 deletions
@@ -0,0 +1,179 @@
+# 项目结构
+
+**技术栈:**
+- 后端: 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`）