企业级定制 AI Skills 项目包落地指南 (Trae 篇)

1. 为什么需要企业级定制 Skills？

在 AI 辅助编程（Vibe Coding）的早期，我们倾向于引入各种“大而全”的通用 Skill（如 frontend-design、fullstack-developer）。但在真实的企业级中后台项目中，这种做法往往会导致灾难性的后果：

• 幻觉与上下文污染：AI 可能会用原生的 <table> 或标准的 el-table 来写列表，而不是团队重度封装的 CmcCardTable。
• 规范割裂：AI 可能会写出 Options API、混用 Axios 直接调用，而不是使用团队沉淀的 useTableList 或统一的 API 封装。
• 调度失效：当加载了太多功能重叠的 Skill 时，AI 无法精准判断当前该用哪一个，导致响应缓慢或答非所问。

核心理念： 企业级 Skill 的本质不是教 AI “如何写代码”，而是教 AI “在这个特定的工程里，团队的规矩是什么”。我们需要对 Skill 做减法，并在业务垂直领域做深透。

---

2. 黄金架构：“1 + 3 + 2” Skill 矩阵模型

对于一个标准的企业级前端工程（如 Vue3 + Vite + TS + Element Plus），推荐构建以下 6 个核心 Skill 即可覆盖 99% 的日常开发场景：

🧱 1 个基建兜底 (Framework Foundation)

• vue-best-practices: 规范 Vue3 组合式 API 的基础写法、宏定义（defineProps）、Tailwind CSS 的使用边界。

🏢 3 个业务引擎 (Business Domain) —— 核心！

• biz-components (如 cmc-components): 强制约束 UI 组件的选型（用什么组件渲染表格、弹窗、表单）。
• biz-utils (如 cmc-utils): 强制约束状态管理、Hooks、公共工具函数的使用（如分页 Hook、消息 Hook）。
• biz-api (如 cmc-api): 规范接口的目录结构、入参出参的 TS 类型定义、全局拦截器约定。

🛠️ 2 个工程保障 (Engineering & Quality)

• lint-standards (如 antfu-eslint): 指导 AI 如何处理特定 Lint 报错，禁止滥用 any 和 @ts-ignore。
• test-specs (如 vitest-specs): 规范单元测试的 Mock 策略和断言写法。

---

3. 手把手：如何编写一个高质量的 SKILL.md

在 .trae/skills/ 目录下，每个 Skill 文件夹内都有一个核心的 SKILL.md。一个能让 AI “随叫随到，指哪打哪” 的 Skill 必须包含以下三个要素：

核心要素一：高精度的触发词 (Description)

AI 是根据 Description 来决定是否调用该工具的。切忌使用泛泛而谈的描述，必须包含具体的动词和场景。

• ❌ 反面教材："这是一个关于前端组件的技能，包含了各种组件的用法。" (太宽泛，AI 不知道什么时候用)
• ✅ 最佳实践："在本项目中，当你需要开发新的 UI 页面、构建列表/表单/弹窗、或者用户要求修改视图层 (.vue 文件的 template) 时，必须立即触发此 Skill，以获取本项目的定制化组件库规范。"

核心要素二：红线与绝对禁忌 (Rules & Anti-patterns)

告诉 AI 不要做什么，往往比告诉它要做什么更重要。

核心要素三：Show, Don't Tell (提供具体的代码片段)

大模型是基于模式匹配的，给它一个标准的模板，它就能完美复制。

---

4. 落地细节：企业级 Skill 编写范例

以下是三个最核心的业务 Skill 的内部配置参考，其他团队可直接套用此结构替换为自己的业务代码。

📁 范例一：cmc-components (UI 组件规范)

路径: .trae/skills/cmc-components/SKILL.md

# cmc-components

**Description**: 在 cmclink-ibs-web 项目中开发 UI 界面、构建数据列表、表单、弹窗或调整布局时，**必须且首选**触发此 Skill。它包含了本项目高度定制化的组件库规范。

## 🚫 绝对禁忌 (Anti-patterns)

1. 严禁直接使用原生的 `el-table` 和 `el-pagination`，必须使用 `CmcCardTable` 和 `Pagination`。
2. 严禁直接使用原生的 `el-dialog`，必须使用 `CmcDialog`。
3. 严禁在 template 中硬编码中文字符，必须使用 `t('xxx.xxx')` 进行国际化。

## ✅ 组件使用映射表

当用户要求实现以下功能时，必须使用对应的组件：

