sentclaw/AGENTS.md

项目结构

技术栈:

• 后端: 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 厂商支持

开发命令

快速初始化

# 一键初始化所有环境
./scripts/setup.sh

Docker 服务

# 启动 MySQL + Redis
docker-compose up -d

# 停止服务
docker-compose down

# 查看日志
docker-compose logs -f

后端开发

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

前端开发

cd web

# 安装依赖（首次）
npm install

# 启动开发服务器
npm run dev  # 运行在 http://localhost:5173

# 代码检查
npm run lint

# 代码格式化
npm run format

# 构建生产版本
npm run build

桌面应用开发

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）