@gong-ym/ai-spec-auto 0.2.3

package/.agents/skills/profiles/vue/create-route/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: create-route
+description: 指导在 Vue 3 项目中按团队规范创建和维护页面路由，包括路由模块配置、页面落点、懒加载与 meta 约束。当前端需要新增或调整页面路由时使用本技能。
+compatibility: Requires a local Vue project workspace and the repository's route/page conventions under .agents/rules/.
+---
+
+# 创建与维护 Vue 路由
+
+## 重要提示
+
+开始前必须先对齐这些规则：
+
+- `.agents/rules/03-项目结构.md`：页面、路由、mock、store 的目录落点
+- `.agents/rules/06-路由规范.md`：路由模块、懒加载、meta、唯一命名
+- `.agents/rules/05-API规范.md`：若页面会接真实接口，接口落点必须同步考虑
+
+如果当前仓库还没有 `src/router/index.ts` 或 `src/router/modules/`，先按 proposal/specs/design/tasks 判断：
+
+- 是补路由骨架
+- 还是保持占位入口，不强行新增半套路由
+
+不要在没有路由入口的情况下，擅自发明另一套散落式路由结构。
+
+## 目标
+
+把页面路由稳定落到当前 Vue 项目的既有规范中：
+
+- 页面目录：`src/views/<page>/index.vue`
+- 路由模块：`src/router/modules/<module>.ts`
+- 路由入口：`src/router/index.ts`
+
+## 创建步骤
+
+### 1. 明确页面与路由落点
+
+先确认：
+
+- 页面目录名使用 `kebab-case`
+- 路由模块文件名使用 `kebab-case`
+- 路由 `name` 使用 `PascalCase`，且全局唯一
+
+示例：
+
+```text
+src/views/user-list/index.vue
+src/router/modules/user-list.ts
+```
+
+### 2. 创建或补全路由模块
+
+```ts
+// src/router/modules/user-list.ts
+import type { RouteRecordRaw } from 'vue-router'
+
+const routes: RouteRecordRaw[] = [
+  {
+    path: '/user-list',
+    name: 'UserList',
+    component: () => import('@/views/user-list/index.vue'),
+    meta: {
+      title: '用户列表',
+      requiresAuth: true,
+    },
+  },
+]
+
+export default routes
+```
+
+硬约束：
+
+- 页面级路由必须使用 `() => import()` 懒加载
+- `meta.title`、`meta.requiresAuth` 要按项目约定补齐
+- 禁止在模块里静态导入页面组件
+
+### 3. 在路由入口注册模块
+
+```ts
+// src/router/index.ts
+import userListRoutes from './modules/user-list'
+
+const routes = [
+  ...userListRoutes,
+]
+```
+
+硬约束：
+
+- 路由只在统一入口注册
+- 禁止在页面组件、布局组件或其他目录里重复维护路由
+
+### 4. 对齐页面与交互边界
+
+如果当前页面只是：
+
+- 占位页
+- mock 页
+- 演示版
+
+则路由 meta、按钮文案和页面提示里要显式体现，不要伪装成生产可用页面。
+
+## 适配策略
+
+### 已有完整路由骨架
+
+优先：
+
+- 复用现有 `src/router/index.ts`
+- 复用现有 `src/router/modules/`
+- 保持现有模块风格、导出形式和 meta 结构
+
+### 尚无完整路由骨架
+
+优先：
+
+- 在 proposal/specs/design/tasks 中写清“补路由骨架”是本次范围的一部分
+- 保持最小实现，不顺手扩展守卫、权限体系、菜单体系
+
+不要：
+
+- 在 `App.vue` 里临时堆一套伪路由，再同时新建 `src/router/`
+- 创建和现有项目风格冲突的第二套路由组织方式
+
+## 快速检查清单
+
+- [ ] 页面落在 `src/views/<page>/index.vue`
+- [ ] 路由模块落在 `src/router/modules/<module>.ts`
+- [ ] 页面级路由使用动态导入懒加载
+- [ ] 路由 `name` 全局唯一，`path` 与 proposal/specs/design/tasks 一致
+- [ ] `meta.title`、`meta.requiresAuth` 已补齐
+- [ ] 未在组件或页面内部重复维护路由
+- [ ] 若为 mock/演示页，已在页面或 proposal 中明确边界
+
+## 与其他技能的配合
+
+- 页面结构优先交给 `create-view`
+- 页面专用组件拆分交给 `create-component`
+- 页面真实接口交给 `create-api`
+- 样式与主题约束交给 `theme-variables`
+
+`create-route` 只解决“路由落点、路由模块和入口注册”，不要把它扩成页面实现总入口。

