ACORG docs

主题

Skill: Vue ​

基于 Antfu Skills 集合中的 vue、vue-best-practices、vue-router-best-practices、vue-testing-best-practices 和 vueuse-functions,让 AI 客户端遵循 Vue 3、Composition API、TypeScript 与现代工程实践。

作用说明 ​

Antfu Skills 是 Anthony Fu 维护的一组 Agent Skills,面向 Vite、Nuxt、Vue 等现代前端技术栈。它的特点是:

  • 按需加载: Skill 只有在任务命中时才读取详细内容
  • 可共享: 可以跨项目复用,也可以在团队内统一安装
  • 文档驱动: 部分 Skill 从官方文档生成,并通过引用资料保持上下文可追溯
  • 实践导向: 一些 Skill 来自社区最佳实践,用于约束组件拆分、路由、测试等高频场景

Vue 相关 Skill 适合在以下任务中使用:

  • 编写或重构 .vue 单文件组件
  • 设计组件边界、Props、Emits、Slots 和数据流
  • 编写 composable、Pinia 状态、Vue Router 路由
  • 为 Vue 组件和 composable 补充 Vitest / Vue Test Utils / Playwright 测试
  • 判断是否应优先使用 VueUse composable

安装 ​

安装 Antfu Skills 集合中的全部 Skill:

bash
pnpx skills add antfu/skills --skill='*'

全局安装:

bash
pnpx skills add antfu/skills --skill='*' -g

如果只想安装 Vue 相关能力,可以按客户端支持情况选择单个 Skill:

bash
pnpx skills add antfu/skills --skill='vue'
pnpx skills add antfu/skills --skill='vue-best-practices'
pnpx skills add antfu/skills --skill='vue-router-best-practices'
pnpx skills add antfu/skills --skill='vue-testing-best-practices'
pnpx skills add antfu/skills --skill='vueuse-functions'

使用方法 ​

为了稳定触发,建议在提示词前显式声明:

text
use vue skill, <你的需求>

如果任务涉及最佳实践、路由、测试或 VueUse,可以同时点名相关 Skill:

text
use vue skill and vue-best-practices skill, 重构这个 Vue 页面,拆分组件并提取 composable
text
use vue-router-best-practices skill, 修复路由参数变化后页面数据不刷新的问题
text
use vue-testing-best-practices skill, 给这个组件补充 Vitest 单测
text
use vueuse-functions skill, 用 VueUse 改写当前窗口尺寸和滚动位置监听逻辑

核心约定 ​

来自 vue Skill 的默认偏好:

  • 使用 Vue 3.5 及以上语义
  • 默认使用 Composition API
  • 默认使用 <script setup lang="ts">
  • 优先使用 TypeScript,避免 JavaScript-only 写法
  • 深层响应式不是必需时,优先考虑 shallowRef
  • 使用 defineProps、defineEmits、defineModel、defineExpose、defineOptions、defineSlots 等宏
  • 不推荐滥用 Reactive Props Destructure,除非项目已有明确约定

组件模板示例:

text
<script setup lang="ts">
import { computed, onMounted, watch } from 'vue'

const props = defineProps<{
  title: string
  count?: number
}>()

const emit = defineEmits<{
  update: [value: string]
}>()

const model = defineModel<string>()

const doubled = computed(() => (props.count ?? 0) * 2)

watch(() => props.title, (value) => {
  console.log('title changed:', value)
})

onMounted(() => {
  console.log('mounted')
})
</script>

<template>
  <div>{{ title }} - {{ doubled }}</div>
</template>

最佳实践 ​

vue-best-practices 是更强约束的 Vue 工作流 Skill。它强调在编码前先确认架构,并在非平凡功能中先规划组件边界。

执行 Vue 任务时优先遵循:

  • 保持状态可预测:源状态最小化,派生值使用 computed
  • 数据流显式:默认 Props Down / Events Up
  • 组件职责单一:路由页和入口组件只做组合,不要承载完整业务实现
  • 复杂逻辑进 composable:以 useXxx() 命名,API 保持小而清晰
  • 模板保持声明式:分支、派生、复杂计算放到 <script setup>
  • 性能优化放在功能正确之后,不要提前过度优化

