前言
前端项目要区分做toB，toC，不同的风格技术栈完全不同，前端的风格也不同
ai编码工具推荐:
- codex
- claude code
- github copilot cli
github copilot cli 支持
openai和claude模型
前端还是Claude 模型审美更好，使用 Claude opus 4.6 来编码
流程
AI时代的开发都是文档先行，代码不值钱，规划项目的能力是很重要的
1. 明确技术栈
明确自己项目的定位，明确技术栈使用哪些组件
AI特别喜欢自己造轮子，就任意失控，所以推荐自己想这些功能用哪些组件来实现
这就需要你对前端的技术有一点了解，不行和gpt5.5聊然后去看各大论坛和github大家使用反馈情况
判断是否选择这个技术站
比较推荐的技术栈就是 React，React生态下 AI巨会写相关的代码，写的很优秀
2. 编写 AGENTS.md 或 CLAUDE.md
编写指导AI编码、AI写文档、AI测试、AI review的提示词，将这些提示词作为资产放到项目中去
要用的时候给code agent来进行编码
- 比如:
# AGENTS.md
## 1. 项目定位
本项目为 **虹启万象平台** 前端应用。
应用形态为：
- 企业级中后台管理系统
- Admin Dashboard Layout
- 面向 AI 能力、知识库、解决方案、应用聚合、大模型资源管理等场景
- 强调统一入口、统一管理、统一体验
应用名称：
```text
虹启万象
```
英文名称可使用：
```text
HongQi WanXiang Platform / HQWX Platform
```
---
## 2. 技术栈
前端基础技术：
| 类型 | 技术 |
| --------------------- | ------------------------------------- |
| 框架 | Vue 3 |
| 构建工具 | Vite |
| UI 组件库 | Element Plus |
| 网络请求 | Axios |
| 路由管理 | Vue Router |
| 状态管理 | Pinia |
| 图表展示 | ECharts |
| 图标库 | lucide-vue-next |
| Office 文件预览 | vue-office |
| Markdown / KaTeX 渲染 | markdown-it-katex |
| 大模型图标 | https://icons.lobehub.com/components/ |
默认使用：
```vue
<script setup lang="ts">
```
必须优先使用：
- Composition API
- TypeScript
- 组件化拆分
- services 层统一请求
- composables 抽离复杂逻辑
---
## 3. 后端与鉴权约定
当前后端已实现认证服务与 API 网关能力。
数据流：
```text
Client → Gateway → Auth Service
```
统一鉴权方案：
- 使用 **Access JWT**
- 使用 **Refresh Token**
- 由 **API Gateway** 统一鉴权
- 服务内部默认带 `/api/v1` 前缀
- 网关可将外部路径映射到内部服务路径
开发时注意：
- 前端不直接绕过网关访问后端服务
- 请求统一走 Axios 封装
- Token 相关逻辑统一放在认证模块中处理
- 不要在业务组件中直接拼接鉴权 Header
- 不要在页面组件中直接写刷新 Token 逻辑
---
## 4. 推荐目录结构
```text
src/
├── api/ # API 类型定义或接口声明
├── assets/ # 静态资源
├── components/ # 通用组件
├── composables/ # 可复用逻辑
├── layouts/ # 页面布局
├── router/ # 路由配置
├── services/ # 请求服务封装
├── stores/ # Pinia 状态管理
├── styles/ # 全局样式
├── types/ # 全局类型定义
├── utils/ # 工具函数
└── views/ # 页面级组件
```
建议页面模块：
```text
views/
├── dashboard/
├── agent/
├── solutions/
├── knowledge-base/
├── applications/
├── playground/
│ ├── llm/
│ ├── image/
│ └── video/
├── model-center/
├── ai-model-management/
└── user-management/
```
---
## 5. 编码规范
### 5.1 组件职责
一个组件只做一件事。
组件类型建议区分为：
- 展示组件
- 输入组件
- 容器组件
- 页面组件
- 业务弹窗组件
- 表格 / 列表组件
不要把请求、状态、复杂计算、表格渲染、弹窗逻辑全部写在一个组件里。
---
### 5.2 文件行数限制
建议控制：
| 文件类型 | 行数限制 |
| ------------ | -------------------- |
| 普通组件 | ≤ 200 行 |
| 页面组件 | ≤ 400 行 |
| composable | ≤ 200 行 |
| service 文件 | 按模块拆分，避免过大 |
| store 文件 | 按业务域拆分 |
超过限制时必须拆分。
---
### 5.3 Vue 写法
统一使用：
```vue
<script setup lang="ts">
```
优先使用：
- `ref`
- `reactive`
- `computed`
- `watch`
- `onMounted`
- 自定义 composables
禁止在新代码中使用 Options API。
---
### 5.4 逻辑与视图分离
复杂逻辑必须抽离。
示例：
```text
components/SolutionUploadDialog.vue
composables/useSolutionUpload.ts
services/solutionService.ts
```
组件只负责：
- 展示数据
- 接收用户输入
- 触发事件
- 调用 composable 暴露的方法
复杂逻辑放到：
- `composables/useXxx.ts`
- `services/xxxService.ts`
- `stores/xxxStore.ts`
- `utils/xxx.ts`
---
### 5.5 请求统一管理
组件中禁止直接写：
```ts
axios.get(...)
axios.post(...)
fetch(...)
```
必须通过 `services` 调用。
推荐写法：
```ts
// services/solutionService.ts
export function getSolutionList(params: SolutionListParams) {
return request.get<SolutionListResponse>('/solutions', { params })
}
```
页面中调用：
```ts
const result = await getSolutionList(query)
```
---
### 5.6 状态管理
状态分层：
| 状态类型 | 推荐方式 |
| -------------- | ------------------------- |
| 单组件内部状态 | `ref` / `reactive` |
| 父子组件通信 | `props` / `emit` |
| 跨页面共享状态 | Pinia |
| 持久化登录状态 | Pinia + storage |
| URL 状态 | Vue Router query / params |
不要把所有状态都塞进 Pinia。
---
### 5.7 模板保持简单
模板只负责展示。
复杂逻辑不要写在模板中。
不推荐：
```vue
<div>{{ list.filter(item => item.enabled).map(item => item.name).join(',') }}</div>
```
推荐：
```ts
const enabledNames = computed(() =>
list.value
.filter(item => item.enabled)
.map(item => item.name)
.join(',')
)
```
```vue
<div>{{ enabledNames }}</div>
```
---
### 5.8 重复逻辑处理
同一逻辑出现三次，必须抽象。
可抽象为：
- 通用组件
- composable
- util function
- service method
- Pinia action
---
### 5.9 错误处理
所有异步请求必须考虑错误处理。
推荐：
```ts
try {
loading.value = true
const data = await getSolutionList(params)
list.value = data.items
} catch (error) {
ElMessage.error('获取解决方案列表失败')
} finally {
loading.value = false
}
```
不要静默吞掉异常。
---
### 5.10 TypeScript 要求
新代码必须补充基础类型。
禁止大量使用：
```ts
any
```
除非确实无法确定类型，并且需要加注释说明原因。
推荐：
```ts
interface SolutionItem {
id: string
name: string
provider?: string
tags: string[]
createdAt: string
}
```
---
## 6. UI 与交互规范
整体风格：
- 企业级
- 简洁
- 白 / 红 / 灰为主
- 少用花哨动效
- 少用过度渐变
- 保持中后台系统的可读性和稳定感
页面设计原则：
- 信息层级清楚
- 操作按钮明确
- 表格、筛选、弹窗规范统一
- 空状态、加载态、错误态必须完整
- 危险操作必须二次确认
- 管理员操作需有明确视觉区分
常见状态必须覆盖：
| 状态 | 要求 |
| -------- | ---------------------- |
| loading | 使用骨架屏或加载组件 |
| empty | 使用清晰空状态文案 |
| error | 展示失败原因或重试入口 |
| success | 给予必要反馈 |
| disabled | 明确不可操作原因 |
---
## 7. 路由规范
路由建议按业务模块拆分。
示例：
```ts
{
path: '/solutions',
name: 'Solutions',
component: () => import('@/views/solutions/index.vue'),
meta: {
title: '解决方案',
requiresAuth: true
}
}
```
要求：
- 路由必须配置 `meta.title`
- 需要登录的页面必须配置 `requiresAuth: true`
- 管理员页面需要配置权限字段
- 页面组件使用懒加载
---
## 8. 接口与服务规范
### 8.1 Axios 封装
统一封装请求实例：
```text
services/request.ts
```
需要包含：
- baseURL
- timeout
- request interceptor
- response interceptor
- Access Token 注入
- 401 处理
- Refresh Token 处理
- 统一错误提示策略
---
### 8.2 Service 命名
推荐：
```text
authService.ts
solutionService.ts
knowledgeBaseService.ts
applicationService.ts
modelService.ts
playgroundService.ts
userService.ts
```
函数命名示例：
```ts
login()
logout()
refreshToken()
getSolutionList()
uploadSolution()
deleteKnowledgeFile()
getModelList()
createChatCompletion()
generateImage()
```
---
## 9. AI 生成代码要求
AI 生成代码后必须整理。
必须检查：
- 是否有冗余代码
- 是否补充 TypeScript 类型
- 是否有错误处理
- 是否有 loading 状态
- 是否直接在组件里写请求
- 是否把复杂逻辑堆在页面里
- 是否出现重复逻辑
- 是否有无用 import
- 是否违反组件行数限制
- 是否影响现有路由和页面结构
禁止直接提交未经整理的 AI 生成代码。
---
## 10. 开发任务处理原则
当需要新增功能时，优先按以下顺序处理：
1. 明确页面归属模块
2. 明确是否已有 service
3. 明确是否已有 store
4. 明确是否需要新增组件
5. 明确是否需要新增路由
6. 明确接口数据结构
7. 实现页面和交互
8. 补充错误态、加载态、空状态
9. 简单自测
10. 清理冗余代码
---
## 11. 禁止事项
禁止：
- 直接在组件中写 Axios 请求
- 直接在页面中处理复杂鉴权逻辑
- 新代码使用 Options API
- 大量使用 `any`
- 一个页面文件无限堆逻辑
- 重复复制相同代码
- 无 loading、无错误处理、无空状态
- 未确认接口结构时强行写死字段
- 擅自修改全局布局和主题风格
- 删除已有功能但不说明原因
---
## 12. 输出代码时的要求
生成或修改代码时，需要尽量做到：
- 文件路径清晰
- 给出完整代码
- 标明新增文件和修改文件
- 不要只给片段，除非用户明确要求
- 保持项目现有风格
- 不引入不必要的新依赖
- 优先复用已有组件、service、store、utils
- 改动范围尽量小
- 保证代码可读、可维护
---
## 13. 项目当前重点模块
当前平台重点模块包括：
- 仪表盘
- Agent
- 解决方案
- 公共知识库
- AI 应用
- AI 操场
- LLM 调试
- Image 调试
- Video 调试
- 大模型中心
- AI 模型管理
- 用户管理
开发时应优先保证这些模块的导航、布局、权限、数据流和交互体验一致。
---
## 14. 总体原则
本项目的核心目标不是堆功能，而是形成一个稳定、清晰、可维护的企业级 AI 平台前端。
所有代码应优先满足：
1. 结构清楚
2. 职责明确
3. 易于维护
4. 易于扩展
5. 风格统一
6. 可被团队继续接手
最终目标：
```text
让下一个开发者 30 秒内能看懂组件结构，3 分钟内能定位业务逻辑，10 分钟内能完成小改动。
```
3. 出稿图
3.1 使用gpt-image-2生成参考图
当你不知道web前端要弄成什么样子就可以使用gpt image2 来生成
描述清楚你的需求，页面风格，使用gpt image2 就能生成一个很好的参考图，抽奖
提示词可以去别的找找参考参考，自己积累积累，或者之直接让AI生成
比如:
3.2 figma 或者 google stitch 生成草稿
figma的 ai 生成 能快速出一个react 相关的组件十分好用，如果满意可以直接导出
然后交给AI复用这些组件，进一步迭代功能
google stitch 为直接生成参考页面，量大管饱，纯抽奖，不过现在比较推荐gpt-image-2
4. 让AI查看接口文档来实现需求
推荐使用md文档，并让文档中编写好接口并附带说明，比如下面的例子
### 1. 创建用户
- **接口地址**：`POST /api/v1/admin/users`
- **请求参数**（JSON）：
- `username`（string）：用户名
- `password`（string）：密码
- `email`（string，可选）：邮箱
- `display_name`（string，可选）：展示名称
- `avatar_url`（string，可选）：头像地址
- **返回结果**：
- `success`（bool）
- `message`（string）
- `data`（object，可选）：创建的用户信息
**请求exp**
```json
{
"username": "string",
"password": "string",
"email": "string",
"display_name": "string",
"avatar_url": "string"
}
```
**响应exp**
```json
{
"success": true,
"message": "user created, user_id=2",
"data": {
"id": 2,
"username": "string",
"email": "string"
}
}
```
md先行，对AI友好型，不推荐直接导出openapi.json文件，因为单个文件太大了，AI上下文很容易爆掉
5. AI完成编码人进行完成的E2E测试
功能测试这一块AI全替代成本太高，最好还是人来进行AI测试
虽然Agent 有 computer use，使用playwright能实现对浏览器的原生操作进行测试，单还是不保险
另一种可行的方式是直接让AI将测试流程固定下来E2E测试每次CI触发，进行全流程测试，也不失一种选择
人的工作
人需要的是对整个项目的把控
- 架构的把控
- 技术栈的把控
- 复杂事务的拆分
- 文档的编写（给AI提供方向和提示词的编写）