package/.agents/skills/profiles/vue/create-store/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: create-store
+description: 指导在 Vue 3 项目中按团队规范使用 Pinia 创建和维护全局状态 store，包括目录结构、命名与持久化策略。当前端需要新增或重构状态管理时使用本技能。
+compatibility: Requires a local Vue project workspace and the repository's store conventions under .agents/rules/.
+---
+
+# 创建与维护 Pinia Store
+
+## 目录与命名
+
+- 文件位置：`src/store/modules/<module-name>/index.ts`（store 定义）+ `type.ts`（类型定义）
+- 导出名称：`useXxxStore`
+- 集中导出：`src/store/index.ts`
+
+---
+
+## 创建步骤
+
+### 1. 创建类型定义
+
+```ts
+// src/store/modules/user/type.ts
+export interface UserInfo {
+  id: string
+  name: string
+  avatar: string
+  roles: string[]
+}
+```
+
+### 2. 创建 Setup Store
+
+```ts
+// src/store/modules/user/index.ts
+import { ref, computed } from 'vue'
+import { defineStore } from 'pinia'
+import type { UserInfo } from './type'
+
+export const useUserStore = defineStore('user', () => {
+  const userInfo = ref<UserInfo | null>(null)
+  const token = ref('')
+  const isLoggedIn = computed(() => !!token.value)
+
+  function setUser(info: UserInfo) { userInfo.value = info }
+  function setToken(val: string) { token.value = val }
+  function resetUser() { userInfo.value = null; token.value = '' }
+
+  return { userInfo, token, isLoggedIn, setUser, setToken, resetUser }
+})
+```
+
+### 3. 持久化（如需要）
+
+配合 `pinia-plugin-persistedstate`：
+
+```ts
+// src/store/modules/theme/index.ts
+import { ref } from 'vue'
+import { defineStore } from 'pinia'
+
+export const useThemeStore = defineStore(
+  'theme',
+  () => {
+    const mode = ref<'light' | 'dark'>('light')
+    function toggleMode() { mode.value = mode.value === 'light' ? 'dark' : 'light' }
+    return { mode, toggleMode }
+  },
+  { persist: { key: 'app-theme', pick: ['mode'] } },
+)
+```
+
+### 4. 集中导出
+
+```ts
+// src/store/index.ts
+export { useUserStore } from './modules/user'
+export { useThemeStore } from './modules/theme'
+```
+
+---
+
+## 使用约定
+
+- 全局共享状态集中在 `src/store/modules/`，禁止在组件中用 `ref` 维护全局数据
+- Store 只存纯数据与业务行为，不耦合 UI 组件
+- 消费方式：`const userStore = useUserStore()`
+- 模块私有类型放 `type.ts`，全局共享类型放 `src/types/`
+
+---
+
+## 快速检查清单
+
+- [ ] 文件在 `src/store/modules/<name>/` 下，包含 `index.ts` 和 `type.ts`？
+- [ ] 使用 setup 函数语法，导出名称为 `useXxxStore`？
+- [ ] 在 `src/store/index.ts` 集中导出？
+- [ ] 按需使用 `persist` 持久化？
+- [ ] 未在 store 中耦合 UI 逻辑？

