ub-vuejs

UB VueJS

概述

使用此技能，按照最新稳定版本的 Vue 核心最佳实践进行开发，并采用严格的 TypeScript 配置，同时以兼顾迁移的方式处理旧版代码。新代码仅生成现代模式，并逐步重构现有旧版模式。

根据检测到的项目和运行时实际情况进行实现，但组件设计应优先考虑向前兼容的迁移，而不是默认保留旧版模式或过时的指导。

按需加载参考资料

• 调整路由指导或跨技能编写约定时，阅读 ../ub-authoring/references/authoring-conventions.md。
• 阅读 references/vue-modern-patterns.md，了解规范的现代 Vue 配方和 API 用法模式。
• 阅读 references/vue-legacy-to-modern-migration.md，了解迁移映射、兼容性例外和现代化顺序。

不适用场景

• 如果任务主要依赖 Nuxt 运行时行为、应用目录规范、服务端路由或 Nitro 相关事项，请勿使用此技能；根据 Vue 编写是否仍是首要关注点，同时加载 ub-nuxt 或交由其处理。
• 如果主要问题是 Tailwind 集成或纯 CSS 架构，而非 Vue 组件逻辑，请勿使用此技能。

核心工作流

1. 从 package.json、锁文件、vite.config.*、vue.config.* 和 TypeScript 配置中检测 Vue 版本系列和工具链。
2. 确认任务属于 Vue 核心范围（SFC、响应式、侦听器、SSR 和水合、组件契约）。如果任务特定于 Nuxt，请同时加载框架规则，或交由 .agents/skills/ub-nuxt/SKILL.md 处理。
3. 对于重要或与版本相关的建议，比较官方指导、仓库实际情况和观察到的代码现状。
4. 如果权威来源、仓库实际情况或现有代码在重要建议上存在实质性分歧，请指出 OFFICIAL_CONFLICT。
5. 如果重要声明在经过针对性研究后仍无法从官方来源确认，请指出 UNVERIFIED。
6. 使用严格的 TypeScript 实现，并默认采用 script setup SFC，同时设置 lang="ts"。
7. 应用 references/vue-modern-patterns.md 中的现代 Vue 模式。
8. 更新现有代码时，拒绝生成旧版代码，并应用 references/vue-legacy-to-modern-migration.md 中的迁移映射。
9. 使用目标项目中可用的类型检查、lint 和测试验证行为。

版本与研究政策

• 以 Vue 的最新稳定版本为目标。
• 从 package.json 和锁文件中确定项目实际使用的 Vue 版本。
• 使用网络搜索，根据 Vue 官方文档核实当前最佳实践、API 可用性和迁移指南。
• 判断哪些内容能在当前项目中安全落地时，以仓库实际情况作为实现标准。
• 对前瞻性设计和便于迁移的模式，优先以 Vue 官方文档作为指导基准。
• 如果官方指导与仓库实际情况在非平凡建议上存在实质性分歧，请标记 OFFICIAL_CONFLICT，采用对仓库安全的方案，并说明迁移路径。
• 如果官方来源之间对非平凡建议存在分歧，也请标记 OFFICIAL_CONFLICT，不要悄然消除分歧。
• 如果经过有针对性的研究，仍无法在官方来源中确认某项非平凡主张，请标记为 UNVERIFIED，或避免将其作为已确定的指导。
• 仅在非平凡、依赖版本或存在争议的指导中说明冲突与不确定性，不要对简单修改作此说明。
• 当项目安装的版本低于最新稳定版本时，指出版本差距并建议升级路径。
• 除非明确要求，否则不要使用预发布或 Beta 功能。
• 如存在项目专属版本政策和工具链说明，请检查宿主仓库中的 AGENTS.md 或同等说明；不要假定其中包含此目录的默认设置。
• 生成的指导中不要硬编码版本号——建议应保持长期适用。

时效性审查

• 变化频率：高
• 审查建议：在修改相关内容时进行审查；条件允许时，按季度定期维护。
• 触发信号：Vue 核心 API 新增、Hydration 或 Watcher 语义变更、新的迁移指南，或影响 Vue 编写方式的仓库工具链变更。
• 执行方式：仅作建议；Vue 指导过时应触发审查，而非自动阻止操作。
• 稳定核心：即使易用性细节有所变化，Composition API、严格的 TypeScript 和严谨的 Watcher 模式仍是稳定的基准。

