Claw 项目完整结构提交
This commit is contained in:
zqm
274
Claw/.trae/rules/项目规则.md
Normal file
274
Claw/.trae/rules/项目规则.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 企业微信智控未来系统项目规则
|
||||
|
||||
## 1. 项目背景与目标
|
||||
|
||||
- **项目背景**：用户拥有一个未经认证的企业微信，包含应用"智控未来"，以及两台服务器（服务器A：公网服务器47.109.191.115 - pactgo.cn，配置SSL证书，外网可访问；服务器B：内网服务器，安装LMStudio，只能访问外网，外网无法直接访问）
|
||||
|
||||
- **项目目标**：使用Rust和官方原生微信小程序技术栈实现：用户通过企业微信应用"智控未来"和微信小程序进行聊天，下发任务。任务经服务器A（网关）通过WebSocket反向连接转发到服务器B（SmartClaw），B上的LMStudio进行AI处理后返回结果给用户。
|
||||
|
||||
- **核心架构**：WebSocket反向连接（B主动连接A），Embedded-Redis（仅A启动），HeedDB嵌入式数据库，原生小程序（WXML+WXSS+JS）。
|
||||
|
||||
## 2. 系统架构
|
||||
|
||||
### 2.1 整体架构
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant WeChat as 企业微信/小程序
|
||||
participant Gateway as 网关服务（服务器A）
|
||||
participant SmartClaw as SmartClaw服务（服务器B）
|
||||
participant LMStudio as LMStudio
|
||||
|
||||
User->>WeChat: 发送消息/任务
|
||||
WeChat->>Gateway: HTTPS回调请求
|
||||
Gateway->>SmartClaw: WebSocket转发任务
|
||||
SmartClaw->>SmartClaw: 处理任务（智能控制核心逻辑）
|
||||
SmartClaw->>LMStudio: HTTP调用LMStudio API
|
||||
LMStudio-->>SmartClaw: SSE流式返回结果
|
||||
SmartClaw-->>Gateway: WebSocket回传结果
|
||||
Gateway-->>WeChat: HTTPS回调响应
|
||||
WeChat-->>User: 显示结果
|
||||
```
|
||||
|
||||
### 2.2 组件说明
|
||||
|
||||
| 组件 | 职责 | 技术栈 |
|
||||
|------|------|--------|
|
||||
| 企业微信应用 | 用户交互界面，接收用户消息和任务 | 企业微信JS-SDK |
|
||||
| 微信小程序 | 用户交互界面，接收用户消息和任务 | WXML + WXSS + JavaScript（官方原生） |
|
||||
| 网关服务（服务器A） | 接收HTTPS请求，WebSocket反向连接，Embedded-Redis多用户管理 | Rust + Actix Web + Embedded-Redis |
|
||||
| SmartClaw服务（服务器B） | WebSocket客户端，处理任务，调用LMStudio，HeedDB存储 | Rust + Actix Web + HeedDB |
|
||||
| 智能控制核心逻辑 | 核心业务逻辑，处理用户任务，调用LMStudio | Rust |
|
||||
| LMStudio | 提供AI能力，SSE流式响应 | 第三方工具 |
|
||||
|
||||
## 3. 技术选型
|
||||
|
||||
### 3.1 后端技术栈
|
||||
|
||||
| 技术 | 版本 | 用途 |
|
||||
|------|------|------|
|
||||
| Rust | 1.70+ | 后端开发语言 |
|
||||
| Actix Web | 4.0+ | Web框架，处理HTTP/WebSocket请求 |
|
||||
| Tokio | 1.0+ | 异步运行时 |
|
||||
| Serde | 1.0+ | 序列化/反序列化 |
|
||||
| Reqwest | 0.11+ | HTTP客户端 |
|
||||
| Embedded-Redis | 最新版 | 嵌入式Redis（仅网关服务启动） |
|
||||
| HeedDB | 最新版 | 嵌入式K/V数据库（Sled底层） |
|
||||
|
||||
### 3.2 前端技术栈
|
||||
|
||||
| 技术 | 版本 | 用途 |
|
||||
|------|------|------|
|
||||
| WXML + WXSS + JavaScript | 最新版 | 微信小程序官方原生技术栈 |
|
||||
| 企业微信JS-SDK | 最新版 | 企业微信网页开发 |
|
||||
| 微信开发者工具 | 最新版 | 官方IDE，完整API支持 |
|
||||
| wx.request() | 原生API | HTTP客户端 |
|
||||
| wx.connectSocket() | 原生API | WebSocket通信 |
|
||||
|
||||
## 4. 网络通信方案
|
||||
|
||||
### 4.1 企业微信/小程序与网关服务通信
|
||||
|
||||
- **企业微信**：使用企业微信回调机制，网关服务提供HTTPS接口接收企业微信的消息推送，回调地址：`https://pactgo.cn/wecom`
|
||||
- **微信小程序**：使用HTTPS接口与网关服务通信，实现消息发送和任务下发，接口地址：`https://pactgo.cn/api/v1/`
|
||||
|
||||
### 4.2 网关服务与SmartClaw服务通信
|
||||
|
||||
由于SmartClaw服务在内网中，外网不能访问它，采用**WebSocket反向连接方案**：
|
||||
|
||||
1. **SmartClaw服务主动连接**：服务器B启动时，主动WebSocket连接到服务器A（wss://pactgo.cn/ws/control）
|
||||
2. **长连接保持**：维持持久WebSocket连接，支持心跳检测和断线重连
|
||||
3. **双向通信**：服务器A通过WebSocket发送任务，服务器B处理完成后回传结果
|
||||
4. **零配置**：使用Embedded-Redis（仅网关服务启动），无需独立Redis服务
|
||||
|
||||
### 4.3 SmartClaw服务与LMStudio通信
|
||||
|
||||
- 使用LMStudio提供的HTTP API接口进行通信
|
||||
- 支持SSE流式响应，实时返回AI处理结果
|
||||
- 服务器B上的LMStudio监听地址：http://127.0.0.1:1234
|
||||
|
||||
## 5. 安全考虑
|
||||
|
||||
### 5.1 网络安全
|
||||
|
||||
- 所有通信使用HTTPS加密（企业微信强制要求）
|
||||
- 服务器A配置防火墙，只开放443端口（HTTPS）
|
||||
- 服务器B只允许来自服务器A的WebSocket连接
|
||||
- 使用有效SSL证书（Let's Encrypt）
|
||||
|
||||
### 5.2 认证与授权
|
||||
|
||||
- 企业微信应用使用CorpID和Secret进行认证，回调地址：`https://pactgo.cn/wecom`
|
||||
- 微信小程序使用AppID和AppSecret进行认证，接口地址：`https://pactgo.cn/api/v1/`
|
||||
- 服务器间WebSocket通信使用预共享密钥认证
|
||||
- 多用户多设备状态管理使用Embedded-Redis
|
||||
|
||||
### 5.3 数据安全
|
||||
|
||||
- 敏感数据加密存储（HeedDB嵌入式数据库支持事务）
|
||||
- 定期备份数据
|
||||
- 实现访问控制，确保只有授权用户能访问相关功能
|
||||
- 多用户多设备状态管理使用Embedded-Redis
|
||||
|
||||
## 6. 项目结构
|
||||
|
||||
```
|
||||
Claw/
|
||||
├── Server/ # 后端服务
|
||||
│ ├── gateway/ # 网关服务（服务器A）
|
||||
│ │ ├── src/ # 源代码
|
||||
│ │ ├── target/ # 编译产出
|
||||
│ │ └── Cargo.toml # 项目配置
|
||||
│ ├── SmartClaw/ # 智能控制服务（服务器B）
|
||||
│ │ ├── src/ # 源代码
|
||||
│ │ ├── target/ # 编译产出
|
||||
│ │ └── Cargo.toml # 项目配置
|
||||
│ └── shared/ # 共享代码
|
||||
│ ├── src/ # 源代码
|
||||
│ ├── target/ # 编译产出
|
||||
│ └── Cargo.toml # 项目配置
|
||||
├── client/ # 客户端代码
|
||||
│ ├── wechat_app/ # 微信小程序（官方原生技术栈）
|
||||
│ │ ├── pages/ # 页面目录（index, chat, task, user）
|
||||
│ │ ├── utils/ # 工具函数（api.js, util.js, constant.js）
|
||||
│ │ ├── components/ # 自定义组件（message, task-card, user-avatar）
|
||||
│ │ ├── assets/ # 静态资源（images, icons）
|
||||
│ │ ├── app.js # 应用入口文件
|
||||
│ │ ├── app.json # 应用配置文件
|
||||
│ │ ├── app.wxss # 应用全局样式
|
||||
│ │ ├── project.config.json # 项目配置文件
|
||||
│ │ └── sitemap.json # 站点地图配置
|
||||
│ └── web/ # 企业微信网页应用（可选）
|
||||
│ ├── index.html # 网页入口
|
||||
│ ├── css/ # 样式文件
|
||||
│ ├── js/ # JavaScript文件
|
||||
│ └── assets/ # 静态资源
|
||||
├── build/ # 构建产物
|
||||
│ ├── gateway/ # 网关服务构建产物
|
||||
│ ├── SmartClaw/ # 智能控制服务构建产物
|
||||
│ └── client/ # 客户端构建产物
|
||||
├── docs/ # 项目文档
|
||||
├── scripts/ # 脚本文件
|
||||
│ ├── build.sh # 构建脚本
|
||||
│ ├── deploy_gateway.sh # 网关服务部署脚本
|
||||
│ └── deploy_smart_claw.sh # 智能控制服务部署脚本
|
||||
├── .gitignore # Git忽略文件
|
||||
├── Cargo.toml # 根Rust项目配置（workspace）
|
||||
├── nginx.conf # nginx反向代理配置
|
||||
├── ssl/ # SSL证书目录
|
||||
│ ├── pactgo.cn-chain.pem # SSL证书链
|
||||
│ └── pactgo.cn-key.pem # SSL私钥
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
## 7. 实施步骤
|
||||
|
||||
1. **准备阶段**:
|
||||
* 创建项目基础结构
|
||||
* 初始化Git仓库
|
||||
* 初始化Rust和前端项目
|
||||
|
||||
2. **后端开发**:
|
||||
* 开发服务器A后端（网关服务）
|
||||
* 开发服务器B后端（SmartClaw服务）
|
||||
* 测试服务器间通信
|
||||
|
||||
3. **前端开发**:
|
||||
* 开发微信小程序（官方原生技术栈：WXML+WXSS+JS）
|
||||
* 配置企业微信应用（企业微信JS-SDK）
|
||||
|
||||
4. **部署与测试**:
|
||||
* 编写部署脚本
|
||||
* 部署到服务器
|
||||
* 功能测试
|
||||
* 性能测试
|
||||
* 安全测试
|
||||
|
||||
5. **文档编写**:
|
||||
* 编写项目文档
|
||||
* 编写API文档
|
||||
* 编写部署文档
|
||||
* 编写使用文档
|
||||
|
||||
## 8. 注意事项
|
||||
|
||||
1. **网络通信**:
|
||||
* 服务器B在内网中，使用WebSocket反向连接方案：SmartClaw服务主动连接网关服务的WebSocket
|
||||
* 维持持久WebSocket连接，支持心跳检测和断线重连
|
||||
* 使用Embedded-Redis进行多用户多设备状态管理
|
||||
|
||||
2. **安全考虑**:
|
||||
* 所有通信使用HTTPS加密（企业微信强制要求）
|
||||
* 服务器A配置防火墙，只开放443端口（HTTPS）
|
||||
* 服务器B只允许来自服务器A的WebSocket连接
|
||||
* 使用有效SSL证书（Let's Encrypt）
|
||||
* 实现认证与授权机制（AppID、CorpID、API密钥）
|
||||
|
||||
3. **性能考虑**:
|
||||
* 优化WebSocket反向连接，实现长连接和心跳检测
|
||||
* 合理使用Embedded-Redis进行多用户状态管理
|
||||
* 合理使用LMStudio，支持流式响应（SSE）
|
||||
* 使用HeedDB嵌入式数据库，零配置高性能
|
||||
* 实现异步处理，提供任务状态反馈
|
||||
|
||||
4. **兼容性**:
|
||||
* 考虑Windows Server 2012的环境（静态链接编译）
|
||||
* 确保代码在目标环境中能正常运行
|
||||
* 网关服务需配置Embedded-Redis和SSL证书
|
||||
* SmartClaw服务需配置HeedDB和LMStudio连接
|
||||
|
||||
5. **部署环境**:
|
||||
* 服务器A：Windows Server 2012系统
|
||||
* 服务器B：Windows Server 2012系统，安装LMStudio
|
||||
|
||||
## 9. 开发计划
|
||||
|
||||
### 9.1 阶段一：基础设施搭建
|
||||
|
||||
- 配置服务器环境
|
||||
- 安装必要的软件和依赖
|
||||
- 搭建开发环境
|
||||
|
||||
### 9.2 阶段二：后端开发
|
||||
|
||||
- 开发网关服务（服务器A）的Web服务（Embedded-Redis多用户管理）
|
||||
- 开发SmartClaw服务（服务器B）的Web服务（WebSocket客户端）
|
||||
- 实现WebSocket反向连接通信（B主动连接A）
|
||||
- 开发智能控制核心逻辑
|
||||
- 集成LMStudio API（SSE流式响应）
|
||||
|
||||
### 9.3 阶段三：前端开发
|
||||
|
||||
- 开发微信小程序（官方原生技术栈：WXML+WXSS+JS）
|
||||
- 配置企业微信应用（企业微信JS-SDK）
|
||||
|
||||
### 9.4 阶段四：测试与部署
|
||||
|
||||
- 功能测试
|
||||
- 性能测试
|
||||
- 安全测试
|
||||
- 部署到生产环境
|
||||
|
||||
### 9.5 阶段五：运维与监控
|
||||
|
||||
- 配置监控系统
|
||||
- 制定运维计划
|
||||
- 建立故障处理流程
|
||||
|
||||
## 10. 风险评估
|
||||
|
||||
| 风险 | 影响 | 应对措施 |
|
||||
|------|------|----------|
|
||||
| 企业微信未经认证 | 可能限制部分功能 | 尽量使用企业微信开放的基础功能，避免需要认证的高级功能 |
|
||||
| SmartClaw服务在内网 | 外网无法直接访问 | 使用WebSocket反向连接方案：B主动连接A |
|
||||
| LMStudio性能 | 可能影响处理速度 | 优化智能控制核心逻辑，支持SSE流式响应 |
|
||||
| 网络延迟 | 可能影响用户体验 | 优化WebSocket长连接，实现心跳检测和断线重连 |
|
||||
| SSL证书配置 | 影响企业微信回调 | 使用Let's Encrypt自动化证书管理 |
|
||||
| 多用户并发 | 可能影响系统性能 | 使用Embedded-Redis进行多用户状态管理 |
|
||||
|
||||
## 11. 结论
|
||||
|
||||
基于以上分析，本项目在技术、网络和成本方面都是可行的。采用WebSocket反向连接架构，使用官方原生微信小程序技术栈，实现用户通过企业微信和微信小程序与系统进行交互，完成AI任务的下发、处理和结果返回。系统具备多用户多设备管理能力，支持高并发和零配置部署。
|
||||
|
||||
建议按照开发计划分阶段实施，确保系统的稳定性和可靠性。同时，要注意安全防护，保护用户数据和系统资源。
|
||||
Reference in New Issue
Block a user