Hermes Agent如何帮助Vue3前端工程的AI Native化实战手册

写给那些写了多年Vue、习惯了"改个页面先找组件、再找路由、再找api"前端流程的朋友们。

---

写在前面：前端AI Native到底在解决什么问题

前端工程师的日常是什么样的？接到需求 -> 找对应页面组件 -> 理清props和emit -> 找api调用层 -> 改页面 -> 联调 -> 样式调整 -> 自测。这些环节里，至少有50%是机械性重复劳动，而且前端工程有一个比后端更严重的问题：组件关系是隐性的。

后端至少有Controller -> Service -> Mapper这种明确的分层目录。前端呢？一个页面组件里可能直接import了三四个子组件，emit了五六个事件，调用了一堆api函数。新来的同事（或者AI）打开一个.vue文件，根本看不懂这个组件在全局的哪个位置、依赖谁、被谁依赖。

前端AI Native化的核心目标：让AI能理解组件关系、能独立完成后端API对接前端页面的完整链路、能自主维护组件文档和API文档。

在动手之前，仍然遵循同样的核心原则：AI上下文即代码（AI-Context-as-Code）。所有AI能读懂的文件都是工程的一部分，纳入Git版本控制。

---

第1步：让AI读懂你的前端工程（预计1-2天）

创建工程级AGENTS.md

在你的Vue3工程根目录（和vite.config.ts同级）创建AGENTS.md。

# 工程名称：XXX管理后台

## 技术栈
- Vue 3 + TypeScript + Vite 5.x
- Pinia（状态管理）
- Vue Router 4（路由）
- Axios（HTTP请求）
- Element Plus（UI组件库）
- Tailwind CSS 3.x（原子化CSS）

## 核心目录结构
src/
  api/            --- HTTP接口封装（每个业务域一个文件）
  components/     --- 全局公共组件（不涉及业务）
  composables/    --- 组合式函数（可复用的逻辑单元）
  layouts/        --- 页面布局组件
  pages/          --- 页面级组件（直接对应路由）
    order/        --- 订单模块
    user/         --- 用户模块
  router/         --- 路由配置
  stores/         --- Pinia状态
  types/          --- TypeScript类型定义
  utils/          --- 工具函数

## 关键约定
- API响应统一格式：{ code: number, data: T, message: string }
- 页面组件文件名用Index.vue作为路由入口（如 pages/order/Index.vue）
- 页面级组件放在pages/下，可复用组件放在components/下
- API函数统一使用async/await，禁止裸Promise
- 组件Props必须定义类型和默认值（禁止裸Object类型）

## 后端API约定
- 后端工程路径：../xxx-order（相对本工程的路径）
- 后端AGENTS.md：../xxx-order/AGENTS.md
- 所有API返回Result<T>，T在src/types/下有对应类型定义
- 分页查询使用PageVO { list: T[], total: number, pageNum: number, pageSize: number }
- 金额单位为分，前端展示时需除以100并格式化

## Git仓库
- 本工程仓库地址：git@git.company.com:xxx/xxx-admin.git
- 后端工程仓库地址：git@git.company.com:xxx/xxx-order.git
- 默认分支：main
- 如果本地没有代码，先 clone 再操作：
  git clone git@git.company.com:xxx/xxx-admin.git
  git clone git@git.company.com:xxx/xxx-order.git

## 不可踩的坑
- 不要用any类型，ESLint会报错
- Element Plus的表格组件必须设置row-key，否则翻页会出问题
- 路由懒加载必须使用import()格式，不能直接import页面组件
- axios拦截器中不要在请求拦截器里调用Element的Message组件（可能未初始化）
- Tailwind类名不要拼接字符串，要用完完整整的类名

## 常用操作命令
- 本地启动：npm run dev
- 类型检查：npx vue-tsc --noEmit
- 构建：npm run build
- 单测：npm run test:unit

## 详细规范（按需加载）
- 组件编码规范：docs/skills/vue-component-dev/SKILL.md
- API调用规范：docs/skills/api-layer/SKILL.md
- 类型定义规范：docs/skills/types-definition/SKILL.md