package/.agents/skills/profiles/vue/create-view/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: create-view
+description: 指导在 Vue 3 项目中按团队规范创建和维护页面视图，包括目录结构、路由模块配置及懒加载用法。当前端需要新增或重构页面时使用本技能。
+compatibility: Requires a local Vue project workspace and the repository's page/view conventions under .agents/rules/.
+---
+
+# 创建与维护页面视图
+
+## 目录结构
+
+`src/views/<view-name>/`：`index.vue`（入口）+ `components/`（页面级子组件）+ `composables/`（useXxx）。目录名 `kebab-case`，通用组件提取到 `src/components/`。
+
+---
+
+## 创建步骤
+
+### 1. 页面组件
+
+```vue
+<!-- src/views/user-manage/index.vue -->
+<script setup lang="ts">
+import UserTable from './components/user-table/index.vue'
+import { useUserFilter } from './composables/useUserFilter'
+const { filters, resetFilters } = useUserFilter()
+</script>
+
+<template>
+  <div class="user-manage">
+    <UserTable :filters="filters" @reset="resetFilters" />
+  </div>
+</template>
+
+<style scoped lang="scss">
+.user-manage { padding: 16px; background-color: var(--color-bg-layout); }
+</style>
+```
+
+### 2. 路由模块
+
+```ts
+// src/router/modules/user-manage.ts
+import type { RouteRecordRaw } from 'vue-router'
+
+const routes: RouteRecordRaw[] = [
+  {
+    path: '/user-manage',
+    name: 'UserManage',
+    component: () => import('@/views/user-manage/index.vue'),
+    meta: { title: '用户管理', requiresAuth: true, icon: 'user' },
+  },
+]
+export default routes
+```
+
+- `() => import()` 懒加载，`name` 用 `PascalCase` 全局唯一
+- `meta` 必须配置 `title`、`requiresAuth`
+
+### 3. 注册路由
+
+在 `src/router/index.ts` 中导入并展开模块路由。
+
+### 4. 页面组合式函数
+
+```ts
+// src/views/user-manage/composables/useUserFilter.ts
+import { reactive } from 'vue'
+export function useUserFilter() {
+  const filters = reactive({ keyword: '', status: '' })
+  const resetFilters = () => Object.assign(filters, { keyword: '', status: '' })
+  return { filters, resetFilters }
+}
+```
+
+---
+
+## 快速检查清单
+
+- [ ] 目录 `kebab-case`，入口 `index.vue`？
+- [ ] 路由在 `src/router/modules/` 下，使用懒加载？
+- [ ] `meta` 配置了 `title`、`requiresAuth`？
+- [ ] 页面专用逻辑抽取到 `composables/`？

package/.agents/skills/profiles/vue/theme-variables/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: theme-variables
+description: 指导在 Vue 3 项目中正确使用主题 CSS 变量，避免硬编码颜色并保证暗色/浅色主题切换一致性。当前端编写或修改样式时使用本技能。
+compatibility: Requires a local Vue project workspace plus the repository's style conventions and theme variable setup.
+---
+
+# 主题 CSS 变量与样式规范
+
+## 基本原则
+
+所有样式必须使用 **CSS 变量** 表达主题颜色，禁止硬编码。
+
+---
+
+## 变量定义
+
+通过 `data-theme` 切换亮暗模式，在 `src/styles/variables.scss` 中定义：
+
+```scss
+:root, [data-theme='light'] {
+  --color-primary: #1677ff;
+  --color-text: #1f1f1f;
+  --color-text-secondary: #666666;
+  --color-bg-layout: #f5f5f5;
+  --color-bg-container: #ffffff;
+  --color-border: #d9d9d9;
+  --color-success: #52c41a;
+  --color-warning: #faad14;
+  --color-error: #ff4d4f;
+}
+
+[data-theme='dark'] {
+  --color-primary: #1668dc;
+  --color-text: #ffffffd9;
+  --color-text-secondary: #ffffff73;
+  --color-bg-layout: #141414;
+  --color-bg-container: #1f1f1f;
+  --color-border: #424242;
+  --color-success: #49aa19;
+  --color-warning: #d89614;
+  --color-error: #dc4446;
+}
+```
+
+---
+
+## 在组件中使用
+
+```vue
+<style scoped lang="scss">
+.card {
+  background-color: var(--color-bg-container);
+  color: var(--color-text);
+  border: 1px solid var(--color-border);
+}
+</style>
+```
+
+CSS Modules 中同理。
+
+## 常用变量
+
+`--color-primary`、`--color-text`、`--color-text-secondary`、`--color-bg-layout`、`--color-bg-container`、`--color-border`、`--color-success`、`--color-warning`、`--color-error`
+
+**反例：** `background-color: #1677ff` ❌ → `background-color: var(--color-primary)` ✅
+
+---
+
+## 快速检查清单
+
+- [ ] 所有颜色来自 `var(--color-xxx)`？
+- [ ] 未硬编码任何颜色值？
+- [ ] 新增变量同时在 light 和 dark 中声明？