实现规则

Vue 核心与 SFC

• 生成的代码必须使用 TypeScript。
• 编写 SFC 时，默认使用 script setup 和 lang="ts"。
• 新代码使用 Composition API 和编译器宏。
• 新代码中的组件 v-model 约定优先使用 defineModel()。
• 优先使用 useTemplateRef() 创建基于字符串的模板引用。

响应性与 Watcher

• 若能提升清晰度，则在 script setup 中使用响应式 props 解构。
• 监听解构后的 props 时使用 getter 源，绝不要直接将值作为 watch 源传入。
• 对接受值、ref 或 getter 输入的可组合函数，使用 MaybeRefOrGetter<T> 和 toValue()。
• 在为浏览器 API、事件、计时器、存储、传感器或异步状态辅助函数编写通用的专用可组合函数之前，先考虑 VueUse（vueuse.org，尤其是 @vueuse/core）。
• 在 Watcher 回调中，必须在任何 await 边界之前同步注册 onWatcherCleanup()。
• Watch 源优先使用精确的 getter；仅在必要时使用数值形式的 deep。

SSR 与 Hydration

• 使用 useId() 生成 SSR 安全的 ID。
• 渲染首屏下方的大型区域时，对异步组件使用延迟 Hydration 策略。
• 谨慎使用 data-allow-mismatch，并为每种不匹配类型记录使用理由。
• 如果目标元素会在同一渲染周期稍后创建，则使用 Teleport defer。

性能与构建规范

• 优先实施影响较大的优化：稳定的 props、代码分割、大型列表虚拟化，以及对深层响应性的控制。
• 在构建配置中有意且明确地设置编译时标志。
• 避免缺少测量依据的过早微优化。

避免使用旧式模式的防护规则

• 新代码不得生成 Options API。
• 新代码不得生成类式组件、混入、过滤器或以 this 为中心的组件逻辑。
• 如果 defineModel() 可用，不得生成手动编写的 modelValue 和 update:modelValue 样板代码。
• 如果 useTemplateRef() 可用且适用，不得生成 ref(null) 模板引用模式。
• 不得生成在异步边界之后注册清理逻辑的侦听器代码。

迁移兼容例外政策（参见 references/vue-legacy-to-modern-migration.md）：

• 仅当现有代码库需要有限的兼容性支持时，才允许暂时保留旧式模式。
• 记录每种保留的旧式模式、保留原因以及明确的后续现代化路径。

非目标：

• 不要在此技能中编码 Nuxt 特有的目录／运行时策略；请交由 ub-nuxt 处理。
• 不要在此技能中提供深入的 Tailwind 实现指导；请交由 ub-tailwind 处理。

输出要求

生成或审查代码时，始终包含：

1. 环境说明：Vue 版本系列、TypeScript 状态以及检测到的关键工具。
2. 源信息说明：检测到的项目版本和实际工具链，以及与最新稳定版指导原则之间的任何重大差异。
3. 版本说明：检测到的 Vue 版本，以及是否有意排除任何预发布版行为。
4. 模式说明：选择了哪些现代 API，以及选择原因。
5. 旧式模式说明：移除了哪些旧式模式，或因兼容性原因有意保留了哪些模式。
6. 验证说明：运行了哪些检查（类型检查、lint、测试、构建）以及检查结果。
7. 相关时的冲突说明：标注 OFFICIAL_CONFLICT 或 UNVERIFIED，并简要说明原因及对实现的影响。

完成检查清单

• 强制采用最新稳定版 Vue 基准和 TypeScript 要求。
• 新代码使用 Composition API、script setup 和 lang ts。
• 在适用场景中使用 defineModel、useTemplateRef 和现代侦听器模式。
• 在涉及 SSR 时，正确使用 SSR 和 hydration 原语。
• 不引入任何新的旧式输出。
• 对任何保留的旧式模式，都明确说明保留原因并提供渐进式迁移路径。
• 在适用时，将 Nuxt 和 Tailwind 相关问题交由其专属技能处理。
• 在相关时，明确披露任何重大的官方来源冲突或未经核实的非简单指导原则。