这份文档和后端AGENTS.md有一个重要的不同：明确写明了后端工程的相对路径和后端AGENTS.md的位置。这是前后端一体化的基础。AI要跨工程协作，首先得知道另一个工程在哪里。

建议的前端工程AI上下文目录结构

xxx-admin/                           <-- 前端工程根目录
  vite.config.ts
  AGENTS.md                          <-- 前端工程总入口
  package.json
  tsconfig.json
  tailwind.config.js
  src/
    api/
      order.ts                       <-- 订单相关API
      user.ts                        <-- 用户相关API
    components/
      AppTable.vue                   <-- 通用表格组件
      SearchForm.vue                 <-- 通用搜索表单
    composables/
      useTableQuery.ts               <-- 表格查询逻辑复用
      usePagination.ts               <-- 分页逻辑复用
    layouts/
      MainLayout.vue                 <-- 主布局（侧边栏+顶部栏+主内容区）
    pages/
      order/
        Index.vue                    <-- 订单列表页（路由入口）
        components/
          OrderSearchForm.vue        <-- 订单搜索条件（仅列表页使用）
          OrderDetailDrawer.vue      <-- 订单详情抽屉
      user/
        Index.vue
    router/
      index.ts                       <-- 路由配置
      modules/order.ts              <-- 订单模块路由
    stores/
      user.ts                        <-- 用户状态
      order.ts                       <-- 订单列表筛选条件等全局状态
    types/
      order.ts                       <-- 订单相关TS类型
      user.ts                        <-- 用户相关TS类型
      api.ts                         <-- 通用API响应类型
  docs/
    skills/
      vue-component-dev/
        SKILL.md                     <-- Vue组件编码规范
      api-layer/
        SKILL.md                     <-- API调用层规范
      types-definition/
        SKILL.md                     <-- TypeScript类型定义规范
    schema.md                        <-- 页面组件关系图（Mermaid）
    api-map.md                       <-- API接口与页面的映射关系
  ../xxx-order/                      <-- 后端工程（同级目录）
    pom.xml
    AGENTS.md

关键点：前端和后端的工程目录建议放在同级目录下（不是前后端混合在一个工程里），这样AI可以通过相对路径 ../xxx-order 直接访问后端代码和文档。现代前后端分离的开发方式天然支持这种目录组织。

Schema对于前端工程的特殊意义

后端工程用SQL Schema作为业务事实的来源。前端工程没有数据库，但有等价物：TypeScript类型定义。

把核心业务类型定义整理到 docs/api-types.md 中：

## 订单相关类型

### OrderVO（订单列表展示）
{
  id: number
  orderNo: string
  userName: string
  totalAmount: number        // 单位：分
  status: OrderStatus        // 10|20|30|40|90
  statusText: string         // 展示文本
  createdAt: string          // ISO 8601
}

### OrderQuery（订单查询参数）
{
  orderNo?: string
  status?: OrderStatus
  dateRange?: [string, string]
  pageNum: number            // 默认1
  pageSize: number           // 默认20
}

### PageVO<T>（通用分页响应）
{
  list: T[]
  total: number
  pageNum: number
  pageSize: number
}

这份文档是前后端一体化的关键桥梁。前端AI和后端AI对同一份数据结构达成共识，联调时不会出现"后端返回的字段和前端类型对不上"的经典问题。

第1步验收标准

1. AI能通过AGENTS.md回答：这个前端工程用了什么UI组件库、主要的页面有哪些、怎么发HTTP请求
2. AI能找到后端工程的位置并读取后端的AGENTS.md
3. AI能说清楚至少3个页面的路由路径和对应的组件文件位置

---

第2步：让AI能"操作"你的前端工程（预计3-5天）

创建前端专属Skill文件

前端开发和后端开发有完全不同的关注点。前端Skill重点解决：组件设计规范、API调用模式、TypeScript类型管理这三个问题。

在 docs/skills/vue-component-dev/SKILL.md 中：

---
name: vue-component-dev
description: Vue3组件开发规范，涵盖组件拆分、Props定义、组合式函数使用
---

# Vue3 组件开发规范

## 组件拆分原则