package/.agents/skills/profiles/vue/vue-best-practices/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: vue-best-practices
+description: MUST be used for Vue.js tasks. Strongly recommends Composition API with `<script setup>` and TypeScript as the standard approach. Covers Vue 3, SSR, Volar, vue-tsc. Load for any Vue, .vue files, Vue Router, Pinia, or Vite with Vue work. ALWAYS use Composition API unless the project explicitly requires Options API.
+license: MIT
+metadata:
+  author: github.com/vuejs-ai
+  version: "18.0.0"
+---
+
+# Vue Best Practices Workflow
+
+Use this skill as an instruction set. Follow the workflow in order unless the user explicitly asks for a different order.
+
+## Workflow Checklist
+
+- [ ] Confirm the project really is Vue and identify the expected architecture
+- [ ] Read the required core references before implementation
+- [ ] Apply optional references only when the requirement needs them
+- [ ] Verify behavior first, then run the performance pass
+
+## Gotchas
+
+- Do not force Options API or JSX patterns into a Composition API project without explicit repo evidence
+- Do not load every reference file by default; keep the working set scoped to the current task
+
+## Core Principles
+- **Keep state predictable:** one source of truth, derive everything else.
+- **Make data flow explicit:** Props down, Events up for most cases.
+- **Favor small, focused components:** easier to test, reuse, and maintain.
+- **Avoid unnecessary re-renders:** use computed properties and watchers wisely.
+- **Readability counts:** write clear, self-documenting code.
+
+## 1) Confirm architecture before coding (required)
+
+- Default stack: Vue 3 + Composition API + `<script setup lang="ts">`.
+- If the project explicitly uses Options API, load `vue-options-api-best-practices` skill if available.
+- If the project explicitly uses JSX, load `vue-jsx-best-practices` skill if available.
+
+### 1.1 Must-read core references (required)
+
+- Before implementing any Vue task, make sure to read and apply these core references:
+  - `references/reactivity.md`
+  - `references/sfc.md`
+  - `references/component-data-flow.md`
+  - `references/composables.md`
+- Keep these references in active working context for the entire task, not only when a specific issue appears.
+
+### 1.2 Plan component boundaries before coding (required)
+
+Create a brief component map before implementation for any non-trivial feature.
+
+- Define each component's single responsibility in one sentence.
+- Keep entry/root and route-level view components as composition surfaces by default.
+- Move feature UI and feature logic out of entry/root/view components unless the task is intentionally a tiny single-file demo.
+- Define props/emits contracts for each child component in the map.
+- Prefer a feature folder layout (`components/<feature>/...`, `composables/use<Feature>.ts`) when adding more than one component.
+
+## 2) Apply essential Vue foundations (required)
+
+These are essential, must-know foundations. Apply all of them in every Vue task using the core references already loaded in section `1.1`.
+
+### Reactivity
+
+- Must-read reference from `1.1`: [reactivity](references/reactivity.md)
+- Keep source state minimal (`ref`/`reactive`), derive everything possible with `computed`.
+- Use watchers for side effects if needed.
+- Avoid recomputing expensive logic in templates.
+
+### SFC structure and template safety
+
+- Must-read reference from `1.1`: [sfc](references/sfc.md)
+- Keep SFC sections in this order: `<script>` → `<template>` → `<style>`.
+- Keep SFC responsibilities focused; split large components.
+- Keep templates declarative; move branching/derivation to script.
+- Apply Vue template safety rules (`v-html`, list rendering, conditional rendering choices).
+
+### Keep components focused
+
+Split a component when it has **more than one clear responsibility** (e.g. data orchestration + UI, or multiple independent UI sections).
+
+- Prefer **smaller components + composables** over one “mega component”
+- Move **UI sections** into child components (props in, events out).
+- Move **state/side effects** into composables (`useXxx()`).
+
+Apply objective split triggers. Split the component if **any** condition is true:
+
+- It owns both orchestration/state and substantial presentational markup for multiple sections.
+- It has 3+ distinct UI sections (for example: form, filters, list, footer/status).
+- A template block is repeated or could become reusable (item rows, cards, list entries).
+
+Entry/root and route view rule:
+
+- Keep entry/root and route view components thin: app shell/layout, provider wiring, and feature composition.
+- Do not place full feature implementations in entry/root/view components when those features contain independent parts.
+- For CRUD/list features (todo, table, catalog, inbox), split at least into:
+  - feature container component
+  - input/form component
+  - list (and/or item) component
+  - footer/actions or filter/status component
+- Allow a single-file implementation only for very small throwaway demos; if chosen, explicitly justify why splitting is unnecessary.
+
+### Component data flow
+
+- Must-read reference from `1.1`: [component-data-flow](references/component-data-flow.md)
+- Use props down, events up as the primary model.
+- Use `v-model` only for true two-way component contracts.
+- Use provide/inject only for deep-tree dependencies or shared context.
+- Keep contracts explicit and typed with `defineProps`, `defineEmits`, and `InjectionKey` as needed.
+
+### Composables
+
+- Must-read reference from `1.1`: [composables](references/composables.md)
+- Extract logic into composables when it is reused, stateful, or side-effect heavy.
+- Keep composable APIs small, typed, and predictable.
+- Separate feature logic from presentational components.
+
+## 3) Consider optional features only when requirements call for them
+
+### 3.1 Standard optional features
+
+Do not add these by default. Load the matching reference only when the requirement exists.
+
+- Slots: parent needs to control child content/layout -> [component-slots](references/component-slots.md)
+- Fallthrough attributes: wrapper/base components must forward attrs/events safely -> [component-fallthrough-attrs](references/component-fallthrough-attrs.md)
+- Built-in component `<KeepAlive>` for stateful view caching -> [component-keep-alive](references/component-keep-alive.md)
+- Built-in component `<Teleport>` for overlays/portals -> [component-teleport](references/component-teleport.md)
+- Built-in component `<Suspense>` for async subtree fallback boundaries -> [component-suspense](references/component-suspense.md)
+- Animation-related features: pick the simplest approach that matches the required motion behavior.
+  - Built-in component `<Transition>` for enter/leave effects -> [transition](references/component-transition.md)
+  - Built-in component `<TransitionGroup>` for animated list mutations -> [transition-group](references/component-transition-group.md)
+  - Class-based animation for non-enter/leave effects -> [animation-class-based-technique](references/animation-class-based-technique.md)
+  - State-driven animation for user-input-driven animation -> [animation-state-driven-technique](references/animation-state-driven-technique.md)
+
+### 3.2 Less-common optional features
+
+Use these only when there is explicit product or technical need.
+
+- Directives: behavior is DOM-specific and not a good composable/component fit -> [directives](references/directives.md)
+- Async components: heavy/rarely-used UI should be lazy loaded -> [component-async](references/component-async.md)
+- Render functions only when templates cannot express the requirement -> [render-functions](references/render-functions.md)
+- Plugins when behavior must be installed app-wide -> [plugins](references/plugins.md)
+- State management patterns: app-wide shared state crosses feature boundaries -> [state-management](references/state-management.md)
+
+## 4) Run performance optimization after behavior is correct
+
+Performance work is a post-functionality pass. Do not optimize before core behavior is implemented and verified.
+
+- Large list rendering bottlenecks -> [perf-virtualize-large-lists](references/perf-virtualize-large-lists.md)
+- Static subtrees re-rendering unnecessarily -> [perf-v-once-v-memo-directives](references/perf-v-once-v-memo-directives.md)
+- Over-abstraction in hot list paths -> [perf-avoid-component-abstraction-in-lists](references/perf-avoid-component-abstraction-in-lists.md)
+- Expensive updates triggered too often -> [updated-hook-performance](references/updated-hook-performance.md)
+
+## 5) Final self-check before finishing
+
+- Core behavior works and matches requirements.
+- All must-read references were read and applied.
+- Reactivity model is minimal and predictable.
+- SFC structure and template rules are followed.
+- Components are focused and well-factored, splitting when needed.
+- Entry/root and route view components remain composition surfaces unless there is an explicit small-demo exception.
+- Component split decisions are explicit and defensible (responsibility boundaries are clear).
+- Data flow contracts are explicit and typed.
+- Composables are used where reuse/complexity justifies them.
+- Moved state/side effects into composables if applicable
+- Optional features are used only when requirements demand them.
+- Performance changes were applied only after functionality was complete.