组件需要拆分的常见信号:

  • 同时负责数据编排和多块复杂 UI
  • 有 3 个以上独立 UI 区域,例如表单、筛选、列表、状态栏
  • 模板块重复,或明显可以复用为行、卡片、列表项
  • 页面级组件里出现完整 CRUD / 列表 / 表单实现

路由实践 ​

vue-router-best-practices 覆盖 Vue Router 4 的常见问题:

  • 同一路由不同 params 导航时,不要依赖重新挂载触发生命周期
  • beforeRouteEnter 中不能直接访问组件实例的 this
  • 导航守卫里的异步请求需要 await,避免竞态和错误放行
  • 避免无限重定向循环,登录态判断必须有明确退出条件
  • 新代码避免使用已不推荐的 next() 风格守卫
  • 组件卸载时清理事件监听和副作用
  • 生产 SPA 应使用 Vue Router,不要手写脆弱的路径状态

测试实践 ​

vue-testing-best-practices 覆盖 Vue 测试栈:

  • 单元测试优先使用 Vitest
  • 组件测试使用 Vue Test Utils
  • 端到端测试优先考虑 Playwright
  • 测试行为而不是组件内部实现,减少重构导致的脆弱测试
  • 异步交互使用 await、nextTick、flushPromises 等方式稳定等待
  • Pinia、provide/inject、异步组件、Suspense、Teleport 需要专门的测试包装
  • 不要只依赖快照测试判断功能正确
  • 需要真实 DOM 事件或样式计算时,选择合适的浏览器测试环境

VueUse ​

vueuse-functions 用于判断是否应优先使用 VueUse。它的原则是:

  • 在 Vue / Nuxt 开发中,先检查是否已有合适的 VueUse composable
  • 对常见浏览器、状态、监听、存储、尺寸、滚动、节流、防抖等需求,优先使用 VueUse
  • 对需要额外依赖的函数,先确认项目已安装相关依赖；确有必要时再引入
  • 对 EXPLICIT_ONLY 类函数,只在用户明确要求或项目已有约定时使用

常见自动适用场景:

  • 状态与存储: useLocalStorage、useSessionStorage、useStorage、useAsyncState
  • DOM 与窗口: useWindowSize、useElementSize、useResizeObserver、useEventListener
  • 交互与传感器: onClickOutside、useMouse、useScroll、useFocus
  • 网络与异步: useFetch、useWebSocket、useTimeoutPoll
  • Watch 工具: watchDebounced、watchThrottled、watchOnce
  • 工具函数: useDebounceFn、useThrottleFn、useToggle、useCounter

与其他 Skill 的关系 ​

  • vite: 提供 Vite 配置、插件、SSR、库模式和构建相关上下文
  • antdv-next: 提供 Antdv Next 组件 API、示例、主题 Token 和语义结构
  • vue: 提供 Vue 核心 API 与 <script setup> 写法
  • vue-best-practices: 提供组件拆分、数据流、composable 和性能实践
  • vue-router-best-practices: 提供 Vue Router 4 路由与导航守卫实践
  • vue-testing-best-practices: 提供 Vue 测试实践
  • vueuse-functions: 提供 VueUse composable 选择与使用指南

常见问题 ​

Skill 和 AGENTS.md / CLAUDE.md 谁更适合? ​

Antfu README 的观点是:Skill 的价值在于可共享和按需加载。AGENTS.md 或 CLAUDE.md 会被更稳定地预加载,适合写项目强约束；Skill 更适合放通用知识库和可复用实践。

如果某个 Vue 约定必须始终生效,可以在 AGENTS.md / CLAUDE.md 中显式要求使用对应 Skill。

AI 仍然写 Options API? ​

在提示词、项目记忆文件和 Skill 描述里同时强调 Vue 3 + Composition API + <script setup lang="ts">。如果项目确实是 Vue 2 或 Options API 老项目,应单独维护对应 Skill,避免污染 Vue 3 上下文。

使用 VueUse 会不会增加依赖? ​

如果项目已经安装 VueUse,优先使用合适 composable。若未安装,只有在它能明显降低复杂度或减少错误时再建议安装,不要为了简单逻辑引入新依赖。

参考链接 ​