project-rules

智能体平台前端项目开发规则

项目概述

这是一个基于 React 18 + UmiJS Max + Ant Design 的智能体平台前端项目，提供智能体开发、管理和使用的完整解决方案。

技术栈规范

核心技术

• 前端框架: React 18 (函数组件 + Hooks)
• UI 组件库: Ant Design 5.x + ProComponents
• 图形引擎: AntV X6 (流程图、图可视化)
• 框架工具: UmiJS Max 4.x (约定式路由、插件体系)
• 状态管理: UmiJS 内置 model (主要方案)
• 类型检查: TypeScript 5.x
• 样式方案: CSS Modules + Less (禁止全局污染)
• 包管理: pnpm (Node.js > 18.0.0)

代码规范

文件命名

• 组件文件：PascalCase (如 UserProfile.tsx)
• 工具文件：camelCase (如 formatDate.ts)
• 样式文件：与组件同名 (如 UserProfile.less)
• 类型文件：camelCase + .types.ts 后缀

组件开发规范

// 组件必须包含详细注释
/**
 * 用户资料组件
 * @param {Object} props - 组件属性
 * @param {string} props.userId - 用户ID
 * @param {boolean} props.editable - 是否可编辑
 * @param {Function} props.onSave - 保存回调
 * @returns {JSX.Element} 用户资料组件
 */
interface UserProfileProps {
  userId: string;
  editable?: boolean;
  onSave?: (data: UserData) => void;
}

const UserProfile: React.FC<UserProfileProps> = ({ userId, editable = false, onSave }) => {
  // 组件实现
};

性能优化要求

• 使用 useMemo 缓存计算结果
• 使用 useCallback 缓存函数引用
• 路由和组件必须懒加载
• 表单、表格优先使用 ProComponents
• 图形功能统一使用 AntV X6

状态管理规范

• 全局状态使用 UmiJS model
• 局部状态使用 useState/useReducer
• 避免 props 层层传递
• 异步请求封装在 services/ 目录

样式规范

// 使用 CSS Modules，避免全局污染
.userProfile {
  // 组件样式
  &__header {
    // 子元素样式
  }
  
  &--editable {
    // 修饰符样式
  }
}

AppDev Web IDE 开发规范

文件结构规范

• 页面组件: pages/AppDev/components/ 目录下
• 自定义 Hooks: hooks/useAppDev*.ts 命名规范
• 状态管理: 使用 models/appDev.ts 中的 useAppDevStore
• API 服务: services/appDev.ts 统一管理

核心 Hooks 使用

// 文件管理
const fileManagement = useAppDevFileManagement({
  projectId: workspace.projectId,
  onFileSelect: setActiveFile,
  onFileContentChange: updateFileContent,
});

// AI 聊天
const chat = useAppDevChat({
  projectId: workspace.projectId,
  onMessage: handleMessage,
});

// 开发服务器
const server = useAppDevServer({
  projectId: workspace.projectId,
  onStatusChange: handleServerStatus,
});