9.8 KiB
9.8 KiB
WXAuto Center AI 开发流程规则
概述
本项目是 WXAuto Center 中控系统，采用 FastAPI + PostgreSQL + Redis 架构。本规则用于规范 AI Agent 开发流程，确保代码质量和项目一致性。
项目结构
wxauto_api/
├── api/ # API 路由层
│ ├── __init__.py
│ ├── nodes.py # 节点管理
│ ├── messages.py # 消息发送
│ ├── external.py # 外部接口
│ ├── plugins.py # 插件管理
│ └── callback.py # 回调接口
├── services/ # 业务逻辑层
│ ├── node_manager.py
│ ├── monitor_service.py
│ └── log_service.py
├── models.py # 数据模型
├── config.py # 配置管理
├── main.py # FastAPI 主入口
├── data/ # 数据目录
│ ├── db/ # PostgreSQL 数据
│ ├── redis/ # Redis 数据
│ └── logs/ # 应用日志
├── doc/ # 项目文档
├── scripts/ # 部署脚本
├── static/ # 前端资源
└── plugins/ # 插件系统
开发流程
1. 需求分析 (Requirement Analysis)
原则：在开始任何代码修改前，必须充分理解需求。
执行步骤
-
澄清需求
- 明确功能目标和边界
- 确认输入输出格式
- 识别依赖关系和影响范围
-
影响评估
- 确定修改涉及的文件
- 评估对现有功能的影响
- 检查是否有breaking change
-
任务分解
- 使用 TodoWrite 工具创建任务清单
- 优先级排序
- 预估任务间的依赖
检查清单
- 需求已明确，无歧义
- 影响范围已评估
- 任务已分解并创建 Todo
- 依赖项已识别
2. 设计 (Design)
原则：设计先行，避免返工。
执行步骤
-
接口设计
- RESTful API 设计规范
- 请求/响应格式定义
- 错误码设计
-
数据模型设计
- 数据库表结构（如需）
- 配置项设计
- 数据流设计
-
模块设计
- 公共函数抽取
- 模块边界定义
- 依赖关系梳理
检查清单
- API 接口设计已确定
- 数据模型已设计（如需）
- 模块划分已明确
- 向后兼容性已考虑
3. 实现 (Implementation)
原则：遵循代码规范，保持一致性。
代码规范
- 文件头部注释
# ///
# filename.py
# 描述：模块功能描述
# 作者：AI Generated
# 创建日期：YYYY-MM-DD
# ///
- 函数注释
async def function_name(param1: str, param2: int) -> Dict[str, Any]:
"""
函数功能说明
Args:
param1: 参数1说明
param2: 参数2说明
Returns:
返回值说明
Raises:
HTTPException: 异常说明
"""
-
命名规范
- 类名：PascalCase (如
NodeManager) - 函数名：snake_case (如
send_message) - 常量：UPPER_SNAKE_CASE (如
MAX_RETRIES) - API 字段：snake_case (如
node_id,wechat_status)
- 类名：PascalCase (如
-
路径规范
- 项目根目录：
/Users/skn/Desktop/wxauto_api - 使用绝对路径
- 数据目录：
data/db,data/redis,data/logs
- 项目根目录：
执行步骤
- 创建 Todo 跟踪任务
TodoWrite(todos=[
{"id": "1", "content": "任务1", "status": "in_progress"},
{"id": "2", "content": "任务2", "status": "pending"},
])
-
按优先级实现
- 先核心功能，后辅助功能
- 先底层模块，后上层调用
- 先接口定义，后具体实现
-
同步更新相关文件
- API 路由 ↔ 服务层
- 前端 ↔ 后端接口
- 配置 ↔ 代码
检查清单
- 代码符合注释规范
- 函数有文档字符串
- 命名符合规范
- 错误处理完善
- 无硬编码配置
4. 代码审核 (Code Review)
原则：主动发现并修复问题。
自检清单
-
逻辑检查
- 所有分支都有处理
- 异常情况已处理
- 边界条件已考虑
-
安全检查
- 无硬编码密钥
- 输入已验证
- SQL 注入防护
- 权限检查完整
-
性能检查
- 无阻塞操作在 async 中
- 数据库连接正确关闭
- 无内存泄漏
-
一致性检查
node_idvsnode_name使用正确- 配置命名一致
- API 响应格式一致
执行步骤
-
代码自查
- 逐文件检查
- 逐函数验证
-
路径验证
- Grep 搜索关键路径引用
- 确认无残留
wxauto_center等旧路径
-
导入验证
python -c "from module import something"
检查清单
- 代码通过自检清单
- 无路径错误
- 导入测试通过
- 配置一致性检查通过
5. 测试 (Testing)
原则：测试驱动开发，验证所有功能。
测试类型
-
单元测试
- 工具函数测试
- 数据模型测试
- 业务逻辑测试
-
集成测试
- API 接口测试
- 数据库操作测试
- Redis 操作测试
-
手动测试
- 前端功能测试
- 端到端流程测试
执行步骤
- 启动服务
# 本地开发
python main.py
# Docker 环境
docker compose up -d
- API 测试
# 获取节点列表
curl -X GET "http://localhost:8080/api/v1/nodes/" \
-H "X-API-Key: your-external-api-key"
# 发送消息
curl -X POST "http://localhost:8080/api/v1/external/send" \
-H "X-ExternalKey: your-external-api-key" \
-H "Content-Type: application/json" \
-d '{"node_id": "wx1", "who": "文件传输助手", "msg": "test"}'
- 验证清单
- API 请求成功
- 响应格式正确
- 错误处理正确
- 前端显示正确
检查清单
- 核心 API 测试通过
- 错误场景测试通过
- 前端功能正常
- 日志输出正常
6. 文档更新 (Documentation)
原则：文档与代码同步更新。
文档类型
-
API 文档 (
doc/API.md)- 接口说明
- 请求/响应示例
- 错误码说明
-
架构文档 (
doc/ARCHITECTURE.md)- 系统架构图
- 模块说明
- 流程图
-
部署文档 (
scripts/README.md)- Docker 部署说明
- 环境配置
- 故障排查
执行步骤
-
识别需更新的文档
- 新增功能 → API 文档
- 架构变更 → 架构文档
- 部署变更 → 部署文档
-
更新文档内容
- 接口签名变更
- 响应格式变更
- 配置项变更
-
添加变更记录
- 版本号
- 变更日期
- 变更说明
文档格式规范
接口文档示例
### POST /api/v1/resource
发送消息
**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| node_id | string | 是 | 节点ID |
| who | string | 是 | 接收人 |
| msg | string | 是 | 消息内容 |
**响应示例**
```json
{
"success": true,
"data": {...}
}
错误码
| 错误码 | 说明 |
|---|---|
| 404 | 节点不存在 |
| 503 | 节点不可用 |
#### 检查清单
- [ ] API 文档已更新
- [ ] 响应示例完整
- [ ] 错误码已说明
- [ ] 变更已记录
---
### 7. 脚本与部署 (Scripts & Deployment)
**原则**：部署脚本自动化，环境一致。
#### 脚本类型
1. **启动脚本** (`scripts/start_*.sh`)
- 环境检查
- 服务启动/停止
- 状态查看
2. **Docker 配置** (`Dockerfile`, `docker-compose.yml`)
- 多架构支持 (arm64/amd64)
- 数据卷挂载
- 环境变量
#### 执行步骤
1. **更新启动脚本**
- 路径正确性
- 架构兼容性
2. **更新 Docker 配置**
- 镜像版本
- 端口映射
- 数据目录
3. **验证部署**
```bash
# 本地构建测试
docker build -t wxauto-center:test .
# 启动测试
docker compose up -d
# 验证服务
curl http://localhost:8080/api/v1/nodes/
检查清单
- 启动脚本路径正确
- Docker 配置正确
- 数据目录已创建
- 端口无冲突
- 多架构支持（如需）
流程总结
┌─────────────────────────────────────────────────────────────┐
│ AI 开发流程 │
├─────────────────────────────────────────────────────────────┤
│ 1. 需求分析 → 2. 设计 → 3. 实现 → 4. 审核 → 5. 测试 │
│ ↓ │
│ 6. 文档更新 → 7. 部署脚本 │
└─────────────────────────────────────────────────────────────┘
关键规则
- Todo 跟踪：每个任务使用 TodoWrite 跟踪
- 先设计后实现：避免返工
- 边做边测：不要最后才测试
- 文档同步：代码变更即文档变更
- 路径规范：使用绝对路径，项目根目录为
/Users/skn/Desktop/wxauto_api
常用命令
# 安装依赖
pip install -r requirements.txt
# 启动服务
python main.py
# Docker 启动
docker compose up -d
# API 测试
curl http://localhost:8080/api/v1/nodes/
附录
配置管理
- 开发环境：
config.json - 环境变量：
.env - Docker 环境：通过
docker-compose.yml配置
数据库
- PostgreSQL：端口 5432
- Redis：端口 6379
- 数据目录：
data/db,data/redis
日志
- 应用日志：
data/logs/app.log - Docker 日志：
docker compose logs -f