### 什么时候拆组件
- 同一个.vue文件超过300行 -> 拆分
- 某个UI区块在两个以上页面出现 -> 提取为公共组件
- 某个逻辑单元可以独立测试 -> 提取为composable

### 组件分类和存放
pages/{module}/Index.vue              -> 页面入口，只管布局和组合
pages/{module}/components/*.vue       -> 页面私有组件，仅该页面使用
components/*.vue                       -> 全局公共组件，至少两个页面使用
composables/*.ts                       -> 可复用逻辑（不含UI）

## Props定义规范

必须使用TypeScript interface定义，禁止裸Object类型：

```typescript
// 正确
interface Props {
  orderList: OrderVO[]
  loading?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  loading: false
})

// 错误
const props = defineProps(['orderList', 'loading'])

API调用模式

所有API请求统一走 src/api/ 下的函数，禁止在.vue文件中直接调用axios：

// src/api/order.ts 中的API函数
export function queryOrderList(params: OrderQuery) {
  return request.get<PageVO<OrderVO>>('/api/orders', { params })
}

// 页面组件中调用
import { queryOrderList } from '@/api/order'
const { data, loading } = useTableQuery(queryOrderList, searchForm)

组合式函数规范

useXxx命名，内部用ref/reactive + computed/watchEffect：

// composables/useTableQuery.ts
export function useTableQuery<T, P>(
  apiFn: (params: P) => Promise<PageVO<T>>,
  searchForm: Ref<P>
) {
  const list = ref<T[]>([])
  const loading = ref(false)
  const pagination = reactive({ pageNum: 1, pageSize: 20, total: 0 })

  async function fetchData() {
    loading.value = true
    try {
      const res = await apiFn({ ...searchForm.value, ...pagination })
      list.value = res.list
      pagination.total = res.total
    } finally {
      loading.value = false
    }
  }

  onMounted(fetchData)

  return { list, loading, pagination, fetchData }
}

样式规范

优先使用Tailwind CSS原子类，只在Tailwind无法满足需求时才写SCSS：

<!-- 正确 -->
<div class="flex items-center gap-4 p-4 bg-gray-50 rounded-lg">

<!-- 避免 -->
<div class="order-card">
<!-- 然后在<style lang="scss">里写 -->

前端Skill和后端的最大不同在于：前端有大量组件关系和视觉层级的概念是后端没有的。页面嵌套关系、组件复用边界、状态共享方式，这些才是前端AI化的核心。

第一个AI前端编码任务：订单列表页

帮我实现一个订单列表页面，要求：

1. 新建 src/pages/order/Index.vue，路由路径 /orders
2. 搜索条件：订单号（模糊）、订单状态（下拉选择）、日期范围（日期选择器）
3. 数据展示：接入后端的 GET /api/orders 接口（接口定义见 backend AGENTS.md）
4. 分页功能，默认每页20条，支持切换每页数量
5. 状态列需要展示对应的中文文本（10=已创建 20=已支付 30=已发货 40=已完成 90=已取消）
6. 金额展示格式为元，保留两位小数（后端返回单位是分）

涉及的文件：
- src/pages/order/Index.vue（页面入口）
- src/pages/order/components/OrderSearchForm.vue（搜索表单）
- src/pages/order/components/OrderStatusTag.vue（状态标签）
- src/api/order.ts（API函数）
- src/types/order.ts（TypeScript类型）
- src/router/modules/order.ts（路由配置）

遵循AGENTS.md和docs/skills/vue-component-dev/SKILL.md规范。
先读取后端工程的AGENTS.md确认API格式，再开始编码。

注意最后一句："先读取后端工程的AGENTS.md确认API格式"。这句话很关键，它告诉AI在做前端开发时主动去读后端的上下文，而不是凭空猜测API格式。这就是前后端一体化的第一个具体动作。

---

第3步：AI首次接触工程时的工作流（clone -> 读懂 -> 操作）

前面的内容都假设代码已经在本地了。但现实中，AI Agent第一次接触一个工程，本地目录可能根本不存在。一个完整的AI Native工程应该让AI能够从零开始：拿到仓库地址 -> clone -> 自动发现上下文文件 -> 加载Skill -> 开始工作。

3.1 AGENTS.md是AI接触工程的入口

当AI clone完工程后，第一步就是读AGENTS.md。所以AGENTS.md必须包含AI"自助上手"所需的全部信息：

# AI自助上手指南（写在AGENTS.md开头的前几行）

如果你是AI Agent第一次接触这个工程，按以下步骤操作：
1. 确认本工程根目录：检查当前目录下是否有 AGENTS.md、pom.xml（Java）或 package.json（前端）
2. 如果是前后端一体化项目，检查 AGENTS.md 中的"Git仓库"章节
3. 如果关联工程（前端/后端）尚未clone，执行git clone
4. 加载 docs/skills/ 下的Skill文件（遵循skill规范的Agent会自动加载，或通过 skill_view(name='xxx') 手动加载）
5. 阅读"核心目录结构"和"关键约定"
6. 确认就绪，可以开始工作

这段文字写在AGENTS.md的最开头（工程名称之后），是给AI Agent看的"开机引导"。人类开发者不需要看，但对AI Agent来说至关重要。

3.2 完整的首次接触流程

以"订单详情功能"为例子，AI首次接触前后端两个工程时的完整流程：

AI的内心独白（实际执行的动作）：

1. 用户说"帮我实现订单详情功能，前端在xxx-admin，后端在xxx-order"
2. 检查本地是否有这两个工程
   - ls ~/workspace/xxx-admin -> 不存在
   - ls ~/workspace/xxx-order -> 不存在
3. 读取AGENTS.md中的Git仓库章节
   - git clone git@git.company.com:xxx/xxx-order.git ~/workspace/xxx-order
   - git clone git@git.company.com:xxx/xxx-admin.git ~/workspace/xxx-admin
4. 进入后端工程，读后端AGENTS.md
   - 确认技术栈：Java 17 + Spring Boot
   - 确认分层规范 + API约定
   - 加载 docs/skills/java-spring-boot-dev/SKILL.md
5. 进入前端工程，读前端AGENTS.md
   - 确认技术栈：Vue3 + TypeScript + Element Plus
   - 加载 docs/skills/vue-component-dev/SKILL.md
6. 现在AI对两个工程都有了完整认知，可以开始端到端开发了

3.3 Git仓库信息的标准格式

在AGENTS.md中，Git仓库信息应该包含以下字段：

## Git仓库

### 本工程
- 仓库地址：git@git.company.com:xxx/xxx-order.git
- 默认分支：main
- 本地路径建议：~/workspace/xxx-order

### 关联工程（前后端一体化需要）
| 工程名 | 仓库地址 | 本地路径建议 |
|---|---|---|
| 前端管理后台 | git@git.company.com:xxx/xxx-admin.git | ~/workspace/xxx-admin |
| 共用文档 | git@git.company.com:xxx/xxx-docs.git | ~/workspace/xxx-docs |

### Clone命令
git clone git@git.company.com:xxx/xxx-order.git ~/workspace/xxx-order
git clone git@git.company.com:xxx/xxx-admin.git ~/workspace/xxx-admin

注意事项：

• 仓库地址用SSH格式（git@git.xxx:xxx/xxx.git），不要用HTTPS（需要手动输密码）
• 如果公司GitLab需要特定的SSH密钥，在"不可踩的坑"中注明
• 本地路径建议统一用 ~/workspace/ 作为根目录，保持跨工程路径可预期

---

第4步：建立前后端一体化的协作机制（核心）

前后端一体化的本质是：让AI Agent能同时操控两份工程，实现端到端的功能开发。这需要在AGENTS.md和工程结构层面做专门的设计。

4.1 在双方的AGENTS.md中互相引用

前端AGENTS.md中增加：

## 后端工程
- 工程路径：../xxx-order（相对路径）
- 后端AGENTS.md：../xxx-order/AGENTS.md
- API基础路径：http://localhost:8080
- API文档：../xxx-order/docs/api.md
- 数据库Schema：../xxx-order/docs/schema.sql

## 协作规则
- 涉及API变更时，必须先更新后端再更新前端
- 新增接口时，先在../xxx-order/docs/api.md中定义接口，再实现
- 前后端共用类型定义在 docs/api-types.md 中维护

后端AGENTS.md中增加：

## 前端工程
- 工程路径：../xxx-admin（相对路径）
- 前端AGENTS.md：../xxx-admin/AGENTS.md
- 前端工程使用Element Plus + TypeScript
- API响应格式必须统一为 Result<T>

## 协作规则
- 新增接口时必须在 docs/api.md 中同步更新接口文档（含请求示例和响应示例）
- 返回VO字段命名用驼峰（和前端TS类型对齐）
- 分页接口统一返回 PageVO<T>，避免前端每个页面重新定义分页类型

4.2 建立跨工程的AGENTS.md索引文件

在两个工程的共同父目录（或任一工程的根目录）创建一个 AGENTS.unified.md：

# 订单系统 - 前后端一体化上下文

## 本目录下有哪些工程

| 工程 | 路径 | 类型 | AGENTS.md |
|---|---|---|---|
| 后端订单服务 | xxx-order/ | Java/Spring Boot | xxx-order/AGENTS.md |
| 前端管理后台 | xxx-admin/ | Vue3/TypeScript | xxx-admin/AGENTS.md |

## 端到端协作约定

### API变更流程
1. 后端在 xxx-order/docs/api.md 中更新接口定义
2. 前端AI检查 AGENTS.unified.md 中的接口变更记录
3. 前端更新 src/api/ 和 src/types/ 下的对应文件

### 新增功能端到端流程
1. 后端实现Service + Controller + 写测试
2. 后端更新 docs/api.md
3. 前端读取更新后的接口文档
4. 前端实现API函数 + 类型定义 + 页面组件
5. 联调验证

## 共用的数据结构
详见各工程的 docs/api-types.md

当AI Agent的上下文不足时（比如某个工程里的AI看不到另一个工程），可以由AGENTS.md引导AI读取AGENTS.unified.md，获取全局视图。

4.3 接口文档作为前后端契约

前后端联调最大的痛点是什么？接口文档不同步。解决方法是把接口文档放在两个工程都能访问的地方，并让AI在修改接口时强制更新文档。

在后端工程的 docs/api.md 中维护契约：

## 订单相关接口

### GET /api/orders - 订单列表查询

请求参数（Query String）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderNo | string | 否 | 订单号模糊查询 |
| status | number | 否 | 订单状态：10/20/30/40/90 |
| startTime | string | 否 | 开始日期，格式：2025-01-01 |
| endTime | string | 否 | 结束日期 |
| pageNum | number | 否 | 页码，默认1 |
| pageSize | number | 否 | 每页数量，默认20，最大100 |

响应示例：
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 10001,
        "orderNo": "O202501010001",
        "userName": "张三",
        "totalAmount": 9900,
        "status": 20,
        "createdAt": "2025-01-01T10:30:00"
      }
    ],
    "total": 1,
    "pageNum": 1,
    "pageSize": 20
  },
  "message": "success"
}

这份文档是前后端AI的共同语言。前端AI读到这里就知道该定义什么类型、该调用什么接口、返回值长什么样。后端AI在修改接口时必须同步更新这份文档，否则前端AI会基于过期信息编码。

---

第5步：端到端功能开发实战（核心场景）

场景：新增"订单详情"功能

需求：点击订单列表的"查看详情"按钮，弹出抽屉展示订单完整信息，包括订单基本信息和订单商品明细。

给AI Agent的指令：

实现"订单详情"功能，需要前后端联动：

后端（xxx-order工程）：
1. 新增 GET /api/orders/{id}/detail 接口
2. 返回订单基本信息 + 商品明细列表
3. OrderDetailVO包含：id, orderNo, userName, totalAmount, status, 
   createdAt, items: OrderItemVO[]
4. OrderItemVO包含：productName, quantity, price（单位：分）
5. 更新 docs/api.md

前端（xxx-admin工程）：
1. 在订单列表页的"操作"列增加"查看详情"按钮
2. 点击后弹出 OrderDetailDrawer 组件
3. 抽屉展示订单基本信息（两列布局）和商品明细（表格）
4. 新增 src/api/order.ts 中的 getOrderDetail 函数
5. 新增 src/types/order.ts 中的 OrderDetailVO 和 OrderItemVO 类型

先完成后端，再完成前端。后端接口文档更新后，前端再基于文档编码。

AI Agent的执行流程：

1. 读取前端AGENTS.md -> 找到后端工程路径 ../xxx-order
2. 读取后端AGENTS.md -> 了解后端工程结构、分层规范、API约定
3. 后端实现：
   • 在 domain/ 中定义 OrderDetailVO 和 OrderItemVO
   • 在 application/ 中实现查询逻辑
   • 在 adapter/ 中新增 Controller 接口
   • 在 docs/api.md 中更新接口文档
4. 前端实现：
   • 读取更新后的 docs/api.md，确认接口格式
   • 在 src/types/order.ts 中定义 TypeScript 类型
   • 在 src/api/order.ts 中新增 API 函数
   • 实现 OrderDetailDrawer.vue 组件
   • 在 Index.vue 中接入按钮和抽屉
5. 反馈：列出前后端各自变更的文件，标注需要人工验收的点

关键：AI如何跨工程操作

实际操作中，AI Agent需要能够在两个工程目录之间切换。在Hermes Agent中，可以通过 workdir 参数或 terminal 命令的 workdir 参数来切换工作目录：

# AI在后端工程中执行
terminal(command="cd ../xxx-order && ./mvnw test -Dtest=OrderAppServiceTest")

# AI在前端工程中执行
terminal(command="cd ../xxx-admin && npm run build")

在AGENTS.md中约定好目录切换规则后，AI就能自主在两个工程之间穿梭。

---

第6步：工程级AI工具箱的持续维护

6.1 前端Skill库

Skill文件	触发场景
vue-component-dev/SKILL.md	所有Vue组件开发
api-layer/SKILL.md	API调用层相关变更
types-definition/SKILL.md	TypeScript类型定义

6.2 前后端共用文档

文件	位置	作用
docs/api-types.md	前端工程	前后端共用的数据结构定义
docs/api.md	后端工程	接口契约文档（前后端共同遵守）
docs/schema.md	前端工程	页面组件关系图（Mermaid）
AGENTS.unified.md	父目录	跨工程索引（可选）

6.3 踩坑记录（前端特有）

## 踩坑记录

### 2025-02-10：Element Plus表格在Safari下宽度计算错误
现象：表格列宽在Safari下不生效，内容溢出。
原因：Safari对flex布局的计算和Chrome有差异，Element Plus的表格依赖flex。
解决：给表格列设置min-width而非width，或使用固定列方案。

### 2025-02-15：Pinia状态在页面刷新后丢失
现象：用户筛选条件在页面刷新后丢失。
原因：Pinia默认是内存存储，刷新即清空。
解决：使用 pinia-plugin-persistedstate 插件持久化需要保留的状态。

---

写在最后：前端AI Native化的特殊挑战

前端工程AI化有三个后端不存在的问题，需要特别注意：

1. 视觉层难以用文字描述
后端逻辑是纯文本的，AI读代码就能理解。前端有大量的视觉信息（布局、颜色、间距）是AI无法从代码中完全感知的。解决方法是：在AGENTS.md中补充设计规范（间距体系、颜色变量、组件库版本），在组件注释中说明视觉意图。

2. 组件关系是网状的
后端是树状分层（Controller -> Service -> Mapper），前端是网状依赖（页面引用组件，组件引用composable，composable引用api）。解决方法是：维护 docs/schema.md 页面组件关系图，用Mermaid可视化组件依赖。

3. 联调成本仍然存在
即使AI能同时写前后端代码，本地联调仍然需要人来做（启动后端服务 -> 启动前端服务 -> 手动测试）。AI能减少的是联调前的"接口对不上"问题，通过强制维护 docs/api.md 契约文档来实现。

---

本文基于Vue3 + Vite + TypeScript技术栈编写，工程级AI上下文管理的思路适用于各类前端框架（React、Angular等）和各类AI编码工具。