- **数据列表**: `<CmcCardTable :data="tableData" :columns="columns" v-loading="loading">`
- **船名航次输入**: `<VesselVoyageKeywordSelect v-model:vessel-code="vessel" v-model:voyage-code="voyage" />`
- **港口输入**: `<PortSelect v-model="portCode" />`
- **字典下拉框**: `<BaseDataSelect category="CARGOTYPE" />`
- **空状态**: `<EmptyResult image-src="@/assets/images/empty.png" />`

## 💡 标准列表页模板示例

(此处提供一段包含 CmcCardTable, Pagination, CmcTab 的标准精简代码...)

📁 范例二：cmc-utils (业务逻辑与 Hooks 规范)

路径: .trae/skills/cmc-utils/SKILL.md

# cmc-utils

**Description**: 在处理页面业务逻辑、拉取接口数据、进行表单校验、状态管理 (Pinia) 以及触发全局消息提示时，必须触发此 Skill。

## 🛠️ 核心 Hooks 使用指南

### 1. 列表数据获取 (`useTableList` / `useCrud`)

**严禁**在组件内部手动写 `try...catch` 去调用列表 API，必须使用 `useTableList`。

```typescript
import { useTableList } from '~/composables/business/useTableList'
import * as api from '~/api/xxx'

const { tableData, loading, total, pageNo, pageSize, search, loadData } = useTableList({
  api: api.getPageList,
  immediate: true,
  searchParams: ref({ keyword: '' }),
})
```

2. 消息与确认弹窗 (useMessage & useConfirm)

严禁直接引入 ElMessage 和 ElMessageBox。

import { useConfirm } from '~/composables/ui/useConfirm'
import { useMessage } from '~/composables/ui/useMessage'

const msg = useMessage()
const { confirm } = useConfirm()

// 成功/失败提示
msg.success('操作成功')
msg.error(t('common.error'))

// 确认操作
await confirm(t('common.deleteConfirm')) // 若用户取消会自动 reject 阻断流程
await api.deleteData()

3. 表单校验 (useSimpleRules)

import { useSimpleRules } from '~/composables/validation/useSimpleRules'

const rules = useSimpleRules()

const formRules = computed(() => ({
  portCode: [rules.required(t('releaseTimeQuery.pleaseSelectPort'))],
  email: [rules.required(), rules.email()]
}))

📁 范例三：cmc-api (接口对接规范)

路径: .trae/skills/cmc-api/SKILL.md

# cmc-api

**Description**: 当你需要新增后端接口调用、定义 TypeScript 接口类型 (interface) 或阅读现有 API 结构时触发。

## 📜 API 定义规范

1. **目录结构**: API 必须放置在 `src/api/_modules/<业务域>/index.ts` 中。
2. **实例导入**: 统一从 `~/axios.service` 导入 `instance`。
3. **类型定义**:
   - 必须定义请求参数 `Params` 和响应结构 `Res` 的 Interface。
   - 响应结构必须包含 `code: number`, `msg: string`, `data: any`。
4. **拦截器约定**:
   - `code === 0` 的判断已经在全局 Axios 拦截器中处理，业务代码和 API 封装中**无需重复判断**。

## 💡 代码示例
```typescript
import instance from '~/axios.service'

export interface GetListParams {
  keyword?: string
  pageNo: number
  pageSize: number
}

export interface GetListRes {
  code: number
  msg: string
  data: {
    list: any[]
    total: number
  }
}

/**
 * 获取业务列表
 */
export async function reqBizList(params: GetListParams): Promise<GetListRes> {
  return instance.post(`/system/biz/list`, params)
}

---

5. 给其他团队的推广建议 (Rollout Strategy)

如果您要把这套体系推广给公司内的其他团队，建议按照以下 4 步走：

1. 盘点资产 (Audit)：让各组梳理自己项目里被封装得最深、最容易被新员工写错的组件和方法。（比如：各组自己的 Table、Form、Axios 封装）。
2. 对症下药 (Extract)：不要把整个文档丢给 AI。把盘点出的核心组件抽象成 3-5 个垂直领域的 Skill。
3. 清洗外部 Skill (Clean)：坚决剔除官方推荐中与现有工程化冲突的通用 Skill。在高度定制化的企业项目中，通用等于毒药。
4. 测试与调优 (Refine)：在 Trae 中开启一个新对话，输入“帮我写一个标准的增删改查页面”。观察 AI 是否准确调用了该组定制的 Skill 并生成了符合规矩的代码。如果 AI 还是用了原生组件，说明 Description 的触发词写得不够狠，继续修改触发权重。

💡 总结： Vibe Coding 不是让 AI 自由发挥，而是给 AI 戴上“企业规范的镣铐”跳舞。通过这套精简而高权重的 Skill 矩阵，AI 就能真正成为一个懂你们团队“黑话”、绝不乱写烂代码的高级工程师。